@h2loop/uav 1.0.0

package/skills/uav/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: uav
+description: >-
+  UAV domain expertise for ArduPilot / PX4 work — flight logs, parameters, tuning, and
+  telemetry. Load this at the START of any UAV task in whatever mode you are in (Code,
+  Plan, Debug, Ask): deciding which uav_* tool answers a question, decoding/triaging a
+  .bin/.log/.ulog/.tlog, auditing params, recommending tuning, interpreting a check
+  (battery, attitude, altitude, hover, rcou, rcin, vibration, mag, ekf), explaining WHY a
+  guardrail bound is what it is, or narrating a cross-flight regression. It carries the
+  tool map, the grounding discipline (guardrails judge, you narrate), signal semantics,
+  per-check interpretation, the tuning playbook, and the fan-out rules. This is a domain
+  LAYER, not a mode — you stay in your current mode and use it.
+---
+# UAV skill — ArduPilot/PX4 flight-log domain layer
+
+You are doing UAV work inside a normal Hydron mode (Code / Plan / Debug / Ask). This skill
+is the domain layer that rides across that mode — it does not replace it. The deterministic
+harness (the `uav_*` tools) produces findings (severity + verdict); your job is to drive the
+right tool, then **explain** the results grounded in guardrail bounds and their sources —
+never to author a verdict from raw numbers.
+
+## Tooling — which tool for which job (call these directly; no mode switch)
+
+- **Triage one log** → `uav_analyze` (.bin/.log/.tlog/.ulog): decode + the vehicle-aware
+  system checks + param audit + persist the episode. It already isolates the decode, the
+  full param load, and per-table SQL and returns only the rendered report — call it directly,
+  do not wrap it in a subagent.
+- **Ad-hoc read** → `uav_query`: read-only SQL over ONE decoded flight, for a single quick
+  peek (one aggregate / a few rows).
+- **Real computation** → `uav_python`: pandas/numpy over the flight's decoded tables
+  (`load("VIBE")`, `load("ATT")`, …; `TimeUS` is µs since boot; `print()` results). Use this
+  the moment an analysis needs binning, correlation, scoring/ranking windows, regression, FFT,
+  or multi-signal joins. Rule of thumb: **if you're about to run a 2nd `uav_query` to assemble
+  an answer, write `uav_python` instead.** Numbers must come from code you actually ran.
+- **Chart** → `uav_plot` (`timeseries` | `xy` | `fft`): the FINAL picture, not a substitute
+  for reasoning. Never hand-write SQL for a visualisation.
+- **Parameters** → `uav_param_audit` (safety / range / consistency; ranges grounded in
+  `apm.pdef.xml`, never invented).
+- **Tuning** → `uav_tune`: FFT over gyro/VIBE → dominant peak → recommended `INS_HNTCH_*`
+  notch params (recommend, then push via the gated MAVLink link — never auto-write).
+- **Run-tracking** → `uav_tag`: label a flight (test profile / campaign) — the param-history
+  record ArduPilot lacks.
+- **Handoff** → `uav_export`: one CSV per message type for PlotJuggler.
+- **Record a conclusion** → `uav_finding`: at the END of an investigation, `op:"list"` first,
+  judge whether it's already represented (same root cause counts), then `op:"add"` only if
+  genuinely new (`supersedes_id` to replace a stale one). Only ABSOLUTE-bound findings the
+  deterministic checks did not already cover — never a relative-only one.
+- **Bench / live vehicle** → `serial_*` (watch/drive the FC console) and the `mavlink` MCP
+  (read params/telemetry; gated param writes) when a link is configured.
+
+## Load the reference that matches the task
+
+Read each by its explicit path under `references/`:
+
+- **`references/grounding.md`** — how thresholds/guardrails are sourced and cited. The core
+  principle (the LLM narrates, the guardrails judge), the three guardrail sources (OEM
+  datasheet / rule-of-thumb / per-airframe tuned) and their precedence, and the work-style
+  rules (chain-of-thought, ask-don't-assume, cite the bound, surface-don't-over-verdict).
+  **Read this before you state why a bound is what it is, or you are tempted to judge a raw
+  number yourself. A flag must clear an ABSOLUTE grounded bound — not merely stand out
+  relative to peers or its own baseline.**
+- **`references/signals.md`** — signal/column dictionary + analysis method. Which column
+  actually answers a question (e.g. throttle = `RCOU` motor-mean / `CTUN.ThO`, **not** the
+  near-constant `CTUN.ThH`), EKF innovation names, plus the reason-and-explore-before-plotting
+  discipline. **Read this before any correlation / "does X relate to Y" / visualisation
+  question.**
+- **`references/checks.md`** — per-check interpretation (battery, attitude, altitude, hover,
+  rcou, rcin, vibration, mag, ekf): the table/fields it reads, the rule, what an anomaly means
+  physically, and how to talk about it without over-verdicting. Read this when interpreting
+  any finding.
+- **`references/tuning-methodology.md`** — the ORDERED tuning playbook: pre-tune gates →
+  harmonic notch → rate PID → attitude → position/altitude → sensor source (`EK3_SRC`) → drift
+  over the sortie. Read this for ANY "how do I tune / what params / why is it oscillating /
+  altitude is noisy" question. `references/tuning.md` is the notch-recommender detail.
+- **`references/compare.md`** — how to narrate a cross-flight diff (params, findings, regime;
+  tuning-phase vs production reference; direction/magnitude; ranking without closing the
+  verdict). Read this for `/uav-compare` or the `uav-compare` subagent's output.
+- **`references/project-config.md`** — the optional per-project override files under
+  `<project>/.hydron/` (thresholds, param rules, param metadata, format converters): what each
+  controls, merge-vs-replace semantics, and the exact path to WRITE when a user asks to change
+  a bound, a param range, or add a custom log format.
+
+If the right reference is not obvious, read `references/grounding.md` first — the grounding
+discipline governs almost every UAV answer.
+
+## Orchestration — split unrelated work, fan it out
+
+- When ONE message asks MULTIPLE INDEPENDENT investigation-class questions — each needing its
+  own multi-step drill-down, none depending on another's answer — spawn ONE **`uav-investigate`**
+  subagent PER question and issue those task calls TOGETHER so they run in parallel, then
+  synthesize the briefs. Do NOT work them serially in this thread, and do NOT merge unrelated
+  questions into one investigation. (E.g. "what caused the EKF spike at 800s?", "walk the
+  altitude-excursion cause-chain", and "cross-check the IMUs" → three parallel investigations.)
+- Split only when the questions are genuinely independent. If one's answer feeds the next, do
+  them in order. If each is a single one-shot tool call (several `uav_analyze`/`uav_plot`
+  requests), just call the tools directly — in parallel where independent — with no subagent.
+- Other specialist subagents: **`uav-compare`** (cross-flight regression over an airframe's
+  history) and **`uav-verify`** (adversarially confirm a proposed flag clears an ABSOLUTE
+  bound — use before reporting any anomaly the deterministic checks did NOT produce). Each runs
+  the same grounded discipline and returns only its brief; the heavy chatter stays out of the
+  main thread.

package/skills/uav/references/checks.md

@@ -0,0 +1,174 @@
+# Per-check interpretation
+
+**21 system checks** run as SQL over the per-flight in-memory tables, plus a **parameter
+audit** over the PARM set (`param.*` findings). Each yields a `severity`
+(`OK` / `HIGH` / `CRITICAL`) and a `verdict` (`PASS` / `FAIL` / `SKIP` — `SKIP` = required
+table/param absent). These are deterministic. Your job is to explain a FAIL physically and
+rank it — never to manufacture a verdict. Always cite the bound and its source (see
+`grounding.md`). Column names follow the sample log; the decoder is FMT-driven, so verify
+per-firmware at decode time. The detailed write-ups below cover the core checks; the full
+catalog (by subsystem) and the param audit follow at the end.
+
+## battery (CRITICAL)
+
+- **Tables / fields:** `ERR` (`Subsys`, `ECode`), correlated with `MSG`, `MODE`, `BAT`.
+- **Rule:** `ERR.Subsys=6 AND ECode=1` with count > 0 → CRITICAL. A correlation check —
+  join on `TimeUS` to assemble the "battery failsafe → RTL" story (`ERR` + `MSG`
+  "Battery critical" + `MODE`→RTL + `BAT` sag).
+- **Physically:** the flight controller declared a battery failsafe — voltage or
+  capacity crossed the configured floor and the vehicle acted on it (commonly RTL/Land).
+- **How to talk about it:** narrate the timeline (when the failsafe fired, what the mode
+  did after), cite the `err_subsys:6 / err_ecode:1` signature as the ArduPilot battery-failsafe
+  firmware constant (rule-of-thumb), and point
+  at the `BAT` sag if present. Don't speculate on root cause beyond what the timeline
+  shows; surface it as the top-ranked finding when present.
+
+## attitude (HIGH)
+
+- **Tables / fields:** `ATT` — `DesRoll-Roll`, `DesPitch-Pitch`.
+- **Rule:** sustained `MAX(ABS(desired - actual)) > max_deg` (default 5°, over a sample
+  window) → HIGH.
+- **Physically:** the vehicle could not hold the commanded attitude — control authority,
+  tuning, or a disturbance (wind, payload, a failing motor) is preventing it from
+  tracking the setpoint.
+- **How to talk about it:** report the peak divergence in degrees vs the 5° bound (a seed
+  default), note whether it was sustained or a transient, and correlate with rcou
+  saturation or vibration before suggesting a cause. Rank, don't conclude.
+
+## altitude (HIGH)
+
+- **Tables / fields:** `CTUN` — `DAlt-Alt` (desired vs achieved altitude).
+- **Rule:** `MAX(ABS(DAlt-Alt)) > max_m` (default 2 m) → HIGH.
+- **Physically:** altitude tracking error — the vehicle is not holding commanded height,
+  often tied to thrust margin, baro/EKF altitude estimate, or aggressive descent.
+- **How to talk about it:** state the peak error in metres vs the 2 m seed bound; tie it
+  to hover-throttle or EKF findings if they co-occur. A few-metre transient in an
+  aggressive manoeuvre is different from sustained error in a hold — say which.
+
+## hover (HIGH)
+
+- **Tables / fields:** `CTUN.ThH` (hover throttle).
+- **Rule:** `AVG(ThH)` outside the band `[0.25, 0.75]` → HIGH.
+- **Physically:** hover throttle near the band edges signals a thrust-to-weight problem —
+  low end = overpowered/twitchy or light; high end = underpowered/overweight, little
+  margin for manoeuvre or wind.
+- **How to talk about it:** report the average hover throttle vs the `[0.25, 0.75]`
+  rule-of-thumb band, and frame it as a thrust-margin observation. Relate to the ≥ 2:1
+  thrust-to-weight rule-of-thumb. Surface; the engineer judges acceptability.
+
+## rcou — motor outputs (HIGH)
+
+- **Tables / fields:** `RCOU` — `C1..C8`.
+- **Rule:** any channel pegged at max → HIGH (saturation / imbalance).
+- **Physically:** a motor output pinned at its ceiling means that motor has no headroom —
+  the mixer is asking for more than it can give, indicating imbalance, a weak/failing
+  motor, CG offset, or undersized propulsion.
+- **How to talk about it:** name which channels saturated and for how long, and correlate
+  with attitude divergence (a saturated motor often explains an attitude FAIL). Describe
+  the imbalance pattern; leave the mechanical diagnosis to the engineer.
+
+## rcin — pilot inputs (OK / context)
+
+- **Tables / fields:** `RCIN` — `C3` (throttle), other channels for range sanity.
+- **Rule:** values outside `[1000, 2000]` µs → HIGH; otherwise context.
+- **Physically:** this is what the pilot commanded. Out-of-range values can mean RC
+  calibration, signal loss, or a failsafe trigger; in-range values are context that helps
+  explain other findings (e.g. an attitude divergence during an aggressive stick input).
+- **How to talk about it:** mostly use rcin as supporting context — "the divergence
+  coincided with a full-throttle climb the pilot commanded." Only flag it as a finding
+  when the ranges are genuinely out of bounds.
+
+## vibration (HIGH)
+
+- **Tables / fields:** `VIBE` — `VibeX`, `VibeY`, `VibeZ`; plus `VIBE.Clip`.
+- **Rule:** any axis peak ≥ 30 m/s² → HIGH (FC max is 105). Clipping:
+  `MAX(Clip) > 0` → anomaly (any clip event).
+- **Physically:** excessive vibration corrupts the IMU/accelerometer feed, which then
+  poisons the EKF state estimate — a root cause that propagates into altitude and EKF
+  findings. Clipping means the accelerometer railed and lost data outright.
+- **How to talk about it:** report peak per-axis vs the 30 m/s² bound (rule-of-thumb)
+  and note any clip events against the `max:0` bound. Frame vibration as a likely
+  upstream cause when EKF/altitude also FAIL. Tuning (notch filtering) is the usual
+  remedy, but that analysis lives in a separate path — surface, don't prescribe here.
+
+## mag — magnetometer (HIGH)
+
+- **Tables / fields:** `MAG.Health`; `MSG` for yaw-alignment timing.
+- **Rule:** `MIN(Health) < 1` → HIGH. Late yaw-align: first `MSG` matching
+  `/EKF.*yaw align/i` minus arm time > `late_align_s` (default 30 s); no such MSG → SKIP
+  that sub-check.
+- **Physically:** an unhealthy magnetometer or a late yaw alignment means the heading
+  estimate was unreliable early in the flight — interference, a bad compass calibration,
+  or magnetic disturbance near the airframe.
+- **How to talk about it:** state whether health dropped below 1 and/or how long yaw
+  alignment took vs the 30 s bound. Connect to any EKF/heading anomalies. If the
+  yaw-align MSG is absent, say the sub-check was skipped — never imply a clean pass over
+  missing data.
+
+## ekf — EKF innovations (HIGH)
+
+- **Tables / fields:** `XKF3` — innovations `IVN`, `IVE`, `IVD`.
+- **Rule:** innovation ratio > `max_ratio` (default 0.5) → HIGH. This is a correlation /
+  trend check, not a single scalar — regime-dependent.
+- **Physically:** large EKF innovations mean the filter's prediction and its sensor
+  measurements disagree — the state estimate is being pulled around. Common upstream
+  causes: vibration corrupting the IMU, mag/GPS disagreement, or sensor dropout.
+- **How to talk about it:** report the peak innovation ratio vs the 0.5 seed bound (from
+  ArduPilot health criteria), and explicitly correlate with vibration, mag, and GPS
+  findings — EKF FAILs are usually downstream of one of those. This is exactly where a
+  model is tempted to hand-wave; resolve it to the explicit criterion and the correlated
+  evidence, not a vibe. Surface the chain; let the engineer rule on root cause.
+
+## gps — GPS health (HIGH)
+
+- **Tables / fields:** `GPS`/`GPA` — `NSats`, `HDop`.
+- **Rule:** `NSats < 6` or `HDop > 2.0` → HIGH (fix loss / poor geometry).
+- **Physically:** too few satellites or high HDOP means a weak position fix — the EKF
+  position/velocity estimate degrades, which can cascade into altitude and EKF findings,
+  especially outside GPS-denied regimes.
+- **How to talk about it:** report satellite count and HDOP vs the `min:6` / `hdop_max:2.0`
+  bounds, and note when in the flight the fix degraded. Correlate with EKF innovations.
+  Surface and rank; the engineer decides whether the regime made it acceptable.
+
+---
+
+## Full catalog (added checks — boundary + consistency tier)
+
+Beyond the core checks above, these run when their data is present (else SKIP). Each cites
+its bound's source; bounds live in `uav-thresholds.yaml`.
+
+**Power & battery** (`BAT`, `POWR`)
+- `min_cell_voltage` (CRITICAL) — `MIN(BAT.Volt)/cells` (cells≈`ROUND(MAX(Volt)/4.2)`) below per-cell floor. Cite datasheet min; per-cell sag under load is the real health signal.
+- `voltage_sag` (HIGH) — `MAX(BAT.VoltR-Volt)` large → weak pack/connector/high IR under load.
+- `over_current` (HIGH) — `MAX(BAT.Curr)` above ESC/motor rating (airframe-specific; ground from datasheet).
+- `internal_resistance` (HIGH) — `MAX(BAT.Res)` high → ageing/damaged pack (seed-default; pack-specific, override per airframe).
+- `board_brownout` (CRITICAL) — `MIN(POWR.Vcc)` dipped near/below 4.5V → flight-controller power-rail brownout; correlate with any reboots/errors.
+
+**Control & propulsion** (`RATE`, `MOTB`, `ESC`)
+- `rate_tracking` (HIGH) — desired-vs-actual body rates diverge (`RDes-R`,`PDes-P`,`YDes-Y`) → tune/saturation; pairs with vibration & oscillation.
+- `thrust_margin` (HIGH) — `MOTB.FailFlags`>0 (thrust loss) or low `ThrOut`/`LiftMax` headroom → undersized/▼T:W (rule-of-thumb ~2:1).
+- `esc_health` (HIGH) — ESC over-temp (`Temp`/`MotTemp`) or `Err`>0 → desync/overheat risk.
+
+**Estimation & sensors** (`XKF4`, `GPA`, `MAG`, `IMU`)
+- `ekf_variance` (HIGH) — `XKF4` SV/SP/SH/SM spikes (or `FS` set) → estimator stress/failsafe.
+- `gps_accuracy` (HIGH) — `GPA.HAcc` above bound → poor fix quality even with sats.
+- `mag_offsets` (HIGH) — large `MAG.Ofs*` → bad calibration / interference; correlate with current draw.
+- `imu_health` (HIGH) — `IMU.EG`/`EA` error counts > 0 → IMU dropouts; check across instances.
+
+## Parameter audit (`param.*`)
+
+A separate deterministic pass over the PARM set (range/safety/consistency). Findings are
+`tier:system`, `check` ids prefixed `param.`. Bounds in `<project>/.hydron/param-rules.yaml`
+(create/edit this file to add or change a rule; merged over the built-in ruleset).
+
+- **`param.safety.*`** — arming checks not disabled (`ARMING_CHECK≠0`, CRITICAL), battery
+  failsafe configured (`BATT_LOW/CRT_VOLT`, CRITICAL), radio failsafe (`FS_THR_ENABLE`),
+  geofence (`FENCE_ENABLE`). A disabled safety is a config risk, not a flight symptom — say so.
+- **`param.consistency.*`** — cell-count vs failsafe voltages agree; frame class/type set;
+  notch filter enabled when expected.
+- **`param.range.*`** — tuning/safety params within sane ranges (`INS_GYRO_FILTER`,
+  `ATC_RAT_*_P`, `MOT_SPIN_*`, `RTL_ALT`, …). Out-of-range = likely misconfig; cite the range.
+
+When narrating a param finding, frame it as *configuration* (what's set vs recommended),
+distinct from a *telemetry* anomaly (what the vehicle did) — and never invent a range; cite
+`param-rules.yaml` / the datasheet.

package/skills/uav/references/compare.md

@@ -0,0 +1,49 @@
+# Narrating a cross-flight diff
+
+Comparison is the tuning-phase path: track how a single airframe's behaviour shifts
+flight-to-flight. The harness produces the diff (param changes + finding changes); your
+job is to narrate what moved, by how much, and in which direction — grounded in the
+guardrails, ranked, and without closing the verdict.
+
+## What to compare
+
+- **Params** — what changed in the ~1,117-param set between the two flights. Highlight
+  the deltas that plausibly explain a finding shift (e.g. a notch-filter or gain change
+  alongside a vibration or attitude change).
+- **Findings** — which checks improved, regressed, appeared, or disappeared between the
+  two flights, with each check's measured value on both sides and the bound it relates
+  to.
+- **Regime** — note if the two flights were flown differently (aggressive vs hover,
+  GPS-denied vs open). A finding shift driven by a regime change is not the same as a
+  shift at constant regime. If the regime is ambiguous, ask before attributing the shift.
+
+## Reference: tuning vs production
+
+- **Tuning phase** → the reference is the *last* flight. You are tracking pattern shifts
+  over the tuning cycle; the question is "did this change move the airframe in the right
+  direction?"
+- **Production vehicle** → the reference is the *fixed* guardrail bound, for consistency.
+  The question is "is this flight within bounds?"
+
+Same machinery, different reference. State which one you are using.
+
+## How to describe a shift
+
+For each shifted finding, give:
+- the check and its measured value on flight A vs flight B;
+- the **direction** (improved toward / regressed away from the bound) and the
+  **magnitude** of the change;
+- the guardrail bound it relates to and that bound's source (datasheet / rule-of-thumb /
+  tuned — see `grounding.md`);
+- the plausible param change that correlates with it, if any.
+
+Example shape: "Peak Z vibration fell from 41 to 28 m/s² (now under the 30 m/s²
+customer-stated bound), coinciding with INS_HNTCH params being enabled — the EKF
+innovation peak also dropped from 0.7 to 0.4."
+
+## Rank, don't close the verdict
+
+Order the shifts by significance (a CRITICAL battery change or a regression that crosses
+a bound outranks a small in-bounds wobble). Present the ranked narrative and the
+correlated evidence; leave the call — "is this tuning step good enough to keep?" — to the
+engineer. Surface the chain; don't decide it.

package/skills/uav/references/grounding.md

@@ -0,0 +1,94 @@
+# Grounding — how thresholds and guardrails are sourced and cited
+
+This is the customer's #1 concern: a generic model asked "is this flight OK?" guesses,
+because it does not know *this* airframe's actual limits. UAV anomaly judgments must be
+grounded in the vehicle's real constraints, not the model's priors.
+
+## The principle: the LLM narrates, the guardrails judge
+
+The verdict is kept out of your hands. The deterministic harness compares the measured
+value against an **explicit guardrail** and produces the `Finding` (its `severity` and
+its `verdict`). You only **explain** confirmed findings and answer questions — you never
+decide "anomalous vs fine" from raw numbers. A hallucinated threshold therefore cannot
+become a verdict: the threshold is data, not a guess.
+
+```mermaid
+flowchart LR
+  M["measured value (decoded)"] --> G{"guardrail check (deterministic)"}
+  GR["guardrails: OEM datasheet + rules-of-thumb + per-airframe bounds"] --> G
+  G -->|in bounds| OK["verdict: PASS"]
+  G -->|out of bounds| FAIL["verdict: FAIL (severity)"]
+  OK --> N["LLM narrates / answers (grounded in the finding, not the raw data)"]
+  FAIL --> N
+```
+
+## Where guardrails come from (the three sources)
+
+Every bound lives in `uav-thresholds.yaml` and carries its source, so a finding can cite
+*why* the bound is what it is — grounding the explanation, not just the verdict.
+
+1. **OEM datasheet** — component-specific limits (battery min voltage, max current,
+   internal-resistance ceiling, ESC/motor ratings). The authoritative bounds for a given
+   airframe's parts. Hydron already RAG-indexes datasheets, so these can be retrieved per
+   component rather than hand-typed: **call `query_hydron_project`** with the component +
+   the limit you need (e.g. *"min cell voltage and max continuous current for the Tattu
+   6S 16000mAh on airframe X"*) and cite the returned value + its citation as the finding's
+   source. Only do this when a project with the datasheet ingested is selected; otherwise
+   fall back to `uav-thresholds.yaml`.
+2. **Rule-of-thumb** — industry constants that hold across vehicles (e.g. ≥ 2:1
+   thrust-to-weight for a multicopter, a healthy hover-throttle band, vibration < 30 m/s²).
+   A small curated rules-of-thumb library in the pack.
+3. **Per-airframe tuned** — values the lab sets for a specific vehicle in
+   `uav-thresholds.yaml`, refined over its tuning cycle.
+
+**Precedence:** per-airframe tuned > OEM datasheet > rule-of-thumb default.
+
+## Retrieval ladder — how to source a bound that isn't already in `uav-thresholds.yaml`
+
+The verdict is ALWAYS deterministic (the harness compares the measured value to a bound).
+These steps only supply *which bound to use and where it came from* — its citation. Walk
+the ladder in order and stop at the first that yields a sourced bound; record which tier +
+the citation on the finding:
+
+1. **Local config** — `<project>/.hydron/uav-thresholds.yaml` (tuned / customer-stated).
+   Authoritative; no lookup needed. Create/edit this file to set or change a bound.
+2. **KG / RAG** — `query_hydron_project` for an **ingested** OEM datasheet limit (cite the
+   returned citation). Only when a project with that datasheet is selected.
+3. **Web** — a **web-search MCP (Exa by default)** when the bound is **not in the KG**:
+   `exa_web_search_exa` / `exa_web_fetch_exa` to find the OEM datasheet spec or the
+   published rule-of-thumb, then **cite the URL**. This is the "knowledge grounding outside
+   the KG" path — datasheets the lab never ingested, community tuning guides, manufacturer
+   PDFs.
+
+If no tier yields a defensible bound, **say so and surface the raw value for the engineer**
+— never invent a threshold. A web/KG result is a *source for a bound*, not a verdict; the
+harness still decides PASS/FAIL. Treat web results with appropriate skepticism (prefer the
+manufacturer's own datasheet over a forum post) and always attach the link so the engineer
+can verify.
+
+## Grounding applies to the system tier only
+
+Only **system** findings (the built-in inspection-order checks) are guardrail-grounded
+and enter the regression record / comparison. **User** findings (ad-hoc `uav_query`) are
+exploratory, tagged `tier:'user'` with their query provenance, and are **not** part of
+the canonical grounded comparison. They answer a question; they do not assert a grounded
+verdict. Never fold a user query's result into the regression record or present it as a
+grounded verdict.
+
+## The hard tier — correlation checks
+
+Simple bound checks (battery V/I/resistance) are deterministic and easy. IMU/EKF drift
+needs multi-step analysis: trends, cross-signal correlation, regime awareness — not a
+single scalar threshold. Grounding matters most here, precisely because it is where a
+model is tempted to hand-wave. Even these resolve to explicit, explainable criteria, not
+vibes.
+
+## Work-style rules (cite this when narrating)
+
+- **Chain-of-thought** — reason step-by-step over the findings before concluding.
+- **Ask clarifying questions over assuming** — when vehicle type, configuration, regime,
+  or intent is ambiguous, ask; don't guess.
+- **Cite the guardrail** — every anomaly states the bound it breached and that bound's
+  source (datasheet / rule-of-thumb / tuned), never an unsourced number.
+- **Surface, don't over-verdict** — rank anomalies; leave the final call to the engineer.
+  Investigation is case-by-case.

package/skills/uav/references/project-config.md

@@ -0,0 +1,27 @@
+# Project config files (optional per-project overrides)
+
+These tune the pack per project/lab. They live under `.hydron/` at the project root. All are
+OPTIONAL: the tools ship built-in defaults and work without them. To customise, **WRITE the
+file directly at the exact path below** — the tools read only these paths.
+
+Merge semantics differ:
+- The two YAML files are **MERGED** (deep-merged) over the built-in defaults (which are baked
+  into the pack, not shipped as files). Author them from scratch listing only the keys you are
+  overriding — everything else keeps its default.
+- `apm-params.json` is different: it **REPLACES** the bundled snapshot wholesale. A partial
+  file drops every param you omit, so include the full set you need. The baseline snapshot
+  ships at the plugin's own `data/apm-params.json`.
+
+Files:
+
+- `<project>/.hydron/uav-thresholds.yaml` — per-airframe anomaly guardrail bounds. Deep-merged
+  over the built-in defaults; this is the authoritative first rung when sourcing a bound.
+- `<project>/.hydron/param-rules.yaml` — curated `{param: {min, max, severity}}` range/safety
+  rules for `uav_param_audit`. Merged over the built-in ruleset.
+- `<project>/.hydron/apm-params.json` — ArduPilot param metadata (name → `{min, max, units}`).
+  REPLACES the snapshot bundled with the plugin wholesale (not merged) when present.
+- `<project>/.hydron/uav-format-converters.json` — registry of custom log-format converters
+  (proprietary formats → a known format, applied before decode). No default; add only if needed.
+
+When a user asks to change a bound, a param range, or add a custom log format, **write to the
+matching file above — do not hard-code the value** anywhere else.

package/skills/uav/references/signals.md

@@ -0,0 +1,60 @@
+# Signal dictionary + analysis method (pick the RIGHT column before you plot)
+
+Choosing the wrong column silently produces wrong conclusions (e.g. correlating vibration
+against `CTUN.ThH` — a near-constant hover estimate — falsely shows "no relationship").
+Look the signal up here first. Columns follow the sample log; the decoder is FMT-driven, so
+verify per-firmware.
+
+## Throttle (the classic trap)
+- **`RCOU.C1…C8`** — actual **motor PWM output** (~1000–2000 µs). Use the **mean of the active
+  motors** as the true instantaneous throttle/effort. ← use this for "throttle".
+- **`CTUN.ThI`** — throttle **input** (pilot demand, 0–1). **`CTUN.ThO`** — throttle **output**
+  (0–1, post-mix). Either is a valid throttle proxy.
+- **`CTUN.ThH`** — throttle **hover**: the *slowly-learned* hover-throttle estimate
+  (`MOT_THST_HOVER`), **≈ constant over a flight**. **NOT instantaneous throttle** — never use
+  it as the throttle axis.
+
+## Vibration / IMU
+- `VIBE.VibeX/Y/Z` (m/s²) is **whole-airframe vibration sensed at the IMU**, reported **per IMU
+  instance** (`VIBE.IMU` = which IMU). It is **NOT per-motor** vibration — the log does not
+  attribute vibration to a specific motor. Label it "airframe vibration (IMU N)", never
+  "motor N vibration". Per-**motor** signals are `RCOU.Cn` (output PWM) and `ESC` (per-ESC
+  RPM/temp); to *attribute* a vibration peak to a motor you must correlate the FFT peak Hz with a
+  motor's RPM (`ESC.RPM`/`RPM` × poles), not read it off VIBE.
+- `VIBE.Clip0/1/2` = cumulative clip counts (per IMU).
+- `IMU.GyrX/Y/Z`, `AccX/Y/Z`; `IMU.I` = instance (interleaved — de-interleave for FFT);
+  `EG/EA` = gyro/accel error counts; `T` = temp; `GHz/AHz` = sample rates.
+
+## Attitude / rates (tracking error = desired − actual)
+- `ATT.DesRoll/Roll`, `DesPitch/Pitch`, `DesYaw/Yaw` (deg).
+- `RATE.RDes/R`, `PDes/P`, `YDes/Y` (deg/s) + `*Out` (controller output).
+
+## Altitude / position
+- `CTUN.DAlt/Alt` (desired/achieved), `BAlt` (baro), `DCRt/CRt` (climb rate). 
+
+## Battery / power / ESC
+- `BAT.Volt`, `VoltR` (resting), `Curr`, `CurrTot`, `Res` (internal resistance), `Temp`, `RemPct`.
+- `POWR.Vcc` (board 5V rail). `ESC.RPM/Volt/Curr/Temp/MotTemp/Err` (per-ESC). `MOTB.LiftMax/ThrOut/ThLimit/FailFlags`.
+
+## EKF (XKF* = EKF3, NKF* = EKF2)
+- Innovations `XKF3`/`NKF3`: **velocity** `IVN/IVE/IVD` (+`IVT`), **position** `IPN/IPE/IPD`.
+  Vibration-driven stress shows in velocity innov; GPS issues in position innov.
+- Variances `XKF4`/`NKF4`: `SV/SP/SH/SM`; `FS` = failsafe flags.
+
+## Mag / GPS
+- `MAG.MagX/Y/Z` (field), `OfsX/Y/Z` (offsets), `MOX/Y/Z` (motor compensation), `Health`.
+- `GPS.NSats/HDop/Status`; `GPA.HAcc/VAcc/SAcc` (accuracy estimates).
+
+## Method (general — fit the analysis to the data)
+- **Explore first** with `uav_query` (SQL) and/or **Python** (`bash`: `python3` + pandas/numpy
+  over `uav_export` CSVs, or pymavlink on the log) — check columns, units, ranges, sample
+  counts, distribution, outliers. Reason before you plot.
+- **Don't force one statistic.** Inspect the *shape* of a relationship (linear / threshold /
+  none / time-varying) and pick a summary that fits it. A single correlation can mislead —
+  clustered/narrow ranges, nonlinearity, and outliers all distort it — so per-bucket trends,
+  medians, and robust/aggregate measures often tell the real story. Report the evidence and
+  the caveats, not just a coefficient.
+- Use a **representative** signal (aggregate noisy or biased channels rather than one arbitrary
+  sample). Confirm the column means what you think (above) before trusting the result.
+- `uav_plot`: derived exprs for error signals (`ATT.DesRoll - ATT.Roll`), `xy` for correlations,
+  `fft` for spectra — the final picture after the reasoning, not a substitute for it.

package/skills/uav/references/tuning-methodology.md

@@ -0,0 +1,79 @@
+# Methodical tuning — the ordered playbook (generic, airframe-agnostic)
+
+How to turn a log into **reasoned, ordered parameter suggestions** — the loop a good tuner
+runs by hand, and what the Autopilot Methodical Configurator (AMC) automates. This is
+METHODOLOGY, not a value table: you read the evidence from the log (`uav_query`/`uav_python`),
+you take every parameter's valid **range/default from `apm.pdef.xml`** (via `uav_param_audit` —
+never invent a range), and you suggest a *direction and magnitude* with justification. Actual
+per-airframe target values are the lab's tuned profile, not baked in here.
+
+Two hard rules, always:
+- **Order matters — do not skip ahead.** Each stage assumes the ones above it are clean. Tuning
+  a PID loop on a vibrating airframe, or on top of a bad sensor source, chases ghosts.
+- **Recommend only; change ONE thing; then re-fly and re-check.** You never write params (that's
+  the gated MAVLink link). Every suggestion cites the signal it's based on, the param + its
+  `apm.pdef.xml` range, the direction, and how to confirm it on the next log.
+
+## Stage 0 — Pre-tune gates (must pass before ANY gain tuning)
+If these fail, fix them first; do not touch PIDs.
+- **Vibration / clipping**: `VIBE.VibeX/Y/Z` within bound, `VIBE.Clip*` not accumulating.
+  Clipping or high vibe corrupts the gyro the PIDs act on. → go to Stage 1.
+- **Mechanical**: props balanced, frame rigid, IMU isolation intact (shows as broadband vibe).
+- **Sensors healthy**: `MAG.Health`, GPS `NSats`/`HAcc`, `POWR.Vcc` rail, EKF not failsafing
+  (`XKF4.FS`). A bad sensor source is Stage 5 — but a *failing* one blocks everything.
+
+## Stage 1 — Vibration & harmonic notch (FIRST)
+Clean the gyro before touching gains. Use `uav_tune` (FFT → `INS_HNTCH_*`; see
+`references/tuning.md`). Confirm the motor/prop peak, set the notch, re-fly, confirm the peak
+dropped. Only then proceed.
+
+## Stage 2 — Rate loop (inner PID: the core of the tune)
+Signals: `RATE.RDes/R`, `PDes/P`, `YDes/Y` (deg/s) and `*Out` (controller output).
+Read from the log with `uav_python`:
+- **Tracking error** = desired − actual per axis. Large steady error → P too low.
+- **Oscillation** on the *actual* trace (and on `*Out`) → gain too high (usually D, then P).
+- **Lag / mushy response** → P/D too low, or `FLTD`/`FLTT` filters too aggressive.
+
+Params (ranges from `apm.pdef.xml`): `ATC_RAT_RLL_P/I/D`, `ATC_RAT_PIT_P/I/D`,
+`ATC_RAT_YAW_P/I/D`, plus `_FLTD` (D-term filter), `_FLTT` (target filter), `_FLTE`. Standard
+heuristics: raise D until high-freq oscillation appears then back off ~25%; set P near D×10 as a
+start; keep I so that I/P stays in the usual band. **One axis, one gain, at a time.** Justify each
+from the tracking-error/oscillation evidence you measured.
+
+## Stage 3 — Attitude (angle) loop (outer)
+Only after the rate loop is crisp. Signals: `ATT.DesRoll/Roll`, `DesPitch/Pitch`, `DesYaw/Yaw`.
+Sluggish angle response with a clean rate loop → raise `ATC_ANG_RLL_P` / `ATC_ANG_PIT_P` /
+`ATC_ANG_YAW_P`. Overshoot → lower. These are usually a light touch.
+
+## Stage 4 — Position / altitude / velocity loops
+Signals: `CTUN.DAlt/Alt`, `DCRt/CRt` (climb-rate track), horizontal pos/vel from `XKF1`/`POS`.
+Params: `PSC_POSZ_P`, `PSC_VELZ_P`, `PSC_ACCZ_P/I/D` (vertical), `PSC_POSXY_P`, `PSC_VELXY_*`
+(horizontal). Poor altitude hold that is NOT a sensor problem → adjust the vertical PSC chain.
+But first rule out the sensor source (Stage 5) — noisy altitude is usually source, not gain.
+
+## Stage 5 — Sensor source & fusion (EK3_SRC) — esp. altitude
+The EKF blends sources; picking the wrong primary shows as noise the PIDs can't fix.
+- **Barometer is noisy near the ground** (prop-wash, ground effect). For low-altitude precision,
+  prefer **GPS** or a **rangefinder / 1-D lidar** for height. Params: `EK3_SRC1_POSZ`
+  (1=baro, 2=GPS, 3=rangefinder, …), `RNGFND*`, `EK3_RNG_USE_HGT`.
+- Horizontal source: `EK3_SRC1_POSXY` / `_VELXY` (GPS vs beacon vs optical flow); yaw:
+  `_YAW` (compass vs GPS-yaw vs external).
+- Evidence: compare `CTUN.BAlt` (baro) noise vs GPS/rangefinder height over the same window with
+  `uav_python`; if baro is the noisy one at low altitude, recommend switching `POSZ` source (or
+  blending) — with the range/enum from `apm.pdef.xml`.
+
+## Stage 6 — Drift over the sortie (endurance / large airframes)
+Gyro/estimator drift matters more on **long sorties** and **large airframes** (heavy airframes
+lean on the estimator; small ones are GPS-compensated at ~5 Hz). Method:
+- Trend the EKF innovation/variance over time, not just the peak: `XKF4.SV/SP/SH/SM` and
+  `XKF3` innovations (`uav_python`, binned over the flight). A steady upward drift in a variance
+  or a growing bias signals estimator/gyro drift.
+- The **acceptable drift bound scales with the airframe** — so it is a **tunable per-airframe
+  threshold** (the lab's profile), not a fixed number here. Report the observed drift rate and
+  compare it against the airframe's bound if one is configured; otherwise surface the trend and
+  say no absolute bound is set.
+
+## Closing the loop (every stage)
+Suggest → (human) gate-write over the MAVLink param link → re-fly → re-run the relevant
+analysis on the new log → confirm the metric moved the right way. Cite the before/after. Tag the
+retest (`uav_tag`) so `uav-compare` can track the tuning trajectory across flights.