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(guards): register the new surfaces guards and finish the herald SDK README

nirholas7571925504fa
diff --git a/data/guards.json b/data/guards.json
index 489d873a8..1a38e042d 100644
--- a/data/guards.json
+++ b/data/guards.json
@@ -1027,6 +1027,27 @@
},
"expect": "rugcheck.js"
}
+ },
+ {
+ "id": "check-ios-icons",
+ "script": "ios/scripts/make-icons.mjs",
+ "npm": "check:ios-icons",
+ "title": "The iOS app icon still is the brand mark",
+ "protects": "The committed app icon and launch images are exactly what the current brand mark produces, and the icon carries no alpha channel.",
+ "why": "The iOS icon is the one asset that cannot be generated at build time: it is compiled into the .ipa from Assets.xcassets, so whatever is committed is what ships to every home screen. Both failure modes are silent. A hand-exported replacement drifts away from public/pwa-512x512.png and nothing anywhere notices, so the app wears a stale mark for a release cycle. And an icon that reaches App Store Connect with an alpha channel is rejected outright, which surfaces at upload time on someone else's Mac, hours after the change that caused it. Re-deriving the assets and comparing bytes catches both before either can leave the repository.",
+ "stages": [
+ "gate"
+ ],
+ "needs": "none",
+ "proof": {
+ "summary": "The committed app icon replaced with bytes the brand mark does not produce.",
+ "violation": {
+ "write": {
+ "ios/native/App/App/Assets.xcassets/AppIcon.appiconset/[email protected]": "not the brand mark\n"
+ }
+ },
+ "expect": "app icon"
+ }
}
],
"exempt": [
diff --git a/docs/guards.md b/docs/guards.md
index 1d4fb886d..e14da0800 100644
--- a/docs/guards.md
+++ b/docs/guards.md
@@ -96,6 +96,7 @@ Run `npm run audit:guards` to print the current count and per-stage breakdown. T
| The guard registry | `npm run audit:guards` | Every guard is registered and every stage claim is true. |
| Design-token ratchet | `npm run audit:tokens` | Hardcoded colour hexes cannot creep back past a committed baseline. |
| Credential material | `npm run check:secrets` | No dotenv file, private key, keystore, or downloaded cloud credential becomes a tracked file, and no added line carries a provider-issued key. |
+| iOS app icon | `npm run check:ios-icons` | The committed iOS icon and launch images are exactly what the current brand mark produces, and the icon carries no alpha channel. |
### Routing and pages
diff --git a/docs/herald.md b/docs/herald.md
index 7cfe13f68..6e61229f0 100644
--- a/docs/herald.md
+++ b/docs/herald.md
@@ -45,6 +45,12 @@ npm install @three-ws/herald
npm install @three-ws/walk three
```
+The avatar presenter finds a companion in three places, cheapest first: one you
+pass in (`createHerald({ companion })`), one already live on the page
+(`window.__walkCompanion`, which is what every three.ws page has), or a module
+URL you name (`avatarOptions: { walkModule: '/walk-companion.js' }`). None of
+them is a static import, so the optional 3D body can never break a build.
+
```js
import { createHerald } from '@three-ws/herald';
diff --git a/herald-sdk/README.md b/herald-sdk/README.md
index ee316a29a..12c7651b3 100644
--- a/herald-sdk/README.md
+++ b/herald-sdk/README.md
@@ -159,9 +159,26 @@ Reasons are stable strings: `duplicate`, `stale`, `below-importance-floor`,
| Presenter | Needs | Used when |
| --- | --- | --- |
-| `avatar` | `@three-ws/walk` or the CDN build, WebGL | A body can be rendered |
+| `avatar` | A walk companion and WebGL | A body can be rendered |
| `card` | Nothing | Everything else |
+The avatar presenter looks for a companion in three places, cheapest first: one
+you passed in, one already live on the page (`window.__walkCompanion`), or a
+module URL you name.
+
+```js
+import { createWalkCompanion } from '@three-ws/walk';
+
+const walk = createWalkCompanion();
+const herald = createHerald({ companion: walk }); // hand it over, or
+
+createHerald({ avatarOptions: { walkModule: '/walk-companion.js' } }); // name a build
+```
+
+The import is never a static specifier, so an optional 3D body can never become
+a hard build-time dependency: with none of the three available, deliveries use
+the card and nothing breaks.
+
`presenter: 'auto'` (the default) tries the avatar and falls back to the card,
per page, once. The card is not a consolation prize: it is theme-aware, honours
`prefers-reduced-motion` and `prefers-color-scheme`, is dismissible with
diff --git a/public/guards.json b/public/guards.json
index 489d873a8..1a38e042d 100644
--- a/public/guards.json
+++ b/public/guards.json
@@ -1027,6 +1027,27 @@
},
"expect": "rugcheck.js"
}
+ },
+ {
+ "id": "check-ios-icons",
+ "script": "ios/scripts/make-icons.mjs",
+ "npm": "check:ios-icons",
+ "title": "The iOS app icon still is the brand mark",
+ "protects": "The committed app icon and launch images are exactly what the current brand mark produces, and the icon carries no alpha channel.",
+ "why": "The iOS icon is the one asset that cannot be generated at build time: it is compiled into the .ipa from Assets.xcassets, so whatever is committed is what ships to every home screen. Both failure modes are silent. A hand-exported replacement drifts away from public/pwa-512x512.png and nothing anywhere notices, so the app wears a stale mark for a release cycle. And an icon that reaches App Store Connect with an alpha channel is rejected outright, which surfaces at upload time on someone else's Mac, hours after the change that caused it. Re-deriving the assets and comparing bytes catches both before either can leave the repository.",
+ "stages": [
+ "gate"
+ ],
+ "needs": "none",
+ "proof": {
+ "summary": "The committed app icon replaced with bytes the brand mark does not produce.",
+ "violation": {
+ "write": {
+ "ios/native/App/App/Assets.xcassets/AppIcon.appiconset/[email protected]": "not the brand mark\n"
+ }
+ },
+ "expect": "app icon"
+ }
}
],
"exempt": [