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(ibm-community): write the Sperax integration article for the IBM user group, with rendered diagrams and a publishing kit

nirholas7d114276c7fe
diff --git a/docs/ibm-community-defi-3d-sperax-post-ibm-hosted.html b/docs/ibm-community-defi-3d-sperax-post-ibm-hosted.html
new file mode 100644
index 000000000..dee8d6333
--- /dev/null
+++ b/docs/ibm-community-defi-3d-sperax-post-ibm-hosted.html
@@ -0,0 +1,357 @@
+<p><img src="https://three.ws/ibm-sperax/ibm-sperax-featured.png" alt="HEADER IMAGE" style="max-width:100%;height:auto;border:1px solid #e0e0e0;margin:8px 0"></p>
+<hr style="border:none;border-top:1px solid #e0e0e0;margin:44px 0">
+<h2>0. An IBM employee writing about two crypto companies</h2>
+<p>I work at IBM. I am about to publish six thousand words about two crypto companies. I want to deal with that up front, because it is the first thing I would think if this turned up in my feed.</p>
+<p>IBM has thousands of Business Partners. Two of them, Sperax and three.ws, are also partners with each other, and they shipped something together that I think is the most complete piece of embodied-agent engineering I have read this year. I am not here to explain IBM&#39;s partnership strategy. That is not my job, not my call, and not something any one employee should narrate on a community blog. I am here for a much narrower reason, and it is entirely my own:</p>
+<p><strong>My job at IBM is decision management. The best real-world material on automated-decision integrity I have read in months arrived from a direction nobody in my part of the industry is looking.</strong></p>
+<p>That is the whole pitch. If you skip everything else, read section 7.</p>
+<h3>The triangle, drawn plainly</h3>
+<p>Three relationships, all real, all different, and they close around one agent:</p>
+<ul>
+<li><strong>Sperax and three.ws are partners with each other</strong>, and they built the integration this post is about.</li>
+<li><strong>Both are IBM Business Partners.</strong></li>
+<li><strong>The three.ws agent runtime runs on IBM Granite models through watsonx.ai</strong>, using your own IBM Cloud credentials.</li>
+</ul>
+<p>Split by what each side actually contributes and the shape is clean:</p>
+<ul>
+<li><strong>three.ws gives the agent a body.</strong> A rigged, animated 3D avatar you can generate from a sentence, drop into any web page with one custom element, or place in a room through a phone camera with AR. It speaks, it gestures, and its expression changes with what it is doing.</li>
+<li><strong>Sperax gives the agent a domain, and the domain is decentralized finance.</strong> An open-source AI agent workspace where an agent can swap, lend, borrow, hunt yield, and watch a position toward liquidation, across 99 built-in tool packages exposing 592 tool APIs against live protocols. Somewhere real to act, where being wrong costs money in the same block.</li>
+<li><strong>IBM Granite can be the agent&#39;s brain.</strong> The three.ws runtime is model-agnostic and runs Granite through watsonx.ai on your own credentials, so the reasoning layer is enterprise-grade and stays yours.</li>
+</ul>
+<p>Body, domain, brain. Read one at a time those are three product announcements. Read together they are the most complete end-to-end example I have seen of what an embodied enterprise agent actually costs to build, and because both partner codebases are public, this group can read every line of it, including the parts that went wrong.</p>
+<h3>Why this is worth an enterprise reader&#39;s afternoon</h3>
+<p>I want to make the argument rather than assume it, because I know what &quot;DeFi&quot; does to an enterprise audience&#39;s attention.</p>
+<p>Every hard problem in enterprise agents shows up in this domain first, in its most extreme form, because the consequences arrive in seconds instead of quarters. An agent that reads stale data, or states a mechanism confidently and wrongly, or reports an action it did not take, produces an irreversible financial loss within one block. There is no quarterly review that catches it. So the people building here have had to solve, under real pressure, the exact things the rest of us are still writing policy documents about: how you prove a number came from its source, how you record what an autonomous system did in a way nobody can quietly edit, how you make a system refuse to act until a human says yes, and how you keep an interface from projecting more confidence than its data has earned.</p>
+<p>They have not solved all of it. Section 7 is a story about them getting it badly wrong and then fixing it in public. That is exactly why it is worth reading. Most enterprise AI governance material I encounter is aspirational. This is a diff.</p>
+<h3>Being precise about who did what</h3>
+<p>One more piece of precision, because &quot;three partners&quot; can be heard as something it is not.</p>
+<p><strong>IBM did not commission, sponsor, review, endorse, or co-build the three.ws and Sperax integration.</strong> Two partner companies decided to build something, built it, and published the code. IBM&#39;s place in the triangle is real but specific: the partner relationships themselves, and the model layer the agent can run on. Nothing described in this post is an IBM product, an IBM deliverable, or an IBM endorsement. The developer tools three.ws publishes for exploring Granite are its own work. And this user group is a community space three.ws moderates on IBM&#39;s platform, not an IBM product either. I lead it, I work at IBM, and neither of those makes anything posted here an IBM release.</p>
+<p>One more, since the domain invites it: <strong>this is not financial advice and it is not a product recommendation.</strong> I picked this case study because decentralized finance is unusually hostile to a chat box, not because I am telling anyone to use it. There is no token in this post, no price, and nothing to buy.</p>
+<p>That precision is not a legal footnote. It is most of the reason the post is worth your time. This is what partner companies do on their own initiative, in the open, with the receipts left in, and you get to audit it rather than take a press release&#39;s word for it. I could not have written this article about a closed enterprise integration, and that is worth sitting with.</p>
+<h3>Why it belongs in this group</h3>
+<p>Look at what this one integration actually touches, and then ask how many production engineering write-ups you have read on any of it:</p>
+<ul>
+<li><strong>Real-time 3D as an application interface</strong>, rather than as a demo or a game. An animated character rendered inside somebody else&#39;s product, driven by that product&#39;s live state.</li>
+<li><strong>A high-stakes domain as an agent&#39;s workplace</strong>, where the state changes every few seconds, most of it is numeric, and a confidently wrong answer costs money.</li>
+<li><strong>On-chain identity for agents</strong>, so the thing on your screen is bound to something verifiable rather than to a row in a private database.</li>
+<li><strong>Machine-to-machine payment</strong>, where one program pays another per call with no human in the loop.</li>
+<li><strong>Enterprise foundation models underneath all of it</strong>, which is the part of the stack this community actually works in.</li>
+<li><strong>AR as the next surface for the same avatar</strong>, which is not part of this integration and which I will flag again at the end so nobody misreads it as shipped.</li>
+</ul>
+<p>That list is close to word for word the remit this group was founded on: spatial reasoning, generative 3D, agentic pipelines, and real-time interactive AI. This case study is the browser-panel end of that spectrum. AR is the other end, and the same avatar walks between them.</p>
+<h3>One more thing, and then the engineering</h3>
+<p>Decision management means I spend my working life on a single question: what happens when an automated decision is wrong, and who finds out. Agents with faces and voices made that question louder for me, not quieter. A chatbot that gives you a bad answer looks exactly like a chatbot giving you a good one. An agent with a <em>body</em> can look reassuring while it is wrong, and that is a genuinely new failure mode that our existing controls were not designed for.</p>
+<p>So I asked the three.ws team to walk me through how the integration works and to write it up honestly, including what broke. What follows is that walkthrough, checked against both repositories myself, with the parts I found most useful to this group kept and the parts that make the best announcement cut.</p>
+<hr style="border:none;border-top:1px solid #e0e0e0;margin:44px 0">
+<h2>1. Why decentralized finance is the hard case for an agent interface</h2>
+<p>Before any of the engineering, it is worth being specific about why this domain and not another. I did not pick it for the crypto. I picked it because it breaks the chat box in four distinct ways, and every one of them is a general lesson wearing a specific costume.</p>
+<p><strong>The state moves every block.</strong> A number the agent read twelve seconds ago may already be wrong. A support chatbot answering from a knowledge base has no equivalent problem. Here, the gap between reading and acting is a risk window, and any interface that renders a value without rendering its age is quietly lying about how much it knows.</p>
+<p><strong>It is numerically dense and unit-hostile.</strong> Amounts in the smallest indivisible unit against amounts in whole tokens. Contracts against coins. Annual percentage rate against annual percentage yield. Basis points. Prose flattens all of that: &quot;your position is healthy&quot; reads identically whether the underlying calculation used the right unit or was off by a factor of ten to the eighteenth. Section 7 is a real example of a units-shaped bug that survived into a shipped preview.</p>
+<p><strong>Actions are irreversible.</strong> No chargeback, no undo, no support ticket that reverses a confirmed transaction. This is the property that makes an agent in this domain different in kind from an agent that drafts an email. An agent that is wrong ninety-nine times out of a hundred in a text box is annoying. Here, the hundredth is permanent.</p>
+<p><strong>The mechanics are protocol-specific, and models state them confidently anyway.</strong> Two protocols can both use the word &quot;staking&quot; and compute completely different things underneath. A language model trained on the general internet will produce a fluent, plausible, wrong explanation of the specific one in front of it, and there is nothing in the sentence&#39;s texture to warn you. This is the single most important thing I took from the whole write-up, and it is why section 11 lists a maintained domain skill pack as a planned item rather than a nice-to-have.</p>
+<h3>What the agent actually does in there</h3>
+<p>For anyone who has never opened this kind of workspace, the tool catalog is the fastest orientation. Grouped roughly as the repository groups them:</p>
+<table style="border-collapse:collapse;width:100%;margin:24px 0">
+<thead>
+<tr>
+<th style="border:1px solid #e0e0e0;padding:10px 14px;text-align:left;background:#f4f4f4">Category</th>
+<th style="border:1px solid #e0e0e0;padding:10px 14px;text-align:left;background:#f4f4f4">What the agent can call</th>
+</tr>
+</thead>
+<tbody><tr>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Trading</td>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Swaps across aggregators, limit orders, route comparison</td>
+</tr>
+<tr>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Lending</td>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Supply and borrow, health factor, liquidation watch</td>
+</tr>
+<tr>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Yield</td>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Pool discovery, rate comparison, auto-compounding</td>
+</tr>
+<tr>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Analytics</td>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Total value locked, protocol revenue, chain metrics, exchange volume</td>
+</tr>
+<tr>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Portfolio</td>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Wallet tracking, profit and loss, allocation, gas history</td>
+</tr>
+<tr>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Market intelligence</td>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Funding rates, sentiment indices, large-holder alerts, fund flows</td>
+</tr>
+</tbody></table>
+<p>That is 592 callable APIs across 99 packages, and the repository ships a machine-readable index of all of them that marks <strong>which ones move funds</strong>. I want to underline that, because it is the kind of thing that only exists when someone has thought about the problem seriously. A tool catalog that distinguishes &quot;reads a number&quot; from &quot;spends your money&quot; is a governance primitive, not documentation.</p>
+<p>The same instinct shows up in the SDK&#39;s execution model, which does not let an agent act and then tell you:</p>
+<pre style="background:#f4f4f4;border-left:4px solid #0f62fe;padding:16px 20px;overflow-x:auto;font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:14px;line-height:1.6"><code class="language-typescript">// Async mode returns immediately so you can stream the agent&#39;s work.
+const { data } = await sperax.agent.runAsync({
+ prompt: &#39;Find the best USDC yield on Arbitrum and prepare a deposit&#39;,
+ maxSteps: 15,
+});
+
+for await (const event of sperax.agent.stream(data.operationId)) {
+ if (event.event === &#39;stream_chunk&#39;) process.stdout.write(event.data.content);
+}
+
+// The run pauses before acting; you decide whether it proceeds.
+await sperax.agent.approve(data.operationId);
+</code></pre>
+<p>Note the verb in the prompt: <em>prepare</em> a deposit. The run streams its reasoning, stops at the boundary where value would move, and waits for a human. Registering an agent on-chain works the same way: the API builds the calldata and never holds a key or broadcasts for you.</p>
+<h3>And this is where a body starts to earn its place</h3>
+<p>Put those four properties together and you get an interface problem that is genuinely under-served by text.</p>
+<p>A dashboard reports state. A face reports <em>change in</em> state, pre-attentively, before you have read anything. When a position&#39;s health drifts from comfortable toward dangerous, the number moving from one value to another has to be noticed, parsed, and interpreted. An expression that has been holding concern for the last ten seconds is noticed before you read a single digit.</p>
+<p>That is the actual argument for embodiment here, and it is why section 7 matters more than the rendering. The channel only helps if what it is expressing is true.</p>
+<hr style="border:none;border-top:1px solid #e0e0e0;margin:44px 0">
+<h2>2. What was actually built</h2>
+<p>The host side is <a href="https://chat.sperax.io">SperaxOS</a>. The specifications, from its own repository: 99 built-in tool packages exposing 592 tool APIs, 63 of which are reachable from any MCP client, an agent runtime on Next.js with more than 70 model providers behind it, an on-chain agent registry, an Apache-2.0 license, and self-hosting through Docker. It is a serious piece of software, which matters here, because the interesting engineering constraints in this post all come from it being somebody&#39;s real product rather than a demo harness.</p>
+<p>The integration puts the three.ws agent inside it. In the chat panel, an agent has a body. It speaks, it gestures, and its facial expression and posture shift continuously in response to what its tools are actually doing.</p>
+<p>Here is what has shipped, as of this writing:</p>
+<table style="border-collapse:collapse;width:100%;margin:24px 0">
+<thead>
+<tr>
+<th style="border:1px solid #e0e0e0;padding:10px 14px;text-align:left;background:#f4f4f4">Surface</th>
+<th style="border:1px solid #e0e0e0;padding:10px 14px;text-align:left;background:#f4f4f4">What it is</th>
+</tr>
+</thead>
+<tbody><tr>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Standalone plugin</td>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">A hosted manifest at a well-known URL plus four LLM-callable tools. Install it in the host, paste an agent ID, done.</td>
+</tr>
+<tr>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Native component</td>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">The <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">three.ws</code> npm package mounted directly in the host&#39;s own React tree, no iframe.</td>
+</tr>
+<tr>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Inline 3D in a chat message</td>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">A markdown element that renders a live, orbitable model inside a reply.</td>
+</tr>
+<tr>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Emotion and lip-sync engines</td>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Ported from three.ws into the host codebase, kept framework-agnostic so they are unit-testable.</td>
+</tr>
+<tr>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Hash-chained action ledger</td>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Ported the same direction, with the reconcile job that checks it.</td>
+</tr>
+<tr>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Three packages ported the other way</td>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Chain and token utilities, a typed tool-authoring SDK, and a market-data collector, all now running inside three.ws.</td>
+</tr>
+<tr>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">A guided 3D site tour</td>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">An eight-stop template that exports as a single script tag.</td>
+</tr>
+</tbody></table>
+<h3>The panel, running, right here</h3>
+<p>Below is the actual plugin panel three.ws serves to SperaxOS, framed live rather than
+screenshotted. Same URL the host frames, same avatar, same emotion blend. If your browser
+or this page's sanitizer blocks the frame, you get the still image underneath instead.</p>
+<div style="border:1px solid #e0e0e0;background:#f4f4f4;padding:12px">
+<iframe src="https://three.ws/sperax/iframe" title="Live three.ws avatar panel, the same one SperaxOS frames"
+ width="100%" height="480" loading="lazy" style="border:0;display:block;background:#fff"></iframe>
+</div>
+<p><em>The live three.ws avatar panel. This is the plugin's <code>ui.url</code>, not a recording.</em></p><p>The rest of this post is what I learned reading how those were built.</p>
+<hr style="border:none;border-top:1px solid #e0e0e0;margin:44px 0">
+<h2>3. The first design question is not the one you expect</h2>
+<p>I assumed the hard question was &quot;how do you render a 3D avatar inside an application you do not control.&quot; It is not. Rendering is a solved problem and the team spent very little time on it.</p>
+<p>The actual question is <strong>who owns the React tree</strong>, and it has two legitimate answers depending on the host.</p>
+<p><img src="https://three.ws/ibm-sperax/ibm-sperax-integration-paths.png" alt="FIGURE 1" style="max-width:100%;height:auto;border:1px solid #e0e0e0;margin:8px 0"></p>
+<p><em>Figure 1. The two integration paths, and what each one costs you.</em></p>
+<p><strong>Path one is for hosts that will not take your code.</strong> Most plugin ecosystems will not let a third party ship JavaScript into the main bundle, and I think they are right not to. For those hosts, three.ws ships a standalone plugin: one hosted manifest, one hosted iframe, and a handful of HTTP endpoints. Nothing to vendor, nothing for the host&#39;s security team to review, no supply chain to audit. It is live in a day.</p>
+<p><strong>Path two is for hosts that want the dependency.</strong> When a host is willing to take a package, an iframe is a downgrade. You lose shared context, you pay for a second renderer, and you cannot compose the avatar into anything the host renders itself.</p>
+<p>SperaxOS ended up in both camps at once, which is why the integration has both halves. If you are building something similar, the team&#39;s advice, which I would repeat, is: <strong>ship the manifest first, because it gets you live and it works for hosts that will never take your code. Then do the native integration, because that is the one that finds your bugs.</strong> More on that in section 5, and it is not a throwaway line.</p>
+<h3>The manifest, in full</h3>
+<p>The whole of path one is one JSON file served with CORS:</p>
+<pre style="background:#f4f4f4;border-left:4px solid #0f62fe;padding:16px 20px;overflow-x:auto;font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:14px;line-height:1.6"><code>https://three.ws/.well-known/sperax-plugin.json
+</code></pre>
+<p>Its shape:</p>
+<pre style="background:#f4f4f4;border-left:4px solid #0f62fe;padding:16px 20px;overflow-x:auto;font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:14px;line-height:1.6"><code class="language-jsonc">{
+ &quot;identifier&quot;: &quot;three-ws&quot;,
+ &quot;type&quot;: &quot;standalone&quot;,
+ &quot;ui&quot;: { &quot;url&quot;: &quot;https://three.ws/sperax/iframe/&quot;, &quot;height&quot;: 480, &quot;mode&quot;: &quot;iframe&quot; },
+ &quot;settings&quot;: {
+ &quot;type&quot;: &quot;object&quot;,
+ &quot;required&quot;: [&quot;agentId&quot;],
+ &quot;properties&quot;: { &quot;agentId&quot;: { &quot;type&quot;: &quot;string&quot;, &quot;title&quot;: &quot;Agent ID&quot; } }
+ },
+ &quot;api&quot;: [
+ { &quot;name&quot;: &quot;render_agent&quot;, &quot;url&quot;: &quot;https://three.ws/api/chat-plugin/render-agent&quot;, &quot;...&quot;: &quot;...&quot; },
+ { &quot;name&quot;: &quot;speak&quot;, &quot;url&quot;: &quot;https://three.ws/api/chat-plugin/speak&quot;, &quot;...&quot;: &quot;...&quot; },
+ { &quot;name&quot;: &quot;gesture&quot;, &quot;url&quot;: &quot;https://three.ws/api/chat-plugin/gesture&quot;, &quot;...&quot;: &quot;...&quot; },
+ { &quot;name&quot;: &quot;emote&quot;, &quot;url&quot;: &quot;https://three.ws/api/chat-plugin/emote&quot;, &quot;...&quot;: &quot;...&quot; }
+ ]
+}
+</code></pre>
+<p>Four tools, and I want to note what is <em>not</em> in that list. There is no <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">set_expression_to_happy</code>. The tools are <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">render_agent</code> to bind or swap the avatar, <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">speak</code> with an emotional valence in the range minus one to one, <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">gesture</code> for a named physical beat (wave, nod, point, shrug), and <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">emote</code> to blend a named feeling into a continuous emotional state. Only the last two touch the face, and neither of them sets it. They contribute to it. That distinction is section 6.</p>
+<p>The only required setting is a public agent ID. No API key, which is a design decision I appreciate: the plugin cannot leak a credential it never asks for.</p>
+<hr style="border:none;border-top:1px solid #e0e0e0;margin:44px 0">
+<h2>4. Every tool call runs in two halves</h2>
+<p>This is the piece I would put on a slide if I were teaching this.</p>
+<p><img src="https://three.ws/ibm-sperax/ibm-sperax-tool-call-halves.png" alt="FIGURE 2" style="max-width:100%;height:auto;border:1px solid #e0e0e0;margin:8px 0"></p>
+<p><em>Figure 2. Both halves run on every call. The split is what keeps the model from asserting things it cannot know.</em></p>
+<p>When the model calls <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">speak</code>, two things happen in parallel. The host frames the plugin&#39;s panel and posts the call into it, and the avatar speaks. Separately, the host&#39;s plugin gateway POSTs the same arguments to the tool&#39;s HTTP endpoint, and that endpoint returns a short result the model reads back into its own context.</p>
+<p>Why bother with both? Because <strong>the model must never be the thing that asserts the avatar moved.</strong> If the model simply says &quot;I waved&quot; and the panel silently failed, the transcript now contains a false statement that the model will happily build on for the rest of the conversation. Splitting the halves means the model receives a result saying the wave was dispatched, and the panel is the thing that actually waved. The two can be compared.</p>
+<p>That is not a hypothetical. It is exactly the bug they shipped first, and the fix is my favorite twenty lines in either repository:</p>
+<pre style="background:#f4f4f4;border-left:4px solid #0f62fe;padding:16px 20px;overflow-x:auto;font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:14px;line-height:1.6"><code class="language-js">async function resolveAgent(agentId) {
+ if (!isUuid(agentId)) return { known: true, name: null };
+ try {
+ const [row] = await sql`
+ SELECT name FROM agent_identities
+ WHERE id = ${agentId} AND deleted_at IS NULL
+ LIMIT 1
+ `;
+ if (!row) return { known: false, name: null };
+ return { known: true, name: typeof row.name === &#39;string&#39; ? row.name : null };
+ } catch (err) {
+ console.warn(&#39;[chat-plugin] agent lookup failed, binding unverified:&#39;, err?.message);
+ return { known: true, name: null };
+ }
+}
+</code></pre>
+<p>The original version confirmed any agent ID it was handed. Someone with a typo in their settings got a model cheerfully announcing &quot;I have bound to your agent&quot; over a permanently empty panel. There is no error anywhere. The system is behaving exactly as written, and it is lying.</p>
+<p>Three behaviors in the fix are deliberate, and I would defend all three in a design review:</p>
+<ol>
+<li><strong>A well-formed ID that does not exist comes back as a real error</strong>, one the model can explain, pointing the user back to their dashboard to recopy it.</li>
+<li><strong>A handle or manifest ID passes through unverified</strong>, because the browser element resolves those and the server has no business pretending it checked something it did not.</li>
+<li><strong>A database outage degrades to an unverified binding instead of a 500.</strong> An infrastructure problem on one side must never take down the other side&#39;s chat panel.</li>
+</ol>
+<p>That third one is the decision-management instinct showing, and I was glad to see it in someone else&#39;s code. The failure mode of a dependency should be proportional to what the dependency actually does. A name lookup being unavailable is not a reason to break a conversation.</p>
+<p>One small practical note that will save somebody an afternoon: hosts rename the settings header. LobeChat sends <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">lobe-chat-plugin-settings</code> and SperaxOS sends <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">Sperax-Plugin-Settings</code>. Read both.</p>
+<hr style="border:none;border-top:1px solid #e0e0e0;margin:44px 0">
+<h2>5. The native path is where the real bugs live</h2>
+<p>Path two is a dependency and a mount:</p>
+<pre style="background:#f4f4f4;border-left:4px solid #0f62fe;padding:16px 20px;overflow-x:auto;font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:14px;line-height:1.6"><code class="language-tsx">// three.ws registers &lt;agent-3d&gt; via customElements.define(...)
+useEffect(() =&gt; {
+ if (typeof window !== &#39;undefined&#39; &amp;&amp; !window.VIEWER) window.VIEWER = {};
+ import(&#39;three.ws&#39;).then(() =&gt; {
+ customElements.whenDefined(&#39;agent-3d&#39;).then(() =&gt; setRegistered(true));
+ });
+}, []);
+</code></pre>
+<p>Six lines, two scars, and both are worth your time even if you never touch 3D.</p>
+<p><strong>The dynamic import is not a style choice.</strong> The package shipped <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">sideEffects: false</code> in its manifest. For a package whose entire job is a <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">customElements.define</code> side effect, that field is simply false, and a production bundler believed it: the registration was tree-shaken away and the element silently never upgraded. Not an error, not a warning, just an element that stays inert. The host now carries a patch for the flag <em>and</em> imports dynamically, because dynamic imports are never tree-shaken. <strong>If you publish a custom element, go check that field right now.</strong></p>
+<p><strong>The <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">window.VIEWER</code> seed is the other one.</strong> The library assigned to <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">window.VIEWER.json</code> during model boot without ever initializing the global. In three.ws&#39;s own pages the global happened to exist. In someone else&#39;s application it did not, and boot threw a <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">TypeError</code>.</p>
+<p>Neither of those is findable from inside your own product. That is the whole argument for doing the native integration even after the iframe works: the iframe protects you from the host, and it also protects you from learning what your package does in a world you did not build.</p>
+<p>Once the component is native, it composes in ways the iframe cannot. The host added a markdown plugin so a chat message can contain a live model:</p>
+<pre style="background:#f4f4f4;border-left:4px solid #0f62fe;padding:16px 20px;overflow-x:auto;font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:14px;line-height:1.6"><code class="language-html">&lt;avatar3d url=&quot;https://.../model.glb&quot; size=&quot;260&quot; clip=&quot;Wave&quot; zoom=&quot;true&quot; /&gt;
+</code></pre>
+<p>That renders in the same React tree, no iframe, no sandbox, and the model can come from anywhere. An agent answering &quot;what does this thing look like&quot; can now answer with the thing.</p>
+<p>There is also a client lane in the tool router, which I had not thought about before reading this. Animation control cannot round-trip through a server without the animation being late, so a dispatcher intercepts the calls that belong to the browser before the rest go server-side:</p>
+<pre style="background:#f4f4f4;border-left:4px solid #0f62fe;padding:16px 20px;overflow-x:auto;font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:14px;line-height:1.6"><code class="language-ts">const CLIENT_TOOL_IDS = new Set([&#39;agent-3d-controls&#39;, &#39;get-available-animations&#39;]);
+
+for (const tool_call of params.tool_calls) {
+ if (CLIENT_TOOL_IDS.has(tool_call.function.name)) params.onClientToolCall(tool_call);
+ else serverToolCalls.push(tool_call);
+}
+</code></pre>
+<p>Obvious once you see it. Worth stealing if your agent controls anything with a frame rate.</p>
+<hr style="border:none;border-top:1px solid #e0e0e0;margin:44px 0">
+<h2>6. Emotion as a continuous blend, not a state machine</h2>
+<p>Here is the part I expected to find cosmetic and did not.</p>
+<p>The obvious way to build an expressive avatar is a state machine: happy, sad, thinking, alarmed. It takes about thirty seconds of real use to see why that is wrong. The avatar snaps between moods, and the snap reads as a cartoon. Worse, for a monitoring interface, a state machine has to <em>choose</em>, and the truth is usually a mixture.</p>
+<p>The approach both teams now share is a continuous weighted blend. Each emotion is a float between zero and one. Events spike it. It then decays exponentially, at its own rate, every frame. All active emotions are blended into facial morph targets and body language on every frame, so a face can be forty percent concerned, thirty percent curious, and thirty percent neutral at the same time, which is how faces actually work.</p>
+<p><img src="https://three.ws/ibm-sperax/ibm-sperax-empathy-decay.png" alt="FIGURE 3" style="max-width:100%;height:auto;border:1px solid #e0e0e0;margin:8px 0"></p>
+<p><em>Figure 3. The five decay curves. Each dot marks where a full spike has fallen to the floor value and the emotion is treated as inactive.</em></p>
+<p>The ported definition table doubles as the design document, and the comments are the original author&#39;s:</p>
+<pre style="background:#f4f4f4;border-left:4px solid #0f62fe;padding:16px 20px;overflow-x:auto;font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:14px;line-height:1.6"><code class="language-ts">export const EMOTION_DEFINITIONS: Record&lt;EmotionName, EmotionDef&gt; = {
+ // Positive sentiment or success: a warm, open smile.
+ celebration: { decaySeconds: 6, morphs: { jawOpen: 0.2, smile: 0.85 } },
+ // Negative sentiment or tool error: a worried frown with raised inner brows.
+ concern: { decaySeconds: 12, morphs: { browInnerUp: 0.6, frown: 0.55 } },
+ // Loading or processing: an inquisitive head tilt.
+ curiosity: { decaySeconds: 8, headTiltZ: 0.12 },
+ // Emotional or supportive moments: a soft, squinting, caring look.
+ empathy: { decaySeconds: 13, morphs: { browInnerUp: 0.5, eyeSquint: 0.4 } },
+ // Long-running operations: a patient backward lean.
+ patience: { decaySeconds: 20, leanX: -0.08 },
+};
+</code></pre>
+<p><strong>The decay rates carry the entire personality, and they are deliberately not uniform.</strong> Celebration is bright and brief at six seconds. Concern lingers at twelve, so a risk that appeared while you were looking away is still on the face when you look back. Patience runs twenty, so an agent waiting on a slow operation keeps <em>looking</em> like it is waiting instead of going blank. Empathy is the slowest of the soft states at thirteen, because empathy that switches off the instant a sentence ends reads as insincere, and it turns out that is true of rendered faces too.</p>
+<p>Two implementation choices are what make this maintainable rather than a pile of magic numbers:</p>
+<p><strong>Keep the engine pure.</strong> The emotion module has no 3D library and no React in it. It maps time and spikes to logical morph weights, and a separate module resolves those logical names onto whatever concrete blendshapes the loaded mesh happens to have. So the emotion model is unit-testable with no renderer, and it ported cleanly between two codebases that share no UI framework. If you take one architectural idea from this post, take this one: <strong>the interesting part of your system should not import your rendering layer.</strong></p>
+<p><strong>Compose, do not multiplex.</strong> Speech drives the mouth through an entirely separate path. A Web Audio analyser samples the speech waveform each frame and maps a smoothed amplitude onto the jaw channel, gated below a noise floor so room hum does not make the avatar chew, saturating well before a full open so it never gapes:</p>
+<pre style="background:#f4f4f4;border-left:4px solid #0f62fe;padding:16px 20px;overflow-x:auto;font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:14px;line-height:1.6"><code class="language-ts">const NOISE_GATE = 0.02;
+const FULL_OPEN_RMS = 0.22;
+const MAX_JAW = 0.7;
+</code></pre>
+<p>Because articulation and emotion write to different logical channels and are summed, the agent can deliver bad news <em>while looking concerned about it</em>. A state machine would have to pick one.</p>
+<hr style="border:none;border-top:1px solid #e0e0e0;margin:44px 0">
+<h2>7. The part that actually matters, and it is not the rendering</h2>
+<p>Now the section I asked for, and the reason I wanted this written up at all.</p>
+<p><strong>An expressive avatar sitting on top of wrong data is not a nice interface. It is a confident liar, and it is worse than a table of numbers, because a table does not lean toward you and look reassuring.</strong></p>
+<p>They learned this the direct way, and to their credit the commit history says so in plain language.</p>
+<p>The SPA staking panel in the host application, and the chat tools behind it, were returning literals. Total SPA locked: zero. Total veSPA supply: zero. Average lockup: zero. The four-year staking rate: a hardcoded <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">22.61</code>, with a source comment that said, and I am quoting the code, &quot;from app screenshot.&quot; Because two of those were zero, the panel&#39;s own has-data check failed and it rendered dashes in every field. The agent, meanwhile, would narrate the number that had been copied off a screenshot months earlier, with a face on.</p>
+<p>The fix reads the contracts instead:</p>
+<ul>
+<li>Total locked and escrow supply now come from live <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">totalSPALocked()</code> and <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">totalSupply()</code> calls on the voting-escrow contract. At the time of the fix that was 242.66 million SPA locked against 416.78 million veSPA.</li>
+<li>The rate is derived from the rewarder contract&#39;s <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">rewardsPerWeek</code> over a trailing eight-week window, landing at 21.0 percent at maximum lock. Close to the number that had been copied, which is exactly the point: it is now sourced and auditable rather than coincidentally near-correct. The eight-week window exists because emissions funding is irregular enough that any single week is noise.</li>
+</ul>
+<p>The worse bug was in the estimator, and this is the one I would use in a decision-integrity training session. It is also section 1&#39;s fourth property in the flesh. Both call sites computed voting power with the linear <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">amount * lockSeconds / MAXTIME</code> slope that a <em>different</em> well-known vote-escrow design uses. Same word, same general idea, different math: this escrow mints one veSPA per SPA per <strong>year</strong> locked, capped at four years. Someone locking 1,000 SPA for four years was shown an estimate of roughly 1,000 veSPA and would actually have received roughly 3,984.</p>
+<p>A four-fold understatement. In a preview. Next to an avatar nodding encouragingly.</p>
+<p>It is now a shared helper backing both the dashboard panel and the chat tool preview, verified against the contract&#39;s own <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">estimateDeposit</code> at six different lock lengths, and pinned by tests so it cannot drift back.</p>
+<p>The rule that came out of it, and which I think generalizes far past this domain:</p>
+<blockquote style="border-left:4px solid #0f62fe;background:#edf5ff;margin:28px 0;padding:18px 24px;font-size:1.05em">
+<p><strong>The avatar may only express state it can prove.</strong> If a number cannot be read from its source of truth, the correct behavior is a visible unknown, not a confident face over a stale literal.</p>
+</blockquote>
+<p>I would go further, from the decision-management side. Embodiment raises the cost of being wrong, because it raises the user&#39;s trust before the data has earned it. Every project in this group that puts a face on an agent is quietly taking on that liability. It is worth deciding, on purpose and in advance, what your avatar does when it does not know.</p>
+<hr style="border:none;border-top:1px solid #e0e0e0;margin:44px 0">
+<h2>8. Failing honestly, including about other people&#39;s systems</h2>
+<p>A smaller story, same principle, opposite direction.</p>
+<p>While embedding the partner&#39;s own application in a frame, a probe fetched the target and received a <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">403</code>, so the page hid the embed and told the user the site had refused framing.</p>
+<p>The site had refused nothing. Its bot protection challenges every datacenter address, and the probe was running on one. The giveaway is that a plain top-level request, a static asset, and a path that does not exist all returned the same <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">403</code>, which has nothing to do with framing. The header being read as a framing policy belonged to the challenge page, not to the application.</p>
+<p>The probe now sends an unframed control request alongside the framed one, and only trusts a framing refusal when the control was actually served. On a challenged network it reports <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">UNKNOWN</code> and exits with a distinct code.</p>
+<p><strong>A negative result from a network you do not control is not a fact about the other system.</strong> I have watched teams write a permanent configuration change on exactly this kind of evidence. Reporting &quot;I could not tell&quot; is a feature.</p>
+<hr style="border:none;border-top:1px solid #e0e0e0;margin:44px 0">
+<h2>9. Provenance, for a body that can move money</h2>
+<p>Once an embodied agent can execute rather than only explain, expressiveness stops being the interesting problem and provenance starts.</p>
+<p>three.ws had built a hash-chained ledger for its own agent activity, and the host ported the primitive: an append-only, SHA-256 hash-chained record of every value movement an agent initiates, where each entry commits its predecessor.</p>
+<pre style="background:#f4f4f4;border-left:4px solid #0f62fe;padding:16px 20px;overflow-x:auto;font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:14px;line-height:1.6"><code>entryHash = sha256( canonicalFields(entry) || prevHash )
+</code></pre>
+<p>Each user owns an independent chain. Sequence numbers are per-user and monotonic from one, the first entry commits a genesis hash of sixty-four zeros, and the canonical serialization is a fixed field order with free-text detail folded in through a key-sorted stringify, so identical payloads always hash identically.</p>
+<p>The field separator is a NUL byte, and the reasoning is the sort of detail that decides whether a scheme is sound or decorative. Two of the committed fields are free text and can contain spaces. With a printable separator the encoding is ambiguous: two different field tuples could serialize to the same string, and a chain built on an ambiguous encoding proves nothing at all. A NUL cannot occur in any of the values, so the serialization is injective and the hash means what it claims.</p>
+<p>Editing or deleting any historical row breaks the chain from that point forward. A reconcile job runs on a schedule looking for two things: a chain break, and an on-chain movement that was never recorded. <strong>The second alarm is the interesting one.</strong> A value movement with no corresponding ledger entry is the signal that a key is being used outside the agent runtime, which is to say it is a breach detector wearing an accounting hat.</p>
+<p>What did <em>not</em> get ported is as deliberate as what did. The origin system&#39;s signing keys, its price oracle, and its multi-wallet funding topology all stayed behind, because the receiving system has different custody and its own valuation source. A port that drags its origin&#39;s assumptions along with it is not a port, it is a fork with extra steps.</p>
+<p>For an agent with a face, this is the other half of trustworthiness. The emotion layer makes the agent legible in the moment. The ledger makes it accountable afterward. You need both, and I would argue the second one is the part that lets a regulated organization say yes to the first.</p>
+<hr style="border:none;border-top:1px solid #e0e0e0;margin:44px 0">
+<h2>10. The code went both ways, and that is the part I would negotiate for</h2>
+<p>Here is what surprised me most, and it is a partnership observation rather than a technical one.</p>
+<p><img src="https://three.ws/ibm-sperax/ibm-sperax-code-exchange.png" alt="FIGURE 4" style="max-width:100%;height:auto;border:1px solid #e0e0e0;margin:8px 0"></p>
+<p><em>Figure 4. What moved which way. The right-hand column is the half nobody writes a press release about.</em></p>
+<p><strong>Into the host from three.ws:</strong> the emotion engine, the lip-sync driver, the inline 3D markdown element, the client-side tool dispatcher, and the hash-chained ledger with its reconcile job.</p>
+<p><strong>Into three.ws from the host:</strong></p>
+<ul>
+<li>A zero-dependency single source of truth for chain and token constants, minimal contract interface fragments, and address and amount validation. The existing maps were kept verbatim and a section was added for a chain the origin did not cover.</li>
+<li>A typed tool-authoring layer, derived from the host&#39;s plugin SDK. One call declares a tool&#39;s identity, its schemas, and its permission manifest, and derives the machine-readable schema automatically. A second call wires a typed implementation onto it and routes every invocation through a single entry point that validates parameters, enforces the declared rate limit, and normalizes both success and failure into one shape. A third adapts the result into the exact registration shape the receiving project&#39;s MCP servers already use, so adopting it is one call instead of a rewrite. It was rewritten from TypeScript into plain ESM with JSDoc to match the receiving codebase&#39;s conventions, and re-scoped away from chat-interface concepts it no longer needed.</li>
+<li>A market-data collector, since hardened considerably: per-topic subscription acknowledgements on one exchange whose retired topic used to fail silently, a unit conversion on another whose raw size field counts contracts rather than units, a geographic restriction probe on a third, and per-lane health reporting. It runs as a standalone always-on service because it holds long-lived WebSockets, and the proxy in front of it returns a 503 when the collector is unreachable rather than inventing numbers, which is the same principle as section 7 wearing different clothes.</li>
+</ul>
+<p>If you are ever in the room where an integration is being negotiated, <strong>this is the clause to push for: a shared right to port implementation between the two codebases.</strong> Two teams working on adjacent problems produce more reusable primitives than either will build alone, and a partnership you can measure in merged commits ages a great deal better than one you can only measure in announcements.</p>
+<hr style="border:none;border-top:1px solid #e0e0e0;margin:44px 0">
+<h2>11. What is planned, stated as plans and not as shipping claims</h2>
+<p>I asked for this list explicitly and I am labeling it clearly, because I do not want anything here read as available today.</p>
+<p>Shipped and live: everything in the table in section 2.</p>
+<p>Designed, in progress, or proposed:</p>
+<ol>
+<li><strong>Compute endowments.</strong> USDs, the Sperax stablecoin, pays yield to whoever holds it, automatically, with no staking step: the balance grows in the wallet. The idea is that you deposit once and that yield stream funds an agent&#39;s compute balance indefinitely, so the agent never runs out of inference budget. Set the domain aside for a second and look at the shape of it: it is a real answer to &quot;who pays for this agent&#39;s inference in year three,&quot; and it needs no new financial mechanism, only new plumbing between an existing yield stream and an existing credit ledger. I find that the most interesting idea on the list, as an agent-economics question, independent of the asset involved.</li>
+<li><strong>A recurring credit grant keyed to holdings</strong> rather than a one-time claim, so the relationship is retention rather than a giveaway.</li>
+<li><strong>A second settlement asset</strong> on the machine-to-machine payment rails that already handle per-call settlement over the x402 HTTP payment scheme.</li>
+<li><strong>A domain skill pack</strong>, so an agent reasons about the specific protocol mechanics from a maintained source rather than approximating them from training data. The voting-power bug in section 7 is precisely the failure a real skill pack prevents, which is why I think this one matters more than it sounds.</li>
+<li><strong>The guided site tour deployed on the live partner site.</strong> The template exists and exports as a single script tag. A builder preview can only prove the mechanics, so the real test is the deployment.</li>
+</ol>
+<hr style="border:none;border-top:1px solid #e0e0e0;margin:44px 0">
+<h2>12. What I would like from this group</h2>
+<p>A few things, and then the links.</p>
+<p><strong>If you have embedded an agent into somebody else&#39;s application, tell us which path you took.</strong> Section 3 is the fork in the road, and I would like the group&#39;s collective experience on it. My suspicion is that most people reach for the iframe and never do the native version, and therefore never find their equivalent of the <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">sideEffects</code> bug.</p>
+<p><strong>If you publish a web component, go and check your <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">sideEffects</code> field.</strong> That is the single most immediately actionable thing in this post and it takes ninety seconds.</p>
+<p><strong>If you put a face on an agent, decide now what it does when it does not know.</strong> Section 7 is my honest reason for publishing this. I would rather this group be known for building agents that are legible about their uncertainty than for building agents that are charming about it.</p>
+<p><strong>And the AR question I promised to come back to.</strong> Everything above happens in a rectangle on a screen. The same rigged avatar, the same emotion blend, the same tool calls, can also be placed in a room through a phone camera, and three.ws ships that surface separately. It is not part of this integration and I am not going to pretend it is. But every argument in section 7 gets sharper when the agent is standing in your kitchen instead of sitting in a panel, because the trust an embodied thing borrows from being <em>present</em> is larger again. If somebody in this group wants to be the first to put a domain-grounded agent into AR and write up what broke, I will give that post the front of the group and I will bring the questions to both teams myself.</p>
+<p>And if you want to try any of it, none of the following requires an account with anyone, and the generation step requires no key at all:</p>
+<ul>
+<li>Generate a rigged, animation-ready avatar from a sentence at <a href="https://three.ws/create">three.ws/create</a>, or a static model at <a href="https://three.ws/forge">three.ws/forge</a>.</li>
+<li>Embed it with the documented custom element at <a href="https://three.ws/docs/embedding">three.ws/docs/embedding</a>, or install the package if you want it natively in a React tree.</li>
+<li>Read <a href="https://three.ws/.well-known/sperax-plugin.json">the plugin manifest itself</a>. It is the shortest complete description of the four-tool interface, and the pattern transfers to any host of the same lineage.</li>
+<li>The integration write-up from the three.ws side is at <a href="https://three.ws/sperax">three.ws/sperax</a>, and the host application is Apache-2.0 at <a href="https://github.com/nirholas/sperax">github.com/nirholas/sperax</a> if you want to read the receiving half.</li>
+</ul>
+<p>Back to the third corner of the triangle, with one practical note. The agent brain is provider-agnostic on both sides of this integration, so pointing it at IBM Granite through watsonx.ai changes nothing about the rest. The emotion engine in section 6 takes its spikes from tool-call outcomes and sentiment rather than from any provider&#39;s output format, and the four plugin tools are plain HTTP. Your model choice is genuinely orthogonal to the body, which is the property that makes the whole stack swappable. If you are wiring an embodied agent to Granite and you hit something ugly, post it here. That is what the group is for.</p>
+<p>I will bring the harder questions from this thread back to the three.ws team, the same way I did for the meetup Q&amp;A. The skeptical ones are still the most useful ones.</p>
diff --git a/docs/ibm-community-defi-3d-sperax-post-ibm.html b/docs/ibm-community-defi-3d-sperax-post-ibm.html
new file mode 100644
index 000000000..793a0e0d8
--- /dev/null
+++ b/docs/ibm-community-defi-3d-sperax-post-ibm.html
@@ -0,0 +1,349 @@
+<p style="border:2px dashed #0f62fe;background:#edf5ff;padding:14px 18px;text-align:center;font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:14px;color:#0f62fe">HEADER IMAGE: click here, use the toolbar image button to upload <strong>ibm-sperax-featured.png</strong>, then delete this line.</p>
+<hr style="border:none;border-top:1px solid #e0e0e0;margin:44px 0">
+<h2>0. An IBM employee writing about two crypto companies</h2>
+<p>I work at IBM. I am about to publish six thousand words about two crypto companies. I want to deal with that up front, because it is the first thing I would think if this turned up in my feed.</p>
+<p>IBM has thousands of Business Partners. Two of them, Sperax and three.ws, are also partners with each other, and they shipped something together that I think is the most complete piece of embodied-agent engineering I have read this year. I am not here to explain IBM&#39;s partnership strategy. That is not my job, not my call, and not something any one employee should narrate on a community blog. I am here for a much narrower reason, and it is entirely my own:</p>
+<p><strong>My job at IBM is decision management. The best real-world material on automated-decision integrity I have read in months arrived from a direction nobody in my part of the industry is looking.</strong></p>
+<p>That is the whole pitch. If you skip everything else, read section 7.</p>
+<h3>The triangle, drawn plainly</h3>
+<p>Three relationships, all real, all different, and they close around one agent:</p>
+<ul>
+<li><strong>Sperax and three.ws are partners with each other</strong>, and they built the integration this post is about.</li>
+<li><strong>Both are IBM Business Partners.</strong></li>
+<li><strong>The three.ws agent runtime runs on IBM Granite models through watsonx.ai</strong>, using your own IBM Cloud credentials.</li>
+</ul>
+<p>Split by what each side actually contributes and the shape is clean:</p>
+<ul>
+<li><strong>three.ws gives the agent a body.</strong> A rigged, animated 3D avatar you can generate from a sentence, drop into any web page with one custom element, or place in a room through a phone camera with AR. It speaks, it gestures, and its expression changes with what it is doing.</li>
+<li><strong>Sperax gives the agent a domain, and the domain is decentralized finance.</strong> An open-source AI agent workspace where an agent can swap, lend, borrow, hunt yield, and watch a position toward liquidation, across 99 built-in tool packages exposing 592 tool APIs against live protocols. Somewhere real to act, where being wrong costs money in the same block.</li>
+<li><strong>IBM Granite can be the agent&#39;s brain.</strong> The three.ws runtime is model-agnostic and runs Granite through watsonx.ai on your own credentials, so the reasoning layer is enterprise-grade and stays yours.</li>
+</ul>
+<p>Body, domain, brain. Read one at a time those are three product announcements. Read together they are the most complete end-to-end example I have seen of what an embodied enterprise agent actually costs to build, and because both partner codebases are public, this group can read every line of it, including the parts that went wrong.</p>
+<h3>Why this is worth an enterprise reader&#39;s afternoon</h3>
+<p>I want to make the argument rather than assume it, because I know what &quot;DeFi&quot; does to an enterprise audience&#39;s attention.</p>
+<p>Every hard problem in enterprise agents shows up in this domain first, in its most extreme form, because the consequences arrive in seconds instead of quarters. An agent that reads stale data, or states a mechanism confidently and wrongly, or reports an action it did not take, produces an irreversible financial loss within one block. There is no quarterly review that catches it. So the people building here have had to solve, under real pressure, the exact things the rest of us are still writing policy documents about: how you prove a number came from its source, how you record what an autonomous system did in a way nobody can quietly edit, how you make a system refuse to act until a human says yes, and how you keep an interface from projecting more confidence than its data has earned.</p>
+<p>They have not solved all of it. Section 7 is a story about them getting it badly wrong and then fixing it in public. That is exactly why it is worth reading. Most enterprise AI governance material I encounter is aspirational. This is a diff.</p>
+<h3>Being precise about who did what</h3>
+<p>One more piece of precision, because &quot;three partners&quot; can be heard as something it is not.</p>
+<p><strong>IBM did not commission, sponsor, review, endorse, or co-build the three.ws and Sperax integration.</strong> Two partner companies decided to build something, built it, and published the code. IBM&#39;s place in the triangle is real but specific: the partner relationships themselves, and the model layer the agent can run on. Nothing described in this post is an IBM product, an IBM deliverable, or an IBM endorsement. The developer tools three.ws publishes for exploring Granite are its own work. And this user group is a community space three.ws moderates on IBM&#39;s platform, not an IBM product either. I lead it, I work at IBM, and neither of those makes anything posted here an IBM release.</p>
+<p>One more, since the domain invites it: <strong>this is not financial advice and it is not a product recommendation.</strong> I picked this case study because decentralized finance is unusually hostile to a chat box, not because I am telling anyone to use it. There is no token in this post, no price, and nothing to buy.</p>
+<p>That precision is not a legal footnote. It is most of the reason the post is worth your time. This is what partner companies do on their own initiative, in the open, with the receipts left in, and you get to audit it rather than take a press release&#39;s word for it. I could not have written this article about a closed enterprise integration, and that is worth sitting with.</p>
+<h3>Why it belongs in this group</h3>
+<p>Look at what this one integration actually touches, and then ask how many production engineering write-ups you have read on any of it:</p>
+<ul>
+<li><strong>Real-time 3D as an application interface</strong>, rather than as a demo or a game. An animated character rendered inside somebody else&#39;s product, driven by that product&#39;s live state.</li>
+<li><strong>A high-stakes domain as an agent&#39;s workplace</strong>, where the state changes every few seconds, most of it is numeric, and a confidently wrong answer costs money.</li>
+<li><strong>On-chain identity for agents</strong>, so the thing on your screen is bound to something verifiable rather than to a row in a private database.</li>
+<li><strong>Machine-to-machine payment</strong>, where one program pays another per call with no human in the loop.</li>
+<li><strong>Enterprise foundation models underneath all of it</strong>, which is the part of the stack this community actually works in.</li>
+<li><strong>AR as the next surface for the same avatar</strong>, which is not part of this integration and which I will flag again at the end so nobody misreads it as shipped.</li>
+</ul>
+<p>That list is close to word for word the remit this group was founded on: spatial reasoning, generative 3D, agentic pipelines, and real-time interactive AI. This case study is the browser-panel end of that spectrum. AR is the other end, and the same avatar walks between them.</p>
+<h3>One more thing, and then the engineering</h3>
+<p>Decision management means I spend my working life on a single question: what happens when an automated decision is wrong, and who finds out. Agents with faces and voices made that question louder for me, not quieter. A chatbot that gives you a bad answer looks exactly like a chatbot giving you a good one. An agent with a <em>body</em> can look reassuring while it is wrong, and that is a genuinely new failure mode that our existing controls were not designed for.</p>
+<p>So I asked the three.ws team to walk me through how the integration works and to write it up honestly, including what broke. What follows is that walkthrough, checked against both repositories myself, with the parts I found most useful to this group kept and the parts that make the best announcement cut.</p>
+<hr style="border:none;border-top:1px solid #e0e0e0;margin:44px 0">
+<h2>1. Why decentralized finance is the hard case for an agent interface</h2>
+<p>Before any of the engineering, it is worth being specific about why this domain and not another. I did not pick it for the crypto. I picked it because it breaks the chat box in four distinct ways, and every one of them is a general lesson wearing a specific costume.</p>
+<p><strong>The state moves every block.</strong> A number the agent read twelve seconds ago may already be wrong. A support chatbot answering from a knowledge base has no equivalent problem. Here, the gap between reading and acting is a risk window, and any interface that renders a value without rendering its age is quietly lying about how much it knows.</p>
+<p><strong>It is numerically dense and unit-hostile.</strong> Amounts in the smallest indivisible unit against amounts in whole tokens. Contracts against coins. Annual percentage rate against annual percentage yield. Basis points. Prose flattens all of that: &quot;your position is healthy&quot; reads identically whether the underlying calculation used the right unit or was off by a factor of ten to the eighteenth. Section 7 is a real example of a units-shaped bug that survived into a shipped preview.</p>
+<p><strong>Actions are irreversible.</strong> No chargeback, no undo, no support ticket that reverses a confirmed transaction. This is the property that makes an agent in this domain different in kind from an agent that drafts an email. An agent that is wrong ninety-nine times out of a hundred in a text box is annoying. Here, the hundredth is permanent.</p>
+<p><strong>The mechanics are protocol-specific, and models state them confidently anyway.</strong> Two protocols can both use the word &quot;staking&quot; and compute completely different things underneath. A language model trained on the general internet will produce a fluent, plausible, wrong explanation of the specific one in front of it, and there is nothing in the sentence&#39;s texture to warn you. This is the single most important thing I took from the whole write-up, and it is why section 11 lists a maintained domain skill pack as a planned item rather than a nice-to-have.</p>
+<h3>What the agent actually does in there</h3>
+<p>For anyone who has never opened this kind of workspace, the tool catalog is the fastest orientation. Grouped roughly as the repository groups them:</p>
+<table style="border-collapse:collapse;width:100%;margin:24px 0">
+<thead>
+<tr>
+<th style="border:1px solid #e0e0e0;padding:10px 14px;text-align:left;background:#f4f4f4">Category</th>
+<th style="border:1px solid #e0e0e0;padding:10px 14px;text-align:left;background:#f4f4f4">What the agent can call</th>
+</tr>
+</thead>
+<tbody><tr>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Trading</td>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Swaps across aggregators, limit orders, route comparison</td>
+</tr>
+<tr>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Lending</td>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Supply and borrow, health factor, liquidation watch</td>
+</tr>
+<tr>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Yield</td>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Pool discovery, rate comparison, auto-compounding</td>
+</tr>
+<tr>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Analytics</td>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Total value locked, protocol revenue, chain metrics, exchange volume</td>
+</tr>
+<tr>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Portfolio</td>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Wallet tracking, profit and loss, allocation, gas history</td>
+</tr>
+<tr>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Market intelligence</td>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Funding rates, sentiment indices, large-holder alerts, fund flows</td>
+</tr>
+</tbody></table>
+<p>That is 592 callable APIs across 99 packages, and the repository ships a machine-readable index of all of them that marks <strong>which ones move funds</strong>. I want to underline that, because it is the kind of thing that only exists when someone has thought about the problem seriously. A tool catalog that distinguishes &quot;reads a number&quot; from &quot;spends your money&quot; is a governance primitive, not documentation.</p>
+<p>The same instinct shows up in the SDK&#39;s execution model, which does not let an agent act and then tell you:</p>
+<pre style="background:#f4f4f4;border-left:4px solid #0f62fe;padding:16px 20px;overflow-x:auto;font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:14px;line-height:1.6"><code class="language-typescript">// Async mode returns immediately so you can stream the agent&#39;s work.
+const { data } = await sperax.agent.runAsync({
+ prompt: &#39;Find the best USDC yield on Arbitrum and prepare a deposit&#39;,
+ maxSteps: 15,
+});
+
+for await (const event of sperax.agent.stream(data.operationId)) {
+ if (event.event === &#39;stream_chunk&#39;) process.stdout.write(event.data.content);
+}
+
+// The run pauses before acting; you decide whether it proceeds.
+await sperax.agent.approve(data.operationId);
+</code></pre>
+<p>Note the verb in the prompt: <em>prepare</em> a deposit. The run streams its reasoning, stops at the boundary where value would move, and waits for a human. Registering an agent on-chain works the same way: the API builds the calldata and never holds a key or broadcasts for you.</p>
+<h3>And this is where a body starts to earn its place</h3>
+<p>Put those four properties together and you get an interface problem that is genuinely under-served by text.</p>
+<p>A dashboard reports state. A face reports <em>change in</em> state, pre-attentively, before you have read anything. When a position&#39;s health drifts from comfortable toward dangerous, the number moving from one value to another has to be noticed, parsed, and interpreted. An expression that has been holding concern for the last ten seconds is noticed before you read a single digit.</p>
+<p>That is the actual argument for embodiment here, and it is why section 7 matters more than the rendering. The channel only helps if what it is expressing is true.</p>
+<hr style="border:none;border-top:1px solid #e0e0e0;margin:44px 0">
+<h2>2. What was actually built</h2>
+<p>The host side is <a href="https://chat.sperax.io">SperaxOS</a>. The specifications, from its own repository: 99 built-in tool packages exposing 592 tool APIs, 63 of which are reachable from any MCP client, an agent runtime on Next.js with more than 70 model providers behind it, an on-chain agent registry, an Apache-2.0 license, and self-hosting through Docker. It is a serious piece of software, which matters here, because the interesting engineering constraints in this post all come from it being somebody&#39;s real product rather than a demo harness.</p>
+<p>The integration puts the three.ws agent inside it. In the chat panel, an agent has a body. It speaks, it gestures, and its facial expression and posture shift continuously in response to what its tools are actually doing.</p>
+<p>Here is what has shipped, as of this writing:</p>
+<table style="border-collapse:collapse;width:100%;margin:24px 0">
+<thead>
+<tr>
+<th style="border:1px solid #e0e0e0;padding:10px 14px;text-align:left;background:#f4f4f4">Surface</th>
+<th style="border:1px solid #e0e0e0;padding:10px 14px;text-align:left;background:#f4f4f4">What it is</th>
+</tr>
+</thead>
+<tbody><tr>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Standalone plugin</td>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">A hosted manifest at a well-known URL plus four LLM-callable tools. Install it in the host, paste an agent ID, done.</td>
+</tr>
+<tr>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Native component</td>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">The <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">three.ws</code> npm package mounted directly in the host&#39;s own React tree, no iframe.</td>
+</tr>
+<tr>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Inline 3D in a chat message</td>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">A markdown element that renders a live, orbitable model inside a reply.</td>
+</tr>
+<tr>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Emotion and lip-sync engines</td>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Ported from three.ws into the host codebase, kept framework-agnostic so they are unit-testable.</td>
+</tr>
+<tr>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Hash-chained action ledger</td>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Ported the same direction, with the reconcile job that checks it.</td>
+</tr>
+<tr>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Three packages ported the other way</td>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Chain and token utilities, a typed tool-authoring SDK, and a market-data collector, all now running inside three.ws.</td>
+</tr>
+<tr>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">A guided 3D site tour</td>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">An eight-stop template that exports as a single script tag.</td>
+</tr>
+</tbody></table>
+<p>The rest of this post is what I learned reading how those were built.</p>
+<hr style="border:none;border-top:1px solid #e0e0e0;margin:44px 0">
+<h2>3. The first design question is not the one you expect</h2>
+<p>I assumed the hard question was &quot;how do you render a 3D avatar inside an application you do not control.&quot; It is not. Rendering is a solved problem and the team spent very little time on it.</p>
+<p>The actual question is <strong>who owns the React tree</strong>, and it has two legitimate answers depending on the host.</p>
+<p style="border:2px dashed #0f62fe;background:#edf5ff;padding:14px 18px;text-align:center;font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:14px;color:#0f62fe">FIGURE 1: click here, use the toolbar image button to upload <strong>ibm-sperax-integration-paths.png</strong>, then delete this line.</p>
+<p><em>Figure 1. The two integration paths, and what each one costs you.</em></p>
+<p><strong>Path one is for hosts that will not take your code.</strong> Most plugin ecosystems will not let a third party ship JavaScript into the main bundle, and I think they are right not to. For those hosts, three.ws ships a standalone plugin: one hosted manifest, one hosted iframe, and a handful of HTTP endpoints. Nothing to vendor, nothing for the host&#39;s security team to review, no supply chain to audit. It is live in a day.</p>
+<p><strong>Path two is for hosts that want the dependency.</strong> When a host is willing to take a package, an iframe is a downgrade. You lose shared context, you pay for a second renderer, and you cannot compose the avatar into anything the host renders itself.</p>
+<p>SperaxOS ended up in both camps at once, which is why the integration has both halves. If you are building something similar, the team&#39;s advice, which I would repeat, is: <strong>ship the manifest first, because it gets you live and it works for hosts that will never take your code. Then do the native integration, because that is the one that finds your bugs.</strong> More on that in section 5, and it is not a throwaway line.</p>
+<h3>The manifest, in full</h3>
+<p>The whole of path one is one JSON file served with CORS:</p>
+<pre style="background:#f4f4f4;border-left:4px solid #0f62fe;padding:16px 20px;overflow-x:auto;font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:14px;line-height:1.6"><code>https://three.ws/.well-known/sperax-plugin.json
+</code></pre>
+<p>Its shape:</p>
+<pre style="background:#f4f4f4;border-left:4px solid #0f62fe;padding:16px 20px;overflow-x:auto;font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:14px;line-height:1.6"><code class="language-jsonc">{
+ &quot;identifier&quot;: &quot;three-ws&quot;,
+ &quot;type&quot;: &quot;standalone&quot;,
+ &quot;ui&quot;: { &quot;url&quot;: &quot;https://three.ws/sperax/iframe/&quot;, &quot;height&quot;: 480, &quot;mode&quot;: &quot;iframe&quot; },
+ &quot;settings&quot;: {
+ &quot;type&quot;: &quot;object&quot;,
+ &quot;required&quot;: [&quot;agentId&quot;],
+ &quot;properties&quot;: { &quot;agentId&quot;: { &quot;type&quot;: &quot;string&quot;, &quot;title&quot;: &quot;Agent ID&quot; } }
+ },
+ &quot;api&quot;: [
+ { &quot;name&quot;: &quot;render_agent&quot;, &quot;url&quot;: &quot;https://three.ws/api/chat-plugin/render-agent&quot;, &quot;...&quot;: &quot;...&quot; },
+ { &quot;name&quot;: &quot;speak&quot;, &quot;url&quot;: &quot;https://three.ws/api/chat-plugin/speak&quot;, &quot;...&quot;: &quot;...&quot; },
+ { &quot;name&quot;: &quot;gesture&quot;, &quot;url&quot;: &quot;https://three.ws/api/chat-plugin/gesture&quot;, &quot;...&quot;: &quot;...&quot; },
+ { &quot;name&quot;: &quot;emote&quot;, &quot;url&quot;: &quot;https://three.ws/api/chat-plugin/emote&quot;, &quot;...&quot;: &quot;...&quot; }
+ ]
+}
+</code></pre>
+<p>Four tools, and I want to note what is <em>not</em> in that list. There is no <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">set_expression_to_happy</code>. The tools are <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">render_agent</code> to bind or swap the avatar, <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">speak</code> with an emotional valence in the range minus one to one, <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">gesture</code> for a named physical beat (wave, nod, point, shrug), and <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">emote</code> to blend a named feeling into a continuous emotional state. Only the last two touch the face, and neither of them sets it. They contribute to it. That distinction is section 6.</p>
+<p>The only required setting is a public agent ID. No API key, which is a design decision I appreciate: the plugin cannot leak a credential it never asks for.</p>
+<hr style="border:none;border-top:1px solid #e0e0e0;margin:44px 0">
+<h2>4. Every tool call runs in two halves</h2>
+<p>This is the piece I would put on a slide if I were teaching this.</p>
+<p style="border:2px dashed #0f62fe;background:#edf5ff;padding:14px 18px;text-align:center;font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:14px;color:#0f62fe">FIGURE 2: click here, use the toolbar image button to upload <strong>ibm-sperax-tool-call-halves.png</strong>, then delete this line.</p>
+<p><em>Figure 2. Both halves run on every call. The split is what keeps the model from asserting things it cannot know.</em></p>
+<p>When the model calls <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">speak</code>, two things happen in parallel. The host frames the plugin&#39;s panel and posts the call into it, and the avatar speaks. Separately, the host&#39;s plugin gateway POSTs the same arguments to the tool&#39;s HTTP endpoint, and that endpoint returns a short result the model reads back into its own context.</p>
+<p>Why bother with both? Because <strong>the model must never be the thing that asserts the avatar moved.</strong> If the model simply says &quot;I waved&quot; and the panel silently failed, the transcript now contains a false statement that the model will happily build on for the rest of the conversation. Splitting the halves means the model receives a result saying the wave was dispatched, and the panel is the thing that actually waved. The two can be compared.</p>
+<p>That is not a hypothetical. It is exactly the bug they shipped first, and the fix is my favorite twenty lines in either repository:</p>
+<pre style="background:#f4f4f4;border-left:4px solid #0f62fe;padding:16px 20px;overflow-x:auto;font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:14px;line-height:1.6"><code class="language-js">async function resolveAgent(agentId) {
+ if (!isUuid(agentId)) return { known: true, name: null };
+ try {
+ const [row] = await sql`
+ SELECT name FROM agent_identities
+ WHERE id = ${agentId} AND deleted_at IS NULL
+ LIMIT 1
+ `;
+ if (!row) return { known: false, name: null };
+ return { known: true, name: typeof row.name === &#39;string&#39; ? row.name : null };
+ } catch (err) {
+ console.warn(&#39;[chat-plugin] agent lookup failed, binding unverified:&#39;, err?.message);
+ return { known: true, name: null };
+ }
+}
+</code></pre>
+<p>The original version confirmed any agent ID it was handed. Someone with a typo in their settings got a model cheerfully announcing &quot;I have bound to your agent&quot; over a permanently empty panel. There is no error anywhere. The system is behaving exactly as written, and it is lying.</p>
+<p>Three behaviors in the fix are deliberate, and I would defend all three in a design review:</p>
+<ol>
+<li><strong>A well-formed ID that does not exist comes back as a real error</strong>, one the model can explain, pointing the user back to their dashboard to recopy it.</li>
+<li><strong>A handle or manifest ID passes through unverified</strong>, because the browser element resolves those and the server has no business pretending it checked something it did not.</li>
+<li><strong>A database outage degrades to an unverified binding instead of a 500.</strong> An infrastructure problem on one side must never take down the other side&#39;s chat panel.</li>
+</ol>
+<p>That third one is the decision-management instinct showing, and I was glad to see it in someone else&#39;s code. The failure mode of a dependency should be proportional to what the dependency actually does. A name lookup being unavailable is not a reason to break a conversation.</p>
+<p>One small practical note that will save somebody an afternoon: hosts rename the settings header. LobeChat sends <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">lobe-chat-plugin-settings</code> and SperaxOS sends <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">Sperax-Plugin-Settings</code>. Read both.</p>
+<hr style="border:none;border-top:1px solid #e0e0e0;margin:44px 0">
+<h2>5. The native path is where the real bugs live</h2>
+<p>Path two is a dependency and a mount:</p>
+<pre style="background:#f4f4f4;border-left:4px solid #0f62fe;padding:16px 20px;overflow-x:auto;font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:14px;line-height:1.6"><code class="language-tsx">// three.ws registers &lt;agent-3d&gt; via customElements.define(...)
+useEffect(() =&gt; {
+ if (typeof window !== &#39;undefined&#39; &amp;&amp; !window.VIEWER) window.VIEWER = {};
+ import(&#39;three.ws&#39;).then(() =&gt; {
+ customElements.whenDefined(&#39;agent-3d&#39;).then(() =&gt; setRegistered(true));
+ });
+}, []);
+</code></pre>
+<p>Six lines, two scars, and both are worth your time even if you never touch 3D.</p>
+<p><strong>The dynamic import is not a style choice.</strong> The package shipped <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">sideEffects: false</code> in its manifest. For a package whose entire job is a <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">customElements.define</code> side effect, that field is simply false, and a production bundler believed it: the registration was tree-shaken away and the element silently never upgraded. Not an error, not a warning, just an element that stays inert. The host now carries a patch for the flag <em>and</em> imports dynamically, because dynamic imports are never tree-shaken. <strong>If you publish a custom element, go check that field right now.</strong></p>
+<p><strong>The <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">window.VIEWER</code> seed is the other one.</strong> The library assigned to <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">window.VIEWER.json</code> during model boot without ever initializing the global. In three.ws&#39;s own pages the global happened to exist. In someone else&#39;s application it did not, and boot threw a <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">TypeError</code>.</p>
+<p>Neither of those is findable from inside your own product. That is the whole argument for doing the native integration even after the iframe works: the iframe protects you from the host, and it also protects you from learning what your package does in a world you did not build.</p>
+<p>Once the component is native, it composes in ways the iframe cannot. The host added a markdown plugin so a chat message can contain a live model:</p>
+<pre style="background:#f4f4f4;border-left:4px solid #0f62fe;padding:16px 20px;overflow-x:auto;font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:14px;line-height:1.6"><code class="language-html">&lt;avatar3d url=&quot;https://.../model.glb&quot; size=&quot;260&quot; clip=&quot;Wave&quot; zoom=&quot;true&quot; /&gt;
+</code></pre>
+<p>That renders in the same React tree, no iframe, no sandbox, and the model can come from anywhere. An agent answering &quot;what does this thing look like&quot; can now answer with the thing.</p>
+<p>There is also a client lane in the tool router, which I had not thought about before reading this. Animation control cannot round-trip through a server without the animation being late, so a dispatcher intercepts the calls that belong to the browser before the rest go server-side:</p>
+<pre style="background:#f4f4f4;border-left:4px solid #0f62fe;padding:16px 20px;overflow-x:auto;font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:14px;line-height:1.6"><code class="language-ts">const CLIENT_TOOL_IDS = new Set([&#39;agent-3d-controls&#39;, &#39;get-available-animations&#39;]);
+
+for (const tool_call of params.tool_calls) {
+ if (CLIENT_TOOL_IDS.has(tool_call.function.name)) params.onClientToolCall(tool_call);
+ else serverToolCalls.push(tool_call);
+}
+</code></pre>
+<p>Obvious once you see it. Worth stealing if your agent controls anything with a frame rate.</p>
+<hr style="border:none;border-top:1px solid #e0e0e0;margin:44px 0">
+<h2>6. Emotion as a continuous blend, not a state machine</h2>
+<p>Here is the part I expected to find cosmetic and did not.</p>
+<p>The obvious way to build an expressive avatar is a state machine: happy, sad, thinking, alarmed. It takes about thirty seconds of real use to see why that is wrong. The avatar snaps between moods, and the snap reads as a cartoon. Worse, for a monitoring interface, a state machine has to <em>choose</em>, and the truth is usually a mixture.</p>
+<p>The approach both teams now share is a continuous weighted blend. Each emotion is a float between zero and one. Events spike it. It then decays exponentially, at its own rate, every frame. All active emotions are blended into facial morph targets and body language on every frame, so a face can be forty percent concerned, thirty percent curious, and thirty percent neutral at the same time, which is how faces actually work.</p>
+<p style="border:2px dashed #0f62fe;background:#edf5ff;padding:14px 18px;text-align:center;font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:14px;color:#0f62fe">FIGURE 3: click here, use the toolbar image button to upload <strong>ibm-sperax-empathy-decay.png</strong>, then delete this line.</p>
+<p><em>Figure 3. The five decay curves. Each dot marks where a full spike has fallen to the floor value and the emotion is treated as inactive.</em></p>
+<p>The ported definition table doubles as the design document, and the comments are the original author&#39;s:</p>
+<pre style="background:#f4f4f4;border-left:4px solid #0f62fe;padding:16px 20px;overflow-x:auto;font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:14px;line-height:1.6"><code class="language-ts">export const EMOTION_DEFINITIONS: Record&lt;EmotionName, EmotionDef&gt; = {
+ // Positive sentiment or success: a warm, open smile.
+ celebration: { decaySeconds: 6, morphs: { jawOpen: 0.2, smile: 0.85 } },
+ // Negative sentiment or tool error: a worried frown with raised inner brows.
+ concern: { decaySeconds: 12, morphs: { browInnerUp: 0.6, frown: 0.55 } },
+ // Loading or processing: an inquisitive head tilt.
+ curiosity: { decaySeconds: 8, headTiltZ: 0.12 },
+ // Emotional or supportive moments: a soft, squinting, caring look.
+ empathy: { decaySeconds: 13, morphs: { browInnerUp: 0.5, eyeSquint: 0.4 } },
+ // Long-running operations: a patient backward lean.
+ patience: { decaySeconds: 20, leanX: -0.08 },
+};
+</code></pre>
+<p><strong>The decay rates carry the entire personality, and they are deliberately not uniform.</strong> Celebration is bright and brief at six seconds. Concern lingers at twelve, so a risk that appeared while you were looking away is still on the face when you look back. Patience runs twenty, so an agent waiting on a slow operation keeps <em>looking</em> like it is waiting instead of going blank. Empathy is the slowest of the soft states at thirteen, because empathy that switches off the instant a sentence ends reads as insincere, and it turns out that is true of rendered faces too.</p>
+<p>Two implementation choices are what make this maintainable rather than a pile of magic numbers:</p>
+<p><strong>Keep the engine pure.</strong> The emotion module has no 3D library and no React in it. It maps time and spikes to logical morph weights, and a separate module resolves those logical names onto whatever concrete blendshapes the loaded mesh happens to have. So the emotion model is unit-testable with no renderer, and it ported cleanly between two codebases that share no UI framework. If you take one architectural idea from this post, take this one: <strong>the interesting part of your system should not import your rendering layer.</strong></p>
+<p><strong>Compose, do not multiplex.</strong> Speech drives the mouth through an entirely separate path. A Web Audio analyser samples the speech waveform each frame and maps a smoothed amplitude onto the jaw channel, gated below a noise floor so room hum does not make the avatar chew, saturating well before a full open so it never gapes:</p>
+<pre style="background:#f4f4f4;border-left:4px solid #0f62fe;padding:16px 20px;overflow-x:auto;font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:14px;line-height:1.6"><code class="language-ts">const NOISE_GATE = 0.02;
+const FULL_OPEN_RMS = 0.22;
+const MAX_JAW = 0.7;
+</code></pre>
+<p>Because articulation and emotion write to different logical channels and are summed, the agent can deliver bad news <em>while looking concerned about it</em>. A state machine would have to pick one.</p>
+<hr style="border:none;border-top:1px solid #e0e0e0;margin:44px 0">
+<h2>7. The part that actually matters, and it is not the rendering</h2>
+<p>Now the section I asked for, and the reason I wanted this written up at all.</p>
+<p><strong>An expressive avatar sitting on top of wrong data is not a nice interface. It is a confident liar, and it is worse than a table of numbers, because a table does not lean toward you and look reassuring.</strong></p>
+<p>They learned this the direct way, and to their credit the commit history says so in plain language.</p>
+<p>The SPA staking panel in the host application, and the chat tools behind it, were returning literals. Total SPA locked: zero. Total veSPA supply: zero. Average lockup: zero. The four-year staking rate: a hardcoded <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">22.61</code>, with a source comment that said, and I am quoting the code, &quot;from app screenshot.&quot; Because two of those were zero, the panel&#39;s own has-data check failed and it rendered dashes in every field. The agent, meanwhile, would narrate the number that had been copied off a screenshot months earlier, with a face on.</p>
+<p>The fix reads the contracts instead:</p>
+<ul>
+<li>Total locked and escrow supply now come from live <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">totalSPALocked()</code> and <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">totalSupply()</code> calls on the voting-escrow contract. At the time of the fix that was 242.66 million SPA locked against 416.78 million veSPA.</li>
+<li>The rate is derived from the rewarder contract&#39;s <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">rewardsPerWeek</code> over a trailing eight-week window, landing at 21.0 percent at maximum lock. Close to the number that had been copied, which is exactly the point: it is now sourced and auditable rather than coincidentally near-correct. The eight-week window exists because emissions funding is irregular enough that any single week is noise.</li>
+</ul>
+<p>The worse bug was in the estimator, and this is the one I would use in a decision-integrity training session. It is also section 1&#39;s fourth property in the flesh. Both call sites computed voting power with the linear <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">amount * lockSeconds / MAXTIME</code> slope that a <em>different</em> well-known vote-escrow design uses. Same word, same general idea, different math: this escrow mints one veSPA per SPA per <strong>year</strong> locked, capped at four years. Someone locking 1,000 SPA for four years was shown an estimate of roughly 1,000 veSPA and would actually have received roughly 3,984.</p>
+<p>A four-fold understatement. In a preview. Next to an avatar nodding encouragingly.</p>
+<p>It is now a shared helper backing both the dashboard panel and the chat tool preview, verified against the contract&#39;s own <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">estimateDeposit</code> at six different lock lengths, and pinned by tests so it cannot drift back.</p>
+<p>The rule that came out of it, and which I think generalizes far past this domain:</p>
+<blockquote style="border-left:4px solid #0f62fe;background:#edf5ff;margin:28px 0;padding:18px 24px;font-size:1.05em">
+<p><strong>The avatar may only express state it can prove.</strong> If a number cannot be read from its source of truth, the correct behavior is a visible unknown, not a confident face over a stale literal.</p>
+</blockquote>
+<p>I would go further, from the decision-management side. Embodiment raises the cost of being wrong, because it raises the user&#39;s trust before the data has earned it. Every project in this group that puts a face on an agent is quietly taking on that liability. It is worth deciding, on purpose and in advance, what your avatar does when it does not know.</p>
+<hr style="border:none;border-top:1px solid #e0e0e0;margin:44px 0">
+<h2>8. Failing honestly, including about other people&#39;s systems</h2>
+<p>A smaller story, same principle, opposite direction.</p>
+<p>While embedding the partner&#39;s own application in a frame, a probe fetched the target and received a <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">403</code>, so the page hid the embed and told the user the site had refused framing.</p>
+<p>The site had refused nothing. Its bot protection challenges every datacenter address, and the probe was running on one. The giveaway is that a plain top-level request, a static asset, and a path that does not exist all returned the same <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">403</code>, which has nothing to do with framing. The header being read as a framing policy belonged to the challenge page, not to the application.</p>
+<p>The probe now sends an unframed control request alongside the framed one, and only trusts a framing refusal when the control was actually served. On a challenged network it reports <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">UNKNOWN</code> and exits with a distinct code.</p>
+<p><strong>A negative result from a network you do not control is not a fact about the other system.</strong> I have watched teams write a permanent configuration change on exactly this kind of evidence. Reporting &quot;I could not tell&quot; is a feature.</p>
+<hr style="border:none;border-top:1px solid #e0e0e0;margin:44px 0">
+<h2>9. Provenance, for a body that can move money</h2>
+<p>Once an embodied agent can execute rather than only explain, expressiveness stops being the interesting problem and provenance starts.</p>
+<p>three.ws had built a hash-chained ledger for its own agent activity, and the host ported the primitive: an append-only, SHA-256 hash-chained record of every value movement an agent initiates, where each entry commits its predecessor.</p>
+<pre style="background:#f4f4f4;border-left:4px solid #0f62fe;padding:16px 20px;overflow-x:auto;font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:14px;line-height:1.6"><code>entryHash = sha256( canonicalFields(entry) || prevHash )
+</code></pre>
+<p>Each user owns an independent chain. Sequence numbers are per-user and monotonic from one, the first entry commits a genesis hash of sixty-four zeros, and the canonical serialization is a fixed field order with free-text detail folded in through a key-sorted stringify, so identical payloads always hash identically.</p>
+<p>The field separator is a NUL byte, and the reasoning is the sort of detail that decides whether a scheme is sound or decorative. Two of the committed fields are free text and can contain spaces. With a printable separator the encoding is ambiguous: two different field tuples could serialize to the same string, and a chain built on an ambiguous encoding proves nothing at all. A NUL cannot occur in any of the values, so the serialization is injective and the hash means what it claims.</p>
+<p>Editing or deleting any historical row breaks the chain from that point forward. A reconcile job runs on a schedule looking for two things: a chain break, and an on-chain movement that was never recorded. <strong>The second alarm is the interesting one.</strong> A value movement with no corresponding ledger entry is the signal that a key is being used outside the agent runtime, which is to say it is a breach detector wearing an accounting hat.</p>
+<p>What did <em>not</em> get ported is as deliberate as what did. The origin system&#39;s signing keys, its price oracle, and its multi-wallet funding topology all stayed behind, because the receiving system has different custody and its own valuation source. A port that drags its origin&#39;s assumptions along with it is not a port, it is a fork with extra steps.</p>
+<p>For an agent with a face, this is the other half of trustworthiness. The emotion layer makes the agent legible in the moment. The ledger makes it accountable afterward. You need both, and I would argue the second one is the part that lets a regulated organization say yes to the first.</p>
+<hr style="border:none;border-top:1px solid #e0e0e0;margin:44px 0">
+<h2>10. The code went both ways, and that is the part I would negotiate for</h2>
+<p>Here is what surprised me most, and it is a partnership observation rather than a technical one.</p>
+<p style="border:2px dashed #0f62fe;background:#edf5ff;padding:14px 18px;text-align:center;font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:14px;color:#0f62fe">FIGURE 4: click here, use the toolbar image button to upload <strong>ibm-sperax-code-exchange.png</strong>, then delete this line.</p>
+<p><em>Figure 4. What moved which way. The right-hand column is the half nobody writes a press release about.</em></p>
+<p><strong>Into the host from three.ws:</strong> the emotion engine, the lip-sync driver, the inline 3D markdown element, the client-side tool dispatcher, and the hash-chained ledger with its reconcile job.</p>
+<p><strong>Into three.ws from the host:</strong></p>
+<ul>
+<li>A zero-dependency single source of truth for chain and token constants, minimal contract interface fragments, and address and amount validation. The existing maps were kept verbatim and a section was added for a chain the origin did not cover.</li>
+<li>A typed tool-authoring layer, derived from the host&#39;s plugin SDK. One call declares a tool&#39;s identity, its schemas, and its permission manifest, and derives the machine-readable schema automatically. A second call wires a typed implementation onto it and routes every invocation through a single entry point that validates parameters, enforces the declared rate limit, and normalizes both success and failure into one shape. A third adapts the result into the exact registration shape the receiving project&#39;s MCP servers already use, so adopting it is one call instead of a rewrite. It was rewritten from TypeScript into plain ESM with JSDoc to match the receiving codebase&#39;s conventions, and re-scoped away from chat-interface concepts it no longer needed.</li>
+<li>A market-data collector, since hardened considerably: per-topic subscription acknowledgements on one exchange whose retired topic used to fail silently, a unit conversion on another whose raw size field counts contracts rather than units, a geographic restriction probe on a third, and per-lane health reporting. It runs as a standalone always-on service because it holds long-lived WebSockets, and the proxy in front of it returns a 503 when the collector is unreachable rather than inventing numbers, which is the same principle as section 7 wearing different clothes.</li>
+</ul>
+<p>If you are ever in the room where an integration is being negotiated, <strong>this is the clause to push for: a shared right to port implementation between the two codebases.</strong> Two teams working on adjacent problems produce more reusable primitives than either will build alone, and a partnership you can measure in merged commits ages a great deal better than one you can only measure in announcements.</p>
+<hr style="border:none;border-top:1px solid #e0e0e0;margin:44px 0">
+<h2>11. What is planned, stated as plans and not as shipping claims</h2>
+<p>I asked for this list explicitly and I am labeling it clearly, because I do not want anything here read as available today.</p>
+<p>Shipped and live: everything in the table in section 2.</p>
+<p>Designed, in progress, or proposed:</p>
+<ol>
+<li><strong>Compute endowments.</strong> USDs, the Sperax stablecoin, pays yield to whoever holds it, automatically, with no staking step: the balance grows in the wallet. The idea is that you deposit once and that yield stream funds an agent&#39;s compute balance indefinitely, so the agent never runs out of inference budget. Set the domain aside for a second and look at the shape of it: it is a real answer to &quot;who pays for this agent&#39;s inference in year three,&quot; and it needs no new financial mechanism, only new plumbing between an existing yield stream and an existing credit ledger. I find that the most interesting idea on the list, as an agent-economics question, independent of the asset involved.</li>
+<li><strong>A recurring credit grant keyed to holdings</strong> rather than a one-time claim, so the relationship is retention rather than a giveaway.</li>
+<li><strong>A second settlement asset</strong> on the machine-to-machine payment rails that already handle per-call settlement over the x402 HTTP payment scheme.</li>
+<li><strong>A domain skill pack</strong>, so an agent reasons about the specific protocol mechanics from a maintained source rather than approximating them from training data. The voting-power bug in section 7 is precisely the failure a real skill pack prevents, which is why I think this one matters more than it sounds.</li>
+<li><strong>The guided site tour deployed on the live partner site.</strong> The template exists and exports as a single script tag. A builder preview can only prove the mechanics, so the real test is the deployment.</li>
+</ol>
+<hr style="border:none;border-top:1px solid #e0e0e0;margin:44px 0">
+<h2>12. What I would like from this group</h2>
+<p>A few things, and then the links.</p>
+<p><strong>If you have embedded an agent into somebody else&#39;s application, tell us which path you took.</strong> Section 3 is the fork in the road, and I would like the group&#39;s collective experience on it. My suspicion is that most people reach for the iframe and never do the native version, and therefore never find their equivalent of the <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">sideEffects</code> bug.</p>
+<p><strong>If you publish a web component, go and check your <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">sideEffects</code> field.</strong> That is the single most immediately actionable thing in this post and it takes ninety seconds.</p>
+<p><strong>If you put a face on an agent, decide now what it does when it does not know.</strong> Section 7 is my honest reason for publishing this. I would rather this group be known for building agents that are legible about their uncertainty than for building agents that are charming about it.</p>
+<p><strong>And the AR question I promised to come back to.</strong> Everything above happens in a rectangle on a screen. The same rigged avatar, the same emotion blend, the same tool calls, can also be placed in a room through a phone camera, and three.ws ships that surface separately. It is not part of this integration and I am not going to pretend it is. But every argument in section 7 gets sharper when the agent is standing in your kitchen instead of sitting in a panel, because the trust an embodied thing borrows from being <em>present</em> is larger again. If somebody in this group wants to be the first to put a domain-grounded agent into AR and write up what broke, I will give that post the front of the group and I will bring the questions to both teams myself.</p>
+<p>And if you want to try any of it, none of the following requires an account with anyone, and the generation step requires no key at all:</p>
+<ul>
+<li>Generate a rigged, animation-ready avatar from a sentence at <a href="https://three.ws/create">three.ws/create</a>, or a static model at <a href="https://three.ws/forge">three.ws/forge</a>.</li>
+<li>Embed it with the documented custom element at <a href="https://three.ws/docs/embedding">three.ws/docs/embedding</a>, or install the package if you want it natively in a React tree.</li>
+<li>Read <a href="https://three.ws/.well-known/sperax-plugin.json">the plugin manifest itself</a>. It is the shortest complete description of the four-tool interface, and the pattern transfers to any host of the same lineage.</li>
+<li>The integration write-up from the three.ws side is at <a href="https://three.ws/sperax">three.ws/sperax</a>, and the host application is Apache-2.0 at <a href="https://github.com/nirholas/sperax">github.com/nirholas/sperax</a> if you want to read the receiving half.</li>
+</ul>
+<p>Back to the third corner of the triangle, with one practical note. The agent brain is provider-agnostic on both sides of this integration, so pointing it at IBM Granite through watsonx.ai changes nothing about the rest. The emotion engine in section 6 takes its spikes from tool-call outcomes and sentiment rather than from any provider&#39;s output format, and the four plugin tools are plain HTTP. Your model choice is genuinely orthogonal to the body, which is the property that makes the whole stack swappable. If you are wiring an embodied agent to Granite and you hit something ugly, post it here. That is what the group is for.</p>
+<p>I will bring the harder questions from this thread back to the three.ws team, the same way I did for the meetup Q&amp;A. The skeptical ones are still the most useful ones.</p>
diff --git a/docs/ibm-community-defi-3d-sperax-post.html b/docs/ibm-community-defi-3d-sperax-post.html
new file mode 100644
index 000000000..c327ded5b
--- /dev/null
+++ b/docs/ibm-community-defi-3d-sperax-post.html
@@ -0,0 +1,371 @@
+<!doctype html>
+<html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Sperax, three.ws, and IBM Granite: giving a DeFi agent a body, a brain, and a reason to trust it</title>
+<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=IBM+Plex+Sans:wght@400;600;700&display=swap" rel="stylesheet">
+<style>
+ body{ max-width:820px; margin:0 auto; padding:56px 24px 96px; background:#fff; color:#161616;
+ font-family:'IBM Plex Sans',system-ui,sans-serif; font-size:17px; line-height:1.65; }
+ h1{ font-size:40px; line-height:1.2; letter-spacing:-.01em; margin:0 0 24px; }
+ h2{ font-size:27px; margin:52px 0 16px; letter-spacing:-.01em; }
+ h3{ font-size:21px; margin:34px 0 12px; }
+ p,li{ font-size:17px; }
+ ul,ol{ padding-left:26px; }
+ li{ margin-bottom:8px; }
+ a{ color:#0f62fe; }
+ em{ color:#525252; }
+ img+p em{ display:block; margin-top:6px; font-size:15px; }
+</style></head>
+<body>
+<h1>Sperax, three.ws, and IBM Granite: giving a DeFi agent a body, a brain, and a reason to trust it</h1>
+<p><em>By Jessica Swanson. Posted in the <a href="https://community.ibm.com/community/user/groups/community-home?communitykey=e71510cc-d953-408f-9a1c-019f5c0a7016">Three.ws User Group</a> on IBM Community.</em></p>
+<p><img style="max-width:100%;height:auto;border:1px solid #e0e0e0;margin:8px 0" src="./media/ibm-sperax-featured.png" alt="Sperax, three.ws, and IBM"></p>
+<hr style="border:none;border-top:1px solid #e0e0e0;margin:44px 0">
+<h2>0. An IBM employee writing about two crypto companies</h2>
+<p>I work at IBM. I am about to publish six thousand words about two crypto companies. I want to deal with that up front, because it is the first thing I would think if this turned up in my feed.</p>
+<p>IBM has thousands of Business Partners. Two of them, Sperax and three.ws, are also partners with each other, and they shipped something together that I think is the most complete piece of embodied-agent engineering I have read this year. I am not here to explain IBM&#39;s partnership strategy. That is not my job, not my call, and not something any one employee should narrate on a community blog. I am here for a much narrower reason, and it is entirely my own:</p>
+<p><strong>My job at IBM is decision management. The best real-world material on automated-decision integrity I have read in months arrived from a direction nobody in my part of the industry is looking.</strong></p>
+<p>That is the whole pitch. If you skip everything else, read section 7.</p>
+<h3>The triangle, drawn plainly</h3>
+<p>Three relationships, all real, all different, and they close around one agent:</p>
+<ul>
+<li><strong>Sperax and three.ws are partners with each other</strong>, and they built the integration this post is about.</li>
+<li><strong>Both are IBM Business Partners.</strong></li>
+<li><strong>The three.ws agent runtime runs on IBM Granite models through watsonx.ai</strong>, using your own IBM Cloud credentials.</li>
+</ul>
+<p>Split by what each side actually contributes and the shape is clean:</p>
+<ul>
+<li><strong>three.ws gives the agent a body.</strong> A rigged, animated 3D avatar you can generate from a sentence, drop into any web page with one custom element, or place in a room through a phone camera with AR. It speaks, it gestures, and its expression changes with what it is doing.</li>
+<li><strong>Sperax gives the agent a domain, and the domain is decentralized finance.</strong> An open-source AI agent workspace where an agent can swap, lend, borrow, hunt yield, and watch a position toward liquidation, across 99 built-in tool packages exposing 592 tool APIs against live protocols. Somewhere real to act, where being wrong costs money in the same block.</li>
+<li><strong>IBM Granite can be the agent&#39;s brain.</strong> The three.ws runtime is model-agnostic and runs Granite through watsonx.ai on your own credentials, so the reasoning layer is enterprise-grade and stays yours.</li>
+</ul>
+<p>Body, domain, brain. Read one at a time those are three product announcements. Read together they are the most complete end-to-end example I have seen of what an embodied enterprise agent actually costs to build, and because both partner codebases are public, this group can read every line of it, including the parts that went wrong.</p>
+<h3>Why this is worth an enterprise reader&#39;s afternoon</h3>
+<p>I want to make the argument rather than assume it, because I know what &quot;DeFi&quot; does to an enterprise audience&#39;s attention.</p>
+<p>Every hard problem in enterprise agents shows up in this domain first, in its most extreme form, because the consequences arrive in seconds instead of quarters. An agent that reads stale data, or states a mechanism confidently and wrongly, or reports an action it did not take, produces an irreversible financial loss within one block. There is no quarterly review that catches it. So the people building here have had to solve, under real pressure, the exact things the rest of us are still writing policy documents about: how you prove a number came from its source, how you record what an autonomous system did in a way nobody can quietly edit, how you make a system refuse to act until a human says yes, and how you keep an interface from projecting more confidence than its data has earned.</p>
+<p>They have not solved all of it. Section 7 is a story about them getting it badly wrong and then fixing it in public. That is exactly why it is worth reading. Most enterprise AI governance material I encounter is aspirational. This is a diff.</p>
+<h3>Being precise about who did what</h3>
+<p>One more piece of precision, because &quot;three partners&quot; can be heard as something it is not.</p>
+<p><strong>IBM did not commission, sponsor, review, endorse, or co-build the three.ws and Sperax integration.</strong> Two partner companies decided to build something, built it, and published the code. IBM&#39;s place in the triangle is real but specific: the partner relationships themselves, and the model layer the agent can run on. Nothing described in this post is an IBM product, an IBM deliverable, or an IBM endorsement. The developer tools three.ws publishes for exploring Granite are its own work. And this user group is a community space three.ws moderates on IBM&#39;s platform, not an IBM product either. I lead it, I work at IBM, and neither of those makes anything posted here an IBM release.</p>
+<p>One more, since the domain invites it: <strong>this is not financial advice and it is not a product recommendation.</strong> I picked this case study because decentralized finance is unusually hostile to a chat box, not because I am telling anyone to use it. There is no token in this post, no price, and nothing to buy.</p>
+<p>That precision is not a legal footnote. It is most of the reason the post is worth your time. This is what partner companies do on their own initiative, in the open, with the receipts left in, and you get to audit it rather than take a press release&#39;s word for it. I could not have written this article about a closed enterprise integration, and that is worth sitting with.</p>
+<h3>Why it belongs in this group</h3>
+<p>Look at what this one integration actually touches, and then ask how many production engineering write-ups you have read on any of it:</p>
+<ul>
+<li><strong>Real-time 3D as an application interface</strong>, rather than as a demo or a game. An animated character rendered inside somebody else&#39;s product, driven by that product&#39;s live state.</li>
+<li><strong>A high-stakes domain as an agent&#39;s workplace</strong>, where the state changes every few seconds, most of it is numeric, and a confidently wrong answer costs money.</li>
+<li><strong>On-chain identity for agents</strong>, so the thing on your screen is bound to something verifiable rather than to a row in a private database.</li>
+<li><strong>Machine-to-machine payment</strong>, where one program pays another per call with no human in the loop.</li>
+<li><strong>Enterprise foundation models underneath all of it</strong>, which is the part of the stack this community actually works in.</li>
+<li><strong>AR as the next surface for the same avatar</strong>, which is not part of this integration and which I will flag again at the end so nobody misreads it as shipped.</li>
+</ul>
+<p>That list is close to word for word the remit this group was founded on: spatial reasoning, generative 3D, agentic pipelines, and real-time interactive AI. This case study is the browser-panel end of that spectrum. AR is the other end, and the same avatar walks between them.</p>
+<h3>One more thing, and then the engineering</h3>
+<p>Decision management means I spend my working life on a single question: what happens when an automated decision is wrong, and who finds out. Agents with faces and voices made that question louder for me, not quieter. A chatbot that gives you a bad answer looks exactly like a chatbot giving you a good one. An agent with a <em>body</em> can look reassuring while it is wrong, and that is a genuinely new failure mode that our existing controls were not designed for.</p>
+<p>So I asked the three.ws team to walk me through how the integration works and to write it up honestly, including what broke. What follows is that walkthrough, checked against both repositories myself, with the parts I found most useful to this group kept and the parts that make the best announcement cut.</p>
+<hr style="border:none;border-top:1px solid #e0e0e0;margin:44px 0">
+<h2>1. Why decentralized finance is the hard case for an agent interface</h2>
+<p>Before any of the engineering, it is worth being specific about why this domain and not another. I did not pick it for the crypto. I picked it because it breaks the chat box in four distinct ways, and every one of them is a general lesson wearing a specific costume.</p>
+<p><strong>The state moves every block.</strong> A number the agent read twelve seconds ago may already be wrong. A support chatbot answering from a knowledge base has no equivalent problem. Here, the gap between reading and acting is a risk window, and any interface that renders a value without rendering its age is quietly lying about how much it knows.</p>
+<p><strong>It is numerically dense and unit-hostile.</strong> Amounts in the smallest indivisible unit against amounts in whole tokens. Contracts against coins. Annual percentage rate against annual percentage yield. Basis points. Prose flattens all of that: &quot;your position is healthy&quot; reads identically whether the underlying calculation used the right unit or was off by a factor of ten to the eighteenth. Section 7 is a real example of a units-shaped bug that survived into a shipped preview.</p>
+<p><strong>Actions are irreversible.</strong> No chargeback, no undo, no support ticket that reverses a confirmed transaction. This is the property that makes an agent in this domain different in kind from an agent that drafts an email. An agent that is wrong ninety-nine times out of a hundred in a text box is annoying. Here, the hundredth is permanent.</p>
+<p><strong>The mechanics are protocol-specific, and models state them confidently anyway.</strong> Two protocols can both use the word &quot;staking&quot; and compute completely different things underneath. A language model trained on the general internet will produce a fluent, plausible, wrong explanation of the specific one in front of it, and there is nothing in the sentence&#39;s texture to warn you. This is the single most important thing I took from the whole write-up, and it is why section 11 lists a maintained domain skill pack as a planned item rather than a nice-to-have.</p>
+<h3>What the agent actually does in there</h3>
+<p>For anyone who has never opened this kind of workspace, the tool catalog is the fastest orientation. Grouped roughly as the repository groups them:</p>
+<table style="border-collapse:collapse;width:100%;margin:24px 0">
+<thead>
+<tr>
+<th style="border:1px solid #e0e0e0;padding:10px 14px;text-align:left;background:#f4f4f4">Category</th>
+<th style="border:1px solid #e0e0e0;padding:10px 14px;text-align:left;background:#f4f4f4">What the agent can call</th>
+</tr>
+</thead>
+<tbody><tr>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Trading</td>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Swaps across aggregators, limit orders, route comparison</td>
+</tr>
+<tr>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Lending</td>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Supply and borrow, health factor, liquidation watch</td>
+</tr>
+<tr>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Yield</td>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Pool discovery, rate comparison, auto-compounding</td>
+</tr>
+<tr>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Analytics</td>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Total value locked, protocol revenue, chain metrics, exchange volume</td>
+</tr>
+<tr>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Portfolio</td>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Wallet tracking, profit and loss, allocation, gas history</td>
+</tr>
+<tr>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Market intelligence</td>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Funding rates, sentiment indices, large-holder alerts, fund flows</td>
+</tr>
+</tbody></table>
+<p>That is 592 callable APIs across 99 packages, and the repository ships a machine-readable index of all of them that marks <strong>which ones move funds</strong>. I want to underline that, because it is the kind of thing that only exists when someone has thought about the problem seriously. A tool catalog that distinguishes &quot;reads a number&quot; from &quot;spends your money&quot; is a governance primitive, not documentation.</p>
+<p>The same instinct shows up in the SDK&#39;s execution model, which does not let an agent act and then tell you:</p>
+<pre style="background:#f4f4f4;border-left:4px solid #0f62fe;padding:16px 20px;overflow-x:auto;font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:14px;line-height:1.6"><code class="language-typescript">// Async mode returns immediately so you can stream the agent&#39;s work.
+const { data } = await sperax.agent.runAsync({
+ prompt: &#39;Find the best USDC yield on Arbitrum and prepare a deposit&#39;,
+ maxSteps: 15,
+});
+
+for await (const event of sperax.agent.stream(data.operationId)) {
+ if (event.event === &#39;stream_chunk&#39;) process.stdout.write(event.data.content);
+}
+
+// The run pauses before acting; you decide whether it proceeds.
+await sperax.agent.approve(data.operationId);
+</code></pre>
+<p>Note the verb in the prompt: <em>prepare</em> a deposit. The run streams its reasoning, stops at the boundary where value would move, and waits for a human. Registering an agent on-chain works the same way: the API builds the calldata and never holds a key or broadcasts for you.</p>
+<h3>And this is where a body starts to earn its place</h3>
+<p>Put those four properties together and you get an interface problem that is genuinely under-served by text.</p>
+<p>A dashboard reports state. A face reports <em>change in</em> state, pre-attentively, before you have read anything. When a position&#39;s health drifts from comfortable toward dangerous, the number moving from one value to another has to be noticed, parsed, and interpreted. An expression that has been holding concern for the last ten seconds is noticed before you read a single digit.</p>
+<p>That is the actual argument for embodiment here, and it is why section 7 matters more than the rendering. The channel only helps if what it is expressing is true.</p>
+<hr style="border:none;border-top:1px solid #e0e0e0;margin:44px 0">
+<h2>2. What was actually built</h2>
+<p>The host side is <a href="https://chat.sperax.io">SperaxOS</a>. The specifications, from its own repository: 99 built-in tool packages exposing 592 tool APIs, 63 of which are reachable from any MCP client, an agent runtime on Next.js with more than 70 model providers behind it, an on-chain agent registry, an Apache-2.0 license, and self-hosting through Docker. It is a serious piece of software, which matters here, because the interesting engineering constraints in this post all come from it being somebody&#39;s real product rather than a demo harness.</p>
+<p>The integration puts the three.ws agent inside it. In the chat panel, an agent has a body. It speaks, it gestures, and its facial expression and posture shift continuously in response to what its tools are actually doing.</p>
+<p>Here is what has shipped, as of this writing:</p>
+<table style="border-collapse:collapse;width:100%;margin:24px 0">
+<thead>
+<tr>
+<th style="border:1px solid #e0e0e0;padding:10px 14px;text-align:left;background:#f4f4f4">Surface</th>
+<th style="border:1px solid #e0e0e0;padding:10px 14px;text-align:left;background:#f4f4f4">What it is</th>
+</tr>
+</thead>
+<tbody><tr>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Standalone plugin</td>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">A hosted manifest at a well-known URL plus four LLM-callable tools. Install it in the host, paste an agent ID, done.</td>
+</tr>
+<tr>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Native component</td>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">The <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">three.ws</code> npm package mounted directly in the host&#39;s own React tree, no iframe.</td>
+</tr>
+<tr>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Inline 3D in a chat message</td>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">A markdown element that renders a live, orbitable model inside a reply.</td>
+</tr>
+<tr>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Emotion and lip-sync engines</td>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Ported from three.ws into the host codebase, kept framework-agnostic so they are unit-testable.</td>
+</tr>
+<tr>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Hash-chained action ledger</td>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Ported the same direction, with the reconcile job that checks it.</td>
+</tr>
+<tr>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Three packages ported the other way</td>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">Chain and token utilities, a typed tool-authoring SDK, and a market-data collector, all now running inside three.ws.</td>
+</tr>
+<tr>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">A guided 3D site tour</td>
+<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">An eight-stop template that exports as a single script tag.</td>
+</tr>
+</tbody></table>
+\n<p>The rest of this post is what I learned reading how those were built.</p>
+<hr style="border:none;border-top:1px solid #e0e0e0;margin:44px 0">
+<h2>3. The first design question is not the one you expect</h2>
+<p>I assumed the hard question was &quot;how do you render a 3D avatar inside an application you do not control.&quot; It is not. Rendering is a solved problem and the team spent very little time on it.</p>
+<p>The actual question is <strong>who owns the React tree</strong>, and it has two legitimate answers depending on the host.</p>
+<p><img style="max-width:100%;height:auto;border:1px solid #e0e0e0;margin:8px 0" src="./media/ibm-sperax-integration-paths.png" alt="Two integration paths for embedding an agent in a host application"></p>
+<p><em>Figure 1. The two integration paths, and what each one costs you.</em></p>
+<p><strong>Path one is for hosts that will not take your code.</strong> Most plugin ecosystems will not let a third party ship JavaScript into the main bundle, and I think they are right not to. For those hosts, three.ws ships a standalone plugin: one hosted manifest, one hosted iframe, and a handful of HTTP endpoints. Nothing to vendor, nothing for the host&#39;s security team to review, no supply chain to audit. It is live in a day.</p>
+<p><strong>Path two is for hosts that want the dependency.</strong> When a host is willing to take a package, an iframe is a downgrade. You lose shared context, you pay for a second renderer, and you cannot compose the avatar into anything the host renders itself.</p>
+<p>SperaxOS ended up in both camps at once, which is why the integration has both halves. If you are building something similar, the team&#39;s advice, which I would repeat, is: <strong>ship the manifest first, because it gets you live and it works for hosts that will never take your code. Then do the native integration, because that is the one that finds your bugs.</strong> More on that in section 5, and it is not a throwaway line.</p>
+<h3>The manifest, in full</h3>
+<p>The whole of path one is one JSON file served with CORS:</p>
+<pre style="background:#f4f4f4;border-left:4px solid #0f62fe;padding:16px 20px;overflow-x:auto;font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:14px;line-height:1.6"><code>https://three.ws/.well-known/sperax-plugin.json
+</code></pre>
+<p>Its shape:</p>
+<pre style="background:#f4f4f4;border-left:4px solid #0f62fe;padding:16px 20px;overflow-x:auto;font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:14px;line-height:1.6"><code class="language-jsonc">{
+ &quot;identifier&quot;: &quot;three-ws&quot;,
+ &quot;type&quot;: &quot;standalone&quot;,
+ &quot;ui&quot;: { &quot;url&quot;: &quot;https://three.ws/sperax/iframe/&quot;, &quot;height&quot;: 480, &quot;mode&quot;: &quot;iframe&quot; },
+ &quot;settings&quot;: {
+ &quot;type&quot;: &quot;object&quot;,
+ &quot;required&quot;: [&quot;agentId&quot;],
+ &quot;properties&quot;: { &quot;agentId&quot;: { &quot;type&quot;: &quot;string&quot;, &quot;title&quot;: &quot;Agent ID&quot; } }
+ },
+ &quot;api&quot;: [
+ { &quot;name&quot;: &quot;render_agent&quot;, &quot;url&quot;: &quot;https://three.ws/api/chat-plugin/render-agent&quot;, &quot;...&quot;: &quot;...&quot; },
+ { &quot;name&quot;: &quot;speak&quot;, &quot;url&quot;: &quot;https://three.ws/api/chat-plugin/speak&quot;, &quot;...&quot;: &quot;...&quot; },
+ { &quot;name&quot;: &quot;gesture&quot;, &quot;url&quot;: &quot;https://three.ws/api/chat-plugin/gesture&quot;, &quot;...&quot;: &quot;...&quot; },
+ { &quot;name&quot;: &quot;emote&quot;, &quot;url&quot;: &quot;https://three.ws/api/chat-plugin/emote&quot;, &quot;...&quot;: &quot;...&quot; }
+ ]
+}
+</code></pre>
+<p>Four tools, and I want to note what is <em>not</em> in that list. There is no <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">set_expression_to_happy</code>. The tools are <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">render_agent</code> to bind or swap the avatar, <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">speak</code> with an emotional valence in the range minus one to one, <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">gesture</code> for a named physical beat (wave, nod, point, shrug), and <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">emote</code> to blend a named feeling into a continuous emotional state. Only the last two touch the face, and neither of them sets it. They contribute to it. That distinction is section 6.</p>
+<p>The only required setting is a public agent ID. No API key, which is a design decision I appreciate: the plugin cannot leak a credential it never asks for.</p>
+<hr style="border:none;border-top:1px solid #e0e0e0;margin:44px 0">
+<h2>4. Every tool call runs in two halves</h2>
+<p>This is the piece I would put on a slide if I were teaching this.</p>
+<p><img style="max-width:100%;height:auto;border:1px solid #e0e0e0;margin:8px 0" src="./media/ibm-sperax-tool-call-halves.png" alt="Every tool call runs in two halves, in parallel"></p>
+<p><em>Figure 2. Both halves run on every call. The split is what keeps the model from asserting things it cannot know.</em></p>
+<p>When the model calls <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">speak</code>, two things happen in parallel. The host frames the plugin&#39;s panel and posts the call into it, and the avatar speaks. Separately, the host&#39;s plugin gateway POSTs the same arguments to the tool&#39;s HTTP endpoint, and that endpoint returns a short result the model reads back into its own context.</p>
+<p>Why bother with both? Because <strong>the model must never be the thing that asserts the avatar moved.</strong> If the model simply says &quot;I waved&quot; and the panel silently failed, the transcript now contains a false statement that the model will happily build on for the rest of the conversation. Splitting the halves means the model receives a result saying the wave was dispatched, and the panel is the thing that actually waved. The two can be compared.</p>
+<p>That is not a hypothetical. It is exactly the bug they shipped first, and the fix is my favorite twenty lines in either repository:</p>
+<pre style="background:#f4f4f4;border-left:4px solid #0f62fe;padding:16px 20px;overflow-x:auto;font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:14px;line-height:1.6"><code class="language-js">async function resolveAgent(agentId) {
+ if (!isUuid(agentId)) return { known: true, name: null };
+ try {
+ const [row] = await sql`
+ SELECT name FROM agent_identities
+ WHERE id = ${agentId} AND deleted_at IS NULL
+ LIMIT 1
+ `;
+ if (!row) return { known: false, name: null };
+ return { known: true, name: typeof row.name === &#39;string&#39; ? row.name : null };
+ } catch (err) {
+ console.warn(&#39;[chat-plugin] agent lookup failed, binding unverified:&#39;, err?.message);
+ return { known: true, name: null };
+ }
+}
+</code></pre>
+<p>The original version confirmed any agent ID it was handed. Someone with a typo in their settings got a model cheerfully announcing &quot;I have bound to your agent&quot; over a permanently empty panel. There is no error anywhere. The system is behaving exactly as written, and it is lying.</p>
+<p>Three behaviors in the fix are deliberate, and I would defend all three in a design review:</p>
+<ol>
+<li><strong>A well-formed ID that does not exist comes back as a real error</strong>, one the model can explain, pointing the user back to their dashboard to recopy it.</li>
+<li><strong>A handle or manifest ID passes through unverified</strong>, because the browser element resolves those and the server has no business pretending it checked something it did not.</li>
+<li><strong>A database outage degrades to an unverified binding instead of a 500.</strong> An infrastructure problem on one side must never take down the other side&#39;s chat panel.</li>
+</ol>
+<p>That third one is the decision-management instinct showing, and I was glad to see it in someone else&#39;s code. The failure mode of a dependency should be proportional to what the dependency actually does. A name lookup being unavailable is not a reason to break a conversation.</p>
+<p>One small practical note that will save somebody an afternoon: hosts rename the settings header. LobeChat sends <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">lobe-chat-plugin-settings</code> and SperaxOS sends <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">Sperax-Plugin-Settings</code>. Read both.</p>
+<hr style="border:none;border-top:1px solid #e0e0e0;margin:44px 0">
+<h2>5. The native path is where the real bugs live</h2>
+<p>Path two is a dependency and a mount:</p>
+<pre style="background:#f4f4f4;border-left:4px solid #0f62fe;padding:16px 20px;overflow-x:auto;font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:14px;line-height:1.6"><code class="language-tsx">// three.ws registers &lt;agent-3d&gt; via customElements.define(...)
+useEffect(() =&gt; {
+ if (typeof window !== &#39;undefined&#39; &amp;&amp; !window.VIEWER) window.VIEWER = {};
+ import(&#39;three.ws&#39;).then(() =&gt; {
+ customElements.whenDefined(&#39;agent-3d&#39;).then(() =&gt; setRegistered(true));
+ });
+}, []);
+</code></pre>
+<p>Six lines, two scars, and both are worth your time even if you never touch 3D.</p>
+<p><strong>The dynamic import is not a style choice.</strong> The package shipped <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">sideEffects: false</code> in its manifest. For a package whose entire job is a <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">customElements.define</code> side effect, that field is simply false, and a production bundler believed it: the registration was tree-shaken away and the element silently never upgraded. Not an error, not a warning, just an element that stays inert. The host now carries a patch for the flag <em>and</em> imports dynamically, because dynamic imports are never tree-shaken. <strong>If you publish a custom element, go check that field right now.</strong></p>
+<p><strong>The <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">window.VIEWER</code> seed is the other one.</strong> The library assigned to <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">window.VIEWER.json</code> during model boot without ever initializing the global. In three.ws&#39;s own pages the global happened to exist. In someone else&#39;s application it did not, and boot threw a <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">TypeError</code>.</p>
+<p>Neither of those is findable from inside your own product. That is the whole argument for doing the native integration even after the iframe works: the iframe protects you from the host, and it also protects you from learning what your package does in a world you did not build.</p>
+<p>Once the component is native, it composes in ways the iframe cannot. The host added a markdown plugin so a chat message can contain a live model:</p>
+<pre style="background:#f4f4f4;border-left:4px solid #0f62fe;padding:16px 20px;overflow-x:auto;font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:14px;line-height:1.6"><code class="language-html">&lt;avatar3d url=&quot;https://.../model.glb&quot; size=&quot;260&quot; clip=&quot;Wave&quot; zoom=&quot;true&quot; /&gt;
+</code></pre>
+<p>That renders in the same React tree, no iframe, no sandbox, and the model can come from anywhere. An agent answering &quot;what does this thing look like&quot; can now answer with the thing.</p>
+<p>There is also a client lane in the tool router, which I had not thought about before reading this. Animation control cannot round-trip through a server without the animation being late, so a dispatcher intercepts the calls that belong to the browser before the rest go server-side:</p>
+<pre style="background:#f4f4f4;border-left:4px solid #0f62fe;padding:16px 20px;overflow-x:auto;font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:14px;line-height:1.6"><code class="language-ts">const CLIENT_TOOL_IDS = new Set([&#39;agent-3d-controls&#39;, &#39;get-available-animations&#39;]);
+
+for (const tool_call of params.tool_calls) {
+ if (CLIENT_TOOL_IDS.has(tool_call.function.name)) params.onClientToolCall(tool_call);
+ else serverToolCalls.push(tool_call);
+}
+</code></pre>
+<p>Obvious once you see it. Worth stealing if your agent controls anything with a frame rate.</p>
+<hr style="border:none;border-top:1px solid #e0e0e0;margin:44px 0">
+<h2>6. Emotion as a continuous blend, not a state machine</h2>
+<p>Here is the part I expected to find cosmetic and did not.</p>
+<p>The obvious way to build an expressive avatar is a state machine: happy, sad, thinking, alarmed. It takes about thirty seconds of real use to see why that is wrong. The avatar snaps between moods, and the snap reads as a cartoon. Worse, for a monitoring interface, a state machine has to <em>choose</em>, and the truth is usually a mixture.</p>
+<p>The approach both teams now share is a continuous weighted blend. Each emotion is a float between zero and one. Events spike it. It then decays exponentially, at its own rate, every frame. All active emotions are blended into facial morph targets and body language on every frame, so a face can be forty percent concerned, thirty percent curious, and thirty percent neutral at the same time, which is how faces actually work.</p>
+<p><img style="max-width:100%;height:auto;border:1px solid #e0e0e0;margin:8px 0" src="./media/ibm-sperax-empathy-decay.png" alt="The five emotion decay curves and a blended face at one moment"></p>
+<p><em>Figure 3. The five decay curves. Each dot marks where a full spike has fallen to the floor value and the emotion is treated as inactive.</em></p>
+<p>The ported definition table doubles as the design document, and the comments are the original author&#39;s:</p>
+<pre style="background:#f4f4f4;border-left:4px solid #0f62fe;padding:16px 20px;overflow-x:auto;font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:14px;line-height:1.6"><code class="language-ts">export const EMOTION_DEFINITIONS: Record&lt;EmotionName, EmotionDef&gt; = {
+ // Positive sentiment or success: a warm, open smile.
+ celebration: { decaySeconds: 6, morphs: { jawOpen: 0.2, smile: 0.85 } },
+ // Negative sentiment or tool error: a worried frown with raised inner brows.
+ concern: { decaySeconds: 12, morphs: { browInnerUp: 0.6, frown: 0.55 } },
+ // Loading or processing: an inquisitive head tilt.
+ curiosity: { decaySeconds: 8, headTiltZ: 0.12 },
+ // Emotional or supportive moments: a soft, squinting, caring look.
+ empathy: { decaySeconds: 13, morphs: { browInnerUp: 0.5, eyeSquint: 0.4 } },
+ // Long-running operations: a patient backward lean.
+ patience: { decaySeconds: 20, leanX: -0.08 },
+};
+</code></pre>
+<p><strong>The decay rates carry the entire personality, and they are deliberately not uniform.</strong> Celebration is bright and brief at six seconds. Concern lingers at twelve, so a risk that appeared while you were looking away is still on the face when you look back. Patience runs twenty, so an agent waiting on a slow operation keeps <em>looking</em> like it is waiting instead of going blank. Empathy is the slowest of the soft states at thirteen, because empathy that switches off the instant a sentence ends reads as insincere, and it turns out that is true of rendered faces too.</p>
+<p>Two implementation choices are what make this maintainable rather than a pile of magic numbers:</p>
+<p><strong>Keep the engine pure.</strong> The emotion module has no 3D library and no React in it. It maps time and spikes to logical morph weights, and a separate module resolves those logical names onto whatever concrete blendshapes the loaded mesh happens to have. So the emotion model is unit-testable with no renderer, and it ported cleanly between two codebases that share no UI framework. If you take one architectural idea from this post, take this one: <strong>the interesting part of your system should not import your rendering layer.</strong></p>
+<p><strong>Compose, do not multiplex.</strong> Speech drives the mouth through an entirely separate path. A Web Audio analyser samples the speech waveform each frame and maps a smoothed amplitude onto the jaw channel, gated below a noise floor so room hum does not make the avatar chew, saturating well before a full open so it never gapes:</p>
+<pre style="background:#f4f4f4;border-left:4px solid #0f62fe;padding:16px 20px;overflow-x:auto;font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:14px;line-height:1.6"><code class="language-ts">const NOISE_GATE = 0.02;
+const FULL_OPEN_RMS = 0.22;
+const MAX_JAW = 0.7;
+</code></pre>
+<p>Because articulation and emotion write to different logical channels and are summed, the agent can deliver bad news <em>while looking concerned about it</em>. A state machine would have to pick one.</p>
+<hr style="border:none;border-top:1px solid #e0e0e0;margin:44px 0">
+<h2>7. The part that actually matters, and it is not the rendering</h2>
+<p>Now the section I asked for, and the reason I wanted this written up at all.</p>
+<p><strong>An expressive avatar sitting on top of wrong data is not a nice interface. It is a confident liar, and it is worse than a table of numbers, because a table does not lean toward you and look reassuring.</strong></p>
+<p>They learned this the direct way, and to their credit the commit history says so in plain language.</p>
+<p>The SPA staking panel in the host application, and the chat tools behind it, were returning literals. Total SPA locked: zero. Total veSPA supply: zero. Average lockup: zero. The four-year staking rate: a hardcoded <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">22.61</code>, with a source comment that said, and I am quoting the code, &quot;from app screenshot.&quot; Because two of those were zero, the panel&#39;s own has-data check failed and it rendered dashes in every field. The agent, meanwhile, would narrate the number that had been copied off a screenshot months earlier, with a face on.</p>
+<p>The fix reads the contracts instead:</p>
+<ul>
+<li>Total locked and escrow supply now come from live <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">totalSPALocked()</code> and <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">totalSupply()</code> calls on the voting-escrow contract. At the time of the fix that was 242.66 million SPA locked against 416.78 million veSPA.</li>
+<li>The rate is derived from the rewarder contract&#39;s <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">rewardsPerWeek</code> over a trailing eight-week window, landing at 21.0 percent at maximum lock. Close to the number that had been copied, which is exactly the point: it is now sourced and auditable rather than coincidentally near-correct. The eight-week window exists because emissions funding is irregular enough that any single week is noise.</li>
+</ul>
+<p>The worse bug was in the estimator, and this is the one I would use in a decision-integrity training session. It is also section 1&#39;s fourth property in the flesh. Both call sites computed voting power with the linear <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">amount * lockSeconds / MAXTIME</code> slope that a <em>different</em> well-known vote-escrow design uses. Same word, same general idea, different math: this escrow mints one veSPA per SPA per <strong>year</strong> locked, capped at four years. Someone locking 1,000 SPA for four years was shown an estimate of roughly 1,000 veSPA and would actually have received roughly 3,984.</p>
+<p>A four-fold understatement. In a preview. Next to an avatar nodding encouragingly.</p>
+<p>It is now a shared helper backing both the dashboard panel and the chat tool preview, verified against the contract&#39;s own <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">estimateDeposit</code> at six different lock lengths, and pinned by tests so it cannot drift back.</p>
+<p>The rule that came out of it, and which I think generalizes far past this domain:</p>
+<blockquote style="border-left:4px solid #0f62fe;background:#edf5ff;margin:28px 0;padding:18px 24px;font-size:1.05em">
+<p><strong>The avatar may only express state it can prove.</strong> If a number cannot be read from its source of truth, the correct behavior is a visible unknown, not a confident face over a stale literal.</p>
+</blockquote>
+<p>I would go further, from the decision-management side. Embodiment raises the cost of being wrong, because it raises the user&#39;s trust before the data has earned it. Every project in this group that puts a face on an agent is quietly taking on that liability. It is worth deciding, on purpose and in advance, what your avatar does when it does not know.</p>
+<hr style="border:none;border-top:1px solid #e0e0e0;margin:44px 0">
+<h2>8. Failing honestly, including about other people&#39;s systems</h2>
+<p>A smaller story, same principle, opposite direction.</p>
+<p>While embedding the partner&#39;s own application in a frame, a probe fetched the target and received a <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">403</code>, so the page hid the embed and told the user the site had refused framing.</p>
+<p>The site had refused nothing. Its bot protection challenges every datacenter address, and the probe was running on one. The giveaway is that a plain top-level request, a static asset, and a path that does not exist all returned the same <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">403</code>, which has nothing to do with framing. The header being read as a framing policy belonged to the challenge page, not to the application.</p>
+<p>The probe now sends an unframed control request alongside the framed one, and only trusts a framing refusal when the control was actually served. On a challenged network it reports <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">UNKNOWN</code> and exits with a distinct code.</p>
+<p><strong>A negative result from a network you do not control is not a fact about the other system.</strong> I have watched teams write a permanent configuration change on exactly this kind of evidence. Reporting &quot;I could not tell&quot; is a feature.</p>
+<hr style="border:none;border-top:1px solid #e0e0e0;margin:44px 0">
+<h2>9. Provenance, for a body that can move money</h2>
+<p>Once an embodied agent can execute rather than only explain, expressiveness stops being the interesting problem and provenance starts.</p>
+<p>three.ws had built a hash-chained ledger for its own agent activity, and the host ported the primitive: an append-only, SHA-256 hash-chained record of every value movement an agent initiates, where each entry commits its predecessor.</p>
+<pre style="background:#f4f4f4;border-left:4px solid #0f62fe;padding:16px 20px;overflow-x:auto;font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:14px;line-height:1.6"><code>entryHash = sha256( canonicalFields(entry) || prevHash )
+</code></pre>
+<p>Each user owns an independent chain. Sequence numbers are per-user and monotonic from one, the first entry commits a genesis hash of sixty-four zeros, and the canonical serialization is a fixed field order with free-text detail folded in through a key-sorted stringify, so identical payloads always hash identically.</p>
+<p>The field separator is a NUL byte, and the reasoning is the sort of detail that decides whether a scheme is sound or decorative. Two of the committed fields are free text and can contain spaces. With a printable separator the encoding is ambiguous: two different field tuples could serialize to the same string, and a chain built on an ambiguous encoding proves nothing at all. A NUL cannot occur in any of the values, so the serialization is injective and the hash means what it claims.</p>
+<p>Editing or deleting any historical row breaks the chain from that point forward. A reconcile job runs on a schedule looking for two things: a chain break, and an on-chain movement that was never recorded. <strong>The second alarm is the interesting one.</strong> A value movement with no corresponding ledger entry is the signal that a key is being used outside the agent runtime, which is to say it is a breach detector wearing an accounting hat.</p>
+<p>What did <em>not</em> get ported is as deliberate as what did. The origin system&#39;s signing keys, its price oracle, and its multi-wallet funding topology all stayed behind, because the receiving system has different custody and its own valuation source. A port that drags its origin&#39;s assumptions along with it is not a port, it is a fork with extra steps.</p>
+<p>For an agent with a face, this is the other half of trustworthiness. The emotion layer makes the agent legible in the moment. The ledger makes it accountable afterward. You need both, and I would argue the second one is the part that lets a regulated organization say yes to the first.</p>
+<hr style="border:none;border-top:1px solid #e0e0e0;margin:44px 0">
+<h2>10. The code went both ways, and that is the part I would negotiate for</h2>
+<p>Here is what surprised me most, and it is a partnership observation rather than a technical one.</p>
+<p><img style="max-width:100%;height:auto;border:1px solid #e0e0e0;margin:8px 0" src="./media/ibm-sperax-code-exchange.png" alt="What was ported in each direction between the two codebases"></p>
+<p><em>Figure 4. What moved which way. The right-hand column is the half nobody writes a press release about.</em></p>
+<p><strong>Into the host from three.ws:</strong> the emotion engine, the lip-sync driver, the inline 3D markdown element, the client-side tool dispatcher, and the hash-chained ledger with its reconcile job.</p>
+<p><strong>Into three.ws from the host:</strong></p>
+<ul>
+<li>A zero-dependency single source of truth for chain and token constants, minimal contract interface fragments, and address and amount validation. The existing maps were kept verbatim and a section was added for a chain the origin did not cover.</li>
+<li>A typed tool-authoring layer, derived from the host&#39;s plugin SDK. One call declares a tool&#39;s identity, its schemas, and its permission manifest, and derives the machine-readable schema automatically. A second call wires a typed implementation onto it and routes every invocation through a single entry point that validates parameters, enforces the declared rate limit, and normalizes both success and failure into one shape. A third adapts the result into the exact registration shape the receiving project&#39;s MCP servers already use, so adopting it is one call instead of a rewrite. It was rewritten from TypeScript into plain ESM with JSDoc to match the receiving codebase&#39;s conventions, and re-scoped away from chat-interface concepts it no longer needed.</li>
+<li>A market-data collector, since hardened considerably: per-topic subscription acknowledgements on one exchange whose retired topic used to fail silently, a unit conversion on another whose raw size field counts contracts rather than units, a geographic restriction probe on a third, and per-lane health reporting. It runs as a standalone always-on service because it holds long-lived WebSockets, and the proxy in front of it returns a 503 when the collector is unreachable rather than inventing numbers, which is the same principle as section 7 wearing different clothes.</li>
+</ul>
+<p>If you are ever in the room where an integration is being negotiated, <strong>this is the clause to push for: a shared right to port implementation between the two codebases.</strong> Two teams working on adjacent problems produce more reusable primitives than either will build alone, and a partnership you can measure in merged commits ages a great deal better than one you can only measure in announcements.</p>
+<hr style="border:none;border-top:1px solid #e0e0e0;margin:44px 0">
+<h2>11. What is planned, stated as plans and not as shipping claims</h2>
+<p>I asked for this list explicitly and I am labeling it clearly, because I do not want anything here read as available today.</p>
+<p>Shipped and live: everything in the table in section 2.</p>
+<p>Designed, in progress, or proposed:</p>
+<ol>
+<li><strong>Compute endowments.</strong> USDs, the Sperax stablecoin, pays yield to whoever holds it, automatically, with no staking step: the balance grows in the wallet. The idea is that you deposit once and that yield stream funds an agent&#39;s compute balance indefinitely, so the agent never runs out of inference budget. Set the domain aside for a second and look at the shape of it: it is a real answer to &quot;who pays for this agent&#39;s inference in year three,&quot; and it needs no new financial mechanism, only new plumbing between an existing yield stream and an existing credit ledger. I find that the most interesting idea on the list, as an agent-economics question, independent of the asset involved.</li>
+<li><strong>A recurring credit grant keyed to holdings</strong> rather than a one-time claim, so the relationship is retention rather than a giveaway.</li>
+<li><strong>A second settlement asset</strong> on the machine-to-machine payment rails that already handle per-call settlement over the x402 HTTP payment scheme.</li>
+<li><strong>A domain skill pack</strong>, so an agent reasons about the specific protocol mechanics from a maintained source rather than approximating them from training data. The voting-power bug in section 7 is precisely the failure a real skill pack prevents, which is why I think this one matters more than it sounds.</li>
+<li><strong>The guided site tour deployed on the live partner site.</strong> The template exists and exports as a single script tag. A builder preview can only prove the mechanics, so the real test is the deployment.</li>
+</ol>
+<hr style="border:none;border-top:1px solid #e0e0e0;margin:44px 0">
+<h2>12. What I would like from this group</h2>
+<p>A few things, and then the links.</p>
+<p><strong>If you have embedded an agent into somebody else&#39;s application, tell us which path you took.</strong> Section 3 is the fork in the road, and I would like the group&#39;s collective experience on it. My suspicion is that most people reach for the iframe and never do the native version, and therefore never find their equivalent of the <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">sideEffects</code> bug.</p>
+<p><strong>If you publish a web component, go and check your <code style="font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">sideEffects</code> field.</strong> That is the single most immediately actionable thing in this post and it takes ninety seconds.</p>
+<p><strong>If you put a face on an agent, decide now what it does when it does not know.</strong> Section 7 is my honest reason for publishing this. I would rather this group be known for building agents that are legible about their uncertainty than for building agents that are charming about it.</p>
+<p><strong>And the AR question I promised to come back to.</strong> Everything above happens in a rectangle on a screen. The same rigged avatar, the same emotion blend, the same tool calls, can also be placed in a room through a phone camera, and three.ws ships that surface separately. It is not part of this integration and I am not going to pretend it is. But every argument in section 7 gets sharper when the agent is standing in your kitchen instead of sitting in a panel, because the trust an embodied thing borrows from being <em>present</em> is larger again. If somebody in this group wants to be the first to put a domain-grounded agent into AR and write up what broke, I will give that post the front of the group and I will bring the questions to both teams myself.</p>
+<p>And if you want to try any of it, none of the following requires an account with anyone, and the generation step requires no key at all:</p>
+<ul>
+<li>Generate a rigged, animation-ready avatar from a sentence at <a href="https://three.ws/create">three.ws/create</a>, or a static model at <a href="https://three.ws/forge">three.ws/forge</a>.</li>
+<li>Embed it with the documented custom element at <a href="https://three.ws/docs/embedding">three.ws/docs/embedding</a>, or install the package if you want it natively in a React tree.</li>
+<li>Read <a href="https://three.ws/.well-known/sperax-plugin.json">the plugin manifest itself</a>. It is the shortest complete description of the four-tool interface, and the pattern transfers to any host of the same lineage.</li>
+<li>The integration write-up from the three.ws side is at <a href="https://three.ws/sperax">three.ws/sperax</a>, and the host application is Apache-2.0 at <a href="https://github.com/nirholas/sperax">github.com/nirholas/sperax</a> if you want to read the receiving half.</li>
+</ul>
+<p>Back to the third corner of the triangle, with one practical note. The agent brain is provider-agnostic on both sides of this integration, so pointing it at IBM Granite through watsonx.ai changes nothing about the rest. The emotion engine in section 6 takes its spikes from tool-call outcomes and sentiment rather than from any provider&#39;s output format, and the four plugin tools are plain HTTP. Your model choice is genuinely orthogonal to the body, which is the property that makes the whole stack swappable. If you are wiring an embodied agent to Granite and you hit something ugly, post it here. That is what the group is for.</p>
+<p>I will bring the harder questions from this thread back to the three.ws team, the same way I did for the meetup Q&amp;A. The skeptical ones are still the most useful ones.</p>
+</body></html>
diff --git a/docs/ibm-community-defi-3d-sperax-post.md b/docs/ibm-community-defi-3d-sperax-post.md
new file mode 100644
index 000000000..43b929607
--- /dev/null
+++ b/docs/ibm-community-defi-3d-sperax-post.md
@@ -0,0 +1,463 @@
+# Sperax, three.ws, and IBM Granite: giving a DeFi agent a body, a brain, and a reason to trust it
+
+_By Jessica Swanson. Posted in the [Three.ws User Group](https://community.ibm.com/community/user/groups/community-home?communitykey=e71510cc-d953-408f-9a1c-019f5c0a7016) on IBM Community._
+
+![Sperax, three.ws, and IBM](./media/ibm-sperax-featured.png)
+
+---
+
+## 0. An IBM employee writing about two crypto companies
+
+I work at IBM. I am about to publish six thousand words about two crypto companies. I want to deal with that up front, because it is the first thing I would think if this turned up in my feed.
+
+IBM has thousands of Business Partners. Two of them, Sperax and three.ws, are also partners with each other, and they shipped something together that I think is the most complete piece of embodied-agent engineering I have read this year. I am not here to explain IBM's partnership strategy. That is not my job, not my call, and not something any one employee should narrate on a community blog. I am here for a much narrower reason, and it is entirely my own:
+
+**My job at IBM is decision management. The best real-world material on automated-decision integrity I have read in months arrived from a direction nobody in my part of the industry is looking.**
+
+That is the whole pitch. If you skip everything else, read section 7.
+
+### The triangle, drawn plainly
+
+Three relationships, all real, all different, and they close around one agent:
+
+- **Sperax and three.ws are partners with each other**, and they built the integration this post is about.
+- **Both are IBM Business Partners.**
+- **The three.ws agent runtime runs on IBM Granite models through watsonx.ai**, using your own IBM Cloud credentials.
+
+Split by what each side actually contributes and the shape is clean:
+
+- **three.ws gives the agent a body.** A rigged, animated 3D avatar you can generate from a sentence, drop into any web page with one custom element, or place in a room through a phone camera with AR. It speaks, it gestures, and its expression changes with what it is doing.
+- **Sperax gives the agent a domain, and the domain is decentralized finance.** An open-source AI agent workspace where an agent can swap, lend, borrow, hunt yield, and watch a position toward liquidation, across 99 built-in tool packages exposing 592 tool APIs against live protocols. Somewhere real to act, where being wrong costs money in the same block.
+- **IBM Granite can be the agent's brain.** The three.ws runtime is model-agnostic and runs Granite through watsonx.ai on your own credentials, so the reasoning layer is enterprise-grade and stays yours.
+
+Body, domain, brain. Read one at a time those are three product announcements. Read together they are the most complete end-to-end example I have seen of what an embodied enterprise agent actually costs to build, and because both partner codebases are public, this group can read every line of it, including the parts that went wrong.
+
+### Why this is worth an enterprise reader's afternoon
+
+I want to make the argument rather than assume it, because I know what "DeFi" does to an enterprise audience's attention.
+
+Every hard problem in enterprise agents shows up in this domain first, in its most extreme form, because the consequences arrive in seconds instead of quarters. An agent that reads stale data, or states a mechanism confidently and wrongly, or reports an action it did not take, produces an irreversible financial loss within one block. There is no quarterly review that catches it. So the people building here have had to solve, under real pressure, the exact things the rest of us are still writing policy documents about: how you prove a number came from its source, how you record what an autonomous system did in a way nobody can quietly edit, how you make a system refuse to act until a human says yes, and how you keep an interface from projecting more confidence than its data has earned.
+
+They have not solved all of it. Section 7 is a story about them getting it badly wrong and then fixing it in public. That is exactly why it is worth reading. Most enterprise AI governance material I encounter is aspirational. This is a diff.
+
+### Being precise about who did what
+
+One more piece of precision, because "three partners" can be heard as something it is not.
+
+**IBM did not commission, sponsor, review, endorse, or co-build the three.ws and Sperax integration.** Two partner companies decided to build something, built it, and published the code. IBM's place in the triangle is real but specific: the partner relationships themselves, and the model layer the agent can run on. Nothing described in this post is an IBM product, an IBM deliverable, or an IBM endorsement. The developer tools three.ws publishes for exploring Granite are its own work. And this user group is a community space three.ws moderates on IBM's platform, not an IBM product either. I lead it, I work at IBM, and neither of those makes anything posted here an IBM release.
+
+One more, since the domain invites it: **this is not financial advice and it is not a product recommendation.** I picked this case study because decentralized finance is unusually hostile to a chat box, not because I am telling anyone to use it. There is no token in this post, no price, and nothing to buy.
+
+That precision is not a legal footnote. It is most of the reason the post is worth your time. This is what partner companies do on their own initiative, in the open, with the receipts left in, and you get to audit it rather than take a press release's word for it. I could not have written this article about a closed enterprise integration, and that is worth sitting with.
+
+### Why it belongs in this group
+
+Look at what this one integration actually touches, and then ask how many production engineering write-ups you have read on any of it:
+
+- **Real-time 3D as an application interface**, rather than as a demo or a game. An animated character rendered inside somebody else's product, driven by that product's live state.
+- **A high-stakes domain as an agent's workplace**, where the state changes every few seconds, most of it is numeric, and a confidently wrong answer costs money.
+- **On-chain identity for agents**, so the thing on your screen is bound to something verifiable rather than to a row in a private database.
+- **Machine-to-machine payment**, where one program pays another per call with no human in the loop.
+- **Enterprise foundation models underneath all of it**, which is the part of the stack this community actually works in.
+- **AR as the next surface for the same avatar**, which is not part of this integration and which I will flag again at the end so nobody misreads it as shipped.
+
+That list is close to word for word the remit this group was founded on: spatial reasoning, generative 3D, agentic pipelines, and real-time interactive AI. This case study is the browser-panel end of that spectrum. AR is the other end, and the same avatar walks between them.
+
+### One more thing, and then the engineering
+
+Decision management means I spend my working life on a single question: what happens when an automated decision is wrong, and who finds out. Agents with faces and voices made that question louder for me, not quieter. A chatbot that gives you a bad answer looks exactly like a chatbot giving you a good one. An agent with a *body* can look reassuring while it is wrong, and that is a genuinely new failure mode that our existing controls were not designed for.
+
+So I asked the three.ws team to walk me through how the integration works and to write it up honestly, including what broke. What follows is that walkthrough, checked against both repositories myself, with the parts I found most useful to this group kept and the parts that make the best announcement cut.
+
+---
+
+## 1. Why decentralized finance is the hard case for an agent interface
+
+Before any of the engineering, it is worth being specific about why this domain and not another. I did not pick it for the crypto. I picked it because it breaks the chat box in four distinct ways, and every one of them is a general lesson wearing a specific costume.
+
+**The state moves every block.** A number the agent read twelve seconds ago may already be wrong. A support chatbot answering from a knowledge base has no equivalent problem. Here, the gap between reading and acting is a risk window, and any interface that renders a value without rendering its age is quietly lying about how much it knows.
+
+**It is numerically dense and unit-hostile.** Amounts in the smallest indivisible unit against amounts in whole tokens. Contracts against coins. Annual percentage rate against annual percentage yield. Basis points. Prose flattens all of that: "your position is healthy" reads identically whether the underlying calculation used the right unit or was off by a factor of ten to the eighteenth. Section 7 is a real example of a units-shaped bug that survived into a shipped preview.
+
+**Actions are irreversible.** No chargeback, no undo, no support ticket that reverses a confirmed transaction. This is the property that makes an agent in this domain different in kind from an agent that drafts an email. An agent that is wrong ninety-nine times out of a hundred in a text box is annoying. Here, the hundredth is permanent.
+
+**The mechanics are protocol-specific, and models state them confidently anyway.** Two protocols can both use the word "staking" and compute completely different things underneath. A language model trained on the general internet will produce a fluent, plausible, wrong explanation of the specific one in front of it, and there is nothing in the sentence's texture to warn you. This is the single most important thing I took from the whole write-up, and it is why section 11 lists a maintained domain skill pack as a planned item rather than a nice-to-have.
+
+### What the agent actually does in there
+
+For anyone who has never opened this kind of workspace, the tool catalog is the fastest orientation. Grouped roughly as the repository groups them:
+
+| Category | What the agent can call |
+| --- | --- |
+| Trading | Swaps across aggregators, limit orders, route comparison |
+| Lending | Supply and borrow, health factor, liquidation watch |
+| Yield | Pool discovery, rate comparison, auto-compounding |
+| Analytics | Total value locked, protocol revenue, chain metrics, exchange volume |
+| Portfolio | Wallet tracking, profit and loss, allocation, gas history |
+| Market intelligence | Funding rates, sentiment indices, large-holder alerts, fund flows |
+
+That is 592 callable APIs across 99 packages, and the repository ships a machine-readable index of all of them that marks **which ones move funds**. I want to underline that, because it is the kind of thing that only exists when someone has thought about the problem seriously. A tool catalog that distinguishes "reads a number" from "spends your money" is a governance primitive, not documentation.
+
+The same instinct shows up in the SDK's execution model, which does not let an agent act and then tell you:
+
+```typescript
+// Async mode returns immediately so you can stream the agent's work.
+const { data } = await sperax.agent.runAsync({
+ prompt: 'Find the best USDC yield on Arbitrum and prepare a deposit',
+ maxSteps: 15,
+});
+
+for await (const event of sperax.agent.stream(data.operationId)) {
+ if (event.event === 'stream_chunk') process.stdout.write(event.data.content);
+}
+
+// The run pauses before acting; you decide whether it proceeds.
+await sperax.agent.approve(data.operationId);
+```
+
+Note the verb in the prompt: *prepare* a deposit. The run streams its reasoning, stops at the boundary where value would move, and waits for a human. Registering an agent on-chain works the same way: the API builds the calldata and never holds a key or broadcasts for you.
+
+### And this is where a body starts to earn its place
+
+Put those four properties together and you get an interface problem that is genuinely under-served by text.
+
+A dashboard reports state. A face reports *change in* state, pre-attentively, before you have read anything. When a position's health drifts from comfortable toward dangerous, the number moving from one value to another has to be noticed, parsed, and interpreted. An expression that has been holding concern for the last ten seconds is noticed before you read a single digit.
+
+That is the actual argument for embodiment here, and it is why section 7 matters more than the rendering. The channel only helps if what it is expressing is true.
+
+---
+
+## 2. What was actually built
+
+The host side is [SperaxOS](https://chat.sperax.io). The specifications, from its own repository: 99 built-in tool packages exposing 592 tool APIs, 63 of which are reachable from any MCP client, an agent runtime on Next.js with more than 70 model providers behind it, an on-chain agent registry, an Apache-2.0 license, and self-hosting through Docker. It is a serious piece of software, which matters here, because the interesting engineering constraints in this post all come from it being somebody's real product rather than a demo harness.
+
+The integration puts the three.ws agent inside it. In the chat panel, an agent has a body. It speaks, it gestures, and its facial expression and posture shift continuously in response to what its tools are actually doing.
+
+Here is what has shipped, as of this writing:
+
+| Surface | What it is |
+| --- | --- |
+| Standalone plugin | A hosted manifest at a well-known URL plus four LLM-callable tools. Install it in the host, paste an agent ID, done. |
+| Native component | The `three.ws` npm package mounted directly in the host's own React tree, no iframe. |
+| Inline 3D in a chat message | A markdown element that renders a live, orbitable model inside a reply. |
+| Emotion and lip-sync engines | Ported from three.ws into the host codebase, kept framework-agnostic so they are unit-testable. |
+| Hash-chained action ledger | Ported the same direction, with the reconcile job that checks it. |
+| Three packages ported the other way | Chain and token utilities, a typed tool-authoring SDK, and a market-data collector, all now running inside three.ws. |
+| A guided 3D site tour | An eight-stop template that exports as a single script tag. |
+
+\nThe rest of this post is what I learned reading how those were built.
+
+---
+
+## 3. The first design question is not the one you expect
+
+I assumed the hard question was "how do you render a 3D avatar inside an application you do not control." It is not. Rendering is a solved problem and the team spent very little time on it.
+
+The actual question is **who owns the React tree**, and it has two legitimate answers depending on the host.
+
+![Two integration paths for embedding an agent in a host application](./media/ibm-sperax-integration-paths.png)
+
+_Figure 1. The two integration paths, and what each one costs you._
+
+**Path one is for hosts that will not take your code.** Most plugin ecosystems will not let a third party ship JavaScript into the main bundle, and I think they are right not to. For those hosts, three.ws ships a standalone plugin: one hosted manifest, one hosted iframe, and a handful of HTTP endpoints. Nothing to vendor, nothing for the host's security team to review, no supply chain to audit. It is live in a day.
+
+**Path two is for hosts that want the dependency.** When a host is willing to take a package, an iframe is a downgrade. You lose shared context, you pay for a second renderer, and you cannot compose the avatar into anything the host renders itself.
+
+SperaxOS ended up in both camps at once, which is why the integration has both halves. If you are building something similar, the team's advice, which I would repeat, is: **ship the manifest first, because it gets you live and it works for hosts that will never take your code. Then do the native integration, because that is the one that finds your bugs.** More on that in section 5, and it is not a throwaway line.
+
+### The manifest, in full
+
+The whole of path one is one JSON file served with CORS:
+
+```
+https://three.ws/.well-known/sperax-plugin.json
+```
+
+Its shape:
+
+```jsonc
+{
+ "identifier": "three-ws",
+ "type": "standalone",
+ "ui": { "url": "https://three.ws/sperax/iframe/", "height": 480, "mode": "iframe" },
+ "settings": {
+ "type": "object",
+ "required": ["agentId"],
+ "properties": { "agentId": { "type": "string", "title": "Agent ID" } }
+ },
+ "api": [
+ { "name": "render_agent", "url": "https://three.ws/api/chat-plugin/render-agent", "...": "..." },
+ { "name": "speak", "url": "https://three.ws/api/chat-plugin/speak", "...": "..." },
+ { "name": "gesture", "url": "https://three.ws/api/chat-plugin/gesture", "...": "..." },
+ { "name": "emote", "url": "https://three.ws/api/chat-plugin/emote", "...": "..." }
+ ]
+}
+```
+
+Four tools, and I want to note what is *not* in that list. There is no `set_expression_to_happy`. The tools are `render_agent` to bind or swap the avatar, `speak` with an emotional valence in the range minus one to one, `gesture` for a named physical beat (wave, nod, point, shrug), and `emote` to blend a named feeling into a continuous emotional state. Only the last two touch the face, and neither of them sets it. They contribute to it. That distinction is section 6.
+
+The only required setting is a public agent ID. No API key, which is a design decision I appreciate: the plugin cannot leak a credential it never asks for.
+
+---
+
+## 4. Every tool call runs in two halves
+
+This is the piece I would put on a slide if I were teaching this.
+
+![Every tool call runs in two halves, in parallel](./media/ibm-sperax-tool-call-halves.png)
+
+_Figure 2. Both halves run on every call. The split is what keeps the model from asserting things it cannot know._
+
+When the model calls `speak`, two things happen in parallel. The host frames the plugin's panel and posts the call into it, and the avatar speaks. Separately, the host's plugin gateway POSTs the same arguments to the tool's HTTP endpoint, and that endpoint returns a short result the model reads back into its own context.
+
+Why bother with both? Because **the model must never be the thing that asserts the avatar moved.** If the model simply says "I waved" and the panel silently failed, the transcript now contains a false statement that the model will happily build on for the rest of the conversation. Splitting the halves means the model receives a result saying the wave was dispatched, and the panel is the thing that actually waved. The two can be compared.
+
+That is not a hypothetical. It is exactly the bug they shipped first, and the fix is my favorite twenty lines in either repository:
+
+```js
+async function resolveAgent(agentId) {
+ if (!isUuid(agentId)) return { known: true, name: null };
+ try {
+ const [row] = await sql`
+ SELECT name FROM agent_identities
+ WHERE id = ${agentId} AND deleted_at IS NULL
+ LIMIT 1
+ `;
+ if (!row) return { known: false, name: null };
+ return { known: true, name: typeof row.name === 'string' ? row.name : null };
+ } catch (err) {
+ console.warn('[chat-plugin] agent lookup failed, binding unverified:', err?.message);
+ return { known: true, name: null };
+ }
+}
+```
+
+The original version confirmed any agent ID it was handed. Someone with a typo in their settings got a model cheerfully announcing "I have bound to your agent" over a permanently empty panel. There is no error anywhere. The system is behaving exactly as written, and it is lying.
+
+Three behaviors in the fix are deliberate, and I would defend all three in a design review:
+
+1. **A well-formed ID that does not exist comes back as a real error**, one the model can explain, pointing the user back to their dashboard to recopy it.
+2. **A handle or manifest ID passes through unverified**, because the browser element resolves those and the server has no business pretending it checked something it did not.
+3. **A database outage degrades to an unverified binding instead of a 500.** An infrastructure problem on one side must never take down the other side's chat panel.
+
+That third one is the decision-management instinct showing, and I was glad to see it in someone else's code. The failure mode of a dependency should be proportional to what the dependency actually does. A name lookup being unavailable is not a reason to break a conversation.
+
+One small practical note that will save somebody an afternoon: hosts rename the settings header. LobeChat sends `lobe-chat-plugin-settings` and SperaxOS sends `Sperax-Plugin-Settings`. Read both.
+
+---
+
+## 5. The native path is where the real bugs live
+
+Path two is a dependency and a mount:
+
+```tsx
+// three.ws registers <agent-3d> via customElements.define(...)
+useEffect(() => {
+ if (typeof window !== 'undefined' && !window.VIEWER) window.VIEWER = {};
+ import('three.ws').then(() => {
+ customElements.whenDefined('agent-3d').then(() => setRegistered(true));
+ });
+}, []);
+```
+
+Six lines, two scars, and both are worth your time even if you never touch 3D.
+
+**The dynamic import is not a style choice.** The package shipped `sideEffects: false` in its manifest. For a package whose entire job is a `customElements.define` side effect, that field is simply false, and a production bundler believed it: the registration was tree-shaken away and the element silently never upgraded. Not an error, not a warning, just an element that stays inert. The host now carries a patch for the flag *and* imports dynamically, because dynamic imports are never tree-shaken. **If you publish a custom element, go check that field right now.**
+
+**The `window.VIEWER` seed is the other one.** The library assigned to `window.VIEWER.json` during model boot without ever initializing the global. In three.ws's own pages the global happened to exist. In someone else's application it did not, and boot threw a `TypeError`.
+
+Neither of those is findable from inside your own product. That is the whole argument for doing the native integration even after the iframe works: the iframe protects you from the host, and it also protects you from learning what your package does in a world you did not build.
+
+Once the component is native, it composes in ways the iframe cannot. The host added a markdown plugin so a chat message can contain a live model:
+
+```html
+<avatar3d url="https://.../model.glb" size="260" clip="Wave" zoom="true" />
+```
+
+That renders in the same React tree, no iframe, no sandbox, and the model can come from anywhere. An agent answering "what does this thing look like" can now answer with the thing.
+
+There is also a client lane in the tool router, which I had not thought about before reading this. Animation control cannot round-trip through a server without the animation being late, so a dispatcher intercepts the calls that belong to the browser before the rest go server-side:
+
+```ts
+const CLIENT_TOOL_IDS = new Set(['agent-3d-controls', 'get-available-animations']);
+
+for (const tool_call of params.tool_calls) {
+ if (CLIENT_TOOL_IDS.has(tool_call.function.name)) params.onClientToolCall(tool_call);
+ else serverToolCalls.push(tool_call);
+}
+```
+
+Obvious once you see it. Worth stealing if your agent controls anything with a frame rate.
+
+---
+
+## 6. Emotion as a continuous blend, not a state machine
+
+Here is the part I expected to find cosmetic and did not.
+
+The obvious way to build an expressive avatar is a state machine: happy, sad, thinking, alarmed. It takes about thirty seconds of real use to see why that is wrong. The avatar snaps between moods, and the snap reads as a cartoon. Worse, for a monitoring interface, a state machine has to *choose*, and the truth is usually a mixture.
+
+The approach both teams now share is a continuous weighted blend. Each emotion is a float between zero and one. Events spike it. It then decays exponentially, at its own rate, every frame. All active emotions are blended into facial morph targets and body language on every frame, so a face can be forty percent concerned, thirty percent curious, and thirty percent neutral at the same time, which is how faces actually work.
+
+![The five emotion decay curves and a blended face at one moment](./media/ibm-sperax-empathy-decay.png)
+
+_Figure 3. The five decay curves. Each dot marks where a full spike has fallen to the floor value and the emotion is treated as inactive._
+
+The ported definition table doubles as the design document, and the comments are the original author's:
+
+```ts
+export const EMOTION_DEFINITIONS: Record<EmotionName, EmotionDef> = {
+ // Positive sentiment or success: a warm, open smile.
+ celebration: { decaySeconds: 6, morphs: { jawOpen: 0.2, smile: 0.85 } },
+ // Negative sentiment or tool error: a worried frown with raised inner brows.
+ concern: { decaySeconds: 12, morphs: { browInnerUp: 0.6, frown: 0.55 } },
+ // Loading or processing: an inquisitive head tilt.
+ curiosity: { decaySeconds: 8, headTiltZ: 0.12 },
+ // Emotional or supportive moments: a soft, squinting, caring look.
+ empathy: { decaySeconds: 13, morphs: { browInnerUp: 0.5, eyeSquint: 0.4 } },
+ // Long-running operations: a patient backward lean.
+ patience: { decaySeconds: 20, leanX: -0.08 },
+};
+```
+
+**The decay rates carry the entire personality, and they are deliberately not uniform.** Celebration is bright and brief at six seconds. Concern lingers at twelve, so a risk that appeared while you were looking away is still on the face when you look back. Patience runs twenty, so an agent waiting on a slow operation keeps *looking* like it is waiting instead of going blank. Empathy is the slowest of the soft states at thirteen, because empathy that switches off the instant a sentence ends reads as insincere, and it turns out that is true of rendered faces too.
+
+Two implementation choices are what make this maintainable rather than a pile of magic numbers:
+
+**Keep the engine pure.** The emotion module has no 3D library and no React in it. It maps time and spikes to logical morph weights, and a separate module resolves those logical names onto whatever concrete blendshapes the loaded mesh happens to have. So the emotion model is unit-testable with no renderer, and it ported cleanly between two codebases that share no UI framework. If you take one architectural idea from this post, take this one: **the interesting part of your system should not import your rendering layer.**
+
+**Compose, do not multiplex.** Speech drives the mouth through an entirely separate path. A Web Audio analyser samples the speech waveform each frame and maps a smoothed amplitude onto the jaw channel, gated below a noise floor so room hum does not make the avatar chew, saturating well before a full open so it never gapes:
+
+```ts
+const NOISE_GATE = 0.02;
+const FULL_OPEN_RMS = 0.22;
+const MAX_JAW = 0.7;
+```
+
+Because articulation and emotion write to different logical channels and are summed, the agent can deliver bad news *while looking concerned about it*. A state machine would have to pick one.
+
+---
+
+## 7. The part that actually matters, and it is not the rendering
+
+Now the section I asked for, and the reason I wanted this written up at all.
+
+**An expressive avatar sitting on top of wrong data is not a nice interface. It is a confident liar, and it is worse than a table of numbers, because a table does not lean toward you and look reassuring.**
+
+They learned this the direct way, and to their credit the commit history says so in plain language.
+
+The SPA staking panel in the host application, and the chat tools behind it, were returning literals. Total SPA locked: zero. Total veSPA supply: zero. Average lockup: zero. The four-year staking rate: a hardcoded `22.61`, with a source comment that said, and I am quoting the code, "from app screenshot." Because two of those were zero, the panel's own has-data check failed and it rendered dashes in every field. The agent, meanwhile, would narrate the number that had been copied off a screenshot months earlier, with a face on.
+
+The fix reads the contracts instead:
+
+- Total locked and escrow supply now come from live `totalSPALocked()` and `totalSupply()` calls on the voting-escrow contract. At the time of the fix that was 242.66 million SPA locked against 416.78 million veSPA.
+- The rate is derived from the rewarder contract's `rewardsPerWeek` over a trailing eight-week window, landing at 21.0 percent at maximum lock. Close to the number that had been copied, which is exactly the point: it is now sourced and auditable rather than coincidentally near-correct. The eight-week window exists because emissions funding is irregular enough that any single week is noise.
+
+The worse bug was in the estimator, and this is the one I would use in a decision-integrity training session. It is also section 1's fourth property in the flesh. Both call sites computed voting power with the linear `amount * lockSeconds / MAXTIME` slope that a *different* well-known vote-escrow design uses. Same word, same general idea, different math: this escrow mints one veSPA per SPA per **year** locked, capped at four years. Someone locking 1,000 SPA for four years was shown an estimate of roughly 1,000 veSPA and would actually have received roughly 3,984.
+
+A four-fold understatement. In a preview. Next to an avatar nodding encouragingly.
+
+It is now a shared helper backing both the dashboard panel and the chat tool preview, verified against the contract's own `estimateDeposit` at six different lock lengths, and pinned by tests so it cannot drift back.
+
+The rule that came out of it, and which I think generalizes far past this domain:
+
+> **The avatar may only express state it can prove.** If a number cannot be read from its source of truth, the correct behavior is a visible unknown, not a confident face over a stale literal.
+
+I would go further, from the decision-management side. Embodiment raises the cost of being wrong, because it raises the user's trust before the data has earned it. Every project in this group that puts a face on an agent is quietly taking on that liability. It is worth deciding, on purpose and in advance, what your avatar does when it does not know.
+
+---
+
+## 8. Failing honestly, including about other people's systems
+
+A smaller story, same principle, opposite direction.
+
+While embedding the partner's own application in a frame, a probe fetched the target and received a `403`, so the page hid the embed and told the user the site had refused framing.
+
+The site had refused nothing. Its bot protection challenges every datacenter address, and the probe was running on one. The giveaway is that a plain top-level request, a static asset, and a path that does not exist all returned the same `403`, which has nothing to do with framing. The header being read as a framing policy belonged to the challenge page, not to the application.
+
+The probe now sends an unframed control request alongside the framed one, and only trusts a framing refusal when the control was actually served. On a challenged network it reports `UNKNOWN` and exits with a distinct code.
+
+**A negative result from a network you do not control is not a fact about the other system.** I have watched teams write a permanent configuration change on exactly this kind of evidence. Reporting "I could not tell" is a feature.
+
+---
+
+## 9. Provenance, for a body that can move money
+
+Once an embodied agent can execute rather than only explain, expressiveness stops being the interesting problem and provenance starts.
+
+three.ws had built a hash-chained ledger for its own agent activity, and the host ported the primitive: an append-only, SHA-256 hash-chained record of every value movement an agent initiates, where each entry commits its predecessor.
+
+```
+entryHash = sha256( canonicalFields(entry) || prevHash )
+```
+
+Each user owns an independent chain. Sequence numbers are per-user and monotonic from one, the first entry commits a genesis hash of sixty-four zeros, and the canonical serialization is a fixed field order with free-text detail folded in through a key-sorted stringify, so identical payloads always hash identically.
+
+The field separator is a NUL byte, and the reasoning is the sort of detail that decides whether a scheme is sound or decorative. Two of the committed fields are free text and can contain spaces. With a printable separator the encoding is ambiguous: two different field tuples could serialize to the same string, and a chain built on an ambiguous encoding proves nothing at all. A NUL cannot occur in any of the values, so the serialization is injective and the hash means what it claims.
+
+Editing or deleting any historical row breaks the chain from that point forward. A reconcile job runs on a schedule looking for two things: a chain break, and an on-chain movement that was never recorded. **The second alarm is the interesting one.** A value movement with no corresponding ledger entry is the signal that a key is being used outside the agent runtime, which is to say it is a breach detector wearing an accounting hat.
+
+What did *not* get ported is as deliberate as what did. The origin system's signing keys, its price oracle, and its multi-wallet funding topology all stayed behind, because the receiving system has different custody and its own valuation source. A port that drags its origin's assumptions along with it is not a port, it is a fork with extra steps.
+
+For an agent with a face, this is the other half of trustworthiness. The emotion layer makes the agent legible in the moment. The ledger makes it accountable afterward. You need both, and I would argue the second one is the part that lets a regulated organization say yes to the first.
+
+---
+
+## 10. The code went both ways, and that is the part I would negotiate for
+
+Here is what surprised me most, and it is a partnership observation rather than a technical one.
+
+![What was ported in each direction between the two codebases](./media/ibm-sperax-code-exchange.png)
+
+_Figure 4. What moved which way. The right-hand column is the half nobody writes a press release about._
+
+**Into the host from three.ws:** the emotion engine, the lip-sync driver, the inline 3D markdown element, the client-side tool dispatcher, and the hash-chained ledger with its reconcile job.
+
+**Into three.ws from the host:**
+
+- A zero-dependency single source of truth for chain and token constants, minimal contract interface fragments, and address and amount validation. The existing maps were kept verbatim and a section was added for a chain the origin did not cover.
+- A typed tool-authoring layer, derived from the host's plugin SDK. One call declares a tool's identity, its schemas, and its permission manifest, and derives the machine-readable schema automatically. A second call wires a typed implementation onto it and routes every invocation through a single entry point that validates parameters, enforces the declared rate limit, and normalizes both success and failure into one shape. A third adapts the result into the exact registration shape the receiving project's MCP servers already use, so adopting it is one call instead of a rewrite. It was rewritten from TypeScript into plain ESM with JSDoc to match the receiving codebase's conventions, and re-scoped away from chat-interface concepts it no longer needed.
+- A market-data collector, since hardened considerably: per-topic subscription acknowledgements on one exchange whose retired topic used to fail silently, a unit conversion on another whose raw size field counts contracts rather than units, a geographic restriction probe on a third, and per-lane health reporting. It runs as a standalone always-on service because it holds long-lived WebSockets, and the proxy in front of it returns a 503 when the collector is unreachable rather than inventing numbers, which is the same principle as section 7 wearing different clothes.
+
+If you are ever in the room where an integration is being negotiated, **this is the clause to push for: a shared right to port implementation between the two codebases.** Two teams working on adjacent problems produce more reusable primitives than either will build alone, and a partnership you can measure in merged commits ages a great deal better than one you can only measure in announcements.
+
+---
+
+## 11. What is planned, stated as plans and not as shipping claims
+
+I asked for this list explicitly and I am labeling it clearly, because I do not want anything here read as available today.
+
+Shipped and live: everything in the table in section 2.
+
+Designed, in progress, or proposed:
+
+1. **Compute endowments.** USDs, the Sperax stablecoin, pays yield to whoever holds it, automatically, with no staking step: the balance grows in the wallet. The idea is that you deposit once and that yield stream funds an agent's compute balance indefinitely, so the agent never runs out of inference budget. Set the domain aside for a second and look at the shape of it: it is a real answer to "who pays for this agent's inference in year three," and it needs no new financial mechanism, only new plumbing between an existing yield stream and an existing credit ledger. I find that the most interesting idea on the list, as an agent-economics question, independent of the asset involved.
+2. **A recurring credit grant keyed to holdings** rather than a one-time claim, so the relationship is retention rather than a giveaway.
+3. **A second settlement asset** on the machine-to-machine payment rails that already handle per-call settlement over the x402 HTTP payment scheme.
+4. **A domain skill pack**, so an agent reasons about the specific protocol mechanics from a maintained source rather than approximating them from training data. The voting-power bug in section 7 is precisely the failure a real skill pack prevents, which is why I think this one matters more than it sounds.
+5. **The guided site tour deployed on the live partner site.** The template exists and exports as a single script tag. A builder preview can only prove the mechanics, so the real test is the deployment.
+
+---
+
+## 12. What I would like from this group
+
+A few things, and then the links.
+
+**If you have embedded an agent into somebody else's application, tell us which path you took.** Section 3 is the fork in the road, and I would like the group's collective experience on it. My suspicion is that most people reach for the iframe and never do the native version, and therefore never find their equivalent of the `sideEffects` bug.
+
+**If you publish a web component, go and check your `sideEffects` field.** That is the single most immediately actionable thing in this post and it takes ninety seconds.
+
+**If you put a face on an agent, decide now what it does when it does not know.** Section 7 is my honest reason for publishing this. I would rather this group be known for building agents that are legible about their uncertainty than for building agents that are charming about it.
+
+**And the AR question I promised to come back to.** Everything above happens in a rectangle on a screen. The same rigged avatar, the same emotion blend, the same tool calls, can also be placed in a room through a phone camera, and three.ws ships that surface separately. It is not part of this integration and I am not going to pretend it is. But every argument in section 7 gets sharper when the agent is standing in your kitchen instead of sitting in a panel, because the trust an embodied thing borrows from being *present* is larger again. If somebody in this group wants to be the first to put a domain-grounded agent into AR and write up what broke, I will give that post the front of the group and I will bring the questions to both teams myself.
+
+And if you want to try any of it, none of the following requires an account with anyone, and the generation step requires no key at all:
+
+- Generate a rigged, animation-ready avatar from a sentence at [three.ws/create](https://three.ws/create), or a static model at [three.ws/forge](https://three.ws/forge).
+- Embed it with the documented custom element at [three.ws/docs/embedding](https://three.ws/docs/embedding), or install the package if you want it natively in a React tree.
+- Read [the plugin manifest itself](https://three.ws/.well-known/sperax-plugin.json). It is the shortest complete description of the four-tool interface, and the pattern transfers to any host of the same lineage.
+- The integration write-up from the three.ws side is at [three.ws/sperax](https://three.ws/sperax), and the host application is Apache-2.0 at [github.com/nirholas/sperax](https://github.com/nirholas/sperax) if you want to read the receiving half.
+
+Back to the third corner of the triangle, with one practical note. The agent brain is provider-agnostic on both sides of this integration, so pointing it at IBM Granite through watsonx.ai changes nothing about the rest. The emotion engine in section 6 takes its spikes from tool-call outcomes and sentiment rather than from any provider's output format, and the four plugin tools are plain HTTP. Your model choice is genuinely orthogonal to the body, which is the property that makes the whole stack swappable. If you are wiring an embodied agent to Granite and you hit something ugly, post it here. That is what the group is for.
+
+I will bring the harder questions from this thread back to the three.ws team, the same way I did for the meetup Q&A. The skeptical ones are still the most useful ones.
diff --git a/docs/ibm-community-defi-3d-sperax-publishing-kit.md b/docs/ibm-community-defi-3d-sperax-publishing-kit.md
new file mode 100644
index 000000000..f63522d7b
--- /dev/null
+++ b/docs/ibm-community-defi-3d-sperax-publishing-kit.md
@@ -0,0 +1,161 @@
+# Publishing kit: the Sperax integration post on IBM Community
+
+Everything the **Post to Blog** form asks for, in the order it asks. The article
+itself is [ibm-community-defi-3d-sperax.md](./ibm-community-defi-3d-sperax.md);
+these are only the form values and the sequence that puts it live cleanly.
+
+Rebuild the three output files after any edit to the draft:
+
+```bash
+node scripts/build-ibm-community-post.mjs
+```
+
+---
+
+## 1. Title of Your Blog Entry
+
+```
+Sperax, three.ws, and IBM Granite: giving a DeFi agent a body, a brain, and a reason to trust it
+```
+
+## 2. Permalink
+
+IBM allows letters, numbers, and dashes, and truncates long slugs (the group's
+existing posts show cuts around 49 characters). This one is 38, so it survives
+whole and carries all three names:
+
+```
+sperax-three-ws-ibm-granite-defi-agent
+```
+
+Full URL it produces:
+`https://community.ibm.com/community/user/blogs/jessica-swanson/2026/09/10/sperax-three-ws-ibm-granite-defi-agent`
+
+## 3. Category
+
+`Blog Post` (the form's default, no change needed).
+
+## 4. Body
+
+**Use the editor's `HTML` button, do not paste rendered text.** Pasting from a
+browser carries local image paths that resolve for nobody, and the editor
+silently drops the stylesheet that formats the code blocks.
+
+There are two fragments. Pick one.
+
+### Option A: `-post-ibm.html` (works today, five manual uploads)
+
+Images are left as labelled placeholder lines you replace by hand with the
+editor's image button. Nothing has to be deployed first. This is the safe path.
+
+### Option B: `-post-ibm-hosted.html` (one paste, zero uploads, needs a deploy)
+
+Every figure points at its public three.ws URL under
+`https://three.ws/ibm-sperax/`, and section 2 carries a **live** avatar
+panel framed from `https://three.ws/sperax/iframe`, the same URL SperaxOS itself
+frames. Not a screenshot: the actual plugin panel, running in the post.
+
+That is possible because three.ws already serves
+`frame-ancestors 'self' https://ibm.com https://*.ibm.com`, so community.ibm.com
+is allowlisted to frame it.
+
+Two prerequisites, both real:
+
+1. **The images must be deployed.** They are staged in
+ `public/ibm-sperax/` but a production deploy has to land before those URLs
+ resolve. Paste this fragment before that and every figure is a broken image.
+2. **The editor's sanitizer has to allow `<iframe>`.** three.ws permits the frame;
+ whether IBM's editor keeps the tag is not something that can be tested without
+ posting. Paste, save, and look at the preview. If the frame is gone, delete the
+ surrounding block and fall back to Option A for that one spot; the rest of the
+ fragment is unaffected.
+
+1. Open your chosen fragment ([Option A](./ibm-community-defi-3d-sperax-post-ibm.html) or [Option B](./ibm-community-defi-3d-sperax-post-ibm-hosted.html)) in a text editor.
+2. Select all, copy.
+3. In the blog form, click **HTML** in the second toolbar row.
+4. Paste, then save/close the HTML view.
+
+That fragment is built for this editor specifically: no document shell, no `<h1>`
+(the Title field above is the headline), no byline (the post shows its own author
+and group), and every style that matters inlined on the element, so code blocks,
+the comparison table, and the pull quote survive.
+
+### 5 images to place (Option A only)
+
+The fragment leaves five blue dashed placeholder lines, each naming the file to
+upload at that spot. For each one: click the line, use the **image** button in
+the toolbar to upload the named file from `docs/media/`, then delete the
+placeholder line.
+
+| Placeholder | File | Where it lands |
+| --- | --- | --- |
+| HEADER IMAGE | `ibm-sperax-featured.png` | Very top, above section 0 |
+| FIGURE 1 | `ibm-sperax-integration-paths.png` | Section 3, above the "Figure 1." caption |
+| FIGURE 2 | `ibm-sperax-tool-call-halves.png` | Section 4 |
+| FIGURE 3 | `ibm-sperax-empathy-decay.png` | Section 6 |
+| FIGURE 4 | `ibm-sperax-code-exchange.png` | Section 10 |
+
+The italic caption under each figure is already in the body. Leave it there.
+
+## 4b. Featured image
+
+Use `docs/media/ibm-sperax-featured.png` (2400x1200): the three partner logos on
+white, nothing else.
+
+It is built for IBM's stated guidance on that field. Landscape and well over the
+1200x600 minimum. No text beyond the logos themselves, since IBM warns that the
+card crops differently across the community and text does not survive it. The row
+is centred with even margins on all four sides (roughly 210px left and right, 516px
+top and bottom), so a tighter crop loses only white space.
+
+Do **not** use the older `ibm-x-threews-lockup.png` here. It carries only IBM and
+three.ws, and this post is about three parties.
+
+Regenerate with `node scripts/render-ibm-sperax-featured.mjs`. It crops the IBM
+mark out of the existing lockup and reads the other two logos from the three.ws
+brand folder and the SperaxOS checkout, so no trademark asset is duplicated into
+this repo.
+
+## 5. Search Engine Optimization (click **Show**)
+
+Meta description, 156 characters:
+
+```
+The best material on automated-decision integrity I read this year came from two crypto Business Partners. Sperax, three.ws, IBM Granite, and one DeFi agent.
+```
+
+Keywords, if the field is offered:
+
+```
+embodied AI agents, 3D avatars, DeFi agents, decentralized finance, agent interfaces, web components, watsonx.ai, IBM Granite, MCP, agent governance, decision integrity
+```
+
+## 6. Association and visibility
+
+| Field | Value | Note |
+| --- | --- | --- |
+| Associate this post with a group | Three.ws User Group | Already selected. |
+| Who can read your blog entry? | **Reconsider "Selected Group"** | The screenshot shows `Selected Group`, which limits the post to group members. Every earlier post in this group is publicly readable, which is what earns it search traffic and lets non-members find the group. Switch to the public/all-members option unless the intent is a members-only piece. |
+| Who can make comments on this? | Members Only | Fine as set. |
+
+---
+
+## Before publishing
+
+- **Confirm the partner-status line.** The post opens by stating that Sperax is
+ also an IBM Business Partner. That came from the three.ws side and is not
+ independently evidenced here. It is written in the plainest possible form, with
+ no tier, program name, or date attached, so a correction is a one-word edit.
+ Confirm the wording Sperax uses for its own status first.
+- **Do not let section 0 become "why IBM partnered with these companies."** Jessica is
+ making a personal, professional case as a decision-management practitioner. She does
+ not own IBM's partnership strategy and must not appear to narrate it. This is the
+ riskiest edit anyone could make to the draft.
+- **Keep the "Being precise about who did what" subsection.** Section 0 opens on a
+ triangle of three real relationships (three.ws with Sperax, both with IBM, and the
+ runtime on Granite through watsonx.ai), and that subsection is what stops a reader
+ collapsing it into "IBM built this." The sentence beginning "IBM did not commission,
+ sponsor, review, endorse, or co-build" is the load-bearing one. It is the first
+ thing an editor would cut for flow and the one thing that must stay.
+- **Check the five figures rendered** in the preview before hitting publish. A
+ leftover placeholder line is the most likely thing to slip through.
diff --git a/docs/ibm-community-defi-3d-sperax.md b/docs/ibm-community-defi-3d-sperax.md
new file mode 100644
index 000000000..9679d4dd3
--- /dev/null
+++ b/docs/ibm-community-defi-3d-sperax.md
@@ -0,0 +1,542 @@
+---
+title: "Sperax, three.ws, and IBM Granite: giving a DeFi agent a body, a brain, and a reason to trust it"
+venue: IBM Community, Three.ws User Group (blog post)
+author: Jessica Swanson (IBM, Operational Decision Manager, AI & Data Science), group leader of the Three.ws User Group
+status: draft, not yet posted
+description: "An IBM decision-management practitioner makes her own case for why the best material on automated-decision integrity she has read this year came from two crypto Business Partners. Sperax gives the agent a DeFi domain, three.ws gives it a body, IBM Granite can be its brain. Both partner codebases are public, so this is a diff rather than a policy document."
+media:
+ - "Featured image: media/ibm-sperax-featured.png (2400x1200, the three partner logos on white). Rendered by `node scripts/render-ibm-sperax-featured.mjs`. IBM Community asks for landscape, at least 1200x600, and warns against text because the card crops differently across the site; this is logos only, centred, with even margins on both axes so a tighter crop loses only white. The older ibm-x-threews-lockup.png is NOT the right choice here: it omits Sperax."
+ - "Figure 1: media/ibm-sperax-integration-paths.png (2000x930)"
+ - "Figure 2: media/ibm-sperax-tool-call-halves.png (2000x894)"
+ - "Figure 3: media/ibm-sperax-empathy-decay.png (2000x942)"
+ - "Figure 4: media/ibm-sperax-code-exchange.png (2000x957)"
+ - "All four figures are regenerated by `node scripts/render-ibm-sperax-diagrams.mjs`. Upload them inline in the IBM Community editor at the points where the body embeds them, and keep the italic caption under each one."
+publish: |
+ `node scripts/build-ibm-community-post.mjs` strips this frontmatter and every
+ editor note and writes the two files the author publishes from:
+
+ docs/ibm-community-defi-3d-sperax-post.md the clean article body
+ docs/ibm-community-defi-3d-sperax-post.html the same body, styled
+
+ This file stays the source of truth; edit it, then rebuild, so the two outputs
+ cannot drift from it or from each other. To publish: open the .html in a browser,
+ select all, copy, and paste into the IBM Community blog editor. Then re-upload the
+ five images through the editor (a pasted local file reference will not resolve for
+ readers) and set the lockup as the featured image. Hand the .md to anyone who wants
+ the text rather than the formatting.
+framing_notes: |
+ Every framing rule in docs/ibm.md applies to this draft and must survive any edit:
+ three.ws is an IBM Business Partner, the platform integration runs agents on IBM
+ Granite through watsonx.ai using the reader's own IBM Cloud credentials, and the
+ /api/ibm/* surfaces plus the open-source connector are independent developer tools,
+ not IBM products, not partnership deliverables, and not endorsed by IBM. The user
+ group itself is a community space three.ws moderates on IBM's platform, not an IBM
+ product. Section 0 carries that disclosure in Jessica's own words; do not cut it.
+
+ THREE-WAY CLAIM: the post opens on a triangle of three real but DIFFERENT
+ relationships, and they must stay distinguishable in any edit:
+ 1. three.ws and Sperax are partners with each other and shipped this integration.
+ 2. Both are IBM Business Partners. (Sperax's status comes from the owner, not from
+ anything in this repository. It is stated with no tier, no program name and no
+ date attached, because those are the details that get corrected. Confirm the
+ wording Sperax uses for its own status before publishing.)
+ 3. The three.ws runtime runs on IBM Granite through watsonx.ai with the reader's
+ own IBM Cloud credentials.
+ What is NOT true, and what the draft explicitly denies, is that IBM commissioned,
+ sponsored, reviewed, endorsed or co-built the integration. "Three partners" and
+ "IBM built this" are different claims. Never let an edit collapse them.
+
+ Per the group's posting rules (docs/ops/seo-keyword-plan.md), crypto-cluster content
+ belongs on three.ws/blog instead. This draft is written to clear that bar: it is an
+ engineering article about embedding embodied agents in a host application, using a
+ finance workspace as the case study. It carries no token, no ticker, no price, and no
+ launch. If it has to be trimmed further, cut section 11 (what is planned) first, since
+ that is the part closest to partnership marketing.
+
+ Jessica is an IBM employee writing in her own voice as the group's leader. She must
+ never be made to speak for three.ws or Sperax, and never to endorse a financial
+ product. Keep every first-person claim to things she can actually attest: what she
+ read, what she asked, what she thinks. Attribute engineering decisions to the two
+ engineering teams.
+
+ WHY SHE IS THE AUTHOR: section 0 answers this deliberately, and the answer must not
+ drift. She is NOT explaining IBM's partnership strategy. An Operational Decision
+ Manager in AI & Data Science does not own that decision and must not narrate it on a
+ community blog. Her stated reason is personal and professional: her field is
+ decision integrity, and this is the best real-world material on it she has read. Any
+ edit that turns "here is my case as a practitioner" into "here is why IBM partnered
+ with these companies" makes her speak for IBM on something she does not own, and is
+ the single riskiest change anyone could make to this draft.
+
+ The title says "IBM Granite" rather than "IBM" on purpose. A bare "IBM" between two
+ crypto company names reads as a corporate endorsement; "IBM Granite" names a
+ technology in the stack, which is precisely and only what it is.
+---
+
+# Sperax, three.ws, and IBM Granite: giving a DeFi agent a body, a brain, and a reason to trust it
+
+_By Jessica Swanson. Posted in the [Three.ws User Group](https://community.ibm.com/community/user/groups/community-home?communitykey=e71510cc-d953-408f-9a1c-019f5c0a7016) on IBM Community._
+
+![Sperax, three.ws, and IBM](./media/ibm-sperax-featured.png)
+
+_[Editor note, not for publication: upload the image above as the blog's featured image.]_
+
+---
+
+## 0. An IBM employee writing about two crypto companies
+
+I work at IBM. I am about to publish six thousand words about two crypto companies. I want to deal with that up front, because it is the first thing I would think if this turned up in my feed.
+
+IBM has thousands of Business Partners. Two of them, Sperax and three.ws, are also partners with each other, and they shipped something together that I think is the most complete piece of embodied-agent engineering I have read this year. I am not here to explain IBM's partnership strategy. That is not my job, not my call, and not something any one employee should narrate on a community blog. I am here for a much narrower reason, and it is entirely my own:
+
+**My job at IBM is decision management. The best real-world material on automated-decision integrity I have read in months arrived from a direction nobody in my part of the industry is looking.**
+
+That is the whole pitch. If you skip everything else, read section 7.
+
+### The triangle, drawn plainly
+
+Three relationships, all real, all different, and they close around one agent:
+
+- **Sperax and three.ws are partners with each other**, and they built the integration this post is about.
+- **Both are IBM Business Partners.**
+- **The three.ws agent runtime runs on IBM Granite models through watsonx.ai**, using your own IBM Cloud credentials.
+
+Split by what each side actually contributes and the shape is clean:
+
+- **three.ws gives the agent a body.** A rigged, animated 3D avatar you can generate from a sentence, drop into any web page with one custom element, or place in a room through a phone camera with AR. It speaks, it gestures, and its expression changes with what it is doing.
+- **Sperax gives the agent a domain, and the domain is decentralized finance.** An open-source AI agent workspace where an agent can swap, lend, borrow, hunt yield, and watch a position toward liquidation, across 99 built-in tool packages exposing 592 tool APIs against live protocols. Somewhere real to act, where being wrong costs money in the same block.
+- **IBM Granite can be the agent's brain.** The three.ws runtime is model-agnostic and runs Granite through watsonx.ai on your own credentials, so the reasoning layer is enterprise-grade and stays yours.
+
+Body, domain, brain. Read one at a time those are three product announcements. Read together they are the most complete end-to-end example I have seen of what an embodied enterprise agent actually costs to build, and because both partner codebases are public, this group can read every line of it, including the parts that went wrong.
+
+### Why this is worth an enterprise reader's afternoon
+
+I want to make the argument rather than assume it, because I know what "DeFi" does to an enterprise audience's attention.
+
+Every hard problem in enterprise agents shows up in this domain first, in its most extreme form, because the consequences arrive in seconds instead of quarters. An agent that reads stale data, or states a mechanism confidently and wrongly, or reports an action it did not take, produces an irreversible financial loss within one block. There is no quarterly review that catches it. So the people building here have had to solve, under real pressure, the exact things the rest of us are still writing policy documents about: how you prove a number came from its source, how you record what an autonomous system did in a way nobody can quietly edit, how you make a system refuse to act until a human says yes, and how you keep an interface from projecting more confidence than its data has earned.
+
+They have not solved all of it. Section 7 is a story about them getting it badly wrong and then fixing it in public. That is exactly why it is worth reading. Most enterprise AI governance material I encounter is aspirational. This is a diff.
+
+### Being precise about who did what
+
+One more piece of precision, because "three partners" can be heard as something it is not.
+
+**IBM did not commission, sponsor, review, endorse, or co-build the three.ws and Sperax integration.** Two partner companies decided to build something, built it, and published the code. IBM's place in the triangle is real but specific: the partner relationships themselves, and the model layer the agent can run on. Nothing described in this post is an IBM product, an IBM deliverable, or an IBM endorsement. The developer tools three.ws publishes for exploring Granite are its own work. And this user group is a community space three.ws moderates on IBM's platform, not an IBM product either. I lead it, I work at IBM, and neither of those makes anything posted here an IBM release.
+
+One more, since the domain invites it: **this is not financial advice and it is not a product recommendation.** I picked this case study because decentralized finance is unusually hostile to a chat box, not because I am telling anyone to use it. There is no token in this post, no price, and nothing to buy.
+
+That precision is not a legal footnote. It is most of the reason the post is worth your time. This is what partner companies do on their own initiative, in the open, with the receipts left in, and you get to audit it rather than take a press release's word for it. I could not have written this article about a closed enterprise integration, and that is worth sitting with.
+
+### Why it belongs in this group
+
+Look at what this one integration actually touches, and then ask how many production engineering write-ups you have read on any of it:
+
+- **Real-time 3D as an application interface**, rather than as a demo or a game. An animated character rendered inside somebody else's product, driven by that product's live state.
+- **A high-stakes domain as an agent's workplace**, where the state changes every few seconds, most of it is numeric, and a confidently wrong answer costs money.
+- **On-chain identity for agents**, so the thing on your screen is bound to something verifiable rather than to a row in a private database.
+- **Machine-to-machine payment**, where one program pays another per call with no human in the loop.
+- **Enterprise foundation models underneath all of it**, which is the part of the stack this community actually works in.
+- **AR as the next surface for the same avatar**, which is not part of this integration and which I will flag again at the end so nobody misreads it as shipped.
+
+That list is close to word for word the remit this group was founded on: spatial reasoning, generative 3D, agentic pipelines, and real-time interactive AI. This case study is the browser-panel end of that spectrum. AR is the other end, and the same avatar walks between them.
+
+### One more thing, and then the engineering
+
+Decision management means I spend my working life on a single question: what happens when an automated decision is wrong, and who finds out. Agents with faces and voices made that question louder for me, not quieter. A chatbot that gives you a bad answer looks exactly like a chatbot giving you a good one. An agent with a *body* can look reassuring while it is wrong, and that is a genuinely new failure mode that our existing controls were not designed for.
+
+So I asked the three.ws team to walk me through how the integration works and to write it up honestly, including what broke. What follows is that walkthrough, checked against both repositories myself, with the parts I found most useful to this group kept and the parts that make the best announcement cut.
+
+---
+
+## 1. Why decentralized finance is the hard case for an agent interface
+
+Before any of the engineering, it is worth being specific about why this domain and not another. I did not pick it for the crypto. I picked it because it breaks the chat box in four distinct ways, and every one of them is a general lesson wearing a specific costume.
+
+**The state moves every block.** A number the agent read twelve seconds ago may already be wrong. A support chatbot answering from a knowledge base has no equivalent problem. Here, the gap between reading and acting is a risk window, and any interface that renders a value without rendering its age is quietly lying about how much it knows.
+
+**It is numerically dense and unit-hostile.** Amounts in the smallest indivisible unit against amounts in whole tokens. Contracts against coins. Annual percentage rate against annual percentage yield. Basis points. Prose flattens all of that: "your position is healthy" reads identically whether the underlying calculation used the right unit or was off by a factor of ten to the eighteenth. Section 7 is a real example of a units-shaped bug that survived into a shipped preview.
+
+**Actions are irreversible.** No chargeback, no undo, no support ticket that reverses a confirmed transaction. This is the property that makes an agent in this domain different in kind from an agent that drafts an email. An agent that is wrong ninety-nine times out of a hundred in a text box is annoying. Here, the hundredth is permanent.
+
+**The mechanics are protocol-specific, and models state them confidently anyway.** Two protocols can both use the word "staking" and compute completely different things underneath. A language model trained on the general internet will produce a fluent, plausible, wrong explanation of the specific one in front of it, and there is nothing in the sentence's texture to warn you. This is the single most important thing I took from the whole write-up, and it is why section 11 lists a maintained domain skill pack as a planned item rather than a nice-to-have.
+
+### What the agent actually does in there
+
+For anyone who has never opened this kind of workspace, the tool catalog is the fastest orientation. Grouped roughly as the repository groups them:
+
+| Category | What the agent can call |
+| --- | --- |
+| Trading | Swaps across aggregators, limit orders, route comparison |
+| Lending | Supply and borrow, health factor, liquidation watch |
+| Yield | Pool discovery, rate comparison, auto-compounding |
+| Analytics | Total value locked, protocol revenue, chain metrics, exchange volume |
+| Portfolio | Wallet tracking, profit and loss, allocation, gas history |
+| Market intelligence | Funding rates, sentiment indices, large-holder alerts, fund flows |
+
+That is 592 callable APIs across 99 packages, and the repository ships a machine-readable index of all of them that marks **which ones move funds**. I want to underline that, because it is the kind of thing that only exists when someone has thought about the problem seriously. A tool catalog that distinguishes "reads a number" from "spends your money" is a governance primitive, not documentation.
+
+The same instinct shows up in the SDK's execution model, which does not let an agent act and then tell you:
+
+```typescript
+// Async mode returns immediately so you can stream the agent's work.
+const { data } = await sperax.agent.runAsync({
+ prompt: 'Find the best USDC yield on Arbitrum and prepare a deposit',
+ maxSteps: 15,
+});
+
+for await (const event of sperax.agent.stream(data.operationId)) {
+ if (event.event === 'stream_chunk') process.stdout.write(event.data.content);
+}
+
+// The run pauses before acting; you decide whether it proceeds.
+await sperax.agent.approve(data.operationId);
+```
+
+Note the verb in the prompt: *prepare* a deposit. The run streams its reasoning, stops at the boundary where value would move, and waits for a human. Registering an agent on-chain works the same way: the API builds the calldata and never holds a key or broadcasts for you.
+
+### And this is where a body starts to earn its place
+
+Put those four properties together and you get an interface problem that is genuinely under-served by text.
+
+A dashboard reports state. A face reports *change in* state, pre-attentively, before you have read anything. When a position's health drifts from comfortable toward dangerous, the number moving from one value to another has to be noticed, parsed, and interpreted. An expression that has been holding concern for the last ten seconds is noticed before you read a single digit.
+
+That is the actual argument for embodiment here, and it is why section 7 matters more than the rendering. The channel only helps if what it is expressing is true.
+
+---
+
+## 2. What was actually built
+
+The host side is [SperaxOS](https://chat.sperax.io). The specifications, from its own repository: 99 built-in tool packages exposing 592 tool APIs, 63 of which are reachable from any MCP client, an agent runtime on Next.js with more than 70 model providers behind it, an on-chain agent registry, an Apache-2.0 license, and self-hosting through Docker. It is a serious piece of software, which matters here, because the interesting engineering constraints in this post all come from it being somebody's real product rather than a demo harness.
+
+The integration puts the three.ws agent inside it. In the chat panel, an agent has a body. It speaks, it gestures, and its facial expression and posture shift continuously in response to what its tools are actually doing.
+
+Here is what has shipped, as of this writing:
+
+| Surface | What it is |
+| --- | --- |
+| Standalone plugin | A hosted manifest at a well-known URL plus four LLM-callable tools. Install it in the host, paste an agent ID, done. |
+| Native component | The `three.ws` npm package mounted directly in the host's own React tree, no iframe. |
+| Inline 3D in a chat message | A markdown element that renders a live, orbitable model inside a reply. |
+| Emotion and lip-sync engines | Ported from three.ws into the host codebase, kept framework-agnostic so they are unit-testable. |
+| Hash-chained action ledger | Ported the same direction, with the reconcile job that checks it. |
+| Three packages ported the other way | Chain and token utilities, a typed tool-authoring SDK, and a market-data collector, all now running inside three.ws. |
+| A guided 3D site tour | An eight-stop template that exports as a single script tag. |
+
+<!-- LIVE-EMBED -->
+
+The rest of this post is what I learned reading how those were built.
+
+---
+
+## 3. The first design question is not the one you expect
+
+I assumed the hard question was "how do you render a 3D avatar inside an application you do not control." It is not. Rendering is a solved problem and the team spent very little time on it.
+
+The actual question is **who owns the React tree**, and it has two legitimate answers depending on the host.
+
+![Two integration paths for embedding an agent in a host application](./media/ibm-sperax-integration-paths.png)
+
+_Figure 1. The two integration paths, and what each one costs you._
+
+**Path one is for hosts that will not take your code.** Most plugin ecosystems will not let a third party ship JavaScript into the main bundle, and I think they are right not to. For those hosts, three.ws ships a standalone plugin: one hosted manifest, one hosted iframe, and a handful of HTTP endpoints. Nothing to vendor, nothing for the host's security team to review, no supply chain to audit. It is live in a day.
+
+**Path two is for hosts that want the dependency.** When a host is willing to take a package, an iframe is a downgrade. You lose shared context, you pay for a second renderer, and you cannot compose the avatar into anything the host renders itself.
+
+SperaxOS ended up in both camps at once, which is why the integration has both halves. If you are building something similar, the team's advice, which I would repeat, is: **ship the manifest first, because it gets you live and it works for hosts that will never take your code. Then do the native integration, because that is the one that finds your bugs.** More on that in section 5, and it is not a throwaway line.
+
+### The manifest, in full
+
+The whole of path one is one JSON file served with CORS:
+
+```
+https://three.ws/.well-known/sperax-plugin.json
+```
+
+Its shape:
+
+```jsonc
+{
+ "identifier": "three-ws",
+ "type": "standalone",
+ "ui": { "url": "https://three.ws/sperax/iframe/", "height": 480, "mode": "iframe" },
+ "settings": {
+ "type": "object",
+ "required": ["agentId"],
+ "properties": { "agentId": { "type": "string", "title": "Agent ID" } }
+ },
+ "api": [
+ { "name": "render_agent", "url": "https://three.ws/api/chat-plugin/render-agent", "...": "..." },
+ { "name": "speak", "url": "https://three.ws/api/chat-plugin/speak", "...": "..." },
+ { "name": "gesture", "url": "https://three.ws/api/chat-plugin/gesture", "...": "..." },
+ { "name": "emote", "url": "https://three.ws/api/chat-plugin/emote", "...": "..." }
+ ]
+}
+```
+
+Four tools, and I want to note what is *not* in that list. There is no `set_expression_to_happy`. The tools are `render_agent` to bind or swap the avatar, `speak` with an emotional valence in the range minus one to one, `gesture` for a named physical beat (wave, nod, point, shrug), and `emote` to blend a named feeling into a continuous emotional state. Only the last two touch the face, and neither of them sets it. They contribute to it. That distinction is section 6.
+
+The only required setting is a public agent ID. No API key, which is a design decision I appreciate: the plugin cannot leak a credential it never asks for.
+
+---
+
+## 4. Every tool call runs in two halves
+
+This is the piece I would put on a slide if I were teaching this.
+
+![Every tool call runs in two halves, in parallel](./media/ibm-sperax-tool-call-halves.png)
+
+_Figure 2. Both halves run on every call. The split is what keeps the model from asserting things it cannot know._
+
+When the model calls `speak`, two things happen in parallel. The host frames the plugin's panel and posts the call into it, and the avatar speaks. Separately, the host's plugin gateway POSTs the same arguments to the tool's HTTP endpoint, and that endpoint returns a short result the model reads back into its own context.
+
+Why bother with both? Because **the model must never be the thing that asserts the avatar moved.** If the model simply says "I waved" and the panel silently failed, the transcript now contains a false statement that the model will happily build on for the rest of the conversation. Splitting the halves means the model receives a result saying the wave was dispatched, and the panel is the thing that actually waved. The two can be compared.
+
+That is not a hypothetical. It is exactly the bug they shipped first, and the fix is my favorite twenty lines in either repository:
+
+```js
+async function resolveAgent(agentId) {
+ if (!isUuid(agentId)) return { known: true, name: null };
+ try {
+ const [row] = await sql`
+ SELECT name FROM agent_identities
+ WHERE id = ${agentId} AND deleted_at IS NULL
+ LIMIT 1
+ `;
+ if (!row) return { known: false, name: null };
+ return { known: true, name: typeof row.name === 'string' ? row.name : null };
+ } catch (err) {
+ console.warn('[chat-plugin] agent lookup failed, binding unverified:', err?.message);
+ return { known: true, name: null };
+ }
+}
+```
+
+The original version confirmed any agent ID it was handed. Someone with a typo in their settings got a model cheerfully announcing "I have bound to your agent" over a permanently empty panel. There is no error anywhere. The system is behaving exactly as written, and it is lying.
+
+Three behaviors in the fix are deliberate, and I would defend all three in a design review:
+
+1. **A well-formed ID that does not exist comes back as a real error**, one the model can explain, pointing the user back to their dashboard to recopy it.
+2. **A handle or manifest ID passes through unverified**, because the browser element resolves those and the server has no business pretending it checked something it did not.
+3. **A database outage degrades to an unverified binding instead of a 500.** An infrastructure problem on one side must never take down the other side's chat panel.
+
+That third one is the decision-management instinct showing, and I was glad to see it in someone else's code. The failure mode of a dependency should be proportional to what the dependency actually does. A name lookup being unavailable is not a reason to break a conversation.
+
+One small practical note that will save somebody an afternoon: hosts rename the settings header. LobeChat sends `lobe-chat-plugin-settings` and SperaxOS sends `Sperax-Plugin-Settings`. Read both.
+
+---
+
+## 5. The native path is where the real bugs live
+
+Path two is a dependency and a mount:
+
+```tsx
+// three.ws registers <agent-3d> via customElements.define(...)
+useEffect(() => {
+ if (typeof window !== 'undefined' && !window.VIEWER) window.VIEWER = {};
+ import('three.ws').then(() => {
+ customElements.whenDefined('agent-3d').then(() => setRegistered(true));
+ });
+}, []);
+```
+
+Six lines, two scars, and both are worth your time even if you never touch 3D.
+
+**The dynamic import is not a style choice.** The package shipped `sideEffects: false` in its manifest. For a package whose entire job is a `customElements.define` side effect, that field is simply false, and a production bundler believed it: the registration was tree-shaken away and the element silently never upgraded. Not an error, not a warning, just an element that stays inert. The host now carries a patch for the flag *and* imports dynamically, because dynamic imports are never tree-shaken. **If you publish a custom element, go check that field right now.**
+
+**The `window.VIEWER` seed is the other one.** The library assigned to `window.VIEWER.json` during model boot without ever initializing the global. In three.ws's own pages the global happened to exist. In someone else's application it did not, and boot threw a `TypeError`.
+
+Neither of those is findable from inside your own product. That is the whole argument for doing the native integration even after the iframe works: the iframe protects you from the host, and it also protects you from learning what your package does in a world you did not build.
+
+Once the component is native, it composes in ways the iframe cannot. The host added a markdown plugin so a chat message can contain a live model:
+
+```html
+<avatar3d url="https://.../model.glb" size="260" clip="Wave" zoom="true" />
+```
+
+That renders in the same React tree, no iframe, no sandbox, and the model can come from anywhere. An agent answering "what does this thing look like" can now answer with the thing.
+
+There is also a client lane in the tool router, which I had not thought about before reading this. Animation control cannot round-trip through a server without the animation being late, so a dispatcher intercepts the calls that belong to the browser before the rest go server-side:
+
+```ts
+const CLIENT_TOOL_IDS = new Set(['agent-3d-controls', 'get-available-animations']);
+
+for (const tool_call of params.tool_calls) {
+ if (CLIENT_TOOL_IDS.has(tool_call.function.name)) params.onClientToolCall(tool_call);
+ else serverToolCalls.push(tool_call);
+}
+```
+
+Obvious once you see it. Worth stealing if your agent controls anything with a frame rate.
+
+---
+
+## 6. Emotion as a continuous blend, not a state machine
+
+Here is the part I expected to find cosmetic and did not.
+
+The obvious way to build an expressive avatar is a state machine: happy, sad, thinking, alarmed. It takes about thirty seconds of real use to see why that is wrong. The avatar snaps between moods, and the snap reads as a cartoon. Worse, for a monitoring interface, a state machine has to *choose*, and the truth is usually a mixture.
+
+The approach both teams now share is a continuous weighted blend. Each emotion is a float between zero and one. Events spike it. It then decays exponentially, at its own rate, every frame. All active emotions are blended into facial morph targets and body language on every frame, so a face can be forty percent concerned, thirty percent curious, and thirty percent neutral at the same time, which is how faces actually work.
+
+![The five emotion decay curves and a blended face at one moment](./media/ibm-sperax-empathy-decay.png)
+
+_Figure 3. The five decay curves. Each dot marks where a full spike has fallen to the floor value and the emotion is treated as inactive._
+
+The ported definition table doubles as the design document, and the comments are the original author's:
+
+```ts
+export const EMOTION_DEFINITIONS: Record<EmotionName, EmotionDef> = {
+ // Positive sentiment or success: a warm, open smile.
+ celebration: { decaySeconds: 6, morphs: { jawOpen: 0.2, smile: 0.85 } },
+ // Negative sentiment or tool error: a worried frown with raised inner brows.
+ concern: { decaySeconds: 12, morphs: { browInnerUp: 0.6, frown: 0.55 } },
+ // Loading or processing: an inquisitive head tilt.
+ curiosity: { decaySeconds: 8, headTiltZ: 0.12 },
+ // Emotional or supportive moments: a soft, squinting, caring look.
+ empathy: { decaySeconds: 13, morphs: { browInnerUp: 0.5, eyeSquint: 0.4 } },
+ // Long-running operations: a patient backward lean.
+ patience: { decaySeconds: 20, leanX: -0.08 },
+};
+```
+
+**The decay rates carry the entire personality, and they are deliberately not uniform.** Celebration is bright and brief at six seconds. Concern lingers at twelve, so a risk that appeared while you were looking away is still on the face when you look back. Patience runs twenty, so an agent waiting on a slow operation keeps *looking* like it is waiting instead of going blank. Empathy is the slowest of the soft states at thirteen, because empathy that switches off the instant a sentence ends reads as insincere, and it turns out that is true of rendered faces too.
+
+Two implementation choices are what make this maintainable rather than a pile of magic numbers:
+
+**Keep the engine pure.** The emotion module has no 3D library and no React in it. It maps time and spikes to logical morph weights, and a separate module resolves those logical names onto whatever concrete blendshapes the loaded mesh happens to have. So the emotion model is unit-testable with no renderer, and it ported cleanly between two codebases that share no UI framework. If you take one architectural idea from this post, take this one: **the interesting part of your system should not import your rendering layer.**
+
+**Compose, do not multiplex.** Speech drives the mouth through an entirely separate path. A Web Audio analyser samples the speech waveform each frame and maps a smoothed amplitude onto the jaw channel, gated below a noise floor so room hum does not make the avatar chew, saturating well before a full open so it never gapes:
+
+```ts
+const NOISE_GATE = 0.02;
+const FULL_OPEN_RMS = 0.22;
+const MAX_JAW = 0.7;
+```
+
+Because articulation and emotion write to different logical channels and are summed, the agent can deliver bad news *while looking concerned about it*. A state machine would have to pick one.
+
+---
+
+## 7. The part that actually matters, and it is not the rendering
+
+Now the section I asked for, and the reason I wanted this written up at all.
+
+**An expressive avatar sitting on top of wrong data is not a nice interface. It is a confident liar, and it is worse than a table of numbers, because a table does not lean toward you and look reassuring.**
+
+They learned this the direct way, and to their credit the commit history says so in plain language.
+
+The SPA staking panel in the host application, and the chat tools behind it, were returning literals. Total SPA locked: zero. Total veSPA supply: zero. Average lockup: zero. The four-year staking rate: a hardcoded `22.61`, with a source comment that said, and I am quoting the code, "from app screenshot." Because two of those were zero, the panel's own has-data check failed and it rendered dashes in every field. The agent, meanwhile, would narrate the number that had been copied off a screenshot months earlier, with a face on.
+
+The fix reads the contracts instead:
+
+- Total locked and escrow supply now come from live `totalSPALocked()` and `totalSupply()` calls on the voting-escrow contract. At the time of the fix that was 242.66 million SPA locked against 416.78 million veSPA.
+- The rate is derived from the rewarder contract's `rewardsPerWeek` over a trailing eight-week window, landing at 21.0 percent at maximum lock. Close to the number that had been copied, which is exactly the point: it is now sourced and auditable rather than coincidentally near-correct. The eight-week window exists because emissions funding is irregular enough that any single week is noise.
+
+The worse bug was in the estimator, and this is the one I would use in a decision-integrity training session. It is also section 1's fourth property in the flesh. Both call sites computed voting power with the linear `amount * lockSeconds / MAXTIME` slope that a *different* well-known vote-escrow design uses. Same word, same general idea, different math: this escrow mints one veSPA per SPA per **year** locked, capped at four years. Someone locking 1,000 SPA for four years was shown an estimate of roughly 1,000 veSPA and would actually have received roughly 3,984.
+
+A four-fold understatement. In a preview. Next to an avatar nodding encouragingly.
+
+It is now a shared helper backing both the dashboard panel and the chat tool preview, verified against the contract's own `estimateDeposit` at six different lock lengths, and pinned by tests so it cannot drift back.
+
+The rule that came out of it, and which I think generalizes far past this domain:
+
+> **The avatar may only express state it can prove.** If a number cannot be read from its source of truth, the correct behavior is a visible unknown, not a confident face over a stale literal.
+
+I would go further, from the decision-management side. Embodiment raises the cost of being wrong, because it raises the user's trust before the data has earned it. Every project in this group that puts a face on an agent is quietly taking on that liability. It is worth deciding, on purpose and in advance, what your avatar does when it does not know.
+
+---
+
+## 8. Failing honestly, including about other people's systems
+
+A smaller story, same principle, opposite direction.
+
+While embedding the partner's own application in a frame, a probe fetched the target and received a `403`, so the page hid the embed and told the user the site had refused framing.
+
+The site had refused nothing. Its bot protection challenges every datacenter address, and the probe was running on one. The giveaway is that a plain top-level request, a static asset, and a path that does not exist all returned the same `403`, which has nothing to do with framing. The header being read as a framing policy belonged to the challenge page, not to the application.
+
+The probe now sends an unframed control request alongside the framed one, and only trusts a framing refusal when the control was actually served. On a challenged network it reports `UNKNOWN` and exits with a distinct code.
+
+**A negative result from a network you do not control is not a fact about the other system.** I have watched teams write a permanent configuration change on exactly this kind of evidence. Reporting "I could not tell" is a feature.
+
+---
+
+## 9. Provenance, for a body that can move money
+
+Once an embodied agent can execute rather than only explain, expressiveness stops being the interesting problem and provenance starts.
+
+three.ws had built a hash-chained ledger for its own agent activity, and the host ported the primitive: an append-only, SHA-256 hash-chained record of every value movement an agent initiates, where each entry commits its predecessor.
+
+```
+entryHash = sha256( canonicalFields(entry) || prevHash )
+```
+
+Each user owns an independent chain. Sequence numbers are per-user and monotonic from one, the first entry commits a genesis hash of sixty-four zeros, and the canonical serialization is a fixed field order with free-text detail folded in through a key-sorted stringify, so identical payloads always hash identically.
+
+The field separator is a NUL byte, and the reasoning is the sort of detail that decides whether a scheme is sound or decorative. Two of the committed fields are free text and can contain spaces. With a printable separator the encoding is ambiguous: two different field tuples could serialize to the same string, and a chain built on an ambiguous encoding proves nothing at all. A NUL cannot occur in any of the values, so the serialization is injective and the hash means what it claims.
+
+Editing or deleting any historical row breaks the chain from that point forward. A reconcile job runs on a schedule looking for two things: a chain break, and an on-chain movement that was never recorded. **The second alarm is the interesting one.** A value movement with no corresponding ledger entry is the signal that a key is being used outside the agent runtime, which is to say it is a breach detector wearing an accounting hat.
+
+What did *not* get ported is as deliberate as what did. The origin system's signing keys, its price oracle, and its multi-wallet funding topology all stayed behind, because the receiving system has different custody and its own valuation source. A port that drags its origin's assumptions along with it is not a port, it is a fork with extra steps.
+
+For an agent with a face, this is the other half of trustworthiness. The emotion layer makes the agent legible in the moment. The ledger makes it accountable afterward. You need both, and I would argue the second one is the part that lets a regulated organization say yes to the first.
+
+---
+
+## 10. The code went both ways, and that is the part I would negotiate for
+
+Here is what surprised me most, and it is a partnership observation rather than a technical one.
+
+![What was ported in each direction between the two codebases](./media/ibm-sperax-code-exchange.png)
+
+_Figure 4. What moved which way. The right-hand column is the half nobody writes a press release about._
+
+**Into the host from three.ws:** the emotion engine, the lip-sync driver, the inline 3D markdown element, the client-side tool dispatcher, and the hash-chained ledger with its reconcile job.
+
+**Into three.ws from the host:**
+
+- A zero-dependency single source of truth for chain and token constants, minimal contract interface fragments, and address and amount validation. The existing maps were kept verbatim and a section was added for a chain the origin did not cover.
+- A typed tool-authoring layer, derived from the host's plugin SDK. One call declares a tool's identity, its schemas, and its permission manifest, and derives the machine-readable schema automatically. A second call wires a typed implementation onto it and routes every invocation through a single entry point that validates parameters, enforces the declared rate limit, and normalizes both success and failure into one shape. A third adapts the result into the exact registration shape the receiving project's MCP servers already use, so adopting it is one call instead of a rewrite. It was rewritten from TypeScript into plain ESM with JSDoc to match the receiving codebase's conventions, and re-scoped away from chat-interface concepts it no longer needed.
+- A market-data collector, since hardened considerably: per-topic subscription acknowledgements on one exchange whose retired topic used to fail silently, a unit conversion on another whose raw size field counts contracts rather than units, a geographic restriction probe on a third, and per-lane health reporting. It runs as a standalone always-on service because it holds long-lived WebSockets, and the proxy in front of it returns a 503 when the collector is unreachable rather than inventing numbers, which is the same principle as section 7 wearing different clothes.
+
+If you are ever in the room where an integration is being negotiated, **this is the clause to push for: a shared right to port implementation between the two codebases.** Two teams working on adjacent problems produce more reusable primitives than either will build alone, and a partnership you can measure in merged commits ages a great deal better than one you can only measure in announcements.
+
+---
+
+## 11. What is planned, stated as plans and not as shipping claims
+
+I asked for this list explicitly and I am labeling it clearly, because I do not want anything here read as available today.
+
+Shipped and live: everything in the table in section 2.
+
+Designed, in progress, or proposed:
+
+1. **Compute endowments.** USDs, the Sperax stablecoin, pays yield to whoever holds it, automatically, with no staking step: the balance grows in the wallet. The idea is that you deposit once and that yield stream funds an agent's compute balance indefinitely, so the agent never runs out of inference budget. Set the domain aside for a second and look at the shape of it: it is a real answer to "who pays for this agent's inference in year three," and it needs no new financial mechanism, only new plumbing between an existing yield stream and an existing credit ledger. I find that the most interesting idea on the list, as an agent-economics question, independent of the asset involved.
+2. **A recurring credit grant keyed to holdings** rather than a one-time claim, so the relationship is retention rather than a giveaway.
+3. **A second settlement asset** on the machine-to-machine payment rails that already handle per-call settlement over the x402 HTTP payment scheme.
+4. **A domain skill pack**, so an agent reasons about the specific protocol mechanics from a maintained source rather than approximating them from training data. The voting-power bug in section 7 is precisely the failure a real skill pack prevents, which is why I think this one matters more than it sounds.
+5. **The guided site tour deployed on the live partner site.** The template exists and exports as a single script tag. A builder preview can only prove the mechanics, so the real test is the deployment.
+
+---
+
+## 12. What I would like from this group
+
+A few things, and then the links.
+
+**If you have embedded an agent into somebody else's application, tell us which path you took.** Section 3 is the fork in the road, and I would like the group's collective experience on it. My suspicion is that most people reach for the iframe and never do the native version, and therefore never find their equivalent of the `sideEffects` bug.
+
+**If you publish a web component, go and check your `sideEffects` field.** That is the single most immediately actionable thing in this post and it takes ninety seconds.
+
+**If you put a face on an agent, decide now what it does when it does not know.** Section 7 is my honest reason for publishing this. I would rather this group be known for building agents that are legible about their uncertainty than for building agents that are charming about it.
+
+**And the AR question I promised to come back to.** Everything above happens in a rectangle on a screen. The same rigged avatar, the same emotion blend, the same tool calls, can also be placed in a room through a phone camera, and three.ws ships that surface separately. It is not part of this integration and I am not going to pretend it is. But every argument in section 7 gets sharper when the agent is standing in your kitchen instead of sitting in a panel, because the trust an embodied thing borrows from being *present* is larger again. If somebody in this group wants to be the first to put a domain-grounded agent into AR and write up what broke, I will give that post the front of the group and I will bring the questions to both teams myself.
+
+And if you want to try any of it, none of the following requires an account with anyone, and the generation step requires no key at all:
+
+- Generate a rigged, animation-ready avatar from a sentence at [three.ws/create](https://three.ws/create), or a static model at [three.ws/forge](https://three.ws/forge).
+- Embed it with the documented custom element at [three.ws/docs/embedding](https://three.ws/docs/embedding), or install the package if you want it natively in a React tree.
+- Read [the plugin manifest itself](https://three.ws/.well-known/sperax-plugin.json). It is the shortest complete description of the four-tool interface, and the pattern transfers to any host of the same lineage.
+- The integration write-up from the three.ws side is at [three.ws/sperax](https://three.ws/sperax), and the host application is Apache-2.0 at [github.com/nirholas/sperax](https://github.com/nirholas/sperax) if you want to read the receiving half.
+
+Back to the third corner of the triangle, with one practical note. The agent brain is provider-agnostic on both sides of this integration, so pointing it at IBM Granite through watsonx.ai changes nothing about the rest. The emotion engine in section 6 takes its spikes from tool-call outcomes and sentiment rather than from any provider's output format, and the four plugin tools are plain HTTP. Your model choice is genuinely orthogonal to the body, which is the property that makes the whole stack swappable. If you are wiring an embodied agent to Granite and you hit something ugly, post it here. That is what the group is for.
+
+I will bring the harder questions from this thread back to the three.ws team, the same way I did for the meetup Q&A. The skeptical ones are still the most useful ones.
diff --git a/docs/ibm-community.md b/docs/ibm-community.md
index b999325ae..057bbf614 100644
--- a/docs/ibm-community.md
+++ b/docs/ibm-community.md
@@ -4,20 +4,25 @@ This is the running catalog of everything published in the [Three.ws User Group]
Dates marked "approx." are derived from the site's relative timestamps ("17 days ago") on the snapshot date; blog dates come from their URLs and are exact.
-## Group snapshot (2026-08-13)
+## Group snapshot (2026-09-10)
| Metric | Value |
| ------ | ----- |
-| Members | 16 |
-| Discussion threads | 8 listed in the [digest viewer](https://community.ibm.com/community/user/groups/community-home/digestviewer?communitykey=e71510cc-d953-408f-9a1c-019f5c0a7016), which reports "Showing 1 to 8 of 8" |
-| Blog posts | 4 |
+| Members | 17 |
+| Discussion threads | 8 catalogued below; the group header tallies 10 |
+| Blog posts | 5 (the fifth is the USC post below, not yet catalogued in full) |
| Library entries | 2 (the attachments on the BOWYER and SperaxOS threads) |
| Upcoming events | 0 |
+| Past events | 2 (the in-world meetup, and "Live build: text prompt to embedded 3D agent in 30 minutes") |
The group header counts threads as 10 while the digest viewer lists 8. The
header's tally is the one to distrust: the digest viewer is the per-thread
listing this catalog is built from, and it is explicit about its own total.
+The 2026-09-10 figures come from the group home page rather than the digest
+viewer, so the thread count is the header's and carries the caveat above.
+Re-run the per-thread pass against the digest viewer to confirm it.
+
## Blog posts
### 1. Welcome to the Three.ws User Group: Building AI Agents With 3D Capabilities
@@ -86,6 +91,23 @@ Two placeholders are still live in the published post: a bracketed note about th
next meetup date and a bracketed "[link once available]" for the recording. If
either gets filled in, update this entry.
+### 5. Empowering the On-Chain Agent Economy: How three.ws, the University of Southern California, and IBM are ...
+
+- **Author:** not captured
+- **Published:** not captured (listed as a featured blog on the group home page on 2026-09-10)
+- **Activity:** not captured
+- **URL:** not captured
+
+Partial entry. The title is truncated on the group home page and the post was
+not opened when this snapshot was taken, so only the visible teaser is recorded:
+it opens on the argument that the AI conversation has been dominated by text
+boxes, static chatbot interfaces, and single-turn query responses, and that the
+next phase is something else. Open the post, then replace this entry with the
+same fields the four above carry (author, exact date, activity, URL, faithful
+summary). Note for whoever does: the title names IBM alongside three.ws and a
+university, so check it against the framing rules in [ibm.md](./ibm.md) and flag
+anything that reads as an IBM partnership deliverable.
+
## Discussion threads
Newest first, matching the digest viewer's order.
@@ -169,8 +191,9 @@ A first-run walkthrough of the Forge from a user's perspective, no account, wall
| Draft | Subject |
|---|---|
| [ibm-community-governed-agents-post.md](./ibm-community-governed-agents-post.md) | Granite Guardian as an action veto once agents can control a home, ride in a car, and order a manufactured object; the watsonx.ai surface map; the quarter's shipping recap; and the group's next event question |
+| [ibm-community-defi-3d-sperax.md](./ibm-community-defi-3d-sperax.md) | Written for Jessica to publish in her own voice. Section 0 answers "why is an IBM employee writing about two crypto companies" as her own practitioner case (her field is decision integrity, this is the best material on it she has read) rather than as IBM partnership strategy, which she does not own. Then the triangle of three relationships (Sperax with three.ws, both as IBM Business Partners, and the three.ws runtime on Granite through watsonx.ai) split as body / DeFi domain / brain, with an explicit subsection denying that IBM commissioned or endorsed the integration itself, and framed through her decision-management day job. Section 1 makes DeFi a real subject rather than a backdrop (the four properties that break a chat box, the tool catalog, the approve-before-acting execution model): the two ways to embed an embodied agent in a host application (standalone manifest vs native component), the continuous emotion blend that replaced a state machine, why grounding the avatar in verified reads mattered more than the rendering, honest failure when a probe is bot-challenged, the hash-chained action ledger, the code that moved in both directions, what is planned, and AR flagged as the next surface rather than a shipped one. Carries four diagrams rendered by [scripts/render-ibm-sperax-diagrams.mjs](../scripts/render-ibm-sperax-diagrams.mjs) into [media/](./media), plus [ibm-community-defi-3d-sperax-post.md](./ibm-community-defi-3d-sperax-post.md) and its styled `-post.html` twin, both generated by [scripts/build-ibm-community-post.mjs](../scripts/build-ibm-community-post.mjs) with the frontmatter and editor notes stripped. Edit the draft, never the generated trio. Form values, the permalink slug, the meta description, and the image-placement sequence are in [ibm-community-defi-3d-sperax-publishing-kit.md](./ibm-community-defi-3d-sperax-publishing-kit.md). **Open question before posting:** the draft states that Sperax is also an IBM Business Partner, which came from the owner and is not evidenced anywhere in this repo; confirm the wording Sperax uses for its own partner status first |
-The draft carries the framing rules from [ibm.md](./ibm.md) in its frontmatter, including which section to cut first if the group's no-crypto-cluster rule is applied strictly.
+Both drafts carry the framing rules from [ibm.md](./ibm.md) in their frontmatter, including which section to cut first if the group's no-crypto-cluster rule is applied strictly.
## Keeping this catalog current
diff --git a/docs/media/ibm-sperax-code-exchange.png b/docs/media/ibm-sperax-code-exchange.png
new file mode 100644
index 000000000..8b5331085
Binary files /dev/null and b/docs/media/ibm-sperax-code-exchange.png differ
diff --git a/docs/media/ibm-sperax-empathy-decay.png b/docs/media/ibm-sperax-empathy-decay.png
new file mode 100644
index 000000000..9de284155
Binary files /dev/null and b/docs/media/ibm-sperax-empathy-decay.png differ
diff --git a/docs/media/ibm-sperax-featured.png b/docs/media/ibm-sperax-featured.png
new file mode 100644
index 000000000..76b2080d1
Binary files /dev/null and b/docs/media/ibm-sperax-featured.png differ
diff --git a/docs/media/ibm-sperax-integration-paths.png b/docs/media/ibm-sperax-integration-paths.png
new file mode 100644
index 000000000..16e3aab6d
Binary files /dev/null and b/docs/media/ibm-sperax-integration-paths.png differ
diff --git a/docs/media/ibm-sperax-tool-call-halves.png b/docs/media/ibm-sperax-tool-call-halves.png
new file mode 100644
index 000000000..1ef8c005b
Binary files /dev/null and b/docs/media/ibm-sperax-tool-call-halves.png differ
diff --git a/public/ibm-sperax/ibm-sperax-code-exchange.png b/public/ibm-sperax/ibm-sperax-code-exchange.png
new file mode 100644
index 000000000..8b5331085
Binary files /dev/null and b/public/ibm-sperax/ibm-sperax-code-exchange.png differ
diff --git a/public/ibm-sperax/ibm-sperax-empathy-decay.png b/public/ibm-sperax/ibm-sperax-empathy-decay.png
new file mode 100644
index 000000000..9de284155
Binary files /dev/null and b/public/ibm-sperax/ibm-sperax-empathy-decay.png differ
diff --git a/public/ibm-sperax/ibm-sperax-featured.png b/public/ibm-sperax/ibm-sperax-featured.png
new file mode 100644
index 000000000..76b2080d1
Binary files /dev/null and b/public/ibm-sperax/ibm-sperax-featured.png differ
diff --git a/public/ibm-sperax/ibm-sperax-integration-paths.png b/public/ibm-sperax/ibm-sperax-integration-paths.png
new file mode 100644
index 000000000..16e3aab6d
Binary files /dev/null and b/public/ibm-sperax/ibm-sperax-integration-paths.png differ
diff --git a/public/ibm-sperax/ibm-sperax-tool-call-halves.png b/public/ibm-sperax/ibm-sperax-tool-call-halves.png
new file mode 100644
index 000000000..1ef8c005b
Binary files /dev/null and b/public/ibm-sperax/ibm-sperax-tool-call-halves.png differ
diff --git a/scripts/audit-docs.mjs b/scripts/audit-docs.mjs
index 3b320eed8..965a25a62 100644
--- a/scripts/audit-docs.mjs
+++ b/scripts/audit-docs.mjs
@@ -324,6 +324,9 @@ const UNPUBLISHED_DOCS = new Map([
['google-x-accounts', 'internal: outreach directory of external X accounts'],
['ibm-community-article', 'internal: source draft of an IBM Community post'],
['ibm-community-governed-agents-post', 'internal: source draft of an IBM Community post'],
+ ['ibm-community-defi-3d-sperax', 'internal: source draft of an IBM Community post'],
+ ['ibm-community-defi-3d-sperax-post', 'internal: generated paste-ready body of an IBM Community post'],
+ ['ibm-community-defi-3d-sperax-publishing-kit', 'internal: form values and publishing sequence for an IBM Community post'],
['ibm-community-live-reaction-jessica', 'internal: source draft of an IBM Community post'],
['ibm-community-recap-jessica', 'internal: source draft of an IBM Community post'],
['ibm-community-recap-nichxbt', 'internal: source draft of an IBM Community post'],
diff --git a/scripts/build-ibm-community-post.mjs b/scripts/build-ibm-community-post.mjs
new file mode 100644
index 000000000..1c0435c5b
--- /dev/null
+++ b/scripts/build-ibm-community-post.mjs
@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+// Turns the IBM Community draft in docs/ into the two paste-ready files the
+// author actually publishes from.
+//
+// The draft carries YAML frontmatter (venue, media manifest, framing rules) and
+// editor notes that must never reach the published post. This strips both, then
+// writes:
+// *-post.md the clean article body, for anyone who wants the Markdown
+// *-post.html the same body styled, to read in a browser
+// *-post-ibm.html a body fragment for the IBM Community editor's HTML
+// view: no document shell, no <h1> (the form has a Title
+// field), and every image swapped for a labelled
+// placeholder to upload by hand. Works today.
+// *-post-ibm-hosted.html the same fragment with the images pointed at their
+// public three.ws URLs and a live avatar panel embedded,
+// so publishing is one paste and no uploads. Requires the
+// images under public/blog/ibm-sperax/ to be deployed
+// first, otherwise every figure is a broken image.
+//
+// Both come from one source, so the Markdown and the HTML can never drift.
+//
+// Key styling is inlined on block elements as well as declared in the
+// stylesheet: the IBM Community editor drops <style> on paste, so code blocks,
+// tables and pull quotes would otherwise arrive as unformatted paragraphs.
+//
+// node scripts/build-ibm-community-post.mjs
+import { marked } from 'marked';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const SRC = resolve(root, 'docs/ibm-community-defi-3d-sperax.md');
+const OUT_MD = resolve(root, 'docs/ibm-community-defi-3d-sperax-post.md');
+const OUT_HTML = resolve(root, 'docs/ibm-community-defi-3d-sperax-post.html');
+const OUT_IBM = resolve(root, 'docs/ibm-community-defi-3d-sperax-post-ibm.html');
+const OUT_IBM_HOSTED = resolve(root, 'docs/ibm-community-defi-3d-sperax-post-ibm-hosted.html');
+// NOT under /blog/: the route table rewrites `/blog/<slug>` to `<slug>.html`, and
+// the top-level blog/ tree is copied into dist/ separately, so a public/blog/
+// subdirectory is two collisions waiting to happen. Its own prefix has neither.
+const HOSTED_BASE = 'https://three.ws/ibm-sperax';
+
+const raw = readFileSync(SRC, 'utf8');
+
+// Frontmatter is editorial metadata for us, never post content.
+const fm = raw.match(/^---\n([\s\S]*?)\n---\n/);
+if (!fm) throw new Error(`${SRC} has no frontmatter to strip; refusing to guess where the post starts.`);
+const title = (fm[1].match(/^title:\s*"?(.*?)"?\s*$/m) || [, 'IBM Community post'])[1];
+
+let body = raw.slice(fm[0].length);
+
+// Editor notes are wrapped in _[...]_ and marked as not for publication.
+const notes = body.match(/^_\[Editor note[^\n]*\]_\n\n?/gm) || [];
+body = body.replace(/^_\[Editor note[^\n]*\]_\n\n?/gm, '');
+if (/not for publication|do not paste this note/i.test(body)) {
+ throw new Error('An editor note survived the strip; fix the pattern before shipping this file.');
+}
+
+// The live-embed marker is an HTML comment: invisible to a Markdown reader, and
+// carried through the render so the hosted fragment can swap a live panel in at
+// exactly that point. It has to survive into the rendered HTML, so strip it from
+// the Markdown output only, never from `body` before parsing.
+const LIVE_MARKER = '<!-- LIVE-EMBED -->';
+// \\s* rather than \\n\\n: the renderer emits the comment with its own trailing
+// whitespace, so a newline-exact pattern leaves the marker sitting in the HTML.
+const stripMarker = (text) => text.replace(new RegExp(`${LIVE_MARKER}\\s*`, 'g'), '\\n');
+
+writeFileSync(OUT_MD, `${stripMarker(body).trimStart()}`, 'utf8');
+
+marked.setOptions({ gfm: true, breaks: false });
+const rendered = marked.parse(body);
+
+// Inline the styles that matter for a paste into a rich-text editor.
+const INLINE = [
+ [/<pre>/g, '<pre style="background:#f4f4f4;border-left:4px solid #0f62fe;padding:16px 20px;overflow-x:auto;font-family:\'IBM Plex Mono\',ui-monospace,monospace;font-size:14px;line-height:1.6">'],
+ [/<code>/g, '<code style="font-family:\'IBM Plex Mono\',ui-monospace,monospace;font-size:0.92em;background:#f4f4f4;padding:1px 5px">'],
+ [/<pre style="([^"]*)"><code style="[^"]*">/g, '<pre style="$1"><code>'],
+ [/<blockquote>/g, '<blockquote style="border-left:4px solid #0f62fe;background:#edf5ff;margin:28px 0;padding:18px 24px;font-size:1.05em">'],
+ [/<table>/g, '<table style="border-collapse:collapse;width:100%;margin:24px 0">'],
+ [/<th>/g, '<th style="border:1px solid #e0e0e0;padding:10px 14px;text-align:left;background:#f4f4f4">'],
+ [/<td>/g, '<td style="border:1px solid #e0e0e0;padding:10px 14px;vertical-align:top">'],
+ [/<img /g, '<img style="max-width:100%;height:auto;border:1px solid #e0e0e0;margin:8px 0" '],
+ [/<hr>/g, '<hr style="border:none;border-top:1px solid #e0e0e0;margin:44px 0">'],
+];
+const post = INLINE.reduce((html, [find, replace]) => html.replace(find, replace), rendered);
+
+writeFileSync(
+ OUT_HTML,
+ `<!doctype html>
+<html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${title}</title>
+<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=IBM+Plex+Sans:wght@400;600;700&display=swap" rel="stylesheet">
+<style>
+ body{ max-width:820px; margin:0 auto; padding:56px 24px 96px; background:#fff; color:#161616;
+ font-family:'IBM Plex Sans',system-ui,sans-serif; font-size:17px; line-height:1.65; }
+ h1{ font-size:40px; line-height:1.2; letter-spacing:-.01em; margin:0 0 24px; }
+ h2{ font-size:27px; margin:52px 0 16px; letter-spacing:-.01em; }
+ h3{ font-size:21px; margin:34px 0 12px; }
+ p,li{ font-size:17px; }
+ ul,ol{ padding-left:26px; }
+ li{ margin-bottom:8px; }
+ a{ color:#0f62fe; }
+ em{ color:#525252; }
+ img+p em{ display:block; margin-top:6px; font-size:15px; }
+</style></head>
+<body>
+${stripMarker(post)}</body></html>
+`,
+ 'utf8',
+);
+
+// ---------------------------------------------------- IBM editor HTML fragments
+// Placeholders are labelled by role rather than by position: the captions in the
+// body already number the four diagrams 1 to 4, and a placeholder that numbered
+// the header lockup as 1 would put every later figure out of step with them.
+const FIGURES = [
+ ['HEADER IMAGE', 'ibm-sperax-featured.png'],
+ ['FIGURE 1', 'ibm-sperax-integration-paths.png'],
+ ['FIGURE 2', 'ibm-sperax-tool-call-halves.png'],
+ ['FIGURE 3', 'ibm-sperax-empathy-decay.png'],
+ ['FIGURE 4', 'ibm-sperax-code-exchange.png'],
+];
+
+// three.ws serves `frame-ancestors 'self' https://ibm.com https://*.ibm.com`, so
+// community.ibm.com is already allowed to frame the real plugin panel. Whether it
+// SURVIVES depends on the editor's own sanitizer, which is why the hosted fragment
+// carries a still image inside the same block as a fallback.
+const LIVE_EMBED = `<h3>The panel, running, right here</h3>
+<p>Below is the actual plugin panel three.ws serves to SperaxOS, framed live rather than
+screenshotted. Same URL the host frames, same avatar, same emotion blend. If your browser
+or this page's sanitizer blocks the frame, you get the still image underneath instead.</p>
+<div style="border:1px solid #e0e0e0;background:#f4f4f4;padding:12px">
+<iframe src="https://three.ws/sperax/iframe" title="Live three.ws avatar panel, the same one SperaxOS frames"
+ width="100%" height="480" loading="lazy" style="border:0;display:block;background:#fff"></iframe>
+</div>
+<p><em>The live three.ws avatar panel. This is the plugin's <code>ui.url</code>, not a recording.</em></p>`;
+
+const buildFragment = (imageFor, liveEmbed) => {
+ let i = 0;
+ const frag = post
+ // The form has its own Title field; a second copy in the body reads as a typo.
+ .replace(/<h1[^>]*>[\s\S]*?<\/h1>\s*/, '')
+ // Same for the byline: the post already shows its author and its group.
+ .replace(/<p><em>By Jessica Swanson\.[\s\S]*?<\/em><\/p>\s*/, '')
+ // ONE pass, and it must stay one pass. Both forms are matched by a single
+ // alternation because the hosted replacement itself contains an <img>: a
+ // second sweep would match the tags this one just inserted and run off the
+ // end of FIGURES. The wrapping <p> is part of the match so a replacement
+ // that is itself a <p> does not end up nested inside one.
+ .replace(/<p>\s*<img[^>]*>\s*<\/p>|<img[^>]*>/g, () => imageFor(FIGURES[i++]))
+ .replace(LIVE_MARKER, liveEmbed);
+ if (i !== FIGURES.length) {
+ throw new Error(
+ `Expected ${FIGURES.length} images in the post, found ${i}. ` +
+ 'Update FIGURES to match the draft before shipping this fragment.',
+ );
+ }
+ if (/<p>\s*<p /.test(frag)) throw new Error('A placeholder nested inside a paragraph; fix the replace.');
+ return frag;
+};
+
+const placeholder = ([label, file]) =>
+ `<p style="border:2px dashed #0f62fe;background:#edf5ff;padding:14px 18px;text-align:center;` +
+ `font-family:'IBM Plex Mono',ui-monospace,monospace;font-size:14px;color:#0f62fe">` +
+ `${label}: click here, use the toolbar image button to upload ` +
+ `<strong>${file}</strong>, then delete this line.</p>`;
+
+const hostedImage = ([label, file]) =>
+ `<p><img src="${HOSTED_BASE}/${file}" alt="${label}"` +
+ ` style="max-width:100%;height:auto;border:1px solid #e0e0e0;margin:8px 0"></p>`;
+
+writeFileSync(OUT_IBM, buildFragment(placeholder, ''), 'utf8');
+writeFileSync(OUT_IBM_HOSTED, buildFragment(hostedImage, LIVE_EMBED), 'utf8');
+
+console.log('wrote docs/ibm-community-defi-3d-sperax-post.md');
+console.log('wrote docs/ibm-community-defi-3d-sperax-post.html');
+console.log('wrote docs/ibm-community-defi-3d-sperax-post-ibm.html');
+console.log('wrote docs/ibm-community-defi-3d-sperax-post-ibm-hosted.html');
+console.log(` title: ${title}`);
+console.log(` editor notes stripped: ${notes.length}`);
+console.log(` words: ${body.split(/\s+/).filter(Boolean).length}`);
diff --git a/scripts/render-ibm-sperax-diagrams.mjs b/scripts/render-ibm-sperax-diagrams.mjs
new file mode 100644
index 000000000..d165fdaf2
--- /dev/null
+++ b/scripts/render-ibm-sperax-diagrams.mjs
@@ -0,0 +1,366 @@
+#!/usr/bin/env node
+// Renders the four diagrams for the IBM Community article draft
+// docs/ibm-community-defi-3d-sperax.md into docs/media/.
+//
+// Styled for IBM Community's light theme (IBM Plex Sans, Carbon greys, IBM
+// blue) so they sit natively in the post rather than looking pasted in.
+//
+// Every value drawn is read from the shipped source it describes:
+// - the emotion decay seconds come from SperaxOS src/components/Avatar3D/emotions.ts
+// - the tool names come from public/sperax/manifest.json
+// - the ported packages come from STRUCTURE.md and each package README
+//
+// node scripts/render-ibm-sperax-diagrams.mjs
+import { chromium } from 'playwright';
+import { mkdirSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const outDir = resolve(root, 'docs/media');
+mkdirSync(outDir, { recursive: true });
+
+const BLUE = '#0f62fe';
+const TEAL = '#007d79';
+const PURPLE = '#8a3ffc';
+const MAGENTA = '#d02670';
+const GREEN = '#198038';
+const INK = '#161616';
+const MUTE = '#525252';
+const LINE = '#e0e0e0';
+
+const shell = (w, body, extraCss = '') => `<!doctype html><html><head><meta charset="utf-8">
+<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=IBM+Plex+Sans:wght@400;500;600;700&display=swap" rel="stylesheet">
+<style>
+ *{ margin:0; padding:0; box-sizing:border-box; }
+ html,body{ width:${w}px; background:#fff; color:${INK};
+ font-family:'IBM Plex Sans', system-ui, sans-serif; }
+ .wrap{ width:100%; padding:56px 64px; display:flex; flex-direction:column; }
+ .kicker{ font-size:19px; font-weight:600; letter-spacing:.08em; text-transform:uppercase; color:${BLUE}; margin-bottom:10px; }
+ h1{ font-size:42px; font-weight:600; letter-spacing:-.01em; line-height:1.15; }
+ .sub{ font-size:21px; color:${MUTE}; margin-top:12px; line-height:1.45; max-width:1500px; }
+ .mono{ font-family:'IBM Plex Mono', ui-monospace, monospace; }
+ .foot{ margin-top:44px; padding-top:22px; border-top:1px solid ${LINE};
+ display:flex; justify-content:space-between; font-size:17px; color:${MUTE}; }
+ ${extraCss}
+</style></head><body><div class="wrap">${body}</div></body></html>`;
+
+const foot = (left) =>
+ `<div class="foot"><span>${left}</span><span class="mono">three.ws &times; SperaxOS</span></div>`;
+
+// ── 1. Two integration paths ────────────────────────────────────────────────
+const paths = () =>
+ shell(
+ 2000,
+ `
+ <div class="kicker">Embedding an agent in someone else's application</div>
+ <h1>Two integration paths. Ship both, in this order.</h1>
+ <div class="sub">The choice is not how to render an avatar. It is who owns the React tree.</div>
+ <div class="cols">
+ ${[
+ {
+ n: '1',
+ c: BLUE,
+ t: 'Standalone plugin',
+ w: 'The host will not take your code',
+ items: [
+ ['One hosted manifest', 'served with CORS at a well-known URL'],
+ ['One hosted iframe', 'the visible avatar panel'],
+ ['Four HTTP endpoints', 'render_agent, speak, gesture, emote'],
+ ],
+ pro: 'Live in a day. Nothing to vendor, review, or audit.',
+ con: 'No shared context. A second renderer. Cannot compose into a message.',
+ },
+ {
+ n: '2',
+ c: PURPLE,
+ t: 'Native component',
+ w: 'The host wants the dependency',
+ items: [
+ ['npm install three.ws', 'the &lt;agent-3d&gt; custom element'],
+ ['Same React tree', 'no iframe, no sandbox'],
+ ['Client tool lane', 'animation calls never leave the browser'],
+ ],
+ pro: 'Composes into chat messages. Finds the bugs the iframe hides.',
+ con: 'A dependency the host has to trust and upgrade.',
+ },
+ ]
+ .map(
+ (p) => `<div class="card" style="border-top:6px solid ${p.c}">
+ <div class="cn" style="color:${p.c}">Path ${p.n}</div>
+ <div class="ct">${p.t}</div>
+ <div class="cw">When: ${p.w}</div>
+ <div class="rows">${p.items
+ .map(
+ (i) =>
+ `<div class="row"><div class="rt mono" style="color:${p.c}">${i[0]}</div><div class="rs">${i[1]}</div></div>`,
+ )
+ .join('')}</div>
+ <div class="verdict"><span class="tag good">Gets you</span>${p.pro}</div>
+ <div class="verdict"><span class="tag bad">Costs you</span>${p.con}</div>
+ </div>`,
+ )
+ .join('')}
+ </div>
+ ${foot('SperaxOS is in both camps at once, so the integration has both halves')}`,
+ `
+ .cols{ display:grid; grid-template-columns:1fr 1fr; gap:34px; margin-top:36px; }
+ .card{ border:1px solid ${LINE}; background:#f4f4f4; padding:32px 34px 30px; display:flex; flex-direction:column; }
+ .cn{ font-size:17px; font-weight:600; letter-spacing:.08em; text-transform:uppercase; }
+ .ct{ font-size:34px; font-weight:600; margin-top:6px; }
+ .cw{ font-size:20px; color:${MUTE}; margin-top:6px; }
+ .rows{ margin-top:24px; display:flex; flex-direction:column; gap:14px; }
+ .row{ background:#fff; border:1px solid ${LINE}; padding:14px 18px; }
+ .rt{ font-size:20px; font-weight:500; }
+ .rs{ font-size:18px; color:${MUTE}; margin-top:3px; }
+ .verdict{ font-size:19px; color:${INK}; margin-top:18px; line-height:1.45; }
+ .tag{ display:inline-block; font-size:15px; font-weight:600; letter-spacing:.06em; text-transform:uppercase;
+ padding:3px 9px; margin-right:10px; vertical-align:2px; }
+ .good{ background:#defbe6; color:${GREEN}; }
+ .bad{ background:#fff1f1; color:${MAGENTA}; }`,
+ );
+
+// ── 2. Two halves per tool call ─────────────────────────────────────────────
+// The connector is one SVG rather than CSS pseudo-elements: borders on the
+// boxes plus 1px pseudo-element rules read as an unintended open rectangle.
+const forkConnector = () => {
+ const W = 1872;
+ const H = 92;
+ const cx = W / 2;
+ const lx = W * 0.235;
+ const rx = W * 0.765;
+ const head = (x) =>
+ `<path d="M ${x - 8} ${H - 13} L ${x} ${H - 1} L ${x + 8} ${H - 13}" fill="none" stroke="${MUTE}" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>`;
+ return `<svg width="${W}" height="${H}" viewBox="0 0 ${W} ${H}" style="display:block">
+ <path d="M ${cx} 0 L ${cx} ${H / 2} M ${lx} ${H / 2} L ${rx} ${H / 2} M ${lx} ${H / 2} L ${lx} ${H - 2} M ${rx} ${H / 2} L ${rx} ${H - 2}"
+ fill="none" stroke="${MUTE}" stroke-width="2"/>
+ ${head(lx)}${head(rx)}
+ </svg>`;
+};
+
+const halves = () =>
+ shell(
+ 2000,
+ `
+ <div class="kicker">The rule that keeps the body honest</div>
+ <h1>Every tool call runs in two halves, in parallel.</h1>
+ <div class="sub">The model never asserts that it waved. It receives a result saying the wave was dispatched, and the panel is what actually waved.</div>
+ <div class="flow">
+ <div class="step host">
+ <div class="sl">Host application</div>
+ <div class="sb mono">the model calls a tool<br><span style="color:${BLUE}">speak(text, sentiment)</span></div>
+ </div>
+ ${forkConnector()}
+ <div class="fork">
+ <div class="branch" style="border-top:5px solid ${PURPLE}">
+ <div class="bl" style="color:${PURPLE}">2a &nbsp;the visible body</div>
+ <div class="sb">host frames <span class="mono">ui.url</span> and posts the call into it<br>
+ <span class="mono" style="color:${PURPLE}">&lt;agent-3d&gt;</span> animates the avatar in the panel</div>
+ </div>
+ <div class="branch" style="border-top:5px solid ${TEAL}">
+ <div class="bl" style="color:${TEAL}">2b &nbsp;the model-facing result</div>
+ <div class="sb">gateway POSTs the arguments to <span class="mono">api[].url</span><br>
+ <span class="mono" style="color:${TEAL}">{ ok: true, action: "speak", spoken: "..." }</span></div>
+ </div>
+ </div>
+ </div>
+ <div class="note"><strong>The bug this prevents:</strong> the first version confirmed any agent ID. A user with a typo got a model
+ saying "I have bound to your agent" over an empty panel, forever. The endpoint now resolves the ID before it answers, and a
+ database outage degrades to an unverified binding rather than a 500, so an outage on one side never takes the host's chat panel down.</div>
+ ${foot('Both halves run on every call')}`,
+ `
+ .flow{ margin-top:40px; display:flex; flex-direction:column; align-items:center; }
+ .step{ border:1px solid ${LINE}; background:#f4f4f4; padding:22px 34px; text-align:center; min-width:660px; }
+ .host{ border-top:5px solid ${BLUE}; }
+ .sl{ font-size:17px; font-weight:600; letter-spacing:.08em; text-transform:uppercase; color:${MUTE}; }
+ .sb{ font-size:21px; margin-top:8px; line-height:1.55; }
+ .fork{ display:grid; grid-template-columns:1fr 1fr; gap:56px; width:100%; }
+ .branch{ border:1px solid ${LINE}; background:#fff; padding:24px 30px; }
+ .bl{ font-size:19px; font-weight:600; letter-spacing:.04em; text-transform:uppercase; margin-bottom:6px; }
+ .note{ margin-top:38px; border-left:5px solid ${BLUE}; background:#edf5ff; padding:20px 26px;
+ font-size:20px; line-height:1.55; color:${INK}; }`,
+ );
+
+// ── 3. Empathy Layer decay curves ───────────────────────────────────────────
+// intensity(t) = exp(-ln(20) * t / decaySeconds): a full spike reaches 0.05 at
+// decaySeconds, matching DECAY_FLOOR in emotions.ts.
+const EMOTIONS = [
+ { name: 'celebration', secs: 6, color: MAGENTA, why: 'bright but brief' },
+ { name: 'curiosity', secs: 8, color: BLUE, why: 'alert, engaged' },
+ { name: 'concern', secs: 12, color: '#ff832b', why: 'lingers, so a risk stays on the face' },
+ { name: 'empathy', secs: 13, color: PURPLE, why: 'slow to fade, like the real thing' },
+ { name: 'patience', secs: 20, color: TEAL, why: 'sustained waiting state' },
+];
+
+function decayChart() {
+ const W = 1080;
+ const H = 470;
+ const PADL = 74;
+ const PADB = 62;
+ const PADT = 18;
+ const TMAX = 22;
+ const x = (t) => PADL + (t / TMAX) * (W - PADL - 30);
+ const y = (v) => PADT + (1 - v) * (H - PADT - PADB);
+ const ln20 = Math.log(20);
+ const curves = EMOTIONS.map((e) => {
+ const pts = [];
+ for (let i = 0; i <= 220; i++) {
+ const t = (i / 220) * TMAX;
+ pts.push(`${x(t).toFixed(1)},${y(Math.exp((-ln20 * t) / e.secs)).toFixed(1)}`);
+ }
+ return `<polyline points="${pts.join(' ')}" fill="none" stroke="${e.color}" stroke-width="3.5" stroke-linecap="round"/>
+ <circle cx="${x(e.secs).toFixed(1)}" cy="${y(0.05).toFixed(1)}" r="5" fill="${e.color}"/>`;
+ }).join('');
+ const grid = [0, 0.25, 0.5, 0.75, 1]
+ .map(
+ (v) =>
+ `<line x1="${PADL}" y1="${y(v)}" x2="${W - 30}" y2="${y(v)}" stroke="${LINE}" stroke-width="1"/>
+ <text x="${PADL - 14}" y="${y(v) + 6}" text-anchor="end" font-size="17" fill="${MUTE}" font-family="IBM Plex Mono">${v.toFixed(2)}</text>`,
+ )
+ .join('');
+ const ticks = [0, 5, 10, 15, 20]
+ .map(
+ (t) =>
+ `<text x="${x(t)}" y="${H - PADB + 30}" text-anchor="middle" font-size="17" fill="${MUTE}" font-family="IBM Plex Mono">${t}s</text>`,
+ )
+ .join('');
+ return `<svg width="${W}" height="${H}" viewBox="0 0 ${W} ${H}">
+ ${grid}
+ <line x1="${PADL}" y1="${y(0.05)}" x2="${W - 30}" y2="${y(0.05)}" stroke="${MUTE}" stroke-width="1" stroke-dasharray="5 5"/>
+ <text x="${W - 32}" y="${y(0.05) - 12}" text-anchor="end" font-size="17" fill="${MUTE}" font-family="IBM Plex Mono">DECAY_FLOOR 0.02 to 0.05</text>
+ ${curves}${ticks}
+ <text x="${PADL}" y="${H - 12}" font-size="18" fill="${MUTE}">time since the event spiked the emotion</text>
+ </svg>`;
+}
+
+const empathy = () =>
+ shell(
+ 2000,
+ `
+ <div class="kicker">Section 2 &middot; the Empathy Layer</div>
+ <h1>A continuous blend, not a state machine.</h1>
+ <div class="sub">Each emotion is a float in [0, 1]. Events spike it, and it decays exponentially at its own rate. Every active
+ emotion is blended into morph targets and body language on every frame, so a face can hold three feelings at once.</div>
+ <div class="grid">
+ <div class="chart">${decayChart()}</div>
+ <div class="legend">
+ <div class="lh">Decay is the personality</div>
+ ${EMOTIONS.map(
+ (e) => `<div class="li">
+ <span class="swatch" style="background:${e.color}"></span>
+ <span class="ln mono">${e.name}</span>
+ <span class="ls mono">${e.secs}s</span>
+ <span class="lw">${e.why}</span>
+ </div>`,
+ ).join('')}
+ <div class="blendbox">
+ <div class="lh" style="margin-bottom:14px">What a face holds at one moment</div>
+ ${[
+ ['concern', 40, '#ff832b'],
+ ['curiosity', 30, BLUE],
+ ['neutral', 30, '#8d8d8d'],
+ ]
+ .map(
+ ([n, p, c]) => `<div class="bar">
+ <span class="bn mono">${n}</span>
+ <span class="btrack"><span class="bfill" style="width:${p}%;background:${c}"></span></span>
+ <span class="bp mono">${p}%</span></div>`,
+ )
+ .join('')}
+ <div class="bnote">A state machine has to pick one of these. That snap is what reads as a cartoon.</div>
+ </div>
+ </div>
+ </div>
+ ${foot('Values read from the shipped emotion table, ported between both codebases')}`,
+ `
+ .grid{ display:grid; grid-template-columns:1080px 1fr; gap:44px; margin-top:32px; align-items:start; }
+ .chart{ border:1px solid ${LINE}; background:#f4f4f4; padding:16px 10px 4px; }
+ .legend{ display:flex; flex-direction:column; }
+ .lh{ font-size:19px; font-weight:600; letter-spacing:.06em; text-transform:uppercase; color:${MUTE}; margin-bottom:16px; }
+ .li{ display:flex; align-items:baseline; gap:12px; padding:11px 0; border-bottom:1px solid ${LINE}; }
+ .swatch{ width:16px; height:16px; flex:0 0 16px; }
+ .ln{ font-size:21px; font-weight:500; width:170px; }
+ .ls{ font-size:21px; color:${INK}; width:64px; }
+ .lw{ font-size:18px; color:${MUTE}; }
+ .blendbox{ margin-top:34px; border:1px solid ${LINE}; background:#edf5ff; padding:24px 26px; }
+ .bar{ display:flex; align-items:center; gap:14px; margin-bottom:12px; }
+ .bn{ font-size:19px; width:140px; }
+ .btrack{ flex:1; height:16px; background:#fff; border:1px solid ${LINE}; }
+ .bfill{ display:block; height:100%; }
+ .bp{ font-size:19px; width:60px; text-align:right; }
+ .bnote{ font-size:18px; color:${MUTE}; margin-top:14px; line-height:1.5; }`,
+ );
+
+// ── 4. Two-way code exchange ────────────────────────────────────────────────
+const exchange = () =>
+ shell(
+ 2000,
+ `
+ <div class="kicker">Section 5 &middot; the part nobody puts in a press release</div>
+ <h1>Most of the code moved in the direction opposite to the marketing.</h1>
+ <div class="sub">If you are negotiating an integration, this is the clause to push for: a shared right to port implementation between the two codebases.</div>
+ <div class="ex">
+ <div class="side">
+ <div class="sh" style="color:${BLUE}">three.ws &rarr; SperaxOS</div>
+ ${[
+ ['Empathy Layer', 'continuous emotion blend, engine kept pure'],
+ ['Lip-sync driver', 'RMS amplitude to a jaw morph, composed on top'],
+ ['Inline 3D chat element', 'a live model inside a markdown message'],
+ ['Client tool dispatcher', 'animation calls never round-trip a server'],
+ ['Hash-chained action ledger', 'plus the reconcile job that reads it'],
+ ]
+ .map(
+ (i) =>
+ `<div class="item"><div class="it">${i[0]}</div><div class="is">${i[1]}</div></div>`,
+ )
+ .join('')}
+ </div>
+ <div class="arrows"><div class="a" style="color:${BLUE}">&rarr;</div><div class="a" style="color:${TEAL}">&larr;</div></div>
+ <div class="side">
+ <div class="sh" style="color:${TEAL}">SperaxOS &rarr; three.ws</div>
+ ${[
+ ['@three-ws/defi-utils', 'chain and token constants, address validation'],
+ ['@three-ws/tool-sdk', 'defineTool, defineExecutor, toMcpTools'],
+ ['Liquidation collector', 'three exchange streams, since hardened'],
+ ['Rigor about sourcing', 'no figure ships that cannot be read live'],
+ ['A second production host', 'the environment that found our real bugs'],
+ ]
+ .map(
+ (i) =>
+ `<div class="item"><div class="it">${i[0]}</div><div class="is">${i[1]}</div></div>`,
+ )
+ .join('')}
+ </div>
+ </div>
+ ${foot('A partnership measured in merged code ages better than one measured in announcements')}`,
+ `
+ .ex{ display:grid; grid-template-columns:1fr 120px 1fr; gap:0; margin-top:38px; align-items:start; }
+ .side{ border:1px solid ${LINE}; background:#f4f4f4; padding:28px 30px; }
+ .sh{ font-size:23px; font-weight:600; letter-spacing:.04em; text-transform:uppercase; margin-bottom:20px; }
+ .item{ background:#fff; border:1px solid ${LINE}; padding:14px 18px; margin-bottom:12px; }
+ .it{ font-size:22px; font-weight:500; }
+ .is{ font-size:18px; color:${MUTE}; margin-top:3px; }
+ .arrows{ display:flex; flex-direction:column; align-items:center; justify-content:center; height:100%; padding-top:90px; gap:26px; }
+ .a{ font-size:56px; line-height:1; }`,
+ );
+
+const JOBS = [
+ ['ibm-sperax-integration-paths.png', paths()],
+ ['ibm-sperax-tool-call-halves.png', halves()],
+ ['ibm-sperax-empathy-decay.png', empathy()],
+ ['ibm-sperax-code-exchange.png', exchange()],
+];
+
+// Height is whatever the content needs: a fixed canvas leaves a band of dead
+// white under every diagram, which reads as a broken image in a blog post.
+const browser = await chromium.launch();
+for (const [file, html] of JOBS) {
+ const page = await browser.newPage({ viewport: { width: 2000, height: 800 }, deviceScaleFactor: 1 });
+ await page.setContent(html, { waitUntil: 'networkidle' });
+ await page.evaluate(() => document.fonts.ready);
+ await page.screenshot({ path: resolve(outDir, file), fullPage: true });
+ const box = await page.evaluate(() => document.body.scrollHeight);
+ await page.close();
+ console.log(`wrote docs/media/${file} (2000x${box})`);
+}
+await browser.close();
diff --git a/scripts/render-ibm-sperax-featured.mjs b/scripts/render-ibm-sperax-featured.mjs
new file mode 100644
index 000000000..565071277
--- /dev/null
+++ b/scripts/render-ibm-sperax-featured.mjs
@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// Renders the featured image for the IBM Community post: the three partner logos
+// on white, nothing else.
+//
+// IBM Community's featured-image guidance asks for a landscape image of at least
+// 1200x600 and warns against text, because the card crops differently across the
+// site. Logos are the exception the author asked for; everything else stays out,
+// and the composition is centred so a tighter crop loses only white space.
+//
+// Sources, all local:
+// IBM cropped from docs/media/ibm-x-threews-lockup.png (the group's own lockup)
+// three.ws public/brand/three-ws-lockup-on-light.png
+// Sperax the SperaxOS repo's public/sperax.svg, inlined and forced to black
+//
+// node scripts/render-ibm-sperax-featured.mjs
+import { chromium } from 'playwright';
+import sharp from 'sharp';
+import { readFileSync, existsSync, mkdirSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const outDir = resolve(root, 'docs/media');
+mkdirSync(outDir, { recursive: true });
+
+const SPERAX_SVG = '/workspaces/sperax-fix/repo/public/sperax.svg';
+if (!existsSync(SPERAX_SVG)) {
+ throw new Error(
+ `Sperax logo not found at ${SPERAX_SVG}. It lives in the SperaxOS checkout, not this repo; ` +
+ 'clone it or point this constant at another copy before rendering.',
+ );
+}
+
+// The IBM mark is cropped out of the group's existing lockup so this script never
+// needs a separate trademark asset checked in.
+const ibmMark = await sharp(resolve(root, 'docs/media/ibm-x-threews-lockup.png'))
+ .extract({ left: 260, top: 440, width: 816, height: 320 })
+ .png()
+ .toBuffer();
+
+const b64 = (buf) => `data:image/png;base64,${buf.toString('base64')}`;
+const threeWs = readFileSync(resolve(root, 'public/brand/three-ws-lockup-on-light.png'));
+// Two fixes to the Sperax file. Its mark is drawn in currentColor, so one colour
+// declaration blackens it. And its width/height attributes (500.6 x 500, square)
+// contradict its viewBox (183 x 39, wide), which makes any CSS height render the
+// artwork at a fraction of the box it reserves. Strip both and let the viewBox
+// drive the aspect ratio.
+const sperax = readFileSync(SPERAX_SVG, 'utf8')
+ .replace(/\s(width|height)="[^"]*"/g, '')
+ .replace('<svg ', '<svg preserveAspectRatio="xMidYMid meet" style="color:#161616" ');
+
+const W = 2400;
+const H = 1200;
+const html = `<!doctype html><html><head><meta charset="utf-8"><style>
+ *{margin:0;padding:0;box-sizing:border-box}
+ html,body{width:${W}px;height:${H}px;background:#fff;overflow:hidden}
+ .row{width:100%;height:100%;display:flex;align-items:center;justify-content:center;gap:120px;padding:0 200px}
+ .slot{display:flex;align-items:center;justify-content:center}
+ .slot img,.slot svg{display:block;width:auto}
+ /* Each lockup has a different ink-to-box ratio, so heights are tuned for equal
+ optical weight rather than set to one shared number. */
+ .sperax svg{height:108px}
+ .tws img{height:168px}
+ .ibm img{height:126px}
+ .sep{width:2px;height:140px;background:#e0e0e0;flex:0 0 2px}
+</style></head><body>
+ <div class="row">
+ <div class="slot sperax">${sperax}</div>
+ <div class="sep"></div>
+ <div class="slot tws"><img src="${b64(threeWs)}" alt=""></div>
+ <div class="sep"></div>
+ <div class="slot ibm"><img src="${b64(ibmMark)}" alt=""></div>
+ </div>
+</body></html>`;
+
+const browser = await chromium.launch();
+const page = await browser.newPage({ viewport: { width: W, height: H }, deviceScaleFactor: 1 });
+await page.setContent(html, { waitUntil: 'networkidle' });
+await page.screenshot({ path: resolve(outDir, 'ibm-sperax-featured.png') });
+await browser.close();
+
+console.log(`wrote docs/media/ibm-sperax-featured.png (${W}x${H})`);