@h2loop/uav 1.0.0

package/.hydron-plugin/plugin.json

@@ -0,0 +1,3 @@
+{
+  "engines": { "hydron": "^1.0.0" }
+}

package/README.md

@@ -0,0 +1,281 @@
+# @h2loop/uav — Hydron UAV Domain Pack
+
+ArduPilot/PX4 flight-log intelligence for [Hydron](../hydron-cli): decode a `.bin`, run
+deterministic system checks, persist the observation locally, and compare against the
+airframe's prior flight. Built as an **external Hydron plugin** (no core rebuild).
+
+**→ [USAGE.md](USAGE.md) — install, validate, and everyday use** (start here). Also:
+[CHANGELOG.md](CHANGELOG.md) · [PACKAGING.md](PACKAGING.md) (distribution/IP).
+
+Design docs: `internal-docs/wiki/engineering/features/domain-plugins/uav/`.
+
+## Status
+
+This cycle = **P1 + P1b + P2** (verified against the real sample log `17-03-2026 Sortie 4.bin`):
+
+- ✅ **Decode** — pure-TS FMT-driven DataFlash decoder, no runtime deps, validated
+  field-by-field against the 73 oracle CSVs (`src/decode/`). TimeUS kept as `bigint`.
+- ✅ **Decode dual-stack** — TS `.bin`; pymavlink `.tlog`/`.log`; **PX4 `.ulog`** (pyulog).
+  Same `DecodedLog` → the same checks run on PX4.
+- ✅ **Check** — **23 system checks + param audit** over in-memory `bun:sqlite`: power
+  (cell-V, sag, current, internal-resistance, brownout), control (attitude, rate-tracking,
+  hover, rcou/rcin, thrust-margin), sensors (vibration **+ alignment/degradation classifier**,
+  imu, mag/offsets, gps, **EKF/EKF2 velocity+position innovations**, variance), ESC, and
+  ERR/MODE event findings. Deterministic; missing tables → `SKIP`.
+- ✅ **Param audit + grounding** — safety/range/consistency over PARM, ranges grounded in
+  ArduPilot's **`apm.pdef.xml`** metadata (3419 params bundled; KG path for online).
+- ✅ **Tuning (USP)** — `uav_tune`: FFT → dominant peak → recommended `INS_HNTCH_*` notch params.
+- ✅ **MAVLink param link** — bridge Tier-C `param_get/set` (gated `--allow-param-write`) for
+  the push + retest loop; flight C2 intentionally absent.
+- ✅ **Persist + run-tracking** — local episode store + keyed diff; `uav_tag` run labels +
+  airframe-profile baseline (`diffAgainstProfile`).
+- ✅ **PlotJuggler handoff** — `uav_export` writes one CSV per message type.
+- ✅ **Control plane** — on-demand `uav` skill + references, the `uav-investigate` /
+  `uav-compare` / `uav-verify` subagents (spawned automatically), `/uav-*` commands, built-in
+  threshold / param-rule defaults (overridable per project via `.hydron/uav-thresholds.yaml` /
+  `param-rules.yaml`), bundled `apm-params.json`. **No dedicated UAV mode** — the domain rides
+  in the normal modes.
+
+## Layout
+
+```
+src/
+  types.ts              # LOCKED shared contracts (DecodedLog, Finding, Report, EpisodeDocument, Thresholds)
+  index.ts              # plugin entry — registers uav_analyze, uav_query, uav_param_audit
+  decode/               # FMT-driven .bin decoder (TS port of split_dataflash_log.py) + tests
+  harness/
+    analyze.ts          # the per-flight pipeline orchestrator
+    loadtables.ts       # DecodedLog -> in-memory SQLite
+    checks.ts           # the 21 system checks + param audit -> Finding[]
+    thresholds.ts       # uav-thresholds.yaml loader (+ built-in v1 defaults)
+    extract.ts          # DecodedLog -> entity/episode/params/events/measurements
+  store/
+    store.ts            # episode JSON + index.jsonl (system of record)
+    diff.ts             # keyed param/finding diff
+script/analyze.ts       # standalone smoke harness (no hydron runtime needed)
+agents/                 # subagents (uav-investigate / uav-compare / uav-verify)
+commands/               # /uav-* slash commands
+skills/uav/             # on-demand `uav` skill + references
+data/                   # bundled apm-params.json + built-in defaults
+bridge/                 # optional MAVLink→MCP Python bridge
+plugins/                # BUILT bundle (index.js + worker/) — generated
+mcp.json                # exa + mavlink MCP servers (disabled by default)
+```
+
+## Run standalone
+
+```bash
+bun install
+bun run script/analyze.ts "/path/to/flight.bin" --project /path/to/workdir
+bun test          # 29 tests: decoder vs oracle, checks, store/diff
+bun run typecheck
+```
+
+## Knowledge grounding (the retrieval ladder)
+
+Verdicts are always deterministic (harness vs bound). Sourcing a bound's value + citation
+walks a ladder, first hit wins, never invents:
+
+1. **`uav-thresholds.yaml`** — tuned / customer-stated bounds (local, authoritative).
+2. **`query_hydron_project`** — ingested OEM datasheets in the project KG/RAG (cite citation).
+3. **Exa.ai web MCP** (`exa_web_search_exa` / `exa_web_fetch_exa`) — datasheets / rules-of-thumb
+   **not in the KG**; cite the URL. Pluggable: swap for another search MCP. These tools are
+   available in the normal modes; the UAV subagents allow-list them so they don't prompt per call.
+
+## Verified sample result (`17-03-2026 Sortie 4.bin`)
+
+ArduCopter V4.6.3, ~48 min, 1306 params. **battery CRITICAL** (2× ERR 6/1 failsafes),
+**vibration HIGH** (VibeZ 40.4 > 30), **hover HIGH** (avg ThH 0.17 < 0.25 band); attitude/
+altitude/rcou/rcin/mag/ekf clean. Decode ~0.4 s.
+
+## RAM / large-file scaling (P0 — design-partner blocker)
+
+> **AirBound requires 1.5–2 GB files and ~4-flight compares; we'd only tested to ~60 MB,
+> and big files froze the machine.** This is the top priority. See
+> `internal-docs/.../uav/11-airbound-scale-and-deep-integration.md`.
+
+> **✅ Landed (2026-06-29) — P-scale steps 1–5 (streaming decode → on-disk SQLite).**
+> `analyzeFlight`/`uav_query` now stream `.bin` rows straight into a throwaway **on-disk**
+> SQLite (`harness/db.ts` `openAnalysisDb`/`createSqliteSink`; `decode/dataflash.ts`
+> `decodeDataflashInto`; `harness/load.ts` `decodeToDb`), retaining only the low-rate
+> tables `extract.ts`/`vehicle.ts` read in JS (`RETAIN_TABLES = PARM/MSG/GPS/ERR/MODE`);
+> high-rate aggregates moved to SQL in `extract.ts`. The 24 checks were already SQL-only.
+> Verified by `src/harness/streaming.test.ts` (synthetic `.bin` parity/concurrency/cleanup +
+> a real-bin smoke). **Synthetic benchmark (115 MB / 5M-row log):** peak RSS **781 MB → 282 MB
+> (~2.8×)** — the eliminated part is the JS row graph (the term that scales linearly and
+> freezes at GB scale).
+>
+> **✅ P1b landed — chunked file read.** `decode/dataflash.ts` `decodeCore` now reads the file
+> in 4 MiB windows and carries cross-boundary messages, instead of `arrayBuffer()`-ing the whole
+> file. **Peak RSS is now independent of file size.**
+>
+> **Real benchmark (the 1.69 GB golden `2026-04-07 15-20-25.bin`):** streaming `analyze`
+> completes at **~332 MB peak RSS in ~79 s** (down from ~1.08 GB pre-P1b; the old full path
+> would be 10 GB+ and freeze). Retained JS rows tiny (PARM 1397 / MSG 117 / ERR 2). **AirBound's
+> 1.5 GB gate is met, RSS flat in file size.** `loadTables` (`:memory:`) and `decodeAuto` are
+> unchanged for `uav_tune`/`export`/`plot`.
+>
+> **Test hygiene:** the golden flight log lives outside the repo and changes; `src/test-fixture.ts`
+> centralizes it. Full-decode / pymavlink / CSV-oracle tests `skipIf(!goldenFullDecodeSafe())`
+> (skip when the golden is absent or >500 MB — they'd OOM on a GB log); the memory-safe
+> streaming path is exercised on the real golden via `hasGolden()`. Suite: **172 pass / 16 skip
+> / 0 fail**.
+
+## CPU: off-thread decode + duty-cycle throttle — ✅ landed
+
+The streaming decode trades memory for CPU (millions of batched inserts + parse of tens of
+millions of messages on one thread). Two **cross-platform** controls (no `nice`/OS-priority):
+- **Off the main thread (#3):** `analyze`/`uav_query` run the decode in a **Worker**
+  (`harness/worker-entry.ts` + `worker-client.ts`), so Hydron's main loop stays responsive and
+  the OS schedules the work on another core. **The full on-disk SQLite is still built inside the
+  worker** — later `uav_query`/root-cause keep full row specificity. If a Worker can't run, it
+  **falls back to in-thread** (the feature never breaks).
+- **CPU ceiling (#4):** set `UAV_DECODE_MAX_CPU` (e.g. `0.6` ≈ 60% of a core) to duty-cycle the
+  decode (`harness/throttle.ts`, applied per-chunk in `decodeCore`). Unset = full speed. Trades
+  wall-clock for a CPU cap — cross-platform (timer-based). Verified in
+  `src/harness/throttle-worker.test.ts` (strict worker path matches in-thread; throttle idles).
+
+## Multi-flight compare at GB scale (P-multicompare) — ✅ landed
+
+`uav_compare` compares **2+ already-analyzed flights at once** — finding-severity trend, key-
+metric trend (vibe_peak, hover_thr, …), and parameter drift across the runs. It diffs the small
+stored per-flight **EpisodeDocuments** (≈100 KB each), never the raw logs, so **comparing four
+1 GB flights costs ~four 100 KB docs, not 4 GB** (analyze each first — each streams at ~flat
+RAM). New: `store/diff.ts` `diffEpisodesN` (N-way), `store/store.ts` `readEpisodeById`,
+`harness/compare.ts` `compareFlights`, and the `uav_compare` tool. Tested in
+`src/harness/compare.test.ts`.
+
+Root cause (in this code): `uav_analyze` holds **three concurrent copies** of the log —
+the whole file buffer, **every row of every message type as boxed JS arrays** in
+`log.tables` (`decode/dataflash.ts`), and a full copy again in an **`:memory:`** SQLite
+(`harness/loadtables.ts`). The JS row graph dominates and OOMs on big logs. The 24 checks
+already run as **pure SQL aggregates** over the DB, so the fix is structural:
+
+- **P0:** `loadtables.ts` → on-disk throwaway SQLite (not `:memory:`) + `journal_mode=OFF` /
+  `synchronous=OFF` / bounded `cache_size`. (Partial — removes one copy.)
+- **P1 (the real fix):** stream decode rows directly into the on-disk DB in batches; retain
+  in JS only the low-rate tables `extract.ts`/`vehicle.ts` iterate (PARM/MSG/MODE/ERR/GPS);
+  move `extract.ts`'s duration/vibe_peak/hover aggregates to SQL. High-rate tables
+  (IMU/RATE/ATT/VIBE/BAT/CTUN) then live only on disk; RAM is bounded by `cache_size`.
+- **P1b:** read the file in 1 MB chunks (reuse the `contentHash` sliding-buffer) instead of
+  `arrayBuffer()`; **P2:** size-based "large-file mode", per-table row caps with `partial`
+  flags, optional child-process decode so a blowup can't freeze the host.
+- **Multi-file:** the streaming/on-disk design must hold for **4 concurrent flights**
+  (`uav-compare`), each its own on-disk DB, diffed via SQL joins.
+
+## Known limitations / next
+
+- **Multidisciplinary root cause (P1, AirBound litmus test)** — beyond the current metric
+  checks, rank + eliminate competing hypotheses (aero × firmware × electronics) and cite
+  each; first demo target: **improperly tuned pitch-gain filter** (RATE oscillation ×
+  VIBE/FFT × `ATC_RAT_PIT_*`/`INS_GYRO_FILTER` params).
+- **Pluggable diverse ingest (P1)** — weather-station CSV, custom params, external sensor
+  logs, time-aligned with the flight (self-registering handler layer).
+- **Deep UAV-tool integration (the moat)** — SITL replay to confirm a hypothesis, deeper
+  pymavlink/MAVProxy + param-metadata + firmware code-context grounding.
+- **Correlation/trend tier** (oscillation FFT, compass-motor interference, EKF drift over
+  time) and **param airframe-profile diff** (`auditAgainstProfile` stub) are not yet built.
+- **PX4 `.ulog`** isn't wired yet; the pymavlink path is tested on the ArduPilot `.bin`.
+- Live `uav_watch`/`uav_stream` and the `uav-diagnose` orchestrator (core-gated) are future.
+- `uav-thresholds.yaml` overlay parsing is minimal (built-in v1 defaults are authoritative
+  until the YAML parse is fleshed out).
+
+---
+
+## Install (plugin system)
+
+The pack is now a proper **Hydron plugin bundle**. Install it with the `hydron plugin` CLI:
+
+```bash
+# Global (available in every project on this machine):
+hydron plugin add @h2loop/uav
+
+# Project-scoped (committed to repo, shared with the team):
+hydron plugin add @h2loop/uav --project
+```
+
+`hydron plugin add` validates the bundle, then COPIES it into the plugins root (global →
+`~/.config/hydron-cli/plugins/uav`; `--project` → `<repo>/.hydron/plugins/uav`). A local-path
+install (`hydron plugin add /path/to/uav-pack [--project]`) is also supported for dev. Once
+installed, agents, commands, skills, tools, MCP servers, and the ambient domain context are
+all discovered and loaded automatically — no manual config wiring needed.
+
+**Scope & persistence.** The install persists across sessions — install once, it's picked up
+at every future startup. Global = "this machine does UAV work" (available in every repo);
+`--project` = "this repo is UAV work" (committed with the repo, shared with the team). A
+project's local `uav-thresholds.yaml` still overrides the global one.
+
+Uninstall with `hydron plugin remove uav` (add `--project` for the project-scoped install).
+Other commands: `hydron plugin list` (installed plugins + status), `hydron plugin enable
+<name>` / `disable <name>`, `hydron plugin update <name>`, `hydron plugin validate <path>`
+(static analysis before installing).
+
+After install or uninstall, **fully quit and relaunch Hydron** — the plugin loads once per
+process (a window reload isn't enough).
+
+**UAV is a domain LAYER, not a mode.** Every mode (Ask / Architect / Code / Debug) becomes
+UAV-aware via a short always-on signpost (the `experimental.chat.system.transform` hook) plus
+the on-demand `uav` skill. There is **no dedicated UAV agent or mode**; the `uav-investigate`,
+`uav-compare`, and `uav-verify` subagents handle isolated multi-step loops and are spawned
+automatically, not selected by the user.
+
+## MCP prerequisites
+
+The plugin ships two MCP servers (both **disabled by default**). Enable them per-project in
+your Hydron config:
+
+### Exa (web grounding)
+
+Provides `exa_web_search_exa` / `exa_web_fetch_exa` for OEM datasheet limits not in the
+project KG.
+
+**Requires:** `EXA_API_KEY` environment variable (get one at https://exa.ai).
+
+### MAVLink bridge (live link)
+
+A local Python stdio server. Read-only tools: `read_params`, `param_get`, `param_get_all`,
+`get_messages`, `tail_telemetry`, `get_flight_mode`, `get_status`. The write tier
+(`param_set` / `param_set_batch`) is **off by default** — see below.
+
+**Requires:**
+- Python ≥ 3.10 with `pymavlink>=2.4.49` and `mcp[cli]>=1.0.0` installed. The pack does **not**
+  auto-provision a venv — install the deps yourself: `pip install -r bridge/requirements.txt`
+  (ideally into a venv), and point the command's `python3` at that interpreter.
+- A reachable MAVLink endpoint (e.g. `udp:127.0.0.1:14550` from SITL or a telemetry radio),
+  or a `.tlog`/`.log` file for offline replay.
+- The `bridge/` directory ships with the plugin (the `mcp.json` references it).
+
+Enable per-project in your Hydron config. **Param writes are OFF by default** (the bridge
+defaults to `--read-only`). To enable the tune→push→retest write tier, the command must pass
+**both** `--no-read-only` **and** `--allow-param-write`. ⚠ this lets the agent write params to
+a **live vehicle** — prefer SITL/bench.
+```jsonc
+"mcp": {
+  "mavlink": {
+    "enabled": true,
+    "command": ["python3", "<plugin-path>/bridge/uav_mavlink_bridge.py",
+                "--connect", "udp:127.0.0.1:14550",
+                "--no-read-only", "--allow-param-write"]
+  }
+}
+```
+
+Connect-target forms: `udp:HOST:PORT` (default `udp:127.0.0.1:14550` = SITL/MAVProxy) |
+`tcp:HOST:PORT` | `serial:/dev/ttyUSB0:BAUD` | `/path/log.tlog` (offline replay); can also be
+set via the `MAVLINK_CONNECT` env on the server. **"Connected" ≠ a live vehicle:** the panel
+shows Connected once the bridge process starts, but tools only return data while something is
+actually publishing MAVLink at the connect target; otherwise calls time out (`-32001`). Plain
+`.bin` log analysis via `uav_analyze` does **not** need the bridge.
+
+## Known limitations
+
+1. **Loader collision (host bug) — FIXED.** Hydron's plugin dedup used to key on the hook
+   module's basename (`index`), so two plugins each shipping a `plugins/index.ts` hook could
+   collide and one would be silently dropped. This is now resolved in hydron-cli:
+   `getPluginName` keys on the plugin install directory, not the basename, so multiple
+   hook-bearing plugins coexist.
+
+2. **Local-path install copies everything:** `hydron plugin add ./path` does a raw `fs.cp`
+   with no `files`/`.npmignore` filtering. If you ran `bun install` or `bun run build` locally,
+   the copy includes `node_modules` + built artifacts + source. **Publish to npm and install via
+   spec** (`hydron plugin add @h2loop/uav`) for a clean install — npm respects `files`.

package/USAGE.md

@@ -0,0 +1,172 @@
+# @h2loop/uav — Install, Validate & Use
+
+The UAV domain pack for Hydron: point it at an ArduPilot/PX4 flight log and get grounded
+analysis, tuning suggestions, in-editor charts, and (optionally) a live MAVLink link. This guide
+covers getting it running on **macOS, Linux, and Windows**, validating it works, and everyday use.
+
+---
+
+## 1. Prerequisites (all platforms)
+
+- **Hydron** installed (the host — CLI and/or VS Code extension). Required.
+- **Bun** — *only* needed to build the bundle from source or run the pack's tests; **not**
+  needed to use a published pack.
+- **Python ≥ 3.10** — *only* for the optional live MAVLink bridge (`pymavlink>=2.4.49` +
+  `mcp[cli]>=1.0.0`). The pack does **not** auto-provision a venv; you install the deps
+  yourself (see §6). Plain `.bin` log analysis needs no Python.
+- *Optional:* `export EXA_API_KEY=…` for web grounding of bounds.
+- macOS/Linux are native; on **Windows** use **WSL2** for the bridge's Python (the bridge is
+  POSIX-oriented).
+
+---
+
+## 2. Install per OS
+
+Install with the **`hydron plugin`** CLI — a cross-platform command (no bash wrapper, no PATH
+patching). `hydron plugin add` COPIES the whole bundle into the plugins root, so the source
+location no longer matters after install.
+
+```bash
+# Global — available in every project on this machine:
+hydron plugin add @h2loop/uav
+
+# Project-scoped — committed with the repo, shared with the team:
+hydron plugin add @h2loop/uav --project
+
+# Local path (dev, from a checkout):
+hydron plugin add /path/to/uav-pack            #   add --project to scope it to a repo
+```
+
+### macOS / Linux
+Native. Nothing extra needed to use a published pack. Python ≥ 3.10 is only required for the
+optional MAVLink bridge (§6).
+
+### Windows — use WSL2 for the bridge
+The `hydron plugin add` command itself is cross-platform. The MAVLink bridge, however, is
+POSIX-oriented Python, so run it (and ideally Hydron) inside **WSL2** (Ubuntu):
+```powershell
+wsl --install -d Ubuntu        # PowerShell (admin), one-time; then open the Ubuntu shell
+```
+Use the **VS Code "WSL" remote** (or Hydron's CLI inside WSL) so Hydron and the bridge share
+the same environment.
+
+### Uninstall (any OS)
+```bash
+hydron plugin remove uav             # add --project for the project-scoped install
+```
+
+After install (or uninstall), **fully quit + relaunch Hydron** — the plugin loads once at
+process start (a window reload isn't enough).
+
+---
+
+## 3. Validate it works
+
+### Install checks (plugin CLI)
+| Check | Command | Expect |
+|---|---|---|
+| Installed & enabled | `hydron plugin list` | `uav` listed as enabled |
+| Bundle valid | `hydron plugin validate /path/to/uav-pack` | passes static analysis (before installing) |
+| Removed | `hydron plugin remove uav` | `uav` no longer in `hydron plugin list` |
+
+### Behavior (in a Hydron session, after restart)
+| # | Test | Prompt / action | Expect |
+|---|---|---|---|
+| 1 | Tools load | "what UAV tools do you have?" | `uav_analyze, uav_plot, uav_tune, uav_finding, uav_query, uav_python, …` |
+| 2 | Analyze + vehicle type | "analyze `/path/flight.bin`" | ranked anomaly report; detects multirotor / fixed-wing / VTOL |
+| 3 | Graph labeling | "plot VibeZ over time" | chart **plus** a note: *VIBE = airframe vibration at the IMU, not per-motor* |
+| 4 | Tuning | "run uav_tune on this flight" | `INS_HNTCH_*` notch params (+ `INS_HNTC2_*` if a distinct 2nd peak) |
+| 5 | Per-airframe bounds | drop `<project>/.hydron/uav-thresholds.yaml` with `vibration: { max_ms2: 60 }`, re-analyze | vibration judged against 60, not the default 30 |
+
+Automated tests: `bun test`. Real-log tests run only when `UAV_GOLDEN_BIN=/path/to.bin` is set.
+
+---
+
+## 4. Everyday use
+
+Point Hydron at a `.bin`/`.tlog`/`.ulog` and talk to it in any mode — the UAV layer rides along.
+
+- **Triage:** "analyze `/path/flight.bin` and rank the anomalies."
+- **Visualize:** "plot desired-vs-actual roll tracking error"; "FFT the gyro"; "x=RCOU.C1 y=VIBE.VibeZ".
+- **Investigate (parallel fan-out):** "what caused the EKF spike at 800s, walk the altitude excursion, and cross-check the IMUs."
+- **Tune:** "`/uav-tune /path/flight.bin`" → notch + mode recommendation with valid ranges.
+- **Save a conclusion:** "save that as a finding" (or `/uav-save-finding`).
+- **Compare / batch:** "`/uav-compare flightA flightB`"; "`/uav-batch-report /path/to/logs`".
+
+---
+
+## 5. Per-lab config (pluggable, no plugin change)
+
+Drop these into your project's `.hydron/` — the pack ships generic defaults; your specifics override:
+
+- **`uav-thresholds.yaml`** — your airframe's bounds. Deep-merges over defaults, so list only the
+  keys you change (e.g. `vibration: { max_ms2: 60 }`). Name your profile with `ruleset_version`.
+- **`uav-format-converters.json`** — register a converter for a non-standard log format.
+
+See `skills/uav/references/project-config.md` for the full list (`uav-thresholds.yaml`,
+`param-rules.yaml`, `apm-params.json`, `uav-format-converters.json`) and merge semantics.
+
+---
+
+## 6. Live MAVLink bridge (the `mavlink` MCP)
+
+A **MAVLink→MCP bridge**: a local Python stdio server Hydron spawns so the agent can query a
+live vehicle / SITL / log replay. Read-only tools: `get_status`, `get_flight_mode`,
+`read_params`, `param_get`, `param_get_all`, `get_messages`, `tail_telemetry`. The **write**
+tools `param_set`/`param_set_batch` are **off by default** (see the ⚠ note below).
+
+### Install the Python deps yourself
+The pack does **not** auto-provision a venv. The bridge needs Python ≥ 3.10 with
+`pymavlink>=2.4.49` and `mcp[cli]>=1.0.0`:
+```bash
+pip install -r bridge/requirements.txt     # ideally into a venv
+```
+Then point the `mavlink` command's `python3` at that interpreter.
+
+### Enable and configure (per-project in opencode.jsonc)
+The `mavlink` server ships in `mcp.json` **disabled by default**. Enable it per-project:
+```jsonc
+"mcp": {
+  "mavlink": {
+    "enabled": true,
+    "command": ["python3", "<plugin-path>/bridge/uav_mavlink_bridge.py",
+                "--connect", "udp:127.0.0.1:14550"]
+  }
+}
+```
+Connect-target forms: `udp:HOST:PORT` (default `udp:127.0.0.1:14550` = SITL/MAVProxy) |
+`tcp:HOST:PORT` | `serial:/dev/ttyUSB0:BAUD` | `/path/log.tlog` (offline replay). Can also be
+set via the `MAVLINK_CONNECT` env on the server.
+
+> **"Connected" ≠ a live vehicle.** The panel shows `mavlink Connected` once the bridge *process*
+> starts. The tools only return data while something is **actually publishing MAVLink** at the
+> connect target. With no source, calls return empty / time out (`-32001`). Start your SITL/vehicle
+> (or leave it — log analysis via `uav_analyze` doesn't need the live bridge).
+
+> **Param writes are OFF by default.** The bridge defaults to `--read-only`. To enable the
+> tune→push→retest write tier (`param_set` / `param_set_batch`), the command must pass **both**
+> `--no-read-only` **and** `--allow-param-write`:
+> ```jsonc
+> "command": ["python3", "<plugin-path>/bridge/uav_mavlink_bridge.py",
+>             "--connect", "udp:127.0.0.1:14550",
+>             "--no-read-only", "--allow-param-write"]
+> ```
+> ⚠ this lets the agent **write parameters to a live vehicle** — prefer SITL/bench, and point
+> `--connect` at a real airframe only when you intend that.
+
+---
+
+## 7. Troubleshooting
+
+- **UAV tools don't appear** → you didn't *fully* restart Hydron (a window reload isn't enough); the
+  plugin loads once per process. Confirm it's installed with `hydron plugin list`. On Windows make
+  sure Hydron is running in the **same WSL env** you're using.
+- **`mavlink` shows Disabled** → the `python3` in the `mavlink` command lacks `pymavlink`+`mcp`, or
+  it isn't Python ≥ 3.10. Install the deps (`pip install -r bridge/requirements.txt`, ideally into a
+  venv) and point the command at that interpreter.
+- **Every mavlink tool → `MCP error -32001: Request timed out`** → the bridge is Connected but **no
+  MAVLink source is live** at the connect target. Start SITL / point `--connect` at a live link.
+- **`MCP error -32000: Connection closed`** → the bridge crashed at startup: usually the wrong Python
+  (no deps — see Disabled above) or a **port clash** (only one Hydron instance can bind the bridge's
+  UDP port at a time — don't run two).
+- **See also:** `PACKAGING.md`, `CHANGELOG.md`, `bridge/README.md`.

package/agents/uav-compare.md

@@ -0,0 +1,36 @@
+---
+mode: subagent
+displayName: UAV Compare
+description: >-
+  Cross-flight regression for ONE airframe over its stored history (not just a pair).
+  Loops over the airframe's episodes, diffs consecutive flights, and returns only the
+  narrated trend — the multi-flight decode, the per-table SQL, and the per-step diffs
+  stay in this subagent. This is a genuine loop (many flights, many diffs); that is why
+  it is a subagent rather than a one-shot tool call.
+permission:
+  # deny-all FIRST, then allow specifics: PermissionNext resolves with findLast (last
+  # matching rule wins), so "*": deny MUST precede the allows or it overrides them all.
+  "*": deny
+  bash: allow
+  "uav_analyze": allow
+  "uav_query": allow
+  skill: { "*": deny, "uav": allow }
+---
+You are a UAV compare subagent. You produce a cross-flight regression for one airframe over
+its history, keeping the multi-flight decode and the per-table SQL out of the primary window.
+
+Do this:
+1. Determine the airframe's flight set. If given an explicit pair, use it; otherwise load the
+   airframe's stored episodes in order (`uav_query` over the local store) and walk the history.
+2. For each consecutive pair, fetch the server-side param + finding diff. Accumulate the
+   trend — a param that drifts the same direction across several flights matters more than a
+   one-flight blip.
+3. Return ONLY a narrated regression: the params and findings that shifted, the direction and
+   magnitude of each shift (and whether it is a one-flight jump or a sustained trend), and
+   which guardrail each relates to — citing the bound and its source. Ground every shift
+   against an absolute bound, not just "moved a lot relative to last flight".
+
+In the tuning phase the reference is the *last* flight (track pattern shifts); for a
+production vehicle the reference is the *fixed* guardrail. Rank the shifts by
+significance and surface them — do not close the verdict. Leave that to the engineer.
+See the `uav` skill's compare reference for how to narrate the diff.

package/agents/uav-investigate.md

@@ -0,0 +1,60 @@
+---
+mode: subagent
+displayName: UAV Investigate
+description: >-
+  Drill into ONE open-ended question about a flight (e.g. "what caused the EKF jump at
+  ~800s?") and return a single grounded brief. The multi-step loop — analyze, repeated
+  uav_query, uav_python, web-grounding — and all its intermediate output stay in this
+  subagent; only the ranked conclusion comes back. Use for investigations, NOT for a
+  one-shot uav_analyze (call that tool directly from the parent — it already isolates the
+  decode and per-table SQL).
+permission:
+  # deny-all FIRST, then allow specifics: PermissionNext resolves with findLast (last
+  # matching rule wins), so "*": deny MUST precede the allows or it overrides them all.
+  "*": deny
+  bash: allow
+  read: allow
+  "uav_analyze": allow
+  "uav_query": allow
+  "uav_python": allow
+  "uav_param_audit": allow
+  "uav_finding": allow
+  "exa_web_search_exa": allow
+  "exa_web_fetch_exa": allow
+  "query_hydron_project": allow
+  skill: { "*": deny, "uav": allow }
+---
+You are a UAV investigation subagent. You exist because a real investigation is a LOOP — it
+takes many tool calls and produces a lot of intermediate output (SQL rows, Python summaries,
+dead ends). All of that stays in your window; only your final brief returns to the parent.
+
+If the task is a single one-shot decode-and-check, you are the wrong tool — say so; the parent
+should call `uav_analyze` directly (the tool already keeps the decode and per-table SQL out of
+context). You earn your keep only on open-ended questions.
+
+How to investigate (reason, don't jump to a verdict):
+1. Establish the baseline with `uav_analyze` if not already done — what fired, what didn't.
+2. Form a hypothesis, then TEST it with evidence: `uav_query` for the relevant rows,
+   `uav_python` (numpy/pandas) for aggregates, correlations, per-window stats, spectra. Quote
+   the exact window/timestamp your numbers come from; do not eyeball.
+3. Ground every claim against an ABSOLUTE bound, never relative-to-peers. "X is 6× its
+   neighbour" is NOT a fault unless X also clears its absolute guardrail (uav-thresholds.yaml,
+   then query_hydron_project, then a cited web source). If you can only show a relative
+   difference, say "within absolute tolerance — relative only" and do not flag it.
+4. Iterate until the chain holds or the evidence runs out. State what you could NOT confirm.
+
+Persisting a conclusion is a REQUIRED final step — for EACH finding that cleared an absolute
+bound in step 3, actually call the tool; do not just describe it in your brief:
+- FIRST `uav_finding op:"list" flight_id:<id>` — read what is already stored (deterministic +
+  earlier agent findings).
+- DECIDE whether your finding is already represented — same root cause counts, even if worded
+  differently or covered by a deterministic check (e.g. don't add "IMU2 disagreement" when
+  `imu_consistency` already reports it). This is a judgment, not a string match.
+- Only if it is genuinely new, `uav_finding op:"add"` with a clear title, severity, the measured
+  value, the absolute threshold_used, and a detail citing the bound + its source. Pass
+  supersedes_id to replace a stale one. Never add a finding you could only support relative-to-peers.
+
+Return: the ranked findings (most significant first), each with its measured value, the time
+window it came from, the absolute bound it breached and that bound's source, which ones you
+persisted (and which you skipped as already-stored), and a one-paragraph synthesis. No raw row
+dumps, no full FFT bins. Surface and rank; leave the final verdict to the engineer.

package/agents/uav-verify.md

@@ -0,0 +1,45 @@
+---
+mode: subagent
+displayName: UAV Verify
+description: >-
+  Adversarial check on ONE proposed flag. Given a claimed anomaly, decide whether it clears
+  an ABSOLUTE grounded bound or is merely relative-to-peers / eyeballed. Returns a verdict:
+  GROUNDED (cite the bound + source + margin) or RELATIVE-ONLY (not a fault). Use this before
+  reporting a flag the deterministic checks did NOT already produce.
+permission:
+  # deny-all FIRST, then allow specifics: PermissionNext resolves with findLast (last
+  # matching rule wins), so "*": deny MUST precede the allows or it overrides them all.
+  "*": deny
+  bash: allow
+  read: allow
+  "uav_query": allow
+  "uav_python": allow
+  "query_hydron_project": allow
+  "exa_web_search_exa": allow
+  "exa_web_fetch_exa": allow
+  skill: { "*": deny, "uav": allow }
+---
+You are an adversarial verifier. Your DEFAULT is to refute the flag. Your only job: decide
+whether a proposed anomaly is grounded in an absolute bound, or is an artifact of relative
+comparison. You do not investigate broadly and you do not author new findings — you judge one.
+
+You are given: a claimed flag (signal, measured value, the reasoning behind it).
+
+Test it:
+1. Is there an ABSOLUTE bound for this signal? Look in this order: uav-thresholds.yaml →
+   query_hydron_project (ingested datasheets) → a cited web source (ArduPilot health docs,
+   OEM datasheet). If no absolute bound exists, the flag is NOT grounded — say so.
+2. Does the measured value actually breach that absolute bound? Recompute from the data with
+   `uav_query` / `uav_python` if needed; quote the window. "N× the other instances", "highest
+   of the three", "looks elevated" are RELATIVE signals and never, by themselves, a fault — an
+   IMU at 0.20 m/s² inter-instance spread is fine against a 0.7 m/s² bound even if it is 6× its
+   neighbours.
+3. Check the bound applies to this vehicle type and regime before accepting it.
+
+Return ONE verdict, nothing else:
+- `GROUNDED` — measured value, the absolute bound it breaches, the bound's source, and the
+  margin by which it breaches.
+- `RELATIVE-ONLY` — the absolute bound (or "none exists"), the value's margin INSIDE it, and a
+  one-line reason the original flag was relative/eyeballed.
+Bias toward RELATIVE-ONLY when uncertain. A flag survives only if you can name the absolute
+bound it breaks.