feat(skill): sync canonical daemon docs at build + modernize app template

Pull the canonical Reachy Mini docs (APP_CREATION_GUIDE, javascript-sdk,
AGENTS + robot-knowledge skills) from pollen-robotics/reachy_mini@main on
every build via scripts/sync-daemon-docs.mjs, and resolve the canonical SDK
pin (max of npm dist-tags latest/rc) to keep the generated app template in
sync. Network-tolerant: keeps the committed snapshot on fetch failure.

Modernize the generated 3-file app template to the published npm SDK:
- import @pollen-robotics/reachy-mini-sdk from jsDelivr /+esm (no bundler),
replacing the stale gh feature-branch single-file build
- setHeadPose -> setHeadRpyDeg, setAntennas(rad) -> setAntennasDeg(deg),
add setBodyYawDeg
- point the agent at the auto-fetched daemon/ docs, with a guardrail that
the upstream npm/Vite/mountHost toolchain does NOT apply here

Make skill-loader discover docs recursively so daemon/*.md are exposed via
read_skill_doc. The auth/session lifecycle and 3-file/no-build constraints
are unchanged.

Co-authored-by: Cursor <cursoragent@cursor.com>

Dockerfile

@@ -47,8 +47,11 @@ COPY --from=backend-builder /build/backend/node_modules   /app/backend/node_modu
 COPY --from=backend-builder /build/backend/package.json   /app/backend/package.json
 
 # Skills are loaded from source markdown at runtime (skill-loader.ts reads
-# them from disk). Ship them alongside the compiled JS.
-COPY backend/src/agent/skills /app/backend/dist/agent/skills
+# them from disk). We copy them FROM the backend-builder stage (not the build
+# context) so the build-time `sync-daemon-docs.mjs` output is included: the
+# freshly fetched `daemon/*.md` canonical docs and the SDK pin substituted into
+# SKILL.md.
+COPY --from=backend-builder /build/backend/src/agent/skills /app/backend/dist/agent/skills
 
 # Frontend static build - server.ts detects this folder automatically.
 COPY --from=frontend-builder /build/frontend/dist /app/frontend/dist

backend/package.json

@@ -5,7 +5,8 @@
   "type": "module",
   "scripts": {
     "dev": "tsx watch src/server.ts",
-    "build": "tsc",
+    "sync-docs": "node scripts/sync-daemon-docs.mjs",
+    "build": "node scripts/sync-daemon-docs.mjs && tsc",
     "start": "node dist/server.js",
     "typecheck": "tsc --noEmit"
   },

backend/scripts/sync-daemon-docs.mjs

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+// Sync canonical Reachy Mini docs from the daemon repo at build time.
+//
+// Why: the vibe-coder ships an agent skill that teaches an LLM how to build a
+// Reachy Mini browser app. The robot knowledge and the JS SDK surface live in
+// `pollen-robotics/reachy_mini`. Hand-copying them here drifts. Instead we pull
+// the canonical markdown from the daemon `main` branch on every build and we
+// resolve the canonical SDK pin from the npm dist-tags, then substitute it into
+// the generated app template (SKILL.md).
+//
+// This runs inside the Docker `backend-builder` stage (via `npm run build`) and
+// locally (`npm run sync-docs`). It is network-tolerant: if the registry or
+// raw.githubusercontent is unreachable, it keeps the committed snapshot and
+// exits 0 so the build never breaks.
+
+import { mkdir, writeFile, readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SKILL_DIR = path.resolve(
+  __dirname,
+  "../src/agent/skills/reachy-mini-app",
+);
+const DAEMON_DIR = path.join(SKILL_DIR, "daemon");
+const SKILL_HUB = path.join(SKILL_DIR, "SKILL.md");
+
+const DAEMON_REPO = "pollen-robotics/reachy_mini";
+// Defaults to `main` (the durable canonical ref). Override with
+// DAEMON_DOCS_REF to track a branch/tag/SHA - e.g. an unmerged docs PR that
+// already carries the modern bare-HTML + CDN guidance.
+const DAEMON_REF = process.env.DAEMON_DOCS_REF || "main";
+const RAW_BASE = `https://raw.githubusercontent.com/${DAEMON_REPO}/${DAEMON_REF}`;
+
+const SDK_PKG = "@pollen-robotics/reachy-mini-sdk";
+const NPM_REGISTRY = `https://registry.npmjs.org/${SDK_PKG}`;
+const JSDELIVR_META = `https://data.jsdelivr.com/v1/packages/npm/${SDK_PKG}`;
+
+// Canonical daemon docs to mirror. `remote` is relative to the repo root,
+// `local` is the filename written under `daemon/` (auto-discovered by the
+// skill-loader, exposed to the agent via `read_skill_doc`).
+const DOCS = [
+  // The single source of truth for building a JS app. Its bare-HTML + CDN
+  // section is the pattern this vibe-coder uses; its robotics best-practices
+  // section covers safe teardown.
+  { remote: "ts/APP_CREATION_GUIDE.md", local: "APP_CREATION_GUIDE.md" },
+  // JS SDK runtime reference - the authoritative method/event names.
+  { remote: "docs/source/SDK/javascript-sdk.md", local: "javascript-sdk.md" },
+  // Top-level orientation hub.
+  { remote: "AGENTS.md", local: "AGENTS.md" },
+  // Robot-knowledge skills (behaviour, motion, interaction, low-level access).
+  { remote: "skills/motion-philosophy.md", local: "motion-philosophy.md" },
+  { remote: "skills/interaction-patterns.md", local: "interaction-patterns.md" },
+  { remote: "skills/control-loops.md", local: "control-loops.md" },
+  { remote: "skills/rest-api.md", local: "rest-api.md" },
+  { remote: "skills/safe-torque.md", local: "safe-torque.md" },
+];
+
+const FETCH_TIMEOUT_MS = 15_000;
+
+async function fetchText(url) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), FETCH_TIMEOUT_MS);
+  try {
+    const res = await fetch(url, { signal: ctrl.signal });
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    return await res.text();
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function fetchJson(url) {
+  return JSON.parse(await fetchText(url));
+}
+
+// ── semver (prerelease-aware) ───────────────────────────────────────────────
+// Minimal comparator: numeric core dominates; a prerelease ranks below its own
+// release but we only ever compare tags against each other, so the standard
+// semver precedence rules are enough.
+function parseSemver(v) {
+  const m = /^(\d+)\.(\d+)\.(\d+)(?:-(.+))?$/.exec(String(v).trim());
+  if (!m) return null;
+  return {
+    major: Number(m[1]),
+    minor: Number(m[2]),
+    patch: Number(m[3]),
+    prerelease: m[4] ?? null,
+  };
+}
+
+function comparePrerelease(a, b) {
+  // No prerelease ranks higher than a prerelease (1.8.0 > 1.8.0-rc1).
+  if (a === null && b === null) return 0;
+  if (a === null) return 1;
+  if (b === null) return -1;
+  const as = a.split(".");
+  const bs = b.split(".");
+  for (let i = 0; i < Math.max(as.length, bs.length); i++) {
+    const x = as[i];
+    const y = bs[i];
+    if (x === undefined) return -1;
+    if (y === undefined) return 1;
+    const xn = /^\d+$/.test(x);
+    const yn = /^\d+$/.test(y);
+    if (xn && yn) {
+      const d = Number(x) - Number(y);
+      if (d !== 0) return d < 0 ? -1 : 1;
+    } else if (xn !== yn) {
+      return xn ? -1 : 1; // numeric identifiers rank lower than alphanumeric
+    } else if (x !== y) {
+      return x < y ? -1 : 1;
+    }
+  }
+  return 0;
+}
+
+function compareSemver(a, b) {
+  const pa = parseSemver(a);
+  const pb = parseSemver(b);
+  if (!pa && !pb) return 0;
+  if (!pa) return -1;
+  if (!pb) return 1;
+  for (const key of ["major", "minor", "patch"]) {
+    if (pa[key] !== pb[key]) return pa[key] < pb[key] ? -1 : 1;
+  }
+  return comparePrerelease(pa.prerelease, pb.prerelease);
+}
+
+function semverMax(...versions) {
+  return versions
+    .filter(Boolean)
+    .reduce((best, v) => (best && compareSemver(best, v) >= 0 ? best : v), null);
+}
+
+// ── canonical pin resolution ────────────────────────────────────────────────
+// Canonical = max(latest, rc): always the newest published release, including
+// a release candidate when one is ahead of the stable `latest`.
+async function resolveCanonicalPin() {
+  let tags = null;
+  try {
+    const meta = await fetchJson(NPM_REGISTRY);
+    tags = meta?.["dist-tags"] ?? null;
+  } catch (err) {
+    console.warn(`[sync-docs] npm registry unreachable (${err.message}), trying jsDelivr`);
+  }
+  if (!tags) {
+    try {
+      const meta = await fetchJson(JSDELIVR_META);
+      tags = meta?.tags ?? null;
+    } catch (err) {
+      console.warn(`[sync-docs] jsDelivr unreachable (${err.message})`);
+    }
+  }
+  if (!tags) return null;
+  const pin = semverMax(tags.latest, tags.rc);
+  if (pin) {
+    console.log(
+      `[sync-docs] dist-tags latest=${tags.latest} rc=${tags.rc} -> canonical pin ${pin}`,
+    );
+  }
+  return pin;
+}
+
+// ── doc sync ────────────────────────────────────────────────────────────────
+function buildHeader(remote, pin) {
+  const stamp = new Date().toISOString().slice(0, 10);
+  const pinLine = pin ? ` · canonical SDK pin: \`${pin}\`` : "";
+  return (
+    `> **Auto-fetched** from [\`${DAEMON_REPO}@${DAEMON_REF}\`](https://github.com/${DAEMON_REPO}/blob/${DAEMON_REF}/${remote}) ` +
+    `on ${stamp}${pinLine}.\n` +
+    `> Do not edit by hand - run \`npm run sync-docs\` to refresh.\n\n`
+  );
+}
+
+async function syncDocs(pin) {
+  await mkdir(DAEMON_DIR, { recursive: true });
+  let fetched = 0;
+  let kept = 0;
+  for (const { remote, local } of DOCS) {
+    const dest = path.join(DAEMON_DIR, local);
+    try {
+      const body = await fetchText(`${RAW_BASE}/${remote}`);
+      await writeFile(dest, buildHeader(remote, pin) + body, "utf-8");
+      fetched++;
+      console.log(`[sync-docs] ✓ ${remote} -> daemon/${local}`);
+    } catch (err) {
+      // Keep whatever snapshot is already committed; never break the build.
+      console.warn(
+        `[sync-docs] ✗ ${remote} (${err.message}) - keeping committed snapshot`,
+      );
+      kept++;
+    }
+  }
+  return { fetched, kept };
+}
+
+// ── pin substitution in SKILL.md ────────────────────────────────────────────
+// Rewrites every `@pollen-robotics/reachy-mini-sdk@<version>` occurrence (the
+// CDN import and the API reference) to the resolved canonical pin.
+async function substitutePin(pin) {
+  if (!pin) {
+    console.warn("[sync-docs] no canonical pin resolved - skipping SKILL.md pin update");
+    return;
+  }
+  let hub;
+  try {
+    hub = await readFile(SKILL_HUB, "utf-8");
+  } catch (err) {
+    console.warn(`[sync-docs] cannot read SKILL.md (${err.message}) - skipping pin update`);
+    return;
+  }
+  const pinRe = /(@pollen-robotics\/reachy-mini-sdk@)[^/"'\s]+/g;
+  const before = hub;
+  hub = hub.replace(pinRe, `$1${pin}`);
+  if (hub === before) {
+    console.log("[sync-docs] SKILL.md already pinned to the canonical version");
+    return;
+  }
+  await writeFile(SKILL_HUB, hub, "utf-8");
+  console.log(`[sync-docs] SKILL.md SDK pin updated to ${pin}`);
+}
+
+async function main() {
+  console.log("[sync-docs] syncing canonical daemon docs + SDK pin…");
+  const pin = await resolveCanonicalPin();
+  const { fetched, kept } = await syncDocs(pin);
+  await substitutePin(pin);
+  console.log(`[sync-docs] done (fetched ${fetched}, kept ${kept}/${DOCS.length}).`);
+}
+
+main().catch((err) => {
+  // Last-resort guard: still exit 0 so a transient failure never breaks build.
+  console.warn(`[sync-docs] unexpected error: ${err?.stack || err}`);
+  process.exit(0);
+});

backend/src/agent/skill-loader.ts

@@ -35,7 +35,13 @@ export function loadSkill(id: string): Skill | null {
   const dir = path.join(SKILLS_DIR, id);
   if (!existsSync(dir)) return null;
 
-  const files = readdirSync(dir).filter((f) => f.endsWith(".md"));
+  // Recursive so canonical docs synced into a `daemon/` subfolder
+  // (scripts/sync-daemon-docs.mjs) are discovered too. Relative paths are
+  // kept as the doc `filename` (e.g. "daemon/javascript-sdk.md"), which is
+  // also how SKILL.md links to them and how `read_skill_doc` addresses them.
+  const files = readdirSync(dir, { recursive: true })
+    .map((f) => String(f).split(path.sep).join("/"))
+    .filter((f) => f.endsWith(".md"));
   if (files.length === 0) return null;
 
   const hubFile = files.find((f) => f.toLowerCase() === "skill.md");

backend/src/agent/skills/reachy-mini-app/SKILL.md

@@ -44,7 +44,7 @@ that does.
 ## What this mode can do well
 
 - HF OAuth login and robot session management via the JS SDK.
-- Head and antenna motion (`setHeadPose`, `setAntennas`).
+- Head, body and antenna motion (`setHeadRpyDeg`, `setBodyYawDeg`, `setAntennasDeg`).
 - Live WebRTC video stream (`attachVideo`).
 - Preset robot sound playback (`playSound`).
 - Raw data-channel commands (`sendRaw`) for low-level motor targets.
@@ -323,12 +323,19 @@ nice-to-have, not a blocker.
     </script>
 
     <!--
-      The ReachyMini SDK is a pure ES module served from jsDelivr. We expose
-      it on `window` so main.js (classic script) can use it without fighting
-      with static module resolution.
+      The ReachyMini SDK is the published npm package, loaded as a pure ES
+      module from jsDelivr's `/+esm` endpoint (no bundler, no build step). We
+      expose it on `window` so main.js (classic script) can use it without
+      fighting with static module resolution.
+
+      The version is pinned to a specific release for reproducibility. The
+      vibe-coder keeps this pin in sync with the latest SDK release on every
+      build (scripts/sync-daemon-docs.mjs resolves max(latest, rc) from the
+      npm dist-tags). This is the "bare HTML + CDN, no bundler" variant
+      documented in §11.5 of the daemon's APP_CREATION_GUIDE.
     -->
     <script type="module">
-      import { ReachyMini } from "https://cdn.jsdelivr.net/gh/pollen-robotics/reachy_mini@feat/ehance-js-lib/js/reachy-mini.js";
+      import { ReachyMini } from "https://cdn.jsdelivr.net/npm/@pollen-robotics/reachy-mini-sdk@1.8.0-rc1/+esm";
       window.ReachyMini = ReachyMini;
       window.dispatchEvent(new Event("reachymini:ready"));
     </script>
@@ -494,7 +501,7 @@ nice-to-have, not a blocker.
 // Flow driven by the central button + direction pad:
 //   signed-out → robot.login() (HF OAuth redirect)
 //   authenticated → robot.connect() + robot.startSession(robotId)
-//   ready → direction buttons fire robot.setHeadPose(roll, pitch, yaw)
+//   ready → direction buttons fire robot.setHeadRpyDeg(roll, pitch, yaw)
 //
 // When the page is embedded (host shell, mobile app, or vibe-coder
 // preview), the bootstrap script in `index.html` has already seeded
@@ -684,7 +691,7 @@ function bindHeadControls() {
     if (!btn || !robot) return;
     const pose = HEAD_POSES[btn.dataset.pose];
     if (!pose) return;
-    robot.setHeadPose(pose.roll, pose.pitch, pose.yaw);
+    robot.setHeadRpyDeg(pose.roll, pose.pitch, pose.yaw);
   });
 }
 
@@ -846,6 +853,37 @@ the robot can do* or *how it should behave*.
   endpoints. Usually you use the JS SDK; read this when you need
   lower-level access or a debug dashboard.
 
+### Canonical daemon docs (auto-fetched at build, `daemon/` subfolder)
+
+These are pulled verbatim from `pollen-robotics/reachy_mini@main` on every
+build (see `scripts/sync-daemon-docs.mjs`), so they are always the freshest
+upstream truth. Prefer them over the condensed chapters above when you need
+exact, current detail. Load via `read_skill_doc`:
+
+- [daemon/javascript-sdk.md](daemon/javascript-sdk.md): **authoritative** JS
+  SDK method/event reference (the exact, current names: `setHeadRpyDeg`,
+  `setAntennasDeg`, `setBodyYawDeg`, lifecycle, events). Check here whenever
+  unsure about an API name.
+- [daemon/APP_CREATION_GUIDE.md](daemon/APP_CREATION_GUIDE.md): the upstream
+  single source of truth. Look for its **bare HTML + CDN (no bundler)** section
+  - the pattern this vibe-coder uses - and its **robotics best-practices /
+  safe-teardown** section.
+- [daemon/AGENTS.md](daemon/AGENTS.md): upstream orientation hub.
+- [daemon/motion-philosophy.md](daemon/motion-philosophy.md),
+  [daemon/interaction-patterns.md](daemon/interaction-patterns.md),
+  [daemon/control-loops.md](daemon/control-loops.md),
+  [daemon/rest-api.md](daemon/rest-api.md),
+  [daemon/safe-torque.md](daemon/safe-torque.md): robot-behaviour knowledge.
+
+> **Important - what does NOT apply here.** The upstream guide describes a full
+> TypeScript + Vite + `mountHost()` toolchain with `npm install` and a build
+> step. **Ignore those parts.** This vibe-coder produces exactly **3 files, no
+> build, no npm** (see Hard constraints above). Only the runtime concepts apply:
+> the JS SDK method/event names, the robot knowledge, the bare-HTML + CDN
+> pattern, and the safe-teardown best practices. The auth/session lifecycle here
+> stays `login()`/`connect()`/`startSession()`/`authenticate()` - do **not**
+> switch to `mountHost()`/`connectToHost()`.
+
 ## Things you should NOT do
 
 - Do **not** create a `package.json`, `tsconfig.json`, `vite.config.*`,
@@ -864,7 +902,10 @@ the robot can do* or *how it should behave*.
   They all need a CORS proxy and server-side secrets, which is
   explicitly out of scope for this vibe coder.
 - Do **not** rebuild the ReachyMini JS SDK; it handles HF auth,
-  signaling and WebRTC negotiation. Import it from jsdelivr.
+  signaling and WebRTC negotiation. Import the published npm package
+  `@pollen-robotics/reachy-mini-sdk` from jsDelivr's `/+esm` endpoint
+  (no bundler). Do **not** pin to a git branch or the legacy single-file
+  `gh/.../reachy-mini.js` build.
 - Do **not** call `attachVideo(ui.video)` AFTER `startSession()`. The
   remote video track is published during the SDP exchange inside
   `startSession`. If the `<video>` element isn't already attached by
@@ -919,7 +960,11 @@ in `index.html` already covers `reachy:app:ready` and
 `reachy:host:hello`. Wire the rest yourself only if your app needs
 graceful teardown beyond "the iframe was destroyed".
 
-## API quick reference (`reachy_mini` JS SDK)
+## API quick reference (`@pollen-robotics/reachy-mini-sdk`)
+
+> For the exhaustive, always-current reference read
+> [daemon/javascript-sdk.md](daemon/javascript-sdk.md) (auto-fetched from
+> upstream). The summary below is the day-to-day subset.
 
 ```typescript
 new ReachyMini({ clientId, appName })
@@ -942,11 +987,12 @@ robot.stopSession()
 // Video - attach BEFORE startSession, save the returned detach function
 robot.attachVideo(el)  // returns () => void, call it to stop piping frames
 
-// Motion
-robot.setHeadPose(roll, pitch, yaw)  // degrees
-robot.setAntennas(right, left)       // radians
-robot.playSound(file)                // preset robot SFX
-robot.sendRaw(jsonPayload)           // escape hatch for custom commands
+// Motion (all angles in degrees)
+robot.setHeadRpyDeg(roll, pitch, yaw)  // head orientation
+robot.setBodyYawDeg(yaw)               // body rotation around vertical axis
+robot.setAntennasDeg(right, left)      // antenna positions
+robot.playSound(file)                  // preset robot SFX
+robot.sendRaw(jsonPayload)             // escape hatch for custom commands
 
 // Events
 robot.addEventListener("robotsChanged", (e) => e.detail.robots)

backend/src/agent/skills/reachy-mini-app/daemon/AGENTS.md

@@ -0,0 +1,305 @@
+> **Auto-fetched** from [`pollen-robotics/reachy_mini@main`](https://github.com/pollen-robotics/reachy_mini/blob/main/AGENTS.md) on 2026-05-29 · canonical SDK pin: `1.8.0-rc1`.
+> Do not edit by hand - run `npm run sync-docs` to refresh.
+
+# Reachy Mini Development Guide for AI Agents
+
+This guide helps AI agents assist users in developing Reachy Mini applications.
+
+---
+
+## Agent Behavior
+
+### FIRST: Check for agents.local.md
+
+**Before doing anything else**, search for `agents.local.md` in the current directory:
+
+```
+IF agents.local.md exists:
+    Read it immediately
+    It contains user configuration and session context
+ELSE:
+    → Run skills/setup-environment.md to set up the environment
+```
+
+This file stores the user's robot type, preferences, and setup status. Always check it first.
+
+### Be a Teacher
+
+Unless the user explicitly requests otherwise:
+- Explain concepts as you go
+- Encourage questions ("Let me know if you'd like more detail on any of this")
+- Guide non-technical users through each step
+- Don't assume prior knowledge
+
+### Two App Flavours — Default to JS, Python for developers
+
+Reachy Mini supports two app types. **Default to a JS (Live/Web) app** unless the user explicitly wants on-robot Python, or has a need that only Python can cover (heavy on-robot compute, rich hardware access, deterministic real-time control loops, or bundled offline LAN tooling).
+
+| Flavour | Default for | Where it runs |
+|---|---|---|
+| **JS app (recommended)** | End-users, shareable-by-URL experiences, anyone who wants "open a link, use the robot". Remote launch, zero-install, streaming A/V UIs. | Static HF Space; reaches the robot over WebRTC via the central signaling server. |
+| **Python app** | Developer tools, on-robot control loops, heavy motion sequencing, offline/LAN. | Robot owner's machine (laptop / CM4), optionally with a bundled web UI. |
+
+Both coexist — a Python app can bundle a browser UI, and a JS app can call the Python daemon's REST API.
+
+**When unsure, start JS.** If the user later discovers they need on-robot compute they can graduate to a Python app; the reverse migration is rarely needed.
+
+Confirm the choice with the user up front, then jump to the corresponding section:
+- JS path → [Live/Web/JS Apps](#livewebjs-apps)
+- Python path → instructions below
+
+---
+
+**Python path (for developers):**
+
+- **NEVER create app folders manually** — use `reachy-mini-app-assistant`.
+- **If a command fails**, ask the user to run it in their terminal — don't attempt complex workarounds.
+
+```bash
+# Default template (minimal app - good for most cases):
+reachy-mini-app-assistant create <app_name> <path> --publish
+
+# Conversation template (for LLM integration, speech, making robot talk):
+reachy-mini-app-assistant create --template conversation <app_name> <path> --publish
+```
+
+Python apps put web UIs in `static/`. See `skills/create-app.md` for details.
+
+### Always Create plan.md Before Coding
+
+Before implementing any app:
+1. Create `plan.md` in the app directory
+2. Write your understanding of what the user wants
+3. List your technical approach
+4. Ask clarifying questions and provide answer fields inside `plan.md`
+5. Wait for answers before coding
+
+### Keep Notes in agents.local.md
+
+Use `agents.local.md` to store:
+- User's robot type (Lite/Wireless)
+- Environment preferences
+- Useful context for future sessions
+- Keep it concise
+
+---
+
+## Robot Basics
+
+**Reachy Mini** is a small expressive robot:
+
+| Component | Description |
+|-----------|-------------|
+| **Head** | 6 DOF: x, y, z, roll, pitch, yaw (via Stewart platform) |
+| **Body** | Rotation around vertical axis |
+| **Antennas** | 2 motors, also usable as physical buttons |
+
+**Hardware variants:**
+- **Lite**: USB connection to laptop (full compute power)
+- **Wireless**: Onboard CM4, connects via WiFi (limited compute)
+
+---
+
+## SDK Essentials
+
+### Connection
+
+```python
+from reachy_mini import ReachyMini
+
+with ReachyMini() as mini:
+    # Your code here
+```
+
+### Two Motion Methods
+
+| Method | Use when |
+|--------|----------|
+| `goto_target()` | **Default** - smooth interpolation for gestures that last at least 0.5s each |
+| `set_target()` | Real-time control loops (e.g. tracking) at 10Hz+ |
+
+### Basic Example
+
+See and run `examples/minimal_demo.py` - demonstrates connection, head motion, and antenna control.
+
+### Before Writing Code
+
+- Read `docs/source/SDK/python-sdk.md` for API overview
+- Skim `src/reachy_mini/reachy_mini.py` for method signatures and docstrings
+- Check `examples/` for runnable code patterns
+
+---
+
+## Live/Web/JS Apps
+
+> ### START HERE: [`ts/APP_CREATION_GUIDE.md`](ts/APP_CREATION_GUIDE.md)
+>
+> That guide is the **single source of truth** for building a Reachy Mini JS app: scaffolding, `public/icon.svg`, host shell, `sdk: static` deploy, `mountHost()` / `connectToHost()` API, local dev, FAQ, and the host ↔ embed architecture reference. Everything that used to live in `SPEC.md` and `APP_AUTHOR_GUIDE.md` is folded in.
+>
+> **Today's SDK pin** (used by all three reference apps): `@pollen-robotics/reachy-mini-sdk@1.8.0-rc1-main.fd4354c`. See [§10 SDK version pinning](ts/APP_CREATION_GUIDE.md#10-sdk-version-pinning).
+
+Browser apps that drive a Reachy Mini over WebRTC, deployed as Hugging Face Spaces. Any HF-authenticated user opens the Space URL from anywhere and reaches any robot they have access to, through the central signaling server.
+
+**What this flavour unlocks:**
+
+- **Zero-install sharing** - the Space URL *is* the product. No LAN, no USB, no local daemon on the end-user side.
+- **Off-robot compute** - work lives in the browser or the Space backend; the robot stays a pure IO device.
+- **Bidirectional media** - robot camera/mic → browser; optionally user's mic → robot speaker.
+- **Free OAuth + robot picker + top bar + leave flow** via the host shell (`@pollen-robotics/reachy-mini-sdk/host`). You only write the app's UI; use any framework you want inside the iframe.
+
+### Clone a reference app and trim
+
+| Reference app | Stack | Use it for |
+|---|---|---|
+| [`pollen-robotics/reachy_mini_minimal_conversation`](https://huggingface.co/spaces/pollen-robotics/reachy_mini_minimal_conversation) | **Vanilla TS + Vite** | Smallest runtime, zero framework. |
+| [`pollen-robotics/reachy_mini_emotions`](https://huggingface.co/spaces/pollen-robotics/reachy_mini_emotions) | React 19 + MUI 7 + Vite | UI-rich apps (rich components, theming, deep links). |
+| [`pollen-robotics/reachy_mini_telepresence`](https://huggingface.co/spaces/pollen-robotics/reachy_mini_telepresence) | React 19 + MUI 7 + Vite | Camera / media-stream apps. |
+
+These are kept in lockstep with every SDK release. **Mimicking them is the fastest path to a working app.** The 3-file contract, deploy steps, gotchas, and SDK pin all live in [`ts/APP_CREATION_GUIDE.md`](ts/APP_CREATION_GUIDE.md) - read it before scaffolding anything non-trivial.
+
+> **One non-negotiable**: write `plan.md` first (same rule as Python apps) and wait for user approval before scaffolding.
+
+### Mobile-first by default
+
+Unless the user explicitly asks for a desktop-only / kiosk / dev-tool UI, **assume the app will be opened on a smartphone**. The Space URL is shareable, and "open this link on your phone and play with the robot" is the most common end-user flow. The reference apps are already responsive; cloning them gets you the mobile baseline for free - don't undo it by hardcoding desktop widths. Use the viewport meta with `width=device-width, initial-scale=1, viewport-fit=cover`, fluid `rem` / `vh` / `vw` units, touch hit targets ≥ 44×44 px, no hover-only affordances, and test in Chrome devtools' phone emulation before declaring the app done.
+
+### SDK runtime API (motion + media + daemon-side playback)
+
+Once `connectToHost()` resolves you get a live `ReachyMini` instance (`handle.reachy`). The full method/event reference lives in [`docs/source/SDK/javascript-sdk.md`](docs/source/SDK/javascript-sdk.md). The quick mental model:
+
+- **Motion (degrees)**: `setHeadRpyDeg(r, p, y)`, `setAntennasDeg(right, left)`, `setBodyYawDeg(yaw)`. Atomic raw-units: `setTarget({ head?: number[16], antennas?: [rRad, lRad], body_yaw?: rad })`. The head matrix is in world frame, so `body_yaw` alone pivots the body under the head — to make the head follow the body, ship a `head` matrix in the same call with the body delta added to the head yaw. Use your own last-commanded buffer as the baseline, not telemetry (lags by one RTT).
+- **Recorded-move playback (daemon-side, single-clock A/V sync)**: `playMove(motion, { audioBlob?, audioLeadMs? = -100 })` → `{finished|cancelled|error}`. `cancelMove()` stops mid-play. For record-time flows: `uploadAudio(blob)` returns `uploadId`, then `playUploadedAudio(uploadId)` resolves on the daemon's `started` broadcast (sync anchor). **Use these instead of hand-rolling `sendRaw` chunked uploads.**
+- **Audio**: `setAudioMuted(bool)`, `setMicMuted(bool)`, `getVolume()` / `setVolume(0-100)`, `getMicrophoneVolume()` / `setMicrophoneVolume(0-100)`. `playSound(file)`.
+- **Wake / torque**: `setMotorMode("enabled"|"disabled"|"gravity_compensation")`, `wakeUp()` / `gotoSleep()` / `isAwake()` / `ensureAwake()`.
+- **Media flow**: `<video>` passed to `reachy.attachVideo()` receives the **robot's** camera/mic over WebRTC. Do NOT call `navigator.mediaDevices.getUserMedia()` to read robot media - that grabs the user's *own* laptop camera. Bidirectional audio is automatic when `enableMicrophone: true` is passed to `mountHost()`.
+- **Events**: `connected`, `disconnected`, `robotsChanged`, `streaming`, `sessionStopped`, `sessionRejected` (robot busy - inspect `e.detail.activeApp`), `state` (every ~500 ms), `videoTrack`, `micSupported`, `error`.
+- **Math utilities**: `rpyToMatrix`, `matrixToRpy`, `degToRad`, `radToDeg`.
+- **Motion utilities** (subpath `@pollen-robotics/reachy-mini-sdk/animation`): `Pose` / `PartialPose` types, `INIT_POSE` safe-rest constant, `distanceBetweenPoses` (per-channel raw distance, head in magic-mm), `scaledDuration` → `{ duration, limiter, perChannel }` (synchronous client-side duration math, mirrors the daemon so you can sync audio cues without an RPC), `safelyReturnToPose(reachy)` (canonical `onLeave` one-liner: enables torque safely, computes scaled duration, dispatches goto to `INIT_POSE`, returns synchronously after dispatch), `installShutdownHandler(reachy)` (**standalone apps only** - host-shell apps use `handle.onLeave()` instead, mixing both double-fires the goto). Full recipe and anti-patterns: [§14 of the JS App Creation Guide](ts/APP_CREATION_GUIDE.md#14-robotics-best-practices).
+
+**The host owns all teardown** - never call `reachy.stopSession()` yourself, register an `onLeave` callback instead. For the canonical `onLeave` body, see [§14.3](ts/APP_CREATION_GUIDE.md#143-safe-return-to-home-pose-safelyreturntopose).
+
+### Legacy: minimal CDN-only path (`webrtc_example`)
+
+Before the host shell, JS apps were `sdk: static` HF Spaces with a single `index.html` importing the SDK directly from jsDelivr and reimplementing OAuth + picker + session lifecycle by hand. The canonical example is [`cduss/webrtc_example`](https://huggingface.co/spaces/cduss/webrtc_example).
+
+**Use this only** for one-off prototypes that don't need the host shell's surface (no top bar, no picker, no theme propagation, no mobile-catalog tile). For anything you'd share, **start from a reference app instead** - you get OAuth, picker, mobile-catalog discovery, mode-B handoff, and the entire `connectToHost()` API for free.
+
+---
+
+## REST API
+
+The daemon exposes an HTTP/WebSocket API at `http://{daemon-ip}:8000/api`.
+
+> REST and the JS SDK's WebRTC data channel are **sibling transports** into the same `process_command()` backend on the daemon — WebRTC is a JSON subset (motion, audio, state). Commands you send from JS (`setHeadRpyDeg`, `setAntennasDeg`, …) reach the same handler as the corresponding REST endpoints; picking one transport or the other is a deployment choice, not a functional one.
+
+- **Lite**: `localhost:8000` (daemon runs on your machine)
+- **Wireless**: `reachy-mini.local:8000` or the robot's IP address
+
+**Use REST API for:** Web UIs, non-Python clients, remote control, AI/LLM integration via HTTP. => Note: for the app to be discoverable, it must be a python app for now, this will change in a future release.
+
+**Interactive docs:** `http://{daemon-ip}:8000/docs` (when daemon is running)
+
+See `skills/rest-api.md` for details.
+
+---
+
+## Platform Compatibility
+
+| Setup | Compute | Camera | Notes |
+|-------|---------|--------|-------|
+| **Lite** | Full (laptop) | Direct USB | Most flexible, best for dev |
+| **Wireless (local)** | Limited (CM4) | Direct | Memory/CPU constrained |
+| **Wireless (streamed)** | Full (laptop) | Via network | Some tracking quality loss |
+| **Simulation** | Full | N/A | Can't test camera features |
+
+---
+
+## Safety Limits
+
+| Joint | Range |
+|-------|-------|
+| Head pitch/roll | [-40, +40] degrees |
+| Head yaw | [-180, +180] degrees |
+| Body yaw | [-160, +160] degrees |
+| Yaw delta (head - body) | Max 65° difference |
+
+Gentle collisions with body are safe. SDK clamps values automatically.
+
+For coordinate systems and architecture details, see `docs/source/SDK/core-concept.md`.
+
+---
+
+## Example Apps
+
+| App | Key Patterns | Source |
+|-----|--------------|--------|
+| **reachy_mini_conversation_app** | AI integration, control loops, LLM tools | [GitHub](https://github.com/pollen-robotics/reachy_mini_conversation_app) |
+| **marionette** | Recording motion, safe torque, HF dataset | [HF Space](https://huggingface.co/spaces/RemiFabre/marionette) |
+| **fire_nation_attacked** | Head-as-controller, leaderboards, games | [HF Space](https://huggingface.co/spaces/RemiFabre/fire_nation_attacked) |
+| **spaceship_game** | Head-as-joystick, antenna buttons | [HF Space](https://huggingface.co/spaces/apirrone/spaceship_game) |
+| **reachy_mini_radio** | Antenna interaction pattern | [HF Space](https://huggingface.co/spaces/pollen-robotics/reachy_mini_radio) |
+| **reachy_mini_simon** | No-GUI pattern (antenna to start) | [HF Space](https://huggingface.co/spaces/apirrone/reachy_mini_simon) |
+| **hand_tracker_v2** | Camera-based control loop | [HF Space](https://huggingface.co/spaces/pollen-robotics/hand_tracker_v2) |
+| **reachy_mini_dances_library** | Symbolic motion definition | [GitHub](https://github.com/pollen-robotics/reachy_mini_dances_library) |
+
+---
+
+## Documentation
+
+| Topic | File |
+|-------|------|
+| **Build a JS app (single source of truth)** | **[`ts/APP_CREATION_GUIDE.md`](ts/APP_CREATION_GUIDE.md)** |
+| JavaScript SDK runtime API (motion, events, daemon-side playback) | [`docs/source/SDK/javascript-sdk.md`](docs/source/SDK/javascript-sdk.md) |
+| Quickstart | `docs/source/SDK/quickstart.md` |
+| Python SDK | `docs/source/SDK/python-sdk.md` |
+| Core concepts | `docs/source/SDK/core-concept.md` |
+| Media architecture (WebRTC / GStreamer) | `docs/source/SDK/media-architecture.md` |
+| AI integration | `docs/source/SDK/integration.md` |
+| Troubleshooting | `docs/source/troubleshooting.md` |
+
+For platform-specific guides (Lite, Wireless, Simulation), see `docs/source/platforms/`.
+
+---
+
+## Skills Reference
+
+Read these files in `skills/` when you need detailed knowledge:
+
+| Skill | When to use |
+|-------|-------------|
+| **setup-environment.md** | First session, no `agents.local.md` exists |
+| **create-app.md** | Creating a new app with `reachy-mini-app-assistant` |
+| **control-loops.md** | Building real-time reactive apps (tracking, games) |
+| **motion-philosophy.md** | Choosing between `goto_target` and `set_target` |
+| **safe-torque.md** | Enabling/disabling motors without jerky motion |
+| **ai-integration.md** | Building LLM-powered apps |
+| **symbolic-motion.md** | Defining motion mathematically (dances, rhythms) |
+| **interaction-patterns.md** | Using antennas as buttons, head as controller |
+| **debugging.md** | App crashes, connectivity issues, basic checks |
+| **testing-apps.md** | Testing before delivery (sim vs physical) |
+| **rest-api.md** | HTTP/WebSocket API for non-Python clients |
+| **deep-dive-docs.md** | When to read full SDK documentation |
+
+---
+
+## Quick Reference
+
+**Motor names:** `body_rotation`, `stewart_1-6`, `right_antenna`, `left_antenna`
+
+**Interpolation methods:** `linear`, `minjerk` (default), `ease_in_out`, `cartoon`
+
+**Emotions library:**
+```python
+from reachy_mini.motion.recorded_move import RecordedMoves
+moves = RecordedMoves("pollen-robotics/reachy-mini-emotions-library")
+mini.play_move(moves.get("happy"), initial_goto_duration=1.0)
+```
+
+---
+
+## Community
+
+- **App guide**: https://huggingface.co/blog/pollen-robotics/make-and-publish-your-reachy-mini-apps
+- **Source code**: https://github.com/pollen-robotics/reachy_mini
+- **Community apps**: https://huggingface.co/spaces?q=reachy_mini
+- **Discord**: https://discord.gg/Y7FgMqHsub

backend/src/agent/skills/reachy-mini-app/daemon/APP_CREATION_GUIDE.md

@@ -0,0 +1,1501 @@
+> **Auto-fetched** from [`pollen-robotics/reachy_mini@main`](https://github.com/pollen-robotics/reachy_mini/blob/main/ts/APP_CREATION_GUIDE.md) on 2026-05-29 · canonical SDK pin: `1.8.0-rc1`.
+> Do not edit by hand - run `npm run sync-docs` to refresh.
+
+# App Creation Guide
+
+> ### Use `@pollen-robotics/reachy-mini-sdk@1.8.0-rc1` today
+>
+> Every reference app currently pins the same SDK release line:
+> **`1.8.0-rc1`** (precisely `1.8.0-rc1-main.fd4354c`). The host shell,
+> the embed adapter, the SDK runtime, and the daemon on the robot
+> are validated end-to-end against that build. Mixing versions
+> across these boundaries causes silent protocol drift - see
+> [§10 SDK version pinning](#10-sdk-version-pinning).
+>
+> Add this to your `package.json`:
+>
+> ```json
+> { "dependencies": { "@pollen-robotics/reachy-mini-sdk": "1.8.0-rc1-main.fd4354c" } }
+> ```
+
+**This is the single source of truth for building a Reachy Mini JS
+app.** [`../AGENTS.md`](../AGENTS.md) at the repo root points here;
+the JS SDK reference at [`../docs/source/SDK/javascript-sdk.md`](../docs/source/SDK/javascript-sdk.md)
+documents the runtime API (motion, events, daemon-side playback) once
+`connectToHost()` resolves. Everything else - scaffolding, deploy,
+host shell, gotchas - lives here.
+
+How to ship a Hugging Face Space that runs on a Reachy Mini robot,
+using `@pollen-robotics/reachy-mini-sdk/host` for OAuth, robot picking, session
+lifecycle, and a top bar - so your code stays focused on **your
+app's UI** and nothing else.
+
+| Doc        | Purpose                              | Audience                          |
+|------------|--------------------------------------|-----------------------------------|
+| **This**   | **Single source of truth for app authors** (scaffold, deploy, host contract, invariants) | **You, building a new app**       |
+| [`../docs/source/SDK/javascript-sdk.md`](../docs/source/SDK/javascript-sdk.md) | Runtime SDK API reference (methods, events, state machine, daemon-side playback) | App authors after `connectToHost()` resolves |
+| [`host/README.md`](./host/README.md) | One-page tour of the `@pollen-robotics/reachy-mini-sdk/host` package layout | First-time visitors to the host source |
+
+## Table of contents
+
+1. [What you get for free](#1-what-you-get-for-free)
+2. [Quickstart: clone a reference app](#2-quickstart-clone-a-reference-app)
+3. [The app-author contract](#3-the-app-author-contract)
+4. [`mountHost()` API](#4-mounthost-api)
+5. [`connectToHost()` API](#5-connecttohost-api)
+6. [Visual identity: icon, name, emoji](#6-visual-identity-icon-name-emoji)
+7. [Receiving an external config (deep-link, mobile)](#7-receiving-an-external-config)
+8. [Cleaning up on leave](#8-cleaning-up-on-leave)
+9. [Local dev: HF token vs OAuth redirect](#9-local-dev)
+10. [SDK version pinning](#10-sdk-version-pinning)
+11. [Deploying to Hugging Face Spaces](#11-deploying-to-hugging-face-spaces)
+12. [FAQ and common pitfalls](#12-faq-and-common-pitfalls)
+13. [Architecture reference (host ↔ embed contract)](#13-architecture-reference-host--embed-contract)
+    1. [Roles: app · host · embed](#131-roles-app--host--embed)
+    2. [App identity & official apps](#132-app-identity--official-apps)
+    3. [Two boot modes, one URL surface](#133-two-boot-modes-one-url-surface)
+    4. [Host phase state machine + handoff sequence](#134-host-phase-state-machine--handoff-sequence)
+    5. [Engineering invariants](#135-engineering-invariants)
+    6. [Protocol v1 messages](#136-protocol-v1-messages)
+    7. [Non-goals](#137-non-goals)
+    8. [Threat model](#138-threat-model)
+14. [Robotics best practices](#14-robotics-best-practices) - `@pollen-robotics/reachy-mini-sdk/animation`
+    1. [Pose types: `Pose` vs `PartialPose`](#141-pose-types-pose-vs-partialpose)
+    2. [Distance & scaled duration](#142-distance--scaled-duration)
+    3. [Safe return to home pose (`safelyReturnToPose`)](#143-safe-return-to-home-pose-safelyreturntopose)
+    4. [Standalone exit hooks (`installShutdownHandler`)](#144-standalone-exit-hooks-installshutdownhandler)
+    5. [Daemon parity warning](#145-daemon-parity-warning)
+    6. [Anti-patterns](#146-anti-patterns)
+
+---
+
+## 1. What you get for free
+
+By integrating `@pollen-robotics/reachy-mini-sdk/host`, your app **does not have to
+write**:
+
+- **Hugging Face OAuth**: sign-in screen, redirect handling,
+  token storage, sign-out menu - all in the host shell.
+- **Robot discovery and picker**: list of online robots, live
+  online/offline/busy updates, click-to-pick.
+- **Connection overlay**: the 3-step "Connecting / Starting
+  session / Waking up" view rendered on top of your iframe.
+- **End-session button and tear-down**: a "Back to apps" affordance
+  in the top bar that cleanly closes the WebRTC session.
+- **Dark / light theme switching**: respected from
+  `prefers-color-scheme` or HF settings, propagated to your iframe.
+
+What **you** write:
+
+- `index.html` (~30 lines of theme bootstrap + OAuth placeholders).
+- `src/dispatch.ts` (~20 lines, picks shell vs embed mode and self-
+  assigns `window.ReachyMini`).
+- `src/embed.{ts,tsx}` - **your app's actual code**. You receive a
+  live `ReachyMini` SDK handle and render whatever you want.
+- `public/icon.svg` - one SVG that powers the top bar, the mobile
+  catalog tile, and the favicon.
+
+You can use **any framework** inside your `embed` entry: React,
+Svelte, Vue, vanilla TS. The host runs outside your iframe and
+doesn't care.
+
+---
+
+## 2. Quickstart: clone a reference app
+
+Pick the reference closest to your needs and clone its repo from Hugging Face:
+
+| Reference app                       | Stack                       | Use it for                                  |
+|-------------------------------------|-----------------------------|---------------------------------------------|
+| [`pollen-robotics/reachy_mini_minimal_conversation`](https://huggingface.co/spaces/pollen-robotics/reachy_mini_minimal_conversation) | **Vanilla TS + Vite**       | Smallest runtime, no framework              |
+| [`pollen-robotics/reachy_mini_emotions`](https://huggingface.co/spaces/pollen-robotics/reachy_mini_emotions)                         | React 19 + MUI 7 + Vite     | UI-rich app with rich components / theming  |
+| [`pollen-robotics/reachy_mini_telepresence`](https://huggingface.co/spaces/pollen-robotics/reachy_mini_telepresence)                 | React 19 + MUI 7 + Vite     | App with camera / media streams             |
+
+```bash
+# Example: start from the vanilla TS template
+git clone https://huggingface.co/spaces/pollen-robotics/reachy_mini_minimal_conversation my_new_app
+cd my_new_app
+# Edit package.json `name`, README frontmatter (`title`, `emoji`,
+# `short_description`), public/icon.svg, and src/embed.ts to your app.
+npm install
+npm run dev
+# → http://localhost:5173
+```
+
+All three reference apps pin `@pollen-robotics/reachy-mini-sdk` to
+the same RC version in their `package.json` - see [§10 SDK version pinning](#10-sdk-version-pinning).
+
+---
+
+## 3. The app-author contract
+
+Exactly **three source files** are the entire integration surface,
+plus `public/icon.svg`, a `package.json` (for the Vite build + the
+SDK npm dep), and the Space `README.md` frontmatter
+(see [§11 Deploying](#11-deploying-to-hugging-face-spaces)).
+
+Don't add mandatory files outside this list - keep apps
+interchangeable.
+
+### 3.1 `index.html`
+
+The reference apps' `index.html` no longer loads the SDK from a CDN
+`<script>` tag - `src/dispatch.ts` imports the SDK from npm and self-
+assigns `window.ReachyMini` before any host code runs. This removes
+the jsDelivr branch / cache-purge friction we used to live with.
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
+    <title>My App</title>
+    <link rel="icon" href="/icon.svg" type="image/svg+xml" />
+
+    <!-- Theme bootstrap: paints the right palette BEFORE CSS lands so
+         there's no flash. Priority: `?theme=dark|light` query param
+         (set by the host when iframing us), then `prefers-color-scheme`. -->
+    <script>
+      (function () {
+        try {
+          var params = new URLSearchParams(window.location.search);
+          var raw = params.get("theme");
+          var mode;
+          if (raw === "dark" || raw === "light") {
+            mode = raw;
+          } else if (window.matchMedia && window.matchMedia("(prefers-color-scheme: dark)").matches === false) {
+            mode = "light";
+          } else {
+            mode = "dark";
+          }
+          document.documentElement.setAttribute("data-theme", mode);
+        } catch (_) {
+          document.documentElement.setAttribute("data-theme", "dark");
+        }
+      })();
+    </script>
+
+    <!-- HF Spaces helper variables.
+         - In production, HF substitutes these placeholders at file-
+           serve time when `hf_oauth: true` is set on the Space.
+         - In `npm run dev`, placeholders stay untouched; we detect
+           that and drop `window.huggingface` so the SDK falls back to
+           the clientId you supplied via `mountHost({ clientId })`. -->
+    <script>
+      (function () {
+        var clientId = "__OAUTH_CLIENT_ID__";
+        var scopes = "__OAUTH_SCOPES__";
+        var spaceHost = "__SPACE_HOST__";
+        var spaceId = "__SPACE_ID__";
+        var looksSubstituted = clientId && clientId.indexOf("__") !== 0;
+        if (looksSubstituted) {
+          window.huggingface = window.huggingface || {};
+          window.huggingface.variables = {
+            OAUTH_CLIENT_ID: clientId,
+            OAUTH_SCOPES: scopes && scopes.indexOf("__") !== 0 ? scopes : "openid profile",
+            SPACE_HOST: spaceHost && spaceHost.indexOf("__") !== 0 ? spaceHost : "",
+            SPACE_ID: spaceId && spaceId.indexOf("__") !== 0 ? spaceId : "",
+          };
+        }
+      })();
+    </script>
+  </head>
+  <body>
+    <div id="root"></div>
+    <!-- Single dispatcher. Picks the host shell (standalone visit) or
+         the embedded app (host's iframe) based on `?embedded=1`. -->
+    <script type="module" src="/src/dispatch.ts"></script>
+  </body>
+</html>
+```
+
+### 3.2 `src/dispatch.ts`
+
+The dispatcher does three things, in order:
+
+1. Imports `ReachyMini` from npm and self-assigns `window.ReachyMini` -
+   both the host shell and the embed wait for that global.
+2. Dispatches a `reachymini:ready` event so the embed's wait loop
+   takes its fast path.
+3. Branches on `?embedded=1` (legacy alias `?embed=1` also accepted):
+   embed bundle vs host shell bundle.
+
+```ts
+import { ReachyMini } from "@pollen-robotics/reachy-mini-sdk";
+
+(window as unknown as { ReachyMini: typeof ReachyMini }).ReachyMini = ReachyMini;
+window.dispatchEvent(new Event("reachymini:ready"));
+
+const params = new URLSearchParams(window.location.search);
+const isEmbed =
+  params.get("embedded") === "1" || params.get("embed") === "1";
+
+if (isEmbed) {
+  void import("./embed");
+} else {
+  void import("@pollen-robotics/reachy-mini-sdk/host/auto").then(({ mountHost }) => {
+    mountHost({
+      appName: "My App",
+      appIconUrl: "/icon.svg",
+      appEmoji: "🤖",
+      enableMicrophone: false,
+      // Optional: forward dev shortcuts from .env.local. See §9.
+      devToken:
+        import.meta.env.VITE_HF_TOKEN && import.meta.env.VITE_HF_USERNAME
+          ? {
+              token: import.meta.env.VITE_HF_TOKEN as string,
+              userName: import.meta.env.VITE_HF_USERNAME as string,
+            }
+          : undefined,
+      clientId: import.meta.env.VITE_HF_OAUTH_CLIENT_ID as string | undefined,
+    });
+  });
+}
+```
+
+### 3.3 `src/embed.ts` (vanilla example)
+
+```ts
+import { connectToHost } from '@pollen-robotics/reachy-mini-sdk/host/embed';
+
+interface MyConfig {
+  startingEmotion?: string;
+}
+
+async function main() {
+  const handle = await connectToHost<MyConfig>();
+  const { reachy, theme, config, onLeave } = handle;
+
+  document.body.innerHTML = '<h1>Connected!</h1>';
+
+  reachy.setHeadRpyDeg(0, 10, 0);
+
+  onLeave(async () => {
+    document.body.innerHTML = '<p>Bye!</p>';
+  });
+}
+
+void main().catch((err) => {
+  console.error('[my-app] boot failed', err);
+  window.parent.postMessage(
+    { source: 'reachy-mini', type: 'embed:error', version: 1,
+      message: String(err), fatal: true },
+    window.location.origin,
+  );
+});
+```
+
+### 3.4 `public/icon.svg`
+
+A single 24×24-friendly SVG at `public/icon.svg` powers **all three**
+identity surfaces (host top bar, mobile catalog tile, browser
+favicon). See [§6 Visual identity](#6-visual-identity-icon-name-emoji)
+for the resolution path and PNG fallback notes.
+
+### 3.5 `package.json`
+
+`npm`-managed; only mandatory bits are the Vite build script and the
+SDK pin. See [§10 SDK version pinning](#10-sdk-version-pinning) for
+the exact version string.
+
+---
+
+## 4. `mountHost()` API
+
+Called once from `dispatch.ts` when the URL is **not** in embed mode.
+Renders the shell into `#root`. The shell's visual theme (MUI
+light/dark) is bundled and not overridable - the host owns its
+look, apps own theirs inside the iframe.
+
+```ts
+import { mountHost } from '@pollen-robotics/reachy-mini-sdk/host/auto';
+
+mountHost({
+  appName: 'My App',          // REQUIRED: passed to the SDK + shown in top bar
+  appIconUrl: '/icon.svg',    // optional: top-bar logo (see §6)
+  appEmoji: '🤖',             // optional: fallback when no icon.svg
+  enableMicrophone: false,    // false unless you need WebRTC audio in
+  clientId: undefined,        // optional: HF OAuth client ID; defaults to window.huggingface.variables.OAUTH_CLIENT_ID
+  devToken: undefined,        // optional: { token, userName } - dev shortcut, see §9
+  target: undefined,          // optional: HTMLElement | string CSS selector; default '#root'
+});
+```
+
+**Required**: `appName`. Everything else has sensible defaults.
+
+**Return**: `{ dispose(): void }` - call to unmount cleanly. You
+usually never need this; the page lifecycle handles it.
+
+---
+
+## 5. `connectToHost()` API
+
+Called once from `embed.{ts,tsx}` to get a live SDK handle.
+
+```ts
+import { connectToHost } from '@pollen-robotics/reachy-mini-sdk/host/embed';
+
+interface MyConfig { /* whatever your app accepts */ }
+
+const handle = await connectToHost<MyConfig>();
+```
+
+Awaiting `connectToHost()` blocks until:
+
+1. The URL hash creds are parsed and wiped.
+2. The SDK script loaded (`window.ReachyMini` ready).
+3. The host posted `host:init` (Mode A only; Mode B times out
+   after 8 s and proceeds from hash alone).
+4. The SDK connected, started a session, and woke the robot.
+
+The resolved `handle` exposes:
+
+```ts
+interface ConnectedHandle<TConfig> {
+  // Live state at boot
+  reachy: ReachyMiniInstance;        // SDK instance, session live, robot awake
+  theme: 'dark' | 'light';
+  config: TConfig | null;
+  appName: string;
+  hostName: string;
+  userName: string | null;
+
+  // Subscribe to live updates from the host (returns an unsub fn)
+  onLeave(cb: () => void | Promise<void>): () => void;
+  onThemeChange(cb: (theme: 'dark' | 'light') => void): () => void;
+  onConfigChange(cb: (config: TConfig | null) => void): () => void;
+
+  // Push state / requests back to the host
+  setAppState(s: { phase, connectingStep?, message? }): void;
+  requestLeave(): void;                                      // ask host to end the session
+  reportError(msg: string, opts?: { fatal?, detail? }): void;
+}
+```
+
+The API is intentionally minimal. If you need a custom channel
+between host and embed, file a feature request - we'll add it as
+a typed message rather than expose a free-form sink.
+
+### Typing your config
+
+`connectToHost<T>()` types the `config` field; runtime validation
+is **your job**. An attacker controlling the URL can shape config
+freely - cast is not enough.
+
+```ts
+const handle = await connectToHost<MyConfig>();
+const config = isValidConfig(handle.config) ? handle.config : null;
+```
+
+---
+
+## 6. Visual identity: icon, name, emoji
+
+> **App identity is your HF Space ID** (`owner/space`). An app
+> published at `huggingface.co/spaces/your-name/cool-thing` has
+> identity `your-name/cool-thing` everywhere downstream (mobile
+> catalog, "last opened", official badge). Apps in the
+> `pollen-robotics/*` namespace are automatically tagged as
+> official in the catalog; no extra config.
+
+Your app's identity surfaces in **three independent places**, all
+fed from the same sources but each by its own resolution path:
+
+| Surface                       | What it shows                          | How it gets there                                                                                  |
+|-------------------------------|----------------------------------------|----------------------------------------------------------------------------------------------------|
+| Host top bar (in your iframe) | App logo + app name                    | You pass `appName` + `appIconUrl` + `appEmoji` to `mountHost()` in `dispatch.ts`                   |
+| Hugging Face mobile catalog   | App tile (icon + title + description)  | The mobile reads the catalog API; the API reads HF Spaces' frontmatter + probes `public/icon.svg` |
+| Browser tab / OS              | Favicon                                | Your `index.html` `<link rel="icon" href="/icon.svg">`                                             |
+
+The host shell itself **does not discover or list other apps**.
+It renders only the app it lives in. The catalog is owned by the
+mobile and the website API; see §11 FAQ for the API spec if you
+need to validate your app shows up.
+
+### Single source of truth: one `icon.svg`, one Space frontmatter
+
+You ship **one** SVG file and **one** README frontmatter; both
+the host and the mobile catalog read from them:
+
+1. **`public/icon.svg`** in your repo. Vite copies it verbatim to
+   `dist/icon.svg`, where nginx serves it at the root URL of your
+   Space. Reference it from `index.html`:
+
+   ```html
+   <link rel="icon" href="/icon.svg" type="image/svg+xml" />
+   ```
+
+   Pass it to `mountHost()` so the top bar renders it without a
+   probe:
+
+   ```ts
+   mountHost({ appName: 'My App', appIconUrl: '/icon.svg' });
+   ```
+
+   The catalog API also picks it up by listing the Space's
+   files (`siblings`) and matching `public/icon.svg` (or
+   `public/icon.png`), no live probe required.
+
+2. **HF Space frontmatter** in your `README.md`:
+
+   ```yaml
+   ---
+   title: My App
+   emoji: 🤖
+   colorFrom: yellow
+   colorTo: red
+   sdk: static
+   pinned: false
+   hf_oauth: true
+   short_description: One-line description shown in the catalog.
+   tags:
+     - reachy_mini
+     - reachy_mini_js_app
+   ---
+   ```
+
+   See [§11.1](#111-required-frontmatter) for the full annotated
+   frontmatter.
+
+   - `title` is the app name in the mobile catalog (the in-iframe
+     top bar uses `appName` from `mountHost()` instead).
+   - `emoji` is the fallback logo when no `icon.svg` is shipped.
+     Pass the same value to `mountHost({ appEmoji: '🤖' })` so the
+     top bar's fallback matches.
+   - `short_description` shows under the app tile in the catalog.
+   - The **`reachy_mini_js_app` tag is mandatory** to appear in
+     the mobile catalog. The catalog API filters on this exact
+     string. Don't remove it.
+   - `hf_oauth: true` makes HF auto-provision an OAuth client and
+     inject the ID at file-serve time.
+
+### Icon design recommendations
+
+Your icon renders at three different sizes; design for all three:
+
+- **Host top bar inside the iframe**: ~24x24 px square.
+- **Mobile catalog tile**: ~64x64 px square card.
+- **Browser tab favicon**: 16x16 px.
+
+Practical guidance:
+
+- Use a **square viewBox** (e.g. `viewBox="0 0 24 24"`) so the
+  three target sizes all crop identically.
+- Keep the icon **readable at 16 px**: thick strokes, simple
+  silhouette, max 2-3 distinct shapes.
+- Inline all colours; **don't reference external CSS**, the icon
+  is served standalone.
+- Respect dark and light backgrounds: an icon that vanishes on
+  light should provide a `<style>` tag with `@media (prefers-color-scheme)`
+  rules or, simpler, use a neutral mid-tone palette.
+- **Optimise the SVG**: target ~30 KB or less. Tools: `svgo`,
+  Figma's "Export SVG → optimise".
+
+### PNG fallback
+
+If you can't ship SVG (heavy raster art, exported portrait, ...),
+the catalog API also accepts `public/icon.png`. SVG wins when both
+exist. The host top bar only renders the SVG variant - if your
+`mountHost({ appIconUrl })` points at a PNG, it works, but you
+lose the crisp upscale on hi-DPI screens.
+
+---
+
+## 7. Receiving an external config
+
+The host accepts a base64-encoded JSON `config` from two sources:
+
+1. **URL parameter**: `https://<space>.hf.space/?config=eyJlbW90aW9uIjoiam95In0=`
+   (decoded once, passed verbatim).
+2. **Mobile handoff**: the mobile app embeds your Space with
+   `?embedded=1#creds=<base64-bundle-including-config>`.
+
+Your app receives `config` typed as `unknown`; cast and validate.
+
+```ts
+interface MyConfig { startingEmotion?: string; }
+
+function isMyConfig(v: unknown): v is MyConfig {
+  return v != null && typeof v === 'object' && (
+    (v as MyConfig).startingEmotion === undefined ||
+    typeof (v as MyConfig).startingEmotion === 'string'
+  );
+}
+
+const handle = await connectToHost<MyConfig>();
+const initial: MyConfig = isMyConfig(handle.config) ? handle.config : {};
+
+handle.onConfigChange((next) => {
+  if (isMyConfig(next)) /* react to it */;
+});
+```
+
+If your app's UI state changes in a way the mobile would want to
+remember (e.g. user picked a different emotion), persist it in
+your app's storage. The host does **not** propagate state
+upstream - apps don't push config to the host in v1.
+
+---
+
+## 8. Cleaning up on leave
+
+The host fires a tear-down sequence in three scenarios:
+
+- User clicks "End session" / "Back to apps" in the top bar.
+- Your app calls `handle.requestLeave()`.
+- The page is unloaded (`pagehide`, e.g. user closes the tab).
+
+In all three cases your `onLeave` callbacks fire. You have **~1.5-2 s**
+before the host force-unmounts the iframe; use that to:
+
+```ts
+import { safelyReturnToPose } from "@pollen-robotics/reachy-mini-sdk/animation";
+
+handle.onLeave(async () => {
+  safelyReturnToPose(handle.reachy); // canonical safe-rest one-liner, see §14.3
+  player.cancel();                   // stop streaming motion frames
+  audioCtx?.close();                 // release audio
+  ws?.close();                       // close any side channels
+  await flushTelemetry();            // your async hooks
+});
+```
+
+`safelyReturnToPose` is the recommended first call in every `onLeave` -
+it re-enables torque, computes a scaled duration, and dispatches a
+goto to `INIT_POSE`. Full recipe in
+[§14.3](#143-safe-return-to-home-pose-safelyreturntopose).
+
+You do **not** need to call `reachy.stopSession()` yourself - the
+host does. You also don't need to navigate away; the iframe is
+unmounted by the host.
+
+---
+
+## 9. Local dev
+
+You have two options, picked by the `devToken` and `clientId`
+props passed to `mountHost()`. Reference apps support both via
+`.env.local`.
+
+### Option A: personal access token (no OAuth)
+
+Fastest for local dev. Skips the OAuth redirect entirely.
+
+1. Get a token at <https://huggingface.co/settings/tokens> (read
+   scope is enough).
+2. Create `.env.local`:
+
+   ```
+   VITE_HF_TOKEN=hf_xxx
+   VITE_HF_USERNAME=your-handle
+   ```
+
+3. In `dispatch.ts`, forward both to `mountHost`:
+
+   ```ts
+   mountHost({
+     appName: 'My App',
+     devToken: import.meta.env.VITE_HF_TOKEN && import.meta.env.VITE_HF_USERNAME
+       ? { token: import.meta.env.VITE_HF_TOKEN, userName: import.meta.env.VITE_HF_USERNAME }
+       : undefined,
+   });
+   ```
+
+4. `npm run dev` → you're signed in on page load.
+
+`.env.local` must be gitignored. **Never commit the token.**
+
+### Option B: real OAuth client ID
+
+Use this when you're touching the OAuth / logout paths.
+
+1. Go to <https://huggingface.co/settings/applications/new>.
+2. Homepage URL: `http://localhost:5173` · Redirect URIs:
+   `http://localhost:5173` · Scopes: at least `openid`, `profile`.
+3. Copy the client ID into `.env.local`:
+
+   ```
+   VITE_HF_OAUTH_CLIENT_ID=...
+   ```
+
+4. Forward to `mountHost`:
+
+   ```ts
+   mountHost({
+     appName: 'My App',
+     clientId: import.meta.env.VITE_HF_OAUTH_CLIENT_ID,
+   });
+   ```
+
+---
+
+## 10. SDK version pinning
+
+Every reference app pins the same exact SDK version in `package.json`.
+Pin yours the same way - mixing versions across `@pollen-robotics/reachy-mini-sdk`,
+`@pollen-robotics/reachy-mini-sdk/host`, and the daemon on the robot
+produces hard-to-debug protocol drift.
+
+The current pinned version across all three reference apps:
+
+```json
+{
+  "dependencies": {
+    "@pollen-robotics/reachy-mini-sdk": "1.8.0-rc1-main.fd4354c"
+  }
+}
+```
+
+This is the `1.8.0-rc1` release line, with the `-main.fd4354c` suffix
+identifying the commit-tagged prerelease build that's been validated
+end-to-end against the host shell + daemon. **Use the same string in
+your `package.json`** unless you're explicitly tracking a newer RC.
+
+> When a newer RC is published, the source of truth is whichever
+> string is currently shared by [`reachy_mini_minimal_conversation`'s
+> `package.json`](https://huggingface.co/spaces/pollen-robotics/reachy_mini_minimal_conversation/blob/main/package.json),
+> [`reachy_mini_emotions`'s `package.json`](https://huggingface.co/spaces/pollen-robotics/reachy_mini_emotions/blob/main/package.json),
+> and [`reachy_mini_telepresence`'s `package.json`](https://huggingface.co/spaces/pollen-robotics/reachy_mini_telepresence/blob/main/package.json).
+> If those three diverge, fall back to whatever this guide says.
+
+### Why pin a specific build (not `^1.8.0` or a major like `@1`)?
+
+The host shell, the embed adapter (`connectToHost`), the SDK, and the
+robot daemon negotiate over a versioned WebRTC data-channel protocol.
+A patch bump on one side that crosses a protocol boundary will
+silently fall back (or noisily fail) at runtime - well past the type
+checker.
+
+Pin to the exact build string the reference apps use, upgrade
+intentionally, and re-test against a live robot before shipping.
+
+---
+
+## 11. Deploying to Hugging Face Spaces
+
+> Reachy Mini JS apps ship as **`sdk: static`** Hugging Face Spaces.
+> HF serves the Vite build straight from its CDN and replaces
+> `__OAUTH_CLIENT_ID__` and friends at file-serve time, because
+> `hf_oauth: true` is set in the README frontmatter.
+
+### 11.1 Required frontmatter
+
+```yaml
+---
+title: My Reachy Mini App
+emoji: 🤖
+colorFrom: yellow
+colorTo: red
+sdk: static
+pinned: false
+hf_oauth: true
+short_description: One-line description shown in the mobile catalog.
+tags:
+  - reachy_mini
+  - reachy_mini_js_app   # mandatory: mobile-catalog discovery filters on this exact string
+---
+```
+
+- `sdk: static` is what makes HF serve your `dist/` from its CDN.
+- `hf_oauth: true` is what triggers `__OAUTH_CLIENT_ID__` substitution.
+- The **`reachy_mini_js_app` tag is mandatory** for mobile-catalog
+  discovery. The catalog API filters on this exact string.
+- Apps in the `pollen-robotics/*` namespace are automatically tagged
+  as "official" in the catalog (see [§13.2 App identity & official apps](#132-app-identity--official-apps)); no extra config.
+
+### 11.2 Build and push
+
+```bash
+# 1. Build locally
+npm install
+npm run build
+# → dist/  (contains index.html with the __OAUTH_CLIENT_ID__ placeholder
+#    intact, your bundled JS, and dist/icon.svg copied from public/)
+
+# 2. Create the Space and clone it next to your source tree
+hf repos create <app-name> --repo-type space --space-sdk static
+git clone https://huggingface.co/spaces/<username>/<app-name> ../<app-name>-space
+
+# 3. Stage the Space contents:
+#    - README.md (the frontmatter)
+#    - dist/...  (served at the Space root by HF's CDN)
+#    - public/icon.svg duplicated at the repo path the mobile catalog
+#      API matches (HF's `siblings` listing only sees committed files,
+#      not the Vite-emitted dist/icon.svg).
+cp README.md ../<app-name>-space/
+cp -R dist/. ../<app-name>-space/
+mkdir -p ../<app-name>-space/public
+cp public/icon.svg ../<app-name>-space/public/
+# (also cp public/icon.png if you ship a raster fallback)
+
+# 4. Push
+cd ../<app-name>-space
+git add -A && git commit -m "Initial deploy" && git push
+```
+
+### 11.3 What HF does at serve time
+
+- Substitutes `__OAUTH_CLIENT_ID__`, `__OAUTH_SCOPES__`,
+  `__SPACE_HOST__`, and `__SPACE_ID__` inside any `.html` file at the
+  Space root (because `hf_oauth: true`).
+- Serves the rest of `dist/` as static assets via its CDN (immutable
+  caching honours the hashed filenames Vite emits).
+- Indexes `siblings` for the mobile catalog probe (which is why you
+  need `public/icon.svg` committed at the repo path, not just inside
+  `dist/`).
+
+### 11.4 Cache busting
+
+If a push doesn't take effect, push an empty commit to force HF to
+re-resolve the Space:
+
+```bash
+git commit --allow-empty -m "chore: bust HF Spaces cache" && git push
+```
+
+---
+
+## 12. FAQ and common pitfalls
+
+### "I see a `Robot is busy` error even though no one is using the robot"
+
+The host's SDK and the embed's SDK both claim a peer at the
+central. The host **must** disconnect when the embed boots; if it
+doesn't, the central sees two peers with the same `appName` and
+rejects the embed.
+
+This is handled automatically by `@pollen-robotics/reachy-mini-sdk/host`
+(see [§13.5.1 Single live SDK per tab](#1351-single-live-sdk-per-tab)).
+If you see this in dev, you likely have **two tabs** open on the
+same Space - that's expected behaviour.
+
+### "My app loads React + MUI even though I wrote vanilla TS"
+
+The **host shell** is React + MUI. It runs **only outside your
+iframe** (sign-in screen, picker, top bar). Once your app is live,
+the host's React tree is idle.
+
+Your iframe content is whatever you wrote. Vanilla TS apps stay
+slim inside the iframe.
+
+### "Vite warns about React being installed in two places"
+
+You're using the legacy `file:./vendor/reachy-mini-host` dep
+pattern (now unsupported — the host ships from npm as part of
+`@pollen-robotics/reachy-mini-sdk`). Migrate to the npm dep and,
+if you still see the warning, add to your `vite.config.ts`:
+
+```ts
+export default defineConfig({
+  resolve: {
+    dedupe: ['react', 'react-dom', 'react/jsx-runtime',
+             '@emotion/react', '@emotion/styled',
+             '@mui/material', '@mui/icons-material'],
+  },
+  optimizeDeps: {
+    include: ['@pollen-robotics/reachy-mini-sdk',
+              '@pollen-robotics/reachy-mini-sdk/host',
+              '@pollen-robotics/reachy-mini-sdk/host/auto',
+              '@pollen-robotics/reachy-mini-sdk/host/embed'],
+  },
+});
+```
+
+### "I want a different sign-in flow"
+
+Not supported in v1. The host owns OAuth. If you need a custom
+flow, the standalone shell isn't for you - publish your Space
+with the host disabled (just don't call `mountHost()`) and roll
+your own.
+
+### "I want a different theme than the bundled MUI one"
+
+The host shell's look is fixed (light + dark MUI bundle). Apps
+own their own theme **inside the iframe** - use the
+`handle.theme` value as your mode signal and wrap your app in
+whatever ThemeProvider you want.
+
+```ts
+const handle = await connectToHost();
+// Mirror `handle.theme` ('dark' | 'light') in your own
+// ThemeProvider. The host pushes updates via onThemeChange().
+```
+
+### "The icon doesn't show up in the top bar"
+
+Check the three sources in priority order (§6):
+
+1. Is `/icon.svg` reachable at the deployed URL? Open
+   `https://<space>.hf.space/icon.svg` directly.
+2. Is the file's MIME type `image/svg+xml`? The host's probe
+   checks the response's `content-type`.
+3. Did you pass `appIconUrl: '/icon.svg'` to `mountHost()`?
+
+If 1 + 2 + 3 are correct and it still fails, file a bug.
+
+### "My Space serves the bundle but the OAuth login redirects loop"
+
+HF only substitutes `__OAUTH_CLIENT_ID__` when `hf_oauth: true` is
+set in the README frontmatter **and** the file is HTML. Common
+mistakes:
+
+- `hf_oauth: true` missing → placeholder stays as literal
+  `"__OAUTH_CLIENT_ID__"`; the SDK falls back to no client ID and
+  the login never resolves.
+- You pushed a built `dist/index.html` that already had the
+  placeholder replaced locally (e.g. you ran with `.env.local` and
+  some bundler hardcoded the value). HF only substitutes
+  `__...__` literals; if the file already has a real ID baked in
+  for a different OAuth client, the redirect targets the wrong app.
+- The Space pre-dates the `hf_oauth` substitution (very old
+  Spaces). Re-create the Space.
+
+### "My app doesn't appear in the mobile catalog"
+
+Three things must be true simultaneously:
+
+1. The Space tags include the exact string `reachy_mini_js_app` (see
+   the [§11.1 frontmatter](#111-required-frontmatter)).
+2. `public/icon.svg` exists in the **committed repo tree** (not just
+   in `dist/`). The catalog probe inspects `siblings`, which is a
+   listing of committed files, not served URLs.
+3. The Space is public (or the requesting user has access).
+
+### "Where do I see if my app crashed at boot?"
+
+Three places, in order:
+
+1. Browser console of the standalone Space tab (mountHost errors).
+2. Browser console of the iframe (embed errors). The embed
+   `postMessage`s any boot error back to the host as
+   `embed:error` - the host surfaces fatal ones via a banner.
+3. HF Space "Logs" tab - only build-time errors show up here for
+   static Spaces (no runtime container).
+
+### "How do I test the mobile-handoff mode locally?"
+
+Hit your dev server at:
+
+```
+http://localhost:5173/?embedded=1#creds=<base64({"hfToken":"hf_xxx","userName":"you","robotPeerId":"abc","signalingUrl":"https://...","theme":"dark","config":null,"hostName":"Reachy Mini","appName":"My App"})>
+```
+
+The dispatcher will skip the shell and go straight to your embed.
+Useful for testing the embed path without spinning up the mobile
+app. The exact bundle shape is documented at
+[§13.3 Two boot modes](#133-two-boot-modes-one-url-surface).
+
+---
+
+## 13. Architecture reference (host ↔ embed contract)
+
+> **You don't need this section to ship an app.** §1-§12 plus §14
+> (Robotics best practices) are enough. This appendix is the canonical
+> contract between the **app**, the **host shell**, and the **embed
+> adapter** - useful when you're debugging a weird boot, considering an
+> unusual deployment, or contributing to the host shell itself.
+
+### 13.1 Roles: app · host · embed
+
+Three actors, one app repository:
+
+| Actor      | Lives in                                              | Owns                                                                       |
+|------------|-------------------------------------------------------|----------------------------------------------------------------------------|
+| **App**    | `index.html` + `src/dispatch.ts` + `src/embed.{ts,tsx}` | UI, app-specific UX, **full freedom over framework / tooling choices**     |
+| **Host**   | `@pollen-robotics/reachy-mini-sdk/host/auto`          | OAuth, robot discovery, robot picker, connecting overlay, end-session flow |
+| **Embed**  | `@pollen-robotics/reachy-mini-sdk/host/embed`         | SDK lifecycle inside the iframe (`startSession`, `ensureAwake`, teardown)  |
+
+The **App** consumes the Reachy Mini SDK (imported in
+`src/dispatch.ts` and self-assigned to `window.ReachyMini`) plus the
+`@pollen-robotics/reachy-mini-sdk/host` subpath exports. It contains
+**zero auth code, zero picker code, zero session-lifecycle code**.
+
+#### Why React + MUI for the host shell (and only the host)
+
+The host shell needs a real component library: sign-in forms, robot
+picker lists, connecting overlays, top bar, dark-mode toggles. It's
+built with **React 19 + MUI 7 + Emotion**.
+
+- The shell renders **only outside your iframe** and only between
+  sessions; once your app is live, the shell's React tree is idle.
+- Apps written in another framework still load the shell's bundle
+  for sign-in / picker UI. That's the cost of the iframe model and
+  we accept it.
+
+The trade-off favours **fast host iteration + tech freedom for
+apps** over a slimmer host shell.
+
+### 13.2 App identity & official apps
+
+A Reachy Mini app is uniquely identified by its **Hugging Face Space
+ID**, of the form `owner/space` (e.g. `pollen-robotics/emotions`).
+Everything downstream of identity flows from this single string:
+
+- The catalog API filters and dedupes apps by `space.id`.
+- The mobile app stores and recalls "last opened" apps by
+  `owner/space`.
+- The host shell does **not** need this ID at runtime (it lives
+  inside the app it renders); it's used solely by the discovery
+  surface.
+
+**An app is "official" if and only if its Space ID starts with
+`pollen-robotics/`.** No allowlist, no separate registry, no
+`official: true` field. Adding `pollen-robotics/` to your URL is the
+entire qualification. Where the distinction surfaces:
+
+| Surface                | Behaviour                                                       |
+|------------------------|-----------------------------------------------------------------|
+| Mobile catalog         | "Official" badge / sort priority on `pollen-robotics/*` Spaces  |
+| Website `/api/js-apps` | Returns `isOfficial: true` for `pollen-robotics/*`              |
+| Host shell             | **No notion of "official"**. Renders the app the same way always |
+
+### 13.3 Two boot modes, one URL surface
+
+The same `index.html` is served for both modes. The dispatcher
+(`src/dispatch.ts`) picks between them based on the URL.
+
+| Mode                  | URL shape                                                            | What happens                                         |
+|-----------------------|----------------------------------------------------------------------|------------------------------------------------------|
+| **A. Hub standalone** | `https://<space>.hf.space/`                                          | Full host shell (OAuth → picker → iframe with app)   |
+| **B. Mobile handoff** | `https://<space>.hf.space/?embedded=1#creds=<base64(CredsBundle)>`   | Skip shell; app boots directly, creds come via hash  |
+
+#### Dispatch rule
+
+```
+if (URL.searchParams.has("embedded") && URL.hash.startsWith("#creds=")):
+    boot embed  → import("./embed")
+else:
+    boot host   → import("@pollen-robotics/reachy-mini-sdk/host/auto").mountHost({...})
+```
+
+`?embedded=1` without creds is an invalid mode - the embed shows an
+`ErrorView`.
+
+#### `CredsBundle` (lives only in the URL hash, never in search)
+
+The bundle has the shape:
+
+```ts
+{
+  hfToken: string;       // short-lived HF bearer (15 min TTL)
+  userName: string;
+  robotPeerId: string;
+  signalingUrl: string;
+  theme: 'dark' | 'light';
+  config: unknown | null;
+  hostName: string;
+  appName: string;
+}
+```
+
+The hash is **never sent to a server**. The embed wipes it with
+`history.replaceState` on the very first synchronous tick of
+`connectToHost()`, **before any `await`** - see
+[§13.5.2 Hash-only creds + immediate wipe](#1352-hash-only-creds--immediate-wipe).
+
+#### Mode A standalone flow (the long story)
+
+Phase machine inside the host:
+
+```
+booting → (signed-out | authenticated) → connecting → connected →
+picking → handing-off → live → stopping → picking
+```
+
+- `booting`: wait for `window.ReachyMini`, instantiate the SDK,
+  call `authenticate()`.
+- `signed-out`: render the OAuth sign-in screen.
+- `authenticated` → `connecting` → `connected` (SSE welcome) →
+  `picking`.
+- During `picking`, the robot list reacts live to the SDK's
+  `robotsChanged` event.
+- On robot selection, the host mounts the iframe at
+  `<same-origin>?embedded=1#creds=<base64>` and overlays
+  `ConnectingView` (3-step stepper: `link` → `session` → `wake`).
+- When the embed reaches `phase: 'live'`, the overlay fades out.
+
+Top bar layout while `live`:
+
+```
+[icon] [app name] ........ [robot status] [end-session] [oauth menu]
+```
+
+The top bar stays rendered through every phase of Mode A and does
+**not** render at all in Mode B.
+
+End-session flow:
+
+1. Triggered by the End-session button, `embed:request-leave`, or
+   `pagehide`.
+2. Host → phase `stopping`, `LeavingView` overlay, posts
+   `host:leaving`.
+3. Embed runs `onLeave` callbacks → `reachy.stopSession()` → acks.
+4. Host receives ack (or hits `timeoutMs`) → unmounts iframe →
+   phase `picking`.
+
+#### Mode B mobile handoff flow
+
+The mobile app opens the Space in a WebView with a pre-built URL
+containing creds in the hash. The dispatcher loads `./embed`
+directly. **No host shell is mounted.** The user sees:
+
+- No sign-in view (mobile already authenticated).
+- No robot picker (mobile already picked).
+- No welcome-back animation.
+- No host top bar - if your app wants one, it draws it itself.
+
+There is **no end-session button** in Mode B. Closing the WebView
+triggers `pagehide`, which fires `onLeave` and stops the session.
+
+### 13.4 Host phase state machine + handoff sequence
+
+#### Host phase machine (Mode A only)
+
+```mermaid
+stateDiagram-v2
+    [*] --> booting
+    booting --> sdk_missing: SDK load timeout
+    booting --> signed_out: authenticate() false
+    booting --> authenticated: authenticate() true
+    booting --> error: ctor / clientId error
+
+    signed_out --> booting: user clicks Sign in
+    authenticated --> connecting: auto
+    connecting --> connected: SSE welcome
+    connecting --> error: HTTP / network fail
+    connected --> picking
+    picking --> handing_off: selectRobot()
+    handing_off --> live: embed reports phase=live
+    handing_off --> error: embed:error { fatal: true }
+
+    live --> stopping: endSession() OR embed:request-leave
+    stopping --> picking: leave-ack OR timeout
+
+    error --> picking: retry() if SDK authed
+    error --> booting: retry() if no SDK
+    error --> signed_out: retry() if auth expired
+```
+
+#### Handoff sequence (host → embed)
+
+Showcases the single-SDK-per-tab invariant
+([§13.5.1](#1351-single-live-sdk-per-tab)).
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant H as Host
+    participant HS as Host SDK
+    participant C as Central
+    participant E as Embed (iframe)
+    participant ES as Embed SDK
+
+    U->>H: click robot card
+    H->>H: phase = handing-off, mount iframe
+    E->>E: parse #creds, replaceState wipe
+    E->>H: embed:ready
+    H->>HS: disconnect() [§13.5.1]
+    H->>E: host:init
+    E->>ES: connect() → startSession() → ensureAwake()
+    ES->>C: claim robot
+    C-->>ES: session live
+    E->>H: embed:app-state { phase: 'live' }
+    H->>H: hide ConnectingView overlay
+```
+
+### 13.5 Engineering invariants
+
+Four hard invariants. A failure here is a regression in the host
+shell - it must produce a defined observable behaviour and must
+stay covered by tests.
+
+#### 13.5.1 Single live SDK per tab
+
+**Contract**: at any instant, exactly one SDK instance per tab is
+registered at the central.
+
+**Mechanism**:
+- Host mounts the SDK in `booting` and uses it for the picker.
+- As soon as the embed posts `embed:ready`, the host calls
+  `disconnect()` on its SDK and zeroes its references.
+- On `leave-ack` (or timeout), the host calls `connect()` again to
+  refresh the fleet and lands back on `picking`.
+
+**Why**: removes the entire class of "Robot is busy" false
+positives where the central thinks the shell still owns the robot.
+
+**Defence in depth**: the host's SDK registers as `<appName> (shell)`
+at the central; the embed keeps the clean `appName`. This protects
+the narrow window where both SDKs overlap (between `embed:ready`
+and `disconnect()`).
+
+#### 13.5.2 Hash-only creds + immediate wipe
+
+**Contract**: HF tokens never appear in URL search, never in
+referer, never in HF Spaces access logs.
+
+**Mechanism**:
+- Creds are serialised as base64 JSON in the URL hash fragment
+  (`#creds=...`).
+- The embed wipes the hash with `history.replaceState` on the
+  first synchronous tick of `connectToHost()`, before any `await`.
+- On `host:leaving`, the embed clears `sessionStorage.hf_*` keys
+  before sending the `leave-ack`.
+
+**Token TTL**: `hf_token_expires` is set to **15 min** at seed
+time. The SDK refreshes on demand.
+
+#### 13.5.3 Bundle and SDK pinning
+
+**Contract**: a fix in the host reaches every Space within one
+cache cycle, with no per-app rebuild. A fix in the SDK can be
+rolled out by the SDK team, not by every app team.
+
+**Pinning rules**:
+- App bundles (`index-<hash>.js`): hashed by Vite, cache-busted
+  on deploy.
+- `@pollen-robotics/reachy-mini-sdk` in `package.json`: pinned to
+  an **exact prerelease build** (today: `1.8.0-rc1-main.fd4354c`),
+  not a range. See [§10 SDK version pinning](#10-sdk-version-pinning).
+- `@pollen-robotics/reachy-mini-sdk/host` subpath imports: same
+  pin, same package.
+
+On detected mismatch (e.g. unknown protocol version, structurally
+invalid `host:init`), the host's `ErrorView` primary button calls
+`window.location.reload(true)` to bypass any intermediary cache.
+
+#### 13.5.4 React Strict Mode safety
+
+**Contract**: every effect in the host package survives a double
+mount in `<React.StrictMode>` without doubling network I/O, SDK
+instances, or postMessage traffic.
+
+**Why this matters**: React 18+ in dev intentionally mounts every
+component, runs every effect, runs every cleanup, then mounts and
+runs effects again. Code that "looked fine" in prod will fire two
+parallel `connect()` calls, leak two SSE subscribers, post
+`embed:ready` twice. In Mode A this surfaces as ghost sessions at
+the central; in Mode B as two competing WebRTC peer connections.
+
+**Mechanisms**:
+- **Boot guard refs**: `useReachyHost()` uses a `bootStartedRef`
+  set on first mount; the second StrictMode invocation early-
+  returns instead of re-instantiating the SDK.
+- **Subscription cleanup**: every `useEffect` returns its tear-
+  down. `robotsChanged`, `phaseChanged`, `welcome` are all
+  unsubscribed in cleanup.
+- **Idempotent SDK calls**: `connect()` is a no-op when the SDK is
+  already `connected` / `streaming`; the host relies on this rather
+  than gating with a flag.
+- **`connectToHost()` is one-shot**: a module-level
+  `bootPromiseRef` returns the same promise for a second call,
+  rather than re-running the handshake.
+
+### 13.6 Protocol v1 messages
+
+Full type definitions in
+[`ts/host/src/lib/protocol.ts`](./host/src/lib/protocol.ts).
+Envelopes are JSON, carry `source: 'reachy-mini'` and `version: 1`.
+Both sides validate `event.origin` against `window.location.origin`
+before trusting the payload.
+
+| Direction       | Type                          | Purpose                                       |
+|-----------------|-------------------------------|-----------------------------------------------|
+| embed → host    | `embed:ready`                 | "I'm alive, send creds"                       |
+| host  → embed   | `host:init`                   | Theme, signaling URL, hfToken, robotPeerId, config |
+| embed → host    | `embed:app-state`             | Lifecycle phase + connecting sub-step         |
+| host  → embed   | `host:theme-changed`          | Theme switched (no reload)                    |
+| host  → embed   | `host:config-changed`         | Config updated (no reload, mobile-driven)     |
+| host  → embed   | `host:leaving`                | Tear-down request with `timeoutMs`            |
+| embed → host    | `embed:request-leave`         | App requests end-of-session                   |
+| embed → host    | `embed:error`                 | Error report (`{ message, fatal, detail? }`)  |
+
+Intentionally **not** in the v1 protocol:
+
+- `embed:request-config-update` (apps don't push config upstream).
+- `host:custom` / `embed:custom` (no free-form channel; new needs
+  land as typed messages via a major bump).
+- Any heartbeat / ping-pong messages.
+
+#### Versioning policy
+
+- `version: 1` is the only version today.
+- **Additive changes** (new optional field, new message type) ship
+  without a version bump.
+- **Breaking changes** (removed field, changed semantics, removed
+  message type) bump to `version: 2`. The host MAY support both
+  versions for one release cycle, then drop v1.
+- On unknown version, the receiver logs a warning and ignores the
+  message. No negotiation handshake.
+
+#### Idempotency
+
+- `host:leaving` may arrive twice; the embed runs `onLeave`
+  callbacks **once** (gated by a `pendingLeaveTokenRef`) and acks
+  every time.
+- `host:init` may arrive twice (rare: bridge re-arm); the embed
+  treats the latest as authoritative and re-applies theme / config.
+
+### 13.7 Non-goals
+
+To stay simple and auditable, the host shell explicitly does NOT do:
+
+- **App discovery / listing / catalog**. The shell renders exactly
+  **one** app: the one it ships with. Listing apps lives in the
+  Reachy Mini mobile app, fed by the website's `/api/js-apps`
+  endpoint (filtered on `reachy_mini_js_app`).
+- **"Official app" badging in the shell**. Officialness is derived
+  from the Space ID prefix and surfaces only in the mobile catalog.
+- **Multi-robot per tab**. One robot at a time per Space session.
+- **Hot reload of the app code without reloading the iframe**.
+  Code updates require unmounting + remounting.
+- **App ↔ app communication**. Apps are sandboxed by design.
+- **Offline mode**. The central is required for every session.
+- **Automatic WebRTC retry**. On a session drop, the user goes
+  back to the picker manually.
+- **Queue or persistence of postMessage events** if the bridge is
+  down. The bridge is best-effort; both sides re-converge on the
+  next message.
+- **Server-side rendering**. The host is a CSR shell, deliberately.
+- **Cross-origin iframe**. The embed is same-origin with the host
+  (both served by the Space); the origin check relies on this.
+- **Imposing a framework on app authors**. Apps inside the iframe
+  are completely free of framework constraints.
+
+### 13.8 Threat model
+
+The host runs in a HF Spaces container; the embed runs in a
+same-origin iframe within the same Space.
+
+| Asset                    | Threat                                   | Mitigation                                     |
+|--------------------------|------------------------------------------|------------------------------------------------|
+| HF bearer token          | Leak via URL log / referer               | Hash-only + immediate wipe (§13.5.2), 15 min TTL |
+| HF bearer token          | Leak via sessionStorage to other origin  | Same-origin embed, no cross-origin postMessage |
+| `config` payload         | Attacker controls URL → malformed JSON   | App MUST validate at the boundary (typed cast is not enough) |
+| postMessage channel      | Random extension posts a forged message  | Receivers check `source === 'reachy-mini'` AND `event.origin === window.location.origin` |
+| Central session          | Tab crashes, robot stays claimed         | `pagehide` triggers `stopSession()`; central also enforces idle timeout |
+
+**Out of scope** for this iteration:
+- Defence against a malicious app that the user explicitly loaded.
+  We trust apps published under the `pollen-robotics/*` namespace.
+- Defence against a compromised central. The signaling URL is
+  configurable per-Space; the central is the trust root.
+
+---
+
+## 14. Robotics best practices
+
+Subpath import: `@pollen-robotics/reachy-mini-sdk/animation`
+
+Pure-TypeScript helpers that every Reachy Mini JS app used to copy-paste
+from Rémi's `reachy-mini-js-practices` bench (the same source referenced
+inline in `ts/animation/safe-return.ts`, `distance.ts`, `presets.ts`).
+**No daemon changes** - everything routes through existing data-channel
+commands (`setMotorMode`, `setTarget`, `gotoTarget`). Three concrete
+callers today (`reachy_mini_emotions`, `reachy_mini_marionette` v1 + v2)
+still carry their own copies; consolidate onto this lib for new apps.
+
+See [`ts/animation/DESIGN.md`](./animation/DESIGN.md) for the two-phase
+roadmap: Phase 1 (everything below) ships now; Phase 2 is the video-game-style
+animation graph (named layers, masking, crossfades, procedural clips) - not
+in this release.
+
+### 14.1 Pose types: `Pose` vs `PartialPose`
+
+```ts
+import type { Pose, PartialPose } from "@pollen-robotics/reachy-mini-sdk/animation";
+
+interface Pose         { head: number[]; antennas: [number, number]; body_yaw: number }
+interface PartialPose  { head?: number[]; antennas?: [number, number] | number[]; body_yaw?: number }
+```
+
+- **`Pose`**: all three channels required. Use for hand-authored targets
+  where you want the type system to nag if you forget a channel.
+- **`PartialPose`**: any subset. Matches the SDK's `setTarget` /
+  `gotoTarget` partial-update semantics, and is the shape of
+  `reachy.robotState` (fields appear only after the daemon has emitted
+  them).
+
+Wire-format units, everywhere: `head` is a flat 16-float row-major 4×4
+homogeneous matrix, `antennas` is `[right, left]` in **radians**,
+`body_yaw` is a scalar in **radians**.
+
+> Avoid carrying degrees around in your motion code. Convert at the UI
+> boundary (`degToRad` / `radToDeg` from the SDK root) so everything
+> below the boundary speaks wire units. Apps that drift between deg and
+> rad ship subtle off-by-57 bugs.
+
+### 14.2 Distance & scaled duration
+
+The pure math behind "how big is this move" and "how long should it
+take", computed **synchronously client-side** so apps can sync audio
+cues, schedule streamer ticks, and live-tune constants without an extra
+round-trip to the daemon.
+
+```ts
+import {
+    distanceBetweenPoses,
+    scaledDuration,
+    DEFAULT_SCALED_DURATION_PRESET,
+} from "@pollen-robotics/reachy-mini-sdk/animation";
+
+const dist = distanceBetweenPoses(reachy.robotState, target);
+// { head?: number /* magic-mm */,
+//   antennas?: { right: number, left: number } /* deg */,
+//   body_yaw?: number /* deg */ }
+
+const plan = scaledDuration(reachy.robotState, target);
+// { duration: number,
+//   limiter: "head"|"antennaR"|"antennaL"|"body_yaw"|null,
+//   perChannel: { head?, antennaR?, antennaL?, body_yaw? } }
+
+reachy.gotoTarget({ ...target, duration: plan.duration });
+```
+
+The head metric is **magic-mm** - `translation_mm + rotation_deg` fused
+into a single scalar that's monotonic with "how big does this move
+feel". Mirror of the daemon's
+`utils/interpolation.distance_between_poses`.
+
+**Log `plan.limiter` in your motion paths.** It answers "why does the
+home return take 1.2 s?" instantly without bisecting through three
+channels by hand.
+
+The default preset is calibrated on a real Reachy Mini (May 2026 bench):
+
+| Field | Default | Rationale |
+|---|---|---|
+| `headSecPerMagicMm` | `0.015` | 0.02 reads as noticeably slow on the head. |
+| `antennaSecPerDeg` | `0.005` | Antennas are light; PR [#952](https://github.com/pollen-robotics/reachy_mini/pull/952) resonance window penalises too-fast moves. |
+| `bodyYawSecPerDeg` | `0.015` | Body sits between head (heavy) and antennas (light). |
+| `minDurationSec` | `0.01` | Low floor so small in-app corrections feel snappy. |
+| `maxDurationSec` | `1.5` | Matches the host shell's leave-protocol budget so `safelyReturnToPose` fits inside `onLeave`. |
+
+Derive a custom preset by spreading (don't mutate - the constant is
+deep-frozen):
+
+```ts
+const SLOWER_HEAD = {
+    ...DEFAULT_SCALED_DURATION_PRESET,
+    headSecPerMagicMm: 0.03,
+};
+const plan = scaledDuration(current, target, SLOWER_HEAD);
+```
+
+Edge case: when no channel overlaps between `current` and `target`,
+`scaledDuration` returns `{ duration: minDurationSec, limiter: null,
+perChannel: {} }`. The resulting `gotoTarget` is a safe no-op held over
+the minimum dwell. Pass an explicit `duration` if you need a longer
+dwell.
+
+### 14.3 Safe return to home pose (`safelyReturnToPose`)
+
+The canonical "return to safe rest" recipe in one call. Use it as your
+`onLeave` body (see [§8 Cleaning up on leave](#8-cleaning-up-on-leave)):
+
+```ts
+import { safelyReturnToPose } from "@pollen-robotics/reachy-mini-sdk/animation";
+
+handle.onLeave(() => safelyReturnToPose(handle.reachy));
+```
+
+What it does, in order:
+
+1. `reachy.setMotorMode("enabled")` - safe since daemon PR
+   [#1138](https://github.com/pollen-robotics/reachy_mini/pull/1138)
+   (torque-on now pins all targets to the present pose before flipping).
+2. Reads `reachy.robotState` for the current pose snapshot.
+3. Computes `scaledDuration(current, target, preset)`.
+4. Dispatches `reachy.gotoTarget({ ...target, duration })`.
+
+Returns the `ScaledDurationResult` **synchronously after dispatching** -
+does NOT await completion. If you need to await the motion finishing,
+subscribe to the `state` event or `await sleep(plan.duration * 1000)`.
+
+Default target is `INIT_POSE`:
+
+```ts
+import { INIT_POSE } from "@pollen-robotics/reachy-mini-sdk/animation";
+
+// INIT_POSE.head     : identity 4×4 matrix (np.eye(4) in daemon parlance)
+// INIT_POSE.antennas : [-0.1745, 0.1745]  ≈  ±10° outward (anti-resonance offset, PR #952)
+// INIT_POSE.body_yaw : 0
+```
+
+Override for app-specific rest poses:
+
+```ts
+handle.onLeave(() =>
+    safelyReturnToPose(handle.reachy, {
+        target: { head: customHeadMatrix, antennas: [0, 0], body_yaw: 0 },
+    })
+);
+```
+
+**Safe to call when the data channel is closed.** Every underlying SDK
+call swallows "channel closed" errors silently; the planned
+`ScaledDurationResult` is still returned so you can log the move that
+would have happened.
+
+### 14.4 Standalone exit hooks (`installShutdownHandler`)
+
+> **Host-shell apps: stop. Use `handle.onLeave()` from `connectToHost()`
+> instead** - it integrates with the host's leave-protocol budget and
+> avoids double-firing. Mixing the two dispatches `safelyReturnToPose`
+> twice on close.
+
+`installShutdownHandler` is for **standalone apps** (test benches,
+custom dashboards, anything that doesn't go through `mountHost()`):
+
+```ts
+import { installShutdownHandler } from "@pollen-robotics/reachy-mini-sdk/animation";
+
+const reachy = new ReachyMini({ appName: "my-bench" });
+await reachy.authenticate();
+await reachy.connect();
+// ...pick robot, startSession...
+installShutdownHandler(reachy);
+```
+
+What it does:
+
+- Wires `pagehide` AND `beforeunload`. Both can fire on a real tab
+  close, but in different scenarios - mobile Safari only fires
+  `pagehide`. Wiring both is necessary for cross-browser coverage.
+- Reentry-guards so `safelyReturnToPose` doesn't dispatch twice when
+  both handlers fire on the same close.
+- Defaults to `onlyWhenStreaming: true`: skips the goto when no session
+  is live, so a stale tab where the user never picked a robot doesn't
+  command anything on close.
+
+### 14.5 Daemon parity warning
+
+`INIT_POSE` and the magic-mm head coefficient mirror constants in the
+**Python daemon**:
+
+- `INIT_POSE.head` ↔ `Backend.INIT_HEAD_POSE` (`np.eye(4)`) in
+  `src/reachy_mini/daemon/backend/abstract.py`.
+- `INIT_POSE.antennas` ↔ `Backend.INIT_ANTENNAS_JOINT_POSITIONS`
+  (`[-0.1745, 0.1745]`).
+- The magic-mm head distance ↔
+  `src/reachy_mini/daemon/utils/interpolation.py:distance_between_poses`.
+
+**If a daemon PR changes any of these, the JS side must follow in the
+same release.** `ts/animation/presets.ts` calls this out at the top of
+each constant; respect it. Both `INIT_POSE` and
+`DEFAULT_SCALED_DURATION_PRESET` are deep-frozen on the JS side so apps
+can't accidentally drift via `INIT_POSE.head[0] = 0` (mutations throw in
+strict mode, silently no-op otherwise).
+
+### 14.6 Anti-patterns
+
+| Don't | Do |
+|---|---|
+| Re-implement `distanceBetweenPoses` / `scaledDuration` in your app. | Import from `/animation`. The lib exists exactly because three apps did this and drifted. |
+| Mix `installShutdownHandler` and `onLeave` in a host-shell app. | `onLeave` only. They both dispatch `safelyReturnToPose` and step on each other. |
+| Call `reachy.stopSession()` inside your `onLeave`. | Let the host tear down. Do app-specific cleanup (return-to-pose, close audio, close sockets) and return. |
+| Mutate `INIT_POSE` or `DEFAULT_SCALED_DURATION_PRESET`. | They're deep-frozen; spread to derive a variant. |
+| `await safelyReturnToPose(...)` expecting the move to complete. | It resolves after **dispatch**, not after motion finishes. `await sleep(plan.duration * 1000)` or subscribe to `state` if you need to wait. |
+| Carry degrees through your motion code. | Convert at the UI boundary; speak radians + magic-mm everywhere below it. |
+| Pass `null` head / antennas / body_yaw to opt a channel out of a `gotoTarget`. | Use `PartialPose` and **omit** the channel. The SDK treats omission as "hold previous target". |

backend/src/agent/skills/reachy-mini-app/daemon/control-loops.md

@@ -0,0 +1,150 @@
+> **Auto-fetched** from [`pollen-robotics/reachy_mini@main`](https://github.com/pollen-robotics/reachy_mini/blob/main/skills/control-loops.md) on 2026-05-29 · canonical SDK pin: `1.8.0-rc1`.
+> Do not edit by hand - run `npm run sync-docs` to refresh.
+
+# Skill: Control Loops
+
+## When to Use
+
+- Building an app that needs real-time reactivity (face tracking, games, joystick control)
+- User asks about `set_target()` or continuous motion control
+- App needs to respond to sensor input at > 10Hz (ideally 50Hz+)
+
+## Quick Check
+
+If the app only needs choreographed, predetermined motions, use `goto_target()` instead (see `motion-philosophy.md`).
+
+---
+
+## The Core Rule
+
+**One control loop, one place calling `set_target()`, running at fixed frequency (~100Hz).**
+
+```python
+import time
+from reachy_mini import ReachyMini
+
+with ReachyMini() as mini:
+    while not stop_event.is_set():
+        # Compute target pose (can change every tick!)
+        pose = compute_current_target_pose()
+
+        # Send it
+        mini.set_target(head=pose, antennas=antennas)
+
+        # Maintain frequency
+        time.sleep(0.01)  # ~100Hz
+```
+
+## Why This Matters
+
+- **Single control point** prevents race conditions and jerky motion
+- **Continuous targets** maintain "illusion of life" - even when idle, keep sending
+- **Modify the pose, not where you call set_target** - complex behavior = change what pose you compute, don't add more set_target calls
+
+---
+
+## Reference Implementation: moves.py
+
+**Best example:** `~/reachy_mini_resources/reachy_mini_conversation_app/src/reachy_mini_conversation_app/moves.py`
+
+> If this folder doesn't exist, run `skills/setup-environment.md` to clone reference apps.
+
+This file demonstrates control with:
+
+### Primary vs Secondary Moves
+
+- **Primary moves** (emotions, dances, goto, breathing) - mutually exclusive, run sequentially
+- **Secondary moves** (face tracking, speech sync) - additive offsets layered on top
+- **Pose fusion** - combining primary pose with secondary offsets
+
+### Phase-Aligned Timing
+
+Uses `time.monotonic()` to measure elapsed time accurately:
+- Avoids wall-clock jumps from NTP sync, sleep/wake, etc.
+- Ensures consistent timing regardless of system load
+
+### Threading Model
+
+- Dedicated worker thread owns robot output
+- Other threads communicate via queues
+- Never call `set_target()` from multiple threads
+
+---
+
+## Basic Control Loop Template
+
+```python
+import time
+import threading
+import numpy as np
+from reachy_mini import ReachyMini
+from reachy_mini.utils import create_head_pose
+
+class MyController:
+    def __init__(self):
+        self.stop_event = threading.Event()
+        self.target_yaw = 0.0
+        self.target_pitch = 0.0
+
+    def control_loop(self, mini: ReachyMini):
+        """Main control loop - only place that calls set_target."""
+        while not self.stop_event.is_set():
+            # Build pose from current targets
+            pose = create_head_pose(
+                yaw=self.target_yaw,
+                pitch=self.target_pitch,
+                degrees=True
+            )
+
+            # Send to robot
+            mini.set_target(head=pose)
+
+            # ~100Hz
+            time.sleep(0.01)
+
+    def update_target(self, yaw: float, pitch: float):
+        """Called from other threads/callbacks to update targets."""
+        self.target_yaw = yaw
+        self.target_pitch = pitch
+
+# Usage
+controller = MyController()
+with ReachyMini() as mini:
+    loop_thread = threading.Thread(target=controller.control_loop, args=(mini,))
+    loop_thread.start()
+
+    # Update targets from elsewhere (e.g., tracking callback)
+    controller.update_target(yaw=30, pitch=10)
+
+    # ... eventually
+    controller.stop_event.set()
+    loop_thread.join()
+```
+
+---
+
+## Common Patterns
+
+### Adding Idle Motion (Breathing)
+
+```python
+def compute_breathing_offset(t: float) -> float:
+    """Subtle pitch oscillation for 'alive' feeling."""
+    return 2.0 * np.sin(2 * np.pi * 0.2 * t)  # 0.2 Hz, 2 degree amplitude
+
+# In control loop:
+t = time.monotonic()
+breathing = compute_breathing_offset(t)
+pose = create_head_pose(yaw=target_yaw, pitch=target_pitch + breathing, degrees=True)
+```
+
+---
+
+## Frequency Considerations
+
+| Frequency | Use case |
+|-----------|----------|
+| 100 Hz | Real-time tracking, games |
+| 50 Hz | Most interactive apps |
+| 30 Hz | Minimum for smooth motion |
+| < 30 Hz | Might look jerky |

backend/src/agent/skills/reachy-mini-app/daemon/interaction-patterns.md

@@ -0,0 +1,154 @@
+> **Auto-fetched** from [`pollen-robotics/reachy_mini@main`](https://github.com/pollen-robotics/reachy_mini/blob/main/skills/interaction-patterns.md) on 2026-05-29 · canonical SDK pin: `1.8.0-rc1`.
+> Do not edit by hand - run `npm run sync-docs` to refresh.
+
+# Skill: Interaction Patterns
+
+## When to Use
+
+- Designing how users will interact with the robot
+- Building games or interactive experiences
+- Creating apps without a traditional GUI
+
+---
+
+## Antennas as Buttons
+
+The antenna motors use low P in PID - they're semi-passive and safe to push. This makes them natural physical buttons.
+
+```python
+ANTENNA_THRESHOLD = 0.3  # radians, tune as needed
+
+def check_antenna_press(mini):
+    _, antennas = mini.get_current_joint_positions()
+    if antennas is None:
+        return None
+
+    left, right = antennas
+    if abs(left) > ANTENNA_THRESHOLD:
+        return "left"
+    if abs(right) > ANTENNA_THRESHOLD:
+        return "right"
+    return None
+```
+
+### Use Cases
+
+- **Start/stop**: Press antenna to begin game
+- **Selection**: Left = option A, Right = option B
+- **Confirmation**: Any antenna = "yes"
+
+**Reference:** `~/reachy_mini_resources/reachy_mini_radio/` (change radio station with antennas)
+
+> If `~/reachy_mini_resources/` doesn't exist, run `skills/setup-environment.md` to clone reference apps.
+
+---
+
+## Head as Controller
+
+The head has 6 DOF - it's a powerful input device for games or recording.
+
+### Reading Head Position
+
+```python
+def get_head_as_joystick(mini):
+    """Map head orientation to joystick-like values."""
+    pose = mini.get_current_head_pose()
+    # Extract orientation (implementation depends on pose format)
+    # Typically you'd extract yaw and pitch
+
+    # Normalize to -1 to 1 range
+    yaw_normalized = pose_yaw / 45.0  # Assuming ±45° range
+    pitch_normalized = pose_pitch / 30.0  # Assuming ±30° range
+
+    return {
+        "x": np.clip(yaw_normalized, -1, 1),
+        "y": np.clip(pitch_normalized, -1, 1)
+    }
+```
+
+### Use Cases
+
+- **Games**: Head tilt controls spaceship, character, cursor
+- **Recording**: Capture head motion for playback
+- **Puppeteering**: Control another robot or avatar
+
+**References:**
+- `~/reachy_mini_resources/fire_nation_attacked/` - Head as joystick in game
+- `~/reachy_mini_resources/spaceship_game/` - Head controls spaceship
+- `~/reachy_mini_resources/marionette/` - Record and playback head motion
+
+---
+
+## No-GUI Pattern
+
+For simple apps, skip the web UI. Use antenna interactions:
+
+### Basic Flow
+
+```python
+def run(self, mini):
+    # 1. Signal readiness (twitch antennas)
+    self.twitch_antennas(mini)
+
+    # 2. Wait for user to press antenna
+    print("Press an antenna to start...")
+    while True:
+        press = check_antenna_press(mini)
+        if press:
+            break
+        time.sleep(0.1)
+
+    # 3. Run the actual app
+    self.main_loop(mini)
+```
+
+### Signaling States
+
+Use antenna motion to communicate without GUI:
+
+| State | Antenna behavior |
+|-------|------------------|
+| Ready/waiting | Gentle twitch |
+| Processing | Slow wave |
+| Success | Quick double bounce |
+| Error | Shake rapidly |
+
+**Reference:** `~/reachy_mini_resources/reachy_mini_simon/` (full game using only antennas)
+
+---
+
+## Combining Patterns
+
+Many apps combine multiple patterns:
+
+```python
+class InteractiveApp:
+    def run(self, mini):
+        # Start with antenna press (no-GUI)
+        self.wait_for_start(mini)
+
+        while self.running:
+            # Use head as input
+            joystick = self.get_head_as_joystick(mini)
+
+            # Check for antenna presses
+            antenna = check_antenna_press(mini)
+            if antenna == "left":
+                self.action_a()
+            elif antenna == "right":
+                self.action_b()
+
+            # Update game/app state based on head position
+            self.update(joystick)
+
+            time.sleep(0.01)
+```
+
+---
+
+## Tips
+
+- **Debounce antenna presses** - Add cooldown to prevent multiple triggers
+- **Provide feedback** - Move antennas or play emotion when input detected
+- **Consider accessibility** - Not everyone can push antennas easily
+- **Test threshold values** - Different users push with different force

backend/src/agent/skills/reachy-mini-app/daemon/javascript-sdk.md

@@ -0,0 +1,241 @@
+> **Auto-fetched** from [`pollen-robotics/reachy_mini@main`](https://github.com/pollen-robotics/reachy_mini/blob/main/docs/source/SDK/javascript-sdk.md) on 2026-05-29 · canonical SDK pin: `1.8.0-rc1`.
+> Do not edit by hand - run `npm run sync-docs` to refresh.
+
+# JavaScript SDK runtime reference
+
+> **Building a Reachy Mini JS app?** The single source of truth is
+> [`ts/APP_CREATION_GUIDE.md`](../../../ts/APP_CREATION_GUIDE.md) at
+> the repo root. It covers scaffolding, `public/icon.svg`, the host
+> shell, `sdk: static` deploy,
+> `mountHost()` / `connectToHost()` API, local dev, FAQ, and the host
+> ↔ embed contract. **Pin the SDK to
+> `@pollen-robotics/reachy-mini-sdk@1.8.0-rc1-main.fd4354c`** (the
+> version validated against the host shell + daemon).
+>
+> **This file** is the runtime API surface of the `ReachyMini` class
+> you receive from `handle.reachy` once `connectToHost()` resolves:
+> methods, events, properties, state machine, and the daemon-side
+> recorded-move playback API. Bookmark it after you've shipped a
+> first app from the guide.
+
+Reachy Mini ships a browser SDK that drives a robot over WebRTC.
+The npm package `@pollen-robotics/reachy-mini-sdk` exposes:
+
+- The `ReachyMini` class (the SDK runtime documented below).
+- The host shell + embed adapter under the `./host*` subpath
+  exports (`./host`, `./host/auto`, `./host/embed`, `./host/protocol`).
+  See [`ts/APP_CREATION_GUIDE.md`](../../../ts/APP_CREATION_GUIDE.md)
+  for the integration recipe.
+
+## Architecture
+
+```
+┌─────────────────────────────────┐
+│  Browser                        │
+│  (your app + reachy-mini-sdk.js)│
+└───────┬────────────┬────────────┘
+        │ SSE/HTTP   │ WebRTC (peer-to-peer)
+        │ signaling  │ video + audio + data
+┌───────▼──────┐     │
+│  Signaling   │     │
+│  Server      │     │
+│  (HF Space)  │     │
+└───────┬──────┘     │
+        │            │
+┌───────▼────────────▼────────────┐
+│  Robot                          │
+│  GStreamer WebRTC daemon        │
+│  camera · mic · motors          │
+└─────────────────────────────────┘
+```
+
+1. Your app is a static HTML/JS page hosted on Hugging Face Spaces.
+2. The SDK handles authentication, signaling, and WebRTC negotiation.
+3. The signaling server relays SDP offers/answers and ICE candidates
+   and validates Hugging Face OAuth tokens.
+4. Once the WebRTC connection is established, video, audio, and
+   commands flow peer-to-peer; the signaling server is no longer in
+   the path.
+
+When you use the host shell (`mountHost()` + `connectToHost()`,
+documented in [`ts/APP_CREATION_GUIDE.md`](../../../ts/APP_CREATION_GUIDE.md)),
+the steps below are handled for you. The class-level API documented
+here is what you use **after** `connectToHost()` resolves, or what
+you call directly if you opted out of the host shell.
+
+## API Reference
+
+### Constructor
+
+```js
+new ReachyMini({
+    signalingUrl: "https://pollen-robotics-reachy-mini-central.hf.space",  // default
+    enableMicrophone: true,  // default — request mic on startSession()
+})
+```
+
+### State Machine
+
+```
+'disconnected' ──connect()──▸ 'connected' ──startSession()──▸ 'streaming'
+     ▴ disconnect()                ▴ stopSession()
+     └─────────────────────────────┘
+```
+
+### Properties (read-only)
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `state` | `string` | `"disconnected"`, `"connected"`, or `"streaming"` |
+| `robots` | `Array` | Available robots: `[{ id, meta: { name } }]` |
+| `robotState` | `Object` | Latest `state` event detail — `{ head: number[16], antennas: [rRad, lRad], body_yaw, motor_mode, is_move_running }` (wire shape) |
+| `username` | `string\|null` | HF username after `authenticate()` |
+| `isAuthenticated` | `boolean` | True if a valid HF token is available |
+| `micSupported` | `boolean` | True if robot offers bidirectional audio |
+| `micMuted` | `boolean` | Your microphone mute state |
+| `audioMuted` | `boolean` | Robot speaker mute state (local only) |
+
+### Methods
+
+| Method | Returns | Description |
+| :--- | :--- | :--- |
+| `authenticate()` | `Promise<boolean>` | Check for existing HF OAuth token |
+| `login()` | — | Redirect to HF login page |
+| `connect()` | `Promise` | Open SSE connection, receive robot list |
+| `startSession(robotId)` | `Promise` | Negotiate WebRTC, resolves when video + data ready |
+| `stopSession()` | `Promise` | End session, back to `connected` |
+| `disconnect()` | — | Close signaling (keeps auth) |
+| `logout()` | — | Clear HF credentials |
+| `attachVideo(videoEl)` | `() => void` | Bind video stream to element; returns cleanup function |
+| `setTarget({ head?, antennas?, body_yaw? })` | `boolean` | Atomic raw-units update — `head` is `number[16]` (flat 4×4), `antennas` is `[rRad, lRad]`, `body_yaw` is radians |
+| `setHeadRpyDeg(roll, pitch, yaw)` | `boolean` | Set head orientation in degrees (wraps `setTarget`) |
+| `setAntennasDeg(right, left)` | `boolean` | Set antenna positions in degrees (wraps `setTarget`) |
+| `setBodyYawDeg(yaw)` | `boolean` | Set body yaw in degrees (wraps `setTarget`) |
+| `playSound(filename)` | `boolean` | Play a sound file on the robot |
+| `sendRaw(data)` | `boolean` | Send arbitrary JSON via data channel |
+| `requestState()` | `boolean` | Request a state snapshot |
+| `setAudioMuted(muted)` | — | Mute/unmute robot speaker (local) |
+| `setMicMuted(muted)` | — | Mute/unmute your microphone |
+| `playMove(motion, opts?)` | `Promise<{finished?, cancelled?, error?, has_audio?}>` | Upload + play a recorded move (optionally with audio) on the daemon's local clock; resolves when playback ends — see [Daemon-side recorded-move playback](#daemon-side-recorded-move-playback) |
+| `cancelMove()` | `boolean` | Cancel an in-flight `playMove` |
+| `uploadAudio(blob, opts?)` | `Promise<string>` | Upload a standalone audio slot, returns `uploadId` — pair with `playUploadedAudio` for record-time sync |
+| `playUploadedAudio(uploadId, opts?)` | `Promise<{started: true, ...}>` | Trigger daemon-side standalone audio playback; resolves on the daemon's `started` broadcast (use as a sync anchor) |
+| `cancelAudio()` | `boolean` | Cancel an in-flight `playUploadedAudio` |
+
+> **`setTarget` head-vs-body coupling.** The `head` matrix is in the
+> world frame. Sending `setTarget({ body_yaw })` alone rotates the
+> body *but not the head's commanded world yaw* — the head's gaze
+> stays fixed in world frame, so visually it appears to counter-rotate
+> as the body turns. For tank-style "head follows body", add the body
+> yaw delta to the head RPY's yaw and ship `head` + `body_yaw` in the
+> same `setTarget` call. The baseline for the head yaw must be the
+> last *commanded* value you tracked yourself, not `state.head` from
+> the telemetry event — telemetry lags one WebRTC RTT and cumulative
+> deltas computed against it stall under rapid input.
+
+### Events
+
+Use `robot.addEventListener(name, handler)` — the SDK extends `EventTarget`.
+
+| Event | Detail | Description |
+| :--- | :--- | :--- |
+| `connected` | `{ peerId }` | Signaling connection established |
+| `disconnected` | `{ reason }` | Signaling connection lost |
+| `robotsChanged` | `{ robots }` | Robot list updated |
+| `streaming` | `{ sessionId, robotId }` | WebRTC session active |
+| `sessionStopped` | `{ reason }` | Session ended |
+| `state` | `{ head, antennas, body_yaw, motor_mode, is_move_running }` | Robot state update (~500ms; wire shape — see "Receive robot state" above) |
+| `videoTrack` | `{ track, stream }` | Video track available |
+| `micSupported` | `{ supported }` | Bidirectional audio availability |
+| `error` | `{ source, error }` | Error from `signaling`, `webrtc`, or `robot` |
+
+### Math Utilities
+
+```js
+import { rpyToMatrix, matrixToRpy, degToRad, radToDeg } from "@pollen-robotics/reachy-mini-sdk";
+
+rpyToMatrix(roll, pitch, yaw)  // degrees → 4×4 rotation matrix (ZYX)
+matrixToRpy(matrix)            // 4×4 matrix → { roll, pitch, yaw } in degrees
+```
+
+## Daemon-side recorded-move playback
+
+Long recorded moves (and any move with audio) should play **server-side on the daemon's local clock**, not by streaming `set_target` frames from the browser. The browser uploads the move once over the WebRTC data channel and the daemon ticks the inner loop at the requested frequency — no per-frame round-trip, smooth on wireless robots. When audio is attached the daemon plays it on the same GStreamer pipeline, so motion and audio share a single clock (no cross-network drift).
+
+### Combined motion + audio
+
+```js
+const result = await robot.playMove(motion, {
+    audioBlob,                    // optional, 16 kHz mono PCM WAV
+    audioLeadMs: -100,            // system-wide default
+    description: "happy wave",
+    onProgress: (p) => console.log(p.phase, p.sent, p.total),
+    onStarted: ({ duration_s, has_audio }) => { /* sync anchor */ },
+});
+// result is { finished: true } | { cancelled: true } | { error: "..." }
+
+// Cancel at any time from another code path:
+robot.cancelMove();
+```
+
+`motion` is the shape the Python `RecordedMove` parser expects:
+```js
+{ time: [0, 0.01, 0.02, …], set_target_data: [{ head, antennas, body_yaw }, …] }
+```
+
+`audioLeadMs` shifts audio relative to motion at the daemon:
+- **Positive** — audio fires N ms BEFORE motion (compensates motor pickup).
+- **Negative** — motion fires N ms BEFORE audio (compensates GStreamer playbin warmup).
+- **Default `-100`** is the empirical system-wide constant (combined motor + pipeline). Tune only after measuring.
+
+The encoded wire form defaults to `gzip+base64` (typically ~3× smaller for recorded-move JSON). Falls back to plain JSON if the browser lacks `CompressionStream`.
+
+### Record-time audio (sync anchor)
+
+For recording flows that want the SAME audio pipeline at capture AND replay (so pipeline latency cancels out and one `audioLeadMs` works for all recordings):
+
+```js
+// 1. During the countdown — upload the source audio.
+const audioId = await robot.uploadAudio(audioBlob, { description: "song" });
+
+// 2. At the GO! moment — kick off daemon-side playback, await the
+//    started broadcast, then start motion capture.
+await robot.playUploadedAudio(audioId);
+const captureT0 = performance.now();
+startMyMotionCapture();
+
+// 3. On stop / cancel / restart — stop the audio.
+robot.cancelAudio();
+```
+
+The daemon does NOT emit a `finished` event for standalone audio; callers know the duration from the WAV header and call `cancelAudio()` when done.
+
+### Audio format
+
+Audio must be canonical **16 kHz mono 16-bit PCM WAV**. Apps are responsible for normalizing before upload — the daemon does not transcode. Format mismatch is a frequent cause of "audio is silent / wrong speed" on inherited datasets.
+
+### Backpressure & cancellation
+
+`playMove` and `uploadAudio` pace chunk sends on the data channel's `bufferedAmount` so multi-megabyte uploads (a 3-min song's WAV is ~6 MB base64) don't degrade other channels on the same peer connection. There's no separate `pause` — to stop a long upload mid-way, close the session.
+
+## Security
+
+- Authentication goes through Hugging Face OAuth — only users logged in to HF can access the signaling server.
+- By default, you can only connect to robots registered under your own HF account.
+- WebRTC connections are encrypted (DTLS/SRTP).
+
+## Prerequisites
+
+- Your robot must be running the wireless firmware and connected to the central signaling server.
+- The robot must have a valid Hugging Face token configured (see [Usage](../platforms/reachy_mini/usage)).
+- Currently supported on **wireless versions** only.
+
+## Working examples
+
+The three reference apps maintained alongside the SDK are the canonical worked examples. They all use the host shell pattern and the current SDK pin:
+
+- [`pollen-robotics/reachy_mini_minimal_conversation`](https://huggingface.co/spaces/pollen-robotics/reachy_mini_minimal_conversation) — vanilla TS + Vite.
+- [`pollen-robotics/reachy_mini_emotions`](https://huggingface.co/spaces/pollen-robotics/reachy_mini_emotions) — React 19 + MUI 7 + Vite.
+- [`pollen-robotics/reachy_mini_telepresence`](https://huggingface.co/spaces/pollen-robotics/reachy_mini_telepresence) — React 19 + MUI 7 + Vite with camera + media streams.
+
+Clone the closest one and trim. See [`ts/APP_CREATION_GUIDE.md`](../../../ts/APP_CREATION_GUIDE.md) for the step-by-step.

backend/src/agent/skills/reachy-mini-app/daemon/motion-philosophy.md

@@ -0,0 +1,115 @@
+> **Auto-fetched** from [`pollen-robotics/reachy_mini@main`](https://github.com/pollen-robotics/reachy_mini/blob/main/skills/motion-philosophy.md) on 2026-05-29 · canonical SDK pin: `1.8.0-rc1`.
+> Do not edit by hand - run `npm run sync-docs` to refresh.
+
+# Skill: Motion Control Philosophy
+
+## When to Use
+
+- Deciding between `goto_target()` and `set_target()`
+- Planning how motion will work in your app
+- User asks about smooth motion or interpolation
+
+---
+
+## The Two Methods
+
+| Method | Behavior | Use when |
+|--------|----------|----------|
+| `goto_target()` | Smooth interpolation over duration | **Default choice** - gestures, choreography, transitions |
+| `set_target()` | Immediate, no interpolation | Real-time control requiring continuous reactivity |
+
+---
+
+## goto_target(): The Default Choice
+
+Use this for most motion. It handles interpolation automatically.
+
+```python
+from reachy_mini import ReachyMini
+from reachy_mini.utils import create_head_pose
+
+with ReachyMini() as mini:
+    pose = create_head_pose(yaw=30, pitch=10, degrees=True)
+    mini.goto_target(head=pose, duration=1.0, method="minjerk")
+```
+
+### Interpolation Methods
+
+| Method | Character |
+|--------|-----------|
+| `linear` | Constant speed |
+| `minjerk` | Natural, smooth (default) |
+| `ease_in_out` | Slow start/end |
+| `cartoon` | Exaggerated, bouncy |
+
+### Key Insight
+
+During `goto_target()` interpolation, **you cannot react to external stimuli**. The robot commits to completing the movement. This is fine for:
+- Playing emotions
+- Choreographed sequences
+- Transitioning between states
+
+---
+
+## set_target(): For Real-Time Control
+
+Use this when you need to react every frame (face tracking, games, joystick).
+
+**Requirements:**
+- Must run in a control loop at 50-100 Hz
+- Single place in code calling `set_target()`
+- Keep sending targets even when "idle"
+
+See `control-loops.md` for implementation details.
+
+---
+
+## Decision Flowchart
+
+```
+Does your app need to react to input/sensors in real-time?
+├── NO → Use goto_target()
+│        - Simpler code
+│        - Guaranteed smooth motion
+│        - Good for: emotions, dances, scripted sequences
+│
+└── YES → Use set_target() in a control loop
+          - More complex but fully reactive
+          - You control smoothing
+          - Good for: tracking, games, recording
+```
+
+---
+
+## Common Mistake
+
+Don't do this:
+
+```python
+# BAD: Multiple set_target calls scattered in code
+def on_face_detected(face):
+    mini.set_target(head=look_at_face(face))
+
+def on_button_press():
+    mini.set_target(head=neutral_pose)
+
+def idle_behavior():
+    mini.set_target(head=breathing_pose)
+```
+
+Do this instead:
+
+```python
+# GOOD: Single control loop, update target variables
+def control_loop():
+    while running:
+        pose = compute_final_pose()  # Combines all inputs
+        mini.set_target(head=pose)
+        time.sleep(0.01)
+
+def on_face_detected(face):
+    controller.face_target = look_at_face(face)
+
+def on_button_press():
+    controller.override = neutral_pose
+```

backend/src/agent/skills/reachy-mini-app/daemon/rest-api.md

@@ -0,0 +1,123 @@
+> **Auto-fetched** from [`pollen-robotics/reachy_mini@main`](https://github.com/pollen-robotics/reachy_mini/blob/main/skills/rest-api.md) on 2026-05-29 · canonical SDK pin: `1.8.0-rc1`.
+> Do not edit by hand - run `npm run sync-docs` to refresh.
+
+# Skill: REST API
+
+## When to Use
+
+- Building web UIs or dashboards (JavaScript/TypeScript)
+- Creating clients in non-Python languages
+- Controlling robot from a different machine
+- Building AI applications that connect via HTTP
+- Creating MCP (Model Context Protocol) servers
+
+---
+
+## Overview
+
+The Reachy Mini daemon exposes a **FastAPI-based REST API** with HTTP and WebSocket endpoints. This allows control from any language or platform.
+
+**Base URL:** `http://localhost:8000/api` (when daemon is running)
+
+**Interactive docs:** `http://localhost:8000/docs` (Swagger UI)
+
+---
+
+## Key Endpoints
+
+### Movement Control
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/move/goto` | POST | Move to target (head pose, antennas, body yaw) |
+| `/api/move/set_target` | POST | Set instant target (high-frequency control) |
+| `/api/move/play/wake_up` | POST | Wake up the robot |
+| `/api/move/play/goto_sleep` | POST | Put robot to sleep |
+| `/api/move/play/recorded-move-dataset/{dataset}/{move}` | POST | Play recorded moves |
+| `/api/move/running` | GET | List running move tasks |
+| `/api/move/stop` | POST | Stop a running move |
+
+### State Queries
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/state/full` | GET | Complete robot state |
+| `/api/state/present_head_pose` | GET | Current head pose |
+| `/api/state/present_body_yaw` | GET | Current body rotation |
+| `/api/state/present_antenna_joint_positions` | GET | Antenna positions |
+| `/api/state/doa` | GET | Direction of arrival (microphones) |
+
+### Motor Control
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/motors/status` | GET | Motor status/control mode |
+| `/api/motors/set_mode/{mode}` | POST | Change mode (enabled, disabled, gravity_compensation) |
+
+### WebSocket Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `ws://localhost:8000/api/state/ws/full` | Real-time state streaming |
+| `ws://localhost:8000/api/move/ws/updates` | Movement event streaming |
+| `ws://localhost:8000/api/move/ws/set_target` | Stream target commands |
+
+---
+
+## When to Use REST API vs Python SDK
+
+**Use REST API when:**
+- Building web frontends
+- Using non-Python languages (JavaScript, Go, Rust, etc.)
+- Running on a different machine from the robot
+- Need language-agnostic access
+
+**Use Python SDK when:**
+- Building Python apps on the same machine
+- Need direct kinematic calculations
+- Working with media streams (camera, audio)
+- Building high-frequency control loops (better latency)
+- Working with recorded moves
+
+---
+
+## Example: JavaScript Fetch
+
+```javascript
+// Move head to position
+const response = await fetch('http://localhost:8000/api/move/goto', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    head_pose: { yaw: 30, pitch: 10 },
+    duration: 1.0
+  })
+});
+
+// Get current state
+const state = await fetch('http://localhost:8000/api/state/full')
+  .then(r => r.json());
+console.log(state);
+```
+
+---
+
+## Example: WebSocket State Streaming
+
+```javascript
+const ws = new WebSocket('ws://localhost:8000/api/state/ws/full');
+
+ws.onmessage = (event) => {
+  const state = JSON.parse(event.data);
+  console.log('Head pose:', state.head_pose);
+};
+```
+
+---
+
+## Source Code Reference
+
+For implementation details (in this repository):
+- **Main FastAPI app:** `src/reachy_mini/daemon/app/main.py`
+- **Router modules:** `src/reachy_mini/daemon/app/routers/`
+- **API docs:** `docs/source/troubleshooting.md` (REST API FAQ section)

backend/src/agent/skills/reachy-mini-app/daemon/safe-torque.md

@@ -0,0 +1,120 @@
+> **Auto-fetched** from [`pollen-robotics/reachy_mini@main`](https://github.com/pollen-robotics/reachy_mini/blob/main/skills/safe-torque.md) on 2026-05-29 · canonical SDK pin: `1.8.0-rc1`.
+> Do not edit by hand - run `npm run sync-docs` to refresh.
+
+# Skill: Safe Torque Handling
+
+## Motor Control Modes
+
+Three modes selected via `setMotorMode(...)` (JS) or `enable_motors()` / `disable_motors()` / `enable_gravity_compensation()` (Python):
+
+- **`enabled`** — torque on, position control. Motors hold the commanded pose. Default working state.
+- **`disabled`** — torque off. The head is fully compliant; it falls under gravity. Used during motion recording so the user can move the head by hand.
+- **`gravity_compensation`** — torque on, current control. Motors actively cancel gravity, so the head feels weightless and can be pushed around by hand without falling. Requires the Placo kinematics engine.
+
+`enable_motors()` pins all targets to the present pose before flipping torque on, so the head never snaps to an old goal. Set targets *after* enabling, not before — targets set before are overwritten.
+
+## When to Use
+
+- Enabling or disabling motor torque
+- Recording motion (compliance mode)
+- Any app that toggles motors on/off
+
+---
+
+## The Problem
+
+When you toggle motor torque carelessly:
+- **Disabling torque**: Head falls (gravity)
+- **Enabling torque**: Head jumps to old goal position
+
+Both cause jerky, unpleasant motion.
+
+---
+
+## Before Disabling Torque
+
+Go to a safe position first (head will fall when torque is off):
+
+```python
+from reachy_mini.reachy_mini import SLEEP_HEAD_POSE
+import numpy as np
+
+# Move to sleep position before disabling
+antenna_angle = np.deg2rad(15)
+reachy_mini.goto_target(
+    SLEEP_HEAD_POSE,
+    antennas=[-antenna_angle, antenna_angle],
+    duration=1.0,
+)
+reachy_mini.disable_motors()
+```
+
+---
+
+## Before Enabling Torque
+
+Set goal to current position first (prevents jump to old goal):
+
+```python
+def _goto_current_pose(reachy_mini, duration=0.05):
+    """Set goal to current position to prevent jumps."""
+    head_pose = reachy_mini.get_current_head_pose()
+    _, antennas = reachy_mini.get_current_joint_positions()
+
+    reachy_mini.goto_target(
+        head=head_pose,
+        antennas=list(antennas) if antennas is not None else None,
+        duration=duration,
+    )
+```
+
+---
+
+## Known Bug: Partial Motor Enable/Disable
+
+There is a known edge case when enabling/disabling only a **subset** of motors. The workaround is to call a full disable before enabling:
+
+```python
+def _safe_enable_motors(self, reachy_mini: ReachyMini) -> None:
+    """Enable motors safely, handling edge cases."""
+    self._goto_current_pose(reachy_mini, duration=0.05)
+    reachy_mini.disable_motors()  # Needed to handle edge case with mixed motor states
+    reachy_mini.enable_motors()
+```
+
+**Reference:** See `~/reachy_mini_resources/fire_nation_attacked/fire_nation_attacked/main.py` for a working implementation of this pattern.
+
+> If `~/reachy_mini_resources/` doesn't exist, run `skills/setup-environment.md` to clone reference apps.
+
+---
+
+## Complete Safe Enable Pattern
+
+```python
+def safe_enable_motors(reachy_mini: ReachyMini) -> None:
+    """Enable motors without jerky motion."""
+    # 1. Read current position
+    head_pose = reachy_mini.get_current_head_pose()
+    _, antennas = reachy_mini.get_current_joint_positions()
+
+    # 2. Set goal to current (very short duration)
+    reachy_mini.goto_target(
+        head=head_pose,
+        antennas=list(antennas) if antennas is not None else None,
+        duration=0.05,
+    )
+
+    # 3. Full disable (handles mixed motor state edge case)
+    reachy_mini.disable_motors()
+
+    # 4. Enable all motors
+    reachy_mini.enable_motors()
+```
+
+---
+
+## Reference Implementation
+
+**Best example:** `~/reachy_mini_resources/marionette/marionette/main.py`
+
+This app toggles torque for motion recording and demonstrates the full safe pattern.