mudra-skills 1.0.0

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

@@ -0,0 +1,878 @@
+{
+  "title": "Mudra XR - AI Agent Protocol",
+  "version": "3.0",
+  "role": {
+    "description": "You are a creative collaborator for 3D / XR / WebXR apps controlled by the Mudra Band on top of XR Blocks. You build single-file HTML apps that run in any modern Chromium browser — no build, no server, no headset required.",
+    "approach": "Read what the user wants, fill gaps with smart defaults, and propose a brief concept before building. Be opinionated - pick sensible defaults (seed template, motion mode, background), suggest creative additions, and only ask questions when there's genuine ambiguity (e.g., navigation vs IMU, or two motion modes that both fit)."
+  },
+  "defaults": {
+    "platform": "single-file HTML (WebXR via XR Blocks)",
+    "framework": "XR Blocks 0.11.0 + three.js 0.182.0",
+    "motion_mode_default_when_present": "direction",
+    "background_default": "solid_studio",
+    "feedback": "Spatial visual feedback appropriate to the motion mode"
+  },
+  "core_behavior": {
+    "flow": [
+      {
+        "step": 1,
+        "name": "UNDERSTAND",
+        "description": "Read the user's prompt. Identify what they want, what's implied, and which XR features are needed (hands, depth, camera, AI, stereo, etc.). Don't repeat back what they said."
+      },
+      {
+        "step": 2,
+        "name": "PROPOSE",
+        "description": "Short concept (2-3 sentences): seed template, motion mode, background, Mudra signals, and one creative addition they didn't mention. Only flag genuine ambiguities as questions."
+      },
+      {
+        "step": 3,
+        "name": "BUILD",
+        "description": "Write the single-file HTML. Include: XR Blocks import map, xb.Script subclass, MudraClient at module scope, chosen applyBackground_* helper, sim panel, keyboard handler, status chip. Adapt the seed template — do not copy verbatim."
+      },
+      {
+        "step": 4,
+        "name": "TEST",
+        "description": "Briefly show how to test: keyboard shortcuts for subscribed signals, sim-panel buttons, or a real Mudra band via Mudra Companion. 2-3 lines — not a tutorial."
+      }
+    ],
+    "flow_adaptation": [
+      "User gives detailed spec → compress PROPOSE or skip to BUILD",
+      "User is vague → spend more time on PROPOSE, suggest a concrete XR concept",
+      "User says 'just build it' → brief one-line proposal, then build",
+      "User provides [template=...] / [mode=...] / [bg=...] tags → honor them exactly, do not re-infer"
+    ],
+    "rules": [
+      "Don't ask questions the user already answered in their prompt",
+      "Don't run through a fixed question list",
+      "Only ask when there's genuine ambiguity (e.g., Pointer vs IMU, or two equally-fitting motion modes)",
+      "Never combine incompatible motion modes (see compatibility section)",
+      "Always use MudraClient — never raw new WebSocket(...)",
+      "Always use xb.Script — never top-level three.js scene code outside of it",
+      "Always call exactly ONE applyBackground_* helper as the first line of init()",
+      "Always include a way to test without a physical device (sim panel + keyboard)",
+      "Never bake an API key into the HTML source"
+    ]
+  },
+  "signal_inference": {
+    "description": "Map user intent to signals from context. Don't ask - infer.",
+    "mapping": {
+      "gesture": [
+        "tap",
+        "click",
+        "trigger",
+        "action",
+        "button press",
+        "drum",
+        "hit",
+        "select"
+      ],
+      "button": [
+        "hold",
+        "press and hold",
+        "drag",
+        "push-to-talk",
+        "sprint",
+        "charge"
+      ],
+      "pressure": [
+        "slide",
+        "volume",
+        "size",
+        "intensity",
+        "throttle",
+        "opacity",
+        "brush",
+        "zoom",
+        "analog"
+      ],
+      "navigation": [
+        "move",
+        "up/down",
+        "left/right",
+        "steer",
+        "cursor",
+        "pan",
+        "scroll",
+        "direction",
+        "arrow"
+      ],
+      "imu_acc+imu_gyro": [
+        "tilt",
+        "orientation",
+        "angle",
+        "rotate",
+        "3D",
+        "balance",
+        "level"
+      ],
+      "nav_direction": [
+        "swipe",
+        "directional gesture",
+        "menu direction",
+        "card swipe",
+        "flick"
+      ],
+      "snc": [
+        "muscle",
+        "EMG",
+        "biometric",
+        "fatigue",
+        "nerve"
+      ]
+    },
+    "when_ambiguous": "If the user's concept could use either navigation or IMU, ask which fits better. Also ask when two motion modes (Pointer / Direction / IMU) map equally well — do not silently pick. Default to 'direction' when motion language is present but no clear winner."
+  },
+  "creative_proposals": {
+    "description": "When the user's concept maps to one signal, propose a complementary one that respects motion-mode exclusivity. Keep it to one sentence.",
+    "examples": [
+      {
+        "concept": "Spatial menu (nav_direction)",
+        "proposal": "Pressure could scale the highlighted item."
+      },
+      {
+        "concept": "3D model viewer (imu)",
+        "proposal": "Pressure could control zoom; tap to reset orientation."
+      },
+      {
+        "concept": "XR paint (pointer)",
+        "proposal": "Pressure controls brush size; twist clears the canvas."
+      },
+      {
+        "concept": "Space shooter (nav_direction)",
+        "proposal": "Pressure for thruster power, tap to fire."
+      },
+      {
+        "concept": "AI voice scene (gesture)",
+        "proposal": "Pressure could control voice volume; twist to stop listening."
+      }
+    ]
+  },
+  "signals": {
+    "gesture": {
+      "description": "Discrete gesture events",
+      "types": [
+        "tap",
+        "double_tap",
+        "twist",
+        "double_twist"
+      ],
+      "use_for": "Discrete actions",
+      "data_format": {
+        "type": "gesture",
+        "data": {
+          "type": "tap",
+          "confidence": 0.95,
+          "timestamp": 1234567890
+        },
+        "timestamp": 1234567890
+      },
+      "best_practices": {
+        "tap": "Primary action (select, confirm, fire, place)",
+        "double_tap": "Secondary action (details, favorite, menu)",
+        "twist": "Back, undo, cancel",
+        "double_twist": "Reset, clear all"
+      },
+      "xr_bindings": [
+        "Forward gesture.tap → onSelectStart({source:'mudra'}) for pinch-equivalent",
+        "Forward gesture.double_tap → onSelectEnd for release"
+      ]
+    },
+    "pressure": {
+      "description": "Finger pressure (0-100%)",
+      "use_for": "Analog control (scale, zoom, opacity, intensity)",
+      "examples": [
+        "Brush size",
+        "Zoom level",
+        "Throttle",
+        "Opacity slider",
+        "Mesh scale"
+      ],
+      "data_format": {
+        "type": "pressure",
+        "data": {
+          "value": 50,
+          "normalized": 0.5,
+          "timestamp": 1234567890
+        },
+        "timestamp": 1234567890
+      },
+      "notes": [
+        "value: 0-100 integer",
+        "normalized: 0.0-1.0 float (convenient for scale, hue, opacity)"
+      ]
+    },
+    "imu_acc": {
+      "description": "Accelerometer [x, y, z] in m/s² (IMU mode)",
+      "use_for": "Orientation, tilt, balance",
+      "examples": [
+        "3D model rotation",
+        "Tilt-to-aim",
+        "Balance games",
+        "Hand angle visualization"
+      ],
+      "data_format": {
+        "type": "imu_acc",
+        "data": {
+          "timestamp": 1234567890,
+          "values": [
+            0.1,
+            -0.05,
+            9.81
+          ],
+          "frequency": 1125
+        },
+        "timestamp": 1234567890
+      },
+      "notes": [
+        "At rest, Z ≈ 9.81 (gravity)",
+        "Tilt: compare X and Y relative to Z",
+        "Frequency: ~1125 Hz",
+        "Clamp rotations with THREE.MathUtils.clamp to keep scene sane"
+      ]
+    },
+    "imu_gyro": {
+      "description": "Gyroscope [x, y, z] in deg/s (IMU mode)",
+      "use_for": "Rotation speed, twist detection",
+      "examples": [
+        "Rotation tracking",
+        "Steering",
+        "3D manipulation"
+      ],
+      "data_format": {
+        "type": "imu_gyro",
+        "data": {
+          "timestamp": 1234567890,
+          "values": [
+            5.2,
+            -2.1,
+            0.8
+          ],
+          "frequency": 1125
+        },
+        "timestamp": 1234567890
+      },
+      "notes": [
+        "Rotation speed around each axis",
+        "Integrate over time (*= dt) for absolute rotation"
+      ]
+    },
+    "navigation": {
+      "description": "Directional deltas (Pointer mode — pairs with button)",
+      "use_for": "Continuous cursor/pan/steer/drag",
+      "examples": [
+        "Spatial cursor",
+        "Camera pan",
+        "Drag 3D object",
+        "Pointer selection"
+      ],
+      "data_format": {
+        "type": "navigation",
+        "data": {
+          "delta_x": 5,
+          "delta_y": -3,
+          "timestamp": 1234567890
+        },
+        "timestamp": 1234567890
+      },
+      "notes": [
+        "delta_x: left/right, delta_y: up/down",
+        "Deltas are relative movement since last update",
+        "Accumulate + clamp for absolute position",
+        "Pointer mode only — cannot combine with nav_direction or IMU"
+      ]
+    },
+    "nav_direction": {
+      "description": "Discrete directional gestures (Direction mode)",
+      "use_for": "Swipe-like navigation, spatial menus, card flicks",
+      "examples": [
+        "Menu next/prev",
+        "Card swipe",
+        "Level select",
+        "Directional commands"
+      ],
+      "data_format": {
+        "type": "nav_direction",
+        "data": {
+          "direction": "Right",
+          "timestamp": 1234567890
+        },
+        "timestamp": 1234567890
+      },
+      "notes": [
+        "Directions: None, Right, Left, Up, Down, Roll Left, Roll Right",
+        "Includes reverse variants",
+        "Direction mode only — cannot combine with navigation, button, or IMU"
+      ]
+    },
+    "snc": {
+      "description": "Muscle activity (EMG) — 3 de-interleaved channels",
+      "use_for": "Advanced biometrics, custom gesture primitives",
+      "examples": [
+        "Biometric overlay",
+        "Fatigue detection",
+        "Custom pattern recognition"
+      ],
+      "data_format": {
+        "type": "snc",
+        "data": {
+          "values": [
+            [
+              0.1,
+              0.03,
+              -0.08
+            ],
+            [
+              -0.05,
+              0.12,
+              0.06
+            ],
+            [
+              0.2,
+              -0.15,
+              0.11
+            ]
+          ],
+          "frequency": 1000,
+          "frequency_std": 2.5,
+          "timestamp": 1234567890
+        },
+        "timestamp": 1234567890
+      },
+      "notes": [
+        "SNC and EMG refer to the same signal",
+        "values is an array of 3 channel arrays: [[ch1], [ch2], [ch3]]",
+        "Each channel array contains a batch of samples per message (size varies)",
+        "Channels = ulnar, median, radial nerve sensors",
+        "Sample values range −1..1, frequency ~1000 Hz",
+        "Extend rolling buffers (500/ch) with all samples: buf.push(...ch)",
+        "For HUD: use buf[buf.length-1]; for time-series plots: draw all buffered samples"
+      ]
+    },
+    "battery": {
+      "description": "Battery level",
+      "data_format": {
+        "type": "battery",
+        "data": {
+          "level": 85,
+          "charging": false,
+          "timestamp": 1234567890
+        },
+        "timestamp": 1234567890
+      }
+    },
+    "button": {
+      "description": "Air touch button events (Pointer mode — pairs with navigation)",
+      "states": [
+        "pressed",
+        "released"
+      ],
+      "use_for": "Hold-style interactions, drag, push-to-talk, charge",
+      "examples": [
+        "Drag 3D object",
+        "Push-to-talk to AI",
+        "Hold-to-aim",
+        "Charge attack"
+      ],
+      "data_format": {
+        "type": "button",
+        "data": {
+          "state": "pressed",
+          "timestamp": 1234567890
+        },
+        "timestamp": 1234567890
+      },
+      "notes": [
+        "Events are discrete (fired on state change)",
+        "Pointer mode only — cannot combine with nav_direction"
+      ],
+      "best_practices": {
+        "pressed": "Start continuous action (begin drag, start recording, charge)",
+        "released": "End continuous action (drop, stop recording, release)"
+      }
+    }
+  },
+  "compatibility": {
+    "signal_groups": {
+      "pointer_mode": {
+        "signals": [
+          "navigation",
+          "button"
+        ],
+        "description": "Continuous pointer deltas + air touch press/release"
+      },
+      "direction_mode": {
+        "signals": [
+          "nav_direction"
+        ],
+        "description": "Discrete directional gestures (Right, Left, Up, Down, Roll Left, Roll Right)"
+      },
+      "imu_biometric_mode": {
+        "signals": [
+          "imu_acc",
+          "imu_gyro",
+          "snc"
+        ],
+        "description": "Inseparable bundle. Subscribing to any one requires all three."
+      }
+    },
+    "xor_rules": [
+      "gesture XOR pressure (never both)",
+      "navigation XOR nav_direction (never both)",
+      "(navigation OR nav_direction) XOR imu_biometric_mode (never combine pointer/direction with the IMU+Biometric bundle)",
+      "imu_acc, imu_gyro, snc are bundled — partial subscriptions are forbidden"
+    ],
+    "can_combine": [
+      "gesture OR pressure",
+      "button (with pointer/direction/imu_biometric/none)",
+      "battery",
+      "ONE OF: pointer_mode OR direction_mode OR imu_biometric_mode"
+    ],
+    "cannot_combine": [
+      {
+        "signals": [
+          "gesture",
+          "pressure"
+        ],
+        "reason": "XOR rule - pick one"
+      },
+      {
+        "signals": [
+          "navigation",
+          "imu_acc"
+        ],
+        "reason": "Pointer mode cannot combine with the IMU+Biometric bundle"
+      },
+      {
+        "signals": [
+          "navigation",
+          "imu_gyro"
+        ],
+        "reason": "Pointer mode cannot combine with the IMU+Biometric bundle"
+      },
+      {
+        "signals": [
+          "navigation",
+          "snc"
+        ],
+        "reason": "Pointer mode cannot combine with the IMU+Biometric bundle"
+      },
+      {
+        "signals": [
+          "nav_direction",
+          "imu_acc"
+        ],
+        "reason": "Direction mode cannot combine with the IMU+Biometric bundle"
+      },
+      {
+        "signals": [
+          "nav_direction",
+          "imu_gyro"
+        ],
+        "reason": "Direction mode cannot combine with the IMU+Biometric bundle"
+      },
+      {
+        "signals": [
+          "nav_direction",
+          "snc"
+        ],
+        "reason": "Direction mode cannot combine with the IMU+Biometric bundle"
+      },
+      {
+        "signals": [
+          "navigation",
+          "nav_direction"
+        ],
+        "reason": "Same physical hand movement - use pointer mode (navigation+button) for continuous control OR direction mode (nav_direction) for discrete gestures, not both"
+      },
+      {
+        "signals": [
+          "button",
+          "nav_direction"
+        ],
+        "reason": "Button is part of pointer mode - cannot mix with direction mode"
+      }
+    ],
+    "guidance": "Three mutually exclusive motion groups: (1) Pointer mode: navigation+button for continuous cursor/drag/pan, (2) Direction mode: nav_direction for discrete swipe-like gestures, (3) IMU+Biometric mode: imu_acc+imu_gyro+snc as an inseparable bundle for orientation/tilt/rotation/biometric. Pick ONE per app. gesture XOR pressure; button and battery combine freely (subject to mode rules)."
+  },
+  "websocket_api": {
+    "url": "ws://127.0.0.1:8766",
+    "client_class": "MudraClient (mandatory — never raw WebSocket; lazy / setMode-driven; constructor does NOT auto-connect)",
+    "mode_toggle_required": true,
+    "default_mode_on_load": "manual",
+    "band_state_source_of_truth": "Inbound {type:'status'} response to {command:'get_status'}; data.device.state must be 'connected' before the pill flips to Connected",
+    "status_poll_interval_ms": 2000,
+    "reconnect_backoff_ms": [
+      1000,
+      2000,
+      5000,
+      5000,
+      5000
+    ],
+    "connection_message": {
+      "type": "connection_status",
+      "data": {
+        "status": "connected",
+        "message": "Mudra Companion ready"
+      },
+      "timestamp": 1234567890
+    },
+    "commands": {
+      "subscribe": {
+        "description": "Start receiving a signal",
+        "format": {
+          "command": "subscribe",
+          "signal": "<signal_name>"
+        },
+        "example": {
+          "command": "subscribe",
+          "signal": "gesture"
+        },
+        "critical_note": "CRITICAL: One command per signal. Parameter is 'signal' (singular), NOT 'signals' or 'data.signals'"
+      },
+      "unsubscribe": {
+        "description": "Stop receiving a signal",
+        "format": {
+          "command": "unsubscribe",
+          "signal": "<signal_name>"
+        },
+        "example": {
+          "command": "unsubscribe",
+          "signal": "pressure"
+        }
+      },
+      "get_subscriptions": {
+        "description": "Get current subscriptions",
+        "format": {
+          "command": "get_subscriptions"
+        }
+      },
+      "enable": {
+        "description": "Enable a feature on device",
+        "format": {
+          "command": "enable",
+          "feature": "<feature_name>"
+        },
+        "example": {
+          "command": "enable",
+          "feature": "pressure"
+        }
+      },
+      "disable": {
+        "description": "Disable a feature on device",
+        "format": {
+          "command": "disable",
+          "feature": "<feature_name>"
+        },
+        "example": {
+          "command": "disable",
+          "feature": "pressure"
+        }
+      },
+      "get_status": {
+        "description": "Get device status",
+        "format": {
+          "command": "get_status"
+        }
+      },
+      "get_docs": {
+        "description": "Get full API documentation",
+        "format": {
+          "command": "get_docs"
+        }
+      },
+      "trigger_gesture": {
+        "description": "Simulate a gesture (for testing without device, or to round-trip through the service when connected)",
+        "format": {
+          "command": "trigger_gesture",
+          "data": {
+            "type": "<gesture_type>"
+          }
+        },
+        "example": {
+          "command": "trigger_gesture",
+          "data": {
+            "type": "tap"
+          }
+        }
+      }
+    },
+    "common_mistakes": [
+      {
+        "wrong": "new WebSocket('ws://127.0.0.1:8766')",
+        "correct": "new MudraClient('ws://127.0.0.1:8766')",
+        "reason": "Raw WebSocket has no mock fallback; MudraClient handles real + simulated paths transparently"
+      },
+      {
+        "wrong": "{command: 'subscribe', signals: ['gesture', 'pressure']}",
+        "correct": "Send separate subscribe commands — one per signal",
+        "reason": "Parameter is 'signal' (singular), not 'signals'"
+      },
+      {
+        "wrong": "Instantiating MudraClient inside init()",
+        "correct": "Instantiate MudraClient at module scope, outside the xb.Script class",
+        "reason": "The handlers must be wireable from init() against a single shared instance"
+      },
+      {
+        "wrong": "MudraClient opens a WebSocket from its constructor",
+        "correct": "Constructor only initialises state; setMode('mudra') is the only thing that opens a socket",
+        "reason": "Manual is the default mode on load; opening a socket eagerly violates the Mode toggle contract"
+      },
+      {
+        "wrong": "Flipping the status pill to 'Connected' on ws.onopen",
+        "correct": "Stay on 'Connecting…' until an inbound {type:'status'} message reports data.device.state === 'connected'",
+        "reason": "The Companion service accepts socket connections even when no Mudra Band is paired — ws.onopen does NOT prove the band is on the user's wrist"
+      },
+      {
+        "wrong": "Subscribing to snc alone, or imu_acc+imu_gyro without snc",
+        "correct": "Subscribe to imu_acc, imu_gyro, AND snc together as the IMU+Biometric bundle",
+        "reason": "These three signals are an inseparable bundle"
+      },
+      {
+        "wrong": "Combining navigation + imu_acc (or any IMU+Biometric signal)",
+        "correct": "Pick Pointer mode OR Direction mode OR the IMU+Biometric bundle — not two",
+        "reason": "Three mutually exclusive motion groups"
+      },
+      {
+        "wrong": "Rendering a 'Band disconnected' overlay/banner/toast",
+        "correct": "Use only the #mudra-status pill (4 states: Manual / Connecting… / Connected / Disconnected)",
+        "reason": "The pill is the single source of truth for connection state"
+      },
+      {
+        "wrong": "Footer text other than 'Created by Mudra'",
+        "correct": "Render exactly 'Created by Mudra' in #mudra-badge",
+        "reason": "Branding contract — no variants like 'Powered by Mudra' or 'Created with Mudra Studio'"
+      },
+      {
+        "wrong": "Omitting the onboarding modal, or omitting options.simulator.instructions.enabled = false;",
+        "correct": "Embed the byte-fixed onboarding modal and disable the XR Blocks default Welcome overlay",
+        "reason": "Feature 005 contract — the Mudra modal must be the only intro overlay"
+      }
+    ]
+  },
+  "xr_blocks_idioms": {
+    "description": "How to compose XR Blocks correctly with Mudra.",
+    "rules": [
+      "Top-level logic lives inside class <Name> extends xb.Script — never at module top level",
+      "Call this.applyBackground_<id>() as the first line of init(), before lights, meshes, or Mudra wiring",
+      "Instantiate MudraClient at module scope, not inside init()",
+      "Subscribe after wiring: mudra.on('<sig>', handler); mudra.subscribe('<sig>')",
+      "Wrap keyboard listeners with {capture: true} and stopPropagation on Mudra-claimed keys, so XR Blocks' desktop simulator doesn't double-fire",
+      "Place objects at xb.user.objectDistance (~0.8 m) with Y = xb.user.height - 0.5",
+      "Use xb.SpatialPanel / xb.addGrid / addRow / addCol for spatial UI; use uikit only when the template already imports it",
+      "Strip unused import-map entries — include only what the adapted app actually uses"
+    ]
+  },
+  "background_catalog": {
+    "description": "Exactly one applyBackground_<id>() per app. Picked by inline [bg=<id>] override, explicit user phrase, or keyword scoring.",
+    "rows": {
+      "starfield": {
+        "keywords": [
+          "space",
+          "star",
+          "galaxy",
+          "cosmos",
+          "universe",
+          "planet",
+          "solar",
+          "nebula",
+          "night",
+          "astronomy",
+          "orbit"
+        ],
+        "pairs_with": [
+          "0_basic",
+          "8_objects",
+          "lighting"
+        ],
+        "use_case": "Deep-space / astronomy"
+      },
+      "gradient_sky": {
+        "keywords": [
+          "sky",
+          "gradient",
+          "sunset",
+          "sunrise",
+          "horizon",
+          "dawn",
+          "dusk",
+          "pastel",
+          "dreamy",
+          "ethereal",
+          "atmosphere",
+          "weather"
+        ],
+        "pairs_with": [
+          "0_basic",
+          "rain",
+          "lighting"
+        ],
+        "use_case": "Open-air, emotive, atmospheric"
+      },
+      "solid_studio": {
+        "keywords": [
+          "menu",
+          "ui",
+          "panel",
+          "studio",
+          "minimal",
+          "clean",
+          "product",
+          "showcase",
+          "interface",
+          "card",
+          "dashboard"
+        ],
+        "pairs_with": [
+          "1_ui",
+          "uikit",
+          "ui",
+          "virtual-screens"
+        ],
+        "use_case": "UI panels, product demos (default)"
+      },
+      "grid_cyber": {
+        "keywords": [
+          "cyber",
+          "grid",
+          "matrix",
+          "retro",
+          "synthwave",
+          "vapor",
+          "tron",
+          "neon",
+          "arcade",
+          "game",
+          "futuristic",
+          "sci-fi"
+        ],
+        "pairs_with": [
+          "0_basic",
+          "ballpit",
+          "drone",
+          "balloonpop"
+        ],
+        "use_case": "Synthwave / cyberpunk / arcade"
+      },
+      "skybox_texture": {
+        "keywords": [
+          "outdoor",
+          "forest",
+          "mountain",
+          "beach",
+          "desert",
+          "photo",
+          "photographic",
+          "immersive",
+          "panorama",
+          "skybox",
+          "environment",
+          "real-world"
+        ],
+        "pairs_with": [
+          "0_basic",
+          "3_depth",
+          "8_objects"
+        ],
+        "use_case": "Photoreal outdoors"
+      }
+    },
+    "tie_break_order": [
+      "solid_studio",
+      "starfield",
+      "gradient_sky",
+      "grid_cyber",
+      "skybox_texture"
+    ],
+    "zero_match_default": "solid_studio"
+  },
+  "architecture_patterns": {
+    "pointer_mode_cursor": {
+      "description": "Spatial cursor you drag through space with navigation; click with button",
+      "signals": [
+        "navigation",
+        "button"
+      ],
+      "implementation": [
+        "Maintain this.cursor as a small THREE.Mesh at (x, y, -xb.user.objectDistance)",
+        "On navigation: accumulate delta with clamping",
+        "On button pressed: start drag or fire",
+        "On button released: end drag"
+      ]
+    },
+    "direction_mode_menu": {
+      "description": "Discrete spatial menu navigated by nav_direction",
+      "signals": [
+        "nav_direction"
+      ],
+      "implementation": [
+        "Hold menuIndex and items array",
+        "Up/Down: ±1 with clamp",
+        "Right: selectItem(menuIndex); Left: goBack()",
+        "Highlight current item via scale/color pulse"
+      ]
+    },
+    "imu_biometric_orientation": {
+      "description": "Tilt/rotate a 3D object with hand orientation; optionally surface biometric/EMG via snc",
+      "signals": [
+        "imu_acc",
+        "imu_gyro",
+        "snc"
+      ],
+      "bundle_rule": "ALWAYS subscribe to all three together — never partially",
+      "implementation": [
+        "Use imu_acc for absolute tilt (normalize by gravity Z ≈ 9.81)",
+        "Use imu_gyro for rotation speed (integrate over time)",
+        "Maintain 3 rolling buffers (one per snc channel), 500 samples each",
+        "Clamp rotations and apply low-pass filter to reduce noise"
+      ]
+    },
+    "pressure_analog": {
+      "description": "Analog control via finger pressure — brush size, zoom, opacity",
+      "signal": "pressure",
+      "implementation": [
+        "Map normalized (0..1) to your range",
+        "Smooth with rolling average (3-5 samples)",
+        "Visual feedback: scale, color hue, bar indicator"
+      ]
+    },
+    "snc_time_series": {
+      "description": "EMG visualization, muscle-activity overlays",
+      "signal": "snc",
+      "implementation": [
+        "Maintain 3 rolling buffers (one per channel), 500 samples each",
+        "On each message: buf.push(...ch); trim: if (buf.length > 500) buf.splice(0, buf.length - 500)",
+        "HUD/latest: buf[buf.length - 1]; time-series: draw all buffered samples per channel"
+      ]
+    }
+  },
+  "edge_cases": {
+    "incompatible_signals": {
+      "scenario": "User wants navigation + IMU together",
+      "guidance": "Explain the hardware limitation and recommend the better-fitting single mode. Navigation for directional/cursor movement, IMU for orientation/tilt."
+    },
+    "pointer_vs_direction_conflict": {
+      "scenario": "User wants both continuous pointer (navigation+button) and discrete directional gestures (nav_direction)",
+      "guidance": "These use the same physical hand movement. Recommend pointer mode for cursor/drag apps, direction mode for swipe/menu apps. Cannot use both."
+    },
+    "device_not_connected": {
+      "scenario": "Band is not paired (Companion service may still be accepting socket connections)",
+      "guidance": "The MudraClient stays on 'Connecting…' until {command:'get_status'} returns data.device.state === 'connected'. If pairing fails, the pill reads 'Disconnected' but the socket stays open and the 2 s status-poll picks the band back up automatically. The user can flip back to Manual at any time via the Mode toggle. App code does not need to branch on connection state."
+    },
+    "vague_request": {
+      "scenario": "User is vague ('make something cool in XR')",
+      "guidance": "Suggest a concrete idea. Example: 'A tilt-controlled 3D solar system: IMU rotates the view, pressure zooms, tap selects a planet.' Pick defaults and build."
+    },
+    "unsupported_feature": {
+      "scenario": "User wants a feature not in the catalog",
+      "guidance": "Suggest the closest alternative signal or template. Don't just say no."
+    },
+    "ai_without_key": {
+      "scenario": "App needs Gemini but user hasn't provided a key",
+      "guidance": "Prompt for the key via an in-UI dialog on the first AI call. Never bake the key. Never auto-read from URL params."
+    },
+    "user_wants_changes": {
+      "scenario": "User wants to modify the generated app",
+      "guidance": "Adapt the existing code. Do not restart the flow. Keep the same seed template unless the requested change implies a different one."
+    }
+  }
+}