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.

feat(forge): add TripoSplat image-to-splat worker and /api/forge-splat so one photo becomes a splat the viewer opens

nirholasb72233fb87d9
diff --git a/STRUCTURE.md b/STRUCTURE.md
index e203607cd..ff8ff7636 100644
--- a/STRUCTURE.md
+++ b/STRUCTURE.md
@@ -110,6 +110,7 @@ packages, a generated standalone GitHub mirror). See
| Visitor feedback loop | Recorder [@three-ws/witness](packages/witness), capture + panel [src/feedback-companion.js](src/feedback-companion.js) (mounted by [src/walk-companion.js](src/walk-companion.js)), intake [api/feedback/report.js](api/feedback/report.js), queue API [api/feedback/index.js](api/feedback/index.js), scoring [api/_lib/feedback/triage.js](api/_lib/feedback/triage.js), store [api/_lib/feedback/store.js](api/_lib/feedback/store.js), cron [api/cron/feedback-triage.js](api/cron/feedback-triage.js), review page [pages/feedback.html](pages/feedback.html) `→ /feedback` + [src/feedback-page.js](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/feedback.md), [docs/witness.md](docs/witness.md). Tests: [tests/feedback-triage.test.js](tests/feedback-triage.test.js) |
| Session-to-test recorder | [packages/witness/](packages/witness) `→ @three-ws/witness`: recorder [recorder.js](packages/witness/src/recorder.js), selector synthesis [selector.js](packages/witness/src/selector.js), capture-time privacy [redact.js](packages/witness/src/redact.js), spec compiler [compile.js](packages/witness/src/compile.js); compiled repros land in [tests/repros/](tests/repros) with [their own Playwright config](tests/repros/playwright.config.mjs) | 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](docs/witness.md). Tests: [packages/witness/test/](packages/witness/test) (36, `npm run test:witness`) |
| Prepaid credits (`/credits`) | [pages/credits.html](pages/credits.html) `→ /credits` + [src/credits.js](src/credits.js), balance/ledger [api/credits/index.js](api/credits/index.js) `→ GET /api/credits`, deposit verifier [api/credits/deposit.js](api/credits/deposit.js) `→ POST /api/credits/deposit` over [api/_lib/credit-deposit.js](api/_lib/credit-deposit.js), ledger engine [api/_lib/credits.js](api/_lib/credits.js), schema [api/_lib/migrations/20260621200000_credits.sql](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](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](api/pricing.js) returns ([api/_lib/three-tier.js](api/_lib/three-tier.js)), which is the discount [api/_lib/credits.js](api/_lib/credits.js) already applies to every debit, and lists what credits buy straight from the pricing catalog ([api/_lib/pricing/catalog.js](api/_lib/pricing/catalog.js)). Ledger is keyset-paginated. Docs: [docs/payment-sessions.md](docs/payment-sessions.md). Tests: [tests/credits.test.js](tests/credits.test.js) |
+| MCP credit plans (`/mcp-plans`) | [pages/mcp-plans.html](pages/mcp-plans.html) `→ /mcp-plans` + [src/mcp-plans.js](src/mcp-plans.js), API [api/mcp-plans.js](api/mcp-plans.js) `→ GET/POST /api/mcp-plans`, meter [api/_lib/mcp-credits.js](api/_lib/mcp-credits.js) wired into [api/_mcp/dispatch.js](api/_mcp/dispatch.js), catalog and purchase [api/_lib/mcp-plans.js](api/_lib/mcp-plans.js), schema [api/_lib/migrations/20261023160000_mcp_plans.sql](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](docs/mcp.md). Tests: [tests/mcp-credit-plans.test.js](tests/mcp-credit-plans.test.js) |
| Developer plans and quotas (`/developers`) | Config [api/_lib/dev-plans/config.js](api/_lib/dev-plans/config.js) (the only place plan numbers live), gate [api/_lib/dev-plans/quota.js](api/_lib/dev-plans/quota.js) wired into [api/_lib/gateway.js](api/_lib/gateway.js) for every `/api/v1` route, subscriptions [api/_lib/dev-plans/subscription.js](api/_lib/dev-plans/subscription.js), checkout + receipts [api/_lib/dev-plans/billing.js](api/_lib/dev-plans/billing.js), per-key analytics [api/_lib/dev-plans/analytics.js](api/_lib/dev-plans/analytics.js), key cache + immediate invalidation [api/_lib/api-key-cache.js](api/_lib/api-key-cache.js), allowlists [api/_lib/ip-allowlist.js](api/_lib/ip-allowlist.js); REST [api/v1/dev-plans.js](api/v1/dev-plans.js) `→ GET /api/v1/dev-plans`, [api/v1/me/dev-plan/](api/v1/me/dev-plan) `→ /api/v1/me/dev-plan{,/checkout,/confirm,/schedule,/receipts}`, key tools [api/keys/[id]/rotate.js](api/keys/%5Bid%5D/rotate.js), [allowlist.js](api/keys/%5Bid%5D/allowlist.js), [analytics.js](api/keys/%5Bid%5D/analytics.js); page [pages/developers.html](pages/developers.html) `→ /developers` + [public/developers.css](public/developers.css); dashboard Plan tab [src/dashboard-next/pages/developers-plan.js](src/dashboard-next/pages/developers-plan.js) `→ /dashboard/developers#plan`, key tools [src/dashboard-next/pages/api-key-tools.js](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](docs/developer-plans.md) |
| Spend and token ceilings (`/spend`) | [pages/spend.html](pages/spend.html) `→ /spend` + [src/spend-page.js](src/spend-page.js), read model [api/spend/me.js](api/spend/me.js) `→ GET /api/me/spend`, ceilings [api/agents/_id/token-budget.js](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 into `assertAgentBudget` in [api/_lib/inference-billing.js](api/_lib/inference-billing.js), counters [api/_lib/migrations/20261010173000_agent_token_budgets.sql](api/_lib/migrations/20261010173000_agent_token_budgets.sql), free-tier choices [api/_lib/free-tier.js](api/_lib/free-tier.js) | Live | Per-agent hourly, daily and per-run token ceilings enforced before the model call with one conditional upsert per window (two calls racing for the last token admit exactly one), next to the dollar budget. Hitting a ceiling pauses the agent, notifies the owner (`token_budget_paused`) and opens one extend-once approval (venue `token_budget`); resume refuses while the window is still full (`409 still_capped`). The spend page shows balance, month-to-date and projected month end, per-agent usage by day, model and tool, and every 50/80/100 percent alert (`spend_cap_alert`) from the same latches the bell uses. The free-tier `429 free_tier_exhausted` body carries `choices` (wait, top up, bring your own key, and a one-step `paid_fallback` on brain chat, copilot and v1 messages). Docs: [docs/inference-billing.md](docs/inference-billing.md). Tests: [tests/token-budgets.test.js](tests/token-budgets.test.js). |
| Agent lifecycle, runs and automations over MCP (Runs tab) | MCP tools [api/_mcp/tools/agent-lifecycle.js](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/](api/_lib/agents-v1) (runs, automations, run receipts), policy rows in [packages/mcp-policy/src/table.js](packages/mcp-policy/src/table.js); replay endpoint [api/agent-run-replay.js](api/agent-run-replay.js) `→ /api/agent-run-replay`; Runs tab [src/agent-run-replay.js](src/agent-run-replay.js), mounted from [src/avatar-page.js](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.md) `→ /docs/mcp`, [docs/agent-runtime.md](docs/agent-runtime.md#autonomous-runs-budgets-receipts-and-replay). Tests: [tests/mcp-agent-lifecycle.test.js](tests/mcp-agent-lifecycle.test.js), [tests/agent-run-replay-endpoint.test.js](tests/agent-run-replay-endpoint.test.js) |
@@ -124,7 +125,7 @@ packages, a generated standalone GitHub mirror). See
| Agent payment sessions (`/payments`) | [pages/payments.html](pages/payments.html) `-> /payments`, API [api/pay/session.js](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/execute.js) + [api/pay/simulate.js](api/pay/simulate.js), engine [api/_lib/pay/payment-session.js](api/_lib/pay/payment-session.js) + governor [api/_lib/pay/spend-governor.js](api/_lib/pay/spend-governor.js), expiry sweep [api/cron/payment-session-sweep.js](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](packages/agentcore-payments-mcp), and cancel-and-refund. Press `N` for the create dialog. Docs: [docs/payment-sessions.md](docs/payment-sessions.md), [docs/tutorials/agent-spending-envelope.md](docs/tutorials/agent-spending-envelope.md). Tests: [tests/payment-session-governor.test.js](tests/payment-session-governor.test.js), [tests/payment-session-sweep.test.js](tests/payment-session-sweep.test.js) |
| Skill bundles (seller builder + evidence pricing) | [pages/bundles.html](pages/bundles.html) `→ /bundles`, API [api/agents/[id]/bundles.js](api/agents/%5Bid%5D/bundles.js), arithmetic [api/_lib/bundle-pricing.js](api/_lib/bundle-pricing.js), checkout [api/marketplace/purchase-bundle.js](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](docs/skill-bundles.md). Tests: [tests/bundle-pricing.test.js](tests/bundle-pricing.test.js), [tests/vercel-agents-subpath-routes.test.js](tests/vercel-agents-subpath-routes.test.js) |
| External skill import (browse, scan, approve, fork, publish) | [pages/skills-import.html](pages/skills-import.html) `→ /skills/import` + [src/skills-import.js](src/skills-import.js), REST [api/skill-imports.js](api/skill-imports.js) `→ /api/skill-imports/*`, registries and pinning [api/_lib/skill-import-sources.js](api/_lib/skill-import-sources.js), scanner [api/_lib/skill-import-scan.js](api/_lib/skill-import-scan.js), store [api/_lib/skill-import-store.js](api/_lib/skill-import-store.js), chat spend gate [api/_lib/skill-import-gate.js](api/_lib/skill-import-gate.js), MCP [api/_mcp/tools/skill-imports.js](api/_mcp/tools/skill-imports.js), migration [api/_lib/migrations/20261011013000_skill_imports.sql](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](docs/skill-import.md), manifest spec [specs/SKILL_REGISTRY_MANIFEST.md](specs/SKILL_REGISTRY_MANIFEST.md), live check [scripts/skill-import-live-check.mjs](scripts/skill-import-live-check.mjs). |
-| Skill import from an OpenAPI spec or GitHub repo | Package [packages/skill-import/](packages/skill-import/README.md) (parser, operation classifier, handler/manifest/SKILL.md generators), REST [api/skills/import.js](api/skills/import.js) `→ POST/GET /api/skills/import`, [api/skills/import/[id].js](api/skills/import/%5Bid%5D.js) `→ GET/PATCH/DELETE` (enable/disable/delete, owner-scoped), bundle host [api/skills/import/[id]/[...file].js](api/skills/import/%5Bid%5D/%5B...file%5D.js), store [api/_lib/openapi-skill-imports.js](api/_lib/openapi-skill-imports.js), migration [api/_lib/migrations/20261015130000_openapi_skill_imports.sql](api/_lib/migrations/20261015130000_openapi_skill_imports.sql), UI tab "From an API" in [pages/skills-import.html](pages/skills-import.html) `→ /skills/import` + [src/skills-import.js](src/skills-import.js), CLI `three-ws skills import <url>` / `three-ws skills drafts` in [packages/three-ws-cli/src/commands/skills.js](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. Docs: [docs/skills.md](docs/skills.md#importing-a-skill-from-an-openapi-spec-or-a-github-repo). Tests: [packages/skill-import/tests/](packages/skill-import/tests), [tests/openapi-skill-import.test.js](tests/openapi-skill-import.test.js), [packages/three-ws-cli/tests/skills.test.js](packages/three-ws-cli/tests/skills.test.js) |
+| Skill import from an OpenAPI spec, GitHub repo or Solana Anchor IDL | Package [packages/skill-import/](packages/skill-import/README.md) (parser, operation classifier, handler/manifest/SKILL.md generators), REST [api/skills/import.js](api/skills/import.js) `→ POST/GET /api/skills/import`, [api/skills/import/[id].js](api/skills/import/%5Bid%5D.js) `→ GET/PATCH/DELETE` (enable/disable/delete, owner-scoped), bundle host [api/skills/import/[id]/[...file].js](api/skills/import/%5Bid%5D/%5B...file%5D.js), store [api/_lib/openapi-skill-imports.js](api/_lib/openapi-skill-imports.js), migration [api/_lib/migrations/20261015130000_openapi_skill_imports.sql](api/_lib/migrations/20261015130000_openapi_skill_imports.sql), UI tab "From an API" in [pages/skills-import.html](pages/skills-import.html) `→ /skills/import` + [src/skills-import.js](src/skills-import.js), CLI `three-ws skills import <url>` / `three-ws skills drafts` in [packages/three-ws-cli/src/commands/skills.js](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](packages/skill-import/src/anchor-idl.js), migration [20261023120000_openapi_skill_imports_anchor_kind.sql](api/_lib/migrations/20261023120000_openapi_skill_imports_anchor_kind.sql)). Docs: [docs/skills.md](docs/skills.md#importing-a-skill-from-an-openapi-spec-or-a-github-repo). Tests: [anchor-idl.test.js](packages/skill-import/tests/anchor-idl.test.js), [packages/skill-import/tests/](packages/skill-import/tests), [tests/openapi-skill-import.test.js](tests/openapi-skill-import.test.js), [packages/three-ws-cli/tests/skills.test.js](packages/three-ws-cli/tests/skills.test.js) |
| Marketplace analytics & trial funnel | [pages/marketplace-analytics.html](pages/marketplace-analytics.html) `→ /marketplace/analytics`, renderer [src/marketplace-analytics.js](src/marketplace-analytics.js), backend [api/marketplace/analytics.js](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](docs/marketplace.md), tutorial [docs/tutorials/sell-a-skill-with-a-trial.md](docs/tutorials/sell-a-skill-with-a-trial.md). Tests: [tests/marketplace-analytics-paid-only.test.js](tests/marketplace-analytics-paid-only.test.js) |
| OKX.AI marketplace services | [api/okx/3d/[service].js](api/okx/3d/%5Bservice%5D.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](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](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](api/_lib/okx-catalog.js); pipeline: [api/_okx3d/](api/_okx3d); showcase: [pages/agent-identities.html](pages/agent-identities.html) `→ /agent-identities` + [src/agent-identities.js](src/agent-identities.js), fed at runtime by [api/agent-identities.js](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/okx-marketplace.md), [docs/agent-identities.md](docs/agent-identities.md). Tests: [tests/api/okx-forge.test.js](tests/api/okx-forge.test.js) |
| OKX.AI marketplace chat bot host | [workers/okx-chat-bot/](workers/okx-chat-bot) (Cloud Run service `okx-chat-bot`), local revive [scripts/okx-bot-revive.mjs](scripts/okx-bot-revive.mjs) `→ npm run okx:bot`, session seeding [scripts/okx-bot-seed-state.mjs](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](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](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()](workers/okx-chat-bot/provider.js) 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](workers/okx-chat-bot/cloudbuild.yaml) (`--max-instances=1` is load-bearing, one GCS state writer). Tests: [tests/okx-chat-bot.test.js](tests/okx-chat-bot.test.js) |
@@ -154,7 +155,7 @@ packages, a generated standalone GitHub mirror). See
| AR-ready exports ("View in your space") | Device-routing core [api/_lib/ar-launch.js](api/_lib/ar-launch.js), UA-branched launch endpoint [api/ar.js](api/ar.js) `→ /api/ar`, the actual AR page it hands off to [pages/ar-view.html](pages/ar-view.html) + [src/ar-view.js](src/ar-view.js) `→ /ar/view`, MCP tool [api/_mcp3d/tools/ar.js](api/_mcp3d/tools/ar.js) (`export_ar`, free), in-viewer AR button [public/viewer.html](public/viewer.html), docs [docs/ar.md](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](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/ar-export.test.js), [tests/api/ar-endpoint.test.js](tests/api/ar-endpoint.test.js). Evidence: [prompts/store-submissions/_generated/ar/](prompts/store-submissions/_generated/ar/). Store-submission prompt 21. |
| AR Forge (prompt → model → your room) | [public/ar-forge.html](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](pages/daily.html) `→ /daily` + [src/daily.js](src/daily.js), deterministic theme rotation [src/daily/daily-theme.js](src/daily/daily-theme.js), streak state machine [src/daily/creator-streak.js](src/daily/creator-streak.js) | Live | The **anonymous-first retention loop** the platform lacked: the logged-in streak system ([api/_lib/streaks.js](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/daily-theme.test.js), [tests/creator-streak.test.js](tests/creator-streak.test.js). |
-| AR Studio (multi-model live camera scene) | [pages/ar-studio.html](pages/ar-studio.html) `→ /ar/studio` + [src/ar-studio.js](src/ar-studio.js), multi-anchor WebXR session [src/ar/multi-place.js](src/ar/multi-place.js), pure scene math [src/ar/studio-scene.js](src/ar/studio-scene.js) | 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](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](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](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](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](multiplayer/src/rooms/StudioRoom.js) + schema [multiplayer/src/studio-schemas.js](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 wrapper [src/ar/studio-net.js](src/ar/studio-net.js), and a shared logical coordinate frame [src/ar/studio-coords.js](src/ar/studio-coords.js) (relEast/relNorth/yawDeg) so every device agrees on placement; QR-marker colocalization ([src/irl/marker-anchor.js](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: [tests/ar-studio-scene.test.js](tests/ar-studio-scene.test.js), [tests/ar-studio-coords.test.js](tests/ar-studio-coords.test.js), [tests/ar-estimated-lighting.test.js](tests/ar-estimated-lighting.test.js), [tests/studio-room.test.js](tests/studio-room.test.js). **Shipped as open source:** the same surface is extracted, generalized and published as [3d-ar-studio](https://www.npmjs.com/package/3d-ar-studio) (repo [nirholas/3D-AR-Studio](https://github.com/nirholas/3D-AR-Studio), 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. |
+| AR Studio (multi-model live camera scene) | [pages/ar-studio.html](pages/ar-studio.html) `→ /ar/studio` + [src/ar-studio.js](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/](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](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](packages/ar-studio/src/studio/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](packages/ar-studio/src/studio/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](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](multiplayer/src/rooms/StudioRoom.js) + schema [multiplayer/src/studio-schemas.js](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](packages/ar-studio/src/studio/net.js) (hosted-server binding in [src/ar/studio-net.js](src/ar/studio-net.js)), and a shared logical coordinate frame [packages/ar-studio/src/studio/coords.js](packages/ar-studio/src/studio/coords.js) (relEast/relNorth/yawDeg) so every device agrees on placement; QR-marker colocalization ([src/irl/marker-anchor.js](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-package-parity.test.js), [tests/ar-studio-scene.test.js](tests/ar-studio-scene.test.js), [tests/ar-studio-coords.test.js](tests/ar-studio-coords.test.js), [tests/ar-estimated-lighting.test.js](tests/ar-estimated-lighting.test.js), [tests/studio-room.test.js](tests/studio-room.test.js). **Shipped as open source:** the same surface is extracted, generalized and published as [3d-ar-studio](https://www.npmjs.com/package/3d-ar-studio) (source of truth is [packages/ar-studio/](packages/ar-studio), mirrored to [nirholas/3D-AR-Studio](https://github.com/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](pages/portal.html) `→ /portal` + controller [src/portal/main.js](src/portal/main.js), renderer [src/portal/render.js](src/portal/render.js), styles [src/portal/portal.css](src/portal/portal.css); reader [api/_lib/portal/outline.js](api/_lib/portal/outline.js) + guarded fetch [api/_lib/portal/fetch-site.js](api/_lib/portal/fetch-site.js) + robots matcher [api/_lib/portal/robots.js](api/_lib/portal/robots.js); pure layout [packages/portal/src/layout.js](packages/portal/src/layout.js); GLB export [api/_lib/portal/world-glb.js](api/_lib/portal/world-glb.js); endpoint [api/portal.js](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/](packages/portal). Docs: [docs/portal.md](docs/portal.md). Spec: [specs/PORTAL_WORLD.md](specs/PORTAL_WORLD.md). Tests: [tests/portal-robots.test.js](tests/portal-robots.test.js), [tests/portal-outline.test.js](tests/portal-outline.test.js), [tests/portal-layout.test.js](tests/portal-layout.test.js), [tests/portal-endpoint.test.js](tests/portal-endpoint.test.js), [tests/e2e/portal.spec.js](tests/e2e/portal.spec.js) |
| IRL (agents in the real world) | [pages/irl.html](pages/irl.html) `→ /irl` + [src/irl.js](src/irl.js), WebXR placement [src/ar/webxr.js](src/ar/webxr.js) + pinch [src/ar/pinch-scale.js](src/ar/pinch-scale.js), animated Quick Look bake [src/usdz-animated.js](src/usdz-animated.js) (static fallback [src/usdz-pipeline.js](src/usdz-pipeline.js)), backend [api/irl/](api/irl) | Live | Pin an agent at a real GPS spot; discovery is presence-proof-gated ([docs/irl/THREAT-MODEL.md](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](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](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](docs/irl.md). SDK: [packages/irl/](packages/irl). **Share** ([src/irl/share-frame.js](src/irl/share-frame.js), [api/irl/share.js](api/irl/share.js), [api/irl/share/[token].js](api/irl/share/%5Btoken%5D.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/_lib/irl-analytics.js), [api/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](src/irl/visit-link.js) pure rules, [src/irl/visit-banner.js](src/irl/visit-banner.js) the "you're here to meet" banner, printable sign [pages/irl-sign.html](pages/irl-sign.html) `→ /irl/sign?pin=<id>` + [src/irl-sign.js](src/irl-sign.js), dashboard modal in [src/dashboard-next/pages/irl-placements.js](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](src/irl/pin-ar.js): iOS bakes the pin's GLB to an animated USDZ for Quick Look (the banner reads "Talk to <name>" 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](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](docs/irl/street-demo.md). Tests: [tests/irl-visit-link.test.js](tests/irl-visit-link.test.js), [tests/irl-pin-ar.test.js](tests/irl-pin-ar.test.js), [tests/irl-pin-talk.test.js](tests/irl-pin-talk.test.js), e2e [tests/e2e/irl-pin-talk.spec.js](tests/e2e/irl-pin-talk.spec.js). |
| Smart glasses (the nearest-agent cue on your lens) | Pure HUD protocol [src/irl/glasses/protocol.js](src/irl/glasses/protocol.js), controller [src/irl/glasses/bridge.js](src/irl/glasses/bridge.js), Web Bluetooth transport [src/irl/glasses/transport.js](src/irl/glasses/transport.js), device adapters [src/irl/glasses/frame.js](src/irl/glasses/frame.js) (Brilliant Labs Frame) + [src/irl/glasses/g1.js](src/irl/glasses/g1.js) (Even Realities G1), connect sheet [src/irl/glasses/connect-ui.js](src/irl/glasses/connect-ui.js), wired into [src/irl.js](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](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.md) `→ /docs/glasses`, build plan [docs/glasses/meta-ray-ban-display.md](docs/glasses/meta-ray-ban-display.md), platform research [docs/glasses/research.md](docs/glasses/research.md). Tests: [tests/irl-glasses-protocol.test.js](tests/irl-glasses-protocol.test.js) |
@@ -202,7 +203,7 @@ packages, a generated standalone GitHub mirror). See
| Agent-native 3D + embeddable distribution | MCP tool [api/_mcp/tools/agents.js](api/_mcp/tools/agents.js) (`attach_avatar_to_agent`); shared oEmbed provider [api/agent-oembed.js](api/agent-oembed.js) `→ /api/oembed` + builder [api/_lib/embed.js](api/_lib/embed.js) (`forgeEmbedTarget`, shared by `get_embed_code` in [api/_mcp/tools/embed.js](api/_mcp/tools/embed.js)); Forge share page oEmbed discovery [api/forge-share.js](api/forge-share.js) `→ /forge/share/:id`; distribution snippet builders [src/forge-embed-snippets.js](src/forge-embed-snippets.js) + panel [src/forge-embed-panel.js](src/forge-embed-panel.js); autonomous demo [examples/agent-native-3d/](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](specs/EMBED_SPEC.md#share-routes-on-chain-agents). Docs: [docs/mcp.md#attach_avatar_to_agent](docs/mcp.md#attach_avatar_to_agent). Roadmap prompt 10 (closes the roadmap campaign). |
| Animation pipeline | [public/animations/](public/animations) + [scripts/build-animations.mjs](scripts/build-animations.mjs) | In-repo | Mixamo source FBX + GLB retargeting pipeline · see [docs/3d-asset-pipeline.md](docs/3d-asset-pipeline.md) |
| Procedural animation (runtime IK layers) | [src/procedural/](src/procedural) — analytic two-bone IK [two-bone-ik.js](src/procedural/two-bone-ik.js), gaze [look-at.js](src/procedural/look-at.js), terrain foot planting [foot-plant.js](src/procedural/foot-plant.js), drift-free re-application [pose-baseline.js](src/procedural/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](walk-sdk/src/companion.js) `_updateGaze`), the walkaround world ([src/walk.js](src/walk.js) `rebuildFootPlant`), and agent avatars ([src/agent-avatar.js](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](src/idle-animation.js). Docs: [docs/procedural-animation.md](docs/procedural-animation.md). Tests: [tests/procedural-anim.test.js](tests/procedural-anim.test.js), [tests/agent-avatar-look-target.test.js](tests/agent-avatar-look-target.test.js) |
-| Self-hosted 3D GPU fleet (the engines behind the Forge) | [workers/model-trellis2/](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/](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](api/_lib/forge-territory.js) (EU, UK and KR never reach a Tencent-model lane; unknown country fails closed), [workers/model-trellis/](workers/model-trellis), [workers/model-hunyuan3d/](workers/model-hunyuan3d) (2.0 + 2.1 PBR + 2.1 RTX), [workers/model-triposg/](workers/model-triposg), [workers/modly/](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-triposr), [workers/model-text2motion/](workers/model-text2motion), [workers/rig/](workers/rig) (auto-rigging, deployed as `model-rig`), [workers/rig-nonhuman/](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/](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/](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/](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/avatar-reconstruction/](workers/avatar-reconstruction), CPU stages [workers/rembg/](workers/rembg) · [workers/remesh/](workers/remesh) · [workers/segment/](workers/segment) · [workers/stylize/](workers/stylize), talking-avatar video [workers/longcat/](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/](workers/model-video2scene), selfie-pipeline CPU orchestrator [workers/avatar-pipeline-controller/](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" | "momask"`) is the text→motion lane behind `GCP_TEXT2MOTION_URL`, the `text_to_animation` MCP tool, and `POST /api/forge-motion`: prompt in, a retargetable three.js `AnimationClip` out, applied with the same engine (`src/animation-retarget.js`) as the curated animation library. It is the one GPU service whose production URL points at us-east4, and its `cloudbuild.yaml` deploys both regions from one image so the standby never lags. Ops map: [docs/ops/gcp-credits-plan.md](docs/ops/gcp-credits-plan.md) |
+| Self-hosted 3D GPU fleet (the engines behind the Forge) | [workers/model-trellis2/](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/](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](api/_lib/forge-territory.js) (EU, UK and KR never reach a Tencent-model lane; unknown country fails closed), [workers/model-trellis/](workers/model-trellis), [workers/model-hunyuan3d/](workers/model-hunyuan3d) (2.0 + 2.1 PBR + 2.1 RTX), [workers/model-triposg/](workers/model-triposg), [workers/modly/](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-triposr), [workers/model-text2motion/](workers/model-text2motion), [workers/rig/](workers/rig) (auto-rigging, deployed as `model-rig`), [workers/rig-nonhuman/](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/](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/](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/](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/](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/avatar-reconstruction/](workers/avatar-reconstruction), CPU stages [workers/rembg/](workers/rembg) · [workers/remesh/](workers/remesh) · [workers/segment/](workers/segment) · [workers/stylize/](workers/stylize), talking-avatar video [workers/longcat/](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/](workers/model-video2scene), selfie-pipeline CPU orchestrator [workers/avatar-pipeline-controller/](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" | "momask"`) is the text→motion lane behind `GCP_TEXT2MOTION_URL`, the `text_to_animation` MCP tool, and `POST /api/forge-motion`: prompt in, a retargetable three.js `AnimationClip` out, applied with the same engine (`src/animation-retarget.js`) as the curated animation library. It is the one GPU service whose production URL points at us-east4, and its `cloudbuild.yaml` deploys both regions from one image so the standby never lags. Ops map: [docs/ops/gcp-credits-plan.md](docs/ops/gcp-credits-plan.md) |
| Self-hosted Granite Guardian (governance lane behind watsonx) | [workers/granite-guardian/](workers/granite-guardian/README.md) (Cloud Run `granite-guardian`, europe-west4, vLLM on one L4), client lane in [api/_lib/granite-guardian.js](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-guardian.test.js), [tests/api/identity-integrity.test.js](tests/api/identity-integrity.test.js) |
| Reconstruct completion backstop (abandoned selfie jobs) | [api/cron/reconstruct-sweep.js](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](api/_lib/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](api/cron/auto-rig-sweep.js), which plays the same role for the rerig lane. Docs: [docs/avatar-reconstruction.md](docs/avatar-reconstruction.md#who-finishes-the-job) |
| Avatar fidelity evaluation (selfie → avatar, scored) | [workers/avatar-reconstruction/eval/](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](workers/avatar-reconstruction/eval/test_identity_eval.py) alongside monotonicity. [`run_eval.py`](workers/avatar-reconstruction/eval/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`](workers/avatar-reconstruction/eval/tune_morph.py) sweeps the morph parameters against ISE offline; [`robustness.py`](workers/avatar-reconstruction/eval/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`](workers/avatar-reconstruction/eval/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](workers/avatar-reconstruction/eval/README.md), program plan [docs/avatar-fidelity-program.md](docs/avatar-fidelity-program.md) |
@@ -247,7 +248,7 @@ packages, a generated standalone GitHub mirror). See
| Third-party display-name safety | [api/_lib/display-name-safety.js](api/_lib/display-name-safety.js), applied at ERC-8004 metadata hydration in [api/cron/[name].js](api/cron/%5Bname%5D.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](scripts/deactivate-slur-agents.mjs) (`--dry-run`). Tests: [tests/display-name-safety.test.js](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](scripts/fbx-to-glb.mjs) | In-repo | Skinned/animated FBX → GLB (FBX2glTF), `npm run convert:fbx` |
| Avatar schema | [packages/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/](packages/readme-3d) | Standalone-ready (npm `readme-3d`, extraction script for [nirholas/readme-3d](https://github.com/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](README.md). Tests: [packages/readme-3d/test/](packages/readme-3d/test) |
+| 3D-in-markdown toolkit | [packages/readme-3d/](packages/readme-3d) | Standalone-ready (npm `readme-3d`, extraction script for [nirholas/readme-3d](https://github.com/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](README.md). In product: `POST /api/readme-3d` ([api/readme-3d.js](api/readme-3d.js), docs in [docs/api/readme-3d.md](docs/api/readme-3d.md)), the `/readme-3d` page ([pages/readme-3d.html](pages/readme-3d.html), [src/readme-3d.js](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](src/readme-3d-copy.js)). Tests: [packages/readme-3d/test/](packages/readme-3d/test) |
| Realtime worlds server (Colyseus) | [multiplayer/](multiplayer) (`@three-ws/multiplayer`): entry [multiplayer/src/index.js](multiplayer/src/index.js), rooms [multiplayer/src/rooms/](multiplayer/src/rooms), wire schemas [multiplayer/src/schemas.js](multiplayer/src/schemas.js), deploy [multiplayer/deploy-cloudrun.sh](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](multiplayer/README.md). Tests: [tests/multiplayer-server-boot.test.js](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/](examples/coach-leo) | In-repo | VR demo |
| Avatar service backend | [api/](api) + [workers/](workers) | In-repo | Serverless-style handlers + Cloudflare workers |
@@ -343,7 +344,7 @@ packages, a generated standalone GitHub mirror). See
| Crypto news + archive + markets hub | [pages/markets.html](pages/markets.html) + [src/markets-page.js](src/markets-page.js) `→ /markets`, [pages/markets-news.html](pages/markets-news.html) + [src/markets-news.js](src/markets-news.js) `→ /markets/news`, [pages/news-article.html](pages/news-article.html) + [src/news-article.js](src/news-article.js) `→ /markets/news/article`, [pages/news-archive.html](pages/news-archive.html) + [src/news-archive.js](src/news-archive.js) `→ /markets/archive`, [pages/news-digest.html](pages/news-digest.html) + [src/news-digest.js](src/news-digest.js) `→ /markets/digest`; backend [api/news/](api/news) (feed, article, knowledge, archive, digest, rss, image) over [api/_lib/article-extract.js](api/_lib/article-extract.js) (page→reader→feed→preview ladder) and [api/_lib/news-rights.js](api/_lib/news-rights.js) (publisher rights layer, enforced at every read path), [api/_lib/news-coins.js](api/_lib/news-coins.js) (ticker→live market snapshot), [api/_lib/news-knowledge-store.js](api/_lib/news-knowledge-store.js) (durable `news_knowledge` corpus) + hourly archiver [api/cron/news-archive-append.js](api/cron/news-archive-append.js) over [api/_lib/news.js](api/_lib/news.js) + [api/_lib/news-sources.js](api/_lib/news-sources.js), corpus on `gs://three-ws-news-archive`, purge tooling [scripts/news-takedown-purge.mjs](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/coin-pages.md), [docs/api-reference.md](docs/api-reference.md), [docs/news-rights.md](docs/news-rights.md) (publisher takedown path) |
| Robinhood Chain markets + buy flow | Hub + detail pages [pages/markets-robinhood.html](pages/markets-robinhood.html) + [src/markets-robinhood.js](src/markets-robinhood.js) `→ /markets/robinhood`, [pages/robinhood-stock.html](pages/robinhood-stock.html) + [src/robinhood-stock.js](src/robinhood-stock.js) `→ /markets/robinhood/stock/:symbol`, [pages/robinhood-coin.html](pages/robinhood-coin.html) + [src/robinhood-coin.js](src/robinhood-coin.js) `→ /markets/robinhood/coin/:address`, buy flow [src/robinhood-purchase.js](src/robinhood-purchase.js), wallet desk [pages/hood-desk.html](pages/hood-desk.html) + [src/hood-desk.js](src/hood-desk.js) + [src/hood-desk.css](src/hood-desk.css) `→ /markets/robinhood/desk`; backend [api/_lib/robinhood.js](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/_lib/robinhood-desk.js)) + [api/x402/robinhood-portfolio.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](tests/robinhood-desk.test.js) (the derivations) and [tests/e2e/hood-desk.spec.js](tests/e2e/hood-desk.spec.js) (the panels, the empty states, the ladder collapse and the trade ticket). Docs: [docs/robinhood-chain-markets.md](docs/robinhood-chain-markets.md) |
| $THREE launchpad (native bonding curve) | Page [pages/three-launchpad.html](pages/three-launchpad.html) + [src/three-launchpad/](src/three-launchpad) `→ /three-launchpad`; backend [api/_lib/native-launch/](api/_lib/native-launch) + [api/native-launch/[action].js](api/native-launch/%5Baction%5D.js); lane toggle in [public/studio/launch-panel.js](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](docs/native-launchpad.md) |
-| Uniswap v4 hooks (EVM) | [contracts/v4-hooks/](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](scripts/uniswap-v4-hook-census.mjs) | 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](contracts/v4-hooks/README.md), [docs/uniswap-v4-hooks.md](docs/uniswap-v4-hooks.md) |
+| Uniswap v4 hooks (EVM) | [contracts/v4-hooks/](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](scripts/uniswap-v4-hook-census.mjs) (decodes permission bits, flags HookForge hooks), HookForge catalog generator [scripts/gen-hookforge-catalog.mjs](scripts/gen-hookforge-catalog.mjs) over the pinned snapshot [data/hookforge-registry.json](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](contracts/v4-hooks/README.md), [docs/uniswap-v4-hooks.md](docs/uniswap-v4-hooks.md) |
| Robinhood Chain coin launches (Pons) | Page [pages/launch-robinhood.html](pages/launch-robinhood.html) + [src/launch-robinhood/page.js](src/launch-robinhood/page.js) `→ /launch/robinhood`; HTTP [api/agents/pons/[action].js](api/agents/pons/[action].js) (`POST /api/agents/:id/pons/{quote,launch}`); custodial launch [api/_lib/evm-leg/pons-launch.js](api/_lib/evm-leg/pons-launch.js); calldata, curve math and launch feed [api/_lib/pons.js](api/_lib/pons.js); agent skill [src/agent-skills-pons.js](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](tests/pons.test.js) rebuilds real mainnet launches byte-for-byte. Docs: [docs/pons-launch.md](docs/pons-launch.md) |
| Paired coins (Robinhood Chain, multi-quote launchpad) | Hub [pages/paired-coins.html](pages/paired-coins.html) + [src/paired/hub.js](src/paired/hub.js) `→ /markets/robinhood/paired`, coin page [pages/paired-coin.html](pages/paired-coin.html) + [src/paired/coin.js](src/paired/coin.js) + trade ticket [src/paired/trade.js](src/paired/trade.js) `→ /markets/robinhood/paired/:address`, launch page [pages/launch-paired.html](pages/launch-paired.html) + [src/paired/launch.js](src/paired/launch.js) `→ /launch/paired`; reads [api/_lib/paired-launchpad.js](api/_lib/paired-launchpad.js) + [api/_lib/paired-markets.js](api/_lib/paired-markets.js) + [api/_lib/paired-directory.js](api/_lib/paired-directory.js) + [api/_lib/paired-trades.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](api/_lib/evm-leg/paired-launch.js) behind [api/agents/paired/[action].js](api/agents/paired/[action].js) (`POST /api/agents/:id/paired/{quote,launch,claim}`, `GET .../fees`); MCP [api/_mcp/tools/paired.js](api/_mcp/tools/paired.js); agent skills [src/agent-skills-paired.js](src/agent-skills-paired.js); contracts [contracts/paired-launchpad/](contracts/paired-launchpad); operator script [scripts/paired-register-quotes.mjs](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](docs/paired-coins.md) |
| Launch lanes (Uniswap pool lane, idempotent EVM launches, lane picker) | Launch page [pages/launch-uniswap.html](pages/launch-uniswap.html) + [src/uniswap-launch/page.js](src/uniswap-launch/page.js) `→ /launch/uniswap`, lane comparison [src/launch/lane-picker.js](src/launch/lane-picker.js) mounted on `/launch`, `/launch/paired` and `/launch/uniswap`; lane config [api/_lib/launch-lanes.js](api/_lib/launch-lanes.js) behind [api/launches/[id].js](api/launches/[id].js) (`GET /api/launches/lanes`, `GET /api/launches/:id`); durable records [api/_lib/evm-launch-records.js](api/_lib/evm-launch-records.js) + [api/_lib/evm-launch-settlers.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-launch.js) + [api/_lib/evm-leg/uniswap-config.js](api/_lib/evm-leg/uniswap-config.js) behind [api/agents/uniswap/[action].js](api/agents/uniswap/[action].js) (`POST /api/agents/:id/uniswap/{quote,launch}`); MCP [api/_mcp/tools/launches.js](api/_mcp/tools/launches.js); contract [contracts/src/ThreeWsUniswapLauncher.sol](contracts/src/ThreeWsUniswapLauncher.sol); doc generator [scripts/gen-launch-lanes-doc.mjs](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](docs/launch-lanes.md) |
diff --git a/api/forge-splat.js b/api/forge-splat.js
index 71c83339b..a95f72ed2 100644
--- a/api/forge-splat.js
+++ b/api/forge-splat.js
@@ -8,7 +8,7 @@
* → { job_id, status, splat_url?, ply_url?, num_gaussians?, viewer_url?, error? }
*
* Routes to workers/model-triposplat (GCP Cloud Run) when MODEL_TRIPOSPLAT_URL
- * is set. The result opens in the Splat Viewer (/splat?url=...).
+ * is set. The result opens in the Splat Viewer (/splat?src=...).
*/
import { cors, json, method, readJson, wrap, rateLimited } from './_lib/http.js';
@@ -101,7 +101,7 @@ async function pollJob(req, res, jobId) {
splat_url: splatUrl,
ply_url: result.plyUrl || null,
num_gaussians: result.numGaussians ?? null,
- viewer_url: splatUrl ? `/splat?url=${encodeURIComponent(splatUrl)}` : null,
+ viewer_url: splatUrl ? `/splat?src=${encodeURIComponent(splatUrl)}` : null,
error: result.error || null,
});
}
diff --git a/data/changelog.json b/data/changelog.json
index 31e270609..593a70c00 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -1,6 +1,15 @@
{
"$comment": "Curated changelog entries for three.ws, the editorial layer of the public changelog. New PAGE launches are tracked automatically via the `added` field in data/pages.json; this file is for everything else holders care about: improvements, fixes, SDK releases, trading/payments capabilities, security work. scripts/build-page-index.mjs merges both sources into CHANGELOG.md, public/changelog.json, and public/changelog.xml. Newest first. Allowed tags: feature, improvement, fix, sdk, infra, docs, security, desktop (desktop entries become the desktop app's release notes). `link` is optional and must be a live three.ws path.",
"entries": [
+ {
+ "date": "2026-10-23",
+ "title": "Chain turnover on /chains",
+ "summary": "The chains leaderboard now has a sortable Turnover column (24h DEX volume divided by TVL) that shows which chains have capital actively trading rather than parked. Chains with no TVL or no reported volume show n/a.",
+ "tags": [
+ "feature"
+ ],
+ "link": "/chains"
+ },
{
"date": "2026-10-23",
"title": "Onchain viewer reads multi-part memo inscriptions",
@@ -8,6 +17,56 @@
"tags": ["feature"],
"link": "/onchain"
},
+ {
+ "date": "2026-10-23",
+ "title": "Prepaid credit plans and free trials for paid MCP tools",
+ "summary": "Buy a credit bundle or a 24-hour or 30-day time pass at /mcp-plans and call paid MCP tools without paying each call over x402. Every account gets 3 free calls per tool. Credits are debited before a call, refunded when the tool errors, and every result reports creditsUsed and creditsRemaining. A drained plan falls back to the per-call payment-required error.",
+ "tags": ["feature"],
+ "link": "/mcp-plans"
+ },
+ {
+ "date": "2026-10-23",
+ "title": "Copy any model as a GitHub README 3D block",
+ "summary": "Forge results, avatar pages, the avatar dashboard and model pages now have a Copy as GitHub README 3D action. It simplifies the model to a size GitHub renders and puts a stl code fence on your clipboard that GitHub shows as an interactive 3D viewer in any README, issue or pull request. The same converter is a free API (POST /api/readme-3d) and has a live page at /readme-3d.",
+ "tags": ["feature"],
+ "link": "/readme-3d"
+ },
+ {
+ "date": "2026-10-23",
+ "title": "AR Studio source now lives in the monorepo",
+ "summary": "The 3d-ar-studio npm package and the /ar/studio page now run the same code: the package source moved into packages/ar-studio and the page imports its scene math, multi-anchor WebXR session, room client and lighting modules directly, so fixes land once instead of in two diverging copies.",
+ "tags": [
+ "sdk",
+ "improvement"
+ ],
+ "link": "/ar/studio"
+ },
+ {
+ "date": "2026-10-23",
+ "title": "Oracle's smart-wallet prior now reads the live database",
+ "summary": "The cold-start wallet prior behind Oracle's pedigree pillar is loaded from the daily-seeded wallet_reputation table instead of a committed June snapshot, so it tracks the current gmgn.ai rankings. It is cached in-process with a bounded refresh, keeps the last good rows if the database blips, and serves an empty prior (and logs it) rather than inventing wallets.",
+ "link": "/docs/oracle",
+ "tags": ["improvement"]
+ },
+ {
+ "date": "2026-10-23",
+ "title": "One catalog for all 39 HookForge hooks, and a census that recognizes them",
+ "summary": "The Uniswap v4 hooks guide now carries the full HookForge registry (39 hooks, pinned by commit) grouped by family, with the agent-native ones linked to their Solana counterparts, plus a design note reconciling AgentTierHook with reputation-fee. The hook census now decodes each hook's 14 permission bits from its address and calls hookName() to flag HookForge hooks when they show up on chain.",
+ "link": "/docs/uniswap-v4-hooks",
+ "tags": [
+ "docs"
+ ]
+ },
+ {
+ "date": "2026-10-23",
+ "title": "Turn a Solana program's Anchor IDL into an agent skill",
+ "summary": "POST /api/skills/import now accepts idl_url or program_id. Each account type becomes a read tool that decodes it by address, each instruction a preview tool that builds the unsigned instruction with a plain summary, and a destructive send tool that hands it to the wallet confirm flow. A risk panel flags token movement, SOL spend, account closure and authority changes. Nothing the skill generates can sign.",
+ "tags": [
+ "feature",
+ "sdk"
+ ],
+ "link": "/skills/import"
+ },
{
"date": "2026-10-23",
"title": "llms.txt links the docs as markdown, and install.md tells an agent how to connect",
@@ -17,11 +76,22 @@
],
"link": "/docs/cli"
},
+ {
+ "date": "2026-10-23",
+ "title": "Splat Viewer: Spark 2.3 level of detail, saved camera hotspots, video export, and image to splat",
+ "summary": "The Splat Viewer now builds a level-of-detail tree for large scenes, lets you save up to 25 camera views as hotspots, play them as a camera path and export it as a video in the browser. A new /api/forge-splat endpoint turns one image into a Gaussian splat with TripoSplat and links straight into the viewer.",
+ "tags": [
+ "feature"
+ ],
+ "link": "/splat"
+ },
{
"date": "2026-10-23",
"title": "Agents answer mentions of their own X account, in their own persona",
"summary": "An agent with its own connected X account and mention replies switched on is now polled by the mention bot. It replies in its own persona, attaches a render of its own avatar to conversational replies, and only acts on the intents its owner allowed, up to a daily cap. Dry run stays the default: nothing posts until the owner turns dry run off and the operator enables live mode. A connection missing the posting scope is reported as missing_scope instead of being polled.",
- "tags": ["feature"],
+ "tags": [
+ "feature"
+ ],
"link": "/agents"
},
{
diff --git a/docs/forge.md b/docs/forge.md
index 97271ef0a..910a60f7f 100644
--- a/docs/forge.md
+++ b/docs/forge.md
@@ -307,6 +307,28 @@ curl -s 'https://three.ws/api/forge-holopart?job=<job_id>'
`/api/forge-segment` and the `partcrafter` backend both produce); FBX is
rejected the same way stylize and segment reject it.
+### Image to splat (TripoSplat)
+
+`/api/forge-splat` turns one reference image into a 3D Gaussian splat with
+[TripoSplat](https://github.com/VAST-AI-Research/TripoSplat) (MIT code and
+weights), served by `workers/model-triposplat`. The result is a `.splat` plus a
+`.ply`, and opens straight in the Splat Viewer.
+
+```bash
+curl -sX POST https://three.ws/api/forge-splat \
+ -H 'content-type: application/json' \
+ -d '{"image_url":"https://.../house.webp","num_gaussians":131072}'
+# → 202 { "job_id": "...", "status": "queued", "eta_seconds": 45 }
+
+curl -s 'https://three.ws/api/forge-splat?job=<job_id>'
+# → { "status": "done", "splat_url": "https://.../t.splat", "ply_url": "https://.../t.ply",
+# "num_gaussians": 131072, "viewer_url": "/splat?src=..." }
+```
+
+`num_gaussians` is 8192 to 262144 (default 131072): fewer is lighter to render,
+more is sharper. Returns 503 `unconfigured` until `MODEL_TRIPOSPLAT_URL` and
+`GCP_RECONSTRUCTION_KEY` point at the deployed worker.
+
**Regenerate part keeps the rig.** Before the regenerated part is swapped
into the live model, Restyle Studio diffs the whole-model bytes HoloPart
received against the whole-model bytes it returned with
diff --git a/docs/splat.md b/docs/splat.md
index 292f4ed46..f0bad0de1 100644
--- a/docs/splat.md
+++ b/docs/splat.md
@@ -58,13 +58,20 @@ Supported inputs at a glance:
- `.splat`: the antimatter15 layout (32 bytes per splat).
- `.ksplat`: the compressed KSplat format for faster loads.
+## Large scenes, hotspots and video
+
+- **Level of detail**: once a scene clears 50,000 splats the viewer builds a Spark 2.3 LoD tree from the decoded buffer in Spark's worker pool, so distant regions render coarser. No network or paging is involved (Spark's `paged` mode streams chunked remote sources and has no path for an in-memory buffer).
+- **Hotspots**: save up to 25 named camera views from the current orbit position, jump to any of them, and see them as markers on the stage.
+- **Camera timeline**: play the saved views in order as a smooth camera path.
+- **Video export**: record the playing path in the browser with `MediaRecorder` and download it. Nothing is uploaded.
+
## States and limits
- **Idle**: prompts you to load a splat, drop a file, or try a sample.
- **Fetching / decoding**: shows the host and the buffer size in MB; large radiance fields take a moment to decode.
- **Error**: an invalid file reports "that file isn't a valid splat"; a blocked fetch explains the CORS limit and suggests downloading then uploading; the retry loads a sample so the stage is never dead.
- **CORS**: only hosts that send permissive cross-origin headers load by URL; the viewer auto-rewrites GitHub, Hugging Face, and Dropbox links, but other hosts may require a local upload.
-- **Client-side only**: files you upload are decoded in the browser and never sent to a server. There is no generation here; this is a viewer for captures produced elsewhere.
+- **Client-side only**: files you upload are decoded in the browser and never sent to a server. Generation is a separate step: `POST /api/forge-splat` (TripoSplat) turns one image into a splat and returns a `viewer_url` that opens here via `?src=`.
- Rendering runs on WebGL; very large scenes are bounded by your device's GPU and memory.
## Related
diff --git a/tests/api/forge-splat.test.js b/tests/api/forge-splat.test.js
index cea7edee7..91ffced51 100644
--- a/tests/api/forge-splat.test.js
+++ b/tests/api/forge-splat.test.js
@@ -139,7 +139,7 @@ describe('GET /api/forge-splat?job=', () => {
expect(body.splat_url).toMatch(/\.splat$/);
expect(body.ply_url).toMatch(/\.ply$/);
expect(body.num_gaussians).toBe(131072);
- expect(body.viewer_url).toBe(`/splat?url=${encodeURIComponent(body.splat_url)}`);
+ expect(body.viewer_url).toBe(`/splat?src=${encodeURIComponent(body.splat_url)}`);
});
it('rejects a missing or malformed job id', async () => {
diff --git a/workers/model-triposplat/README.md b/workers/model-triposplat/README.md
new file mode 100644
index 000000000..3ac29c0a8
--- /dev/null
+++ b/workers/model-triposplat/README.md
@@ -0,0 +1,31 @@
+# model-triposplat
+
+One image in, one 3D Gaussian splat out. Wraps [VAST-AI-Research/TripoSplat](https://github.com/VAST-AI-Research/TripoSplat) (MIT code and weights, LICENSE read 2026-10-12). It is the Forge "Image to splat" lane behind `POST /api/forge-splat`, and its output opens directly in the Splat Viewer (`/splat?src=...`, Spark).
+
+## Contract
+
+| Call | Body / response |
+|---|---|
+| `POST /infer` | `{ images: [data-uri \| https url], num_gaussians?: 8192..262144 }` -> `202 { task_id, status }`. Only the first image is used. |
+| `GET /tasks/:id` | `{ task_id, status, splat_url?, ply_url?, result_gcs_url?, num_gaussians?, elapsed_ms?, error?, error_kind? }` |
+| `GET /health` | `503` with `ok:false` once model load has spent its retry budget. |
+| `GET /` | Unauthenticated descriptor for the warmth probe. |
+
+All calls except `/` and `/health` need `Authorization: Bearer $API_KEY`. Image URLs go through the SSRF-hardened fetcher in `worker_security.py` (https only, private ranges refused). Task state is persisted to GCS so a poll can land on any instance. `num_gaussians` defaults to 131072; upstream's ceiling is 262144.
+
+## Environment
+
+| Var | Purpose |
+|---|---|
+| `API_KEY` | shared bearer secret (`avatar-reconstruction-key`) |
+| `GCS_BUCKET` | output bucket (results under `raw-splats/triposplat/`) |
+| `WEIGHTS_DIR` | default `/weights/triposplat` |
+| `MAX_CONCURRENT` | default 1 (L4, 24 GB) |
+
+## Deploy
+
+Stage weights once with `./stage-assets.sh` (copies `VAST-AI/TripoSplat` from Hugging Face to `gs://three-ws-model-weights/triposplat`), then build and deploy with `gcloud builds submit --config workers/model-triposplat/cloudbuild.yaml` (owner-gated production deploy). Point the API at it with `MODEL_TRIPOSPLAT_URL` plus the shared `GCP_RECONSTRUCTION_KEY`.
+
+## Tests
+
+`python test_splat_prep.py` (pure input/density/naming path; also gates the Docker build). API side: `tests/api/forge-splat.test.js`, `tests/api/gcp-triposplat-provider.test.js`.