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.

626 KB
Raw Blame

Repository Structure

three.ws ships all platform surfaces from a single npm-workspaces monorepo. This file maps each product surface to where it lives in this repository, so external developers can find what they need without reading 50 top-level directories.

When an internal surface gains an external consumer that needs an independent release cadence, we promote it to its own published package (and, for most packages, a generated standalone GitHub mirror). See Promotion path at the bottom.

three.ws surface map

Surface Location Status Notes
Web renderer / viewer avatar-sdk/ → /viewer Published as @three-ws/avatar <agent-3d> web component
Entity studio (one detail page for agents AND avatars) pages/avatar-page.html + src/avatar-page.js → /avatars/:id and → /agents/:id, view switcher src/view-switcher.js, AR lane src/ar-page.js → /avatars/:id/ar + /agents/:id/ar, long-form agent profile pages/agent-detail.html + src/agent-detail.js → /agents/:id/profile Live The canonical page every entity link on the platform lands on: search, /agents, /gallery, the marketplace, galaxy, launches and profiles all point here. One controller renders both kinds from one shell (3D stage + wallet-reactive aura, identity, tabs for Overview / Chat / Pose / Skills / Plugins / Embed, related grid). Agent mode projects the agent record onto the avatar shape (agentStudioRecord): the agent's name, description, tags and custodial wallet win, its bound body supplies geometry and fork lineage, and chat posts the real agentId so replies come from that agent's brain and memory. Agents and avatars are separate tables with separate UUIDs, so an id that lands on the wrong route is probed against the other store and redirected to its canonical path instead of 404ing. An agent with no body yet renders a designed stage state ("create a body" / "pick one from the marketplace") rather than an empty viewer, and every body-scoped surface (AR, Pose, forks, coin launch, GLB stats) stays hidden. Docs: docs/agents-vs-avatars.md
Agent shell (companion identity + agentic ⌘K + persistent navigation) src/agents/guest-agent.js, src/shared/agent-names.js, src/walk-companion-identity.js, public/search.js, src/view-transitions.js, src/shell/page-lifecycle.js Live The agent IS the interface: every visitor gets a named ephemeral agent in the first five seconds (auto-summoned corner companion with an identity chip; “Claim →” prefills /create-agent and POST /api/agents makes it real); the ⌘K palette executes real commands in place (forge → free text→3D lane, digest → clustered news, price → live market data, ask → streamed /api/chat) and announces completions so the companion reacts; pages marked data-shell (/markets, /coins) navigate by swapping only the main element so the agent and shell never unload (page modules re-init via onPageReady). Docs: docs/agent-shell.md. Tests: tests/search-commands.test.js, tests/guest-agent.test.js, tests/agent-names.test.js
Event Markets core api/_lib/event-markets/index.js, odds.js, config.js, view.js, routes.js, api/event-markets/[...path].js, api/_mcpagent/event-markets-tools.js, data/event-markets.json Live once migration 20261011020000 is applied Markets, outcomes, picks, implied odds, lock boundary, season points budget, void refunds, history from the pick log, admin create/edit/lock/void/resolve, MCP event_markets_list / event_market / event_market_pick. Docs: docs/event-markets.md. Tests: tests/event-markets.test.js, tests/event-markets-mcp.test.js
Event Market announcements api/_lib/event-markets/announce.js, review.js, poster.js, api/event-markets/announcements.js, api/cron/event-market-announce.js, pages/event-market-announcements.html → /admin/event-market-announcements Live, posting off until the owner enables it Cron writes drafts per market lifecycle change; admin queue approves, edits, rejects; poster is the only sender and refuses anything not approved (flag EVENT_MARKET_ANNOUNCE_POST, daily cap). Entrants tagged only with self-linked X handles. Docs: docs/event-markets.md. Tests: tests/event-market-announcements.test.js
Event Market auto-open api/_lib/event-markets/auto-open.js, sources/, api/cron/event-markets-open.js, api/ops/event-markets.js, pages/event-markets-admin.html → /admin/event-markets Live once migration 20261012010000 is applied Opens a market per Arena tournament, platform event, build round and bounty; adds late entrants pre-lock; logs skips; writes the event_market.opened outbox row. Docs: docs/event-markets.md. Tests: tests/event-markets-auto-open.test.js
Event Market resolution api/_lib/event-markets/resolvers/, lifecycle.js, override.js, api/cron/event-markets-resolve.js, api/ops/event-market-override.js, data/event-market-resolution.json Live once migration 20261012130000 is applied Locks at locks_at, resolves from our own arena, event, launch, round and bounty records with the evidence stored on the market, retries while pending, voids on tie, no data, cancellation or timeout; admin override needs a written reason. Docs: docs/event-markets.md. Tests: tests/event-market-resolvers.test.js, tests/event-market-lifecycle.test.js
Event Market pages and share cards pages/event-markets.html → /event-markets, pages/event-market.html → /event-markets/<slug>, src/event-markets/, api/event-market-og.js, api/event-market-share.js, api/_lib/event-market-card.js Live Browse and detail pages, pick flow, odds chart, per-market SVG share card and crawlable meta page, entry strips on Arena, event, launches and home. Docs: docs/event-markets.md. Tests: tests/event-market-card.test.js
Event Market scoring, leaderboard and rewards api/_lib/event-markets/scoring.js, rollup.js, fairness.js, leaderboard.js, api/cron/event-markets-rollup.js, data/event-market-scoring.json, pages/event-markets-leaderboard.html → /event-markets/leaderboard, scripts/event-markets-season-payouts.mjs Live once migration 20261012400000 is applied; payouts owner-gated Scores, streaks, season ranks and badges from the rollup cron; wallet-derived names; fair-play ranking checks; season reward table printed for owner approval, never sent automatically. Docs: docs/event-markets.md. Tests: tests/event-markets-scoring.test.js
Event Market live feed api/event-markets/stream.js, api/_lib/event-markets/hub.js, feed.js, moves.js, live-stats.js, api/cron/event-markets-feed.js, src/event-markets/live-feed.js, ticker.js, data/event-markets-feed.json Live (migration 20261012200000 applied) SSE odds, picks, moves and lifecycle with Last-Event-ID resume, odds-move detector, home ticker, in-place odds on the market page with polling fallback, pulse and trending additions. Docs: docs/event-markets.md. Tests: tests/event-markets-live-feed.test.js, tests/event-markets-live-stats.test.js. Bench: scripts/event-markets-fanout-bench.mjs
Solana agent registry (8004) api/_lib/solana-8004.js, hook in api/_lib/onchain-deploy.js, read side in api/_lib/agent-economy.js and api/agents/a2a-hire.js, badge in src/agent-detail.js, back-fill scripts/register-8004-agents.mjs, proof scripts/prove-8004-registry.mjs, SDK patch scripts/fix-8004-solana-esm.mjs Devnet live; mainnet registration opt-in (SOLANA_8004_REGISTER_MAINNET=1) Authority-managed registration beside the Metaplex identity, registry block on the agent row, live tier read in hires, tier tie-break in offer ranking, minRegistryTier guard, agent-page badge, rate-limited back-fill. Docs: docs/solana-agent-registry.md. Tests: tests/solana-8004.test.js, tests/solana-8004.devnet.test.js
App pages (hub plus Android, Seeker, iOS, Desktop, Web) Pages pages/apps.html → /apps and pages/apps-{web,android,seeker,ios,desktop}.html → /apps/*, code src/apps.js, src/apps.css Built and verified locally One page per platform with its real install path and status; the desktop page reads the live release feed. Docs: docs/apps.md
The Grid (a neon wireframe room of live app surfaces, a board, a directory, a Pulse wall and a kiosk per app) Code src/desktop/grid/ → /?world=grid, entered from the campus HUD, tests tests/desktop-grid.test.js Built and verified locally Walk up to a surface and press E to open the app on the desktop; every panel reads a live feed; byte tier comes from mined gems. Docs: docs/desktop.md
The Field (a live, zoomable map of every agent and surface) Page pages/desktop.html → /?view=field, code src/field/ (README): pure layout and camera logic.js, feeds data.js, map field.js, entry and view switch entry.js Built and verified locally Public agents drawn as stars in a golden-angle core around ten live districts; semantic zoom from one readout per district to full cards (avatars, launches, $THREE quote and CA, Pulse wallet moves, top skills, most-talked-to agents); Pulse events fly in as comets; search over places, agents and every nav page; any page opens in place at a shareable /?go= URL. The homepage / is the web desktop; the campus is at /?world=1. Docs: docs/field.md
Web desktop (homepage as an OS, with a 3D campus in front of it) Page pages/desktop.html → /, code src/desktop/ (README): boot and lock screen boot.js + boot-logic.js, campus src/desktop/world/ (rooms rooms.js, props props.js, surfaces surfaces.js, textures public/campus/ built by scripts/build-campus-textures.mjs, solids src/shared/solids.js), gem ledger api/world/gems.js over api/_lib/world-gems.js (migration 20261015000000_world_gems.sql); previous homepage pages/home.html → /classic Built and verified locally Boots with a live log of real checks (GPU, site catalog, account, fonts, avatar, $THREE feed, gem ledger), locks with a greeting and live chips, then the visitor walks in as their avatar: a daylit campus of real walk-in buildings (physical sky and sun with soft shadows, CC0 Poly Haven surfaces, props streamed from the object library, walls and furniture as solids) with the home office (sit at the desk to open the desktop on the monitor, pick up the phone for Pocket, put on the headset for WebXR), the three.ws Exchange with a live ticker (Trenches), the Launchpad, the Forge, the Gallery, Agent Plaza, the Marketplace and a gem mine with server-rolled, rate-limited digs. Real registered agents stand on the campus in their own bodies (world/cast.js, agents.js, talk.js): a greeter meets you at the gate, and walking up to any of them opens a conversation through its own /api/chat brain, with the one-tag <agent-3d> embed to put it on your own site. Taskbar, Start, widgets and snappable windows framing real three.ws pages in the CTRL Mica theme; icons on a snap grid, All Apps, Settings (profile, Arrival, accent, wallpaper, icon size), session in localStorage plus IndexedDB. Framed pages hide the site nav via public/nav.js (tws-os: frame name). Docs: docs/desktop.md. Tests: tests/desktop-boot.test.js, tests/world-places.test.js, tests/world-rooms.test.js, tests/world-props.test.js, tests/solids.test.js, tests/world-ticker.test.js, tests/desktop-layout.test.js, tests/desktop-page.test.js; browser drives scripts/desktop-world-smoke.mjs, scripts/desktop-interact.mjs
Desktop widgets and assistant Code src/desktop/widgets/ (README): pure grid, catalog and formatting logic.js, shared feeds data.js, renderers render.js, desktop layer, gallery and board index.js; assistant src/desktop/assistant/ (README) Built and verified locally Eleven live widgets ($THREE, Weather, Clock, Calendar, New agents, Pulse, Launches, Platform, Headlines, System, Sticky note) in three sizes, pinned to a snap grid on the desktop (drag, edit mode, Add widget gallery with live previews) or on the widgets board with a greeting and a news column; feeds shared and paused while hidden, offline states with retry. The assistant streams /api/chat, opens desktop apps from [[open:id]] tags, and switches to any public agent's persona. Docs: docs/desktop-widgets.md. Tests: tests/desktop-widgets.test.js, tests/desktop-assistant.test.js
Desktop OS layer (file system and native apps) Code src/desktop/os/ (README): IndexedDB file system fs.js, app host and context host.js, lazy registry registry.js, apps in apps/ Built and verified locally Files, Notepad, Photos, Calculator, Clock, Weather, Camera, Paint, Terminal, Task Manager and Media Player mount into desktop windows through one mount(host, ctx) contract on a persistent virtual file system. Docs: docs/desktop.md. Tests: tests/desktop-os-files.test.js, tests/desktop-os-apps.test.js, tests/desktop-os-system.test.js; browser drive scripts/desktop-os-smoke.mjs
Partner benefits (what each partnership gives users) Page pages/partner-benefits.html → /partners/benefits, linked from pages/partners.html Live once deployed One card per programme (OpenAI, NVIDIA, IBM, Google Cloud, AWS, Alibaba Cloud, Quicknode, HackerNoon) with the designation, what it brings builders and links to docs. Static, no amounts or IDs. Docs: docs/partner-benefits.md
Trenches Pulse (Solana + Robinhood Chain intelligence) Service services/pulse/ (vendored nirholas/pulse: firehose, scorer, API, Telegram newsletter), proxy api/trenches.js → /api/trenches, page pages/trenches.html + src/trenches.js → /trenches Built and verified locally; service deploy pending owner approval Real pump.fun firehose over Solana WebSocket: launches, graduations, hottest tokens, runners, scored wallets. Offline upstream is a designed 503 state, never fabricated data. Docs: docs/trenches.md. Tests: tests/trenches-api.test.js
Browse by goal (every feature grouped into twelve goals, search, pins, what-next strip) pages/everything.html, src/everything.js, src/everything.css, taxonomy scripts/lib/feature-jobs.mjs, public/next-steps.js Live /everything reads public/features.json, which scripts/build-page-index.mjs builds from data/pages.json plus the goal taxonomy, so a new page appears with no extra step. Also drives the goal labels in the ⌘K palette and the nav entry. Docs: docs/everything.md. Tests: tests/feature-jobs.test.js, tests/next-steps.test.js
AI index (llms.txt, llms-full.txt, install.md) Generator scripts/build-page-index.mjs, outputs public/llms.txt, public/llms-full.txt, public/install.md, test tests/llms-index.test.js Live llms.txt follows llmstxt.org and links each curated doc as /docs/<slug>.md. llms-full.txt adds the full markdown of those docs (40 KB cap each, docs naming other crypto projects left out). install.md is built from public/.well-known/mcp.json: setup command, per-client settings, every hosted endpoint.
Event Market agent forecasters api/_lib/event-markets/forecasters.js, analyze.js, forecast-runner.js, forecaster-routes.js, api/cron/event-markets-forecasters.js, api/_mcpagent/event-market-forecast-tools.js, src/event-markets/forecasting.js, forecasters.js, pages/event-markets-forecasters.html → /event-markets/forecasters, data/event-markets-agents.json Live (migration 20261012120000 applied) Agent picks as the agent's own identity with confidence, rationale and evidence; market-page agents panel; track record and calibration on the agent profile; ranked board; follow with notifications; owner-controlled autonomous mode (off by default); MCP analyze, forecasters and agent pick. Docs: docs/event-markets.md. Tests: tests/event-markets-agents.test.js, tests/event-markets-agents-mcp.test.js, tests/event-markets-forecasting-ui.test.js
Event Market staking (Solana) contracts/event-markets-stake/, api/_lib/event-markets/staking/, api/event-markets/staking-admin.js, src/event-markets/staking-panel.js, pages/event-markets-staking-admin.html → /admin/event-markets-staking, scripts/event-markets-stake-admin.mjs Built and tested locally; off until the owner deploys and sets EVENT_MARKETS_STAKING_ENABLED Parimutuel stake pools (USDC, $THREE) with unsigned stake and claim transactions, age and region gate, caps, kill switch and vault reconciliation. Owner-gated mainnet steps. Docs: docs/event-markets-staking.md. Tests: tests/event-markets-staking.test.js, tests/event-markets-staking.chain.test.js
Walk companion + playground walk-sdk/ → /walk-companion.js Published as @three-ws/walk Corner mascot + full-page stroll/platformer playground + diverse avatar picker. App entries: src/walk-companion.js, src/walk-playground.js
The walkaround world (/temporary) pages/temporary.html → /temporary, app src/walk.js, environments src/walk-environments.js + public/environments/, multiplayer src/walk-net.js → walk_world, day/night src/walk-day-night.js, radar src/game/hud/minimap.js, companions src/walk-npcs.js, agent desks src/walk-agent-desk.js Live Walk your avatar through six real staged environments (park, cyberpunk street, beach, gallery, void, office) with physics-driven locomotion on a heightfield, four camera modes, gestures, voice chat, trails, capture, and live peers. Time of day is real and shared: the same deterministic world clock /play runs on (src/shared/world-clock.js) drives the sun arc, sky gradient, light levels, and IBL strength, so two people in the same world always agree on whether it is night. The sky crossfades on a wider curve than the light levels, so dawn and dusk linger instead of flipping. Armed for outdoor stages only (indoor/void keep their authored manifest lighting) and paused while AR passthrough owns the rig. The radar is /play's: /temporary mounts the same rotating GTA-style minimap the world HUD uses, with a compass, the walkable-disc boundary ring, and live blips for peers (their nameplate colours), NPC companions, live agent desks, the guide's named landmarks, and scenery. Click or tap it to set a walk-to waypoint (Minimap.worldFromScreen() inverts the rotating projection); M or the dock button toggles it and the choice persists. Frame pacing is shared too: the loop runs through src/shared/frame-governor.js (60fps focused, 30 unfocused, 30 under power saver) and the controls overlay carries the cross-surface Power-saver switch. Tests: tests/walk-day-night.test.js, tests/minimap-projection.test.js
Walk landing + one-tag embed (/walk) pages/walk-landing.html → /walk, embed app pages/walk-embed.html → /walk/app and → /walk-embed (src/walk-embed.js), board pages/walk-leaderboard.html → /walk-leaderboard, ranking API api/walk/leaderboard.js, curated quotes data/walk-social.json Live The marketing entry for Walk and the surface the → /walk route actually serves (the walkaround world above is at /temporary). Live demo embeds across six environments, the copyable one-tag iframe snippet, the Chrome extension pitch, and a top-three teaser off the real all-time distance ranking, which reads rows straight from the leaderboard endpoint and falls back to designed empty and retryable error states. All nine demo iframes stay keyboard-reachable, which axe's frame-focusable-content rule requires of any frame whose document has focusable content, and each gets a scripted focus ring because an iframe whose document holds focus matches no focus pseudo-class. Page copy is mirrored in the walk_landing namespace of public/locales/en.json, which the i18n runtime applies over the served HTML, so the two must be edited together.
Pocket Console (/pocket) pages/pocket.html → /pocket, app src/pocket.js, styles src/pocket.css, screen pages/walk-embed.html via the typed contract in src/walk-embed-events.js Live A handheld with a live 3D agent inside the screen, built for the thing people actually share: the D-pad walks the agent, A waves, B jumps, L/R change the cartridge, START swaps the screen between PLAY, STATS (the agent record read live) and SELECT (a game menu over GET /api/agents/public), and the power LED is a real switch that unmounts the frame so an off screen stops rendering. Keyboard, touch and the Gamepad API drive the same controls. Four shell finishes and four scenes, all carried in the URL, so a share link is the device as you left it. ?chrome=off is the embed: the device alone on a transparent background with no nav, footer or language pill, addressed by avatar id so the GLB streams through the same-origin proxy and renders identically on a third-party domain. The screen runs the walk embed at zoom=0.74 (the param this surface added, documented in docs/tutorials/walk-companion.md). Docs: docs/pocket.md
Live Docs (runnable code samples) Pure decisions public/docs-live-core.js, runner public/docs-live.js, styles public/docs-live.css, mounted by the docs viewer docs/index.html Live Every code sample across the ~318 documentation pages is editable, and the runnable ones execute in place: an html snippet containing <agent-3d> renders a real animated avatar in a sandboxed frame directly under the code, a single-curl bash block sends a real request and reports status, latency, size, body and response headers, and a js snippet runs as a module with its console streamed back. Slots such as $API_KEY or <agent-id> become input fields, with credential-shaped names held in memory and never written to storage. The safety split is the design: everything deciding what a reader may fire lives in the pure core and is unit-tested rather than trusted to a click handler. Only three.ws hosts are reachable, any path that can move funds or mint is refused outright on every verb, writes arm before they send, every fetch goes out with credentials: omit, and frames run sandbox="allow-scripts" without allow-same-origin. Authors opt a block out with <!-- live:off -->. Loaded lazily after the first page render, so a page with no runnable samples costs nothing. Docs: docs/live-docs.md → /docs/live-docs. Tests: tests/docs-live-core.test.js
Docs World (immersive 3D docs) pages/docs-world.html → /docs/world, app src/docs-world/ (world/player/controls/overlays), styles public/docs-world.css, shared manifest docs/nav.json Live The documentation as a walkable place: each section of the docs sidebar is a glowing pavilion on a ring; walk up (WASD / touch joystick, four shared camera modes via src/game/camera-modes.js) or tap one to list its pages, and read the live markdown in an in-world DOM reader (src/shared/markdown.js). One content source: both surfaces read docs/nav.json + /docs/<slug>.md, so classic and immersive docs cannot drift. Deep links mirror the classic hash routes (/docs/world#forge); the classic header's "3D world" button carries the open page across. Avatar is the platform's default rigged body (the same one /walk uses, since the agent mannequin ships unskinned and cannot be clip-driven) or any rigged GLB via ?avatar=, animated by the canonical clip library. No-WebGL devices get a designed fallback routing to /docs. Docs: docs/docs-world.md. Tests: tests/docs-world.test.js
x402 prepaid balances and batch settlement ledger api/_lib/x402/prepaid-ledger.js, batcher api/_lib/x402/prepaid-settle.js, chain legs api/_lib/x402/prepaid-chain.js, route hook api/_lib/x402/prepaid-route.js (paidEndpoint({ mode: 'prepaid' })), endpoints api/x402-prepaid/, crons x402-prepaid-settle and x402-prepaid-reconcile, reconcile CLI scripts/x402-prepaid-reconcile.mjs, migration api/_lib/migrations/20261023160000_x402_prepaid_ledger.sql Built; live settlement gated on the owner A buyer deposits USDC once and each paid call debits a ledger row (never negative, charged only on success), then one Solana transaction per window pays every seller above a floor, so cent-sized calls stop starving the settle floor. A nightly reconciliation proves deposits minus debits minus settled equals held and alerts on any drift. Docs: docs/ops/x402-prepaid.md. Tests: tests/x402-prepaid-ledger.test.js
x402 upto (pay for what the call used) scheme module api/_lib/x402/upto.js, verify and claim in api/_lib/x402-spec.js, seller option paidEndpoint({ upto: { capAtomics, charge } }) in api/_lib/x402-paid-endpoint.js, buyer api/_lib/x402/a2a-client.js (buildSolanaUptoPayload), first route api/x402/llm-proxy.js Built; on-chain run gated on the owner The buyer escrows a cap, the seller settles only the measured charge and the rest of the deposit is refunded; a failed handler settles nothing. Opt in with X402_UPTO_ENABLED=true. Docs: docs/x402-upto.md. Tests: tests/x402-upto.test.js
Prompt library (/prompts) Source data/prompt-library.json, builder scripts/build-prompt-library.mjs → public/prompts.json + public/prompts.txt, page pages/prompts.html → /prompts + src/prompt-library/ (page.js, page.css) Live Prompts written to be copied out and pasted into someone else's assistant, grouped by what they build (3D models and rigged avatars, site embeds, the x402 economy, platform integrations) and by what they need first (nothing at all, the free MCP server, the skills pack, a funded wallet). Every prompt names a real endpoint or tool, says what to do when a job comes back pending, and says what to hand back; the ones that can spend money are written so the assistant stops and shows the amount and the recipient first. Each card copies to the clipboard or opens straight in claude.ai with the text already in the box, and the whole library is fetchable as /prompts.json or /prompts.txt so an agent can read it without scraping. The builder validates the data on every build (unique kebab-case ids, known category and setup, balanced <placeholder> brackets, internal links that resolve to routes in data/pages.json) and npm run check:prompt-library holds the published copies in sync inside npm run gate. Docs: docs/prompts.md → /docs/prompts. Tests: tests/prompt-library.test.js
React avatar creator avatar-sdk/ → /react /creator Published as @three-ws/avatar Same package, React subpath
Avatar CLI (manifests in the build pipeline) packages/avatar-cli/, landing pages/avatar-cli.html → /avatar-cli, styles public/avatar-cli.css, page runtime src/avatar-cli-page.js Published as @three-ws/avatar-cli The terminal half of the avatar story, and the half that makes an avatar auditable. Four commands over one file: init scaffolds a schema-valid manifest from a wallet plus a mesh (reading the GLB once to compute its SHA-256 and size, so the document cannot disagree with the bytes it was built from), validate checks it against packages/avatar-schema/ and exits non-zero so it works as a build gate, hash prints a bare digest that composes in a shell, and preview emits a resolver URL, an <agent-3d> snippet paired with the loader that registers it, and a zero-install iframe. Offline and deterministic throughout: no account, no API key, no network call, which is what makes it safe in a release script. preview warns instead of printing a dead snippet when mesh.uri is still a local file:// path. The landing page proves the emitted markup by rendering it live rather than screenshotting it. Docs: docs/avatar-cli.md → /docs/avatar-cli, tutorial docs/tutorials/ship-an-avatar-manifest.md. Tests: packages/avatar-cli/test/
Asset catalog (one search over every ready-made asset) join + ranking api/_lib/asset-catalog.js, code generation api/_lib/asset-snippets.js, REST api/catalog.js → /api/catalog, MCP tools api/_mcp/tools/library.js, CLI packages/assets-cli/ Published as @three-ws/assets The CC0 prop library, the ready-made character library and the motion-clip library joined into one ranked catalog (thousands of items; the live count is total on GET /api/catalog) that also hands back paste-ready source: the <model-viewer> tag the browse grids render with, <agent-3d> pinned to the exact published version plus its SRI hash, plain three.js, or React. Reachable three ways off one implementation: GET /api/catalog, the free MCP tools search_catalog / get_catalog_item / get_item_source (on /api/mcp's public allowlist, so a plain JSON-RPC call needs no OAuth and no x402, though an MCP client connecting there is sent through sign-in on initialize; the keyless /api/mcp-studio serves the same three to a client with no account via api/_mcp-studio/catalog-tools.js), and npx @three-ws/assets add <id>, which downloads the asset into the caller's project and rewrites the snippet to the local path. Every word of a query must match, with a labelled partial-match fallback so a phrase never dead-ends. Docs: docs/mcp.md → /docs/mcp, docs/api-reference.md. Tests: tests/api/mcp-asset-catalog.test.js, tests/api/catalog-endpoint.test.js, packages/assets-cli/test/
MCP resources and guided prompts registry and readers api/_mcp/resources.js, prompts api/_mcp/prompts.js, read_resource tools api/_mcp/tools/resources.js and api/_mcp3d/tools/resources.js, create_agent in api/_mcp/tools/agents.js over the shared creation path api/_lib/agent-create.js, subscriptions table api/_lib/migrations/20260922120000_mcp_resource_subscriptions.sql, manifest generator scripts/build-mcp-surfaces.mjs Live on /api/mcp, /api/mcp-agent, /api/mcp-3d, /api/mcp-bazaar Live read-only three:// views of the caller's account (agents, each agent's Solana wallet with balances, limits and freeze state, usage, chat, runs, orders, DCA, intents, wallets, launches) plus the public marketplace, model catalog, x402 catalog and 3D assets, each as JSON or markdown and each also reachable through the read_resource tool. resources/subscribe stores a fingerprint per client and the authenticated GET event stream emits notifications/resources/updated when it moves; a wallet moves when its latest signature changes. Seventeen guided prompts render against each server's live tools/list, so a server only offers flows whose tools it publishes, and venue flows switch to their executing tools once those ship. npm run audit:mcp-surfaces keeps server*.json and /.well-known/mcp.json in step with the code. Docs: docs/mcp.md → /docs/mcp. Tests: tests/mcp-resources.test.js, tests/mcp-prompts.test.js
Terminal avatar (any avatar or agent body, live in a terminal) packages/tty-avatar/ Published as @three-ws/tty-avatar npx @three-ws/tty-avatar <avatar id> draws the avatar in colour at 24 fps in any terminal: a software rasterizer (packages/tty-avatar/src/raster.js, z-buffered scanline fill, key + fill + rim lighting) over a subpixel grid that three encoders turn into truecolor half-blocks, braille, or plain ASCII (packages/tty-avatar/src/encode.js). Sources: a .glb path, a URL, an avatar id (/api/avatars/:id), agent:<id> (the agent's bound body via /api/agents/:id), or a three.ws page URL. Moods are procedural whole-body motion (packages/tty-avatar/src/moods.js), so a rigless prop animates too, and they cross-fade. The point of it: install-hooks --write merges nine Claude Code hooks whose command is a bare cat > ~/.three-ws/tty-avatar/event.json (zero startup cost per tool call), the viewer polls that file and maps each payload to a mood and a caption (packages/tty-avatar/src/state.js), so the avatar thinks, works, errors, asks and celebrates in step with the agent. Every avatar and agent page's Embed tab prints the command (src/avatar-page.js). Docs: docs/tty-avatar.md → /docs/tty-avatar. Tests: packages/tty-avatar/test/ (builds a real GLB in memory and exercises loader, rasterizer, encoders, moods, state bridge, hook installer and CLI)
Model Diff (what changed between two GLBs) pages/diff.html → /diff + page runtime src/model-diff.js, 3D stage src/model-diff-stage.js, styles public/model-diff.css, engine packages/glb-diff/, free API api/3d/diff.js → /api/3d/diff (catalog entry api/_lib/3d-catalog/diff.js), MCP tool diff_models in api/_mcp/tools/models.js Live The check that catches the most expensive silent failure in an asset pipeline: a checksum flags every re-export, and cannot tell a lossless recompression from a rig that quietly lost three finger joints. Objects are paired in three passes the way git pairs renamed files (name, then content hash, then similarity), so an exporter that renumbers Mesh.001 reads as a rename rather than a rewrite, and a node that kept its name but changed parent reads as a move. Vertex data is hashed at a 1e-4 quantum with normals, UVs and skin weights included, so a Draco round trip registers as nothing and a re-skin registers as a change. Positions, UVs and skin weights also hash independently (topology/uv/skinWeights on every mesh field), so a caller can tell exactly which kind of edit happened; api/_lib/preserve-contract.js builds directly on those fields plus the skins/animations sections so an edit can declare what it promises to keep (topology, UVs, skeleton, skin, clips) and refuse to report success if that promise breaks, the check behind Restyle Studio's material restyles, seeded variants, and HoloPart part regenerations. Every difference carries a severity (none to breaking), where breaking means something a consumer addresses by name is gone: a clip, a joint, a mesh. One engine, four surfaces, so a CI verdict can never disagree with the page: the browser page (drop two files, nothing uploaded; overlay / wipe / side-by-side in 3D, clicking a row frames that node), the free keyless API (?a=&b=, format=markdown for a pull-request comment), the glb-diff CLI (--fail-on breaking, exit 2 reserved for "could not run"), and the MCP tool. Docs: docs/model-diff.md → /docs/model-diff. Tests: packages/glb-diff/tests/glb-diff.test.js, tests/model-diff-api.test.js, tests/api/preserve-contract.test.js
Rig Doctor (will this GLB animate?) pages/rig-doctor.html → /rig-doctor, analysis src/rig-report.js, page runtime src/rig-doctor-page.js, styles public/rig-doctor.css Live The answer to the most expensive silent failure on the platform: a rig loads, renders, and never moves, because clips address bones by name and this skeleton calls them something else. Drop a .glb and the page reads its glTF JSON chunk in the browser, names the authoring convention (twelve fingerprints, from Mixamo and Ready Player Me to Unreal, VRM, MMD, Biped, Rigify, and HumanIK), and scores four limb groups independently against the 52-joint canonical set, because "62% covered" is not actionable and "your legs will not move" is. The verdict mirrors the runtime gate in src/animation-manager.js exactly (a skinned mesh plus 8 mapped joints), so it predicts rather than approximates. It then does two things a report cannot: mounts the real src/avatar-pose.js stage on a blob URL of the file so the user watches their own rig perform the actual clip library, and runs src/glb-canonicalize.js in-browser to hand back a repaired GLB with canonical joint names. Nothing is uploaded: the only network calls are for the clip library and the sample rigs. Also emits a schema-v1 manifest, an <agent-3d> snippet, and the matching packages/avatar-cli/ commands. Docs: docs/rig-doctor.md → /docs/rig-doctor. Tests: tests/rig-report.test.js
The pump.fun pill (/pill) pages/pill.html → /pill + src/pill.js + src/pill.css, rigger scripts/rig-pill-mascot.py, decimator scripts/decimate-glb.mjs, assets public/avatars/pumpfun-pill-cupsey.glb (rigged) + pumpfun-pill-cupsey-static.glb (the rigger's input) Live pump.fun verified $THREE as officially ours, and this is the thank-you: their pill mascot rigged, animated, and drivable in the browser. WASD or a touch joystick walks it, Shift runs, Space jumps, drag orbits, and the toolbar fires wave/jump/dance. The stage plays the model's own six embedded clips, so it needs no retargeting at load and no clip fetch. The model could not go through workers/rig: a capsule with four stubby nubs has no neck, no separate head and no long limbs for a humanoid predictor to find, so it got its own pipeline. That pipeline is general to capsule-with-nubs mascots, not to this character: limbs discovered from the mesh's distance transform, medial curves traced with a minimum-cost path, skin weights decided by walking each vertex inward to the medial axis of the part it is skin for (straight-line and geodesic distance both weld the raised hand to the cheek it rests against), and the neutral standing pose baked into the shipped geometry so bind and rest coincide. Canonical bone names mean the whole clip library retargets onto it at 100% coverage. Docs: docs/pill-mascot.md → /docs/pill-mascot. Tests: tests/pill-rig.test.js
Talking page guide page-agent-sdk/ Published as @three-ws/page-agent Drop-in rigged 3D agent that narrates any page + visitor avatar picker. <page-agent> web component. Rigged-only catalog. preset="…" resolves one of 5 personas (greeting/role/suggested-prompt chips/tool allowlist) — see page-agent-sdk/README.md#persona-presets. See page-agent-sdk/PUBLISHING.md
Guided site tour tour-sdk/ Published as @three-ws/tour 3D guide walks a live site, spotlights sections, narrates each. One-tag CDN build + free roam
Concierge (embeddable AI support chat) concierge-sdk/, backend api/concierge.js → /api/concierge, landing pages/concierge.html → /concierge, first-party CDN copy → /concierge/concierge.global.js (mirrored by concierge-sdk/build.mjs) Published as @three-ws/concierge An AI concierge for ANY website: floating launcher, chat panel with a rigged 3D avatar bust (blink/idle/viseme lipsync via the page-agent stage lineage), SSE-streamed answers grounded in the live page (ask-time DOM harvest + host knowledge, no crawler), speaks while streaming (sentence-level TTS handoff), push-to-talk mic, themes/accent/position, avatar picker or custom GLB. Backend is anonymous + CORS-* (third-party origins by design) with its own rate buckets (limits.conciergeIp/conciergeGlobal), no platform-side content filter on the visitor question, and streaming failover over the shared free-first chain (api/_lib/llm.js). Shopping mode (Shopify): when embedded on a Shopify storefront it auto-detects the store (window.Shopify / shop config) and becomes a shopping assistant, reading the store's public /products.json + /collections.json + /policies/* at ask-time (no key, no crawler, same-origin), retrieving the relevant products per question via keyword+intent search (concierge-sdk/src/shopify.js), grounding the answer in them, and rendering real product cards (image/live price/link + on-store /cart/add.js add-to-cart). The endpoint accepts a bounded shopping payload and swaps the system prompt to a store assistant. <three-concierge> element, data-concierge one-tag auto-init, or new Concierge({...}). Also reachable from any AI agent via the MCP server packages/concierge-mcp/ (@three-ws/concierge-mcp, registry io.github.nirholas/concierge-mcp): concierge_ask (ask any site's concierge, grounded in the fetched page), concierge_embed (generate the embed), concierge_avatars. Examples: concierge-sdk/examples/ (one-tag, web component, imperative, custom avatar, React, self-hosted backend). Docs: docs/concierge.md, tutorial docs/tutorials/build-a-site-concierge.md. Tests: concierge-sdk/test/, tests/api-concierge.test.js, packages/concierge-mcp/test/
Assistant widget (3D avatar assistant for any website) Loader public/assistant/v1.js -> /assistant/v1.js, iframe app pages/assistant-frame.html + src/assistant-frame.js -> /assistant-frame, builder pages/assistant.html + src/assistant-page.js -> /assistant, shared validators src/assistant-widget-core.js. npm SDK assistant-sdk/ (@three-ws/assistant) is the single source for the loader; its build.mjs emits the npm ESM + the mirrored one-tag build at public/assistant/v1.js. MCP server packages/assistant-mcp/ (@three-ws/assistant-mcp, registry io.github.nirholas/assistant-widget): build_assistant_widget (config -> paste-ready snippet + frame URL + JS-API call), list_assistant_options (avatars, backgrounds, modes, attributes). Published as @three-ws/assistant One script tag adds a floating launcher to any site; clicking it pops up a full-body animated avatar against the host page (transparent) or a color/gradient. Two modes: chatbot (free chain via POST /api/chat, or the visitor's own Groq/OpenRouter key sent browser-to-provider, stored in the frame's localStorage only) and speak mode (avatar repeats typed text out loud via Web Speech + head-anchored speech bubble + talking clip). All params re-validated in-frame (CSS/URL injection safe). Sibling of Concierge (chat panel) - this one is the full-body, avatar-first widget. Install three ways: one-tag CDN, npm i @three-ws/assistant, or the MCP server for AI agents. Examples: assistant-sdk/examples/. Docs: docs/assistant-widget.md -> /docs/assistant-widget, tutorial docs/tutorials/add-a-3d-assistant.md. Tests: tests/assistant-widget.test.js, assistant-sdk/test/, packages/assistant-mcp/test/
Forge cost preview + pay-to-keep api/forge-quote.js, api/forge-keep.js, api/_lib/forge-quote.js, api/_lib/forge-keep.js, src/forge-keep.js, scripts/forge-pay-to-keep.mjs Live (pay-to-keep off by default) Public no-spend GET /api/forge-quote priced from the real tier and catalog code, shown on /forge. Pay-to-keep is gated by FORGE_PAY_TO_KEEP (npm run forge:pay-to-keep -- on) and reuses the single-use consumption ledger and $THREE hold-or-pay rail. Docs: docs/forge.md. Tests: tests/api/forge-quote.test.js, tests/api/forge-keep.test.js
Forge provider webhook + anon upload sweep Tripo completion webhook api/forge/webhook/tripo.js → /api/forge/webhook/tripo, sweeper api/_lib/anon-upload-sweep.js run by the /api/cron/anon-upload-sweep cron Live The webhook finishes a Tripo job faster than polling (HMAC-SHA256 signature on TRIPO_WEBHOOK_SECRET with a 5 minute replay window, deliveries deduplicated in forge_webhook_deliveries); polling stays the fallback when no webhook arrives or the secret is unset. The sweeper deletes anonymous presigned-PUT objects that exceed their declared size ceiling. Pipeline: docs/forge-pipeline.md
Community agent skills (markdown instructions anyone can contribute) community-skills/ (skills/<slug>/, registry.json, CONTRIBUTING.md), catalog API api/skills/community.js, page → /skills/community Live One-markdown-file skills an agent imports in one click and follows from the next message on. Browse and import at /skills/community
Agent eval suites Task suites evals/suites/, loader api/_lib/evals/suites.js, outcome checks api/_lib/evals/checks.js Live Fixed task sets an agent configuration is scored against: each task names the prompt, the tools the agent may call, the outcome checks, and optional sandbox tools that return only their declared preview and never execute
Chat (conversational surface) chat/ → /chat Live Svelte 4 + Vite client, fork of eplus, built by build:chat inside build:gcp into public/chat → dist/chat. Free Built-in lane via /api/chat/proxy plus BYOK providers; inline 3D forge tools + ModelViewer3D; shares the platform wallet via src/shared/. Sign-in is wallet (SIWE/SIWS) or email+password against the platform's own /api/auth/*, on the same cookie session as the rest of the site (chat/src/passwordAuth.js). The app is the chat and only the chat: marketing lives at the site root, and the hash routes that once rendered in-app copies of it resolve to the real page and redirect (chat/src/three-ui/site-routes.js). Docs: chat/README.md. Tests: tests/chat-app-core.test.js
three.ws's own guided tour + onboarding src/feature-tour/ → /feature-tour.js, entry src/feature-tour.js, curriculum public/tour/curriculum.json generated by scripts/build-tour.mjs, landing pages/tour.html → /tour Live A hardened, site-native fork of the tour-sdk/ engine (same curriculum schema — stops/sections/tracks/highlight/narration/targets), lazy-injected only when a tour is starting/active (feature-tour-boot Vite plugin) so pages that never tour pay no Three.js cost. Three tracks share one curriculum: full (every feature, chapter by chapter), quick (highlighted heroes), and onboarding (added 2026-07-12) — a 6-stop, hand-authored new-account walkthrough chaining /start → make an avatar (/create/selfie) → build a world (/diorama) → live /markets data → an optional coin launch (/create-agent, clearly skippable) → the new creator's own /profile. Auto-offered once to a signed-in account with zero creations across avatars/agents/forged models/worlds (GET /api/me → show_onboarding_tour, backed by users.onboarding_tour_seen_at/onboarding_tour_completed_at, migration api/_lib/migrations/20260712030000_onboarding_tour_state.sql); always reachable afterward via "🎬 Replay guided tour" in the public/getting-started.js checklist panel. Tests: tests/feature-tour-curriculum.test.js, tests/api-me-onboarding-tour.test.js
Tour Atlas (visual index + tour health board) Page pages/tour-atlas.html -> /tour/atlas + src/tour-atlas.js, manifest source data/tour-atlas.json published to public/tour/atlas.json by scripts/build-tour-atlas.mjs, capture scripts/capture-tour-atlas.mjs npm run tour:atlas, screenshots public/media/tour/ Live Every stop of the guided tour above, photographed on the live site with the tour's own spotlight ring painted over the feature it is talking about. Searchable by feature, path or narration, filterable by chapter, track, and anchor health; each card is one click from the live tour via /<path>?tour=start&stop=<id>. It doubles as the tour's health board: a stop whose CSS anchor rotted, whose page stopped answering, or whose screenshot is missing shows up here and fails npm run audit:tour-atlas, which also holds the page's advertised stop count to the manifest's real total. Tests: tests/tour-atlas.test.js
Onboarding tier (Simple ⇄ Everything) Menu tags public/nav-data.js, runtime + window.twsTier public/nav.js, styles public/nav.css, homepage start path + gate pages/home.html + public/home.css Live Progressive disclosure for first-time visitors: the platform's ~119 nav destinations and ten deep homepage sections were competing with its core promise, so a new visitor now gets the ~28 links and the sections that carry one journey (make an avatar, build an agent, publish it) with a three-step start path under the hero. Everything else (the whole Launch menu, trading, token economy, Oracle, pay-per-call, dev platform, the stack) is tagged tier: 'advanced' / data-tier="advanced" and revealed by one control. Mechanism is one <html> class (tws-lite) over one localStorage key (tws:tier), applied pre-paint and never re-rendered (the nav binds document-level listeners once), with the two surfaces synced through a tws:tier-change event. Deep links into a gated section reveal it for that visit. Nothing is removed, only deferred. Docs: docs/onboarding-tier.md. Tests: tests/onboarding-tier.test.js
Tour Builder (no-code playground) pages/tour-builder.html → /tour-builder Live Point-and-click editor over a demo storefront: pick avatar, add stops, preview the real tour, export curriculum + Shopify snippets. Also ships Templates — ready-made tours (Sperax's DeFi protocol tour is the first) that load straight into the editor. Logic: public/tour-builder/builder.js, presets: public/tour-builder/presets/. Sperax template doc: docs/tutorials/sperax-tour.md
Avatar builder (full app) character-studio/ Fork of m3-org/CharacterStudio, MIT, see character-studio/LICENSE Web-first character creator
Scene Studio (3D scene editor) src/scene-studio/ → /scene: boot main.js, shared GLB loader loader.js, action bar actions.js, Agent chat tab agent-tab.js + its endpoint api/scene/agent.js, TSL material graph tab tsl-editor.js, first-run overlay empty-state.js, icon-button labels toolbar-a11y.js, chrome studio.css Vendored mrdoob/three.js r184 editor, MIT, see src/scene-studio/vendor/README.md Import GLBs, compose scenes, edit materials/lights, export. The sibling modules never touch vendor/**: they add the Import-from-Forge / Export-presets / Share bar (which docks beside the resizable sidebar rather than over its tabs), the empty-state card a brand-new scene needs, accessible names plus aria-pressed on the icon-only translate/rotate/scale buttons and names on the animation timeline's play/pause/stop transport, and toast-based failures in place of native alert()/prompt(). Below 600px the sidebar dock drops the vendored .TabbedPanel 335px floor so it fits a 320px screen instead of hanging 15px off it, and the empty-state card starts below the action bar and caps itself at the viewport region. Pinned under the nav by --nav-h (the real injected-header height), not --header-h. Two added sidebar tabs: Agent drives the open scene by prompt through a free, keyless, rate-limited tool-calling model, executing real editor.execute(Command)s and pushing an undoable, screenshotted version per mutating turn; Nodes is a dropdown-wired TSL material graph editor for the selected object, no node canvas. The studio adds tws-modal-open to <body> so the site-wide corner-stack widgets (public/corner-stack.js) don't float on top of its controls. Deep links: ?model=<glb_url>, ?handoff=1 from /pose, #file=<url>. Docs: docs/scene-studio.md, src/scene-studio/README.md. Tests: tests/scene-studio-actions.test.js, tests/scene-studio-agent-restore.test.js
Diorama (text → 3D world) src/diorama/ → /diorama In-repo · backend api/diorama.js One sentence → an explorable 3D diorama: Claude composes the scene, each object is forged to a real GLB, assembled live, saved to a public gallery + shareable permalink
Workbench (image → 3D workflows) Page pages/workbench.html → /workbench + src/workbench/: controller main.js, viewport viewport.js, in-browser mesh ops mesh-tools.js, node model workflows.js, runner runner.js, graph editor graph-editor.js, API client api.js Live A desktop-style workspace: icon rail (Generate, Workflows, Extensions, Settings), a workflow panel of node cards, and a viewport with undo/redo, import, GLB/OBJ/STL/PLY export, smooth, decimate and free memory. Workflows are typed image/mesh chains saved per browser and edited in a node graph; they run against the real Forge endpoints (/api/forge, /api/forge-batch, /api/forge-rembg, /api/forge-remesh, /api/forge?action=rig, /api/material-studio), checkpointing in-browser edits to durable storage before any server step. A Batch drawer (toolbar icon or B) queues up to 8 prompts against /api/forge-batch and polls the group. Extensions reads the live engine catalog and lane health. Docs: docs/workbench.md
Modly (local GPU generation + Modly app integrations) Hub page pages/modly.html → /modly + src/modly-page.js; shared local client src/modly-local.js; Forge "Use your GPU" lane src/forge-modly.js wired in src/forge.js → /forge; desktop app apps/forge-desktop/; Modly extensions integrations/modly/ Live (web); desktop app and extensions in-repo Builds on Modly (MIT, Lightning Pixel). Browser surfaces talk to the visitor's own Modly on localhost only after Connect, run its image-to-3D models with real progress and cancel, and copy results to storage so rig/optimize/AR work. Modly users get three.ws cloud nodes and publishing. Docs: docs/modly.md. Tests: tests/modly-local.test.js, integrations/modly/tests/
three.ws Forge for desktop (Electron app) App apps/forge-desktop/ (Electron main electron/main/, React renderer src/, FastAPI engine api/); download page pages/forge-desktop.html → /forge-desktop + src/forge-desktop.js, src/forge-desktop-release.js; release pipeline apps/forge-desktop/cloudbuild.yaml, scripts/release-mac.sh In-repo; download page live after deploy, shows "run from source" until the first release is published (owner-gated) Fork of Modly (MIT, Lightning Pixel) rebranded and wired to three.ws: device-flow sign-in with the key in OS secure storage, one-click Publish to /avatars/:id, the CC0 library in Import, three.ws cloud nodes, and an electron-updater feed at /releases/forge/. Docs: docs/forge-desktop.md, runbook docs/ops/forge-desktop-release.md. Tests: tests/forge-desktop-release.test.js, apps/forge-desktop npm run test:node
Mesh tools + slicer handoff src/mesh-ops/ (worker repair/smooth/decimate, panel in Forge Optimize and /m/:id), src/slicer-handoff.js, route api/slicer/model.js → /api/slicer/:id/[Nmm/]model.stl|3mf over api/_lib/print/slicer.js Live after deploy; adapted from Modly (MIT) In-browser mesh repair, Taubin/Laplacian smoothing and decimation with undo, plus Open in OrcaSlicer / Bambu Studio and print-ready STL/3MF downloads. Docs: docs/forge.md. Tests: tests/mesh-ops.test.js, tests/slicer-handoff.test.js
Forge Workflows (node builder) Page pages/forge-workflows.html → /forge/workflows + src/forge-workflows/ (graph model, runner, node registry, editor, templates) Live after deploy A visual editor that chains the real Forge endpoints into one run: Generate 3D (any live engine, or Your GPU via Modly), Remesh, Rig, Segment, Stylize, Game-ready, Preview, Export and Save, with typed ports, preflight, per-node progress, cancel, a step cache, re-run from a failed node and For Each batches adapted from Modly (MIT). Four templates, browser autosave, JSON import/export; phones get a step list that runs templates. Linked from the /forge header. Docs: docs/forge-workflows.md. Tests: tests/forge-workflows-graph.test.js, tests/forge-workflows-runner.test.js
CAD Forge (text → parametric CAD) Page pages/cad.html + src/cad/ → /cad and → /cad/:id (controller main.js, viewer viewer.js, shared parameter contract params.js), API api/cad.js → /api/cad over api/_lib/cad/ (writer ladder, write/build/repair loop, store, service), MCP tools api/_mcp3d/tools/cad.js (cad_generate, cad_rebuild), sandboxed kernel worker workers/cad-forge/ Built and verified locally · worker deploy pending (deploy it before the API image that carries /cad) A sentence becomes a build123d program the OpenCascade kernel has accepted: kernel errors go back to the writer (Kimi K3 on NIM first) until it builds, and the page streams each real stage. Key dimensions are annotated constants that become sliders; each value set rebuilds on the kernel and is cached under its own link. Downloads STEP, STL, GLB (true scale), a four-view SVG drawing and the Python program; handoffs to AR, Materialize and Scene Studio; refinements are linked designs. Parts join cross-entity search as type part. The worker runs model-written code with a static policy, seccomp, an unprivileged uid and rlimits, under a zero-role service account. Docs: docs/cad-forge.md. Tests: tests/cad-forge.test.js plus the worker's in-image gate
Anatomy (machines as interactive cutaways) Page pages/anatomy.html + src/anatomy/ → /anatomy and → /anatomy/:id (spec contract spec.js, streaming scanner stream.js, shapes, effect shaders, viewer.js, embeddable UI mountAnatomy in runtime.js), API api/anatomy.js → /api/anatomy over api/_lib/anatomy/ (writer ladder, spec guide, service, store), agent skill .agents/skills/anatomy/ (reference.md generated by scripts/build-anatomy-skill.mjs) Built and verified locally One line becomes an isometric wireframe cutaway: a model writes a JSON spec that the page draws part by part while it streams, then saves to a permalink. Real part motion (spin, oscillate, slider-crank, pulse) with inherited hierarchies, WebGL flame/exhaust/plasma/water/smoke/steam/sparks/arc shaders, particle flows, a focus-framing tour, explode, section, x-ray and part inspection. Agents author specs directly with the skill and save them via action: "publish". Docs: docs/anatomy.md. Tests: tests/anatomy.test.js, browser check scripts/verify-anatomy-browser.mjs
Scene Composer (dress an avatar) pages/compose.html → /compose + src/scene-compose.js Live Forge props from text and parent them to a rigged avatar's skeleton bones, then Export GLB or save them back onto the avatar record as appearance.attachments. Bones are grouped into readable regions and stripped of rig prefixes; transform gizmos, 50-deep undo, grid snap, camera presets. Feeds off api/forge.js, api/forge-gallery.js (own creations, falling back to the community showcase for a first-time visitor), api/explore.js ?source=avatar&only3d=1 for the avatar picker, and PATCH /api/avatars/:id for Save outfit. Below 900px the scene panel becomes a drawer. Docs: docs/compose.md
Splat Viewer (photoreal Gaussian avatars) pages/splat.html → /splat + page module src/splat-viewer.js, renderer src/splat-stage.js Live Renders Gaussian-splat and radiance-field scenes in the browser, the photoreal output of capture engines like GaussianAvatars and HumanGaussian. Loads a .ply, .spz, .splat, .ksplat or .sog by URL, by upload, by drag-and-drop onto the stage, or from a ?src= deep link, plus two procedurally generated samples; decoding is entirely client-side and nothing is uploaded. The format is sniffed from the bytes rather than the filename, and the URL loader rewrites GitHub blob/raw, Hugging Face /blob/ and Dropbox links to their CORS-enabled raw form so a pasted human-facing link still fetches. src/splat-stage.js is shared with the Forge Studio Lab (src/forge-studio/lab/mesh-to-splat.js) and wraps Spark (@sparkjsdev/spark, MIT), lazy-loaded on first render and torn down explicitly (the WebGL context is released by hand on every scene swap, which Spark's own dispose stops short of). Every state is designed: idle/drop, engine load, fetch, decode, sort, error, and a live HUD carrying the scene label, its real splat count, a recenter control and a download of the loaded buffer. Docs: docs/splat.md
X post reader and video tool Shared reader api/_lib/x-syndication.js, endpoints api/x-video/extract.js + api/x-video/download.js, page pages/x-video.html → /x-video + module src/x-video.js Live One keyless reader for public X posts: text, author, likes/replies/reposts/quotes/views/bookmarks, timestamps and every mp4 variant. Three rungs in order (X syndication, fxtwitter, guest-token GraphQL when X_BEARER_TOKEN is set); a rung that fails falls through, and only an all-rungs "gone" answer becomes post unavailable (404). It replaced oEmbed (text only) in pumpfun_social_x_post_impact (api/pump-fun-mcp.js) and src/social/x-post-impact.js. The free /x-video page extracts a post and offers one download per quality; the download proxy accepts only https video.twimg.com and pbs.twimg.com, refuses credentials and ports, and never follows redirects. Docs: docs/x-video.md
Creator portfolio (human profile) pages/profile.html → /u/:username (self-view /profile), backend api/users/[username].js + paginated api/users/[username]/creations.js → /api/users/:username/creations Live Every three.ws user's public portfolio: avatars, agents, widgets, skills, plugins, coins, memories, items for sale, and (added 2026-07-12, extended 2026-07-23) a Creations tab merging forged 3D models + Scene Studio worlds + Material Studio restyles — real, live, spinning <model-viewer> cards, cursor-paginated for 100+ items. /forge, /diorama, and /restyle all stay anonymous by default (no login required); a signed-in creator's user_id is attached to forge_creations/dioramas rows at generation/save time (migration api/_lib/migrations/20260712010000_creator_portfolio_user_ids.sql) and to a new material_restyles row per AI restyle or colorway variant (migration api/_lib/migrations/20260723140000_material_restyles.sql, store api/_lib/material-restyle-store.js) so those creations surface here. The same opt-in attribution now links back from the diorama viewer HUD, the diorama gallery cards, and the forge result bar ("by @user") whenever a creation's creator is known. /@:handle (pages/handle.html) is a separate, narrower agent-embed page — not the human portfolio.
Model detail page (/m/:id) pages/model.html → /m/:id, page module src/model-page.js + pure helpers src/model-lib.js + src/model.css, backend api/forge-creation.js (?related=&view= + voted state; DELETE, scoped to the owning x-forge-client, lets a creator erase a creation, its stored GLB, preview, and recorded source uploads included) and api/forge-comments.js, store reads api/_lib/forge-store.js (getPublicCreation/listRelated/recordCreationView), schema api/_lib/migrations/20260805120000_model_page.sql Live Every finished forge model as a first-class page in the classic model-platform detail layout: interactive viewer hero with AR and fullscreen, title + creator card with a real follow button (follow graph), live triangle/vertex stats from GET /api/3d/inspect (nothing persisted, nothing invented), the full prompt as the description, honest attribute chips, anonymous likes shared with the Forge-Off vote rail (forge_votes, same forge:cid id), a real page-view counter (forge_creations.view_count), a signed-in comment thread (forge_comments, bell-notifies the creator via the comment event type), paid remix via the existing x402 rail, embed/share/download, and a same-category suggested-models rail. Linked from the Details button on /creations cards and the Forge showcase. Tests: tests/model-lib.test.js
Labs (hidden-gems hub) pages/labs.html + src/labs.js → /labs In-repo Data-driven discovery hub: renders every data/pages.json entry flagged showcase: true as a live card (status check + iframe preview), filterable by category
Playground (drop-in .glb viewer) pages/playground.html → /playground Live A 3D scene sandbox with nothing to install: drop or pick a .glb and it renders in <model-viewer> with animation playback, environment and background presets, auto-rotate, shadow and exposure controls, live file stats, and a copy-ready embed snippet. The file never leaves the browser (it is read as a blob URL), so the failure path carries the weight: a model that will not parse, a stalled download, or a blocked model-viewer CDN lands in an in-viewer error card with Retry and a file picker rather than an endless spinner.
Holo Sticker (procedural foil demo) pages/holo.html → /holo, app src/holo.js, bendable extrusion src/holo-geometry.js, styles src/holo.css Live A real-time holographic foil sticker rendered with physical materials, fully procedural (no assets fetched): tilt it with the pointer, peel the corner (vertex-shader cylinder roll over faces rebuilt as a constrained Delaunay mesh with an interior lattice, so they curl instead of tearing), switch foil styles, die-cut arbitrary typed text via a marching-squares vectorizer, and download the frame as a PNG
Machine Atlas (code-generated machines) pages/assembly.html → /assembly, app src/assembly.js, styles src/assembly.css, geometry src/assembly/ Live Two working machines with no model files behind them: a nine-cylinder radial aero engine and a coupled steam locomotive, generated at runtime from their dimensions (revolved profiles, extruded sections, lofted NACA blade stations). Motion is solved, not keyframed: pistons follow the exact planar slider-crank and the locomotive valve gear closes a four-bar chain every frame by circle intersection. Live dimension sliders rebuild the geometry, explode and structure views take it apart, hover names any part, subassemblies toggle, and the Source panel prints the generating calls from the live values. Every configuration is a shareable link; export as GLB or save a PNG frame. Docs: src/assembly/README.md. Tests: tests/assembly-machines.test.js
Examples gallery pages/examples.html → /examples, curated snippets public/examples.js, generated index renderer public/examples-index.js, styles public/examples.css, hosted example tree public/examples/ built by scripts/build-hosted-examples.mjs Live Two halves. The top is 17 copy-paste snippets that RUN on the page, grouped into four lanes (avatars and embeds, 3D models, agents, agent economy) behind a sticky jump nav and a text/tag filter that folds away lanes as they empty (a deep link always beats an active filter): each is a complete document loading the production CDN bundle into an iframe, so "Run" executes exactly the code shown, and the model/agent/economy lanes call the live CORS-open production APIs rather than illustrating them (free text→3D at /api/v1/ai/text-to-3d, free text→speech at /api/v1/ai/tts played through the new speakAudio() viseme path, /api/3d/inspect, the 112-clip /animations/manifest.json, /api/forged, the public no-auth MCP server at /api/mcp-studio for both tools/list and a live look_at_model render-and-critique, the 402 quote from /api/x402/forge, /api/pump/launches). The agent-from-files card loads a real manifest from /examples/coach-leo/manifest.json: npm run build:examples publishes examples/coach-leo/ and its wave skill into public/examples/ with body/image URIs rewritten absolute, so the manifest resolves the same way off-site as it does here. The bottom is every example that ships in the repo, generated by scripts/build-examples-index.mjs scanning every examples/ directory into data/examples.json, mirrored to the served public/examples.json by scripts/mirror-examples-index.mjs (npm run build:examples runs all three). Because it is scanned, the page cannot advertise a deleted example or miss an added one; each card carries the files it contains and the command that runs it. Tests: tests/examples-page.test.js, tests/examples-index.test.js
Cookbook (runnable recipes) Index pages/cookbook.html -> /cookbook, recipe viewer pages/recipe.html -> /cookbook/<slug>, manifest public/cookbook-manifest.js, styles public/cookbook.css, recipe prose docs/cookbook/, runnable files public/cookbook/recipes/, notebook export public/cookbook/self-correcting-3d/ Live The sibling of the Examples gallery, and deliberately a different thing: an example is a snippet you read on the page, a recipe is a file you download and run. Five recipes, each one executed against the live API before it was published: a standard-library text-to-3D CLI, a parallel asset-pack builder that emits a manifest plus a gallery, an MCP server that hands Claude Code or Cursor a 3D tool, a CI budget gate over api/3d/inspect.js, and the function-calling-plus-vision notebook also submitted to the OpenAI Cookbook. The manifest is the single source of truth for both surfaces; recipe prose is markdown under docs/cookbook/ fetched by the viewer, so adding a recipe is a manifest entry plus a .md plus the file itself. Route order is load-bearing in both vercel.json and the dev middleware: the notebook's static export must be matched before the generic /cookbook/<slug> rule or the viewer shadows it. Docs: public/cookbook/recipes/README.md. Tests: tests/cookbook.test.js
Walkthroughs (interactive product tours from real frames) Index pages/walkthroughs.html + src/walkthroughs-index.js → /walkthroughs, player pages/walkthrough.html + src/walkthrough.js → /walkthroughs/<slug> (routed in vercel.json, mirrored by the Vite dev middleware in vite.config.js), pure step geometry src/walkthrough-geometry.js, generated manifest + screenshot sets public/walkthroughs/ captured by scripts/capture-walkthroughs.mjs Live Step-by-step guided tours (forge a 3D model, build an agent, embed an avatar, find an agent worth using) built from real frames captured on the live product: each step zooms and pans to the element it describes, cuts a spotlight around it, and anchors a callout, so it reads like a screen recording but is a handful of deep-linkable, keyboard-operable JPEGs that degrade to annotated stills under reduced motion. Index and player read the same generated manifest, so a walkthrough that did not capture cleanly cannot be advertised. Registered in data/pages.json.
Cross-entity search pages/search.html → /search + page module src/search-page.js, backend api/search.js + query layer api/_lib/cross-search.js Live The one search across every creation type: avatars, on-chain/Solana agents, forged 3D models, worlds, and coins. Federates (not one SQL UNION, because the stores are genuinely heterogeneous and two of five are not even in the same database) five parallel queries, normalizes into one card shape, and ranks by recency plus real signals (follower count via user_follows, remix count, view count); see the file header in api/search.js for the full unify-vs-federate writeup. Model results carry a working "Remix, $0.25" action against the existing paid rail (api/x402/remix-asset.js), reused from pages/creations.html rather than re-derived. Coin search checks three.ws's own launch directory (pump_agent_mints) first, then falls back to market-wide pump.fun/Birdeye search for broader coverage (those external matches carry no verified timestamp or creator profile, and are ranked/labelled accordingly). The page reads ?q= and ?type= from the URL before it paints the filter row, so a shared scoped link shows the filter it is actually applying; a type whose source returned nothing for the current query is dimmed from the real counts in the response. The backend answering {enabled:false} (creation stores unreachable) renders its own "search is warming up" state with a retry and live browse links, never a false "nothing matched". Enter runs the query without waiting out the debounce and Escape clears it. Linked from the Discover nav menu.
My Creations (personal creation index) pages/mine.html → /mine (alias → /my-creations) + page module src/mine.js, styles src/mine.css Live The answer to "where did the thing I just made go?". One newest-first grid merging four real feeds: /api/agents and /api/avatars/mine (session-scoped), /api/forge-gallery (scoped to this browser's forge:cid, so a model forged before signing up is still findable), and /api/users/:username/creations (models, worlds and restyles forged while signed in on any device), de-duplicated by id. Cards carry Open, Edit (or "Forge again", which re-runs the original prompt through /forge?prompt=) and Copy link, with lazy <model-viewer> previews under a six-context budget. Signed out it still renders this browser's models behind a sign-in prompt rather than an empty void, and a total source failure renders an error state, never a false "you have nothing". Reachable from the nav's My creations button (public/nav.html, drawer row in public/nav.js, Build menu in public/nav-data.js), the dashboard sidebar, the create-agent success screen, the /create hub, /forge's creations strip and /my-agents. Tests: tests/mine-page.test.js
Cross-surface rankings, streaks & badges pages/rankings.html → /rankings, backend api/leaderboard/unified.js, streak/badge engine api/_lib/streaks.js (migration api/_lib/migrations/20260712020000_leaderboard_streaks_badges.sql), daily Top-10 badge sweep api/cron/leaderboard-rollup.js Live Five real, queried leaderboard metrics — creations (forge models + worlds), remixes received, coin launches, followers, and walk distance (signed-in walkers, all-time) — ranked live with the viewer's own rank pinned even off-page. Every signed-in qualifying action (login, a finished forge model, a saved world, a /walk session) rolls a per-user daily streak in user_streaks via recordDailyActivity(), called from api/_lib/auth.js, api/_lib/forge-store.js, api/_lib/diorama-store.js, and api/walk/metrics.js. Four real earned badges persist in user_badges: First Creation, Remixed (awarded in api/x402/remix-asset.js when a remix lands on your creation), 7-Day Streak, and a daily-refreshed top10_<metric> per leaderboard. Streak + badges surface on the profile (pages/profile.html) and the Rankings page itself. Rejected metrics (documented in api/leaderboard/unified.js's header): royalties earned in USD (the settlement record is a single overwritten JSONB column, not a cumulative ledger) and /play activity (no per-human-user session table exists).
Agent creator earnings ("Earned") API api/agents/[id]/earnings.js → GET /api/agents/:id/earnings, read model api/_lib/agent-earnings.js, snapshot api/_lib/creator-earnings-snapshot.js run by api/cron/creator-earnings-snapshot.js (every 30 min), pump.fun + on-chain client api/_lib/pump-creator-fees.js, migrations 20260930120000_launcher_claims.sql and 20260930121000_agent_coin_earnings.sql, card src/shared/agent-earnings-card.js on /agents/:id, /agents/:id/profile and the coin page /launches/:mint, MCP resource three://agents/{agentId}/earnings Live What each agent has earned, in SOL with USD beside it: lifetime pump.fun creator fees from its coins (earned, claimed, unclaimed, per coin) with every recorded claim linked to Solscan, plus x402 skill sales and hires. Each coin's fee recipient is read on-chain; pump.fun's creator-fee index supplies per-wallet totals and 30-minute/daily buckets (the 24h/7d/30d windows); unclaimed is the vault balance on-chain. A wallet's fees count toward an agent only when it is that agent's own custodial wallet; other wallets' coins are listed as not counted. Devnet excluded. Docs: docs/api-reference.md. Tests: tests/agent-earnings.test.js, tests/pump-creator-fees.test.js
Trader + earnings leaderboard pages/leaderboard.html → /leaderboard, controller src/leaderboard.js, Earned tab src/leaderboard-earned.js, styles src/leaderboard.css; APIs api/sniper/leaderboard.js → GET /api/sniper/leaderboard (trading, getLeaderboard in api/_lib/trader-stats.js) and api/leaderboard/earnings.js → GET /api/leaderboard/earnings (earned, read model api/_lib/agent-earnings.js) Live Two boards on one page, with the tab and window in the URL (?tab=earned&window=7d) so any view is shareable. Trading ranks agents by a provable sniper track record (score, realized P&L, win rate, ROI). Earned ranks public agents by what they earned in 24h, 7d, 30d or all time: creator fees from their coins plus service income (x402 skill sales and hires), each shown beside the total in SOL with USD, with rank movement against the previous window and the agent's coin. Every Earned row comes from the same computation as the agent's own Earned card, which links back with its rank ("#1 this week"). Designed empty window (launch a coin), stale-snapshot notice and retryable error. Docs: docs/api-reference.md. Tests: tests/agent-earnings-board.test.js; live cross-check scripts/check-earnings-board.mjs
Creator-fee payouts Core api/_lib/creator-payouts-core.js, store and sender api/_lib/creator-payouts.js, endpoint api/creator-payouts.js, crons creator-payout-distribute.js + creator-payout-reconcile.js, page pages/creator-payouts.html → /creator/payouts + src/creator-payouts-page.js, migration 20261023190000_creator_payouts.sql Live; sending off until CREATOR_PAYOUTS_LIVE=true The creator's share of every claimed pump.fun fee, sent to a wallet the owner registers by signature plus step-up (48 hour cooldown on change, session-only). One distribution row per claim, held with a named reason (no wallet, cooldown, below minimum, paused), reconciled against the chain. Docs: docs/creator-payouts.md. Tests: tests/creator-payouts.test.js
Revenue ledger and reinvest rules Core api/_lib/revenue-ledger-core.js, sync api/_lib/revenue-ledger.js, reconcile api/_lib/revenue-reconcile.js, rules and runs api/_lib/revenue-reinvest.js, routes api/_lib/revenue-routes.js → /api/revenue/*, crons revenue-ledger-reconcile.js + revenue-reinvest.js, pages pages/earnings.html → /earnings + pages/agent-earnings.html → /agents/:id/earnings with src/earnings-page.js, src/earnings-chart.js, src/agent-earnings-page.js, migration 20261023170000_revenue_ledger.sql Live; reinvest legs need an owner confirmation and obey spend guards Every income event (creator fees, skill sales, hires, royalties, invoices, realised trading PnL) in one ledger with its Solana transaction, hourly chain reconcile, CSV and JSON export, optional public page, and capped reinvest rules the owner confirms in the browser. Docs: docs/revenue-ledger.md. Tests: tests/revenue-ledger.test.js
Creator-fee payouts Core api/_lib/creator-payouts-core.js, store and sender api/_lib/creator-payouts.js, endpoint api/creator-payouts.js, crons creator-payout-distribute.js + creator-payout-reconcile.js, page pages/creator-payouts.html → /creator/payouts + src/creator-payouts-page.js, migration 20261023190000_creator_payouts.sql Live; sending off until CREATOR_PAYOUTS_LIVE=true The creator's share of every claimed pump.fun fee, sent to a wallet the owner registers by signature plus step-up (48 hour cooldown on change, session-only). One distribution row per claim, held with a named reason (no wallet, cooldown, below minimum, paused), reconciled against the chain. Docs: docs/creator-payouts.md. Tests: tests/creator-payouts.test.js
Funded launch intents Pairs api/pump/pairs.js + api/_lib/pump-launch-pairs.js, intents api/pump/launch-intents.js + api/_lib/pump-funded-launch.js, page pages/launch-intent.html → /launch/intents + src/launch/launch-intent-page.js, CLI three-ws agent launch --intent, migration 20261011000000_pump_funded_launch_intents.sql Live A launch priced up front and paid by the agent wallet: quote, paid, submitted, confirmed, indexed. Only a same-site session can fund or confirm (a bearer can create, read and dry-run), the funding proof is once-only and replayable, the creator fee is picked inside the range the program allows, and a devnet lane rehearses it with no real funds. Docs: docs/launch-intents.md. Tests: tests/pump-funded-launch.test.js
create-agent (one command, one 3D character) packages/create-agent/ (client src/forge.js, scaffold src/scaffold.js, CLI bin/create-agent.js), server tools api/_mcp-studio/tools.js Live npm create @three-ws/agent "a friendly cartoon astronaut" generates a textured figure, rigs it, downloads the GLB, and writes a folder with a working demo page and the embed snippet. No account and no API key: it rides the public, keyless JSON-RPC tools on /api/mcp-studio (forge_avatar, forge_free, rig_mesh) that the platform already exposes to MCP clients. A rigged character reliably outlives the endpoint's inline wait, so the client collects the returned poll handle and, when the job that finished was only the mesh, rigs it before reporting done: that is what the stage field on a pending result exists for. Progress is real elapsed time, never an invented bar. Docs docs/create-agent.md. Tests: tests/create-agent.test.js
Agent persona template gallery (create wizard) Catalog data/agent-templates.json, module src/create-agent-templates.js, dialog + strip in pages/create-agent.html → /create-agent, wiring wireTemplates in src/create-agent.js Live "Start from a template" in step 1 of the wizard: 26 Solana-first finance personas (whale watching, wallet safety, yield, launch vetting, tax planning) in a searchable, tag-filterable grid with a preview pane. One click prefills persona, greeting, category and skills (name, description and tags only fill what is empty), with Undo and a jump to the Personality step. Rewritten from the owner's defi-agents repo; every persona branded for another project dropped, tools are real MCP tool names, no addresses, no third-party coins. The new finance category is also offered by the marketplace filter, the agent editor and the spec generator. Docs docs/create-agent.md. Tests: tests/agent-templates.test.js, tests/create-agent-templates.test.js, tests/e2e/create-agent-templates.spec.js
Glance (agent cards for home screens, READMEs and chat) Page public/glance/index.html -> /glance (+ glance-page.js, glance.css), hosted element public/glance/element.js, endpoints api/glance/card.js / api/glance/mine.js / api/glance/token.js / api/glance/template.js, model api/_lib/glance-card.js, SVG api/_lib/glance-svg.js, PNG api/_lib/glance-png.js, widget tokens api/_lib/glance-tokens.js (glance_widget_tokens), Adaptive Card api/_lib/glance-adaptive.js, Windows widget worker public/glance-sw.js (imported by the VitePWA service worker, manifest widgets member in vite.config.js), Android home screen widget solana-mobile/android-overlay/ (applied by solana-mobile/scripts/apply-overlay.mjs inside build-apk.sh), macOS and iOS WidgetKit widget apple/ (shared apple/GlanceKit/, extension apple/GlanceWidget/, Mac app apple/macos/, an iOS target in ios/native/App/App.xcodeproj), npm client packages/agent-glance/ Live One agent reduced to what fits in an OS widget slot: name, one live number (actions in the last 24h), and a link back. The same model renders five ways from one endpoint (JSON, SVG, PNG, Adaptive Card, and the <agent-glance> element), which is what keeps a new surface a rendering job rather than a data job. Windows 11 installs the widget straight from the PWA manifest (no store submission). Android ships it in the app (1.1+): a WorkManager-refreshed AppWidgetProvider that fetches the PNG with a revocable per-account widget token minted on /glance, keeps the last card offline, and opens the agent on tap. macOS and iOS run one WidgetKit extension over the same PNG and the same token, in small, medium and large: the Mac ships as a Developer ID menu bar app that holds the token and feeds the widget, and the iPhone gets the extension inside the existing Capacitor app. Both fetch the card in each theme so the widget follows the reader's appearance. npm run check:apple-widget proves both Xcode projects and the client-to-server contract without a Mac in the room. Deliberately not the 3D embed: no widget host on any of these platforms can run WebGL, so the body stays at /widgets and the status lives here. Private avatars never leak (the thumbnail is attached only for a public or unlisted avatar; everything else draws a generated monogram). Spec specs/GLANCE_CARD.md, docs docs/glance.md, docs/native-widgets.md. Tests: tests/glance-card.test.js, tests/glance-png.test.js, tests/glance-tokens.test.js, tests/glance-sw.test.js, tests/agent-glance-sdk.test.js, guard scripts/check-apple-widget.mjs
Daily Match (agent output arena) pages/daily-match.html → /daily-match, backend api/leaderboard/daily-match.js Live Live daily standings ranking public agents by real output shipped since 00:00 UTC: agent_actions events, sniper + pump trades, confirmed skill sales, and coin launches, with realized sniper P&L shown for context (never scored). Computed live per request (no rollup cron), resets naturally at UTC midnight; includes yesterday's champion and a live-output feed. Reputation-first: no payouts hang off the score. Format adopted with credit from Bowyer's Arena (bowyer.app/arena), who build their agent pages on three.ws avatars.
KOL Tracker pages/tracker.html → /tracker, backend api/kol/[action].js → GET /api/kol/tracker?window=&limit=, aggregator src/kol/tracker.js, wallet list src/kol/wallet-store.js (bundled src/kol/wallets.json + admin R2 imports via POST /api/kol/import-gmgn), FIFO P&L engine src/kol/wallet-pnl.js, cached X follower/avatar lookup src/kol/x-profile.js Live Solana crypto KOLs ranked by realized P&L computed from each tracked wallet's own on-chain trade history (24h/7d/30d), with win rate, volume, and trade count — every number traceable to real trades, never a competitor's computed leaderboard. A wallet only shows an X handle/avatar/follower-count when an admin has explicitly attached a verified xHandle via import-gmgn's xHandles map (never inferred or scraped); unattached wallets rank by wallet address alone. Rows with no configured trade source (PUMPFUN_BOT_URL) fall back to an imported pnlUsd/winRate labeled with its pnlSource rather than fabricating on-chain numbers. Prewarm cron: api/cron/kol-tracker-refresh.js.
Keyless X guest reader (profiles and timelines) api/_lib/x-guest/, rung 2 in src/kol/x-profile.js, coin X-account feature api/_lib/oracle/x-account.js, feeder api/cron/oracle-social-ingest.js (every 10 min) Live Reads public X profiles and timelines through the guest-token GraphQL surface with no API key, adapted from XActions (Apache-2.0). Backs the KOL tracker's follower counts when TWITTER_BEARER_TOKEN is unset or rate limited, adds the coin's own X account age and followers to Oracle intel, and feeds tracked-KOL cashtag tweets to POST /api/oracle/social. Fails soft with a named reason (rate_limited, stale_query_id, ...). Tests: tests/x-guest.test.js.
Agent Galaxy (every agent as a star, positioned by meaning) pages/galaxy.html → /galaxy + src/galaxy.js, backend api/galaxy.js → GET/POST /api/galaxy, assembler api/_lib/galaxy.js, embedding cache api/_lib/agent-embeddings.js, live-economy overlay over GET /api/galaxy/flows In-repo · awaits watsonx credentials Every published agent embedded with an IBM Granite model on watsonx.ai, projected to 3D by PCA and grouped into k-means constellations that Granite then names, rendered as a Three.js point cloud. Typing a phrase embeds the query in the same space and lights the matching stars; the Money-Cam layer animates real on-chain transfers between them, and star brightness comes from each agent’s real wallet net worth. No mock path anywhere: with no watsonx credentials on the service GET /api/galaxy answers 503 and the page says so, offering the agent list and the integration doc instead of an empty universe. Tests: tests/e2e/galaxy.spec.js, tests/galaxy-flows.test.js
The Agent Economy (live, network wide) pages/economy.html → /economy + page module src/economy-live.js, hire panel src/shared/agent-hire.js, feeds GET /api/agents/economy?view=offers (api/agents/economy.js), GET /api/marketplace/agents, GET /api/agenc/x402-services (api/agenc/[action].js) over the shared discovery client api/_lib/x402/bazaar-client.js Live The wide-angle counterpart to the curated two-agent demo at /agent-economy: the real population of agents earning on three.ws, the agent-to-agent service market they hire each other through, and the live x402 bazaar of pay-per-call endpoints across Solana and Base. Three feeds, each owning its own loading / empty / error state so a slow or failing one never blanks the page, each retryable in place, and each polled every 45s while the tab is visible. Service rows name themselves from the facilitator's metadata when it publishes one and from the endpoint URL when it does not (most listings carry no name), show the endpoint they charge for, and never render a link to a path template or a rejected URL scheme. The A2A offers feed is empty until an owner prices an agent skill (agent_paid_services), which is a real state with a route out of it, not a stub. Tests: tests/api/bazaar-endpoints.test.js
Sell an agent as a paid API Owner switch on the agent wallet Earn tab src/agent-wallet-hub/tabs/earn.js (client src/agent-economy-hub.js), owner API api/agents/[id]/api-service.js → GET/PUT /api/agents/:id/api-service, paid route api/x402/agents.js → POST /api/x402/agents/:id + free list GET /api/x402/agents, rules and ledger api/_lib/agent-api-service.js, shared turn api/_lib/agent-turn.js, discovery slice buildSellableAgentItems() in api/wk.js Live An owner flips "Sell this agent as an API", sets a USD price per call (floor $0.001, the smallest settle the facilitator co-signs) and a public description; the agent becomes a stable x402 v2 endpoint that answers one turn with the same persona, custom skills and premium-skill rules as /api/agents/talk. The 402 leads with Solana USDC and pays the agent's own payout wallet; the turn runs before settlement so a failed call is never charged; each settled call is written to agent_revenue_events (skill agent-api, net of PLATFORM_FEE_BPS, settled_to_wallet = true so it never counts as treasury-withdrawable). Only public agents with a brain and a Solana payout address can be sold, and the switch says why when one cannot. Agents on sale appear in /.well-known/x402.json and under Agents on /x402. Docs: docs/x402.md, docs/api-reference.md. Tests: tests/api/x402-agent-api.test.js
Platform analytics (every platform total, one page) pages/analytics.html → /analytics + page module src/platform-analytics.js, endpoint api/platform/analytics.js → GET /api/platform/analytics?window=30d|90d|all, data layer api/_lib/platform-analytics.js Live The partner and investor view: agents, agents with a wallet, coins launched, 3D models generated, LLM tokens processed, x402 settlements and volume, marketplace sales and volume, and agent-to-agent hire volume, each with an all-time total, a zero-filled daily series and a method string rendered under "How each number is calculated". Counting predicates match the endpoints that already publish the same figure (/api/home-stats, the MARKET_PAID_KINDS gate, platformEconomyStats()), so no two pages disagree. A failing source is null plus a named errors entry, never a zero; the page shows an unavailable tile for it and a whole-page retry only when nothing could be read. Creator fees (SOL) read the agent_coin_earnings snapshot from parity order 015 with the same per-wallet counting rule as /api/agents/:id/earnings. Docs: docs/api-reference.md. Tests: tests/platform-analytics.test.js
Why three.ws (builder pitch on live numbers) pages/why-three-ws.html → /why-three-ws + page module src/why-three-ws.js Live What a builder gets, the build-get found-earn-reinvest loop as an accessible SVG, and a comparison against categories of platform (never named products) where each cell links to its proof. The five proof tiles are read from GET /api/platform/analytics?window=all (nothing numeric is typed into the page); a failed metric renders as Unavailable, never zero. Tests: tests/why-three-ws.test.js
Builder competitions (tokenized build-off) pages/compete.html → /compete, /compete/:slug + page module src/compete.js, config data/competitions.json (ships empty), API api/competitions.js, logic api/_lib/competitions.js, registrations api/_lib/migrations/20261023200000_competition_entries.sql Live (no competition configured) Enter an agent, launch its coin through three.ws inside the window, rank by creator fees earned (same attribution as the agent earnings page). Phase and countdown come from the clock; dates, tracks, prizes, judges and rules come from data/competitions.json, so running one is a config edit. Empty config renders "no competition is running". How to run one: docs/competitions.md. Tests: tests/competitions.test.js
Experiments (public write-ups of what we tried) pages/experiments.html → /experiments + page module src/experiments-index.js, entries data/experiments.json, write-ups docs/experiments-<slug>.md (served at /docs/experiments-<slug>), validator scripts/lib/experiments-index.mjs run by npm run build:pages, published index public/experiments.json Live One card per experiment (question, status, spend, published date, headline result) with a URL-synced status filter, each opening a write-up in the six-section template: the question, method, spend, result, what we got wrong, what we changed, plus an appendix of the SELECT queries behind every number. The build fails on a missing field, an unknown status, a missing write-up, or a write-up missing a template section. How to add one: docs/experiments.md. Tests: tests/experiments-index.test.js
Agent Symphony (economy as generative music) pages/symphony.html → /symphony, engine src/symphony.js, grammar src/symphony-score.js Live The live activity bus (GET /api/feed + /api/feed-stream SSE) rendered as WebAudio generative music: one synthesized note per real platform event, voice by event type (payments pluck, coin buys land as bass, new agents chime, guard refusals play dissonance, jackpots glissando), pitch register by amount (whales sit lower), stable per-actor motif + stereo position via FNV-1a hash, all quantized to one pentatonic scale so arbitrary event streams harmonize. Canvas visualization, live ledger with real click-throughs, and a MediaRecorder tap that exports a shareable audio clip of the master bus. A burst gate collapses event floods (a sniper sweep emitting dozens of identical guard events) into one accented note per actor per 1.5s. Solo mode narrows the stream to one participant client-side (?agent=<id> exact, ?actor=<label> case-insensitive), reachable from the per-row "solo" control and from the "Listen →" link on every agent profile's Wallet Story card. No audio assets, no synthetic events. Tests: tests/symphony-score.test.js
Platform activity feed pages/feed.html → /feed + pages/community.html → /community, backend api/users/me/feed.js Live Reverse-chronological creation events (avatars, agents, coins, models, worlds) plus follow activity, merged at read time from forge_creations, dioramas, and user_follows (no separate event log to drift out of sync). ?scope=following (default; session-gated, anonymous gets 401) vs ?scope=all (public; powers /community and first-visit feeds); limit 1..50, before ISO cursor. Items deep-link to creator portfolios. Distinct from the Money Pulse ticker GET /api/feed (docs/money-feed.md). Docs: docs/social-layer.md
Contributor thank-you roll pages/contributors.html → /contributors, linked from pages/community.html and README.md In-repo A public acknowledgment page for people improving three.ws through code, reviews, issue reports, and design ideas. The code-contributor roll reads GitHub's public contributor record live, excludes bots and anonymous-email records, and has explicit loading, failure, and retry states; a curated section credits non-code contributions that led to concrete improvements, beginning with the Forge/R2 outage report in issue #164.
Follow graph api/users/[username]/follow.js + api/users/[username]/follows.js, table user_follows, buttons on pages/profile.html Live GET returns {following, followed_by, followers_count, following_count}; POST/DELETE are idempotent (session + CSRF, self-follow 400) and return the same envelope so one round-trip updates the button and the counts. A genuinely new edge (ON CONFLICT DO NOTHING) publishes a follow user event to the notification bell exactly once. Feeds the activity feed's following scope, search ranking, and the followers leaderboard metric. Tests: tests/api/users-follow.test.js. Docs: docs/social-layer.md
Herald: messages delivered in person SDK herald-sdk/ → /herald.js (published as @three-ws/herald), rail api/herald/announce.js + api/herald/stream.js + api/_lib/herald.js, playground pages/herald.html → /herald + src/herald-page.js, CLI herald-sdk/bin/herald.mjs, MCP packages/herald-mcp/ Live A 3D character walks onto the page and says what happened, instead of a badge nobody notices. The library is the interrupt budget: importance scoring with pluggable scorers, a floor, quiet hours, a rate limit, dedupe with a TTL, freshness, batch collapse, focus awareness, and a stable reason for every message it refuses (duplicate, rate-limited, quiet-hours, below-importance-floor). Delivery is the walk companion (walk-sdk control.announce) with an accessible aria-live card fallback for anything that cannot render 3D, and opt-in gesture-gated voice. The rail is the part nobody expects: POST /api/herald/announce with an API key carrying the herald:announce scope reaches the browser tab the caller has open over SSE, so herald watch -- npm test makes your avatar tell you the build finished, and an AI agent can do the same through the MCP server. An announcement is always delivered to the caller's own sessions (no recipient field, so no key can interrupt anyone else); the queue is Redis-backed, drained not broadcast, and expires in five minutes. Docs: docs/herald.md, docs/api-reference.md. Tests: tests/herald-rules.test.js, tests/herald-runtime.test.js, tests/herald-rail.test.js, tests/herald-announce-endpoint.test.js
Notification bell & preferences Event vocabulary api/_lib/feed.js (USER_EVENT_TYPES → publishUserEvent() → user_notifications), endpoints api/notifications/, preference matrix api/_lib/notify-prefs.js, bell client src/notifications.js, avatar announcements src/notification-herald.js, settings panel src/dashboard-next/pages/settings.js Live In-app inbox covering remixes (api/x402/remix-asset.js), DMs (api/friends/messages.js), coin bonding-curve graduations (pump cron in api/cron/[name].js), follows, sales, purchases, IRL, market, and account events. Preferences are a category × channel matrix (in_app always on; push/email/telegram/avatar are per-category opt-outs) edited from /dashboard/settings. The avatar channel delivers in person: for a fresh, unread notification in an opted-in category the corner companion walks on screen, gestures, and says the line with a link straight to it, summoning itself for that one message and retreating if it was off (walk-sdk control.announce). Rules (15-minute freshness, once per browser, two per batch, visible tab only, device-level mute) live in src/notification-herald.js. Docs: docs/notifications.md, docs/social-layer.md. Tests: tests/notification-herald.test.js, tests/notify-prefs.test.js
Approval inbox Page pages/approvals.html → /approvals (deep links /approvals/<id>?t=) + src/approvals-page.js, API api/approvals/, library api/_lib/approvals.js, wallet-intent wiring api/_lib/wallet-intents.js, push actions public/push-sw.js, migration api/_lib/migrations/20261010120000_approval_requests.sql Live When an agent's spend rule is set to "Ask me", the action becomes an approval request instead of executing: a confirmation table (recipient, amount, asset and chain, USD value, risk notes), a SHA-256 payload hash, and a deadline (15 min for swaps, 6 h for transfers). Delivered through the notification fan-out (bell, web push with Approve/Deny buttons, iOS, Telegram/Discord) with a signed deep link, plus email when nothing else reached the owner. In a paired Telegram or Discord chat each request arrives with the full confirmation table and Approve/Deny buttons whose callback data is HMAC-signed over the request, payload hash, deadline, link and presser (api/_lib/gateway/approval-buttons.js); the chat also takes /approvals, /positions, /pause and /kill (api/_lib/gateway/control-commands.js), and ignores forwarded messages. Approving re-checks the hash and claims the row with a conditional update, so it executes exactly the shown action once; deny and expiry fail closed. The inbox adds status tabs, an agent filter, bulk deny, revocable auto-approve rules (per venue, capped at $1,000, optionally per agent or team), and an activity log from the audit log. Docs: docs/approvals.md. Tests: tests/approvals.test.js, workers/agent-gateway/tests/approval-buttons.test.js
Personal companion (/companion) Page pages/companion.html → /companion + src/companion/ (page, source cards, voice), API api/companion/ (settings, sources, contacts, events, ingest, stream, poll), engine api/_lib/companion/ (store, encrypted BYOK configs, triage, lanes for Telegram / iCal / IMAP), cron api/cron/companion-poll.js, migration api/_lib/migrations/20260828140000_companion_harness.sql Live Turns a person's own inbox, chats, calendar and phone into deliveries a 3D character makes in person. BYOK per source (a Telegram bot the user made, a private iCal URL, IMAP with an app password) plus a universal bridge token anything can POST to. Every message is scored 0-100 by the shared deterministic rules (@three-ws/companion/triage, the same module the CLI runs locally) and optionally refined by the user's own Anthropic key; above their threshold and outside quiet hours it is delivered through companion_delivery notifications, so the bell, Web Push, and the avatar channel all carry it. A contact's message is spoken by that contact's avatar and voice (control.announce({ avatar }) in walk-sdk). A delivery whose lane can carry an answer (Telegram, through the user's own bot) offers a reply box in place, and the reply is stored with the message. Live SSE at /api/companion/stream feeds the desktop app and any third-party body. Docs: docs/companion.md. Tests: tests/companion-triage.test.js, tests/companion-calendar.test.js, packages/companion-sdk/tests/
three.ws Drive: the agent in the car (/drive) Page pages/drive.html → /drive + src/drive/ (page controller, surface presets, native bridge, local commands, motion gate); native CarPlay scene ios/native/App/App/CarPlaySceneDelegate.swift + DriveLink.swift; Android Auto car app solana-mobile/android-overlay/app/src/main/java/ws/three/app/drive/ Live (web) / built and compiled (Android Auto) / built, entitlement pending (CarPlay) The existing talk loop (/api/asr → /api/chat → /api/tts → lipsync on a real rigged avatar) rebuilt for a car panel: one glanceable two-line reply instead of a transcript, exactly four controls, night by default, and a keyboard that hides itself while the wheels turn. Speed comes from navigator.geolocation's real ground speed, so moving above walking pace locks text entry back and a sustained stop is what unlocks it. Control phrases ("repeat that", "stop talking", "louder", "night mode") are answered locally with no round trip, matched against the whole utterance so "stop at the next charger" still reaches the agent. Hands free ends a turn from the real captured mic level on the Riva lane. The car screen is never ours to draw on, on either platform: Apple's voice-based conversational category (iOS 26.4) grants templates and an audio session and no drawing surface, and Android grants a canvas only to navigation apps and has no conversational category at all, so both car screens render the same four rows and this page runs beside them, joined by the versioned threeWsDrive channel (a WebKit message handler on iOS, a JavaScript interface on Android). Android Auto declares androidx.car.app.category.IOT because that is accurate: the home tools in api/chat.js reach a real house, so "turn the porch light on" from the car is the product. Its web view has no window and therefore no animation frames, so ?surface=androidauto runs the loop as audio with the stage off, and refuses tap-to-approve for guarded actions because a person who cannot see what they are approving must not be asked. A guarded action while moving is refused on every surface and offered for when the car stops. Docs: docs/carplay.md, ios/docs/CARPLAY.md, solana-mobile/docs/ANDROID-AUTO.md. Tests: tests/drive-surface.test.js
Hands-free voice for the house (/voice/home) Loop src/voice/home-voice.js, VAD src/voice/vad.js, wake word src/voice/wake-word.js + catalog src/voice/wake-words.js, panel src/voice/home-voice-ui.js + public/home-voice.css; page pages/voice-home.html → /voice/home + src/voice-home.js; models committed under public/models/voice/wake-word/ with the silero + onnxruntime runtime staged by scripts/copy-voice-models.mjs Live The browser half of three.ws Home: mic → silero VAD → openWakeWord → /api/asr → /api/chat (home tools) → /api/tts/speak → lipsync, with one getUserMedia shared by all three consumers. Wake-word matching runs entirely in the tab on committed openWakeWord v0.5.1 weights served from three.ws, so nothing is uploaded until after the wake word; nothing about detection is even downloaded until the user opts in. Barge-in cuts playback ~110 ms after the user starts talking, and a playback-aware guard means the agent saying its own wake word (score 0.99) wakes it zero times. A pause is not an ending: a closed segment stays open 450 ms so "Hey Jarvis… turn the kitchen light off" is one command. Guarded actions are spoken in full, shown on screen by name and entity id, and satisfied only by the token confirm redeemed at POST /api/home/:id/confirm; a general "yeah" is refused by name and a screenless surface is refused outright. Twelve designed states, mute that ends the track rather than hiding a dot, and every leg timed live. Docs: docs/home-voice.md. Proof: scripts/check-home-voice.mjs (36 assertions in a real Chromium, plus two --live scenarios against a real Home Assistant: live-confirm mints a real confirmation and proves redeeming it really unlocks a real deadbolt and cannot be replayed, and live proves the spoken command really turns the light off wherever a tool-calling provider key is configured, skipping with its reason where none is). Tests: tests/home-voice.test.js
Knock: a priced door to a person (/knock) Hub pages/knock.html → /knock + src/knock/page.js, public door pages/knock-door.html → /knock/<handle> + src/knock/door.js, API api/knock/ (door, directory, send, reply, settings, inbox, escrowed, escrow-sync), paid lane api/x402/knock.js, escrowed lane api/_lib/knock/escrow.js + browser client src/knock/escrow-program.js / src/knock/escrow-checkout.js, engine api/_lib/knock/ (pure policy, store, delivery, receipt tokens), migration api/_lib/migrations/20260828210000_knock_doors.sql, SDK + CLI packages/knock-sdk/ (@three-ws/knock), MCP packages/knock-mcp/ (@three-ws/knock-mcp) Live Every account can publish a door at /knock/<username> and set what one message from a stranger costs. Paying it buys exactly one message through, and the delivery is in person: the knock becomes a companion_events row whose importance is derived from the amount paid, so the recipient's corner avatar walks on wherever they are and says who is at the door and what they paid. The USDC settles straight to the recipient (payTo on the 402 challenge is their own address, and a priced door cannot be opened without one), so there is no platform wallet in the path and no cut. Solana leads; Base is advertised only when the owner sets an address for it. Every refusal happens before the 402 (shut door, daily cap, block list, length limits) and again before settlement, so a knock that was never going to land is never a knock somebody paid for. Only the subject line is spoken; an untrusted body never uses the recipient's avatar as a speaker. The sender gets a derived HMAC receipt URL and reads the reply through it with no account, which is why answering someone never hands out an address. Free doors take a plain POST on a tight per-IP bucket. A door can also take escrowed knocks (row below), which the door page offers beside paying up front and the owner runs from their own wallet in the settings panel; nothing on this server can move an escrowed payment. Spec: specs/KNOCK_PROTOCOL.md. Docs: docs/knock.md. Tests: tests/knock-policy.test.js, packages/knock-sdk/test/, packages/knock-mcp/test/
Visitor feedback loop Recorder @three-ws/witness, capture + panel src/feedback-companion.js (mounted by src/walk-companion.js), intake api/feedback/report.js, queue API api/feedback/index.js, scoring api/_lib/feedback/triage.js, store api/_lib/feedback/store.js, cron api/cron/feedback-triage.js, review page pages/feedback.html → /feedback + src/feedback-page.js Live The return channel on the corner companion: the visitor tells the avatar what broke and the report carries the route, build SHA, viewport, and the last console errors and failed requests the browser captured, so a vague sentence lands as an actionable row. The companion offers proactively at the one moment worth asking (right after the page actually threw), once per route per session, never in a background tab. Feedback is data, never an instruction: the model that reads untrusted visitor text writes six scalars to that report's own row and has no path to the repo, a deploy, or any other write; the admin-only /feedback queue groups reports into one row per problem and a person decides. A report arrives as a runnable failing test: the recorded session compiles into a Playwright spec asserting the failure is GONE (red until fixed, green after), reachable from the queue's Copy test button, GET /api/feedback/repro, npm run feedback:repro, and the get_feedback_repro MCP tool. Docs: docs/feedback.md, docs/witness.md. Tests: tests/feedback-triage.test.js
Session-to-test recorder packages/witness/ → @three-ws/witness: recorder recorder.js, selector synthesis selector.js, capture-time privacy redact.js, spec compiler compile.js; compiled repros land in tests/repros/ with their own Playwright config Published as @three-ws/witness (Apache-2.0, zero deps) Turns a real user session into a runnable failing test. Records INTENT (about 2 KB) rather than DOM mutations (megabytes), so it can be always-on, which is the point: the trace already exists when somebody decides to complain. Every element gets the strongest handle that is unique in the live document (test id > id > aria-label > role+name > text > name > placeholder > class > structural path), framework-generated ids and utility classes refused, and each trace carries a replay confidence equal to its WEAKEST link. The compiled spec asserts the failure is gone, never that it happened, so it locks in the fix rather than the bug; a session with no machine-visible failure emits test.fail() and says which assertion a human must add rather than faking green. Privacy is enforced at capture: typed values are never held (only a length and a shape), password/hidden/email/tel/date inputs and data-witness="off" subtrees record nothing, URLs lose their credentials before storage. Docs: docs/witness.md. Tests: packages/witness/test/ (36, npm run test:witness)
Prepaid credits (/credits) pages/credits.html → /credits + src/credits.js, balance/ledger api/credits/index.js → GET /api/credits, deposit verifier api/credits/deposit.js → POST /api/credits/deposit over api/_lib/credit-deposit.js, ledger engine api/_lib/credits.js, schema api/_lib/migrations/20260621200000_credits.sql Live The prepaid balance every metered action on the platform debits. Top up by sending SOL, USDC or $THREE to the platform deposit wallet; GET /api/credits publishes the accepted-asset catalog with each rate (deposit.assets), USDC credits at the fixed published rate, and paying in $THREE earns the owner-configured bonus (THREE_CREDIT_BONUS_BPS, read live by creditBonusBps() in api/_lib/token/config.js) as a separate grant row (connect + SIWS-link + sign in the page, or paste a signature you already sent); crediting is server-authoritative and idempotent on the signature, so a signature that is not signed by a wallet linked to the account credits nobody. The page renders the caller's $THREE holder tier from the same holder block api/pricing.js returns (api/_lib/three-tier.js), which is the discount api/_lib/credits.js already applies to every debit, and lists what credits buy straight from the pricing catalog (api/_lib/pricing/catalog.js). Ledger is keyset-paginated. Docs: docs/payment-sessions.md. Tests: tests/credits.test.js
MCP credit plans (/mcp-plans) pages/mcp-plans.html → /mcp-plans + src/mcp-plans.js, API api/mcp-plans.js → GET/POST /api/mcp-plans, meter api/_lib/mcp-credits.js wired into api/_mcp/dispatch.js, catalog and purchase api/_lib/mcp-plans.js, schema api/_lib/migrations/20261023160000_mcp_plans.sql Built, unapplied Credit bundles and time passes for paid MCP tools, bought from the prepaid balance. The dispatcher debits before a call, refunds on error, spends a metered free trial last, returns creditsUsed and creditsRemaining in _meta, and falls back to the per-call -32402 when a plan holder runs dry. Docs: the pricing section of docs/mcp.md. Tests: tests/mcp-credit-plans.test.js
Developer plans and quotas (/developers) Config api/_lib/dev-plans/config.js (the only place plan numbers live), gate api/_lib/dev-plans/quota.js wired into api/_lib/gateway.js for every /api/v1 route, subscriptions api/_lib/dev-plans/subscription.js, checkout + receipts api/_lib/dev-plans/billing.js, per-key analytics api/_lib/dev-plans/analytics.js, key cache + immediate invalidation api/_lib/api-key-cache.js, allowlists api/_lib/ip-allowlist.js; REST api/v1/dev-plans.js → GET /api/v1/dev-plans, api/v1/me/dev-plan/ → /api/v1/me/dev-plan{,/checkout,/confirm,/schedule,/receipts}, key tools api/keys/[id]/rotate.js, allowlist.js, analytics.js; page pages/developers.html → /developers + public/developers.css; dashboard Plan tab src/dashboard-next/pages/developers-plan.js → /dashboard/developers#plan, key tools src/dashboard-next/pages/api-key-tools.js Live Free, Builder, Scale, Enterprise. Monthly quota, burst and concurrency enforced at the gateway (429 + Retry-After, 402 quota_exceeded with the next plan). Upgrades in credits, USDC or $THREE on Solana, user wallet signs, proration, downgrade at period end, receipts. Migration 20261010230000_dev_plans.sql. Doc docs/developer-plans.md
Spend and token ceilings (/spend) pages/spend.html → /spend + src/spend-page.js, read model api/spend/me.js → GET /api/me/spend, ceilings api/agents/_id/token-budget.js `→ /api/agents/:id/token-budget(/resume /extend)over [api/_lib/token-budgets.js](api/_lib/token-budgets.js), gate wired intoassertAgentBudget` in api/_lib/inference-billing.js, counters api/_lib/migrations/20261010173000_agent_token_budgets.sql, free-tier choices api/_lib/free-tier.js Live
Pay-per-request model access (POST /api/v1/chat/completions with no key) price table api/_lib/pricing/inference-models.js, cap sizing, escrow and claim api/_lib/metered-router.js, endpoint api/v1/chat/completions.js, price sheet api/v1/models.js → GET /api/v1/models Live (needs X402_UPTO_ENABLED) An unauthenticated request answers 402 with an x402 upto Solana offer whose cap is the model's worst case for that request; the retry escrows the cap, the completion runs, and the claim settles measured tokens times the published price while the rest is refunded. A request that produces nothing cancels the channel; a dropped stream settles the tokens already sent. Docs: docs/metered-router.md. Tests: tests/metered-router.test.js.
Agent lifecycle, runs and automations over MCP (Runs tab) MCP tools api/_mcp/tools/agent-lifecycle.js (get_agent, update_agent, delete_agent, start_agent, stop_agent, upload_agent_avatar, create_agent_run, update_agent_run, cancel_agent_run, get_agent_run_steps, automation_list, automation_get, automation_create, automation_update, automation_delete, automation_trigger) over the REST validators and engines in api/_lib/agents-v1/ (runs, automations, run receipts), policy rows in packages/mcp-policy/src/table.js; replay endpoint api/agent-run-replay.js → /api/agent-run-replay; Runs tab src/agent-run-replay.js, mounted from src/avatar-page.js on /agents/:id?view=runs Built, ships with the next deploy An MCP client can now edit, start, stop, re-skin and delete an agent, and drive autonomous runs and automations, with create and update validated by the same schemas as the REST path. delete_agent and automation_delete are destructive: refused without confirm_delete and a matching get_agent / automation_get preview. A run carries two budgets (model turns and dollars), honors cancel between steps, ends with a plain-language summary, and chains a sha256 receipt over every step; get_agent_run_steps returns each tool call paired with its result and receipt. The owner-only Runs tab lists every run, replays it step by step with a scrubber, polls a live run, verifies the receipt chain server-side, and cancels. Docs: docs/mcp.md → /docs/mcp, docs/agent-runtime.md. Tests: tests/mcp-agent-lifecycle.test.js, tests/agent-run-replay-endpoint.test.js
Agents REST API (/api/v1) and webhooks Router api/v1/rest.js over api/_lib/agents-v1/ (http envelope, agents, runs, automations, skills, webhooks.js, run-stream.js, agent-export.js, openapi.js), delivery queue api/_lib/webhook-dispatch.js, retry cron api/cron/webhook-deliveries.js, dashboard src/dashboard-next/pages/developers.js → /dashboard/developers Built, ships with the next deploy Agent CRUD, start/stop, sync chat and history, runs with resumable SSE, automations with trigger-now, skills, strategies, export/import, and HTTPS webhooks (run.finished, automation.fired, message.received, approval.needed) with HMAC signatures, 8-attempt backoff, a delivery log and replay. Cursor pagination, {data, meta} envelope, Idempotency-Key. Docs: docs/api-reference.md, docs/developer-platform.md. Tests: tests/api/v1-rest-router.test.js, tests/api/agent-export.test.js, tests/api/run-stream.test.js, tests/webhook-dispatch-signing.test.js
Platform OpenAPI spec + Postman collection Spec public/.well-known/openapi.yaml → /.well-known/openapi.yaml, generator scripts/build-postman-collection.mjs → public/.well-known/postman-collection.json → /.well-known/postman-collection.json Built, ships with the next deploy A ready-to-import Postman Collection v2.1 generated from the same OpenAPI spec every client already reads, via openapi-to-postmanv2; a clean() pass strips the converter's per-run random ids and fabricated example responses so the checked-in file is byte-identical across regenerations. npm run build:postman-collection regenerates it, npm run check:postman-collection (wired into npm run gate) fails when it drifts from the spec. Docs: docs/api-reference.md
Agent mail (inbox, rules, send controls) Page pages/agent-mail.html → /agents/:id/mail and /agent-mail + src/agent-mail.js, REST api/v1/agent-mail.js → /api/v1/agents/:id/mail/*, MCP api/_mcp/tools/mail.js, service api/_lib/mail/ (service, controls, untrusted, rules, inbound, content rules, spam, threading, extract, otp), webhook api/mail/inbound.js, migration api/_lib/migrations/20261010184500_agent_mail_controls.sql Built, ships with the next deploy; outside delivery waits on the agents.three.ws DNS records (owner) Each agent can hold an address on agents.three.ws: quote-then-confirm mailbox creation and sends that show the exact recipients and body first, content rules, a per-agent recipient allowlist and daily send cap that only a signed-in owner can change, instant delivery between agent mailboxes, received mail fenced as untrusted data on every surface, and inbox tools (inbox_wait_for_code) that extract one-time codes and sign-in links for signups from owner-listed, authenticated senders only (migration 20261023160000_agent_mail_code_senders.sql). Owner rules turn matching mail into a read-only, zero-budget agent run, either at once or after a yes in /approvals. Docs: docs/agent-mail.md. Tests: tests/agent-mail-controls.test.js
Agent commerce (invoices, sends, offers, limit requests) Owner console pages/commerce.html → /commerce and /invoices + src/commerce-page.js, public invoice and receipt page pages/agent-invoice.html → /invoices/:id + src/agent-invoice-page.js, REST api/agent-commerce/[...route].js → /api/agent-commerce/*, library api/_lib/agent-commerce/, MCP api/_mcpagent/commerce-tools.js on /api/mcp-agent, watcher cron api/cron/agent-invoice-watch.js, migration api/_lib/migrations/20261010221500_agent_commerce.sql Built, ships with the next deploy Agents and owners issue invoices in USDC, SOL or $THREE, payable by Solana Pay link or QR; a per-minute watcher matches payments by reference key and memo and moves invoices to paid, underpaid or expired, with webhooks, owner notifications and a public receipt. Paid mainnet invoices feed the earnings ledger. agent_send is preview-then-confirm and gated by the destination allowlist and approvals; offers sell with a quote and an explicit confirm and release the fulfillment only once the chain shows payment; spending_setup proposals need the owner's step-up (password, fresh sign-in or a linked-wallet signature) and can never be approved by the agent. Docs: docs/agent-commerce.md. Tests: tests/agent-commerce-invoices.test.js
Agent perps (perpetual futures desk) Page pages/agent-perps.html → /agents/:id/perps and /agent-perps + src/agent-perps.js + src/agent-perps.css, REST api/v1/agents/[id]/perps/[...path].js over api/_lib/perps/routes.js → /api/v1/agents/:id/perps/*, MCP api/_mcpagent/perps-tools.js (perps_* on /api/mcp-agent), service api/_lib/perps/service.js, venue contract and registry api/_lib/perps/index.js, venue modules phoenix, jupiter and hyperliquid (signing in hyperliquid-signing.js, shared math in venue-common.js, outage failover in venue-health.js), live probe scripts/perps-venue-probe.mjs, paper ledger api/_lib/perps/paper.js, limits api/_lib/perps/limits.js, alerts api/_lib/perps/alerts.js, cron api/cron/perps-tick.js, migration api/_lib/migrations/20261010213000_perps_desk.sql Built, ships with the next deploy (paper by default; live per agent once the owner turns it on) An agent goes long or short with USDC collateral from its own Solana wallet. Every action is a preview then a confirmed, idempotent execute that refuses if the quote moved past tolerance. Mandatory per-agent leverage and per-position margin caps (2x and $25 by default), slippage and quote-move limits, a live tracker stream with PnL, funding and liquidation distance, owner alert thresholds delivered through notifications, and a kill switch that cancels and closes everything. Paper mode fills at live prices; live transactions are simulated before the agent wallet signs. Docs: docs/perps.md. Tests: tests/perps-desk.test.js, tests/perps-venues.test.js, tests/perps-mcp-permission.test.js
Agent predictions (shadow mode and arbitrage scanner) Page pages/agent-predictions.html → /agents/:id/predictions and /agent-predictions + src/agent-predictions.js + src/agent-predictions.css, shadow ledger api/_lib/predictions/shadow.js, scanner api/_lib/predictions/arb.js, fee models api/_lib/predictions/fee-models.json, routes in api/_lib/predictions/routes.js, migration api/_lib/migrations/20261024020000_prediction_shadow_ledger.sql Built, ships with the next deploy (shadow by default; live is owner-session only) Records each strategy decision at the live order-book price without sending an order, marks it at resolution, and reports shadow beside live P&L before and after fees. A scanner finds YES plus NO pairs under $1 after venue and provider fees. Docs: docs/predictions.md. Tests: tests/predictions-shadow.test.js
Papertrade reads (HyperEVM synthetic perps) REST api/papertrade.js → /api/papertrade?view=markets, quote, account or protocol, MCP api/_mcpagent/papertrade-tools.js (papertrade_* on /api/mcp-agent), client and service api/_lib/papertrade/index.js, position math api/_lib/papertrade/math.js Built, ships with the next deploy Read-only window onto Papertrade: live markets priced at the Hyperliquid mid, exact open quotes (hard-bust price, capacity limits, and the payout ladder after the deadband, impact haircut and live win fee), any wallet's positions valued live, and protocol health including the payout queue. Nothing signs or trades. Docs: docs/papertrade.md. Tests: tests/papertrade-math.test.js
Solana trading tools (MCP + REST) registry api/_lib/trading-tools/registry.js, REST api/v1/trading/[...path].js and api/v1/trading/index.js over api/_lib/trading-tools/routes.js → /api/v1/trading/*, MCP api/_mcpagent/trading-tools.js (on /api/mcp-agent, group trading), swap comparison and router transaction check api/_lib/trading-tools/swap-routes.js, quote and guarded fill api/_lib/trading-tools/swap.js through api/agents/solana-trade.js, research api/_lib/trading-tools/market.js, ecosystem signals api/_lib/trading-tools/ecosystem.js, arbitrage api/_lib/trading-tools/arbitrage.js, live route check scripts/check-trading-routes.mjs (npm run check:trading-routes) Built, ships with the next deploy Ten tools an agent trades Solana with, one registry for both surfaces: token search, price, indicators, news, and market signals (one token, or with no mint the ecosystem view: macro readings, top movers and anomalies with their inputs and as_of). swap_quote compares every aggregator on net output after fees and impact and says why one route won; with agent_id it runs the guard chain and issues a five-minute quote_id. swap_simulate dry-runs it; swap_execute fills it only with confirm_swap: true, re-priced and refused below the approved minimum, once per quote. arbitrage_quote shows the non-atomic risk, a simulated worst case and a verdict, and refuses above $100 unless asked. Docs: docs/trading-tools.md → /docs/trading-tools. Tests: tests/trading-tools-swap.test.js, tests/trading-tools-arbitrage.test.js
Web domains (/domains) pages/domains.html → /domains + src/domains/, API api/domains/[action].js → /api/domains/*, MCP api/_mcp/tools/domains.js, service api/_lib/domains-service.js + api/_lib/cloud-domains.js + api/_lib/domain-connect.js, renewals api/cron/domain-renewals.js, schema api/_lib/migrations/20261011000000_web_domains.sql Live pending deploy Search, price, check and register web domains through Google Cloud Domains, paid from credits behind a quote, an explicit confirm and an idempotency key, then serve an agent's public page on the domain. Coin pages carry a live domain suggestion panel. Docs: docs/domains.md. Tests: tests/domains-service.test.js
Agent payment sessions (/payments) pages/payments.html -> /payments, API api/pay/session.js (POST/GET/PATCH/DELETE /api/pay/session, GET /api/pay/session/:id/executions), spend rail api/pay/execute.js + api/pay/simulate.js, engine api/_lib/pay/payment-session.js + governor api/_lib/pay/spend-governor.js, expiry sweep api/cron/payment-session-sweep.js Live The dashboard for platform-managed spend envelopes: fund a budget out of /credits, get a one-time pss_ bearer token, and hand it to an agent that pays x402 endpoints without ever holding a private key (the platform's Solana wallet signs, and the governor enforces budget, host allowlist and per-tx cap atomically on every call). Each card carries the budget bar, remaining balance, expiry countdown, host allowlist, per-tx cap, an inline execution ledger from GET /api/pay/session/:id/executions with a Solscan link per settled payment, an env-var-referencing MCP config for packages/agentcore-payments-mcp, and cancel-and-refund. Press N for the create dialog. Docs: docs/payment-sessions.md, docs/tutorials/agent-spending-envelope.md. Tests: tests/payment-session-governor.test.js, tests/payment-session-sweep.test.js
Skill bundles (seller builder + evidence pricing) pages/bundles.html → /bundles, API api/agents/[id]/bundles.js, arithmetic api/_lib/bundle-pricing.js, checkout api/marketplace/purchase-bundle.js Live (seller side); no buyer-facing browser view yet Sell several of one agent's skills as one purchase. The price is derived from the agent's own ledger rather than a rule of thumb: the public ?action=pricing endpoint finds every buyer who already bought 2+ of the selected skills, suggests the median of what they really paid (basis: median_basket), and backtests any candidate price against those same baskets; with no such buyer yet it falls back to 20% off the sum of the parts and labels itself discount_off_list so a default is never read as a finding. Every amount is an atomic integer carried as a BigInt end to end, because a 9-decimal mint puts real sums past Number.MAX_SAFE_INTEGER. Checkout settles on-chain and writes one skill_purchases row per skill (kind = 'bundle', amount 0) so one bundle sale is never counted as N skill sales. Docs: docs/skill-bundles.md. Tests: tests/bundle-pricing.test.js, tests/vercel-agents-subpath-routes.test.js
External skill import (browse, scan, approve, fork, publish) pages/skills-import.html → /skills/import + src/skills-import.js, REST api/skill-imports.js → /api/skill-imports/*, registries and pinning api/_lib/skill-import-sources.js, scanner api/_lib/skill-import-scan.js, store api/_lib/skill-import-store.js, chat spend gate api/_lib/skill-import-gate.js, MCP api/_mcp/tools/skill-imports.js, migration api/_lib/migrations/20261011013000_skill_imports.sql Live Installs SKILL.md skills from any public GitHub repository or registry manifest (built in: the three.ws community repo, the public Anthropic agent skills repo, and skills published on three.ws). Each skill is pinned to its commit or sha256, licence-checked, scanned, and installed only after the owner approves; skills that ask to spend, sign or message are gated. Updates arrive as a diff the owner approves. Docs docs/skill-import.md, manifest spec specs/SKILL_REGISTRY_MANIFEST.md, live check scripts/skill-import-live-check.mjs.
Skill import from an OpenAPI spec, GitHub repo or Solana Anchor IDL Package packages/skill-import/ (parser, operation classifier, handler/manifest/SKILL.md generators), REST api/skills/import.js → POST/GET /api/skills/import, api/skills/import/[id].js → GET/PATCH/DELETE (enable/disable/delete, owner-scoped), bundle host api/skills/import/[id]/[...file].js, store api/_lib/openapi-skill-imports.js, migration api/_lib/migrations/20261015130000_openapi_skill_imports.sql, UI tab "From an API" in pages/skills-import.html → /skills/import + src/skills-import.js, CLI three-ws skills import <url> / three-ws skills drafts in packages/three-ws-cli/src/commands/skills.js Live Point at any public OpenAPI/Swagger URL or GitHub repo and get a generated skill bundle: every operation becomes a tools.json entry and a handlers.js function that calls ctx.fetch, with auth placeholders filled from the skill's declared secrets, never hardcoded. A README-only repo becomes a declarative skill instead. Every import lands as a disabled draft, owner-scoped and labelled untrusted; enabled only ever flips via the dedicated PATCH route, never at creation. Anchor IDLs (idl_url or on-chain program_id) become read_* account decoders, unsigned preview_* tools and destructive send_* confirmation handoffs with a risk panel (anchor-idl.js, migration 20261023120000_openapi_skill_imports_anchor_kind.sql). Docs: docs/skills.md. Tests: anchor-idl.test.js, packages/skill-import/tests/, tests/openapi-skill-import.test.js, packages/three-ws-cli/tests/skills.test.js
Marketplace analytics & trial funnel pages/marketplace-analytics.html → /marketplace/analytics, renderer src/marketplace-analytics.js, backend api/marketplace/analytics.js Live Public transparency page for the skill marketplace: paid sales, volume, top skills/agents, and the trial conversion funnel. Every money aggregate gates on status = 'confirmed' alone. Counting status IN ('confirmed','trial') as a sale published 10,454 "sales" and 6.2M $THREE of "volume" on 2026-07-30 against a table holding zero confirmed purchases, because a trial row is a free grant whose amount is only the list price it would have cost. Free trials now render as their own stat and as a four-stage funnel (granted → used → exhausted → converted), which also names the two shapes that mean a wiring fault rather than weak demand: trials never spent, or trials exhausted with nothing converting. Docs: docs/marketplace.md, tutorial docs/tutorials/sell-a-skill-with-a-trial.md. Tests: tests/marketplace-analytics-paid-only.test.js
OKX.AI marketplace services api/okx/3d/[service].js → /api/okx/3d/* Live 3D services sold to other agents on OKX.AI (agent #2632). The listed line-up (rebuilt 2026-08-22) is three.ws Forge: four paid A2MCP rows (forge-draft $0.01 / forge-standard $0.05 / forge-hd $0.25 / forge-image $0.25) plus a free forge-status poll, tools in api/_okx3d/forge.js. Each row is a real MCP Streamable HTTP server whose paid forge_3d tool 402s with eip155:196 leading; the buyer receives exactly what the ChatGPT custom GPT receives (GLB + concept image + viewer + AR link), because both fronts shape responses through api/_mcp-studio/studio-shape.js. Agent Identity Studio and the single-capability REST endpoints are on the back burner: listed: false keeps them out of the listing and the submission payload while they stay deployed and payable. Catalog source of truth: api/_lib/okx-catalog.js; pipeline: api/_okx3d/; showcase: pages/agent-identities.html → /agent-identities + src/agent-identities.js, fed at runtime by api/agent-identities.js → /api/agent-identities (demo runs from data/agent-identities.json merged with the live catalog row, so the price the page quotes is the price the paid endpoint charges); docs: docs/okx-marketplace.md, docs/agent-identities.md. Tests: tests/api/okx-forge.test.js
OKX.AI marketplace chat bot host workers/okx-chat-bot/ (Cloud Run service okx-chat-bot), local revive scripts/okx-bot-revive.mjs → npm run okx:bot, session seeding scripts/okx-bot-seed-state.mjs → npm run okx:bot:seed-state Live · Cloud Run since 2026-09-04, replies blocked on AI funding Always-on host for the XMTP chat behind agent #2632. Supervises the okx-a2a daemon plus the onchainos wallet session, persists the wallet/XMTP identity to GCS across revisions, and rebuilds the AI subsession's briefing from api/_lib/okx-chat-briefing.js on every boot so quoted prices can never drift from the catalog. It exists because the stack used to live on a codespace that sleeps, and its outage mode is silent: an expired wallet session leaves the process healthy while no chat is delivered, which flagged the listing offline once. Health reaches the platform as the okx_chat_bot subsystem on /api/healthz via a bot_heartbeat row; a logged-out session pages with the exact login commands. The AI credential is probed against the provider rather than assumed present (workers/okx-chat-bot/provider.js), because a key the provider refuses is indistinguishable from a working one until a buyer's message goes unanswered. The AI credential is an ordered chain rather than one lane (vertex on GCP credits, then an Anthropic key, then an Anthropic-wire-format gateway, then an interactive grant, then an OpenAI key): electProvider() probes every rung on its own env overlay every 15 minutes and serves on the first that answers, so a lane the owner funds is picked up with no deploy and a refused one is never elected. Live state as of 2026-09-09, readable from the bot_heartbeat row when gcloud is not authenticated: the host has been up since 2026-09-04 with the wallet session logged in and one XMTP client serving, so buyer chat IS delivered, and every lane is refused for lack of funds (Vertex Lightning dunning decision is deny, OpenAI billing_not_active, OpenRouter 402), so no reply can be authored. The running revision predates the chain, which its heartbeat meta shows by carrying no providerLane / providerChain keys. Deploy: workers/okx-chat-bot/cloudbuild.yaml (--max-instances=1 is load-bearing, one GCS state writer). Tests: tests/okx-chat-bot.test.js
Crypto Data API docs / landing pages/crypto.html → /crypto In-repo · docs surface Screenshot-worthy public docs + funnel-top for the free, keyless Crypto Data API (/api/crypto/*: token snapshot, security, holders, launches, bonding, whales, symbol, wallet, trending, portfolio, airdrops). Renders hero, endpoint table, tabbed quickstart (curl/JS/Python), per-endpoint request/response reference and a live "Try it" console. Probes production at runtime and marks each endpoint Live vs Coming soon (degrades gracefully while sibling endpoints roll out). CTAs funnel to paid uniques: /launcher, /vanity-wallet, /forge. Spec: x402-overhaul campaign (retired 2026-07-28; readable in git history)
Free Crypto Data API + discovery api/crypto/index.js → /api/crypto, api/crypto/openapi.js → /api/crypto/openapi.json, docs docs/crypto-api.md → /docs/crypto-api Live · docs surface Front door + OpenAPI 3.1 for the free, keyless Crypto Data API. Catalog assembler api/_lib/crypto-catalog/index.js merges api/_lib/crypto-catalog/*.js self-describing descriptors (currently airdrops, bonding, holders, launches, linkage, portfolio, security, symbol, token, trending, wallet, whales) via a static import barrel (the production source of truth, since Vercel's bundler only ships what static imports reach) plus an additive dev-time directory glob; skips malformed/throwing entries, never throws, valid-empty when zero. New descriptor = drop the file AND add its import line to the barrel. OpenAPI built from the same catalog via api/_lib/crypto-catalog/openapi.js. Index does HTML/JSON content negotiation. Endpoint handlers live in api/crypto/*.js. Spec: x402-overhaul campaign (retired 2026-07-28; readable in git history)
Token due diligence (holder quality + funding graph) api/_lib/token-due-diligence.js, endpoints api/crypto/due-diligence.js → /api/crypto/due-diligence and api/crypto/funding-graph.js, MCP tool api/_mcp/tools/token-due-diligence.js (token_due_diligence), token-page panel src/token-dd-panel.js, guard limits in api/_lib/agent-trade-guards.js, docs docs/token-due-diligence.md Live Insider hold rate, sniper share, bundler exposure, fresh-wallet share and smart-money holders computed from chain reads and our own wallet_reputation, with a two-hop funding force graph on /three. Buys are refused above max_insider_pct, max_sniper_pct, max_bundler_pct or max_fresh_wallet_pct. Tests: tests/token-due-diligence.test.js, tests/agent-trade-endpoint.test.js. Fixture: tests/fixtures/token-dd/three-recorded.json
Unified Crypto API aggregator — storefront + OpenAPI Registry api/v1/_providers.js (providerCatalog()), front door api/v1/x/[...slug].js → /api/v1/x/<provider>/<endpoint>, discovery → GET /api/v1/x, storefront pages/crypto-api.html → /crypto-api, OpenAPI 3.1 api/openapi-json.js → /openapi.json, docs § in docs/api-reference.md, dir guide api/v1/README.md Live Third-party crypto/DeFi/on-chain APIs (CoinGecko, DefiLlama × 2, Jupiter, DexScreener, Solana RPC, OpenAI-compatible) re-offered as one bill: free per-IP tier → BYOK pass-through → three.ws plan → x402 pay-per-call, in that order. Everything (OpenAPI paths, the /crypto-api live table, the docs quota table) renders from providerCatalog() at request/page-load time — no hand-enumeration, so a new provider descriptor shows up everywhere with zero page edits. Test: tests/openapi-aggregator.test.js. Not to be confused with the separate /api/crypto/* bundle below (different campaign, different registry). Spec: x402-catalog campaign (retired 2026-07-28; readable in git history)
3D Vision (let an agent see a model) api/_lib/3d-vision.js, route api/3d/look.js → /api/3d/look, MCP tool look_at_model in api/_mcp-studio/tools.js and on every OKX forge endpoint (api/_okx3d/forge.js), SDK packages/see/ (@three-ws/see) Live Every text-to-3D API answers with a URL to a binary an AI agent cannot open, so the agent that generated a model has no way to check its own work; that blindness is why agentic 3D stalls at one shot. This renders any public GLB from up to six angles (three-quarter, front, side, back, top, bottom; the default four are the smallest set that answers "is this good") and hands the frames back as MCP image content blocks, which a multimodal client renders into the conversation, so the model literally looks at its own output and can regenerate naming the fault it saw. Reuses the platform's headless renderer (api/_lib/avatar-render.js) with the full-body preset so props and creatures are not cropped like humanoids, renders frames sequentially because the browser is shared, and reports a partial turntable rather than failing. Geometry comes from the existing free inspector and is best-effort: a hiccup costs the numbers, never the frames. Free and keyless on REST and MCP, and free for OKX buyers on the paid forge endpoints, so an agent can confirm it got what it paid for. Docs: docs/3d-vision.md. Tests: tests/3d-vision.test.js
Run receipts (expected vs observed, per stage) core api/_lib/run-receipt.js, storage + stats + rig read-back api/_lib/run-receipt-store.js, table api/_lib/migrations/20261014000000_run_receipts.sql, studio wiring api/_mcp-studio/receipts.js, REST api/runs.js → /api/runs, page pages/runs.html + src/runs.js → /runs, /runs/:id, offline verifier scripts/run-receipt-verify.mjs Live Every 3D Studio generation (forge_avatar, text_to_avatar, mesh_forge, forge_free, rig_mesh, refine_model) writes a receipt: for each stage (input, subject, brief, mesh, geometry, visual, rig, delivery) what was expected, what was observed, a verdict (met, recovered, missed, skipped, pending) and the cause when it fell short. The rig stage is verified by reading the delivered GLB back with Rig Doctor's analysis, not from the rigger's report. Receipts are ed25519-signed with the attestation key, linked from every tool result (structuredContent.receipt), completed by check_job when a stage was still running, and aggregated at /runs into stage-by-stage met rates and top causes (counts only, no prompts). Fail-open: no database means an inline receipt without a link. Docs: docs/run-receipts.md → /docs/run-receipts. Tests: tests/run-receipt.test.js
Free 3D API + docs api/3d/index.js → /api/3d, api/3d/openapi.js → /api/3d/openapi.json, landing page public/3d.html → /3d, reference doc docs/3d-api.md → /docs/3d-api Live · docs surface Front door + OpenAPI 3.1 for the free, keyless 3D API. Catalog assembler api/_lib/3d-catalog/index.js merges api/_lib/3d-catalog/*.js descriptors (currently generate, inspect) via a static import barrel (production source of truth) plus an additive dev-time directory glob; new descriptor = drop the file AND add its barrel import line; skips malformed, never throws; OpenAPI built from the same catalog via api/_lib/3d-catalog/openapi.js. Index does HTML/JSON content negotiation and advertises the paid ladder (Forge Pro, Rigged Avatars). Docs page: hero, live endpoint table, runnable quickstart with a live "Run inspect" console, embedded <model-viewer> GLB preview, and the free→paid ladder. Free endpoints: api/3d/generate.js (prompt 12), api/3d/inspect.js (prompt 13). GPT Store Actions surface: api/3d/studio.js → /api/3d/studio, a store-compliant twin of generate that strips the x402/upgrade block, drops internal ids, and runs the api/_mcp-studio/safety.js age-13+ content gate before any GPU work; backs the "three.ws 3D Studio" custom GPT (prompts/store-submissions/_generated/openai-actions.yaml + openai-gpt-config.md, store-submission prompt 12). Spec: x402-overhaul campaign (retired 2026-07-28; readable in git history)
x402 Preflight (signed payability attestations) Format core api/_lib/x402/preflight.js, server api/x402/preflight.js → /.well-known/x402-preflight, page pages/preflight.html → /preflight + src/preflight-page.js, client SDK + CLI packages/x402-preflight, MCP tool api/_mcp3d/tools/preflight.js, spec specs/x402-preflight.md, docs docs/x402-preflight.md Live The reliability layer x402 is missing. x402 says what a resource costs; nothing says whether the seller can still SETTLE it, so a buyer discovers an empty seller fee wallet only after signing. Born from the 2026-08-28 incident where three.ws was that seller: sponsor at 0.000899107 SOL against a 0.02 floor, 95 payment attempts, 0 settled, 3 hours. A seller publishes a signed, time-bounded ed25519 attestation of per-network payability, built from the same gatherX402SettleHealth() sensor healthz uses plus the live sponsor floor guard, so every field is measured rather than declared. payable is three-valued (a seller that cannot measure must say unknown, never true), every rate ships with its window and sample, alternates names the rails that DO work so a client re-routes in the same round trip, and retry_after stops a fleet synchronising into a retry storm. Verification enforces expiry, so a healthy attestation cannot be replayed through an outage. The open format is unencumbered: any x402 seller can serve one, any client can verify one, nothing routes through three.ws. Tests: tests/x402-preflight.test.js (38, including a cross-implementation digest check that the browser SDK and the node server sign byte-identical bytes).
Paid Market Data API (x402, 18 endpoints) Registry api/_lib/market-data/registry.js, fetchers api/_lib/market-data/fetch.js, factory api/_lib/market-data/endpoint.js, routes api/x402/market-*.js → /api/x402/market-<category>, free index api/x402/market.js → /api/x402/market, catalog projection api/_lib/service-catalog/services/market-data.js, docs docs/market-data-api.md → /docs/market-data-api Live Every free /markets feed (coins, coin profile, price history, categories, exchanges, derivatives, global+Fear&Greed, ETH gas, trending, DeFi TVL, chains, ~15k yield pools, stablecoins, fees/revenue, DEX volumes, hacks) wrapped as pay-per-call x402 endpoints at $0.001 USDC (Solana/Base), plus the $0.005 one-call market-pulse bundle. One registry drives the live 402s, the discovery-doc listings, and the free index - zero drift by construction; the fetchers delegate to the SAME exported builders the free pages use (api/coin/*, api/defi/*), so paid data always matches the site. Params rejected pre-settle (422) and upstream outages (503) never charge the buyer. Tests: tests/market-data-api.test.js.
Market anomaly feed (cron + paid x402 + alert kind) Engine api/_lib/market-anomaly.js, series loaders api/_lib/market-anomaly-sources.js, store api/_lib/market-anomaly-store.js, cron api/cron/market-anomalies.js (every 15 min), paid route api/x402/market-anomalies.js → /api/x402/market-anomalies, alert kind market_anomaly in api/alerts/_rules.js + api/_lib/pump-alert-runner.js + packages/alerts-mcp, migration api/_lib/migrations/20261023140000_market_anomalies.sql, docs docs/market-anomalies.md Live Modified z-score, EWMA and rate-of-change detectors over real series: coin price (CoinGecko sparklines), Solana TVL and Solana stablecoin supply (DeFiLlama history), stablecoin depegs, Hyperliquid funding history and open interest snapshots. Sparse or flat series are skipped with a logged reason, never scored. Tests: tests/market-anomaly.test.js.
Datapoint fabric (x402, 480k+ endpoints) Registry api/_lib/market-data/datapoints.js, dynamic route api/x402/d/[...path].js → /api/x402/d/<family>/<id>/<metric>, free catalog api/x402/d/index.js → /api/x402/d, discovery slice buildDatapointItems in api/wk.js, docs § in docs/market-data-api.md Live Every individual market datapoint as its OWN standalone paid endpoint — one URL = one value = one $0.0005 USDC x402 micro-payment (override X402_PRICE_DATAPOINT_<FAMILY>). 9 families × 68 metrics × live id spaces ≈ 484k addressable endpoints (17.5k coins × 20, ~15.5k pools × 7, ~6k protocols × 6, chains, stablecoins, exchanges, global/gas/fear-greed) served by ONE dynamic route reading the registry; ids are runtime values, nothing hardcodes a third-party asset. Path that cannot exist → 404/422 with NO 402 issued; unknown id/outage rejects pre-settle. Free catalog enumerates families, metrics, prices, and pages each family's full live id space (200/page) so crawlers can walk the universe; the .well-known discovery doc carries a curated runtime-derived slice (83 concrete resources). Tests: tests/market-datapoints.test.js.
Pole Club (x402 micro-tips drive a live 3D room) Page pages/club.html → /club and → /stripclub (same page, the path picks the walk-in via src/club-variant.js), stage app src/club.js with src/club-camera.js, src/club-crowd.js, src/club-dances.js, src/club-audio.js, src/club-venue.js, src/club-perf.js, src/club-sequence.js, in-room life src/club-money.js (the $0.001 bills), src/club-floor-crowd.js (the people around the stages) and src/club-tip-hud.js (the tip tags over each dancer); walk-in src/club-entrance.js + cover gate src/club-gate.js (shared express flag src/shared/club-express.js), the 3D doorman src/club-bouncer.js and the line outside src/club-queue.js; paid endpoints api/x402/club-cover.js → /api/x402/club-cover and api/x402/dance-tip.js → /api/x402/dance-tip; style table api/_lib/club/styles.js and feed row shaper api/_lib/club/tip-rows.js; free reads api/club/leaderboard.js, api/club/tips.js, api/club/tips-stream.js → /api/club/tips/stream (SSE), api/club/presence.js; payouts api/_lib/club/payouts.js via the /api/cron/club-payouts job; assets public/club/ Live The platform's showcase of x402 as a live interaction loop rather than a billing detail: a $0.01 USDC cover charge at the door (with an on-chain bouncer that reads the paying wallet's ban list and prior visits, and a device-cached pass so one cover lasts the night). That bouncer is also a character in the alley: a rigged avatar posted beside the door who tracks you as you walk up, quotes the cover, and acts out each step of the payment (reads the list while the wallet is checked, nods you through by tier, shakes his head on a refusal), driven by the club:door-state event the cover gate emits on every state change; tap him and he explains how the club works. A roped line of waiting avatars talks among itself beside him, then $0.001 USDC per routine at three poles. A settled tip is what puts a dancer on the pole, so the payment IS the interaction. Inside, the room is alive: a crowd stands around the stages (never in the camera's sightlines), each dancer carries a floating tag you tip her from (click her or her pole to pick a style), and every settled tip turns into $0.001 bills: thrown from the camera for your own tip, dropped from the rig for anyone else's, left lying on that stage so each pile is the dancer's night so far. Tips paid from a platform wallet (x402_ring_wallets) arrive flagged agent: they drop one violet bill and never start a routine or pass for a person, and each pole card splits tips today into people and agents. Third-person walk-in through alley → gallery → clubhouse → stage before the room opens; dancers are ordinary gallery avatars retargeted onto the shared clip library, swappable per pole. Tips land live over SSE with REST backfill on reconnect, and per-dancer earnings accrue to club_dancer_wallets for the payout sweep. /club?demo is the express entry that skips the cover for QA and recordings. /stripclub is a second entrance to the same room: it opens on a brick back alley (CC BY 4.0 model, credited on screen and in public/club/venue/LICENSES.md) instead of the neon alley, shares the cover pass, and falls back to the neon alley if its model cannot load.
Living Stages (an AI host performs live, tipped in $THREE) Page pages/stage.html → /stage (the marquee) and → /stage?id=<stage> (the venue), runtime src/stage.js, realtime client src/stage-net.js → stage_world in multiplayer/src/rooms/StageRoom.js with the show logic in multiplayer/src/stage-show.js; API api/stage/index.js → /api/stage, tips api/stage/tip.js → /api/stage/tip, host brain api/stage/host.js → /api/stage/host (HMAC, multiplayer server only) Live An embodied agent hosts a show in a 3D venue. Each beat is a timed utterance broadcast every client renders identically: TTS through a PositionalAudio whose analyser drives lip-sync, plus live captions, so a late joiner or a no-WebGL browser still reads the show. The crowd is co-present on a server-assigned ring, questions queue for the host, and a $THREE tip that settles on-chain to the host wallet is verified by the API and pushed into the room so the host reacts within a beat. The page resolves the realtime server through the same chain as /play (src/shared/game-server-url.js) from the game-server meta it carries; localhost talks to :2567. The client subscribes to the host frame with listen (the join resolves before the first state patch, so onChange on the not-yet-decoded child throws) and registers message handlers before any state work, because the room opens the show the instant the first person arrives. With no feed the pill reads offline and reconnects on tap. Docs: docs/stage.md. Tests: tests/multiplayer-server-boot.test.js (a real stage_world join wired the way the page does it), tests/stage-show.test.js
Outcome-weighted memory and decision trail verify Weights api/_lib/memory-outcomes.js, recall api/_lib/memory-store.js searchMemories, link writes linkOutcomeToMemories in api/_lib/reasoning-ledger.js called from api/cron/reconcile-decisions.js, recall ids captured in workers/agent-sniper/executor.js, verify api/agents/[id]/decision-trail-verify.js → GET /api/agents/:id/decision-trail/verify over api/_lib/ledger-verify.js, badge in src/reasoning-ledger.js → /reasoning-ledger, migration api/_lib/migrations/20261023150000_memory_outcome_link.sql Built, ships with the next deploy (migration pending) Recall ids ride on each snipe decision (decision_recalls, outside the hashed entry so the chain stays immutable); when the position closes the cron stamps pnl USD, win and hold time onto each recalled memory (memory_outcomes). Recall multiplies the score by a bounded, age-decayed, never-zero weight and returns rankScore and outcome. Tests: tests/memory-outcome-recall.test.js, tests/decision-memory-link.test.js, tests/ledger-endpoints.test.js
Fits: the public cosmetics economy pages/fits.html → /fits, page module src/fits.js + pure helpers src/fits-lib.js, backends api/cosmetics/leaderboard.js + api/cosmetics/earnings.js, engine api/_lib/cosmetics-economy.js Live The settled-sale cosmetics ledger, promoted out of a panel inside /play into a public surface. Rarest premium fits ranked by how few wallets own them (owner count first, rarity as the tie-break, so a legendary never sorts under an equally-scarce rare), top collectors by rarity-weighted flex score, top creators by actually settled USDC, and a live sales drip; each fit deep-links to its coin world at /play?coin=<mint>. Plus a creator-earnings lookup any wallet can run without an account (lifetime + 30-day, paid vs pending, per-cosmetic and per-coin-world breakdowns), reachable in one click from each creator row rather than by copy-pasting an address. Coin mints are runtime ledger values, never hardcoded. Headline numbers are derived from the same rows rendered beneath them, so they cannot disagree; the volume tile is labelled as the returned sales window, not as an all-time total. Sub-cent sales keep their precision instead of collapsing to $0.00. Tests: tests/fits-lib.test.js
Receipt Vault: buyer-side proof of purchase pages/receipts.html → /receipts, page module src/receipts.js + pure helpers src/receipts-lib.js, backend api/x402/my-receipts.js, storage api/_lib/x402/receipt-storage.js, issuer api/_lib/x402/offer-receipt-issuer.js, key publication api/x402/did.js → /.well-known/did.json Live What a given wallet spent on the platform's paid endpoints. Every settled x402 call issues a signed Offer & Receipt artifact (USE-17) and durably logs it; a buyer connects a Solana or EVM wallet, signs one read-only message (5-minute window, no transaction, no fee) and gets every receipt ever issued to that wallet: endpoint, settled amount, network, explorer-linked tx, the full signed artifact as JSON, plus search and CSV export. The signing message is a fixed four-line string that must stay byte-identical between buildReceiptsMessage() (client) and buildExpectedMessage() (server); tests/receipts-lib.test.js pins that contract against a verbatim copy of the server's function. The signed artifact carries no amount and omits the tx hash under the spec §5.2 privacy default, so the row records both separately as our own audit trail (migration api/_lib/migrations/2026-07-28-x402-receipt-settlement.sql); receipts predating that capture report as "N of M priced" rather than under-reporting a total. Issuance requires OFFER_RECEIPT_JWK (jws) or OFFER_RECEIPT_SIGNING_PRIVATE_KEY (eip712); unset means no receipts are issued at all. Docs: docs/x402-endpoints.md
SKILL-MD 1.0 catalog (agent-readable paid-route index) Generator api/_lib/skill-md.js, handler api/skill-md.js → /.well-known/skill.md, route in vercel.json, linked from service.skill_md in the /.well-known/x402.json doc (api/wk.js) and from data/pages.json into llms.txt Live A single markdown file, generated straight from the live /openapi.json catalog and the real buildExactRequirements() rail logic, listing every paid HTTP route (method, path, price, parameters), the Solana and Base payment rails it settles on, and a sample 402 challenge, in the format the upstream x402-skill-md validator checks. Test tests/skill-md.test.js runs that real validator against the generated document on every run (zero errors besides SM005, the expected "no EVM rail" finding on deployments without a configured Base facilitator). Not to be confused with public/skill.md → /skill.md (no .well-known), the Agent Skills connector file above that tells a model how to install three.ws's MCP servers; the two cross-link to each other. Docs: docs/x402-endpoints.md
Unified service catalog (one source, two storefronts) api/_lib/service-catalog/index.js, descriptors api/_lib/service-catalog/services/ Live The canonical written-once record of every service (paid x402 + free crypto/3D bundles + OKX.AI rows). toBazaarDiscovery() generates every static /api/x402/* entry in the api/wk.js discovery doc (replacing ~1,400 lines of hand-mirrored blocks); toOkxCatalog() reproduces the OKX catalogIndex() payload exactly, with an include:'all' projection ready for listing expansion. New paid service = drop services/<slug>.js + add its barrel import row. No-drift guards: tests/service-catalog.test.js. Spec: specs/SERVICE_CATALOG.md
pay registry listing (Solana Foundation pay-skills) Projection api/_lib/service-catalog/pay-skills.js, generator scripts/build-pay-skills.mjs (npm run build:pay-skills / check:pay-skills / verify:pay-skills), output distributions/pay-skills/, guard tests/pay-skills.test.js, runbook § 8 of docs/ops/x402-discovery-listings.md Ready to submit Three providers (three-ws/3d, three-ws/market-data, three-ws/agent-trust) for the registry behind the Solana Foundation pay CLI and MCP server, in the upstream layout so publishing is a copy. Paths, schemas, examples and prices come from the service catalog and the live price functions; registry-grade copy (verb-first 24-64 char ASCII summaries, every parameter described) lives in the projection and is rule-checked at build. verify:pay-skills runs the registry's own pay catalog check with live, never-paying probes; all three pass the Solana gate. The upstream PR is owner-gated.
Conversational refinement + remix economy Iterate: api/_mcp-studio/tools.js refine_model (free, on /api/mcp-studio) + mcp-server/src/tools/refine-model.js (paid stdio, $0.25); shared lineage core mcp-server/src/tools/_lineage.js. Remix (paid track): feed api/remix-feed.js → /api/remix-feed (free browse/publish/lineage), settlement api/x402/remix-asset.js → /api/x402/remix-asset + core api/_lib/remix-settlement.js + split math api/_lib/remix-royalty.js. Docs docs/remix.md, docs/mcp-studio.md. Live Talk to a model to iterate it ("make it metallic") — real anchored re-generation with a revertable/branchable version lineage rendered as a viewer version strip; free on both the OpenAI 3D Studio and the paid MCP server. Creators publish a finished model as remixable (provenance + license + royalty on the existing forge_creations rows — no parallel store); another agent pays $0.25 USDC to remix it and a creator-set royalty (≤20%, capped) routes on-chain to the original creator via the audited transferSolanaUSDC rail. Split/caps/payout unit-tested (tests/remix-settlement.test.js, tests/remix-royalty.test.js, tests/refine-lineage.test.js). Free track stays crypto-free. Prompt 09.
Terminal renderer (3D in a shell, no GPU) Renderer core packages/tty-3d/ (@three-ws/tty-3d, CLI three-tty), hosted stream api/tty.js → /tty, /tty/:id, /api/tty, page pages/tty.html + src/tty-page.js → /tty. Docs: docs/tty.md. Tests: packages/tty-3d/tests/tty-3d.test.js, tests/api-tty.test.js Live curl three.ws/tty and a rigged agent walks in your terminal, with nothing installed on either side. A pure-CPU software rasterizer (z-buffer, per-vertex linear blend skinning off the glTF animation samplers, meshopt decode on the way in) draws into a framebuffer the size of the caller's terminal and encodes it as ▀ half-blocks, so one cell carries two independently coloured pixels and pixels come out square. The server streams paced frames as text/plain, so the HTTP response IS the animation. Sibling of packages/tty-avatar/, which adds moods, avatar-id resolution and Claude Code hooks on top of a terminal renderer but deliberately does not do skeletal animation; this package owns the 3D.
Restyle Studio (material/PBR editor + AI restyle + variants) pages/restyle.html → /restyle, src/restyle.js. PBR preset/variant library packages/viewer-presets/src/materials.js (@three-ws/viewer-presets). AI restyle + persistence core api/_lib/material-studio-store.js, free hosted endpoint api/material-studio.js → /api/material-studio; paid agent twin mcp-server/src/tools/restyle-material.js (restyle_material, $0.05 stdio MCP), thin core mcp-server/src/tools/_material-core.js. Shares the refine_model lineage core (mcp-server/src/tools/_lineage.js) so a restyle/variant is just another kind of version, feeding prompt 09 remix. Docs: docs/restyle.md, docs/mcp-tools.md. Live Re-skin any GLB without regenerating its mesh: live PBR editing (color/metalness/roughness/emissive/texture) with a one-click preset library (18 looks: chrome, gold, copper, brushed steel, gunmetal, matte, glossy, rubber, ceramic, glass, real glass, wood, stone, fabric, skin, car paint, neon, holographic), seeded reproducible colorway variants (mulberry32 PRNG, so the same base plus seed yields the same set), and free-text AI restyle ("make it chrome", "cyberpunk neon") via IBM Granite-proposed PBR factors applied + re-exported server-side. Every AI restyle / saved checkpoint mints a real, gltf-validator-checked, durably-stored GLB recorded in an immutable parent to child lineage: non-destructive in the durable sense, not just an in-browser Reset. Every restyle, variant, and HoloPart part regeneration is checked against its own source with Model Diff's engine via api/_lib/preserve-contract.js before it is ever persisted: topology, UVs, skeleton, skin and clips must come back unchanged (a part regenerate relaxes that to skeleton and clips, since the selected part's own shape is meant to change), or the operation throws instead of returning a URL. Each lineage step with a parent exposes a "Diff" link straight to the Model Diff page, pre-loaded with that exact before/after pair. Every server failure surfaces the API's own error_description, and a storage outage says so and points at Export GLB, which is wholly in-browser. Roadmap prompt 06.
Embodiment: a living agent body in the chat Hosted embed pages/embodiment/embed.html → /embodiment/embed (Vite input + vercel route, frame-ancestors *); engine apps-sdk/embodiment/embodiment-stage.js (EmbodimentStage) + overlay.js; persona tools (free) api/_mcp-studio/persona-tools.js → /api/mcp-studio (create_agent_persona, get_agent_persona, persona_say; deliberately absent from the ChatGPT plugin surface /api/mcp-chatgpt, because their widget needs frameDomains) and (paid) api/_mcp3d/tools/studio.js; shared inline-body artifact api/_lib/embodiment-artifact.js; identity store api/_lib/persona-store.js (Postgres agent_personas + fs fallback + durable R2 GLB); reload route api/mcp3d/persona.js → /api/mcp3d/persona; live chain-state feed api/mcp3d/persona-identity.js → /api/mcp3d/persona-identity (polled only when the embed is opened with ?wallet=1). Emotion/rig/lip-sync cores under src/embodiment/ + src/voice/. Live A generated avatar becomes a persistent, named body that renders inline in ChatGPT/Claude: it lip-syncs each reply, blends the matching expression + gesture, idles between turns, and reloads by persona_id in a fresh session (the id is the capability, no sign-in). Rides the universal canonicalize/retarget clip library; a rig without face morphs animates the jaw, a non-humanoid GLB falls back to a gentle idle (decideRigMode/supportsCanonicalClips), never a bind-pose T-pose. Zero crypto/token surface. Tests: tests/persona-store.test.js, tests/api/persona-resolve-route.test.js, tests/api/persona-identity-route.test.js, tests/mcp-studio.test.js, tests/embodiment-rig-mode.test.js. Evidence: prompts/store-submissions/_generated/embodiment/. Store-submission prompt 07.
Claude.ai artifact embed + builder Endpoint api/artifact.js → /api/artifact, prebuilt viewer public/artifact-viewer.bundle.js (source scripts/artifact-viewer/src.js, npm run build:artifact-viewer), builder page public/artifact/index.html → /artifact + README, contract specs/CLAUDE_ARTIFACT.md, vendored sandbox CSP public/claude-artifact-csp.txt (refresh: scripts/refresh-claude-csp.mjs). Live GET /api/artifact?agent=<uuid> returns ONE self-contained HTML document with three.js, GLTFLoader, the viewer and the agent GLB all inlined, because Claude's artifact sandbox CSP blocks every external script and fetch. Paste the URL into a Claude conversation and the agent renders inline. The builder page is the pre-flight: it lists real public agents that carry an embeddable avatar (/api/agents/public?avatar=1), renders the response in a sandboxed iframe under the same CSP Claude applies, and reports payload size, fetch time, frame render time and sandbox compliance before you paste. Size is graded against the ceiling the endpoint can actually emit (a 6 MB model base64-inlines to 8 MB, plus the 565 KB viewer), not against the raw model cap, so a large-but-accepted artifact is not flagged as over budget. ?model=<glb url> is the viewer-only lane (allowlisted https origins, SSRF-guarded, 6 MB cap). Tests: tests/api/artifact.test.js pins the generated HTML against the vendored Claude CSP.
Avatar Artifact: the standalone shareable viewer Page pages/avatar-artifact.html → /avatar-artifact, scene + artifact loader src/avatar-artifact.js, docs docs/avatar-artifact.md. Live One page, one avatar, no wrapper: the URL you paste into an <iframe> on someone else's site or send to a person who has never heard of three.ws. ?agent=<uuid> renders that agent's avatar from the live public record (the name becomes the heading and the document title, an Open profile link appears), ?model=<glb url> renders any GLB from the same allowlisted hosts /api/artifact enforces, and a bare link renders the house portrait: a procedural figure that tracks cursor, touch and arrow keys. Ships no third-party CDN (three.js is bundled, because an embed host never agreed to a cross-origin script) and suspends its render loop on a hidden tab. An avatar with no baked clips is driven by the shared retargeted idle from the universal clip library rather than left in a bind-pose T-pose. Every failure lane (no such agent, private avatar, no avatar yet, blocked host, dead model, no WebGL) has its own sentence and its own next move; the Copy embed snippet carries the artifact parameters so the iframe shows what you were looking at.
Spatial MCP (3D as a native response type) Spec specs/SPATIAL_MCP.md, pure validator/builder/lint public/spatial-mcp/spatial-validator.js (published at https://three.ws/spatial-mcp/spatial-validator.js; server-side re-export api/_lib/spatial-mcp.js), npm package + conformance fixture corpus packages/spatial-mcp/ (@three-ws/spatial-mcp, CC0, drift-guarded byte-identical to the published module), validator tool api/_mcp3d/tools/spatial.js (validate_spatial_response, free), reference renderer public/spatial-mcp/spatial-renderer.js + demo/checker public/spatial-mcp/index.html + public/spatial-mcp/demo.js → /spatial-mcp, docs docs/spatial-mcp.md. Live · both stores Open (CC0) shape for returning a live, interactive 3D scene as a first-class MCP tool result (scene GLB, camera, environment, animation, AR handoff, affordances) instead of a URL. Every three.ws 3D generator emits a conformant artifact under structuredContent.spatial; the validator returns actionable errors, not a boolean; the framework-free reference renderer displays any conformant payload — including one transformed from a foreign tool result (portability proof at /spatial-mcp). The page runs the real validator in the browser: every rendered payload shows its verdict, and a paste-in checker validates arbitrary payloads as you type (with a deliberately broken example) so an implementer debugs an adapter without leaving the page. Zero coin surface — reusable in the OpenAI free app. Tests: tests/spatial-mcp.test.js, render smoke tests/e2e/spatial-mcp-render.spec.js. Evidence: prompts/store-submissions/_generated/spatial-mcp/. Store-submission prompt 20.
AR-ready exports ("View in your space") Device-routing core api/_lib/ar-launch.js, UA-branched launch endpoint api/ar.js → /api/ar, the actual AR page it hands off to pages/ar-view.html + src/ar-view.js → /ar/view, MCP tool api/_mcp3d/tools/ar.js (export_ar, free), in-viewer AR button public/viewer.html, docs docs/ar.md. Live · both stores GET /api/ar?src=<glb> branches on the request User-Agent server-side: Android gets a clean 302 into the Google Scene Viewer ARCore intent (browser fallback to the WebGL viewer); iOS, desktop, and any live avatar get a 200 interstitial carrying this model's real og:image/title (so a pasted link still unfurls, which a bare 302 cannot do) that immediately hands off to /ar/view. /ar/view is a real Vite-bundled page, not HTML this endpoint writes inline, because Quick Look needs a genuine USDZ and <model-viewer> does not generate one on its own: the page fetches the GLB and runs it through the same client-side usdz-pipeline.js (three.js USDZExporter) that /avatars/:id/ar (src/ar-page.js) already used correctly, sets the result as ios-src, then offers Quick Look. An earlier version of this endpoint inlined a <model-viewer> with no ios-src and a comment claiming model-viewer converted GLB to USDZ on its own; it does not, so iOS visitors silently fell back to the plain 3D viewer for months. Bad input rejected at the boundary with a designed error page. export_ar returns the AR launch link + a conformant Spatial-MCP artifact; response is OpenAI-clean (no ids/coin surface). kind=avatar is the living-agent lane: the interstitial's redirect target leads with a "Bring it to life" handoff into /irl?avatar=<glb> (avatar-producing tools return irlUrl automatically), and Android goes to /ar/view too instead of the blind Scene Viewer redirect so the living path stays visible. Tests: tests/ar-export.test.js, tests/api/ar-endpoint.test.js. Evidence: prompts/store-submissions/_generated/ar/. Store-submission prompt 21.
AR Forge (prompt → model → your room) public/ar-forge.html → /ar (self-contained page, CDN model-viewer + local meshopt decoder, no Vite registration needed; vercel route sets xr-spatial-tracking permissions-policy) Live Mobile-first app: one prompt hits the free NVIDIA lane (POST /api/forge {backend:"nvidia"}, poll ?job=), the result renders in an AR-capable <model-viewer> with "View in your space" (WebXR / Scene Viewer / Quick Look). Non-AR devices get a QR handoff to GET /api/ar?src= (server-side UA routing) plus a copyable /viewer?src= share link. Deep link /ar?src=<glb>&title= reopens any shared model; recent forges persist in localStorage. Designed idle/working/failed/result states; https-only GLB guard.
Daily Forge (daily challenge + creator streak) pages/daily.html → /daily + src/daily.js, deterministic theme rotation src/daily/daily-theme.js, streak state machine src/daily/creator-streak.js Live The anonymous-first retention loop the platform lacked: the logged-in streak system (api/_lib/streaks.js) needs an account, so the no-sign-up forge majority had no reason to return. Every UTC day resolves to one curated creative theme (the same for everyone, hashed from the date — no backend, no randomness) with a running "Day N" counter; forging today's theme on the free lane lights a localStorage streak (consecutive-day state machine: extend / reset-on-gap / never-double-count, best preserved, at-risk vs lapsed display), and milestones (3/7/14/30/50/100/365) fire a celebration. The generation lands in the shared recents so it's one tap from /ar and /ar/studio; a "Fresh from the community" strip reads /api/forge-gallery?scope=community. changefreq: daily in the sitemap. Tests: tests/daily-theme.test.js, tests/creator-streak.test.js.
AR Studio (multi-model live camera scene) pages/ar-studio.html → /ar/studio + src/ar-studio.js, which imports its reusable core (multi-anchor WebXR session, pure scene math, room client, coords) from the 3d-ar-studio package source packages/ar-studio/ Live The standalone multi-model AR surface: place ANY number of models/avatars into one live camera view (every earlier AR lane was single-model). Model sources: in-view forge (POST /api/forge {backend:"nvidia"} runs behind the live camera, result drops into the room), the forge gallery (/api/forge-gallery, yours + community tabs), recent forges (localStorage, shared with /ar), the CC0 Object Library (/api/objects/library, an Objects tray tab with client-side name/category search), a pasted GLB link, or repeatable ?src= deep links (https/relative only). Rendering ladder: WebXR immersive-ar with one XRAnchor per placed model + always-armed reticle (Android), getUserMedia passthrough + gyro world-lock (iOS/everywhere), grid preview + drag-look + QR handoff (desktop). Gestures: tap select, drag move, pinch resize, two-finger twist rotate; per-model duplicate/rotate/remove, clear-with-undo. Real device AR, not just the camera composite: the AR control resolves what the device can actually do and routes there rather than defaulting every non-WebXR device to the composite: the immersive WebXR session where it exists, Apple Quick Look on iOS and Google Scene Viewer on Android otherwise (both selectable per-model from the selection bar too), and an honest "open this on a phone" QR prompt everywhere else. The button relabels itself to match ("Immersive" only where an immersive session is real). Quick Look reads USDZ, so the selected model's GLB is converted on the device through the same usdz-pipeline.js bake /avatars/:id/ar uses, not the camera-passthrough composite, which has no real-world plane detection or scale and previously shipped as the only iOS experience. Humanoids with no baked clips idle via the universal retarget (src/irl/pin-idle.js); scene persists in localStorage and the whole ARRANGEMENT (models + transforms) round-trips through a base64url #s= hash on the share/QR URL, so a composed scene reopens exactly on any device. Presence realism: WebXR placements are lit by the real room via lighting-estimation (src/ar/estimated-lighting.js, three's XREstimatedLight, real primary-light direction/colour + a live environment cube map so metal/glass reflect the actual room, reverting to baked lights when the device isn't estimating) and occluded by real geometry via depth-sensing (src/ar/depth-occlusion.js); the passthrough path matches room brightness AND colour by sampling the camera feed. Desktop keyboard controls (arrows nudge / R rotate / D duplicate / Delete). Photo capture composites camera + WebGL (src/irl/share-frame.js). Reachable from /ar, the forge AR panel, and the /viewer action sheet. Shared rooms (build together, live): "Share live" opens a room with a 6-char code; anyone who opens /ar/studio?room=CODE joins the same scene and every add / move / scale / rotate / remove delta-syncs in real time, with a live "N here" presence pill. New Colyseus room multiplayer/src/rooms/StudioRoom.js + schema multiplayer/src/studio-schemas.js (owner-gated edits, per-room/per-owner caps, per-client rate limit, https-only src validation, the same discipline as WalkRoom's object channel), client packages/ar-studio/src/studio/net.js (hosted-server binding in src/ar/studio-net.js), and a shared logical coordinate frame packages/ar-studio/src/studio/coords.js (relEast/relNorth/yawDeg) so every device agrees on placement; QR-marker colocalization (src/irl/marker-anchor.js) is the co-located "same physical table" upgrade. Runs on the same Colyseus host as /walk and /irl (a new room, not a new process). Tests: package suite npm test --prefix packages/ar-studio, tests/ar-studio-package-parity.test.js, tests/ar-studio-scene.test.js, tests/ar-studio-coords.test.js, tests/ar-estimated-lighting.test.js, tests/studio-room.test.js. Shipped as open source: the same surface is extracted, generalized and published as 3d-ar-studio (source of truth is packages/ar-studio/, mirrored to nirholas/3D-AR-Studio via data/standalone-mirrors.json; the in-app studio imports the same modules, so there is one implementation, demo https://nirholas.github.io/3D-AR-Studio/, MCP server io.github.nirholas/3d-ar-studio), so any site can embed a multi-model AR studio with one script tag. It defaults to OUR catalogue and generation lane (/cdn/objects/library/manifest.json, /api/mcp-studio, /animations/manifest.json, /hdri/*, /api/ar), which is why those surfaces answer open CORS.
Portal (any website as a walkable world) Page pages/portal.html → /portal + controller src/portal/main.js, renderer src/portal/render.js, styles src/portal/portal.css; reader api/_lib/portal/outline.js + guarded fetch api/_lib/portal/fetch-site.js + robots matcher api/_lib/portal/robots.js; pure layout packages/portal/src/layout.js; GLB export api/_lib/portal/world-glb.js; endpoint api/portal.js → /api/portal Live Paste an address and walk the page: each section becomes a building sized by its word count (log scale), each link a door (same-site doors rebuild the world there and push browser history, outside links open the page), each image a billboard loaded through /api/img, each code block a monolith, and the palette comes from the page's own theme-color or a hash of its host. The layout is a pure, seeded function so the browser, the GLB exporter, the MCP tools and the npm package all build the identical city from one link. Crawler manners are part of the product: a declared user agent, robots.txt honoured per RFC 9309, one fetch per page cached fleet-wide for an hour, and an IP-pinned SSRF guard with size and time ceilings. format=glb returns the world as glTF with named nodes. SDK + CLI + MCP server: packages/portal/. Docs: docs/portal.md. Spec: specs/PORTAL_WORLD.md. Tests: tests/portal-robots.test.js, tests/portal-outline.test.js, tests/portal-layout.test.js, tests/portal-endpoint.test.js, tests/e2e/portal.spec.js
IRL (agents in the real world) pages/irl.html → /irl + src/irl.js, WebXR placement src/ar/webxr.js + pinch packages/ar-studio/src/studio/pinch.js, animated Quick Look bake src/usdz-animated.js (static fallback src/usdz-pipeline.js), backend api/irl/ Live Pin an agent at a real GPS spot; discovery is presence-proof-gated (docs/irl/THREAT-MODEL.md). Place in AR leads the dock on AR-capable devices: WebXR hit-test anchoring on Android with two-finger pinch resize (25%..400%) persisted to the pin (anchor_scale; the pinch lands as a follow-up PATCH /api/irl/pins {id, scale} after the placement tap), and ARKit Quick Look on iOS with the idle clip baked into the USDZ so the agent moves instead of standing in a T-pose. Discovered pins are equally alive in the in-page camera view: every mounted humanoid GLB plays the retargeted idle clip via a per-pin mixer (src/irl/pin-idle.js, phase-randomized, LOD-bounded), camera-aware gaze composes on top of the running animation, and the scene renders with ACES tone mapping + IBL + soft shadows (e2e: tests/e2e/irl-pin-idle.spec.js). Inbound /irl?avatar=<glb> is the living-agent handoff from GET /api/ar?…&kind=avatar (explicit ?avatar= wins over a saved session). Money Drops and World Lines: docs/irl.md. SDK: packages/irl/. Share (src/irl/share-frame.js, api/irl/share.js, api/irl/share/[token].js) mints a permanent, unfurlable /irl/s/:token link from the captured AR photo for the pin you just placed - never a coordinate, owner-gated, falls back to the plain native share sheet with no active pin. Analytics (api/_lib/irl-analytics.js, api/irl/analytics.js) is the first site-wide usage rollup for the feature - pins placed, nearby reads, placement method, shares, drop claims - aged out by the existing hourly reaper. Visit links and signs (src/irl/visit-link.js pure rules, src/irl/visit-banner.js the "you're here to meet" banner, printable sign pages/irl-sign.html → /irl/sign?pin=<id> + src/irl-sign.js, dashboard modal in src/dashboard-next/pages/irl-placements.js): /irl?pin=<id> is the scannable handoff for a street demo. The page names the agent from the coordinate-free agent card until the presence-gated nearby read returns that pin, then flashes it and opens its card once. The discovered-pin card gains View in AR for ANY discovered pin, capability-routed by src/irl/pin-ar.js: iOS bakes the pin's GLB to an animated USDZ for Quick Look (the banner reads "Talk to " and its tap reopens the card with the conversation live), Android with ARCore enters the same WebXR hit-test session as placement in a view-only mode (enterFloorAnchor({ viewPin }): the pin's mounted model is the session content, nothing persists, the group's transform is restored on exit), everything else opens the /api/ar launcher in a new tab. Talk (src/irl/pin-talk.js) is a live spoken conversation with the agent standing in front of you, inside the pin sheet: the same TalkController as talk mode on /avatars/:id (mic or typed turn, /api/chat in the agent's persona by agentId, TTS in its voice, lipsync from the audio FFT onto the pin's mounted model via AvatarMouthTarget), barge-in on the mic, and a talk interaction logged once per conversation (never the transcript). While a conversation or a view-only AR session is open the pin's full model is pinned resident in enforceLOD (_pinnedFull). Runbook: docs/irl/street-demo.md. Tests: tests/irl-visit-link.test.js, tests/irl-pin-ar.test.js, tests/irl-pin-talk.test.js, e2e tests/e2e/irl-pin-talk.spec.js.
Smart glasses (the nearest-agent cue on your lens) Pure HUD protocol src/irl/glasses/protocol.js, controller src/irl/glasses/bridge.js, Web Bluetooth transport src/irl/glasses/transport.js, device adapters src/irl/glasses/frame.js (Brilliant Labs Frame) + src/irl/glasses/g1.js (Even Realities G1), connect sheet src/irl/glasses/connect-ui.js, wired into src/irl.js behind the /irl "Connect glasses" button Live (companion BLE lenses) · Meta Ray-Ban Display and native camera/voice lanes planned No smart-glasses display in 2026 can render a three.ws avatar: Frame and the G1 are thin Bluetooth screens with no browser, and Meta Ray-Ban Display is a 600x600 additive panel whose SDK states custom pixel and 3D rendering are unsupported. So the lens carries the SIGNAL (nearest agent, direction, distance, arrivals) that /irl already computes for its on-screen nudge (src/irl/proximity-cue.js), and the phone keeps the BODY in AR. The protocol module is pure (no DOM, no Bluetooth, no clock) so formatting, direction glyphs and byte-level packet framing are unit tested; the bridge above it owns WHEN to push (3 Hz ceiling, single-flight writes, 4 s heartbeat that recovers a dropped write, 3.5 s announcements) and mirrors IrlNet's status-event shape. A connected link stamps its telemetry as a glasses encounter. Web Bluetooth is Chromium-only, and the connect sheet gates on that honestly rather than failing at pair time. Docs: docs/glasses.md → /docs/glasses, build plan docs/glasses/meta-ray-ban-display.md, platform research docs/glasses/research.md. Tests: tests/irl-glasses-protocol.test.js
Verifiable 3D provenance (content credentials, signed by default) Spec specs/PROVENANCE_3D.md, pure core api/_lib/provenance-3d.js, automatic issuance api/_lib/auto-provenance.js, Solana anchor api/_lib/provenance-anchor.js, MCP tools api/_mcp3d/tools/provenance.js (verify_provenance free, anchor_provenance paid $0.05), free REST verify api/provenance.js → /api/provenance, model page + viewer badge (src/model-page.js, public/viewer.html), docs docs/provenance.md. Live (verify + automatic signing) · anchor gated on issuer key + devnet funds C2PA-style signed content credentials for AI 3D: creator, prompt, model/provider, lineage, timestamp, and the GLB's sha256, ed25519-signed by the three.ws issuer. Every forge-generated GLB (every lane: free NIM, Forge Pro, rigged avatars, self-host, async GCP workers) and every x402 paid-asset download gets this credential automatically and free, with no anchor and no spend, keyed by content hash so a credential is only ever issued once per file; the owner can turn it off with PROVENANCE_AUTO_DISABLE=true. Free public verify_provenance / GET /api/provenance?src=… recompute the hash and return `verified
Simulation readiness (a physics grade for 3D assets) Spec specs/SIM_READINESS.md, pure core api/_lib/sim-readiness.js, storage api/_lib/sim-readiness-store.js + migration 20260813180000_sim_readiness_grades.sql, free MCP tool api/_mcp3d/tools/sim-readiness.js (grade_sim_readiness), free REST api/sim-readiness.js → /api/sim-readiness, shared badge + details panel public/sim-readiness-panel.js (<sim-readiness>, used by public/viewer.html and src/model-page.js), write path in api/_lib/forge-store.js materializeCreation, docs docs/sim-readiness.md. Live The question a renderer never asks and a rigid-body solver always does: can this mesh be simulated as-is? Four verdicts (simulation_ready, needs_scale, needs_repair, unusable, plus unreadable for non-glTF bytes) over measurements derived entirely from the geometry: watertightness and winding via welded-position topology, real-world extents read as meters per the glTF unit convention, exact volume/centroid/inertia from the divergence theorem and tetrahedron covariance, and a convex-hull proxy with its convexity ratio. Nothing is guessed: where a value cannot be known from the mesh (true scale, density) the report says so. Grades are keyed by GLB content hash, not URL, so one row serves the forge creation, the Object Library entry, a remix and an arbitrary third-party URL; every finished generation is graded on the write path, so a model page renders its verdict with no extra request. Signed into the content credential as simReadiness (provenance v2), which is what makes the physics claim as forge-proof as the authorship claim. Free, no account, no coin surface, both stores. Tests: tests/sim-readiness.test.js, tests/api/sim-readiness-endpoint.test.js, tests/provenance-3d.test.js.
Engine QA (a real-time-engine fitness grade) Isomorphic core api/_lib/engine-qa-core.js (thresholds + verdict math, zero imports), server grader api/_lib/engine-qa.js, browser-only partial grader src/engine-qa-client.js, free REST api/3d/engine-qa.js → /api/3d/engine-qa (?lods=1 builds a real LOD chain first, ?format=stl exports a watertight mesh), shared badge + details panel public/engine-qa-panel.js (<engine-qa>, used by public/viewer.html and Rig Doctor's src/rig-doctor-page.js), LOD chain builder packages/glb-tools/src/lod.js (buildLodChain, real meshoptimizer decimation tagged MSFT_lod), opt-in generation variant in api/_lib/forge-store.js (buildLodVariant, wired through api/_lib/forge-options.js's lods option) + migration 20261015020000_forge_lod_variant.sql, docs docs/engine-qa.md → /docs/engine-qa. Live The question a game engine's import step asks that neither glTF validation nor simulation readiness answers: will this run at 60fps, and can it collide cheaply? Five checks, each pass/warn/fail/skip, overall the worst non-skip verdict: draw calls (real scene-graph walk, one per node+primitive pair actually reachable from the root, so instancing counts correctly), material count, texel density (texels per meter of real-world surface, skip honestly when nothing is UV-mapped to a texture), a per-LOD-level triangle budget plus the monotonic-decrease rule a chain must satisfy, and collider suitability (reuses the print pipeline's watertight/manifold analyzer). The thresholds and verdict math live in one zero-dependency core so the server grader and Rig Doctor's zero-network browser pass can never disagree. The same buildLodChain pipeline backs an on-demand upgrade in the panel and an opt-in { lods: true } generation option that stores a combined MSFT_lod GLB as a third object alongside the delivered mesh, fire-and-forget, same pattern as the existing web-delivery variant. Tests: tests/engine-qa-core.test.js, tests/engine-qa.test.js, tests/engine-qa-client.test.js, tests/forge-options.test.js, tests/forge-store-materialize.test.js.
Engine bridges (Unity, Godot, Unreal) Shared contract specs/ENGINE_BRIDGE.md, Unity UPM package packages/unity-bridge (ThreeWsClient.cs + ThreeWsForgeImporter.cs on glTFast), Godot addon packages/godot-bridge (three_ws_client.gd + forge_importer.gd on Godot's native GLTFDocument), Unreal plugin packages/unreal-bridge (FThreeWsClient + FThreeWsForgeImporter on Unreal's Interchange glTF pipeline), docs docs/engine-bridges.md → /docs/engine-bridges. Live (Unity, Godot) · Unreal plugin ships source-complete, untestable in this environment (no license-free headless Unreal install) One prompt-to-mesh contract, three independent implementations, each calling only the public Forge API: POST /api/forge to submit, GET /api/forge?job=<id> to poll (server-side failover keeps the same job id even if the lane dies mid-run), a plain HTTPS GET to download. Anonymous by default via a per-instance x-forge-client handle, same free-first routing every other caller gets; set a provider key for BYOK. The same four shared import settings (generate_colliders, import_materials, scale, destination) map onto each engine's own equivalent: a convex MeshCollider in Unity, a ConvexPolygonShape3D in Godot, a bounding-box UBodySetup in Unreal. Each package ships an editor window/dock (Unity: Window > three.ws > Forge Bridge; Godot: the three.ws Forge dock; Unreal: Window > three.ws Forge Bridge) plus a runnable example and a README. Godot's test/smoke_test.gd runs the full flow headlessly against the live API (godot --headless --script test/smoke_test.gd); Unity and Unreal require a licensed GUI install to exercise, so they're verified by code review against the shared contract instead. Store packaging: npm run package:engine-stores (scripts/package-engine-bridges.mjs) validates each bridge and builds a deterministic upload zip for the Unity Asset Store, Godot Asset Library and Fab from the listing metadata in docs/engine-store-listings/; the owner submits, see docs/engine-store-publishing.md.
OpenAI Select Partner (partner surface + announcement pack) pages/openai/index.html → /openai, badge assets public/partners/openai/, announcement blog/three-ws-openai-select-partner.html → /blog/three-ws-openai-select-partner, directory card in pages/partners.html → /partners, press/social pack marketing/openai-select-partner/, original OpenAI-supplied badge files + press-release template OAI Select Tier Assets/ Live three.ws's OpenAI Partner Network Select-tier surface. /openai is the partner landing: the supplied badge (used unmodified, on a white plate), the four live OpenAI surfaces (the free keyless 3D Studio MCP connector → /api/mcp-studio, the custom-GPT Actions twin → /api/3d/studio, Spatial MCP, and AR in ChatGPT), the connect table, and the eleven-tool list. The marketing pack holds badge-usage rules and the press-release draft, which is gated on OpenAI's written approval before publishing (see its README).
NVIDIA Inception (membership surface + GPU docs cluster) Landing page pages/nvidia/index.html → /nvidia (vercel route + vite input + dev middleware, same wiring as /openai), membership doc docs/nvidia-inception.md → /docs/nvidia-inception + overview deck docs/nvidia-inception/index.html → /docs/nvidia-inception/index.html, free hosted-model map docs/nvidia-models.md → /docs/nvidia-models, forum write-up docs/nvidia-nemotron-spotlight.md → /docs/nvidia-nemotron-spotlight, tutorials docs/tutorials/nvidia-3d-free.md → /tutorials/nvidia-3d-free and docs/tutorials/nvidia-nim-self-host.md → /tutorials/nvidia-nim-self-host, engineering post blog/image-to-3d-on-nvidia-l4-and-blackwell.html → /blog/image-to-3d-on-nvidia-l4-and-blackwell, member badge public/marks/nvidia-inception-badge.svg in public/footer.html, directory card in pages/partners.html → /partners Live Everything NVIDIA on the platform, in two layers. Free hosted lane: one NVIDIA_API_KEY behind TRELLIS text-to-3D, FLUX.1-schnell, the Llama/Nemotron chat lineup, Nemotron vision, nv-embedqa, the reranker, NemoGuard, and Magpie speech (nvidia-models). Self-hosted GPU fleet: 12 Cloud Run GPU services, 11 on nvidia-l4 and one on nvidia-rtx-pro-6000 (Blackwell), covering text/image-to-3D, texture, remesh, rigging, and motion (see each workers/model-*/README.md). Membership was accepted July 2026 and is a startup program, not a partnership or an investment; the badge links to NVIDIA's startup program and must not imply endorsement.
Press kit (brand marks + media assets) pages/press/index.html → /press, marks public/brand/, layout source marketing/brand/, renderer scripts/render-brand-assets.mjs npm run build:brand-assets Live The self-serve press surface: transparent-PNG marks (cube, horizontal and stacked lockups for dark and light grounds), the OpenAI announcement graphics, boilerplate at four lengths (one line, short, long, and a full-length bio) with copy buttons, fast facts, and the mark-usage rules. Everything is rendered from source rather than hand-exported, so a copy change re-renders the whole set; the renderer also builds /brand/three-ws-press-kit.zip with a README carrying the usage rules so the files cannot travel without them. Announcement cards come from marketing/openai-select-partner/cards/social-card.html via npm run build:openai-cards.
Sperax partnership + SperaxOS plugin pages/sperax.html → /sperax, plugin public/sperax/, manifest → /.well-known/sperax-plugin.json, tools api/chat-plugin/[tool].js → /api/chat-plugin/*, panel → /sperax/iframe/, bundled SDK component chat-plugin/ (@three-ws/chat-plugin, for hosts that mount plugins as React components instead of framing the manifest) In-repo · Live Partnership landing for the SperaxOS integration: three.ws ships as a standalone plugin.delivery plugin that gives a SperaxOS agent an embodied 3D avatar (speak/gesture/emote/render_agent), bound to an ERC-8004 identity, settling over Base x402. Launch offer: free AI credits for three.ws users on chat.sperax.io — page explains what it is and how to claim. Blog: /blog/three-ws-speraxusd-integration
Agent Monitor (fleet ops board) pages/monitor.html + src/monitor.js → /monitor In-repo · Live HQ-style ops-room dashboard for the whole 3D agent fleet on one screen, every panel a real public feed on its own poll cadence: fleet ranked by real actions (api/agents/public.js sort=live) with a click-to-load 3D <agent-3d> spotlight, live screen casts (api/agent-screen-active.js), 24h money pulse + 7d sparkline + agent coin launches (api/pulse.js view=stats), delta-polled on-chain event wire (/api/pulse with head_cursor), A2A hire volume (api/agent-economy/volume.js), uptime probes (api/status.js), a community forge feed (api/forge-gallery.js), the tip-earner leaderboard, and the crew directory (api/crews/directory.js). Panel controls: fleet search + sort (server q=/sort=), wire kind filters + pause, x402 period and A2A window toggles, mainnet/devnet switch, spotlight prev/next/fullscreen, and keyboard shortcuts (f search, r refresh, [/] cycle spotlight)
Live Agents wall (mission control) pages/agents-live.html + src/agents-live.js → /agents-live In-repo · roster api/agents/public.js (sort=live), batched activity api/agents/activity.js, per-agent SSE api/agent-screen-stream.js Real-time grid of every meaningful agent, ranked by most-recent on-chain/skill action (never-used placeholders suppressed). Each card streams a live caster feed when watched, else its real agent_actions as a terminal + an "active Nm ago" recency chip. Two feed layers, because they answer different questions: every mounted card gets its activity from ONE batched /api/agents/activity call (whole page, one round-trip, shared row mapper api/_lib/agent-activity.js), while SSE listeners are pooled (src/shared/stream-pool.js, sized from the origin's real transport) and spent only where something is genuinely pushed: a casting agent, the spotlight, a warming caster, or the card a viewer reaches for. Layers: showrunner spotlight (src/showrunner.js), reputation arena (src/agents-live-arena.js), platform ticker (src/theater-feed.js)
On-demand caster pool (the live browser behind a watched agent) Worker workers/agent-screen-pool/ (deploy workers/agent-screen-pool/cloudbuild.yaml); API watch set api/agent/watch-intent.js + api/agent/watch-wanted.js + api/agent/watch-status.js, frame sink api/agent-screen-push.js In-repo · built + deploy-ready, not yet deployed as a Cloud Run service Casts a real Chromium page for exactly the agents viewers are watching right now (bounded by MAX_BROWSERS), running a real multi-step web task from tasks/index.js and pushing JPEG frames the wall renders; tears each browser down when the last viewer leaves, so cost scales with concurrent viewers instead of agent count. Auth is the shared SCREEN_WORKER_SECRET (Secret Manager screen-worker-secret); each authenticated poll refreshes the pool-liveness key so a card with no pool running stays on the honest zero-cost activity view. Tests: tests/agent-screen-task-sequencer.test.js (sequencer + task library), scripts/agent-screen-pool-proof.mjs (real worker, real Chromium, real wire contract)
The Crawl (agents reading the open web, watched live) pages/crawl.html → /crawl, app src/crawl/ (stage, live page, corpus table, send panel), styles public/crawl.css, API api/crawl/[action].js with limits in api/_lib/crawl.js, worker workers/agent-crawler/ (deploy workers/agent-crawler/cloudbuild.yaml) In-repo · built and verified locally against production data; API, page and worker awaiting deploy Owners send an agent out with a topic and optional start pages; a Cloud Run fleet of real Chromium contexts reads the web around it, scoring every link against the topic, honouring robots.txt (three.ws-crawler), a per-site gap and a private-address guard, and searching DuckDuckGo, Hacker News and Wikipedia when it runs out of leads. Viewers watch the live frame with the agent's own avatar walking across the page to the link it chose (one SSE hub per API instance over a 75s Redis live layer). Every page read is filed in a public corpus (crawl_pages, full text in object storage) with a JSONL export, and becomes a 30-day memory in the agent when its owner sent it. Docs: docs/crawl.md. Tests: tests/agent-crawler-frontier.test.js, tests/agent-crawler-seeds.test.js, tests/agent-crawler-guard.test.js
Take the wheel (owner drives the agent's computer) Client src/agent-screen-control.js mounted in src/agent-screen.js → /agent-screen; API api/agent-screen-control.js (lease + input) + api/agent-screen-control-drain.js (caster read side); caster dispatch workers/agent-screen-pool/control.js; shared sanitizer src/shared/agent-screen-control.js In-repo · Live · doc docs/agent-screen-control.md The reverse of the frame stream: an agent's OWNER can grab the wheel of its live cast browser and drive it, real mouse, drag, scroll, keyboard, and navigation. Owner-only (session ownership, not the public watch/react channel); acquiring mints a short-lived capability LEASE token used as a bearer for the high-frequency input stream (no per-event CSRF). Events travel normalized (0..1) and are sanitized + range-clamped on the API boundary; nav is SSRF-guarded (no loopback/private/metadata). The caster pool drains queued events into its real Playwright page and pauses its own autonomous task while a human holds the wheel so the two never fight over the cursor. The cast browser holds no wallet or keys, so driving it cannot move funds, that boundary is what makes remote control safe. Tests: tests/agent-screen-control.test.js (21 unit), scripts/agent-screen-control-proof.mjs (real Chromium dispatch)
X/Twitter automation toolkit nirholas/XActions (external repo, also on npm as xactions) External Formerly vendored in-repo; removed 2026-07-03 — install from npm or use the upstream repo
Agora — the Commons (living economy) pages/agora.html + src/agora/ → /agora, life engine workers/agora-citizens/, read model api/agora/[action].js In-repo · devnet AgenC Watchable 3D world where agent + human citizens post, claim, work, prove and earn $THREE on-chain. Play mode ("Enter the Commons") makes it walkable GTA-style — your avatar walks the square among the working NPC citizens, other humans appear live over the agora_world Colyseus room, and walking up to a citizen (proximity → E) opens its passport: src/agora/player-mode.js, pure math src/agora/player-logic.js, room multiplayer/src/rooms/AgoraRoom.js. Play mode also has an opt-in "Record on-chain (BNB testnet)" toggle (OFF by default) that gaslessly commits your moves to the WorldMoves contract every ~block via MegaFuel (self-pay fallback) and renders other on-chain players as lightweight ghost markers read back from real Moved events: src/agora/onchain-presence.js, sender src/bnb/move-sender.js, event reader src/bnb/world-presence-reader.js, pure ghost interpolation src/bnb/onchain-ghosts.js, server relay lib api/_lib/bnb/world-moves.js, config endpoint api/bnb/world-config.js. WorldMoves contract: contracts/src/WorldMoves.sol (code-complete + anvil-fork-proven; public BSC testnet deploy pending a funded deployer key — see contracts/DEPLOYMENTS.md). Arena (Competitive tasks — citizens race, first valid proof wins the whole escrow) at src/agora/arena.js; Guilds (Collaborative tasks — contributors split the reward) at src/agora/guild.js, both live-driven by api/agora/task. Spec: docs/agora.md
/play in-game economy (cash, bank/ATM, vendors, $THREE boutique) Client: src/game/coincommunities.js → /play, general-store/bank NPCs src/game/npc/economy-npcs.js, store/bank UI src/game/economy-ui.js, on-chain purchase flow src/game/boutique-purchase.js, wardrobe src/game/play-systems.js. Server: multiplayer/src/rooms/WalkRoom.js (store/bank/boutique handlers), price tables multiplayer/src/shop.js, purse/bank model multiplayer/src/economy.js, on-chain settlement multiplayer/src/game-token.js In-repo The GTA-style open world's real economy (W04 of the World Online program, program brief retired to git history). Walk up to a General Store clerk (E) to buy tools/consumables or sell gathered goods for cash, server-priced and validated every time; walk up to the Bank Teller to deposit cash into a protected balance (survives a death drop) or withdraw it. Premium wardrobe cosmetics unlock with a real on-chain $THREE payment from the player's connected Solana wallet; the server only grants the item after re-verifying the confirmed transaction on RPC. Distinct from the separate USDC/x402 avatar-shop rail (api/x402/cosmetic-purchase.js), which sells a different catalog for the standalone character creator. Published publicly at pages/play/economy.html → /play/economy (src/play-economy.js), fed by api/play/economy.js → /api/play/economy, which serializes the SAME shop/economy/spin-wheel modules the server prices trades with rather than restating them, so the public reference cannot drift from the game. Docs: docs/in-game-economy.md, tutorial docs/tutorials/earn-and-spend-in-play.md. Tests: tests/api/play-economy.test.js
Flappin UFO (/play/ufo) pages/play/ufo.html → /play/ufo, game src/play/ufo/game.js, shared deterministic physics and verifier src/play/ufo/sim.js, styles src/play/ufo/ufo.css. API: api/play/ufo-runs.js → /api/play/ufo-runs over api/_lib/migrations/20261023150000_ufo_runs.sql; metric ufo_score in api/leaderboard/unified.js In-repo A hold-to-climb canvas arcade game whose levels get longer and tighter. The browser and the server run the SAME fixed-step simulation (src/play/ufo/sim.js): the client records the ticks where thrust flipped, the server replays them, rejects impossible runs (422) and stores the score it computed, never the claim. Best run per player ranks; the top run replays as a ghost on the same fixed course. Docs: docs/play-ufo.md. Tests: tests/play-ufo-runs.test.js
/play character & avatar customization (avatar creator, selfie→3D, wardrobe boutique) Lobby creator flow src/game/coincommunities-ui.js _openCreate(), selfie SDK wrapper src/avatar-creator.js, shop src/game/cosmetics-shop.js, wardrobe src/game/cosmetics-wardrobe.js, boutique NPCs src/game/npc/npc-catalog.js (npc-tailor, npc-fitting-room), boutique spawn points src/game/world-zones.js (type: 'boutique'), in-world avatar switcher src/game/avatar-switcher.js (HUD Avatar button / V, swap applied in src/game/coincommunities.js _applyAvatarSwap()) In-repo W03 of the World Online program (program brief retired to git history). Before dropping into /play, design an avatar from scratch or a selfie (real Avaturn SDK), upload a .glb, or sculpt in the full Avatar Studio; no sign-in required. Once in the world, press V (or the HUD Avatar button) to change avatars without leaving: saved three.ws avatars, quick picks, gallery, paste-a-URL, upload, and the creator, rebuilt live on your rig and broadcast to peers over the room's avatar message. The cosmetics shop/wardrobe (real x402-settled catalog, server-persisted equip) also has a physical home: walk up to Roux · Tailor to browse/buy, or Nell's Fitting Room to equip anything you own. Doc: docs/character-studio.md. Tests: tests/play-avatar-switcher.test.js, tests/walkroom-avatar-swap.test.js.
/play forge-in-world (prompt or photo to a live prop) Lane client src/game/forge-prop.js, palette form + /forge chat command src/game/coincommunities-ui.js (_buildForgeRow(), _submitForge()), placement handler src/game/coincommunities.js (_forgeProp()), styles src/game/coincommunities.css, rendering src/game/world-objects.js (registerUploadedProp), server gate multiplayer/src/build-limits.js (normalizePropAssetUrl) In-repo Describe an item in the build palette's Forge form (or type /forge a glowing campfire in world chat, or attach a reference photo) and the free draft forge lane generates a real textured GLB in about half a minute. The finished model is registered as a placeable prop and armed, so the next click drops it into the shared world through the SAME obj:spawn channel player uploads use: the URL travels on the object, every connected player renders it, and the room persists it like any other build. No new server surface was needed because the durable forge URL (S3_PUBLIC_DOMAIN, an *.r2.dev host) already satisfies the world asset allow-list; an off-list host is refused with obj:reject/asset_url. Generation is one-at-a-time per player, and every failure (rate limit, refused prompt, dead upload, timeout) reports a recovery line in the palette's status strip. Docs: docs/play-forge-in-world.md. Tests: tests/forge-prop.test.js
/play photo mode (the screenshot people post) Card compositor + preview sheet src/game/photo-mode.js + src/game/photo-mode.css, shared offscreen capture src/game/scene-capture.js, HUD camera button src/game/coincommunities-ui.js (photoBtn, setPhotoActive()), P keybinding + lazy host src/game/coincommunities.js (_openPhotoMode()), event agenda action src/game/meetup-event.js (_capturePhoto()) In-repo Press P or the HUD camera button and the world lands on a monochrome share card: the shot, the three.ws mark, the coin's name and symbol, the date, and during a live event that event's own name, read from the same public/event.json the countdown and agenda run on, so an event photo stamps itself with nothing to keep in sync. Download and Copy-image sit under a preview that the world keeps running behind; Escape or the X closes it, and P retakes over it. The shot is an offscreen render, not a canvas grab. captureSceneCanvas() renders one extra frame into a WebGLRenderTarget and reads that back, which is why the HUD, chat, name tags and the preview card itself are never in the frame, why the classic black-screenshot bug (reading a drawing buffer the compositor already took) cannot happen, and why nobody pays the permanent per-frame cost of preserveDrawingBuffer. Cost when no one is taking a photo is zero twice over: no extra render, and the whole module plus its CSS is imported on the FIRST press. Deliberately alive in zen mode, building and driving, since a clean world is exactly when the shot is wanted. Clipboard support is feature-detected: where ClipboardItem is missing the Copy button stays visible and says so rather than breaking. Same capture path backs the build-share thumbnail (_captureBuildShot()). Tests: tests/photo-mode.test.js (compositor geometry, preview sheet, clipboard fallback, event stamp), tests/e2e/play-photo-mode.spec.js (real Chromium + WebKit, pixels of the saved PNG), walkthrough scripts/play-photo-mode-check.mjs
/play combat & weapons (server-authoritative, danger zones, wanted, tombstones) Client: src/game/combat-system.js → /play (vitals HUD wiring, danger-zone ground, tombstone loot, hit feedback, the window.twsCombat bridge into W08's MobSystem), HUD src/game/hud/world-hud.js. Server: multiplayer/src/combat-handlers.js (mob AI, attack/loot intents, death + respawn), pure math multiplayer/src/combat.js, weapon/mob/loot tables multiplayer/src/items.js, zone geometry multiplayer/src/world-features.js, handlers wired in multiplayer/src/rooms/WalkRoom.js In-repo W07 of the World Online program (program brief retired to git history). Equip a sword/bat/pistol/bow from the hotbar and press X (or tap the touch Attack button) to fight; but only inside one of three named danger zones (Southern Wilds, Northern Wilds, Eastern Marches); town stays lawful by construction. PvE mobs chase and swing back through the same server-side damage path a player's attack uses; a kill (mob or PvP) spills a lootable tombstone, PvP raises the attacker's wanted/heat stars (visible on WorldHud and a downed peer's nameplate), and death drops carried cash/pack before an automatic respawn in town.
/play NPCs & world life (traffic, vendors, quest-givers, mobs) Manager src/game/npc/world-life.js, nav graph src/game/npc/nav-graph.js, ambient crowd/traffic src/game/npc/ambient-life.js, quest-giver NPCs src/game/npc/quest-npcs.js, quest-zone waypoints src/game/npc/quest-markers.js, Jobs Board UI src/game/quests-ui.js, W07-gated mobs src/game/npc/mobs.js. Server: quest engine multiplayer/src/quests.js, quest zones multiplayer/src/quest-zones.js, handlers in multiplayer/src/rooms/WalkRoom.js In-repo W08 of the World Online program (program brief retired to git history). A deterministic nav graph drives client-side ambient pedestrians + ring-road traffic that read identically for every player without a single packet; real gameplay stays server-authoritative. Five quest-giver NPCs (Dockmaster Reyes, Warden Okoro, Cook Mara, Foreman Dell, The Fixer) front the jobs board the quest engine (W05) already ran server-side but no client ever reached; pressing E opens the real board, accepting a job drops a waypoint at its objective (goto zones auto-complete by walking there, interact zones get their own "press E"), and finishing pays real cash server-side. Hostile mobs are live: W07's CombatSystem (src/game/combat-system.js) installs the window.twsCombat contract this module's mobs were built against, so MobSystem renders real server-authoritative PvE hostiles with zero changes here. Two jobs; cross-town-delivery (North↔South) and east-west-express (East↔West); are real driving missions: each goto leg is flagged vehicle: true and only completes off the authoritative vehicle-driver map (multiplayer/src/vehicles.js), so walking through a depot never counts, only driving through it does. Depots sit on the avenue vehicle spawns, so a car is always parked at the start. Tests: tests/quests-vehicle-delivery.test.js.
/play vehicles (the drivable fleet & the Trench Car) Handling spec + fleet registry multiplayer/src/vehicles.js, client manager src/game/vehicles.js, meshes src/game/vehicle-mesh.js, shared GLB loader src/game/vehicle-model.js, staged model public/vehicles/ (built by scripts/build-trench-car.mjs, npm run build:trench-car), Rapier chassis src/physics/physics-world.js, server gate + anti-cheat multiplayer/src/rooms/WalkRoom.js In-repo W02 of the World Online program. Real cars you drive with WASD (touch gets pedals and a wheel), simulated locally on the SAME Rapier world the character controller uses, so a car collides with the town exactly as a walking avatar does, and relayed through a server that validates per-type speed and bounds and owns who may drive what. The Trench Car, a community model from the avatar gallery (trench-car), is the only car in the world: ambient traffic drives it in every town (src/game/npc/ambient-life.js) and it is parked in every vehicle bay, so the car you watch go past is the car you can get into (the four procedural box types it used to share the road with were retired 2026-08-17). A car builds a procedural stand-in instantly and swaps the GLB body and wheels into the same group and pivots when the download lands, so a car that upgrades mid-drive keeps its physics, camera and driver, and a failed download still leaves a drivable car. One shared template per model; only the brake-light material is per car. Drivers sit in a seated pose that peers see too (server-authored drive motion). Docs: docs/play-vehicles.md. Tests: tests/vehicles-trench-car.test.js, tests/e2e/play-vehicles.spec.js, tests/quests-vehicle-delivery.test.js; real-Rapier repro node scripts/verify-w02-physics-core.mjs trench
Frame governor & power saver (/play, /club, /walk) src/shared/frame-governor.js, wired in src/game/coincommunities.js, src/club.js, src/club-entrance.js, src/walk.js; toggle UI in src/game/coincommunities-ui.js Live Shared frame-rate governor for the heavy 3D surfaces: 60fps while active, 30fps when idle or unfocused, plus a user-facing Power-saver mode (30fps + lighter rendering, "for a cooler, quieter machine") persisted in localStorage tws-power-saver and shared across surfaces (getPowerSaver/setPowerSaver/onPowerSaverChange, trackWindowFocus). Tests: tests/frame-governor.test.js
/play safety & lifecycle invariants Doc docs/play-hardening.md → /docs/play-hardening. Guards: cssBgImage() + clampParam() + isPlausibleMint() in src/game/coincommunities-ui.js / src/game/coincommunities.js, avatar template cache + releaseAvatar() in src/game/avatar-rig.js, reconnect pruning (_markRemotesStale/_pruneStaleRemotes) and _disposeObject3D() in src/game/coincommunities.js. Harnesses: scripts/play-desktop-audit.mjs, scripts/play-mobile-repro.mjs Live The rules that keep the platform's largest interactive surface safe, honest and phone-survivable, each written against a failure that actually shipped: untrusted display names and coin metadata never become markup or CSS (a tombstone owner's name once ran as HTML for everyone who walked past it; a crafted coin image_uri could paint a full-screen overlay across the lobby), a malformed ?coin= is refused instead of building a convincing world nobody else can join, a valid ?coin= that lost the rest of its query (a hand-typed link, a truncated share, an unfurl that kept only the mint) is named from the coin feed by _fetchCoinIdentity()/mergeCoinIdentity() instead of building a real district under a totem reading "COMMUNITY" with a blank market cap, a reconnect retires the peers who left rather than accumulating frozen ghosts and a tripled headcount, and everything the world loads (crowd/NPC GLBs, the sun's 2048² shadow map, totem, jumbotron, dance floor, district, environment) is genuinely freed on the way out instead of held until the tab is killed. Tests: tests/play-deeplink-safety.test.js, tests/play-deeplink-identity.test.js
Cinematic rendering (shared 3D quality bar) src/shared/cinematic-render.js — applyCinematicDefaults(), loadEnvironment(), detectQualityTier(), updateGroundContactShadow(); curated HDRIs in public/hdri/ (CC0, Poly Haven) Live, wired into every three.js viewer on the platform (/irl, talk mode, /play, /club, /ar, /xr, /walk, /coin3d, marketplace lobby, demo pages, the <agent-3d>/<page-agent> embeds, and more) One module every WebGLRenderer-based viewer calls into instead of re-deriving ACES tone mapping, sRGB output color space, HDRI image-based lighting, and soft VSM shadows per file. detectQualityTier() picks high/medium/mobile from real device signals and caps pixel ratio + disables shadows/HDRI accordingly; loadEnvironment() fetches a real photographic HDRI (studio/outdoor/sunset) and falls back to a procedural room environment on mobile tier or fetch failure (including cross-origin embed contexts where the absolute /hdri/*.hdr URL can't resolve). /walk keeps its own richer per-biome HDR system (src/walk-environments.js); surfaces already running a postprocessing tone-mapping pass (/oracle-graph, /club-entrance) only take the sRGB/HDRI half to avoid double-applying the curve.
/play Wheel of Fortune (Fortune's Folly; free/paid $THREE spins) Client: src/game/wheel-station.js (the plaza landmark, proximity prompt, E to spin; lazy-imports the actual UI on first interact), spin UI src/game/spin-wheel-ui.js (20-segment wheel, free/paid flow, wallet signing). Server: multiplayer/src/spin-wheel.js (paytable, RNG, level/cooldown/pack gates, handlers), split-payment settlement multiplayer/src/game-token.js (buildSpinPayment/verifySpinPayment; the same primitives the $THREE boutique uses), wheel location multiplayer/src/world-features.js WHEEL, persisted cooldown field in multiplayer/src/economy.js, handlers wired in multiplayer/src/rooms/WalkRoom.js In-repo W09 of the World Online program (program brief retired to git history). Walk up to the wheel in the plaza and press E: one free spin every 12h (a real persisted cooldown; survives a disconnect, unlike the ephemeral per-action cooldowns everything else on this row's neighbors use), or pay $3 in $THREE; split 50% to the holder-rewards pool / 50% to the treasury, verified on-chain before any prize is granted, mirroring the boutique's proven settlement pattern exactly. Gated behind an average skill level of 3 (a light anti-farm floor, not a grind) and never lets a won prize get lost to a full pack; room for at least one possible item prize is checked before a spin is even offered, paid or free. All 20 wedges are equal-odds by design, matching the client's fixed-angle wheel rendering exactly (see the header note in spin-wheel.js on why that must never drift). Tests: tests/spin-wheel.test.js.
/play live events (countdown chip, agenda drawer, synchronized fireworks) Config public/event.json (one file, shared with the lobby countdown and the server-side souvenir grant). Client: in-world layer src/game/meetup-event.js + src/game/meetup-event.css, pure schedule math src/game/meetup-schedule.js, particle show src/game/fireworks.js, lobby banner + wayfinding pill src/game/event-countdown.js. Mounted from pages/play.html In-repo Turns the $THREE home town into a place something is happening in for the length of a scheduled event, driven entirely by public/event.json: reset it to its no-event state (npm run event:schedule -- --clear --apply) and the world is normal again, with no code change. A countdown chip docks under the King of the Totem card (and stands the generic pill down, so there is only ever one countdown on screen) and opens a right-docked agenda drawer that marks the running segment, dims finished ones, counts the rest down in local time, and carries a live $THREE pulse row (/api/three-signal) plus one-tap Buy and commemorative-photo actions. Six phases derive from the wall clock (far → upcoming → preshow → live → afterglow → ended), so every player agrees on what is on and what is next without a round-trip. Fireworks are deterministic, not networked: four-second buckets hashed with the event id give every client the identical sky (fireworkPlan()), the same trick src/shared/world-clock.js uses for the shared sun; density ramps into a closing barrage, power-saver halves it, at most 14 shells live at once, and a backgrounded tab rejoins the show live instead of replaying the backlog requestAnimationFrame paused through. Preview any schedule with ?meetup=now or ?meetup=<ISO>. Doc: docs/play-live-events.md. Browser audit: npm run audit:meetup (scripts/meetup-audit.mjs). Tests: tests/meetup-schedule.test.js, tests/meetup-event-ui.test.js
/play event souvenirs (a free wearable you keep for having been there) Config public/event.json (souvenir.cosmeticId, the same file the countdown reads). Server: window/world/item resolution multiplayer/src/event-drop.js, join-time grant _grantEventSouvenir in multiplayer/src/rooms/WalkRoom.js, event tier + catalog entry multiplayer/src/cosmetics-catalog.js, unlock + persistence multiplayer/src/economy.js. Client: drop card src/game/event-souvenir.js, wardrobe treatment src/game/cosmetics-wardrobe.js. Asset: public/accessories/laurel-meetup.glb generated by scripts/generate-accessory-glbs.mjs, poster by scripts/render-accessory-thumbs.mjs In-repo Everyone who joins the event world between an event's startsAt and endsAt is granted a free commemorative wearable (the Meetup Laurel), once, forever, wearable in every coin world. After endsAt it is never granted again and there is no purchase path at any point: a third catalog tier, event, carries price: 0, so the boutique's tier === 'premium' && price > 0 filter excludes it by construction and the x402 purchase ledger is filtered to premium ids so it cannot mint one. Server-authoritative and idempotent: the window and the world both come from the shared event config (never a client option), the grant is a no-op on an account that already owns it, and the one-shot souvenir message only fires on the not-owned to owned transition, so a reconnect produces neither a duplicate nor a second announcement. Fails open on every axis (no config, unreachable config, closed window, wrong world all mean grant nothing and never delay a join). Doc: docs/event-souvenirs.md. Tests: tests/event-souvenir.test.js; live conformance node scripts/play-souvenir-conformance.mjs (real server, no browser) and node scripts/play-souvenir-e2e.mjs (real browser)
/play Coin Wars portal (in-world war door, league board, spectator screen) Client: src/game/war-portal.js + src/game/war-portal.css (plaza landmark, canvas league board, queue panel, results echo), wired in src/game/coincommunities.js; arena page pages/play/war.html → /play/war → src/play/war.js + src/play/war-world.js + src/play/war.css. API: api/wars.js → /api/wars over api/_lib/wars-store.js (ledger + queue + live registry) and api/_lib/war-ticket.js (signs a pairing). Server: multiplayer/src/rooms/ClashRoom.js clash_arena, pairing math multiplayer/src/war-matchmaking.js, ticket verify multiplayer/src/war-ticket.js, spectator snapshots multiplayer/src/war-live.js, league math multiplayer/src/war-standings.js, portal location multiplayer/src/world-features.js WAR_PORTAL In-repo F18. Coin Wars ran full community-vs-community battles with an Elo league behind it and no door into it from any world. The portal is that door: a plaza landmark whose board shows this coin's real league standing, its last battles, and any war running right now (read from /api/wars, folded through the arena's own standings module, never a second implementation). Press E to run the coin's holder gate and queue the community; the matchmaker pairs it with another waiting community, seals both sides into an HMAC war ticket, and hands the player to /play/war with a return link carrying the full coin identity, so walking back lands in the same world with the result already echoing on the board. While a war is live the board becomes a spectator screen (score, round clock, kill feed) off a cheap poll, and a win takes the board over for a few seconds. Costs nothing when nobody is near it: no poll fires outside WAR_PORTAL_BOARD_REACH. Docs: docs/coin-wars.md. Tests: tests/war-matchmaking.test.js, tests/clash-match.test.js
/play event countdown (lobby banner + in-world pill) Self-attaching module src/game/event-countdown.js loaded by pages/play.html; config public/event.json (single source of the event window; the file is the edit surface for scheduling an event), read through the shared parser + state machine in src/shared/event-config.js. Verified end to end in a real browser by npm run verify:event (scripts/verify-event-countdown.mjs). Campaign orders: the event- files in prompts/finish/ In-repo While public/event.json describes an upcoming or live event, the lobby shows a banner (name, tagline, local-time start, ticking countdown, CTA into the event world) and the in-world view gets a dismissible top-center pill (dismissal persisted per event in localStorage). Three explicit states: upcoming, live (pulsing marker, CTA suppressed when already standing in the event world), and over (everything unmounts, the interval stops). Zero edits to coincommunities*.js by design (the ambient-crowd pattern): it waits for the lobby DOM and mounts nothing when the config is missing, malformed, or expired.
The event landing page (/event) pages/event.html → /event, page module src/event-page.js; config public/event.json (the SAME file the /play countdown reads, never a second copy of the times); live population api/play/population.js → /api/play/population, backed by the multiplayer server's public /population aggregate in multiplayer/src/index.js Live The one link the community shares before and during an event, written for someone with zero context. Hero countdown ticking off public/event.json, a single large CTA into the event world, a plain-language "what to expect" built only from what /play actually does, and the run of show rendered in the visitor's own timezone with an "Add to calendar" button that builds a real RFC 5545 .ics in the browser (no third-party calendar service, so the guest list never leaves the device). Four designed states: upcoming (days/hours/minutes/seconds), live (LIVE marker plus the real number of people standing in the world), ended (says it happened, relabels the agenda to "What happened", and still routes people into /play), and no-config (an honest "no event scheduled" with the same door). The live number is real or absent: when the multiplayer server is unreachable the panel keeps the live state and drops the count instead of inventing one. Doc: docs/api-reference.md.
/play friends, presence & verified profiles (drawer, cross-world DMs, in-world profile cards) Client: src/game/friends-panel.js (shared with /walk), mounted in src/game/coincommunities.js _openFriends()/_closeFriends(), HUD button + unread badge in src/game/coincommunities-ui.js, account-level state/polling in src/friends.js, profile card in the shared inspector src/shared/avatar-inspector.js (renderProfile). Server: signed ticket verify + socialHub registration + verified username on the Player schema in multiplayer/src/rooms/WalkRoom.js + multiplayer/src/schemas.js, ticket signer api/_lib/presence-store.js / verifier multiplayer/src/presence-token.js, hub in multiplayer/src/social-hub.js In-repo W09+W10 of the World Online program (program brief retired to git history). Press J or the HUD Friends button to open a right-docked drawer showing your account's friend graph; live online/offline presence per coin world, requests, and DM threads; the same graph and threads /walk and the standalone /friends page already share. community-net.js carries a signed presence ticket into every walk_world join and forwards the server's social push onto its own event bus, which is what makes a /play player visible to friends and able to receive a live DM. W10 makes the platform identity first-class in-world: the ticket also carries the account's username + display name (signed, so nobody can wear a handle they don't own), WalkRoom publishes the verified username on the Player schema, nameplates show the @handle, the signed-in lobby defaults to the account's display name with an @handle chip, and clicking any verified player (or I) opens their real three.ws profile card in the shared avatar inspector: bio, follower counts, follow/unfollow (/api/users/:username/follow), the right friends verb (Message → the in-world DM drawer when already friends, Add friend / Accept otherwise), their latest creations, and a link to /u/<username>. Works identically in /walk (same room, same inspector). Tests: tests/play-friends-presence.test.js, tests/play-profile-identity.test.js.
Crew HQ (crews, tags, 3D presence room) Page pages/crews.html + src/crews-page.js + src/crews.css → /crews and /crews/<TAG>, data layer api/_lib/crews-store.js, endpoints api/crews/ (index.js, [tag].js, search.js, directory.js), presence api/_lib/presence-store.js, schema api/_lib/migrations/2026-06-05-crews.sql Live The group half of the social system: a crew is a set of accounts flying one 2-6 character tag, with one owner, one crew per account, and a public headquarters. The HQ renders the roster as a room rather than a list, each member standing as their own agent's 3D avatar (resolved by standeesFor(), private models never emitted) and lit by the same Redis presence the friends drawer reads. Crew colour is an FNV-1a hash of the tag, so a crew looks like itself everywhere without stored art. Live <agent-3d> figures are capped and lazily mounted so a large crew cannot exhaust the browser's WebGL contexts. The backend shipped with W09 and had no UI at all until this page; the in-world friends drawer now links to it. Docs: docs/crews.md. Tests: tests/crews-shared.test.js, tests/crews-wiring.test.js
Agent Spotlight (community showcase) Index pages/spotlight.html + src/spotlight.js → /spotlight, entry page pages/spotlight-entry.html + src/spotlight-entry.js → /spotlight/:id, shared render + form modules src/spotlight-shared.js / src/spotlight-form.js, styles src/spotlight.css, crawler share cards api/spotlight-og.js, HTTP boundary api/spotlight/[action].js, queries + ranking api/_lib/spotlight-store.js, schema api/_lib/migrations/20260901160000_agent_showcase.sql, curated seed scripts/seed-spotlight.mjs Live The curated half of /agents: the index lists every agent ever registered, this lists the ones a person wrote up and the community voted on. An entry stores the pitch only (headline, one-liner, write-up, category, tags, demo link); the agent's name, avatar, skills, on-chain identity, conversation count and builder are read live off agent_identities on every request, so a card can never drift from the agent it points at. Ranked by (votes + 1) / (age_days + 1) ^ 1.2, computed identically in JS and in the SQL ORDER BY; the + 1 keeps a brand-new entry on the first page, and the day scale (rather than the hour scale every feed copies from Hacker News) is what stops a low-volume board's trending from collapsing into newest. One entry per agent (re-submitting edits it), one vote per account, votes counted on read rather than denormalised. Entries badged Curated were written by three.ws about someone else's public agent, say so in words on the entry page, and are replaced the moment that builder submits their own. The API lives at /api/spotlight/* because /api/showcase is the unrelated ERC-8004 directory (api/showcase.js); the tables keep the agent_showcase name they were applied under. Docs: docs/spotlight.md. Tests: tests/spotlight-ranking.test.js
Success Stories (verified results) Page pages/stories.html + src/stories.js → /stories, shared results renderer src/spotlight-verified.js (also drawn as "Verified results" on /spotlight/:id), metrics api/_lib/spotlight-metrics.js, actions stories / consent / moderate on api/spotlight/[action].js, schema api/_lib/migrations/20260930171500_agent_showcase_story_consent.sql Live Spotlight entries whose agent OWNER opted in (a checkbox on the submit form, off by default, or "Feature as a success story" on the entry page), shown only when the agent has a verified result: a coin launched (pump_agent_mints), service income (agent_revenue_events USDC net plus completed agent_hires), or creator fees (the agent earnings read model, when it is live). Curated entries never qualify without the owner's consent, and consent given by a previous owner does not carry over. Every figure is computed server-side and links to where it can be checked. Admins hide or restore any entry with POST /api/spotlight/moderate (audit-logged); a hidden entry drops out of /spotlight, /stories and the entry page. Docs: docs/spotlight.md. Tests: tests/spotlight-stories.test.js
/play Robinhood Chain worlds (every observed launch venue + The Odyssey coins, live-trade animation) Firehose worker workers/robinhood-feed/ (watches The Odyssey plus every launch venue found from mint logs, grades each deployer and the dev-sold state, normalizes to the pump-compatible event shape, serves SSE/WS/REST; venue catalog in src/venue-catalog.json). API bridge: api/robinhood/coin-trades.js (the in-world chart-screen's trade feed), api/robinhood/play-worlds.js (the /worlds lobby's Robinhood Chain tab). Client: chain-flavored biome hoodchain in src/game/world-env.js (auto-pinned in src/game/coincommunities.js isRobinhoodCoin()), trade-feed endpoint routing in src/game/chart-screen.js, lobby tab + EVM-address support in src/worlds-lobby.js (routes Robinhood coins to /play, unchanged pump.fun coins stay on /temporary) In-repo Every Robinhood Chain memecoin (chain 4663) gets the same treatment pump.fun coins already have: a deterministic 3D world seeded by its contract address, in a distinct dark ticker-tape palette, with real launchpad/Uniswap-v3 trades rippling the space live via MarketReactor. Multiplayer (walk_world, filtered by coin+tier) needed zero code changes, it already keys rooms by an opaque coin id string. isValidToken() in api/_lib/coin-communities.js was widened to accept EVM addresses (it previously 400'd every EVM-chain world's Town chat, even though the CHAINS list already declared ethereum/base/bsc support). Tests: workers/robinhood-feed/tests/normalize.test.js (against real captured on-chain logs).
Sealed wallet gift drops (send/claim) Client: src/pages/sealed-drops.js — create + "My drops" sections mounted into public/vanity-wallet.html (#drop-create/#drop-mine, below the vanity grinder — vanity pattern fields are shared), claim flow on its own page pages/drop.html → /drop/:id (24-hex-char id, routed in vite.config.js dev middleware + vercel.json). Crypto: src/solana/vanity/sealed-envelope.js (ECIES seal/open, X25519 keygen — all client-side, three.ws never sees a plaintext key), src/solana/vanity/drop-protocol.js (claim-token derivation). Server: api/vanity/drops.js (create/claim/reveal/reclaim, on-chain funding), OG card api/og/sealed-drop.js In-repo Fund a fresh wallet — optionally vanity-ground with the same prefix/suffix grinder above — wrap it in a sealed link, and send it. Two seal modes: a bearer link (the claim key rides in the URL fragment, anyone with the full link claims once) or sealed to a recipient's X25519 key (only they can ever open it, even with the link). The create fee settles via x402; the gift amount funds on-chain into a fresh wallet server-side. Claiming decrypts entirely in the browser and offers the recovered seed phrase/secret key for import — the server only ever sees the sealed ciphertext. "My drops" (browser-local, by a random sender tag) lists what you've sent so expired-unclaimed gifts can be reclaimed.
Premium vanity inventory (sell pre-ground addresses) public/vanity/premium/ → /vanity/premium, batch grinder workers/vanity-grinder/, store api/_lib/vanity-inventory-store.js, sell api/x402/vanity-premium.js, replenish api/cron/vanity-inventory-replenish.js In-repo · GCP spot CPU Long (4–5+ char) brandable Solana addresses ground ahead of time on cheap spot CPU, sealed at rest (AES-256-GCM or GCP-KMS envelope, api/_lib/vanity-vault.js), and sold from stock via x402 — priced by rarity ($1–$50) on vanity-premium, or by fixed 4–5 char tiers ($2.50/$10) directly through /api/x402/vanity (instant delivery, source:"inventory") and the pump-launch vanity upsell — delivered exactly once, ciphertext destroyed on delivery. An hourly cron watches stock and fires a fresh grind batch (Cloud Run Job) when low. Free vanity_premium MCP browse tool. Runbook: docs/ops/gcp-credits.md
Embed examples examples/ In-repo embed-test.html, web-component.html, two-agents.html, minimal.html, agent-native-3d/ (below). Also: skills/ (six installable skill bundles), three-concierge/ (Trinity, reference agent for manifest spec agent-manifest/0.2), monicas-apartment/ (walkable first-person Three.js scene demo, added 2026-07-17), agenc-task-roundtrip/ (end-to-end AgenC task flow on Solana devnet), metamask-agent-wallet/ (single-page demo giving an agent a server-side MetaMask wallet), pump-fun-agent/ (example manifest composing the four production pump.fun skills), paid-mcp-server/ (an MCP server whose tools charge per call in USDC on Solana over x402: one free orientation tool, one paid glTF/GLB inspector, 15 tests, added 2026-07-30), google-adk/ (a Google Agent Development Kit agent calling the free three.ws MCP server through MCPToolset, added 2026-10-13)
Examples satellite repo (public developer front door) Exporter scripts/export-satellites.mjs (npm run export:satellites), runbook docs/ops/examples-repo-export.md, curated source examples/ + the published @three-ws/* SDKs Built and gated in-repo; publishing is owner-gated (the three-ws GitHub org does not exist yet) Assembles the public three-ws/examples repo from this monorepo as a strictly ONE-WAY export: the monorepo is the only source of truth, the satellite history is disposable, and it is never pulled, fetched, or merged from (same rule as the retired 3D-Agent mirror). No CI is involved (GitHub Actions are unavailable here), so the export runs locally from the push routine. Every relative reference is resolved against its real location and routed by where it lands rather than regex-swept: to the shipped file, to another exported unit (so an agent manifest's skill uri still resolves), to the published package on jsDelivr, to the live docs page, or to a monorepo permalink. A four-stage smoke gate then aborts the export on any failure, because a broken public example is anti-marketing: structure (no reference escapes or dangles, no file: dep survives), registry (every pinned @three-ws/* version exists on npm), install (npm install plus each example's own check command), and links (every https://three.ws URL reachable). On success it stamps a single-parent git history into the staging tree and prints the org-creation and push commands; it never touches a remote. Examples referencing a crypto project other than $THREE are held out of the manifest under the CLAUDE.md commit gate (pump-fun-agent, three-concierge, agenc-task-roundtrip).
Product-led growth satellites Canonical source satellites/, exporter scripts/export-growth-satellites.mjs (npm run export:growth-satellites), runbook docs/ops/growth-satellite-export.md Built and gated in-repo; destination repositories require the nirholas owner identity Three focused acquisition surfaces whose first experience is deliberately smaller than this monorepo: satellites/agent-starter/ is a responsive, Codespaces-ready live <agent-3d> page with real motion, speech, a keyless create command, a ten-minute learning path, and a structural check; satellites/glb-quality-gate/ is a Node 24 GitHub Action that discovers changed GLBs through the pull-request API, reads base/head bytes without a checkout, runs the published @three-ws/glb-diff engine, upserts a PR report, writes the workflow summary, and gates at a configurable severity. satellites/oracle-desk/ is a self-custody Node trading desk over the public Oracle API: radar (PumpPortal launches plus the Oracle SSE stream), four research seats with bars over each verdict, a risk desk, execution priced by the official pump.fun curve and PumpSwap SDKs with the fleet's exit ladder and round-trip firewall, an audit loop that moves a seat's binding bar on each graded trade, a head of desk that fires the worst seat and refits it from its own trades, and a treasury freeze and sweep; paper by default, live behind an explicit acknowledgement, dashboard in the Oracle theme, 38 node:test tests. The exporter installs locked dependencies, runs real tests, builds the committed Action bundle, copies Apache legal files, and stamps one clean history per destination. The monorepo remains the only source of truth.
Agent-native 3D + embeddable distribution MCP tool api/_mcp/tools/agents.js (attach_avatar_to_agent); shared oEmbed provider api/agent-oembed.js → /api/oembed + builder api/_lib/embed.js (forgeEmbedTarget, shared by get_embed_code in api/_mcp/tools/embed.js); Forge share page oEmbed discovery api/forge-share.js → /forge/share/:id; distribution snippet builders src/forge-embed-snippets.js + panel src/forge-embed-panel.js; autonomous demo examples/agent-native-3d/ In-repo Closes the loop: create → own → discover/remix → use everywhere. attach_avatar_to_agent gives a registered agent identity a persistent body (chains into register_agent for on-chain identity + anchor_provenance for a signed authenticity credential). Any Forge creation now unfurls via real oEmbed (paste /forge/share/:id into Notion/Discord/Slack) with the same type:rich iframe payload get_embed_code returns via MCP. The Forge "Embed this model" panel hands out five real distribution flavours from one GLB — iframe, <model-viewer>, <agent-3d>, a @three-ws/page-agent talking guide, and a @three-ws/walk companion — all built from one shared, pure snippet module so every surface stays byte-identical. examples/agent-native-3d/run.mjs drives the full agent-native chain live against /api/mcp-studio (mesh_forge → rig_mesh → create_agent_persona → persona_say → get_agent_persona → every distribution snippet) with zero mocks and a documented, logged fallback if the shared free-tier generation lane is rate-limited at run time. Spec: specs/EMBED_SPEC.md. Docs: docs/mcp.md#attach_avatar_to_agent. Roadmap prompt 10 (closes the roadmap campaign).
Animation pipeline public/animations/ + scripts/build-animations.mjs In-repo Mixamo source FBX + GLB retargeting pipeline · see docs/3d-asset-pipeline.md
Procedural animation (runtime IK layers) src/procedural/ — analytic two-bone IK two-bone-ik.js, gaze look-at.js, terrain foot planting foot-plant.js, drift-free re-application pose-baseline.js Live Post-mixer layers that do what no baked clip can: the chest/neck/head chain turns toward a world point, and each foot lands on its own patch of uneven ground. Rig-agnostic via canonicalNodeMapFromObject; an unsupported rig reports enabled === false and no-ops. Wired into the corner companion (walk-sdk/src/companion.js _updateGaze), the walkaround world (src/walk.js rebuildFootPlant), and agent avatars (src/agent-avatar.js _applyLookTarget — which is what finally makes setLookTarget() and the LOOK_AT action move the rig). Ambient idle motion (breathing/blink/saccade/weight-shift) stays in src/idle-animation.js. Docs: docs/procedural-animation.md. Tests: tests/procedural-anim.test.js, tests/agent-avatar-look-target.test.js
Self-hosted 3D GPU fleet (the engines behind the Forge) workers/model-trellis2/ (TRELLIS.2, MIT, the default image-to-3D lane trellis2: PBR GLB with alpha, resolution 512/1024/1536; built and tested, deploy owner-gated), workers/model-pixal3d/ (TencentARC Pixal3D, MIT, on TRELLIS.2's backbone: the pixal3d fidelity lane labeled "Match my photo", 1 to 4 pixel-aligned input photos with optional view_labels and one-photo fill_other_sides view synthesis via MV-Adapter (Apache-2.0); built and tested, deploy owner-gated), territory router api/_lib/forge-territory.js (EU, UK and KR never reach a Tencent-model lane; unknown country fails closed), workers/model-trellis/, workers/model-hunyuan3d/ (2.0 + 2.1 PBR + 2.1 RTX), workers/model-triposg/, workers/modly/ (Modly v0.4.3 running its TripoSG and Hunyuan3D 2 Mini Turbo extensions as the untextured Forge lanes modly and modly_hunyuan, behind MODEL_MODLY_URL; weights staged, built and tested, deploy owner-gated), workers/model-triposr/, workers/model-text2motion/, workers/rig/ (auto-rigging, deployed as model-rig), workers/rig-nonhuman/ (UniRig + SkinTokens, MIT, the non-humanoid rigging fallback model-rig reaches for when its own mesh_classify.py heuristic rules out a Mixamo-shaped humanoid, behind RIG_NONHUMAN_URL; built and tested, deploy owner-gated), workers/model-anigen/ (VAST-AI-Research AniGen, MIT, the rig-on-generation Forge lane anigen labeled "Rig on generate": predicts mesh, joint skeleton and skin weights together from a single reference image, so the GLB it returns needs no separate rerig call; opt-in only, never a default or failover target; built and tested, deploy owner-gated), workers/model-partcrafter/ (PartCrafter, MIT, LICENSE read 2026-10-11, the partcrafter Forge lane labeled "Editable parts": decodes a reference photo straight into N individually named part meshes in one diffusion-transformer pass; built and tested, deploy owner-gated), workers/model-holopart/ (HoloPart, MIT, LICENSE read 2026-10-11, the "Complete hidden parts" lane behind /api/forge-holopart: takes an already part-segmented mesh (from workers/segment or model-partcrafter) and fills in the occluded geometry of every part, closing each into a standalone shape; built and tested, deploy owner-gated), workers/model-triposplat/ (VAST-AI-Research TripoSplat, MIT, LICENSE read 2026-10-12: the image-to-Gaussian-splat lane behind POST /api/forge-splat, output opens in the Splat Viewer; behind MODEL_TRIPOSPLAT_URL; built and tested, deploy owner-gated), workers/model-sam3d-objects/ (Meta SAM 3D Objects, SAM License: rebuilds the objects in one photo as a single laid-out scene GLB with named nodes object_01, object_02, ..., behind POST /api/forge-scene-objects (api/forge-scene-objects.js) and the AR Studio "From a photo" tab; needs a 32 GB+ GPU and gated weights, so it answers 503 backend_unconfigured until MODEL_SAM3D_URL is set; built and tested, weights and deploy owner-gated), workers/avatar-reconstruction/, CPU stages workers/rembg/ · workers/remesh/ · workers/segment/ · workers/stylize/, talking-avatar video workers/longcat/ (LongCat-Video-Avatar-1.5, gates the /create/video lane via LONGCAT_WORKER_URL; the one fleet member that is not a Cloud Run service, because its ~45 GB resident weight set needs an 80 GB GPU, so it is built and tested but undeployed), streaming video→3D workers/model-video2scene/, selfie-pipeline CPU orchestrator workers/avatar-pipeline-controller/ Live · Cloud Run GPU (us-central1, plus us-east4 where trellis/hunyuan/triposr hold standbys and model-text2motion runs as its production lane) Every generation engine the Forge dispatches to, each with its own cloudbuild.yaml. The L4 quota is per region and both us-central1 and us-east4 are granted 3, so a warm pin in one region only starves lanes in that same region (increase to 16 filed 2026-07-16, still reconciling); the Hunyuan3D-2.1 PBR realism lane also ships an RTX PRO 6000 build (model-hunyuan3d-21-rtx, quota granted 1000) as the warm primary. model-text2motion (MDM default + MoMask, both MIT, selectable per request via `model: "mdm"
Self-hosted Granite Guardian (governance lane behind watsonx) workers/granite-guardian/ (Cloud Run granite-guardian, europe-west4, vLLM on one L4), client lane in api/_lib/granite-guardian.js Live · Cloud Run GPU (europe-west4) IBM's open-weight ibm-granite/granite-guardian-3.3-8b served by the stock vLLM OpenAI image, so /api/guardian/assess, the identity integrity check, and the Granite Twin/Oracle/Attest/IRL screens return real Granite Guardian verdicts on a deployment with no IBM Cloud account. watsonx.ai stays the lead lane when configured; every verdict names the model and provider that produced it. Placed in europe-west4 because that region's L4 grant is otherwise unused, so its warm pin never starves the 3D lanes. Tests: tests/api-guardian.test.js, tests/api/identity-integrity.test.js
Reconstruct completion backstop (abandoned selfie jobs) api/cron/reconstruct-sweep.js, every 5 min via vercel.json crons → Cloud Scheduler Live 2026-07-25 A reconstruct job used to be advanced only by the user's browser: /create/selfie polls regenerate-status, and each poll runs the finalize stages. Close the tab and the worker still finished the GLB and stored it durably, but nothing ever collected it — 26 jobs were stranded that way, oldest from 2026-05-31, invisible to db-retention (which prunes only terminal rows). This sweep is the server-side driver: it picks up reconstruct jobs quiet >3 min and runs the same shared stages in reconstruct-finalize.js, so an abandoned job still lands in the user's library. 30-day rescue window (the worker's GCS blobs + Firestore job state are durable, so a weeks-old job is still deliverable); past that, or when a job's provider is no longer pollable from platform credentials, rows fail out with an honest reason so the open set can't grow unbounded. BYOK (meshy/tripo) jobs stay browser-driven — a cron has no user context to resolve their keys. Sibling of auto-rig-sweep.js, which plays the same role for the rerig lane. Docs: docs/avatar-reconstruction.md
Avatar fidelity evaluation (selfie → avatar, scored) workers/avatar-reconstruction/eval/ In-repo · gates every reconstruction change Identity Shape Error (ISE) — does the reconstructed avatar have this person's face shape? Texture-blind, pose- and scale-invariant, dimensionless: MediaPipe's 468 landmarks and the avatar's corresponding head vertices are both Umeyama-aligned onto the neutral canonical face over a stable identity subset (no eyes/lips, so a smile is not scored as identity), then compared. A pipeline cannot score better by resizing or tilting the head — only by matching shape, a property pinned in eval/test_identity_eval.py alongside monotonicity. run_eval.py scores a whole reference set against a live worker and diffs two revisions, surfacing per-face regressions a mean would hide; tune_morph.py sweeps the morph parameters against ISE offline; robustness.py measures the opposing axis (does a blurred / turned / occluded / dim / low-res photo of the same person still yield the same head?), and the shipped max_displacement_frac is the knee of those two curves. The 40-face reference set is synthesised by make_refs.py over a deterministic grid of the platform's diversity matrix — no real biometrics, no licence terms, rebuildable by any agent — gitignored and mirrored to gs://three-ws-avatar-reconstructions/eval-refs/. Docs: eval/README.md, program plan docs/avatar-fidelity-program.md
Avatar Composer (modular studio generation) api/_lib/avatar-composer/ In-repo · wired into the studio seed lane Assembles a rigged, ARKit-expression-ready GLB by mixing skinned parts (hair / top / bottom / footwear / glasses) across the RPM base bodies onto one shared 67-joint skeleton, then recolors each part and scales the rig — the Ready-Player-Me / Avaturn "one skeleton, many parts" architecture in pure JS on @gltf-transform, no GPU or external service. Replaces the recolor-one-of-five-bodies studio lane so two draws almost never look alike. Borrowed parts keep their own inverse binds but remap onto the identity skeleton; mixing is restricted to a base's rest-pose group so parts always fit. Consumed by api/cron/avaturn-seed-cron.js (legacy studio-avatar.js recolor is the fallback) and the one-click api/avatars/surprise.js endpoint (instant avatar, previewed in public/gallery/surprise.js). Docs: api/_lib/avatar-composer/README.md. Tests: tests/avatar-composer.test.js
Auto-rigging worker (Mixamo skeleton + ARKit-52 blendshapes) workers/rig/ Live · Cloud Run GPU model-rig (us-central1) Make-It-Animatable engine (MIT) predicts the 52-bone Mixamo skeleton + weights; workers/rig/rig_glb.py grafts them into the original GLB (textures untouched); ICT-FaceKit (MIT) ARKit-52 expression transfer for emotions/lipsync. Serves every rig call behind GCP_UNIRIG_URL (env name predates the engine swap); it replaced the retired unirig service, whose worker directory was deleted 2026-08-11. Canonicalization proof: rig worker skeleton cases in tests/glb-canonicalize.test.js
Additive wardrobe (dress any avatar from the catalog) Runtime src/avatar-garment.js + taxonomy src/garment-taxonomy.js + catalog src/garment-catalog.js + closet UI src/garment-closet.js (in the /avatar-edit Wardrobe tab), bake pass api/_lib/bake-garments.js, contract specs/GARMENT_MANIFEST.md Live in the avatar editor · catalog seeding in progress The wardrobe's additive half: catalog garments (top/bottom/footwear/outerwear/hair/headwear/glasses/accessory) are skinned onto ANY loaded humanoid at wear-time — skin indices rewritten to the avatar's bone order via glb-canonicalize canonical names, garment inverse-binds kept where skeletons correspond (divergent rest poses reconcile), body culled under declared occludes regions so skin never clips through cloth, ≥60% weight-coverage gate refuses unbindable pieces. Saved outfits persist in appearance.garments and the server bake re-runs the same rebind on @gltf-transform so exports/embeds are dressed. Catalog: public GCS three-ws-garments bucket, sha256-verified per download, licence-gated (CC0/CC-BY/MIT/Apache/BSD only). Docs: docs/avatar-wardrobe.md. Tests: tests/avatar-garment.test.js, tests/garment-catalog.test.js, tests/bake-garments.test.js
Garment Forge (text prompt → catalog garment) workers/garment-forge/, public API api/garment-forge.js → POST/GET /api/garment-forge, MCP tools api/_mcp/tools/garments.js (generate_garment, garment_status, list_garment_catalog), verify harness scripts/verify-garment.mjs, contract specs/GARMENT_MANIFEST.md Live · Cloud Run CPU (garment-forge, us-central1) Generation lane that feeds the additive wardrobe's catalog: prompt → ghost-mannequin reference photo (Vertex image lane) → PBR mesh on the deployed GPU fleet (model-hunyuan3d-21-rtx → model-hunyuan3d-21 → model-trellis) → composed onto the canonical reference body (parametric-base) → rigged by model-rig with full-body context → reference body stripped back out (pure glTF repack), bones canonicalized, occludes derived from REGION_BONES weight mass, all 6 manifest rules validated in-process (including the ≥60% bind-coverage gate) → garment.glb + manifest.json + thumb.webp published immutably to gs://three-ws-garments/garments/<slot>/<id>/v<n>/ and appended to the live catalog. Build gate: workers/garment-forge/test_garment_glb.py (33 checks, runs inside docker build). Docs: workers/garment-forge/README.md
Parametric avatar base (change-everything sliders) Baker scripts/build-parametric-base.mjs → public/avatars/parametric-base.glb, CC0 source data avatar-sources/anny/, studio wiring src/avatar-studio.js (?base=parametric) + src/avatar-sculpt.js Live in Avatar Studio (Base switcher) One canonical humanoid whose identity is 306 baked morph-target sliders (nose/ears/mouth/eyes/brows/cheeks/jaw/head shape/neck plus gender, ethnicity, muscle, weight, age, height, torso, hips, midsection, arms and legs), built from the CC0 MakeHuman/MPFB2 body vendored via naver/anny. 52-bone mixamorig:* skeleton, so the full clip library retargets onto every slider combination. Sparse-accessor morphs keep the GLB at 6.5 MB; the baker enforces a 96 MB morph-texture VRAM ceiling because three.js allocates one dense texture layer per target. On top of the sliders: skeleton-space proportions (src/avatar-proportions.js, baked server-side by api/_lib/bake-proportions.js) and a free-sculpt brush (src/avatar-sculpt-brush.js, wire format src/avatar-sculpt-doc.js, baked by api/_lib/bake-sculpt.js) for the shapes no catalogue has. Contract: specs/PARAMETRIC_AVATAR.md. Tests: tests/parametric-base.test.js, tests/bake-proportions.test.js, tests/avatar-sculpt-brush.test.js
VRoid Hub import (partner-licensed avatar import) Picker page pages/import-vroid.html → /import/vroid, OAuth connect api/auth/vroid/[action].js (connect/callback/status/disconnect, PKCE, config in api/_lib/vroid/config.js, API client api/_lib/vroid/client.js, encrypted token storage api/_lib/vroid/token-store.js + token-crypto.js), license evaluator api/_lib/vroid/license.js, listing endpoint api/vroid/models.js → GET /api/vroid/models, import endpoint api/vroid/import.js → POST /api/vroid/import Built 2026-10-13, OAuth app registration owner-gated (see prompts/finish/_context/production-100-OWNER-ACTIONS.md) Pulls a VRoid Hub character the user owns, hearted, or was granted into three.ws as a real avatar: the picker lists both sets with per-model license badges (public agent, export, modify, monetize) computed from the live CharacterModelLicenseSerializer the Hub API returns, so an action only appears when the creator actually permitted it. Import mints a Hub download license, resolves its one-time S3 redirect, runs the file through the same GLB-header check and glb-canonicalize bone pass every other avatar upload uses, and lands the user straight in the avatar editor (/avatars/{id}/edit) with idle/walk already retargeted. License fields and the required creator credit line persist on the avatar's source_meta so every later surface (agent creation, export, marketplace) can re-check them without another Hub round trip. Tests: tests/vroid-license.test.js
Animation gallery pages/animations.html + src/animations-gallery.js Live at /animations 2,100+ clips with poster thumbnails (scripts/build-animation-thumbnails.mjs), derived categories (src/animation-categories.js), shared live-preview engine (src/animations-live-preview.js) · see docs/animations.md
Gesture vocabulary pages/gestures.html + src/gestures-page.js, slots src/runtime/animation-slots.js Live at /gestures The 19 gesture slots an agent plays, each previewed on a live avatar, with the skill hints that trigger it and a builder that saves a per-slot clip override straight onto an agent (meta.edits.animations). Hint table is generated from the shipped skill definitions by scripts/build-agent-hints.mjs, so attribution cannot go stale · see docs/animations.md
Acoustic gesture control pages/sonar.html + src/sonar-page.js, sensor src/sonar/doppler.js, detectors src/sonar/gestures.js, shared input chain src/sonar/controller.js, embed surface <agent-3d sonar> (src/element.js startSonar()) Live at /sonar Hand control for a 3D agent with no camera: the speakers emit an inaudible carrier and the microphone reads the Doppler shift of a hand off it, so a sweep steps through the gesture vocabulary, a push dollies the camera and a held lift turns it. The sensor picks a carrier by measuring every candidate against the machine's own hardware, because the frequency a laptop's speakers can actually project differs per model and an unprojectable one reads exactly like an empty room. Both modules are DOM-free and 3D-free, so any surface can consume them. Ported from Sonar (MIT), itself an implementation of SoundWave (CHI 2012) One controller serves both surfaces, so the mode arbitration and reverse handling exist once; the embed loads none of the sensing until a page calls startSonar(), and every gesture fires a cancelable sonar-gesture event a host page can take over · see docs/sonar.md, docs/web-component.md. Tests: tests/sonar-gestures.test.js, tests/sonar-controller.test.js
GPU particle morphing pages/dissolve.html + src/dissolve/ (page.js controller, engine.js GPGPU sim, sample-core.js surface sampling, shape.js GLB to colour cloud, audio.js, recorder.js, shelf.js) Live at /dissolve Dissolves any GLB into up to 1M GPU particles, morphs A to B over a shared Morton-ordered stage, bends them with black hole, vortex, shockwave and collapse forces, reacts to the mic, records clips and shares pairs by link. See docs/dissolve.md. Tests: tests/dissolve-core.test.js, tests/dissolve-shelf.test.js
Choreographer pages/choreograph.html + src/choreograph-page.js, engine src/runtime/choreography.js Live at /choreograph Timeline for composing gesture slots into named, timed routines, previewed on the shared live-preview engine with crossfades and a scrubbable playhead. One dependency-free module defines the routine format, the URL wire format and the timing engine; the studio, PUT /api/agents/:id/animations (stored at meta.choreographies), the public manifest and AgentAvatar.playChoreography all import it, and <agent-3d>.playRoutine('welcome') performs one from any embed. Also published as @three-ws/avatar/runtime/choreography.js · see docs/choreography.md
Character Library pages/character-library.html + src/character-library.js (search/sort/link logic in src/shared/character-library-view.js, covered by tests/character-library-view.test.js) → /character-library, API api/avatars/library.js Live at /character-library Professionally rigged Mixamo characters (skinned GLB + thumbnails on R2, avatars/mixamo/), each drives the full animation library. The live count comes from the R2 manifest and renders in the hero; no page copy hard-codes it. Pipeline: scripts/fetch-mixamo-avatars.mjs → scripts/convert-mixamo-avatars.mjs → scripts/fetch-mixamo-avatar-thumbnails.mjs → scripts/build-mixamo-avatar-library.mjs publishes avatars/library/manifest.json. Cards deep-link into the 3D viewer (/app#model=), Widget Studio (/studio?model=), and Animation Studio (/pose?src=). Mirrors the animation-library R2-manifest pattern (no DB). See public/avatars/mixamo/README.md
Object Library pages/objects.html + src/objects-library.js → /objects, API api/objects/library.js Live at /objects Hundreds of CC0 (public-domain) 3D props from Poly Haven (packed to GLB on R2, objects/polyhaven/). Pipeline: scripts/fetch-polyhaven-objects.mjs (glTF→GLB via @gltf-transform) → scripts/render-glb-thumbnails.mjs → scripts/build-object-library.mjs publishes objects/library/manifest.json. Same R2-manifest pattern as the Character/animation libraries (no DB). Cards preview in the 3D viewer (/app#model=), place into AR Studio (/ar/studio?src=), and download the GLB directly (CC0). AR Studio's tray also has an Objects tab over the same manifest. The grid renders 48 cards at a time (a Load more button, plus an IntersectionObserver that pulls the next chunk as you approach it) and each card is a still thumbnail until you dwell on it, at which point that one card upgrades to a live auto-rotating <model-viewer>; at most six stay mounted. The manifest read falls back to the bucket's public CDN domain when the signed S3 read fails (getPublicObjectBuffer in api/_lib/r2.js), so a bad storage credential can no longer empty a library of public CC0 bytes.
NVIDIA SimReady assets (CC BY 4.0, in the object library) Ingest scripts/ingest-simready.py, converter scripts/simready-to-glb.py, triangle budget scripts/slim-glb.mjs, R2 upload scripts/publish-simready.mjs, catalog public/objects/simready/catalog.json Converted locally; R2 upload and manifest publish pending owner approval Every asset of Hugging Face nvidia/simready-assets (industrial, hospital, residential, lighting, OEM) converted from OpenUSD to a plain-glTF GLB (world-space bake, UsdPreviewSurface to glTF PBR, 1024px textures, 80k-triangle budget) and joined into the object library and /api/catalog with license: CC-BY-4.0 and an attribution credit the /objects cards display. Docs: docs/simready-assets.md. Tests: tests/api/mcp-asset-catalog.test.js
Data Desk pages/data-desk.html + src/data-desk.js → /data-desk, API api/data-desk.js → /api/data-desk, writer api/_lib/x402/fresh-workers/jobs.js Live at /data-desk Live market data BOUGHT by the fresh-wallet workers with real USDC over x402: the newest purchase of each of 18 datasets (global snapshot, trending, gas, DeFi TVL, stablecoins, news pulse, fees, DEX volumes, mood, hacks, yields, DeFi radar, chains, crypto intel, market pulse, heatmap, $THREE intel, coin markets), each rendered with a slug-specific layout and its receipt (fresh wallet, price, Solscan link), a ledger of recent purchases, and the lane's 24 h numbers (wallets closed, USDC recirculated, SOL burned in fees, rent recycled). Honest feed: no synthetic rows; before the first purchase the page shows its designed empty state. Auto-refreshes every minute, / focuses the filter.
Agent-Forged Gallery pages/forged.html + src/forged-gallery.js → /forged, API api/forged.js, writer api/_lib/x402/pipelines/forge-content.js Live at /forged 3D props BOUGHT by the autonomous x402 agents with real USDC: the hourly forge-content pipeline pays /api/x402/forge (draft tier), the generated GLB lands in forge_autonomous_props with payment provenance (payer wallet, price, Solana settlement signature), and /forged renders each prop with its on-chain receipt linked to Solscan. Honest feed: no synthetic entries; before the first paid generation the page shows its designed empty state. Category chips built from the eight families in api/_lib/x402/pipelines/forge-catalog.js (club-decor, ar-object, diorama-set, avatar-item, vehicle, container, furniture, terrain), prompt search, newest/priciest/most-novel sorts.
Motion Swap (avatar body-swap in video) pages/motion-swap.html → /motion-swap + src/motion-swap.js, API api/motion-swap.js, worker workers/model-video2motion/ Live Upload a video of one person, get it back with a 3D avatar performing their motion. The worker (CPU Cloud Run, MediaPipe pose + hands + multiclass person segmentation, all Apache-2.0) tracks 33 body world landmarks plus 21 per hand each frame, solves them onto the canonical Wolf3D skeleton, body and all 30 finger bones, with an in-house bend-plane IK solver (pose_solver.py, pure NumPy, unit-tested), and emits a standard AnimationClip.toJSON() + person-mask video + per-frame screen anchors. The browser composites in one WebGL scene: footage on a shader quad with the subject pixelated under the mask, avatar retargeted via src/animation-retarget.js and pinned to the subject's anchor each frame, MediaRecorder export with original audio. Provider mode video2motion (GCP_VIDEO2MOTION_URL) in api/_providers/gcp.js. Docs: docs/motion-swap.md. Tests: test_pose_solver.py (solver) and test_service.py (HTTP contract, ffmpeg normalize/mask encode, SSRF guard, live MediaPipe pass).
Video to Motion (video → downloadable animation file) pages/video-to-motion.html → /video-to-motion + src/video-to-motion.js, reuses API api/motion-swap.js and worker workers/model-video2motion/ for capture, export via api/avatar/presign-glb.js + api/forge-remesh.js (FBX) Live For creators who want the animation file itself rather than a composited video: upload a video, preview the captured motion on a stock avatar or any rigged GLB you drop in or paste a URL for, trim the clip's in/out points, and download it as a GLB (clip retargeted onto the previewed avatar via src/animation-retarget.js and baked with GLTFExporter), a BVH (the platform's own canonical-skeleton proportions, written by src/animation-bvh-export.js, the standard shape for re-retargeting in a DCC tool), and an FBX (server-side Blender conversion that preserves the rig, via /api/forge-remesh's operation:"convert"; the exported GLB is hosted anonymously through /api/avatar/presign-glb first so the worker's SSRF-guarded mesh_url fetch can reach it). Signed-in users can save the clip straight to an agent's animation library (PUT /api/agents/:id/animations). Cross-linked from /motion-swap, /animations, and /mocap-studio. Docs: docs/video-to-motion.md. Tests: tests/animation-bvh-export.test.js (BVH writer, round-tripped through three.js's own BVHLoader) and tests/e2e/video-to-motion.spec.js (empty/processing/ready/failed/limit states at 320/768/1440px, a non-Mixamo Daz/Genesis rig retargeting in the browser, and the real exported GLB/BVH bytes).
Smart home (/smart-home) Page pages/smart-home.html → /smart-home and /smart-home/:id + src/home/ (connect, manage, scene-model, scene-render, scene-fallback, satellite, satellite-link, pcm-player, plan, api). Store api/_lib/home/store.js, runtime + backpressure runtime.js + admission.js, gate + tools tools.js + confirm.js, roster members.js, privacy privacy.js, plans + quotas entitlements.js + usage.js, SSRF pin api/_lib/home-url-guard.js. HTTP api/home/ (index, [id], [id]/call, [id]/activate, [id]/stream, [id]/grants, [id]/members, [id]/confirm, invites/[token], pair, pair/redeem, privacy, plan). Client packages/home-bridge/, MCP server packages/home-mcp/, hosted MCP tools api/_mcp/tools/home.js. Dial-out for LAN-only houses services/home-relay/ + home-assistant-integration/ (HACS). Voice services/home-satellite/ (Wyoming). Harness scripts/home-test-instance.mjs, unroutable-LAN relay rig scripts/home-relay-live.mjs + scripts/home-relay-e2e.mjs + scripts/home-relay-gate-proof.mjs, load fleet + envelope + chaos scripts/home-fleet.mjs / scripts/home-load.mjs / scripts/home-chaos.mjs (npm run home:fleet, home:load, home:chaos). Migrations api/_lib/migrations/*_home_*.sql Live The agent past the screen and into the building. Zero device code, ever: Home Assistant owns Zigbee, Z-Wave, Matter, Thread, BLE and 1,500 integrations, and three.ws is the layer in between: a connection record with the token encrypted at rest, a pooled per-home WebSocket, a room graph the 3D scene renders live, intent resolved to the household's own scenes, and one gate in front of everything. The gate is the product decision: reads are free, moves toward safety (lock, close, arm) run immediately and never prompt, and moves that OPEN the house (unlock, open a door/gate/garage, disarm) never run from a model call at all. They mint a pending confirmation a signed-in person redeems at POST /api/home/:id/confirm, which refuses every bearer principal including one holding home:act. It exists because Home Assistant's own intent__HassTurnOff is documented as performing an unlock on a lock, verified live. Entity and area names are untrusted input travelling in structuredContent, never interpolated into prose. Three reachability answers, all shipped: a remote https URL, a browser or MCP server inside the network, and the HACS integration that dials out so no Home Assistant credential ever leaves the house. Docs: docs/smart-home.md, docs/tutorials/connect-your-home.md, docs/home-households.md, docs/home-privacy.md, docs/home-plans.md, docs/ops/home-operations.md (SLOs, the alerts, the measured scale envelope, the backpressure ladder, the seven chaos scenarios and the Cloud Run sizing). Evidence: tasks/home/. Tests: tests/home-*.test.js, tests/e2e/home-connect.spec.js, packages/home-bridge/tests/, packages/home-mcp/tests/
Sign Language (feature home) pages/sign-language.html → /sign-language + src/sign-language-page.js Live The front door for signing avatars: a live avatar signing on arrival (PoseStage + src/sign-speech.js SignSpeaker, portrait-framed), an input that signs or spells anything you type (reporting which words were which), a playable vocabulary of every word with a real sign, and an embedded webcam sign-recognition demo. Controls for signing speed, left- vs right-handed signing, and which avatar signs: src/sign-avatars.js owns the shared rig list, the one preference block every signing surface reads, and the Avatar pill group whose third pill opens the avatar gallery, so any avatar you own (or any public one) signs with the same vocabulary; a rig with no usable skeleton is rejected with a named message and the working rig is remounted. Verified in a real browser by npm run verify:sign-avatar (scripts/verify-sign-avatar.mjs). Engines: src/sign-rig.js (skeleton measured from the bind pose → forward kinematics, two-bone arm IK, and hand geometry, so a sign is authored as a place in signing space or as CONTACT, "fingertips on the palm", never as joint angles), src/sign-handshapes.js (A, Z, 0, 9, and the named shapes), src/sign-clip.js (resting signer, phase poser, non-manual face markers, eased timeline → clip JSON), src/sign-dictionary.js (the lexical vocabulary, one- and two-handed), src/fingerspelling.js (the manual alphabet), src/sign-speech.js (text→one signing clip: hands rise once and lower once, signs where they exist and spelling for the rest), src/sign-input.js (browser Holistic landmarks → text). Face markers ride a morph-target lane through src/animation-retarget.js, re-pointed at whichever meshes the target avatar owns. Tools: npm run sign:sheet (contact sheet of every sign, scripts/sign-contact-sheet.mjs), npm run build:sign-goldens (positional snapshot). Docs: docs/sign-language.md. Tests: tests/{sign-rig,sign-dictionary,sign-linguistics,sign-goldens,fingerspelling,sign-speech,sign-input}.test.js.
ASL alphabet (learn + practice) pages/asl-alphabet.html → /asl-alphabet + src/asl-alphabet-page.js, letter notes src/asl-alphabet-data.js Live The manual alphabet as a reference you can turn around: every letter A-Z and digit 0-9 formed on a live portrait-framed rig (src/fingerspelling.js via PoseStage), each with a written handshape description and the letters it is confused with (F/9, M/N, K/V, G/Q). A single letter holds its final frame (playOnce({ settleTo: null })) so it can be orbited; a word settles like a signer finishing. Typing any letter key signs it. Spelling a word lights each key in step with the hand, driven by the marks schedule the clip builder emits rather than a parallel timer. A practice drill spells a random letter or word and checks what you type, keeping a streak in localStorage. Shares speed / dominant-hand / avatar preferences with /sign-language under one key via src/sign-avatars.js, including a custom avatar picked from the gallery on either page. Deep links ?letter=W, ?spell=HELLO. Docs: docs/sign-language.md.
Sign Mirror (camera-graded handshape practice) pages/sign-mirror.html → /sign-mirror + src/sign-mirror-page.js, grader src/sign-grader.js, reference hand src/sign-hand-model.js Live The practice half of the signing loop: the avatar forms the target letter, MediaPipe's hand landmarker watches the learner's hand in-tab, and the grader scores the handshape live, finger by finger, naming the finger that is off. Avatar pose, target diagram, and grading all read the same handshape spec (src/sign-handshapes.js) so taught and graded can never drift. The whole practice loop is on-device: no frame, landmark, or score is ever uploaded. Course rail orders the alphabet easiest-first with localStorage progress; shared sign prefs (hand, avatar) carry over from /sign-language and /asl-alphabet. Tests: tests/sign-grader.test.js
ASL recognition (webcam signing → text) worker workers/model-asl-recognition/, API api/asl-recognition.js (GCP_ASL_RECOGNITION_URL) Live The reverse direction of sign speech: the browser extracts MediaPipe landmarks from the webcam (video never leaves the device) and the worker transcribes continuous ASL fingerspelling to text on CPU via LiteRT, with a decode-confidence score and an LLM cleanup pass on the API. Model: Kaggle 2023 ASLFR 1st-place (Apache-2.0 code + weights, FSboard CC BY 4.0 corpus, the license-clean chain most ASL models lack). Cloud Run gen2 + patchelf --clear-execstack on the LiteRT .so. Next: word-level signs (PopSign retrain). Tests: test_decode.py (schema + decode, no weights) and test_model_smoke.py (real weights end to end, run inside the built image).
Smart home: the connect flow and household management Page pages/smart-home.html -> /smart-home + controller src/home/connect.js, manage view src/home/manage.js, styles src/home/home.css. Consumes api/home/index.js (GET/POST /api/home), api/home/[id].js, /api/home/:id/grants and /api/home/:id/log. Reachability rules shared with the server through the @three-ws/home-bridge ./url subpath export Live The front door of the Home lane: how a stranger gets from "I have a Home Assistant somewhere" to "my agent is connected", and every way that goes wrong. Fifteen designed states rather than a happy path plus an error toast: signed out, empty, inline validation, the private-host refusal, verifying, connected, a rejected token, unreachable, degraded, disconnected, many homes, the plan ceiling, the dial-out pairing flow, one deep-linked home, and an id that is not this account's. Every one of them names itself on #hm-root[data-state], so "which state am I in" is answerable from outside the page and no state can be reached only by accident. Two rules hold the surface together. The token goes to the server once and never comes back: the field is type=password with a reveal toggle, it is never written to storage, never put in a URL, never logged and never echoed by the API, and it is gone from the DOM the moment a connect succeeds. Reachability is decided in the browser, before the network: a 192.168.x.x or .local address is refused with zero network calls using the same normalizeBaseUrl/isPrivateHost the server validates with, so the two can never disagree and nobody waits out a timeout to be told something we knew at the first keystroke. Every string that came from a house (a label, an entity id, an area name) is rendered as textContent, because those are attacker-influenceable and there is a physical actuator on the other end. Docs: docs/smart-home.md. Tests: tests/e2e/home-connect.spec.js (behaviour on every screen), tests/e2e/home-connect-gallery.spec.js (all fifteen photographed at 1440px and 320px, each asserted to log nothing and to fit a 320px screen), tests/e2e/home-connect-live.spec.js (nothing stubbed: a real Home Assistant connected, the real token proven absent from every browser store, and the container really stopped to reach the degraded state)
Smart home: plans, entitlements and quotas (/smart-home/plan) Page pages/smart-home-plan.html -> /smart-home/plan + controller src/home/plan.js, styles src/home/plan.css. Resolver api/_lib/home/entitlements.js, counters api/_lib/home/usage.js, endpoint api/home/plan.js. Enforced at api/home/index.js (acquisition), api/home/[id]/stream.js (streams), api/home/[id]/members.js (seats), api/home/[id]/call.js (paused homes), api/_lib/home/privacy.js (retention ceiling), api/_lib/home/turn-gate.js called from api/chat.js (agent turns). Cost measurement scripts/measure-home-entitlement-cost.mjs. Migration api/_lib/migrations/20260903160000_home_plan_overrides.sql Live What a plan covers for connected houses, and the two things no plan may ever refuse. A limit never blocks a safety action: over quota, downgraded or paused, locking a door, closing a garage or valve and arming an alarm always execute, checked before any counter is read and classified from the domain and service alone so the exemption never depends on a healthy socket. Nothing about the gate is sold: confirmations, the action log's integrity and every role safety property are on every tier and there is deliberately no dimension for any of them. Seven metered dimensions (homes, seats, streams, voice minutes, agent turns, log retention, relay connections), each carrying the measured cost that justifies it. No fourth entitlement system: limits resolve from account-tier.js badges merged by MAX (so holding $THREE never costs a Pro their Pro limits) and are scaled by the three-tier.js holder multiplier, never by thresholds of our own. One counter: an agent turn is the same priced usage_events chat row an invoice reads, tagged with home_id, not a second tally that could disagree. That row is also what the turn gate reads: over quota the agent refuses a home action, but read-only tools stay open (the model has to see which door is open before it can lock it) and safety actions are never reached by the gate at all. The gate fails open, so a billing read that hiccups serves the user rather than locking them out of their own house. A downgrade pauses, it never disconnects: excess homes get deactivated_at with a written reason, the credential and the action log survive, revoked_at stays null, and the user swaps which houses are live. Enterprise limits are a home_plan_overrides row with the reason on it, not a tier. Every number is env-overridable (HOME_LIMIT_<TIER>_<DIMENSION>), so applying an owner-approved price is a config change. Docs: docs/home-plans.md. Tests: tests/home-entitlements.test.js, tests/home-turn-gate.test.js, tests/e2e/home-plan.spec.js
Smart home: the live 3D home (/smart-home/:id) Page pages/home-scene.html -> /smart-home/:id and -> /home/:id, styles public/home-scene.css. Pure layout src/home/scene-model.js, WebGL renderer src/home/scene-render.js, the 2D house src/home/scene-fallback.js, page controller src/home/scene.js, the top-down floorplan editor the scene follows src/home/floorplan.js with its validation and storage api/_lib/home/layout.js behind GET/PUT/DELETE /api/home/:id/layout api/home/[id]/layout.js, browser half of the API contract src/home/api.js. Consumes GET /api/home/:id, the SSE stream api/home/[id]/stream.js, api/home/[id]/call.js and /api/home/:id/grants Live A live 3D model of the user's house, driven entirely by their own Home Assistant, with the agent's body standing in it. The body is the visitor's own agent, resolved through the canonical my agent record (src/agents/active-agent.js) that the walk world, /play and the voice satellite read, swapped live when they switch agents in another tab and falling back to the platform body when they have no agent, no avatar, or a private one (which publishes no model URL by design). Home Assistant stores no geometry, so everything spatial is derived from its four flat registries by a PURE module with no Three.js in it: floors stack by level, rooms pack per floor in name order, and a saved floorplan overrides the packing through one layout option. That split is why the layout of a real recorded house is asserted in a unit test without a GPU. A room is lit the way the room is lit: colour and intensity from the lights that are actually on, genuinely dark when they are all off, and the outline around its footprint goes amber the moment anything in it is unlocked or open. A room with sixty entities is not sixty objects: objects are ranked (lights, locks, covers, climate, alarms, media, fans, cameras, the rest), capped per surface, and the remainder summarized; numeric sensors become readouts, never objects. A device Home Assistant cannot reach is drawn as a ghost with a marker, never omitted. The house never empties: a dropped connection greys the scene, keeps every room, and says how old it is. Stale (the platform is retrying) and disconnected (nobody is) are different pills, and only the second offers a button. Disconnecting a home reaches the screens showing it: revoking a connection closes the pooled bridge and hands every open stream a final revoked status with the sentence explaining it, then hangs up, so a wall display cannot sit on a green Live badge over a house that is no longer connected. The 2D view is not a consolation prize: same model, real rows and real buttons, reads and operates the whole house, and it is where a browser with no WebGL or a device measured below 18 fps is routed automatically, with the page saying so. A guarded action answers 409 and the question is rendered on the object it would move, with an optional standing allowance for that one entity. Measured: 86 ms median from a real Home Assistant service call to the SSE frame, 10 to 23 ms from that frame to the painted one, 0.1 to 0.3 ms of per-frame work, 108 draw calls, and a flat heap across ten minutes of live updates. Docs: docs/home-scene.md. Tests: tests/home-scene-model.test.js, tests/e2e/home-scene.spec.js
three.ws Home privacy, retention, export and deletion Inventory + purge + export + deletion api/_lib/home/privacy.js, disclosure copy api/_lib/home/disclosure.js, endpoint api/home/privacy.js -> /api/home/privacy, schema api/_lib/migrations/20260903180000_home_privacy_retention.sql, purge section E of api/cron/db-retention.js Live The single place that knows everything the Home lane stores. INVENTORY is not documentation of the code, it IS the code: the endpoint renders it, the export walks it, and tests/home-privacy.test.js re-derives the set of home_* tables from the migration files and fails the build if one of them has no row, which is what stops an undocumented data class from ever landing. The load-bearing promise is that entity names and states are never persisted (the room graph lives in the bridge runtime's memory and dies with the instance); a second test fails any migration that creates a table shaped like a state history. The action log's window is per home and the owner's, 90 days by default, adjustable down to a day and up to ten years with a written reason the schema also enforces, applied immediately on change and swept by the platform's existing retention cron rather than a cron of its own. Deletion goes further than the cascades: memberships and grants on other people's homes, the departed user's id inside another household's action log, invitations addressed to their email, and the lane's rows in the 365-day audit_log. Docs: docs/home-privacy.md. Tests: tests/home-privacy.test.js
Avatar thumbnail coverage api/_lib/avatar-thumbs.js + crons api/cron/avatar-thumbnail-backfill.js (absent thumbnails, */5) and api/cron/avatar-thumbnail-render.js (stale marketplace thumbnails, */10) Live The single owner of avatars.thumbnail_key. Enforces the invariant that a thumbnail key is persisted only after its R2 object is confirmed to exist — a key pointing at a missing object makes R2 return 404 text/plain, which Chrome blocks as ERR_BLOCKED_BY_ORB inside an <img>. Fills coverage cheapest-first: zero-copy adoption of forge_creations.preview_key, then a headless-chromium GLB→PNG render to thumb/<avatarId>.png (api/_lib/render-glb.js). Bounded retries via the avatar_thumbnail_backfill claim ledger (migration), with isBrowserInfrastructureError() separating an OOM-killed browser from a genuinely broken model so a crash never retires healthy avatars. Bulk runner: scripts/backfill-avatar-thumbnails.mjs (--status, --adopt-only, --loop, --reset-infra). Docs: docs/avatar-thumbnails.md. Tests: tests/avatar-thumbs.test.js, tests/home-thumbnail-orb.test.js
Forge model categorization Classifier api/_lib/forge-classify.js, wired at generation in api/_lib/forge-store.js (createCreation), backfill scripts/backfill-forge-categories.mjs, coloured badges in src/forge-showcase.js + /forge-studio twin Live Assigns every forge model a model_category (avatar/accessory/item/scene/creature/vehicle/other) from its prompt with a deterministic, dependency-free keyword classifier — most-specific-first so "a knight riding a horse" is an avatar, not a creature. Nothing set the category before, so ~99.8% of the corpus was other and the category badges, filters, and Forge-Off category dimension were dead; the classifier now runs inline on every generation (all lanes) and reclassifies ~85% of the 9.8k-row back catalogue (dry-run verified). Coloured category pills render across the showcase/gallery/community feed. Tests: tests/forge-classify.test.js.
Forge thumbnail coverage api/_lib/forge-thumbs.js + cron api/cron/forge-thumbnail-backfill.js (*/5) Live Gives every finished forge model a real picture. The dominant free NVIDIA/TRELLIS lane is geometry-first and paints no reference image, so ~83% of finished forge_creations land with preview_image_url = NULL and render as gradient placeholders on every browse surface (showcase, gallery, /community, /search, creator portfolios). This cron claims the newest previewless models, renders each GLB to a 768² PNG via the shared headless-chromium renderer (api/_lib/render-glb.js), uploads it, and fills the preview slot — object confirmed in R2 before the key is committed (same ORB-safety invariant as avatars), and fill-only so a maker's captured poster always wins. Self-provisioning claim ledger (forge_thumbnail_backfill, created at runtime), bounded attempts, lease-based reclaim, browser-death batch abort with attempt refund. ?dry_run=1 reports coverage. Tests: tests/forge-thumbs.test.js.
Catalog quality gate (what earns a slot in the public catalog) api/_lib/seed-quality.js, consumed by api/cron/forge-seed-cron.js Live · mesh stage always on, vision stage behind SEED_CRON_VISION The bar every platform-seeded model clears before it reaches /characters or /objects. Nobody asked for seeded content, so it has to earn its slot: a user who generates a coarse mesh chose to, a visitor browsing the catalog did not. Two stages, cheapest first. Mesh sanity is free and deterministic (reuses api/_lib/glb-quality.js, the interactive forge's own scorer, plus catalog bounds: vertex floor/ceiling, byte floor/ceiling, must-carry-a-texture, non-collapsed bbox, and a mesh-count rule that applies to avatar only because a prop may legitimately be a pile of parts): a degenerate blob is rejected here for the price of a GLB fetch and never costs a model call. Vision judge renders one view and asks two questions: realism via judgeOnce imported (never forked) from api/_lib/quality-bench.js so the gate and the regression bench can never disagree about what a score means, plus a catalog-specific rig-readiness check (one complete humanoid with separated limbs, or a bust / blob / crowd?). Fails closed on mesh, fails soft on vision: an unreachable judge publishes on the mesh verdict marked vision_unavailable, because recording a Vertex outage as a quality reject would corrupt the accept-rate maths. Rejects are copied (never moved) to forge/rejected/ with a full-verdict JSON sidecar, which is the tuning dataset. SEED_GATE_VERSION stamps every verdict since an accept rate is only comparable within one version. Two transports (in-process for Cloud Run, remote via /api/render/avatar-clip + /api/vision for a credential-less workstation) share one decision path. Docs: docs/seed-quality.md. Tests: tests/seed-quality.test.js
Forge-Off (community voting + weekly board) Store api/_lib/forge-store.js (castVote/removeVote/listShowcase sort+voter/forgeOffWeekStart), endpoint api/forge-vote.js, board read api/forge-gallery.js (scope=community&sort=top&window=week), weekly crown cron api/cron/forge-off-crown.js (7 0 * * 1), UI src/forge-showcase.js + /forge-studio twin src/forge-studio/forge-showcase.js, schema migration 20260625120000_forge_board.sql Live Turns the "Fresh from the Forge" strip on /forge into a live board: auth-free upvotes (one per browser, keyed to the same forge:cid id as "Your creations"), a Fresh/Top-this-week sort toggle, optimistic vote pills that reconcile against the authoritative vote_count (recomputed from forge_votes, never a drifting counter), and a Monday-00:07-UTC cron that permanently crowns each week's top-voted creation into forge_board_winners. The crown is the writer the Sketchfab showcase cron's strongest tier had been waiting on. Docs: docs/forge-off.md. Tests: tests/api/forge-gallery-community.test.js
Materialize (generation to a physical object) Page pages/materialize.html → /materialize + src/materialize.js + src/materialize-lib.js, order tracking pages/materialize-order.html + src/materialize-order.js → /materialize/orders/:id, operator console pages/materialize-ops.html + src/materialize-ops.js → /materialize/ops, certificate page pages/certificate.html → /cert/:id + src/certificate-page.js, insert card pages/print-insert.html → /materialize/insert/:id. Engine api/_lib/print/ (mesh-io, topology, bvh, voxel-sdf, analyze, repair, export-stl, export-3mf, quote, gate, rules, certificate, editions, adapters, fulfillment, ops-notify). State machine api/_lib/print-store.js. HTTP api/print/ (catalog, quote, prepare, upload, orders, orders/[id], orders/[id]/confirm, certs/[id], editions, ops/[action], webhook/[provider]) plus the agent lane api/x402/print-order.js. Catalog data/print-catalog.json. Sweep api/cron/print-orders-sync.js Live The physical lane of the forge: any generation becomes a real print, shipped. One POST /api/print/quote both analyzes the mesh (manifold check, shells, open edges, thinnest wall, exact volume via the Manifold WASM kernel, a 0-100 score with buyer-readable deductions) and prices it from one tunable catalog file, returning an HMAC-signed 24h quote token that carries every priced parameter so checkout cannot be replayed or edited. Prepare reconstructs the solid, fills holes, scales, optionally hollows with drain holes, and writes STL / 3MF (with per-vertex colour sampled from the source texture, which is what makes a full-colour print possible) / repaired GLB. Checkout is USDC on Solana for humans and x402 for agents, on the same pipeline: POST /api/x402/print-order validates the token and address BEFORE issuing the 402, so a malformed order is refused for free. Fulfillment is an adapter layer (manual operator lane plus a partner API) behind a whitelisted state machine; provider webhooks are HMAC-verified against the raw bytes and idempotent by delivery id. Every shipped print gets a Solana-attested certificate hashing the exact manufactured file. The fabrication gate runs twice and is not advisory: deterministically at quote time (before money moves, returning 451 with the category and the policy link) and again on the paid order through the LLM chain, with submitOrder() refusing anything without a recorded allow verdict. Docs: docs/materialize.md, operator runbook docs/ops/materialize-fulfillment.md. Spec: specs/PRINT_PIPELINE.md. Tests: tests/api/print-fabrication-gate.test.js, tests/api/print-gate-wiring.test.js, tests/api/print-exporters.test.js, tests/print-store.test.js, tests/print-adapter-contract.test.js, tests/print-certificate.test.js, tests/print-ops-authorization.test.js, tests/print-webhook-idempotency.test.js, tests/print-orders-sync.test.js, tests/print-fulfillment-routing.test.js, tests/print-quote-engine.test.js, tests/materialize-lib.test.js
Realism quality bench Benchmark data/quality-bench/prompts.json (23 fixed prompts + 3 CC0 reference photos), runner scripts/quality-bench.mjs, shared generate/render/judge core api/_lib/quality-bench.js, dashboard api/quality-bench.js + pages/quality-bench.html → /quality-bench (internal, not in data/pages.json), weekly smoke cron api/cron/quality-bench.js (23 3 * * 1) Live The measurement loop the realism campaign hangs on: fires the fixed prompt set through the real /api/forge path, renders 3 canonical views per result with the same headless three.js renderer as the avatar clip/OG-card renders (api/_lib/render-clip.js), and scores every view with Vertex Gemini vision (gemini-2.5-pro, temperature 0, scored twice and averaged, judge never sees forge's internal prompt-enhancement text). Runs are committed append-only JSON under data/quality-bench/runs/; the dashboard renders score trends by lane/tier/subject-class, a worst-5 critique gallery, and the full results table. node scripts/quality-bench.mjs --compare=latest,previous exits nonzero on a >1.0 mean drop — run it before/after any forge change that could affect quality. Docs: data/quality-bench/README.md.
Likeness bench (Phase 1 verification metric) Scoring core api/_lib/likeness-score.js, face-embedding runtime api/_lib/face-embed.js, store + distribution queries api/_lib/likeness-store.js (schema), weekly sweep api/cron/likeness-eval.js (47 3 * * 1), by-hand runner scripts/likeness-eval.mjs, internal board api/likeness-bench.js + pages/likeness-bench.html → /likeness-bench (admin or x-ops-secret, not in data/pages.json) Live · applied 2026-08-14 (this file alone, via apply-migrations.mjs --apply --file, because db:migrate would have applied seven other agents' pending migrations with it). The header comment still reads "Draft, NOT applied" and must stay that way: an applied migration is an immutable record and editing its bytes trips the drift guard The number the roadmap gates Phase 1 on, measured instead of asserted. The realism bench scores whether a generation looks real and never asks whose face it is; the reconstruction worker's ISE eval scores face shape offline against a synthetic set and stores nothing. This closes the gap: it renders a finished reconstruction head-framed at three yaws (head-on 0°, three-quarter 35°, profile 65°) with the platform's own headshot preset, embeds every render and every input capture with OSS face recognition (YuNet detection, MIT + SFace 128-d identity, Apache-2.0, both hash-pinned from OpenCV Zoo and run on onnxruntime-web's WASM backend so there is no native install step), and files a 1-5 score against the generation record in forge_creations. The 1-5 mapping is anchored on SFace's own published decision boundary (cosine 0.363 = 3.0, so the roadmap's 4/5 gate is cosine 0.68, roughly twice the same-identity threshold) rather than on taste. Refuses rather than fabricates: captures_unusable, render_unusable and a genuinely low score are three separate statuses, and a budget-truncated sweep is withheld from the distribution. Reports turn_falloff (identity lost between head-on and the worst view), which is the only place a frontally-flattering texture transfer is visible. Stores no biometrics: no capture URLs, no crops, no embeddings, only the measurement. Docs: docs/likeness-eval.md. Tests: tests/likeness-score.test.js
Payment-outcome board (x402 failure visibility) Endpoint api/ops/payment-outcomes.js, page pages/payment-outcomes.html -> /payment-outcomes (admin session or x-ops-secret, noindex, not in data/pages.json), sensors api/_lib/ops/x402-settle-health.js + api/_lib/x402/wallet-balance-monitor.js + api/_lib/x402/sponsor-runway.js + api/_lib/custodial-key-health.js Live Every way an x402 payment can fail, in one read, before it halts the economy. The 2026-07-11 audit found the griefing classes (verify-reject floods, settle failures, sponsor-fee starvation) were only visible after the economy stopped: recordPaymentMetric was already emitting the events and nothing surfaced them. Four panels: inbound rates over 1h/3h/24h from the durable x402_audit_log (settle success, verify reject, replay reject with its own inbound_attempts denominator, top failure reasons by stage, replay stage split), the outbound ring settle sensor with its triage hint, every configured ring wallet against its own floor plus the measured sponsor runway, and stranded custody. The wallet panel is per-wallet on purpose: settle-floor starvation and dry wallets look identical from outside and have opposite fixes, and a board showing only the sponsor renders a starved payer as healthy. Panels are read independently and a failed one names itself in degraded (207 Multi-Status) rather than blanking the board; on the page a rate with no attempts renders n/a and an unmeasured custody total renders not measured, because a green zero on a reading that never happened is worse than no board. Docs: docs/ops/payment-outcomes.md.
Forge funnel board (does anyone keep what Forge makes) Report api/_lib/forge-funnel.js, endpoint api/ops/forge-funnel.js, page pages/forge-funnel.html -> /forge-funnel (admin session or x-ops-secret, noindex, not in data/pages.json), CLI scripts/forge-funnel-report.mjs (npm run forge:funnel), destination list src/shared/forge-destinations.js + composer chips src/shared/forge-destination-picker.js, columns from migration 20260921120000_forge_destination.sql Built, needs migration applied and a deploy The generation health sensor says whether a mesh came back. This says whether anyone kept it: useful-output rate (accepted or downloaded over finished), first and second asset rates for new makers, D7/D30 return, acceptance by what the model was for, attempts and generation seconds per kept model by engine, and x402 revenue per kept model. Forge recorded the verdict columns from its first migration and nothing read them until this board. The destination is asked once in a chip row under a finished model on /forge and /forge-studio, remembered per browser and sent on later requests; API callers send destination. Platform-generated rows (seeder, quality benchmark) are flagged internal and excluded. Docs: docs/ops/forge-funnel.md. Tests: tests/forge-funnel.test.js
MCP client analytics (which AI clients use our MCP servers) Library api/_lib/mcp-clients.js (recording hooks in api/mcp.js, api/mcp-3d.js, api/mcp-bazaar.js, api/mcp-agent.js, api/pump-fun-mcp.js and api/ibm-mcp.js), endpoint api/ops/mcp-clients.js, page pages/mcp-clients.html -> /mcp-clients (admin session, noindex, not in data/pages.json), script src/mcp-clients.js, migrations 20261009172000_mcp_client_analytics.sql + 20261015010000_mcp_client_sessions_client_nullable.sql, retention step in api/cron/db-retention.js Live Every MCP initialize names its client. The servers issue an Mcp-Session-Id on initialize, and tool calls that echo it are counted per client, version, surface, auth kind and tool. Aggregates only; raw session rows expire after 30 days; request bodies are never stored. The free-studio surface (api/_mcp-studio/handler.js) keeps its own recorder, api/_lib/mcp-client-analytics.js, because it issues the session id before dispatch to support its streaming tool-call path; its tables are the same mcp_client_sessions/mcp_client_daily, which is why the nullable-column migration exists (two independently-evolved recorders had migrated the same table names with a mismatched client column, which crashed every mcp-clients.js write until fixed). Docs: docs/ops/mcp-clients.md. Tests: tests/mcp-clients.test.js, tests/api/ops-mcp-clients.test.js, tests/mcp-client-analytics.test.js
Sketchfab showcase (community models → official account) Cron api/cron/sketchfab-showcase.js, lib api/_lib/sketchfab.js, ledger migration api/_lib/migrations/20260714130000_sketchfab_uploads.sql Live · dormant until SKETCHFAB_API_TOKEN is set Publishes the best community forge models to the official three.ws Sketchfab account, prompt and backlink included. Selection order: forge-board winners (now populated by the Forge-Off crown cron), then top-voted (>=1 vote), then creator-accepted (accepted or downloaded, refinement children excluded, title-quality heuristic). Brand safety is two layers: a SQL denylist plus NemoGuard re-moderation; blocked rows park as blocked in the sketchfab_uploads ledger (states pending/uploaded/live/failed/blocked). ?dry_run=1 exercises selection before the token is wired; SKETCHFAB_UPLOADS_PER_RUN clamps 1-5 (default 2). Docs: docs/sketchfab.md
Third-party display-name safety api/_lib/display-name-safety.js, applied at ERC-8004 metadata hydration in api/cron/[name].js Live The ERC-8004 crawler indexes 126k+ on-chain agents and renders each one's name/description/image from attacker-controlled metadata. Visibility used to be decided solely by the agent's own meta.active, so a Base-registered agent whose name was a racial slur shipped to /marketplace. matchedSlurStem() now withholds such rows (active = false), which removes them from every feed at once since explore/marketplace/agents/search all filter active = true. Deliberately narrow — whole-word hate slurs only, never general profanity, and hex-address aware: leet folding turns 0xdb6b887289c380… into letter soup, so long alphanumeric runs are excluded from the spaced-out-evasion pass. A false positive silently delists a legitimate agent, so precision outranks recall. Backfill for already-indexed rows: scripts/deactivate-slur-agents.mjs (--dry-run). Tests: tests/display-name-safety.test.js — pins the real agent names an earlier substring matcher wrongly flagged.
FBX → GLB conversion scripts/fbx-to-glb.mjs In-repo Skinned/animated FBX → GLB (FBX2glTF), npm run convert:fbx
Avatar schema packages/avatar-schema/ Published as @three-ws/avatar-schema JSON Schema for on-chain avatar manifests
3D-in-markdown toolkit packages/readme-3d/ Standalone-ready (npm readme-3d, extraction script for nirholas/readme-3d) CLI + library converting GLB/glTF/OBJ/STL into the ASCII-STL blocks GitHub renders as interactive 3D in markdown; mesh simplification to the 512 KB limit, check size gate, tutorials, examples, Pages docs site, Claude skill. Powers the live avatar in README.md. In product: POST /api/readme-3d (api/readme-3d.js, docs in docs/api/readme-3d.md), the /readme-3d page (pages/readme-3d.html, src/readme-3d.js), and the "GitHub README 3D" copy action in the forge export menu, avatar page, avatar dashboard and model page (src/readme-3d-copy.js). Tests: packages/readme-3d/test/
Realtime worlds server (Colyseus) multiplayer/ (@three-ws/multiplayer): entry multiplayer/src/index.js, rooms multiplayer/src/rooms/, wire schemas multiplayer/src/schemas.js, deploy multiplayer/deploy-cloudrun.sh Live (three-ws-multiplayer Cloud Run service, us-central1) The authoritative server behind every live world: walk_world (/play, /walk), agora_world (/agora), irl_world (/irl), clash_arena (/play/war), stage_world (Living Stages), studio_world (/ar/studio). One Node process, deployed apart from three-ws-api because a long-lived WebSocket fleet scales differently from request/response traffic. Publishes /health, the identity-free /population aggregate the /event page reads, and three HMAC-signed /internal/* webhooks the API pushes friends DMs, stage tips, and operator announcements through. Horizontal scaling is wired behind REDIS_URI (redis driver + presence); without it the deploy pins one instance so a coin world never splits. Docs: multiplayer/README.md. Tests: tests/multiplayer-server-boot.test.js (boots the real entry point over real HTTP + WS), plus node scripts/play-reconnect-proof.mjs (nine wire-level session-eviction assertions) and node multiplayer/scripts/fish-smoke.mjs
Integration demos examples/coach-leo/ In-repo VR demo
Avatar service backend api/ + workers/ In-repo Serverless-style handlers + Cloudflare workers
Open inference network: node operator client packages/node-operator/ (README, Dockerfile + Dockerfile.gpu, src/, tests/) In-repo Phase 4 roadmap: anyone runs an inference node. Self-contained client whose Solana ed25519 keypair IS its identity: it registers with the coordinator (signature over threews-node-register:{pk}:{ts}, no shared secret), claims jobs from /api/nodes/jobs, executes real local inference (Xenova/all-MiniLM-L6-v2 on ONNX Runtime; q8 on CPU, fp32 on CUDA via Dockerfile.gpu), and returns an ed25519 receipt over sha256(jobId).sha256(model).sha256(prompt).sha256(output).start.end that the coordinator recomputes before accepting. npm run e2e proves register -> job -> verified signed result against the REAL api/nodes/* handlers booted from server/index.mjs. Spec: specs/inference-nodes.md. Docs: docs/inference-node-operator.md. Tests: packages/node-operator/tests/node-operator.test.js, tests/inference-nodes-coordinator.test.js
Open Inference Protocol (OIN v0.1) spec specs/OPEN_INFERENCE_PROTOCOL.md, verifier api/_lib/oin-verify.js, conformance runner scripts/oin-conformance.mjs, reference node workers/stylize/oin.py In-repo Phase 4 roadmap: the vendor-neutral wire protocol that decouples inference from any single provider. A job envelope, a signed capability advertisement at GET /.well-known/oin, and an Ed25519-signed response bound to the job by a SHA-256 digest over its RFC 8785 canonical form, so any third party can verify a node's result without trusting the transport or the platform. The stylize worker is the reference node behind OIN_ENABLED=true (byte-for-byte its pre-OIN self with the flag off) and self-hosted operators with no GCS bucket sign filesystem artifacts via OIN_RESULT_DIR. node scripts/oin-conformance.mjs --node <url> drives advertisement, submit, poll, response verification, and artifact hashing end to end. Settlement rides on specs/inference-receipts.md. Tests: tests/oin-verify.test.js, workers/stylize/test_stylize.py
Production server (Google Cloud Run) server/ + Dockerfile Live Single Express container serving the static frontend, the vercel.json route table, and all api/** handlers with Vercel-parity routing; deploy via npm run deploy:gcp (server/cloudbuild.yaml), crons via scripts/create-gcp-scheduler.mjs · see server/README.md
Multiplayer 3D world (world.three.ws) deploy/world/: Dockerfile, cloudrun.yaml, apply-hardening.sh, patches in deploy/world/patches/; health monitor api/cron/world-health.js Not deployed (as of 2026-10-25): the hyperfy-world Cloud Run service was deleted 2026-10-23 (owner action, per the Cloud Run audit log) and world.three.ws currently returns 404; /healthz reports world as down via the ops_alerts fallback (order 453). Config and monitor stay in place for a redeploy Hyperfy pinned to an exact upstream commit and rebuilt with three local patches (server-side upload cap, /status blueprint-asset enumeration, fail-closed-without-ADMIN_CODE). World state (SQLite + uploaded assets) lives in the GCS bucket world-three-ws-data mounted at /app/world, so the container is stateless. The world is gated: without ADMIN_CODE Hyperfy's effectiveRank falls back to Ranks.ADMIN and every anonymous visitor gets server-side build rights: the fail-open default that emptied the world on 2026-06-12. Deploy + verify with bash deploy/world/apply-hardening.sh; builders unlock in-world with /admin <code>. See deploy/world/README.md
Metaplex Agent Registry deploy (Genesis-333 mint for everyone) pages/deploy-onchain.html + src/deploy-onchain.js → /deploy-onchain, shared builders packages/metaplex-agent-mcp/src/lib/ (published as @three-ws/metaplex-agent-mcp, also in the official MCP registry as io.github.nirholas/metaplex-agent) Live Mint any agent into the Metaplex Agent Registry in the exact Genesis 333 shape: data: URI metadata, verified creator, 5% royalties, immutable metadata, EIP-8004 identity with model.uri + x402Support. The page signs with the user's own wallet (Phantom/Solflare/Backpack, signAllTransactions) through the same-origin RPC proxy; a wallet that advertises Solana transaction v1 over Wallet Standard instead signs create + register as ONE atomic v1 transaction (Genesis-shape mints overflow v0's 1,232 bytes but fit v1's 4,096), built by api/_lib/solana/transaction-v1.js; the MCP server gives agents the identical mint with their own key (preview-first, confirm:true gated) plus a prepare/send lane for external wallets. Both consume one isomorphic builder library, and tests pin the output byte-for-byte to the live Genesis #332 URIs. Devnet is a free rehearsal lane end-to-end. A mainnet deploy also pays a flat 0.02 SOL fee to the $THREE buyback wallet, halved at 50k $THREE in the paying wallet and waived at 250k, disclosed in every preview and carried inside the create transaction (packages/metaplex-agent-mcp/src/lib/three.js); the three_status tool prices it against any wallet.
Solana Memo viewer public/onchain/index.html → /onchain Live A shareable, wallet-free reader for public Solana transaction Memos. It accepts a signature or Solscan transaction URL, requests version-1 transactions directly from the mainnet RPC, previews the supported raster data URI formats, provides a file download or text-copy action, and keeps each result tied to its signer, timestamp, and Solscan source. It refuses to execute active formats such as SVG because Memo content is untrusted. Docs: docs/solana.md.
Onchain agent wallets (spending allowances, not private keys) packages/onchain-agent-wallets/ (published as @three-ws/onchain-agent-wallets, MCP registry io.github.nirholas/onchain-agent-wallets) Live Give an agent a Solana wallet without giving it the money. Funds sit in a vault token account the OWNER owns, derived deterministically from the owner address plus the agent id (createWithSeed(owner, "oaw1:<agent>")); the agent holds only a capped SPL Token delegation over it, so the token program itself refuses any spend past the ceiling and decrements it on every transfer. Guardrails on top (per-tx, rolling daily, recipient and host allowlists, expiry, pause, confirm-above threshold) are enforced before signing, and every decision including refusals lands in a local ledger. pay_x402 probes the price unpaid, checks it against the guardrails, tops the agent up for exactly that amount, pays, and leaves it empty. Owner actions need no key on the machine: they come back as unsigned transactions for Phantom/Solflare/Ledger. Delegation tests run the real SPL Token program in process and assert that 61 against a remaining allowance of 60 fails on-chain.
Destination whitelist (cooldown allowlist for agent wallet payouts) Engine api/_lib/destination-whitelist.js, endpoint api/wallet-whitelist/index.js, MCP tools api/_mcp/tools/whitelist.js, cron api/cron/whitelist-activate.js, hub tab src/agent-wallet-hub/tabs/whitelist.js, migration api/_lib/migrations/20261010160000_destination_whitelist.sql Live; migration applied to production New payout addresses wait out an owner-set cooldown (24h default, 1h floor), need step-up to add, are proposal-only for agents, cancel in one click and remove instantly. Enforced in the shared spend guards for transfers, tips, bridge, payouts and withdrawals. Docs: docs/destination-whitelist.md. Tests: tests/destination-whitelist.test.js
Owner-funded agent budgets (on-chain allowances) lib api/_lib/onchain-allowance.js, store and guard hook api/_lib/onchain-allowance-store.js, endpoint api/agents/solana-allowance.js -> /api/agents/:id/solana/allowance, guard wiring api/agent/guard.js, hub tab src/agent-wallet-hub/tabs/allowance.js, devnet proof scripts/allowance-devnet-proof.mjs, migration api/_lib/migrations/20261023170000_agent_onchain_allowances.sql Live; migration applied to production; recurring behind ALLOWANCE_RECURRING_ENABLED The owner keeps funds in their own wallet and signs one transaction creating a capped, expiring fixed delegation to the agent wallet via the Solana Subscriptions and Allowances program. The remaining on-chain allowance is a hard ceiling in the spend guards, and the Budget tab shows cap, spent, remaining and expiry with one-click revoke. Docs: docs/agent-allowance-budgets.md. Tests: tests/onchain-allowance.test.js
Capped burner (agent spends alone up to a cap, owner confirms the rest) classifier api/_lib/burner-tier.js (shared by guard and editor), guard in api/_lib/agent-trade-guards.js, approvals + decision trail in api/_lib/approvals.js, owner wallet signatures api/_lib/owner-sign.js, hub tab src/agent-wallet-hub/tabs/burner.js, signing UI src/approvals-page.js Live Policy { autoMaxUsd, dailyAutoMaxUsd, confirmAboveUsd, expiryMinutes } on PUT /api/agents/:id/solana/limits. Over the cap a spend becomes a pending approval, not a failure; doc: docs/approvals.md. Tests: tests/burner-tier.test.js, tests/burner-approvals.test.js
On-chain contracts (Solidity + Solana) contracts/ · contracts/README.md Mixed: ThreeWSPayments + ThreeWSFactory live on BSC/Base/Arbitrum, the rest in-repo Every contract and program three.ws owns, in one Foundry project plus three Anchor programs. ERC-8004 identity/reputation/validation registries (reference implementations of the canonical deployments the platform actually reads), the live x402 USDC receiver and its CREATE2 vanity factory, AgentPayments, GreenfieldVault, WorldMoves, and the Solana skill_license / agent_invocation programs. forge test covers the Solidity set with 242 tests across 8 suites; the Solana side is covered by the LiteSVM row below. Deploy status per contract and the address provenance per chain: contracts/DEPLOYMENTS.md
Contract audit pack contracts/AUDIT-README.md, invariants specs/ECONOMY_CONTRACT_INVARIANTS.md, threat model specs/ECONOMY_CONTRACT_THREAT_MODEL.md, static analysis contracts/audit/ In-repo Everything a review firm needs on day one for the reputation, royalty and delegation contracts: scope + deploy status per contract, stable invariant ids with a positive and a negative test each, an assets/actors/failure-modes threat model, and committed Slither + Clippy output with every finding fixed or dispositioned in writing
Recurring payments (subscriptions + DCA) Page public/recurring.html → /recurring, module src/recurring.js, lifecycle rules api/_lib/recurring.js, APIs api/agent-subscriptions.js → /api/agent-subscriptions and api/dca-strategies.js → /api/dca-strategies, hourly crons run-subscriptions + run-dca in api/cron/[name].js, schema api/_lib/migrations/20260813191500_recurring_payment_lifecycle.sql Live One signed ERC-7710 permission, then money moves on a schedule: a subscription transfers a fixed USDC amount to an agent's wallet each period, a DCA strategy swaps the same amount into a token through Uniswap V3. /recurring is the whole lifecycle in one place (create, pause, resume, cancel, per-charge history) plus an Incoming tab scoped by agent ownership rather than by payer, so a creator sees what is being paid in. Every attempt is written to subscription_charges / dca_executions, and one shared classifier decides what a failure means: a revoked or expired permission pauses the schedule with the reason attached, a network blip releases the period claim and retries for three ticks, a timeout is never retried (the only failure that could double-charge), a diverged DCA quote skips the period for free, and a platform-side relayer outage never counts against the owner at all. Settlement needs AGENT_RELAYER_KEY + RPC_URL_<chainId> on the deployment; DCA creation needs DCA_ALLOWED_TOKEN_OUT + DCA_CHAIN_ID. Docs: docs/recurring-payments.md. Tests: tests/recurring-charge-outcomes.test.js, tests/api/recurring-subscription-cron.test.js
Solana program invariant tests contracts/program-tests/ In-repo LiteSVM suite running the real compiled SBF bytecode of skill_license, agent_invocation, and knock_escrow against invariants SL-*, AI-*, and KE-*, with the real SPL Token and ATA programs loaded. 42 tests green
Reputation Explorer Page public/reputation/index.html + module public/reputation/reputation.js → /reputation Live EAS-backed review history for ANY Ethereum address, agent or not: search an address or ENS name, pick a chain (Base, Base Sepolia, Ethereum, Optimism, Arbitrum, Polygon), and read every attestation written to it straight from that chain's EASScan GraphQL index. Reviews render as stars plus comment; attestations written against any other schema render their own decoded fields, so a non-review card is never a blank row. The list pages 30 at a time and filters by All / Scored / With comments. An unreachable index is reported as unknown history with a retry, never as zero reviews. Writing a review is wallet-gated and lands on Base Sepolia. Owning an ERC-8004 agent on the viewed chain surfaces the registry's own vote count beside the EAS numbers. ?agent=<chainId>:<id> resolves an ERC-8004 agent to its owner address and forwards. Docs: docs/reputation.md
Reputation Staking Market spec specs/REPUTATION_STAKING_MARKET.md, engine src/shared/reputation-staking.js, server api/_lib/reputation-market.js + api/reputation/market*.js, surface public/reputation/market/ → /reputation/market In-repo · devnet open, mainnet owner-gated Phase 3 roadmap: stake conviction on an agent and earn from its attested action history. A stake is a staker-signed Solana transfer to the market escrow carrying an rsm.v1 SPL-Memo, so the chain (not the database) defines a position; the server only verifies it by reading the transaction back. Yield comes from a fixed per-epoch pool split by principal × time × agentWeight, where the weight is derived purely from the agent's signed threews.* attestations (work concave in log2, faults charged double), so conviction never pays itself. Principal is never slashed and settlement clamps earnings to the escrow surplus. Extends the SPL-Memo attestation layer in docs/solana-reputation.md. Storage: reputation_staking_market migration. Walkthrough: docs/reputation-staking-market.md. Devnet proof: node scripts/reputation-market-proof.mjs. Tests: tests/reputation-staking.test.js
On-chain skill licenses contracts/skill-license/ → /api/skills/license-onchain In-repo Anchor program: each purchased skill = a 1/1 SPL NFT + SkillLicense PDA, a trustless alternative to DB-backed access checks. Backend: api/_lib/skill-license-onchain.js
Tokenized 3D (mint an avatar as an NFT) api/_lib/tokenize-3d.js + api/_lib/tokenize-3d-metadata.js, MCP tools api/_mcp/tools/tokenize.js (mint_3d_asset, get_3d_asset_onchain), signed ledger provenance api/_lib/asset-provenance.js, launch directory api/v1/tokenized/launches.js → GET /api/v1/tokenized/launches, public gallery pages/minted.html + src/minted.js → /minted In-repo Mint a generated/owned GLB as a Metaplex Core NFT whose media is a live 3D viewer (GLB under animation_url), with baked provenance + enforced capped royalties (10%), idempotent, devnet-default. Every generated avatar AND every mint also appends an ERC-191-signed record to the agent_actions ledger (verifiable via @three-ws/provenance-mcp's query_action). A mint naming parent_mint (a remix) routes the parent creator's royalty out of the mint fee as a real on-chain USDC transfer (mainnet, x402-collected calls only) — api/_lib/remix-royalty.js split math, api/_lib/remix-settlement.js payout wallet. Premium/token-gated generation: the Forge High tier (200k poly + PBR) is $THREE hold-or-pay gated — api/forge.js requireFeatureAccess('forge.high') + api/_lib/three-tier.js tier ladder, x402 pay-per-use or credits fallback; Draft/Standard stay free and ungated. Launch record: tokenized_3d_assets + remix-royalty columns. Public gallery: /minted renders the launch directory live (model-viewer thumbnails, network toggle, royalty + remix badges) — the NFT counterpart of /launches. Docs: docs/mcp.md. E2E: scripts/tokenize-3d-devnet-e2e.mjs. Tests: tests/tokenize-3d.test.js, tests/tokenize-3d-remix-royalty.test.js, tests/asset-provenance.test.js
Generative 3D drops (supply-capped collections) engine api/_lib/drops.js, store api/_lib/drop-store.js, routes api/drops/[action].js → /api/drops/{list,get,items,verify,create,publish,reveal}, index pages/drops.html + src/drops.js → /drops, collection pages/drop-collection.html + src/drop-collection.js → /drops/:slug, styles src/drops.css In-repo A drop stores its SPEC, not its art: every item's traits derive from (seed, index, layers) alone, so the whole supply is a pure function and a holder can recompute it. Creator gives a base style plus weighted trait layers; the roll is instant and free at any supply up to 10,000 because no art is generated at create time. Rarity is scored from the ACTUAL rolled distribution (sum of supply/occurrences per trait), ranked, and bucketed into the platform's common/rare/epic/legendary tiers. A published sha256 over the canonical spec is the commitment; the seed stays withheld until publish, which freezes the spec one-way. Art is forged per item on reveal through api/forge.js (claim-then-poll, conditional UPDATE so a double click cannot start two jobs, stale claims self-release after 15 min), which is what keeps a 10k collection economically possible. Reveals inherit the universal animation retarget and the GLB/VRM/USDZ export path. Distinct from /drop/:id (the unrelated sealed wallet gift claim page); the routes are ordered so they cannot shadow each other. Schema: drops + drop_items. Docs: docs/drops.md. Tests: tests/drops-engine.test.js
Token-gated 3D embeds (holder-only interactive scenes) Gate config + on-chain verify api/_lib/embed-gate.js, access tokens api/_lib/embed-gate-token.js, endpoints api/embed/gate-create.js + api/embed/gate-verify.js, gate-aware resolver api/embed/resolve.js, MCP tool api/_mcp/tools/embed.js (create_gated_embed), widget public/embed/v1.js (<three-d>) + standalone host public/embed/v1/gated.html → /embed/v1/gated In-repo create_gated_embed(asset_id, gate) turns an avatar or on-chain agent you own into a holder-only interactive <three-d> embed — visitors must prove a real, server-verified SPL balance (SIWS challenge → nonce → signature → Solana RPC read, never a client-reported number) before the live scene renders; below the bar they see a designed locked teaser + connect-wallet CTA. mint defaults to $THREE but is a runtime parameter (coin-agnostic plumbing). Anti-abuse: short-lived signed access tokens (auto re-verify on expiry) + per-IP/per-wallet rate limits. Storage: embed_gates + embed_gate_nonces. Spec: specs/EMBED_SPEC.md. Docs: docs/token-gated-3d-embeds.md. Tests: tests/embed-gate.test.js
Agent token plans (the coin an agent will become) Rules + storage api/_lib/agent-token-plan.js (migration api/_lib/migrations/20260811130000_agent_token_plans.sql), API actions plan + plan-dry-run in api/agents/tokens/[action].js → /api/agents/tokens/{plan,plan-dry-run}, profile panel src/agent-token-plan.js on /agents/:id In-repo · Live The launch configuration bound to the agent record: one saved, editable plan per (agent, network) carrying the coin's name, ticker, story, artwork, pairing, buyback share and dev buy, with a derived readiness verdict and SOL cost estimate. Saving costs nothing and mints nothing. plan-dry-run is the free proof lane: it builds the SAME pump.fun create instructions the real launch builds from the SAME plan, compiles them against a real blockhash and simulates them on the cluster (devnet by default), never signing and never broadcasting, and separates funding_required from a genuinely broken plan. Both launch paths (/api/agents/tokens/launch-confirm from the owner's wallet, /api/pump/launch-agent from the agent's custodial wallet) call markPlanLaunched and write a pump_agent_mints row, which is also what finally puts user-wallet launches into /launches and the profile's launch history. Docs: docs/agent-tokens.md. Tests: tests/agent-token-plan.test.js, tests/agent-token-plan-api.test.js, tests/agent-token-plan-render.test.js
Fee Bridge (creator fees to an X account in USDC) Page pages/fee-bridge.html (unrouted until launch) + src/fee-bridge.js + src/fee-bridge.css, API api/fee-bridge/[action].js → /api/fee-bridge/*, engine api/_lib/fee-bridge/ (config, chain, ledger, math), cron api/cron/fee-bridge.js (every 10 min), migration api/_lib/migrations/20260917150000_fee_bridge.sql, studio option in public/studio/fees-panel.js In-repo · Held (not public) A coin routes 100% of its pump.fun creator fees to the bridge wallet (FEE_BRIDGE_SECRET_KEY_B64, signer fee-bridge, exempt from economy sweeps via holdsUserFunds) and is registered to an X handle after an on-chain routing and ownership check. The cron cranks distribution, swaps SOL to USDC on Jupiter, buys $THREE for the treasury with 20% and credits 80% to the handle. The owner connects X (read scope, return_to=/fee-bridge), links a Solana wallet and withdraws; balances past $5 auto-pay. Every send persists its signature before broadcast so passes resume from chain state. Held back by the owner (2026-09-17) until the launch is approved: the page has no route, no build input and no pages.json or changelog entry, and the studio option only appears once FEE_BRIDGE_ENABLED is on. To launch, restore those four and set the env. Docs: docs/fee-bridge.md. Tests: tests/fee-bridge-math.test.js
Agent token market data (what the coin looks like on the profile) Cluster read api/_lib/pump-curve-view.js → GET /api/pump/curve + GET /api/v1/pump/curve, view model src/widgets/bonding-curve.js (computeView), normalization + widget src/pump/coin-status-card.js (mapCoin / mapCurve / mountCoinStatus), profile wiring src/agent-detail.js (token chip + launch history) In-repo · Live The live market half of an agent token. Two sources, one normalized shape: pump.fun's indexer (/api/pump/coin, mainnet, carries logo + 24h volume) and the bonding curve read straight off the cluster (/api/pump/curve), which is the ONLY source on devnet and the fallback whenever the indexer has not indexed a fresh mint or cannot be reached. A devnet coin renders in SOL and is badged DEVNET (devnet SOL has no dollar value) and links to the explorer instead of a pump.fun page that does not exist for that cluster, so the free rehearsal path renders exactly like a real launch. The curve gate accepts a pump.fun-ground pump suffix, a three.ws 3ws mark, any plausible devnet address, and otherwise asks pump_agent_mints whether the mint is one of ours: a coin launched from a user's own wallet carries no mark and used to be refused with a cached not_a_pump_mint 404. Market cap is derived as price × supply because the SDK's price.marketCap goes negative on live curves. Free proof: scripts/agent-token-market-proof.mjs (reads only, signs nothing). Docs: docs/agent-tokens.md. Tests: tests/pump-curve-mint-gate.test.js, tests/agent-detail-launch-history.test.js, src/pump/coin-status-card.curve.dom.test.js
Agent self-signup, capabilities, stats, honest health Signup api/v1/agents/signup.js → POST /api/v1/agents/signup, claim api/v1/agents/claim.js, logic api/_lib/agent-signup.js, capabilities api/v1/capabilities.js (built by api/_lib/platform-capabilities.js), totals api/stats.js (+ api/_lib/platform-stats.js), readiness api/health.js (+ api/_lib/health-probes.js), page sections in pages/status.html, tables in migration Live An agent with only an Ed25519 key signs a message and gets an agent, custodial wallets and a one-time API key, in paper mode (frozen spend, trade kill switch, live perps off) until a human claims it with a code. Nonces are single-use per key through a database primary key, timestamps must be within 300s. Docs: docs/api-reference.md. Demo: scripts/agent-signup-demo.mjs. Tests: tests/agent-signup.test.js
Agent self-onboarding (signup with a Solana key, x402 plan upgrade) REST api/auth/agent-signup.js → /api/auth/agent-signup, api/billing/agent-upgrade.js → /api/billing/agent-upgrade, service api/_lib/agent-onboarding.js, CLI packages/three-ws-cli/src/commands/signup.js, migration api/_lib/migrations/20261023120000_agent_signup_challenges.sql Built, ships with the next deploy and migration; first mainnet upgrade payment is owner-gated Challenge-response signup (single-use nonce bound to the key, one account per key, IP/key rate limits, daily cap) and a per-account-priced USDC x402 upgrade that returns a scoped key. Docs: docs/agent-self-onboarding.md. Tests: tests/agent-onboarding.test.js, tests/agent-upgrade.test.js, tests/agent-signup-route.test.js
Launch Studio (coin-launch use cases) api/_lib/launch/ → /launch-studio, api/pump/launch-studio.js, public/launch-studio/launch-studio.js In-repo Engine + catalog of 50 declarative launch recipes: reward coins for trending GitHub repos/creators (github-trending.js) and coins riding live narratives (launcher-trends.js). Live preview, then a /launch handoff that carries the recipe's fee routing as ?reward= and pre-fills the fee split after the mint. Docs: docs/launch-usecases.md, api/_lib/launch/README.md
Coin launchpad for 3D agents (/launch) pages/launch.html + src/launch/launch-page.js → /launch, logic src/launch/launch-model.js, wallet signing src/launch/launch-wallet.js, tx assembly api/_lib/pump-launch-tx.js, endpoints in api/pump/[action].js (launch-config, my-coins, build-metadata, launch-prep, launch-confirm, launch-agent, collect-creator-fee-*) Live Pick one of your agents, name the coin, launch on pump.fun from your wallet or the agent's wallet, then claim creator rewards under My coins. Metadata links the agent page and (for public avatars) its GLB. A disclosed 1% fee on the dev buy rides in the launch transaction and is verified at confirm. Transactions compile v0 against pump.fun's lookup table, or Solana transaction v1 when v0 overflows and the wallet supports it. ?reward= recipe links mount the studio launch panel (public/launch/launch.js). Docs: docs/launchpad.md
Native launchpad (three.ws's own bonding curve) Curve economics api/_lib/native-launch/config.js, curve wrapper api/_lib/native-launch/dbc.js, dispatcher api/native-launch/[action].js → /api/native-launch/{config,quote,pool,launch-prep,launch-confirm,launches}, lane toggle in public/studio/launch-panel.js In-repo (devnet-verified; mainnet config not yet deployed) The second launch lane beside pump.fun: a coin launch on a bonding curve three.ws configures and owns, so the platform earns a share of every trade instead of only creator fees. Runs on Meteora's audited Dynamic Bonding Curve program with three.ws as the on-chain partner — 1B supply, SOL-quoted, immutable metadata, 1% trading fee split 50/50 creator/platform, graduating at ~85 SOL raised into a DAMM v2 pool with 100% of LP permanently locked (un-ruggable, both sides keep earning). Same custody model as the pump lane (server builds an unsigned tx, the launcher's wallet + mint keypair sign client-side, confirm verifies on-chain that the curve program actually ran before recording). The lane hides itself entirely until a partner config is pinned for that network (NATIVE_LAUNCH_CONFIG_KEY[_DEVNET]), so launches fall back to pump.fun rather than half-working. Not to be confused with /api/launchpad/* (Launchpad Studio, the page builder). Storage: native_launches. Setup: scripts/native-launchpad-create-config.mjs. E2E: scripts/native-launchpad-e2e-devnet.mjs. Docs: docs/native-launchpad.md. Tests: tests/native-launch-curve.test.js, tests/native-launch-endpoint.test.js
Memetic Launcher (per-user autonomous coin launcher) pages/launcher.html → /launcher + src/user-launcher.js, API api/launcher/me.js, engine api/_lib/launcher-engine.js (cron api/cron/launcher-tick.js), trends api/_lib/launcher-trends.js In-repo Every user designs their own autonomous pump.fun launcher: mode (trend/meme/hybrid/random), trend sources, cadence, network. Preview (default) records picks without moving SOL; Live mints for real, SELF-FUNDED - each launch paid by the user's own agent wallet (base ~0.022 SOL + dev buy), never master SOL, with typed go-live confirm, dev-buy + daily-SOL-cap clamps, unfunded-wallet skips (breaker-immune), and an agent-wallet funding panel with live balances. Docs: docs/memetic-launcher.md. Tests: tests/user-launcher.test.js, tests/launcher-engine.test.js
pump.fun first-claims Telegram channel (@pumpfunclaims) Delivery lane api/_lib/pump-claims-push.js, cron api/cron/pump-claims-push.js (every 5 min), shared scanner api/_lib/pump-claims.js (also backs GET /api/pump/first-claims and the pumpfun_first_claims MCP tool) In-repo · lane wired, channel dark pending PUMPFUN_BOT_URL + TELEGRAM_PUMP_CLAIMS_CHAT_ID A live feed of first-time pump.fun creator fee claims, one message per claim: the first time a creator ever pulls accrued rewards out of the fee vault is an irreversible on-chain signal that they are engaged with their coin. Mirrors the commit-feed lane's safety properties (DB lock, seed-without-posting on first run, per-message state writes, oldest-first drain, 3h replay cutoff) but dedupes by transaction signature rather than timestamp, because claims routinely share a second and a timestamp cursor drops the second one. No fallback to the holder changelog channel on purpose. The RPC fallback inside the scanner cannot serve this feed (the pump program clears a 200-signature page in under one second, so a scan covers no useful window); an indexer is required. Docs: docs/pump-claims-channel.md. Tests: tests/pump-claims-push.test.js
Ship log (release notes joined to the commits that shipped them) Package packages/shipfeed/, endpoint api/ship/feed.js → GET /api/ship/feed, page public/ship/index.html → /ship, provenance for the announcement lane api/_lib/ship-provenance.js Live The join between the two records of the same work this repo keeps: the changelog (readable, incomplete) and the commit log (complete, unreadable). @three-ws/shipfeed parses conventional commits, scores each one by audience (holder / developer / internal) and signal, and links release notes to the commits that produced them with no metadata in the workflow: a Changelog: trailer wins where one exists, otherwise a time window plus IDF-weighted term overlap plus tag agreement plus proximity, and every link publishes its confidence and its reasons (?explain=<sha> returns one commit's full reasoning). Unclaimed commits are grouped into bursts and shown as "unannounced", which is the half no changelog has ever surfaced. The same package now drives both Telegram lanes: release announcements carry a "shipped in N commits" compare link, and the raw commit feed reads its headline from the parser (feat(resilience): reads as "Feature · resilience") and skips merges, chore(deps): bumps and lockfile-only changes. Zero dependencies, works on any repository, CLI included (npx @three-ws/shipfeed). Docs: docs/shipfeed.md. Tests: packages/shipfeed/tests/, tests/ship-feed-endpoint.test.js, tests/ship-provenance.test.js
On-chain agent invocation contracts/agent-invocation/ In-repo Anchor program: verifiable agent-to-agent skill invocation events. SDK: agent-protocol-sdk/
Escrowed knocks (pay-per-reply) contracts/knock-escrow/ In-repo Anchor program making a knock's payment conditional instead of final: knock parks the price in a vault owned by the knock's own PDA, and only three things can happen to it. answer pays the owner minus a fee capped at 10% in the program itself, refuse refunds the sender in full and takes no fee, and reclaim refunds the sender once the reply window closes and can be called by anyone. Each KnockRecord snapshots the fee that was in force when it was made, so an authority cannot reprice money already in escrow, and it stores only the SHA-256 of the message and the reply, never their text. The trust-me version of this settles straight to the owner at api/knock/ (row above); this is the version that works between strangers. Both sides are reachable from a browser: senders escrow and crank their own refund from the door page, owners open their on-chain door, answer for payment or refuse for a refund from /knock, all signed by their own wallet (src/knock/escrow-checkout.js). Docs: contracts/knock-escrow/README.md, docs/knock.md. Tests: tests/knock-escrow-program.test.js, tests/knock-escrow-pda.test.js, tests/api-knock-escrowed.test.js, tests/api-knock-escrow-sync.test.js
Cross-chain SDKs sdk/, solana-agent-sdk/, agent-payments-sdk/, agent-protocol-sdk/ Published Cross-chain agent SDKs
MCP integration mcp-server/, mcp-bridge/, packages/*-mcp/ 41 npm servers + 10 hosted remote (51 total, incl. the free /api/mcp-studio 3D Studio, whose ChatGPT plugin surface api/mcp-chatgpt.js → /api/mcp-chatgpt serves the eight 3D tools and the model viewer without the persona tools or any frameDomains, and api/mcp-grok.js → /api/mcp-grok serves every studio tool with no widget templates plus, for a caller signed in with OAuth 2.1 or a connector key, the account's agent tools from the core server through api/_mcp-studio/account-tools.js, never a value-moving one (tests/mcp-grok-accounts.test.js); all three doors share api/_mcp-studio/handler.js, and SURFACES in api/_mcp-studio/dispatch.js defines what each advertises), all in the MCP registry. Canonical metadata: prompts/store-submissions/_generated/mcp-listing-source.json, generated from the manifests by scripts/build-mcp-listing-source.mjs (npm run audit:mcp-listing fails when it drifts) Model Context Protocol surface, full server list in docs/mcp.md. One-click client setup: pages/connect.html → /connect (Claude, Cursor and VS Code install links plus ChatGPT, Grok Bot, Claude Code and generic steps; the Grok Bot tab is the shared connector card src/grok-connector.js, also mounted on the Grok landing page pages/grok.html → /grok (src/grok-page.js: capabilities, a live strip of recent gallery creations, an in-page MCP demo against /api/mcp-grok, three scheduled recipes, the skill file); /connect is built live from public/.well-known/mcp.json with tool counts from the catalog; config names match the CLI's slugForPath). CLI: packages/three-ws-cli/ (npx three-ws setup), docs docs/cli.md → /docs/cli. One-command setup per client (npx three-ws --claude), doctor, agent status and team live in packages/three-ws-cli/src/commands/; the hosted installers public/cli/ (/cli/install, /cli/claude, each with a .sha256 and an ed25519 .sig, public key signing-key.pem) are signed by scripts/sign-cli-scripts.mjs (npm run sign:cli, verified by npm run check:cli-scripts in the gate); the clean-container check is packages/three-ws-cli/tests/container/run.sh. Per-tool pages (schema, example call, price, a try-it for free read-only tools): pages/mcp-tool.html → /mcp-tools/<server>/<tool>. The census (tools, resources, prompts per server, with a how-it-is-calculated note) is computed at build time into public/tools.json and at request time by api/mcp-census.js → /api/mcp-census (api/_lib/mcp-census.js); the release-by-release diff of added tools is public/mcp-tool-history.json (scripts/build-mcp-tool-history.mjs); docs that quote a count use <!-- mcp-count:... --> markers that npm run check:mcp-counts (scripts/check-mcp-counts.mjs) verifies in the gate, alongside tests/mcp-tool-quality.test.js and tests/mcp-prompt-references.test.js (npm run test:mcp-surface). Searchable index of every tool: pages/mcp-tools.html → /mcp-tools, rendered from the generated public/mcp-catalog.json (scripts/build-mcp-catalog.mjs, npm run build:mcp-catalog, staleness gated by npm run audit:mcp-catalog). Tool safety annotations are verified against each handler by scripts/audit-mcp-safety.mjs (npm run audit:mcp-safety, rules in scripts/lib/mcp-safety-check.mjs, guarded-file list shared with the golden snapshot via scripts/lib/mcp-tool-sources.mjs); docs docs/mcp-safety.md → /docs/mcp-safety. Trust policy: api/mcp-policy.js -> GET /api/mcp-policy turns those verified labels into a ready-to-paste client allowlist (profiles strict/balanced/open x formats claude/vscode/json), surfaced by the builder panel on /mcp-tools. Connector-review readiness (every paid stdio tool answers a clean x402 challenge, and the reviewer entitlement lifts it): scripts/audit-mcp-reviewer-path.mjs, npm run audit:mcp-reviewer. Tests: tests/mcp-safety-audit.test.js, tests/mcp-catalog.test.js, tests/api/mcp-policy.test.js
CLI payer (x402 and MPP) packages/three-ws-cli/src/pay/ (challenge parser, permissions and daily ledger, keychain/sealed-file keystore, x402 and MPP signers, engine, stdio MCP server), commands pay.js and wallet.js Live three-ws pay <url> settles an x402 v1/v2 or MPP Solana 402 with a locally held key, inside ~/.config/three-ws/pay-permissions.json; --dry-run signs nothing; refusals exit 10 with a reason string; pay mcp exposes pay_quote and pay_fetch. Docs: README. Tests: pay-units, pay-flow, pay-cli
CLI automation mode and run reports packages/three-ws-cli/src/automation.js (exit-code table, --non-interactive), src/commands/automation.js (agents, runs, wallet balance, orders, report run), generator src/report/run-report.js (also imported by the run page src/agent-run-replay.js) Live Every command takes --json (one document on stdout) and --non-interactive, with exit codes 0 ok, 2 usage, 3 auth, 4 guard refusal, 5 payment required, 6 network (pay keeps 10 to 14). report run <id> --out f.html writes one offline file with the goal, tool calls, decisions, trades, outcome and the decision-trail head hash. Docs: docs/cli.md. Tests: packages/three-ws-cli/tests/automation.test.js
MPP on Solana (one URL, two challenge formats) and skill rails Wire layer api/_lib/mpp-solana.js (mppx core), seller option mpp: true in api/_lib/x402-paid-endpoint.js (enabled on api/x402/gas-oracle.js), agent payer dryRun / preferProtocol in api/_lib/x402-buyer-fetch.js, skill router api/skills/[id]/invoke.js + api/_lib/skill-rails.js Live (mainnet settlement owner-gated) A paid route answers an unpaid call with the x402 accepts list AND WWW-Authenticate: Payment (Solana charge, pull mode) at the same price; an Authorization: Payment credential settles through the existing x402 verify/settle path and the response carries Payment-Receipt. The agent payer reads either, applies its spending caps to the charge, and can quote in dry run. Marketplace skills are priced once and served over x402, MPP, A2A and AP2 with one split and one receipt. Docs: docs/mpp-solana.md, docs/skill-rails.md. Tests: tests/mpp-solana.test.js, tests/skill-rails.test.js
Grok Bot integration (custom MCP connector) Door api/mcp-grok.js → /api/mcp-grok on the shared studio handler api/_mcp-studio/ (signed-in account tools api/_mcp-studio/account-tools.js, job tools api/_mcp-studio/job-tools.js), install tokens api/mcp-studio/install.js → /api/mcp-studio/install, guided prompts api/_mcp/prompts.js, landing page pages/grok.html → /grok, connector card src/grok-connector.js (also on /connect), skill file public/grok-skill.md (template data/grok-skill-md.template.md), connector probe scripts/mcp-client-probe.mjs (npm run probe:mcp-clients) Free remote MCP server for Grok Bot, Grok connectors and the xAI API: no call hangs, quota per MCP session or install token, the free studio anonymously, plus the account's agent tools with a connector key or OAuth 2.1 (?auth=oauth), never a value-moving tool. Connector reference docs/grok-bot.md → /docs/grok-bot (setup per auth mode, server choice, links contract, jobs and idempotency, limits, spend rule, prompts, probe troubleshooting; samples run by scripts/run-doc-samples.mjs, drift test tests/grok-bot-doc.test.js); product tour docs/grok.md
X creation claim Page pages/x-claim.html → /x/claim (src/x-claim.js), API api/x/claim.js, logic api/_lib/x-creation-claim.js, ledger migration api/_lib/migrations/20261009213000_x_creation_claims.sql Models the @-mention bot made for an X author move from the bot account into their library when they link the same X id (on link, on the page, or at creation time). Doc: docs/x-mention-bot.md. Tests: tests/x-creation-claim.test.js
Awesome 3D Agents (curated list) Source data/awesome.json, generator scripts/build-awesome.mjs (npm run build:awesome, drift-gated by npm run check:awesome, publishable mirror via npm run awesome:standalone), outputs awesome/README.md + public/awesome.json, page pages/awesome.html -> /awesome, link checker scripts/check-awesome-links.mjs (npm run awesome:links) Live An awesome-list of everything needed to give an AI agent a body: text-to-3D, capture and splatting, avatars, rigging, motion, lipsync and voice, web renderers, asset pipelines, physics and networking, agent frameworks, datasets, free assets, learning. One JSON source produces both the GitHub-facing list and the searchable page, so they cannot disagree. Every url is fetched and classified (ok / moved / bot-filtered / broken) before it ships; the checker stays out of the deploy path so a third-party outage cannot redden someone else's build. The README is written to pass npx awesome-lint: badge on the heading line, no License section, no Contributing entry in the contents, and every description capitalised and ended with a period, all enforced by the generator and by tests/awesome-list.test.js. Its last two lint rules read GitHub repository topics, which a list inside a product repo cannot satisfy, so --standalone emits a ready-to-publish mirror repo (readme, contributing, code of conduct, license) outside this checkout. Contributing: awesome/CONTRIBUTING.md
Open source credits Source logic scripts/lib/open-source-credits.mjs, generator scripts/build-open-source-credits.mjs (wired into npm run prebuild) → data/open-source-credits.json, endpoint api/open-source-credits.js → GET /api/open-source-credits, page pages/open-source.html -> /open-source (src/open-source.js) Live Every third-party dependency, GPU worker model, and free asset source three.ws runs on, grouped by area (rendering, formats and compression, generation models, motion, voice, assets, infrastructure) with its license, upstream link, and what it powers on the platform. Three kinds of entry feed it: every direct npm dependency resolved from its own installed package metadata, hand-curated worker models whose license lives in each worker's README prose (including an honest "not declared upstream" for packages with none, rather than a guessed default), and asset sources like Poly Haven and the CC0 animation packs. A guard test (tests/open-source-credits.test.js) deep-equals a fresh buildCredits() run against the committed dataset, so a new direct dependency added without regenerating it fails the suite instead of rotting silently. In-surface credits point back here: Poly Haven on pages/objects.html and the object viewer (src/app-next-overlay.js), meshoptimizer and glTF-Transform in the Forge export dialog (src/forge-export.js), and studio-tier clip source/license in the animation gallery (src/animations-gallery.js). Docs: docs/open-source-credits.md → /docs/open-source-credits
Skill supply-chain scanner Scanner api/_lib/skill-supply-scan.js (acorn AST + prose rules), policy and moderation api/_lib/skill-scan-store.js, endpoints api/skills/scan.js → POST /api/skills/scan and api/skills/moderation.js → /api/skills/moderation, enforcement in api/skills/index.js, api/skills/[id].js and api/_lib/skill-candidates.js, rescan scripts/rescan-marketplace-skills.mjs, migration 20261024000000_skill_supply_scan.sql, publish form in pages/marketplace.html + src/marketplace.js Live Every skill version is scanned before it lists: secret access, undeclared network hosts (requires.network), dynamic or obfuscated code, injected or confirmation-skipping instructions. Verdicts clean, review (held for an admin) and blocked (422, cannot publish); authors get file, line and fix guidance. Docs: docs/skill-supply-scan.md. Tests: tests/skill-supply-scan.test.js
Suggested skills (skills from experience) api/_lib/skill-candidates.js, pure core api/_lib/skill-candidate-bundle.js, handler api/agents/[id]/skill-candidates.js → /api/agents/:id/skill-candidates, dashboard list src/dashboard/suggested-skills.js, MCP tool list_skill_candidates in api/_mcp/tools/custom-skills.js, migration 20261023130000_agent_skill_candidates.sql Live After a verified success (a multi-tool run with no error, a passed labor-escrow job, a closed profitable trade) the agent records a candidate with argument shapes only, drafts a skill/0.1 bundle (model writes prose, the handler is templated), validates it with the marketplace publisher's checks, and lists it on the agent dashboard. The owner installs it on that agent only, publishes it, or dismisses it; nothing installs or publishes without the click. A later run that deviates from an installed skill and succeeds appends a revision proposal instead of editing it. Test tests/skill-candidates.test.js. Docs: docs/skill-candidates.md
Agent Skills pack .agents/skills/ (canonical) → manifest .agents/skills/SKILLS.md, .agents/skills/skills-pack.json; published 3D subset public/skills/3d-studio/ → /skills/3d-studio/ In-repo; bundled in the three-ws-core plugin; 3D subset live on the site Portable SKILL.md folders (Agent Skills open standard) for any Claude surface, in five categories: 3d/creative (cross-platform-safe), platform/agents (create an agent, author and sell its skills, hire other agents, connect a client to the MCP servers), wallet/payments, intel/trading, ops/production. Counts live in the generated manifest, never here. The 3d/creative ones are also published as a public, downloadable bundle at /skills/3d-studio/ (three-ws-3d-skills.zip), which is what an OpenAI Plugin Directory submission uploads on its Skills tab; a skill referencing a tool api/_mcp-studio/ does not declare is dropped rather than shipped as a dead path. The same build renders the two entry-point skills from shared facts (scripts/lib/skill-md-facts.mjs): public/skill.md → /skill.md from data/skill-md.template.md, and the Grok variant public/grok-skill.md → /grok-skill.md from data/grok-skill-md.template.md (links and example calls checked by tests/grok-skill-file.test.js). Regenerate manifest: npm run build:skills-pack (drift gate npm run check:skills-pack); regenerate the published bundle: npm run build:openai-skills (drift gate npm run check:openai-skills, wired into npm run gate). Docs: docs/agent-skills.md
Standalone skill repos scripts/build-standalone-skill-repos.mjs → .data/standalone-repos/<repo>/ (gitignored) Generated on demand; publishing is owner-gated Assembles the three.ws-origin skills into small, publishable repos so an external user installs with one npx skills add nirholas/<repo> (or /plugin marketplace add nirholas/<repo>); npm run check:skills-spec validates every skill against the Agent Skills spec and npm run test:skills-install proves the install in a clean directory instead of cloning this monorepo: three-ws-skills (everything), three-ws-3d-skills (the crypto-free 3d/creative subset), three-ws-agent-economy-skills (wallet/payments + platform/agents). Each output is a complete one-plugin marketplace (.claude-plugin/{marketplace,plugin}.json, skills/, generated README.md with every trigger, LICENSE). Built from the same collectSkills() the manifest uses, so a copy cannot drift; nothing is committed here. npm run build:skill-repos, validate with npm run check:skill-repos (wired into npm run gate). Docs: docs/agent-skills.md
GitHub growth kit scripts/lib/repo-growth-kit.mjs, scripts/boost-github-repos.mjs, scripts/build-github-profile.mjs Live Brings every public repo on the nirholas account to discovery best practice, least-starred first: star and share block, AGENTS.md and llms.txt, community health files, tuned settings, plus the generated profile catalog repo. The mirror sync reuses the same module so it never erases the block. Repos about other crypto projects are held back until the owner approves. Docs: docs/github-growth.md
Claude Code plugin marketplace marketplace/ → plugins three-ws-3d, three-ws-developer In-repo · installable via /plugin marketplace add nirholas/three.ws 3D generation + rigged avatars inside Claude Code (free lane + paid x402 tools) and developer tooling for building on three.ws. Index: marketplace/README.md
SNS naming + pay-by-name api/sns.js, api/sns-subdomain.js, api/threews/subdomain.js, api/x402/pay-by-name.js, src/solana/sns-subdomain.js, pages/threews-claim.html In-repo *.threews.sol subdomain mint, x402 payments addressed by name. Env: THREEWS_SOL_PARENT_SECRET_BASE58
Self-hosted x402 facilitator + ring economy api/x402-facilitator/[action].js, api/_lib/x402/self-facilitator.js, api/x402/ring-settle.js, api/_lib/x402/pipelines/ring-rebalance.js, api/x402-ring.js, scripts/x402-ring-setup.mjs In-repo (off by default) Closed-loop agent-to-agent x402: platform wallets pay platform endpoints, settled in-house (no external facilitator). Fee-minimized, SOL-floor guarded, internal-labeled. Env: X402_SELF_FACILITATOR_ENABLED, X402_FEE_PAYER_SECRET_BASE58, X402_TREASURY_SECRET_BASE58. See docs/x402-ring-economy.md, docs/x402-settlement-pending.md
Pending x402 settlement (settlement_pending) api/_lib/x402/pending-settlements.js, api/cron/x402-settlement-reconcile.js, settle path api/_lib/x402-spec.js + api/_lib/x402/self-facilitator.js, migration api/_lib/migrations/20260917200000_x402_pending_settlements.sql Live The third settle outcome: a transaction that is broadcast but not yet confirmed answers settlement_pending with its signature instead of a failure the buyer's own wallet contradicts. A retry reconciles against the recorded signature rather than broadcasting a second transaction (the x402 PendingSettlementStore contract, Postgres-backed so it survives Cloud Run replica hopping), the endpoint still delivers with status:'pending', and the reconcile cron claims the settle credit and closes the books once the chain answers. Tunable: X402_SETTLE_CONFIRM_TIMEOUT_MS (12s default). Docs: docs/x402-settlement-pending.md. Tests: tests/x402-settlement-pending.test.js, tests/x402-settlement-pending-resource.test.js, tests/api/x402-settlement-reconcile.test.js
Fresh-wallet workers (x402 volume from never-used wallets) api/_lib/x402/fresh-workers/ (plan.js pure planning, chain.js fund + sweep legs, jobs.js job catalog + sinks, wallets.js lifecycle store, run.js the tick), cron api/cron/x402-fresh-workers.js fired by api/cron/economy-tick.js, stats API api/fresh-workers.js → /api/fresh-workers, runner scripts/x402-fresh-workers-run.mjs, migration api/_lib/migrations/20260922100000_x402_fresh_workers.sql Live (on by default) Every minute mints a few brand-new Solana wallets (secret-box encrypted, never mirrored into x402_ring_wallets), funds each in one transaction with exactly one job's USDC plus its own fees, has each self-pay a real x402 endpoint (a standard-tier Forge generation every N ticks, otherwise the next dataset in an 18-entry market-data rotation), lands the result where the site reads it (forge_autonomous_props → /forged with a fresh-wallet badge; x402_data_desk → /data-desk), then sweeps leftover USDC to the treasury, closes the token account (rent back to the funder) and drains the wallet to exactly zero. Stateful per wallet so an interrupted tick is finished by the next tick's reclaim pass; stranded wallets alert. Fresh wallets join ringAllowedAddresses() for a bounded window (X402_FRESH_WORKERS_MEMBERSHIP_HOURS) so the leak scanner classifies the funding leg as internal. Env: X402_FRESH_WORKERS_* (see .env.example). Docs: docs/x402-fresh-workers.md. Tests: tests/x402-fresh-workers.test.js
Wallet rescue (leaked-key recovery, dry run by default) and Jito tip accounts scripts/rescue-wallet.mjs, bundle builder atomic-rescue.js, tip source jito-tip-accounts.js In-repo CLI; --execute is owner-gated One atomic Jito bundle moves every token account and the SOL out of a compromised wallet, paid by a separate safe fee payer. Live getTipAccounts with a pinned fallback feeds the rescue, the MCP bundle tools and api/_lib/execution-engine.js. Runbook: docs/ops/wallet-rescue.md. Tests: tests/atomic-rescue.test.js, tests/jito-tip-module.test.js
Transaction landing race (several providers per signed trade, per-provider stats, tip ceiling) landing-race.js, provider table landing-providers.js, engine execution-engine.js, devnet proof scripts/landing-race-devnet.mjs Live in the engine; stats table migration pending apply The same signed tx is sent to every enabled provider, first confirmation wins, a failing provider is skipped until a probe passes, and landing_provider_stats keeps landed/lost/outpaced and latency. Doc: docs/transaction-landing-race.md. Tests: tests/landing-race.test.js
Ring payer pool (many distinct payers) api/_lib/x402/pool.js, api/_lib/x402/pipelines/ring-pool-fund.js, scripts/x402-ring-pool-setup.mjs, migration api/_lib/migrations/2026-07-17-x402-ring-pool.sql In-repo (off by default) Reused rotating payer wallets (500–1,000) the ring tick cycles through so the closed loop shows many distinct, attributed payers at 1 tx/settle. Keys secret-box-encrypted in x402_ring_pool; pubkeys mirrored into x402_ring_wallets(role='pool') so they join the controlled set automatically; NOT in solana-signers.js so sweepback never touches them. LRU rotation (claimNextPayer), batched threshold funding (ring-pool-fund). Env: X402_RING_POOL_ENABLED, X402_RING_POOL_SIZE. See docs/x402-ring-economy.md
$THREE micro-buy loop (x402 buy pressure) Endpoint api/x402/three-buy.js → /api/x402/three-buy, driver api/cron/three-buy-loop.js, engine api/_lib/token/microbuy.js, shared Jupiter client api/_lib/token/jupiter.js, ledger migration 20260717233000_three_microbuy.sql In-repo (off by default) Many tiny, real USDC→$THREE market buys per minute (target ~60/min), each triggered by (and paid through) a settled x402 call: the x402 toll routes to the ring treasury like every other endpoint, and the paid good is one on-chain buy on Jupiter. BUY-ONLY, never sells; accrued $THREE swept to the treasury. High-frequency sibling of the daily buyback (api/_lib/token/buyback.js). Real spend hard-bounded by a UTC-daily USD ceiling enforced atomically (Redis reserve-before-buy). autobuy:false in ring-catalog.js so the generic ring never fires it. Env: THREE_MICROBUY_ENABLED, THREE_MICROBUY_SECRET_KEY_B64 (or reuses the buyback wallet), THREE_MICROBUY_PER_TICK, THREE_MICROBUY_DAILY_CAP_USD. See docs/three-microbuy.md.
Money flow map pages/flow.html → /flow, pure graph math + force layout src/flow-map-core.js, canvas/DOM layer src/flow-map.js, styles src/flow-map.css, backend view api/pulse.js → GET /api/pulse?view=graph Live The TOPOLOGY of the agent economy, which every other economy surface here misses because a leaderboard cannot show shape. A force-directed canvas map of who paid whom, for which skill, and how much, built from two already-public on-chain sources: agent-to-agent x402 skill payments (meta.to payee wallet + meta.service) and tips (meta.from payer wallet). Every edge is a settled transfer with an explorer-verifiable signature; no inferred or estimated edges exist. Nodes are classified source / hub / relay / sink / quiet from flow asymmetry, which makes capital dispersion (value entering agent wallets and never circulating out) visible at a glance and puts a number on it as "stuck capital". Counterparty privacy matches the live feed: a wallet is NAMED only when it resolves to a public, non-opted-out agent, otherwise it stays an address-only dashed node. Keyboard and screen-reader parity is structural, not a bolt-on: the table below the canvas renders from the same filtered data and selecting a row selects the node. Docs: docs/money-flow-map.md. Tests: tests/flow-map-core.test.js
Economy funding root (master wallet) api/_lib/economy-master.js, cron api/cron/treasury-topup.js, registry api/_lib/solana-signers.js In-repo (inert until keyed) One master wallet (WwwuGbq…T3WwW, ECONOMY_MASTER_SECRET_BASE58) auto-tops-up every other Solana engine below its floor. Funder-only — never trades/settles; reserve/per-engine/per-run guarded; allowlisted to registry wallets; fee-minimized. See docs/economy-master.md + the signer registry api/_lib/solana-signers.js
Economy master audit ledger + breach monitor ledger api/_lib/economy-ledger.js (schema), reconcile cron api/cron/economy-reconcile.js, export scripts/economy-ledger-export.mjs In-repo Tamper-evident (SHA-256 hash-chained) accounting book of every SOL movement from the master, with running balance + USD-at-transfer-time. The reconcile cron checks it every 30 min for tamper, unrecorded on-chain outbound (breach/key-compromise), and on-chain integrity; findings land in payment_reconciliation. Accounting CSV/JSON export. See docs/economy-master.md
Economy wallet registry + rotation schema api/_lib/migrations/20260819010000_economy_wallet_registry.sql, operator script scripts/economy-wallets.mjs (npm run economy:wallets), runbook docs/ops/economy-wallet-rotation.md Live A durable log of every wallet each economy role has ever held, with lineage between them. api/_lib/solana-signers.js says what the economy uses now; rotating a signer overwrote an env var and the previous address survived nowhere, so reconciling an old settle meant guessing on-chain. economy_wallet_registry keeps one active wallet per role (enforced by a partial unique index, so a half-finished rotation cannot be left behind) plus the full retired history. Generates fresh vanity-prefixed keypairs, writes the secret to a 0600 file outside the repo, and prints the funding and cutover steps; it never stores secret material and never installs a key into production itself.
Earned autonomy (sniper fleet) tier engine api/_lib/sniper-autonomy.js, tier-scaled optimizer api/_lib/sniper-optimizer.js + cron api/cron/sniper-optimize.js, tier-weighted portfolio layer scripts/sniper-evolve.mjs + cron api/cron/sniper-evolve.js, judge knowledge pack workers/agent-sniper/judge-knowledge.js → workers/agent-sniper/llm-judge.js, board api/sniper/experiments.js + src/sniper-experiments.js → /sniper/experiments Live A trading arm's own realized record decides how much rope it gets, recomputed every optimizer run: probation → standard → trusted → autonomous. The tier scales how far and how fast the optimizer may move a knob, which fields it may touch at all (trusted unlocks the entry universe, the LLM confidence bar, and the take-initials ladder), how much of the fixed fleet budget the evolution loop concentrates on the arm, and how much real evidence the LLM judge is handed before it rules (base rate, learned signal weights, the arm's own record, the realized win-rate table, the model's own calibration). Decided on realized net P&L and average edge, never win rate, so a 36%-hit-rate arm that actually makes money earns room while a 60%-hit-rate arm that loses money does not. Symmetric: an arm that stops paying loses its tier on the next pass. No tier can reach a safety rail (firewall, Mayhem exclusion, price impact, concurrency, loss cap, fleet ceiling) and a bounded stop-loss survives every tier. Tests: tests/sniper-autonomy.test.js, tests/sniper-optimizer.test.js, tests/sniper-judge-knowledge.test.js. See docs/sniper-autonomy.md
Fleet stall diagnosis (why an arm is not trading) policy api/_lib/sniper-stall.js, funding invariant api/_lib/agent-funding-policy.js, operational floor MIN_OPERATIONAL_WALLET_SOL in api/_lib/agent-trade-guards.js, board field on api/sniper/experiments.js + src/sniper-experiments.js → /sniper/experiments, ops page workers/agent-sniper/alerts.js Live An armed arm can evaluate every launch and still never buy, because a skipped evaluation writes no row: four arms sat dead for a week behind a bare 0. Each armed strategy now reports a stall code the executor actually enforces (wallet_dry, mcap_band_unreachable, mcap_band_tight, strict_model_offline, size_over_budget, kill_switch, no_qualifying_launch), and the two arithmetic deadlocks behind them are gone: an entry clamps to the day's remaining budget instead of sitting out when size drifted above the cap, and the reclaim that pulls idle SOL back to the treasury can no longer take a trading wallet below one complete trade or below the level the auto-funder will instantly restore (the two crons were ping-ponging 0.24 SOL six times in 15 minutes). Tests: tests/sniper-stall.test.js, tests/economy-sweepback.test.js. See docs/trading-experiment.md, docs/economy-master.md
Capabilities command center page pages/dashboard-next/capabilities.html → /dashboard/capabilities, client src/dashboard-next/pages/capabilities.js, feeds api/sniper/status.js, api/sniper/strategy.js, api/agent/launcher.js, api/agent/market-maker.js Live One screen for all four autonomous capabilities across every agent the signed-in user owns: Alpha Hunt smart-money strategies, the scheduled pump.fun Coin Launcher (with a Launch Now trigger the worker picks up within 60s), Creator Auto-Claim fee harvesting (with a per-coin Claim action), and the Jito-executed Market Maker. Reads the whole account in four requests via the all=1 mode on both agent endpoints, refreshed every 30s; a lane that fails renders an in-place error with a working Retry rather than a zero, and the refresh preserves the open tab, scroll position, and any action still in flight.
Autonomous trading experiment policy scripts/trading-experiment-setup.mjs, laddered exit workers/agent-sniper/exit-logic.js (decideLadderedExit), no-Mayhem gate workers/agent-sniper/mayhem-gate.js, journal workers/agent-sniper/journal.js → api/sniper/journal.js In-repo One agent, ~10 SOL, newer pump.fun launches ($10k–$100k mcap, no Mayhem). Take-initials-at-2× laddered exit keeps a moon bag (never a 100% exit up), hard stop-loss underneath. Every decision journaled with its reasoning. UI-funded, simulate-first. See docs/trading-experiment.md
Wallet Portfolio (any-address viewer) aggregation api/_lib/portfolio-overview.js (pure, tested in tests/portfolio-overview.test.js), endpoint api/crypto/portfolio.js → /api/crypto/portfolio, page pages/portfolio.html + src/portfolio.js + src/portfolio.css → /portfolio Live Live portfolio for any Solana or Ethereum wallet: total value, 24h move with stated coverage, stable/major/token split, top-asset allocation donut, holdings table with dust folding. Solana fully keyless (Helius DAS or public RPC + Jupiter Lite + DexScreener); EVM needs ALCHEMY_API_KEY and 503s honestly without it. Docs: docs/portfolio.md. Wiring test: tests/portfolio-page.test.js
Atomic (Solana Transaction V1 inspector) decoder api/_lib/solana/transaction-v1.js, endpoint api/solana/atomic.js → /api/solana/atomic, page pages/atomic.html + src/atomic.js + src/atomic.css → /atomic In-repo Live mainnet V1 feature-gate status plus exact signed-wire inspection for a transaction signature or base64 handoff. Normalizes resource budgets across legacy, V0, and V1, reads V1 caps from transactionConfig, shows exact 1,232/4,096-byte utilization and confirmed compute use, and tells a paymaster whether the two execution limits are explicit before it co-signs. Read-only: never signs, simulates, or broadcasts. Docs: docs/atomic.md. Tests: tests/transaction-v1.test.js, tests/atomic-page.test.js
Airdrop Checker (any-address eligibility) scanner api/_lib/wallet-activity.js, evaluator api/_lib/airdrop-eligibility.js (pure, tested in tests/airdrop-eligibility.test.js), registry data/airdrops.json, endpoint api/crypto/airdrops.js → /api/crypto/airdrops, page pages/airdrops.html + src/airdrops.js + src/airdrops.css → /airdrops Live Scores any wallet's REAL on-chain activity against tracked airdrop criteria: Solana keyless (signature scan over the rotating RPC chain + balance-layer token diversity), EVM via Etherscan V2 behind ETHERSCAN_API_KEY. Unmeasurable fields report as unknown and never count as met; protocol-specific steps are unscored manual to-dos; capped scans flag totals as minimums. Cross-links with /portfolio and shares its recent-wallet list. Docs: docs/airdrops.md. Wiring test: tests/airdrops-page.test.js
Exit Lab (counterfactual exit replay) kernel api/_lib/exit-replay.js, corpus api/sniper/exit-lab.js → /api/sniper/exit-lab, page pages/exit-lab.html + src/exit-lab.js → /exit-lab Live Replays every REAL closed sniper position through the live decideLadderedExit with the exit rules changed, so the fleet can ask "were our exits right?" about SOL it already spent. The kernel is pure and is imported by BOTH the handler and the browser, so a slider move is instant and server and client can never disagree. Two-phase walk over the recorded path (entry to peak to final quote) mirroring the live partial-sell bookkeeping leg for leg. States its own limits on the page: earlier exits are exact, longer holds are a lower bound, laddered positions are excluded with a stated reason. Grid search is an exact enumeration, flagged as in-sample. Tests: tests/exit-replay.test.js, tests/exit-lab-page.test.js. Docs: docs/exit-lab.md, tutorial docs/tutorials/find-a-better-exit-policy.md
Shareable trade card (per closed trade) model api/_lib/trade-card.js, loader api/_lib/trade-card-store.js, image api/trade-og.js → /api/trade-og?id=, page api/trade-share.js → /trade/<position id>, share link on every closed row in src/trader.js Live The trader-level card answers "is this trader any good?"; this one answers "what just happened?" and is the artifact worth posting the minute a position closes. One closed agent_sniper_positions row becomes an SVG 1200x630 card (coin, result with its return multiple, SOL in/out, hold time, exit reason) plus an SSR page carrying per-trade Open Graph / Twitter / Farcaster meta, both legs linked to Solscan, and a one-tap post. Image and page render from ONE pure model, so the picture that unfurls and the page it lands on can never disagree about a number. Honest by construction: a loss renders exactly like a win, a simulate-mode fill is stamped PAPER and never counted as live, and a moon-bag exit says the position was not fully sold. Unknown, still-open or deleted trades fall back rather than break an unfurl. Tests: tests/trade-card.test.js
Trade receipts ("why it traded") model + loader api/_lib/trade-receipt.js, endpoint api/sniper/receipt.js → /api/sniper/receipt?id=, shared renderer src/shared/trade-receipt-view.js, drawer on src/trader.js → /trader/:id?trade=<id>, section on api/trade-share.js → /trade/:id, MCP tool trade_receipt in api/_mcp/tools/trader.js, tests tests/trade-receipt.test.js Live (read-only) Why an agent took one trade, from the rows its gates actually wrote: entry trigger, Oracle score and pillars at entry with the base-rate reasons behind it, the trade firewall verdict and checks (the simulated buy/sell round-trip included), the LLM judge thesis, the Risk Officer review, paid x402 sentiment and rug-pull reads with their payment tx, launch intel, and every journal leg with its signature. Each block is timed against the entry; evidence logged after the exit is dropped and evidence seen while holding is labeled as such, so a receipt never passes hindsight off as a reason. Same visibility gate as /api/sniper/trader. Doc: docs/trade-receipts.md.
Live trade rooms (spectate a trader trading live in 3D) Page pages/trade-room.html → /trade-rooms (lobby) and → /trade-rooms/:agentId (a room), controller src/trade-room/main.js, 3D scene src/trade-room/scene.js, pure model shared with the API src/trade-room/model.js, styles src/trade-room/trade-room.css; read model api/_lib/trade-room.js, spectator presence api/_lib/trade-room-presence.js, endpoints api/sniper/rooms.js, api/sniper/room.js, SSE api/sniper/room-stream.js Live Roadmap 12.13. Every public trader gets a room: their own 3D body (public or unlisted avatar, else the default rig) on a pedestal, a trade board and LED ticker tape, and one crowd figure per open viewer. The stream polls agent_sniper_positions for that trader and derives buys, sells and quote moves from timestamps, so fills land within about 2s and the avatar reacts (point on a buy, celebrate or slump on a sell). Each trade carries its receipt (/api/sniper/receipt), Solscan tx, /trade/:id card and a Fork; the room links to ghost-copy and copy. Quiet rooms show the latest real trades, when the trader last traded, and which rooms are live. Presence is a Redis sorted set per room with an in-process fallback. The canvas is mirrored by an accessible trade list with an aria-live announcer; devices that cannot hold the frame budget or lack WebGL get the list view and are told why. Linked from /trader/:id, the leaderboard hero and the nav. Docs: docs/trade-rooms.md. Tests: tests/trade-room.test.js
Trading growth programs (big-win X poster, first-rug softener, early-leader bonus) engine api/_lib/growth-programs/ (flags + caps config.js, big-win-x.js, rug-softener.js, early-leaders.js, capped payout leg payouts.js), crons api/cron/big-win-x.js + api/cron/growth-payouts.js, ops board api/ops/growth-programs.js → /api/ops/growth-programs, claim API api/sniper/rug-softener.js → /api/sniper/rug-softener, claim banner src/dashboard-next/rug-softener-banner.js on /dashboard/sniper, ledger migration api/_lib/migrations/20260929120000_growth_program_payouts.sql, report scripts/growth-programs-report.mjs Built, disarmed Roadmap 917 items 3.8, 12.15 and 13.4. Posts notable live wins to @trythreews (never naming the traded coin, linking the /trade/:id card, filtered like the changelog X lane), pays $THREE toward a first-timer's first verified rug, and pays a bounded $THREE bonus to the first leaders with a verified, followed record. The selection logic runs on live data and is inspectable at any time; posting and paying only run when BIG_WIN_X_ENABLED, RUG_SOFTENER_ENABLED or EARLY_LEADER_ENABLED is set, under rolling caps with code ceilings, from the Arena prize wallet (THREE_PRIZE_PAYOUT_KEY) via a Token-2022-aware transfer. Docs + owner arm steps: docs/growth-programs.md. Tests: tests/growth-programs.test.js
Never sell 100% of a winner (moon-bag policy) rule workers/agent-sniper/exit-logic.js (moonbagExitFraction, moonbagAlways), retained-bag booking workers/agent-sniper/executor.js, position fields api/_lib/migrations/20260725100000_sniper_moonbag_always.sql, board api/sniper/experiments.js + src/sniper-experiments.js → /sniper/experiments Live Fleet-wide owner rule: a terminal exit that is IN PROFIT sells down to the moon-bag floor (default 15%) instead of to zero, and the retained tokens ride indefinitely. Once the cost basis is back the remainder is free, so a bag that goes to zero costs nothing and a bag that runs is the whole upside; selling the last slice for a rounding error gives that up. Applies with or without the proactive 2x ladder. A loss exit with the stake still at risk is still a FULL exit and the hard stop-loss is never overridden. The position still books closed, so realized P&L and the max_concurrent_positions slot are unaffected and a held bag can never stop an arm trading; only the tokens stay behind (moonbag_base_amount). Per-strategy opt-out moonbag_always = false. Tests: tests/sniper-laddered-exit.test.js, tests/trading-experiment-e2e.test.js. See docs/trading-experiment.md
Autonomous Trading hub (front door) pages/trading.html → /trading + src/trading-hub.js, pure formatters src/trading-hub-format.js, surface + doc directory src/trading-hub-data.js, styles src/trading-hub.css Live One entry point for a trading system that had grown to ~20 pages with no front door. Live fleet vitals from GET /api/sniper/status (mode, armed strategies, open positions, feed health, funding, uptime), the agent scoreboard from GET /api/sniper/leaderboard (realized P&L only, closed trades only, with cumulative sparkline), the five-gate entry-to-exit explainer, and directories of every trading surface and doc. Feed health is reported separately from process health because a beating worker with a silent feed reads as green while seeing nothing. Directory is data, so tests/trading-hub.test.js asserts every link resolves against data/pages.json and the docs tree. Docs: docs/trading-hub.md, tutorial docs/tutorials/read-the-trading-fleet.md
Strategy Objects (settings, research gates, ask-before-trade) library and builder pages/strategies.html → /strategies (?editor=new), form + JSON editor src/shared/strategy-forms.js, live preview, text compiler box and gated backtest src/shared/strategy-settings.js, agent panel with mode switch, approvals and decision log src/shared/agent-strategy-panel.js; schema and gate evaluator api/_lib/strategy-schema.js, gate report api/_lib/strategy-research.js, approvals and decision log api/_lib/strategy-approvals.js, preview api/_lib/strategy-preview.js, runtime api/_lib/agent-strategy-runtime.js, APIs api/strategies.js → /api/strategies and api/agents/agent-strategy-objects.js → /api/agents/:id/strategies, migration api/_lib/migrations/20261010140000_strategy_research_gates.sql Built, ships with the next deploy Version 2 Strategy Objects: source filter, market cap band, SOL size, a price-impact cap that only tightens the agent breaker, nine research gates (holders, largest holder, liquidity, firewall score, mint and freeze authority, creator launches, graduations, dev sold) that fail closed on unknown data, and ask (default) or auto mode. Every blocked coin is logged with the check and reason; ask mode files a payload-hash approval that executes once after re-checking every guard. The builder edits one config through sliders, toggles and raw JSON, shows a live count of recent launches the settings would have bought, compiles plain English into the fields, and backtests with the gates applied. Doc: docs/strategy-objects.md. Tests: tests/strategy-research-gates.test.js, tests/strategy-schema.test.js
Sniper Experiments (rules vs LLM A/B fleet) pages/sniper-experiments.html + src/sniper-experiments.js → /sniper/experiments, aggregate api/sniper/experiments.js, LLM judge workers/agent-sniper/llm-judge.js, fleet seeding scripts/seed-sniper-experiments.mjs Live The sniper fleet runs labeled rule-set variants side by side (strict shields, oracle-gated, and decision_mode=llm arms judged per-launch by Grok / Claude / OpenRouter auto with no shields), all behind the same safety rails. The page is the live scoreboard of which entry conditions actually make money; real on-chain fills only.
Backtest integrity and research/live wall audit, manifests, reproducibility api/_lib/backtest-integrity.js, read-only handle api/_lib/research-context.js, canaries api/_lib/data-canaries.js + api/_lib/data-canary-health.js + cron api/cron/data-canary.js, import wall scripts/lib/research-wall.mjs, view src/shared/backtest-integrity-view.js Built, ships with the next deploy; scheduler sync owner-gated Look-ahead audit of the sniper entry gate on every backtest, dataset manifest with content hash (older results marked unreproducible), 30 minute price and candle canaries that reorder fallback chains, and a test that fails if research code can reach a live execution module. Docs: docs/backtest-integrity.md. Tests: tests/backtest-integrity.test.js
Arm your agent (Oracle conviction on autopilot) pages/arm.html + src/arm.js → /oracle/arm (also /arm), config + graded ledger API api/oracle/watch.js → /api/oracle/watch, alert test api/oracle/test-alert.js, verified Telegram chat lookup api/oracle/telegram-chat.js → /api/oracle/telegram-chat (the send-test box and follow panel only accept this linked chat id), live stream api/oracle/feed.js, proof of edge api/oracle/backtest.js Live The rules screen that turns an Oracle score into an agent that acts. Four steps: the conviction floor (Prime / Strong+ / Lean+, each showing its real 30-day win rate, average peak and 3x count for that exact bar), position sizing with hard daily and open-position caps, an optional personal Telegram alert with a send-test button, and simulate-or-live arming. Beside the form is a live preview of every coin clearing the rules as they stand, updated every 20 seconds, with the size the agent would commit to each: tighten the bar and the list shrinks in front of you. The agent spends only from its own custodial Solana wallet, whose balance and remaining trade runway sit in the control bar, and every action it takes is graded against the outcome in the ledger below. The conviction preview and edge readout are public endpoints, so a signed-out visitor sees the product working before being asked for an account. Arming in live mode is gated on the shared risk acknowledgement (src/shared/risk-ack.js).
Oracle Lab (the conviction model, published) pages/oracle-lab.html + src/oracle-lab.js → /oracle-lab, model API api/oracle/model.js → /api/oracle/model, SDK packages/oracle-model/ → @three-ws/oracle-model Live The glass box over the Oracle. Publishes the scoring model itself, not a summary of it: every bucket weight with the number of labeled launches behind it and what happened to them, the held-out reliability curve for each tier claim, the version history of every refit INCLUDING the candidates the promotion gate refused and why, and a scorer that runs the real weights in the visitor's browser. The model is a lookup table (~32KB), so @three-ws/oracle-model downloads it once and reproduces any score offline with no key, no rate limit and no telemetry; verify() re-measures our published AUC/Brier/reliability against a caller's own labeled outcomes, and diff() shows every weight that moved between two versions. ?view=registry and ?view=diff&from=&to= serve the same data server-side. Docs: docs/oracle-model.md → /docs/oracle-model. Tests: packages/oracle-model/test/ (23), tests/oracle/fit.test.js (43)
Oracle conviction model (three heads, learned on a clock) Fitter api/_lib/oracle/fit.js, scorer api/_lib/oracle/conviction.js, DB-backed weights api/_lib/oracle/model-store.js, learning loop api/cron/oracle-refit.js (every 6h), CLI scripts/oracle-fit.mjs Live, v3 v2 ranked "spikes 3x or graduates", so a coin that ran 3x and went to zero counted as a hit: Prime-tier coins hit that target 58.2% of the time and rugged 53.0% of the time. v3 fits three heads over one design matrix (win = ran and the holder kept it, rug = holder down more than half, moon = ran at all) and anchors the public score on win, publishing giveBackRisk = 1 - P(win)/P(moon) beside it: given it runs, how often a coin like this hands the run straight back. Weights moved out of the container image into oracle_model_versions, so the refit cron can promote a better model between deploys; it was frozen at its 2026-08-09 fit for nineteen days because nothing but a human could refit it. Every candidate faces a promotion gate (complete fit, absolute AUC floor, every tier band still earning its claim, no feature-set collapse, a material gain over the incumbent, no regression on the other heads) and is stored either way with the reason. Thin buckets are shrunk toward zero by n/(n+200) so 34 samples cannot reverse a verdict. Docs: docs/oracle-model.md
Price-independent outcome labels workers/agent-sniper/intel/learn.js deriveOutcome, migrations 20260828170000 + 20260828190000 Live The rug flag was a readout of the SOL price. It was decided by "market cap under $3,000", and an empty pump.fun bonding curve is worth a fixed 30 * 1e9 / 1073000191 = 27.958993 SOL, so the test amounted to asking whether SOL was above about $107.30 that day: of 206,428 coins labeled rugged, 206,419 were under $3,000; of 25,180 labeled survivors, the cheapest was exactly $3,000. Same dead curves, sorted by a price feed. Labels now use retained = last_mc/ath_mc and hold_multiple = ath_multiple * retained, both taken from the same reading so the price cancels; the real rug rate is 11.4%, not 91%, and it holds within two points from 60 minutes to three days. label_version marks which rule judged a row and the fitter trains on version 2 only. The training-set upsert also stopped being do nothing, which had made a written label permanently uncorrectable.
Coin Intelligence (the read the sniper trades on) pages/coin-intel.html → /coin-intel (self-contained page: markup, styles and module script in one file), read API api/pump/intel.js → /api/pump/intel, serverless firehose api/cron/coin-intel-observe.js, shared finalize path workers/agent-sniper/intel/finalize.js Live The public dashboard over the Coin Intelligence engine: every pump.fun launch observed for its first ~90 seconds, classified, scored 0..100, and labeled by outcome after the fact. Four views off one endpoint (view=feed live radar with category/verdict/quality/search filters, view=leaderboard best of 24h plus confirmed graduated/pumped winners, view=traders cross-coin wallet reputation with real win-rates, view=learning the per-signal weights the model learned). A coin's card opens a drawer with its launch signals, trade footprint, risk flags, a funder-cluster bubble map, the classified order book, and Oracle conviction fetched in parallel from api/oracle/coin.js. Reads pump_coin_intel / pump_coin_wallets / pump_coin_outcomes / pump_intel_weights, all written by the engine; the endpoint never writes and degrades to a designed "engine warming up" state (200 with degraded:true) when those tables are absent. traders and learning are whole-history aggregates and are edge-cached for minutes; the radar stays on a 5s cache and auto-refreshes every 15s. Watchlist stars share the ld_watchlist key with /oracle, /launches and /watchlist.
Fade Radar (the inverse of smart money) page pages/fade.html → /fade, client src/fade-radar.js, read layer api/_lib/fade-radar.js, API api/pump/fade.js → /api/pump/fade, tests tests/fade-radar.test.js Live The question the Smart Money Radar cannot ask: how much of a coin's buy side has never once been right. A reverse indicator is a wallet the graph has watched buy 5+ coins whose outcome is known with zero winners among them, read live from the same smart_wallet_reputation graph the firewall and the sniper scorer use, so the fade side needs no job of its own. Three boards off one endpoint (live coins ranked by fade score, the reverse-indicator wallets themselves, and the calibration), plus a per-mint read agents can gate on. The verdict bands carry a measured, out-of-sample number rather than a claim: the cohort is rebuilt from coins labelled in the earlier half of the history and graded on the later half, where avoid coins won 1.8% against a 22.1% baseline over 26,626 labelled coins, recomputed at most every 12 hours into app_settings. Never a short and never a trade: on a bonding curve the only tradeable fade is not buying. Docs: docs/fade-radar.md
Recording Pipeline (is the data loop actually running?) pages/pipeline.html → /pipeline (self-contained page: markup, styles and module script in one file), one-call status API api/pipeline.js → /api/pipeline, shared derivation api/_lib/pipeline-summary.js Live One board for the whole closed loop that turns a pump.fun launch into a trade signal: the always-on recorder (workers/agent-sniper), signal intel, ground-truth outcomes, Oracle conviction, the wallet reputation graph, trained per-signal weights, and the agents trading on the result. Seven stage cards, each linking into the surface that owns it, over one endpoint that queries every stage independently so a cold worker or a table that does not exist yet reports an honest zero rather than failing the whole response. The recorder is network-scoped: bot_heartbeat is keyed by worker alone, so asking about devnet while the worker records mainnet answers offline with a reason instead of lending one network's liveness to the other. The board polls every 8s and patches its cards in place, so a card the user tabbed to keeps focus and only the one-line health summary is announced. next_action is the same machine-readable recommendation the page renders as its call to action, so an agent reading the JSON and a person reading the page get one answer. Docs: docs/api-reference.md (Recording Pipeline API). Tests: tests/pipeline-summary.test.js
Agent voice cloning (your voice, on your agent) Capture + BYOK panel src/voice/voice-setup.js (VoiceSetup), mounted as step 5 of the create wizard (src/create-agent.js → /create-agent), in the agent editor, and in the talk-mode shell src/voice/voice-clone-modal.js; server api/agents/_id/voice.js → GET/PUT/DELETE /api/agents/:id/voice + POST /api/agents/:id/voice/clone; credential resolver api/_lib/agent-voice-key.js; playback config mapper agentVoiceConfig in src/runtime/speech.js, consumed by the hosted embed pages/agent-embed.html → /agent/:id/embed and the SDK runtime src/runtime/index.js In-repo · BYOK live, platform lane awaits a key Record or upload 30+ seconds and the agent speaks in that voice everywhere on three.ws. Three credential lanes, and they are not interchangeable: a clone only exists inside the ElevenLabs account that made it, so the winning lane is recorded on agent_identities.voice_key_source and replayed on every synthesis. BYOK is the activation path today (no platform ELEVENLABS_API_KEY is set on the service), and the panel renders inline key entry rather than a dead "not configured" message; setting that one variable lights up the platform lane, metered to $THREE credits. /api/tts/eleven only spends an owner's key when the request names the agent, which is what lets a bound voice speak to signed-out visitors inside a cross-origin embed. Docs: docs/tutorials/voice-and-lipsync.md, src/voice/README.md. Tests: tests/api/agents-voice.test.js, tests/runtime/agent-voice-config.test.js
Trading Copilot (conversational) client src/agent-copilot.js, hub tab src/agent-wallet-hub/tabs/copilot.js, server api/agents/copilot.js → POST /api/agents/:id/copilot (SSE) In-repo Owner-only chat over an agent's Solana wallet: text/voice in, markdown replies, live data cards (portfolio, firewall, quote, smart-money, intel) and confirm-before-execute trade/limits cards. Read-only tools run server-side; state-changing intents return as proposals the browser re-quotes and runs through the existing spend guards + firewall + custody audit. Slash commands, copy/regenerate, localStorage persistence. See docs/trading-copilot.md
Alpha Co-pilot (the agent narrates its own read) page pages/alpha-copilot.html → /alpha-copilot, client src/alpha-copilot.js, styles src/alpha-copilot.css, profile cross-link src/shared/alpha-copilot-link.js, server api/agents/alpha.js → GET /api/agents/:id/alpha/candidates + POST /api/agents/:id/alpha/read, grounding + scrub api/_lib/alpha-read.js Live The intelligence and voice layer on the same trade rails the Trading Copilot uses: pick a public agent from a real gallery, pick a real live pump.fun mint off the candidate feed, and the agent reads it in character while its <agent-3d> avatar speaks the verdict aloud (agent TTS provider, then the free server lane, then browser speech). Every figure it says is validated against the signals bundle the server actually fetched (bonding-curve state, a real non-binding reference buy quote for true price impact, graduation progress, smart-money wallets, and for the owner the wallet balance and spend limits); a mismatch replaces the line and raises hallucination_guard.line_replaced, which the page surfaces rather than hides. The narrator never signs: acting on a read is an owner-only drawer that re-quotes through previewAgentTrade and executes through executeAgentTrade, so the spend policy, firewall, and custody audit all still apply. Docs: docs/alpha-copilot.md
Social recovery & inheritance (guardian console) page pages/guardian.html -> /guardian + client src/guardian.js, inbox api/agents/recovery-inbox.js -> GET /api/agents/recovery-inbox, per-agent actions api/agents/recovery.js -> /api/agents/:id/recovery/..., rules api/_lib/agent-recovery.js, owner-side tab src/agent-wallet-hub/tabs/recovery.js, schema api/_lib/migrations/20260623100000_social_recovery.sql Live The other side of a locked-out or departed owner. The owner names guardians, an approval threshold and a beneficiary from their agent's wallet hub; the guardians and beneficiaries act from /guardian, which lists every agent they are trusted to protect with the open recovery or inheritance process, the reason the requester gave, who has already voted, the safety-window and expiry countdowns, and their own approve / decline / confirm / complete actions. A key is never decrypted or exported: completing a process re-points ownership only. The requester cannot approve their own takeover, an open request freezes autonomous spend, threshold approvals start a 48h time-lock, and the real owner's return cancels the whole thing. Inheritance is a dead-man's switch armed from real owner activity plus a grace window. Docs: docs/guardian.md, docs/custody.md. Tests: tests/agent-recovery.test.js, tests/api-agents-recovery-handler.test.js
Master wallet (per-user custodial hub) page pages/wallet.html → /wallet + controller src/master-wallet.js, client src/wallet-api.js, styles public/master-wallet.css; API api/user/wallet/index.js (create + balances), send.js, fund-agent.js, history.js; schema master_wallets In-repo One custodial Solana + EVM keypair per USER account (distinct from per-agent wallets): hold SOL/USDC across Solana and Base, top up any agent you own, send to any Solana address, and read history straight from chain. Session-cookie auth only, so no API key or agent can ever spend it; writes are CSRF-guarded and capped at 5 outbound transfers per user per day. The page prices every send through the server's simulate path first and requires an explicit confirm showing recipient, amount, asset and network before anything is signed. NOT src/wallet.js, which connects an external Phantom/Seed-Vault wallet. Docs: docs/user-wallet.md. Tests: tests/master-wallet-page.test.js
Real-funds agreements (signature gate) dialog public/risk-ack.js, app wrapper src/shared/risk-ack.js, server enforcement api/_lib/real-funds-agreement.js, sign/status endpoint api/legal/risk-ack.js, review page public/legal/agreements.html → /legal/agreements, documents public/legal/tos.html, public/legal/risk.html, public/legal/agent-wallet.html → /legal/agent-wallet, coverage guard tests/real-funds-agreement-coverage.test.js In-repo Before any real-funds action (deposit address reveal, tip, trade, snipe, withdraw, send, swap, launch, x402, onramp, autopilot arm) a person signs the Terms of Service, Risk Disclosure, and Agent Wallet Agreement: one checkbox per document, eligibility and no-liability attestations, and a typed-name e-signature. Signatures land append-only in legal_signatures with document versions and text fingerprints. Every custodial money endpoint calls requireRealFundsAgreement(), which answers 403 risk_ack_required for unsigned accounts (session and API key alike); devnet exempt. See docs/risk-acknowledgment.md
Global markets + coin detail pages pages/coins.html + src/coins-index.js → /coins, pages/coin.html + src/coin-page.js → /coin/:id, backend api/coin/ (detail, tickers, ohlc, pool, markets, news, global over api/_lib/coingecko.js) In-repo CoinGecko-style markets index (global stats bar, sortable top-coins table, search, sparklines) + a rich detail page per coin: interactive chart with a source switcher (native CoinGecko line chart, TradingView advanced candlesticks, or the DexScreener / GeckoTerminal on-chain terminal, each shown only when it can chart the coin; GeckoTerminal's pool resolved via api/coin/pool.js; the same provider list, DEXTools included, is one tab away on every other coin chart through the compact src/shared/chart-switcher.js, which /trades, Mission Control, /oracle/coin/<mint> and the /pump-dashboard market chart mount, the buildless Oracle page from the stable /chart-switcher.js bundle; tests tests/chart-switcher.dom.test.js), 1h→1y price-performance matrix, market-stats grid, circulating/max supply bar with Mcap/FDV ratio, ATH/ATL with drawdown & recovery multiple, community sentiment vote split, community + developer (GitHub) activity grids, a paginated exchange-listings table (api/coin/tickers, ±2% depth + trust) linking into exchange detail, related news, and full link pills (site/social/whitepaper/forum/chat/explorers). Design adopted from cryptocurrency.cv; accepts CoinGecko slugs or Solana mints. Docs: docs/coin-pages.md
Global Intel Globe (/globe) Page pages/globe.html -> /globe, renderer src/globe-intel.js, pure logic src/globe-intel-core.js, styles src/globe-intel.css; API api/globe/intel.js over api/_lib/globe-sources.js and api/_lib/globe-centroids.js; ingest api/cron/globe-ingest.js -> globe_events; reference set data/globe-reference.json, geometry baked by scripts/build-globe-geometry.mjs into public/data/globe-land.json + data/country-centroids.json Live A 3D globe of what is happening on Earth right now. Eleven layers on one sphere: armed conflict, force posture and sanctions classified out of the GDELT 2.0 event stream by CAMEO code, attention hotspots computed from them, natural events (USGS, NASA EONET, GDACS), severe weather (GDACS), national internet outages (Georgia Tech IODA), economic stress (World Bank), and the reference geography that gives the live layers meaning: overseas military bases, nuclear sites, and maritime chokepoints that score themselves against the live feed rather than sitting still. Every upstream is keyless, so the page works on a fresh clone. GDELT publishes one file every 15 minutes and no queryable history (its GEO 2.0 API 404s for every query), so the 24h/7d/30d control is only honest because the cron keeps the window in Postgres; each layer reports the span it actually covered and the panel prints "Covers 15h so far" rather than implying a week. A dead upstream renders as a named layer with its reason, never as an empty globe. Camera, zoom, projection, range and layer selection all live in the URL, so any view is a shareable link. Globe and flat map are the same geometry lerped between two projections, written into position rather than a vertex shader so every marker stays pickable in both. Docs: docs/globe.md. Tests: tests/globe-intel-core.test.js, tests/globe-sources.test.js
Token in 3D (/coin3d, embeddable) pages/coin3d.html + src/coin3d/main.js → /coin3d; pair bridge api/coin/pair.js → /api/coin/pair over tokenForPool() in api/_lib/market/ohlcv.js In-repo Any Solana token as a live 3D scene: logo medallion, holder galaxy sized by balance, graduation ring, and a tape of real swaps, all from on-chain and live market data, degrading to a data view where WebGL is unavailable. Addressable two ways: ?mint= (what three.ws keys tokens by) or ?pair= (what every DEX terminal keys a market by), resolved through /api/coin/pair, the inverse of api/coin/pool.js. ?embed=1 plus frame-ancestors * on the route make it framable on any site, with one attribution link as its only added chrome. Tests: tests/api/coin-pair.test.js (route contract), tests/api/coin-pair-resolver.test.js (the resolver and its fallback). Docs: docs/coin3d-embed.md
DEXTools hub + Boost card embed (/dextools, /embed/dextools-boost) pages/dextools.html + src/dextools-hub.js → /dextools; pages/dextools-boost-embed.html + src/dextools-boost-embed.js → /embed/dextools-boost; input parser src/dextools-input.js; visit totals api/coin/dextools-stats.js → /api/coin/dextools-stats over dextools_referrals (written by the counted redirect api/coin/dextools.js) In-repo Every three.ws x DEXTools integration on one page: the $THREE DEXTools chart beside its /coin3d?pair= scene, public visit totals by day, surface and coin, an embed builder that turns any pasted DEXTools / DexScreener / GeckoTerminal / pump.fun / Birdeye link into a 3D-scene or Boost-card snippet with live preview, and the Social Boost wins. The Boost card embed mounts the shared socialBoostCard() (src/shared/dextools-boost.js) with every link counted as embed-boost, framable anywhere (frame-ancestors *). Tests: tests/dextools-input.test.js. Docs: docs/dextools.md
Chart Companion (/chart-companion, embeddable, OBS overlay) pages/chart-companion.html + src/chart-companion/main.js → /chart-companion; reaction engine src/chart-companion/reactor.js; input parser src/chart-companion/target.js In-repo A live DEXTools chart with a 3D <agent-3d> companion that reacts to every real swap (/api/pump/dex-trades, polled): whale buys, dumps, streaks and new 24h highs each get a clip from the shared animation library, a facial emotion and one line built from the swap, with a feed linking every reaction to its transaction. Sizes are judged against the coin's own rolling median, so it works on any coin. Addressed by DEXTools link, ?pair= or ?mint=; ?agent= brings your own agent; ?embed=1 frames anywhere (frame-ancestors *); ?overlay=1 is a transparent OBS browser source. Tests: tests/chart-companion-reactor.test.js, tests/chart-companion-target.test.js. Docs: docs/chart-companion.md
Market tools (heatmap, sentiment, gas, compare) pages/heatmap.html + src/heatmap.js → /heatmap, pages/fear-greed.html + src/fear-greed.js → /fear-greed, pages/gas.html + src/gas.js → /gas, pages/compare.html + src/compare.js → /compare; backend api/coin/fear-greed.js, api/coin/gas.js In-repo Four tools extending Markets, same design system: treemap heatmap (market-cap-sized tiles), Fear & Greed gauge + history, live Ethereum gas tracker (keyless eth_feeHistory), and up-to-4-coin compare (overlay perf + stats). All real key-free data; cross-linked from the markets table. Docs: docs/coin-pages.md
Market tools II (screener, categories, exchanges, derivatives, converter, DeFi, chains, stablecoins) Pages+JS → /screener /categories /exchanges /derivatives /converter /defi /chains /stablecoins; backend api/coin/ (categories, exchanges, derivatives, rates) over CoinGecko + api/defi/ (protocols, chains, stablecoins) over DeFiLlama In-repo Eight more Markets tools, same design system: token screener + category rankings + exchange/derivatives tables + crypto⇄fiat converter (CoinGecko), plus a DeFiLlama trio — DeFi TVL by protocol, chains by TVL, stablecoins with peg health. All real key-free data; cross-linked from the markets table. Docs: docs/coin-pages.md
Market surfaces III (protocol/chain/stablecoin detail + fees, DEX volumes, hacks, trending) Detail pages → /protocol/:slug /chain/:name /stablecoin/:id over api/defi/protocol.js, api/defi/chain.js, api/defi/stablecoin.js; surfaces → /fees /dex-volumes /hacks over api/defi/ (fees, dex-volumes, hacks over DeFiLlama) + → /markets/trending over api/coin/trending.js (CoinGecko /search/trending); list rows in src/defi.js, src/chains.js, src/stablecoins.js now deep-link into the detail pages In-repo Turns the DeFiLlama list pages into full detail experiences: a protocol page (TVL history + hallmark markers, per-chain breakdown, fees/revenue, funding rounds, methodology), a chain page (TVL + stablecoin + DEX-volume charts, top protocols), a stablecoin page (supply history, per-chain distribution, peg-deviation badge). Plus three new market surfaces — protocol fees & revenue, the DEX-volume leaderboard, and a searchable DeFi hacks database ($16.7B all-time) — and a CoinGecko trending page (most-searched coins/categories/NFTs). All real key-free data, cross-linked. Docs: docs/coin-pages.md
Market detail pages (exchange, category) + DeFi yields pages/exchange.html + src/exchange-page.js → /exchange/:id over api/coin/exchange.js, pages/category.html + src/category-page.js → /category/:id over api/coin/category.js + api/coin/markets.js (?category=), pages/yields.html + src/yields.js → /yields over api/defi/yields.js In-repo Rich detail pages that turn list rows into full profiles. Exchange: trust badge, normalized-volume stat, BTC-volume history chart, and a per-pair markets table (spot + derivatives fallback), reached from /exchanges and the new Derivatives Exchanges table. Category: rank, sector stats, the full sortable coins table for that sector, and related categories, reached from /categories. Yields: an explorer over ~15k live DeFiLlama pools with chain/project/stablecoin/min-TVL filters, APY/TVL sort, URL-synced state, and a per-pool APY+TVL history chart on row expand. Docs: docs/coin-pages.md
Perpetual contract detail page pages/derivative.html + src/derivative-page.js + src/derivative-page.css → /derivative/:venue/:symbol over api/coin/derivative.js; slug helper src/shared/derivative-slug.js vendored to api/_lib/derivative-slug.js; venue directory api/_lib/derivative-venues.js In-repo Every row of /derivatives now opens a full contract page instead of dead-ending in the table: mark price against its own index and the basis between them, the funding rate turned into what a position you size yourself pays per interval, per day and per year, open interest and volume with the contract's rank across every venue listing that underlying, the underlying's spot chart, and a cross-venue funding table with callouts for the cheapest venue to hold a long, the best paid venue to hold a short, the funding spread and price dispersion (liquid venues only). Also reached from the contracts table on a derivatives venue's /exchange/:id profile. Tests: tests/api/derivative-contract.test.js. Docs: docs/coin-pages.md
Crypto news + archive + markets hub pages/markets.html + src/markets-page.js → /markets, pages/markets-news.html + src/markets-news.js → /markets/news, pages/news-article.html + src/news-article.js → /markets/news/article, pages/news-archive.html + src/news-archive.js → /markets/archive, pages/news-digest.html + src/news-digest.js → /markets/digest; backend api/news/ (feed, article, knowledge, archive, digest, rss, image) over api/_lib/article-extract.js (page→reader→feed→preview ladder) and api/_lib/news-rights.js (publisher rights layer, enforced at every read path), api/_lib/news-coins.js (ticker→live market snapshot), api/_lib/news-knowledge-store.js (durable news_knowledge corpus) + hourly archiver api/cron/news-archive-append.js over api/_lib/news.js + api/_lib/news-sources.js, corpus on gs://three-ws-news-archive, purge tooling scripts/news-takedown-purge.mjs In-repo The Markets news wing + front door: /markets/news is “Your briefing”: live news aggregated natively from 197 publisher feeds (Featured/Trending/Saved tabs, breaking ticker, AI briefing card, top-stories hero + rail, search, sentiment, ticker chips, og:image preview resolution for imageless feeds), a rich article reader that shows a bounded lead excerpt plus our own summary/key points/entities/market context and sends the reader to the publisher for the rest (the excerpt cap and any rightsholder takedowns are enforced server-side across the reader, RSS mirror, archive search, and agent knowledge corpus, never just hidden client-side), and renders live coin cards (price/24h/7d/sparkline→/coin/:id) for detected tickers, and related coverage. Every read story is recorded to a durable news knowledge base (GET /api/news/knowledge) that grounds the 3D agents, itself subject to the same excerpt limit. Plus the largest open crypto-news archive (662,047 enriched articles, Sept 2017 → today, EN+中文, GCS-hosted) and the /markets hub aggregating global stats, the top-100 table, breaking news, and every market surface as a hero card. Docs: docs/coin-pages.md, docs/api-reference.md, docs/news-rights.md (publisher takedown path)
Robinhood Chain markets + buy flow Hub + detail pages pages/markets-robinhood.html + src/markets-robinhood.js → /markets/robinhood, pages/robinhood-stock.html + src/robinhood-stock.js → /markets/robinhood/stock/:symbol, pages/robinhood-coin.html + src/robinhood-coin.js → /markets/robinhood/coin/:address, buy flow src/robinhood-purchase.js, wallet desk pages/hood-desk.html + src/hood-desk.js + src/hood-desk.css → /markets/robinhood/desk; backend api/_lib/robinhood.js + api/v1/robinhood/{chain,stocks,stocks-detail,coins,coins-detail,launches,desk,wallet}.js (free, the last two composed for the desk over api/_lib/robinhood-desk.js) + api/x402/robinhood-portfolio.js (x402 paid) In-repo The 24/7 tokenized-equity board for Robinhood Chain (4663): live Chainlink NAV vs. Uniswap DEX premium for every Stock Token (one multicall, never 95 RPC calls), a memecoin screener across NOXA/The Odyssey launchpads (CoinGecko categories + on-chain launch logs via Blockscout), and chain TVL/gas/block stats. Detail pages add NAV history, holders, transfers, and contract links. Coin pages carry a real buy panel: injected-wallet connect, chain-switch to 4663, live Uniswap v3 QuoterV2 quote + SwapRouter02 swap with slippage, LI.FI bridge deep-link; Stock Tokens are display-only (tokenized securities, not offered to US persons) with an eligibility-gated outbound DEX link instead. Paid portfolio endpoint returns ERC-8056 uiMultiplier-correct holdings. The Hood Desk (/markets/robinhood/desk) is the wallet-first view of the same chain: paste or connect any address and it loads that wallet's book (native + priced ERC-20 positions), its native balance curve rebuilt from Blockscout's daily and per-transaction feeds (the public RPC is not an archive node), an activity tape that folds token transfers onto the transaction that emitted them, the NAV premium ridge layered by liquidity floor, counterparty flow, and memecoin movers. Read-only and signature-free; the trade ticket reuses the coin pages' swap panel and the Stock Token eligibility gate. Tests: tests/robinhood-desk.test.js (the derivations) and tests/e2e/hood-desk.spec.js (the panels, the empty states, the ladder collapse and the trade ticket). Docs: docs/robinhood-chain-markets.md
$THREE launchpad (native bonding curve) Page pages/three-launchpad.html + src/three-launchpad/ → /three-launchpad; backend api/_lib/native-launch/ + api/native-launch/[action].js; lane toggle in public/studio/launch-panel.js; config + devnet scripts scripts/native-launchpad-*.mjs In-repo · code-complete, mainnet config creation owner-gated (about 0.006 SOL) Solana. Every coin launched on the lane is quoted in $THREE on Meteora's Dynamic Bonding Curve: buys are made with $THREE, creators earn 50% of the 1% fee in $THREE, and graduation (60M $THREE market cap, about 12.3M $THREE raised) locks 100% of LP in a DAMM v2 pool against $THREE. Public buy and sell via swap-prep, no session needed. Verified by a keyless mainnet simulation that creates the config and a $THREE-quoted pool against the live program. Docs: docs/native-launchpad.md
Uniswap v4 hooks (EVM) contracts/v4-hooks/: SkinHook + SkinToken (wearable 3D items as coins), AgentTierHook (ERC-8004 reputation fee tiers), CREATE2 address mining and deploy scripts; hook census scripts/uniswap-v4-hook-census.mjs (decodes permission bits, flags HookForge hooks), HookForge catalog generator scripts/gen-hookforge-catalog.mjs over the pinned snapshot data/hookforge-registry.json In-repo · contracts code-complete and tested against real v4-core and a live Base fork, not deployed (owner-gated) Additional EVM surface, Solana stays the home chain. SkinHook: every wearable is a fixed-supply ERC-20 with its own ETH pool; equipping locks one whole token in the hook so each wearer shrinks the float, a 2% ETH-side fee is split creator / referrer (named in hookData, the embed that sold it) / treasury as ERC-6909 claims, and the whole supply is seeded as one permanent single-sided position. AgentTierHook: dynamic LP fee by ERC-8004 standing, read from the canonical registries with a pool-configured reviewer set, cached by a permissionless refreshTier, every registry failure resolving to the base fee. v4-core vendored at v4.0.0 under contracts/v4-hooks/lib. Docs: contracts/v4-hooks/README.md, docs/uniswap-v4-hooks.md
Robinhood Chain coin launches (Pons) Page pages/launch-robinhood.html + src/launch-robinhood/page.js → /launch/robinhood; HTTP api/agents/pons/[action].js (POST /api/agents/:id/pons/{quote,launch}); custodial launch api/_lib/evm-leg/pons-launch.js; calldata, curve math and launch feed api/_lib/pons.js; agent skill src/agent-skills-pons.js (pons-launch) In-repo An agent launches a coin on Pons V2 (ETH bonding curve graduating into a locked Uniswap V4 pool) from its own EVM wallet, with an atomic opening buy and the quoted economics pinned on chain. Same gates as every custodial spend: ownership, platform-signing mode, real-funds agreement, per-chain USD spend policy with a pending ledger row before send, audited key decrypt. Landed coins go to fixed_supply_launches (chain robinhood, venue pons) so /launches and agent profiles list them. The same module feeds Pons launches (curve price, market cap, graduation %) into /api/v1/robinhood/launches. Tests: tests/pons.test.js rebuilds real mainnet launches byte-for-byte. Docs: docs/pons-launch.md
Paired coins (Robinhood Chain, multi-quote launchpad) Hub pages/paired-coins.html + src/paired/hub.js → /markets/robinhood/paired, coin page pages/paired-coin.html + src/paired/coin.js + trade ticket src/paired/trade.js → /markets/robinhood/paired/:address, launch page pages/launch-paired.html + src/paired/launch.js → /launch/paired; reads api/_lib/paired-launchpad.js + api/_lib/paired-markets.js + api/_lib/paired-directory.js + api/_lib/paired-trades.js behind api/v1/robinhood/paired-{markets,coins,coins-detail}.js (free); custodial launch api/_lib/evm-leg/paired-launch.js behind api/agents/paired/[action].js (POST /api/agents/:id/paired/{quote,launch,claim}, GET .../fees); MCP api/_mcp/tools/paired.js; agent skills src/agent-skills-paired.js; contracts contracts/paired-launchpad/; operator script scripts/paired-register-quotes.mjs (npm run paired:quotes) In-repo · launchpad live on chain 4663, quote registration owner-gated A coin with a fixed 1B supply split across one to five constant-product curves, one per quote asset from the launchpad's on-chain registry (tokenized stocks, WETH, stablecoins, chain coins). Each curve opens on a virtual quote reserve, so launching costs only the flat ETH fee and gas; liquidity never migrates and cannot be withdrawn, and the creator earns 70% of every swap fee in each asset it trades in. The launchpad is the only source of truth for coins, markets, prices and trades (candles come from its Swap events). Agents launch from their custodial EVM wallet under the same gates as every custodial spend, with an atomic opening buy pinned to the quoted fill; landed coins go to fixed_supply_launches (chain robinhood, venue paired). New quotes are calibrated to a common dollar opening value by paired:quotes, which only prints a plan unless given --apply and the owner key. Docs: docs/paired-coins.md
Launch lanes (Uniswap pool lane, idempotent EVM launches, lane picker) Launch page pages/launch-uniswap.html + src/uniswap-launch/page.js → /launch/uniswap, lane comparison src/launch/lane-picker.js mounted on /launch, /launch/paired and /launch/uniswap; lane config api/_lib/launch-lanes.js behind api/launches/[id].js (GET /api/launches/lanes, GET /api/launches/:id); durable records api/_lib/evm-launch-records.js + api/_lib/evm-launch-settlers.js (table evm_launch_records); Uniswap launch api/_lib/evm-leg/uniswap-launch.js + api/_lib/evm-leg/uniswap-config.js behind api/agents/uniswap/[action].js (POST /api/agents/:id/uniswap/{quote,launch}); MCP api/_mcp/tools/launches.js; contract contracts/src/ThreeWsUniswapLauncher.sol; doc generator scripts/gen-launch-lanes-doc.mjs (npm run docs:launch-lanes) In-repo · Uniswap lane opens when the owner deploys the launcher and sets UNISWAP_LAUNCHER_ADDRESS A fixed-supply coin whose whole supply sits in one single-sided Uniswap V3 pool on Base, with a pool fee tier, an optional timelock or permanent lock, and fee routing. Both EVM lanes (this and paired) take an Idempotency-Key, write a launch record before signing, and report stages through GET /api/launches/:id, so a retry returns the same launch. Solana stays the default lane. Docs: docs/launch-lanes.md
Robinhood Portfolios (generated index portfolios) Generator pages/hood-portfolios.html + src/hood-portfolios.js + src/hood-portfolios.css → /markets/robinhood/portfolios, universe board pages/hood-portfolios-universe.html + src/hood-portfolios-universe.js → /markets/robinhood/portfolios/universe; backend api/_lib/hood-portfolios.js + api/v1/hood-portfolios/{universe,generate,health}.js (free, keyless); universe snapshot data/hood-portfolios-universe.json built by scripts/build-hood-portfolios-universe.mjs (npm run hood:universe); contracts contracts/hood-portfolios/ In-repo · contracts code-complete and fork-proven against live chain 4663, mainnet deploy owner-gated Describe a portfolio in a sentence and get a real basket of Robinhood Chain assets. The screen ranks the whole holdable universe (727 assets: 167 tokenized equities, majors, and the chain-native long tail) through the platform free-first LLM chain, and every token it returns is validated back against that universe before it is shown. The result is committed as an immutable content-addressed manifest (PortfolioRegistry), held in kind by an ERC-20 share vault (Portfolio) whose backing is derived from balances rather than tracked, and rebalanced to published targets by a descending-price auction any address can fill: there is no function that lets a manager trade the fund. Needs no price oracle on any code path, which is what makes it work on a chain where only 34 of 95 registry equities have a Chainlink feed. Halt-aware: a paused tokenized equity stops issuance, redemption and rebalancing, and the UI says so. Ticker impersonation is resolved by contract address at build time (12 contracts on this chain call themselves USDG), so an impostor can never be selected. Backtests run the basket twice, on its schedule and never rebalanced, and report the difference: history comes from Chainlink round data (chunked into multicalls of 40, because this RPC silently drops calls out of a larger one) and a daily snapshot whose coverage compounds, with uncovered legs named rather than dropped. A generated portfolio shares as a deflate-compressed manifest in the URL, its hash re-derived server-side rather than trusted from the link. 38 offline contract tests incl. fuzz + 4 stateful invariants, 5 against a fork of live chain 4663, and 56 vitest across the screen, backtest engine, history reduction and SDK. Docs: docs/robinhood-portfolios.md, contracts/hood-portfolios/README.md
Premium Data API pass api/premium/ + api/_lib/premium.js, dashboards src/dashboard-next/pages/data-api.js → /dashboard/data-api + src/dashboard-next/pages/billing.js → /dashboard/billing In-repo Monthly pass in three tiers (Developer $19.99, Pro $99, Enterprise $499 per 30d, tiered rate limits) paid on Solana in $THREE (20% off), SOL, or USDC — replaces per-call x402 on the news archive with an x402_live_ API key (existing access-control lane) + SIWX browser grants. Quote→sign→verify flow with on-chain balance-delta verification; tables premium_passes/premium_quotes. Docs: docs/premium.md
Liquidations pulse (/coins) Collector services/liquidation-collector/ (standalone always-on Node service, ported from SperaxOS), proxy api/coin/liquidations.js → GET /api/coin/liquidations, UI strip in src/coins-index.js → /coins Live — collector on Cloud Run (liquidation-collector, min-instances 1, unthrottled CPU) since 2026-07-10 Real-time long/short liquidation pain across Binance, Bybit, and OKX public futures WebSocket streams: dominant-side badge (LONG PAIN / SHORT SQUEEZE / BALANCED), 1h long-vs-short bars, and the 3 largest recent liquidations, polled every 30s (pauses on hidden tab). The collector holds long-lived WebSockets so it can't run as a Vercel function — deploy it separately and point LIQUIDATION_COLLECTOR_URL at it. No fallback data: the proxy 503s collector_offline (never fabricated numbers) when unset or unreachable, and the strip degrades to a quiet single-line offline state. Docs: docs/api-reference.md#liquidations
BNB Chain campaign hub pages/bnb.html + src/bnb.js → /bnb, pure helpers src/bnb-hub-helpers.js, live block-time API api/bnb/block-time.js over api/_lib/bnb/chains.js probeBlockTime In-repo · hub live, tracks rolling out The campaign's front door: three feature cards (gasless agent onboarding, on-chain-gated 3D vault, real-time on-chain world), each claim limited to verified facts (0.45s blocks: never 20k TPS or 250ms finality). Embeds a live block-time widget (real RPC measurement on every load). Each card self-detects liveness via a real HTTP probe against its track's route/API on the running deployment: a 404 renders a designed "coming soon" state, never a dead link: so cards auto-light-up as the sibling tracks below ship: gasless registration → /create-agent + api/bnb/register-agent.js (prompt 03), vault → /vault (prompt 12), on-chain world → /bnb-latency (prompt 17) + the Explore on-chain toggle (prompt 16).
BABT holder check (BNB Chain) Lib api/_lib/bnb/babt.js hasBabt(), free API api/bnb/babt-check.js → GET /api/bnb/babt-check?address= In-repo · shipped Free, rate-limited on-chain check for whether a BSC address holds a Binance Account Bound Token (BABT) — a real, live, KYC-backed soulbound token (1.16M+ mainnet holders, verified via eth_getCode/balanceOf against the real contract 0x2B09d47D...5215D7c8). Verification writeup + honest comparison vs. Gitcoin Passport/World ID/Coinbase attestations: docs/bnb-babt-findings.md. Spike prompt retired (readable in git history).
BNB vault UI (browse/buy/unlock/view) pages/vault.html + src/vault.js → /vault, buyer session key src/bnb/vault-session.js, buy calldata src/bnb/vault-buy.js, browser ECIES decrypt src/bnb/vault-crypto-browser.js, pure FSM helpers src/vault-fsm.js — over the buyer API api/vault/{list,status,unlock,download,buy-policy-data}.js and contract contracts/src/GreenfieldVault.sol (prompt 12) In-repo · code+crypto proven on a local anvil-fork deploy, public testnet blocked on the same funded-deployer-key wall as prompts 07/09/10/11/13/14/18 The buyer-facing face of Track B: a grid of live on-chain listings, a "buy" step that sends a real BSC testnet transaction (gasless via MegaFuel when sponsorable, self-pay fallback), an honest "granting access on Greenfield…" polling state for the async cross-chain permission grant, and an "unlock & view" step that decrypts the GLB entirely client-side (AES-256-GCM + secp256k1 ECIES via Web Crypto + @noble/curves, never the server) before rendering it in <model-viewer>. Because the vault's ECIES unlock needs the buyer's raw private key — which a browser extension wallet deliberately never exposes — the buyer identity is a local session key (same pattern as src/agora/onchain-presence.js); MetaMask's only role is funding that session key with a plain tBNB transfer. A "Sell a model" panel wires the real upload (api/bnb/vault-upload.js) + list() path from a directly-connected wallet. GET /api/vault/buy-policy-data builds a real Greenfield Policy protobuf for buy() when a listing's object has genuinely completed Greenfield upload (api/_lib/bnb/vault-policy-data.js); until then buy() uses an honestly-labeled deterministic placeholder, matching the prompt-11 anvil proof's own posture.
BNB Chain live block race pages/bnb-latency.html + src/bnb-latency.js → /bnb-latency, pure helpers src/bnb-latency-helpers.js, live multi-chain API api/bnb/latency.js over api/_lib/bnb/latency-lanes.js (reuses probeBlockTime from api/_lib/bnb/chains.js for BNB, adds Base/Ethereum/Solana lanes) In-repo · shipped Standalone, shareable proof page: four lanes (BNB Chain, Base, Ethereum, Solana) polled every 5s, each showing a freshly measured average block/slot time and a rolling sparkline — no hardcoded numbers, a down RPC shows "reconnecting" on just that lane. Headline strip shows BNB's live average plus its honest measured-vs-measured speedup over Base/Ethereum. Linked from the /bnb hub's "real-time on-chain world" card, which auto-lights-up now that this route resolves.
BNB Chain payments (MPP, x402↔MPP bridge, gasless) Accept api/_lib/bnb/mpp-server.js (mppRequirements/mppChallenge/mppVerify/mppSettle), pay api/_lib/bnb/mpp-buyer.js (mppFetch, re-exported from api/_lib/x402-buyer-fetch.js), gasless rail api/_lib/bnb/megafuel.js, pilot dual-protocol endpoint api/x402/three-intel.js In-repo · shipped, settlement needs merchant creds three.ws speaks MPP (BNB Chain's Machine Payments Protocol) additively alongside x402: MPP's b402 layer is x402 v2 byte-for-byte (same X-PAYMENT/X-PAYMENT-RESPONSE, same EIP-3009 credential), so a dual-protocol endpoint just advertises an extra BNB (eip155:56/97) accept entry and routes BNB-network payments to the b402 facilitator while Solana/Base traffic stays on the untouched x402 path. Verify (off-chain, free, replay-guarded via Redis SET NX PX) always runs before settle; without B402_* merchant credentials, settle fails closed with mpp_not_configured (503) rather than fabricating a receipt. Guide: docs/bnb-payments.md. Wire contract: specs/x402-mpp-bridge.md. Tests: tests/bnb-mpp-server.test.js, tests/bnb-mpp-buyer.test.js.
Seeker / Saga dApp Store app solana-mobile/: TWA wrapper solana-mobile/twa/, Publisher Portal listing copy solana-mobile/publish/, MWA wallet + Seeker detection solana-mobile/src/ Live · v1.0.0 on the Solana dApp Store (submitted 2026-08-28, approved 2026-09-01) Everything needed to package three.ws as a Solana Mobile app and publish it to the on-chain dApp Store. Targets Seeker first; compatible with Saga Gen 1 and Gen 2. Docs: solana-mobile/README.md
iOS App Store app ios/: Capacitor shell + config ios/capacitor.config.ts, Xcode project ios/native/App/, web-side native bridge ios/src/native-bridge.js, offline shell ios/shell/, listing copy ios/publish/, app association handler in api/wk.js In-repo · project builds and the web half ships on every deploy · awaiting an Apple Developer organization account three.ws as a native iOS app (ws.three.app). A Capacitor 8 shell whose WKWebView runs the live https://three.ws, so the app is never a version behind the site; what makes it an app is the native layer around it. ios/src/native-bridge.js ships with the SITE, not the .ipa (Capacitor injects its bridge into the remote page, so window.Capacitor exists on three.ws only inside the app): it supplies the navigator.share WKWebView does not have, routes off-site links to an in-app Safari sheet instead of stranding the app's only WebView, handles universal links and threews:// wallet returns, holds the launch screen until the first real frame, marks html.ios-app, routes a tapped push to its page and keeps the app icon badge equal to the inbox's unread count. Beyond the Android app it has push notifications over APNs (device registry api/push/device.js, sender api/_lib/apns.js, fanned out beside Web Push in api/_lib/notify.js, client in src/push-notifications.js; live once APNS_KEY_ID/APNS_AUTH_KEY are set), a share extension (ios/native/App/ShareExtension/, ws.three.app.share) that takes one to three photos into /create/selfie or a .glb into /create through the App Group and the app's own ThreeWsApp plugin (ThreeWsAppPlugin.swift), and four home screen quick actions (QuickActions.swift). npm run check:ios-app (scripts/check-ios-app.mjs) holds the Swift half to its web callers, since no Linux machine can compile it. The three-ws-ios-native-bridge plugin in vite.config.js copies it into dist/ content-hashed and injects it into every built page except the third-party embed entries (671 pages, /viewer and /ar included, which a transformIndexHtml could not reach because they are copied verbatim from public/). GET /.well-known/apple-app-site-association is served from the API rather than a static file because Apple demands an exact path, a JSON content type and no redirect; it answers 503 not_configured until APPLE_TEAM_ID is set rather than publishing an association that would fail silently on device. In the app, every step that spends money (buying, launching, trading, paying) hands off to real Safari on the same page, signed in through a single-use code from api/auth/handoff.js, because App Review forbids those flows in-app outside IAP; paid flows opt in with leaveAppForPayment() from src/shared/native-handoff.js and the agreements gate hands off every non-custody context. Releases are one command, npm run ios:release (ios/scripts/release.mjs: structural check, cap sync, archive, upload to TestFlight), or Xcode Cloud through ios/native/App/ci_scripts/; both targets bundle a privacy manifest. The app also carries the CarPlay scene for three.ws Drive: CarPlaySceneDelegate renders the car screen's templates while DriveLink bridges them to /drive in the WebView, gated behind the com.apple.developer.carplay-voice-based-conversation entitlement, which only --carplay releases sign in (App-CarPlay.entitlements), so builds archive before Apple grants it. Docs: ios/README.md, docs/ios-app.md, App Review posture ios/docs/REVIEW-RISK.md, submission ios/docs/SUBMISSION.md, CarPlay ios/docs/CARPLAY.md. The project also carries the Agent glance WidgetKit extension (ws.three.app.glance, iOS 17+), whose sources live in apple/ and are shared byte for byte with the Mac app.
three.ws Glance for Mac apple/: shared sources apple/GlanceKit/, WidgetKit extension apple/GlanceWidget/, menu bar host app apple/macos/ (XcodeGen spec apple/macos/project.yml), icon apple/scripts/make-macos-icon.mjs In-repo · builds with XcodeGen and a Development Team · Developer ID distribution, so it needs no App Store review The agent in a Mac's Notification Centre, and the same extension on iPhone. A menu bar app whose whole job is to hold a revocable widget token and prove it works: the Mac never sees a password, because signing in happens on three.ws and the page hands back the token through threews://glance/link or as a code to paste. The widget fetches GET /api/glance/mine?format=png on the system timeline, in both themes so it follows the reader's appearance, caches the last card in the shared App Group container so an offline Mac shows yesterday's card with the time on it, and opens the agent on click. One set of sources builds for both platforms; only the project differs, because an App Group identifier on a Developer ID Mac must carry the team prefix that the same group on iPhone must not. Guard: scripts/check-apple-widget.mjs (npm run check:apple-widget, in npm run gate) proves both Xcode projects and the client-to-server contract on a machine with no Xcode. Docs: apple/README.md, docs/native-widgets.md.
Walk Avatar browser extension extensions/walk-avatar/ — MV3 manifest.json, background.js In-repo · Chrome Web Store release checklist staged (RELEASE.md) Walks your three.ws avatar across any site and reads pages aloud — a browsing companion built on the same rig as the walk-sdk. Ships its own store-required PRIVACY.md, PERMISSIONS.md, and TERMS.md.
Checkout companion browser extension extensions/checkout-companion/ (MV3: extract.js, content.js, panel.js, background.js), analysis api/_lib/companion/checkout.js, endpoint api/companion/checkout.js In-repo The companion at the moment money moves: on a checkout page it reports the total against the price you were shown, money the page did not itemise, fees named and summed, whether the charge repeats, and the cancellation terms. Arithmetic is never the model's job (integer minor units, computed server-side) and no finding is ever a legal verdict (sanitizeModelFindings() drops any that claims an amount or calls something illegal). With no model reachable the arithmetic findings still stand. The extension never reads an input: collectText/collectAmounts refuse form fields, iframes and editable regions structurally, and redaction runs in the browser before anything is sent; only the hostname travels and nothing about the page is stored. Docs: docs/checkout-companion.md. Tests: tests/companion-checkout.test.js, tests/checkout-extract.test.js
Desktop companion app apps/desktop/. Electron main src/main.js, preload src/preload.cjs, stage src/renderer/ In-repo · packaged with electron-builder (npm run dist), not yet published A transparent, click-through, always-on-top character that strolls across the bottom of the desktop and walks over to deliver what cleared the user's bar. Subscribes to /api/companion/stream with the same bridge token the CLI stores, and drives the published walk embed over its postMessage contract, so it carries no 3D code of its own. Not an npm workspace: it installs and builds on its own (see apps/desktop/README.md).
Desktop local agent runtime apps/desktop/src/runtime/ (runtime, keystore, feed, live executor), src/main/local-runtime.js, console view src/console/views/local.js, smoke scripts/smoke-runtime.mjs In-repo; Linux AppImage and deb built, Mac and Windows builds and signing are owner actions Runs agents, paper and live strategies, limit orders and automations on the user's machine with keys in the OS keychain, native payload-hash approvals, a tray menu, and a mascot that shows agent state. Docs: docs/desktop-local-runtime.md. Tests: tests/desktop-runtime.test.js
Desktop menu bar panel apps/desktop/src/main/panel.js, pure logic src/panel/model.js, renderer src/panel/, preload src/panel-preload.cjs In-repo; ships with the desktop app A popover under the tray icon: the selected agent alive in 3D (the published walk embed, gesture tied to local runtime state), SOL balance, start and stop, a pending-approvals card that opens the native review dialog (the panel has no approve call), alerts, companion switch and a one-line ask box. Docs: docs/desktop-menu-bar-panel.md. Tests: tests/desktop-panel.test.js
DCC tool integrations (Blender, ComfyUI, Modly) integrations/: integrations/blender/, integrations/comfyui/, Modly extensions integrations/modly/ (three-ws/ cloud nodes, three-ws-publish/ publish node), shared Python client integrations/_pyclient/ In-repo; Modly extensions install by linking the folder, one-click GitHub install is owner-gated (SUBMITTING.md) First-party plugins that drive the public Forge pipeline (/api/forge, rig, remesh, publish) from inside the tools artists already use, so a model is generated without leaving the DCC. Docs: integrations/README.md, integrations/modly/README.md
LiveKit and Pipecat avatar integrations integrations/livekit/livekit-plugins-threews/ (published as livekit-plugins-threews), integrations/pipecat/pipecat-threews/ (published as pipecat-threews) In-repo; PyPI publish and the upstream community-integration PRs are owner actions A LiveKit Agents AvatarSession plugin and a Pipecat FrameProcessor that both republish a running voice pipeline's TTS and user-turn frames as the same transcript/gesture/speech_started/speech_ended JSON message shape over the room's data channel, which <agent-3d voice="livekit"> (src/runtime/livekit-voice.js) already renders client-side, no server-side video rendering. Each ships a runnable local example against a real open-source livekit-server, no cloud account needed. Docs: docs/voice-framework-integrations.md. Tests: integrations/livekit/livekit-plugins-threews/tests/, integrations/pipecat/pipecat-threews/tests/, browser E2E tests/e2e/agent-3d-livekit-avatar.spec.js, tests/e2e/agent-3d-pipecat-avatar.spec.js
Shopify app: Photo to 3D product media api/shopify/, api/_lib/shopify/, pages/shopify-app.html, src/shopify-app/app.js, migration api/_lib/migrations/20261015060000_shopify_app.sql In-repo; Shopify Partner account, env vars, migration apply, and App Store submission are owner actions An embedded Shopify admin app that turns a product photo into a real GLB (via three.ws's own /api/forge) and attaches it with productCreateMedia, so the storefront shows a 3D viewer on desktop and AR Quick Look on iPhone from one upload (Shopify derives the USDZ). OAuth with session-token-authenticated embedded calls, bulk generation with real per-item status, usage-based Billing API subscription, and the three mandatory privacy webhooks plus app/uninstalled. Docs: docs/shopify-app.md, submission packet marketing/growth/submissions/shopify-app.md.
Site-builder embeds for <agent-3d> (WordPress, Framer, Webflow) WordPress plugin integrations/wordpress/three-ws-agent/ (Gutenberg block + [three_ws_agent] shortcode), Framer code component integrations/framer/, Webflow Code Component integrations/webflow/; shared pin build scripts/build-site-builder-embeds.mjs/scripts/check-site-builder-embeds.mjs/scripts/lib/site-builder-pin.mjs In-repo; WordPress.org / Framer Marketplace / Webflow Apps submissions are owner actions Three independent embeds of the same <agent-3d> web component, one per platform's native extension point, each generated from the same data/agent-3d-releases.json release ledger so all three ship the identical pinned version and SRI hash (npm run check:site-builder-embeds, in npm run gate, fails the build on drift). The WordPress plugin is verified against a real local WordPress in Docker with the official Plugin Check tool (scripts/wordpress-plugin-check.sh, "No errors found"). Framer and Webflow ship no first-party local test harness of their own, so each package carries its own standalone Vite config and a real-React-rendered test harness (the repo root's vite.config.js uses a non-React JSX factory for static-site generation) proving a live WebGL canvas boots against the real pinned CDN script; the Webflow package is additionally verified through the real webflow devlink bundle CLI command, no account needed. Docs: docs/wordpress-embed.md, docs/embedding.md. Submission packet: marketing/growth/submissions/site-builders.md. Tests: tests/e2e/agent-3d-framer-component.spec.js, tests/e2e/agent-3d-webflow-component.spec.js
Base58 difficulty model (the honest math) src/solana/vanity/base58-distribution.js, dispatch in src/solana/vanity/validation.js; ported copies in solana-agent-sdk/src/vanity/verify.ts and mcp-server/src/lib/base58-distribution.js, held in agreement by tests/vanity-model-parity.test.js In-repo The exact probability that a random Solana address matches a vanity pattern, and the single source of truth behind every quote, price, rarity tier, bounty payout and signed receipt. Base58 is a positional encoding of a 256-bit integer, so the leading character is not uniform: the 40 symbols K-z are 17.2x harder to lead with than 5-H, a 58x spread the old flat 58ⁿ model erased. Models are versioned (base58-exact/v2, superseding 58^effectiveLength) and receipts name theirs, so attestations issued before the correction still verify. Spec: docs/PROTOCOL-vanity.md
Vanity address grinder (Rust → WASM) crates/vanity-grinder/ → compiled to src/solana/vanity/wasm/; consumed by src/agent-vanity-grinder.js, src/agent-eth-vanity-card.js In-repo The Rust source behind in-browser Solana/EVM vanity-address mining. Compiled to WebAssembly so grinding runs on the visitor's machine, never the server. Surfaced as the vanity_grinder MCP tool and the premium pre-ground inventory (vanity_premium).
x402 payment modal (drop-in UI) x402-payment-modal/ Published as @three-ws/x402-payment-modal A drop-in payment modal for any x402 paid endpoint — one ES import turns a 402 challenge into a wallet-connect + pay flow. Has a build step, so it sits outside the zero-dependency packages/* SDK family.
x402 modal SDK x402-modal-sdk/ Published as @three-ws/x402-modal The lower-level modal SDK the payment modal builds on. Ships a bundled dist/ (built by build.mjs, never committed); see x402-modal-sdk/README.md and x402-modal-sdk/TUTORIAL.md. Exports pay() plus discover(), the UI-free 402 probe a server or agent can price a call with. Tests: npm --prefix x402-modal-sdk test (protocol + helpers, zero deps) and real-browser conformance scripts/x402-modal-e2e.mjs.
React components packages/react/ Published as @three-ws/react (v1.0.1) React components for embedding three.ws 3D AI agents
x402 auto-paying fetch packages/x402-fetch/ Published as @three-ws/x402-fetch (v1.0.2) Drop-in fetch wrapper that auto-pays x402 challenges
AgentCore payments MCP packages/agentcore-payments-mcp/ Published as @three-ws/agentcore-payments-mcp (v0.1.2) MCP server for platform-managed agent payment sessions
VS Code 3D extension packages/vscode-3d/ In-repo (v0.2.0, not yet on the Marketplace) Makes .glb and .gltf first-class in VS Code: the file opens in a three.js viewer as an editor tab (orbit, animation clips with a scrub bar, wireframe, skeleton, grid, PNG snapshot, looping turntable GIF) with Draco, KTX2 and meshopt decoders shipped inside the extension so a compressed avatar renders offline. The report panel and the status bar reuse src/gltf-inspect.js, the same inspector behind /validation, in the extension host, so a model is never uploaded to be measured. Animate searches the 2,874-clip motion library (/api/animations/library) and retargets the pick onto the open rig inside the webview with src/animation-retarget.js; Bake clip writes the retargeted clip into a copy of the GLB as real glTF channels (packages/vscode-3d/src/bake-clip.js, glTF-Transform, meshopt re-encoded). Text to motion goes through /api/forge-motion. Refine calls the free refine_model tool and keeps the version lineage per file. Optimize runs dedup/prune/weld/resample/meshopt (and quantize) locally. Compare with the committed version reads HEAD out of git and diffs it with packages/glb-diff, opening both versions side by side. Check quality posts the webview render to /api/forge-quality-check. Language features for <agent-3d> in HTML/JSX/Vue/Svelte/Astro/Markdown/PHP (packages/vscode-3d/src/embed-language.js): diagnostics with quick fixes (no source, no size, unpinned latest, missing or stale SRI hash against /agent-3d/versions.json, unknown attributes, bad enum values), hovers, completions, CodeLenses. Generation, rigging and the gallery call the free public lanes (/api/mcp-studio, /api/forge-gallery); the embed command pins the current library release and its SRI hash. Doc: docs/vscode.md. Tests: npm --prefix packages/vscode-3d test (activates the bundled extension against a stand-in host that now covers language providers and diagnostics, proves the retarget-then-bake round trip on the committed cz.glb, and unit tests every module against local HTTP servers).
VS Code x402 extension packages/vscode-x402/ In-repo (v0.2.2, not yet on the Marketplace) VS Code extension for the x402 bazaar
Meta-Allocator (the ETF of degens) pages/meta-allocator.html + src/meta-allocator.js → /meta-allocator, brain api/_lib/meta-allocator.js, endpoint api/meta-allocator.js Live (non-custodial planning) Spreads a budget across the top verified pump.fun leader agents, ranked by risk-adjusted on-chain track record (win rate, realized ROI, peak-to-trough max drawdown from agent_sniper_positions) and diversified across derived correlation groups, then returns a rebalance rule. Free-first llmComplete shaping with a deterministic same-shape fallback so it never fails. Returns a plan (weights + suggested sizes), never a transaction; users act one leader at a time via /vaults. Doc: docs/meta-allocator.md.
Alpha-drip (a leader prices their signal latency) Ladder rules api/_lib/alpha-drip.js, fanout half api/_lib/copy-drip-runtime.js, measured edge half-life api/_lib/alpha-drip-stats.js, endpoint api/copy/alpha-drip.js -> /api/copy/alpha-drip, leader editor src/alpha-drip-panel.js mounted on /dashboard/copy, copier seat on the trader page src/copy-panel.js, schema api/_lib/migrations/20260903235500_copy_alpha_drip.sql Live (off unless a leader turns it on) The $THREE sink on the copy rail: a leader sets how long each holder tier waits before a copy intent is revealed to them, so the thing being sold is latency rather than only a share of the profit. Two rules are structural and enforced server-side: a higher tier can never wait longer than a lower one, and a drip delays the reveal, never the record (the intent row is written in full at fanout time and the public track record is untouched, so there are no hidden trades). The copier is shown the seat their balance buys BEFORE they subscribe, not after; a locked intent renders as a countdown that unlocks in place, and POST /api/copy/executions refuses an unreleased one in the same statement that changes its status, so the guard cannot be raced. Tier size caps are applied after the copy engine has sized and gated the order, never before, so the copier's own caps still bind first. The edge half-life the fairness warning judges a ladder against is measured from the leader's own profitable closes, and is null rather than guessed below five of them. Release runs inside api/cron/copy-fanout.js rather than a second cron, so the release cadence is the fanout cadence. Doc: docs/alpha-drip.md. Tests: tests/alpha-drip.test.js
Ghost-copy (paper-copy a leader) pages/ghost-copy.html + src/ghost-copy.js → /ghost-copy, simulator api/_lib/ghost-copy.js, endpoint api/pump/ghost-copy.js, tests tests/ghost-copy.test.js Live (paper only, zero custody) The bridge between the leaderboard and actually copying someone. Pick a verified trader agent, a budget and a window, and it replays that agent's real closed on-chain round-trips (agent_sniper_positions) against a wallet that does not exist, sizing every order through planCopyOrder, the SAME function the live copy-fanout cron uses, so the result is what the copy engine would actually have generated rather than a marketing figure. Deliberately unflattering: P&L per trade is derived from exact chain lamports (never the stored pct column), losing round-trips all count, the ghost wallet has a real cash constraint so capital locked in an open copy blocks the next one, every skip carries a machine reason plus a human sentence, and the leader's still-open positions are marked at THEIR last on-chain quote and reported as unrealized outside the realized headline. Needs no account, no wallet, no signature and no funded signer, so it ships ahead of any custody decision; state lives in the query string so a result is deep-linkable and shareable. Converts into /vaults for real money. Doc: docs/ghost-copy.md.
Specialist teams (four role agents, one board) Page pages/teams.html + src/teams.js + src/teams.css → /teams and /teams/:id; runtime api/_lib/teams/ (roles and ceilings roles.js, board findings.js, Researcher research.js, runners runtime.js), endpoints api/teams/, migration api/_lib/migrations/20261010120000_teams.sql, tests tests/teams-runtime.test.js Live Finish order 941. Creating a team provisions a Researcher, Entry, Trader and Launcher agent (3D body, wallet, public page) under one spend policy mirrored onto the Trader's trade limits. Every run posts to team_findings; the Trader cites a live research finding or runs research and writes it back (reuse, never redo). Role ceilings are server-enforced and only the Trader can sign, and only a confirmed live trade. The Launcher prepares a native-lane plan and hands off to /three-launchpad for the owner to sign. The board streams over SSE. Doc: docs/teams.md.
Squad chat (coordinator that plans, runs and escalates) Page pages/team-chat.html + src/team-chat.js + src/team-chat.css → /team-chat and /teams/:id/chat; endpoint api/team-chat.js; coordinator api/_lib/team-chat/ (planner plan.js, runner runner.js, specialists specialists.js, metadata guard untrusted.js, memory prefs.js, inbox bridge approvals-bridge.js + approval-executor.js), migration api/_lib/migrations/20261010150000_team_chat.sql, tests tests/team-chat-{plan,escalation,injection}.test.js Live Finish order 942. One sentence becomes a frozen plan of role-tagged steps for a specialist team or a solo agent. Steps stream per-step status with evidence; anything that signs, transfers, launches or exceeds the cap becomes an approval (payload-hash checked, 15 minute expiry) and the run resumes on approve. Paper simulates; live trades sign from the squad wallet and mirror into /approvals; launches and transfers hand off to the page where the owner signs. Preferences persist in agent memory. Coin metadata is quarantined as data. Squad avatars react through <agent-3d>; voice input via src/voice. Doc: docs/team-chat.md.
Syndicates (copy-trade as a team) Board pages/syndicates.html + src/syndicates.js → /syndicates, detail pages/syndicate.html + src/syndicate.js → /syndicates/:slug, shared src/syndicate-shared.js + src/syndicates.css, trader-profile widget src/trader-syndicates.js; model api/_lib/syndicates.js, guarded follow path api/_lib/copy-subscribe.js, endpoints api/syndicates/, migration api/_lib/migrations/20260929120000_copy_syndicates.sql, tests tests/syndicates.test.js Live (non-custodial) Roadmap 917 item 12.7. A named team (flag, motto, color) following one to three copyable leaders. Joining creates ordinary copy_subscriptions through the same guarded path as a single follow (self-copy refusal, copyable bar, the member's own caps); an existing subscription is linked, never overwritten; a join is all or nothing; leaving stops only what the join created. One team per copier per network. Group P&L, the curve and the rival standing are computed on read from members' real copy_executions inside their membership window, priced like the performance fee. The empty board lists today's copyable leaders with whole records. Linked from /trader/:id, /dashboard/copy and /play/arena. Doc: docs/syndicates.md.
Daily trading quests pages/quests.html + src/quests.js → /quests; model api/_lib/trading-quests.js, disarmed $THREE payout api/_lib/quest-rewards.js, endpoints api/quests/, trade proof recorded in api/pump/[action].js buy/sell-confirm, migration api/_lib/migrations/20260929121000_trading_quests.sql, tests tests/trading-quests.test.js, tests/quest-rewards.test.js Live (XP + badges); $THREE rewards disarmed Roadmap 917 item 12.11. Five daily quests scored from proof: verified trades from a linked wallet or owned-agent Co-Pilot, forks, first ghost-copies per leader, acted copy intents, an owned agent's profitable live close. Three a day is a daily clear. XP is an insert-only ledger; badges go to user_badges. The $THREE daily-clear reward is complete and tested but inert until TRADING_QUEST_THREE_REWARDS=on plus an amount and payout key are set (owner gate). Doc: docs/trading-quests.md.
Trader duels (points-only skill predictions) Board pages/duels.html + src/duels.js → /duels, detail pages/duel.html + src/duel.js → /duels/:id, shared src/duels-shared.js + src/duels.css, trader-profile widget src/trader-duels.js; model api/_lib/trader-duels.js, endpoints api/duels/, cron api/cron/duels-tick.js, migration api/_lib/migrations/20260930150000_trader_duels.sql, tests tests/trader-duels.test.js Live (points only) Roadmap 917 item 12.6, built free to play: no token, deposit, escrow or payout, and points have no cash value. The cron opens 24h and week duels for neighbouring traders from the rivalry engine, locks calls at window start, and resolves from agent_sniper_positions + agent_strategy_positions through computeTraderMetrics. Ties, empty windows and private/deleted traders void and refund; an idle trader counts as flat. A correct call pays 2x and 15 XP into trading_quest_completions; daily 100-point allowance, monthly season board, four badges. One call per user per duel, no calls on your own agent, overdraft and double payout refused by constraints. Linked from /trader/:id, /trade-rooms, /quests and /play/arena. Doc: docs/trader-duels.md.
Agent portfolio, launch sniper, alerts and duels (MCP + REST) MCP tools api/_mcpagent/portfolio-tools.js, api/_mcpagent/sniper-alert-tools.js, api/_mcpagent/duels-tools.js; REST api/v1/agents/[id]/portfolio/index.js and api/v1/agents/[id]/portfolio/[...path].js over api/_lib/portfolio-routes.js; stores api/_lib/portfolio-history.js, api/_lib/sniper-control.js, api/_lib/signal-subscription-control.js, api/_lib/pump-alert-rules.js, api/_lib/duel-challenges.js; cron api/cron/agent-portfolio-snapshots.js Live Agent-callable portfolio (valuation, net-worth history, P&L by source), launch sniper control behind a preview-and-confirm spend gate, signal subscriptions, pump alert rules including launch_match (creator history, market cap band, name pattern, safety score) delivered to the owner by bell, push and paired Telegram/Discord chats, and agent-to-agent duel challenges on the free-play points board. Docs: docs/mcp.md, docs/api-reference.md.
Copy Coach (guided first copy) pages/copy-coach.html + src/copy-coach.js + src/copy-coach.css → /copy-coach, model api/_lib/copy-coach.js, endpoint api/copy/coach.js, starter caps STARTER_CAPS in api/_lib/copy-engine.js, tests tests/copy-coach.test.js Live Roadmap 917 prompt 14.3. Four steps for a cautious first-timer: a real signed 25%+ win shown beside the same agent's full 30-day record (a losing record is said plainly), a ghost copy of a leader with fake money (ghost-copy), one tiny real copy behind a confirmation card, then what comes next. The real copy goes through POST /api/copy/subscriptions with starter: true, where the server refuses anything past 0.05 SOL per trade, 0.2 SOL a day, 2 open copies, a 25% drawdown pause, the safety check and an explicit risk_ack; it is non-custodial and spends nothing until the user signs each copied trade. The side panel answers questions through the LLM chain from a fact sheet built from real rows (ghost replay recomputed server side), validated against promises, invented numbers, other coins and links, with a deterministic guide as the fallback. Linked from the nav (next to Copy Trading) and /ghost-copy. Doc: docs/copy-coach.md.
Sentiment Scout (momentum with receipts) Scout tab and drawer section on pages/coin-intel.html via src/coin-intel-scout.js → /coin-intel?tab=scout, model api/_lib/sentiment-scout.js, X search api/_lib/x-search.js, LLM notes api/_lib/scout-notes.js, endpoint api/pump/sentiment-scout.js, MCP sentiment_scout in api/_mcp/tools/trader.js, table sentiment_scout_reads (migration), tests tests/sentiment-scout.test.js Live Roadmap 917 prompt 14.2. Ranks the last hour of Coin Intelligence launches by early volume and buyer percentiles, screens out bundles and dev dumps, enriches the shortlist with the live curve, X posts quoting the exact contract address, pump.fun callouts and paid x402 reads, and returns a 0-100 score with its parts, evidence lines that each carry a source URL, a timestamp and (for social or paid claims) the on-chain facts they were checked against, and one worst-first caution (including one-account X chatter). Unreadable sources are listed, never estimated. An LLM-written two-sentence read per candidate is validated against the evidence. Board candidates are recorded so trade receipts show a Scout flag that preceded an entry, and the Scout's calls are graded against pump_coin_outcomes. LLM-judged sniper strategies opt in with llm_scout_context (workers/agent-sniper/llm-judge.js). Doc: docs/sentiment-scout.md.
Trader Wrapped (season recap) pages/wrapped.html + src/wrapped.js → /wrapped, deck builder api/_lib/wrapped.js, endpoint api/pump/wrapped.js, social card api/wrapped-og.js, share page api/wrapped-share.js → /wrapped/<agent_id>/share, tests tests/wrapped.test.js Live (read-only, zero custody) The artifact the trading stack was missing: one image and one link that say what a season was. Eight slides cut server-side from a trader agent's closed on-chain round-trips (scoreboard, best trade, worst trade, the coin that carried it, rhythm, rank against the field with the nearest rival, receipt), swipeable on touch and keyboard-driven on desktop, with the current slide in the URL hash so a share link lands on the slide the sharer was reading. Arithmetic is delegated wholesale to computeTraderMetrics in api/_lib/trader-stats.js, the same truth layer the leaderboard and trader profile use, so a recap can never disagree with the profile it links to. Deliberately unflattering: the worst-trade slide is not optional, the scoreboard carries an explicit verdict and colors a red season red, per-coin ranking includes coins that lost money, self-launched coins stay excluded from every superlative, the rank always prints the size of the real field beside it, and under 3 settled round-trips the page says there is no season rather than drawing a chart out of noise. Needs no account, wallet, signature or funded signer. Converts through Fork on the best-trade slide and links onward to the verified profile, Ghost-copy and the rival's own wrapped. Doc: docs/trader-wrapped.md.
Rivalries (what changed on the trader board) Engine api/_lib/rivalries.js, endpoint api/sniper/rivalries.js → /api/sniper/rivalries, grudge-match strip src/play/rivalries.js mounted under the leaderboard on pages/play/arena.html → /play/arena, tests tests/rivalries.test.js Live (read-only) The layer a leaderboard never has: not who is ahead, but who just took whose place. Every trader on the board is paired with the one directly above them and the pair is labelled overtake, debut or chase, with the P&L both sides booked inside the lookback as the reason. Derived from ONE position fetch through the shared computeTraderMetrics, run three times: the current window, the same window measured at the lookback cutoff, and the round-trips closed inside the lookback. The past board is re-derived from close timestamps rather than read from a snapshot table, so there is no new table and no cron, it works retroactively from the day it shipped, and it cannot drift out of agreement with /api/sniper/leaderboard or with either profile it links to. The copy is assembled from those numbers rather than generated, which keeps a public strip instant, free and checkable: it will not call a trader "behind" when the board ranks on score and that trader actually holds more SOL, and it will not say someone "booked 0.000 SOL" when they simply were not in the market. Ranking boards apply a three settled round-trip floor; the momentum board does not, because one settled trade is the movement it exists to show. Doc: docs/rivalries.md.
Trader card embed (a leader on someone else page) Hosted element public/trader-card/element.js → /trader-card/element.js (<trader-card>), compact read api/sniper/trader-card.js → /api/sniper/trader-card, pure projection api/_lib/trader-card.js, snippet builder src/shared/trader-embed.js, builder panel on src/trader.js → /trader/:id, tests tests/trader-card.test.js Live (read-only, zero custody) The funnel that runs on other people sites: one script tag renders a trader's live on-chain record in a stream overlay, a link in bio or a blog post, and every coin on it carries a Fork link plus a Ghost-copy call to action, all signed by the reader's own wallet. The leader copies the snippet from their own profile ("Embed this trader"), which renders a live preview of exactly what they are about to paste and bakes in their referral code, so every link the card emits is attributed to them. /api/sniper/trader is a quarter of a megabyte for a well-traded agent, which no widget on a stranger's page should pay for, so this endpoint is the few-kilobyte projection of it through the SAME computeTraderMetrics: an embedded card can never show a record three.ws would dispute, and an unmeasured number renders n/a rather than a zero. Real DOM in a shadow root (selectable, screen-reader readable, keyboard reachable, theme-aware), every link absolute because a relative href on a foreign domain goes to their site, polling that stops when the tab is hidden or the card scrolls off, and a failed refresh that keeps the last good card rather than blanking someone else's page. Doc: docs/trader-card-embed.md.
Clip Director (content engine) pages/clip-director.html + src/clip-director-page.js → /clip-director, brain api/_lib/clip-director.js, endpoint api/clip-director.js Live Turns one real closed trade (agent_sniper_positions) into the optimal shareable card per surface (X / Telegram / Feed): honest hook, the real number, an avatar gesture mapped to a real animation clip, CTA, and alt text, plus an on-chain proof link. Losses get an honest card too. Free-first llmComplete with a deterministic same-shape fallback. Doc: docs/clip-director.md.
Atlas (site-wide Cmd+K search + route map) Palette public/atlas.js -> /atlas.js, ranking public/atlas/score.js, map page pages/atlas.html + src/atlas-page.js -> /atlas, index scripts/build-atlas-index.mjs -> public/atlas-index.json, task catalog data/atlas-intents.json, coverage scripts/inject-atlas.mjs Live Discovery layer for 650+ routes. Cmd+K (or /) opens a search over every page in data/pages.json plus a curated set of TASKS that answer with ordered steps rather than one link, because "which page starts the get-paid flow" is a harder question than "where is /x402/studio". Zero-dependency single file so it runs identically on 250+ standalone HTML entry points; the index is fetched on first open, not page load. Every task step target is resolved against the real route table at build time, so an onboarding path cannot dead-end on a 404. Injected by a Vite three-ws-atlas plugin plus a post-build dist/ walk (same belt-and-suspenders as scripts/inject-tour-boot.mjs, for the same plugin-ordering reason). Embeds and the nav/footer fragments are excluded. Doc: docs/atlas.md. Tests: tests/atlas.test.js.
Internationalization (i18n) Runtime src/i18n.js → /i18n.js; catalogs public/locales/ (en + 84 locales, manifest.json, localized-pages.json); pipeline scripts/i18n-annotate.mjs · i18n-extract.mjs · i18n-translate.mjs (Vertex Gemini, glossary-locked) · i18n-backfill.mjs (re-translates copy that was baked to English during a backend outage); hreflang in api/sitemap/[type].js Live (85 languages) LobeHub-model client-side copy swap. npm run i18n:annotate auto-injects data-i18n* into static HTML (byte-surgical), i18n:extract builds en.json, i18n:translate fans it out to every locale via Vertex with brand/protocol terms masked. i18n:backfill finds keys whose value is still byte-identical to English (the silent failure mode: a baked fallback is present, so every later run skips it) and re-translates them. Runtime auto-detects locale, mounts a floating <lang-switcher>, and injects hreflang. Doc: docs/i18n.md. Tests: tests/i18n.test.js, tests/i18n-annotate.test.js, tests/i18n-backfill.test.js.
Shared utilities (import instead of hand-rolling) Frontend src/shared/markdown.js · src/shared/toast.js · src/shared/fuzzy.js · timeAgo/toEpochMs in src/shared/coin-format.js; backend api/_lib/resilience.js · api/_lib/mem-cache.js · api/_lib/pool.js · api/_lib/csv.js; ops scripts/check-cron-drift.mjs Live · doc docs/shared-utilities.md Thin layers over vetted packages, each replacing a family of hand-rolled copies that had drifted. markdown.js = marked + DOMPurify, the single sanitized path for model/user text reaching innerHTML (the concierge SDK carries its own copy at concierge-sdk/src/markdown.js because it ships as an independent bundle). toast.js = one aria-live region with a real queue. fuzzy.js = @leeoniya/ufuzzy ranking + typo tolerance + match ranges for both command palettes. resilience.js = cockatiel circuit breakers and jittered retry (withRetry, parseRetryAfter, isRetryableError). mem-cache.js = lru-cache with true recency eviction and single-flight cached(). pool.js = p-limit bounded concurrency. csv.js = RFC 4180 quoting plus spreadsheet formula-injection neutralization. check-cron-drift.mjs = cron-parser validation of every cron declared in vercel.json against live Cloud Scheduler, sharing its job-id derivation with scripts/create-gcp-scheduler.mjs so the two can never disagree. Tests: tests/shared-markdown.test.js, tests/fuzzy.test.js, tests/csv.test.js, tests/resilience-shared.test.js
Announcement factory (internal) Calendar scripts/announce-plan.mjs npm run announce:plan, factory scripts/announce-kit.mjs npm run announce:kit, engine api/_lib/announce/, ranker scripts/announce-rank.mjs, gate scripts/check-announce.mjs, packs docs/announcements/, deferrals data/announce-deferred.json Internal, owner-gated · doc docs/announcement-factory.md Works the backlog of shipped surfaces nobody has posted about (322 of 429) into the X content queue, a batch at a time. The calendar is derived from the publisher's own cadence and rotation rules, so it can never promise a slot the scheduler would refuse, and a surface whose frame would carry live third-party market data is flagged for owner approval instead of being quietly packed. Each pack starts as an evidence brief (the rendered live page, the changelog, the docs, the README) whose every fact is already a check the verifier can run; the model chain drafts from that brief and nothing else, and the draft is held against the voice lint, the claims ledger, the evidence list and the account's own archive, then rewritten until it passes. A surface with no route (packages, workers, services) gets a title card typeset from its real README in the site's own fonts, because a post with no image measured 0.875x. Output is a pack plus a queue item at status draft: approval and publishing stay exactly where they were. Tests: tests/announce-factory.test.js
X content pipeline (internal) Queue data/x-content/queue.json, engine api/_lib/x-content/, cron api/cron/x-content.js, CLI scripts/x-content.mjs, media public/x-media/ Internal · docs docs/x-content-pipeline.md, docs/x-story-authoring.md, docs/x-reply-playbook.md The reviewed @trythreews publishing queue: posts and threads with native images, GIFs, and captioned video, blog or external pages imported as native posts or full X Articles (via the X Articles API), a copy lint against automated-feed tells, jittered cadence with lane rotation, and a database ledger that resumes a half-sent thread instead of reposting. A post's video is a proof reel (reel.js): a filmed, passing end-to-end run of its own scenario against production, so a feature that does not work cannot be announced. The queue learns from its own measured results (outcomes.js), releases filmed posts by policy with a veto window (approval.js), and can ship an approved post without a deploy as a signed bundle (overlay.js). A daily partner spotlight (partners.js, CLI scripts/x-partners.mjs, registry data/x-content/partners/, docs docs/x-partner-series.md) owns the prime-time slot: one partner and one feature built on it each day, filmed live, drafted from registry facts only, plus a weekly partner deep-dive X Article built from every feature's run, and a scheduled Cloud Run Job runner (deploy/x-partners/, setup scripts/create-x-partners-job.mjs). Previews only until X_CONTENT_AUTO_PUBLISH=true. Tests: tests/x-content.test.js, x-content-reel, x-content-approval, x-content-outcomes, x-content-overlay, x-content-partners
X post archive + engagement analysis (internal) Snapshots data/x-archive/, schema api/_lib/migrations/20260814120000_x_account_archive.sql, normalization + analysis scripts/x-archive-lib.mjs, commands scripts/x-archive-import.mjs · scripts/x-archive-refresh.mjs · scripts/x-archive-analyze.mjs, report docs/x-archive/ Internal · doc docs/x-archive.md Every post our own X accounts published, kept as raw snapshot files and indexed into x_account_posts / x_account_post_snapshots so engagement is a measured time series rather than a memory. npm run x:archive:analyze regenerates a report ranking posts by engagement and by engagement rate, and scores every measurable signal (media, mentions, length, subject, hour) as lift against the corpus median. Two scraper defects are handled rather than inherited: a profile scrape returns reposts of other accounts with isRetweet: false (authorship is read from the permalink instead), and X renders like counts lazily so real posts arrive at "0 likes" (those are archived, named, and excluded from the medians until npm run x:archive:refresh replaces them with exact X API counters). Distinct from x_posts, which is what platform users publish through api/x/post.js. npm run x:archive:price (scripts/x-archive-price-impact.mjs, logic in api/_lib/x-content/price-impact.js) joins every post to the $THREE/SOL price at post time and its +1h/+4h/+24h returns against an any-time baseline, writes public/data/trythreews-post-impact.json for the Posts view on the $THREE oracle chart (public/oracle-coin.js), and stamps the content pipeline's outcome rows with a +24h price return (api/_lib/x-content/outcomes.js). Tests: tests/x-archive.test.js
X mention-reply bot + operator console Reader api/_lib/x-mentions.js, real-time webhook api/x/webhook.js → /api/x/webhook (Account Activity API, CRC + HMAC signature verified, gated by X_WEBHOOK_ENABLED), pure intent parser api/_lib/x-mention-intents.js, ledger api/_lib/x-mention-store.js (x_mention_events), per-agent decisions endpoint api/x/mention-decisions.js → /api/x/mention-decisions, operator controls api/_lib/x-mention-admin.js (kill switch, blocklist, live-send), console API api/x/ops/[action].js → /api/x/ops/*, console page pages/x-ops.html + src/x-ops.js + src/x-ops.css → /x/ops (admin-only, noindex), health api/_lib/x-mention-health.js feeding /api/healthz, public status api/x/mention-bot/status.js → /api/x/mention-bot/status (shown on /grok) Console: Live (admin-only) · Webhook: receives and records (not yet live-replying) · doc docs/x-mention-bot.md (internal) Every @-mention of a company or agent X account, delivered by polling or by the Account Activity webhook, is parsed into one of seven intents (never treated as an instruction to spend, transfer, launch or post on its own) and recorded once per tweet id before any reply is composed; a reply can be captured dry-run (recorded, never sent) or live. /x/ops is the admin review surface over that ledger: filter by account, intent, decision and dry-run status, read the full mention and would-be-reply text, pause or resume the bot (app_settings kill switch, also honored via X_MENTION_BOT_PAUSED), blocklist or unblock an author, and, for one dry-run reply row, send that exact already-composed reply live (company account via OAuth 1.0a, agent account via its own OAuth2 connection) behind an explicit "this posts publicly" confirmation. The enforcement side (a poll cron honoring the kill switch and blocklist, composing and sending replies automatically) is a separate piece of work tracked in the x-grok campaign; this console and webhook only ever write the switches and ledger rows they are responsible for. Tests: tests/x-ops-authorization.test.js, tests/api/x-webhook.test.js, tests/x-mention-health.test.js
X launch-by-mention Handler api/_lib/x-mention-launch.js (called from composeAnswer in api/_lib/x-mention-poll.js), grammar parseLaunch in api/_lib/x-mention-intents.js Dry run until X_MENTION_BOT_LIVE=1 (owner order 928) · doc docs/x-mention-bot.md @trythreews launch <NAME> $<TICKER> [description] is answered with a prefilled /launch link for the author's linked three.ws agent (or a sign-in, create-agent or give-it-a-body link). The bot never launches or spends: the author reviews the cost and signs on three.ws. Tests: tests/x-mention-launch.test.js
Interactive 3D history timeline pages/timeline.html → /timeline, src/timeline.js, data data/timeline.json Live three.ws's public history (launches, partnerships, listings, press, product ships) as an explorable 3D scene: 60+ milestones as glowing markers along a curved path, 360° free-orbit or a marker-to-marker Walk mode with a guide beacon (reuses the shared AnimationManager + default rig from src/walk.js's pattern), a synced bottom scrubber, category filters, and a detail panel linking to the original source where one exists (IBM Community, NVIDIA Developer Forums, Yahoo Finance, Phemex, CoinGecko, HackerNoon). Real accessible HTML-list fallback for no-WebGL or fetch-failure.
Upstream resilience toolkit scripts/resilience/ + scripts/audit-upstreams.mjs → npm run audit:upstreams, baseline data/upstream-baseline.json, generated map docs/resilience.md Live Answers the question a fallback alone cannot: when a third-party service is down, what is each endpoint ALLOWED to say? An AST pass grades every outbound call site on five protections (deadline, retry, failover, last-good, breaker) and ratchets against a committed baseline, so a new unbounded call fails the build while the existing tail is paid down at its own pace. On top of it, endpoints declare a degradation contract (may-serve-stale, must-refuse, must-not-serve-stale) that tests/upstream-degradation.test.js proves by replacing fetch with a dead upstream and judging the real response. Built after four fallbacks that each passed review turned out to serve remembered data on paths where staleness costs money or grants access. Complements scripts/check-fetch-timeouts.mjs, which enforces the deadline floor. Docs: scripts/resilience/README.md
Ecosystem hubs (curated directories) hubs/ Ready to publish as separate repos Eleven self-contained JSON-backed awesome-list hubs (agent payments, identity, wallets, protocols, skills, data APIs, browser agents, Solana agents, embodied agents, generative 3D, Robinhood Crypto), each with schema, validator, README generator and contribution templates. Index: hubs/README.md

Workers and services not mapped above

One-liners for every workers/<name>/ and services/<name>/ directory that no surface-map row already covers:

Worker / service What it does
workers/oracle/ Score / agent / settle loops powering /oracle. Runs in production inside the API container via the every-2-minutes api/cron/oracle-score.js; the same modules also run as a long-lived process (npm run worker:oracle)
workers/agent-anchor/ Newsroom Anchor worker: turns market intel into anchor-read segments
workers/agent-forge/ Headless Live Avatar Forge caster: forges on a free lane and broadcasts the GLB onto an agent's live screen. Operator-run CLI, not a deployed service
workers/agent-mm/ Launch Copilot market-maker engine (rules-based)
workers/agent-orders/ Programmable Orders Engine: limit / stop / trailing / DCA / TWAP / conditional orders swept against live quotes and fired through the audited agent-trade path. Includes the trail_ratchet two-phase stop and stable exit reason codes. Cloud Run deploy is one command (workers/agent-orders/README.md), owner-gated, so orders stay active until it runs
workers/agent-screen-worker/ Stagehand-driven real browser worker behind the agent screen cast
workers/avatar-pipeline-controller/ FastAPI CPU orchestrator behind Scan-yourself-to-3D (multi-backend lane; not deployed today, GCP_RECONSTRUCTION_URL points at avatar-reconstruction)
workers/deploy/ Cloud Run deploy runbook for the selfie-to-3D pipeline
workers/longcat/ LongCat-Video-Avatar-1.5 talking-avatar worker. Built and tested, not deployed: the resident weight set is ~45 GB, so it needs one 80 GB GPU (A100-80GB/H100-80GB on Compute Engine) rather than a Cloud Run L4. Until LONGCAT_WORKER_URL is set, /api/avatar/video-generate answers its designed 503 worker_unconfigured
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/ Text-guided texturing + magic-brush region retexture GPU server
workers/pump-fun-mcp/ Cloudflare Workers mirror of the canonical pump.fun MCP server
Account linking Telegram sign-in api/auth/telegram/, link codes api/auth/link-codes/, external wallets api/auth/external-wallet/, shared logic api/_lib/account-link/, device page pages/link-device.html → /link-device + src/link-device.js, account panels src/dashboard-next/pages/account-linking.js, CLI three-ws link packages/three-ws-cli/src/link-code.js
Chat trade commands Grammar + confirmation rule api/_lib/gateway/trade-parse.js, handlers api/_lib/gateway/trade-commands.js, wired in commands.js and core.js, P&L share card api/trade-og.js → /api/trade-og?id=&format=png
workers/agent-gateway/ Chat gateway worker: drains gateway_inbox (filled by the webhook receivers in api/gateway/) through handleEvent in api/_lib/gateway/core.js and delivers replies, approval previews, signed approval requests 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. Tests: workers/agent-gateway/tests/
Discord Activity (Forge Room) Page pages/discord-activity.html → /discord-activity + src/discord-activity/app.js, config api/gateway/discord-activity-config.js, OAuth api/gateway/discord-activity-token.js + api/gateway/discord-activity-session.js, auth/session lib api/_lib/gateway/discord-activity-auth.js, room API api/gateway/discord-activity-room/[id].js, store api/_lib/gateway/discord-activity-store.js, agent reactions api/_lib/gateway/discord-activity-agent.js, migration api/_lib/migrations/20261015050000_discord_activity_rooms.sql
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/ 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
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-server.test.js
services/pump-graduations/ Standalone watcher for pump.fun bonding-curve graduations
services/pump-claims/ Real-time listener for GitHub social-fee-PDA claims on the PumpFees program: decodes, attributes to a coin, and writes pump_fee_claims, so api/_lib/pump-claims.js no longer needs PUMPFUN_BOT_URL for that path. Docs: README, docs/pump-claims-channel.md
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/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-threat-model.md. Tests: tests/home-relay-protocol.test.js, tests/home-relay-transport.test.js
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.

npm workspaces

Workspaces declared in package.json, plus a few in-repo publishable packages that ship the same way but are not in the workspaces array (packages/retarget, packages/concierge-mcp, assistant-sdk, concierge-sdk, chat-plugin):

agent-payments-sdk/           → @three-ws/agent-payments (fork of @pump-fun/[email protected])
agent-ui-sdk/                 → @three-ws/agent-ui
avatar-sdk/                   → @three-ws/avatar
page-agent-sdk/               → @three-ws/page-agent        (talking page guide: drop-in rigged 3D agent that narrates any page)
character-studio/             → @m3-org/characterstudio (fork)
mcp-bridge/                   → @three-ws/mcp-bridge
mcp-server/                   → @three-ws/mcp-server
multiplayer/                  → @three-ws/multiplayer
services/liquidation-collector/ → @three-ws/liquidation-collector (standalone Binance/Bybit/OKX liquidation stream collector, ported from SperaxOS)
services/home-relay/          → home-relay                  (terminates the outbound WebSocket a LAN-only Home Assistant dials, multiplexes allowlisted platform sessions onto it)
services/home-satellite/      → @three-ws/home-satellite    (Wyoming voice satellite: gives the household's own Home Assistant Assist pipeline a 3D face, plus the hosted room hub)
chat-plugin/                  → @three-ws/chat-plugin       (LobeChat/SperaxOS sidebar plugin: embodied 3D avatar reacting to tool calls; standalone manifest + React component)
packages/avatar-schema/       → @three-ws/avatar-schema
packages/avatar-cli/          → @three-ws/avatar-cli
packages/retarget/            → @three-ws/retarget          (humanoid bone canonicalizer + clip retargeting engine, extracted from src/)
packages/viewer-presets/      → @three-ws/viewer-presets
packages/defi-utils/          → @three-ws/defi-utils        (zero-dependency chain/token constants + address/amount validation + formatters, EVM + Solana; ported from SperaxOS)
packages/tool-sdk/            → @three-ws/tool-sdk          (typed MCP tool authoring — defineTool/defineExecutor + permission manifests + toMcpTools adapter; ported from SperaxOS)
packages/avatar-agent-mcp/    → @three-ws/avatar-agent-mcp  (MCP server — avatar agent tools)
packages/pumpfun-mcp/         → @three-ws/pumpfun-mcp       (MCP server — pump.fun launch tools)
packages/ibm-watsonx-mcp/     → @three-ws/ibm-watsonx-mcp   (MCP server — IBM watsonx.ai)
packages/ibm-x402-mcp/        → @three-ws/ibm-x402-mcp      (MCP server — IBM x402 payments)
packages/alibaba-cloud-mcp/   → @three-ws/alibaba-cloud-mcp  (MCP server — Alibaba Cloud DashScope: Qwen chat, embeddings, model discovery)
packages/three-token-mcp/     → @three-ws/three-token-mcp   (MCP server — $THREE token tools)
packages/threews-avatar-mcp/  → @three-ws/threews-avatar-mcp (MCP server — three.ws avatar ops)
packages/scene-mcp/           → @three-ws/scene-mcp         (MCP server — text→3D diorama scenes)
packages/blender-mcp/         → @three-ws/blender-mcp       (MCP server - drives a LOCAL headless Blender: inspect/convert/render/script 3D files, plus text-to-3D import)
packages/assistant-mcp/       → @three-ws/assistant-mcp     (MCP server — generate a 3D avatar assistant widget embed)
packages/vanity-mcp/          → @three-ws/vanity-mcp        (MCP server — Solana vanity bounty market + rarity gallery)
packages/naming-mcp/          → @three-ws/naming-mcp        (MCP server — .sol resolve + *.threews.sol identity availability)
packages/intel-mcp/           → @three-ws/intel-mcp         (MCP server — smart-money, signals, KOL, copy-trade intel)
packages/wallet-linkage/      → @three-ws/wallet-linkage    (Solana wallet-linkage scorer: shared fee payer, first-funder, token-account control, direct transfer, funding burst; noisy-OR, 0-100 score; ported from wallet-sleuth)
packages/marketplace-mcp/     → @three-ws/marketplace-mcp   (MCP server — agent marketplace + skills catalog browse)
packages/x402-mcp/            → @three-ws/x402-mcp          (MCP server — self-custodial x402 buyer: find/inspect/pay any service in USDC)
packages/metaplex-agent-mcp/  → @three-ws/metaplex-agent-mcp (MCP server: mint + register on-chain agents in the Metaplex Agent Registry, self-custody or Phantom/Solflare)
packages/onchain-agent-wallets/ → @three-ws/onchain-agent-wallets (MCP server: agent wallets with an SPL-Token-enforced spending allowance, guardrails, x402, revocable custody)
packages/autopilot-mcp/       → @three-ws/autopilot-mcp     (MCP server — agent execution control: scopes, SOL spend caps, propose/execute/undo)
packages/portfolio-mcp/       → @three-ws/portfolio-mcp     (MCP server — portfolio, PnL, balances, trade feed, signed transfers)
packages/hood-portfolios-sdk/ → @three-ws/hood-portfolios-sdk (Robinhood Chain portfolios: universe, generate, backtest, canonical manifest hashing)
packages/provenance-mcp/      → @three-ws/provenance-mcp    (MCP server — append-only, signed, on-chain-verifiable agent action log)
packages/copy-mcp/            → @three-ws/copy-mcp          (MCP server — manage copy-trade follows, sizing & guard rules)
packages/signals-mcp/         → @three-ws/signals-mcp       (MCP server — discover signal feeds by proven edge; rank publishers)
packages/alerts-mcp/          → @three-ws/alerts-mcp        (MCP server — pump.fun alert rules: in-app, webhook, Telegram)
packages/notifications-mcp/   → @three-ws/notifications-mcp (MCP server — inbox, read state, delivery prefs, Web Push)
packages/herald-mcp/          → @three-ws/herald-mcp        (MCP server: an agent tells its human in person, on their own avatar)
packages/billing-mcp/         → @three-ws/billing-mcp       (MCP server — plan quotas, usage, invoices, receipts)
packages/agentcore-payments-mcp/ → @three-ws/agentcore-payments-mcp (MCP server: platform-managed agent payment sessions)
packages/activity-mcp/        → @three-ws/activity-mcp      (MCP server — trending agents/coins, $THREE holder board, activity ticker)
packages/agenc-mcp/           → @three-ws/agenc-mcp         (MCP server — AgenC on-chain task marketplace + agent registry)
packages/agora-mcp/           → @three-ws/agora-mcp         (MCP server — Agora economy: board/pulse/passport reads + register/claim/complete/post writes)
packages/vision-mcp/          → @three-ws/vision-mcp        (MCP server — image understanding via the three.ws vision pipeline)
packages/brain-mcp/           → @three-ws/brain-mcp         (MCP server — multi-provider LLM router)
packages/audio-mcp/           → @three-ws/audio-mcp         (MCP server — TTS, STT, audio-to-face lipsync, motion capture)
packages/kol-mcp/             → @three-ws/kol-mcp           (MCP server — per-wallet KOL portfolio + trade analytics)
packages/clash-mcp/           → @three-ws/clash-mcp         (MCP server — Coin Clash faction battles)
packages/tutor-mcp/           → @three-ws/tutor-mcp         (MCP server — itemized learning-session ledger)
packages/loom-mcp/            → @three-ws/loom-mcp          (MCP server — Loom 3D-creation gallery: browse, fetch, submit)
packages/spatial-mcp/         → @three-ws/spatial-mcp       (Spatial MCP validator, builder + conformance fixture corpus)
packages/agent-sniper/        → @three-ws/agent-sniper      (engine + CLI + MCP server + x402 paid API — autonomous, self-custodial pump.fun sniper)
packages/companion-sdk/       → @three-ws/companion        (personal companion: client + SSE stream, shared triage rules, page stage, CLI, MCP server)
packages/home-bridge/         → @three-ws/home-bridge       (agent to a real home: Home Assistant state + actions, room graph for the 3D scene, physical-action gate)
packages/home-mcp/            → @three-ws/home-mcp          (MCP server: run a real Home Assistant house from any assistant, gate refuses guarded actions over stdio)
walk-sdk/                     → @three-ws/walk             (page walking companion + playground + avatar picker)
herald-sdk/                   → @three-ws/herald           (deliver a message in person: rules engine, avatar/card presenters, sources, CLI)
tour-sdk/                     → @three-ws/tour              (guided site tour: 3D guide walks a live site, spotlights sections)
assistant-sdk/                → @three-ws/assistant        (embeddable 3D avatar assistant widget: loader + one-tag CDN build)
concierge-sdk/                → @three-ws/concierge        (embeddable AI support chat with a lipsyncing 3D avatar)
packages/concierge-mcp/       → @three-ws/concierge-mcp    (MCP server: ask any site's concierge; generate the embed)
packages/ai-sdk/              → @three-ws/ai-sdk           (three.ws tools as Vercel AI SDK tool() definitions: forge, rig, animate, render, agent chat)
packages/langchain/           → @three-ws/langchain        (the same tools as LangChain JS tools, following LangChain's integration-package template)

packages/* is the home for clean, publishable spec/schema/preset packages with no runtime dependency on the main app.

Cross-chain SDKs that ship on their own (sdk/ → @three-ws/sdk, solana-agent-sdk/ → @three-ws/solana-agent, agent-protocol-sdk/ → @three-ws/agent-protocol-sdk) live at the top level but are not npm workspaces.

packages/ is reserved for spec/schema/protocol packages with no runtime dependencies on the main app — things that need to be installable by external consumers (e.g. another team building an avatar viewer that wants to validate our manifest format).

Runtime SDKs and apps live at the top level for historical compatibility with the deploy pipeline and existing import paths.

SDK packages (published)

These wrap already-live platform capabilities (real api/ endpoints + MCP tools) into single-import @three-ws/* SDKs. Each is a zero-dependency, pure-ESM client: it ships src/ directly (no build step), hand-written .d.ts types, and a node --test suite — all green (216 tests across the suite). They share one byte-identical HTTP core (src/http.js: base-URL resolution + typed ThreeWsError/PaymentRequiredError, with 402 carrying the x402 challenge). Verify any of them with cd packages/<name> && node --test test/*.test.js.

Launch state: most are published to npm as @three-ws/<name>. Install with npm i @three-ws/<name>. A few rows are packages finished in tree and queued for their first publish; node scripts/publish-packages.mjs --dry-run prints which is which, live, rather than a claim here going stale. The merchant SDK (@three-ws/x402-server) advertises the two main x402 assets, USDC and $THREE, in one 402 challenge. Publishing is idempotent and the package list is DISCOVERED from the filesystem (every non-private packages/* without a server.json), so a new package ships by existing, not by being added to an array. Runbook: docs/contributing.md.

Package Location Wraps What it does
@three-ws/forge packages/forge/ api/forge*.js, api/mcp-3d.js Text/image/sketch → textured, rig-ready GLB; free TRELLIS lane + paid tiers + auto-rig
@three-ws/names packages/names/ api/sns*.js, api/x402/pay-by-name.js ENS + SNS resolution, *.threews.sol minting, pay-by-name
@three-ws/intel packages/intel/ api/sentiment.js, api/aixbt/, pump_snapshot Token sentiment, narrative intel, momentum scans, token snapshots
@three-ws/vanity packages/vanity/ api/vanity/, src/solana/vanity/ (WASM) WASM-accelerated Solana vanity address mining
@three-ws/reputation packages/reputation/ api/reputation/, api/erc8004/ ERC-8004 agent reputation read + attest
@three-ws/voice packages/voice/ api/asr.js, api/tts/, api/a2f.js ASR + TTS + audio2face lipsync visemes
@three-ws/x402-server packages/x402-server/ api/x402-merchant.js, api/x402-pay.js Merchant/seller side of x402 — turn any endpoint paid
@three-ws/agent-memory packages/agent-memory/ api/agent-memory.js, api/memory/ Embeddings-backed persistent agent memory + entity graph
@three-ws/agenc packages/agenc/ api/agenc/ AgenC coordination protocol — task discovery, status, registry
@three-ws/guardian packages/guardian/ api/guardian/, Granite Guardian Content safety / moderation for agents
@three-ws/glb-tools packages/glb-tools/ _lib/glb-inspect.js, glb-themer.js, bake.js Inspect, re-theme, and bake GLBs from CLI/CI
@three-ws/agent-guards packages/agent-guards/ _lib/agent-spend-policy.js, agent-trade-guards.js Spend + trade guardrails for autonomous agents
@three-ws/agent-vitals packages/agent-vitals/ _lib/agent-vitals/, api/agents/vitals.js, npm run agent:vitals Capability attestation for autonomous agents: not "is it up" but "can it act". Models an agent's preconditions as a causal graph and returns the ROOT blocker plus the command that fixes it, instead of a checklist of symptoms. Docs: docs/agent-vitals.md
@three-ws/agent-runtime packages/agent-runtime/ api/agent/guard.js, api/agent/run.js, chat/src/guard.js Agent decision loop + seven-layer GuardChain (blacklist, intervention, capability, permission, trade, spend, x402), hash-chained action ledger, tx pipeline; server agent loop with read-only tools
@three-ws/skill-license packages/skill-license/ contracts/skill-license/, api/skills/ On-chain skill licenses (SPL NFT + PDA) mint/verify
@three-ws/mocap packages/mocap/ api/mocap/ Motion-capture clips → avatar animation
@three-ws/strategies packages/strategies/ api/strategies.js, dca-strategies.js, copy/mirror engines Automated trading strategies (DCA, copy, mirror)
@three-ws/home-mcp packages/home-mcp/ packages/home-bridge, scripts/home-test-instance.mjs An MCP server that runs a real Home Assistant house from any assistant: rooms and live state, the household's own scenes, and gated service calls. Over stdio the gate REFUSES anything that opens the house, because an MCP client has no person in it to confirm one; the only way through is HOME_ALLOWED_ENTITIES, set by hand by whoever starts the process. Imports the gate from @three-ws/home-bridge rather than keeping a second copy
@three-ws/solana-memo-media-mcp packages/solana-memo-media-mcp/ public/onchain/index.html → /onchain Keyless, read-only MCP server that returns image data URIs embedded in Solana Memo instructions (SPL Memo v1, v2, and the v1-transaction memo program) as validated inline images with signer and SHA-256; address scans pre-filter on the memo summary so 1,000 signatures cost a few RPC calls; read_inscription and /onchain rebuild and verify multi-part first/1, firsts/1 and spl404 inscriptions (src/lib/inscriptions.js, served copy public/onchain/inscriptions.js). Docs: docs/mcp-solana-memo-media.md
@three-ws/pumpfun-skills packages/pumpfun-skills/ pump-fun-skills/ pump.fun create-coin / swap / fees skills (runtime mint)
@three-ws/portal packages/portal/ api/portal Any website as a walkable 3D world: pure layout, API client, CLI, MCP server
@three-ws/home-bridge packages/home-bridge/ docs/smart-home.md The agent's connection to a real house. Live Home Assistant entity state and service calls over the first-party WebSocket API, the user's own curated tools over the mcp_server MCP endpoint, a floor/area/entity room graph with per-room lighting, climate and security rollups for the 3D scene, household macros resolved to the scenes the user already built, and a physical-action gate that never lets an unlock through without an explicit yes. Zero device code: Home Assistant owns Zigbee, Z-Wave, Matter, Thread and the other 1,500 integrations. Docs: docs/smart-home.md
@three-ws/irl packages/irl/ api/irl/, _lib/geohash.js Geofenced real-world presence + nearby discovery
@three-ws/sign-language packages/sign-language/ /sign-language, /asl-alphabet, signed chat replies The ASL engine as a published bundle: text → one signed clip, zero runtime dependencies
@three-ws/pose packages/pose/ get_pose_seed, api/mcp-3d.js Pose-seed generation for rigged avatars
@three-ws/motion packages/motion/ api/motion.js, api/_lib/motion-author.js, pages/motion.html → /motion Text and structure to a full-body three.js AnimationClip with no mocap data, no model weights and no renderer: a Motion Score (a compact, human-editable description of what the body does) is solved into keyframes by forward and inverse kinematics with balance, ground contact and secondary motion. Zero dependencies, so the same solver runs in the browser page, the API handler and the CLI. Tests: packages/motion/test/
@three-ws/render packages/render/ api/_lib/render-cpu.js The renderer behind every server-side avatar picture on three.ws: a pure-JavaScript software rasterizer that turns a rigged, animated GLB into PNG, animated PNG or truecolor terminal output with no GPU, no WebGL and no headless browser. It replaced a headless-chromium pipeline that cost a 300 MB browser launch and 3 to 15 seconds per cold render, which is what made social-card and batch rendering fit inside a serverless budget at all. Sibling of packages/tty-3d/, which owns the terminal-only path. Tests: packages/render/tests/
@three-ws/avatar-stream packages/avatar-stream/ api/avatar-stream.js, src/stream-demo.js, pages/stream.html → /stream Progressive 3D over plain HTTP. Packs a GLB into a layered A3S stream whose first 50 KB is already a complete, skinned, spec-valid avatar, then refines it in place with byte-range requests, so a viewer on a slow connection gets something posable immediately instead of a spinner until the last byte. No custom server, no WebSocket, no new codec: range requests are the whole transport. Tests: packages/avatar-stream/test/
@three-ws/brownout packages/brownout/ docs/brownout.md Data-provenance headers plus request-scoped fault injection: a response says which upstream its data came from and how fresh it is, and a caller can break those upstreams on purpose to prove the integration degrades the way its contract claims. The companion to the resilience audit above, which grades call sites statically; this proves the behaviour at runtime. Tests: packages/brownout/test/
@three-ws/agents packages/agents-sdk/ /api/v1, route logic in api/_lib/agents-v1/ Typed TypeScript client for the v1 Agents API (agents, chat, runs with SSE streaming, skills, automations, wallet, swap) with retries, idempotency keys, typed errors and a client-side confirm gate on fund-moving calls. tsup build, zero runtime dependencies. Not published yet, and most routes it calls are not mounted under /api/v1 yet; its README lists which answer
@three-ws/mcp-policy packages/mcp-policy/ api/_mcp/policy.js, api/mcp-policy.js The tool policy table every MCP server enforces: each tool's group and tier, financial tools off by default and gated on a named confirm flag plus a fresh preview id. ./stdio wires a stdio server in one call. Workspace package, not published yet
@three-ws/agent packages/agent-cli/ @three-ws/agent-runtime, /api/mcp-agent, /api/mcp, /api/v1 Local agent runtime: the agent loop on your own machine with workspace file tools, a resource-limited shell sandbox, the three.ws MCP tools, per-class approvals (financial always asks) and SQLite sessions with full-text search. The runtime core is in tree; the three-ws-agent CLI and TUI entry points it declares are not yet published to npm (both three-ws-agent and @three-ws/agent 404 on the registry)
Wallet and payment accessibility (W3AG) Address formatter src/shared/address.js, modal focus trap src/shared/focus-trap.js, used by src/payment-modal.js, src/wallet/connect-button.js, src/vaults.js Live One formatter draws the short address and announces the full one in groups of four; one trap gives every wallet dialog an inert background, Tab cycling, Escape and focus return. Docs: docs/accessibility.md. Tests: tests/e2e/w3ag-wallet.spec.js, tests/shared-address.test.js

Where things actually live

  • 3D viewer & creator — avatar-sdk/, character-studio/
  • Avatar / accessory assets — public/avatars/, public/accessories/, CC0 parametric-body source data avatar-sources/anny/
  • Animations — public/animations/ (Mixamo FBX → built GLB clips), scripts/build-animations.mjs
  • Animation source clips: animation-sources/ (61 source Mixamo .fbx clips built to GLB by scripts/build-animations.mjs)
  • On-chain identity & contracts — contracts/, packages/avatar-schema/
  • API endpoints — api/ (serverless-style handlers, served in production by the server/ Cloud Run container), workers/ (long-running workers)
  • Examples & demos — examples/, multiplayer/
  • Announcement pipeline: docs/announcements/ holds one evidence-backed pack per feature: the claim, postable copy, media shot IDs, and community variant. npm run announce:rank -- --probe writes the generated data/announcements.json backlog from current pages, packages, workers, services, past coverage, and live route probes. data/announce-media.json drives npm run announce:media; docs/announce-voice.md defines the editorial voice from the engagement archive; npm run check:announce gates each finished pack. Campaign selection, timing, owners, calls to action, and outcome measurement live in the marketing command center and its 90-day campaign ledger. Nothing in this pipeline posts automatically: external publishing stays owner-gated.
  • Marketing assets: marketing/ (produced promo videos + re-render scripts, e.g. marketing/imessage-video/; source-of-truth assets, not shipped to production). The code-rendered motion film pipeline (seekable three.js and screenshot compositions, procedural sound, 16:9 and 9:16 renders, first film "Give your AI a body") lives in marketing/motion-studio/. The narrated product demo lives in marketing/product-demo/: scripts/make-product-demo.mjs (npm run demo:video) films a presenter walking every feature page on the live site, chaptered, with narration from the platform's own TTS lane. Its route is the Feature Tour curriculum, so a new page is in the next recording without editing a script. Docs: docs/product-demo.md
  • Platform agents (server-side): agents/ (endpoint-shopper, fact-checker, tutor, unstoppable, x402-buildout: library modules imported by api/ handlers, each with its own README)
  • Site data files: data/ (pages.json, changelog.json, skills seed, RSS items: what each file drives and which script regenerates it)
  • Repository guards: data/guards.json is the registry of every mechanical check and the stage it runs in (prebuild, gate, deploy build, pre-push, on demand). scripts/audit-guards.mjs proves each entry is real and each stage claim is true, scripts/build-guards.mjs publishes it to public/guards.json, pages/guards.html renders it at /guards, and docs/guards.md plus docs/tutorials/write-a-guard.md document it. There is no CI here, so this is the enforcement layer.
  • Blog: blog/ (hand-authored post HTML plus dataset and syndication companions; SEO injection and routing documented there)
  • Agent work orders: prompts/; everything still open sits in one folder, prompts/finish/; machine-written x402 sweep reports: tasks/
  • Rust crates (WASM): crates/ (vanity-grinder, built via npm run build:wasm)
  • Browser extensions: extensions/ (walk-avatar Chrome extension)
  • Standalone deploy targets: deploy/ (always-on sniper worker; the world.three.ws Hyperfy server)
  • AWS infra: infra/ (AWS CDK stack)
  • Page snapshots: snapshots/ (daily visual record of every page)
  • Maintenance holding page: maintenance/ (zero-build static holding page)
  • Robinhood Chain (4663) developer tooling — robinhood/, standalone packages published to their own nirholas/* GitHub repos (each with its own README): erc8056 (ERC-8056 Scaled UI Amount reference impl), hood-connect (wallet onboarding kit), hood-pay (USDG checkout + payment links), hood-alerts (Telegram/Discord/X launch + whale alerts), hood-status (chain status page), hood-tokenlist (canonical token list), hoodkit/hood402/robinhood-chain-sdk (shared chain + x402 primitives other packages depend on), hood-cli (CLI + the hood init trading-stack setup wizard), hood-launcher, hood-mcp, hood-api, hood-js, hood-traders (autonomous trading fleet, four strategies incl. a bring-your-own-key LLM strategist), robinhood-chain-examples, learn-robinhood-chain. Distinct from the in-repo /play and /markets/robinhood product surfaces above, which live in this repo's own api//src/.
  • Cross-chain SDKs — sdk/, solana-agent-sdk/, agent-payments-sdk/, agent-protocol-sdk/
  • MCP integration — mcp-server/, mcp-bridge/
  • Specs & protocol docs — specs/
  • Vendored third-party reference trees: third_party/ (complete upstream MIT source kept to read, not to build: the Design+Code agent-skill corpus and the ThreeUI Community component library). Read-only, excluded from ESLint, i18n extraction, and the Cloud Build upload. Distinct from the vendor/ directories inside a surface (src/scene-studio/vendor/, public/vendor/, pages/ibm/vendor/), which are third-party code we actually ship.
  • Frontend pages — src/, pages/, public/
  • Tests — tests/

Promotion path

A surface graduates to its own repo only when there is a concrete external need that the monorepo cannot serve:

  1. A third party wants to consume it without pulling our whole tree. Mitigation: publish to npm under @three-ws/* first. If the npm package is enough, no repo split is needed.
  2. Independent release cadence required. When the surface needs its own semver line decoupled from the app.
  3. External contributors blocked. When the repo size or unrelated CI cost is a real friction for outside PRs.

Promotion procedure (when triggered): the directory keeps living in this monorepo (still canonical, still where pull requests go) and gains a generated, read-only mirror instead of being split out. One manifest, data/standalone-mirrors.json, is the source of truth for which directory maps to which public repo:

# 1. Add an entry: { "repo": "<github name>", "path": "packages/<dir>", "direction": "out", "exporter": "sync", "npm": "<package name or null>" }
# 2. Stage it (snapshots the dir, rewrites package.json's repository field, fixes any stale license footer)
npm run sync:repos -- --only <github name>
# 3. The command above prints the push line; running it is the owner's call
git -C dist/standalone-mirrors/<github name> push --force https://github.com/nirholas/<github name>.git HEAD:main

scripts/sync-standalone-repos.mjs never pushes and never calls the GitHub API itself; it only stages under dist/standalone-mirrors/ (gitignored) and prints the command above. npm run sync:repos:check compares what is staged against each mirror's live tree over a codeload tarball and exits non-zero on drift.

Until a surface has a concrete external consumer, skipping the mirror is correct: each one adds a repo to keep in sync for zero functional gain.

The reverse case, retiring a standalone repo that duplicates another repo or has been superseded by an in-repo surface, uses the same stage-then-owner-push split: data/retired-repos.json lists the repo, the reason, and where the capability lives now; node scripts/stage-retired-repo-pointers.mjs writes a one-commit pointer README per entry under dist/retired-repos/<repo>/ (gitignored) and prints the git push --force + gh repo archive command pair for each, never running either.

See also