Skip to content

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

docs(structure): map the smart glasses lane and the announcement factory to their directories

nirholas877df91b66ee
diff --git a/STRUCTURE.md b/STRUCTURE.md
index 5ad1789f4..8d46c5f5d 100644
--- a/STRUCTURE.md
+++ b/STRUCTURE.md
@@ -106,6 +106,7 @@ bottom.
| AR Studio (multi-model live camera scene) | [pages/ar-studio.html](pages/ar-studio.html) `→ /ar/studio` + [src/ar-studio.js](src/ar-studio.js), multi-anchor WebXR session [src/ar/multi-place.js](src/ar/multi-place.js), pure scene math [src/ar/studio-scene.js](src/ar/studio-scene.js) | Live | The standalone multi-model AR surface: place ANY number of models/avatars into one live camera view (every earlier AR lane was single-model). Model sources: in-view forge (`POST /api/forge {backend:"nvidia"}` runs behind the live camera, result drops into the room), the forge gallery (`/api/forge-gallery`, yours + community tabs), recent forges (localStorage, shared with `/ar`), the CC0 Object Library (`/api/objects/library`, an Objects tray tab with client-side name/category search), a pasted GLB link, or repeatable `?src=` deep links (https/relative only). Rendering ladder: WebXR immersive-ar with one XRAnchor per placed model + always-armed reticle (Android), getUserMedia passthrough + gyro world-lock (iOS/everywhere), grid preview + drag-look + QR handoff (desktop). Gestures: tap select, drag move, pinch resize, two-finger twist rotate; per-model duplicate/rotate/remove, clear-with-undo. **Real device AR, not just the camera composite:** the AR control resolves what the device can actually do and routes there rather than defaulting every non-WebXR device to the composite: the immersive WebXR session where it exists, Apple Quick Look on iOS and Google Scene Viewer on Android otherwise (both selectable per-model from the selection bar too), and an honest "open this on a phone" QR prompt everywhere else. The button relabels itself to match ("Immersive" only where an immersive session is real). Quick Look reads USDZ, so the selected model's GLB is converted on the device through the same `usdz-pipeline.js` bake `/avatars/:id/ar` uses, not the camera-passthrough composite, which has no real-world plane detection or scale and previously shipped as the only iOS experience. Humanoids with no baked clips idle via the universal retarget ([src/irl/pin-idle.js](src/irl/pin-idle.js)); scene persists in localStorage and the whole ARRANGEMENT (models + transforms) round-trips through a base64url `#s=` hash on the share/QR URL, so a composed scene reopens exactly on any device. **Presence realism:** WebXR placements are lit by the real room via lighting-estimation ([src/ar/estimated-lighting.js](src/ar/estimated-lighting.js), three's `XREstimatedLight`, real primary-light direction/colour + a live environment cube map so metal/glass reflect the actual room, reverting to baked lights when the device isn't estimating) and occluded by real geometry via depth-sensing ([src/ar/depth-occlusion.js](src/ar/depth-occlusion.js)); the passthrough path matches room brightness AND colour by sampling the camera feed. Desktop keyboard controls (arrows nudge / R rotate / D duplicate / Delete). Photo capture composites camera + WebGL ([src/irl/share-frame.js](src/irl/share-frame.js)). Reachable from `/ar`, the forge AR panel, and the `/viewer` action sheet. **Shared rooms (build together, live):** "Share live" opens a room with a 6-char code; anyone who opens `/ar/studio?room=CODE` joins the same scene and every add / move / scale / rotate / remove delta-syncs in real time, with a live "N here" presence pill. New Colyseus room [multiplayer/src/rooms/StudioRoom.js](multiplayer/src/rooms/StudioRoom.js) + schema [multiplayer/src/studio-schemas.js](multiplayer/src/studio-schemas.js) (owner-gated edits, per-room/per-owner caps, per-client rate limit, https-only src validation, the same discipline as WalkRoom's object channel), client wrapper [src/ar/studio-net.js](src/ar/studio-net.js), and a shared logical coordinate frame [src/ar/studio-coords.js](src/ar/studio-coords.js) (relEast/relNorth/yawDeg) so every device agrees on placement; QR-marker colocalization ([src/irl/marker-anchor.js](src/irl/marker-anchor.js)) is the co-located "same physical table" upgrade. Runs on the same Colyseus host as /walk and /irl (a new room, not a new process). Tests: [tests/ar-studio-scene.test.js](tests/ar-studio-scene.test.js), [tests/ar-studio-coords.test.js](tests/ar-studio-coords.test.js), [tests/ar-estimated-lighting.test.js](tests/ar-estimated-lighting.test.js), [tests/studio-room.test.js](tests/studio-room.test.js). **Shipped as open source:** the same surface is extracted, generalized and published as [3d-ar-studio](https://www.npmjs.com/package/3d-ar-studio) (repo [nirholas/3D-AR-Studio](https://github.com/nirholas/3D-AR-Studio), demo https://nirholas.github.io/3D-AR-Studio/, MCP server `io.github.nirholas/3d-ar-studio`), so any site can embed a multi-model AR studio with one script tag. It defaults to OUR catalogue and generation lane (`/cdn/objects/library/manifest.json`, `/api/mcp-studio`, `/animations/manifest.json`, `/hdri/*`, `/api/ar`), which is why those surfaces answer open CORS. |
| Portal (any website as a walkable world) | Page [pages/portal.html](pages/portal.html) `→ /portal` + controller [src/portal/main.js](src/portal/main.js), renderer [src/portal/render.js](src/portal/render.js), styles [src/portal/portal.css](src/portal/portal.css); reader [api/_lib/portal/outline.js](api/_lib/portal/outline.js) + guarded fetch [api/_lib/portal/fetch-site.js](api/_lib/portal/fetch-site.js) + robots matcher [api/_lib/portal/robots.js](api/_lib/portal/robots.js); pure layout [packages/portal/src/layout.js](packages/portal/src/layout.js); GLB export [api/_lib/portal/world-glb.js](api/_lib/portal/world-glb.js); endpoint [api/portal.js](api/portal.js) `→ /api/portal` | Live | Paste an address and walk the page: each section becomes a building sized by its word count (log scale), each link a door (same-site doors rebuild the world there and push browser history, outside links open the page), each image a billboard loaded through `/api/img`, each code block a monolith, and the palette comes from the page's own `theme-color` or a hash of its host. The layout is a pure, seeded function so the browser, the GLB exporter, the MCP tools and the npm package all build the identical city from one link. Crawler manners are part of the product: a declared user agent, `robots.txt` honoured per RFC 9309, one fetch per page cached fleet-wide for an hour, and an IP-pinned SSRF guard with size and time ceilings. `format=glb` returns the world as glTF with named nodes. SDK + CLI + MCP server: [packages/portal/](packages/portal). Docs: [docs/portal.md](docs/portal.md). Spec: [specs/PORTAL_WORLD.md](specs/PORTAL_WORLD.md). Tests: [tests/portal-robots.test.js](tests/portal-robots.test.js), [tests/portal-outline.test.js](tests/portal-outline.test.js), [tests/portal-layout.test.js](tests/portal-layout.test.js), [tests/portal-endpoint.test.js](tests/portal-endpoint.test.js), [tests/e2e/portal.spec.js](tests/e2e/portal.spec.js) |
| IRL (agents in the real world) | [pages/irl.html](pages/irl.html) `→ /irl` + [src/irl.js](src/irl.js), WebXR placement [src/ar/webxr.js](src/ar/webxr.js) + pinch [src/ar/pinch-scale.js](src/ar/pinch-scale.js), animated Quick Look bake [src/usdz-animated.js](src/usdz-animated.js) (static fallback [src/usdz-pipeline.js](src/usdz-pipeline.js)), backend [api/irl/](api/irl) | Live | Pin an agent at a real GPS spot; discovery is presence-proof-gated ([docs/irl/THREAT-MODEL.md](docs/irl/THREAT-MODEL.md)). **Place in AR** leads the dock on AR-capable devices: WebXR hit-test anchoring on Android with two-finger pinch resize (25%..400%) persisted to the pin (`anchor_scale`; the pinch lands as a follow-up `PATCH /api/irl/pins {id, scale}` after the placement tap), and ARKit Quick Look on iOS with the idle clip baked into the USDZ so the agent moves instead of standing in a T-pose. Discovered pins are equally alive in the in-page camera view: every mounted humanoid GLB plays the retargeted idle clip via a per-pin mixer ([src/irl/pin-idle.js](src/irl/pin-idle.js), phase-randomized, LOD-bounded), camera-aware gaze composes on top of the running animation, and the scene renders with ACES tone mapping + IBL + soft shadows (e2e: [tests/e2e/irl-pin-idle.spec.js](tests/e2e/irl-pin-idle.spec.js)). Inbound `/irl?avatar=<glb>` is the living-agent handoff from `GET /api/ar?…&kind=avatar` (explicit `?avatar=` wins over a saved session). Money Drops and World Lines: [docs/irl.md](docs/irl.md). SDK: [packages/irl/](packages/irl). **Share** ([src/irl/share-frame.js](src/irl/share-frame.js), [api/irl/share.js](api/irl/share.js), [api/irl/share/[token].js](api/irl/share/%5Btoken%5D.js)) mints a permanent, unfurlable `/irl/s/:token` link from the captured AR photo for the pin you just placed - never a coordinate, owner-gated, falls back to the plain native share sheet with no active pin. **Analytics** ([api/_lib/irl-analytics.js](api/_lib/irl-analytics.js), [api/irl/analytics.js](api/irl/analytics.js)) is the first site-wide usage rollup for the feature - pins placed, nearby reads, placement method, shares, drop claims - aged out by the existing hourly reaper. **Visit links and signs** ([src/irl/visit-link.js](src/irl/visit-link.js) pure rules, [src/irl/visit-banner.js](src/irl/visit-banner.js) the "you're here to meet" banner, printable sign [pages/irl-sign.html](pages/irl-sign.html) `→ /irl/sign?pin=<id>` + [src/irl-sign.js](src/irl-sign.js), dashboard modal in [src/dashboard-next/pages/irl-placements.js](src/dashboard-next/pages/irl-placements.js)): `/irl?pin=<id>` is the scannable handoff for a street demo. The page names the agent from the coordinate-free agent card until the presence-gated nearby read returns that pin, then flashes it and opens its card once. The discovered-pin card gains **View in AR** for ANY discovered pin, capability-routed by [src/irl/pin-ar.js](src/irl/pin-ar.js): iOS bakes the pin's GLB to an animated USDZ for Quick Look (the banner reads "Talk to <name>" and its tap reopens the card with the conversation live), Android with ARCore enters the same WebXR hit-test session as placement in a view-only mode (`enterFloorAnchor({ viewPin })`: the pin's mounted model is the session content, nothing persists, the group's transform is restored on exit), everything else opens the `/api/ar` launcher in a new tab. **Talk** ([src/irl/pin-talk.js](src/irl/pin-talk.js)) is a live spoken conversation with the agent standing in front of you, inside the pin sheet: the same `TalkController` as talk mode on `/avatars/:id` (mic or typed turn, `/api/chat` in the agent's persona by `agentId`, TTS in its voice, lipsync from the audio FFT onto the pin's mounted model via `AvatarMouthTarget`), barge-in on the mic, and a `talk` interaction logged once per conversation (never the transcript). While a conversation or a view-only AR session is open the pin's full model is pinned resident in `enforceLOD` (`_pinnedFull`). Runbook: [docs/irl/street-demo.md](docs/irl/street-demo.md). Tests: [tests/irl-visit-link.test.js](tests/irl-visit-link.test.js), [tests/irl-pin-ar.test.js](tests/irl-pin-ar.test.js), [tests/irl-pin-talk.test.js](tests/irl-pin-talk.test.js), e2e [tests/e2e/irl-pin-talk.spec.js](tests/e2e/irl-pin-talk.spec.js). |
+| Smart glasses (the nearest-agent cue on your lens) | Pure HUD protocol [src/irl/glasses/protocol.js](src/irl/glasses/protocol.js), controller [src/irl/glasses/bridge.js](src/irl/glasses/bridge.js), Web Bluetooth transport [src/irl/glasses/transport.js](src/irl/glasses/transport.js), device adapters [src/irl/glasses/frame.js](src/irl/glasses/frame.js) (Brilliant Labs Frame) + [src/irl/glasses/g1.js](src/irl/glasses/g1.js) (Even Realities G1), connect sheet [src/irl/glasses/connect-ui.js](src/irl/glasses/connect-ui.js), wired into [src/irl.js](src/irl.js) behind the /irl "Connect glasses" button | Live (companion BLE lenses) · Meta Ray-Ban Display and native camera/voice lanes planned | No smart-glasses display in 2026 can render a three.ws avatar: Frame and the G1 are thin Bluetooth screens with no browser, and Meta Ray-Ban Display is a 600x600 additive panel whose SDK states custom pixel and 3D rendering are unsupported. So the lens carries the SIGNAL (nearest agent, direction, distance, arrivals) that /irl already computes for its on-screen nudge ([src/irl/proximity-cue.js](src/irl/proximity-cue.js)), and the phone keeps the BODY in AR. The protocol module is pure (no DOM, no Bluetooth, no clock) so formatting, direction glyphs and byte-level packet framing are unit tested; the bridge above it owns WHEN to push (3 Hz ceiling, single-flight writes, 4 s heartbeat that recovers a dropped write, 3.5 s announcements) and mirrors IrlNet's status-event shape. A connected link stamps its telemetry as a `glasses` encounter. Web Bluetooth is Chromium-only, and the connect sheet gates on that honestly rather than failing at pair time. Docs: [docs/glasses.md](docs/glasses.md) `→ /docs/glasses`, build plan [docs/glasses/meta-ray-ban-display.md](docs/glasses/meta-ray-ban-display.md), platform research [docs/glasses/research.md](docs/glasses/research.md). Tests: [tests/irl-glasses-protocol.test.js](tests/irl-glasses-protocol.test.js) |
| Verifiable 3D provenance (content credentials) | Spec [specs/PROVENANCE_3D.md](specs/PROVENANCE_3D.md), pure core [api/_lib/provenance-3d.js](api/_lib/provenance-3d.js), Solana anchor [api/_lib/provenance-anchor.js](api/_lib/provenance-anchor.js), MCP tools [api/_mcp3d/tools/provenance.js](api/_mcp3d/tools/provenance.js) (`verify_provenance` free, `anchor_provenance` paid $0.05), free REST verify [api/provenance.js](api/provenance.js) `→ /api/provenance`, viewer badge [public/viewer.html](public/viewer.html), docs [docs/provenance.md](docs/provenance.md). | Live (verify) · anchor gated on issuer key + devnet funds | C2PA-style signed content credentials for AI 3D: creator, prompt, model/provider, lineage, timestamp, and the GLB's sha256, ed25519-signed by the three.ws issuer with the credential hash anchored on Solana. Free public `verify_provenance` / `GET /api/provenance?src=…` recompute the hash and return `verified | tampered | unknown` (a single changed byte → tampered); the verify path and response are coin-clean (both stores). `anchor_provenance` signs + writes the SPL Memo anchor + stores the credential in R2. Tests: [tests/provenance-3d.test.js](tests/provenance-3d.test.js). Evidence: [prompts/store-submissions/_generated/provenance/](prompts/store-submissions/_generated/provenance/). Store-submission prompt 19. |
| Simulation readiness (a physics grade for 3D assets) | Spec [specs/SIM_READINESS.md](specs/SIM_READINESS.md), pure core [api/_lib/sim-readiness.js](api/_lib/sim-readiness.js), storage [api/_lib/sim-readiness-store.js](api/_lib/sim-readiness-store.js) + migration [20260813180000_sim_readiness_grades.sql](api/_lib/migrations/20260813180000_sim_readiness_grades.sql), free MCP tool [api/_mcp3d/tools/sim-readiness.js](api/_mcp3d/tools/sim-readiness.js) (`grade_sim_readiness`), free REST [api/sim-readiness.js](api/sim-readiness.js) `→ /api/sim-readiness`, shared badge + details panel [public/sim-readiness-panel.js](public/sim-readiness-panel.js) (`<sim-readiness>`, used by [public/viewer.html](public/viewer.html) and [src/model-page.js](src/model-page.js)), write path in [api/_lib/forge-store.js](api/_lib/forge-store.js) `materializeCreation`, docs [docs/sim-readiness.md](docs/sim-readiness.md). | Live | The question a renderer never asks and a rigid-body solver always does: can this mesh be simulated as-is? Four verdicts (`simulation_ready`, `needs_scale`, `needs_repair`, `unusable`, plus `unreadable` for non-glTF bytes) over measurements derived entirely from the geometry: watertightness and winding via welded-position topology, real-world extents read as meters per the glTF unit convention, exact volume/centroid/inertia from the divergence theorem and tetrahedron covariance, and a convex-hull proxy with its convexity ratio. Nothing is guessed: where a value cannot be known from the mesh (true scale, density) the report says so. Grades are keyed by GLB content hash, not URL, so one row serves the forge creation, the Object Library entry, a remix and an arbitrary third-party URL; every finished generation is graded on the write path, so a model page renders its verdict with no extra request. Signed into the content credential as `simReadiness` (provenance v2), which is what makes the physics claim as forge-proof as the authorship claim. Free, no account, no coin surface, both stores. Tests: [tests/sim-readiness.test.js](tests/sim-readiness.test.js), [tests/api/sim-readiness-endpoint.test.js](tests/api/sim-readiness-endpoint.test.js), [tests/provenance-3d.test.js](tests/provenance-3d.test.js). |
| OpenAI Select Partner (partner surface + announcement pack) | [pages/openai/index.html](pages/openai/index.html) `→ /openai`, badge assets [public/partners/openai/](public/partners/openai), announcement [blog/three-ws-openai-select-partner.html](blog/three-ws-openai-select-partner.html) `→ /blog/three-ws-openai-select-partner`, directory card in [pages/partners.html](pages/partners.html) `→ /partners`, press/social pack [marketing/openai-select-partner/](marketing/openai-select-partner/README.md), original OpenAI-supplied badge files + press-release template [OAI Select Tier Assets/](OAI%20Select%20Tier%20Assets/README.md) | Live | three.ws's OpenAI Partner Network Select-tier surface. `/openai` is the partner landing: the supplied badge (used unmodified, on a white plate), the four live OpenAI surfaces (the free keyless [3D Studio MCP connector](docs/mcp-studio.md) `→ /api/mcp-studio`, the custom-GPT Actions twin `→ /api/3d/studio`, [Spatial MCP](specs/SPATIAL_MCP.md), and [AR in ChatGPT](docs/chatgpt-ar.md)), the connect table, and the eleven-tool list. The marketing pack holds badge-usage rules and the press-release draft, which is gated on OpenAI's written approval before publishing (see its README). |
@@ -297,6 +298,7 @@ bottom.
| Atlas (site-wide Cmd+K search + route map) | Palette [public/atlas.js](public/atlas.js) `-> /atlas.js`, ranking [public/atlas/score.js](public/atlas/score.js), map page [pages/atlas.html](pages/atlas.html) + [src/atlas-page.js](src/atlas-page.js) `-> /atlas`, index [scripts/build-atlas-index.mjs](scripts/build-atlas-index.mjs) `-> public/atlas-index.json`, task catalog [data/atlas-intents.json](data/atlas-intents.json), coverage [scripts/inject-atlas.mjs](scripts/inject-atlas.mjs) | Live | **Discovery layer for 650+ routes.** Cmd+K (or `/`) opens a search over every page in `data/pages.json` plus a curated set of TASKS that answer with ordered steps rather than one link, because "which page starts the get-paid flow" is a harder question than "where is /x402/studio". Zero-dependency single file so it runs identically on 250+ standalone HTML entry points; the index is fetched on first open, not page load. Every task step target is resolved against the real route table at build time, so an onboarding path cannot dead-end on a 404. Injected by a Vite `three-ws-atlas` plugin plus a post-build `dist/` walk (same belt-and-suspenders as [scripts/inject-tour-boot.mjs](scripts/inject-tour-boot.mjs), for the same plugin-ordering reason). Embeds and the nav/footer fragments are excluded. Doc: [docs/atlas.md](docs/atlas.md). Tests: [tests/atlas.test.js](tests/atlas.test.js). |
| Internationalization (i18n) | Runtime [src/i18n.js](src/i18n.js) `→ /i18n.js`; catalogs [public/locales/](public/locales) (`en` + 84 locales, `manifest.json`, `localized-pages.json`); pipeline [scripts/i18n-annotate.mjs](scripts/i18n-annotate.mjs) · [i18n-extract.mjs](scripts/i18n-extract.mjs) · [i18n-translate.mjs](scripts/i18n-translate.mjs) (Vertex Gemini, glossary-locked) · [i18n-backfill.mjs](scripts/i18n-backfill.mjs) (re-translates copy that was baked to English during a backend outage); hreflang in [api/sitemap/[type].js](api/sitemap/%5Btype%5D.js) | Live (85 languages) | LobeHub-model client-side copy swap. `npm run i18n:annotate` auto-injects `data-i18n*` into static HTML (byte-surgical), `i18n:extract` builds `en.json`, `i18n:translate` fans it out to every locale via Vertex with brand/protocol terms masked. `i18n:backfill` finds keys whose value is still byte-identical to English (the silent failure mode: a baked fallback is present, so every later run skips it) and re-translates them. Runtime auto-detects locale, mounts a floating `<lang-switcher>`, and injects hreflang. Doc: [docs/i18n.md](docs/i18n.md). Tests: [tests/i18n.test.js](tests/i18n.test.js), [tests/i18n-annotate.test.js](tests/i18n-annotate.test.js), [tests/i18n-backfill.test.js](tests/i18n-backfill.test.js). |
| Shared utilities (import instead of hand-rolling) | Frontend [src/shared/markdown.js](src/shared/markdown.js) · [src/shared/toast.js](src/shared/toast.js) · [src/shared/fuzzy.js](src/shared/fuzzy.js) · `timeAgo`/`toEpochMs` in [src/shared/coin-format.js](src/shared/coin-format.js); backend [api/_lib/resilience.js](api/_lib/resilience.js) · [api/_lib/mem-cache.js](api/_lib/mem-cache.js) · [api/_lib/pool.js](api/_lib/pool.js) · [api/_lib/csv.js](api/_lib/csv.js); ops [scripts/check-cron-drift.mjs](scripts/check-cron-drift.mjs) | Live · doc [docs/shared-utilities.md](docs/shared-utilities.md) | Thin layers over vetted packages, each replacing a family of hand-rolled copies that had drifted. `markdown.js` = `marked` + `DOMPurify`, the single sanitized path for model/user text reaching `innerHTML` (the concierge SDK carries its own copy at [concierge-sdk/src/markdown.js](concierge-sdk/src/markdown.js) because it ships as an independent bundle). `toast.js` = one aria-live region with a real queue. `fuzzy.js` = `@leeoniya/ufuzzy` ranking + typo tolerance + match ranges for both command palettes. `resilience.js` = `cockatiel` circuit breakers **and** jittered retry (`withRetry`, `parseRetryAfter`, `isRetryableError`). `mem-cache.js` = `lru-cache` with true recency eviction and single-flight `cached()`. `pool.js` = `p-limit` bounded concurrency. `csv.js` = RFC 4180 quoting **plus** spreadsheet formula-injection neutralization. `check-cron-drift.mjs` = `cron-parser` validation of every cron declared in vercel.json against live Cloud Scheduler, sharing its job-id derivation with [scripts/create-gcp-scheduler.mjs](scripts/create-gcp-scheduler.mjs) so the two can never disagree. Tests: [tests/shared-markdown.test.js](tests/shared-markdown.test.js), [tests/fuzzy.test.js](tests/fuzzy.test.js), [tests/csv.test.js](tests/csv.test.js), [tests/resilience-shared.test.js](tests/resilience-shared.test.js) |
+| Announcement factory (internal) | Calendar [scripts/announce-plan.mjs](scripts/announce-plan.mjs) `npm run announce:plan`, factory [scripts/announce-kit.mjs](scripts/announce-kit.mjs) `npm run announce:kit`, engine [api/_lib/announce/](api/_lib/announce), ranker [scripts/announce-rank.mjs](scripts/announce-rank.mjs), gate [scripts/check-announce.mjs](scripts/check-announce.mjs), packs [docs/announcements/](docs/announcements/README.md), deferrals [data/announce-deferred.json](data/announce-deferred.json) | Internal, owner-gated · doc [docs/announcement-factory.md](docs/announcement-factory.md) | Works the backlog of shipped surfaces nobody has posted about (322 of 429) into the X content queue, a batch at a time. The calendar is derived from the publisher's own cadence and rotation rules, so it can never promise a slot the scheduler would refuse, and a surface whose frame would carry live third-party market data is flagged for owner approval instead of being quietly packed. Each pack starts as an evidence brief (the rendered live page, the changelog, the docs, the README) whose every fact is already a check the verifier can run; the model chain drafts from that brief and nothing else, and the draft is held against the voice lint, the claims ledger, the evidence list and the account's own archive, then rewritten until it passes. A surface with no route (packages, workers, services) gets a title card typeset from its real README in the site's own fonts, because a post with no image measured 0.875x. Output is a pack plus a queue item at status `draft`: approval and publishing stay exactly where they were. Tests: [tests/announce-factory.test.js](tests/announce-factory.test.js) |
| X content pipeline (internal) | Queue [data/x-content/queue.json](data/x-content/queue.json), engine [api/_lib/x-content/](api/_lib/x-content), cron [api/cron/x-content.js](api/cron/x-content.js), CLI [scripts/x-content.mjs](scripts/x-content.mjs), media `public/x-media/` | Internal, owner-gated · doc [docs/x-content-pipeline.md](docs/x-content-pipeline.md) | The reviewed @trythreews publishing queue: posts and threads with native images, GIFs, and captioned video, blog or external pages imported as native posts or full X Articles (via the X Articles API), a copy lint against automated-feed tells, jittered cadence with lane rotation, and a database ledger that resumes a half-sent thread instead of reposting. Previews only until `X_CONTENT_AUTO_PUBLISH=true`. Tests: [tests/x-content.test.js](tests/x-content.test.js) |
| X post archive + engagement analysis (internal) | Snapshots [data/x-archive/](data/x-archive), schema [api/_lib/migrations/20260814120000_x_account_archive.sql](api/_lib/migrations/20260814120000_x_account_archive.sql), normalization + analysis [scripts/x-archive-lib.mjs](scripts/x-archive-lib.mjs), commands [scripts/x-archive-import.mjs](scripts/x-archive-import.mjs) · [scripts/x-archive-refresh.mjs](scripts/x-archive-refresh.mjs) · [scripts/x-archive-analyze.mjs](scripts/x-archive-analyze.mjs), report [docs/x-archive/](docs/x-archive) | Internal · doc [docs/x-archive.md](docs/x-archive.md) | Every post our own X accounts published, kept as raw snapshot files and indexed into `x_account_posts` / `x_account_post_snapshots` so engagement is a measured time series rather than a memory. `npm run x:archive:analyze` regenerates a report ranking posts by engagement and by engagement *rate*, and scores every measurable signal (media, mentions, length, subject, hour) as lift against the corpus median. Two scraper defects are handled rather than inherited: a profile scrape returns reposts of other accounts with `isRetweet: false` (authorship is read from the permalink instead), and X renders like counts lazily so real posts arrive at "0 likes" (those are archived, named, and excluded from the medians until `npm run x:archive:refresh` replaces them with exact X API counters). Distinct from `x_posts`, which is what platform users publish through [api/x/post.js](api/x/post.js). Tests: [tests/x-archive.test.js](tests/x-archive.test.js) |
| Interactive 3D history timeline | [pages/timeline.html](pages/timeline.html) `→ /timeline`, [src/timeline.js](src/timeline.js), data [data/timeline.json](data/timeline.json) | Live | three.ws's public history (launches, partnerships, listings, press, product ships) as an explorable 3D scene: 60+ milestones as glowing markers along a curved path, 360° free-orbit or a marker-to-marker Walk mode with a guide beacon (reuses the shared `AnimationManager` + default rig from [src/walk.js](src/walk.js)'s pattern), a synced bottom scrubber, category filters, and a detail panel linking to the original source where one exists (IBM Community, NVIDIA Developer Forums, Yahoo Finance, Phemex, CoinGecko, HackerNoon). Real accessible HTML-list fallback for no-WebGL or fetch-failure. |