mudra-skills 3.1.2 → 3.2.0

package/README.md

@@ -78,7 +78,8 @@ Every generated app includes:
 |---|---|---|
 | `gesture` | discrete | finger pinches (index, middle, ring, little, thumb, grab) |
 | `button` | discrete | hardware button press/release |
-| `pressure` | analog | continuous squeeze force (0–1) |
+| `direct_pressure` | analog | Finger pressure 0–100, normalized 0–1 (continuous ungated stream) |
+| `pinch_pressure` | analog | Finger pressure 0–100, normalized 0–1 (tap-to-release filtered stream) |
 | `navigation` | pointer | 2D cursor delta (x, y) |
 | `nav_direction` | discrete | swipe direction (up/down/left/right) |
 | `imu_acc` | analog | accelerometer (x, y, z) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mudra-skills",
-  "version": "3.1.2",
+  "version": "3.2.0",
   "description": "Mudra Band skills for Claude Code, Codex, and Antigravity — 2D, 3D/XR, or auto-classified",
   "type": "module",
   "bin": {

package/skills/mudra-master/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mudra-master
-version: 3.1.2
+version: 3.2.0
 description: Master router for Mudra Band app builds. Use when the user describes an app, experience, prototype, timer, counter, or tool to build with the Mudra Band but has not made clear whether they want a 2D (flat/screen) or 3D (spatial/XR/VR/AR) version. This skill classifies the prompt deterministically and hands off the original prompt verbatim to either mudra-preview (2D) or mudra-xr (3D), asking exactly one 2D-or-3D disambiguation question only when the dimension cannot be inferred. Do not use for pure code edits, repo questions, or any request that is not a Mudra-app build.
 ---
 # Mudra Master Skill

package/skills/mudra-master/mudra-preview/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mudra-preview
-version: 3.1.2
+version: 3.2.0
 description: Generate a working Mudra Band interactive app preview as a single-file HTML. Use when the user describes a Mudra-controlled experience (gesture, pressure, navigation, IMU, EMG), wants to prototype a Mudra Link app, or asks to build/preview a Mudra app.
 ---
 
@@ -44,7 +44,7 @@ The canonical protocol is in `references/agent_protocol.json`.
 
 1. **Read the full instructions** from `references/prompt.md` inside the skill base directory. That file contains the complete protocol contract, signal compatibility rules, the Mode Toggle architecture (mandatory), build defaults, and sample catalog — follow all of it.
 
-2. **Infer intent** from the user's description (or the args passed to this skill). Fill gaps with smart defaults. Ask only if there is genuine ambiguity (e.g., `gesture` vs `pressure`, `navigation` vs `nav_direction`, or directional motion vs IMU+Biometric bundle).
+2. **Infer intent** from the user's description (or the args passed to this skill). Fill gaps with smart defaults. Ask only if there is genuine ambiguity (e.g., `gesture` vs pressure, `navigation` vs `nav_direction`, or directional motion vs IMU+Biometric bundle). Choosing between `direct_pressure` and `pinch_pressure` is **not** an ambiguity — default to `direct_pressure` and state the choice in one clause.
 
 3. **Select the best-matching template** from `assets/` inside the skill base directory. Use the selection rule from `references/prompt.md` (motion mode → interaction pattern → signal overlap).
 
@@ -71,10 +71,12 @@ Every generated app MUST include a **compact, always-visible simulator panel** w
 | `gesture` | `Tap`, `2Tap`, `Twist`, `2Twist` |
 | `nav_direction` | `↑`, `↓`, `←`, `→`, `Roll L`, `Roll R` |
 | `navigation` | `↑`, `↓`, `←`, `→` (each click emits one delta event of ±8) |
-| `pressure` | Slider `0–100%` (or `−` / `+` buttons if horizontal space is tight) |
+| `direct_pressure` | Slider `0–100%` (or `−` / `+` buttons if horizontal space is tight) |
+| `pinch_pressure` | Slider `0–100%` plus a `Release` button that returns it to 0 — mirrors the pinch-hold-release arc |
 | `button` | `Press`, `Release` |
 | `imu_acc` | `Tilt X`, `Tilt Y`, `Tilt Z` (each fires a 5-frame burst at ±2 m/s²) |
 | `imu_gyro` | `Rot X`, `Rot Y`, `Rot Z` (each fires a 5-frame burst at ±10 deg/s) |
+| `imu_quaternion` | `Yaw ±`, `Pitch ±`, `Roll ±`, `Reset` — each click rotates a held Euler state by 15°, converts to a unit quaternion, and emits it as a one-sample frame `{ values: [[w,x,y,z]] }` |
 | `emg` | `Spike` (injects a burst of elevated samples on all 3 channels) |
 
 **How each button must fire**
@@ -99,8 +101,22 @@ Unless the user explicitly asks for a different signal, every generated
 app MUST restrict itself to **at most these signals** (subject to the
 exclusivity rules below):
 
-1. **One** of `pressure` **or** `gesture` — never both. `gesture` and
-   `pressure` are mutually exclusive.
+1. **One** pressure signal **or** `gesture` — never both. `gesture` and
+   pressure are mutually exclusive.
+   - **Pressure mode rule**: there is no signal named `pressure`. Pick
+     **one** of `direct_pressure` or `pinch_pressure` — never both.
+     - `direct_pressure` → Finger pressure 0–100, normalized 0–1.
+       **New** continuous ungated stream — always on, no tap/release
+       gating. **Default.** Requires firmware 6.0.12.11 and above. Use
+       it whenever the user just says "pressure" or names an analog
+       synonym (volume, brush, throttle, zoom, intensity).
+     - `pinch_pressure` → Finger pressure 0–100, normalized 0–1. The
+       **original** tap-to-release filtered stream (formerly named
+       `pressure`). Values stream only between tap and release: streaming
+       starts on tap, the value falls off on release, and streaming
+       stops until the next tap. Works on older firmware. Use it only
+       when the interaction is explicitly commit-then-modulate:
+       grab-and-scale, pinch-to-zoom, pinch-and-hold-to-charge.
    - **Tap exclusivity rule** (within `gesture`): use `tap` OR `double_tap`
      — **never both together** unless the user explicitly names both (e.g.,
      "use single tap for X and double tap for Y").
@@ -120,9 +136,19 @@ Rules:
 - Drop any of the above if the concept does not need it (e.g., a pure
   tap-counter subscribes to `gesture` only and skips the directional
   signal).
-- **`gesture` and `pressure` are mutually exclusive** — pick one
+- **`gesture` and pressure are mutually exclusive** — pick one
   interaction model per app. Tap/twist concepts → `gesture`. Analog
-  concepts (volume, brush, throttle) → `pressure`.
+  concepts (volume, brush, throttle) → `direct_pressure`.
+- **`imu_quaternion` (Hand Orientation) is standalone and free-combining.**
+  It streams absolute, drift-free orientation as unit quaternions and
+  belongs to no bundle — it combines with `navigation`, `nav_direction`,
+  `gesture`, `button`, and the pressure modes alike. Reach for it whenever
+  the concept needs aiming, heading, pose gating, or 1:1 rotation, instead
+  of subscribing to the IMU+Biometric bundle just to derive an angle.
+  Requires firmware 6.0.12.11 and above. **Its payload shape differs
+  from the other IMU signals** — `data.values` is a *list of samples*,
+  each `[w, x, y, z]`, not three per-axis arrays. Read the latest with
+  `values.at(-1)`.
 - `nav_direction` and `navigation` are **mutually exclusive per app** —
   pick the one that fits the interaction (discrete swipes →
   `nav_direction`; continuous cursor/scroll → `navigation`). Never wire
@@ -133,8 +159,8 @@ Rules:
   `nav_direction` — pick directional motion OR the IMU+Biometric bundle,
   never both.
 - Other gesture subtypes (`twist`, `double_twist`, etc.) and other
-  signals (`button`, `imu_acc`, `imu_gyro`, `emg`) are **off by
-  default**. Only include them when the user's prompt names them,
+  signals (`button`, `imu_acc`, `imu_gyro`, `emg`, `imu_quaternion`) are
+  **off by default**. Only include them when the user's prompt names them,
   names a synonym from the Signal Inference table in
   `references/prompt.md` § "Signal Inference Reference", or describes
   an interaction that genuinely cannot be expressed with the defaults
@@ -153,7 +179,9 @@ Rules:
 - Subscribe one signal per command: `{ "command": "subscribe", "signal": "<name>" }` — singular `signal`, never `signals`, never an array
 - Motion modes are mutually exclusive: Pointer (`navigation`+`button`) / Direction (`nav_direction`) / IMU+Biometric (`imu_acc`+`imu_gyro`+`emg`, always all three together)
 - IMU+Biometric bundle: `imu_acc`, `imu_gyro`, `emg` always subscribed together — never partially. The bundle is mutually exclusive with `navigation` and `nav_direction`.
-- `gesture` and `pressure` are mutually exclusive — never combine them
-- `button` combines freely with `gesture`, `pressure`, `emg`, `imu_acc`, `imu_gyro` (subject to the Pointer/Direction/IMU motion-mode XOR — `button` belongs to Pointer mode and never combines with `nav_direction`).
+- Hand Orientation (`imu_quaternion`) is **outside** every motion-mode XOR — it is standalone and combines with any other signal, including `navigation` and `nav_direction`. Requires firmware 6.0.12.11 and above. Payload is `data.values` = list of `[w, x, y, z]` samples; read the latest with `values.at(-1)`.
+- Pressure: pick exactly one. Both are Finger pressure 0–100, normalized 0–1. `direct_pressure` is the **new** continuous ungated stream (default). Requires firmware 6.0.12.11 and above. `pinch_pressure` is the **original** tap-to-release filtered stream and works on older firmware. There is no bare `pressure` signal.
+- `gesture` and pressure are mutually exclusive — never combine them
+- `button` combines freely with `gesture`, either pressure mode, `emg`, `imu_acc`, `imu_gyro`, `imu_quaternion` (subject to the Pointer/Direction/IMU motion-mode XOR — `button` belongs to Pointer mode and never combines with `nav_direction`).
 - **Navigation sensitivity is gentle by default**: keyboard `step = 3`, sim button `±3`, cursor multiplier `0.002`. Raise only when the prompt explicitly asks for fast/snappy movement. See `references/prompt.md` § "Navigation sensitivity defaults".
 - Canonical protocol JSON: `references/agent_protocol.json`

package/skills/mudra-master/mudra-preview/references/agent_protocol.json

@@ -1,6 +1,6 @@
 {
   "title": "Mudra Link - AI Agent Protocol",
-  "version": "3.0",
+  "version": "3.2",
   "role": {
     "description": "You are a creative collaborator for gesture-controlled apps. You help users build applications that respond to hand movements, finger pressure, and muscle activity using the Mudra Band.",
     "approach": "Read what the user wants, fill gaps with smart defaults, and propose a brief concept before building. Be opinionated - pick sensible defaults, suggest creative additions, and only ask questions when there's genuine ambiguity."
@@ -70,7 +70,7 @@
         "sprint",
         "charge"
       ],
-      "pressure": [
+      "direct_pressure": [
         "slide",
         "volume",
         "size",
@@ -79,7 +79,31 @@
         "opacity",
         "brush",
         "zoom",
-        "analog"
+        "analog",
+        "pressure",
+        "press harder",
+        "force"
+      ],
+      "pinch_pressure": [
+        "pinch",
+        "pinch and squeeze",
+        "hold after tap",
+        "squeeze while holding",
+        "press after tap",
+        "tap then squeeze",
+        "sustained pinch"
+      ],
+      "imu_quaternion": [
+        "hand orientation",
+        "wrist orientation",
+        "absolute orientation",
+        "which way the hand is pointing",
+        "aim",
+        "point at",
+        "heading",
+        "roll pitch yaw",
+        "quaternion",
+        "stabilised rotation"
       ],
       "navigation": [
         "move",
@@ -107,7 +131,8 @@
         "nerve"
       ]
     },
-    "bundling_rule": "imu_acc, imu_gyro, and emg always come together as a single group. If the user wants any one of them, subscribe to all three.",
+    "bundling_rule": "imu_acc, imu_gyro, and emg always come together as a single group. If the user wants any one of them, subscribe to all three. imu_quaternion is NOT part of that bundle — it is independently subscribable and combines freely. imu_quaternion: Requires firmware 6.0.12.11 and above. direct_pressure: Requires firmware 6.0.12.11 and above. pinch_pressure works on older firmware.",
+    "pressure_mode_rule": "There is no signal called 'pressure' — that was the old name for pinch_pressure. Pick exactly one of direct_pressure or pinch_pressure. direct_pressure is the NEW continuous ungated stream (always on, no gating; default). Requires firmware 6.0.12.11 and above. pinch_pressure is the ORIGINAL tap-to-release filtered stream (values stream only between tap and release) and works on older firmware. Choose pinch_pressure only when the concept is explicitly about squeezing while a pinch/tap is held.",
     "when_ambiguous": "If the user's concept could use either navigation or the IMU/EMG bundle, ask which fits better. This is the main case where a question is warranted."
   },
   "creative_proposals": {
@@ -118,9 +143,13 @@
         "proposal": "Button hold could sustain a note."
       },
       {
-        "concept": "Drawing app (pressure)",
+        "concept": "Drawing app (direct_pressure)",
         "proposal": "Button could toggle between draw and erase mode."
       },
+      {
+        "concept": "3D model viewer (imu_quaternion)",
+        "proposal": "Tap could reset the orientation to a front-on view."
+      },
       {
         "concept": "Racing game (navigation)",
         "proposal": "Button for boost, tap on nav_direction for turbo."
@@ -135,8 +164,10 @@
       }
     ],
     "forbidden_proposals": [
-      "Never propose pressure to complement gesture — they are mutually exclusive",
-      "Never propose gesture to complement pressure — they are mutually exclusive",
+      "Never propose a pressure signal to complement gesture — they are mutually exclusive",
+      "Never propose gesture to complement direct_pressure or pinch_pressure — they are mutually exclusive",
+      "Never propose direct_pressure and pinch_pressure together — they are mutually exclusive",
+      "Never send 'pressure' as a signal name — it is not a valid signal and returns invalid_signal",
       "Never propose emg alone — it must always come with imu_acc and imu_gyro",
       "Never propose battery as a subscribable signal — battery is read-only via get_status"
     ]
@@ -167,9 +198,9 @@
       },
       "note": "No confidence field — treat every gesture frame as a valid trigger."
     },
-    "pressure": {
-      "description": "Finger pressure (0-100%)",
-      "use_for": "Analog control",
+    "direct_pressure": {
+      "description": "Finger pressure 0–100, normalized 0–1. NEW continuous ungated stream — always on, no tap/release gating. The default pressure signal.",
+      "use_for": "Analog control that is live whenever the finger is pressing, with no gesture gate",
       "examples": [
         "Volume",
         "Brush size",
@@ -178,7 +209,7 @@
         "Opacity"
       ],
       "data_format": {
-        "type": "pressure",
+        "type": "direct_pressure",
         "data": {
           "value": 50,
           "normalized": 0.5,
@@ -187,8 +218,39 @@
         "timestamp": 1234567890
       },
       "notes": [
+        "Finger pressure 0–100, normalized 0–1",
         "value: 0-100 integer",
-        "normalized: 0.0-1.0 float (convenient for scaling)"
+        "normalized: 0.0-1.0 float (convenient for scaling)",
+        "Requires firmware 6.0.12.11 and above.",
+        "Mutually exclusive with pinch_pressure — subscribe to exactly one",
+        "'pressure' is not a valid signal name. That was the old name for pinch_pressure. direct_pressure is a new signal, not a rename."
+      ]
+    },
+    "pinch_pressure": {
+      "description": "Finger pressure 0–100, normalized 0–1. ORIGINAL tap-to-release filtered stream. Formerly named 'pressure'. Values stream only between tap and release: streaming starts on tap, the value falls off on release, and streaming stops until the next tap.",
+      "use_for": "Analog control that only streams while a pinch/tap is held",
+      "examples": [
+        "Tap to grab, then squeeze to scale",
+        "Pinch and hold to charge a shot",
+        "Tap a target, then press harder to zoom in",
+        "Pinch-drag with force-sensitive resistance"
+      ],
+      "data_format": {
+        "type": "pinch_pressure",
+        "data": {
+          "value": 50,
+          "normalized": 0.5,
+          "timestamp": 1234567890
+        },
+        "timestamp": 1234567890
+      },
+      "notes": [
+        "Finger pressure 0–100, normalized 0–1",
+        "Identical payload shape to direct_pressure — only the acquisition window differs",
+        "Values stream only between tap and release; expect a run of frames bracketed by rest",
+        "Mutually exclusive with direct_pressure — subscribe to exactly one",
+        "Works on older firmware — not gated on 6.0.12.11",
+        "Pick this only when the concept is explicitly 'squeeze while pinching/holding'. Otherwise use direct_pressure."
       ]
     },
     "imu_acc": {
@@ -239,6 +301,37 @@
         "Integrate over time for absolute rotation"
       ]
     },
+    "imu_quaternion": {
+      "display_name": "Hand Orientation",
+      "description": "Absolute hand orientation as a stream of unit quaternions [w, x, y, z]",
+      "use_for": "Absolute orientation, aiming, stabilised 3D rotation — no drift integration required",
+      "examples": [
+        "Point-to-aim reticle",
+        "Rotate a 3D model 1:1 with the hand",
+        "Compass / heading readout",
+        "Wrist-orientation gate (only fire when palm is down)",
+        "Orientation-driven camera"
+      ],
+      "data_format": {
+        "type": "imu_quaternion",
+        "data": {
+          "values": [[0.7071, 0.0, 0.7071, 0.0], [0.706, 0.01, 0.708, 0.0]],
+          "frequency": 50,
+          "frequency_std": 0.4,
+          "timestamp": 1234567890
+        },
+        "timestamp": 1234567890
+      },
+      "notes": [
+        "Requires firmware 6.0.12.11 and above.",
+        "CRITICAL SHAPE DIFFERENCE: values is a LIST OF SAMPLES, each sample a 4-element array [w, x, y, z]. This is one nesting level deeper than imu_acc / imu_gyro, whose values is three flat per-axis arrays. Never assume the two shapes match.",
+        "Each sample is a unit quaternion: w² + x² + y² + z² ≈ 1.0. If your norms scatter away from 1, you are chunking the array wrong.",
+        "Use the LAST sample in the packet for live display; use all samples if you need the full motion trace.",
+        "Prefer this over integrating imu_gyro when you need absolute orientation — it does not drift.",
+        "Independently subscribable. NOT part of the imu_acc + imu_gyro + emg bundle, and it combines freely with navigation and nav_direction.",
+        "Rendering tip: feed [w, x, y, z] straight into a quaternion type (e.g. THREE.Quaternion(x, y, z, w) — note the argument order differs)."
+      ]
+    },
     "navigation": {
       "description": "Directional deltas for up/down/left/right movement",
       "use_for": "Directional movement, cursor control, steering",
@@ -344,33 +437,52 @@
   "compatibility": {
     "signal_groups": {
       "discrete": ["gesture", "button"],
-      "analog": ["pressure"],
+      "analog": ["direct_pressure", "pinch_pressure"],
       "pointer_motion": ["navigation", "button"],
       "direction_motion": ["nav_direction"],
-      "imu_biometric": ["imu_acc", "imu_gyro", "emg"]
+      "imu_biometric": ["imu_acc", "imu_gyro", "emg"],
+      "orientation": ["imu_quaternion"]
     },
     "bundling_rules": [
       "imu_acc, imu_gyro, and emg are always subscribed together — using any one requires all three",
-      "gesture and pressure are mutually exclusive — never combine them",
+      "direct_pressure and pinch_pressure are mutually exclusive — exactly one pressure signal per app. direct_pressure: Requires firmware 6.0.12.11 and above. pinch_pressure works on older firmware.",
+      "gesture and either pressure signal are mutually exclusive — never combine them",
+      "imu_quaternion is standalone — it belongs to no bundle and combines freely with every other signal, including navigation and nav_direction. Requires firmware 6.0.12.11 and above.",
       "navigation and nav_direction are mutually exclusive — never combine them",
       "The imu_biometric bundle (imu_acc + imu_gyro + emg) and navigation are mutually exclusive",
       "The imu_biometric bundle (imu_acc + imu_gyro + emg) and nav_direction are mutually exclusive"
     ],
     "valid_combinations": [
       "gesture + button",
-      "pressure + button",
+      "direct_pressure + button",
+      "pinch_pressure + button",
       "navigation + button",
       "nav_direction",
       "imu_acc + imu_gyro + emg",
       "imu_acc + imu_gyro + emg + gesture",
       "imu_acc + imu_gyro + emg + button",
-      "navigation + button + gesture"
+      "navigation + button + gesture",
+      "imu_quaternion",
+      "imu_quaternion + gesture",
+      "imu_quaternion + button",
+      "imu_quaternion + navigation + button",
+      "imu_quaternion + nav_direction",
+      "imu_quaternion + direct_pressure",
+      "imu_quaternion + imu_acc + imu_gyro + emg"
     ],
     "cannot_combine": [
       {
-        "signals": ["gesture", "pressure"],
+        "signals": ["gesture", "direct_pressure"],
+        "reason": "Mutually exclusive analog vs discrete control — pick one interaction model"
+      },
+      {
+        "signals": ["gesture", "pinch_pressure"],
         "reason": "Mutually exclusive analog vs discrete control — pick one interaction model"
       },
+      {
+        "signals": ["direct_pressure", "pinch_pressure"],
+        "reason": "Mutually exclusive — pick direct_pressure (new continuous stream) or pinch_pressure (original tap-to-release stream)"
+      },
       {
         "signals": ["navigation", "nav_direction"],
         "reason": "Mutually exclusive motion modes — navigation is continuous pointer, nav_direction is discrete swipes"
@@ -400,7 +512,7 @@
         "reason": "The imu_biometric bundle (imu_acc + imu_gyro + emg) is incompatible with nav_direction"
       }
     ],
-    "guidance": "If a user's concept needs both directional movement and orientation/biometrics, explain the conflict and recommend which fits better. If they want any of imu_acc, imu_gyro, or emg, subscribe to all three."
+    "guidance": "If a user's concept needs both directional movement and biometrics, explain the conflict and recommend which fits better. If they want any of imu_acc, imu_gyro, or emg, subscribe to all three. Note that pure orientation is NOT a conflict case any more — if the user only needs to know which way the hand is pointing, use imu_quaternion, which combines with navigation and nav_direction and does not pull in the biometric bundle. imu_quaternion: Requires firmware 6.0.12.11 and above. direct_pressure: Requires firmware 6.0.12.11 and above. pinch_pressure works on older firmware."
   },
   "websocket_api": {
     "url": "ws://127.0.0.1:8766",
@@ -420,10 +532,10 @@
       "unsubscribe": {
         "description": "Stop receiving a signal",
         "format": { "command": "unsubscribe", "signal": "<signal_name>" },
-        "example": { "command": "unsubscribe", "signal": "pressure" }
+        "example": { "command": "unsubscribe", "signal": "direct_pressure" }
       },
       "get_subscriptions": {
-        "description": "Get current subscriptions (8-key boolean map — no battery key)",
+        "description": "Get current subscriptions (10-key boolean map — no battery key)",
         "format": { "command": "get_subscriptions" }
       },
       "get_status": {
@@ -447,7 +559,9 @@
               "emg": "boolean",
               "imu_acc": "boolean",
               "imu_gyro": "boolean",
-              "pressure": "boolean",
+              "imu_quaternion": "boolean",
+              "direct_pressure": "boolean",
+              "pinch_pressure": "boolean",
               "gesture": "boolean",
               "navigation": "boolean",
               "nav_direction": "boolean",
@@ -486,7 +600,7 @@
         "missing_command": "Client JSON has no 'command' field. Never expected.",
         "unknown_command": "Command not in the supported list. Never expected after this update.",
         "missing_signal": "subscribe/unsubscribe without a 'signal' field. Never expected.",
-        "invalid_signal": "subscribe/unsubscribe with an unrecognised signal name. Never expected after this update — do NOT send 'battery'.",
+        "invalid_signal": "subscribe/unsubscribe with an unrecognised signal name. Never expected after this update — do NOT send 'battery', and do NOT send 'pressure' (use 'direct_pressure' or 'pinch_pressure').",
         "client_already_connected": "CRITICAL: Server already has another connected client. Show a terminal 'close the other tab' message. Do NOT retry the connection."
       }
     },
@@ -527,6 +641,26 @@
       "suppressed_when": "client_already_connected error frame received (FR-017 path)"
     },
     "common_mistakes": [
+      {
+        "wrong": "{command: 'subscribe', signal: 'pressure'}",
+        "correct": "Subscribe to 'direct_pressure' (default) or 'pinch_pressure' — never both.",
+        "reason": "'pressure' is the old name for pinch_pressure and is no longer a valid signal. The original tap-to-release stream is pinch_pressure; direct_pressure is a new continuous ungated stream. The server returns error: invalid_signal, and the app silently receives nothing."
+      },
+      {
+        "wrong": "Listening for msg.type === 'pressure'",
+        "correct": "Match the mode you subscribed to: msg.type === 'direct_pressure' or msg.type === 'pinch_pressure'.",
+        "reason": "The frame type mirrors the signal name. A handler keyed on 'pressure' never fires."
+      },
+      {
+        "wrong": "Reading imu_quaternion as msg.data.values[0], [1], [2], [3] — i.e. treating values as one flat quaternion",
+        "correct": "values is a list of samples. Take a sample first: const [w, x, y, z] = msg.data.values.at(-1);",
+        "reason": "imu_quaternion nests one level deeper than imu_acc / imu_gyro. Reading it flat gives you the first component of the first four samples — the norm will not be 1 and the rotation will be nonsense."
+      },
+      {
+        "wrong": "Subscribing to imu_acc + imu_gyro + emg just to get hand orientation",
+        "correct": "Subscribe to imu_quaternion alone.",
+        "reason": "imu_quaternion gives absolute, drift-free orientation without pulling in the biometric bundle — and unlike that bundle, it can coexist with navigation and nav_direction."
+      },
       {
         "wrong": "Subscribing to 'battery': {command: 'subscribe', signal: 'battery'}",
         "correct": "Read device.battery and device.charging from get_status response. Battery is NOT a subscribable signal.",
@@ -583,13 +717,24 @@
       "feedback": "scale pulse (1.0 -> 1.05 -> 1.0) over 150ms"
     },
     "pressure_slider": {
-      "description": "Volume, brush size, zoom",
+      "description": "NEW continuous ungated pressure stream — volume, brush size, zoom. Requires firmware 6.0.12.11 and above.",
+      "signal": "direct_pressure",
       "implementation": [
         "Map normalized (0.0-1.0) to your range",
         "Smooth with rolling average (3-5 samples)",
         "Feedback: continuous bar/arc tracking value"
       ]
     },
+    "pinch_and_squeeze": {
+      "description": "ORIGINAL tap-to-release filtered stream — commit with a pinch, then modulate with force. Works on older firmware.",
+      "signal": "pinch_pressure",
+      "implementation": [
+        "Treat the first non-zero frame as the start of the interaction and latch the target being acted on",
+        "Map normalized (0.0-1.0) to the modulated range while the pinch is held",
+        "Treat the return to ~0 as commit/release — fire the final action there",
+        "Feedback: show the latched target plus a force meter, so the user can see what they grabbed and how hard"
+      ]
+    },
     "directional_control": {
       "description": "Steering, movement, menu navigation",
       "signal": "navigation",
@@ -610,13 +755,26 @@
       ]
     },
     "orientation_control": {
-      "description": "Tilt sensing, hand angle, 3D rotation",
+      "description": "Tilt sensing, hand angle, 3D rotation from raw inertial data",
       "signal": "imu_acc + imu_gyro",
       "implementation": [
         "Use accelerometer for absolute tilt angle",
         "Use gyroscope for rotation speed",
         "Combine both for smooth orientation tracking",
         "Apply low-pass filter to reduce noise"
+      ],
+      "prefer_instead": "If you only need to know where the hand is pointing, use imu_quaternion — it is already fused, drift-free, and does not drag in the biometric bundle."
+    },
+    "hand_orientation_control": {
+      "description": "Absolute hand orientation — aiming, 1:1 model rotation, heading, pose gating. Requires firmware 6.0.12.11 and above.",
+      "signal": "imu_quaternion",
+      "implementation": [
+        "Read the latest sample per frame: const [w, x, y, z] = msg.data.values.at(-1)",
+        "Apply it directly to a 3D object's quaternion — no integration, no drift correction",
+        "Capture a reference quaternion on a tap and show rotation relative to it, so the user can zero the pose wherever is comfortable",
+        "Slerp toward the incoming value (factor ~0.2) rather than snapping, to smooth packet jitter",
+        "For a 2D readout, convert to Euler angles once at the render step — do not store Euler state",
+        "Sanity check during development: w² + x² + y² + z² should be ≈ 1.0"
       ]
     }
   },
@@ -649,7 +807,7 @@
   "code_examples": {
     "javascript": {
       "description": "Basic WebSocket connection and signal handling (new Dart server protocol)",
-      "code": "const ws = new WebSocket('ws://127.0.0.1:8766');\nconst subscriptionRecord = new Set();\nconst backoffSchedule = [1000, 2000, 5000, 10000];\nlet backoffIndex = 0;\nlet suppressReconnect = false;\nlet reconnectTimer = null;\nlet lastBandConnected = false;\n\nfunction subscribe(signal) {\n  subscriptionRecord.add(signal);\n  ws.send(JSON.stringify({ command: 'subscribe', signal }));\n}\n\nfunction connect() {\n  const socket = new WebSocket('ws://127.0.0.1:8766');\n\n  socket.onopen = () => {\n    backoffIndex = 0;\n    socket.send(JSON.stringify({ command: 'get_status' }));\n    subscriptionRecord.forEach(signal => socket.send(JSON.stringify({ command: 'subscribe', signal })));\n  };\n\n  socket.onmessage = (event) => {\n    const msg = JSON.parse(event.data);\n    if (msg.type === 'status') {\n      const bandConnected = Boolean(msg.data.device.firmware && msg.data.device.serial_number);\n      const hand = bandConnected ? msg.data.device.hand : 'None';\n      updateConnectionLabel(bandConnected, hand);\n      if (bandConnected && !lastBandConnected) {\n        // Band just reconnected — replay subscriptions (FR-018a)\n        subscriptionRecord.forEach(signal => socket.send(JSON.stringify({ command: 'subscribe', signal })));\n      }\n      lastBandConnected = bandConnected;\n    }\n    if (msg.type === 'error' && msg.data.error === 'client_already_connected') {\n      suppressReconnect = true;\n      showAlreadyInUseMessage();\n    }\n    if (msg.type === 'gesture') handleGesture(msg.data);\n    if (msg.type === 'pressure') handlePressure(msg.data);\n    if (msg.type === 'navigation') handleNavigation(msg.data);\n  };\n\n  socket.onclose = () => {\n    if (suppressReconnect) return;\n    showReconnecting();\n    const delay = backoffSchedule[Math.min(backoffIndex, backoffSchedule.length - 1)];\n    backoffIndex = Math.min(backoffIndex + 1, backoffSchedule.length - 1);\n    reconnectTimer = setTimeout(connect, delay);\n  };\n}"
+      "code": "const ws = new WebSocket('ws://127.0.0.1:8766');\nconst subscriptionRecord = new Set();\nconst backoffSchedule = [1000, 2000, 5000, 10000];\nlet backoffIndex = 0;\nlet suppressReconnect = false;\nlet reconnectTimer = null;\nlet lastBandConnected = false;\n\nfunction subscribe(signal) {\n  subscriptionRecord.add(signal);\n  ws.send(JSON.stringify({ command: 'subscribe', signal }));\n}\n\nfunction connect() {\n  const socket = new WebSocket('ws://127.0.0.1:8766');\n\n  socket.onopen = () => {\n    backoffIndex = 0;\n    socket.send(JSON.stringify({ command: 'get_status' }));\n    subscriptionRecord.forEach(signal => socket.send(JSON.stringify({ command: 'subscribe', signal })));\n  };\n\n  socket.onmessage = (event) => {\n    const msg = JSON.parse(event.data);\n    if (msg.type === 'status') {\n      const bandConnected = Boolean(msg.data.device.firmware && msg.data.device.serial_number);\n      const hand = bandConnected ? msg.data.device.hand : 'None';\n      updateConnectionLabel(bandConnected, hand);\n      if (bandConnected && !lastBandConnected) {\n        // Band just reconnected — replay subscriptions (FR-018a)\n        subscriptionRecord.forEach(signal => socket.send(JSON.stringify({ command: 'subscribe', signal })));\n      }\n      lastBandConnected = bandConnected;\n    }\n    if (msg.type === 'error' && msg.data.error === 'client_already_connected') {\n      suppressReconnect = true;\n      showAlreadyInUseMessage();\n    }\n    if (msg.type === 'gesture') handleGesture(msg.data);\n    if (msg.type === 'direct_pressure') handlePressure(msg.data);   // or 'pinch_pressure' \u2014 whichever mode you subscribed to\n    if (msg.type === 'navigation') handleNavigation(msg.data);\n    if (msg.type === 'imu_quaternion') {\n      const [w, x, y, z] = msg.data.values.at(-1);   // values is a LIST of [w,x,y,z] samples\n      handleOrientation(w, x, y, z);\n    }\n  };\n\n  socket.onclose = () => {\n    if (suppressReconnect) return;\n    showReconnecting();\n    const delay = backoffSchedule[Math.min(backoffIndex, backoffSchedule.length - 1)];\n    backoffIndex = Math.min(backoffIndex + 1, backoffSchedule.length - 1);\n    reconnectTimer = setTimeout(connect, delay);\n  };\n}"
     },
     "test_gesture": {
       "description": "Simulate a gesture for testing without device",
@@ -666,9 +824,17 @@
       "guidance": "Explain the conflict: navigation and the IMU/EMG bundle (imu_acc + imu_gyro + emg) are mutually exclusive. Recommend the better fit: navigation for directional movement/cursor, IMU+EMG for orientation/biometrics."
     },
     "gesture_pressure_conflict": {
-      "scenario": "User wants both gesture and pressure",
+      "scenario": "User wants both gesture and a pressure signal",
       "guidance": "Explain that gesture and pressure are mutually exclusive. Ask which interaction model fits better: gesture for discrete actions (tap/twist) or pressure for analog control (volume/zoom)."
     },
+    "pressure_mode_choice": {
+      "scenario": "User says 'pressure' without specifying a mode",
+      "guidance": "Default to direct_pressure (new continuous ungated stream) and say so in one clause — do not ask. Requires firmware 6.0.12.11 and above. Switch to pinch_pressure only when the described interaction is explicitly 'pinch/tap first, then squeeze' (grab-and-scale, charge-a-shot, pinch-to-zoom). pinch_pressure is the original tap-to-release stream and works on older firmware. Never subscribe to both."
+    },
+    "orientation_request": {
+      "scenario": "User wants tilt, rotation, aiming, or 'which way my hand is pointing'",
+      "guidance": "Use imu_quaternion. It is absolute, drift-free, needs no sensor fusion on your side, and — unlike the imu_acc + imu_gyro + emg bundle — combines freely with navigation and nav_direction. Requires firmware 6.0.12.11 and above. Reach for the raw IMU bundle only when the user actually wants acceleration, shake detection, or biometrics."
+    },
     "partial_imu_request": {
       "scenario": "User asks for only imu_acc OR only imu_gyro OR only emg",
       "guidance": "Subscribe to all three (imu_acc + imu_gyro + emg) regardless — they form an inseparable bundle. Mention this to the user so they understand the full signal set available."