Skip to content

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

feat(spotlight): seed the community showcase and fix a decay curve that made trending mean newest

nirholas0dabfccd739d
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7e68e7332..387f1fa01 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,8 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr
- **3D Drops** (`/drops`): Launch a supply-capped collection of AI-forged 3D characters. Pick a style, define weighted trait layers, and three.ws rolls the whole supply from a published seed: verifiable rarity, rigged animation-ready art, forged on reveal.
- **3D Drops** (`/docs/drops`): How generative 3D collections work on three.ws: weighted trait layers, a supply rolled from a published seed, rarity scored from the actual distribution, art forged per item on reveal, and a verify endpoint anyone can recompute the roll with.
+- **Agent Spotlight** (`/spotlight`): The three.ws community showcase: agents people actually built something with, written up by the builder and ranked by community upvotes. Filter by category, open any entry in 3D, upvote what you like, and submit your own.
+- **Docs · Agent Spotlight** (`/docs/spotlight`): How the Agent Spotlight community showcase works: what an entry stores versus what it reads live off the agent, the trending decay formula, curated versus community entries, and the full showcase API.
- **Filming three.ws on a Seeker without a Seeker** (`/docs/seeker-video`): How to record a Seeker screen recording of the app with no device: why the Trusted Web Activity makes a browser capture at the real panel geometry a genuine capture, and which moments still have to come from an Android emulator.
- **Page performance: the rules a three.ws page plays by** (`/docs/page-performance`): How three.ws keeps real 3D on ordinary pages without making them slow: previews that spin only while someone is looking, models that load when they are wanted, boxes reserved before late content arrives, and images fetched at the size they are shown.
- **$THREE tiers page: the ladder now loads for everyone, signed in or not**: Opening /three without a wallet connected or an account signed in showed an error card instead of the tiers, because the tier lookup refused anonymous requests. The page now shows every tier, its perks, and the exact $THREE threshold to any visitor, with a connect-wallet or sign-in prompt to see your own position. Signed-in accounts without a linked wallet get a clear prompt to connect one, and if the ladder genuinely fails to load the page keeps its heading and offers a retry. (`/three`) `[fix]`
@@ -26,6 +28,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr
- **Stablecoins page: a clear message and a one-click retry when the feed is down**: When DeFiLlama cannot be reached, /stablecoins now says so in plain words and offers a Try again button that refetches in place, instead of a reload link over blank stat cards. An empty answer from the feed gets its own message rather than $0.00 cards. When the page is showing the last good copy because the live feed is unreachable, the footer line says so, and the "updated" time no longer flickers back to a static label after the language pass runs. The page title and description now spell out what the board covers: market cap, peg health, backing mechanism, and chains. (`/stablecoins`) `[fix, improvement]`
- **Strategy Lab backtests and simulated runs find real launches again**: In production, every Strategy Lab backtest and simulated session was scanning for candidates and coming back empty: the server-side strategy runtime was asking for pump.fun data with a page-relative address that only a browser can resolve, and the discovery tools behind it needed an indexer the platform never configured. The runtime now calls the pump.fun tools directly in-process, and the new-launch and trending scans read the live pump.fun feed with the platform's own launch recorder as backup, so a scan returns real mints on the first tick. The Lab page also tells a signed-out visitor exactly what signing in unlocks, links straight to it, shows a live "session running" state while a run streams, and explains a quiet session (every candidate filtered out, or the feed briefly unreachable) instead of a bare "complete". (`/strategy-lab`) `[fix, improvement]`
- **Strategy Objects: signed-out visitors are sent to sign in instead of a half-open builder, and the view switcher is keyboard-visible**: On /strategies, Equip, Fork, and New strategy now take a signed-out visitor straight to sign-in and bring them back to the page afterwards. Before, the page treated everyone as signed in, so the equip picker and the strategy builder opened for visitors who could not use them and Fork failed silently. The My library tab now shows its sign-in prompt without firing a request that could only fail, the Marketplace, Leaderboard, and My library switcher shows a visible focus ring when tabbed to and is announced correctly by screen readers, and the browser tab reads Strategy Objects. (`/strategies`) `[fix, improvement]`
+- **The community showcase is open**: Agent Spotlight is live at /spotlight. The agents index lists everything anyone ever registered, which is thousands of agents and no way to tell which ones are actually good. The spotlight is the other half of that: you write up what your agent does, everyone else upvotes what they like, and the best work rises. Filter by category, search across write-ups and builders, and open any entry straight into the agent's 3D page to talk to it. Entries stay honest by construction: your card stores your pitch and reads the agent's live name, avatar, skills and on-chain identity on every visit, so it can never go stale. One entry per agent, one vote per person, and submitting again edits your entry instead of making a second card. It opens with fourteen agents the team picked out of what the community has already built, from an adversarial code reviewer to an autonomous Solana trader that runs with no language model in the loop. (`/spotlight`) `[feature]`
- **The Story So Far loads again, and catches up to the Android launch**: The 3D history timeline at /timeline had been opening on its error screen in production since it shipped: the page itself was there, but the file holding the milestones never made it into the deployed build, so every visitor was told to check their connection. The file now ships with every build, and a build without it is refused before it can deploy. While there, the timeline gained the milestones since late July, from the first Hugging Face article to the Android app, the Glance home-screen card, and the CoinMarketCap coverage, each with a link to its source. The floating walk companion no longer parks itself on top of the auto-play button, keyboard users get visible focus rings on every control, and the closed detail panel stays out of the tab order. (`/timeline`) `[fix, improvement]`
- **three.ws is on the Solana dApp Store**: The Seeker app is live. Open the dApp Store on a Seeker or Saga, search three.ws, and install it: a 3D agent studio that runs full-screen on the phone. Take a selfie and get a textured, rigged, animation-ready character in about a minute, or describe one in text, or upload a GLB you already have. Give it a personality, a voice and skills, then talk to it in 3D. Browse everyone else's agents in the marketplace, and deploy your own on-chain as a Metaplex Core asset your wallet holds. Every signature routes to the phone's Seed Vault through Mobile Wallet Adapter, so signing in is one tap and the private key never enters the app. Creating, chatting and browsing are free. Anything you make on the phone is waiting on the web app the moment you sign in there. (`/docs/seeker-app`) `[feature]`
- **Widget Studio: an honest preview status, copy that works in every browser, and clearer errors**: On /studio the preview status line now stays in sync with the preview: it no longer snaps back to "Pick an avatar to preview" after the language pass runs, and when an avatar's model cannot be fetched it says so and disables camera capture instead of reporting a live preview over an error screen. Copy buttons fall back to the browser's built-in copy when the clipboard API is denied, so the snippet lands on the clipboard in embedded and in-app browsers too. A failed public-avatar search explains what happened and how to retry, the search box and the script-tag snippet are labelled for screen readers, and the page description now matches what the studio does. (`/studio`) `[fix, improvement]`
diff --git a/STRUCTURE.md b/STRUCTURE.md
index 5e35660e6..974a21a4b 100644
--- a/STRUCTURE.md
+++ b/STRUCTURE.md
@@ -122,6 +122,7 @@ bottom.
| Home page event strip (`/`) | Self-attaching module [src/home-event-banner.js](src/home-event-banner.js) loaded by [pages/home.html](pages/home.html); same config `public/event.json` through [src/shared/event-config.js](src/shared/event-config.js) | Live | Puts the live event in front of everyone who lands on three.ws, not just the people who already opened `/play`. A slim announcement bar between the nav and the hero: event name, start time in the visitor's own timezone, a countdown ticking to the second, and one CTA into the $THREE world (suppressed when the visitor is already there). Same three states as the `/play` surfaces and the same auto-unmount at `endsAt`, flipping upcoming to live without a reload. Dismissal shares the `/play` pill's `cc-event-dismissed:<startsAt>` key, so waving the reminder away on the home page also clears it in-world; the `/play` lobby banner stays, because it is lobby content rather than an overlay. Styled from the home page's own tokens (mono kicker, hairline pill CTA) and light-theme aware. Verified with `npm run verify:event`. |
| `/play` friends, presence & verified profiles (drawer, cross-world DMs, in-world profile cards) | Client: [src/game/friends-panel.js](src/game/friends-panel.js) (shared with `/walk`), mounted in [src/game/coincommunities.js](src/game/coincommunities.js) `_openFriends()`/`_closeFriends()`, HUD button + unread badge in [src/game/coincommunities-ui.js](src/game/coincommunities-ui.js), account-level state/polling in [src/friends.js](src/friends.js), profile card in the shared inspector [src/shared/avatar-inspector.js](src/shared/avatar-inspector.js) (`renderProfile`). Server: signed ticket verify + `socialHub` registration + verified `username` on the Player schema in [multiplayer/src/rooms/WalkRoom.js](multiplayer/src/rooms/WalkRoom.js) + [multiplayer/src/schemas.js](multiplayer/src/schemas.js), ticket signer [api/_lib/presence-store.js](api/_lib/presence-store.js) / verifier [multiplayer/src/presence-token.js](multiplayer/src/presence-token.js), hub in [multiplayer/src/social-hub.js](multiplayer/src/social-hub.js) | In-repo | W09+W10 of the World Online program (program brief retired to git history). Press `J` or the HUD `Friends` button to open a right-docked drawer showing your account's friend graph; live online/offline presence per coin world, requests, and DM threads; the same graph and threads `/walk` and the standalone `/friends` page already share. `community-net.js` carries a signed presence ticket into every `walk_world` join and forwards the server's `social` push onto its own event bus, which is what makes a `/play` player visible to friends and able to receive a live DM. W10 makes the platform identity first-class in-world: the ticket also carries the account's username + display name (signed, so nobody can wear a handle they don't own), WalkRoom publishes the verified `username` on the Player schema, nameplates show the @handle, the signed-in lobby defaults to the account's display name with an @handle chip, and clicking any verified player (or `I`) opens their real three.ws profile card in the shared avatar inspector: bio, follower counts, follow/unfollow (`/api/users/:username/follow`), the right friends verb (Message → the in-world DM drawer when already friends, Add friend / Accept otherwise), their latest creations, and a link to `/u/<username>`. Works identically in `/walk` (same room, same inspector). Tests: [tests/play-friends-presence.test.js](tests/play-friends-presence.test.js), [tests/play-profile-identity.test.js](tests/play-profile-identity.test.js). |
| Crew HQ (crews, tags, 3D presence room) | Page [pages/crews.html](pages/crews.html) + [src/crews-page.js](src/crews-page.js) + [src/crews.css](src/crews.css) `→ /crews` and `/crews/<TAG>`, data layer [api/_lib/crews-store.js](api/_lib/crews-store.js), endpoints [api/crews/](api/crews) (`index.js`, `[tag].js`, `search.js`, `directory.js`), presence [api/_lib/presence-store.js](api/_lib/presence-store.js), schema `api/_lib/migrations/2026-06-05-crews.sql` | Live | The group half of the social system: a crew is a set of accounts flying one 2-6 character tag, with one owner, one crew per account, and a public headquarters. The HQ renders the roster as a room rather than a list, each member standing as their own agent's 3D avatar (resolved by `standeesFor()`, private models never emitted) and lit by the same Redis presence the friends drawer reads. Crew colour is an FNV-1a hash of the tag, so a crew looks like itself everywhere without stored art. Live `<agent-3d>` figures are capped and lazily mounted so a large crew cannot exhaust the browser's WebGL contexts. The backend shipped with W09 and had no UI at all until this page; the in-world friends drawer now links to it. Docs: [docs/crews.md](docs/crews.md). Tests: [tests/crews-shared.test.js](tests/crews-shared.test.js), [tests/crews-wiring.test.js](tests/crews-wiring.test.js) |
+| Agent Spotlight (community showcase) | Page [pages/spotlight.html](pages/spotlight.html) + [src/spotlight.js](src/spotlight.js) + [src/spotlight.css](src/spotlight.css) `→ /spotlight`, HTTP boundary [api/showcase/[action].js](api/showcase), queries + ranking [api/_lib/showcase-store.js](api/_lib/showcase-store.js), schema `api/_lib/migrations/20260901160000_agent_showcase.sql`, curated seed [scripts/seed-showcase.mjs](scripts/seed-showcase.mjs) | Live | The curated half of `/agents`: the index lists every agent ever registered, this lists the ones a person wrote up and the community voted on. An entry stores the pitch only (headline, one-liner, write-up, category, tags, demo link); the agent's name, avatar, skills, on-chain identity, conversation count and builder are read live off `agent_identities` on every request, so a card can never drift from the agent it points at. Ranked by `(votes + 1) / (age_days + 1) ^ 1.2`, computed identically in JS and in the SQL `ORDER BY`; the `+ 1` keeps a brand-new entry on the first page, and the day scale (rather than the hour scale every feed copies from Hacker News) is what stops a low-volume board's `trending` from collapsing into `newest`. One entry per agent (re-submitting edits it), one vote per account, votes counted on read rather than denormalised. Entries badged `Curated` were written by three.ws about someone else's public agent and are replaced the moment that builder submits their own. Docs: [docs/spotlight.md](docs/spotlight.md). Tests: [tests/showcase-ranking.test.js](tests/showcase-ranking.test.js) |
| `/play` Robinhood Chain worlds (NOXA + The Odyssey coins, live-trade animation) | Firehose worker [workers/robinhood-feed/](workers/robinhood-feed) (watches NOXA + Odyssey launchpads + their Uniswap v3 pools, normalizes to the pump-compatible event shape, serves SSE/WS/REST). API bridge: [api/robinhood/coin-trades.js](api/robinhood/coin-trades.js) (the in-world chart-screen's trade feed), [api/robinhood/play-worlds.js](api/robinhood/play-worlds.js) (the `/worlds` lobby's Robinhood Chain tab). Client: chain-flavored biome `hoodchain` in [src/game/world-env.js](src/game/world-env.js) (auto-pinned in [src/game/coincommunities.js](src/game/coincommunities.js) `isRobinhoodCoin()`), trade-feed endpoint routing in [src/game/chart-screen.js](src/game/chart-screen.js), lobby tab + EVM-address support in [src/worlds-lobby.js](src/worlds-lobby.js) (routes Robinhood coins to `/play`, unchanged pump.fun coins stay on `/temporary`) | In-repo | Every Robinhood Chain memecoin (chain 4663) gets the same treatment pump.fun coins already have: a deterministic 3D world seeded by its contract address, in a distinct dark ticker-tape palette, with real launchpad/Uniswap-v3 trades rippling the space live via `MarketReactor`. Multiplayer (`walk_world`, filtered by `coin`+`tier`) needed zero code changes — it already keys rooms by an opaque coin id string. `isValidToken()` in [api/_lib/coin-communities.js](api/_lib/coin-communities.js) was widened to accept EVM addresses (it previously 400'd every EVM-chain world's Town chat, even though the CHAINS list already declared ethereum/base/bsc support). Tests: [workers/robinhood-feed/tests/normalize.test.js](workers/robinhood-feed/tests/normalize.test.js) (against real captured on-chain logs). |
| Sealed wallet gift drops (send/claim) | Client: [src/pages/sealed-drops.js](src/pages/sealed-drops.js) — create + "My drops" sections mounted into [public/vanity-wallet.html](public/vanity-wallet.html) (`#drop-create`/`#drop-mine`, below the vanity grinder — vanity pattern fields are shared), claim flow on its own page [pages/drop.html](pages/drop.html) `→ /drop/:id` (24-hex-char id, routed in [vite.config.js](vite.config.js) dev middleware + [vercel.json](vercel.json)). Crypto: [src/solana/vanity/sealed-envelope.js](src/solana/vanity/sealed-envelope.js) (ECIES seal/open, X25519 keygen — all client-side, three.ws never sees a plaintext key), [src/solana/vanity/drop-protocol.js](src/solana/vanity/drop-protocol.js) (claim-token derivation). Server: [api/vanity/drops.js](api/vanity/drops.js) (create/claim/reveal/reclaim, on-chain funding), OG card [api/og/sealed-drop.js](api/og/sealed-drop.js) | In-repo | Fund a fresh wallet — optionally vanity-ground with the same prefix/suffix grinder above — wrap it in a sealed link, and send it. Two seal modes: a **bearer link** (the claim key rides in the URL fragment, anyone with the full link claims once) or **sealed to a recipient's X25519 key** (only they can ever open it, even with the link). The create fee settles via x402; the gift amount funds on-chain into a fresh wallet server-side. Claiming decrypts entirely in the browser and offers the recovered seed phrase/secret key for import — the server only ever sees the sealed ciphertext. "My drops" (browser-local, by a random sender tag) lists what you've sent so expired-unclaimed gifts can be reclaimed. |
| Premium vanity inventory (sell pre-ground addresses) | [public/vanity/premium/](public/vanity/premium/index.html) `→ /vanity/premium`, batch grinder [workers/vanity-grinder/](workers/vanity-grinder), store [api/_lib/vanity-inventory-store.js](api/_lib/vanity-inventory-store.js), sell [api/x402/vanity-premium.js](api/x402/vanity-premium.js), replenish [api/cron/vanity-inventory-replenish.js](api/cron/vanity-inventory-replenish.js) | In-repo · GCP spot CPU | Long (4–5+ char) brandable Solana addresses ground ahead of time on cheap spot CPU, sealed at rest (AES-256-GCM or GCP-KMS envelope, [api/_lib/vanity-vault.js](api/_lib/vanity-vault.js)), and sold from stock via x402 — priced by rarity ($1–$50) on `vanity-premium`, or by fixed 4–5 char tiers ($2.50/$10) directly through [`/api/x402/vanity`](docs/vanity.md#tier-1--live-grinder) (instant delivery, `source:"inventory"`) and the [pump-launch vanity upsell](docs/pump-launcher.md) — delivered exactly once, ciphertext destroyed on delivery. An hourly cron watches stock and fires a fresh grind batch (Cloud Run Job) when low. Free `vanity_premium` MCP browse tool. Runbook: [docs/ops/gcp-credits.md](docs/ops/gcp-credits.md) |
diff --git a/api/_lib/showcase-store.js b/api/_lib/showcase-store.js
index 0fe7c0246..006429dec 100644
--- a/api/_lib/showcase-store.js
+++ b/api/_lib/showcase-store.js
@@ -40,20 +40,30 @@ export function showcaseConfigured() {
/* ── ranking ──────────────────────────────────────────────────────────────── */
-// Hacker-News-shaped decay: score = (votes + 1) / (age_hours + 2)^1.5.
+// Decay: score = (votes + 1) / (age_days + 1)^1.2.
//
-// The +1 is what makes this a showcase rather than a popularity contest: a
-// just-published entry with no votes yet still outranks a week-old entry with
-// two, so the newest work is seen at all. The exponent is the knob for how fast
-// yesterday's entries fall off; 1.5 puts a 24-hour-old entry at roughly a fifth
-// of the weight of a fresh one, which keeps a full first page turning over
-// daily at the volume this surface sees.
-export const GRAVITY = 1.5;
+// Two deliberate choices, both about the fact that this is a low-volume curated
+// board and not a firehose.
+//
+// The +1 in the numerator is what makes it a showcase rather than a popularity
+// contest: an entry published minutes ago with no votes yet still scores 1.0 and
+// lands on the first page, so new work is seen at all instead of waiting behind
+// whatever was already popular.
+//
+// The clock runs in DAYS, not hours. The hour-scaled decay every ranked feed
+// copies from Hacker News assumes enough vote volume that a good post
+// accumulates score faster than it loses it within a day; at this surface's
+// volume the same curve puts a 24-hour-old entry at ~2% of a fresh one, which
+// collapses "trending" into "newest" and buries genuinely popular work overnight.
+// On this curve a week-old entry with twenty upvotes still outranks a brand-new
+// one, and a month-old entry finally rotates off the front. That is the behaviour
+// a showcase wants: durable good work near the top, always room for the newest.
+export const GRAVITY = 1.2;
export function trendingScore({ voteCount = 0, createdAt, now = Date.now() } = {}) {
const ms = now - new Date(createdAt).getTime();
- const ageHours = Number.isFinite(ms) ? Math.max(0, ms) / 3_600_000 : 0;
- return (Number(voteCount) + 1) / Math.pow(ageHours + 2, GRAVITY);
+ const ageDays = Number.isFinite(ms) ? Math.max(0, ms) / 86_400_000 : 0;
+ return (Number(voteCount) + 1) / Math.pow(ageDays + 1, GRAVITY);
}
/* ── shaping ──────────────────────────────────────────────────────────────── */
@@ -197,7 +207,7 @@ export async function listEntries({
case when ${sort}::text = 'top' then coalesce(v.n, 0) end desc nulls last,
case when ${sort}::text = 'trending'
then (coalesce(v.n, 0) + 1)::numeric
- / power(extract(epoch from (now() - s.created_at))::numeric / 3600.0 + 2, ${GRAVITY}::numeric)
+ / power(extract(epoch from (now() - s.created_at))::numeric / 86400.0 + 1, ${GRAVITY}::numeric)
end desc nulls last,
s.created_at desc
limit ${limit} offset ${offset}
diff --git a/data/changelog.json b/data/changelog.json
index 2be65feac..07ef11bf5 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. `link` is optional and must be a live three.ws path.",
"entries": [
+ {
+ "date": "2026-09-01",
+ "title": "The community showcase is open",
+ "summary": "Agent Spotlight is live at /spotlight. The agents index lists everything anyone ever registered, which is thousands of agents and no way to tell which ones are actually good. The spotlight is the other half of that: you write up what your agent does, everyone else upvotes what they like, and the best work rises. Filter by category, search across write-ups and builders, and open any entry straight into the agent's 3D page to talk to it. Entries stay honest by construction: your card stores your pitch and reads the agent's live name, avatar, skills and on-chain identity on every visit, so it can never go stale. One entry per agent, one vote per person, and submitting again edits your entry instead of making a second card. It opens with fourteen agents the team picked out of what the community has already built, from an adversarial code reviewer to an autonomous Solana trader that runs with no language model in the loop.",
+ "tags": [
+ "feature"
+ ],
+ "link": "/spotlight"
+ },
{
"date": "2026-09-01",
"title": "three.ws is on the Solana dApp Store",
diff --git a/data/pages.json b/data/pages.json
index 4215ce53a..b50963263 100644
--- a/data/pages.json
+++ b/data/pages.json
@@ -2765,6 +2765,14 @@
"changefreq": "weekly",
"added": "2026-08-01"
},
+ {
+ "path": "/docs/spotlight",
+ "title": "Docs \u00b7 Agent Spotlight",
+ "description": "How the Agent Spotlight community showcase works: what an entry stores versus what it reads live off the agent, the trending decay formula, curated versus community entries, and the full showcase API.",
+ "priority": 0.6,
+ "changefreq": "weekly",
+ "added": "2026-09-01"
+ },
{
"path": "/docs/economy-solver",
"title": "Docs · The solved economy",
diff --git a/docs/spotlight.md b/docs/spotlight.md
new file mode 100644
index 000000000..ecd3bde89
--- /dev/null
+++ b/docs/spotlight.md
@@ -0,0 +1,219 @@
+# Agent Spotlight
+
+[**`/spotlight`**](https://three.ws/spotlight) is the three.ws community
+showcase. [`/agents`](https://three.ws/agents) is the directory: every agent
+anyone ever registered, which is thousands of rows and most of them still wearing
+the onboarding default name. The spotlight is the other half of that, the curated
+layer where a person says what an agent is for and the community votes on whether
+they were right.
+
+An entry is a **pitch attached to a live agent**, never a copy of it. The entry
+stores a headline, a one-liner, an optional write-up, a category, up to six tags
+and an optional demo link. Everything else on the card (the agent's name,
+description, skills, avatar, on-chain identity, conversation count and builder)
+is read from `agent_identities` on every request. Rename your agent, swap its
+avatar, register it on-chain: the card updates with it, and there is no stale
+copy to go wrong.
+
+## Submitting
+
+1. Make the agent public. Private agents are excluded: the showcase links
+ straight to `/agents/<id>` and an entry a visitor cannot open is worse than
+ no entry.
+2. Open `/spotlight`, click **Showcase your agent**, and pick it from the
+ dropdown. Only your own public agents that are not already showcased appear.
+3. Write the headline (3 to 90 characters) and the one-liner (10 to 160). The
+ one-liner is pre-filled from the agent's own description so you are editing
+ rather than starting from nothing.
+4. Optional: a write-up of up to 4,000 characters, a demo link, and tags.
+
+**One entry per agent.** Submitting again for the same agent edits the entry you
+already have; it never creates a second card. You can remove your own entry at
+any time, and so can the agent's owner if someone else wrote it up.
+
+## Ranking
+
+Three sorts share one page.
+
+| Sort | What it orders by |
+| --- | --- |
+| **Trending** (default) | Upvotes with time decay, so new work is visible |
+| **Newest** | Publication time |
+| **Most upvoted** | Raw upvote count, all time |
+
+Trending decays with age:
+
+```
+score = (upvotes + 1) / (age_in_days + 1) ^ 1.2
+```
+
+Two things about that formula are deliberate.
+
+The `+ 1` in the numerator means an entry published five minutes ago with no
+votes still scores `1.0` and lands on the first page, so the newest submission is
+seen at all rather than buried under whatever was already popular.
+
+The clock runs in **days**, not hours. The hour-scaled version of this curve that
+every ranked feed copies from Hacker News assumes enough vote volume that a good
+post gains score faster than it loses it inside a day. At this surface's volume
+it does not: that curve puts a 24-hour-old entry at about 2% of a fresh one, so
+any brand-new empty entry outranks a week-old entry everybody liked, and
+"trending" quietly becomes "newest". On the day scale a day-old entry still
+carries a bit under half the weight of a fresh one, a week-old entry with twenty
+upvotes stays above a fresh empty one, and a month-old entry finally rotates off
+the front page. That is the behaviour a showcase wants: durable good work near
+the top, always room for the newest.
+
+The formula lives in one place,
+[`trendingScore()` in `api/_lib/showcase-store.js`](../api/_lib/showcase-store.js),
+and the SQL `ORDER BY` computes the identical expression so the server never
+disagrees with its own documentation.
+
+One upvote per account per entry, and voting again removes it. Votes are counted
+on read rather than stored as a running total, so a lost write can never leave a
+counter permanently wrong.
+
+## Curated entries
+
+Some entries carry a **Curated** badge. Those were written by three.ws about
+someone else's public agent, and the badge exists so a visitor is never told a
+builder said something they did not write. The builder is still credited from the
+agent record, and the moment they submit their own write-up for that agent it
+replaces the curated one and the badge goes away.
+
+Curated entries are seeded by
+[`scripts/seed-showcase.mjs`](../scripts/seed-showcase.mjs), which refuses to
+attach a write-up to an agent that has since been renamed, made private, or
+deleted:
+
+```bash
+node scripts/seed-showcase.mjs # dry run, reports what would land
+node scripts/seed-showcase.mjs --apply # write the entries
+```
+
+## Categories
+
+`trading`, `research`, `creative`, `productivity`, `developer`, `social`,
+`gaming`, `commerce`, `education`, `other`. The filter rail hides empty
+categories, so it shows what the community actually built rather than an
+aspirational taxonomy.
+
+## API
+
+Public reads, no key. Writes need a session cookie and a CSRF token, exactly like
+every other authenticated three.ws endpoint.
+
+### `GET /api/showcase/list`
+
+| Param | Default | Notes |
+| --- | --- | --- |
+| `sort` | `trending` | `trending`, `new`, `top` |
+| `category` | none | One of the category slugs above |
+| `tag` | none | Single tag |
+| `q` | none | Full-text over headline, one-liner, write-up, agent name and description |
+| `limit` | `24` | Max 48 |
+| `offset` | `0` | Offset pagination |
+| `featured` | off | `1` returns only the editor's picks |
+
+```bash
+curl -s 'https://three.ws/api/showcase/list?sort=top&limit=3' | jq '.entries[].title'
+```
+
+```json
+{
+ "entries": [
+ {
+ "id": "…",
+ "title": "A sniper with no language model anywhere in the loop",
+ "tagline": "It trades the conviction oracle on a fixed stake…",
+ "category": "trading",
+ "tags": ["solana", "autonomous", "oracle"],
+ "source": "curated",
+ "vote_count": 0,
+ "voted_by_me": false,
+ "trending_score": 1.0,
+ "agent": {
+ "id": "…",
+ "name": "Crosshair",
+ "url": "/agents/…",
+ "thumbnail": "https://…/thumb/….png",
+ "glb_url": "https://…/….glb",
+ "chat_count": 2,
+ "is_registered": true
+ },
+ "builder": { "name": "…", "profile_url": null }
+ }
+ ],
+ "total": 14,
+ "has_more": false
+}
+```
+
+A signed-in read is personalised (`voted_by_me`) and returns
+`Cache-Control: private, no-store`; an anonymous read is identical for everyone
+and is CDN-cached for 30 seconds.
+
+### `GET /api/showcase/get?id=<uuid>`
+
+One entry, in the same shape, plus a view count bump.
+
+### `GET /api/showcase/categories`
+
+Per-category counts plus the headline totals the hero renders
+(`{ entries, builders, votes }`).
+
+### `GET /api/showcase/eligible`
+
+Session required. The caller's public agents that are not already showcased,
+plus the category list, which is what the submission form is built from.
+
+### `POST /api/showcase/submit`
+
+Session + CSRF. Body:
+
+```json
+{
+ "agentId": "uuid of an agent you own",
+ "title": "3 to 90 characters",
+ "tagline": "10 to 160 characters",
+ "story": "up to 4000 characters, optional",
+ "demoUrl": "https://… (http or https only, optional)",
+ "category": "trading",
+ "tags": ["solana", "autonomous"]
+}
+```
+
+Returns the created or updated entry. `403` if the agent is not yours, `409` if
+it is not public.
+
+### `POST /api/showcase/vote`
+
+Session + CSRF. Body `{ "id": "<entry uuid>" }`. Toggles, and returns the
+server-confirmed state so the button never settles on an optimistic guess:
+
+```json
+{ "voted": true, "vote_count": 12 }
+```
+
+### `POST /api/showcase/remove`
+
+Session + CSRF. Body `{ "id": "<entry uuid>" }`. Soft-deletes the entry. Allowed
+for the submitter and for the agent's owner.
+
+## Where the code lives
+
+| Piece | File |
+| --- | --- |
+| Page shell | [`pages/spotlight.html`](../pages/spotlight.html) |
+| Controller | [`src/spotlight.js`](../src/spotlight.js) |
+| Styles | [`src/spotlight.css`](../src/spotlight.css) |
+| HTTP boundary | [`api/showcase/[action].js`](../api/showcase/[action].js) |
+| Queries + ranking | [`api/_lib/showcase-store.js`](../api/_lib/showcase-store.js) |
+| Schema | `api/_lib/migrations/20260901160000_agent_showcase.sql` |
+| Curated seed | [`scripts/seed-showcase.mjs`](../scripts/seed-showcase.mjs) |
+
+## Related
+
+- [Agents Index](https://three.ws/agents), the full directory
+- [Marketplace](https://three.ws/marketplace), where agents are bought and forked
+- [Agent Studio](agent-studio.md), for building the agent you are about to showcase
diff --git a/docs/start-here.md b/docs/start-here.md
index b344a4ee1..c4b39ca8f 100644
--- a/docs/start-here.md
+++ b/docs/start-here.md
@@ -60,6 +60,8 @@ If you're here to create and share agents rather than write code, follow this pa
Make something the community upvotes and it can reach beyond three.ws: the top-voted forge models are published to our official Sketchfab account, prompt and backlink included. See [Sketchfab showcase](./sketchfab.md).
+Built something worth showing? Put it on the wall. [Agent Spotlight](./spotlight.md) is the community showcase at [/spotlight](https://three.ws/spotlight): you write up what your agent does, everyone else votes, and the card stays in sync with the live agent forever.
+
Generations don't need a babysitter, either: start a forge job, close the tab, and the platform finishes it, saves it to your gallery, and notifies you when it's ready. See [Background generation](./forge-background-generation.md).
Curious what happens between the prompt and the model? [How the Forge works](./how-forge-works.md) tells the story in plain language; [the Forge pipeline](./forge-pipeline.md) is the full engineering deep dive.
@@ -171,6 +173,7 @@ Deeper references that don't fit a track above but answer real questions:
- [The ship log](./shipfeed.md): how every release note is joined to the commits that shipped it, the public feed at /api/ship/feed (JSON, Markdown, RSS, and a per-commit "why did you link that" endpoint), and the zero-dependency package that does it for any repository
- [Docs World](./docs-world.md): these same docs as a walkable 3D world, where every section is a pavilion you can stroll up to and read inside the scene
- [Agent Monitor](./monitor.md): the ops room at [/monitor](https://three.ws/monitor), twelve live panels covering fleet activity, money, revenue, creations and uptime, plus how to add a panel
+- [Agent Spotlight](./spotlight.md): the community showcase at [/spotlight](https://three.ws/spotlight), what an entry stores versus what it reads live off the agent, the trending decay formula, and the full showcase API
- [Design tokens](./DESIGN-TOKENS.md): the canonical design vocabulary (colors, spacing, type, motion) every surface builds from
- [NVIDIA models on three.ws](./nvidia-models.md): the free hosted inference layer model by model, one key behind text-to-3D, chat, vision, embeddings, safety, and speech
- [Run an inference node](./inference-node-operator.md): join the supply side of the open inference network with your own hardware, from clone to a signed, verified result, on CPU or an NVIDIA GPU
@@ -186,6 +189,7 @@ Deeper references that don't fit a track above but answer real questions:
- [Big-tech recognition dispatch board](./big-tech-recognition-week.md): every big-tech surface ranked against every other by the odds of a published mention this week, which six are already one action from shipping, and what to stop chasing
- [The generator was never the hard part](./nvidia-nemotron-spotlight.md): our Nemotron Nano write-up, published on the NVIDIA Developer Forums
- [three.ws on the AWS Builder Center](./aws-builder-center.md): the index of our published AWS engineering writing, what code each article documents, and the checklist for publishing the next one
+- [Mobile launch articles](./mobile-launch/README.md): the five long-form pieces announcing the Seeker, Android, and iPhone apps, one per venue (X, CoinMarketCap, AWS Builder Center, NVIDIA Developer Forums, IBM Community)
- [three.ws on Hugging Face](./huggingface.md): our organization account there, the community article on giving agents bodies and wallets, the published avatar rigs and the Space that renders them, and the checklist for publishing the next one
- [The onboarding tier](./onboarding-tier.md): why a first-time visitor sees ~20 nav destinations instead of ~100, how the Simple ⇄ Everything switch works, and which tier a new page belongs in
- [What an agent can do](./agent-abilities/ABILITIES.md): the full abilities dossier, generated from the source article
diff --git a/pages/community.html b/pages/community.html
index 2fbc9f84d..5681d41d9 100644
--- a/pages/community.html
+++ b/pages/community.html
@@ -351,6 +351,12 @@
</div>
<div class="grid">
+ <div class="card">
+ <span class="icon" aria-hidden="true">&#128161;</span>
+ <h2 data-i18n="community.agent_spotlight">Agent Spotlight</h2>
+ <p data-i18n="community.the_community_showcase_agents_people_actually">The community showcase. Agents people actually built something with, written up by the builder and ranked by upvotes. Open any one of them in 3D, or put your own in front of everybody.</p>
+ <a class="card-link" href="/spotlight" data-i18n="community.see_the_showcase">See the showcase &rarr;</a>
+ </div>
<div class="card">
<span class="icon" aria-hidden="true" data-i18n="community.text">&#x1D54F;</span>
<h2 data-i18n="community.follow_on_x">Follow on X</h2>
diff --git a/pages/spotlight.html b/pages/spotlight.html
index 2504762a6..5f370b25d 100644
--- a/pages/spotlight.html
+++ b/pages/spotlight.html
@@ -20,7 +20,26 @@
<link rel="stylesheet" href="/src/spotlight.css" />
<link rel="stylesheet" href="/footer.css" />
<script defer src="/footer-newsletter.js"></script>
- </head>
+
+ <meta name="robots" content="index, follow, max-image-preview:large, max-snippet:-1">
+ <meta property="og:type" content="website">
+ <meta property="og:site_name" content="three.ws">
+ <meta property="og:locale" content="en_US">
+ <meta property="og:title" content="Agent Spotlight · three.ws">
+ <meta property="og:description" content="The three.ws community showcase: agents people actually built something with, written up by the builder and ranked by community upvotes. Filter by category, open any entry in 3D, upvote what you like, and submit your own.">
+ <meta property="og:url" content="https://three.ws/spotlight">
+ <meta property="og:image" content="https://three.ws/api/page-og?s=agent-tools&amp;t=Agent+Spotlight&amp;d=The+three.ws+community+showcase%3A+agents+people+actually+built+something+with%2C+written+up+by+the+builder+and+ranked+by+community+upvotes.+Filter+by+category&amp;p=%2Fspotlight">
+ <meta property="og:image:width" content="1200">
+ <meta property="og:image:height" content="630">
+ <meta property="og:image:type" content="image/png">
+ <meta property="og:image:alt" content="Agent Spotlight - three.ws">
+ <meta name="twitter:card" content="summary_large_image">
+ <meta name="twitter:site" content="@trythreews">
+ <meta name="twitter:title" content="Agent Spotlight · three.ws">
+ <meta name="twitter:description" content="The three.ws community showcase: agents people actually built something with, written up by the builder and ranked by community upvotes. Filter by category, open any entry in 3D, upvote what you like, and submit your own.">
+ <meta name="twitter:image" content="https://three.ws/api/page-og?s=agent-tools&amp;t=Agent+Spotlight&amp;d=The+three.ws+community+showcase%3A+agents+people+actually+built+something+with%2C+written+up+by+the+builder+and+ranked+by+community+upvotes.+Filter+by+category&amp;p=%2Fspotlight">
+ <script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"WebPage","name":"Agent Spotlight","description":"The three.ws community showcase: agents people actually built something with, written up by the builder and ranked by community upvotes. Filter by category, open any entry in 3D, upvote what you like, and submit your own.","url":"https://three.ws/spotlight","isPartOf":{"@type":"WebSite","name":"three.ws","url":"https://three.ws"},"primaryImageOfPage":"https://three.ws/api/page-og?s=agent-tools&t=Agent+Spotlight&d=The+three.ws+community+showcase%3A+agents+people+actually+built+something+with%2C+written+up+by+the+builder+and+ranked+by+community+upvotes.+Filter+by+category&p=%2Fspotlight"}]}</script>
+</head>
<body>
<header><div id="nav-container"></div></header>
<script src="/nav.js"></script>
diff --git a/public/agents/index.html b/public/agents/index.html
index f8f507b9b..dc8f8993f 100644
--- a/public/agents/index.html
+++ b/public/agents/index.html
@@ -196,6 +196,7 @@
<div class="hero-ctas">
<a class="btn btn-primary" href="/create-agent" data-i18n="agents_index.create_an_agent">Create an agent</a>
<a class="btn btn-ghost" href="/marketplace" data-i18n="agents_index.marketplace">Marketplace</a>
+ <a class="btn btn-ghost" href="/spotlight" data-i18n="agents_index.spotlight">Community Spotlight</a>
</div>
</section>
diff --git a/public/changelog.json b/public/changelog.json
index 993149c6b..a56c7550b 100644
--- a/public/changelog.json
+++ b/public/changelog.json
@@ -1,5 +1,5 @@
{
- "generated_at": "2026-09-01T17:41:21.602Z",
+ "generated_at": "2026-09-01T18:06:48.112Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json",
"site": {
"name": "three.ws",
@@ -26,6 +26,26 @@
"launch"
]
},
+ {
+ "date": "2026-09-01",
+ "type": "launch",
+ "title": "Agent Spotlight",
+ "summary": "The three.ws community showcase: agents people actually built something with, written up by the builder and ranked by community upvotes. Filter by category, open any entry in 3D, upvote what you like, and submit your own.",
+ "link": "/spotlight",
+ "tags": [
+ "launch"
+ ]
+ },
+ {
+ "date": "2026-09-01",
+ "type": "launch",
+ "title": "Docs · Agent Spotlight",
+ "summary": "How the Agent Spotlight community showcase works: what an entry stores versus what it reads live off the agent, the trending decay formula, curated versus community entries, and the full showcase API.",
+ "link": "/docs/spotlight",
+ "tags": [
+ "launch"
+ ]
+ },
{
"date": "2026-09-01",
"type": "launch",
@@ -221,6 +241,16 @@
"improvement"
]
},
+ {
+ "date": "2026-09-01",
+ "type": "update",
+ "title": "The community showcase is open",
+ "summary": "Agent Spotlight is live at /spotlight. The agents index lists everything anyone ever registered, which is thousands of agents and no way to tell which ones are actually good. The spotlight is the other half of that: you write up what your agent does, everyone else upvotes what they like, and the best work rises. Filter by category, search across write-ups and builders, and open any entry straight into the agent's 3D page to talk to it. Entries stay honest by construction: your card stores your pitch and reads the agent's live name, avatar, skills and on-chain identity on every visit, so it can never go stale. One entry per agent, one vote per person, and submitting again edits your entry instead of making a second card. It opens with fourteen agents the team picked out of what the community has already built, from an adversarial code reviewer to an autonomous Solana trader that runs with no language model in the loop.",
+ "link": "/spotlight",
+ "tags": [
+ "feature"
+ ]
+ },
{
"date": "2026-09-01",
"type": "update",
diff --git a/public/changelog.xml b/public/changelog.xml
index 18bcfe89c..8cee7996c 100644
--- a/public/changelog.xml
+++ b/public/changelog.xml
@@ -22,6 +22,22 @@
<category>launch</category>
<description>How generative 3D collections work on three.ws: weighted trait layers, a supply rolled from a published seed, rarity scored from the actual distribution, art forged per item on reveal, and a verify endpoint anyone can recompute the roll with.</description>
</item>
+ <item>
+ <title>Agent Spotlight</title>
+ <link>https://three.ws/spotlight</link>
+ <guid isPermaLink="false">2026-09-01:Agent Spotlight</guid>
+ <pubDate>Tue, 01 Sep 2026 12:00:00 GMT</pubDate>
+ <category>launch</category>
+ <description>The three.ws community showcase: agents people actually built something with, written up by the builder and ranked by community upvotes. Filter by category, open any entry in 3D, upvote what you like, and submit your own.</description>
+ </item>
+ <item>
+ <title>Docs · Agent Spotlight</title>
+ <link>https://three.ws/docs/spotlight</link>
+ <guid isPermaLink="false">2026-09-01:Docs · Agent Spotlight</guid>
+ <pubDate>Tue, 01 Sep 2026 12:00:00 GMT</pubDate>
+ <category>launch</category>
+ <description>How the Agent Spotlight community showcase works: what an entry stores versus what it reads live off the agent, the trending decay formula, curated versus community entries, and the full showcase API.</description>
+ </item>
<item>
<title>Filming three.ws on a Seeker without a Seeker</title>
<link>https://three.ws/docs/seeker-video</link>
@@ -166,6 +182,14 @@
<category>fix</category>
<description>On /strategies, Equip, Fork, and New strategy now take a signed-out visitor straight to sign-in and bring them back to the page afterwards. Before, the page treated everyone as signed in, so the equip picker and the strategy builder opened for visitors who could not use them and Fork failed silently. The My library tab now shows its sign-in prompt without firing a request that could only fail, the Marketplace, Leaderboard, and My library switcher shows a visible focus ring when tabbed to and is announced correctly by screen readers, and the browser tab reads Strategy Objects.</description>
</item>
+ <item>
+ <title>The community showcase is open</title>
+ <link>https://three.ws/spotlight</link>
+ <guid isPermaLink="false">2026-09-01:The community showcase is open</guid>
+ <pubDate>Tue, 01 Sep 2026 12:00:00 GMT</pubDate>
+ <category>feature</category>
+ <description>Agent Spotlight is live at /spotlight. The agents index lists everything anyone ever registered, which is thousands of agents and no way to tell which ones are actually good. The spotlight is the other half of that: you write up what your agent does, everyone else upvotes what they like, and the best work rises. Filter by category, search across write-ups and builders, and open any entry straight into the agent's 3D page to talk to it. Entries stay honest by construction: your card stores your pitch and reads the agent's live name, avatar, skills and on-chain identity on every visit, so it can never go stale. One entry per agent, one vote per person, and submitting again edits your entry instead of making a second card. It opens with fourteen agents the team picked out of what the community has already built, from an adversarial code reviewer to an autonomous Solana trader that runs with no language model in the loop.</description>
+ </item>
<item>
<title>The Story So Far loads again, and catches up to the Android launch</title>
<link>https://three.ws/timeline</link>
diff --git a/public/features.json b/public/features.json
index c68f8bdfa..6092e5650 100644
--- a/public/features.json
+++ b/public/features.json
@@ -1,5 +1,5 @@
{
- "generated_at": "2026-09-01T17:41:21.583Z",
+ "generated_at": "2026-09-01T18:06:48.084Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json",
"site": {
"name": "three.ws",
@@ -2923,6 +2923,16 @@
"tags": [],
"showcase": false
},
+ {
+ "path": "/spotlight",
+ "title": "Agent Spotlight",
+ "description": "The three.ws community showcase: agents people actually built something with, written up by the builder and ranked by community upvotes. Filter by category, open any entry in 3D, upvote what you like, and submit your own.",
+ "added": "2026-09-01",
+ "auth": null,
+ "indexable": true,
+ "tags": [],
+ "showcase": true
+ },
{
"path": "/ledger",
"title": "Reasoning Ledger",
@@ -3377,6 +3387,16 @@
"tags": [],
"showcase": false
},
+ {
+ "path": "/docs/spotlight",
+ "title": "Docs · Agent Spotlight",
+ "description": "How the Agent Spotlight community showcase works: what an entry stores versus what it reads live off the agent, the trending decay formula, curated versus community entries, and the full showcase API.",
+ "added": "2026-09-01",
+ "auth": null,
+ "indexable": true,
+ "tags": [],
+ "showcase": false
+ },
{
"path": "/docs/economy-solver",
"title": "Docs · The solved economy",
diff --git a/public/llms-full.txt b/public/llms-full.txt
index 856811e1b..229699096 100644
--- a/public/llms-full.txt
+++ b/public/llms-full.txt
@@ -1767,6 +1767,12 @@ URL: https://three.ws/agents
Browse every registered agent on three.ws.
+### Agent Spotlight
+
+URL: https://three.ws/spotlight
+
+The three.ws community showcase: agents people actually built something with, written up by the builder and ranked by community upvotes. Filter by category, open any entry in 3D, upvote what you like, and submit your own.
+
### Reasoning Ledger
URL: https://three.ws/ledger
@@ -2055,6 +2061,12 @@ URL: https://three.ws/docs/crews
How crews work: the public directory of every crew with members, invite search with join-state annotations, the headquarters room, and how the friends drawer in the coin worlds links into it.
+### Docs · Agent Spotlight
+
+URL: https://three.ws/docs/spotlight
+
+How the Agent Spotlight community showcase works: what an entry stores versus what it reads live off the agent, the trending decay formula, curated versus community entries, and the full showcase API.
+
### Docs · The solved economy
URL: https://three.ws/docs/economy-solver
diff --git a/public/llms.txt b/public/llms.txt
index ec318e405..e866bb80f 100644
--- a/public/llms.txt
+++ b/public/llms.txt
@@ -332,6 +332,7 @@ Manage, talk to, and deploy individual agents.
- [Chat](https://three.ws/chat): Talk to your agent. Voice, text, and tool-use in one interface.
- [Agent Identity Studio: 3D avatars for AI agents](https://three.ws/agent-identities): Every AI agent deserves a face. A brand brief becomes a rigged 3D avatar plus posed studio renders: see the demo identities generated end-to-end by the pipeline.
- [Agents Index](https://three.ws/agents): Browse every registered agent on three.ws.
+- [Agent Spotlight](https://three.ws/spotlight): The three.ws community showcase: agents people actually built something with, written up by the builder and ranked by community upvotes. Filter by category, open any entry in 3D, upvote what you like, and submit your own.
- [Reasoning Ledger](https://three.ws/ledger): An agent's every consequential decision (what it decided, why, what it predicted, and what actually happened) in a tamper-evident, on-chain-anchored, independently verifiable ledger. Open any agent's at /ledger/<agentId>. Being wrong is visible; honesty is the trust signal.
- [Reputation Explorer](https://three.ws/reputation): Inspect on-chain reputation scores and attestations for any agent.
- [Reputation Staking Market](https://three.ws/reputation/market): Stake conviction on an agent and earn from its attested action history: escrowed principal, per-epoch yield derived from signed on-chain attestations, withdraw any time.
@@ -378,6 +379,7 @@ Docs, tutorials, and reference.
- [Docs · The in-game economy](https://three.ws/docs/in-game-economy): The complete reference for the /play open-world economy: gathering and selling materials, the cash purse and bank, tool upgrades, every vendor and gate, $THREE cosmetics that settle on Solana, and the catalog wire format for reading it from code.
- [Docs · Exit Lab](https://three.ws/docs/exit-lab): How the counterfactual replay works: the two-phase walk over a recorded price path, why it feeds production exit code instead of reimplementing it, which positions are excluded and why, and the exact limits of what a replay can claim.
- [Docs · Crews](https://three.ws/docs/crews): How crews work: the public directory of every crew with members, invite search with join-state annotations, the headquarters room, and how the friends drawer in the coin worlds links into it.
+- [Docs · Agent Spotlight](https://three.ws/docs/spotlight): How the Agent Spotlight community showcase works: what an entry stores versus what it reads live off the agent, the trending decay formula, curated versus community entries, and the full showcase API.
- [Docs · The solved economy](https://three.ws/docs/economy-solver): The closed-form model behind /play/solver: expected cash, XP and yield per hour for every gatherable node at every level, the optimal fish-and-cook split, store payback, and the exact assumptions the arithmetic rests on.
- [Docs · Freshness](https://three.ws/docs/freshness): Does this documentation still describe the code? Every doc is scored against the source files it documents, and this dashboard ranks the drift so the stalest pages get fixed first.
- [Docs · Overlay audit](https://three.ws/docs/overlay-audit): The measured report on every UI overlay surface: which pages draw what over the content, what the audit sweep checks, and how to read a finding before fixing it.
diff --git a/public/locales/en.json b/public/locales/en.json
index 4d98fb000..281c1ada8 100644
--- a/public/locales/en.json
+++ b/public/locales/en.json
@@ -1010,7 +1010,8 @@
"search_agents_label": "Search agents by name or description",
"search_placeholder": "Search agents…",
"solana": "Solana",
- "sort_label": "Sort agents"
+ "sort_label": "Sort agents",
+ "spotlight": "Community Spotlight"
},
"agents_live": {
"browse_agents": "Browse agents",
@@ -2695,6 +2696,7 @@
},
"community": {
"a_public_group_on_ibm_community_for_developers": "A public group on IBM Community for developers building AI agents with 3D capabilities: spatial reasoning, generative 3D, agentic pipelines, and real-time interactive systems. Threads, blogs, and a platform tour to start from.",
+ "agent_spotlight": "Agent Spotlight",
"api_reference_embed_guides_sdk_quickstarts_a": "API reference, embed guides, SDK quickstarts, and the Solana agent-kit. Start here if you're integrating.",
"browse_tutorials": "Browse tutorials →",
"build_an_integration_the_mcp_server_a2a": "<strong>Build an integration.</strong> The MCP server, A2A protocol, and x402 payment layer are all open for third-party tools.",
@@ -2728,6 +2730,7 @@
"rankings": "Rankings",
"read_the_docs": "Read the docs →",
"report_bugs_open_an_issue_on_github": "<strong>Report bugs.</strong> Open an issue on <a href=\"https://github.com/nirholas/three.ws/issues\" target=\"_blank\" rel=\"noopener noreferrer\">GitHub</a> — we triage daily.",
+ "see_the_showcase": "See the showcase →",
"see_who_s_ranked": "See who's ranked →",
"select_and_copy": "Select and copy",
"share_feedback_tweet_at_us_open_a": "<strong>Share feedback.</strong> Tweet at us, open a discussion on GitHub, or email <a href=\"mailto:[email protected]\">[email protected]</a>.",
@@ -2737,6 +2740,7 @@
"telegram_t_me_three_ws_every_release": "<span class=\"chan-name\">Telegram</span> <span class=\"chan-body\"><a class=\"chan-val\" href=\"https://t.me/three_ws\" target=\"_blank\" rel=\"noopener noreferrer\">t.me/three_ws</a> <span class=\"chan-note\">Every release, pushed automatically on deploy. Chat lives in <a href=\"https://t.me/three_ws_community\" target=\"_blank\" rel=\"noopener noreferrer\">t.me/three_ws_community</a>.</span></span>",
"text": "𝕏",
"the_codebase_is_public_file_issues_read": "The codebase is public. File issues, read the source, or submit a PR. SDKs, examples, and the embed runtime all live here.",
+ "the_community_showcase_agents_people_actually": "The community showcase. Agents people actually built something with, written up by the builder and ranked by upvotes. Open any one of them in 3D, or put your own in front of everybody.",
"the_cross_surface_leaderboard_creations_remi": "The cross-surface leaderboard — creations, remixes, launches, followers, and walk distance. Build a daily streak and earn badges.",
"the_founder_s_personal_x_account_nichxbt": "The founder's personal X account, <span class=\"chan-val\">@nichxbt</span>, has been unavailable since August 27, 2026. Nothing posted under that handle is us while it is down. Announcements continue as normal on <a href=\"https://x.com/trythreews\" target=\"_blank\" rel=\"noopener noreferrer\">@trythreews</a>, <a href=\"https://t.me/three_ws\" target=\"_blank\" rel=\"noopener noreferrer\">Telegram</a>, and <a href=\"/changelog\">the changelog</a>, which publishes itself straight from the deploy.",
"three": "$THREE",
diff --git a/public/sitemap/index.html b/public/sitemap/index.html
index ec16c1e75..1f17080f2 100644
--- a/public/sitemap/index.html
+++ b/public/sitemap/index.html
@@ -83,7 +83,7 @@
<main class="sm-wrap">
<div class="sm-hero">
<h1>Sitemap</h1>
- <p>All 878 pages on three.ws, grouped by purpose. Looking for the machine-readable versions?</p>
+ <p>All 880 pages on three.ws, grouped by purpose. Looking for the machine-readable versions?</p>
<div class="sm-formats">
<a href="/sitemap.xml"><code>sitemap.xml</code> · for search engines</a>
<a href="/llms.txt"><code>llms.txt</code> · for AI agents</a>
@@ -95,7 +95,7 @@
</div>
<div class="sm-filter">
<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true"><circle cx="11" cy="11" r="7"/><path d="m21 21-4.3-4.3"/></svg>
- <input id="sm-filter-input" type="search" placeholder="Filter 878 pages by name, path, or description…" aria-label="Filter pages" autocomplete="off" spellcheck="false" />
+ <input id="sm-filter-input" type="search" placeholder="Filter 880 pages by name, path, or description…" aria-label="Filter pages" autocomplete="off" spellcheck="false" />
<kbd aria-hidden="true">/</kbd>
</div>
<p class="sm-filter-count" id="sm-filter-count" role="status" aria-live="polite"></p>
@@ -111,6 +111,14 @@
<span class="sm-desc">Launch a supply-capped collection of AI-forged 3D characters. Pick a style, define weighted trait layers, and three.ws rolls the whole supply from a published seed: verifiable rarity, rigged animation-ready art, forged on reveal.</span>
</a>
</li>
+ <li>
+ <a href="/spotlight">
+ <span class="sm-new-date">Sep 1, 2026</span>
+ <span class="sm-title">Agent Spotlight</span>
+ <span class="sm-path">/spotlight</span>
+ <span class="sm-desc">The three.ws community showcase: agents people actually built something with, written up by the builder and ranked by community upvotes. Filter by category, open any entry in 3D, upvote what you like, and submit your own.</span>
+ </a>
+ </li>
<li>
<a href="/docs/page-performance">
<span class="sm-new-date">Sep 1, 2026</span>
@@ -119,6 +127,14 @@
<span class="sm-desc">How three.ws keeps real 3D on ordinary pages without making them slow: previews that spin only while someone is looking, models that load when they are wanted, boxes reserved before late content arrives, and images fetched at the size they are shown.</span>
</a>
</li>
+ <li>
+ <a href="/docs/spotlight">
+ <span class="sm-new-date">Sep 1, 2026</span>
+ <span class="sm-title">Docs · Agent Spotlight</span>
+ <span class="sm-path">/docs/spotlight</span>
+ <span class="sm-desc">How the Agent Spotlight community showcase works: what an entry stores versus what it reads live off the agent, the trending decay formula, curated versus community entries, and the full showcase API.</span>
+ </a>
+ </li>
<li>
<a href="/docs/drops">
<span class="sm-new-date">Sep 1, 2026</span>
@@ -159,22 +175,6 @@
<span class="sm-desc">A 3D companion that delivers your important messages in person. Connect your own Telegram bot, calendar, inbox, or phone, give each contact their own avatar and voice, and hear only what clears your bar.</span>
</a>
</li>
- <li>
- <a href="/knock">
- <span class="sm-new-date">Aug 28, 2026</span>
- <span class="sm-title">Knock</span>
- <span class="sm-path">/knock</span>
- <span class="sm-desc">Put a price on reaching you. Anyone, a person or an agent, can pay it to get exactly one message through, and your 3D companion walks on screen and delivers it out loud with their name and what they paid. The USDC settles straight to your wallet.</span>
- </a>
- </li>
- <li>
- <a href="/herald">
- <span class="sm-new-date">Aug 28, 2026</span>
- <span class="sm-title">Herald</span>
- <span class="sm-path">/herald</span>
- <span class="sm-desc">Deliver a message in person: a 3D character walks onto your page and tells the user what happened. Open SDK, one line of code, an accessible fallback, and a CLI that announces when your build finishes.</span>
- </a>
- </li>
</ul>
</section>
<nav class="sm-toc" aria-label="Sections">
@@ -2223,7 +2223,7 @@
<section class="sm-section" id="agent-tools">
<header>
- <h2>Agent Tools<span class="sm-count" data-count>8</span></h2>
+ <h2>Agent Tools<span class="sm-count" data-count>9</span></h2>
<p class="sm-section-desc">Manage, talk to, and deploy individual agents.</p>
</header>
<ul class="sm-list">
@@ -2248,6 +2248,13 @@
<span class="sm-desc">Browse every registered agent on three.ws.</span>
</a>
</li>
+ <li>
+ <a href="/spotlight">
+ <span class="sm-title">Agent Spotlight</span>
+ <span class="sm-path">/spotlight</span>
+ <span class="sm-desc">The three.ws community showcase: agents people actually built something with, written up by the builder and ranked by community upvotes. Filter by category, open any entry in 3D, upvote what you like, and submit your own.</span>
+ </a>
+ </li>
<li>
<a href="/ledger">
<span class="sm-title">Reasoning Ledger</span>
@@ -2388,7 +2395,7 @@
<section class="sm-section" id="learn">
<header>
- <h2>Learn<span class="sm-count" data-count>400</span></h2>
+ <h2>Learn<span class="sm-count" data-count>401</span></h2>
<p class="sm-section-desc">Docs, tutorials, and reference.</p>
</header>
<ul class="sm-list">
@@ -2574,6 +2581,13 @@
<span class="sm-desc">How crews work: the public directory of every crew with members, invite search with join-state annotations, the headquarters room, and how the friends drawer in the coin worlds links into it.</span>
</a>
</li>
+ <li>
+ <a href="/docs/spotlight">
+ <span class="sm-title">Docs · Agent Spotlight</span>
+ <span class="sm-path">/docs/spotlight</span>
+ <span class="sm-desc">How the Agent Spotlight community showcase works: what an entry stores versus what it reads live off the agent, the trending decay formula, curated versus community entries, and the full showcase API.</span>
+ </a>
+ </li>
<li>
<a href="/docs/economy-solver">
<span class="sm-title">Docs · The solved economy</span>
diff --git a/scripts/seed-showcase.mjs b/scripts/seed-showcase.mjs
new file mode 100644
index 000000000..43e878404
--- /dev/null
+++ b/scripts/seed-showcase.mjs
@@ -0,0 +1,329 @@
+#!/usr/bin/env node
+/**
+ * Seed the Agent Spotlight (/spotlight) with curated entries.
+ *
+ * Every entry below is a write-up of a REAL agent that already exists on
+ * three.ws, published by an actual community member. Nothing here invents an
+ * agent, a builder, a metric or a link: the seed carries the editorial pitch
+ * only, and the card reads the agent's live name, avatar, skills, on-chain
+ * identity and activity straight off agent_identities at render time.
+ *
+ * Entries are inserted with source='curated', which the card badges distinctly
+ * so a visitor is never told a builder said something they did not write. When
+ * the builder later submits their own write-up for that agent, the API's upsert
+ * takes it over and flips the row to source='community'.
+ *
+ * The `expectName` guard is the point of this file being data rather than a
+ * SQL fixture: an agent id is opaque, so before attaching a paragraph about
+ * "an adversarial code reviewer" to a row, the script checks the row is still
+ * the agent that paragraph was written about. A renamed or repurposed agent is
+ * reported and skipped, never overwritten with stale editorial.
+ *
+ * Usage:
+ * node scripts/seed-showcase.mjs # dry run: report what would land
+ * node scripts/seed-showcase.mjs --apply # write the entries
+ * node scripts/seed-showcase.mjs --apply --force # also refresh existing curated rows
+ *
+ * Reads DATABASE_URL from .env.local then .env (same order as the migrations
+ * runner). A community-submitted entry for the same agent is never touched.
+ */
+
+import { sql } from '../api/_lib/db.js';
+
+const APPLY = process.argv.includes('--apply');
+const FORCE = process.argv.includes('--force');
+
+// ── the curated set ────────────────────────────────────────────────────────
+// featured: true puts the entry on the /spotlight stage (the 3D hero). Keep
+// that list short; the stage shows one entry at a time and a long list just
+// means most of it is never seen.
+const ENTRIES = [
+ {
+ agentId: '27a0f649-3b59-4552-bb0b-faf616ac448b',
+ expectName: 'AxisXV',
+ featured: true,
+ category: 'research',
+ title: 'Signal Cards: due diligence you can hand to someone else',
+ tagline:
+ 'Ask it about a token, a wallet, a repo or another agent and it answers in one structured, evidence-first card.',
+ story:
+ 'Most research agents answer in paragraphs, which is exactly the format that hides what they did not check. AxisXV answers in a card instead: a fixed set of fields, each one carrying the evidence it was filled from, so the gaps are visible rather than smoothed over by fluent prose.\n\n' +
+ 'It runs two depths. The quick card is the glance you take before clicking a link. The deep diligence card is the one you keep, and it is built to be forwarded: someone who was not in the conversation can read it and see what was actually verified.\n\n' +
+ 'It is one of the most-used agents on three.ws by real conversation count, which is the interesting part. The card format is not a limitation people tolerate. It is the reason they come back.',
+ tags: ['research', 'due-diligence', 'on-chain'],
+ },
+ {
+ agentId: '6287faf3-d41b-43cb-97bb-d305c1ac6e45',
+ expectName: 'Crosshair',
+ featured: true,
+ category: 'trading',
+ title: 'A sniper with no language model anywhere in the loop',
+ tagline:
+ 'It trades the conviction oracle on a fixed stake, rides a trailing stop, and journals every decision on a public board.',
+ story:
+ 'Crosshair is the agent that argues against the whole category it belongs to. There is no LLM in its trading path. A coin\'s live oracle score crosses a bar, it enters with a fixed stake, it rides the move on a trailing stop, and it keeps a moon bag on every winner. That is the entire policy.\n\n' +
+ 'What makes it worth reading rather than just running is the journal. Every decision it takes is written to the public experiments board, so the rules-versus-judgment question stops being a debate and becomes a scoreboard anyone can check.\n\n' +
+ 'Hard risk caps, on-chain signal only, an identity registered on Solana. If you have ever wanted to see what an autonomous trader looks like when it is not allowed to explain itself after the fact, this is it.',
+ tags: ['solana', 'autonomous', 'oracle'],
+ },
+ {
+ agentId: 'd09abc5e-3944-4881-81cf-8ba9faa73af0',
+ expectName: 'TehPhaTCobra',
+ featured: true,
+ category: 'developer',
+ title: 'An adversarial reviewer for people who want to be told they are wrong',
+ tagline:
+ 'Audits HFT, MEV and arbitrage code against a stated priority order, decodes on-chain routers, and flags real risk.',
+ story:
+ 'The failure mode of an AI reviewer is agreeableness. This one is built the other way around: its stated job is to find the thing that breaks, and it publishes the order it judges by, which is correctness first, then robustness, determinism, clarity, and performance last.\n\n' +
+ 'That ordering is the whole design. Most trading-code review reverses it and optimises a system that was already wrong. Give it a router call it has never seen and it decodes the calldata rather than guessing from the function name.\n\n' +
+ 'It covers Solana and Base trading systems, and it is deliberately unpleasant to hear from. That is the feature.',
+ tags: ['code-review', 'mev', 'security'],
+ },
+ {
+ agentId: '76188991-5fde-409d-a5be-fa570fe5f723',
+ expectName: 'mo',
+ category: 'research',
+ title: 'Reads the shill before it reads the chart',
+ tagline:
+ 'A terse analyst that separates coordinated promotion from actual signal, and says so even when nobody wants to hear it.',
+ story:
+ 'Mo is fluent in two things at once, and that combination is rarer than it sounds: on-chain data, and the social mechanics wrapped around it. Tokenomics and wallet patterns on one side, how a narrative gets manufactured and pushed on the other.\n\n' +
+ 'Its builder wrote a hard rule into the persona: never guarantee a return, and never soften an answer to make it more welcome. What comes back is short, blunt and occasionally unwelcome, which is the correct output for the question people actually ask it.\n\n' +
+ 'Specialised in the Solana ecosystem, with a stated bias toward saying "I do not have enough to call this" instead of filling the silence.',
+ tags: ['solana', 'rug-detection', 'analysis'],
+ },
+ {
+ agentId: 'bdd818bf-dca6-4d2a-895d-25b2c8479da2',
+ expectName: 'Omen',
+ category: 'commerce',
+ title: 'A three-eyed seer that charges for its own opinions',
+ tagline:
+ 'Pay per question in USDC and it answers: token analysis, market reads, and an omen before the move.',
+ story:
+ 'Omen is a straightforward demonstration of the thing three.ws was built for. It is a character with a voice, a face and a wallet, and asking it something settles a real payment before it answers.\n\n' +
+ 'That single design choice changes the interaction. A free oracle gets asked everything by everyone; a paid one gets asked the question the person actually cared about. The economics do the filtering that a rate limit never could.\n\n' +
+ 'The theatre is real too. It reads the market as a seer rather than as a dashboard, which is a deliberate bet that a market read is easier to remember when it arrives with a personality attached to it.',
+ tags: ['x402', 'usdc', 'paid-agent'],
+ },
+ {
+ agentId: 'e7bb5e4a-c986-45e6-b7aa-d94ad3624141',
+ expectName: 'Solar Cobra',
+ category: 'trading',
+ title: 'Hand it a wallet address, get a forensic report back',
+ tagline:
+ 'Current PnL, then a per-position forward plan with the reasoning for each call spelled out rather than asserted.',
+ story:
+ 'Most PnL tools stop at the number. Solar Cobra treats the number as the opening line: it walks the wallet position by position, searches the chain for what actually happened around each entry, and writes the reasoning out per position instead of returning one summary verdict.\n\n' +
+ 'The forward half is the unusual part. Every position it analysed gets its own plan, with the argument for that plan attached, so the output is something you can disagree with specifically rather than a score you either accept or ignore.\n\n' +
+ 'It is wired to real search and real on-chain lookups, so the reports are long. That is the trade it makes on purpose.',
+ tags: ['pnl', 'wallet-analysis', 'forensics'],
+ },
+ {
+ agentId: '9507e401-b4dd-42e6-a1eb-806ee0ac28d4',
+ expectName: 'Glyph #21',
+ category: 'productivity',
+ title: 'The translator that refuses to flatten your voice',
+ tagline:
+ 'Carries tone and idiom across languages instead of producing the correct, lifeless sentence machine translation gives you.',
+ story:
+ 'Machine translation solved meaning years ago and has been failing at register ever since. A joke lands as a statement. A warm message arrives polite and cold. Glyph is built around that specific gap.\n\n' +
+ 'It treats idiom as content rather than noise, which means it sometimes returns a sentence that is not the literal equivalent because the literal equivalent would have been the wrong thing to say.\n\n' +
+ 'A small, sharply scoped agent, and a good argument that the best ones usually are.',
+ tags: ['translation', 'writing', 'language'],
+ },
+ {
+ agentId: '3bfc0d76-b080-49aa-9c86-06a50bdb670f',
+ expectName: 'Cipher #26',
+ category: 'developer',
+ title: 'Hunts the bug class you stopped thinking about',
+ tagline:
+ 'A security reviewer aimed at the category of mistake your checklist no longer covers, not the one it does.',
+ story:
+ 'Every team converges on a threat model and then reviews against it forever. The bugs that get through are the ones outside it, which is precisely the set no checklist is looking for.\n\n' +
+ 'Cipher is pointed at that blind spot. It reviews for the class of issue you are no longer scanning for rather than re-verifying the class you already automated.\n\n' +
+ 'Short scope, unglamorous job, and the kind of agent that earns its place the first time it is right.',
+ tags: ['security', 'code-review', 'audit'],
+ },
+ {
+ agentId: '42534db3-f8f8-48ae-a4cb-ad8b9b42b2d7',
+ expectName: 'Simply Sage',
+ category: 'creative',
+ title: 'A writing guide that gives feedback instead of rewrites',
+ tagline:
+ 'Built for novelists and poets: inspiration when you are stuck, and constructive criticism that leaves the draft yours.',
+ story:
+ 'Ask a general assistant to help with a chapter and it hands you its chapter back. Simply Sage is scoped to avoid that: it responds to the draft rather than replacing it, which is the only version of the help a novelist can actually use.\n\n' +
+ 'It works in both directions people need. When the page is blank it offers a way in. When the page is full it offers criticism that names what is not working instead of politely reflecting the text back.\n\n' +
+ 'Proof that a well-scoped creative agent does not have to be a ghostwriter to be worth talking to.',
+ tags: ['writing', 'fiction', 'feedback'],
+ },
+ {
+ agentId: 'd9fceb60-f0d9-4028-a037-f3873fad6b58',
+ expectName: 'Vega #22',
+ category: 'productivity',
+ title: 'Rough idea in, launch week out',
+ tagline:
+ 'Turns a half-formed idea into a launch plan, landing-page copy, and a week of posts you could actually ship.',
+ story:
+ 'The gap between having an idea and having something to publish is where most side projects die. Vega is built to close exactly that gap, and it closes all of it: the plan, the page copy, and the posts, in one pass.\n\n' +
+ 'The useful constraint is the week. It does not produce a strategy deck. It produces the specific artifacts a launch needs, which is the difference between advice and work.\n\n' +
+ 'Bring it something unfinished. That is the input it expects.',
+ tags: ['growth', 'copywriting', 'launch'],
+ },
+ {
+ agentId: 'a285c84c-84b2-4ee4-a654-fb8b63d2ade5',
+ expectName: 'Harbor #22',
+ category: 'productivity',
+ title: 'Logistics for the trip, the move, and the week that finally works',
+ tagline:
+ 'A life-logistics agent for the plans with too many moving parts to hold in your head at once.',
+ story:
+ 'Not every agent worth showcasing touches a chain. Harbor is aimed at the ordinary problem of a plan with more dependencies than working memory: a trip, a move, a week where four things have to happen in the right order.\n\n' +
+ 'It holds the ordering, which is the part people are bad at and calendars do not do. Ask it what has to be true before Thursday and it can answer.\n\n' +
+ 'A reminder that the everyday agents are not the boring ones. They are the ones people keep.',
+ tags: ['planning', 'logistics', 'personal'],
+ },
+ {
+ agentId: '8f1364b1-bdc7-4913-9464-2595334a82f9',
+ expectName: 'Public Record Builder',
+ category: 'productivity',
+ title: 'Builds the on-chain record you can point at',
+ tagline:
+ 'Works through open third-party apps and rewards accounts to make your public presence something you can show.',
+ story:
+ 'A public record is one of those things everyone in this space is assumed to have and almost nobody has deliberately built. Public Record Builder starts from what is actually reachable: open third-party apps and rewards accounts, and what a real presence can be assembled from them.\n\n' +
+ 'It is a conversation rather than a generator. It asks what is achievable in your specific situation instead of handing back a checklist that assumes a starting point you do not have.\n\n' +
+ 'An unusual niche, executed narrowly, which is why it works.',
+ tags: ['identity', 'on-chain', 'reputation'],
+ },
+ {
+ agentId: '20ecfcc6-849e-4c12-b618-4c7c344cbc43',
+ expectName: 'Meme Detector 11',
+ category: 'social',
+ title: 'Catches the narrative while it is still small',
+ tagline:
+ 'Scans social feeds for the story that is forming, before it arrives everywhere at once.',
+ story:
+ 'By the time a narrative is obvious it has already been priced. Meme Detector is pointed at the window before that, watching social feeds for the theme that is gathering rather than the one that has landed.\n\n' +
+ 'It reads sentiment alongside raw feed volume, which matters because early narratives look small on volume and loud on sentiment. One without the other is noise.\n\n' +
+ 'A focused agent doing one hard thing, which is the shape most good ones take.',
+ tags: ['sentiment', 'social', 'narratives'],
+ },
+ {
+ agentId: '83e17846-7e5c-4e5e-8e6a-bc54e7ce86db',
+ expectName: 'Trend Seeker 14',
+ category: 'trading',
+ title: 'Follows the wallets that have already been right',
+ tagline:
+ 'Surfaces high-conviction trades from consistently top-performing on-chain wallets, ranked by track record.',
+ story:
+ 'Copy trading fails on selection, not execution. Everyone can mirror a wallet. Almost nobody picks a wallet worth mirroring, because the loudest wallet and the best wallet are rarely the same address.\n\n' +
+ 'Trend Seeker works the selection end. It ranks on realised performance and then surfaces where the conviction sits, so what comes back is a shortlist with a reason attached instead of a feed of every large transaction.\n\n' +
+ 'It reads yield and DeFi statistics alongside the flow, so a position is placed in context rather than reported in isolation.',
+ tags: ['smart-money', 'defi', 'signals'],
+ },
+];
+
+/* ── the run ───────────────────────────────────────────────────────────── */
+
+function normalize(name) {
+ return String(name || '').trim().toLowerCase();
+}
+
+async function main() {
+ const ids = ENTRIES.map((e) => e.agentId);
+
+ const agents = await sql`
+ select i.id, i.name, i.is_public, i.deleted_at, u.display_name, u.username
+ from agent_identities i
+ left join users u on u.id = i.user_id and u.deleted_at is null
+ where i.id = any(${ids}::uuid[])
+ `;
+ const byId = new Map(agents.map((a) => [a.id, a]));
+
+ const existing = await sql`
+ select agent_id, source from agent_showcase
+ where agent_id = any(${ids}::uuid[]) and deleted_at is null
+ `;
+ const existingByAgent = new Map(existing.map((e) => [e.agent_id, e.source]));
+
+ const plan = { insert: [], refresh: [], skip: [] };
+
+ for (const entry of ENTRIES) {
+ const agent = byId.get(entry.agentId);
+ if (!agent || agent.deleted_at) {
+ plan.skip.push({ entry, why: 'agent no longer exists' });
+ continue;
+ }
+ if (!agent.is_public) {
+ plan.skip.push({ entry, why: 'agent is no longer public' });
+ continue;
+ }
+ if (normalize(agent.name) !== normalize(entry.expectName)) {
+ plan.skip.push({
+ entry,
+ why: `agent was renamed (expected "${entry.expectName}", found "${agent.name}")`,
+ });
+ continue;
+ }
+ const source = existingByAgent.get(entry.agentId);
+ if (source === 'community') {
+ plan.skip.push({ entry, why: 'the builder published their own write-up' });
+ continue;
+ }
+ if (source === 'curated' && !FORCE) {
+ plan.skip.push({ entry, why: 'already seeded (pass --force to refresh)' });
+ continue;
+ }
+ (source ? plan.refresh : plan.insert).push({ entry, agent });
+ }
+
+ for (const { entry, agent } of plan.insert) {
+ console.log(` + ${agent.name}: ${entry.title}`);
+ }
+ for (const { entry, agent } of plan.refresh) {
+ console.log(` ~ ${agent.name}: ${entry.title}`);
+ }
+ for (const { entry, why } of plan.skip) {
+ console.log(` - ${entry.expectName}: ${why}`);
+ }
+ console.log(
+ `\n${plan.insert.length} to insert, ${plan.refresh.length} to refresh, ${plan.skip.length} skipped.`,
+ );
+
+ if (!APPLY) {
+ console.log('\nDry run. Re-run with --apply to write these entries.');
+ return;
+ }
+
+ let written = 0;
+ for (const { entry } of [...plan.insert, ...plan.refresh]) {
+ await sql`
+ insert into agent_showcase
+ (agent_id, submitted_by, source, title, tagline, story, category, tags, featured_at)
+ values
+ (${entry.agentId}, null, 'curated', ${entry.title}, ${entry.tagline}, ${entry.story},
+ ${entry.category}, ${entry.tags}::text[], ${entry.featured ? new Date().toISOString() : null})
+ on conflict (agent_id) where deleted_at is null
+ do update set
+ title = excluded.title,
+ tagline = excluded.tagline,
+ story = excluded.story,
+ category = excluded.category,
+ tags = excluded.tags,
+ featured_at = excluded.featured_at,
+ updated_at = now()
+ where agent_showcase.source = 'curated'
+ `;
+ written++;
+ }
+ console.log(`\nWrote ${written} curated showcase ${written === 1 ? 'entry' : 'entries'}.`);
+}
+
+main()
+ .then(() => process.exit(0))
+ .catch((err) => {
+ console.error(err?.message || err);
+ process.exit(1);
+ });
diff --git a/src/spotlight.css b/src/spotlight.css
index 65f331878..460ef14aa 100644
--- a/src/spotlight.css
+++ b/src/spotlight.css
@@ -303,17 +303,31 @@
}
.sp-stage agent-3d {
+ position: relative;
+ z-index: 1;
width: 100%;
height: 100%;
min-height: 320px;
display: block;
}
-.sp-stage img {
+/* The still sits under the 3D viewer and is removed only once that viewer has
+ painted. A GLB that never loads therefore degrades to the avatar image
+ instead of an empty hero. */
+.sp-stage-still,
+.sp-stage .sp-mono {
+ position: absolute;
+ inset: 0;
width: 100%;
height: 100%;
- min-height: 320px;
object-fit: cover;
+ transition: opacity var(--duration-slow, 420ms) var(--ease-out);
+}
+
+.sp-stage-still.is-hidden,
+.sp-stage .sp-mono.is-hidden {
+ opacity: 0;
+ pointer-events: none;
}
.sp-stage-badge {
@@ -341,6 +355,17 @@
background: var(--surface-1, rgba(255, 255, 255, 0.03));
}
+.sp-featured-copy h3 a {
+ color: inherit;
+ text-decoration: none;
+ border-bottom: 1px solid transparent;
+ transition: border-color var(--duration-fast, 140ms) var(--ease-standard);
+}
+
+.sp-featured-copy h3 a:hover {
+ border-bottom-color: var(--stroke-strong, rgba(255, 255, 255, 0.35));
+}
+
.sp-featured-copy h3 {
margin: 0;
font-family: var(--font-display);
@@ -633,6 +658,25 @@
font-weight: var(--weight-medium, 500);
}
+/* The builder credit sits above the card's full-surface title link, so it needs
+ its own stacking context to stay clickable. */
+.sp-card-meta a,
+.sp-featured-copy .sp-card-meta a {
+ position: relative;
+ z-index: 1;
+ color: var(--ink-dim, rgba(255, 255, 255, 0.62));
+ text-decoration: none;
+ border-bottom: 1px solid var(--stroke, rgba(255, 255, 255, 0.14));
+ transition:
+ color var(--duration-fast, 140ms) var(--ease-standard),
+ border-color var(--duration-fast, 140ms) var(--ease-standard);
+}
+
+.sp-card-meta a:hover {
+ color: var(--ink-bright, #fff);
+ border-bottom-color: var(--stroke-strong, rgba(255, 255, 255, 0.4));
+}
+
.sp-tags {
display: flex;
flex-wrap: wrap;
@@ -691,6 +735,14 @@
/* ── vote ─────────────────────────────────────────────────────────────── */
+/* In the featured CTA row the vote button sits beside real buttons, so it
+ matches their height instead of shrink-wrapping to its two tiny lines. */
+.sp-ctas .sp-vote {
+ flex-direction: row;
+ gap: 6px;
+ padding: 10px var(--space-sm, 12px);
+}
+
.sp-vote {
display: inline-flex;
flex-direction: column;
diff --git a/src/spotlight.js b/src/spotlight.js
index 1de7a8d61..1d370c407 100644
--- a/src/spotlight.js
+++ b/src/spotlight.js
@@ -151,50 +151,82 @@ function loadAgent3d() {
document.head.appendChild(s);
}
+// Hide the still only once <agent-3d> has painted a canvas of its own. There is
+// no documented ready event on the component, and a canvas in the DOM is the
+// one signal that means the model is genuinely on screen. Give up after a
+// bounded wait and leave the still in place, which is the correct outcome when
+// the GLB never arrives.
+function revealWhenPainted(viewer, still) {
+ let settled = false;
+ const done = () => {
+ if (settled) return;
+ settled = true;
+ observer.disconnect();
+ clearTimeout(timer);
+ still.classList.add('is-hidden');
+ };
+ const painted = () =>
+ Boolean(viewer.querySelector('canvas') || viewer.shadowRoot?.querySelector('canvas'));
+
+ const observer = new MutationObserver(() => {
+ if (painted()) done();
+ });
+ observer.observe(viewer, { childList: true, subtree: true });
+ const timer = setTimeout(() => {
+ observer.disconnect();
+ }, 15000);
+ if (painted()) done();
+}
+
function stageFor(entry) {
const stage = el('div', { class: 'sp-stage' });
stage.append(el('span', { class: 'sp-stage-badge', text: "Editor's pick" }));
- if (entry.agent.glb_url) {
- // Mounted only when the stage is actually on screen. Below-the-fold WebGL
- // on a browse page costs a visitor real frames for something they may
- // never scroll to.
- const mount = () => {
- loadAgent3d();
- stage.append(
- el('agent-3d', {
- body: entry.agent.glb_url,
- autorotate: 'true',
- 'camera-controls': 'true',
- 'aria-label': `${entry.agent.name} in 3D`,
- }),
- );
- };
- if ('IntersectionObserver' in window) {
- const io = new IntersectionObserver(
- (entries, obs) => {
- if (entries.some((e) => e.isIntersecting)) {
- obs.disconnect();
- mount();
- }
- },
- { rootMargin: '200px' },
- );
- io.observe(stage);
- } else {
- mount();
- }
- } else if (entry.agent.thumbnail) {
- stage.append(
- el('img', {
+ // The still image goes in first and stays until the 3D viewer has actually
+ // painted a canvas. A GLB can fail to load for reasons this page does not
+ // control (a cold CDN, a blocked origin, no WebGL on the device), and a
+ // silently empty hero is the worst version of that failure.
+ const still = entry.agent.thumbnail
+ ? el('img', {
+ class: 'sp-stage-still',
src: entry.agent.thumbnail,
alt: `${entry.agent.name} avatar`,
loading: 'lazy',
decoding: 'async',
- }),
+ })
+ : monogram(entry.agent);
+ stage.append(still);
+
+ if (!entry.agent.glb_url) return stage;
+
+ // Mounted only when the stage is actually on screen. Below-the-fold WebGL on
+ // a browse page costs a visitor real frames for something they may never
+ // scroll to.
+ const mount = () => {
+ loadAgent3d();
+ const viewer = el('agent-3d', {
+ body: entry.agent.glb_url,
+ autorotate: 'true',
+ 'camera-controls': 'true',
+ 'aria-label': `${entry.agent.name} in 3D`,
+ });
+ stage.append(viewer);
+ revealWhenPainted(viewer, still);
+ };
+
+ if ('IntersectionObserver' in window) {
+ const io = new IntersectionObserver(
+ (entries, obs) => {
+ if (entries.some((e) => e.isIntersecting)) {
+ obs.disconnect();
+ mount();
+ }
+ },
+ { rootMargin: '200px' },
);
+ io.observe(stage);
} else {
- stage.append(monogram(entry.agent));
+ mount();
}
return stage;
}
diff --git a/tests/showcase-ranking.test.js b/tests/showcase-ranking.test.js
new file mode 100644
index 000000000..68cf57967
--- /dev/null
+++ b/tests/showcase-ranking.test.js
@@ -0,0 +1,143 @@
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { CATEGORIES, GRAVITY, SORTS, isCategory, mapEntry, trendingScore } from '../api/_lib/showcase-store.js';
+
+const DAY = 86_400_000;
+const NOW = Date.UTC(2026, 8, 1, 12, 0, 0);
+
+function at(daysAgo) {
+ return new Date(NOW - daysAgo * DAY).toISOString();
+}
+
+describe('spotlight trending score', () => {
+ it('matches the published formula exactly', () => {
+ // The doc and the STRUCTURE row both quote (votes + 1) / (age_days + 1) ^ 1.2.
+ // If this drifts, one of the three is lying to a reader.
+ const score = trendingScore({ voteCount: 7, createdAt: at(3), now: NOW });
+ expect(score).toBeCloseTo(8 / Math.pow(4, GRAVITY), 10);
+ });
+
+ it('keeps a brand-new entry with no votes above a month-old entry with a few', () => {
+ const fresh = trendingScore({ voteCount: 0, createdAt: at(0), now: NOW });
+ const stale = trendingScore({ voteCount: 2, createdAt: at(30), now: NOW });
+ expect(fresh).toBeGreaterThan(stale);
+ });
+
+ // This is the property the hour-scaled Hacker News curve fails at this
+ // surface's volume: it decays so fast that any fresh empty entry outranks a
+ // week-old entry everyone liked, which turns trending into newest.
+ it('keeps a week-old entry with real support above a fresh empty one', () => {
+ const fresh = trendingScore({ voteCount: 0, createdAt: at(0), now: NOW });
+ const loved = trendingScore({ voteCount: 20, createdAt: at(7), now: NOW });
+ expect(loved).toBeGreaterThan(fresh);
+ });
+
+ it('still lets recency beat a stale favourite eventually', () => {
+ const fresh = trendingScore({ voteCount: 0, createdAt: at(0), now: NOW });
+ const old = trendingScore({ voteCount: 20, createdAt: at(60), now: NOW });
+ expect(fresh).toBeGreaterThan(old);
+ });
+
+ it('leaves a day-old entry within reach of a fresh one', () => {
+ const fresh = trendingScore({ voteCount: 0, createdAt: at(0), now: NOW });
+ const day = trendingScore({ voteCount: 0, createdAt: at(1), now: NOW });
+ const ratio = day / fresh;
+ expect(ratio).toBeGreaterThan(0.4);
+ expect(ratio).toBeLessThan(0.5);
+ });
+
+ it('treats a future or unparseable timestamp as age zero rather than NaN', () => {
+ expect(trendingScore({ voteCount: 1, createdAt: at(-5), now: NOW })).toBeCloseTo(2, 10);
+ expect(Number.isFinite(trendingScore({ voteCount: 1, createdAt: 'not a date', now: NOW }))).toBe(true);
+ });
+});
+
+describe('spotlight SQL and JS agree', () => {
+ it('computes the same expression in the ORDER BY as trendingScore does', () => {
+ const source = readFileSync(new URL('../api/_lib/showcase-store.js', import.meta.url), 'utf8');
+ // The ranking exists twice by necessity (Postgres orders the page, JS
+ // reports the score on each row). Pin the SQL shape so a change to one
+ // without the other fails here instead of silently reordering the page.
+ expect(source).toMatch(/\(coalesce\(v\.n, 0\) \+ 1\)::numeric/);
+ expect(source).toMatch(/power\(extract\(epoch from \(now\(\) - s\.created_at\)\)::numeric \/ 86400\.0 \+ 1, \$\{GRAVITY\}::numeric\)/);
+ });
+});
+
+describe('spotlight categories', () => {
+ it('exposes a stable slug set the API validates against', () => {
+ expect(CATEGORIES.length).toBeGreaterThan(0);
+ for (const c of CATEGORIES) {
+ expect(c.slug).toMatch(/^[a-z]+$/);
+ expect(c.label.length).toBeGreaterThan(0);
+ expect(isCategory(c.slug)).toBe(true);
+ }
+ });
+
+ it('rejects anything not in the set, case-insensitively', () => {
+ expect(isCategory('TRADING')).toBe(true);
+ expect(isCategory('bogus')).toBe(false);
+ expect(isCategory('')).toBe(false);
+ expect(isCategory(null)).toBe(false);
+ });
+
+ it('offers exactly the three sorts the page renders', () => {
+ expect([...SORTS].sort()).toEqual(['new', 'top', 'trending']);
+ });
+});
+
+describe('spotlight row mapping', () => {
+ const row = {
+ id: 'e1',
+ title: 'A title',
+ tagline: 'A tagline long enough to be real',
+ story: null,
+ demo_url: null,
+ category: 'research',
+ tags: ['on-chain'],
+ source: 'curated',
+ featured_at: null,
+ view_count: 3,
+ created_at: at(2),
+ agent_id: 'a1',
+ agent_name: 'Nova',
+ agent_description: 'does things',
+ agent_skills: ['think'],
+ agent_meta: {},
+ erc8004_agent_id: null,
+ agent_created_at: at(500),
+ avatar_thumbnail_key: 'thumb/x.png',
+ avatar_storage_key: 'u/x.glb',
+ avatar_visibility: 'private',
+ builder_display_name: 'Ada',
+ builder_username: null,
+ vote_count: 4,
+ chat_count: 9,
+ action_count: 0,
+ voted_by_me: false,
+ editable_by_me: false,
+ };
+
+ it('never emits a URL for a private avatar', () => {
+ const entry = mapEntry(row, { now: NOW });
+ expect(entry.agent.thumbnail).toBeNull();
+ expect(entry.agent.glb_url).toBeNull();
+ });
+
+ it('credits a builder without a username but gives no dead profile link', () => {
+ const entry = mapEntry(row, { now: NOW });
+ expect(entry.builder).toEqual({ name: 'Ada', username: null, profile_url: null });
+ });
+
+ it('reports the same score the ranking uses', () => {
+ const entry = mapEntry(row, { now: NOW });
+ expect(entry.trending_score).toBeCloseTo(trendingScore({ voteCount: 4, createdAt: row.created_at, now: NOW }), 6);
+ });
+
+ it('marks an on-chain agent from any of the identity fields', () => {
+ expect(mapEntry(row, { now: NOW }).agent.is_registered).toBe(false);
+ expect(mapEntry({ ...row, erc8004_agent_id: 12n }, { now: NOW }).agent.is_registered).toBe(true);
+ expect(
+ mapEntry({ ...row, agent_meta: { onchain: { network: 'mainnet' } } }, { now: NOW }).agent.is_registered,
+ ).toBe(true);
+ });
+});