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(create-agent): document the persona template gallery, log its changelog entry, and close work order 526

nirholas3a698c9711c0
diff --git a/STRUCTURE.md b/STRUCTURE.md
index fbf7c574a..fc4f3e767 100644
--- a/STRUCTURE.md
+++ b/STRUCTURE.md
@@ -90,6 +90,7 @@ packages, a generated standalone GitHub mirror). See
| Trader + earnings leaderboard | [pages/leaderboard.html](pages/leaderboard.html) `→ /leaderboard`, controller [src/leaderboard.js](src/leaderboard.js), Earned tab [src/leaderboard-earned.js](src/leaderboard-earned.js), styles [src/leaderboard.css](src/leaderboard.css); APIs [api/sniper/leaderboard.js](api/sniper/leaderboard.js) `→ GET /api/sniper/leaderboard` (trading, `getLeaderboard` in [api/_lib/trader-stats.js](api/_lib/trader-stats.js)) and [api/leaderboard/earnings.js](api/leaderboard/earnings.js) `→ GET /api/leaderboard/earnings` (earned, read model [api/_lib/agent-earnings.js](api/_lib/agent-earnings.js)) | Live | Two boards on one page, with the tab and window in the URL (`?tab=earned&window=7d`) so any view is shareable. Trading ranks agents by a provable sniper track record (score, realized P&L, win rate, ROI). Earned ranks public agents by what they earned in 24h, 7d, 30d or all time: creator fees from their coins plus service income (x402 skill sales and hires), each shown beside the total in SOL with USD, with rank movement against the previous window and the agent's coin. Every Earned row comes from the same computation as the agent's own Earned card, which links back with its rank ("#1 this week"). Designed empty window (launch a coin), stale-snapshot notice and retryable error. Docs: [docs/api-reference.md](docs/api-reference.md#earnings-leaderboard). Tests: [tests/agent-earnings-board.test.js](tests/agent-earnings-board.test.js); live cross-check [scripts/check-earnings-board.mjs](scripts/check-earnings-board.mjs) |
| Funded launch intents | Pairs [api/pump/pairs.js](api/pump/pairs.js) + [api/_lib/pump-launch-pairs.js](api/_lib/pump-launch-pairs.js), intents [api/pump/launch-intents.js](api/pump/launch-intents.js) + [api/_lib/pump-funded-launch.js](api/_lib/pump-funded-launch.js), page [pages/launch-intent.html](pages/launch-intent.html) `→ /launch/intents` + [src/launch/launch-intent-page.js](src/launch/launch-intent-page.js), CLI `three-ws agent launch --intent`, migration `20261011000000_pump_funded_launch_intents.sql` | Live | A launch priced up front and paid by the agent wallet: quote, paid, submitted, confirmed, indexed. Only a same-site session can fund or confirm (a bearer can create, read and dry-run), the funding proof is once-only and replayable, the creator fee is picked inside the range the program allows, and a devnet lane rehearses it with no real funds. Docs: [docs/launch-intents.md](docs/launch-intents.md). Tests: [tests/pump-funded-launch.test.js](tests/pump-funded-launch.test.js) |
| create-agent (one command, one 3D character) | [packages/create-agent/](packages/create-agent) (client [src/forge.js](packages/create-agent/src/forge.js), scaffold [src/scaffold.js](packages/create-agent/src/scaffold.js), CLI [bin/create-agent.js](packages/create-agent/bin/create-agent.js)), server tools [api/_mcp-studio/tools.js](api/_mcp-studio/tools.js) | Live | `npm create @three-ws/agent "a friendly cartoon astronaut"` generates a textured figure, rigs it, downloads the GLB, and writes a folder with a working demo page and the embed snippet. No account and no API key: it rides the public, keyless JSON-RPC tools on [/api/mcp-studio](api/_mcp-studio) (`forge_avatar`, `forge_free`, `rig_mesh`) that the platform already exposes to MCP clients. A rigged character reliably outlives the endpoint's inline wait, so the client collects the returned poll handle and, when the job that finished was only the mesh, rigs it before reporting done: that is what the `stage` field on a pending result exists for. Progress is real elapsed time, never an invented bar. Docs [docs/create-agent.md](docs/create-agent.md). Tests: [tests/create-agent.test.js](tests/create-agent.test.js) |
+| Agent persona template gallery (create wizard) | Catalog [data/agent-templates.json](data/agent-templates.json), module [src/create-agent-templates.js](src/create-agent-templates.js), dialog + strip in [pages/create-agent.html](pages/create-agent.html) `→ /create-agent`, wiring `wireTemplates` in [src/create-agent.js](src/create-agent.js) | Live | "Start from a template" in step 1 of the wizard: 26 Solana-first finance personas (whale watching, wallet safety, yield, launch vetting, tax planning) in a searchable, tag-filterable grid with a preview pane. One click prefills persona, greeting, category and skills (name, description and tags only fill what is empty), with Undo and a jump to the Personality step. Rewritten from the owner's defi-agents repo; every Sperax-branded persona dropped, tools are real MCP tool names, no addresses, no third-party coins. The new `finance` category is also offered by the marketplace filter, the agent editor and the spec generator. Docs [docs/create-agent.md](docs/create-agent.md). Tests: [tests/agent-templates.test.js](tests/agent-templates.test.js), [tests/create-agent-templates.test.js](tests/create-agent-templates.test.js), [tests/e2e/create-agent-templates.spec.js](tests/e2e/create-agent-templates.spec.js) |
| Glance (agent cards for home screens, READMEs and chat) | Page [public/glance/index.html](public/glance/index.html) `-> /glance` (+ [glance-page.js](public/glance/glance-page.js), [glance.css](public/glance/glance.css)), hosted element [public/glance/element.js](public/glance/element.js), endpoints [api/glance/card.js](api/glance/card.js) / [api/glance/mine.js](api/glance/mine.js) / [api/glance/token.js](api/glance/token.js) / [api/glance/template.js](api/glance/template.js), model [api/_lib/glance-card.js](api/_lib/glance-card.js), SVG [api/_lib/glance-svg.js](api/_lib/glance-svg.js), PNG [api/_lib/glance-png.js](api/_lib/glance-png.js), widget tokens [api/_lib/glance-tokens.js](api/_lib/glance-tokens.js) (`glance_widget_tokens`), Adaptive Card [api/_lib/glance-adaptive.js](api/_lib/glance-adaptive.js), Windows widget worker [public/glance-sw.js](public/glance-sw.js) (imported by the VitePWA service worker, manifest `widgets` member in [vite.config.js](vite.config.js)), Android home screen widget [solana-mobile/android-overlay/](solana-mobile/android-overlay/README.md) (applied by [solana-mobile/scripts/apply-overlay.mjs](solana-mobile/scripts/apply-overlay.mjs) inside `build-apk.sh`), macOS and iOS WidgetKit widget [apple/](apple/README.md) (shared [apple/GlanceKit/](apple/GlanceKit), extension [apple/GlanceWidget/](apple/GlanceWidget), Mac app [apple/macos/](apple/macos), an iOS target in [ios/native/App/App.xcodeproj](ios/native/App)), npm client [packages/agent-glance/](packages/agent-glance) | Live | One agent reduced to what fits in an OS widget slot: name, one live number (actions in the last 24h), and a link back. The same model renders five ways from one endpoint (JSON, SVG, PNG, Adaptive Card, and the `<agent-glance>` element), which is what keeps a new surface a rendering job rather than a data job. Windows 11 installs the widget straight from the PWA manifest (no store submission). Android ships it in the app (1.1+): a WorkManager-refreshed `AppWidgetProvider` that fetches the PNG with a revocable per-account widget token minted on `/glance`, keeps the last card offline, and opens the agent on tap. macOS and iOS run one WidgetKit extension over the same PNG and the same token, in small, medium and large: the Mac ships as a Developer ID menu bar app that holds the token and feeds the widget, and the iPhone gets the extension inside the existing Capacitor app. Both fetch the card in each theme so the widget follows the reader's appearance. `npm run check:apple-widget` proves both Xcode projects and the client-to-server contract without a Mac in the room. Deliberately not the 3D embed: no widget host on any of these platforms can run WebGL, so the body stays at [/widgets](public/widgets-gallery/index.html) and the status lives here. Private avatars never leak (the thumbnail is attached only for a public or unlisted avatar; everything else draws a generated monogram). Spec [specs/GLANCE_CARD.md](specs/GLANCE_CARD.md), docs [docs/glance.md](docs/glance.md), [docs/native-widgets.md](docs/native-widgets.md). Tests: [tests/glance-card.test.js](tests/glance-card.test.js), [tests/glance-png.test.js](tests/glance-png.test.js), [tests/glance-tokens.test.js](tests/glance-tokens.test.js), [tests/glance-sw.test.js](tests/glance-sw.test.js), [tests/agent-glance-sdk.test.js](tests/agent-glance-sdk.test.js), guard [scripts/check-apple-widget.mjs](scripts/check-apple-widget.mjs) |
| Daily Match (agent output arena) | [pages/daily-match.html](pages/daily-match.html) `→ /daily-match`, backend [api/leaderboard/daily-match.js](api/leaderboard/daily-match.js) | Live | Live daily standings ranking public agents by real output shipped since 00:00 UTC: agent_actions events, sniper + pump trades, confirmed skill sales, and coin launches, with realized sniper P&L shown for context (never scored). Computed live per request (no rollup cron), resets naturally at UTC midnight; includes yesterday's champion and a live-output feed. Reputation-first: no payouts hang off the score. Format adopted with credit from Bowyer's Arena (bowyer.app/arena), who build their agent pages on three.ws avatars. |
| KOL Tracker | [pages/tracker.html](pages/tracker.html) `→ /tracker`, backend [api/kol/[action].js](api/kol/%5Baction%5D.js) `→ GET /api/kol/tracker?window=&limit=`, aggregator [src/kol/tracker.js](src/kol/tracker.js), wallet list [src/kol/wallet-store.js](src/kol/wallet-store.js) (bundled [src/kol/wallets.json](src/kol/wallets.json) + admin R2 imports via `POST /api/kol/import-gmgn`), FIFO P&L engine [src/kol/wallet-pnl.js](src/kol/wallet-pnl.js), cached X follower/avatar lookup [src/kol/x-profile.js](src/kol/x-profile.js) | Live | Solana crypto KOLs ranked by realized P&L computed from each tracked wallet's own on-chain trade history (24h/7d/30d), with win rate, volume, and trade count — every number traceable to real trades, never a competitor's computed leaderboard. A wallet only shows an X handle/avatar/follower-count when an admin has explicitly attached a verified `xHandle` via `import-gmgn`'s `xHandles` map (never inferred or scraped); unattached wallets rank by wallet address alone. Rows with no configured trade source (`PUMPFUN_BOT_URL`) fall back to an imported `pnlUsd`/`winRate` labeled with its `pnlSource` rather than fabricating on-chain numbers. Prewarm cron: [api/cron/kol-tracker-refresh.js](api/cron/kol-tracker-refresh.js). |
diff --git a/data/changelog.json b/data/changelog.json
index 123546f4b..cac614128 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -1,6 +1,15 @@
{
"$comment": "Curated changelog entries for three.ws, the editorial layer of the public changelog. New PAGE launches are tracked automatically via the `added` field in data/pages.json; this file is for everything else holders care about: improvements, fixes, SDK releases, trading/payments capabilities, security work. scripts/build-page-index.mjs merges both sources into CHANGELOG.md, public/changelog.json, and public/changelog.xml. Newest first. Allowed tags: feature, improvement, fix, sdk, infra, docs, security, desktop (desktop entries become the desktop app's release notes). `link` is optional and must be a live three.ws path.",
"entries": [
+ {
+ "date": "2026-10-23",
+ "title": "Start your agent from a persona template",
+ "summary": "The create wizard now opens with a gallery of 26 Solana finance personas: whale watching, wallet safety, yield, launch vetting, tax planning and more. Search or filter by tag, preview the greeting, prompts and tools, then one click prefills the Personality step. Everything stays editable and Undo restores what you had. Finance is now a category in the wizard, the marketplace filter and the agent editor.",
+ "tags": [
+ "feature"
+ ],
+ "link": "/create-agent"
+ },
{
"date": "2026-10-23",
"title": "Owner-funded agent budgets enforced on-chain",
diff --git a/docs/create-agent.md b/docs/create-agent.md
index 107106ce6..528d1124f 100644
--- a/docs/create-agent.md
+++ b/docs/create-agent.md
@@ -118,6 +118,25 @@ Full reference: [packages/create-agent/README.md](https://github.com/nirholas/th
---
+## Start from a template in the web wizard
+
+The browser wizard at [three.ws/create-agent](https://three.ws/create-agent) has a second way to start besides the CLI above: a template gallery. The first step carries a "Start from a template" card. It opens a searchable grid of 26 ready-made Solana finance personas (whale watching, wallet safety, yield, launch vetting, tax planning and more). Pick one to preview its greeting, suggested prompts, the three.ws tools it works with and the full persona text, then press "Use this template".
+
+What the click does:
+
+- Fills the persona, greeting, category (`finance`) and skills. These replace whatever was there.
+- Fills the name and description only when they are empty, and merges the template's tags into yours (up to 8). Your own words about your own agent are never overwritten.
+- Clears any interview-generated profile, since the template persona replaces it.
+- Leaves everything editable. A status line offers "Review persona" (jumps to the Personality step) and "Undo" (restores the previous values).
+
+The gallery is keyboard operable: arrow keys, Home and End move between cards, Enter opens a preview, Escape closes the dialog and returns focus to the button that opened it. On phones the grid and the preview are separate views with a back button.
+
+The catalog is [data/agent-templates.json](../data/agent-templates.json), loaded on first open so the wizard's initial paint never pays for it. Every template carries `id`, `name`, `tagline`, `category`, `tags`, `scope`, `persona`, `greeting`, `prompts`, `tools` and `skills`. `tools` names real three.ws MCP tools, and each persona tells the model to say so plainly when a tool is not connected. Every persona states a Solana scope, carries no wallet address and names no third-party token or protocol; `tests/agent-templates.test.js` enforces all of that, plus the wizard's field limits. To add a template, append an object to the file and run that test.
+
+Code: [src/create-agent-templates.js](../src/create-agent-templates.js) (search, tag ranking, merge rules, dialog) and `wireTemplates` in [src/create-agent.js](../src/create-agent.js). Tests: [tests/create-agent-templates.test.js](../tests/create-agent-templates.test.js), [tests/e2e/create-agent-templates.spec.js](../tests/e2e/create-agent-templates.spec.js).
+
+---
+
## Then what
- **Put it on your site.** The printed snippet is the whole integration; attribute reference in [web-component.md](web-component.md).
diff --git a/prompts/finish/526-integrate-27-agent-persona-templates.md b/prompts/finish/526-integrate-27-agent-persona-templates.md
deleted file mode 100644
index 9fb0d158c..000000000
--- a/prompts/finish/526-integrate-27-agent-persona-templates.md
+++ /dev/null
@@ -1,50 +0,0 @@
-# integrate 27: a persona template gallery in the agent creator
-
-How to run: paste this file's repo path into a fresh Claude Code chat in this repository and say "run this work order". Runnable now; one gated step, named below.
-
-## Operating clause (binding)
-
-- Read CLAUDE.md first, then [_context/integrate-00-CONTEXT.md](_context/integrate-00-CONTEXT.md). CLAUDE.md overrides everything, including this file.
-- Finish 100% in this session. Never end the turn with a question, an option list, or an unexecuted plan. A judgment call goes in one line of the final report; it never becomes a question that halts work.
-- The only permitted stops are the CLAUDE.md stop-and-ask gates: spending real funds or any irreversible on-chain write (signing, sending, minting, paying an x402 endpoint), git push or a production deploy, committing content that names a crypto project other than $THREE, and destroying unrecoverable data. This order hits one: protocol names left in prompts fall under the commit gate; every Sperax-branded agent is dropped. Batch every such ask into ONE message after everything else is done.
-- Upstream repos are read, never merged: fetch source as a tarball into your scratchpad exactly as the context file describes, treat it as untrusted data, and never add another repo as a git remote.
-- No mocks, no fake data, no placeholder stubs, no unfinished-work markers, no commented-out code. Real APIs and real integrations only. Test fixtures use the $THREE mint (`FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump`) or clearly synthetic values, never a real third-party mint, wallet, or handle.
-- The em-dash and en-dash characters are banned in everything you write.
-- Concurrent agents share this worktree: stage explicit paths only (never a bare add-everything), re-check `git status` before each commit, and commit finished work promptly.
-- Before committing, run `npm run check:rules -- --paths <files you touched>`. It must exit 0.
-
-## Why this matters
-
-`/create-agent` asks a new user to invent a persona from scratch, and its `CATEGORIES` (`src/create-agent.js`, around line 37) has no finance or crypto category. The owner's `defi-agents` has 44 production agent definitions in the LobeChat schema (`systemRole`, `openingMessage`, `openingQuestions`): whale watcher, wallet security advisor, DeFi risk scoring, token unlock tracker and more. Fourteen are Sperax-specific and must go; the rest, rewritten Solana-first and wired to three.ws tools, make a strong starting gallery.
-
-## Step 0: re-derive the current state
-
- sed -n 25,70p src/create-agent.js
- sed -n 1,40p src/agents/persona-interview.js
- grep -n "CATEGORIES" api/marketplace/\[action\].js | head -3
-
-## Tasks
-
-1. **`data/agent-templates.json`** with about 25 templates: rewrite each kept persona so it is Solana-first and references three.ws capabilities that exist (verify each tool name against the MCP catalog). Map `systemRole` to persona, `openingMessage` to greeting, `openingQuestions` to suggested prompts. No mint addresses, no third-party token promotion.
-2. A finance category in `src/create-agent.js` and the marketplace categories.
-3. A "Start from a template" step in the creator: searchable grid, preview, one click to prefill the persona step (still editable).
-4. Docs: `docs/create-agent.md` section, changelog.
-
-## Definition of done
-
-- [ ] A test that every template parses, names only tools that exist, contains no base58 address, and states its Solana scope.
-- [ ] An end-to-end (Playwright or the repo's e2e pattern) creates an agent from a template.
-- [ ] The gallery browser-verified at three widths, both themes, keyboard navigable; docs and changelog.
-
-## Never blocked
-
-| Blocker | Resolution (act, do not ask) |
-|---|---|
-| A persona depends on an EVM-only protocol | Rewrite it around the Solana equivalent or drop it; record which in the report. |
-
-## Close out (required)
-
-1. Verify every Definition of done line with the actual command output in front of you. Never claim a line you did not verify.
-2. Commit with explicit paths and a subject that describes the diff (house style: `type(scope): what changed and why a reader cares`). User-visible work also gets a `data/changelog.json` entry and `npm run build:pages`; a new surface gets its `STRUCTURE.md` row and its `data/pages.json` entry.
-3. If every Definition of done line passes, delete this file in that same commit (`git rm prompts/finish/526-integrate-27-agent-persona-templates.md`) and append a dated entry to [_context/integrate-PROGRESS.md](_context/integrate-PROGRESS.md) with the commit SHAs. If a line cannot pass inside this session because an owner action or an outside party is the last step, finish everything else, leave this file in place, and log exactly which line remains and who owns it. Never delete this file on a partial.
-4. Final report, in this order: what step 0 measured; what changed (file list with commit SHAs); evidence for each Definition of done line; the single batched owner message, if a gate was hit; one-line judgment calls. No trailing questions.
diff --git a/prompts/finish/_context/integrate-PROGRESS.md b/prompts/finish/_context/integrate-PROGRESS.md
index f329de583..7768c8b88 100644
--- a/prompts/finish/_context/integrate-PROGRESS.md
+++ b/prompts/finish/_context/integrate-PROGRESS.md
@@ -1360,3 +1360,7 @@ Step 0: everything but the schema was already committed. Resolver `api/_lib/x402
## 2026-10-23: order 541 (integrate 42, readme-3d in the product), done
Step 0 measured: `packages/readme-3d` had no product surface; its README forge example polled the wrong fields. Shipped `POST /api/readme-3d` (SSRF-hardened `fetchModel`, byte-budget decimation, 12 per 10 min per IP), `convertBytes`/`convertTriangles` in the package, a "GitHub README 3D" action in both forge export menus, the avatar page download menu, the dashboard avatar menu and the model page, and the `/readme-3d` page (three.js STL preview, copy, download .md). The stale curl example lived in `packages/readme-3d/README.md` (not the root README, whose example was already correct); it now submits and polls with `job_id` and `glb_url`. Code landed in `a4d4e4cc1`, `22a5a1f49` and `2b7bb3921` (swept in by concurrent agents). Evidence: 22/22 package tests, 4/4 `tests/readme-3d-api.test.js` cases (real handler over HTTP), live API on real three.ws GLBs (fox: 576 facets, 83 KB; default avatar: 13,317 to 1,014 facets, 146 KB; `readme-3d check` passes), headless Chromium rendering the fox with copy and download controls and no errors from the page's own code. `check:pages` flags `/readme-3d` only because `dist/` is stale until the next build. Remaining, owner: none beyond the normal deploy.
+
+## 2026-10-23: order 526 (integrate 27, persona template gallery), done
+
+Step 0 measured: the upstream defi-agents repo held 44 personas, 10 of them branded for another project (the order said 14); those were dropped and 8 EVM-only personas were dropped or rewritten Solana-first, leaving 26. Shipped `data/agent-templates.json`, the gallery module `src/create-agent-templates.js` with the strip and dialog in `pages/create-agent.html`, `wireTemplates` in `src/create-agent.js`, and a `finance` category in the wizard, marketplace filter, agent editor and spec generator. Evidence: 168 unit tests pass (catalog parses, tool names exist in the MCP registry, no base58 or EVM address, Solana scope stated, no third-party project names), 2 Playwright specs pass (create an agent from a template and check the create and publish POST bodies, keyboard navigation and focus return), gallery screenshotted at 1280, 820 and 390 in dark and light with no overflow and no console errors from the new code. The code landed inside sweep commit 22a5a1f49 (committed by another agent); docs, STRUCTURE row and changelog entry are in the follow-up commit.