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.

fix(tests,docs): stop a fresh clone failing on assets and links it never had

ni3a9d65855a8811
diff --git a/api/_lib/announce/kit.js b/api/_lib/announce/kit.js
index cbb685c5f..e28bc6291 100644
--- a/api/_lib/announce/kit.js
+++ b/api/_lib/announce/kit.js
@@ -91,7 +91,7 @@ export function renderPack({ brief, draft, slot, ledgerEntry = {}, rank = null,
'',
`**Surface:** [\`${brief.key}\`](${url}) · **Stage:** drafted · **Slot:** ${slot.notBefore.slice(0, 10)} · **Announced externally:** never`,
'',
- `${rank && total ? `Ranked ${rank} of ${total} never-announced surfaces by \`npm run announce:rank\`` : 'From the announcement backlog'}${ledgerEntry.score ? ` (score ${ledgerEntry.score})` : ''}. ${model && !/^hand/i.test(model) ? `Drafted on ${model} and packed by \`npm run announce:kit\`` : 'Drafted by hand and packed by `npm run announce:kit`'}, from the evidence brief in [\`data/announce-plan/briefs/${id}.json\`](../../data/announce-plan/briefs/${id}.json), against [the announcement voice](../announce-voice.md). Every fact below comes from that brief; nothing in this pack was written from memory.`,
+ `${rank && total ? `Ranked ${rank} of ${total} never-announced surfaces by \`npm run announce:rank\`` : 'From the announcement backlog'}${ledgerEntry.score ? ` (score ${ledgerEntry.score})` : ''}. ${model && !/^hand/i.test(model) ? `Drafted on ${model} and packed by \`npm run announce:kit\`` : 'Drafted by hand and packed by `npm run announce:kit`'}, from the evidence brief \`data/announce-plan/briefs/${id}.json\` (a local build artifact: \`data/announce-plan/\` is gitignored, so regenerate it with \`npm run announce:kit -- --id ${id} --brief-only\`), against [the announcement voice](../announce-voice.md). Every fact below comes from that brief; nothing in this pack was written from memory.`,
'',
'---',
'',
diff --git a/docs/announcements/activity-mcp.md b/docs/announcements/activity-mcp.md
index bacdd16cc..7b7e3b9f8 100644
--- a/docs/announcements/activity-mcp.md
+++ b/docs/announcements/activity-mcp.md
@@ -2,7 +2,7 @@
**Surface:** [`@three-ws/activity-mcp`](https://three.ws) · **Stage:** drafted · **Slot:** 2026-09-21 · **Announced externally:** never
-Ranked 33 of 330 never-announced surfaces by `npm run announce:rank` (score 67). Drafted by hand and packed by `npm run announce:kit`, from the evidence brief in [`data/announce-plan/briefs/activity-mcp.json`](../../data/announce-plan/briefs/activity-mcp.json), against [the announcement voice](../announce-voice.md). Every fact below comes from that brief; nothing in this pack was written from memory.
+Ranked 33 of 330 never-announced surfaces by `npm run announce:rank` (score 67). Drafted by hand and packed by `npm run announce:kit`, from the evidence brief `data/announce-plan/briefs/activity-mcp.json` (a local build artifact: `data/announce-plan/` is gitignored, so regenerate it with `npm run announce:kit -- --id activity-mcp --brief-only`), against [the announcement voice](../announce-voice.md). Every fact below comes from that brief; nothing in this pack was written from memory.
---
diff --git a/docs/announcements/assistant.md b/docs/announcements/assistant.md
index 84ea6e2ef..4a30b991c 100644
--- a/docs/announcements/assistant.md
+++ b/docs/announcements/assistant.md
@@ -2,7 +2,7 @@
**Surface:** [`/assistant`](https://three.ws/assistant) · **Stage:** drafted · **Slot:** 2026-09-22 · **Announced externally:** never
-Ranked 48 of 330 never-announced surfaces by `npm run announce:rank` (score 66). Drafted by hand and packed by `npm run announce:kit`, from the evidence brief in [`data/announce-plan/briefs/assistant.json`](../../data/announce-plan/briefs/assistant.json), against [the announcement voice](../announce-voice.md). Every fact below comes from that brief; nothing in this pack was written from memory.
+Ranked 48 of 330 never-announced surfaces by `npm run announce:rank` (score 66). Drafted by hand and packed by `npm run announce:kit`, from the evidence brief `data/announce-plan/briefs/assistant.json` (a local build artifact: `data/announce-plan/` is gitignored, so regenerate it with `npm run announce:kit -- --id assistant --brief-only`), against [the announcement voice](../announce-voice.md). Every fact below comes from that brief; nothing in this pack was written from memory.
---
diff --git a/docs/announcements/avatar-mcp.md b/docs/announcements/avatar-mcp.md
index 3c0e0e8a6..1405cb647 100644
--- a/docs/announcements/avatar-mcp.md
+++ b/docs/announcements/avatar-mcp.md
@@ -2,7 +2,7 @@
**Surface:** [`@three-ws/avatar-mcp`](https://three.ws) · **Stage:** drafted · **Slot:** 2026-09-21 · **Announced externally:** never
-Ranked 38 of 330 never-announced surfaces by `npm run announce:rank` (score 67). Drafted by hand and packed by `npm run announce:kit`, from the evidence brief in [`data/announce-plan/briefs/avatar-mcp.json`](../../data/announce-plan/briefs/avatar-mcp.json), against [the announcement voice](../announce-voice.md). Every fact below comes from that brief; nothing in this pack was written from memory.
+Ranked 38 of 330 never-announced surfaces by `npm run announce:rank` (score 67). Drafted by hand and packed by `npm run announce:kit`, from the evidence brief `data/announce-plan/briefs/avatar-mcp.json` (a local build artifact: `data/announce-plan/` is gitignored, so regenerate it with `npm run announce:kit -- --id avatar-mcp --brief-only`), against [the announcement voice](../announce-voice.md). Every fact below comes from that brief; nothing in this pack was written from memory.
---
diff --git a/docs/announcements/awesome.md b/docs/announcements/awesome.md
index 71a0a70c3..50135109c 100644
--- a/docs/announcements/awesome.md
+++ b/docs/announcements/awesome.md
@@ -2,7 +2,7 @@
**Surface:** [`/awesome`](https://three.ws/awesome) · **Stage:** drafted · **Slot:** 2026-09-21 · **Announced externally:** never
-Ranked 176 of 330 never-announced surfaces by `npm run announce:rank` (score 46). Drafted by hand and packed by `npm run announce:kit`, from the evidence brief in [`data/announce-plan/briefs/awesome.json`](../../data/announce-plan/briefs/awesome.json), against [the announcement voice](../announce-voice.md). Every fact below comes from that brief; nothing in this pack was written from memory.
+Ranked 176 of 330 never-announced surfaces by `npm run announce:rank` (score 46). Drafted by hand and packed by `npm run announce:kit`, from the evidence brief `data/announce-plan/briefs/awesome.json` (a local build artifact: `data/announce-plan/` is gitignored, so regenerate it with `npm run announce:kit -- --id awesome --brief-only`), against [the announcement voice](../announce-voice.md). Every fact below comes from that brief; nothing in this pack was written from memory.
---
diff --git a/docs/announcements/forge-max.md b/docs/announcements/forge-max.md
index 65f45289a..42da4c207 100644
--- a/docs/announcements/forge-max.md
+++ b/docs/announcements/forge-max.md
@@ -2,7 +2,7 @@
**Surface:** [`/forge-max`](https://three.ws/forge-max) · **Stage:** drafted · **Slot:** 2026-09-18 · **Announced externally:** never
-Ranked 19 of 322 never-announced surfaces by `npm run announce:rank` (score 75). Drafted by hand and packed by `npm run announce:kit`, from the evidence brief in [`data/announce-plan/briefs/forge-max.json`](../../data/announce-plan/briefs/forge-max.json), against [the announcement voice](../announce-voice.md). Every fact below comes from that brief; nothing in this pack was written from memory.
+Ranked 19 of 322 never-announced surfaces by `npm run announce:rank` (score 75). Drafted by hand and packed by `npm run announce:kit`, from the evidence brief `data/announce-plan/briefs/forge-max.json` (a local build artifact: `data/announce-plan/` is gitignored, so regenerate it with `npm run announce:kit -- --id forge-max --brief-only`), against [the announcement voice](../announce-voice.md). Every fact below comes from that brief; nothing in this pack was written from memory.
---
diff --git a/docs/announcements/galaxy.md b/docs/announcements/galaxy.md
index 20c3a2687..b3d50f08d 100644
--- a/docs/announcements/galaxy.md
+++ b/docs/announcements/galaxy.md
@@ -2,7 +2,7 @@
**Surface:** [`/galaxy`](https://three.ws/galaxy) · **Stage:** drafted · **Slot:** 2026-09-22 · **Announced externally:** never
-Ranked 143 of 330 never-announced surfaces by `npm run announce:rank` (score 51). Drafted by hand and packed by `npm run announce:kit`, from the evidence brief in [`data/announce-plan/briefs/galaxy.json`](../../data/announce-plan/briefs/galaxy.json), against [the announcement voice](../announce-voice.md). Every fact below comes from that brief; nothing in this pack was written from memory.
+Ranked 143 of 330 never-announced surfaces by `npm run announce:rank` (score 51). Drafted by hand and packed by `npm run announce:kit`, from the evidence brief `data/announce-plan/briefs/galaxy.json` (a local build artifact: `data/announce-plan/` is gitignored, so regenerate it with `npm run announce:kit -- --id galaxy --brief-only`), against [the announcement voice](../announce-voice.md). Every fact below comes from that brief; nothing in this pack was written from memory.
---
diff --git a/docs/announcements/knock.md b/docs/announcements/knock.md
index a9691f377..fc51b928d 100644
--- a/docs/announcements/knock.md
+++ b/docs/announcements/knock.md
@@ -2,7 +2,7 @@
**Surface:** [`/knock`](https://three.ws/knock) · **Stage:** drafted · **Slot:** 2026-09-21 · **Announced externally:** never
-Ranked 31 of 330 never-announced surfaces by `npm run announce:rank` (score 70). Drafted by hand and packed by `npm run announce:kit`, from the evidence brief in [`data/announce-plan/briefs/knock.json`](../../data/announce-plan/briefs/knock.json), against [the announcement voice](../announce-voice.md). Every fact below comes from that brief; nothing in this pack was written from memory.
+Ranked 31 of 330 never-announced surfaces by `npm run announce:rank` (score 70). Drafted by hand and packed by `npm run announce:kit`, from the evidence brief `data/announce-plan/briefs/knock.json` (a local build artifact: `data/announce-plan/` is gitignored, so regenerate it with `npm run announce:kit -- --id knock --brief-only`), against [the announcement voice](../announce-voice.md). Every fact below comes from that brief; nothing in this pack was written from memory.
---
diff --git a/docs/announcements/materialize.md b/docs/announcements/materialize.md
index 75d5570ac..a15a041a3 100644
--- a/docs/announcements/materialize.md
+++ b/docs/announcements/materialize.md
@@ -2,7 +2,7 @@
**Surface:** [`/materialize`](https://three.ws/materialize) · **Stage:** drafted · **Slot:** 2026-09-19 · **Announced externally:** never
-Ranked 22 of 322 never-announced surfaces by `npm run announce:rank` (score 73). Drafted by hand and packed by `npm run announce:kit`, from the evidence brief in [`data/announce-plan/briefs/materialize.json`](../../data/announce-plan/briefs/materialize.json), against [the announcement voice](../announce-voice.md). Every fact below comes from that brief; nothing in this pack was written from memory.
+Ranked 22 of 322 never-announced surfaces by `npm run announce:rank` (score 73). Drafted by hand and packed by `npm run announce:kit`, from the evidence brief `data/announce-plan/briefs/materialize.json` (a local build artifact: `data/announce-plan/` is gitignored, so regenerate it with `npm run announce:kit -- --id materialize --brief-only`), against [the announcement voice](../announce-voice.md). Every fact below comes from that brief; nothing in this pack was written from memory.
---
diff --git a/packages/glb-diff/tests/glb-diff.test.js b/packages/glb-diff/tests/glb-diff.test.js
index 901179853..d02de0b8f 100644
--- a/packages/glb-diff/tests/glb-diff.test.js
+++ b/packages/glb-diff/tests/glb-diff.test.js
@@ -3,11 +3,19 @@
// Two layers, deliberately. Most cases build glTF Documents in memory so the
// input is exact: a test that says "moving one vertex is a major change" moves
// exactly one vertex. The last block runs the whole pipeline over real rigged
-// avatars shipped in this repo, because an engine that only ever sees synthetic
-// four-triangle meshes is an engine nobody has actually tested.
+// avatars, because an engine that only ever sees synthetic four-triangle meshes
+// is an engine nobody has actually tested.
+//
+// Those avatars are NOT committed. animation-sources/ is gitignored except for
+// its README: the GLBs there are split out of the three.js example models by
+// `npm run extract:animations`, which re-downloads them on demand. So the block
+// skips itself when they have not been staged, the way the animation build
+// already treats a missing source, instead of failing a fresh clone with an
+// ENOENT that reads like a broken engine.
import { describe, expect, it } from 'vitest';
import { Document } from '@gltf-transform/core';
+import { existsSync } from 'node:fs';
import { readFile } from 'node:fs/promises';
import { fileURLToPath } from 'node:url';
import path from 'node:path';
@@ -23,6 +31,16 @@ import { canonicalize, hashNumbers, hashString } from '../src/hash.js';
const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..');
const asset = (name) => path.join(REPO_ROOT, 'animation-sources', name);
+// The exact files the real-avatar block reads. Staged by `npm run extract:animations`.
+const REAL_ASSETS = ['xbot-idle.glb', 'xbot-walk.glb', 'robot-walking.glb'];
+const haveRealAssets = REAL_ASSETS.every((name) => existsSync(asset(name)));
+if (!haveRealAssets) {
+ console.warn(
+ '[glb-diff] skipping the real-avatar block: animation-sources/ has no staged GLBs. ' +
+ 'Run `npm run extract:animations` to fetch them.',
+ );
+}
+
// A minimal but complete rigged model: one triangle skinned to two joints,
// driven by one clip. Small enough to reason about, complete enough that every
// section of the diff has something to compare.
@@ -253,7 +271,7 @@ describe('formatting', () => {
});
});
-describe('real avatars', () => {
+describe.skipIf(!haveRealAssets)('real avatars', () => {
it('describes a rigged Mixamo avatar', async () => {
const bytes = new Uint8Array(await readFile(asset('xbot-idle.glb')));
const model = await describeModel(bytes, { name: 'xbot-idle.glb' });
diff --git a/scripts/audit-docs.mjs b/scripts/audit-docs.mjs
index b90b81813..0fad4f82a 100644
--- a/scripts/audit-docs.mjs
+++ b/scripts/audit-docs.mjs
@@ -336,6 +336,10 @@ const UNPUBLISHED_DOCS = new Map([
['ibm-community-recap-nichxbt', 'internal: source draft of an IBM Community post'],
['ibm-community-blog-meetup-jessica', 'internal: source draft of an IBM Community post'],
['ibm-community-thread', 'internal: source draft of an IBM Community post'],
+ [
+ 'ibm-community-governed-agents-thread',
+ 'internal: discussion-thread draft for the IBM Community user group, held until POST /api/guardian/assess answers on production',
+ ],
['ibm-next-event', 'internal: partner event proposal, prize budget and engineering plan'],
['ibm-event-offer-map', 'internal: partner event inventory naming readiness gaps and unsent asks'],
['ibm-visibility-map', 'internal: outreach map naming unsent asks and unclaimed Partner Plus benefits'],
diff --git a/scripts/check-announce.mjs b/scripts/check-announce.mjs
index 651357491..ca07c8103 100644
--- a/scripts/check-announce.mjs
+++ b/scripts/check-announce.mjs
@@ -46,6 +46,7 @@ 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 QUEUE = join(root, 'data/x-content/queue.json');
const argv = process.argv.slice(2);
const only = (() => {
@@ -109,6 +110,20 @@ const manifestShots = new Map(
(Array.isArray(manifest.shots) ? manifest.shots : Object.values(manifest.shots || {})).map((s) => [s.id, s]),
);
+// Media a queue item declares directly, keyed by the pack it ships with. Most
+// packs point at a captured shot id from data/announce-media.json, but a
+// hand-authored pack can ship a committed card instead, declared on the queue
+// item with its own alt text. That is the artifact the publisher actually
+// sends, so it satisfies the media rule exactly as a captured shot does.
+const queue = existsSync(QUEUE) ? JSON.parse(readFileSync(QUEUE, 'utf8')) : { items: [] };
+const queueMediaByPack = new Map();
+for (const item of queue.items || []) {
+ const src = item?.source?.path;
+ if (!src || !src.endsWith('.md')) continue;
+ const media = (item.posts || []).flatMap((post) => post.media || []);
+ if (media.length) queueMediaByPack.set(basename(src, '.md'), media);
+}
+
// 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.
@@ -198,7 +213,15 @@ for (const file of packs) {
// 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');
+ const queueMedia = queueMediaByPack.get(name) || [];
+ if (!shotIds.length && !queueMedia.length) {
+ fail(name, 'declares no media; a post with no image measured 0.875x');
+ }
+ for (const item of queueMedia) {
+ if (!item.path) fail(name, 'queue media entry has no path');
+ else if (!existsSync(join(root, item.path))) fail(name, `queue media "${item.path}" is missing from the repo`);
+ if (!item.alt) fail(name, `queue media "${item.path || 'entry'}" has no alt text`);
+ }
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);
@@ -209,7 +232,12 @@ for (const file of packs) {
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');
+ // Either the pack states the alt text, or the queue item carries it on the
+ // media it ships. One of the two must exist: a post that goes out without
+ // alt text is unreadable to anyone using a screen reader.
+ if (!/alt text/i.test(body) && !queueMedia.some((item) => item.alt)) {
+ 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 named = gateTerms.filter((term) => new RegExp(`\\b${term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'i').test(`${post}\n${body}`));
diff --git a/tests/model-diff-api.test.js b/tests/model-diff-api.test.js
index 88c9bd865..deaf47434 100644
--- a/tests/model-diff-api.test.js
+++ b/tests/model-diff-api.test.js
@@ -8,6 +8,7 @@
// "does not 500".
import { describe, expect, it } from 'vitest';
+import { existsSync } from 'node:fs';
import { readFile } from 'node:fs/promises';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
@@ -144,10 +145,25 @@ describe('diff_models MCP tool', () => {
});
});
-// One end-to-end pass over real rigged assets in this repo. The endpoint above
-// is covered without network; this proves the engine the endpoint calls agrees
-// with what the page and the CLI would report for the same two files.
-describe('the engine behind the endpoint, on real avatars', () => {
+// One end-to-end pass over real rigged assets. The endpoint above is covered
+// without network; this proves the engine the endpoint calls agrees with what
+// the page and the CLI would report for the same two files.
+//
+// animation-sources/ is gitignored, so these GLBs exist only once
+// `npm run extract:animations` has staged them. Absent, the block skips rather
+// than failing a fresh clone on a missing optional asset.
+const REAL_ASSETS = ['xbot-idle.glb', 'xbot-walk.glb'];
+const haveRealAssets = REAL_ASSETS.every((name) =>
+ existsSync(path.join(REPO_ROOT, 'animation-sources', name)),
+);
+if (!haveRealAssets) {
+ console.warn(
+ '[model-diff] skipping the real-avatar block: animation-sources/ has no staged GLBs. ' +
+ 'Run `npm run extract:animations` to fetch them.',
+ );
+}
+
+describe.skipIf(!haveRealAssets)('the engine behind the endpoint, on real avatars', () => {
it('finds only the clip difference between two exports of one rig', async () => {
const [a, b] = await Promise.all([
readFile(path.join(REPO_ROOT, 'animation-sources/xbot-idle.glb')),