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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
docs(freshness): re-verify 49 docs against drifted code and record the reviews, batch 2 of the 403 drain
nirholas6f629b327532
diff --git a/STRUCTURE.md b/STRUCTURE.mdindex 97b6e7ab3..e7e84581e 100644--- a/STRUCTURE.md+++ b/STRUCTURE.md@@ -59,6 +59,9 @@ packages, a generated standalone GitHub mirror). See| Concierge (embeddable AI support chat) | [concierge-sdk/](concierge-sdk), backend [api/concierge.js](api/concierge.js) `→ /api/concierge`, landing [pages/concierge.html](pages/concierge.html) `→ /concierge`, first-party CDN copy `→ /concierge/concierge.global.js` (mirrored by [concierge-sdk/build.mjs](concierge-sdk/build.mjs)) | Published as `@three-ws/concierge` | An AI concierge for ANY website: floating launcher, chat panel with a rigged 3D avatar bust (blink/idle/viseme lipsync via the page-agent stage lineage), SSE-streamed answers grounded in the live page (ask-time DOM harvest + host `knowledge`, no crawler), speaks while streaming (sentence-level TTS handoff), push-to-talk mic, themes/accent/position, avatar picker or custom GLB. Backend is anonymous + CORS-`*` (third-party origins by design) with its own rate buckets (`limits.conciergeIp`/`conciergeGlobal`), no platform-side content filter on the visitor question, and streaming failover over the shared free-first chain (api/_lib/llm.js). Shopping mode (Shopify): when embedded on a Shopify storefront it auto-detects the store (`window.Shopify` / `shop` config) and becomes a shopping assistant, reading the store's public `/products.json` + `/collections.json` + `/policies/*` at ask-time (no key, no crawler, same-origin), retrieving the relevant products per question via keyword+intent search ([concierge-sdk/src/shopify.js](concierge-sdk/src/shopify.js)), grounding the answer in them, and rendering real product cards (image/live price/link + on-store `/cart/add.js` add-to-cart). The endpoint accepts a bounded `shopping` payload and swaps the system prompt to a store assistant. `<three-concierge>` element, `data-concierge` one-tag auto-init, or `new Concierge({...})`. Also reachable from any AI agent via the MCP server [packages/concierge-mcp/](packages/concierge-mcp) (`@three-ws/concierge-mcp`, registry `io.github.nirholas/concierge-mcp`): `concierge_ask` (ask any site's concierge, grounded in the fetched page), `concierge_embed` (generate the embed), `concierge_avatars`. Examples: [concierge-sdk/examples/](concierge-sdk/examples) (one-tag, web component, imperative, custom avatar, React, self-hosted backend). Docs: [docs/concierge.md](docs/concierge.md), tutorial [docs/tutorials/build-a-site-concierge.md](docs/tutorials/build-a-site-concierge.md). Tests: [concierge-sdk/test/](concierge-sdk/test), [tests/api-concierge.test.js](tests/api-concierge.test.js), [packages/concierge-mcp/test/](packages/concierge-mcp/test) || Assistant widget (3D avatar assistant for any website) | Loader [public/assistant/v1.js](public/assistant/v1.js) `-> /assistant/v1.js`, iframe app [pages/assistant-frame.html](pages/assistant-frame.html) + [src/assistant-frame.js](src/assistant-frame.js) `-> /assistant-frame`, builder [pages/assistant.html](pages/assistant.html) + [src/assistant-page.js](src/assistant-page.js) `-> /assistant`, shared validators [src/assistant-widget-core.js](src/assistant-widget-core.js). npm SDK [assistant-sdk/](assistant-sdk) (`@three-ws/assistant`) is the single source for the loader; its [build.mjs](assistant-sdk/build.mjs) emits the npm ESM + the mirrored one-tag build at `public/assistant/v1.js`. MCP server [packages/assistant-mcp/](packages/assistant-mcp) (`@three-ws/assistant-mcp`, registry `io.github.nirholas/assistant-widget`): `build_assistant_widget` (config -> paste-ready snippet + frame URL + JS-API call), `list_assistant_options` (avatars, backgrounds, modes, attributes). | Published as `@three-ws/assistant` | One script tag adds a floating launcher to any site; clicking it pops up a full-body animated avatar against the host page (transparent) or a color/gradient. Two modes: chatbot (free chain via POST /api/chat, or the visitor's own Groq/OpenRouter key sent browser-to-provider, stored in the frame's localStorage only) and speak mode (avatar repeats typed text out loud via Web Speech + head-anchored speech bubble + talking clip). All params re-validated in-frame (CSS/URL injection safe). Sibling of Concierge (chat panel) - this one is the full-body, avatar-first widget. Install three ways: one-tag CDN, `npm i @three-ws/assistant`, or the MCP server for AI agents. Examples: [assistant-sdk/examples/](assistant-sdk/examples). Docs: [docs/assistant-widget.md](docs/assistant-widget.md) `-> /docs/assistant-widget`, tutorial [docs/tutorials/add-a-3d-assistant.md](docs/tutorials/add-a-3d-assistant.md). Tests: [tests/assistant-widget.test.js](tests/assistant-widget.test.js), [assistant-sdk/test/](assistant-sdk/test), [packages/assistant-mcp/test/](packages/assistant-mcp/test) || Forge cost preview + pay-to-keep | [api/forge-quote.js](api/forge-quote.js), [api/forge-keep.js](api/forge-keep.js), [api/_lib/forge-quote.js](api/_lib/forge-quote.js), [api/_lib/forge-keep.js](api/_lib/forge-keep.js), [src/forge-keep.js](src/forge-keep.js), [scripts/forge-pay-to-keep.mjs](scripts/forge-pay-to-keep.mjs) | Live (pay-to-keep off by default) | Public no-spend `GET /api/forge-quote` priced from the real tier and catalog code, shown on `/forge`. Pay-to-keep is gated by `FORGE_PAY_TO_KEEP` (`npm run forge:pay-to-keep -- on`) and reuses the single-use consumption ledger and $THREE hold-or-pay rail. Docs: [docs/forge.md](docs/forge.md#cost-preview-and-pay-to-keep). Tests: [tests/api/forge-quote.test.js](tests/api/forge-quote.test.js), [tests/api/forge-keep.test.js](tests/api/forge-keep.test.js) |+| Forge provider webhook + anon upload sweep | Tripo completion webhook [api/forge/webhook/tripo.js](api/forge/webhook/tripo.js) `→ /api/forge/webhook/tripo`, sweeper [api/_lib/anon-upload-sweep.js](api/_lib/anon-upload-sweep.js) run by the `/api/cron/anon-upload-sweep` cron | Live | The webhook finishes a Tripo job faster than polling (HMAC-SHA256 signature on `TRIPO_WEBHOOK_SECRET` with a 5 minute replay window, deliveries deduplicated in `forge_webhook_deliveries`); polling stays the fallback when no webhook arrives or the secret is unset. The sweeper deletes anonymous presigned-PUT objects that exceed their declared size ceiling. Pipeline: [docs/forge-pipeline.md](docs/forge-pipeline.md) |+| Community agent skills (markdown instructions anyone can contribute) | [community-skills/](community-skills) (`skills/<slug>/`, `registry.json`, [CONTRIBUTING.md](community-skills/CONTRIBUTING.md)), catalog API [api/skills/community.js](api/skills/community.js), page `→ /skills/community` | Live | One-markdown-file skills an agent imports in one click and follows from the next message on. Browse and import at `/skills/community` |+| Agent eval suites | Task suites [evals/suites/](evals/suites), loader [api/_lib/evals/suites.js](api/_lib/evals/suites.js), outcome checks [api/_lib/evals/checks.js](api/_lib/evals/checks.js) | Live | Fixed task sets an agent configuration is scored against: each task names the prompt, the tools the agent may call, the outcome checks, and optional sandbox tools that return only their declared preview and never execute || Chat (conversational surface) | [chat/](chat) `→ /chat` | Live | Svelte 4 + Vite client, fork of eplus, built by `build:chat` inside `build:gcp` into `public/chat` → `dist/chat`. Free Built-in lane via `/api/chat/proxy` plus BYOK providers; inline 3D forge tools + ModelViewer3D; shares the platform wallet via [src/shared/](src/shared). Sign-in is wallet (SIWE/SIWS) or email+password against the platform's own `/api/auth/*`, on the same cookie session as the rest of the site ([chat/src/passwordAuth.js](chat/src/passwordAuth.js)). The app is the chat and only the chat: marketing lives at the site root, and the hash routes that once rendered in-app copies of it resolve to the real page and redirect ([chat/src/three-ui/site-routes.js](chat/src/three-ui/site-routes.js)). Docs: [chat/README.md](chat/README.md). Tests: [tests/chat-app-core.test.js](tests/chat-app-core.test.js) || three.ws's own guided tour + onboarding | [src/feature-tour/](src/feature-tour) `→ /feature-tour.js`, entry [src/feature-tour.js](src/feature-tour.js), curriculum [public/tour/curriculum.json](public/tour/curriculum.json) generated by [scripts/build-tour.mjs](scripts/build-tour.mjs), landing [pages/tour.html](pages/tour.html) `→ /tour` | Live | A hardened, site-native fork of the [tour-sdk/](tour-sdk) engine (same curriculum schema — stops/sections/tracks/highlight/narration/targets), lazy-injected only when a tour is starting/active (`feature-tour-boot` Vite plugin) so pages that never tour pay no Three.js cost. Three tracks share one curriculum: `full` (every feature, chapter by chapter), `quick` (highlighted heroes), and `onboarding` (added 2026-07-12) — a 6-stop, hand-authored new-account walkthrough chaining `/start` → make an avatar (`/create/selfie`) → build a world (`/diorama`) → live `/markets` data → an optional coin launch (`/create-agent`, clearly skippable) → the new creator's own `/profile`. Auto-offered once to a signed-in account with zero creations across avatars/agents/forged models/worlds (`GET /api/me` → `show_onboarding_tour`, backed by `users.onboarding_tour_seen_at`/`onboarding_tour_completed_at`, migration [api/_lib/migrations/20260712030000_onboarding_tour_state.sql](api/_lib/migrations/20260712030000_onboarding_tour_state.sql)); always reachable afterward via "🎬 Replay guided tour" in the [public/getting-started.js](public/getting-started.js) checklist panel. Tests: [tests/feature-tour-curriculum.test.js](tests/feature-tour-curriculum.test.js), [tests/api-me-onboarding-tour.test.js](tests/api-me-onboarding-tour.test.js) || Tour Atlas (visual index + tour health board) | Page [pages/tour-atlas.html](pages/tour-atlas.html) `-> /tour/atlas` + [src/tour-atlas.js](src/tour-atlas.js), manifest source [data/tour-atlas.json](data/tour-atlas.json) published to [public/tour/atlas.json](public/tour/atlas.json) by [scripts/build-tour-atlas.mjs](scripts/build-tour-atlas.mjs), capture [scripts/capture-tour-atlas.mjs](scripts/capture-tour-atlas.mjs) `npm run tour:atlas`, screenshots [public/media/tour/](public/media/tour) | Live | Every stop of the guided tour above, photographed on the live site with the tour's own spotlight ring painted over the feature it is talking about. Searchable by feature, path or narration, filterable by chapter, track, and anchor health; each card is one click from the live tour via `/<path>?tour=start&stop=<id>`. It doubles as the tour's health board: a stop whose CSS anchor rotted, whose page stopped answering, or whose screenshot is missing shows up here and fails `npm run audit:tour-atlas`, which also holds the page's advertised stop count to the manifest's real total. Tests: [tests/tour-atlas.test.js](tests/tour-atlas.test.js) |@@ -221,7 +224,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/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 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/model-sam3d-objects/](workers/model-sam3d-objects) (Meta SAM 3D Objects, SAM License: rebuilds the objects in one photo as a single laid-out scene GLB with named nodes `object_01`, `object_02`, ..., behind `POST /api/forge-scene-objects` ([api/forge-scene-objects.js](api/forge-scene-objects.js)) and the AR Studio "From a photo" tab; needs a 32 GB+ GPU and gated weights, so it answers `503 backend_unconfigured` until `MODEL_SAM3D_URL` is set; built and tested, weights and deploy owner-gated), [workers/avatar-reconstruction/](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) |@@ -348,7 +351,7 @@ packages, a generated standalone GitHub mirror). See| Strategy Objects (settings, research gates, ask-before-trade) | library and builder [pages/strategies.html](pages/strategies.html) `→ /strategies` (`?editor=new`), form + JSON editor [src/shared/strategy-forms.js](src/shared/strategy-forms.js), live preview, text compiler box and gated backtest [src/shared/strategy-settings.js](src/shared/strategy-settings.js), agent panel with mode switch, approvals and decision log [src/shared/agent-strategy-panel.js](src/shared/agent-strategy-panel.js); schema and gate evaluator [api/_lib/strategy-schema.js](api/_lib/strategy-schema.js), gate report [api/_lib/strategy-research.js](api/_lib/strategy-research.js), approvals and decision log [api/_lib/strategy-approvals.js](api/_lib/strategy-approvals.js), preview [api/_lib/strategy-preview.js](api/_lib/strategy-preview.js), runtime [api/_lib/agent-strategy-runtime.js](api/_lib/agent-strategy-runtime.js), APIs [api/strategies.js](api/strategies.js) `→ /api/strategies` and [api/agents/agent-strategy-objects.js](api/agents/agent-strategy-objects.js) `→ /api/agents/:id/strategies`, migration [api/_lib/migrations/20261010140000_strategy_research_gates.sql](api/_lib/migrations/20261010140000_strategy_research_gates.sql) | Built, ships with the next deploy | Version 2 Strategy Objects: source filter, market cap band, SOL size, a price-impact cap that only tightens the agent breaker, nine research gates (holders, largest holder, liquidity, firewall score, mint and freeze authority, creator launches, graduations, dev sold) that fail closed on unknown data, and `ask` (default) or `auto` mode. Every blocked coin is logged with the check and reason; ask mode files a payload-hash approval that executes once after re-checking every guard. The builder edits one config through sliders, toggles and raw JSON, shows a live count of recent launches the settings would have bought, compiles plain English into the fields, and backtests with the gates applied. Doc: [docs/strategy-objects.md](docs/strategy-objects.md). Tests: [tests/strategy-research-gates.test.js](tests/strategy-research-gates.test.js), [tests/strategy-schema.test.js](tests/strategy-schema.test.js) || Sniper Experiments (rules vs LLM A/B fleet) | [pages/sniper-experiments.html](pages/sniper-experiments.html) + [src/sniper-experiments.js](src/sniper-experiments.js) `→ /sniper/experiments`, aggregate [api/sniper/experiments.js](api/sniper/experiments.js), LLM judge [workers/agent-sniper/llm-judge.js](workers/agent-sniper/llm-judge.js), fleet seeding [scripts/seed-sniper-experiments.mjs](scripts/seed-sniper-experiments.mjs) | Live | The sniper fleet runs labeled rule-set variants side by side (strict shields, oracle-gated, and `decision_mode=llm` arms judged per-launch by Grok / Claude / OpenRouter auto with no shields), all behind the same safety rails. The page is the live scoreboard of which entry conditions actually make money; real on-chain fills only. || Backtest integrity and research/live wall | audit, manifests, reproducibility [api/_lib/backtest-integrity.js](api/_lib/backtest-integrity.js), read-only handle [api/_lib/research-context.js](api/_lib/research-context.js), canaries [api/_lib/data-canaries.js](api/_lib/data-canaries.js) + [api/_lib/data-canary-health.js](api/_lib/data-canary-health.js) + cron [api/cron/data-canary.js](api/cron/data-canary.js), import wall [scripts/lib/research-wall.mjs](scripts/lib/research-wall.mjs), view [src/shared/backtest-integrity-view.js](src/shared/backtest-integrity-view.js) | Built, ships with the next deploy; scheduler sync owner-gated | Look-ahead audit of the sniper entry gate on every backtest, dataset manifest with content hash (older results marked unreproducible), 30 minute price and candle canaries that reorder fallback chains, and a test that fails if research code can reach a live execution module. Docs: [docs/backtest-integrity.md](docs/backtest-integrity.md). Tests: [tests/backtest-integrity.test.js](tests/backtest-integrity.test.js) |-| Arm your agent (Oracle conviction on autopilot) | [pages/arm.html](pages/arm.html) + [src/arm.js](src/arm.js) `→ /oracle/arm` (also `/arm`), config + graded ledger API [api/oracle/watch.js](api/oracle/watch.js) `→ /api/oracle/watch`, alert test [api/oracle/test-alert.js](api/oracle/test-alert.js), live stream [api/oracle/feed.js](api/oracle/feed.js), proof of edge [api/oracle/backtest.js](api/oracle/backtest.js) | Live | The rules screen that turns an Oracle score into an agent that acts. Four steps: the conviction floor (Prime / Strong+ / Lean+, each showing its real 30-day win rate, average peak and 3x count for that exact bar), position sizing with hard daily and open-position caps, an optional personal Telegram alert with a send-test button, and simulate-or-live arming. Beside the form is a live preview of every coin clearing the rules as they stand, updated every 20 seconds, with the size the agent would commit to each: tighten the bar and the list shrinks in front of you. The agent spends only from its own custodial Solana wallet, whose balance and remaining trade runway sit in the control bar, and every action it takes is graded against the outcome in the ledger below. The conviction preview and edge readout are public endpoints, so a signed-out visitor sees the product working before being asked for an account. Arming in live mode is gated on the shared risk acknowledgement ([src/shared/risk-ack.js](src/shared/risk-ack.js)). |+| Arm your agent (Oracle conviction on autopilot) | [pages/arm.html](pages/arm.html) + [src/arm.js](src/arm.js) `→ /oracle/arm` (also `/arm`), config + graded ledger API [api/oracle/watch.js](api/oracle/watch.js) `→ /api/oracle/watch`, alert test [api/oracle/test-alert.js](api/oracle/test-alert.js), verified Telegram chat lookup [api/oracle/telegram-chat.js](api/oracle/telegram-chat.js) `→ /api/oracle/telegram-chat` (the send-test box and follow panel only accept this linked chat id), live stream [api/oracle/feed.js](api/oracle/feed.js), proof of edge [api/oracle/backtest.js](api/oracle/backtest.js) | Live | The rules screen that turns an Oracle score into an agent that acts. Four steps: the conviction floor (Prime / Strong+ / Lean+, each showing its real 30-day win rate, average peak and 3x count for that exact bar), position sizing with hard daily and open-position caps, an optional personal Telegram alert with a send-test button, and simulate-or-live arming. Beside the form is a live preview of every coin clearing the rules as they stand, updated every 20 seconds, with the size the agent would commit to each: tighten the bar and the list shrinks in front of you. The agent spends only from its own custodial Solana wallet, whose balance and remaining trade runway sit in the control bar, and every action it takes is graded against the outcome in the ledger below. The conviction preview and edge readout are public endpoints, so a signed-out visitor sees the product working before being asked for an account. Arming in live mode is gated on the shared risk acknowledgement ([src/shared/risk-ack.js](src/shared/risk-ack.js)). || Oracle Lab (the conviction model, published) | [pages/oracle-lab.html](pages/oracle-lab.html) + [src/oracle-lab.js](src/oracle-lab.js) `→ /oracle-lab`, model API [api/oracle/model.js](api/oracle/model.js) `→ /api/oracle/model`, SDK [packages/oracle-model/](packages/oracle-model) `→ @three-ws/oracle-model` | Live | The glass box over the Oracle. Publishes the scoring model itself, not a summary of it: every bucket weight with the number of labeled launches behind it and what happened to them, the held-out reliability curve for each tier claim, the version history of every refit INCLUDING the candidates the promotion gate refused and why, and a scorer that runs the real weights in the visitor's browser. The model is a lookup table (~32KB), so `@three-ws/oracle-model` downloads it once and reproduces any score offline with no key, no rate limit and no telemetry; `verify()` re-measures our published AUC/Brier/reliability against a caller's own labeled outcomes, and `diff()` shows every weight that moved between two versions. `?view=registry` and `?view=diff&from=&to=` serve the same data server-side. Docs: [docs/oracle-model.md](docs/oracle-model.md) `→ /docs/oracle-model`. Tests: [packages/oracle-model/test/](packages/oracle-model/test) (23), [tests/oracle/fit.test.js](tests/oracle/fit.test.js) (43) || Oracle conviction model (three heads, learned on a clock) | Fitter [api/_lib/oracle/fit.js](api/_lib/oracle/fit.js), scorer [api/_lib/oracle/conviction.js](api/_lib/oracle/conviction.js), DB-backed weights [api/_lib/oracle/model-store.js](api/_lib/oracle/model-store.js), learning loop [api/cron/oracle-refit.js](api/cron/oracle-refit.js) (every 6h), CLI [scripts/oracle-fit.mjs](scripts/oracle-fit.mjs) | Live, v3 | v2 ranked "spikes 3x or graduates", so a coin that ran 3x and went to zero counted as a hit: Prime-tier coins hit that target 58.2% of the time and rugged 53.0% of the time. v3 fits three heads over one design matrix (`win` = ran and the holder kept it, `rug` = holder down more than half, `moon` = ran at all) and anchors the public score on `win`, publishing `giveBackRisk = 1 - P(win)/P(moon)` beside it: given it runs, how often a coin like this hands the run straight back. Weights moved out of the container image into `oracle_model_versions`, so the refit cron can promote a better model between deploys; it was frozen at its 2026-08-09 fit for nineteen days because nothing but a human could refit it. Every candidate faces a promotion gate (complete fit, absolute AUC floor, every tier band still earning its claim, no feature-set collapse, a material gain over the incumbent, no regression on the other heads) and is stored either way with the reason. Thin buckets are shrunk toward zero by `n/(n+200)` so 34 samples cannot reverse a verdict. Docs: [docs/oracle-model.md](docs/oracle-model.md) || Price-independent outcome labels | [workers/agent-sniper/intel/learn.js](workers/agent-sniper/intel/learn.js) `deriveOutcome`, migrations [20260828170000](api/_lib/migrations/20260828170000_oracle_price_independent_labels.sql) + [20260828190000](api/_lib/migrations/20260828190000_oracle_recompute_rug_flag.sql) | Live | The rug flag was a readout of the SOL price. It was decided by "market cap under $3,000", and an empty pump.fun bonding curve is worth a fixed `30 * 1e9 / 1073000191 = 27.958993 SOL`, so the test amounted to asking whether SOL was above about $107.30 that day: of 206,428 coins labeled rugged, 206,419 were under $3,000; of 25,180 labeled survivors, the cheapest was exactly $3,000. Same dead curves, sorted by a price feed. Labels now use `retained = last_mc/ath_mc` and `hold_multiple = ath_multiple * retained`, both taken from the same reading so the price cancels; the real rug rate is 11.4%, not 91%, and it holds within two points from 60 minutes to three days. `label_version` marks which rule judged a row and the fitter trains on version 2 only. The training-set upsert also stopped being `do nothing`, which had made a written label permanently uncorrectable. |diff --git a/data/docs-freshness-reviews.json b/data/docs-freshness-reviews.jsonindex fb4574d82..e36048b2e 100644--- a/data/docs-freshness-reviews.json+++ b/data/docs-freshness-reviews.json@@ -3,10 +3,16 @@"$comment": "Review baselines for `npm run docs:freshness`. Without this file the only clock a doc has is its own last commit, so a page someone read end to end and found correct still measures as drifting, and the only way to clear it is a cosmetic edit that lies about what happened. A stamp here says a human or an agent checked this doc against the repo at that commit. Freshness is then measured from whichever is newer, the doc's last edit or its last review. Write stamps with `npm run docs:review -- <doc> [more docs] --note \"...\"`, never by hand: the tool resolves the commit, refuses a doc that does not exist, and keeps the ordering stable. kind `verified` means the prose was checked against the code and matched. kind `snapshot` means the doc is a dated record (an audit, an incident writeup, a finished work order) that documents a moment and must not be rewritten to match today's code, so it is never counted as drift.","reviews": {"STRUCTURE.md": {- "commit": "dfd78ded2",+ "commit": "0a10f48c2","kind": "verified","by": "agent",- "note": "verified against all 80 drifted files: all are incidental touches from the model-viewer version bump, motion-token migration, and MCP/guards regenerations, none of which change which directory a product surface maps to"+ "note": "freshness sweep: checked against the drifted commits"+ },+ "docs/3d-api.md": {+ "commit": "0a10f48c2",+ "kind": "verified",+ "by": "agent",+ "note": "freshness sweep: checked against the drifted commits"},"docs/3d-asset-pipeline.md": {"commit": "53f2a200f",@@ -15,19 +21,19 @@"note": "full sweep: read against the drifted commits and corrected where wrong"},"docs/a2a-payments.md": {- "commit": "53f2a200f",+ "commit": "0a10f48c2","kind": "verified","by": "agent",- "note": "full sweep: read against the drifted commits and corrected where wrong"+ "note": "freshness sweep: checked against the drifted commits"},"docs/agent-abilities/ABILITIES.md": {- "commit": "a3524e6f6",+ "commit": "0a10f48c2","kind": "verified","by": "agent","note": "freshness sweep: checked against the drifted commits"},"docs/agent-abilities/FULL-ARTICLE.md": {- "commit": "a3524e6f6",+ "commit": "0a10f48c2","kind": "verified","by": "agent","note": "freshness sweep: checked against the drifted commits"@@ -38,6 +44,12 @@"by": "agent","note": "full sweep: read against the drifted commits and corrected where wrong"},+ "docs/agent-abilities/chapters/04-the-mind.md": {+ "commit": "0a10f48c2",+ "kind": "verified",+ "by": "agent",+ "note": "freshness sweep: checked against the drifted commits"+ },"docs/agent-abilities/chapters/11-markets-intelligence.md": {"commit": "53f2a200f","kind": "verified",@@ -62,6 +74,12 @@"by": "agent","note": "full sweep: read against the drifted commits and corrected where wrong"},+ "docs/agent-mail.md": {+ "commit": "0a10f48c2",+ "kind": "verified",+ "by": "agent",+ "note": "freshness sweep: checked against the drifted commits"+ },"docs/agent-shell.md": {"commit": "53f2a200f","kind": "verified",@@ -81,10 +99,16 @@"note": "dated record, kept as written"},"docs/agent-wallet-api.md": {- "commit": "53f2a200f",+ "commit": "0a10f48c2","kind": "verified","by": "agent",- "note": "full sweep: read against the drifted commits and corrected where wrong"+ "note": "freshness sweep: checked against the drifted commits"+ },+ "docs/agora.md": {+ "commit": "0a10f48c2",+ "kind": "verified",+ "by": "agent",+ "note": "freshness sweep: checked against the drifted commits"},"docs/agora/tasks/00-INDEX.md": {"commit": "53f2a200f",@@ -98,12 +122,30 @@"by": "agent","note": "dated record, kept as written"},+ "docs/animation-seeding.md": {+ "commit": "0a10f48c2",+ "kind": "verified",+ "by": "agent",+ "note": "freshness sweep: checked against the drifted commits"+ },+ "docs/api-reference.md": {+ "commit": "0a10f48c2",+ "kind": "verified",+ "by": "agent",+ "note": "freshness sweep: checked against the drifted commits"+ },"docs/apps.md": {"commit": "a3524e6f6","kind": "verified","by": "agent","note": "freshness sweep: checked against the drifted commits"},+ "docs/ar.md": {+ "commit": "0a10f48c2",+ "kind": "verified",+ "by": "agent",+ "note": "freshness sweep: checked against the drifted commits"+ },"docs/assistant-widget.md": {"commit": "53f2a200f","kind": "verified",@@ -134,23 +176,59 @@"by": "agent","note": "full sweep: read against the drifted commits and corrected where wrong"},+ "docs/aws-builder-center-agent-payment-sessions.md": {+ "commit": "0a10f48c2",+ "kind": "verified",+ "by": "agent",+ "note": "freshness sweep: checked against the drifted commits"+ },+ "docs/aws-builder-center-claims-ledger.md": {+ "commit": "0a10f48c2",+ "kind": "verified",+ "by": "agent",+ "note": "freshness sweep: checked against the drifted commits"+ },+ "docs/aws-builder-center-open-weight-3d-forge.md": {+ "commit": "0a10f48c2",+ "kind": "verified",+ "by": "agent",+ "note": "freshness sweep: checked against the drifted commits"+ },"docs/blender-mcp.md": {"commit": "53f2a200f","kind": "verified","by": "agent","note": "full sweep: read against the drifted commits and corrected where wrong"},+ "docs/bnb-vault.md": {+ "commit": "0a10f48c2",+ "kind": "verified",+ "by": "agent",+ "note": "freshness sweep: checked against the drifted commits"+ },"docs/btn-pill-migration.md": {- "commit": "53f2a200f",+ "commit": "0a10f48c2","kind": "verified","by": "agent",- "note": "full sweep: read against the drifted commits and corrected where wrong"+ "note": "freshness sweep: checked against the drifted commits"+ },+ "docs/ca2x402.md": {+ "commit": "0a10f48c2",+ "kind": "verified",+ "by": "agent",+ "note": "freshness sweep: checked against the drifted commits"+ },+ "docs/character-studio.md": {+ "commit": "0a10f48c2",+ "kind": "verified",+ "by": "agent",+ "note": "freshness sweep: checked against the drifted commits"},"docs/chatgpt-ar.md": {- "commit": "53f2a200f",+ "commit": "0a10f48c2","kind": "verified","by": "agent",- "note": "full sweep: read against the drifted commits and corrected where wrong"+ "note": "freshness sweep: checked against the drifted commits"},"docs/choreography.md": {"commit": "53f2a200f",@@ -177,10 +255,10 @@"note": "full sweep: read against the drifted commits and corrected where wrong"},"docs/copy-trading.md": {- "commit": "53f2a200f",+ "commit": "0a10f48c2","kind": "verified","by": "agent",- "note": "full sweep: read against the drifted commits and corrected where wrong"+ "note": "freshness sweep: checked against the drifted commits"},"docs/crawl.md": {"commit": "1396077cf",@@ -212,12 +290,30 @@"by": "agent","note": "full sweep: read against the drifted commits and corrected where wrong"},+ "docs/discord-activity.md": {+ "commit": "0a10f48c2",+ "kind": "verified",+ "by": "agent",+ "note": "freshness sweep: checked against the drifted commits"+ },"docs/doc-freshness.md": {"commit": "302d0ae31","kind": "verified","by": "agent","note": "re-read against the exclusion change"},+ "docs/domains.md": {+ "commit": "0a10f48c2",+ "kind": "verified",+ "by": "agent",+ "note": "freshness sweep: checked against the drifted commits"+ },+ "docs/drops.md": {+ "commit": "0a10f48c2",+ "kind": "verified",+ "by": "agent",+ "note": "freshness sweep: checked against the drifted commits"+ },"docs/economy-master.md": {"commit": "53f2a200f","kind": "verified",@@ -236,6 +332,12 @@"by": "agent","note": "read against code drift; fixed where it differed"},+ "docs/erc8004/validation-attestation.md": {+ "commit": "0a10f48c2",+ "kind": "verified",+ "by": "agent",+ "note": "freshness sweep: checked against the drifted commits"+ },"docs/event-readiness/01-play-first-impression.md": {"commit": "53f2a200f","kind": "verified",@@ -266,6 +368,18 @@"by": "agent","note": "full sweep: read against the drifted commits and corrected where wrong"},+ "docs/event-readiness/LIVE-OPS.md": {+ "commit": "0a10f48c2",+ "kind": "snapshot",+ "by": "agent",+ "note": "dated record, kept as written"+ },+ "docs/fact-check.md": {+ "commit": "0a10f48c2",+ "kind": "verified",+ "by": "agent",+ "note": "freshness sweep: checked against the drifted commits"+ },"docs/feedback.md": {"commit": "1396077cf","kind": "verified",@@ -285,10 +399,10 @@"note": "full sweep: read against the drifted commits and corrected where wrong"},"docs/forge-pipeline.md": {- "commit": "53f2a200f",+ "commit": "0a10f48c2","kind": "verified","by": "agent",- "note": "full sweep: read against the drifted commits and corrected where wrong"+ "note": "freshness sweep: checked against the drifted commits"},"docs/free-crypto-apis.md": {"commit": "53f2a200f",@@ -297,10 +411,16 @@"note": "full sweep: read against the drifted commits and corrected where wrong"},"docs/guards.md": {- "commit": "53f2a200f",+ "commit": "0a10f48c2","kind": "verified","by": "agent",- "note": "full sweep: read against the drifted commits and corrected where wrong"+ "note": "freshness sweep: checked against the drifted commits"+ },+ "docs/hold-to-access.md": {+ "commit": "0a10f48c2",+ "kind": "verified",+ "by": "agent",+ "note": "freshness sweep: checked against the drifted commits"},"docs/home-households.md": {"commit": "53f2a200f",@@ -320,6 +440,18 @@"by": "agent","note": "full sweep: read against the drifted commits and corrected where wrong"},+ "docs/ibm-community-doc-freshness-post.md": {+ "commit": "0a10f48c2",+ "kind": "verified",+ "by": "agent",+ "note": "freshness sweep: checked against the drifted commits"+ },+ "docs/ibm-community-long-running-mcp-tools-post.md": {+ "commit": "0a10f48c2",+ "kind": "verified",+ "by": "agent",+ "note": "freshness sweep: checked against the drifted commits"+ },"docs/internal/MAINNET-TEST-2026-07-03.md": {"commit": "53f2a200f","kind": "snapshot",@@ -327,10 +459,10 @@"note": "dated record, kept as written"},"docs/internal/fable-playbook.md": {- "commit": "53f2a200f",+ "commit": "0a10f48c2","kind": "verified","by": "agent",- "note": "full sweep: read against the drifted commits and corrected where wrong"+ "note": "freshness sweep: checked against the drifted commits"},"docs/irl/THREAT-MODEL.md": {"commit": "53f2a200f",@@ -339,10 +471,10 @@"note": "full sweep: read against the drifted commits and corrected where wrong"},"docs/labor-market.md": {- "commit": "53f2a200f",+ "commit": "0a10f48c2","kind": "verified","by": "agent",- "note": "full sweep: read against the drifted commits and corrected where wrong"+ "note": "freshness sweep: checked against the drifted commits"},"docs/launch-usecases.md": {"commit": "53f2a200f",@@ -363,10 +495,10 @@"note": "full sweep: read against the drifted commits and corrected where wrong"},"docs/money-map.md": {- "commit": "53f2a200f",+ "commit": "0a10f48c2","kind": "verified","by": "agent",- "note": "full sweep: read against the drifted commits and corrected where wrong"+ "note": "freshness sweep: checked against the drifted commits"},"docs/news-rights.md": {"commit": "53f2a200f",@@ -404,6 +536,12 @@"by": "agent","note": "full sweep: read against the drifted commits and corrected where wrong"},+ "docs/open-source-credits.md": {+ "commit": "0a10f48c2",+ "kind": "verified",+ "by": "agent",+ "note": "freshness sweep: checked against the drifted commits"+ },"docs/ops/cron-auth.md": {"commit": "53f2a200f","kind": "verified",@@ -422,12 +560,24 @@"by": "agent","note": "freshness sweep: checked against the drifted commits"},+ "docs/ops/guard-wiring.md": {+ "commit": "0a10f48c2",+ "kind": "verified",+ "by": "agent",+ "note": "freshness sweep: checked against the drifted commits"+ },"docs/ops/home-operations.md": {"commit": "53f2a200f","kind": "verified","by": "agent","note": "full sweep: read against the drifted commits and corrected where wrong"},+ "docs/ops/llm-lanes.md": {+ "commit": "0a10f48c2",+ "kind": "verified",+ "by": "agent",+ "note": "freshness sweep: checked against the drifted commits"+ },"docs/ops/play-store-developer-page.md": {"commit": "53f2a200f","kind": "verified",@@ -435,10 +585,10 @@"note": "full sweep: read against the drifted commits and corrected where wrong"},"docs/ops/search-indexing.md": {- "commit": "53f2a200f",+ "commit": "0a10f48c2","kind": "verified","by": "agent",- "note": "full sweep: read against the drifted commits and corrected where wrong"+ "note": "freshness sweep: checked against the drifted commits"},"docs/ops/solana-rpc-lanes.md": {"commit": "53f2a200f",@@ -458,6 +608,12 @@"by": "agent","note": "full sweep: read against the drifted commits and corrected where wrong"},+ "docs/ops/x-story-findings-2026-09-30.md": {+ "commit": "0a10f48c2",+ "kind": "snapshot",+ "by": "agent",+ "note": "dated record, kept as written"+ },"docs/oracle-trading-mcp-plan.md": {"commit": "a3524e6f6","kind": "verified",@@ -465,10 +621,10 @@"note": "freshness sweep: checked against the drifted commits"},"docs/oracle.md": {- "commit": "1396077cf",+ "commit": "0a10f48c2","kind": "verified","by": "agent",- "note": "read against code drift; fixed where it differed"+ "note": "freshness sweep: checked against the drifted commits"},"docs/overlay-audit.md": {"commit": "53f2a200f",@@ -477,10 +633,16 @@"note": "full sweep: read against the drifted commits and corrected where wrong"},"docs/page-performance.md": {- "commit": "53f2a200f",+ "commit": "0a10f48c2","kind": "verified","by": "agent",- "note": "full sweep: read against the drifted commits and corrected where wrong"+ "note": "freshness sweep: checked against the drifted commits"+ },+ "docs/paired-coins.md": {+ "commit": "0a10f48c2",+ "kind": "verified",+ "by": "agent",+ "note": "freshness sweep: checked against the drifted commits"},"docs/play-hardening.md": {"commit": "53f2a200f",@@ -494,17 +656,29 @@"by": "agent","note": "freshness sweep: checked against the drifted commits"},+ "docs/prompts/05-agents-rest-parity.md": {+ "commit": "0a10f48c2",+ "kind": "snapshot",+ "by": "agent",+ "note": "dated record, kept as written"+ },+ "docs/prompts/11-agent-mail.md": {+ "commit": "0a10f48c2",+ "kind": "snapshot",+ "by": "agent",+ "note": "dated record, kept as written"+ },"docs/pump-platform-fee.md": {- "commit": "53f2a200f",+ "commit": "0a10f48c2","kind": "verified","by": "agent",- "note": "full sweep: read against the drifted commits and corrected where wrong"+ "note": "freshness sweep: checked against the drifted commits"},"docs/pumpfun-program/UPSTREAM-pumpswap-virtual-quote-reserves.md": {- "commit": "53f2a200f",+ "commit": "0a10f48c2","kind": "verified","by": "agent",- "note": "full sweep: read against the drifted commits and corrected where wrong"+ "note": "freshness sweep: checked against the drifted commits"},"docs/research/3d-landscape-2026-10.md": {"commit": "a3524e6f6",@@ -519,7 +693,7 @@"note": "dated record, kept as written"},"docs/risk-acknowledgment.md": {- "commit": "a3524e6f6",+ "commit": "0a10f48c2","kind": "verified","by": "agent","note": "freshness sweep: checked against the drifted commits"@@ -530,6 +704,12 @@"by": "agent","note": "dated record, kept as written"},+ "docs/security/audit-2026-10-25/FINDINGS-DETAIL.md": {+ "commit": "0a10f48c2",+ "kind": "snapshot",+ "by": "agent",+ "note": "dated record, kept as written"+ },"docs/security/review-2026-06-24.md": {"commit": "53f2a200f","kind": "snapshot",@@ -543,10 +723,10 @@"note": "full sweep: read against the drifted commits and corrected where wrong"},"docs/seeker-app.md": {- "commit": "53f2a200f",+ "commit": "0a10f48c2","kind": "verified","by": "agent",- "note": "full sweep: read against the drifted commits and corrected where wrong"+ "note": "freshness sweep: checked against the drifted commits"},"docs/seeker-publishing.md": {"commit": "53f2a200f",@@ -554,8 +734,14 @@"by": "agent","note": "full sweep: read against the drifted commits and corrected where wrong"},+ "docs/shipfeed.md": {+ "commit": "0a10f48c2",+ "kind": "verified",+ "by": "agent",+ "note": "freshness sweep: checked against the drifted commits"+ },"docs/site-performance.md": {- "commit": "a3524e6f6",+ "commit": "0a10f48c2","kind": "verified","by": "agent","note": "freshness sweep: checked against the drifted commits"@@ -693,7 +879,7 @@"note": "freshness sweep: checked against the drifted commits"},"docs/ux-flows/07-crypto-trading-analytics.md": {- "commit": "a3524e6f6",+ "commit": "0a10f48c2","kind": "verified","by": "agent","note": "freshness sweep: checked against the drifted commits"@@ -764,6 +950,18 @@"by": "agent","note": "freshness sweep: checked against the drifted commits"},+ "docs/x-mention-bot.md": {+ "commit": "0a10f48c2",+ "kind": "verified",+ "by": "agent",+ "note": "freshness sweep: checked against the drifted commits"+ },+ "docs/x-partner-series.md": {+ "commit": "0a10f48c2",+ "kind": "verified",+ "by": "agent",+ "note": "freshness sweep: checked against the drifted commits"+ },"docs/x-posts/claims-ledger-thread.md": {"commit": "a3524e6f6","kind": "verified",diff --git a/docs/a2a-payments.md b/docs/a2a-payments.mdindex 14b76b5ec..2a8e4816b 100644--- a/docs/a2a-payments.md+++ b/docs/a2a-payments.md@@ -26,7 +26,9 @@ for what settled A2A payments add up to.An **Intent Mandate** is a signed, offline-verifiable bearer credential: theuser's recorded consent that a named agent may spend up to a total budget, with-a per-call cap, on named networks, for up to 90 days. That is what makes+a per-call cap, on named networks, for up to 90 days. Issuing one is itself a+spend: a signed-in session may do it, but an API key or OAuth token needs the+`wallet:write` scope (`assertBearerMaySpend`), as it does on `a2a-call`. That is what makesautonomy possible, and it is also why the mandate cannot be the whole safetystory. A bearer credential has no revocation of its own: whoever holds it canspend its remaining budget until it expires.@@ -50,8 +52,17 @@ token moves.| 4 | Mandate per-call policy | Is this amount, network, currency and resource inside what was authorized? | `amount_over_per_call`, `currency_mismatch`, `network_not_allowed`, `resource_not_allowed` || 5 | Peer reputation (opt-in) | Does the peer clear the caller's ERC-8004 trust bar? | `reputation_too_low`, `reputation_too_few_reviews`, `reputation_unavailable` || 6 | Mandate cumulative budget | Would lifetime spend under this mandate exceed its total cap? | `budget_exceeded` |+| 6b | Platform ceilings | Is this inside the limits the platform sets and no mandate can widen? Per call $25, per user per day $50, whole payer wallet per day $500 (overridable by `A2A_PLATFORM_PER_CALL_ATOMICS`, `A2A_PLATFORM_USER_DAILY_ATOMICS`, `A2A_PLATFORM_DAILY_ATOMICS`) | `platform_per_call_exceeded`, `platform_user_daily_exceeded`, `platform_daily_exceeded` (all 403) || 7 | The agent's own spend policy | Per-transaction, rolling-daily and per-counterparty ceilings, the owner's plain-English rules, the anomaly guard, any scoped capability | `per_tx_exceeded`, `daily_exceeded`, `counterparty_daily_exceeded`, `policy_blocked`, `policy_step_up`, `policy_freeze`, `wallet_anomaly_frozen`, `capability_required` |+The payer key is platform-held and the mandate is self-issued, so gate 6b is the+last line of defence when the mandate is huge and the agent's own limits are+unset. The same platform caps apply when the mandate is issued: a total budget+above $100 (`A2A_PLATFORM_MAX_MANDATE_ATOMICS`) or a per-call allowance above+the per-call ceiling is refused with `amount_exceeds_platform_cap`. A payment+that fails after gate 6b releases both the mandate and the platform+reservations.+Gate 7 is atomic: it enforces the ceilings **and** writes the payment's pendingreceipt row in one statement under a per-agent advisory lock, so concurrentcalls cannot all pass on the same stale daily total. If the payment then fails@@ -81,6 +92,7 @@ PUT /api/agents/:id/solana/limits (CSRF-gated for cookie callers)| `per_tx_usd` | Ceiling on any single payment | `null` (uncapped) || `daily_usd` | Rolling 24h ceiling on total outflow | `null` (uncapped) || `per_counterparty_daily_usd` | Rolling 24h ceiling **per payee** | `null` (uncapped) |+| `approval_threshold_usd` | Above this amount an autonomous x402 payment (`/api/pay/execute`) or agent hire (`/api/agents/a2a-hire`) is parked in the Approval Inbox and answers 202 with a poll link instead of executing; it resumes when the owner approves. The mandate path above does not park, it keeps its hard gates | `null` (no threshold) || `withdraw_allowlist` | Read-only view of the active [destination whitelist](./destination-whitelist.md). Edit it there: new addresses serve a cooldown and need step-up | `[]` || `frozen` | The kill switch. Halts every autonomous path | `false` || `require_capabilities` | Autonomous spends must present a covering scoped capability | `false` |diff --git a/docs/agent-abilities/ABILITIES.md b/docs/agent-abilities/ABILITIES.mdindex edd5259b5..3c6ae400c 100644--- a/docs/agent-abilities/ABILITIES.md+++ b/docs/agent-abilities/ABILITIES.md@@ -18,7 +18,7 @@ three.ws runs a complete prompt-to-world 3D pipeline in production: text or imagType a prompt at /forge (or call the forge_free MCP tool) and get a downloadable textured 3D model (GLB) plus a browser viewer link. The default lane is completely free — no account, no key, no wallet — with paid quality tiers (draft $0.05 / standard $0.15 / high $0.50 USDC) when more geometric budget is needed.-One ordered free-lane walk lives in the backend registry (api/_lib/forge-tiers.js), and both the env-only default and the health-aware resolver read it, so they can never disagree. It starts at the tier's named free engine (FREE_DEFAULT_FOR_TIERS: our self-hosted TRELLIS worker at draft and standard, our self-hosted Hunyuan3D worker at high), falls through the remaining self-hosted GCP GPU workers, then the free Hugging Face Spaces (Hunyuan3D/TRELLIS/TripoSR with automatic failover; one chain-wide Spaces failure pauses that lane for five minutes, so the walk skips it at once and an explicit pick of it answers 503 with Retry-After and a list of working engines to hop to), and ends at the free NVIDIA NIM/NVCF TRELLIS lane, which is the fallback that still answers a text prompt when every worker and Space is cold. Only configured, capable lanes survive the walk. The NIM lane is async submit + poll and pinned to a 15-step sampling budget below the high tier, since higher budgets overrun its gateway window; prompts are clamped to 77 chars with an auto 'studio lighting' suffix; output bytes are persisted to R2 for a durable first-party URL. The registry also routes to Replicate and BYOK Meshy/Tripo native-geometry engines; paid calls settle over x402 (/api/x402/forge, text_to_3d MCP).+One ordered free-lane walk lives in the backend registry (api/_lib/forge-tiers.js), and both the env-only default and the health-aware resolver read it, so they can never disagree. It starts at the tier's named free engine (FREE_DEFAULT_FOR_TIERS: our self-hosted TRELLIS worker at draft and standard, our self-hosted Hunyuan3D worker at high), falls through the remaining self-hosted GCP GPU workers, then the free Hugging Face Spaces (Hunyuan3D/TRELLIS/TripoSR with automatic failover), and ends at the free NVIDIA NIM/NVCF TRELLIS lane, which is the fallback that still answers a text prompt when every worker and Space is cold. Only configured, capable lanes survive the walk. The NIM lane is async submit + poll and pinned to a 15-step sampling budget below the high tier, since higher budgets overrun its gateway window; prompts are clamped to 77 chars with an auto 'studio lighting' suffix; output bytes are persisted to R2 for a durable first-party URL. The registry also routes to Replicate and BYOK Meshy/Tripo native-geometry engines; paid calls settle over x402 (/api/x402/forge, text_to_3d MCP).Zero-cost text→3D that any human or AI agent can use instantly, with a transparent pay-per-call ladder — identical pricing across REST and MCP — when quality matters.@@ -754,7 +754,7 @@ Your agent becomes a self-sustaining creator: it ships coins on cadence withoutA fee harvester that watches every coin an agent launched and automatically collects the creator fees whenever they cross a threshold — no manual sweeping, no forgotten revenue. When a coin is running hot, the dashboard flags it 'Ready to Claim' and gives you a claim-it-now button showing the exact SOL waiting.-api/cron/launcher-claimer.js runs every 5 minutes: for each launched coin with ≥0.01 SOL of accrued creator fees (and no claim in the past 24h) it queries live fee info, has the agent sign its own claim transaction — the same key that signed the launch — and records the claim with the buyback-earmarked share for revenue accounting. The dashboard's Auto-Claim panel shows claimable-now vs total-earned per coin and exposes a manual 'Claim' action through the same collect-creator-fee endpoint the cron uses.+api/cron/launcher-claimer.js runs every 5 minutes: for each launched coin with ≥0.01 SOL of accrued creator fees (and no claim in the past 24h) it queries live fee info, has the agent sign its own claim transaction (the same key that signed the launch), and records the claim with the buyback-earmarked share for revenue accounting (50% by default, read from the one shared creator-fee claim policy in api/_lib/token/config.js that the creator payout also uses, so the earmark and the payout cannot disagree). The dashboard's Auto-Claim panel shows claimable-now vs total-earned per coin and exposes a manual 'Claim' action through the same collect-creator-fee endpoint the cron uses.Creator fees are the whole point of launching, and they leak when nobody sweeps them. Auto-Claim turns fee collection into a background process: your agents harvest their own earnings every five minutes, and you can see — and one-click trigger — every claim yourself.@@ -842,7 +842,7 @@ You supervise an autonomous trader the way you'd supervise a person: by readingEvery agent has a live screen anyone can watch, and a task bar where any visitor — no account needed — can type a question. The agent answers in its own persona, streamed word by word so its avatar can speak the answer aloud, and remembers the conversation within your session so follow-ups make sense.-A public SSE endpoint that runs the agent's configured brain (anonymous visitors are clamped to free-tier models so public chat can never burn billed keys), writing each exchange to a short-TTL session-scoped memory thread.+A public SSE endpoint that runs the agent's configured brain (anonymous visitors are clamped to free-tier models so public chat can never burn billed keys), writing each exchange to a short-TTL session-scoped memory thread. An unpublished agent answers only its owner, and visitor questions are tagged so the owner's own chat never recalls them into its prompt.Agents aren't just on display — every one of them is a concierge you can interrogate on the spot.@@ -1220,7 +1220,7 @@ Your agent's body can never 404. The exact GLB — manifest baked inside it —Skills are the agent’s installed abilities: trading rails, launch tooling, NFTs, blinks, sentiment, scenes, all wired to real APIs. Owners switch them on and off in the Agent Studio's Skills room (three.ws/agent-studio), and MCP-exposed skills are callable by other agents through /api/mcp. The enabled skill list also travels in the agent's signed manifest, pinned to IPFS whenever a public agent's persona is saved (private agents publish on request), so anyone can verify which skills an agent carries without an account ([agent manifest](/docs/agent-manifest)).-The in-world agent skills system (src/agent-skills.js plus 15 family modules) is what a three.ws agent can DO, and what you can watch it doing. Each skill bundles an instruction, an animation hint, a voice template, and a real handler, so execution flows through the agent protocol bus and the avatar physically performs the action (gestures, speech, mood shifts) instead of silently returning JSON. Skill families span 3D work (present/validate models, build the scene), the full Solana economy (pump.fun launch/trade/watch, Jupiter swaps, Pyth prices, Blinks, NFTs), agent monetization (on-chain payment vaults on Solana and EVM, x402 agent-to-agent hiring under signed mandates), an EVM launch leg (Robinhood Chain coins through Pons, and paired-quote coin launches and markets), and market intelligence (aixbt, sentiment, KOL P&L), all against real APIs and SDKs with no mocks, keys held either in the user's browser wallet or server-side, never in the client. MCP-exposed skills double as tools on /api/mcp, so the same registry powers both the living avatar and the developer API.+The in-world agent skills system (src/agent-skills.js plus 15 family modules) is what a three.ws agent can DO, and what you can watch it doing. Each skill bundles an instruction, an animation hint, a voice template, and a real handler, so execution flows through the agent protocol bus and the avatar physically performs the action (gestures, speech, mood shifts) instead of silently returning JSON. Skill families span 3D work (present/validate models, build the scene), the full Solana economy (pump.fun launch/trade/watch, Jupiter swaps, Pyth prices, Blinks, NFTs), EVM coin launches on Robinhood Chain (a coin on the Pons launchpad, or a paired coin that trades against up to five assets at once, each quoted before the agent confirms), agent monetization (on-chain payment vaults on Solana and EVM, x402 agent-to-agent hiring under signed mandates), and market intelligence (aixbt, sentiment, KOL P&L), all against real APIs and SDKs with no mocks, keys held either in the user's browser wallet or server-side, never in the client. MCP-exposed skills double as tools on /api/mcp, so the same registry powers both the living avatar and the developer API.## Skill registry and performed execution (core)@@ -1338,7 +1338,7 @@ An agent becomes a business: it invoices, gets paid in USDC across two ecosystemOne agent autonomously discovers, pays, and calls a peer agent's paid A2A skill — under a signed Intent Mandate the user issued ahead of time, with optional ERC-8004 reputation gating (minimum average rating and review count) before any USDC moves. The payment is performed, not hidden: PAY_INTENT, then PAY_SETTLED with a celebration emote or PAY_FAILED with visible concern.-src/agent-skills-a2a.js POSTs to /api/agents/a2a-call, where the server enforces the mandate, a budget ledger, the peer's on-chain reputation, and the agent's own spend policy (the freeze switch and the per-transaction, rolling-daily, and per-counterparty ceilings), which a mandate cannot widen: a halted agent is refused with wallet_frozen before the peer is even quoted, and an agent deleted or transferred since the mandate was signed stops being spendable. Each payment writes a receipt to the agent's custody ledger (returned as receipt_id, readable at GET /api/agents/:id/solana/custody?category=x402) and releases it again on any failure; settlement flows over the x402 protocol and the receipt (amount, network, transaction, artifacts) comes back to be spoken in dollars.+src/agent-skills-a2a.js POSTs to /api/agents/a2a-call, where the server (an API key or OAuth token needs the wallet:write scope, like any spend) enforces the mandate, a budget ledger, the peer's on-chain reputation, and the agent's own spend policy (the freeze switch and the per-transaction, rolling-daily, and per-counterparty ceilings), which a mandate cannot widen, plus platform-set ceilings no mandate or agent policy can raise ($25 per call, $50 per user per day, $500 across the whole payer wallet per day): a halted agent is refused with wallet_frozen before the peer is even quoted, and an agent deleted or transferred since the mandate was signed stops being spendable. Each payment writes a receipt to the agent's custody ledger (returned as receipt_id, readable at GET /api/agents/:id/solana/custody?category=x402) and releases it again on any failure; settlement flows over the x402 protocol and the receipt (amount, network, transaction, artifacts) comes back to be spoken in dollars.This is the agent economy made visible and safe: your agent can hire other agents within a budget you pre-authorized, refuse untrusted peers, and you literally watch the money move — every payment bounded by your signed mandate.@@ -1474,7 +1474,7 @@ On three.ws, agents don't just chat — they earn, spend, hire, and get hired, wYour agent can autonomously hire another agent for a skill it doesn't have — it resolves the provider's published offer, reserves the spend against its own policy, pays real USDC from its own wallet, and only settles after the work actually succeeds. A failed job can never charge the hirer: the flow is verify-then-settle by construction. Every completed hire produces an on-chain settlement plus a separate on-chain invocation receipt naming both agents, auditable from both sides with explorer links.-POST /api/agents/a2a-hire chains the offer registry (agent_paid_services), atomic spend reservation (per-tx + daily caps + kill switch), the x402 exact-scheme USDC payment on Solana mainnet via @x402/svm, and an on-chain invocation-receipt program write; hires land in the agent_hires ledger.+POST /api/agents/a2a-hire chains the offer registry (agent_paid_services), atomic spend reservation (per-tx + daily caps + kill switch), a provider standing check (the open Solana agent registry tier is read live with a stale-snapshot fallback, and an optional minRegistryTier rejects a provider below the bar with 409 provider_below_tier before any spend), the x402 exact-scheme USDC payment on Solana mainnet via @x402/svm, and an on-chain invocation-receipt program write; hires land in the agent_hires ledger. A hire above the agent's approval threshold is parked in the Approval Inbox (202 with a poll link) and resumes when the owner approves.Your agent can buy capabilities it lacks, safely, with zero chance of paying for failed work.@@ -1578,7 +1578,7 @@ You can let an agent hold real money because there is a hard ceiling and a big rThe monetization dashboard aggregates your agents' revenue by skill and by day across selectable periods, showing gross, fees, and net. When you want the money, request a withdrawal — all or part of the available balance — straight to your own wallet, with a full withdrawal history.-agent_revenue_events records every sale; GET /api/monetization/withdrawals reads the live balance from them, and POST /api/monetization/withdrawals validates Solana/EVM payout addresses with a 1 USDC minimum against the real available balance.+agent_revenue_events records every sale; GET /api/monetization/withdrawals reads the live balance from them, and POST /api/monetization/withdrawals validates Solana/EVM payout addresses with a 1 USDC minimum against the real available balance. A bearer caller (API key or OAuth token) needs the `wallet:write` scope to request one; reading the balance does not.Agent income is real income: measured, itemized, and withdrawable.@@ -1810,7 +1810,7 @@ The Snipe tab turns a sentence like "snipe creators who've graduated two coins,The compile endpoint runs your description through the platform's LLM chain (with a deterministic phrase parser as a guaranteed fallback), then hard-validates the result and clamps every money and risk knob to the agent's runtime trade guards — the same ceilings enforced on every live buy, so a compiled strategy can never exceed a spend cap. The backtest endpoint replays the strategy over real captured launches (per-launch intel signals joined to labeled outcomes: graduated, pumped, flat, rugged) using the exact same entry-gate and exit-priority functions the live sniper worker runs, models slippage and price impact from recorded early liquidity, and caches results by strategy hash. Nothing is synthesized: exits are evaluated only at the two real price points that were observed (peak and terminal). Arming upserts the strategy into the database where a long-lived worker picks it up, watches the live PumpPortal launch feed, signs buys with the agent's own keypair, and manages every position to a stop-loss, take-profit, trailing-stop, or timeout exit. Each backtest snapshot is linked to the agent, so projected performance can later be compared against realized results.-Owner-only surface end to end: the tab is hidden from non-owners, and every endpoint verifies session or bearer auth, CSRF, per-IP rate limits, and that the agent belongs to the caller. Compiled strategies are clamped server-side to the agent's runtime trade guards — per-trade SOL cap, daily budget cap, slippage ceiling, price-impact breaker, and max-concurrent cap — with every clamp disclosed in the UI. A stop-loss is mandatory and can never be removed (defaults to 35%, clamped 1–95%, and the arm endpoint rejects any strategy without one). Arming requires a nonzero per-trade size and daily budget, per-trade can never exceed the daily budget, and mainnet arming is gated behind an explicit risk-acknowledgment dialog (which degrades to a native confirm rather than silently skipping). Any edit clears the armed state so a stale config is never mistaken for live. The backtest is read-only over real data and reports insufficient-data verdicts and confidence levels instead of inflated numbers. Once live, the worker adds further hard stops: global and per-agent kill switches, daily budget and concurrency enforcement, a price-impact circuit breaker on a fresh quote, one-shot-per-mint idempotency, a Mayhem-mode token exclusion, a fail-closed market-cap band, and a trailing-24-hour realized-loss circuit breaker that halts new buys for a bleeding wallet.+Owner-only surface end to end: the tab is hidden from non-owners, and every endpoint verifies session or bearer auth, CSRF, per-IP rate limits, and that the agent belongs to the caller; a bearer token (API key or OAuth access token) must also carry the `wallet:write` scope to save or arm a strategy. Compiled strategies are clamped server-side to the agent's runtime trade guards (per-trade SOL cap, daily budget cap, slippage ceiling, price-impact breaker, and max-concurrent cap), with every clamp disclosed in the UI. A stop-loss is mandatory and can never be removed (defaults to 35%, clamped 1-95%, and the arm endpoint rejects any strategy without one). Arming requires a nonzero per-trade size and daily budget, per-trade can never exceed the daily budget, and mainnet arming is gated behind an explicit risk-acknowledgment dialog (which degrades to a native confirm rather than silently skipping). Any edit clears the armed state so a stale config is never mistaken for live. The backtest is read-only over real data and reports insufficient-data verdicts and confidence levels instead of inflated numbers. Once live, the worker adds further hard stops: global and per-agent kill switches, daily budget and concurrency enforcement, a price-impact circuit breaker on a fresh quote, one-shot-per-mint idempotency, a Mayhem-mode token exclusion, a fail-closed market-cap band, and a trailing-24-hour realized-loss circuit breaker that halts new buys for a bleeding wallet.## 11 · Earn@@ -1874,7 +1874,7 @@ The Withdraw tab is the owner's exit door and control room for an agent's custodThe agent's private key lives encrypted on the server and never touches the browser — a withdrawal is a server-signed request, and each time the key is decrypted, that access is itself recorded as a custody event. Before signing, the server runs the withdrawal through the shared spend policy: the freeze switch, the withdraw allowlist, the owner's plain-English safety rules (compiled by an LLM into deterministic rules, then enforced by code), per-transaction and rolling 24-hour USD ceilings, and a behavioral anomaly guard. Each request carries a unique idempotency key claimed as a row in the custody ledger, so a retry replays the original result instead of double-sending, and an ambiguous network timeout leaves the withdrawal marked pending with an explorer link rather than risking a duplicate. On a SOL "Max" the server reserves rent plus fee headroom so a full sweep can never brick the wallet, and token withdrawals automatically open the recipient's token account when needed. The asset picker, spend totals, and activity feed all read live on-chain and ledger data — nothing is cached guesswork.-Owner-only end to end: every endpoint verifies the signed-in user owns the agent. Withdrawals are capped at 5 per day per user with an additional per-IP burst guard. Every state-changing request requires a single-use CSRF token, and mainnet withdrawals require an explicit risk acknowledgment. The server enforces the shared spend policy before signing: withdraw allowlist (if set, funds can only go to approved addresses), per-transaction and rolling 24-hour USD ceilings, the owner's plain-English safety rules enforced deterministically, and a behavioral anomaly guard that can auto-freeze the wallet. The freeze switch halts all autonomous spending but deliberately never blocks the owner's withdrawals: a freeze can never trap funds. An API key or OAuth token (a bearer, as opposed to the owner's signed-in session) can withdraw only when it carries the wallet:write scope; the no-funds withdraw preview and every read still answer with a lesser grant, and the same gate (api/_lib/spend-scope.js) guards every REST route that trades, pays, hires, launches, or arms an autonomous spender. Destinations must be valid, on-curve addresses and cannot be the wallet itself. SOL sweeps always reserve rent plus fees so the account survives. Idempotency keys make retries safe against double-sends, ambiguous confirmations return a pending state with an explorer link instead of guessing, and every withdrawal, key decryption, limit change, and policy block lands in an owner-visible audit ledger.+Owner-only end to end: every endpoint verifies the signed-in user owns the agent. Withdrawals are capped at 5 per day per user with an additional per-IP burst guard. Every state-changing request requires a single-use CSRF token, and mainnet withdrawals require an explicit risk acknowledgment. The server enforces the shared spend policy before signing: withdraw allowlist (if set, funds can only go to approved addresses), per-transaction and rolling 24-hour USD ceilings, the owner's plain-English safety rules enforced deterministically, and a behavioral anomaly guard that can auto-freeze the wallet. The freeze switch halts all autonomous spending but deliberately never blocks the owner's withdrawals, so a freeze can never trap funds. Destinations must be valid, on-curve addresses and cannot be the wallet itself. SOL sweeps always reserve rent plus fees so the account survives. Idempotency keys make retries safe against double-sends, ambiguous confirmations return a pending state with an explorer link instead of guessing, and every withdrawal, key decryption, limit change, and policy block lands in an owner-visible audit ledger.## 19 · Give@@ -1914,7 +1914,7 @@ The Self-defense tab is the owner's control room for a wallet that protects itseA deterministic scoring engine builds a behavioral baseline from up to 2,000 of the agent's real historical spends (size distribution, up to 200 known counterparties, active hours, assets, velocity), caches it for three hours, and reads live 1-minute/10-minute velocity counts fresh on every action. The guard runs inline on the spend path itself — trades, snipes, x402 payments, agent hires, and withdrawals all pass through it after the static spend caps — combining up to five weighted signals (oversized amount, never-seen destination, burst velocity, off-hours activity, new asset) with a noisy-OR formula into one score; crossing the sensitivity threshold, or any single catastrophic signal, flips a shared freeze switch in the database, writes an audit row, and fires a real owner notification linking straight to this tab. The tab itself only renders live database state from the owner-gated guard endpoint, polls every 12 seconds while frozen so a flag or cross-device unfreeze appears instantly, and every mutation is CSRF-protected. Approving a flag folds that destination, amount ceiling, and hour back into the config so the wallet gets smarter, not naggier; "Sweep to safety" executes a real, audited, server-signed on-chain transfer of the wallet's maximum SOL to the owner's safe address.-Owner-only surface end to end: the tab is gated to the wallet owner and every API call verifies session or bearer auth plus agent ownership, returning 401/403/404 otherwise. All mutations (config changes, approve/deny/unfreeze, sweeps) require a CSRF token; reads are rate-limited per user, and sweeps carry a per-user daily withdrawal cap plus a per-IP burst limit. Destructive actions demand explicit confirmation dialogs (unfreeze, sweep, reset-learned), and the sweep dialog states the transfer is irreversible and that the wallet stays frozen afterward. The safe address is validated server-side and program addresses (PDAs) are rejected because funds sent there could be unrecoverable; sweeps reserve rent and network fees, use idempotency keys against double-sends, and write audit rows. A freeze blocks every autonomous spend path but never the owner's withdrawal — the escape hatch stays open by design. Freezing is idempotent (no freeze/unfreeze thrashing), critical signals override even Relaxed sensitivity, and scoring errors fail safe rather than silently open.+Owner-only surface end to end: the tab is gated to the wallet owner and every API call verifies session or bearer auth plus agent ownership, returning 401/403/404 otherwise, and a bearer token can only read here unless it carries the `wallet:write` scope (403 `insufficient_scope`). All mutations (config changes, approve/deny/unfreeze, sweeps) require a CSRF token; reads are rate-limited per user, and sweeps carry a per-user daily withdrawal cap plus a per-IP burst limit. Destructive actions demand explicit confirmation dialogs (unfreeze, sweep, reset-learned), and the sweep dialog states the transfer is irreversible and that the wallet stays frozen afterward. The safe address is validated server-side and program addresses (PDAs) are rejected because funds sent there could be unrecoverable; sweeps reserve rent and network fees, use idempotency keys against double-sends, and write audit rows. A freeze blocks every autonomous spend path but never the owner's withdrawal: the escape hatch stays open by design. Freezing is idempotent (no freeze/unfreeze thrashing), critical signals override even Relaxed sensitivity, and scoring errors fail safe rather than silently open.---@@ -1944,7 +1944,7 @@ Real-time and nine-years-deep crypto news in one place, readable without visitinA CoinGecko-style /coins index (global stats bar, sortable top-coins table with 7d sparklines, debounced full-catalog search, load-more paging) and a shareable /coin/:id detail page per coin: interactive 24H-1Y chart with crosshair (switchable between the native CoinGecko chart and TradingView, DexScreener, Birdeye, GMGN, and GeckoTerminal views where the coin qualifies, the embed URLs living once in src/shared/chart-embeds.js so /coin/:id and /launches/<mint> build identical charts and a provider that does not index the coin's chain is never offered; a third-party embed that is blocked or never renders is replaced within a deadline by a designed panel with a Try again button and a link to the provider, never a blank frame), market stats, related news, official links, and per-chain contract addresses. Also a live perpetual-futures view (price, funding rate, open interest per contract).-pages/coins.html + src/coins-index.js and pages/coin.html + src/coin-page.js over api/coin/* (detail, ohlc, markets, tickers, news, global, derivatives) proxying CoinGecko via api/_lib/coingecko.js. The coin page's Markets table (api/coin/tickers) falls back to CoinPaprika when CoinGecko is throttled, and then to the coin's own DEX pairs read by its contract addresses, so a young DEX-only token still lists where it trades. :id accepts a CoinGecko slug OR a Solana mint; mint-shaped ids cross-link into Alpha Copilot, the live trade feed, /launches, and Coin Intelligence.+pages/coins.html + src/coins-index.js and pages/coin.html + src/coin-page.js over api/coin/* (detail, ohlc, markets, news, global, derivatives) proxying CoinGecko via api/_lib/coingecko.js. :id accepts a CoinGecko slug OR a Solana mint; mint-shaped ids cross-link into Alpha Copilot, the live trade feed, /launches, and Coin Intelligence.Full-market price coverage that plugs directly into the platform's Solana/pump.fun surfaces — a coin page is never a dead end.@@ -1982,9 +1982,9 @@ Rug/bundle detection and launch quality signals for any pump.fun coin, free and## /launches feed + pump.fun launch integration-A public directory of every coin launched through three.ws by its agents: registry rows render instantly, then live pump.fun market data (price, art, graduation status) streams in per card, with an agent filter, generative per-mint identicons, and a 60s live refresh. The feed is deliberately neutral: no score, tier, or grade is painted on a user's coin. Judgment is replaced by facts on each mint's own addressable profile at /launches/<mint>, a trader sheet over /api/pump/token-stats (5m/1h/6h/24h volume, buys, sells, net buy, unique traders, price change; holder count, top-10 share, dev share, early-buyer share; mint and freeze authority; bonding-curve progress and graduation state; liquidity) beside a live price chart and trade tape, where a field that could not be read renders as a dash and never as 0. Launching itself is built in: a 'Launch Pump.fun' modal on every agent profile (client-signed, so user keys never leave the browser via launch-prep/launch-confirm), autonomous server-signed agent launches under spend caps, the Memetic Launcher (per-user autonomous launcher with trend sources and daily SOL caps), and Launch Studio's 50 declarative launch recipes.+A public directory of every coin launched through three.ws by its agents: registry rows render instantly, then live pump.fun market data (price, art, graduation status) streams in per card, with an agent filter, generative per-mint identicons, and a 60s live refresh. The feed is deliberately neutral: no score, tier, or grade is painted on a user's coin. Judgment is replaced by facts on each mint's own addressable profile at /launches/<mint>, a trader sheet over /api/pump/token-stats (5m/1h/6h/24h volume, buys, sells, net buy, unique traders, price change; holder count, top-10 share, dev share, early-buyer share; mint and freeze authority; bonding-curve progress and graduation state; liquidity) beside a live price chart and trade tape, where a field that could not be read renders as a dash and never as 0. A Launch receipt panel on the same page (GET /api/pump/launch-receipt) composes mint and freeze authority, supply, top-10 holder share, fee routing, the creation transaction and the Trade Safety Firewall verdict into one plain-English sentence per fact; each source fails independently and shows as unavailable with a reason, never an invented value, and the receipt can be copied as text, downloaded as JSON (it carries a content_hash so a saved copy can be checked later) or shared as a ?variant=receipt card. Launching itself is built in: a 'Launch Pump.fun' modal on every agent profile (client-signed, so user keys never leave the browser via launch-prep/launch-confirm), autonomous server-signed agent launches under spend caps, the Memetic Launcher (per-user autonomous launcher with trend sources and daily SOL caps), and Launch Studio's 50 declarative launch recipes.-src/launches.js reads the platform's own launch records via GET /api/pump/launches (pump_agent_mints bonding-curve coins plus fixed_supply_launches, one query in api/_lib/pump-agent-launches.js) and enriches per-coin from pump.fun via /api/pump/coin; a coin an agent launched on Robinhood Chain through Pons renders with its venue, a chain explorer link and its /markets/robinhood/coin/<address> page instead of pump.fun data; the launch path is documented in docs/coin-launches.md and docs/pump-launcher.md over api/pump/[action].js.+src/launches.js reads the platform's own pump_agent_mints launch records via GET /api/pump/launches and enriches per-coin from pump.fun via /api/pump/coin. A coin an agent launched on Robinhood Chain through Pons renders as its own card that links to the venue, the chain's explorer, and its /markets/robinhood/coin/<address> page instead of pump.fun; the launch path is documented in docs/coin-launches.md and docs/pump-launcher.md over api/pump/[action].js.Launch a real on-chain pump.fun coin from an agent's profile in one flow, and every launch gets a live, shareable home in the platform's public feed plus its own /launches/<mint> profile that shows the numbers and leaves the verdict to the reader.@@ -2008,7 +2008,7 @@ Turn an agent into an on-chain business: its coin is its equity, its invoices arToken sentiment on demand: POST /api/sentiment scores any text (Positive/Negative/Neutral) with a deterministic lexicon scorer; /api/social/sentiment-pulse pulls the real community commentary (pump.fun callouts) for any Solana/pump.fun mint and returns an overall score with per-source breakdown and examples (also sold as the paid sentiment_pulse MCP tool); aixbt narrative intel and momentum-ranked project scans are exposed at api/aixbt/* and as aixbt_intel / aixbt_projects MCP tools. All packaged for developers as the @three-ws/intel npm module.-Sentiment-pulse fetches the coin's most recent pump.fun callouts (the frontend-api-v3 `/callout/coin/:mint` feed the pump.fun coin page renders; the older comments and `/callout/top` routes were retired upstream) plus caller-supplied snippets, scored by the in-repo lexicon engine (src/social/sentiment.js, which matches terms on word boundaries so "partnered" never scores as "red"). A pump.fun outage with no caller-supplied texts answers 502 `upstream_unavailable` rather than a fabricated neutral score, while a coin that is simply quiet still answers 200 with `count: 0`; aixbt endpoints proxy the aixbt market-intelligence service.+Sentiment-pulse fetches the coin's most recent pump.fun callouts (the frontend-api-v3 `/callout/coin/:mint` feed the pump.fun coin page renders; the older comments and `/callout/top` routes were retired upstream) plus caller-supplied snippets, scored by the in-repo lexicon engine (src/social/sentiment.js, which matches terms on word boundaries so "partnered" never scores as "red"). A pump.fun block or outage serves the last successful callouts for that mint as `sources.pumpfunStatus: 'stale'`; only a cold mint with no cached copy and no caller-supplied texts answers 502 `upstream_unavailable` rather than a fabricated neutral score, while a coin that is simply quiet still answers 200 with `count: 0`; aixbt endpoints proxy the aixbt market-intelligence service.Read the crowd on any token before acting — from a free one-call API, an agent skill, an MCP tool, or a single npm import.diff --git a/docs/agent-abilities/FULL-ARTICLE.md b/docs/agent-abilities/FULL-ARTICLE.mdindex 2848ff435..3cd912152 100644--- a/docs/agent-abilities/FULL-ARTICLE.md+++ b/docs/agent-abilities/FULL-ARTICLE.md@@ -752,7 +752,7 @@ Agents that launch their own pump.fun coins on a schedule you set — every N hoA fee harvester that watches every coin an agent launched and automatically collects the creator fees whenever they cross a threshold — no manual sweeping, no forgotten revenue. When a coin is running hot, the dashboard flags it 'Ready to Claim' and gives you a claim-it-now button showing the exact SOL waiting.-**How it works:** api/cron/launcher-claimer.js runs every 5 minutes: for each launched coin with ≥0.01 SOL of accrued creator fees (and no claim in the past 24h) it queries live fee info, has the agent sign its own claim transaction — the same key that signed the launch — and records the claim with the buyback-earmarked share for revenue accounting. The dashboard's Auto-Claim panel shows claimable-now vs total-earned per coin and exposes a manual 'Claim' action through the same collect-creator-fee endpoint the cron uses.+**How it works:** api/cron/launcher-claimer.js runs every 5 minutes: for each launched coin with ≥0.01 SOL of accrued creator fees (and no claim in the past 24h) it queries live fee info, has the agent sign its own claim transaction (the same key that signed the launch), and records the claim with the buyback-earmarked share for revenue accounting (50% by default, read from the one shared creator-fee claim policy in api/_lib/token/config.js that the creator payout also uses, so the earmark and the payout cannot disagree). The dashboard's Auto-Claim panel shows claimable-now vs total-earned per coin and exposes a manual 'Claim' action through the same collect-creator-fee endpoint the cron uses.**Why it matters:** Creator fees are the whole point of launching, and they leak when nobody sweeps them. Auto-Claim turns fee collection into a background process: your agents harvest their own earnings every five minutes, and you can see — and one-click trigger — every claim yourself.@@ -840,7 +840,7 @@ After launching a coin, you configure your agent's market-making behavior with pEvery agent has a live screen anyone can watch, and a task bar where any visitor — no account needed — can type a question. The agent answers in its own persona, streamed word by word so its avatar can speak the answer aloud, and remembers the conversation within your session so follow-ups make sense.-**How it works:** A public SSE endpoint that runs the agent's configured brain (anonymous visitors are clamped to free-tier models so public chat can never burn billed keys), writing each exchange to a short-TTL session-scoped memory thread.+**How it works:** A public SSE endpoint that runs the agent's configured brain (anonymous visitors are clamped to free-tier models so public chat can never burn billed keys), writing each exchange to a short-TTL session-scoped memory thread. An unpublished agent answers only its owner, and visitor questions are tagged so the owner's own chat never recalls them into its prompt.**Why it matters:** Agents aren't just on display — every one of them is a concierge you can interrogate on the spot.@@ -1336,7 +1336,7 @@ The full monetization lifecycle for an agent: register it on-chain with the pumpOne agent autonomously discovers, pays, and calls a peer agent's paid A2A skill — under a signed Intent Mandate the user issued ahead of time, with optional ERC-8004 reputation gating (minimum average rating and review count) before any USDC moves. The payment is performed, not hidden: PAY_INTENT, then PAY_SETTLED with a celebration emote or PAY_FAILED with visible concern.-**How it works:** src/agent-skills-a2a.js POSTs to /api/agents/a2a-call, where the server enforces the mandate, a budget ledger, the peer's on-chain reputation, and the agent's own spend policy (the freeze switch and the per-transaction, rolling-daily, and per-counterparty ceilings), which a mandate cannot widen: a halted agent is refused with wallet_frozen before the peer is even quoted, and an agent deleted or transferred since the mandate was signed stops being spendable. Each payment writes a receipt to the agent's custody ledger (returned as receipt_id, readable at GET /api/agents/:id/solana/custody?category=x402) and releases it again on any failure; settlement flows over the x402 protocol and the receipt (amount, network, transaction, artifacts) comes back to be spoken in dollars.+**How it works:** src/agent-skills-a2a.js POSTs to /api/agents/a2a-call, where the server (an API key or OAuth token needs the wallet:write scope, like any spend) enforces the mandate, a budget ledger, the peer's on-chain reputation, and the agent's own spend policy (the freeze switch and the per-transaction, rolling-daily, and per-counterparty ceilings), which a mandate cannot widen, plus platform-set ceilings no mandate or agent policy can raise ($25 per call, $50 per user per day, $500 across the whole payer wallet per day): a halted agent is refused with wallet_frozen before the peer is even quoted, and an agent deleted or transferred since the mandate was signed stops being spendable. Each payment writes a receipt to the agent's custody ledger (returned as receipt_id, readable at GET /api/agents/:id/solana/custody?category=x402) and releases it again on any failure; settlement flows over the x402 protocol and the receipt (amount, network, transaction, artifacts) comes back to be spoken in dollars.**Why it matters:** This is the agent economy made visible and safe: your agent can hire other agents within a budget you pre-authorized, refuse untrusted peers, and you literally watch the money move — every payment bounded by your signed mandate.@@ -1472,7 +1472,7 @@ On three.ws, agents don't just chat — they earn, spend, hire, and get hired, wYour agent can autonomously hire another agent for a skill it doesn't have — it resolves the provider's published offer, reserves the spend against its own policy, pays real USDC from its own wallet, and only settles after the work actually succeeds. A failed job can never charge the hirer: the flow is verify-then-settle by construction. Every completed hire produces an on-chain settlement plus a separate on-chain invocation receipt naming both agents, auditable from both sides with explorer links.-**How it works:** POST /api/agents/a2a-hire chains the offer registry (agent_paid_services), atomic spend reservation (per-tx + daily caps + kill switch), the x402 exact-scheme USDC payment on Solana mainnet via @x402/svm, and an on-chain invocation-receipt program write; hires land in the agent_hires ledger.+**How it works:** POST /api/agents/a2a-hire chains the offer registry (agent_paid_services), atomic spend reservation (per-tx + daily caps + kill switch), a provider standing check (the open Solana agent registry tier is read live with a stale-snapshot fallback, and an optional minRegistryTier rejects a provider below the bar with 409 provider_below_tier before any spend), the x402 exact-scheme USDC payment on Solana mainnet via @x402/svm, and an on-chain invocation-receipt program write; hires land in the agent_hires ledger. A hire above the agent's approval threshold is parked in the Approval Inbox (202 with a poll link) and resumes when the owner approves.**Why it matters:** Your agent can buy capabilities it lacks, safely, with zero chance of paying for failed work.@@ -1977,7 +1977,7 @@ The Withdraw tab is the owner's exit door and control room for an agent's custod**Under the hood.** The agent's private key lives encrypted on the server and never touches the browser — a withdrawal is a server-signed request, and each time the key is decrypted, that access is itself recorded as a custody event. Before signing, the server runs the withdrawal through the shared spend policy: the freeze switch, the withdraw allowlist, the owner's plain-English safety rules (compiled by an LLM into deterministic rules, then enforced by code), per-transaction and rolling 24-hour USD ceilings, and a behavioral anomaly guard. Each request carries a unique idempotency key claimed as a row in the custody ledger, so a retry replays the original result instead of double-sending, and an ambiguous network timeout leaves the withdrawal marked pending with an explorer link rather than risking a duplicate. On a SOL "Max" the server reserves rent plus fee headroom so a full sweep can never brick the wallet, and token withdrawals automatically open the recipient's token account when needed. The asset picker, spend totals, and activity feed all read live on-chain and ledger data — nothing is cached guesswork.-**Guardrails.** Owner-only end to end: every endpoint verifies the signed-in user owns the agent. Withdrawals are capped at 5 per day per user with an additional per-IP burst guard. Every state-changing request requires a single-use CSRF token, and mainnet withdrawals require an explicit risk acknowledgment. The server enforces the shared spend policy before signing: withdraw allowlist (if set, funds can only go to approved addresses), per-transaction and rolling 24-hour USD ceilings, the owner's plain-English safety rules enforced deterministically, and a behavioral anomaly guard that can auto-freeze the wallet. The freeze switch halts all autonomous spending but deliberately never blocks the owner's withdrawals — a freeze can never trap funds. Destinations must be valid, on-curve addresses and cannot be the wallet itself. SOL sweeps always reserve rent plus fees so the account survives. Idempotency keys make retries safe against double-sends, ambiguous confirmations return a pending state with an explorer link instead of guessing, and every withdrawal, key decryption, limit change, and policy block lands in an owner-visible audit ledger.+**Guardrails.** Owner-only end to end: every endpoint verifies the signed-in user owns the agent. Withdrawals are capped at 5 per day per user with an additional per-IP burst guard. Every state-changing request requires a single-use CSRF token, and mainnet withdrawals require an explicit risk acknowledgment. The server enforces the shared spend policy before signing: withdraw allowlist (if set, funds can only go to approved addresses), per-transaction and rolling 24-hour USD ceilings, the owner's plain-English safety rules enforced deterministically, and a behavioral anomaly guard that can auto-freeze the wallet. The freeze switch halts all autonomous spending but deliberately never blocks the owner's withdrawals, so a freeze can never trap funds. Destinations must be valid, on-curve addresses and cannot be the wallet itself. SOL sweeps always reserve rent plus fees so the account survives. Idempotency keys make retries safe against double-sends, ambiguous confirmations return a pending state with an explorer link instead of guessing, and every withdrawal, key decryption, limit change, and policy block lands in an owner-visible audit ledger.- The confirm screen warns you before the server does: if a destination isn't on your allowlist, a live '⚠ not on allowlist — this will be rejected' badge appears right next to the address- The one-tap Freeze wallet panel — a kill switch that instantly pauses all of the agent's autonomous trading and payments while your own exit stays open@@ -2145,7 +2145,7 @@ Agents launched as pump.fun coins can charge for their services on-chain: buildToken sentiment on demand: POST /api/sentiment scores any text (Positive/Negative/Neutral) with a deterministic lexicon scorer; /api/social/sentiment-pulse pulls the real community commentary (pump.fun callouts) for any Solana/pump.fun mint and returns an overall score with per-source breakdown and examples (also sold as the paid sentiment_pulse MCP tool); aixbt narrative intel and momentum-ranked project scans are exposed at api/aixbt/* and as aixbt_intel / aixbt_projects MCP tools. All packaged for developers as the @three-ws/intel npm module.-**How it works:** Sentiment-pulse fetches the coin's most recent pump.fun callouts (the frontend-api-v3 `/callout/coin/:mint` feed the pump.fun coin page renders; the older comments and `/callout/top` routes were retired upstream) plus caller-supplied snippets, scored by the in-repo lexicon engine (src/social/sentiment.js, which matches terms on word boundaries so "partnered" never scores as "red"). A pump.fun outage with no caller-supplied texts answers 502 `upstream_unavailable` rather than a fabricated neutral score, while a coin that is simply quiet still answers 200 with `count: 0`; aixbt endpoints proxy the aixbt market-intelligence service.+**How it works:** Sentiment-pulse fetches the coin's most recent pump.fun callouts (the frontend-api-v3 `/callout/coin/:mint` feed the pump.fun coin page renders; the older comments and `/callout/top` routes were retired upstream) plus caller-supplied snippets, scored by the in-repo lexicon engine (src/social/sentiment.js, which matches terms on word boundaries so "partnered" never scores as "red"). A pump.fun block or outage serves the last successful callouts for that mint as `sources.pumpfunStatus: 'stale'`; only a cold mint with no cached copy and no caller-supplied texts answers 502 `upstream_unavailable` rather than a fabricated neutral score, while a coin that is simply quiet still answers 200 with `count: 0`; aixbt endpoints proxy the aixbt market-intelligence service.**Why it matters:** Read the crowd on any token before acting — from a free one-call API, an agent skill, an MCP tool, or a single npm import.diff --git a/docs/agent-wallet-api.md b/docs/agent-wallet-api.mdindex d325f88fa..21a287103 100644--- a/docs/agent-wallet-api.md+++ b/docs/agent-wallet-api.md@@ -531,7 +531,7 @@ All writes are owner-gated and CSRF-gated. `:intentId` must be a UUID.### The intent model-Triggers: `on_tip_received` (optional `min_sol`), `on_income`, `on_balance_below` (required `threshold_sol`), `on_schedule` (`cadence` of `daily` or `weekly`, `weekday` 0 through 6, `hour` 0 through 23 UTC), `on_launch_matching` (needs a base58 `creator` and/or a `max_mcap_usd`, optional `min_mcap_usd`), `on_stream_started`, `credits_below` (required `threshold_usd`, the owner's account credits), and `on_mail_received` (optional `from_contains` and `subject_contains` filters, matched case-insensitively). A further trigger, `on_automation`, is fired only by the v1 automation engine, never by the sweep.+Triggers: `on_tip_received` (optional `min_sol`), `on_income`, `on_balance_below` (required `threshold_sol`), `on_schedule` (`cadence` of `daily` or `weekly`, `weekday` 0 through 6, `hour` 0 through 23 UTC), `on_launch_matching` (needs a base58 `creator` and/or a `max_mcap_usd`, optional `min_mcap_usd`), `on_stream_started`, `credits_below` (required `threshold_usd`, the owner's account credits), and `on_mail_received` (optional `from_contains` and `subject_contains` filters, matched case-insensitively; `from_contains` is an exact sender address or a domain such as `acme.example` or `@acme.example`, which also covers its subdomains, never a substring; the rule fires only for mail whose sender passed DMARC). A further trigger, `on_automation`, is fired only by the v1 automation engine, never by the sweep.Actions: `tip`, `transfer`, `withdraw`, `split_income` (move SOL: take `pct` with an `of` basis of `tip`, `income`, or `balance`, or a fixed `amount_sol`, or for a withdraw an `above_sol` floor, plus a `destination`), `buy` and `snipe` (need `amount_sol`, plus a `mint` unless the trigger is `on_launch_matching`, with an optional `slippage_pct` clamped to 0 through 50 and defaulting to 5), `freeze` (no parameters, the kill switch), `notify` (optional `message`, `channel` of `email` or `log`), and `fund_inference` (top up the owner's account credits from the agent's USDC: `amount_usdc` from 0.1 to 1000, at most once per rule per UTC day).@@ -1253,6 +1253,8 @@ Rejections are specific, each a `DelegationError` code: `invalid_delegation` (ma[`POST /api/agent/guard`](../api/agent/guard.js) is the one endpoint that actually enforces a delegation's cap. It accepts the same `{ delegation, delegationSignature }` pair inline (registering or re-registering before evaluating `calls`) and, for every proposed call, resolves the call's lamport cost and rejects with `blockedBy: "spend_delegation"` and `code: "DELEGATION_CAP_EXCEEDED"` or `"DELEGATION_EXPIRED"` when the active delegation would be breached. The delegation layer only ever *tightens* an `allow` into a `block`; if the guard's seven existing layers already blocked the call for another reason, the delegation check never runs or overrides it.+The same endpoint also gates `allowance_pull` calls against an owner-funded on-chain allowance (the `/solana/allowance` route, covered in [agent-allowance-budgets.md](agent-allowance-budgets.md)). The live remaining amount is read from the program's own account, a pull it would reject is refused with `blockedBy: "onchain_allowance"` and a specific `code`, and the verdict carries an `allowance` object (`allow`, `code`, `reason`, `detail`, `allowanceId`, `remaining`). If the account cannot be read, the call is not blocked on that basis and a blind spot is recorded instead.+## Related- [Agent wallets](agent-wallets.md) for the wallet itself: creation, key custody, and the five spend paths.diff --git a/docs/animation-seeding.md b/docs/animation-seeding.mdindex 06eded013..fc2f0a510 100644--- a/docs/animation-seeding.md+++ b/docs/animation-seeding.md@@ -2,8 +2,8 @@three.ws generates its own animation clips. A prompt from `data/motion-prompts.json`goes to our self-hosted text-to-motion GPU worker, the result is measured against a-quality gate, and the keepers are published into the same clip library the curated-Mixamo import already serves.+quality gate, and the keepers are published into the same bulk clip library+(`GET /api/animations/library`) that the CC0 packs feed.This document covers what the gate measures and why, because the "why" is the partthat is easy to get catastrophically wrong.@@ -13,16 +13,23 @@ that is easy to get catastrophically wrong.| Piece | What it does ||---|---|| `data/motion-prompts.json` | The prompt library: 180 prompts across 10 categories. Data, never a hardcoded list. |-| `workers/model-text2motion/` | The GPU worker. Samples a motion-diffusion model and returns a three.js `AnimationClip` JSON. |+| `workers/model-text2motion/` | The GPU worker. Samples a HumanML3D text-to-motion model and returns a three.js `AnimationClip` JSON. Two backends, chosen per `/infer` request with `model`: `mdm` (default, the one the seed runner and `/api/forge-motion` use, and the source of the Kabsch artifacts described below) and `momask`, loaded lazily on first use. || `api/forge-motion.js` | The public route: `POST` a prompt, poll for a clip. Rate limited per IP. || `api/_lib/motion-seed.js` | The prompt loader, the rest-shape conversion, the foot-flick and root-travel repairs, the quality gate, the publishing shape, the free-subset rotation. || `api/_lib/motion-glb.js` | Bakes a clip onto the platform rig as one portable GLB, the artifact the marketplace sells. || `api/_lib/generated-clip-market.js` | The generated collection as a marketplace product line: listing rows, price, and the weekly free rotation. || `scripts/gcp/seed-motion.mjs` | The resumable bulk runner: generate, re-derive, publish, list for sale. |-| `api/animations/library.js` | Serves the clip manifest that generated clips are merged into. |+| `api/animations/library.js` | Serves the clip manifest that generated clips are merged into. Drops any entry with no `license`, or whose `source` names Mixamo, before the response serializes (`isPublishable()`). |+| `scripts/cc0-animation-library.mjs` | Builds the rest of the bulk library from CC0 packs, with per-clip provenance in `scripts/cc0-library.config.json`. |Generated clips are named `gen-<prompt id>-<hash>`, so they are distinguishable from-the `mx-` Mixamo import everywhere: in the manifest, the gallery, and any report.+the other bulk-library clips everywhere: in the manifest, the gallery, and any report.+Every generated entry carries its `source` and `license`, which the gallery shows+on each card. The legacy `mx-` Mixamo import is no longer served: Adobe's terms+allow in-project playback but not redistributing the raw clips, so the publish+phase of `scripts/mixamo-all.mjs` is permanently disabled and the endpoint+filters such entries out. Mixamo-era measurements below are kept as the record of+how the gate was calibrated.## Format: the names match, the basis did not@@ -102,7 +109,10 @@ the same 882 takes in the new basis took the accept rate from 47% to 71%, andThe same conversion now runs for on-demand generation: the `/api/forge-motion`poll returns the converted clip as `clip` next to the raw `clip_url`, and the-Animation Studio plays `clip`.+Animation Studio plays `clip`. `libraryReadyClip` hands `userData` over as a JSON+string (the basis stamp included), because `AnimationClip.parse()` feeds it to+`JSON.parse()`; a plain object there made every generated clip die client-side+with `"[object Object]" is not valid JSON`.## Foot flicks: a second Kabsch artifact@@ -239,9 +249,9 @@ touching a number. A broken pipeline looks exactly like a strict gate.## Loop seamsA motion-diffusion sampler does not produce seamless loops. It samples a window, and-the last frame has no reason to meet the first. This matters because **41% of the-prompt library (56 of 137) is tagged `loop`**, concentrated exactly where looping-matters: locomotion (16 of 20), dance (10 of 12), idle (10 of 14).+the last frame has no reason to meet the first. This matters because **42% of the+prompt library (75 of 180) is tagged `loop`**, concentrated exactly where looping+matters: locomotion (21 of 25), dance (14 of 16), idle (14 of 18).Measured on real output, a generated walk ends **0.25 m** per joint from where itstarted (hips-relative), against **0.000** for the authored library's loops. Publisheddiff --git a/docs/api-reference.md b/docs/api-reference.mdindex 8239c29fb..e66ce0222 100644--- a/docs/api-reference.md+++ b/docs/api-reference.md@@ -4094,7 +4094,11 @@ Bonding-curve / graduation status for one pump.fun mint — % to graduation, SOLin the curve, tokens remaining, market cap, and whether it has already migratedto an AMM (Raydium / PumpSwap). Same engine as[`GET /api/crypto/bonding`](crypto-api.md)-(`api/_lib/pump-bonding.js` `getBondingStatus`).+(`api/_lib/pump-bonding.js` `getBondingStatus`). Data comes from pump.fun's frontend+API, backed by a last-known-good copy that survives 6 hours+(`PUMP_BONDING_LKG_TTL_S`). When pump.fun is unreachable and no copy survives,+the curve account is read from Solana RPC and the response carries+`"source": "onchain"` (with `marketCapUsd` null for a coin still on the curve).```GET /api/v1/pump/curve?mint=<mint>@@ -4766,7 +4770,7 @@ stored. Errors: `401 unauthenticated`, `403` (cross-site origin),GET /api/auth/handoff?code=<code>&next=<path>```-Opened by Safari, never called with `fetch`. On a valid code it consumes it,+Opened by Safari, never called with `fetch`. A request whose `Sec-Fetch-Site` is `cross-site` or `same-site` (a link followed from another page) is refused and redirected to the login with `handoff_expired`, because honouring it would let an attacker sign a victim in as the attacker; the app's own navigation sends `none`. On a valid code it consumes it,replaces any session Safari already had with one for the code's user, andanswers `302` to the path stored at mint time. A used, expired or malformed coderedirects to `/login?error=handoff_expired&next=<path>`, so the visitor signs in@@ -5925,10 +5929,10 @@ Three, not two, and the third is the one to design for.| Result | HTTP | Budget | What to do || ------ | ---- | ------ | ---------- || Settled | 200 | Debited | Use the result. `tx_hash` is your receipt. |-| Rejected pre-settlement | 402 `payment_rejected` | **Restored** | Nothing moved on-chain. Safe to retry. |+| Host answered 402 after the signed payment was sent | 402 `payment_rejected` | **Held** | The transfer was already handed to the host, and a host that is also the fee payer can broadcast it and still answer 402, so a 402 is not proof nothing landed. Check the ledger or the explorer before retrying. || Submitted, unconfirmed | 502 `settle_uncertain` | **Held** | The transfer may have landed. Do not retry blindly: read `/api/pay/session/:id/executions` or the explorer first. |-The budget is deliberately *not* restored on `settle_uncertain`. Releasing it would let the next call spend money that may already be gone, so the accounting stays conservative and the uncertainty stays visible in the ledger.+The budget is deliberately *not* restored on `settle_uncertain` or on a 402 after the payment was signed and sent. Releasing it would let the next call spend money that may already be gone, so the accounting stays conservative and the uncertainty stays visible in the ledger.### Expiry and refundsdiff --git a/docs/ar.md b/docs/ar.mdindex de7ef8426..a86ecad8e 100644--- a/docs/ar.md+++ b/docs/ar.md@@ -54,7 +54,7 @@ You do not add an attribute to enable AR; you link to (or embed) one of the AR s| AR Forge | `/ar` | Generate a model from a prompt and place it immediately || Living-agent AR | `/irl?avatar=<glbUrl>` | A rigged avatar that walks and talks in your room (WebXR) |-The avatar AR page and `/ar/view` (the page `/api/ar` redirects to) render the model in Google's `<model-viewer>` element with `ar ar-modes="webxr scene-viewer quick-look"`, so the same page covers Quick Look, Scene Viewer, and WebXR. The **Place in your space** button appears only when the device exposes a usable AR mode (model-viewer's `canActivateAR`); on desktop the page shows a QR code handoff instead. `/api/ar` itself renders no 3D: it is a server-side router that either 302s into a Scene Viewer intent (plain Android) or serves a tiny Open-Graph interstitial that hands off to `/ar/view` (see [the launcher section](#one-tap-ar-for-any-glb--get-apiar--export_ar)).+The avatar AR page (`/avatars/<id>/ar`, `/agents/<id>/ar`) renders the model in the `<agent-3d ar ar-modes="webxr scene-viewer quick-look" ar-placement="floor">` element, which owns AR end to end and loads no third-party viewer CDN. `/ar/view` (the page `/api/ar` redirects to) renders it in Google's `<model-viewer>` element with the same `ar ar-modes` attributes. Either way one page covers Quick Look, Scene Viewer, and WebXR. The **Place in your space** button appears only when the device exposes a usable AR mode (model-viewer's `canActivateAR`); on desktop the page shows a QR code handoff instead. `/api/ar` itself renders no 3D: it is a server-side router that either 302s into a Scene Viewer intent (plain Android) or serves a tiny Open-Graph interstitial that hands off to `/ar/view` (see [the launcher section](#one-tap-ar-for-any-glb--get-apiar--export_ar)).### Allow XR in iframes@@ -73,7 +73,7 @@ Without `xr-spatial-tracking`, the browser blocks `navigator.xr` inside the fram## Programmatic API-On pages that render the model with `<model-viewer>` (the avatar AR page at `/avatars/<id>/ar`, the `/ar/view` launch page, Forge results), AR is driven through model-viewer's API. This is exactly what [src/ar-page.js](../src/ar-page.js) does:+On pages that render the model with `<model-viewer>` (the `/ar/view` launch page, Forge results), AR is driven through model-viewer's API:```jsconst viewer = document.querySelector('model-viewer');@@ -91,6 +91,8 @@ viewer.addEventListener('ar-status', (e) => {});```+`<agent-3d>` matches that contract, which is what the avatar AR page ([src/ar-page.js](../src/ar-page.js)) relies on: the `ar`, `ar-modes`, `ar-placement` (`floor` or `wall`) and `ios-src` attributes, the `canActivateAR` getter and `activateAR()` method, and the `agent:ar-status` (`e.detail.message` progress text) and `agent:ar-ready` events. When no `ios-src` is given and `quick-look` is an allowed mode, the element bakes the USDZ on the device itself. The attribute list is in [specs/EMBED_SPEC.md](../specs/EMBED_SPEC.md).+For a custom viewer without model-viewer, use the three.ws launcher modules directly; see [Using AR without model-viewer](#using-ar-without-model-viewer) below.---@@ -131,7 +133,7 @@ The child `<img>` element is required: without it, Safari won't intercept a prog## Android Scene Viewer — deep dive-Scene Viewer is launched via an Android intent URL. `src/ar/scene-viewer.js` builds the URL:+Scene Viewer is launched via an Android intent URL. `src/ar/scene-viewer.js` builds the URL (pass `placement: 'wall'` to add `enable_vertical_placement=true` for models meant to hang on a wall; the default is floor):```jsfunction openSceneViewer(glbURL, { title = '', link = '' } = {}) {@@ -208,11 +210,11 @@ navigator.xr.isSessionSupported('immersive-ar')For avatars on three.ws, the USDZ is handled automatically:1. **Pre-generated USDZ:** If the avatar record has a `usdz_url`, it's set as `ios-src` immediately — no conversion needed.-2. **In-browser animated bake:** If not, the page downloads the GLB and bakes an *animated* USDZ via [src/usdz-animated.js](../src/usdz-animated.js) (`glbBlobToAnimatedUsdzBlob`): the avatar is driven through its idle clip, the skinned vertices are sampled at keyframes, and the samples are written into the USDA as time-sampled points that Quick Look loops natively. So a rigged avatar breathes and idles in your room instead of standing in a frozen pose. This runs inline (a dynamic import, not a Web Worker) and typically takes a few seconds depending on model complexity.+2. **In-browser animated bake:** If not, the page (via `<agent-3d>`, through `buildBestEffortArUsdz` in [src/usdz-animated.js](../src/usdz-animated.js)) downloads the GLB and bakes an *animated* USDZ via [src/usdz-animated.js](../src/usdz-animated.js) (`glbBlobToAnimatedUsdzBlob`): the avatar is driven through its idle clip, the skinned vertices are sampled at keyframes, and the samples are written into the USDA as time-sampled points that Quick Look loops natively. So a rigged avatar breathes and idles in your room instead of standing in a frozen pose. This runs inline (a dynamic import, not a Web Worker) and typically takes a few seconds depending on model complexity.3. **Static fallback:** Any bake failure (no rig, no usable clip) falls back to the plain `USDZExporter` path in [src/usdz-pipeline.js](../src/usdz-pipeline.js), which produces a static frame-0 pose. AR never regresses below static.4. **Persistent storage (opt-in):** The AR page's in-browser conversion lives only for that visit (an object URL). Durable USDZ companions come from `generateAndSaveCompanions()` in [src/account.js](../src/account.js), which bakes the animated USDZ, uploads it via `POST /api/avatars/presign-usdz`, and saves `usdz_url` on the avatar record so later AR visits skip the conversion. Companion generation is opt-in per save (`generateCompanions: true`; the `/demos/usdz-ar` demo page enables it) because the bake costs several seconds of client CPU.-The same animated bake serves the `/irl` Place-in-AR button and the `/avatars/:id/ar` page ([src/ar-page.js](../src/ar-page.js)).+The same animated bake serves the `/irl` Place-in-AR button and the `/avatars/:id/ar` page, where `<agent-3d>` runs it and [src/ar-page.js](../src/ar-page.js) only reflects its `agent:ar-status` progress.**USDZ limitations to know:**- Quick Look plays exactly one baked clip; the full animation library and live retargeting need WebXR@@ -462,7 +464,10 @@ How this link ships through ChatGPT end to end (the app connector, the custom GP## Put this AR studio on your own siteThe multi-model studio at [/ar/studio](/ar/studio) is published as a standalone open-source-package, so any site can embed the same thing:+package, so any site can embed the same thing. Its source lives in this repo at+[`packages/ar-studio`](../packages/ar-studio/README.md), mirrored one way to the repository below,+and the in-app WebXR session (`src/ar/webxr.js`) imports the package's anchor, occlusion and pinch+modules directly:```html<script type="module" src="https://unpkg.com/3d-ar-studio/dist/ar-studio.min.js"></script>diff --git a/docs/aws-builder-center-open-weight-3d-forge.md b/docs/aws-builder-center-open-weight-3d-forge.mdindex f0d4372d0..1df523435 100644--- a/docs/aws-builder-center-open-weight-3d-forge.md+++ b/docs/aws-builder-center-open-weight-3d-forge.md@@ -3,7 +3,7 @@ title: "Open-weight text-to-3D in production: lanes, failover, and the GPU workevenue: AWS Builder Centeraccount: three.ws (official organization account, byline "three.ws")status: draft, owner approval required before publishing (external-channel gate in CLAUDE.md)-description: "How a sentence becomes a textured GLB on three.ws: a reference picture first, then a reconstruction lane picked by a health-aware router over our own TRELLIS, Hunyuan3D and TripoSG GPU workers, three layers of failover when a worker dies mid-job, honest cold starts, weight staging that survives a RAM-backed /tmp, the meshopt files our own workers could not read, and the per-generation ledger that tells us what actually happened. Real code, real numbers, and the limits."+description: "How a sentence becomes a textured GLB on three.ws: a reference picture first, then a reconstruction lane picked by a health-aware router over our own TRELLIS.2, TRELLIS, Hunyuan3D, TripoSG and Modly GPU workers, three layers of failover when a worker dies mid-job, honest cold starts, weight staging that survives a RAM-backed /tmp, the meshopt files our own workers could not read, and the per-generation ledger that tells us what actually happened. Real code, real numbers, and the limits."tags: [machine-learning, generative-ai, gpu, open-source, 3d]index: docs/aws-builder-center.md---@@ -49,7 +49,7 @@ promptreference image ladder (Vertex Gemini, then FLUX lanes, then a keyless rung)| one centered subject, plain background, even lightv-health-aware lane router (our TRELLIS / Hunyuan3D / TripoSG workers, hosted rungs)+health-aware lane router (our TRELLIS.2 / TRELLIS / Hunyuan3D / Modly / TripoSG workers, hosted rungs)| submit; failover at submit time if the lane refusesvGPU worker (POST /infer -> 202, task state in Cloud Storage)@@ -62,9 +62,9 @@ A photo skips the first two boxes, because the photo is the reference. A sketch## 2. A picture comes before the shape-The open-weight reconstruction models we run (TRELLIS, Hunyuan3D 2.1, TripoSG) are image-conditioned: they read a picture, not a sentence. So a text prompt is first painted as a reference image, and the realism of the final mesh is set almost entirely by that one image. The module that builds it, [`api/_lib/forge-reference-image.js`](https://github.com/nirholas/three.ws/blob/main/api/_lib/forge-reference-image.js), asks for a single centered subject on a plain seamless studio background, soft shadowless light, and real-world materials, because that is what reconstructs into a mesh that looks real.+The open-weight reconstruction models we run (TRELLIS.2, TRELLIS, Hunyuan3D 2.1, TripoSG) are image-conditioned: they read a picture, not a sentence. So a text prompt is first painted as a reference image, and the realism of the final mesh is set almost entirely by that one image. The module that builds it, [`api/_lib/forge-reference-image.js`](https://github.com/nirholas/three.ws/blob/main/api/_lib/forge-reference-image.js), asks for a single centered subject on a plain seamless studio background, soft shadowless light, and real-world materials, because that is what reconstructs into a mesh that looks real.-The picture has its own failover ladder, and its most useful property is not the order of the rungs but the budget they share. Every lane is bounded on its own (90 seconds for Vertex, 60 for the hosted FLUX lane), but in August a stalled leading lane would burn its whole window, then the next lane would burn its own, and the caller's connection was gone before a 3D job even existed. The ladder now shares one budget (60 seconds by default), and a lane that still has a fallback behind it is capped so it hands off with real time to spare. From [`api/_mcp3d/text-to-image.js`](https://github.com/nirholas/three.ws/blob/main/api/_mcp3d/text-to-image.js):+The picture has its own failover ladder, and its most useful property is not the order of the rungs but the budget they share. Every lane is bounded on its own (90 seconds for Vertex, 60 for the hosted FLUX lane), but in August a stalled leading lane would burn its whole window, then the next lane would burn its own, and the caller's connection was gone before a 3D job even existed. The ladder now shares one budget (60 seconds by default), and a lane that still has a fallback behind it is capped so it hands off with real time to spare. Since 12 October a lane that answers with an auth or billing fault (401, 402 or 403: a dunning hold on Vertex, an exhausted credit balance on a Hugging Face-routed provider) is also parked for five minutes through the shared provider-health breaker, and both the text-to-image ladder and the reference-image builder share one Vertex cooldown key, so a known-dead rung stops re-paying its full timeout on every request. From [`api/_mcp3d/text-to-image.js`](https://github.com/nirholas/three.ws/blob/main/api/_mcp3d/text-to-image.js):```jsexport function laneTimeoutMs(ownCeilingMs, { budgetMs, remainingMs, laneRemains }) {@@ -95,22 +95,24 @@ The engines that matter here:| Lane id | What runs | Where ||---|---|---|+| `trellis2` | Microsoft TRELLIS.2 (4B, MIT), single-hop image to PBR GLB at 512, 1024 or 1536 resolution; the default image lane at every tier since 9 October | our Cloud Run worker (`workers/model-trellis2`), NVIDIA L4, max 2 instances, min 0 unless raised at deploy || `trellis_selfhost` | Microsoft TRELLIS (image-large), single-hop image to textured GLB | our Cloud Run worker, NVIDIA L4, min 1, max 3 instances || `hunyuan3d` | Tencent Hunyuan3D 2.1, shape DiT plus a PBR paint pass | our Cloud Run worker, NVIDIA RTX PRO 6000, min 1, max 1 |-| `triposg` | VAST TripoSG, geometry only, no textures | our Cloud Run worker, NVIDIA L4, scales to zero |+| `triposg` | VAST TripoSG, geometry only, no textures; the sketch lane | our Cloud Run worker, NVIDIA L4, scales to zero |+| `modly`, `modly_hunyuan` | one Modly worker serving TripoSG (`modly`) and Hunyuan3D 2 Mini Turbo (`modly_hunyuan`), both untextured geometry decimated to the tier's polygon budget | our Cloud Run worker (`workers/modly`) || `nvidia` | TRELLIS on NVIDIA's hosted inference, text only | hosted || `huggingface` | community Spaces chaining Hunyuan3D 2.1, Hunyuan3D 2, TRELLIS, TripoSR | hosted |-The instance counts are what `gcloud run services describe` returned on 8 October, not just what the build files request. Engines that need the caller's own API key also live in the registry, but the router never picks them; they run only when a user names one.+The instance counts for the Hunyuan3D, TRELLIS and TripoSG rows are what `gcloud run services describe` returned on 8 October, not just what the build files request; the TRELLIS.2 row is what its Cloud Build config sets. Engines that need the caller's own API key also live in the registry, and the router never picks them on a user's behalf; they run only when a user names one. The one exception is Tripo: when the house `TRIPO_API_KEY` is set it becomes the default geometry engine on the High tier, billed to our own credits, and a user's own key is still preferred.-The ordering is one function, `freeLaneCandidates`, and both the plain resolver and the health-aware resolver walk it, so they cannot drift apart. Draft and Standard name our TRELLIS worker; High names our Hunyuan3D worker; behind the named engine comes a fallback chain of `trellis_selfhost`, `hunyuan3d`, `huggingface`, `nvidia`. A photo filters out the text-only hosted lane. At the High tier a prompt that clearly reads as hard-surface (a robot, a vehicle, furniture) swaps TRELLIS ahead of Hunyuan3D, because single-hop reconstruction is crisper on mechanical shapes, while a prompt that trips both classifiers ("a knight in mecha armor") stays organic and keeps Hunyuan3D first. In production a flag, `FORGE_SELFHOST_PRIMARY`, hoists every self-hosted lane ahead of every hosted one, so requests are served on the GPUs we control before any external free allocation.+The ordering is one function, `freeLaneCandidates`, and both the plain resolver and the health-aware resolver walk it, so they cannot drift apart. As of 9 October every tier names our TRELLIS.2 worker (`FREE_DEFAULT_FOR_TIERS`; the tier picks its resolution, so High buys 1536 rather than a different engine). Behind it comes a fallback chain of `trellis_selfhost`, `hunyuan3d`, `huggingface`, `modly`, `modly_hunyuan`, `nvidia`. A photo filters out the text-only hosted lane. TRELLIS.2 leads because it is MIT licensed with no territory exclusion. Hunyuan3D 2.1 and 2.0 ship under Tencent's community license, which grants no rights in the European Union, the United Kingdom or South Korea, so [`api/_lib/forge-territory.js`](https://github.com/nirholas/three.ws/blob/main/api/_lib/forge-territory.js) drops every Tencent-model lane (`hunyuan3d`, `huggingface`, `modly_hunyuan`) from routing, failover, redispatch and suggestions for a request from those countries. The country comes from the edge geo header, never from a caller field, an unknown country fails closed, and an explicit pick of a Tencent lane from a restricted country answers `403 region_restricted`. A hard-surface reorder (a robot, a vehicle, furniture) that used to swap TRELLIS ahead of Hunyuan3D at the High tier still exists in `freeLaneCandidates`, but with TRELLIS ahead of Hunyuan3D by default it is now a no-op. In production a flag, `FORGE_SELFHOST_PRIMARY`, hoists every self-hosted lane ahead of every hosted one, so requests are served on the GPUs we control before any external free allocation.Then health tempers preference, never the reverse. From `forge-tiers.js`:```js-export function defaultBackendForHealthAware(p, tierId, userImages, health, subjectClass = null) {- const candidates = freeLaneCandidates(p, tierId, userImages, subjectClass);- if (!candidates.length) return DEFAULT_BACKEND_FOR_PATH[p];+export function defaultBackendForHealthAware(p, tierId, userImages, health, subjectClass = null, country = null) {+ const candidates = freeLaneCandidates(p, tierId, userImages, subjectClass, country);+ if (!candidates.length) return houseDefaultForPath(p, tierId) || DEFAULT_BACKEND_FOR_PATH[p];const statusOf = (id) => health?.[id];const preferred = candidates.find((id) => {const s = statusOf(id);@@ -119,11 +121,11 @@ export function defaultBackendForHealthAware(p, tierId, userImages, health, subjif (preferred) return preferred;const usable = candidates.find((id) => statusOf(id) !== 'down');if (usable) return usable;- return DEFAULT_BACKEND_FOR_PATH[p];+ return houseDefaultForPath(p, tierId) || DEFAULT_BACKEND_FOR_PATH[p];}```-Take the first lane that is healthy or simply unknown, because missing telemetry must never demote a preferred lane. Otherwise take the first that is not confirmed down, because a degraded lane beats a dead end. Only when every candidate is confirmed down, fall back to the standing default. The function is pure: the caller gathers a cached health snapshot and passes it in, and if gathering the snapshot throws, the request keeps the environment-resolved lane and behaves exactly as it did before health routing existed.+Take the first lane that is healthy or simply unknown, because missing telemetry must never demote a preferred lane. Otherwise take the first that is not confirmed down, because a degraded lane beats a dead end. Only when every candidate is confirmed down, fall back to a configured house-key lane, then the standing default. The function is pure: the caller gathers a cached health snapshot and passes it in, and if gathering the snapshot throws, the request keeps the environment-resolved lane and behaves exactly as it did before health routing existed.## 4. A health check has to read the right field@@ -155,10 +157,10 @@ export const MAX_FAILOVER_HOPS = 3;``````js-const ASYNC_REDISPATCH_ORDER = ['trellis_selfhost', 'hunyuan3d', 'trellis', 'triposg'];+const ASYNC_REDISPATCH_ORDER = ['trellis2', 'trellis_selfhost', 'hunyuan3d', 'trellis', 'modly', 'modly_hunyuan', 'triposg'];```-A job gets its first lane plus up to three backups. Only lanes with an asynchronous submit and status API qualify: Hugging Face Spaces block for the entire generation, and the hosted NVIDIA lane takes text only while a poll-time rescue always rebuilds from the stored picture, so neither can be a rescue rung. In production the third entry, a paid hosted TRELLIS lane, is not configured, so the live chain is our TRELLIS worker, our Hunyuan3D worker, then TripoSG. TripoSG closes it because it returns an untextured mesh: it runs only once every textured lane has failed or is marked down. It earned the slot during an outage from 18 to 28 September that took the Hunyuan3D and TRELLIS workers down together; without it, roughly 400 photo jobs a day ended in a hard failure while the TripoSG worker sat healthy.+A job gets its first lane plus up to three backups. Only lanes with an asynchronous submit and status API qualify: Hugging Face Spaces block for the entire generation, and the hosted NVIDIA lane takes text only while a poll-time rescue always rebuilds from the stored picture, so neither can be a rescue rung. In production the `trellis` entry, a paid hosted TRELLIS lane, is not configured, so the live chain is our TRELLIS.2 worker, our TRELLIS worker, our Hunyuan3D worker (skipped for requests from the EU, the UK and South Korea), then the untextured geometry lanes: Modly's TripoSG, Modly's Hunyuan3D Mini Turbo, and the TripoSG sketch worker. The geometry lanes close the chain because they return an untextured mesh: they run only once every textured lane has failed or is marked down. (The outage figures below predate TRELLIS.2 and the Modly lanes, when the chain was TRELLIS, Hunyuan3D, TripoSG.) It earned the slot during an outage from 18 to 28 September that took the Hunyuan3D and TRELLIS workers down together; without it, roughly 400 photo jobs a day ended in a hard failure while the TripoSG worker sat healthy.The one ordering decision we would defend hardest is in the poll handler, [`api/forge.js`](https://github.com/nirholas/three.ws/blob/main/api/forge.js): report "running" only after the successor is durably chaseable.@@ -176,7 +178,7 @@ If the Redis write fails, the handler falls through to a designed failure instea**Layer two: the failure names its own way out.** When no successor is possible (cap reached, no stored image, nothing configured), the failed response carries `retryable: true` and `retry_backends`: the ordered, configured lanes a fresh request could still use. The Forge page hops to the first one automatically, once per submission, and flips the engine picker so the switch is visible. If that also fails, it shows the remaining lanes as one-click switches.-**Layer three: nobody has to be watching.** A cron, [`api/cron/forge-finalize.js`](https://github.com/nirholas/three.ws/blob/main/api/cron/forge-finalize.js), runs every minute and sweeps rows still marked generating after two minutes. It polls the worker directly, materializes finished models with the same writer the browser path uses, applies the same poll-time failover, sends the completion notification (the attended path never notifies, because the result is already on screen), and after 45 minutes marks anything still unfinished as failed, so no row stays "generating" forever. Close the tab mid-generation and the model still lands in your gallery.+**Layer three: nobody has to be watching.** A cron, [`api/cron/forge-finalize.js`](https://github.com/nirholas/three.ws/blob/main/api/cron/forge-finalize.js), runs every minute and sweeps rows still marked generating after two minutes, in batches of 25 rows polled eight at a time so one slow backend cannot serialize the tick. It polls the worker directly, materializes finished models with the same writer the browser path uses, applies the same poll-time failover, sends the completion notification (the attended path never notifies, because the result is already on screen), and marks anything still unfinished after 45 minutes as failed, so no row stays "generating" forever. That reap is its own poll-free bulk `UPDATE` that runs ahead of the live-poll batch: when it lived inside the per-row sweep, a backlog of old rows from one slow lane filled every batch and newer rows from other lanes never reached the timeout check. The cron also feeds what it sees back into the submit path: a give-up on the free NVIDIA text lane trips the same cooldown breaker new submissions read, and a stuck text-to-3D job gets one resubmit before it is failed. Close the tab mid-generation and the model still lands in your gallery.Did it work? Over the same seven days: our TRELLIS worker finished 2,882 jobs and failed 96 attempts, and **93 of those 96 were finished on another lane**. Hunyuan3D finished 312 and failed 67, of which 49 were rescued. TripoSG, the last rung, finished 37 and failed 49, and only 5 of those were rescued, which is what a last rung looks like.@@ -238,7 +240,7 @@ The deploy is a plain `gcloud run deploy` inside a Cloud Build config. From [`wo- --timeout=900```-Each instance runs one inference at a time (`MAX_CONCURRENT=1`), so instance count is the concurrent-generation count, and task state lives in Cloud Storage so a job submitted to one instance resolves when polled on another.+Each instance runs one inference at a time (`MAX_CONCURRENT=1`), so instance count is the concurrent-generation count, and task state lives in Cloud Storage so a job submitted to one instance resolves when polled on another. The TRELLIS worker also restarts itself between jobs: glibc malloc arenas are capped at two, and once host RAM or, since 25 October, GPU memory has ratcheted toward its ceiling (nvdiffrast allocates VRAM outside torch's caching allocator, so it only ever shrinks) the instance drains, refuses new `/infer` calls with a 503 so the caller fails over, finishes queued jobs, and exits so Cloud Run starts a fresh one. That replaces a mid-job OOM kill with one extra model load.Two worker behaviours came out of one outage. On 2 September a single transient 403 during the TRELLIS model load was cached as the instance's permanent error. Every later task failed against it instantly, and `min-instances=1` kept that dead instance resident and in rotation for about 12 hours. The load is now retried with exponential backoff, and the error latches only once the whole budget is spent:@@ -287,11 +289,11 @@ Hunyuan3D 2.1 taught the second lesson. Its shape model is a single 6.9 GiB chec- --memory=80Gi```-That is [`workers/model-hunyuan3d/cloudbuild.hunyuan21rtx.yaml`](https://github.com/nirholas/three.ws/blob/main/workers/model-hunyuan3d/cloudbuild.hunyuan21rtx.yaml). The RTX PRO 6000 tier's platform minimum is 20 CPU and 80 GiB of memory, which clears the ceiling with room to spare. The second fix is the image: Blackwell is compute capability 12.0, and the CUDA 12.4 wheels in the L4 image ship no kernels for it, so the RTX image is built on CUDA 12.8 with its extensions compiled for both 8.9 and 12.0. The same image boots on either GPU, so which card runs it is a deploy flag, not a rebuild. The cost of that choice is build time: a cold build compiles torch extensions for two architectures, and the config allows two hours.+That is [`workers/model-hunyuan3d/cloudbuild.hunyuan21rtx.yaml`](https://github.com/nirholas/three.ws/blob/main/workers/model-hunyuan3d/cloudbuild.hunyuan21rtx.yaml). The RTX PRO 6000 tier's platform minimum is 20 CPU and 80 GiB of memory, which clears the ceiling with room to spare. The second fix is the image: Blackwell is compute capability 12.0, and the CUDA 12.4 wheels in the L4 image ship no kernels for it, so the RTX image is built on CUDA 12.8 with its extensions compiled for both 8.9 and 12.0. The same image boots on either GPU, so which card runs it is a deploy flag, not a rebuild. The cost of that choice is build time: a cold build compiles torch extensions for two architectures, and the config allows two hours. The deploy step is not a plain rolling update either: the one-GPU RTX quota is held by the serving revision, so a new revision's instance can never start. The config scales the service to zero to release the GPU, deploys, then restores autoscaling (also when the deploy fails, which hands the GPU back to the previous revision), at the price of the lane being down for one model load.Two smaller habits: pull the previous image before building so `--cache-from` has layers to reuse, and keep the previous model generation deployed. Hunyuan3D 2.0 still runs as its own service, so rolling back is repointing one environment variable.-**On licenses.** "Open-weight" is not one license. TRELLIS, TripoSG and TripoSR are MIT. Hunyuan3D 2.1 ships under Tencent's own license agreement, which carries its own terms; each worker's README records the license of the model it wraps, and we would tell any team to read those terms before choosing which model leads a lane.+**On licenses.** "Open-weight" is not one license. TRELLIS, TripoSG and TripoSR are MIT. Hunyuan3D 2.1 ships under Tencent's own license agreement, which carries its own terms, including a territory clause that excludes the European Union, the United Kingdom and South Korea (which is why TRELLIS.2 is the default lane and section 3 filters Hunyuan lanes by country); each worker's README records the license of the model it wraps, and we would tell any team to read those terms before choosing which model leads a lane.## 10. Every generation is a row@@ -359,11 +361,11 @@ ARG GLTFPACK_VERSION=v1.2ARG GLTFPACK_SHA256=ebc236f5f6c08c7e5c5750476a187d24805d44d8c680449c4b7369c333f817b1```-The image build then runs the meshopt unit test, so a broken decoder fails the build instead of a user's job. The five workers that load caller-supplied meshes all pin the same version and checksum.+The image build then runs the meshopt unit test, so a broken decoder fails the build instead of a user's job. Every worker that loads caller-supplied meshes pins the same version and checksum.## 12. Vendored code, and the check that keeps it honest-Each worker's Docker build context is its own directory, so `../` is unreachable and a shared Python module cannot simply be imported. We vendor instead: shared modules live as byte-identical copies in every worker that needs them. Today that is `worker_security.py` (the SSRF-safe fetch and bearer check, in 17 workers) and `gltf_meshopt.py` with its test (5 workers each). Two upload helpers are on the list too, ready for the day a second worker needs them.+Each worker's Docker build context is its own directory, so `../` is unreachable and a shared Python module cannot simply be imported. We vendor instead: shared modules live as byte-identical copies in every worker that needs them. Today that is `worker_security.py` (the SSRF-safe fetch and bearer check, in 27 workers) and `gltf_meshopt.py` with its test (8 workers each). Two upload helpers are on the list too, ready for the day a second worker needs them.Copies drift. A fix applied to one copy silently leaves the others on the old behaviour, which this repository has already paid for once. So [`scripts/check-vendored-workers.mjs`](https://github.com/nirholas/three.ws/blob/main/scripts/check-vendored-workers.mjs) hashes every copy, treats the most common hash as canonical, and fails naming each drifted file and the exact `cp` to resync it:diff --git a/docs/ibm-community-long-running-mcp-tools-post.md b/docs/ibm-community-long-running-mcp-tools-post.mdindex bf27095e3..a4da680e6 100644--- a/docs/ibm-community-long-running-mcp-tools-post.md+++ b/docs/ibm-community-long-running-mcp-tools-post.md@@ -101,6 +101,7 @@ curl -s https://three.ws/api/mcp-studio \"capabilities": {"tools": { "listChanged": false },"resources": { "listChanged": false, "subscribe": false },+ "prompts": { "listChanged": false },"logging": {}},"instructions": "three.ws 3D Studio turns a text prompt or an image into an interactive, downloadable 3D model (GLB), free. ... If a result comes back with status \"pending\", the model is still rendering: call check_job(job_id) after the suggested wait to collect it. Before generating a prop, character or animation, search_catalog(q) checks the thousands of ready-made CC0 props, rigged characters and motion clips three.ws already publishes ..."@@ -108,9 +109,9 @@ curl -s https://three.ws/api/mcp-studio \}```-(Trimmed: `instructions` is one paragraph covering every tool.) The server teaches the long-running contract before the model has called anything: if you see `pending`, call `check_job` later.+(Trimmed: `instructions` is one paragraph covering every tool. The `initialize` capture and the examples in sections 3 to 10 were taken on 2026-10-08; the server has since added `prompts`, which the capture above now shows.) The server teaches the long-running contract before the model has called anything: if you see `pending`, call `check_job` later.-`tools/list` returns fourteen tools, in about 130 ms in our measurements:+`tools/list` returns sixteen tools, in about 100 ms in our measurements (an early capture, taken on 2026-10-08, listed fourteen; `get_job` and `search_docs` arrived after it):```bashcurl -s https://three.ws/api/mcp-studio \@@ -121,13 +122,13 @@ curl -s https://three.ws/api/mcp-studio \```json["forge_free", "text_to_avatar", "mesh_forge", "rig_mesh", "forge_avatar",- "refine_model", "check_job", "look_at_model",- "search_catalog", "get_catalog_item", "get_item_source",+ "refine_model", "check_job", "look_at_model", "get_job",+ "search_catalog", "get_catalog_item", "get_item_source", "search_docs","create_agent_persona", "get_agent_persona", "persona_say"]```-Six generators, a collector (`check_job`), an inspector (`look_at_model`), three catalog reads, and three persona tools. A second front door, `https://three.ws/api/mcp-chatgpt`, serves the same handler with only the eight 3D tools, for the ChatGPT app listing:+Six generators, a collector (`check_job`), an inspector (`look_at_model`), a job status tool for unattended agents (`get_job`, see below), three catalog reads, a documentation search (`search_docs`), and three persona tools. A second front door, `https://three.ws/api/mcp-chatgpt`, serves the same handler with only the eight 3D tools, for the ChatGPT app listing:```bashcurl -s https://three.ws/api/mcp-chatgpt \@@ -139,16 +140,18 @@ curl -s https://three.ws/api/mcp-chatgpt \["forge_free","text_to_avatar","mesh_forge","rig_mesh","forge_avatar","refine_model","check_job","look_at_model"]```-Both doors are rows in one `SURFACES` table in [`api/_mcp-studio/dispatch.js`](https://github.com/nirholas/three.ws/blob/main/api/_mcp-studio/dispatch.js), each naming its catalog, widgets, model instructions and, for ChatGPT only, a call budget:+The doors are rows in one `SURFACES` table in [`api/_mcp-studio/dispatch.js`](https://github.com/nirholas/three.ws/blob/main/api/_mcp-studio/dispatch.js), each naming its catalog, model instructions and, for hosts with a hard clock, a call budget. The listing below is condensed to the two doors this post uses; the table now has a third row for the Grok connector, with its own budget and sign-in:```jsconst SURFACES = {full: {server: 'mcp-studio',- catalog: [...TOOL_CATALOG, ...CATALOG_TOOL_CATALOG, ...PERSONA_TOOL_CATALOG],- tools: { ...TOOLS, ...CATALOG_TOOLS, ...PERSONA_TOOLS },+ catalog: [...TOOL_CATALOG, ...JOB_TOOL_CATALOG, ...CATALOG_TOOL_CATALOG, ...PERSONA_TOOL_CATALOG],+ tools: { ...TOOLS, ...JOB_TOOLS, ...CATALOG_TOOLS, ...PERSONA_TOOLS },personas: true,- instructions: [...BASE_INSTRUCTIONS, ...CATALOG_INSTRUCTIONS, ...PERSONA_INSTRUCTIONS].join(' '),+ prompts: true,+ jobTool: 'get_job',+ instructions: [...BASE_INSTRUCTIONS, ...JOB_INSTRUCTIONS, ...CATALOG_INSTRUCTIONS, ...PERSONA_INSTRUCTIONS].join(' '),},chatgpt: {server: 'mcp-chatgpt',@@ -359,6 +362,8 @@ if (ticket) return { status: 'submitting', job_id: ticketHandle(ticket) };If you take one idea from this post, take this one: **any tool that starts asynchronous work should be able to name that work before it finishes starting it.** It is an idempotency key applied to the start of a long job: the client chooses the identifier, so a lost response never means a lost job, and a retry finds the same work instead of creating a second copy.+**The client-named variant shipped next.** The ticket is minted by our own client for our own submit. An agent that retries a timed-out call needs the same property one level up, so every generation tool now takes an optional `idempotency_key` (any string up to 200 characters). The first call with a key runs; a later call from the same caller with the same key within 24 hours gets that first job back, still running or finished, instead of starting a second one and spending a second slot of the shared free quota. A key reused with different arguments is refused rather than guessed at. The same release added `get_job`, a status tool for agents that run unattended (it answers from the same code as `check_job`, never starts or repeats a generation, and returns `status`, `phase`, `progress` and `eta_seconds` in one stable shape), and `notifications/progress` events for clients that send a `progressToken` and accept an event stream. Details are in the [3D Studio MCP server documentation](https://three.ws/docs/mcp-studio?utm_source=ibm-community). Each generation also now carries a signed run receipt that records what each stage was expected to do and what it did, with the cause whenever a fallback carried a stage.+The same commit fixed a failure that is easy to miss: provider **billing notices** accepted as output. The prompt director rewrites a short prompt into a fuller brief, and a provider's "raise your key budget at https://..." reply was being forwarded as the brief, which, the code comment records, "is how 22 production generations came out of a billing message." The validator now rejects any rewrite containing a link, any that does not end as a finished sentence, and any no longer than what the user typed, and falls back to the user's own words. **Treat upstream text as untrusted until it passes a shape check, especially text that becomes the input to an expensive job.**---@@ -476,7 +481,7 @@ What keeps this true is mechanical verification. `npm run audit:mcp-safety` parsMCP servers have two more primitives, **resources** and **prompts**, and both are underused. Resources let a client read state without a tool call; prompts let a server ship a whole workflow as a menu item.-The free studio uses resources only for its widgets and lists no prompts. The four account-facing three.ws servers (the main server at `/api/mcp` and three siblings) use both since 2026-09-22, in the changelog's words: "Claude and other AI clients can now read your three.ws account and follow guided flows." The design, in [`api/_mcp/resources.js`](https://github.com/nirholas/three.ws/blob/main/api/_mcp/resources.js) and [`api/_mcp/prompts.js`](https://github.com/nirholas/three.ws/blob/main/api/_mcp/prompts.js), has decisions worth copying.+The free studio uses resources only for its widgets and lists four prompts, written for unattended agents (`agent-get-started`, `daily-3d-brief`, `asset-pack`, `avatar-from-photo`); the ChatGPT listing serves none. The four account-facing three.ws servers (the main server at `/api/mcp` and three siblings) use both since 2026-09-22, in the changelog's words: "Claude and other AI clients can now read your three.ws account and follow guided flows." The design, in [`api/_mcp/resources.js`](https://github.com/nirholas/three.ws/blob/main/api/_mcp/resources.js) and [`api/_mcp/prompts.js`](https://github.com/nirholas/three.ws/blob/main/api/_mcp/prompts.js), has decisions worth copying.**Resources are live, read-only views under a URI scheme:** `three://me` (your account and quota), `three://agents` (the agents you own), `three://models` (every model an agent can think on). Each declares one access rule (public, any signed-in user, or a list of scopes) and reads the same tables as the REST route behind the dashboard, "so a resource can never disagree with the dashboard." An anonymous `resources/list` returns only the public ones, three today.@@ -495,7 +500,7 @@ curl -s https://three.ws/api/mcp -H 'content-type: application/json' \**A fallback for clients without a resource reader:** every resource is also reachable through a `read_resource` tool on the same server. Host support for resources is uneven; the data should not be.-**Prompts are rendered against the live tool catalog,** never a hand-kept list. A prompt is listed only where every tool it needs exists; each tool name passes through a function that throws if the server does not publish it; a test renders every prompt on every server against `tools/list`; confirmation flags are read from each tool's own `inputSchema`. The main server lists fourteen, among them `get-started`, `create-agent`, `hire-agent`, `review-costs` and `embed-avatar`.+**Prompts are rendered against the live tool catalog,** never a hand-kept list. A prompt is listed only where every tool it needs exists; each tool name passes through a function that throws if the server does not publish it; a test renders every prompt on every server against `tools/list`; confirmation flags are read from each tool's own `inputSchema`. The main server lists sixteen, among them `get-started`, `create-agent`, `review-costs`, `embed-avatar` and `agent-get-started`.**Prices in metadata must be real.** `three://models` is what an assistant reads to compare model costs. On 2026-09-25 we fixed it so free models read `[0, 0]` rather than `null`, and a key that routes to another model is priced at the model that answers. The concrete case was IBM's: our `ibm-granite` key names no priced model itself, so it read `null`. Live today:@@ -863,7 +868,7 @@ What the toy leaves out, and production needs:All of this runs with no account, key, or payment:```bash-# discover the server and its fourteen tools+# discover the server and its sixteen toolscurl -s https://three.ws/api/mcp-studio -H 'content-type: application/json' \-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq '[.result.tools[].name]'diff --git a/docs/ops/search-indexing.md b/docs/ops/search-indexing.mdindex 95b1fe814..65f3a749f 100644--- a/docs/ops/search-indexing.md+++ b/docs/ops/search-indexing.md@@ -16,11 +16,11 @@ Every public URL falls into one of these, and the failure modes are different:title, description, canonical, OG/Twitter tags and JSON-LD from`data/pages.json`, so the meta a crawler reads matches the catalog. Run itwith `--write` after adding a page; it never overwrites a tag a page already- has. The `/` entry resolves to `pages/desktop.html` (the web desktop home;- the previous homepage lives at `/classic`). `npm run audit:pages` fails on a- path listed twice in `data/pages.json` even when the rows carry different- copy, because each row would submit the same URL to the sitemap again, and a- page whose own meta says `noindex` does not belong in the manifest at all.+ has. The `/` entry resolves to `pages/desktop.html` (the web desktop home).+ `npm run audit:pages` fails on a path listed twice in `data/pages.json` even+ when the rows carry different copy, because each row would submit the same+ URL to the sitemap again, and a page whose own meta says `noindex` does not+ belong in the manifest at all.2. **A server-rendered page** (`api/*-og.js`, `api/news/story-page.js`). Thehandler composes the document per request from the database.diff --git a/docs/oracle.md b/docs/oracle.mdindex c7d49c530..eefe71da4 100644--- a/docs/oracle.md+++ b/docs/oracle.md@@ -187,7 +187,7 @@ Every action, simulated or live, streams to the trading floor at three.ws/activiA score you cannot audit is an opinion. Oracle grades itself in public, and the grading is mechanical.-**Outcome grading.** Once the data brain labels a coin's ground truth (graduated, rugged, ATH multiple), every agent action on that coin is settled: did the conviction call pay off, what was the peak multiple, what was the realized PnL. A scored coin is a win if it graduated, or reached a 2 times or greater ATH multiple without rugging and without marking below half of entry; a loss if it rugged, marked below 0.5 times, or peaked below 1.2 times — loss conditions outrank a peak-based win, because a 2× wick on a position that then went to zero was exit liquidity, not a win; flat in between. Realized PnL is marked to market as `size · (current_mc / entry_mc − 1)`. This turns the action ledger into an honest win-rate record.+**Outcome grading.** Once the data brain labels a coin's ground truth (graduated, rugged, ATH multiple), every agent action on that coin is settled: did the conviction call pay off, what was the peak multiple, what was the realized PnL. A scored coin is a win if it graduated, or reached a 2 times or greater ATH multiple without rugging and without marking below half of entry; a loss if it rugged, marked below 0.5 times, or peaked below 1.2 times. Loss conditions outrank a peak-based win, because a 2× wick on a position that then went to zero was exit liquidity, not a win; flat in between. Realized PnL is marked to market as `size · (current_mc / entry_mc − 1)`. This turns the action ledger into an honest win-rate record.**Two questions, never conflated.** Grading has to say which question it answers, because there are two and they have different answers. The **trained event** (`PREDICTED_EVENT` in `api/_lib/oracle/conviction.js`) is what the score head was fitted on and what the score claims. Under v3 that is id `runs_and_holds`: the coin graduates or peaks at 3x or more, AND is still worth at least what it cost at first sight, so a coin that spiked 3x and then collapsed is not a hit. (A v2 document scores on id `spike_or_graduate`, where a later collapse does not undo a hit; the engine normalises either model shape and reports which event it is predicting.) The **holder-honest win** is the rug-aware definition in the paragraph above, judged on realized production outcomes rather than the training label, and it is the right number for someone actually holding. Every surface that shows a realized rate now states which of the two it is, and the backtest ships both side by side. Presenting one as the other is what made a working engine read as a broken one.@@ -206,7 +206,7 @@ That rule is the whole Oracle read surface, not one endpoint. `/api/oracle/feed`**A third question: what the fleet actually banked.** `/api/cron/oracle-calibrate` (Cloud Scheduler) joins conviction to the fleet's *realized PnL* on mints it really traded, buckets by conviction band, and writes `oracle_calibration`. A win here is a positive realized PnL on a real fill, which is neither the trained event nor the site's rug-aware win: exit timing belongs to the fleet, so a gap between this table and `/api/oracle/backtest` is expected rather than a bug. Each band carries a bounded `correction_factor` (observed over claimed, clamped to 0.7-1.3, and pinned at 1.0 until the band has enough real trades). That factor is deliberately **not** written back onto the canonical `oracle_conviction` score: the calibration is measured against that score, so mutating it would feed into its own measurement and oscillate. It is exposed at `GET /api/oracle/calibration` and applied where it belongs, in the sniper optimizer's Rule O, which tunes each arm's entry threshold toward the band that realized wins.-**The wins gallery** at `/api/oracle/wins` shows proven calls filtered by period, tier, and minimum ATH multiple. It defaults to called tiers only (Lean, Strong, Prime) — a Watch or Avoid coin that mooned is market context, not proof of edge; pass `tier=all` to browse everything scored.+**The wins gallery** at `/api/oracle/wins` shows proven calls filtered by period, tier, and minimum ATH multiple. It defaults to called tiers only (Lean, Strong, Prime). A Watch or Avoid coin that mooned is market context, not proof of edge; pass `tier=all` to browse everything scored.**The leaderboard** at `/api/oracle/leaderboard` ranks agents by conviction win rate across their full action ledger, with a minimum resolved-action floor so one-trade wonders cannot dominate.@@ -316,7 +316,7 @@ GET https://three.ws/api/oracle/trades?mint=<mint>- Realized calibration per conviction band at `/api/oracle/calibration`: the fleet's actual win rate from real fills, next to what the band predicted, plus the bounded correction factor the scorer applies.- A dynamic 1200x630 OpenGraph conviction card (SVG) for sharing a coin at `/api/oracle/og`. Its live market cap reads pump.fun first (with one retry, honouring `Retry-After`) and falls through to the shared multi-source market reader (Birdeye, DexScreener, GeckoTerminal) when pump.fun does not answer.-The write endpoints. Three need a signed-in caller: `GET·POST /api/oracle/watch` reads or arms an agent's watch config with server-side validation clamping every limit, and `POST /api/oracle/test-alert` sends a test alert. The clamps only ever move a number toward safety: a size above the ceiling is lowered, but arming `mode: "live"` with a `per_trade_sol` under the 0.001 SOL floor, or a `max_daily_sol` smaller than one trade, is a 400 rather than a silent round-up into real spending. Moving a mainnet watch into live-armed also requires the account's signed real-funds agreements (Terms of Service, Risk Disclosure, Agent Wallet Agreement); without them the arm is refused with a 403 that links to `/legal/agreements` (see [Risk acknowledgment](risk-acknowledgment.md)). Re-saving an already live-armed watch, simulate mode, devnet, and disarming are not gated. Simulate runs keep the forgiving clamps. `POST·DELETE /api/oracle/follow` (and the `GET` that reports whether a chat follows an agent) subscribes a Telegram chat to an agent's signals; it needs a session or bearer token, and `chat_id` must equal the chat of the caller's linked Telegram identity (401 when signed out, 403 otherwise), since a caller-supplied chat id alone proves nothing. `GET /api/oracle/telegram-chat` reads that verified chat. One is public and IP rate-limited instead: `POST /api/oracle/social` ingests tweets to additively boost virality (never downgrades an LLM read). The `oracle-social-ingest` cron (every 10 minutes) feeds it: it reads the timelines of tracked KOL handles through the keyless guest reader ([api/_lib/x-guest/](../api/_lib/x-guest/README.md)), keeps tweets with a cashtag from the last 24h, and POSTs them. Separately, each scored coin's own linked X account contributes `social.xAccount` (handle, age in days, followers) to the intel; this is a context feature and is not an input to the fitted model until a refit includes it.+The write endpoints. `GET·POST /api/oracle/watch` reads or arms an agent's watch config with server-side validation clamping every limit, and `POST /api/oracle/test-alert` sends a test alert (both are scoped to the agent's owner; the test alert also only goes to the caller's verified Telegram chat). The clamps only ever move a number toward safety: a size above the ceiling is lowered, but arming `mode: "live"` with a `per_trade_sol` under the 0.001 SOL floor, or a `max_daily_sol` smaller than one trade, is a 400 rather than a silent round-up into real spending. Moving a mainnet watch into live-armed also requires the account's signed real-funds agreements (Terms of Service, Risk Disclosure, Agent Wallet Agreement); without them the arm is refused with a 403 that links to `/legal/agreements` (see [Risk acknowledgment](risk-acknowledgment.md)). Re-saving an already live-armed watch, simulate mode, devnet, and disarming are not gated. Simulate runs keep the forgiving clamps. `POST·DELETE /api/oracle/follow` (and the `GET` that reports whether a chat follows an agent) subscribes a Telegram chat to an agent's signals; it needs a session or bearer token, and `chat_id` must equal the chat of the caller's linked Telegram identity (401 when signed out, 403 otherwise), since a caller-supplied chat id alone proves nothing. `GET /api/oracle/telegram-chat` reads that verified chat. `POST /api/oracle/social` is public and IP rate-limited instead: it ingests tweets to additively boost virality (never downgrades an LLM read). The `oracle-social-ingest` cron (every 10 minutes) feeds it: it reads the timelines of tracked KOL handles through the keyless guest reader ([api/_lib/x-guest/](../api/_lib/x-guest/README.md)), keeps tweets with a cashtag from the last 24h, and POSTs them. Separately, each scored coin's own linked X account contributes `social.xAccount` (handle, age in days, followers) to the intel; this is a context feature and is not an input to the fitted model until a refit includes it.### Through MCPdiff --git a/docs/paired-coins.md b/docs/paired-coins.mdindex ef5912d31..87d38ad25 100644--- a/docs/paired-coins.md+++ b/docs/paired-coins.md@@ -118,7 +118,7 @@ trading: buys and sells only check that the pool exists.| --- | --- || [/markets/robinhood/paired](https://three.ws/markets/robinhood/paired) | Every paired coin, newest first (24 per page, with a load-more button), each with its pool split, dollar market cap and the agent that launched it. Below it, every market a coin can pair with, filterable by class and searchable by ticker, name or contract address. || `/markets/robinhood/paired/:address` | One coin: each pool priced in its own asset and in dollars, a candle chart per pool (`1m` to `1d`), the latest trades refreshed every 15 seconds while the tab is visible, the verified descriptor, and a trade ticket. |-| [/launch/paired](https://three.ws/launch/paired) | An owner picks one of their agents, up to five markets, the weights (even split by default) and an optional opening buy. Every change is re-quoted live, a confirmation dialog shows the quoted cost before anything is signed, and the result links the new coin. |+| [/launch/paired](https://three.ws/launch/paired) | A lane picker to switch to the other launch lanes, then an owner picks one of their agents, up to five markets, the weights (even split by default) and an optional opening buy. Every change is re-quoted live, a confirmation dialog shows the quoted cost before anything is signed, and the result links the new coin. |The trade ticket on a coin page runs entirely in the visitor's own wallet. It prices the tradewith the launchpad's own `quoteBuy` / `quoteSell` at the curve's current point, sets the minimum@@ -313,13 +313,15 @@ a coin on the launchpad answers `404 not_found`.### Agent launch and feesThese act for one of your agents and sign with its custodial EVM wallet. Authenticate with the-owner's session (from the browser, same origin) or with an API key allowed to spend:-`Authorization: Bearer <key>`. A cross-site request riding the session cookie is refused.+owner's session (from the browser, same origin) or with an API key or OAuth token that holds+`wallet:launch` (`wallet:write` implies it): `Authorization: Bearer <key>`. A cross-site request+riding the session cookie is refused.| Endpoint | Does || --- | --- || `POST /api/agents/:id/paired/quote` | Prices the launch and checks policy and funding. Signs nothing. |-| `POST /api/agents/:id/paired/launch` | Sends the launch the quote priced. Answers `201` once it is mined. |+| `POST /api/agents/:id/paired/launch` | Sends the launch the quote priced. Answers `201` once it is mined, `202` while it is still in flight. |+| `GET /api/launches/:id` | The launch record behind a `launch`: its stages, transaction, coin address and result. Owner only. || `GET /api/agents/:id/paired/fees` | Swap fees the agent's wallet can claim now, per quote asset. || `POST /api/agents/:id/paired/claim` | Claims every one of them in one transaction, into the agent's wallet. |@@ -410,6 +412,15 @@ Requires the real-funds agreements to be signed. Re-runs every check, stores thethe approval (only when the opening buy needs one) and the launch, and answers `201` once thelaunch is mined.+Send an `Idempotency-Key` header (8 to 128 printable ASCII characters, scoped to your account).+Every launch runs under a launch record, returned in a `Location: /api/launches/:id` header. A+retry with the same key and body returns the same launch (`200` with `idempotent-replay: true`+once it finished, `202` while it is in flight) instead of launching twice; the same key with a different body is `422 idempotency_key_reused`. If+the request goes away before the receipt arrives, the response is `202` with `{ launch_id, status,+launch }`, and `GET /api/launches/:id` finishes and reports the launch once the transaction lands.+A launch that failed answers `409` with the failure's code and the record in `launch`; retrying needs a new key. The shared+mechanics are in [launch lanes](launch-lanes.md#idempotency-and-status).+```json{"data": {@@ -425,6 +436,8 @@ launch is mined.{ "quote_token": "0x117cc2133c37B721F49dE2A7a74833232B3B4C0C", "symbol": "SPY", "weight_pct": 20 }],"tx_hash": "0x…",+ "launch_id": "…",+ "launch": { "id": "…", "lane": "paired", "status": "finalized", "stages": ["…"] },"block": "…","gas_used": "…","spent_eth": "…",@@ -468,12 +481,14 @@ Errors use the standard `{ "error", "error_description" }` shape.| 400 | `bad_request` | The request is well formed but cannot be launched: an unknown or ambiguous market, a repeated market, weights that do not total 100, a ticker under two characters, a non-https link, a logo that is not an image. The message says which. || 401 | `unauthorized` | No session and no API key. || 403 | `forbidden` | Not your agent, or a cross-site request. |-| 403 | `insufficient_scope` | The API key lacks `wallet:write`, which every POST here needs. |-| 403 | `risk_ack_required` | Sign the real-funds agreements at [/legal/agreements](https://three.ws/legal/agreements) first. |+| 403 | `insufficient_scope` | The API key or token lacks `wallet:launch` (or `wallet:write`), which every POST here needs. |+| 403 | `risk_ack_required` | On `launch`: sign the real-funds agreements at [/legal/agreements](https://three.ws/legal/agreements) first. || 404 | `not_found` | Unknown agent, or an unknown action. || 409 | `launch_blocked` | The wallet cannot cover the launch. `detail.blockers` says what is missing. || 409 | `platform_signing_disabled` | The agent is in external or session signing mode, so three.ws will not sign for it. || 409 | `nothing_to_claim`, `needs_gas` | No fees have accrued yet, or the wallet cannot pay the claim's gas. |+| 400 | `invalid_idempotency_key` | The `Idempotency-Key` header is not 8 to 128 printable ASCII characters. |+| 422 | `idempotency_key_reused` | That key already launched a different coin. `detail.launch_id` names the original. || 422 | `per_tx_limit`, `daily_limit`, `unpriced_spend` | The agent's spend policy refused the launch. || 422 | `bad_request` | The launchpad would revert this exact launch. The message carries the reason. || 422 | `simulation_failed` | The claim would revert. |@@ -528,9 +543,9 @@ audit trail are identical on both surfaces.| `paired_coins` | read | read-only | none || `paired_coin` | read | read-only | none || `paired_launch_quote` | write | not read-only, not destructive | `wallet:read` |-| `paired_launch` | financial | destructive (moves money) | `wallet:write` |+| `paired_launch` | financial | destructive (moves money) | `wallet:launch` || `paired_fees` | read | read-only | `wallet:read` |-| `paired_claim_fees` | write | destructive (moves money) | `wallet:write` |+| `paired_claim_fees` | write | destructive (moves money) | `wallet:launch` |The three reads are public on-chain state and are served to anonymous plain JSON-RPC callers:@@ -549,7 +564,8 @@ curl -s -X POST https://three.ws/api/mcp \call is refused unless it carries `confirm_launch: true` and a fresh preview id. The preview id isissued on the `paired_launch_quote` result (in a text note and in`_meta["three.ws/preview"].quote_id`) and is valid for 10 minutes, for the same caller only. Pass it-to `paired_launch` as `quote_id`. The policy binds every launch argument (`agent_id`, `markets`, `weights`,+to `paired_launch` as `quote_id`, with an `idempotency_key` so a retry returns the same launch+rather than a second one; `launch_status` (from the launch tools) reads the record back. The policy binds every launch argument (`agent_id`, `markets`, `weights`,`name`, `symbol`, `description`, `image_url`, `socials`, `dev_buy`), so a launch that differs fromwhat was quoted is refused with `preview_mismatch`. Only send `confirm_launch: true` after theowner approved the quote.diff --git a/docs/pumpfun-program/UPSTREAM-pumpswap-virtual-quote-reserves.md b/docs/pumpfun-program/UPSTREAM-pumpswap-virtual-quote-reserves.mdindex 877a20113..2697f89fd 100644--- a/docs/pumpfun-program/UPSTREAM-pumpswap-virtual-quote-reserves.md+++ b/docs/pumpfun-program/UPSTREAM-pumpswap-virtual-quote-reserves.md@@ -189,8 +189,8 @@ normally against the reduced reserve.| | ||---|---|-| TypeScript SDK (PumpSwap) | `@pump-fun/pump-swap-sdk`, pinned in `package.json`; the field landed in 1.19.0 |-| TypeScript SDK (bonding curve) | `@pump-fun/pump-sdk`, on the 2.x line since 2026-09-14 |+| TypeScript SDK (PumpSwap) | `@pump-fun/pump-swap-sdk`, pinned in `package.json` (2.x); the field landed in 1.19.0 |+| TypeScript SDK (bonding curve) | `@pump-fun/pump-sdk`, pinned in `package.json`; on the 4.x line since 2026-10-09 || Rust SDK | `[email protected]` || IDL | `contracts/idl/pump/pump_amm.json`, refreshed via `npm run pump:refresh-idls` |diff --git a/docs/ux-flows/07-crypto-trading-analytics.md b/docs/ux-flows/07-crypto-trading-analytics.mdindex 4b807606d..cd3dceed9 100644--- a/docs/ux-flows/07-crypto-trading-analytics.md+++ b/docs/ux-flows/07-crypto-trading-analytics.md@@ -23,10 +23,10 @@ coin-intel, pump-visualizer and pump-live: adding a coin on any surface shows up5. (optional) Switch view tab: `movers`, `wallets` (reputation leaderboard), `edge` (tier backtest win-rate; the hero names the specific bands that invert the ladder instead of claiming calibration, states the fitted event's own hit rate (a 3x run or graduation) beside the stricter clean-win rate, and each calibration row shows "claims N%" next to the realized bar, with "n/a" for an unmeasured band), `proof` (resolved wins), `agents` (agent win-rate ledger), `activity` (live agent actions), `graph` (3D force graph, lazy-imports oracle-graph.js).6. (optional) Click a coin card → `openDrawer(mint)` → `GET /api/oracle/coin?mint=...` renders the 4-pillar conviction breakdown (who/how/what/move); oracle-tape.js streams that coin's live trades.7. (optional) In the drawer: Full page ↗ (`/oracle/coin/<mint>`), pump.fun ↗, GMGN ↗ (via `src/shared/trading-terminals.js`, referral-tagged), solscan ↗, Details ↗ (`/launches/<mint>`), View in 3D ↗ (`/coin3d?mint=`), ☆/★ Watch (writes `ld_watchlist`), Copy mint, Copy link, Share to X; the live Market panel adds GMGN/DEXTools/DexScreener/GeckoTerminal/Birdeye links when available. A DEXTools link that knows only the mint goes through the counted redirect `GET /api/coin/dextools` (it resolves the top pool, redirects to its pair page, and records a per-day, per-surface visit in `dextools_referrals`, since DEXTools Social Boost ranks tokens by pair-page visits); when the pair is already known the link goes straight to its pair page, which is how the Oracle's market panel links the most liquid pair DexScreener names, and $THREE always its Social Boost pair.- 8. (optional, agents view) Follow an agent's signals: expand follow-panel → enter Telegram chat ID → `POST /api/oracle/follow`.- 9. **Arm payoff (gated):** open **Agent** tab → `loadAgentPanel()` → `GET /api/agents`. Pick agent, set Min conviction (Prime/Strong+/Lean+), Size/trade SOL, Max daily SOL, Max open, category filters, optional Telegram chat ID (Send test → server push), toggle Armed + Live/Simulate switches → **Save configuration** → `POST /api/oracle/watch` `{armed, mode, min_score, per_trade_sol, max_daily_sol, max_open, ...}`. Confirmation: "Armed in simulate/live mode. Your agent is watching the stream." Arming live is judged on the raw request, not the clamped values: a `per_trade_sol` below 0.001 SOL or a `max_daily_sol` below `per_trade_sol` answers 400 before any real-money loop starts (simulate keeps the forgiving clamps), and the GET side rejects a non-uuid `agent_id` with 400. The move INTO live-armed also requires a current signature on the three real-funds agreements (`requireRealFundsAgreement()`, `403 risk_ack_required` pointing at `/legal/agreements`); re-saving a watch that is already live-armed, simulate mode, disarming, and devnet all stay open.+ 8. (optional, agents view) Follow an agent's signals: expand follow-panel. It shows the Telegram chat linked to the account (read-only, from `GET /api/oracle/telegram-chat`); signed out it asks to sign in, and with no linked chat it points to Settings, Sign-in methods. Follow → `POST /api/oracle/follow`, which answers 401 without a session and 403 without a verified linked chat.+ 9. **Arm payoff (gated):** open **Agent** tab → `loadAgentPanel()` → `GET /api/agents`. Pick agent, set Min conviction (Prime/Strong+/Lean+), Size/trade SOL, Max daily SOL, Max open, category filters, the linked Telegram chat shown read-only (Send test → server push, same sign-in and linked-chat requirement), toggle Armed + Live/Simulate switches → **Save configuration** → `POST /api/oracle/watch` `{armed, mode, min_score, per_trade_sol, max_daily_sol, max_open, ...}`. Confirmation: "Armed in simulate/live mode. Your agent is watching the stream." Arming live is judged on the raw request, not the clamped values: a `per_trade_sol` below 0.001 SOL or a `max_daily_sol` below `per_trade_sol` answers 400 before any real-money loop starts (simulate keeps the forgiving clamps), and the GET side rejects a non-uuid `agent_id` with 400. The move INTO live-armed also requires a current signature on the three real-funds agreements (`requireRealFundsAgreement()`, `403 risk_ack_required` pointing at `/legal/agreements`); re-saving a watch that is already live-armed, simulate mode, disarming, and devnet all stay open.- **Decision points / branches:** view tabs (9); feed warming vs populated vs filtered-empty; drawer coin scored vs "not scored yet"; agent has wallet vs needs creation (`/create/studio`); simulate vs live mode; signed-out → "Sign in and arm an agent".-- **External calls / dependencies:** `/api/oracle/feed`, `/api/oracle/coin`, `/api/oracle/search`, `/api/oracle/movers`, `/api/oracle/categories`, `/api/oracle/backtest`, `/api/oracle/wins`, `/api/oracle/stats` (hero statline + Telegram channel link), `/api/oracle/activity`, `/api/oracle/watch` (GET+POST), `/api/oracle/follow` (GET+POST), `/api/agents`; SSE `/api/oracle/action-stream`; oracle-tape live trade stream in drawer.+- **External calls / dependencies:** `/api/oracle/feed`, `/api/oracle/coin`, `/api/oracle/search`, `/api/oracle/movers`, `/api/oracle/categories`, `/api/oracle/backtest`, `/api/oracle/wins`, `/api/oracle/stats` (hero statline + Telegram channel link), `/api/oracle/activity`, `/api/oracle/watch` (GET+POST), `/api/oracle/follow` (GET+POST), `/api/oracle/telegram-chat` (GET), `/api/agents`; SSE `/api/oracle/action-stream`; oracle-tape live trade stream in drawer.- **Success state:** live conviction feed scoring every pump.fun launch in real time; coin drawer with pillar breakdown; armed agent acting on the stream (simulate logs / live spends capped SOL), actions graded into a win-rate ledger.- **Empty / error states:** "Oracle is warming up" (backend not live); "No launches clear your filters" + Reset; the symbol search answers in the dropdown rather than closing it, quoting the query back ("No scored coin matches “<q>”. Oracle only searches launches it has scored.") on a miss and "Search is unavailable right now. Try again in a moment." on an outage, and a stale response can no longer overwrite a query the reader has moved on from; drawer "not scored"; "No ranked agents yet"; SSE auto-reconnects ("Reconnecting…"); `api()` returns `{ok:false}` on timeout (12s abort) and degrades gracefully; during a database outage the oracle endpoints (stats, feed, coin, activity, backtest, categories, follow, batch) answer 503 with Retry-After instead of a confident empty record, so the page shows its warming/retry state rather than "0 scored, 0 armed".- **Step count:** 3 required (arrive → feed → live stream, all automatic) + ~6 optional read interactions, + a 6-field gated arm flow (steps 8–9).@@ -96,7 +96,7 @@ coin-intel, pump-visualizer and pump-live: adding a coin on any surface shows up- **Prerequisites / gates:** None — public ranked board.- **Steps (N):**1. Arrive → `readUrl()` hydrates state (tab/network/window/sort/verified), live-refreshing every 20s. Two boards share the page: **Trading** (default) and **Earned** (`?tab=earned`, picked before first paint so it never flashes the trading view).- 2. System: `GET /api/sniper/leaderboard?network=&window=&sort=&verified=` renders ranked rows (agent name + verified badge, wallet chip, unique coins, copiers count); top 3 styled.+ 2. System: `GET /api/sniper/leaderboard?network=&window=&sort=&verified=` renders ranked rows (agent name + verified badge, wallet chip, unique coins, copiers count); top 3 styled. Each row also carries `win_streak` and `hot_streak` (3 or more consecutive wins within the last 25 closed positions); the Arena board (`src/play/arena.js`) shows the streak badge, this page does not.3. (optional) Window: 24h/7d/30d/all (`#lb-window`) → URL + reload.4. (optional) Network: mainnet/devnet (`#lb-network`).5. (optional) Sort: score/pnl/winrate/roi (`#lb-sort` select).