mudra-skills 1.0.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "mudra",
+  "description": "Claude Code skills for building Mudra Band apps — generate 2D flat/screen apps, 3D/XR experiences, or let the router auto-classify and hand off.",
+  "version": "1.0.0",
+  "author": {
+    "name": "Wearable Devices",
+    "email": "jabbour.d@wearabledevices.co.il"
+  },
+  "homepage": "https://github.com/wearable-devices/mudra-skills",
+  "repository": "https://github.com/wearable-devices/mudra-skills",
+  "license": "MIT",
+  "keywords": [
+    "mudra",
+    "wearable",
+    "gestures",
+    "xr",
+    "webxr"
+  ]
+}

package/CLAUDE.md

@@ -0,0 +1,35 @@
+# Mudra Plugin
+
+This plugin provides skills for generating Mudra Band apps.
+
+Use `/mudra-master` (or just describe an app idea) to build a 2D or 3D/XR app controlled by the Mudra Band wristband.
+
+## Skills
+
+- **mudra-master** — router: classifies prompt as 2D / 3D / ASK / DECLINE, then hands off
+- **mudra-preview** — generates single-file HTML 2D apps
+- **mudra-xr** — generates single-file HTML 3D/XR apps using XR Blocks
+
+## Canonical Nine-Signal Table
+
+| Signal | Type | Use for |
+|---|---|---|
+| `gesture` | discrete | finger pinches (index, middle, ring, little, thumb, grab) |
+| `button` | discrete | hardware button press/release |
+| `pressure` | analog | continuous squeeze force (0–1) |
+| `navigation` | pointer | 2D cursor delta (x, y) — Pointer mode |
+| `nav_direction` | discrete | swipe direction (up/down/left/right) — Direction mode |
+| `imu_acc` | analog | accelerometer (x, y, z) — IMU mode |
+| `imu_gyro` | analog | gyroscope (x, y, z) — IMU mode |
+| `snc` | analog | 3-channel bio signal, batched arrays per channel |
+| `battery` | discrete | battery level |
+
+**Motion-mode exclusivity (non-negotiable):** each app uses exactly one of `navigation` XOR `nav_direction` XOR `imu_acc`+`imu_gyro`. The additive signals (`gesture`, `pressure`, `snc`, `battery`) combine freely with any mode.
+
+## Protocol Rules
+
+- WebSocket at `ws://127.0.0.1:8766`
+- Subscribe one signal per command, key `signal` (singular): `{ "command": "subscribe", "signal": "<name>" }`
+- Never use `signals` (plural) or batch subscribe
+- Always wrap with `MudraWebSocket` class (includes mock fallback)
+- Every app must include: mock fallback, always-visible simulator panel, keyboard shortcuts, connection-status indicator

package/bin/install.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { execSync } from 'child_process';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pluginSrc = path.resolve(__dirname, '..');
+const homeDir = process.env.HOME || process.env.USERPROFILE;
+const target = path.join(homeDir, '.claude', 'plugins', 'mudra');
+
+fs.mkdirSync(target, { recursive: true });
+execSync(`cp -r "${pluginSrc}/." "${target}"`);
+
+console.log('');
+console.log('Mudra skills installed successfully!');
+console.log('');
+console.log('Next steps:');
+console.log('  1. Restart Claude Code, or run /reload-plugins');
+console.log('  2. Use the skills:');
+console.log('     /mudra:mudra-master  — auto-classify and route');
+console.log('     /mudra:mudra-preview — generate 2D app');
+console.log('     /mudra:mudra-xr      — generate 3D/XR app');
+console.log('');
+console.log(`Plugin location: ${target}`);

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "mudra-skills",
+  "version": "1.0.0",
+  "description": "Claude Code skills for building Mudra Band apps — 2D, 3D/XR, or auto-classified",
+  "type": "module",
+  "bin": {
+    "mudra-skills": "bin/install.js"
+  },
+  "author": {
+    "name": "Wearable Devices",
+    "email": "jabbour.d@wearabledevices.co.il"
+  },
+  "homepage": "https://github.com/wearable-devices/mudra-skills",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wearable-devices/mudra-skills.git"
+  },
+  "license": "MIT",
+  "keywords": [
+    "claude-code",
+    "plugin",
+    "mudra",
+    "wearable",
+    "gestures",
+    "xr",
+    "webxr"
+  ]
+}

package/skills/mudra-master/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: mudra-master
+version: 2.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
+
+Route an incoming Mudra-Band app-build prompt to the correct child skill — `mudra-preview` for 2D (flat/screen) apps, `mudra-xr` for 3D/XR/VR/AR apps — with a single disambiguation question only when the dimension is unclear.
+
+This skill emits no app artifacts of its own. Its sole outputs are a routing decision, an optional one-line reasoning note, and at most one invocation of a child skill. Every invocation is ephemeral: no log files, no cached state, no persisted history.
+
+## When this skill activates
+
+Activate when the user:
+
+- Describes something they want to **build / make / create / prototyp e** with the Mudra Band — an app, experience, tool, timer, counter, demo, game, dashboard, visualizer, panel, or scene — AND
+- Has not made clear whether they want a 2D (screen-based) or 3D (spatial / XR / VR / AR) version.
+
+I have 2 sklills and I want to build other skill master that can use both skill, how it can be done ?
+
+
+
+and what the structure should look like ?Prefer letting `mudra-preview` or `mudra-xr` activate directly when Claude Code's skill-discovery heuristic matches a child skill's description confidently on an explicit-dimension prompt. This skill is the router for ambiguous prompts and the safe fallback for explicit-dimension prompts that still reach it.
+
+### The verbatim-prompt rule (FR-012)
+
+At no point may the agent modify, summarise, enrich, rephrase, prefix, suffix, or markdown-wrap the user's prompt. The string received is the exact string passed as `args` to the child skill, trimmed only at its leading and trailing whitespace edges. No "Build a 2D …" rewrites. No context injection. No examples appended.
+
+## Classification algorithm
+
+Evaluate these rules top-to-bottom against the user's trimmed, lowercased prompt. **First match wins.** First-match-wins plus a fixed rule order plus a fixed cue list is what makes this router deterministic (FR-015): the same prompt string always produces the same classification.
+
+Before running any rule: if the trimmed prompt is **empty**, do NOT run the classification rules. Emit exactly `What would you like to build?` and stop the turn. The user's next message is a fresh invocation.
+
+| # | Rule                                                                             | Outcome                                                                                                        |
+| - | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| 1 | Prompt contains BOTH whole-word `2d` AND whole-word `3d`                     | `ASK` (source=`LITERAL`) — never guess when both dimension markers are explicit                           |
+| 2 | Prompt contains whole-word `2d` and NOT whole-word `3d`                      | `TWO_D` (source=`LITERAL`, triggering_token=`2D`)                                                        |
+| 3 | Prompt contains whole-word `3d` and NOT whole-word `2d`                      | `THREE_D` (source=`LITERAL`, triggering_token=`3D`)                                                      |
+| 4 | Prompt matches ≥1 token from the 3D cue list AND ≥1 token from the 2D cue list | `ASK` (source=`CUE`)                                                                                       |
+| 5 | Prompt matches ≥1 token from the 3D cue list and NO token from the 2D cue list  | `THREE_D` (source=`CUE`, triggering_token = the first 3D cue that matched, listed in cue-list order below) |
+| 6 | Prompt matches ≥1 token from the 2D cue list and NO token from the 3D cue list  | `TWO_D` (source=`CUE`, triggering_token = the first 2D cue that matched, listed in cue-list order below)   |
+| 7 | Prompt contains NONE of the in-scope build verbs/nouns listed below              | `DECLINE` (source=`OUT_OF_SCOPE`)                                                                          |
+| 8 | None of the above matched                                                        | `ASK` (source=`LITERAL`) — ambiguous prompt, no cue, no literal marker                                    |
+
+**In-scope build verbs/nouns** (Rule 7 passes if AT LEAST ONE appears in the prompt, case-insensitive, whole-word or contiguous substring):
+
+`build`, `make`, `create`, `prototype`, `generate`, `app`, `experience`, `tool`, `timer`, `counter`, `demo`, `game`, `dashboard`, `visualizer`, `visualiser`, `panel`, `scene`, `widget`, `ui`.
+
+### 3D cue tokens
+
+**Fixed built-in constant. Changing this list requires a new `version` bump in this SKILL.md's frontmatter (FR-018).**
+
+Whole-word match (case-insensitive): `XR`, `VR`, `AR`.
+
+Contiguous-substring match (case-insensitive): `immersive`, `spatial`, `room-scale`, `world-space`, `in 3d space`, `headset`, `stereo`.
+
+Rule-5 evaluation order is the order above: `XR` is checked first, then `VR`, `AR`, `immersive`, `spatial`, `room-scale`, `world-space`, `in 3d space`, `headset`, `stereo`. The first cue that matches is the `triggering_token`, rendered in its display form (uppercase for acronyms; as-listed for the rest).
+
+### 2D cue tokens
+
+**Fixed built-in constant. Changing this list requires a new `version` bump in this SKILL.md's frontmatter (FR-018).**
+
+Whole-word match (case-insensitive): `flat`, `HUD`.
+
+Contiguous-substring match (case-insensitive): `on-screen`, `on my screen`, `dashboard`, `screen-based`.
+
+Rule-6 evaluation order is the order above: `flat` first, then `HUD`, `on-screen`, `on my screen`, `dashboard`, `screen-based`.
+
+## Disambiguation question
+
+When Rule 1, Rule 4, or Rule 8 yields an `ASK` outcome, emit exactly this text and then **stop the turn**. Do NOT call any tool. Do NOT re-state or re-request the prompt. Do NOT ask any follow-up beyond this one question — FR-008 / SC-003 forbid a second question:
+
+```
+Your prompt doesn't specify whether this should be a 2D (flat/screen)
+or 3D (spatial/XR) experience. Which should I build?
+
+A) 2D — screen-based
+B) 3D — spatial/XR
+```
+
+## ASK-reply interpretation
+
+After the disambiguation question has been emitted, the user's next message is their reply. Classify it with these rules (first match wins, against the trimmed, lowercased reply):
+
+| Reply pattern                                                                                                         | Outcome                                                                                               |
+| --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| Contains `2d`, equals `a`, `option a`, `screen`, `flat`, `flat ui`, `screen-based`, or clearly picks 2D | `TWO_D` (source=`ASK_REPLY`)                                                                      |
+| Contains `3d`, equals `b`, `option b`, `spatial`, `xr`, `vr`, `ar`, `immersive`, or clearly picks 3D  | `THREE_D` (source=`ASK_REPLY`)                                                                    |
+| Anything else (`either`, `you pick`, blank, nonsense)                                                             | `TWO_D` (source=`ASK_DEFAULT`) — emit the default-notice reasoning note before hand-off (FR-010) |
+
+Once a reply is classified, route the **original prompt** (the one from before the disambiguation question was asked) — NOT the user's reply text — to the chosen child skill (FR-009).
+
+## Out-of-scope decline
+
+When Rule 7 yields `DECLINE`, emit this template, filling only the `<brief reason>` slot with one short human-readable clause (e.g., `a code-refactoring request`, `a question about this repository`, `a file-listing request`). Do NOT call any tool. Do NOT ask 2D-or-3D (FR-014 / SC-007):
+
+```
+I only dispatch Mudra-controlled 2D or 3D app builds. Your request looks
+like <brief reason>. Try rephrasing as a "build / prototype / make a
+[thing]" request, or invoke the underlying tool directly.
+```
+
+## Hand-off
+
+For every outcome in `{TWO_D, THREE_D}`, emit the appropriate pre-hand-off text (if any) and then issue **exactly one** `Skill` tool call. Between classification and hand-off there must be no other tool calls — no `Write`, no `Bash`, no `Read`, no logging, no file writes, no state (FR-019).
+
+### Pre-hand-off reasoning note, by classification source
+
+| Classification source                 | Reasoning note emitted before the Skill call                     |
+| ------------------------------------- | ---------------------------------------------------------------- |
+| `LITERAL` (Rules 2, 3)              | (none — self-evident from the user's own words)                 |
+| `CUE`, outcome=`THREE_D` (Rule 5) | `Routing to 3D skill — detected '<triggering_token>' cue.`    |
+| `CUE`, outcome=`TWO_D` (Rule 6)   | `Routing to 2D skill — detected '<triggering_token>' cue.`    |
+| `ASK_REPLY`                         | (none — the user just answered; the reasoning is their reply)   |
+| `ASK_DEFAULT`                       | `Defaulting to 2D — your reply didn't clearly pick 2D or 3D.` |
+
+Example for an inferred-3D case, prompt `build me a VR meditation app`: emit `Routing to 3D skill — detected 'VR' cue.` then call the Skill tool. `<triggering_token>` is rendered in display form (acronyms uppercase).
+
+### Skill tool invocation
+
+For `outcome=TWO_D` (any source):
+
+```
+Skill(skill="mudra-preview", args="<original prompt, byte-for-byte verbatim, trimmed only at the edges>")
+```
+
+For `outcome=THREE_D` (any source):
+
+```
+Skill(skill="mudra-xr", args="<original prompt, byte-for-byte verbatim, trimmed only at the edges>")
+```
+
+`args` is the ORIGINAL prompt — not the user's disambiguation reply, not a rewritten version, not a prefixed version. Exactly what the user first typed. Invoke the Skill tool exactly once per routing decision. No retries. No fan-out to both children. No wrapper context in `args`.
+
+## Execution flow (summary)
+
+```
+user prompt
+   │
+   ▼
+[empty?  YES → "What would you like to build?"  | STOP]
+   │ NO
+   ▼
+[Classification rules 1–8, first-match-wins]
+   │
+   ├── TWO_D    → [emit reasoning note if any] → Skill(mudra-preview, args=prompt) → DONE
+   ├── THREE_D  → [emit reasoning note if any] → Skill(mudra-xr,      args=prompt) → DONE
+   ├── DECLINE  → [emit out-of-scope template]                                     → DONE
+   └── ASK      → [emit disambiguation question] → STOP TURN → await user reply
+                     │
+                     ▼
+               [ASK-reply rules]
+                     │
+                     ├── TWO_D  (ASK_REPLY)   → Skill(mudra-preview, args=ORIGINAL prompt) → DONE
+                     ├── TWO_D  (ASK_DEFAULT) → [emit default-notice] → Skill(mudra-preview, args=ORIGINAL prompt) → DONE
+                     └── THREE_D (ASK_REPLY)  → Skill(mudra-xr,      args=ORIGINAL prompt) → DONE
+```
+
+## Onboarding contract — defer to children (feature 008)
+
+The locked onboarding modal contract (DOM, CSS, JS, branding string, close behavior, app-aware filter) is owned by the **child** skills:
+
+- 2D apps → `mudra-preview/references/promt.md` § "Onboarding Modal (mandatory, STRICT) — feature 008-strict-onboarding-templates" — see "Close behavior" subsection
+- 3D apps → `mudra-xr/references/promt.md` § "Section 17" **and** `mudra-xr-2/references/xr_build_rules.md` § "§21" — both encode the same locked contract including the close-behavior table.
+
+Binding contracts live at `specs/008-strict-onboarding-templates/contracts/onboarding-block.md` and `…/actions-array.md`.
+
+The contract guarantees a uniform close model across all routed apps:
+
+- The `<dialog>` is opened via `root.showModal()` on page load (never the HTML `open` attribute — non-modal dialogs let an underlying canvas intercept clicks).
+- Both `Continue` and `×` close the modal via the same `closeOb` handler (no skip-vs-save split).
+- Escape closes; `?` reopens (2D always, 3D outside immersive XR).
+- The help-pill `#mudra-onboarding-help` is the mouse/touch re-open path.
+
+This router MUST NOT:
+
+- Mention the onboarding modal in its prompt-trimming or hand-off logic.
+- Append, prefix, or inject any "include onboarding" / "use template N" / "skip close button" hint to `args`.
+- Suggest a different layout, branding string, CTA label, or close behavior.
+- Override or weaken any rule in the child contract (FR-012, FR-019).
+
+The verbatim-prompt rule above already implies all of this — the router never modifies the user's prompt. This subsection exists to make the deferral explicit so future router edits do not accidentally introduce onboarding rules at the router layer.
+
+## Guarantees (invariants the router must preserve)
+
+1. **Deterministic** — the same prompt string always yields the same classification (FR-015).
+2. **Verbatim hand-off** — `args` is byte-identical to the user's original prompt, trimmed only at the edges (FR-012 / SC-006).
+3. **Exactly one Skill call per routed outcome** — never zero (silent guess), never two (fan-out) (FR-002).
+4. **At most one disambiguation question per turn** — never two (SC-003).
+5. **No persisted state** — no files written, no logs, no caches, no console decision records (FR-019).
+6. **Explicit beats inferred** — literal `2D`/`3D` markers always win over any cue match (FR-016).
+7. **No child-skill modification** — routing never reads or edits anything under `.claude/skills/mudra-preview/` or `.claude/skills/mudra-xr/` (FR-011).
+8. **No onboarding-layer overrides** (feature 008) — router never edits or weakens the locked onboarding contract owned by the child skills.
+
+## Not this skill's job
+
+- Generating HTML files — that's `mudra-preview` (2D) or `mudra-xr` (3D).
+- Selecting templates, inferring motion modes, or wiring Mudra signals — child-skill concerns.
+- Explaining WHY a user should pick 2D vs 3D — the disambiguation question is one line, no advice.
+- Refactoring code, answering repo questions, running shell commands — decline these via Rule 7.
+- Logging, persisting, or summarising routing decisions — explicitly forbidden in v1 (FR-019).

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

@@ -0,0 +1,151 @@
+---
+name: mudra-preview
+version: 2.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, SNC), wants to prototype a Mudra Companion app, or asks to build/preview a Mudra app.
+---
+
+# Mudra Preview
+
+Generate a complete, working single-file HTML app controlled by Mudra Band signals.
+
+**Mandatory feature (v1.1.0, updated v1.4.0):** Every generated app MUST
+include a Manual/Mudra **Mode toggle** as defined in `references/promt.md`
+§ "Mode Toggle (Manual / Mudra) — Required". Manual is the default; Mudra
+opens a single WebSocket lazily and disables the simulator panel so signals
+come only from the band.
+
+**Removed in v1.4.0:** Do **not** render a "Band disconnected" overlay,
+toast, or any other separate disconnect alert. Connection state is
+communicated **only** through the existing connection-status pill (which
+shows "Connecting…" / "Connected" / "Disconnected"). No extra notice,
+no banner, no modal.
+
+**Branding (v1.4.0):** The footer/badge text MUST be exactly
+**"Created by Mudra"** — never "Created with Mudra Studio" or any
+other variant.
+
+**Mandatory feature (v1.2.0):** Connection state MUST reflect the **band**, not
+the WebSocket. The Companion service accepts socket connections even when no
+band is paired, so flipping to "Connected" on `ws.onopen` is a lie. Every
+generated app MUST send `{command:"get_status"}` on open and poll it every
+2 s while in Mudra mode, and only show "Connected" when the response has
+`data.device.state === "connected"`. See `references/promt.md` §
+"Disconnect detection — band state via `get_status` polling (mandatory)".
+
+The canonical protocol is in `references/agent_protocol.json` (v2.0).
+
+## Steps
+
+1. **Read the full instructions** from `references/promt.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).
+
+3. **Select the best-matching template** from `assets/` inside the skill base directory. Use the selection rule from `references/promt.md` (motion mode → interaction pattern → signal overlap).
+
+4. **Generate the app** as a single self-contained HTML file:
+   - Follow every rule in `references/promt.md` (protocol contract, signal compatibility, mock WebSocket, theme, fallbacks)
+   - Choose a color palette that matches the concept — never default to dark unless the concept calls for it
+   - Include the Mudra badge, connection indicator, telemetry HUD, simulator panel (see below), and keyboard fallbacks
+
+### Simulator Panel (Required)
+
+Every generated app MUST include a **compact, always-visible simulator panel** with one button set per subscribed signal. The user must be able to trigger every signal with a click — so they can test without the band, or alongside it.
+
+**Layout rules**
+- One thin horizontal strip (usually in or just below the header, or pinned to the bottom edge).
+- **Always visible** — do NOT hide when the band is connected.
+- Group by signal. Use short labels so it stays compact (e.g., `Tap`, `2Tap`, `Twist`, `↑`, `↓`, `Roll L`).
+- Reuse the existing `.btn` style from the chosen template.
+- No drawers, no collapse, no accordion — one click to fire.
+
+**Buttons per signal** (only render the groups for signals the app actually subscribes to)
+
+| Signal | Buttons |
+|---|---|
+| `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) |
+| `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) |
+| `snc` | `Spike` (injects a burst of elevated samples on all 3 channels) |
+
+**How each button must fire**
+- `gesture` buttons → `ws.send(JSON.stringify({ command: 'trigger_gesture', data: { type: '<name>' } }))`. This works both when connected to the real band (round-trips through the service) and when the mock is active (mock echoes it back).
+- **All other signals** → emit locally by calling the same handler `ws.onmessage` would dispatch. Example:
+  ```js
+  function simDir(direction) {
+    // same path the real signal would take
+    handleNavDirection({ direction, timestamp: Date.now() });
+    hudDir.textContent = direction;
+  }
+  ```
+  Always update the telemetry HUD from the sim button, same as the real signal would.
+
+5. **Save the output** to `preview/<concept-name>.html` in the project root (create the `preview/` directory if it doesn't exist). Use a short kebab-case name derived from the concept (e.g., `preview/drum-machine.html`).
+
+6. **Report the file path** so the user can open it in a browser immediately.
+
+## Default Signal Set (v1.3.0 — Required)
+
+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.
+   - **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").
+     - `tap` → frequent/lightweight: counter increment, navigation step,
+       toggle, next/back, select, trigger. **Default choice.**
+     - `double_tap` → only when the user explicitly requests it by name.
+       Never pair it with `tap` as a default two-action scheme.
+     - Generic synonyms ("tap", "click", "press") → `tap`.
+     - When an app needs **two distinct gesture actions** (e.g., forward +
+       backward), pair `tap` with `twist` — not with `double_tap`.
+       `double_tap` is reserved for explicit user requests only.
+2. **One** directional signal — either `nav_direction` **or**
+   `navigation`, never both.
+
+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
+  interaction model per app. Tap/twist concepts → `gesture`. Analog
+  concepts (volume, brush, throttle) → `pressure`.
+- `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
+  both into the same app.
+- **IMU+Biometric bundle (`imu_acc` + `imu_gyro` + `snc`) is
+  inseparable.** If the concept needs any one of them, subscribe to all
+  three. The bundle is **mutually exclusive** with `navigation` and
+  `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`, `snc`, `battery`) are
+  **off by default**. Only include them when the user's prompt names
+  them, names a synonym from the Signal Inference table in
+  `references/promt.md` § "Signal Inference Reference", or describes
+  an interaction that genuinely cannot be expressed with the defaults
+  (e.g., "tilt to steer" → IMU+Biometric bundle; "hold to charge" →
+  `button`).
+- The simulator panel must mirror whichever subset the app actually
+  subscribes to — do not render buttons for signals that are not wired.
+
+## Quick Reference
+
+- WebSocket endpoint: `ws://127.0.0.1:8766` (bare URL — NOT `/events`)
+- Mode toggle (Manual / Mudra) is **mandatory** in every generated app — see `references/promt.md` § "Mode Toggle (Manual / Mudra) — Required"
+- Lazy WS lifecycle: open on Manual→Mudra, close on Mudra→Manual. Manual mode opens NO WebSocket.
+- 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`+`snc`, always all three together)
+- IMU+Biometric bundle: `imu_acc`, `imu_gyro`, `snc` 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` and `battery` combine freely (subject to the Pointer 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/promt.md` § "Navigation sensitivity defaults".
+- Canonical protocol JSON: `references/agent_protocol.json` (v2.0)