sprint-0: foundations -- data model, seed library, tests, demo

Initial commit. Delivers what the brief calls 'Sprint 0 - Foundations'
(see docs/AR_Autopilot_brief.md section 12):

- Complete repository structure (arautopilot package + firmware, display,
  installer, tools placeholders + docs).
- Core data model (Pydantic v2): modes, alarms, actuator config, PID
  config + gain scheduling, vessel config, knob state machine, project
  config with YAML/JSON serialisation.
- Seed library: 2 actuator profiles (hydraulic & electric DC reversible)
  and 2 default tunings (yacht motor planeo 30 m and 40 m). Conservative
  literature values, NOT the integrator's production tuning IP.
- Firmware skeleton: only src/hal/pinout.h with the 21 I/O contract for
  the AR-NMEA-IO v1.0 board. No drivers, no main loop.
- Studio stubs (real PySide6 app starts in Sprint 4).
- pytest suite (80 tests, all green): modes, alarms, actuator, PID
  (incl. gain interpolation and the +/-50% adaptive bound from brief
  section 6), vessel, knob state, project config, library loader,
  end-to-end roundtrip.
- examples/sprint0_demo.py - the acceptance demo from the brief.

Acceptance criteria met:
- pytest green (80/80)
- demo creates, saves (YAML + JSON), reloads, and verifies a full
  ProjectConfig using the seed library
- repository ready for tag `sprint-0-approved`

See CHANGELOG.md for the detailed scope.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

arautopilot/library/default_tunings/yacht_motor_planeo_30m.yaml

@@ -0,0 +1,58 @@
+# =============================================================================
+# Default PID tuning — 30 m planing motor yacht
+# =============================================================================
+#
+# WARNING — Conservative bench/start values only.
+# These gains come from classical marine control literature (Fossen 2011,
+# Perez 2005) scaled to a 30 m planing motor yacht class. They are intended
+# only for bench testing and the very first sea trial — they MUST be replaced
+# with the integrator's affinated values during commissioning.
+#
+# The "real" tuning libraries are integrator IP and are NOT shipped here.
+#
+# Units:
+#   - kp/ki/kd: dimensionless (controller internal units)
+#   - frequencies: Hz
+#   - rate / deadband: degrees, degrees/second
+#
+# Cascaded loops (brief section 6):
+#   - inner: rudder-position controller, 50 Hz
+#   - outer: heading controller, 10 Hz
+#
+# Gain scheduling: outer-loop gains interpolated over SOG (knots).
+# Outside the scheduled range the closest endpoint is held.
+# =============================================================================
+
+schema_version: "0.1.0"
+
+inner_loop_base:
+  kp: 2.5
+  ki: 0.15
+  kd: 0.30
+inner_loop_freq_hz: 50.0
+
+outer_loop_base:
+  kp: 0.90
+  ki: 0.02
+  kd: 1.20
+outer_loop_freq_hz: 10.0
+
+# Three-point schedule covering manoeuvring (5 kn), cruise (15 kn), top (28 kn).
+# At low speed: more kp, less kd (rudder bites more, less inertia anticipation).
+# At high speed: less kp, more kd (gentler corrections, anticipate overshoot).
+gain_schedule:
+  - speed_knots: 5.0
+    gains: { kp: 1.20, ki: 0.03, kd: 0.80 }
+  - speed_knots: 15.0
+    gains: { kp: 0.90, ki: 0.02, kd: 1.20 }
+  - speed_knots: 28.0
+    gains: { kp: 0.55, ki: 0.01, kd: 1.80 }
+
+rot_feedforward_gain: 1.50
+
+setpoint_deadband_deg: 0.5
+setpoint_rate_limit_dps: 4.0
+anti_windup_limit: 8.0
+
+adaptive_enabled: false
+adaptive_max_deviation_pct: 50.0

arautopilot/library/default_tunings/yacht_motor_planeo_40m.yaml

@@ -0,0 +1,45 @@
+# =============================================================================
+# Default PID tuning — 40 m planing motor yacht
+# =============================================================================
+#
+# WARNING — Conservative bench/start values only.
+# Scaled from the 30 m profile to account for the larger vessel: higher mass
+# moment of inertia and longer time constants. Compared to the 30 m profile:
+#   - kp slightly lower (slower response per unit rudder)
+#   - kd slightly higher (more anticipation needed for the inertia)
+#   - setpoint_rate_limit_dps reduced (gentler heading slew)
+#
+# As with the 30 m profile, these are commissioning starting points and
+# must be replaced with the integrator's production tuning.
+# =============================================================================
+
+schema_version: "0.1.0"
+
+inner_loop_base:
+  kp: 2.20
+  ki: 0.12
+  kd: 0.35
+inner_loop_freq_hz: 50.0
+
+outer_loop_base:
+  kp: 0.75
+  ki: 0.015
+  kd: 1.55
+outer_loop_freq_hz: 10.0
+
+gain_schedule:
+  - speed_knots: 5.0
+    gains: { kp: 1.00, ki: 0.025, kd: 1.10 }
+  - speed_knots: 15.0
+    gains: { kp: 0.75, ki: 0.015, kd: 1.55 }
+  - speed_knots: 28.0
+    gains: { kp: 0.45, ki: 0.008, kd: 2.20 }
+
+rot_feedforward_gain: 1.80
+
+setpoint_deadband_deg: 0.5
+setpoint_rate_limit_dps: 3.0
+anti_windup_limit: 8.0
+
+adaptive_enabled: false
+adaptive_max_deviation_pct: 50.0