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
docs(x-content): document the editorial bar and test the claims ledger, review binding, and editor verdict rules
nirholas81fd2d37dce4
diff --git a/docs/x-content-pipeline.md b/docs/x-content-pipeline.mdindex f2da1101c..5c543db19 100644--- a/docs/x-content-pipeline.md+++ b/docs/x-content-pipeline.md@@ -47,7 +47,8 @@ X Articles require the posting account to be on X Premium.| [data/x-content/queue.json](../data/x-content/queue.json) | The queue: cadence, quality limits, and every item. || `data/x-content/articles/<id>.md` | Article bodies, in Markdown. || `public/x-media/<id>/` | Media for queue items. Media must live under `public/` or `data/` so it ships inside the production image. |-| [api/_lib/x-content/](../api/_lib/x-content/) | The engine: quality lint, media rules, Markdown to Article conversion, scheduler, publisher, ledger. |+| [api/_lib/x-content/](../api/_lib/x-content/) | The engine: voice and editorial lint, media rules, live fact verification, the AI editor, review records, Markdown to Article conversion, scheduler, publisher, ledger. |+| `data/x-content/reviews/<id>.json` | The editorial review record for each item, bound to a hash of the exact content that was reviewed. || [api/cron/x-content.js](../api/cron/x-content.js) | The Cloud Scheduler tick, every 15 minutes. || [scripts/x-content.mjs](../scripts/x-content.mjs) | The operator CLI. || `app_settings` row `x_content` | The publish ledger, shared by the cron and the CLI. |@@ -65,17 +66,30 @@ X Articles require the posting account to be on X Premium."windowMinutes": 90,"posts": [{- "text": "Drop a GLB on Rig Doctor and it names the skeleton convention before the bones finish loading: three.ws/rig-doctor",- "textFrom": "docs/announcements/open-source-friday.post.txt",+ "text": "Drop a .glb on Rig Doctor and it names which of 15 rig conventions the skeleton follows, with nothing uploaded: three.ws/rig-doctor","media": [{ "path": "public/x-media/rig-doctor-clip/clip.mp4", "probe": { "durationSec": 18.2, "width": 1920, "height": 1080, "fps": 60, "videoCodec": "h264", "pixFmt": "yuv420p", "audioCodec": "aac" } }]},- { "text": "Eleven rig conventions so far. The twelfth is an open first issue." }- ]+ { "text": "Every clip in the library is authored against one canonical skeleton, so a rig that maps cleanly animates on arrival." }+ ],+ "claims": [+ {+ "says": "15 rig conventions",+ "evidence": [+ { "type": "page", "url": "https://three.ws/rig-doctor", "contains": "15 rig conventions recognised" },+ { "type": "module", "path": "src/rig-report.js", "export": "CONVENTIONS", "length": 15 }+ ]+ },+ { "says": "with nothing uploaded", "evidence": [{ "type": "page", "url": "https://three.ws/rig-doctor", "contains": "Nothing is uploaded" }] },+ { "says": "Every clip in the library is authored against one canonical skeleton", "evidence": [{ "type": "page", "url": "https://three.ws/rig-doctor", "contains": "Every clip in the three.ws library is authored against one canonical skeleton" }] }+ ],+ "mentions": {}}```- `status`: `draft` (may be unfinished), `review` (must pass `check`), `approved` (eligible to publish), `paused`, `posted`.- `lane` and `pattern` are free-form labels; rotation compares them against what was published last.+- `claims` is the fact ledger. Every number, ordinal, and absolute word (first, only, every, never, fastest) in the copy must sit inside some claim's `says`, every `says` must quote the copy, and every claim carries at least one piece of `evidence` (types below).+- `mentions` maps each @handle in the copy to the reason the tag is true. A tag with no reason is blocked.- `textFrom` is optional. When set, `check` fails if the inline text differs from that announcement-pack file, so the copy that was reviewed is the copy that ships.- An `article` item carries `"article": { "title", "body", "cover": { "path" } }`, and its optional `posts` quote the published Article.@@ -92,10 +106,14 @@ npm run x:content -- import https://example.com/our-guest-post --as article --id# 2. Video: transcode to X's spec, burn in captions, and record the probe on the itemnpm run x:content -- prepare-video ~/Desktop/rig-doctor.mov --out public/x-media/rig-doctor-clip/clip.mp4 --captions ~/Desktop/rig-doctor.srt --item rig-doctor-clip-# 3. Rewrite the imported copy in your own voice, then validate+# 3. Rewrite the imported copy in your own voice, declare its claims, then validatenpm run x:content:check-# 4. See exactly what would be sent, and when the queue will send it+# 4. Run the editorial bar: live fact checks, spelling, media quality, and the AI editor+npm run x:content -- review web-component-article+npm run x:content -- review --status review++# 5. See exactly what would be sent, and when the queue will send itnpm run x:content -- run --dry-run --id web-component-articlenpm run x:content:plan```@@ -104,6 +122,36 @@ npm run x:content:planImages for other channels come from [the announcement capture tool](./announcements/README.md) (`npm run announce:media`), which records frames from the live product; point queue media at those files.+## The editorial bar++Formatting rules keep a feed from looking automated. They do not stop a post from being wrong, and a wrong post from a company account costs more than no post. So nothing can be `approved` until `npm run x:content -- review <id>` passes, and the record it writes is bound to a hash of the copy, every media file's bytes, the alt text, the claims, and the mentions. Change one word or swap one image and the approval is void until the item is reviewed again. A record also expires after 14 days, because facts drift. The production cron enforces the same rule from the records that ship in the image.++A review runs five layers, cheapest first:++| Layer | What it catches | Where |+|---|---|---|+| Voice lint | Hype openers, hashtags, emoji, dashes, stacked exclamation marks, shouting, repeats of earlier posts | [quality.js](../api/_lib/x-content/quality.js) |+| Editorial lint | Brand spelling (three.ws, $THREE, GitHub, NVIDIA, glTF, X not Twitter); anything that reads as a price promise or investment pitch; crypto slang; marketing filler; engagement begging; rhetorical-question openers and one-word drumbeats; more than one link or two tags; undeclared numbers, absolutes, and tags | [editorial.js](../api/_lib/x-content/editorial.js) |+| Media quality | Images under 1200 px wide, crops X will cut in the timeline, alt text that is too short or repeats the post, and frames captured more than 21 days ago (recapture with `npm run announce:media`) | [editorial.js](../api/_lib/x-content/editorial.js) |+| Live verification | Every claim against its evidence at the moment of review, every link resolved, every @mention confirmed as a real public X account, and spelling in US or British English (add correct product terms to `quality.glossary`) | [verify.js](../api/_lib/x-content/verify.js) |+| AI editor | Whether the post is actually good: accuracy against the verified evidence, clarity for a reader who has never heard of three.ws, specificity, voice, a partner-safe professional tone, and whether the image supports the copy. It sees the images, scores six dimensions, quotes each issue with a concrete fix, and proposes a rewrite, which is linted too | [editor.js](../api/_lib/x-content/editor.js) |++Evidence types:++| `type` | Passes when |+|---|---|+| `page` | The live page, rendered in a real browser and allowed to finish rendering, contains `contains` |+| `file` | A repo file contains `contains`, or matches the `matches` regular expression |+| `module` | A repo module's `export` has `length` entries, or equals `equals` |+| `github-issue` | `repo#number` has the given `state` and `label` |+| `github-issues` | `repo` has at least `min` issues with the given `state` and `label` |++The live product is the source of truth. When a screenshot disagrees with the live page, the screenshot is stale: recapture it and use the live number. The editor is instructed the same way, and its verdict cannot pass an item it raised a blocking issue on or scored below 4 anywhere. Where a human disagrees with a `revise` verdict that has no blocking issue, `"editorOverride": { "reason": "..." }` on the item records the decision; nothing overrides a failed fact check or blocking lint.++The editor tries Claude on Vertex AI first, then Claude through OpenRouter, then OpenAI, then Kimi K3 on NVIDIA NIM, falling through on any provider or billing error; each record names the model that reviewed it. The CLI reads missing credentials from the Cloud Run service and uses the signed-in `gh` session for GitHub checks.++This bar caught real errors in the first three queued posts. The Rig Doctor post said the tool knew 11 rig conventions while the live page and code said 15, called a merged fix "an open first issue" when no such issue was open, and shipped a screenshot from before the change. The AWS post was 94 characters and stated no mechanism, and an AI rewrite of it upgraded "an AWS Partner" to "a verified AWS Partner", which no evidence supports.+## Going livePosting is owner-gated. The cron ships in preview mode: with `X_CONTENT_AUTO_PUBLISH` unset, each tick returns the exact API calls it would make, which is how the queue is verified in production first.@@ -111,7 +159,7 @@ Posting is owner-gated. The cron ships in preview mode: with `X_CONTENT_AUTO_PUB1. The @trythreews user tokens must be on the Cloud Run service. `X_API_KEY` and `X_API_SECRET` are already there; `X_ACCESS_TOKEN` and `X_ACCESS_SECRET` (generated for @trythreews in the X developer portal, with Read and Write) must be added with `gcloud run services update three-ws-api --region us-central1 --update-secrets` or `--update-env-vars`.2. Deploy, which bakes the queue and media into the image, and sync the Cloud Scheduler job from `vercel.json` with [scripts/create-gcp-scheduler.mjs](../scripts/create-gcp-scheduler.mjs).3. Read a preview tick: the scheduler job's response, or `gcloud logging read 'resource.type="cloud_run_revision" resource.labels.service_name="three-ws-api" textPayload:"x-content"' --freshness=1h`.-4. Set items to `approved` and deploy. To publish one item by hand instead of waiting: `npm run x:content -- run --id <slug>` (needs `DATABASE_URL`, so the ledger prevents a double post).+4. Review each item (`npm run x:content -- review <id>`), set the passing ones to `approved`, commit their review records, and deploy. To publish one item by hand instead of waiting: `npm run x:content -- run --id <slug>` (needs `DATABASE_URL`, so the ledger prevents a double post).5. To publish automatically: `gcloud run services update three-ws-api --region us-central1 --update-env-vars X_CONTENT_AUTO_PUBLISH=true`.Queue edits reach production with the next deploy, because the cron reads the queue from the image. The ledger is in the database, so a redeploy never republishes anything.@@ -127,4 +175,4 @@ Queue edits reach production with the next deploy, because the cron reads the qu## Tests-[tests/x-content.test.js](../tests/x-content.test.js) covers the lint, the media rules, the Markdown to Article offsets, the scheduler's jitter, spacing, cap, rotation, and resume rules, and the publisher's thread chaining, crash resume, and Article draft, publish, and quote sequence.+[tests/x-content.test.js](../tests/x-content.test.js) covers the voice and editorial lint, the claims ledger, media quality, review records binding approval to exact content, the editor verdict rules, the media rules, the Markdown to Article offsets, the scheduler's jitter, spacing, cap, rotation, and resume rules, and the publisher's thread chaining, crash resume, and Article draft, publish, and quote sequence.diff --git a/tests/x-content.test.js b/tests/x-content.test.jsindex 18a15d3d4..b4089a162 100644--- a/tests/x-content.test.js+++ b/tests/x-content.test.js@@ -252,3 +252,114 @@ describe('publisher', () => {expect(row.url).toBe(`https://x.com/trythreews/status/${row.articlePostId}`);});});++describe('editorial', () => {+ it('passes the reviewed Genesis copy untouched', async () => {+ const { languageProblems, assertionsIn } = await import('../api/_lib/x-content/editorial.js');+ const 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';+ expect(languageProblems(text)).toEqual([]);+ expect(assertionsIn(text)).toEqual({ numbers: [], absolutes: [] });+ });++ it('blocks brand errors, financial promotion, slang, pushy asks, and ad-copy structure', async () => {+ const { languageProblems } = await import('../api/_lib/x-content/editorial.js');+ const rules = (text) => languageProblems(text).map((row) => `${row.rule}:${row.severity}`);+ expect(rules('Three.ws ships agents on Github: three.ws/a')).toEqual(['brand:blocking', 'brand:blocking']);+ expect(rules('$THREE has 100x potential for holders: three.ws/a')).toContain('compliance:blocking');+ expect(rules('gm frens, agents are live: three.ws/a')).toContain('register:blocking');+ expect(rules('A robust agent runtime: three.ws/a')).toEqual(['register:major']);+ expect(rules('Agents are live, check it out: three.ws/a')).toContain('register:blocking');+ expect(rules('Fast. Simple. Onchain. three.ws/a')).toContain('structure:blocking');+ expect(rules('What if agents could pay? They can: three.ws/a')).toContain('structure:blocking');+ expect(rules('Two links: three.ws/a and three.ws/b')).toContain('links:blocking');+ });++ it('treats names as names and ordinals as numbers', async () => {+ const { assertionsIn } = await import('../api/_lib/x-content/editorial.js');+ expect(assertionsIn('3D agents on ERC-8004 with $THREE: three.ws/a').numbers).toEqual([]);+ expect(assertionsIn('Rig Doctor knows 11 conventions; teach it the 12th in 40 ms at 86%').numbers).toEqual(['11', '12th', '40 ms', '86%']);+ });++ it('requires every number, absolute, and tag in the copy to be declared', async () => {+ const { claimProblems } = await import('../api/_lib/x-content/editorial.js');+ const item = { posts: [{ text: 'The first viewer with 15 rig conventions, built on @solana: three.ws/a' }] };+ const messages = claimProblems(item).map((row) => row.message).join('\n');+ expect(messages).toMatch(/"15" is an unverified number/);+ expect(messages).toMatch(/"first" is an absolute/);+ expect(messages).toMatch(/@solana has no recorded reason/);++ const declared = {+ ...item,+ claims: [+ { says: 'first viewer', evidence: [{ type: 'file', path: 'x', contains: 'y' }] },+ { says: '15 rig conventions', evidence: [{ type: 'file', path: 'x', contains: 'y' }] },+ ],+ mentions: { '@solana': 'wallets are Solana wallets' },+ };+ expect(claimProblems(declared)).toEqual([]);+ expect(claimProblems({ ...declared, claims: [...declared.claims, { says: 'not in the copy', evidence: [] }] }).map((row) => row.message).join('\n'))+ .toMatch(/does not appear in the copy[\s\S]*has no evidence/);+ });++ it('flags soft, badly cropped, undescribed, and stale media', async () => {+ const { mediaQualityProblems } = await import('../api/_lib/x-content/editorial.js');+ const { default: sharp } = await import('sharp');+ const dir = sandbox();+ await sharp({ create: { width: 800, height: 200, channels: 3, background: '#000' } }).png().toFile(join(dir, 'public/x-media/t/small.png'));+ await sharp({ create: { width: 1800, height: 1013, channels: 3, background: '#000' } }).png().toFile(join(dir, 'public/x-media/t/hero.png'));+ mkdirSync(join(dir, 'public/announce'), { recursive: true });+ writeFileSync(join(dir, 'public/announce/media-manifest.json'), JSON.stringify({ shots: { hero: { src: '/x-media/t/hero.png', route: '/hero', capturedAt: '2026-08-01T00:00:00Z' } } }));+ const now = Date.parse('2026-09-16T00:00:00Z');++ const small = await mediaQualityProblems({ text: 'x', media: [{ path: 'public/x-media/t/small.png', alt: 'short' }] }, dir, { now });+ const smallText = small.map((row) => row.message).join('\n');+ expect(smallText).toMatch(/800px wide/);+ expect(smallText).toMatch(/4\.00:1/);+ expect(smallText).toMatch(/alt text is 5 characters/);++ const stale = await mediaQualityProblems({ text: 'x', media: [{ path: 'public/x-media/t/hero.png', alt: 'The hero page with its drop zone and the four stats beneath it' }] }, dir, { now });+ expect(stale.map((row) => row.message)).toEqual([expect.stringMatching(/captured 46 days ago from \/hero/)]);+ });+});++describe('review', () => {+ it('binds approval to the exact reviewed content', async () => {+ const { approvalProblems, contentHash, reviewPath } = await import('../api/_lib/x-content/review.js');+ const dir = sandbox();+ const item = { id: 'demo', kind: 'post', posts: [{ text: HEAD, media: [{ path: 'public/x-media/t/a.png', alt: 'alt' }] }] };+ expect(approvalProblems(item, dir).join('\n')).toMatch(/no editorial review/);++ mkdirSync(join(dir, 'data/x-content/reviews'), { recursive: true });+ const record = { id: 'demo', contentHash: contentHash(item, dir), reviewedAt: '2026-09-16T00:00:00Z', passed: true, blockers: [] };+ writeFileSync(join(dir, reviewPath('demo')), JSON.stringify(record));+ const now = Date.parse('2026-09-17T00:00:00Z');+ expect(approvalProblems(item, dir, now)).toEqual([]);++ expect(approvalProblems({ ...item, posts: [{ ...item.posts[0], text: `${HEAD} ` }] }, dir, now)).toEqual([]);+ expect(approvalProblems({ ...item, posts: [{ ...item.posts[0], text: HEAD.replace('Rig', 'The rig') }] }, dir, now).join('\n')).toMatch(/changed after the last review/);+ writeFileSync(join(dir, 'public/x-media/t/a.png'), Buffer.alloc(65));+ expect(approvalProblems(item, dir, now).join('\n')).toMatch(/changed after the last review/);+ writeFileSync(join(dir, 'public/x-media/t/a.png'), Buffer.alloc(64));+ expect(approvalProblems(item, dir, Date.parse('2026-10-16T00:00:00Z')).join('\n')).toMatch(/days old/);+ writeFileSync(join(dir, reviewPath('demo')), JSON.stringify({ ...record, passed: false, blockers: ['link three.ws/a: HTTP 404'] }));+ expect(approvalProblems(item, dir, now).join('\n')).toMatch(/did not pass: link three\.ws\/a: HTTP 404/);+ });++ it('blocks an approved item in the queue validator until it is reviewed', () => {+ const dir = sandbox();+ const item = { id: 'demo', status: 'approved', kind: 'post', lane: 'l', pattern: 'p', notBefore: '2026-09-17T14:00:00Z', posts: [{ text: HEAD, media: [{ path: 'public/x-media/t/a.png', alt: 'The Rig Doctor page' }] }] };+ expect(validateItem(item, dir).join('\n')).toMatch(/review: no editorial review/);+ expect(validateItem({ ...item, status: 'review' }, dir)).toEqual([]);+ });++ it('never lets the editor pass its own blocking issue or a low score', async () => {+ const { parseReview } = await import('../api/_lib/x-content/editor.js');+ const scores = { accuracy: 5, clarity: 5, specificity: 5, voice: 5, professionalism: 5, visual: 5 };+ const clean = parseReview(`Here you go: ${JSON.stringify({ verdict: 'publish', scores, issues: [] })}`);+ expect(clean.verdict).toBe('publish');+ expect(parseReview(JSON.stringify({ verdict: 'publish', scores, issues: [{ severity: 'blocking', area: 'accuracy' }] })).verdict).toBe('revise');+ expect(parseReview(JSON.stringify({ verdict: 'publish', scores: { ...scores, clarity: 3 }, issues: [] })).verdict).toBe('revise');+ expect(() => parseReview(JSON.stringify({ verdict: 'ship', scores, issues: [] }))).toThrow(/verdict/);+ expect(() => parseReview('no json here')).toThrow(/no JSON/);+ });+});