Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
feat(announce): capture real media and gate the copy for the 320-surface backlog
nirholasf066b7f0aa94
diff --git a/.gitignore b/.gitignoreindex 1b8b616b9..8151d981e 100644--- a/.gitignore+++ b/.gitignore@@ -564,3 +564,22 @@ public/models/voice/runtime/# Playwright/agent walk screenshots. Scratch output, never commit..shots/++# Announcement media captured from a surface that renders live third-party+# market data. The frames are real and the pipeline needs them, but committing+# one bakes whatever tickers were on screen into the repo, which is the+# operating rules' commit gate on crypto projects other than $THREE. They stay+# out of the tree (and out of a concurrent agent's `git add -A` sweep) until the+# owner approves that specific frame; approval is recorded on the shot in+# data/announce-media.json as thirdPartyMarketDataApproved.+public/announce/img/activity-*++# The announcement ledger, held out of the tree pending owner approval. Its+# entries copy descriptions verbatim out of data/pages.json and packages/*, and+# a handful of those name crypto projects other than $THREE. Nothing there is+# new to the repo (every string already ships in a committed file), but the gate on+# other-coin content is the owner's to lift, not an agent's to assume. Ignored+# rather than merely untracked so a concurrent `git add -A` sweep cannot commit+# it on someone else's behalf. Regenerate any time with+# `npm run announce:rank -- --write --probe`; delete this rule once approved.+data/announcements.jsondiff --git a/STRUCTURE.md b/STRUCTURE.mdindex 875a31e71..19e851254 100644--- a/STRUCTURE.md+++ b/STRUCTURE.md@@ -451,6 +451,7 @@ array. Runbook: [docs/contributing.md](docs/contributing.md#publishing-packages-- **On-chain identity & contracts** — [contracts/](contracts), [packages/avatar-schema/](packages/avatar-schema)- **API endpoints** — [api/](api) (serverless-style handlers, served in production by the [server/](server) Cloud Run container), [workers/](workers) (long-running workers)- **Examples & demos** — [examples/](examples), [multiplayer/](multiplayer)+- **Announcement pipeline**: [docs/announcements/](docs/announcements/README.md) (one pack per feature: the claim and its evidence, the postable text, the media by shot id, the Telegram variant), [data/announcements.json](data/announcements.json) (the ledger: every shipped surface, whether it was ever announced, its score and its stage), [data/announce-media.json](data/announce-media.json) (media recipes captured from the live product into `public/announce/`), [docs/announce-voice.md](docs/announce-voice.md) (the voice contract, derived from the engagement archive). `npm run announce:rank` ranks the backlog, `npm run announce:media` captures the frames, `npm run check:announce` gates a pack. Nothing here posts: publishing stays owner-gated.- **Marketing assets** — [marketing/](marketing/README.md) (produced promo videos + re-render scripts, e.g. [marketing/imessage-video/](marketing/imessage-video); source-of-truth assets, not shipped to production)- **Platform agents (server-side)**: [agents/](agents/README.md) (endpoint-shopper, fact-checker, tutor, unstoppable, x402-buildout: library modules imported by `api/` handlers, each with its own README)- **Site data files**: [data/](data/README.md) (pages.json, changelog.json, skills seed, RSS items: what each file drives and which script regenerates it)diff --git a/data/announce-media.json b/data/announce-media.jsonnew file mode 100644index 000000000..70a69e135--- /dev/null+++ b/data/announce-media.json@@ -0,0 +1,51 @@+{+ "$comment": "Announcement media recipes. Captured by `npm run announce:media`, which runs scripts/capture-doc-media.mjs against this spec. Same engine as the docs figures on purpose: a real route in a real Chromium, motion loops sampled from the running product, and provenance written beside the pixels. Viewport 'wide' is 1600x900, the 16:9 frame X and Telegram both render uncropped. `surface` is the key in data/announcements.json, which is how a pack finds its media. Shots that need a signed-in view set `auth` and use the QA account in .env; `hide` records what was framed out.",+ "defaults": {+ "viewport": "wide",+ "theme": "dark",+ "settle": 6000+ },+ "shots": [+ {+ "id": "activity-hero",+ "surface": "/activity",+ "url": "/activity",+ "alt": "The three.ws Agent Activity trading floor: live conviction-scored trades from autonomous 3D agents on pump.fun, with agents armed, 24h scored, win rate and a top-agent leaderboard",+ "caption": "The trading floor as it actually reads: every row a real action, with the conviction that triggered it."+ },+ {+ "id": "activity-live",+ "surface": "/activity",+ "url": "/activity",+ "alt": "Animated loop of the three.ws Agent Activity feed updating in real time as autonomous agents score and trade pump.fun launches",+ "caption": "Not a mock-up: the feed captured while it streamed.",+ "settle": 9000,+ "motion": { "seconds": 5, "fps": 12 }+ },+ {+ "id": "genesis-hero",+ "surface": "/genesis",+ "url": "/genesis",+ "alt": "The three.ws Genesis page signed in: describe an agent, upload a selfie, or remix a public avatar, and it becomes a rigged 3D agent with its own wallet and on-chain identity",+ "caption": "Genesis, signed in: three ways to start, one minute to an owned agent.",+ "auth": true,+ "hide": ["#home-nav-user"]+ },+ {+ "id": "three-token-hero",+ "surface": "@three-ws/three-token-mcp",+ "url": "/three-token",+ "alt": "The $THREE token page on three.ws: live price, market cap, holder count, a fully graduated bonding curve and streaming live trades",+ "caption": "The live $THREE rail the MCP burn tools settle against."+ },+ {+ "id": "three-token-trades",+ "surface": "@three-ws/three-token-mcp",+ "url": "/three-token",+ "alt": "Animated loop of live $THREE trades streaming onto the three.ws token page",+ "caption": "The trade feed, captured live.",+ "settle": 9000,+ "motion": { "seconds": 5, "fps": 12 }+ }+ ]+}diff --git a/docs/announce-voice.md b/docs/announce-voice.mdnew file mode 100644index 000000000..d58c3c5f0--- /dev/null+++ b/docs/announce-voice.md@@ -0,0 +1,151 @@+# The announcement voice++**Status:** the contract every announcement pack in [`docs/announcements/`](./announcements/) is written and+checked against. **Last measured against the archive:** 2026-09-04.++three.ws has shipped 430 surfaces and posted about roughly 50 of them. The backlog is inventory,+not a roadmap, and working it down means writing a lot of announcements. The failure mode that+threatens is not running out of features. It is that 300 posts written quickly all start to sound+like the same machine wrote them, and an audience that smells a template stops reading the ones+that matter.++So this file is the anti-template. Everything in it is derived from two sources on disk, and it+names them so a claim here can be re-checked rather than believed:++- [`data/x-archive/trythreews-2026-08-14.json`](../data/x-archive/trythreews-2026-08-14.json), 359+ scraped posts, 214 of them ours.+- [`data/x-archive/analysis/trythreews-engagement.json`](../data/x-archive/analysis/trythreews-engagement.json),+ the engagement report over the 158 of those with usable metrics.++---++## What the numbers actually say++Median engagement lift by signal, from the engagement report. "Lift" is the signal's median against+the account's overall median of 12.++| Signal | Lift | Sample | What it means for a draft |+|---|---|---|---|+| $THREE / token topic | **13.3x** | 4 | The token is not a side note. When a feature genuinely touches it, lead with that. |+| Mentions an account | **4.5x** | 21 | Tag the partner a feature really runs on. Never tag one it does not. |+| 100-179 characters | **3.0x** | 17 | The best band reachable in a single post. This is the default. |+| 180-279 characters | 1.67x | 17 | Fine when the mechanism genuinely needs the room. |+| Has an image | **2.3x** | 14 | Non-negotiable. See below. |+| Contains a link | 1.5x | 18 | The link is how anyone gets to the thing. Always include it. |+| **1-99 characters** | **0.83x** | **121** | The account's single biggest problem. |+| **Text only** | **0.875x** | **132** | The second biggest. |+| Has a video | 0.71x | 6 | An uploaded video underperformed a still. Prefer an animated WebP or a real screenshot. |++Read the last three rows together: **121 of 158 measured posts were one-liners and 132 carried no+media at all.** They are the bulk of the account's output and they are the bottom of its+performance. Nothing in this document matters more than not writing another one.++## The five rules++1. **Every post ships an image.** Not a stock graphic: a frame of the real product, captured by+ `npm run announce:media` from the live route. A pack with no media is not finished and the+ gate fails it.+2. **100 characters is the floor and 179 is the target ceiling.** Under 100 a draft is missing the+ mechanism: say how the thing works, not that it exists. Above 179 the measured lift halves.+ The hard wall is 280 weighted characters, which `scripts/post-tweet.mjs` enforces and which a+ URL costs 23 of no matter its real length. The archive's 280-499 band (4.75x over 3 posts) is+ real but not reachable in a single post; that shape is a thread or the Telegram register.+ Check every draft with `node scripts/post-tweet.mjs --file <pack>.post.txt --dry-run`, which+ prints the weighted count and refuses anything over the wall.+3. **One claim, and it has to be checkable.** Every number in a post comes from the captured+ frame or a linked page. If the media says 86% win rate, the post may say 86% win rate. If+ nothing on screen supports a number, it does not go in.+4. **Tag only what is true.** `@solana` when it settles on Solana. `@AnthropicAI` when it is an+ MCP server. `@IBM` when it runs on watsonx. A tag we cannot defend costs more than the 4.5x+ is worth.+5. **Link the surface.** One link, to the page the post is about.++## How this account already sounds++Measured across the 214 posts we have written, not asserted:++- **0 hashtags.** Never add one.+- **0 emoji.** Never add one.+- **2 em-dashes**, and the house style bans the character outright. Use a period, a comma, a+ colon, or parentheses.+- **1 post out of 214 opened with "Introducing".** That is the existing voice and it is a good+ one. Keep it.++## Banned openings++These are the tells that make a post read as generated. None of them appear in our best posts and+the gate rejects all of them:++> Introducing. We're excited to announce. We're thrilled. Say hello to. Meet the new. Big news.+> Today we're launching. Ever wondered. What if you could. Imagine a world where. Game-changer.+> Revolutionary. Seamless. Unlock the power of. Take your X to the next level. The future of X is+> here. And the best part? Let that sink in. Here's the kicker.++Also banned as structure, not just as phrases:++- **The rhetorical-question opener.** "What if your agent could trade for you?" Just say what it does.+- **The one-word-sentence drumbeat.** "Fast. Simple. On-chain." It reads as copywriting, and this+ audience discounts copywriting.+- **The thread that withholds.** Do not make the first post a teaser for the second. Lead with the+ strongest true statement.+- **Adjective stacking.** "A powerful, seamless, next-generation platform." Cut every adjective+ that a reader could not disagree with.++## What to write instead++Open with the mechanism or the number. The strongest posts in the archive do exactly this: they+state a specific, surprising, checkable fact in the first line and let the reader decide it is+impressive.++Three patterns that fit the measured bands:++**The number lead** (100-179 chars). Open on a figure the screenshot proves.++> Seven autonomous agents have scored 832,142 pump.fun launches on three.ws. 86% win rate on the+> top one. Every trade on the floor is live: three.ws/activity++**The mechanism lead** (100-179 chars). Open on how it works, because the how is the interesting part.++> A sentence or a selfie becomes a rigged 3D agent holding its own custodial @solana wallet, a+> persona, and a voice. It walks and emotes on arrival: three.ws/genesis++**The correction lead**, for a feature that contradicts an assumption the reader holds.++> Most "AI agent wallets" are a key in someone's env file. Guardian makes an agent wallet+> recoverable and inheritable: name a guardian, set the timelock, and the wallet survives the+> agent. three.ws/guardian++## Uniqueness, enforced++Announcing 300 features means 300 posts that must not blur together. Two mechanical checks in+`npm run check:announce`:++- **No opening clause is reused.** The first eight words of every pack are compared against every+ other pack. A repeat fails.+- **No pack reuses another pack's lead structure twice in a row.** The pattern (number lead,+ mechanism lead, correction lead) rotates.++Neither check can make a post good. Both stop the corpus from converging on one shape, which is+what makes a run of announcements read as automated.++## The pack++One file per feature in `docs/announcements/<slug>.md`, holding everything a post needs and+nothing it does not. See [`genesis.md`](./announcements/genesis.md) for the worked example. Every+pack carries:++- **The claim**, and the evidence for it, with a link to where it can be checked.+- **The post**, inside the length band, in this voice.+- **The media**, by shot id from [`data/announce-media.json`](../data/announce-media.json), with+ its alt text. Alt text is a requirement, not a courtesy: a post whose whole payload is an image+ is unreadable to a screen reader without it.+- **The Telegram variant.** The community channel takes plain text and a different register: more+ detail, no character ceiling worth worrying about, no tagging.+- **The changelog entry**, ready to paste into `data/changelog.json`.+- **Its state**, mirrored in [`data/announcements.json`](../data/announcements.json).++## What this file does not decide++Posting. Publishing to an external channel is an owner-gated action under the operating rules,+every time, and nothing in this pipeline posts anything. A finished pack is a finished pack: the+owner runs the one command.diff --git a/docs/announcements/README.md b/docs/announcements/README.mdnew file mode 100644index 000000000..2e50a870a--- /dev/null+++ b/docs/announcements/README.md@@ -0,0 +1,61 @@+# Announcement packs++One file per feature we are announcing, plus the exact bytes that get posted.++three.ws has shipped 430 surfaces and posted about roughly 50. The other 320 are not a roadmap,+they are inventory that already works, and the audit that established this lives in+[announcement-coverage.md](../announcement-coverage.md). Working that backlog down is what this+directory is for.++## How a pack gets made++```bash+npm run announce:rank # what to announce next, and why+npm run announce:media # capture the frames from the live product+npm run check:announce # gate the pack before anyone reads it+```++1. **Rank.** [`scripts/announce-rank.mjs`](../../scripts/announce-rank.mjs) re-derives the+ inventory from `data/pages.json`, `packages/`, `workers/` and `services/`, reads the announced+ status out of the coverage audit, probes each route, scores what is left, and writes+ [`data/announcements.json`](../../data/announcements.json). The score's weights come from the+ engagement archive, not from taste; the sources are named in+ [announce-voice.md](../announce-voice.md).+2. **Capture.** Add a shot to [`data/announce-media.json`](../../data/announce-media.json) and run+ `npm run announce:media`. It drives the real route in a real Chromium and writes to+ `public/announce/img/` with provenance (route, commit, time, sha256) beside the pixels. Shots+ marked `auth` sign in with the QA account so the frame shows the working product rather than+ its sign-in gate.+3. **Write.** One `<slug>.md` pack and one `<slug>.post.txt` holding the post itself. The `.txt`+ exists so the bytes the gate checks are the bytes `post-tweet.mjs` sends; a post quoted only+ in prose drifts from the file that ships.+4. **Gate.** `npm run check:announce` enforces media, alt text, length, voice, cross-pack+ uniqueness, and the coin gate.++**Ranking is a hypothesis; the capture is the test.** Two of the first batch's highest-scoring+surfaces were deferred once their frames were looked at: `/genome` sells an empty stud market and+`/portfolio` is an address input with nothing in it. The reasons are recorded on their entries in+the ledger, which is why the capture step comes before the writing step.++## The coin gate++A frame captured from a live trading surface bakes whatever tickers were on screen into a+committed file, and the operating rules require owner approval before committing anything that+references a crypto project other than `$THREE`. `check:announce` fails such a pack, and the+affected files are kept out of the tree by `.gitignore` until approval is recorded on the shot as+`thirdPartyMarketDataApproved`.++## Posting++Nothing here posts. Publishing to an external channel is owner-gated every time. A finished pack+means the owner runs one command:++```bash+node scripts/post-tweet.mjs --file docs/announcements/<slug>.post.txt --dry-run+```++## Packs++| Pack | Surface | Stage |+|---|---|---|+| [genesis.md](./genesis.md) | [`/genesis`](https://three.ws/genesis) | drafted, awaiting approval to post |diff --git a/docs/announcements/genesis.md b/docs/announcements/genesis.mdnew file mode 100644index 000000000..d35a35178--- /dev/null+++ b/docs/announcements/genesis.md@@ -0,0 +1,118 @@+# Announcement pack: Instant Agent Genesis++**Surface:** [`/genesis`](https://three.ws/genesis) · **Ledger key:** `/genesis` · **Stage:** drafted+· **Shipped:** 2026-06-23 · **Announced externally:** never++Ranked first of 320 never-announced surfaces by `npm run announce:rank` (score 106: sitemap+priority 0.9, showcase, token topic, taggable partner, on the audit's shortlist, backed by a+feature doc). Written against [the announcement voice](../announce-voice.md).++---++## The claim, and where it is checked++> A sentence or a selfie becomes a rigged 3D agent that already owns a custodial Solana wallet+> and a custodial EVM wallet, a synthesized persona, a voice, and an optional on-chain identity,+> in under a minute of active work.++Every part of that is verifiable in the tree, which is the only reason it can be posted:++| Part of the claim | Where it is real |+|---|---|+| Prompt or selfie to a textured 3D body | `POST /api/avatars/reconstruct`, the same pipeline behind `/create/prompt` and `/create/selfie` |+| Rigged, not a T-posed mesh | The pipeline chains an auto-rig job and only surfaces the avatar once it can be animated |+| Custodial Solana wallet and custodial EVM wallet | `POST /api/agents/:id/wallet/provision`, real custodial keys ([Agent Wallets](../agent-wallets.md), [Custody](../custody.md)) |+| Synthesized persona and voice | `POST /api/persona/extract` through the shared free-providers-first LLM chain; voices from `/api/tts/voices` |+| Optional on-chain identity | A real [ERC-8004](../erc8004.md) record returning a real transaction hash, defaulting to Base |+| Under a minute of active work | The flow is a state machine over those production endpoints, with a progress bar driven by real job state |++Full mechanism: [docs/genesis.md](../genesis.md).++## Media++Captured from the live route by `npm run announce:media`. Provenance (route, commit, time, sha256)+is in [`public/announce/media-manifest.json`](../../public/announce/media-manifest.json).++| Shot | File | Notes |+|---|---|---|+| `genesis-hero` | `/announce/img/genesis-hero.webp` | 1800x1013, signed in. The three entry modes and the describe field, which is the whole interface. |++**Alt text, required on the post:**++> The three.ws Genesis page signed in: describe an agent, upload a selfie, or remix a public+> avatar, and it becomes a rigged 3D agent with its own wallet and on-chain identity.++The frame is captured against a signed-in QA session so it shows the working page rather than its+sign-in gate. The nav's account chip is framed out, the same call as the corner promo; the recipe+in [`data/announce-media.json`](../../data/announce-media.json) records it.++## The post++Pattern: mechanism lead. **163 weighted characters**, inside the 100-179 band that measured a 3.0x+lift and the best band reachable in a single post. Tags `@solana` because the agent's primary+wallet is genuinely a Solana wallet, and Solana is the home chain.++Postable file: [`genesis.post.txt`](./genesis.post.txt).++```text+A sentence or a selfie becomes a rigged 3D agent holding its own custodial @solana wallet, a persona, and a voice. It walks and emotes on arrival: three.ws/genesis+```++Ship it with `genesis-hero` attached and the alt text above.++### Why it is written that way++The temptation is "Introducing Instant Agent Genesis", and 213 of our 214 posts have correctly+resisted that opening. The interesting fact here is not that the page exists, it is that the thing+it hands back is already funded, already rigged, and already has a voice. So the post opens on the+mechanism and lets the reader reach "that is a lot for one sentence of input" without being told+to. "It walks and emotes on arrival" is doing specific work: it pre-empts the reasonable+assumption that a generated character arrives as a static T-posed mesh, which is what every other+text-to-3D tool hands back.++Two true details were cut to hold the band: the second custodial wallet on Base, and the optional+ERC-8004 identity returning a real transaction hash. Both are in the Telegram variant, where there+is room. Cutting them is a length decision, not a hedge; neither is in doubt.++## Telegram variant++Plain text for the community channel. No tagging, no character ceiling worth managing, more+mechanism, and it says what to do with the thing.++```text+Instant Agent Genesis is live at three.ws/genesis, and it has never been posted about.++Give it a sentence, a selfie, or a public avatar to remix. What comes back is a full agent, not a+model file:++- A textured 3D body off the same reconstruction pipeline /create uses, auto-rigged so it walks+ and emotes immediately rather than arriving in a T-pose.+- Its own custodial Solana wallet and its own custodial EVM wallet, provisioned as part of the+ flow. Real custodial keys, not placeholders.+- A persona synthesized from your description, and a voice you pick.+- Optionally, a real ERC-8004 on-chain identity that returns a real transaction hash.++Under a minute of active work, and the agent is yours: it plugs straight into Agent Studio, the+economy, breeding, and every embed surface.++three.ws/genesis+```++## Changelog++**No new entry.** Genesis was already logged on 2026-06-23 ("Instant Agent Genesis: a selfie or a+sentence becomes a funded, on-chain 3D agent in under a minute"). This pack announces an existing+feature externally for the first time; it ships nothing new, so adding an entry would tell the+community something shipped today that did not.++## Posting++Publishing to an external channel is owner-gated under the operating rules, every time. Nothing in+this pipeline posts. When the owner approves:++```bash+node scripts/post-tweet.mjs --file docs/announcements/genesis.post.txt --dry-run+```++Drop `--dry-run` to send. The Telegram variant goes to the community channel by hand; the+changelog cron must not be used for it, because this is not a changelog entry.diff --git a/docs/announcements/genesis.post.txt b/docs/announcements/genesis.post.txtnew file mode 100644index 000000000..e88c8c698--- /dev/null+++ b/docs/announcements/genesis.post.txt@@ -0,0 +1 @@+A sentence or a selfie becomes a rigged 3D agent holding its own custodial @solana wallet, a persona, and a voice. It walks and emotes on arrival: three.ws/genesis\ No newline at end of filediff --git a/package.json b/package.jsonindex 57d51fcbe..da307ed1e 100644--- a/package.json+++ b/package.json@@ -183,6 +183,9 @@"i18n:repair": "node scripts/i18n-translate.mjs --repair","i18n:backfill": "node scripts/i18n-backfill.mjs","changelog:gaps": "node scripts/changelog-gaps.mjs",+ "announce:rank": "node scripts/announce-rank.mjs",+ "announce:media": "node scripts/capture-doc-media.mjs --spec data/announce-media.json --out public/announce/img --manifest public/announce/media-manifest.json",+ "check:announce": "node scripts/check-announce.mjs","changelog:push": "node scripts/changelog-telegram.mjs","changelog:push:x": "node scripts/changelog-x.mjs","tweet": "node scripts/post-tweet.mjs",@@ -442,7 +445,8 @@"home:instance:down": "node scripts/home-test-instance.mjs --down --name lane","test:home:live": "HOME_LIVE=1 vitest run packages/home-bridge tests/home-store.test.js","home:matrix": "node scripts/home-version-matrix.mjs",- "test:home:e2e": "node --env-file=.env.local ./node_modules/@playwright/test/cli.js test --config=playwright.home.config.js"+ "test:home:e2e": "node --env-file=.env.local ./node_modules/@playwright/test/cli.js test --config=playwright.home.config.js",+ "deck:inception": "node scripts/build-inception-deck.mjs"},"dependencies": {"@0xsplits/splits-sdk": "^6.5.0",diff --git a/scripts/announce-rank.mjs b/scripts/announce-rank.mjsindex 59f9818d5..dd69e5e0d 100644--- a/scripts/announce-rank.mjs+++ b/scripts/announce-rank.mjs@@ -64,6 +64,13 @@ const asJson = flag('--json');const doWrite = flag('--write');const topN = Number(arg('--top', 30));+// Descriptions are copied verbatim out of package.json and pages.json, and a+// lot of them carry an em-dash. They are the raw material an announcement gets+// drafted from, so the glyph is normalized here rather than caught later in+// every draft: the house style bans it everywhere, this file included.+const DASHES = new RegExp('\\s*[\\u2014\\u2013]\\s*', 'g');+const clean = (text) => String(text || '').replace(DASHES, ', ').trim();+// --- inventory --------------------------------------------------------------// Sections of data/pages.json that hold product surfaces. 'learn' and 'blog'@@ -82,8 +89,8 @@ function pageInventory() {key: page.path,kind: 'page',section: section.id,- title: page.title,- description: page.description || '',+ title: clean(page.title),+ description: clean(page.description),added: page.added || null,sitemapPriority: typeof page.priority === 'number' ? page.priority : 0.5,showcase: Boolean(page.showcase),@@ -108,13 +115,13 @@ function dirInventory(base, kind, keyPrefix) {const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));if (pkg.private === true && kind === 'package') continue;title = pkg.name || title;- description = pkg.description || '';+ description = clean(pkg.description);} catch { /* an unparseable package.json still leaves a real directory */ }}if (!description && existsSync(join(dir, name.name, 'README.md'))) {const readme = readFileSync(join(dir, name.name, 'README.md'), 'utf8');const line = readme.split('\n').find((l) => l.trim() && !l.startsWith('#'));- description = (line || '').trim().slice(0, 240);+ description = clean(line).slice(0, 240);}out.push({key: kind === 'package' ? title : `${base}/${name.name}`,diff --git a/scripts/audit-docs.mjs b/scripts/audit-docs.mjsindex ee5e21bf0..bf73183c8 100644--- a/scripts/audit-docs.mjs+++ b/scripts/audit-docs.mjs@@ -273,11 +273,13 @@ if (!explicitFiles.length) {// a commit, so registering one is a decision, never a default.const UNPUBLISHED_DOCS = new Map([['agora', 'internal: strategy framing, not a reader-facing product doc'],+ ['announce-voice', 'internal: the voice contract announcement packs are written and gated against'],['announcement-coverage', 'internal: X announcement coverage matrix for marketing planning'],['announcement-coverage-telegram', 'internal: paste-ready holders-channel post drafted from the coverage matrix'],['avatar-cli', 'internal: in-flight, register when the CLI ships'],['avatar-fidelity-program', 'internal: program goals and competitive targets'],['aws-marketplace-listing-kit', 'internal: paste-ready listing copy and portal steps'],+ ['aws-builder-center-agent-commerce-spine', 'internal: draft prepared for the AWS Builder Center'],['big-tech-recognition-week', 'internal: outreach dispatch board naming unsent asks and unclaimed program benefits'],['bnb-babt-findings', 'owner-gated: names a crypto project other than $THREE'],['bnb-vault', 'owner-gated: names a crypto project other than $THREE'],@@ -289,6 +291,7 @@ const UNPUBLISHED_DOCS = new Map([['coin-pages', 'owner-gated: names a crypto project other than $THREE'],['coingecko-listing-update-2026-08', 'internal: dated listing-update notes prepared for an external venue'],['coinmarketcap-article', 'internal: draft prepared for an external publisher'],+ ['coinmarketcap-article-2026-09-agent-economy', 'internal: draft prepared for an external publisher'],['huggingface-3d-ai-agent-platform', 'internal: draft prepared for an external publisher (Hugging Face community article)'],['coinmarketcap-live-article', 'internal: draft prepared for an external publisher'],['coinmarketcap-article-play', 'internal: draft prepared for an external publisher'],@@ -300,6 +303,7 @@ const UNPUBLISHED_DOCS = new Map([['free-crypto-apis', 'internal: engineering research catalog of external free APIs'],['google-x-accounts', 'internal: outreach directory of external X accounts'],['ibm-community-article', 'internal: source draft of an IBM Community post'],+ ['ibm-community-governed-agents-post', 'internal: source draft of an IBM Community post'],['ibm-community-live-reaction-jessica', 'internal: source draft of an IBM Community post'],['ibm-community-recap-jessica', 'internal: source draft of an IBM Community post'],['ibm-community-recap-nichxbt', 'internal: source draft of an IBM Community post'],@@ -313,6 +317,7 @@ const UNPUBLISHED_DOCS = new Map([['nvidia-nemotron-ask-the-experts-questions', 'internal: paste-ready live-chat copy drafted for an external stream'],['native-launchpad', 'owner-gated: names a crypto project other than $THREE'],['openai-community-3d-studio-post', 'internal: forum post drafted for an external developer community'],+ ['openai-community-physical-world-post', 'internal: forum post drafted for an external developer community'],['open-source-friday-plan', 'internal: program application plan and stream runsheet, not a reader-facing product doc'],['oracle-trading-mcp-plan', 'internal: build order for the Oracle and trading-agent MCP servers, not a reader-facing product doc'],['nvidia-apps-catalog-listing', 'internal: paste-ready listing copy and portal steps for the NVIDIA Inception catalog'],diff --git a/scripts/capture-doc-media.mjs b/scripts/capture-doc-media.mjsindex e1dc7d96e..112a28966 100644--- a/scripts/capture-doc-media.mjs+++ b/scripts/capture-doc-media.mjs@@ -55,11 +55,38 @@ import { fileURLToPath } from 'node:url';import { promisify } from 'node:util';import sharp from 'sharp';+/** Read AUDIT_EMAIL / AUDIT_PASSWORD out of .env the way the rest of scripts/ does. */+function loadDotEnv(file) {+ const full = path.join(ROOT_DIR, file);+ if (!existsSync(full)) return;+ for (const line of readFileSync(full, 'utf8').split('\n')) {+ const m = line.match(/^([A-Z0-9_]+)=(.*)$/);+ if (m && !(m[1] in process.env)) process.env[m[1]] = m[2].replace(/^["']|["']$/g, '');+ }+}+const run = promisify(execFile);-const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');-const SPEC_FILE = path.join(ROOT, 'data/doc-media.json');-const OUT_DIR = path.join(ROOT, 'public/docs/img');-const MANIFEST_FILE = path.join(ROOT, 'public/docs/media-manifest.json');+const ROOT_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');+const ROOT = ROOT_DIR;+loadDotEnv('.env.local');+loadDotEnv('.env');++/** Read a --name value straight off argv. Needed above the CLI block below, which parses argv into the richer opt(). */+function optRaw(name, fallback) {+ const i = process.argv.indexOf(`--${name}`);+ return i !== -1 && process.argv[i + 1] ? process.argv[i + 1] : fallback;+}+// Where a run reads its recipes and writes its pixels. The defaults are the+// docs' own figures; --spec/--out/--manifest point the same engine at another+// set. Announcement media (data/announce-media.json) uses that: it wants the+// identical guarantees (a real route in a real browser, a motion loop of the+// running product, provenance next to the bytes) and duplicating the engine to+// get them would mean two capture paths drifting apart.+const SPEC_FILE = path.join(ROOT, optRaw('spec', 'data/doc-media.json'));+const OUT_DIR = path.join(ROOT, optRaw('out', 'public/docs/img'));+const MANIFEST_FILE = path.join(ROOT, optRaw('manifest', 'public/docs/media-manifest.json'));+/** The web path the written files answer on, derived from OUT_DIR so a manifest never points at the wrong folder. */+const PUBLIC_SRC = `/${path.relative(path.join(ROOT, 'public'), OUT_DIR).split(path.sep).join('/')}`;// ── CLI ───────────────────────────────────────────────────────────────────────const argv = process.argv.slice(2);@@ -85,6 +112,29 @@ const VIEWPORTS = {square: { width: 900, height: 900 },};+// Site chrome that follows the visitor across every route and parks itself over+// a corner of the viewport. Removing the nodes once after load is not enough:+// the feature-discovery card is injected on a timer and reappeared during the+// settle, so the first announcement captures shipped with a "have you tried+// Forge" promo over the subject. A stylesheet installed before any script runs+// holds regardless of when a node appears, and the removal below still handles+// anything that ignores CSS.+const SITE_CHROME = [+ '#tws-corner-stack',+ '.tws-disc-card',+ '.tws-atlas-hint',+ '.twx-i18n-fab',+ // The walk companion roams every route and parks itself over the lower+ // right. It is one of our own features, which is exactly why it cannot sit+ // in a frame announcing a different one.+ '.walk-companion',+ '.walk-trail-layer',+ '.walk-c2w-fx',+ '#cookie-banner',+ '.cookie-banner',+ '[data-consent-banner]',+];+const SCALE = 2;/** Cap the emitted pixel width. Beyond this the extra bytes buy nothing in a doc column. */const MAX_OUT_WIDTH = 1800;@@ -199,12 +249,11 @@ async function preparePage(page, shot) {// over whatever the reader was told to look at. Framing it out is a crop,// not a fabrication: nothing about the documented surface changes.await page- .evaluate(() => {- const chrome = ['#tws-corner-stack', '#cookie-banner', '.cookie-banner', '[data-consent-banner]'];+ .evaluate((chrome) => {for (const selector of chrome) {for (const node of document.querySelectorAll(selector)) node.remove();}- })+ }, [...SITE_CHROME, ...(shot.hide || [])]).catch(() => {});await applyActions(page, shot.actions);await page.waitForTimeout(shot.settle ?? 3500);@@ -334,13 +383,60 @@ async function writeMotion(page, shot, subject, outPath) {}}+/**+ * One signed-in session, reused by every `auth: true` shot.+ *+ * Signed out, an authenticated surface shows its gate, and a gate is the one+ * thing an announcement must not show: the first Genesis capture was a "Sign in+ * to claim your agent" banner over empty inputs, which is a true picture of the+ * page and a false picture of the product. The QA account in .env+ * (AUDIT_EMAIL / AUDIT_PASSWORD) is a real production account, so what these+ * shots show is the real signed-in product with that account's own data.+ *+ * Returns null when the credentials are absent, and the caller then skips those+ * shots loudly rather than shipping a gate.+ */+let authStatePromise = null;+function authState(browser) {+ if (authStatePromise) return authStatePromise;+ authStatePromise = (async () => {+ const email = process.env.AUDIT_EMAIL;+ const password = process.env.AUDIT_PASSWORD;+ if (!email || !password) return null;+ const context = await browser.newContext({ viewport: VIEWPORTS.wide, deviceScaleFactor: 1 });+ const page = await context.newPage();+ try {+ await page.goto(`${BASE}/login`, { waitUntil: 'domcontentloaded', timeout: 60000 });+ // By id, not by input type: /login also renders a passwordless widget+ // whose own input[type=email] comes first in the DOM.+ await page.waitForSelector('#email', { timeout: 30000 });+ await page.fill('#email', email);+ await page.fill('#password', password);+ await page.click('form button[type="submit"]');+ await page.waitForURL((url) => !/\/login/.test(url.pathname), { timeout: 45000 });+ return await context.storageState();+ } catch (err) {+ console.error(`capture-doc-media: sign-in failed (${String(err.message || err).split('\n')[0]})`);+ return null;+ } finally {+ await context.close();+ }+ })();+ return authStatePromise;+}+async function captureShot(browser, shot, commit) {const viewport = VIEWPORTS[shot.viewport || 'desktop'];+ const storageState = shot.auth ? await authState(browser) : null;+ if (shot.auth && !storageState) {+ throw new Error('shot needs a signed-in session; set AUDIT_EMAIL and AUDIT_PASSWORD in .env');+ }const context = await browser.newContext({viewport,deviceScaleFactor: SCALE,colorScheme: shot.theme === 'light' ? 'light' : 'dark',reducedMotion: shot.motion ? 'no-preference' : 'reduce',+ ...(storageState ? { storageState } : {}),});// The site persists its own theme; set it before any script runs so the// first paint is already the theme the shot asked for.@@ -351,6 +447,16 @@ async function captureShot(browser, shot, commit) {/* storage disabled: the colorScheme hint above still applies */}}, shot.theme === 'light' ? 'light' : 'dark');+ await context.addInitScript((selectors) => {+ const css = `${selectors.join(',')}{display:none !important}`;+ const install = () => {+ const style = document.createElement('style');+ style.textContent = css;+ document.head?.appendChild(style);+ };+ if (document.head) install();+ else document.addEventListener('DOMContentLoaded', install, { once: true });+ }, [...SITE_CHROME, ...(shot.hide || [])]);const page = await context.newPage();// Stills and loops both ship as WebP: a UI screenshot at quality 90 is@@ -370,12 +476,14 @@ async function captureShot(browser, shot, commit) {const sha256 = createHash('sha256').update(readFileSync(outPath)).digest('hex');return {id: shot.id,- src: `/docs/img/${shot.id}.webp`,+ src: `${PUBLIC_SRC}/${shot.id}.webp`,alt: shot.alt,caption: shot.caption || null,route: shot.url,viewport: shot.viewport || 'desktop',animated: Boolean(shot.motion),+ authenticated: Boolean(shot.auth),+ hidden: shot.hide && shot.hide.length ? shot.hide : undefined,capturedAt: new Date().toISOString(),capturedFrom: BASE,commit,diff --git a/scripts/check-announce.mjs b/scripts/check-announce.mjsnew file mode 100644index 000000000..9386d1d8d--- /dev/null+++ b/scripts/check-announce.mjs@@ -0,0 +1,222 @@+#!/usr/bin/env node+// check-announce.mjs - the gate every announcement pack has to clear.+//+// The point of the announcement pipeline is to work a 320-surface backlog down+// without the output reading as machine-generated. That risk is not theoretical:+// 300 posts written from one template converge on one shape, an audience learns+// the shape, and then the announcements that matter get skipped along with the+// rest. Taste does not scale to 300 posts. Mechanical checks do, so the ones+// that can be mechanical are here.+//+// What it enforces, and why each one exists:+//+// • Media. A post with no image measured 0.875x against the account+// median, and 132 of our 158 measured posts had none. A pack+// with no captured frame is not finished.+// • Alt text. A post whose payload is an image is unreadable without it.+// • Length. Under 100 characters the mechanism is missing (121 of 158+// posts, the account's worst-performing shape). Over 280+// weighted characters X refuses it outright.+// • Voice. No hashtags, no emoji, no em-dashes, and none of the+// openings that mark generated marketing copy.+// • Uniqueness. No two packs may open with the same clause.+// • The coin gate. A pack that names a crypto project other than $THREE, or+// ships media captured from a surface that renders live+// third-party market data, needs recorded owner approval+// before it can be committed or posted. This is the operating+// rules' commit gate, applied to announcement assets, and it+// is the check most likely to actually fire: a screenshot of+// a live trading surface bakes whatever tickers were on+// screen into a committed file.+//+// It reads packs, never writes, and never posts.+//+// node scripts/check-announce.mjs # check every pack+// node scripts/check-announce.mjs --pack genesis+//+// Wired as `npm run check:announce`.++import { readFileSync, existsSync, readdirSync } from 'node:fs';+import { resolve, dirname, join, basename } from 'node:path';+import { fileURLToPath } from 'node:url';++const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');+const PACK_DIR = join(root, 'docs/announcements');+const MEDIA_SPEC = join(root, 'data/announce-media.json');+const MANIFEST = join(root, 'public/announce/media-manifest.json');++const argv = process.argv.slice(2);+const only = (() => {+ const i = argv.indexOf('--pack');+ return i >= 0 && argv[i + 1] ? argv[i + 1] : null;+})();++// X counts a URL as 23 characters however long it really is, and an astral+// codepoint as 2. Kept byte-compatible with scripts/post-tweet.mjs, which is+// what actually refuses an over-long post.+const weightedLength = (s) =>+ [...s.replace(/https?:\/\/\S+/g, 'x'.repeat(23))].reduce(+ (n, ch) => n + (ch.codePointAt(0) > 0xffff ? 2 : 1),+ 0,+ );++// Openings that mark a post as generated. Measured against our own archive:+// exactly one of 214 posts opened this way, so this bans a shape the account+// has already avoided rather than imposing a new one.+const BANNED_OPENINGS = [+ /^introducing\b/i,+ /^we(?:'re| are) (?:excited|thrilled|proud|happy)/i,+ /^say hello to\b/i,+ /^meet the new\b/i,+ /^big news\b/i,+ /^today we(?:'re| are) launching\b/i,+ /^ever wondered\b/i,+ /^what if you could\b/i,+ /^imagine a world\b/i,+];+const BANNED_PHRASES = [+ /\bgame[- ]chang(?:er|ing)\b/i,+ /\brevolutionary\b/i,+ /\bseamless(?:ly)?\b/i,+ /\bunlock the power\b/i,+ /\bnext level\b/i,+ /\bthe future of \w+ is here\b/i,+ /\band the best part\b/i,+ /\blet that sink in\b/i,+ /\bhere'?s the kicker\b/i,+ /\bsupercharge\b/i,+];++// Built from escapes on purpose: this repo bans both glyphs everywhere, so the+// detector cannot spell them out without failing its own rule.+const BANNED_DASHES = new RegExp('[\\u2014\\u2013]');++const problems = [];+const notes = [];+const fail = (pack, msg) => problems.push(`${pack}: ${msg}`);++if (!existsSync(PACK_DIR)) {+ console.log('check-announce: no docs/announcements/ yet, nothing to check');+ process.exit(0);+}++const spec = existsSync(MEDIA_SPEC) ? JSON.parse(readFileSync(MEDIA_SPEC, 'utf8')) : { shots: [] };+const shotsById = new Map((spec.shots || []).map((s) => [s.id, s]));+const manifest = existsSync(MANIFEST) ? JSON.parse(readFileSync(MANIFEST, 'utf8')) : {};+const manifestShots = new Map(+ (Array.isArray(manifest.shots) ? manifest.shots : Object.values(manifest.shots || {})).map((s) => [s.id, s]),+);++// Surfaces whose frames carry live third-party market data. Derived from+// data/pages.json rather than listed by hand, so a new crypto surface inherits+// the gate instead of quietly escaping it.+const cryptoPaths = new Set();+try {+ const pages = JSON.parse(readFileSync(join(root, 'data/pages.json'), 'utf8'));+ for (const section of pages.sections) {+ if (section.id !== 'crypto') continue;+ for (const page of section.pages) cryptoPaths.add(page.path);+ }+} catch {+ notes.push('data/pages.json unreadable: the coin gate could not classify surfaces');+}++const packs = readdirSync(PACK_DIR)+ .filter((f) => f.endsWith('.md'))+ // README.md documents the directory; it is not a pack.+ .filter((f) => f !== 'README.md')+ .filter((f) => !only || basename(f, '.md') === only);++if (!packs.length) {+ console.log(only ? `check-announce: no pack named ${only}` : 'check-announce: no packs yet');+ process.exit(only ? 1 : 0);+}++const openings = new Map();++for (const file of packs) {+ const name = basename(file, '.md');+ const body = readFileSync(join(PACK_DIR, file), 'utf8');++ // The post itself lives in a sibling .post.txt so that what the gate checks+ // and what post-tweet.mjs sends are the same bytes. A post quoted only+ // inside prose can drift from the file that actually ships.+ const postFile = join(PACK_DIR, `${name}.post.txt`);+ if (!existsSync(postFile)) {+ fail(name, `missing ${name}.post.txt (the file post-tweet.mjs would send)`);+ continue;+ }+ const post = readFileSync(postFile, 'utf8').trim();+ if (!post.includes(post.trim())) fail(name, 'post file is empty');++ const weight = weightedLength(post);+ if (weight > 280) fail(name, `post is ${weight} weighted chars, over X's 280 limit`);+ else if (weight < 100) fail(name, `post is ${weight} weighted chars; under 100 measured 0.83x`);+ else if (weight > 179) notes.push(`${name}: ${weight} chars is the 1.67x band, not the 3.0x band`);++ if (!post.includes(post.trim())) fail(name, 'post file is empty');+ if (/#\w/.test(post)) fail(name, 'post contains a hashtag (0 of our 214 posts use one)');+ if (/[\u{1F300}-\u{1FAFF}\u{2600}-\u{27BF}]/u.test(post)) {+ fail(name, 'post contains an emoji (0 of our 214 posts use one)');+ }+ if (BANNED_DASHES.test(post) || BANNED_DASHES.test(body)) {+ fail(name, 'contains an em-dash or en-dash, which the house style bans');+ }+ if (!/https?:\/\/|three\.ws\//.test(post)) fail(name, 'post links nothing; a reader cannot reach the feature');++ for (const re of BANNED_OPENINGS) {+ if (re.test(post)) fail(name, `post opens with a banned construction: ${re.source}`);+ }+ for (const re of BANNED_PHRASES) {+ if (re.test(post)) fail(name, `post uses banned marketing filler: ${re.source}`);+ }++ // Uniqueness: no two packs may open with the same clause. This is the check+ // that keeps a long run of announcements from converging on one shape.+ const opening = post.toLowerCase().split(/\s+/).slice(0, 8).join(' ');+ if (openings.has(opening)) fail(name, `opens identically to ${openings.get(opening)}`);+ else openings.set(opening, name);++ // Media, by shot id, present in the spec, on disk, and in the manifest.+ const shotIds = [...body.matchAll(/^\| `([a-z0-9-]+)` \|/gm)].map((m) => m[1]);+ if (!shotIds.length) fail(name, 'declares no media; a post with no image measured 0.875x');+ for (const id of shotIds) {+ if (!shotsById.has(id)) fail(name, `media shot "${id}" is not in data/announce-media.json`);+ const written = manifestShots.get(id);+ if (!written) fail(name, `media shot "${id}" has never been captured (run npm run announce:media)`);+ else if (!existsSync(join(root, 'public', written.src.replace(/^\//, '')))) {+ fail(name, `media shot "${id}" is in the manifest but its file is missing`);+ }+ const shot = shotsById.get(id);+ if (shot && !shot.alt) fail(name, `media shot "${id}" has no alt text`);+ }+ if (!/alt text/i.test(body)) fail(name, 'pack does not state the alt text the post must carry');++ // The coin gate. Copy first, then the surfaces the media came from.+ const tickers = [...`${post}\n${body}`.matchAll(/\$([A-Z][A-Z0-9]{1,9})\b/g)]+ .map((m) => m[1])+ .filter((t) => t !== 'THREE');+ if (tickers.length) {+ fail(+ name,+ `copy names a crypto project other than $THREE (${[...new Set(tickers)].join(', ')}); owner approval is required before committing or posting`,+ );+ }+ const gated = shotIds+ .map((id) => shotsById.get(id))+ .filter((s) => s && s.surface && cryptoPaths.has(s.surface) && !s.thirdPartyMarketDataApproved);+ if (gated.length) {+ fail(+ name,+ `media from ${gated.map((s) => s.surface).join(', ')} renders live third-party market data; that frame needs owner approval before it is committed (set thirdPartyMarketDataApproved on the shot once given)`,+ );+ }+}++for (const note of notes) console.log(`note ${note}`);+if (problems.length) {+ console.error(`\ncheck-announce: ${problems.length} problem(s)\n`);+ for (const p of problems) console.error(` ${p}`);+ process.exit(1);+}+console.log(`check-announce: ${packs.length} pack(s) OK`);