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(dashboard): document the avatar storage panel in the account flow

nirholas115bfed231a8
diff --git a/docs/ux-flows/11-account-dashboard.md b/docs/ux-flows/11-account-dashboard.md
index ec49bab9c..1a4c72982 100644
--- a/docs/ux-flows/11-account-dashboard.md
+++ b/docs/ux-flows/11-account-dashboard.md
@@ -152,20 +152,21 @@ Shared auth concepts:
- **Prerequisites / gates:** Signed-in required (`requireUser()`; 401 → `/login?return=…`).
- **Steps (N):**
1. Boot: `mountShell()` → `requireUser()`; 4 skeletons while data loads.
- 2. Parallel fetch: `GET /api/auth/sessions`, `GET /api/notifications?limit=20`, `GET /api/notifications/preferences`, `GET /api/billing/summary` (storage), `GET /api/usage/summary` (LLM usage), `GET /api/dashboard/prefs`.
- 3. Render sections: **Appearance/theme**, **Active sessions**, **Notifications**, **Notification preferences**, **Default payment network**, **Storage usage**, **LLM usage**, **Vanity wallet tools**, **Preferences**, **Data export**, **About**.
+ 2. Parallel fetch: `GET /api/auth/sessions`, `GET /api/notifications?limit=20`, `GET /api/notifications/preferences`, `GET /api/avatars/mine?limit=24` (per-avatar storage mode), `GET /api/billing/summary` (storage), `GET /api/usage/summary` (LLM usage), `GET /api/dashboard/prefs`, `GET /api/version` (About).
+ 3. Render sections: **Appearance/theme**, **Active sessions**, **Notifications**, **Notification preferences**, **Default payment network**, **Avatar storage**, **Storage usage**, **LLM usage**, **Vanity wallet tools**, **Preferences**, **Data export**, **About**.
4. **(optional) Theme:** click Dark/Light/Auto → `localStorage['twx_theme']` (+ `window.threeTheme.set`) → toast "Theme applied" (no API).
5. **(optional) Sessions:** "Revoke" → `DELETE /api/auth/sessions/{id}` → toast + row removed; "Revoke all other" → `DELETE /api/auth/sessions` (revokes every other session **and rotates the current session cookie**) → toast.
6. **(optional) Notifications:** "Mark all read" → `POST /api/notifications/read-all` → toast. The inbox covers the full bell vocabulary (sales, purchases, follows, remixes, DMs, coin-launch graduations, IRL, market, account).
6b. **(optional) Notification preferences:** a category × channel matrix driven by the server response (`categories` + `channels`, default channels in-app / push / email / Telegram / avatar). The **Avatar** column routes a category to the corner companion, which walks on screen and says the message out loud while the user is on the site; a hint line under the table explains it, and it can be muted per browser from the bubble's "Turn off" control. The response also carries `type_categories` (notification type → category), so the client-side herald (`src/notification-herald.js`) gates the avatar channel with the same mapping the server uses for push and email. Toggles flip locally; a single **Save notification preferences** button sends the whole matrix via `PUT /api/notifications/preferences` `{ categories }` → toast "Notification preferences saved". Per-category `lockedChannels` render disabled (in-app is typically locked on); the Telegram column stays disabled ("Link a Telegram chat id to enable") until `telegram_chat_id` is set; a footer reports subscribed push devices.
+ 6c. **(optional) Avatar storage (R2 vs IPFS):** one row per avatar the caller owns, listing its size, its R2 copy, and its IPFS state. `GET /api/avatars/mine` carries a flattened `storage` block (`primary`, `r2_present`, `ipfs_pinned`, `ipfs_cid`, `ipfs_pinned_at`) so the panel needs no per-avatar request. **Pin to IPFS** → `POST /api/avatars/:id/pin-ipfs` reads the object out of R2 and pins it through the provider chain (Pinata, then web3.storage), and the row repaints with the CID linked to a public gateway. A deployment with no pinning provider answers `stub: true` with a `stub:` pseudo-CID: that is a recorded content hash, not a pin, and the row says exactly that ("Content hash only") instead of linking a CID that resolves nowhere. The **R2 / IPFS** segmented control sets which copy a viewer resolves first; it re-reads `GET /api/avatars/:id/storage-mode` and writes the whole record back with `PUT`, because the schema is whole-object and the server owns the attestation block. The IPFS half stays disabled until a real pin exists.
7. **(optional) Default network:** Base/Solana/Polygon → `localStorage['twx_default_network']` + best-effort `PATCH /api/dashboard/prefs` `{ prefs: { default_network } }` → toast.
8. **(optional) Preferences:** toggle email notifications / show tips / compact sidebar → **Save preferences** → `PATCH /api/dashboard/prefs` `{ prefs }` → toast "Preferences saved".
9. **(optional) Data export:** Agents / Avatars / All → fetch `GET /api/agents`, `GET /api/avatars?limit=100`, `GET /api/widgets` → build JSON blob → browser download → toast "Data exported".
- **Decision points / branches:** Theme, default network, and privacy-style toggles are local-first (localStorage) with best-effort prefs sync; sessions/notifications/export hit live APIs. Read-only meters for storage/LLM usage.
-- **External calls / dependencies:** `GET /api/auth/me`, `GET /api/auth/sessions`, `DELETE /api/auth/sessions/{id}`, `DELETE /api/auth/sessions` (revoke-others + cookie rotation), `GET /api/notifications`, `POST /api/notifications/read-all`, `GET /api/notifications/preferences`, `PUT /api/notifications/preferences`, `GET /api/billing/summary`, `GET /api/usage/summary`, `GET`/`PATCH /api/dashboard/prefs`, `GET /api/agents`, `GET /api/avatars`, `GET /api/widgets`.
+- **External calls / dependencies:** `GET /api/auth/me`, `GET /api/auth/sessions`, `DELETE /api/auth/sessions/{id}`, `DELETE /api/auth/sessions` (revoke-others + cookie rotation), `GET /api/notifications`, `POST /api/notifications/read-all`, `GET /api/notifications/preferences`, `PUT /api/notifications/preferences`, `GET /api/avatars/mine`, `POST /api/avatars/{id}/pin-ipfs`, `GET`/`PUT /api/avatars/{id}/storage-mode`, `GET /api/billing/summary`, `GET /api/usage/summary`, `GET`/`PATCH /api/dashboard/prefs`, `GET /api/version`, `GET /api/agents`, `GET /api/avatars`, `GET /api/widgets`.
- **Success state:** Toasts on each action (Theme applied / Session revoked / All notifications marked read / Default network set / Preferences saved / Data exported); sections reflect new state.
-- **Empty / error states:** "No session data", "No notifications" / "You're all caught up", "No usage data"; per-action error toasts with button re-enable for retry; skeletons during load.
-- **Step count:** 3 required (boot + fetch + render) (+6 optional setting flows)
+- **Empty / error states:** "No session data", "No notifications" / "You're all caught up", "No avatars yet" (with a **Create an avatar** action to `/create`), "No usage data"; a panel whose fetch failed renders an in-place error state with a working **Retry** that re-fetches every panel; per-action error toasts with button re-enable for retry; skeletons during load.
+- **Step count:** 3 required (boot + fetch + render) (+7 optional setting flows)
---