Skip to content

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

docs(structure): map the playground, payments and reputation surfaces to their files

nirholas8ef78aab1576
diff --git a/STRUCTURE.md b/STRUCTURE.md
index 98d6b8d27..77bac9604 100644
--- a/STRUCTURE.md
+++ b/STRUCTURE.md
@@ -47,6 +47,7 @@ bottom.
| Creator portfolio (human profile) | [pages/profile.html](pages/profile.html) `→ /u/:username` (self-view `/profile`), backend [api/users/[username].js](api/users/%5Busername%5D.js) + paginated [api/users/[username]/creations.js](api/users/%5Busername%5D/creations.js) `→ /api/users/:username/creations` | Live | Every three.ws user's public portfolio: avatars, agents, widgets, skills, plugins, coins, memories, items for sale, and (added 2026-07-12, extended 2026-07-23) a **Creations** tab merging forged 3D models + Scene Studio worlds + Material Studio restyles — real, live, spinning `<model-viewer>` cards, cursor-paginated for 100+ items. `/forge`, `/diorama`, and `/restyle` all stay anonymous by default (no login required); a signed-in creator's `user_id` is attached to `forge_creations`/`dioramas` rows at generation/save time (migration [api/_lib/migrations/20260712010000_creator_portfolio_user_ids.sql](api/_lib/migrations/20260712010000_creator_portfolio_user_ids.sql)) and to a new `material_restyles` row per AI restyle or colorway variant (migration [api/_lib/migrations/20260723140000_material_restyles.sql](api/_lib/migrations/20260723140000_material_restyles.sql), store [api/_lib/material-restyle-store.js](api/_lib/material-restyle-store.js)) so those creations surface here. The same opt-in attribution now links back from the diorama viewer HUD, the diorama gallery cards, and the forge result bar ("by @user") whenever a creation's creator is known. `/@:handle` ([pages/handle.html](pages/handle.html)) is a separate, narrower agent-embed page — not the human portfolio. |
| Model detail page (`/m/:id`) | [pages/model.html](pages/model.html) `→ /m/:id`, page module [src/model-page.js](src/model-page.js) + pure helpers [src/model-lib.js](src/model-lib.js) + [src/model.css](src/model.css), backend [api/forge-creation.js](api/forge-creation.js) (`?related=&view=` + voted state; `DELETE`, scoped to the owning `x-forge-client`, lets a creator erase a creation, its stored GLB, preview, and recorded source uploads included) and [api/forge-comments.js](api/forge-comments.js), store reads [api/_lib/forge-store.js](api/_lib/forge-store.js) (`getPublicCreation`/`listRelated`/`recordCreationView`), schema [api/_lib/migrations/20260805120000_model_page.sql](api/_lib/migrations/20260805120000_model_page.sql) | Live | Every finished forge model as a first-class page in the classic model-platform detail layout: interactive viewer hero with AR and fullscreen, title + creator card with a real follow button (follow graph), live triangle/vertex stats from `GET /api/3d/inspect` (nothing persisted, nothing invented), the full prompt as the description, honest attribute chips, anonymous likes shared with the Forge-Off vote rail (`forge_votes`, same `forge:cid` id), a real page-view counter (`forge_creations.view_count`), a signed-in comment thread (`forge_comments`, bell-notifies the creator via the `comment` event type), paid remix via the existing x402 rail, embed/share/download, and a same-category suggested-models rail. Linked from the Details button on `/creations` cards and the Forge showcase. Tests: [tests/model-lib.test.js](tests/model-lib.test.js) |
| Labs (hidden-gems hub) | [pages/labs.html](pages/labs.html) + [src/labs.js](src/labs.js) `→ /labs` | In-repo | Data-driven discovery hub: renders every `data/pages.json` entry flagged `showcase: true` as a live card (status check + iframe preview), filterable by category |
+| Playground (drop-in .glb viewer) | [pages/playground.html](pages/playground.html) `→ /playground` | Live | A 3D scene sandbox with nothing to install: drop or pick a `.glb` and it renders in `<model-viewer>` with animation playback, environment and background presets, auto-rotate, shadow and exposure controls, live file stats, and a copy-ready embed snippet. The file never leaves the browser (it is read as a blob URL), so the failure path carries the weight: a model that will not parse, a stalled download, or a blocked model-viewer CDN lands in an in-viewer error card with Retry and a file picker rather than an endless spinner. |
| Holo Sticker (procedural foil demo) | [pages/holo.html](pages/holo.html) `→ /holo`, app [src/holo.js](src/holo.js), styles [src/holo.css](src/holo.css) | Live | A real-time holographic foil sticker rendered with physical materials, fully procedural (no assets fetched): tilt it with the pointer, peel the corner (vertex-shader cylinder roll), switch foil styles, die-cut arbitrary typed text via a marching-squares vectorizer, and download the frame as a PNG |
| Machine Atlas (code-generated machines) | [pages/assembly.html](pages/assembly.html) `→ /assembly`, app [src/assembly.js](src/assembly.js), styles [src/assembly.css](src/assembly.css), geometry [src/assembly/](src/assembly/) | Live | Two working machines with no model files behind them: a nine-cylinder radial aero engine and a coupled steam locomotive, generated at runtime from their dimensions (revolved profiles, extruded sections, lofted NACA blade stations). Motion is solved, not keyframed: pistons follow the exact planar slider-crank and the locomotive valve gear closes a four-bar chain every frame by circle intersection. Live dimension sliders rebuild the geometry, explode and structure views take it apart, hover names any part, subassemblies toggle, and the Source panel prints the generating calls from the live values. Every configuration is a shareable link; export as GLB or save a PNG frame. Docs: [src/assembly/README.md](src/assembly/README.md). Tests: [tests/assembly-machines.test.js](tests/assembly-machines.test.js) |
| Examples gallery | [pages/examples.html](pages/examples.html) `→ /examples`, curated snippets [public/examples.js](public/examples.js), generated index renderer [public/examples-index.js](public/examples-index.js), styles [public/examples.css](public/examples.css), hosted example tree [public/examples/](public/examples) built by [scripts/build-hosted-examples.mjs](scripts/build-hosted-examples.mjs) | Live | Two halves. The top is 17 copy-paste snippets that RUN on the page, grouped into four lanes (avatars and embeds, 3D models, agents, agent economy) behind a sticky jump nav and a text/tag filter that folds away lanes as they empty (a deep link always beats an active filter): each is a complete document loading the production CDN bundle into an iframe, so "Run" executes exactly the code shown, and the model/agent/economy lanes call the live CORS-open production APIs rather than illustrating them (free text→3D at `/api/v1/ai/text-to-3d`, free text→speech at `/api/v1/ai/tts` played through the new `speakAudio()` viseme path, `/api/3d/inspect`, the 112-clip `/animations/manifest.json`, `/api/forged`, the public no-auth MCP server at `/api/mcp-studio` for both `tools/list` and a live `look_at_model` render-and-critique, the 402 quote from `/api/x402/forge`, `/api/pump/launches`). The `agent-from-files` card loads a real manifest from `/examples/coach-leo/manifest.json`: `npm run build:examples` publishes [examples/coach-leo/](examples/coach-leo) and its wave skill into `public/examples/` with body/image URIs rewritten absolute, so the manifest resolves the same way off-site as it does here. The bottom is every example that ships in the repo, generated by [scripts/build-examples-index.mjs](scripts/build-examples-index.mjs) scanning every `examples/` directory into [data/examples.json](data/examples.json), mirrored to the served [public/examples.json](public/examples.json) by [scripts/mirror-examples-index.mjs](scripts/mirror-examples-index.mjs) (`npm run build:examples` runs all three). Because it is scanned, the page cannot advertise a deleted example or miss an added one; each card carries the files it contains and the command that runs it. Tests: [tests/examples-page.test.js](tests/examples-page.test.js), [tests/examples-index.test.js](tests/examples-index.test.js) |
@@ -73,6 +74,7 @@ bottom.
| Visitor feedback loop | Recorder [@three-ws/witness](packages/witness), capture + panel [src/feedback-companion.js](src/feedback-companion.js) (mounted by [src/walk-companion.js](src/walk-companion.js)), intake [api/feedback/report.js](api/feedback/report.js), queue API [api/feedback/index.js](api/feedback/index.js), scoring [api/_lib/feedback/triage.js](api/_lib/feedback/triage.js), store [api/_lib/feedback/store.js](api/_lib/feedback/store.js), cron [api/cron/feedback-triage.js](api/cron/feedback-triage.js), review page [pages/feedback.html](pages/feedback.html) `→ /feedback` + [src/feedback-page.js](src/feedback-page.js) | Live | The return channel on the corner companion: the visitor tells the avatar what broke and the report carries the route, build SHA, viewport, and the last console errors and failed requests the browser captured, so a vague sentence lands as an actionable row. The companion offers proactively at the one moment worth asking (right after the page actually threw), once per route per session, never in a background tab. **Feedback is data, never an instruction:** the model that reads untrusted visitor text writes six scalars to that report's own row and has no path to the repo, a deploy, or any other write; the admin-only `/feedback` queue groups reports into one row per problem and a person decides. **A report arrives as a runnable failing test:** the recorded session compiles into a Playwright spec asserting the failure is GONE (red until fixed, green after), reachable from the queue's Copy test button, `GET /api/feedback/repro`, `npm run feedback:repro`, and the `get_feedback_repro` MCP tool. Docs: [docs/feedback.md](docs/feedback.md), [docs/witness.md](docs/witness.md). Tests: [tests/feedback-triage.test.js](tests/feedback-triage.test.js) |
| Session-to-test recorder | [packages/witness/](packages/witness) `→ @three-ws/witness`: recorder [recorder.js](packages/witness/src/recorder.js), selector synthesis [selector.js](packages/witness/src/selector.js), capture-time privacy [redact.js](packages/witness/src/redact.js), spec compiler [compile.js](packages/witness/src/compile.js); compiled repros land in [tests/repros/](tests/repros) with [their own Playwright config](tests/repros/playwright.config.mjs) | Published as `@three-ws/witness` (Apache-2.0, zero deps) | Turns a real user session into a runnable failing test. Records INTENT (about 2 KB) rather than DOM mutations (megabytes), so it can be always-on, which is the point: the trace already exists when somebody decides to complain. Every element gets the strongest handle that is unique in the live document (test id > id > aria-label > role+name > text > name > placeholder > class > structural path), framework-generated ids and utility classes refused, and each trace carries a replay confidence equal to its WEAKEST link. The compiled spec asserts the failure is gone, never that it happened, so it locks in the fix rather than the bug; a session with no machine-visible failure emits `test.fail()` and says which assertion a human must add rather than faking green. Privacy is enforced at capture: typed values are never held (only a length and a shape), password/hidden/email/tel/date inputs and `data-witness="off"` subtrees record nothing, URLs lose their credentials before storage. Docs: [docs/witness.md](docs/witness.md). Tests: [packages/witness/test/](packages/witness/test) (36, `npm run test:witness`) |
| Prepaid credits (`/credits`) | [pages/credits.html](pages/credits.html) `→ /credits` + [src/credits.js](src/credits.js), balance/ledger [api/credits/index.js](api/credits/index.js) `→ GET /api/credits`, deposit verifier [api/credits/deposit.js](api/credits/deposit.js) `→ POST /api/credits/deposit` over [api/_lib/credit-deposit.js](api/_lib/credit-deposit.js), ledger engine [api/_lib/credits.js](api/_lib/credits.js), schema [api/_lib/migrations/20260621200000_credits.sql](api/_lib/migrations/20260621200000_credits.sql) | Live | The prepaid balance every metered action on the platform debits. Top up by sending SOL or $THREE to the platform deposit wallet (connect + SIWS-link + sign in the page, or paste a signature you already sent); crediting is server-authoritative and idempotent on the signature, so a signature that is not signed by a wallet linked to the account credits nobody. The page renders the caller's $THREE holder tier from the same `holder` block [api/pricing.js](api/pricing.js) returns ([api/_lib/three-tier.js](api/_lib/three-tier.js)), which is the discount [api/_lib/credits.js](api/_lib/credits.js) already applies to every debit, and lists what credits buy straight from the pricing catalog ([api/_lib/pricing/catalog.js](api/_lib/pricing/catalog.js)). Ledger is keyset-paginated. Docs: [docs/payment-sessions.md](docs/payment-sessions.md). Tests: [tests/credits.test.js](tests/credits.test.js) |
+| Agent payment sessions (`/payments`) | [pages/payments.html](pages/payments.html) `-> /payments`, API [api/pay/session.js](api/pay/session.js) (`POST`/`GET`/`PATCH`/`DELETE /api/pay/session`, `GET /api/pay/session/:id/executions`), spend rail [api/pay/execute.js](api/pay/execute.js) + [api/pay/simulate.js](api/pay/simulate.js), engine [api/_lib/pay/payment-session.js](api/_lib/pay/payment-session.js) + governor [api/_lib/pay/spend-governor.js](api/_lib/pay/spend-governor.js), expiry sweep [api/cron/payment-session-sweep.js](api/cron/payment-session-sweep.js) | Live | The dashboard for platform-managed spend envelopes: fund a budget out of `/credits`, get a one-time `pss_` bearer token, and hand it to an agent that pays x402 endpoints without ever holding a private key (the platform's Solana wallet signs, and the governor enforces budget, host allowlist and per-tx cap atomically on every call). Each card carries the budget bar, remaining balance, expiry countdown, host allowlist, per-tx cap, an inline execution ledger from `GET /api/pay/session/:id/executions` with a Solscan link per settled payment, an env-var-referencing MCP config for [packages/agentcore-payments-mcp](packages/agentcore-payments-mcp), and cancel-and-refund. Press `N` for the create dialog. Docs: [docs/payment-sessions.md](docs/payment-sessions.md), [docs/tutorials/agent-spending-envelope.md](docs/tutorials/agent-spending-envelope.md). Tests: [tests/payment-session-governor.test.js](tests/payment-session-governor.test.js), [tests/payment-session-sweep.test.js](tests/payment-session-sweep.test.js) |
| Skill bundles (seller builder + evidence pricing) | [pages/bundles.html](pages/bundles.html) `→ /bundles`, API [api/agents/[id]/bundles.js](api/agents/%5Bid%5D/bundles.js), arithmetic [api/_lib/bundle-pricing.js](api/_lib/bundle-pricing.js), checkout [api/marketplace/purchase-bundle.js](api/marketplace/purchase-bundle.js) | Live (seller side); no buyer-facing browser view yet | Sell several of one agent's skills as one purchase. The price is derived from the agent's own ledger rather than a rule of thumb: the public `?action=pricing` endpoint finds every buyer who already bought 2+ of the selected skills, suggests the median of what they really paid (`basis: median_basket`), and backtests any candidate price against those same baskets; with no such buyer yet it falls back to 20% off the sum of the parts and labels itself `discount_off_list` so a default is never read as a finding. Every amount is an atomic integer carried as a BigInt end to end, because a 9-decimal mint puts real sums past `Number.MAX_SAFE_INTEGER`. Checkout settles on-chain and writes one `skill_purchases` row per skill (`kind = 'bundle'`, amount 0) so one bundle sale is never counted as N skill sales. Docs: [docs/skill-bundles.md](docs/skill-bundles.md). Tests: [tests/bundle-pricing.test.js](tests/bundle-pricing.test.js), [tests/vercel-agents-subpath-routes.test.js](tests/vercel-agents-subpath-routes.test.js) |
| Marketplace analytics & trial funnel | [pages/marketplace-analytics.html](pages/marketplace-analytics.html) `→ /marketplace/analytics`, renderer [src/marketplace-analytics.js](src/marketplace-analytics.js), backend [api/marketplace/analytics.js](api/marketplace/analytics.js) | Live | Public transparency page for the skill marketplace: paid sales, volume, top skills/agents, and the trial conversion funnel. **Every money aggregate gates on `status = 'confirmed'` alone.** Counting `status IN ('confirmed','trial')` as a sale published 10,454 "sales" and 6.2M $THREE of "volume" on 2026-07-30 against a table holding zero confirmed purchases, because a `trial` row is a free grant whose `amount` is only the list price it would have cost. Free trials now render as their own stat and as a four-stage funnel (granted → used → exhausted → converted), which also names the two shapes that mean a wiring fault rather than weak demand: trials never spent, or trials exhausted with nothing converting. Docs: [docs/marketplace.md](docs/marketplace.md), tutorial [docs/tutorials/sell-a-skill-with-a-trial.md](docs/tutorials/sell-a-skill-with-a-trial.md). Tests: [tests/marketplace-analytics-paid-only.test.js](tests/marketplace-analytics-paid-only.test.js) |
| OKX.AI marketplace services | [api/okx/3d/[service].js](api/okx/3d/%5Bservice%5D.js) `→ /api/okx/3d/*` | Live | 3D services sold to other agents on OKX.AI (agent #2632). The **listed** line-up (rebuilt 2026-08-22) is **three.ws Forge**: four paid A2MCP rows (`forge-draft` $0.01 / `forge-standard` $0.05 / `forge-hd` $0.25 / `forge-image` $0.25) plus a free `forge-status` poll, tools in [api/_okx3d/forge.js](api/_okx3d/forge.js). Each row is a real MCP Streamable HTTP server whose paid `forge_3d` tool 402s with `eip155:196` leading; the buyer receives exactly what the ChatGPT custom GPT receives (GLB + concept image + viewer + AR link), because both fronts shape responses through [api/_mcp-studio/studio-shape.js](api/_mcp-studio/studio-shape.js). Agent Identity Studio and the single-capability REST endpoints are on the **back burner**: `listed: false` keeps them out of the listing and the submission payload while they stay deployed and payable. Catalog source of truth: [api/_lib/okx-catalog.js](api/_lib/okx-catalog.js); pipeline: [api/_okx3d/](api/_okx3d); showcase: [pages/agent-identities.html](pages/agent-identities.html) `→ /agent-identities` + [src/agent-identities.js](src/agent-identities.js), fed at runtime by [api/agent-identities.js](api/agent-identities.js) `→ /api/agent-identities` (demo runs from `data/agent-identities.json` merged with the live catalog row, so the price the page quotes is the price the paid endpoint charges); docs: [docs/okx-marketplace.md](docs/okx-marketplace.md), [docs/agent-identities.md](docs/agent-identities.md). Tests: [tests/api/okx-forge.test.js](tests/api/okx-forge.test.js) |
@@ -92,7 +94,7 @@ bottom.
| Unified service catalog (one source, two storefronts) | [api/_lib/service-catalog/index.js](api/_lib/service-catalog/index.js), descriptors [api/_lib/service-catalog/services/](api/_lib/service-catalog/services/index.js) | Live | The canonical written-once record of every service (paid x402 + free crypto/3D bundles + OKX.AI rows). `toBazaarDiscovery()` generates every static `/api/x402/*` entry in the [api/wk.js](api/wk.js) discovery doc (replacing ~1,400 lines of hand-mirrored blocks); `toOkxCatalog()` reproduces the OKX `catalogIndex()` payload exactly, with an `include:'all'` projection ready for listing expansion. New paid service = drop `services/<slug>.js` + add its barrel import row. No-drift guards: [tests/service-catalog.test.js](tests/service-catalog.test.js). Spec: [specs/SERVICE_CATALOG.md](specs/SERVICE_CATALOG.md) |
| Conversational refinement + remix economy | Iterate: [api/_mcp-studio/tools.js](api/_mcp-studio/tools.js) `refine_model` (free, on `/api/mcp-studio`) + [mcp-server/src/tools/refine-model.js](mcp-server/src/tools/refine-model.js) (paid stdio, $0.25); shared lineage core [mcp-server/src/tools/_lineage.js](mcp-server/src/tools/_lineage.js). Remix (paid track): feed [api/remix-feed.js](api/remix-feed.js) `→ /api/remix-feed` (free browse/publish/lineage), settlement [api/x402/remix-asset.js](api/x402/remix-asset.js) `→ /api/x402/remix-asset` + core [api/_lib/remix-settlement.js](api/_lib/remix-settlement.js) + split math [api/_lib/remix-royalty.js](api/_lib/remix-royalty.js). Docs [docs/remix.md](docs/remix.md), [docs/mcp-studio.md](docs/mcp-studio.md). | Live | Talk to a model to iterate it ("make it metallic") — real anchored re-generation with a revertable/branchable version lineage rendered as a viewer version strip; free on both the OpenAI 3D Studio and the paid MCP server. Creators publish a finished model as remixable (provenance + license + royalty on the existing `forge_creations` rows — no parallel store); another agent pays $0.25 USDC to remix it and a creator-set royalty (≤20%, capped) routes on-chain to the original creator via the audited `transferSolanaUSDC` rail. Split/caps/payout unit-tested ([tests/remix-settlement.test.js](tests/remix-settlement.test.js), [tests/remix-royalty.test.js](tests/remix-royalty.test.js), [tests/refine-lineage.test.js](tests/refine-lineage.test.js)). Free track stays crypto-free. Prompt 09. |
| Terminal renderer (3D in a shell, no GPU) | Renderer core [packages/tty-3d/](packages/tty-3d) (`@three-ws/tty-3d`, CLI `three-tty`), hosted stream [api/tty.js](api/tty.js) `→ /tty`, `/tty/:id`, `/api/tty`, page [pages/tty.html](pages/tty.html) + [src/tty-page.js](src/tty-page.js) `→ /tty`. Docs: [docs/tty.md](docs/tty.md). Tests: [packages/tty-3d/tests/tty-3d.test.js](packages/tty-3d/tests/tty-3d.test.js), [tests/api-tty.test.js](tests/api-tty.test.js) | Live | `curl three.ws/tty` and a rigged agent walks in your terminal, with nothing installed on either side. A pure-CPU software rasterizer (z-buffer, per-vertex linear blend skinning off the glTF animation samplers, meshopt decode on the way in) draws into a framebuffer the size of the caller's terminal and encodes it as `▀` half-blocks, so one cell carries two independently coloured pixels and pixels come out square. The server streams paced frames as `text/plain`, so the HTTP response IS the animation. Sibling of [packages/tty-avatar/](packages/tty-avatar), which adds moods, avatar-id resolution and Claude Code hooks on top of a terminal renderer but deliberately does not do skeletal animation; this package owns the 3D. |
-| Restyle Studio (material/PBR editor + AI restyle + variants) | [pages/restyle.html](pages/restyle.html) `→ /restyle`, [src/restyle.js](src/restyle.js). PBR preset/variant library [packages/viewer-presets/src/materials.js](packages/viewer-presets/src/materials.js) (`@three-ws/viewer-presets`). AI restyle + persistence core [api/_lib/material-studio-store.js](api/_lib/material-studio-store.js), free hosted endpoint [api/material-studio.js](api/material-studio.js) `→ /api/material-studio`; paid agent twin [mcp-server/src/tools/restyle-material.js](mcp-server/src/tools/restyle-material.js) (`restyle_material`, $0.05 stdio MCP), thin core [mcp-server/src/tools/_material-core.js](mcp-server/src/tools/_material-core.js). Shares the `refine_model` lineage core ([mcp-server/src/tools/_lineage.js](mcp-server/src/tools/_lineage.js)) so a restyle/variant is just another kind of version, feeding prompt 09 remix. Docs: [docs/mcp-tools.md](docs/mcp-tools.md). | Live | Re-skin any GLB without regenerating its mesh: live PBR editing (color/metalness/roughness/emissive/texture) with a one-click preset library (14 looks — chrome, gold, glass, wood…), seeded reproducible colorway variants (mulberry32 PRNG — same base+seed → same set), and free-text AI restyle ("make it chrome", "cyberpunk neon") via IBM Granite-proposed PBR factors applied + re-exported server-side. Every AI restyle / saved checkpoint mints a real, `gltf-validator`-checked, durably-stored GLB recorded in an immutable parent→child lineage — non-destructive in the durable sense, not just an in-browser Reset. Roadmap prompt 06. |
+| Restyle Studio (material/PBR editor + AI restyle + variants) | [pages/restyle.html](pages/restyle.html) `→ /restyle`, [src/restyle.js](src/restyle.js). PBR preset/variant library [packages/viewer-presets/src/materials.js](packages/viewer-presets/src/materials.js) (`@three-ws/viewer-presets`). AI restyle + persistence core [api/_lib/material-studio-store.js](api/_lib/material-studio-store.js), free hosted endpoint [api/material-studio.js](api/material-studio.js) `→ /api/material-studio`; paid agent twin [mcp-server/src/tools/restyle-material.js](mcp-server/src/tools/restyle-material.js) (`restyle_material`, $0.05 stdio MCP), thin core [mcp-server/src/tools/_material-core.js](mcp-server/src/tools/_material-core.js). Shares the `refine_model` lineage core ([mcp-server/src/tools/_lineage.js](mcp-server/src/tools/_lineage.js)) so a restyle/variant is just another kind of version, feeding prompt 09 remix. Docs: [docs/restyle.md](docs/restyle.md), [docs/mcp-tools.md](docs/mcp-tools.md). | Live | Re-skin any GLB without regenerating its mesh: live PBR editing (color/metalness/roughness/emissive/texture) with a one-click preset library (18 looks: chrome, gold, copper, brushed steel, gunmetal, matte, glossy, rubber, ceramic, glass, real glass, wood, stone, fabric, skin, car paint, neon, holographic), seeded reproducible colorway variants (mulberry32 PRNG, so the same base plus seed yields the same set), and free-text AI restyle ("make it chrome", "cyberpunk neon") via IBM Granite-proposed PBR factors applied + re-exported server-side. Every AI restyle / saved checkpoint mints a real, `gltf-validator`-checked, durably-stored GLB recorded in an immutable parent to child lineage: non-destructive in the durable sense, not just an in-browser Reset. Every server failure surfaces the API's own `error_description`, and a storage outage says so and points at Export GLB, which is wholly in-browser. Roadmap prompt 06. |
| Embodiment: a living agent body in the chat | Hosted embed [pages/embodiment/embed.html](pages/embodiment/embed.html) `→ /embodiment/embed` (Vite input + vercel route, `frame-ancestors *`); engine [apps-sdk/embodiment/embodiment-stage.js](apps-sdk/embodiment/embodiment-stage.js) (`EmbodimentStage`) + [overlay.js](apps-sdk/embodiment/overlay.js); persona tools (free) [api/_mcp-studio/persona-tools.js](api/_mcp-studio/persona-tools.js) → `/api/mcp-studio` (`create_agent_persona`, `get_agent_persona`, `persona_say`) and (paid) [api/_mcp3d/tools/studio.js](api/_mcp3d/tools/studio.js); shared inline-body artifact [api/_lib/embodiment-artifact.js](api/_lib/embodiment-artifact.js); identity store [api/_lib/persona-store.js](api/_lib/persona-store.js) (Postgres `agent_personas` + fs fallback + durable R2 GLB); reload route [api/mcp3d/persona.js](api/mcp3d/persona.js) `→ /api/mcp3d/persona`; live chain-state feed [api/mcp3d/persona-identity.js](api/mcp3d/persona-identity.js) `→ /api/mcp3d/persona-identity` (polled only when the embed is opened with `?wallet=1`). Emotion/rig/lip-sync cores under [src/embodiment/](src/embodiment) + [src/voice/](src/voice). | Live | A generated avatar becomes a persistent, named body that renders inline in ChatGPT/Claude: it lip-syncs each reply, blends the matching expression + gesture, idles between turns, and reloads by `persona_id` in a fresh session (the id is the capability, no sign-in). Rides the universal canonicalize/retarget clip library; a rig without face morphs animates the jaw, a non-humanoid GLB falls back to a gentle idle (`decideRigMode`/`supportsCanonicalClips`), never a bind-pose T-pose. Zero crypto/token surface. Tests: [tests/persona-store.test.js](tests/persona-store.test.js), [tests/api/persona-resolve-route.test.js](tests/api/persona-resolve-route.test.js), [tests/api/persona-identity-route.test.js](tests/api/persona-identity-route.test.js), [tests/mcp-studio.test.js](tests/mcp-studio.test.js), [tests/embodiment-rig-mode.test.js](tests/embodiment-rig-mode.test.js). Evidence: [prompts/store-submissions/_generated/embodiment/](prompts/store-submissions/_generated/embodiment/). Store-submission prompt 07. |
| Claude.ai artifact embed + builder | Endpoint [api/artifact.js](api/artifact.js) `→ /api/artifact`, prebuilt viewer [public/artifact-viewer.bundle.js](public/artifact-viewer.bundle.js) (source [scripts/artifact-viewer/src.js](scripts/artifact-viewer/src.js), `npm run build:artifact-viewer`), builder page [public/artifact/index.html](public/artifact/index.html) `→ /artifact` + [README](public/artifact/README.md), contract [specs/CLAUDE_ARTIFACT.md](specs/CLAUDE_ARTIFACT.md), vendored sandbox CSP [public/claude-artifact-csp.txt](public/claude-artifact-csp.txt) (refresh: [scripts/refresh-claude-csp.mjs](scripts/refresh-claude-csp.mjs)). | Live | `GET /api/artifact?agent=<uuid>` returns ONE self-contained HTML document with three.js, GLTFLoader, the viewer and the agent GLB all inlined, because Claude's artifact sandbox CSP blocks every external script and fetch. Paste the URL into a Claude conversation and the agent renders inline. The builder page is the pre-flight: it lists real public agents that carry an embeddable avatar (`/api/agents/public?avatar=1`), renders the response in a sandboxed iframe under the same CSP Claude applies, and reports payload size, fetch time, frame render time and sandbox compliance before you paste. Size is graded against the ceiling the endpoint can actually emit (a 6 MB model base64-inlines to 8 MB, plus the 565 KB viewer), not against the raw model cap, so a large-but-accepted artifact is not flagged as over budget. `?model=<glb url>` is the viewer-only lane (allowlisted https origins, SSRF-guarded, 6 MB cap). Tests: [tests/api/artifact.test.js](tests/api/artifact.test.js) pins the generated HTML against the vendored Claude CSP. |
| Avatar Artifact: the standalone shareable viewer | Page [pages/avatar-artifact.html](pages/avatar-artifact.html) `→ /avatar-artifact`, scene + artifact loader [src/avatar-artifact.js](src/avatar-artifact.js), docs [docs/avatar-artifact.md](docs/avatar-artifact.md). | Live | One page, one avatar, no wrapper: the URL you paste into an `<iframe>` on someone else's site or send to a person who has never heard of three.ws. `?agent=<uuid>` renders that agent's avatar from the live public record (the name becomes the heading and the document title, an Open profile link appears), `?model=<glb url>` renders any GLB from the same allowlisted hosts `/api/artifact` enforces, and a bare link renders the house portrait: a procedural figure that tracks cursor, touch and arrow keys. Ships no third-party CDN (three.js is bundled, because an embed host never agreed to a cross-origin script) and suspends its render loop on a hidden tab. An avatar with no baked clips is driven by the shared retargeted `idle` from the universal clip library rather than left in a bind-pose T-pose. Every failure lane (no such agent, private avatar, no avatar yet, blocked host, dead model, no WebGL) has its own sentence and its own next move; the Copy embed snippet carries the artifact parameters so the iframe shows what you were looking at. |
@@ -194,6 +196,7 @@ bottom.
| Contract audit pack | [contracts/AUDIT-README.md](contracts/AUDIT-README.md), invariants [specs/ECONOMY_CONTRACT_INVARIANTS.md](specs/ECONOMY_CONTRACT_INVARIANTS.md), threat model [specs/ECONOMY_CONTRACT_THREAT_MODEL.md](specs/ECONOMY_CONTRACT_THREAT_MODEL.md), static analysis [contracts/audit/](contracts/audit) | In-repo | Everything a review firm needs on day one for the reputation, royalty and delegation contracts: scope + deploy status per contract, stable invariant ids with a positive and a negative test each, an assets/actors/failure-modes threat model, and committed Slither + Clippy output with every finding fixed or dispositioned in writing |
| Recurring payments (subscriptions + DCA) | Page [public/recurring.html](public/recurring.html) `→ /recurring`, module [src/recurring.js](src/recurring.js), lifecycle rules [api/_lib/recurring.js](api/_lib/recurring.js), APIs [api/agent-subscriptions.js](api/agent-subscriptions.js) `→ /api/agent-subscriptions` and [api/dca-strategies.js](api/dca-strategies.js) `→ /api/dca-strategies`, hourly crons `run-subscriptions` + `run-dca` in [api/cron/[name].js](api/cron/%5Bname%5D.js), schema [api/_lib/migrations/20260813191500_recurring_payment_lifecycle.sql](api/_lib/migrations/20260813191500_recurring_payment_lifecycle.sql) | Live | One signed ERC-7710 permission, then money moves on a schedule: a subscription transfers a fixed USDC amount to an agent's wallet each period, a DCA strategy swaps the same amount into a token through Uniswap V3. `/recurring` is the whole lifecycle in one place (create, pause, resume, cancel, per-charge history) plus an Incoming tab scoped by agent ownership rather than by payer, so a creator sees what is being paid in. Every attempt is written to `subscription_charges` / `dca_executions`, and one shared classifier decides what a failure means: a revoked or expired permission pauses the schedule with the reason attached, a network blip releases the period claim and retries for three ticks, a timeout is never retried (the only failure that could double-charge), a diverged DCA quote skips the period for free, and a platform-side relayer outage never counts against the owner at all. Settlement needs `AGENT_RELAYER_KEY` + `RPC_URL_<chainId>` on the deployment; DCA creation needs `DCA_ALLOWED_TOKEN_OUT` + `DCA_CHAIN_ID`. Docs: [docs/recurring-payments.md](docs/recurring-payments.md). Tests: [tests/recurring-charge-outcomes.test.js](tests/recurring-charge-outcomes.test.js), [tests/api/recurring-subscription-cron.test.js](tests/api/recurring-subscription-cron.test.js) |
| Solana program invariant tests | [contracts/program-tests/](contracts/program-tests) | In-repo | LiteSVM suite running the real compiled SBF bytecode of `skill_license`, `agent_invocation`, and `knock_escrow` against invariants `SL-*`, `AI-*`, and `KE-*`, with the real SPL Token and ATA programs loaded. 42 tests green |
+| Reputation Explorer | Page [public/reputation/index.html](public/reputation/index.html) + module [public/reputation/reputation.js](public/reputation/reputation.js) `→ /reputation` | Live | EAS-backed review history for ANY Ethereum address, agent or not: search an address or ENS name, pick a chain (Base, Base Sepolia, Ethereum, Optimism, Arbitrum, Polygon), and read every attestation written to it straight from that chain's EASScan GraphQL index. Reviews render as stars plus comment; attestations written against any other schema render their own decoded fields, so a non-review card is never a blank row. The list pages 30 at a time and filters by All / Scored / With comments. An unreachable index is reported as unknown history with a retry, never as zero reviews. Writing a review is wallet-gated and lands on Base Sepolia. Owning an ERC-8004 agent on the viewed chain surfaces the registry's own vote count beside the EAS numbers. `?agent=<chainId>:<id>` resolves an ERC-8004 agent to its owner address and forwards. Docs: [docs/reputation.md](docs/reputation.md) |
| Reputation Staking Market | spec [specs/REPUTATION_STAKING_MARKET.md](specs/REPUTATION_STAKING_MARKET.md), engine [src/shared/reputation-staking.js](src/shared/reputation-staking.js), server [api/_lib/reputation-market.js](api/_lib/reputation-market.js) + [api/reputation/market*.js](api/reputation), surface [public/reputation/market/](public/reputation/market) `→ /reputation/market` | In-repo · devnet open, mainnet owner-gated | Phase 3 roadmap: stake conviction on an agent and earn from its attested action history. A stake is a staker-signed Solana transfer to the market escrow carrying an `rsm.v1` SPL-Memo, so the chain (not the database) defines a position; the server only verifies it by reading the transaction back. Yield comes from a fixed per-epoch pool split by `principal × time × agentWeight`, where the weight is derived purely from the agent's signed `threews.*` attestations (work concave in `log2`, faults charged double), so conviction never pays itself. Principal is never slashed and settlement clamps earnings to the escrow surplus. Extends the SPL-Memo attestation layer in [docs/solana-reputation.md](docs/solana-reputation.md). Storage: [reputation_staking_market migration](api/_lib/migrations/20260811140000_reputation_staking_market.sql). Walkthrough: [docs/reputation-staking-market.md](docs/reputation-staking-market.md). Devnet proof: `node scripts/reputation-market-proof.mjs`. Tests: [tests/reputation-staking.test.js](tests/reputation-staking.test.js) |
| On-chain skill licenses | [contracts/skill-license/](contracts/skill-license) `→ /api/skills/license-onchain` | In-repo | Anchor program: each purchased skill = a 1/1 SPL NFT + `SkillLicense` PDA, a trustless alternative to DB-backed access checks. Backend: [api/_lib/skill-license-onchain.js](api/_lib/skill-license-onchain.js) |
| Tokenized 3D (mint an avatar as an NFT) | [api/_lib/tokenize-3d.js](api/_lib/tokenize-3d.js) + [api/_lib/tokenize-3d-metadata.js](api/_lib/tokenize-3d-metadata.js), MCP tools [api/_mcp/tools/tokenize.js](api/_mcp/tools/tokenize.js) (`mint_3d_asset`, `get_3d_asset_onchain`), signed ledger provenance [api/_lib/asset-provenance.js](api/_lib/asset-provenance.js), launch directory [api/v1/tokenized/launches.js](api/v1/tokenized/launches.js) `→ GET /api/v1/tokenized/launches`, public gallery [pages/minted.html](pages/minted.html) + [src/minted.js](src/minted.js) `→ /minted` | In-repo | Mint a generated/owned GLB as a Metaplex Core NFT whose media is a live 3D viewer (GLB under `animation_url`), with baked provenance + enforced capped royalties (10%), idempotent, devnet-default. Every generated avatar AND every mint also appends an ERC-191-signed record to the `agent_actions` ledger (verifiable via `@three-ws/provenance-mcp`'s `query_action`). A mint naming `parent_mint` (a remix) routes the parent creator's royalty out of the mint fee as a real on-chain USDC transfer (mainnet, x402-collected calls only) — [api/_lib/remix-royalty.js](api/_lib/remix-royalty.js) split math, [api/_lib/remix-settlement.js](api/_lib/remix-settlement.js) payout wallet. Premium/token-gated generation: the Forge High tier (200k poly + PBR) is $THREE hold-or-pay gated — [api/forge.js](api/forge.js) `requireFeatureAccess('forge.high')` + [api/_lib/three-tier.js](api/_lib/three-tier.js) tier ladder, x402 pay-per-use or credits fallback; Draft/Standard stay free and ungated. Launch record: [tokenized_3d_assets](api/_lib/migrations/20260707120000_tokenized_3d_assets.sql) + [remix-royalty columns](api/_lib/migrations/20260708130000_tokenized_3d_remix_royalty.sql). Public gallery: `/minted` renders the launch directory live (model-viewer thumbnails, network toggle, royalty + remix badges) — the NFT counterpart of `/launches`. Docs: [docs/mcp.md](docs/mcp.md#mint_3d_asset). E2E: [scripts/tokenize-3d-devnet-e2e.mjs](scripts/tokenize-3d-devnet-e2e.mjs). Tests: [tests/tokenize-3d.test.js](tests/tokenize-3d.test.js), [tests/tokenize-3d-remix-royalty.test.js](tests/tokenize-3d-remix-royalty.test.js), [tests/asset-provenance.test.js](tests/asset-provenance.test.js) |