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(publishing): draft the September venue posts and register them as unpublished
nirholasc014a909c23f
diff --git a/docs/devto-mcp-fleet-post.md b/docs/devto-mcp-fleet-post.mdnew file mode 100644index 000000000..8739487d0--- /dev/null+++ b/docs/devto-mcp-fleet-post.md@@ -0,0 +1,88 @@+---+venue: dev.to (cross-post to Hashnode and Medium with canonical back to three.ws)+account: three.ws / nichxbt+suggested_title: "We published 72 MCP servers. Here is what I would do differently."+description: "A practical post-mortem on running a large MCP fleet: why we ended up with 72 servers, the four traps that cost us the most (annotation blindness, stdio consent, OAuth discovery 404s, and free/paid entanglement), and the four rules we now build to."+tags: [mcp, ai, agents, opensource]+canonical: https://three.ws/docs/mcp+status: draft, owner approval required before posting (external-channel gate in CLAUDE.md)+---++# We published 72 MCP servers. Here is what I would do differently.++Not a brag. A confession, and then four rules.++I work on [three.ws](https://three.ws), an open-source platform where AI agents get 3D bodies. Along the way we ended up publishing **72 MCP servers in the official Model Context Protocol registry** under one namespace, and **91 npm packages**, 39 of them MCP servers in the main repo. That happened over months, one reasonable decision at a time, and the sum of those reasonable decisions is a discovery problem.++If you are about to publish your second, fifth, or fiftieth MCP server, this is what I know now that I did not know then.++## How you get to 72 without ever deciding to++Every capability that felt independently useful became its own server, because publishing a server is cheap and MCP has no first-class notion of a bundle or a namespace. Avatars, 3D generation, scenes, voice, vision, market data, notifications, billing, naming, provenance, home control, and so on. Each one was defensible. None of them was the result of a plan.++The failure is not technical. All 72 work. The failure is that **a user cannot find the right one**, and neither can an agent, and the registry alone does not fix that.++## Trap 1: tool annotations describe, they do not enforce++MCP gives you `readOnlyHint`, `destructiveHint`, `openWorldHint`. Set them accurately; reviewers check, and inaccurate annotations are a listed rejection reason on the platforms with directories.++But understand what they are: **metadata for the client's UI, not a control.** They do not stop a tool. And the vocabulary has a real gap: `destructiveHint` covers "this deletes something", and does not distinguish between "this spends forty dollars" and "this unlocks a door in a house where a child is asleep".++We now write the server-side refusal first and the interface second. If a guard exists only in prompt text or in a hidden button, it is not a guard. An assistant can be argued out of a sentence; it cannot be argued out of a 403.++## Trap 2: a stdio server cannot obtain consent, and should stop pretending++We publish a server that gives any assistant control of a real Home Assistant house: read the house, list entities, list scenes, run one, call a service.++The dangerous calls (locks, primarily) pass through a physical-action gate, and **over stdio that gate refuses outright**. Not "prompts the user". Refuses.++The reasoning took us a while to arrive at and now seems obvious. A local stdio MCP server has no user-visible surface of its own, no session, and no way to prove that a human saw a request and approved it. Any "confirm?" it emits is a string the model can read, generate, and answer by itself. That is not consent, it is theatre. So the dangerous verbs are only available on a surface where a real person can be shown a real prompt, and the local server says plainly that it will not do it and why.++The pattern generalises past homes to any stdio server that can spend money, send messages as a user, or move something physical.++## Trap 3: the OAuth discovery document nobody checks++Our hosted server sits behind OAuth 2.1. The single most common reason a technically-correct MCP server fails a client's auth handshake is that `/.well-known/oauth-protected-resource` (or its neighbours) is not actually routed and answers 404, usually because the route table and the file layout disagree in production but not locally.++Test it from outside your network, in production, with curl, after every deploy. It is a one-line check and it saves a week of "works on my machine" bug reports from users you cannot debug.++## Trap 4: free and paid entangled in one server++We ship a free 3D server and a paid one. The free one has **no payment code in it at all.** Not disabled, not feature-flagged: absent. Different origin, different codebase, different deploy.++This started as a review-friendliness decision (the directories reject anything that looks like it might charge under false pretences, and "we present a call as free and then charge" is a listed rejection reason). It turned out to be an engineering win too: a claim you can verify by reading an import list is a claim that stays true, and a flag that gates payment is a flag somebody will flip in the wrong environment eventually.++The one exception we allow runs the other way, and it is deliberate: a couple of tools on the **paid** server are permanently free, because they are assurance checks. An asset-grading tool that costs money is a tool nobody calls, and a tool nobody calls prevents nothing.++## The four rules we build to now++**1. One tightly scoped server per audience, not per capability.** Our ChatGPT-facing server is exactly the 3D tools and nothing else: eleven of them, keyless, no wallet, no account. The directories reward tightly scoped apps and reject generic ones, and thirty-seven separately submitted servers read as directory spam even when each one is good. Submit one, document the rest as direct connections.++**2. One hosted server for clients that want everything**, behind real auth, with working discovery metadata.++**3. Typed tool authoring, shared across servers.** We publish `@three-ws/tool-sdk` (`defineTool`, `defineExec`) so annotations, schemas, and error shapes cannot drift from server to server. Fifty hand-written servers will disagree about error shape by the third one, and an agent handling five different error conventions handles none of them well.++**4. Publish where clients actually look.** The official registry is necessary and not sufficient. Ours are also indexed on PulseMCP and Glama, exposed through a LobeHub plugin manifest served from our own domain, and shipped as plugins in an editor plugin marketplace. Discovery is distribution, and distribution is not automatic.++## The one thing that mattered more than all of it++If you take a single idea from this post, take this one instead of anything about fleets.++Every text-to-3D API, ours included, answered tool calls with a **URL to a binary file**. A human clicks it. An agent cannot read it. So we shipped a tool that renders a model into frames returned as MCP image content blocks, and the agent can finally look at what it made, judge it, and iterate.++It was a weekend of work and it changed what the pipeline can do, because a loop needs an error signal and a binary URL is not one.++**Any tool that hands an agent a binary needs a companion that renders it into the agent's own modality.** PDFs, spreadsheets, audio, CAD, compiled artifacts. If your agent cannot perceive its own output, it is guessing, and no amount of prompt engineering fixes that.++## Try any of it++```bash+# 11 keyless 3D tools, no account+curl -s https://three.ws/api/mcp-studio \+ -H 'content-type: application/json' \+ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'+```++Everything is Apache-2.0 at [github.com/nirholas/three.ws](https://github.com/nirholas/three.ws). The MCP docs are at [three.ws/docs/mcp](https://three.ws/docs/mcp).++If you publish MCP servers at any scale, I would like to hear how you handle namespacing and discovery. I do not think our answer is right; it is only the one that worked.diff --git a/docs/google-cloud-community-post.md b/docs/google-cloud-community-post.mdnew file mode 100644index 000000000..8cad037a1--- /dev/null+++ b/docs/google-cloud-community-post.md@@ -0,0 +1,84 @@+---+venue: Google Cloud Community (Medium publication) / Google Cloud Community forums+account: three.ws (official)+suggested_title: "One container, 115 scheduled jobs, and a GPU fleet that sleeps: an AI platform on Cloud Run"+description: "How three.ws serves a static frontend, a route table, every API handler, and a fleet of open 3D model GPUs from Cloud Run: the single-container decision, Cloud Scheduler as the cron plane, Vertex AI as the reliability anchor in a free-first model chain, and the three deploy gates we added after each one caught a real outage."+tags: [cloud-run, cloud-scheduler, vertex-ai, gpu, generative-ai]+status: draft, owner approval required before posting (external-channel gate in CLAUDE.md)+---++# One container, 115 scheduled jobs, and a GPU fleet that sleeps++three.ws is an open-source platform where you describe a character and get a rigged, animated 3D agent you can embed anywhere. It runs on Google Cloud, and three.ws is a member of Google Cloud for Web3 Startups. This is the infrastructure write-up: what runs where, which decisions have held up, and the three deploy gates we added only after each one had already cost us an outage.++Everything is Apache-2.0 at [github.com/nirholas/three.ws](https://github.com/nirholas/three.ws), and `GET https://three.ws/api/version` returns the exact commit and Cloud Run revision production is serving, so any claim here is checkable against the code that serves it.++## The single-container decision++One Cloud Run service serves three things that are usually three deployments: the **static frontend**, the **route table**, and **every API handler**.++The route table is the part worth explaining. Our routes live in a JSON config that the server reads on boot and splits into pre-filesystem and post-filesystem phases, which means a route change is a config change rather than a code change, and the same file is the source of truth for the scheduler sync described below. It is a slightly unusual shape and it has paid for itself repeatedly: there is exactly one place to answer "what serves this path".++Why one container rather than a service per concern:++- **A page and the API it calls share a deploy**, so a frontend that expects a new field cannot ship ahead of the field.+- **Cold-start count is one**, not seven. With serverless services, every additional service is another cold path for a user to hit.+- **The revision is the unit of truth.** "Which revision is serving this?" has one answer, and a rollback is one command.++The trade is real: the container is larger than a per-endpoint function would be, and a hot path shares CPU with a cold one. For a product where the frontend and the API change together in almost every commit, it has been the right trade.++## Cloud Scheduler as the cron plane++There are 115 scheduled jobs. They are declared in the same config file the server reads for routes, and a script syncs that declaration into Cloud Scheduler, so adding a job is a config change reviewed like any other.++Two lessons from operating that many:++**A dispatcher beats 115 schedule entries with independent opinions.** Several of our high-frequency jobs are invoked by one economy tick that fans out, with per-entry cooldowns deciding what actually fires. Sixty jobs each waking on their own minute boundary is sixty simultaneous cold starts on the same minute.++**Declare the schedule where the code lives.** A cron that exists only in the console is invisible to code review, invisible to `git log`, and impossible to recreate after an account change.++## The GPU fleet, and why min-instances is a quota decision++The generation lanes run open 3D model families on their own Cloud Run GPU services (NVIDIA L4s, plus one RTX PRO 6000 Blackwell for the heaviest work): TRELLIS for image to 3D, Hunyuan3D for high-poly reconstruction, TripoSG for sketch to 3D, and around them the mesh pipeline (rigging, remeshing, texturing, segmentation, stylization, background removal, avatar reconstruction, text to motion, video to motion, video to scene). Thirty-two workers in total, most published as Docker images.++The interesting cost is not the container start. It is the **weight load**: on a FUSE-mounted volume a cold load can stall for minutes before the job begins. Which produces the counter-intuitive rule:++**`min-instances` is a quota decision, not a performance one.** A regional L4 grant is finite. Pinning a warm instance on every lane starves the lanes that need to burst. So one lane pins one always-warm instance and bursts to three, another was explicitly moved to zero to free the shared regional pool, and the spiky lane scales to zero. Three different answers to the same question, correct per lane.++A keep-warm job holds an allowlist of scale-to-zero lanes resident during peak hours, with the allowlist in an environment variable so it changes without a deploy. One detail worth copying: **a lane id in that allowlist that matches no known lane fails the tick loudly** rather than warming nothing silently. A typo in a keep-warm config is otherwise invisible until someone complains about latency a fortnight later.++And when the regional pool is exhausted, requests do not fail with a message that says "quota". They fail slowly, in a pattern that reads like a model problem. We keep a named signature for it in the triage runbook, and the first check on any "generation is slow" report is the pool, not the model.++## Vertex AI as the anchor at the bottom of a free-first chain++Every text completion on the platform runs through one shared failover chain that tries free providers first and only reaches a paid key last. That chain is a dozen rungs deep, and two design rules matter more than the ordering:++**The chain can never have an empty rung.** Two rungs are keyless on purpose, so the bottom always exists even when every keyed provider is unset or throttled.++**Vertex Gemini is the reliability anchor**, billed to our own cloud budget rather than a third-party free tier, which means the chain's floor does not depend on somebody else's quota reset. That is the specific reason to put a first-party cloud model in a free-first chain: not because it is cheapest, but because it is the rung whose failure mode you control.++A related trap, which is not cloud-specific but bit us here: **model end-of-life is a silent outage.** An upstream family reached end of life and its rung began answering `410`. The chain fell through correctly, but the real fix was a scheduled job that diffs our hardcoded model ids against live provider catalogues, so we learn before users do. If you hardcode model ids anywhere, you owe yourself that job.++## Three deploy gates, each added after it would have saved us++Our build is a fixed chain and the order is load-bearing: conflict check, browser-graph check, a temporal-dead-zone check, sub-artifact builds, the frontend build, then the steps that write into the output directory *after* the frontend build wipes it. That last ordering fact has broken us more than once, so it is encoded in one command rather than in anyone's memory.++The three gates that matter most, and what each one caught:++**1. A migration gate before submit.** The build refuses to submit when a database migration is pending. Without it, new code shipped over an old schema, and production served handlers querying a column whose migration had never been applied. The error a user sees in that situation looks nothing like "we forgot a migration".++**2. An upload-context simulation.** Before submitting, we simulate the build-context upload and fail if a file the server imports at runtime would be excluded by ignore rules. This exists because a revision shipped with one omitted module and answered every request, health check included, with a module-not-found error. The build was green. The container started. Nothing was wrong except one file that never got uploaded.++**3. A synchronous CDN purge.** Our purge used to run asynchronously, and post-deploy checks then read stale edge content and reported phantom failures. Making it synchronous costs a minute and removes an entire category of "is it deployed or not" confusion.++The fourth, cheaper than all of them: a version endpoint that returns the running commit and revision. Nearly every "is this live?" conversation ends in one curl.++## What I would tell someone starting the same build++- **Put the route table in a file the server reads,** and let other tooling read the same file. One source of truth beats one convention.+- **Decide per lane whether a warm floor is worth it,** and write down why, because the reasoning is not recoverable from the config six months later.+- **Give every failover chain a keyless bottom rung.**+- **Add a gate the day after an incident, not the week after.** Each of the three above was written in the hours following the outage it now prevents, which is the only time the exact failure is still fresh enough to encode.+- **Publish the version.** It costs an afternoon and it retires an entire genre of conversation.++Free to try, no account and no key: [three.ws/forge](https://three.ws/forge) for 3D generation, `https://three.ws/api/mcp-studio` for the eleven-tool MCP server, and [three.ws/docs](https://three.ws/docs) for the rest.diff --git a/docs/home-assistant-community-post.md b/docs/home-assistant-community-post.mdnew file mode 100644index 000000000..63648b5c5--- /dev/null+++ b/docs/home-assistant-community-post.md@@ -0,0 +1,104 @@+---+venue: Home Assistant Community (community.home-assistant.io), category "Share your Projects!"+account: three.ws (official) / nichxbt+description: "Forum post introducing the three.ws Home Assistant integration: a HACS custom integration that dials out over one WebSocket so a LAN-only install can be reached, an MCP server whose door-opening tools refuse over stdio, household roles enforced server-side, and a 3D agent that stands in a live model of your house."+tags: [custom-integration, hacs, mcp, voice, presence]+status: draft, owner approval required before posting (external-channel gate in CLAUDE.md)+---++# I gave my Home Assistant a face, and spent most of the time making sure it cannot open my front door++_Forum post for the [Home Assistant Community](https://community.home-assistant.io), category "Share your Projects!". Written first person for people who run HA, not for people who sell things to people who run HA._++Hi all. I build [three.ws](https://three.ws), an open-source (Apache-2.0) platform for 3D AI agents: you describe a character, you get a rigged, animated 3D body that can talk, and you can embed it anywhere. For most of its life that character lived in a browser tab and the worst thing it could do was say something silly.++Then I connected it to my house, and the whole design changed. This post is what I built, and much more importantly, what I refused to build.++Short version: there is now a HACS integration that connects a LAN-only Home Assistant to a 3D agent that stands in a live model of your home and talks to you, plus an MCP server so **any** assistant (Claude, Cursor, your own) can read and drive your house. Locks are the interesting part, and the answer there is a flat no in several places on purpose.++## What Home Assistant already does, and what I did not rebuild++I wrote zero device code. Not "a thin abstraction", zero. Zigbee, Z-Wave, Matter, Thread, BLE, and the 1,500-plus integrations are the reason this project took weeks instead of years, and re-implementing any of it would have been vandalism. Since the `mcp_server` integration, HA also speaks Model Context Protocol natively, and three.ws already speaks MCP in around forty packages. The two halves met without either side inventing a protocol.++What genuinely does not exist anywhere, as far as I can tell, is the **face**: a real-time 3D presence that stands in a live model of your home, reacts to it, and speaks. That is the part I built.++## The LAN problem, and why the house dials out++Most HA installs cannot be reached from the internet. No forwarded port, no public address, nothing to dial. That is not an edge case, it is the default install, and any integration that assumes otherwise is a cloud product wearing a local-first hat.++So: **the house dials three.ws, and three.ws never dials the house.**++One integration from HACS opens a single outgoing WebSocket and keeps it open.++- Nothing listens on your network.+- No port is forwarded and no firewall rule changes.+- No tunnel daemon, no third-party service, no account anywhere else.+- **three.ws never receives a Home Assistant token.** The integration signs in to HA on your own machine with a credential it creates for itself, and that credential never leaves the house.++Install path, if you want to try it:++1. On three.ws, open `/smart-home`, choose **Connect a home that is only on my network**, and press **show me a code**. It has a ten-minute countdown.+2. In HACS, add `https://github.com/nirholas/three-ws-home-assistant` as a custom repository, category **Integration**.+3. Install **three.ws**, restart HA.+4. **Settings, Devices and services, Add integration, three.ws.** Paste the pairing code.++If your HA already has a remote https address (Nabu Casa, or your own reverse proxy), skip all of that and connect with a long-lived token instead. The relay exists for the houses that do not, not as the default path.++The threat model is written down and published rather than implied. Writing it is what produced two of the constraints above, which is an argument for writing one even when nobody asks.++## The part I care about: locks++Here is where I expect this forum to have opinions, and I would genuinely like them.++An LLM that can call `light.turn_on` is a convenience. An LLM that can call `lock.unlock` is a completely different product with a completely different failure mode, and the industry answer so far has been to put a sentence in a system prompt. **A system prompt is an argument, and an argument can be won by the other side.**++So the refusals live on the server, in four layers:++**1. The physical-action gate.** Anything that opens the house passes through one gate with one implementation (shared between the bridge and the MCP server rather than two copies that drift). It is not a naming convention or a category filter; it is a code path.++**2. Over stdio, that gate refuses outright.** The published MCP server, `@three-ws/home-mcp`, gives any assistant five tools: read the house, list entities, list the scenes your household already built, run one, call a service. Point it at your HA:++```bash+claude mcp add home \+ -e HOME_ASSISTANT_URL=https://example.ui.nabu.casa \+ -e HOME_ASSISTANT_TOKEN=... \+ -- npx -y @three-ws/home-mcp+```++Ask it to unlock a door and it will decline and tell you why. A stdio MCP server has no user-visible surface of its own, no session, and no way to prove a human saw the request and approved it. Anything that presents itself as consent in that environment is a fiction, so unlocking is available only where a real person can be shown a real prompt.++**3. Household roles, enforced server-side.** A house has more than one person in it, and the old answer was to hand over your password. There are five roles now, each stating in plain words at the moment you pick it what it can and cannot do:++- Somebody who lives there can control everything and approve unlocking a door.+- A guest can turn the lights on and **can never** approve unlocking anything, no matter what an agent asks them. That refusal is enforced on the server, so there is no version of any client that could offer them the button.+- A guest or viewer can be scoped to just the kitchen, or just three devices, and **the rooms you did not give them are removed from what they receive**, not hidden on screen. Their app never learns those rooms exist.+- Invitations work once, expire after a week, and can be withdrawn before anyone uses them.+- Removing somebody takes back every standing allowance they ever approved in the same instant, so a door cannot keep opening on the say-so of a person who has left.+- Every action in the home log is attributed to the person who took it, so "who did what" has a real answer.++**4. Voice, where consent is loosest.** Hands-free is the only interface that works when you are carrying groceries, and it is also the interface where a television in the next room can say "yeah". Confirming a physical action requires an intentional utterance, not an affirmative-sounding noise. This one took three rewrites and I still would not call it solved.++## Things I tried and did not ship++**Exposing the agent as a Matter device.** It is the obvious move, it would have been a good headline, and after measuring what it would actually cost and buy, I decided against it for now and published the reasoning rather than quietly dropping the thread. If someone here has done it and thinks I got the trade wrong, I would like to hear it.++**A cloud-first pairing flow.** The first version had the platform dial the house. It worked in my house and in almost nobody else's, for the reasons in the LAN section.++## The rest, briefly++- **A live 3D scene of your home** that the agent stands in, reacting to state as it changes. It is the reason to have a body at all: an agent that is *somewhere* in a house reads differently from a text box that mentions rooms.+- **A voice satellite face.** If you run an HA voice assistant, it can wear the agent's face instead of being a speaker grille.+- **Privacy as a page, not a policy.** See, export and delete everything a connected home stores, on one screen.+- **Honest status.** The status page can tell a dark house (yours is off, or asleep, or the internet is out at your end) from an actual outage on our side, and it says which. One unreachable home can no longer degrade the others, which was a real bug and a fair thing to be annoyed about.+- **Language and units.** The whole surface reads in your language, in your units, at a touch size that works on a wall tablet, and the wall display stays awake.+- **The car**, because it is the same design problem: a voice-first agent that can reach your house from the road, with an Android Auto app built and a CarPlay scene waiting on Apple's entitlement.++## What I would like from this forum++1. **Is the stdio refusal right, or is it paternalistic?** My reasoning is that a local server cannot prove consent. The counter-argument I keep hearing is that it is the user's own machine and their own choice. I have not been convinced yet, but I am listening.+2. **Roles.** Five felt like the smallest set that covers real households (residents, guests, house sitters, kids, view-only displays). If you run a household where those five break down, tell me where.+3. **What should an agent never be allowed to do, even for the owner?** My current list is short: nothing that unlocks without a proven human prompt, and nothing that silently changes another person's access. I suspect this list should be longer.++Everything is Apache-2.0. The integration is at [github.com/nirholas/three-ws-home-assistant](https://github.com/nirholas/three-ws-home-assistant), the MCP server is `@three-ws/home-mcp` on npm, the platform is at [three.ws/smart-home](https://three.ws/smart-home), and the docs (including the relay threat model and the Matter write-up) are at [three.ws/docs/smart-home](https://three.ws/docs/smart-home).++Happy to answer anything, including hostile questions about why a 3D avatar belongs anywhere near a house. That last one is fair and I have a real answer for it: a home has rooms and objects, and an assistant that can be *somewhere* in it is easier to talk to than one that cannot.diff --git a/docs/huggingface-agent-feedback-loop.md b/docs/huggingface-agent-feedback-loop.mdnew file mode 100644index 000000000..69172b7ad--- /dev/null+++ b/docs/huggingface-agent-feedback-loop.md@@ -0,0 +1,121 @@+---+venue: Hugging Face community article (huggingface.co/blog/three-ws/...)+account: three-ws (organization)+suggested_title: "Generate, look, grade, iterate: closing the feedback loop for agentic 3D"+description: "Third three.ws article for the Hugging Face community. Text-to-3D has been one-shot since it existed, because the model that generates an asset cannot perceive it. This is the loop we built to fix that: rendering results back into the model's own modality, a mechanical physics-readiness grade, structural diffing between iterations, and universal retargeting, all on open models running on our own GPUs."+tags: [3d, agents, mcp, open-models, evaluation]+house_rules: |+ Hugging Face blog rules as applied to our previous two articles: keep it AI-focused.+ No coin, exchange, listing, or token content anywhere in this piece. Partner status+ may be stated factually where it is technically relevant, never as promotion.+status: draft, owner approval required before posting (external-channel gate in CLAUDE.md)+---++# Generate, look, grade, iterate: closing the feedback loop for agentic 3D++This is the third piece we have published here. The [first](https://huggingface.co/blog/three-ws/giving-ai-agents-bodies-and-wallets) argued that agents need bodies. The [second](https://huggingface.co/blog/three-ws/building-3d-ai-agents-end-to-end) walked the whole stack end to end. This one is about a single missing primitive that we think holds back every agentic 3D pipeline, ours included, and what happened when we built it.++**The problem in one sentence: every text-to-3D API in existence answers with a URL to a binary file, and a language model cannot read a binary file.**++That is why agentic 3D has been stuck at one shot since it began. The agent spends GPU time, receives a link, and has no way to tell a clean mesh from a melted one. It hands the link to a human and hopes. There is no error signal, so there is no loop, so there is no agency: just a very expensive random draw.++Everything below is Apache-2.0 at [github.com/nirholas/three.ws](https://github.com/nirholas/three.ws), and every endpoint marked free is keyless.++## 1. Let the model look at what it made++The fix is embarrassingly simple once you say it out loud: render the result back into a modality the model actually perceives.++Our `look_at_model` tool renders a GLB from several angles and returns the frames as **MCP image content blocks**, so a multimodal client renders them straight into the conversation. Alongside the frames it returns the geometry facts (triangle count, bounds, material count, whether it is skinned) and a plain-language reading of them.++Three ways in, because different consumers want different shapes:++| You are | Use | You get |+|---|---|---|+| An MCP client | `look_at_model` on `https://three.ws/api/mcp-studio` | frames as image blocks, rendered inline |+| A Node program | `@three-ws/see` | `see(url)` returns views, stats, notes |+| Anything with HTTP | `POST https://three.ws/api/3d/look` | JSON with a frame URL per angle |++```bash+curl -s -X POST https://three.ws/api/3d/look \+ -H 'content-type: application/json' \+ -d '{"src":"https://three.ws/avatars/cesium-man.glb"}'+```++What changes is not the quality of any single generation. What changes is that the agent can now **judge** one, which means it can decide to refine, and every refinement is its own version with its own artifacts. Generate, look, judge, refine, look again.++The generalisation is the part worth taking away, and it is not about 3D at all: **any tool that hands an agent a binary is a tool that needs a companion that renders it into the agent's own modality.** Ours was a mesh. Yours might be a PDF, a spreadsheet, an audio file, a CAD assembly, a compiled binary. If your agent cannot perceive its own output, it is not iterating, it is guessing.++## 2. A grade, so "good" means something mechanical++Perception gets you taste. It does not get you a specification.++A renderer forgives almost everything; a rigid-body solver forgives nothing. A mesh that looks perfect on screen can sink through the floor in MuJoCo, behave as if hollow in Bullet, or turn out to be a metre tall because the generator fitted it to a unit box and nothing in the file says so. Every robotics, game-physics and world-model pipeline rediscovers those defects by hand, one asset at a time.++So we published the claim, mechanically, free, and CC0:++```bash+curl "https://three.ws/api/sim-readiness?src=https://three.ws/avatars/cesium-man.glb"+```++Four verdicts:++| Verdict | Meaning |+|---|---|+| `simulation_ready` | Closed surface, consistent winding, positive volume, real-world extents. The only verdict that licenses trusting the reported mass. |+| `needs_scale` | Geometry is sound, only the units are missing. Multiply; mass properties scale with it. |+| `needs_repair` | Open, non-manifold, or inconsistently wound. Mass is reported but unreliable. |+| `unusable` | No triangles, or zero volume. |++A fifth value, `unreadable`, covers bytes that are not binary glTF 2.0 at all, kept deliberately distinct: one is a broken file, the other is a valid file with nothing to simulate. Verdicts are content-addressed by the file's SHA-256, so identical bytes always get an identical grade and caching is trivially correct.++Two design decisions I would defend to anyone building evaluation infrastructure:++**Free, permanently.** It is also exposed as a free tool on our *paid* MCP server, which is a deliberate exception to that server's pricing. An assurance check that costs money is a check nobody runs, and a check nobody runs prevents nothing.++**A spec, not a service.** [`specs/SIM_READINESS.md`](https://github.com/nirholas/three.ws/blob/main/specs/SIM_READINESS.md) is CC0 and the grader is a pure function you can vendor. If this becomes a standard that other people implement and we never see the traffic, that is the successful outcome, not a lost one. The glTF ecosystem has no machine-readable claim about physical usability, and that hole gets filled either by a shared spec or by fifty incompatible internal scripts.++## 3. Diff, so "changed" means something structural++Between iterations, "did that actually change anything" gets asked constantly, and comparing two viewers by eye is a bad instrument at any scale.++`@three-ws/glb-diff` answers structurally: node graph, meshes, primitives, materials, textures, skins, animations, and what moved. It began as an internal debugging tool for the refine loop, and it is now the thing we reach for whenever a model is subtly wrong. If your pipeline mutates glTF anywhere (optimisation, retexturing, decimation, rigging), it is worth wiring in.++Together with the grade, this is what turns a refine loop into something you can actually evaluate: perception says whether it looks right, the grade says whether it is usable, and the diff says whether the last change did anything at all.++## 4. Retargeting, because the rig is never yours++The other half of "agentic 3D" is that the asset has to *do* something, and animation is where pipelines quietly fail.++Our constraint is that we never see the model first. It might come from our own lanes, from Mixamo, VRoid, Daz, Unreal, or a Blender export from 2019. So instead of a curated allowlist of supported rigs, we canonicalise bone names, then retarget onto the canonical set. The mapping covers Mixamo, Avaturn, Unreal, VRM and VRoid, VRM 1.0, Daz/Genesis, MakeHuman, Blender `.L`/`.R` and simple `shoulderL` conventions, and a new convention is one mapping entry plus a test, not a new code path. A model that genuinely cannot be skeleton-driven falls back to a default rig rather than a bind-pose T-pose, because a T-pose reads as a bug to every user and as "unsupported" to none of them.++It is published on its own as `@three-ws/retarget`.++## 5. The models underneath, and the fleet that serves them++None of this is interesting without generation that works, and all of ours is open models on hardware we run:++- **TRELLIS** for native single-hop image to 3D, taking both user photos and the synthesized view our text lane produces.+- **Hunyuan3D** for high-poly image-conditioned reconstruction, poly-budget aware.+- **TripoSG** for sketch to 3D, and **TripoSR** in the family around it.+- Plus the pipeline workers: rigging, remeshing, texturing, segmentation, stylization, background removal, avatar reconstruction from a photo, text to motion, video to motion, video to scene, and sign-language synthesis.++Thirty-two workers, most published as Docker images. They run as individual GPU services (NVIDIA L4s, plus one RTX PRO 6000 Blackwell for the heaviest lane), each speaking the same task shape, each with a failover chain so an unavailable model degrades quality rather than failing the request.++Three production notes that will save someone a day:++**Decode meshopt before anything reads geometry.** Most of our avatars ship with `EXT_meshopt_compression`. Every server-side consumer that reads geometry (ours are Python and use trimesh) must decode first, and the failure is confusing because the file loads perfectly in every browser viewer you test with.++**Model end-of-life is a silent outage.** When an upstream family reached end of life on one of our free rungs, the rung answered `410`. The chain fell through correctly, but the real lesson was that a scheduled job should diff your hardcoded model ids against the live catalogues so you learn before users do.++**Never let a failover chain have an empty rung.** Two rungs in our text chain are keyless on purpose, so the bottom of the chain always exists even when every keyed provider is unset or throttled.++## 6. What we would like the community to take, argue with, or fork++- **`look_at_model` is the pattern, not the product.** Render your agent's output into your agent's modality. This costs a weekend and changes what your pipeline can do.+- **The readiness spec is CC0 and we want implementations, not traffic.** If you ship assets into a simulator, tell us where the four verdicts are wrong.+- **Retargeting without an allowlist is achievable**, and the mapping table wants conventions we have not hit.+- **Publish the negative results.** We evaluated approaches that did not survive contact (including exposing our agent as a smart-home device) and published the reasoning, and every time we have done that somebody has arrived with a better argument.++Free to try, no account and no key: [three.ws/forge](https://three.ws/forge) for generation, `https://three.ws/api/mcp-studio` for the eleven-tool MCP server, and the [three-ws organization](https://huggingface.co/three-ws) here for the avatar model repo and the viewer Space.++three.ws is an NVIDIA Inception member and an IBM Business Partner; both are programme designations rather than endorsements, and neither company has reviewed this article.diff --git a/docs/huggingface.md b/docs/huggingface.mdindex 43568883a..3b82a1dcd 100644--- a/docs/huggingface.md+++ b/docs/huggingface.md@@ -52,6 +52,14 @@ Note that the files here are deliberately uncompressed. Everything three.ws servA running Space that loads the avatars above in an interactive 3D viewer, so a reader who arrives from the article can orbit a real rig without leaving Hugging Face or installing anything. The equivalent on our own domain is [the avatar inspector](./avatar-inspector.md).+## In draft++| Draft | Subject |+|---|---|+| [huggingface-agent-feedback-loop.md](./huggingface-agent-feedback-loop.md) | Closing the agentic-3D feedback loop: rendering results back into the model's own modality, a mechanical physics-readiness grade, structural glTF diffing, and retargeting with no rig allowlist |++Written to the same house rule as the two published articles: AI-focused, with no coin, exchange, or listing content anywhere in the piece.+## Publishing checklistHugging Face community articles accept Markdown, so a draft in `docs/` is the article. To take one from draft to published:diff --git a/docs/listings.md b/docs/listings.mdindex 68a82d992..3b3351934 100644--- a/docs/listings.md+++ b/docs/listings.md@@ -124,5 +124,6 @@ Subscribe via RSS to track new listings, integrations, and protocol updates.- [AWS Marketplace](/docs/aws-marketplace): the AWS listing and entitlement-issued x402 API keys- [Syndication](/docs/syndication): how announcements flow to HackerNoon and other channels+- [Publishing program, September 2026](./publishing-program-2026-09.md): the venue matrix, running order, and per-venue rules for the current writing push- [x402 protocol](/docs/x402): the payment rail behind the paid endpoints these listings distribute- [Introduction](/docs/introduction): the full technical picture of the platform being listeddiff --git a/docs/nvidia-forum-gpu-fleet-post.md b/docs/nvidia-forum-gpu-fleet-post.mdnew file mode 100644index 000000000..7aaf75ebf--- /dev/null+++ b/docs/nvidia-forum-gpu-fleet-post.md@@ -0,0 +1,85 @@+---+venue: NVIDIA Developer Forums (community showcase / Cloud & Data Center)+account: three.ws (official)+suggested_title: "Running a free text-to-3D service on L4s: cold starts, keep-warm crons, and the quota arithmetic nobody publishes"+description: "The fourth three.ws write-up for the NVIDIA developer community: how a free, keyless text-to-3D and avatar service is served from a self-hosted Cloud Run GPU fleet of L4s plus an RTX PRO 6000 Blackwell, what a FUSE-mounted weight load costs on a cold start, why min-instances is a quota decision and not a performance one, and how the NIM free tier fits into a chain that must never have an empty rung."+tags: [l4, blackwell, nim, nemotron, inception, inference, cloud]+status: draft, owner approval required before posting (external-channel gate in CLAUDE.md)+---++# Running a free text-to-3D service on L4s: cold starts, keep-warm crons, and the quota arithmetic nobody publishes++I run [three.ws](https://three.ws), an open-source platform where you type a sentence and get a textured, rigged, animated 3D character. I have written here three times before: [Nemotron in front of the text-to-3D generator](https://forums.developer.nvidia.com/t/how-nemotron-made-three-ws-text-to-3d-pipeline-usable/376445), [NIM driving a 100-language i18n pipeline](https://forums.developer.nvidia.com/t/how-three-ws-translates-a-web-app-into-100-languages-with-nvidia-nim-an-llm-powered-i18n-pipeline/377379), and a browser-tab digital human streaming Audio2Face-3D onto whatever rig the visitor brought.++This one is about the boring half that keeps the free lane free: the fleet. three.ws is an NVIDIA Inception member; that is a startup programme, not a partnership or an endorsement, and nothing below is an NVIDIA statement.++The thing I want to write down is the arithmetic, because every other "we run open models in production" post I read skipped it, and the arithmetic is where the design lives.++## The fleet++Every generation lane runs as its own Cloud Run service on an **NVIDIA L4** in `us-central1`, plus one **RTX PRO 6000 Blackwell** for the heaviest work. They all speak one task shape (`POST /<endpoint>` returns a task id, `GET /tasks/:id` returns status and result) and share one bearer secret, which means the router does not care which model is behind a lane.++The lanes, and what each is for:++- **TRELLIS** (`model-trellis`): native single-hop image to 3D. Accepts a user's photo, and also the synthesized view that the text lane produces. Textured GLB out.+- **Hunyuan3D** (`model-hunyuan3d`): high-poly image-conditioned reconstruction, poly-budget aware.+- **TripoSG** (`model-triposg`): sketch to 3D. A drawing plus a prompt naming it, untextured geometry out.+- **TripoSR**, plus the mesh pipeline around all of them: rigging, remeshing, texturing, segmentation, stylization, background removal, garment generation, avatar reconstruction from photos, text to motion, video to motion, video to scene, and sign-language synthesis.++Thirty-two workers in total, most of them Docker images you can build and run yourself. The point of self-hosting was never cost alone: it is that a lane we host is a lane we can debug, and a free-tier vendor lane is a lane that changes under you.++## Cold starts are a model-load problem, not a container problem++The single most misleading metric in serverless GPU work is container start time. Ours is fine. The cost is the **weight load**, and on a FUSE-mounted weight volume a cold load can stall for minutes before the job even begins.++Three consequences that shaped the product:++**1. `min-instances` is a quota decision, not a performance one.** The obvious move is min 1 everywhere. You cannot: a regional L4 grant is small (ours is 3 in `us-central1`, with a separate grant of 3 in `us-east4`), and pinning warm instances on every lane starves the lanes that need to burst. So one lane pins an always-warm instance and bursts to three, another was moved to min 0 explicitly to free the shared pool, and the sketch lane scales to zero because its traffic is spiky and its users are patient. Those are three different answers to the same question, and the right answer is per-lane.++**2. A keep-warm cron beats a bigger floor.** A scheduled tick during peak hours holds an allowlist of scale-to-zero lanes resident, and the allowlist is an environment variable so it can change without a deploy. One detail worth stealing: **a lane id in that override that matches no known lane is reported back and fails the tick**, rather than quietly warming nothing. A typo in a keep-warm config is otherwise invisible until somebody complains about latency two weeks later.++**3. Surface the cold start honestly.** When a lane is cold, the user is told a real thing (the model is loading) with a real estimate, not a fake progress bar that fills at a constant rate regardless of what is happening. Our text-to-3D path goes through an intermediate image, so we can also show the concept art the geometry model is about to sculpt. Showing something true makes the wait feel shorter than animating something false.++## Quota starvation looks exactly like a bug++Worth naming because it cost us a debugging session. When the regional L4 pool is exhausted, requests do not fail in a way that says "quota". They fail slowly, in a pattern that reads like a model problem or a network problem. We now have a named signature for it in our triage runbook, and the first check on any "generation is slow" report is the pool, not the model.++The corollary, and this is the operational rule I would give anyone building on a granted GPU pool: **file the quota increase the moment you hit the ceiling, then route around it in the same hour.** Lower a min-instance somewhere else, use the other region's grant, queue behind existing capacity. Parking the feature on the quota request is how a two-day problem becomes a two-week one.++## Failover per lane, and the rung that must never be empty++Every generation lane has a failover chain, so an unavailable model degrades quality rather than failing the request. The same discipline runs on the text side, and that chain is the one where NIM sits.++The text chain tries free rungs first, in order, and only touches a paid key as a last resort. NVIDIA NIM is one of the free rungs (Nemotron, on the free developer tier). Two hard-won notes for anyone building a similar chain:++**Model end-of-life is a silent outage.** When a family we depended on reached end of life on NIM, the rung answered `410`. Our chain fell through correctly, but the deeper lesson was that a chain is only as good as its awareness of upstream catalogue changes, so a scheduled job now diffs our hardcoded model ids against the live catalogues and tells us before users do.++**Reasoning models need an explicit flag.** The Nemotron rung is a reasoning family, so it sends `enable_thinking: false` to keep the answer in `content` rather than in a reasoning field the caller does not read. A chain that treats every provider as interchangeable will produce empty answers on exactly the rungs that are working.++**Never let the chain be empty.** Two rungs in ours are keyless on purpose, so there is always something at the bottom. A failover chain whose last rung requires a key that might be unset is a chain with a hole in it.++## What "free and keyless" actually costs++The free 3D lane needs no account, no key, and no payment. That is a product decision with an infrastructure bill behind it, and the bill is manageable for three specific reasons:++1. **Scale to zero where the traffic is spiky**, and pay standing GPU-hours only where a cold load would be visibly bad.+2. **Self-host the lanes we can**, so the marginal generation costs compute rather than vendor margin.+3. **Grade before you spend.** Two of our free endpoints exist to *avoid* GPU work: a physics-readiness grade that tells a caller whether an asset is usable before they invest in it, and a vision tool that lets an agent look at what it generated and decide whether to iterate. A check that costs money is a check nobody runs, and a caller who cannot evaluate a result will re-generate blindly, which costs everyone more.++## Try it, and check the claims++Free, keyless, no account:++```bash+# text to a textured GLB+curl -s -X POST https://three.ws/api/3d/studio \+ -H 'content-type: application/json' \+ -d '{"prompt":"a small ceramic robot figurine"}'++# is the result usable as a rigid body?+curl "https://three.ws/api/sim-readiness?src=<glb url>"+```++The workers, the routing, the keep-warm cron, and the failover chains are all in the open repository at [github.com/nirholas/three.ws](https://github.com/nirholas/three.ws) (Apache-2.0), and `GET https://three.ws/api/version` returns the exact commit production is running, so anything above can be checked against the code that serves it.++If you run generation lanes on granted GPU capacity, I would like to compare notes on two things: how you decide which lanes deserve a warm floor, and whether anyone has found a better answer to cold weight loads than "pay for a floor and be honest about the wait".diff --git a/docs/nvidia-visibility-map.md b/docs/nvidia-visibility-map.mdindex 5d0aa6b62..324fe9f58 100644--- a/docs/nvidia-visibility-map.md+++ b/docs/nvidia-visibility-map.md@@ -231,6 +231,13 @@ Latencies in it were measured against the live endpoint the day it was written,not estimated. It is owner-gated under the external-channel rule: paste and postwhen approved.+## Drafted, not yet posted++| Draft | Subject |+|---|---|+| [nvidia-forum-gpu-fleet-post.md](./nvidia-forum-gpu-fleet-post.md) | The production GPU fleet: cold weight loads on L4s, min-instances as a quota decision rather than a performance one, the keep-warm cron, and why a failover chain must never have an empty rung |+| [nvidia-forum-browser-digital-human.md](./nvidia-forum-browser-digital-human.md) | Audio2Face-3D streamed onto a rig the visitor generated ninety seconds earlier |+## Benefits we are entitled to and have never requestedStraight from NVIDIA's [Inception program page](https://www.nvidia.com/en-us/startups/).diff --git a/docs/publishing-program-2026-09.md b/docs/publishing-program-2026-09.mdnew file mode 100644index 000000000..19ee04e07--- /dev/null+++ b/docs/publishing-program-2026-09.md@@ -0,0 +1,103 @@+---+title: "Publishing program, September 2026"+description: "The full venue matrix for the September 2026 writing push: eleven long-form drafts and eight short-form entries across developer, cloud, AI, 3D, home-automation and crypto communities, with each venue's own rules, the angle, the status, and the one action that unblocks it."+status: index. Every draft it lists is unposted and owner-gated.+---++# Publishing program, September 2026++Eleven long-form drafts and one short-form kit, written in this repo, covering the recent feature wave (smart home, Drive, Materialize, Knock, agent vitals, simulation readiness, the vision loop, the mobile shells) and every partner and listing status.++**Nothing here is posted.** Publishing to an external channel is owner-gated (CLAUDE.md, stop-and-ask gate 2), and the drafts that reference a crypto project other than $THREE additionally need approval before they can be committed. This page is the map, the running order, and the per-venue rules that the drafts were written against.++Two rules that apply to every entry, because both have burned publishing programs before:++- **Match the venue's register, not our own.** A forum post that reads like a launch announcement gets ignored at best. Every draft here opens with a specific technical claim and a link that backs it.+- **Never post the same body twice.** Cross-posting is done with a canonical link and a rewritten opening, never a copy.++---++## Long-form drafts++| # | Venue | Draft | Angle | Length | Unblocked by |+|---|---|---|---|---|---|+| 1 | OpenAI Developer Community | [openai-community-physical-world-post.md](./openai-community-physical-world-post.md) | The follow-up to the 3D Studio connector: tools that spend money or move matter, the vision loop, the 72-server fleet problem | ~5,650 words | Owner approval |+| 2 | AWS Builder Center | [aws-builder-center-agent-commerce-spine.md](./aws-builder-center-agent-commerce-spine.md) | The authorization spine for autonomous commerce: Concurrent Agreements, budgets instead of credentials, preflight, receipts, physical fulfillment | ~4,000 words | Owner approval |+| 3 | IBM Community (Three.ws User Group) | [ibm-community-governed-agents-post.md](./ibm-community-governed-agents-post.md) | Granite Guardian as an action veto once agents touch homes, cars and manufacturing, plus the full watsonx.ai surface and a build-it-yourself walkthrough | ~4,900 words | Owner approval |+| 4 | CoinMarketCap Community | [coinmarketcap-article-2026-09-agent-economy.md](./coinmarketcap-article-2026-09-agent-economy.md) | What an agent can actually buy now, with the on-chain and payment infrastructure behind it and the honest numbers | ~4,150 words | Owner approval, plus the other-coin commit gate |+| 5 | Home Assistant Community | [home-assistant-community-post.md](./home-assistant-community-post.md) | A HACS integration that dials out, an MCP server whose lock tools refuse over stdio, household roles enforced server-side | ~1,750 words | Owner approval |+| 6 | three.js Forum | [threejs-forum-post.md](./threejs-forum-post.md) | Five open-sourced pieces: retargeting with no rig allowlist, progressive GLB, glTF diffing, physics grade, terminal renderer | ~1,470 words | Owner approval |+| 7 | NVIDIA Developer Forums | [nvidia-forum-gpu-fleet-post.md](./nvidia-forum-gpu-fleet-post.md) | The production GPU fleet: cold weight loads, min-instances as a quota decision, keep-warm crons, chains with no empty rung | ~1,480 words | Owner approval |+| 8 | Hugging Face community article | [huggingface-agent-feedback-loop.md](./huggingface-agent-feedback-loop.md) | Closing the agentic-3D feedback loop: perceive, grade, diff, retarget, on open models | ~1,690 words | Owner approval |+| 9 | dev.to (canonical back to three.ws) | [devto-mcp-fleet-post.md](./devto-mcp-fleet-post.md) | 72 MCP servers, four traps, four rules, and the one change that mattered more than the fleet | ~1,290 words | Owner approval |+| 10 | Google Cloud Community | [google-cloud-community-post.md](./google-cloud-community-post.md) | One container, 115 scheduled jobs, a GPU fleet that sleeps, and three deploy gates each written the day after an outage | ~1,530 words | Owner approval |+| 11 | NVIDIA Developer Forums (already drafted, earlier) | [nvidia-forum-browser-digital-human.md](./nvidia-forum-browser-digital-human.md) | Audio2Face-3D streamed onto a rig the visitor generated ninety seconds ago | existing draft | Owner approval |++## Short-form entries++All in [short-form-venue-kit-2026-09.md](./short-form-venue-kit-2026-09.md), paste-ready with each venue's constraints applied:++| Venue | Entry | Constraint the copy was written against |+|---|---|---|+| Show HN | Free physics-readiness grade plus a CC0 spec | Title describes, never sells; the URL is the thing itself |+| Product Hunt | Materialize launch | 60-character tagline, ~260-character description, the maker comment carries the launch |+| r/homeassistant | The dial-out integration and the stdio refusal | Ends on a genuine open question |+| r/threejs | Pointer to the forum post, retargeting quoted in full | Community rewards the artifact, not the announcement |+| r/LocalLLaMA | Binaries an agent cannot read, and the fix | Generalised past 3D so it is useful to non-3D readers |+| r/3Dprinting | The free printability report | Leads with the free endpoint, discloses the paid lane |+| r/robotics | The four verdicts and a request for adversarial review | Asks for criticism, not clicks |+| LinkedIn | "The quarter our AI agents left the browser tab" | 900 words, no code, one link, preview-optimised opening |+| Alibaba Cloud developer community | Qwen as a first-class lane in a multi-provider router | Technical, tied to the existing marketplace listing |+| Khronos glTF discussion | Is a machine-readable simulability claim wanted at all | A discussion that accepts "no" as a useful answer |++---++## The running order++Sequencing matters because several of these link to each other, and because the venues with the slowest review should start first.++**Week 1, the ones with a review queue or a partner relationship.** AWS Builder Center (2), IBM Community (3), Hugging Face (8). Each is an account we already publish under, and each has an existing index page in this repo that must be updated with the canonical URL after publication.++**Week 1, same day as the others, the ones that are pure community goodwill.** three.js forum (6), Home Assistant (5). These are the two venues where the audience is most likely to become contributors, and neither has a queue.++**Week 2, the developer-audience posts.** OpenAI Developer Community (1), dev.to (9), NVIDIA (7), Google Cloud Community (10). Post 1 and 9 both discuss the MCP fleet, so they must not run on the same day and each needs its own opening.++**Week 2, gated separately.** CoinMarketCap (4), which needs the other-coin approval as well as the channel approval.++**Week 3, short-form.** Show HN, then Product Hunt on a Tuesday to Thursday, then the subreddits spread across separate days. Reddit is the only channel here where posting two of ours within a day looks like a campaign, which is exactly what it must not look like.++**No date pressure on the Khronos discussion.** It is a question, not a launch, and it should be opened when someone can watch the thread for a week.++---++## After each one lands++The same five steps every time, because a published article that nothing points at is half a publication:++1. **Record the canonical URL** in the venue's index page in this repo: [aws-builder-center.md](./aws-builder-center.md), [ibm-community.md](./ibm-community.md), [huggingface.md](./huggingface.md), [openai-listing-channels.md](./openai-listing-channels.md), or [listings.md](./listings.md) for a venue with no index of its own.+2. **Add the news item** to the curated feed so it becomes a page under `/news/<slug>` and enters RSS, which is also how it reaches HackerNoon (their import is automatic and needs no per-post action).+3. **Log a `data/changelog.json` entry** with the `docs` tag.+4. **Answer the thread.** Every draft here ends with a real question, and the value of these venues is in the replies rather than the post.+5. **Update the draft** if the discussion invalidates a claim. A draft that has been contradicted in public and left unedited in the repo is worse than no draft.++---++## Venues considered and not pursued yet++Written down so the next person does not re-derive it:++- **Medium as a primary venue.** Fine as a cross-post with a canonical link, weak as a destination. The former in-app push lanes for Dev.to and Medium were removed with the admin surface, so both are manual.+- **Stack Overflow.** No, in every form. Answering questions there is legitimate; publishing is not.+- **Blender Artists and the ComfyUI community.** Real fits (we ship a Blender addon and ComfyUI nodes) and both deserve their own drafts by someone who uses those tools daily. Writing a forum post about a tool you do not personally use is detectable in the first paragraph.+- **Solana ecosystem developer venues.** Worth a dedicated draft, gated behind the same other-coin approval as the CoinMarketCap piece.+- **A second CoinGecko listing update.** The existing dated notes cover it; nothing new to say until a listing state changes.+- **X threads.** Handled by the existing announcement flow, not by this program.++---++## Related++- [Syndication](./syndication.md): how the RSS feed reaches HackerNoon and any other subscriber, with no per-post action+- [Listings and distribution](./listings.md): every marketplace, directory and media partner with its per-listing status+- [Partner ecosystem](./partners.md): the eight partner programmes and the exact wording each one requires+- [Press kit](./press-kit.md): marks, boilerplate at four lengths, and the rules for bothdiff --git a/docs/short-form-venue-kit-2026-09.md b/docs/short-form-venue-kit-2026-09.mdnew file mode 100644index 000000000..8da79d5c2--- /dev/null+++ b/docs/short-form-venue-kit-2026-09.md@@ -0,0 +1,210 @@+---+title: "Short-form venue kit, September 2026"+description: "Paste-ready copy for the venues that take a paragraph rather than an article: Show HN, Product Hunt, five subreddits, LinkedIn, the Alibaba Cloud developer community, and a Khronos glTF discussion opener. Each entry carries the venue's own rules, the copy, and the first comment."+status: drafts, owner approval required before posting (external-channel gate in CLAUDE.md)+---++# Short-form venue kit, September 2026++The long-form drafts live one per file (see [publishing-program-2026-09.md](./publishing-program-2026-09.md) for the full matrix). This file holds the venues where the unit of publication is a paragraph, a title, or a first comment.++**Rules that apply to every entry here.** Post as a participant, not as a brand voice: each of these communities punishes marketing register and rewards a specific technical claim with a link that backs it. Never post the same text to two subreddits. Answer replies yourself, in your own words. If a claim is not checkable in a live endpoint or the repository, cut it.++---++## 1. Show HN++**Venue:** news.ycombinator.com, "Show HN". One submission, then you live in the comments for six hours.+**Rules that matter:** the title must describe the thing, not sell it; no superlatives; the URL should be the thing itself, not a blog post about it.++**Title (78 characters)**++```+Show HN: Free physics-readiness grade for any glTF file, and a CC0 spec for it+```++**URL**++```+https://three.ws/docs/sim-readiness+```++**First comment (post immediately after submitting)**++> A renderer forgives almost everything. A rigid-body solver forgives nothing. The same mesh that looks perfect in a viewer can sink through the floor in MuJoCo, spin like it is hollow, or turn out to be a metre tall because the generator fitted it to a unit box. Nothing in the file says so, so every robotics, game-physics and world-model pipeline rediscovers the same defects by hand, one asset at a time.+>+> This is a mechanical answer to the question a physics engine actually asks: can I use this as a rigid body right now, and if not, what exactly is wrong. Four verdicts. `simulation_ready` is the only one that licenses trusting the reported mass. `needs_scale` means the geometry is sound and only the units are missing. `needs_repair` means the surface is open, non-manifold, or inconsistently wound, so mass properties are reported but unreliable. `unusable` means no triangles or zero volume. A fifth value, `unreadable`, is for bytes that are not glTF at all, deliberately distinct from a valid file with nothing to simulate.+>+> Free and keyless, because a check that costs money is a check nobody runs:+>+> curl "https://three.ws/api/sim-readiness?src=https://three.ws/avatars/cesium-man.glb"+>+> The spec is CC0 and the grader is a pure function you can vendor. I would rather this became something other people implement than something people call. Source is Apache-2.0 at github.com/nirholas/three.ws. Context: I build a text-to-3D platform, and we needed this badly enough to write it, then realised nobody should have to write it twice.+>+> The part I would most like criticism on: the boundary between `needs_repair` and `unusable`, and whether "real-world extents" is a defensible heuristic or whether it should be a warning rather than a verdict change.++**Alternate submission, if the readiness one has already run:** `Show HN: A live 3D avatar in your terminal, as your coding agent's face` pointing at the `@three-ws/tty-avatar` README.++---++## 2. Product Hunt++**Venue:** producthunt.com. Ship Tuesday to Thursday, 00:01 PT.+**Rules that matter:** tagline maximum 60 characters, description around 260, first comment is where the launch is actually won.++**Name**++```+Materialize by three.ws+```++**Tagline (57 characters)**++```+Describe an object, get it printed and posted to your door+```++**Description (254 characters)**++```+Type a description, three.ws generates the 3D model, and Materialize prints it in resin, nylon, colour sandstone or steel and ships it. Free printability report before any price. Every step is also an API, so an AI agent can order a physical object by itself.+```++**Topics:** 3D, Artificial Intelligence, Design Tools, Developer Tools, Hardware++**Maker's first comment**++> Hi Product Hunt. I build three.ws, an open-source platform that turns a sentence into a rigged 3D character. Materialize is the part that leaves the screen.+>+> The loop: describe something, we generate it, and then it gets manufactured and posted to you. What I care about most is the order the steps happen in.+>+> **The analysis is free and comes first.** Before any price, you get a printability report: whether the mesh is a closed solid, how many separate bodies it has, where the holes are, the thinnest wall, the exact volume, and a 0 to 100 score with named deductions written for a person rather than a slicer. Free because a check that costs money is a check nobody runs.+>+> **The quote is signed and lasts 24 hours,** so the price you were shown is the price you pay.+>+> **Every print ships with proof it is the one you ordered:** a certificate of authenticity with a QR code in the box, and creators can cap how many copies of a model will ever exist.+>+> **It refuses things.** No weapons, no functional key duplicates, no third-party brand marks, screened before production. A print bureau has a human at that checkpoint. We have an API where the buyer might be a machine, so the checkpoint has to be code.+>+> That last part is the unusual bit: an AI agent can run the whole loop, quote and order included, with no human in it. As far as I know this is the first API where an agent can pay for manufacturing.+>+> Free to try the generation half with no account: three.ws/forge. Everything is Apache-2.0. Happy to answer anything, including what it costs and what it cannot print.++---++## 3. Reddit++Five subreddits, five different posts. Never cross-post the same body.++### r/homeassistant++**Title:** `Built a HACS integration that dials out over one WebSocket, so a LAN-only HA can drive a 3D assistant. The lock handling is the interesting part.`++**Body:**++> Most HA installs cannot be reached from the internet: no forwarded port, no public address. That is the default install, not an edge case. So this integration works the other way around: the house dials out over a single outgoing WebSocket and the service never dials the house. Nothing listens on your network, no port forwarding, no tunnel daemon, and the service never receives an HA token (the integration mints its own credential locally and it never leaves the house).+>+> What it connects to is a 3D agent that stands in a live model of your home and talks to you, plus an MCP server so Claude, Cursor or your own assistant can read and drive the house.+>+> The part I would like this sub to pull apart is locks. Every call that would open the house passes through one physical-action gate, and over stdio that gate **refuses outright**. My reasoning: a local stdio MCP server has no user-visible surface, no session, and no way to prove a human saw the request and approved it, so any "confirm?" it prints is a string the model can answer itself. Household roles are enforced server-side too: a guest can turn on lights and can never approve unlocking anything, and a scoped guest's other rooms are removed from the payload rather than hidden in the UI.+>+> Also: we evaluated exposing the agent as a Matter device, measured it, and decided against it for now, and published why.+>+> Repo: github.com/nirholas/three-ws-home-assistant (HACS custom repository). Docs and the relay threat model: three.ws/docs/smart-home. Apache-2.0.+>+> Is the stdio refusal right, or is it paternalistic? That is a genuine question and I have not settled it.++### r/threejs++**Title:** `Five things we open-sourced after animating characters nobody on our team modelled (retargeting with no rig allowlist, progressive GLB, glTF diffing, a physics grade, a terminal renderer)`++**Body:** short pointer to the [three.js forum post](./threejs-forum-post.md), with the retargeting section quoted in full and a request for rig conventions we have not mapped.++### r/LocalLLaMA++**Title:** `Every text-to-3D API answers with a URL to a binary the model cannot read. We fixed the loop by rendering results back into the model's own modality.`++**Body:**++> This is the smallest change we made this year and the one that changed the most.+>+> A `.glb` is opaque to a language model. So an agent that just spent GPU time generating an asset cannot tell a clean mesh from a melted one; it hands the link to a human and hopes. No error signal means no loop, which is why agentic 3D has been one-shot since it existed.+>+> The fix: render the result from several angles and return the frames as MCP image content blocks, so a multimodal model looks at what it made. Then it can judge it, refine it, and look again. Alongside the frames we return geometry facts and a plain-language reading of them.+>+> The generalisation is not about 3D at all: **any tool that hands an agent a binary needs a companion that renders it into the agent's own modality.** PDFs, spreadsheets, audio, CAD, compiled artifacts. If your agent cannot perceive its own output, it is guessing.+>+> Free and keyless if you want to try it against your own stack: `POST https://three.ws/api/3d/look`, or the tool `look_at_model` on `https://three.ws/api/mcp-studio`. Everything Apache-2.0.++### r/3Dprinting++**Title:** `We built a free printability report API (closed solid, separate bodies, thinnest wall, exact volume, 0-100 score with named deductions) and made it the step before any price is quoted`++**Body:** the analysis-first argument, the four things it measures, an honest note that the printing lane behind it is a paid service, and an invitation to tell us which deductions are wrong. Lead with the free endpoint; the sub is allergic to advertising and fine with tools.++### r/robotics++**Title:** `A generated mesh that renders perfectly can be unusable as a rigid body, and the file never says so. Free grade plus a CC0 spec.`++**Body:** the four verdicts, the `needs_scale` versus `needs_repair` distinction, the content-addressed caching, the request for adversarial review from people who have shipped assets into MuJoCo or Isaac in anger.++---++## 4. LinkedIn article++**Venue:** LinkedIn article from the founder account, not a company post.+**Audience:** partners, enterprise readers, and people evaluating the company.++**Title**++```+The quarter our AI agents left the browser tab+```++**Opening (first 210 characters are the preview, make them count)**++> For most of this year our agents lived in a browser tab, and the worst thing a wrong decision could produce was a bad sentence. This quarter they got a house, a car, and a factory, and that changed the engineering.++**Structure:** the blast-radius argument; the three capabilities (home, car, manufacturing); the governance layer that became load-bearing; the operating principle that a refusal must live on the server and not in a prompt; the honest partner and listing status list; and a close on what it takes to make an agent economy that is not a demo. Keep it to 900 words, no code blocks, one link at the end.++---++## 5. Alibaba Cloud developer community++**Venue:** the Alibaba Cloud developer community, following our existing marketplace listing and the editorial feature already published on the marketplace blog.+**Angle:** the model router. Qwen models are first-class lanes in a multi-provider brain router that any agent can be pointed at, reached through DashScope alongside the other providers, and there is a published MCP server (`@three-ws/alibaba-cloud-mcp`) exposing Qwen chat and embeddings to any MCP client.++**Working title**++```+Adding Qwen as a first-class lane in a multi-provider agent brain, and what a router owes each provider+```++**The one non-obvious point to build the piece around:** a router that treats providers as interchangeable produces empty answers on the rungs that are working, because reasoning families, tool-call shapes, and streaming conventions differ. The router's job is not to hide the provider, it is to normalise the parts that must be uniform and to report the model that actually answered, so callers can tell.++---++## 6. Khronos glTF discussion opener++**Venue:** the glTF project's public discussion tracker on GitHub (a discussion, not an issue, and not a pull request).+**Purpose:** find out whether a machine-readable physical-usability claim belongs anywhere near the ecosystem, before proposing anything formal.++**Title**++```+Discussion: is there appetite for a machine-readable "can this be simulated" claim for glTF assets?+```++**Body**++> Context, briefly: we run a text-to-3D service and every downstream consumer of our output (physics engines, game engines, robotics stacks) rediscovers the same defects by hand. A glTF file carries no claim about whether it can be used as a rigid body, so the checks get re-implemented per pipeline, inconsistently.+>+> We wrote and published one (CC0 spec, free endpoint, pure-function grader) covering four verdicts: closed surface with consistent winding and positive volume and plausible real-world extents, versus geometry that is sound but unit-scaled, versus an open or non-manifold surface whose mass properties are unreliable, versus nothing to simulate at all.+>+> I am not proposing an extension here, and I would like to understand the shape of the problem first:+>+> 1. Is this a file-level claim, a validator concern, or purely an application concern?+> 2. If it belongs anywhere in the ecosystem, is it an extension, a validator rule set, or a convention?+> 3. Is "plausible real-world extents" defensible as part of a verdict, or should unit ambiguity only ever be a warning?+>+> Happy for the answer to be "this is an application concern, keep it out of the format". That is useful too.diff --git a/docs/threejs-forum-post.md b/docs/threejs-forum-post.mdnew file mode 100644index 000000000..fb8fb957d--- /dev/null+++ b/docs/threejs-forum-post.md@@ -0,0 +1,107 @@+---+venue: three.js Forum (discourse.threejs.org), category "Resources" (cross-post the demo to "Showcase")+account: nichxbt+description: "Forum post for three.js developers: five open-source pieces pulled out of a production WebGL avatar platform, covering universal humanoid retargeting with no rig allowlist, progressive GLB streaming over plain HTTP, a terminal renderer, structural GLB diffing, and a free physics-readiness grade for glTF."+tags: [three.js, gltf, glb, animation, retargeting, webgl]+status: draft, owner approval required before posting (external-channel gate in CLAUDE.md)+---++# Five things we had to build to animate 3D characters nobody on our team modelled++_Post for the [three.js forum](https://discourse.threejs.org), category Resources._++I work on [three.ws](https://three.ws), a browser-native platform where you type a sentence and get a rigged, animated 3D character you can embed anywhere. Apache-2.0, source at [github.com/nirholas/three.ws](https://github.com/nirholas/three.ws).++The constraint that shaped everything: **we never see the model before it arrives.** It might come from our own generation lane, from Mixamo, from VRoid, from Daz, from a Blender export somebody made in 2019, or from a user's photo processed into a mesh ninety seconds ago. The rig is not ours and we do not get to pick the conventions.++Five pieces fell out of that, each published on its own so you can use them without the rest of the platform. All of them are things I looked for first and could not find.++## 1. Retargeting with no rig allowlist++**Package: `@three-ws/retarget`**++The usual approach to "animate any humanoid" is a curated list of supported rigs. It works until the eleventh rig, and every asset marketplace produces new ones faster than you can add them.++Instead we canonicalise bone names first, then retarget onto the canonical set. The mapping covers Mixamo, Avaturn, Unreal, VRM and VRoid, VRM 1.0, Daz/Genesis, MakeHuman, Blender `.L`/`.R` suffixes, and the simple `shoulderL` style rigs, and adding a new convention is one mapping entry plus a test case rather than a new code path.++Two details that took us longer than they should have:++**Legs are where naive retargeting falls apart.** Arm chains forgive a lot of proportion mismatch. Hip and foot chains do not, and the failure mode is a character that walks with its feet sliding, which readers describe as "the animation is broken" rather than "the retarget is wrong".++**The fallback must not be a T-pose.** If a model genuinely cannot be skeleton-driven (no skin, a non-humanoid prop), we detect that and fall back to a default rig rather than rendering a bind-pose statue. A T-pose in production reads as a bug to every user, and as "unsupported" to zero of them.++If you have ever hand-mapped a skeleton table, this is the package I would have wanted.++## 2. Progressive GLB over plain HTTP++**Package: `@three-ws/avatar-stream`**++A 12 MB avatar on a phone on a train is a blank canvas for eight seconds and then, suddenly, a character. Every user reads that pause as a broken page.++`avatar-stream` packs a GLB into a layered stream so the viewer shows something structurally correct early and refines it, over ordinary HTTP with no special server. It is not a replacement for compression, it composes with it. The reason we wrote our own rather than reaching for an existing progressive format is that we needed the first frame to be *correct*, not a blob: an avatar that appears with the wrong proportions and then snaps is worse than one that appears late.++## 3. A structural diff for glTF++**Package: `@three-ws/glb-diff`, live at three.ws/diff**++When a generation pipeline iterates on a mesh, "did that change anything" is asked constantly, and eyeballing two viewers side by side is a bad instrument. `glb-diff` answers structurally: node graph, meshes, primitives, materials, textures, skins, animations, and what moved between two versions.++It started as an internal debugging tool for our refine loop and turned out to be the thing I reach for most when a model looks subtly wrong. If you run any pipeline that mutates glTF (optimisation, retexturing, decimation), this is worth ten minutes.++## 4. A physics-readiness grade, and a CC0 spec for it++**Free endpoint: `GET https://three.ws/api/sim-readiness?src=<glb>` . Spec: `specs/SIM_READINESS.md`, CC0**++This is the one I would most like this forum to tear apart, because I think the gap is real and I do not think our answer is final.++A renderer forgives almost everything. A rigid-body solver forgives nothing. The same mesh that renders beautifully in three.js can sink through the floor in a physics engine, behave as if hollow, or turn out to be a metre tall because the generator fitted it to a unit box. **A GLB carries no claim about whether it can be simulated**, so every robotics, game-physics and world-model pipeline rediscovers the same defects by hand, one asset at a time.++The grade answers four things mechanically: closed surface, consistent winding, positive volume, and whether the extents are plausible real-world metres.++```bash+curl "https://three.ws/api/sim-readiness?src=https://three.ws/avatars/cesium-man.glb"+```++Four verdicts. `simulation_ready` is the only one that licenses trusting the reported mass. `needs_scale` means the geometry is sound and only the units are missing (multiply and go). `needs_repair` means open, non-manifold, or inconsistently wound, so the mass properties are reported but unreliable. `unusable` means no triangles or zero volume. There is a fifth value, `unreadable`, for bytes that are not binary glTF 2.0 at all, deliberately distinct: one is a broken file, the other is a valid file with nothing to simulate.++Results are content-addressed by the file's SHA-256, so the same bytes always get the same verdict.++It is free and keyless on purpose: a check that costs money is a check nobody runs, and a check nobody runs prevents nothing.++## 5. A terminal renderer, which sounds like a joke and is not++**Packages: `@three-ws/tty-3d` (core), `@three-ws/tty-avatar` (the CLI)**++```bash+npx @three-ws/tty-avatar 81a076b6-55ff-49a2-b007-1d88e7dce2aa+```++That draws a skinned, animated GLB in colour at 24fps in a plain terminal, no browser and no GPU. Three glyph modes: truecolor half-blocks (two colours per cell), braille (2x4 dots per cell for four times the vertical detail), and a plain luminance ramp when the output is piped.++Two reasons it is not a toy. First, it forced the animation stack to be renderer-agnostic, which caught two bugs that WebGL was hiding. Second, wire it to a coding agent's hooks and the avatar becomes that agent's face: thinking while it reads, nodding while it edits, shaking when a tool fails, bouncing when it finishes. An ambient posture in a second pane is a better progress indicator than a spinner because you read it without switching focus.++## Assorted production notes, since this forum appreciates them++**Meshopt will bite you server-side.** Most of our avatars ship with `EXT_meshopt_compression`. Anything in the pipeline that reads geometry outside a browser (our Python workers use trimesh) has to decode it first, and the failure is confusing because the file loads fine in every viewer you test with. If you run a server-side glTF pipeline, put the decode in front of everything, once, rather than per consumer.++**Release the context between scenes.** Our splat viewer held onto the GPU between scenes and the third scene load on a laptop was a slideshow. Disposing properly on unmount is table stakes advice that everyone including us learns twice.++**Wake heavy previews on view, not on load.** A grid of 3D previews that all initialise on page load will jank on any machine. Intersection-observer gating turned our marketplace grid from a stutter into a scroll.++**Soft shadows are the first thing to silently regress.** A renderer change that makes shadows hard does not throw, does not warn, and nobody notices for a week. Ours regressed across three studio pages at once. If you have a shared light rig, pin it in a test that renders and compares, not in a code review.++**52 ARKit blendshapes is the interchange currency for faces.** Not because it is elegant, but because it is what the tooling, the capture stacks and the models converge on. We map onto it and let the rig-specific weirdness live in one adapter.++## What is where++- Retargeting: `@three-ws/retarget`+- Progressive streaming: `@three-ws/avatar-stream`+- Diffing: `@three-ws/glb-diff`, and the page at [three.ws/diff](https://three.ws/diff)+- Physics readiness: [three.ws/docs/sim-readiness](https://three.ws/docs/sim-readiness), spec CC0+- Terminal rendering: `@three-ws/tty-3d`, `@three-ws/tty-avatar`+- Viewer look and feel: `@three-ws/viewer-presets` (light rigs, floor reflections, bloom, PBR presets)+- The whole platform, if you want to see them in situ: [github.com/nirholas/three.ws](https://github.com/nirholas/three.ws)++The generation side runs open model families on our own GPU fleet, and the free lane is keyless if you want to make something to test any of this against: [three.ws/forge](https://three.ws/forge).++Questions welcome, especially on 1 and 4. The retarget mapping wants more rig conventions from people who have hit ones we have not, and the readiness spec wants adversarial review from anyone who has shipped assets into a physics engine in anger.diff --git a/scripts/audit-docs.mjs b/scripts/audit-docs.mjsindex 9217debf7..622897189 100644--- a/scripts/audit-docs.mjs+++ b/scripts/audit-docs.mjs@@ -304,6 +304,14 @@ const UNPUBLISHED_DOCS = new Map([['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'],+ ['home-assistant-community-post', 'internal: forum post drafted for the Home Assistant community'],+ ['threejs-forum-post', 'internal: forum post drafted for the three.js forum'],+ ['nvidia-forum-gpu-fleet-post', 'internal: forum post drafted for the NVIDIA developer forums'],+ ['huggingface-agent-feedback-loop', 'internal: article drafted for the Hugging Face community blog'],+ ['devto-mcp-fleet-post', 'internal: article drafted for dev.to'],+ ['google-cloud-community-post', 'internal: article drafted for the Google Cloud community'],+ ['short-form-venue-kit-2026-09', 'internal: paste-ready copy for short-form external venues'],+ ['publishing-program-2026-09', 'internal: venue matrix and running order for the external writing push'],['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'],