docs: scaffold polisher-control foundation

shared/schemas/examples/machine-capabilities.example.json

@@ -0,0 +1,51 @@
+{
+  "schema_version": "machine-capabilities.v1",
+  "machine_id": "fullum-alpha",
+  "machine_family": "swing-arm",
+  "machine_name": "Fullum Swing-Arm Polisher",
+  "controller_version": "polisher-control/0.1.0",
+  "last_verified": "2026-06-01T00:00:00Z",
+  "supported_motion_families": ["swing-arm-rosette"],
+  "force_range_n": [5, 200],
+  "table_rpm_range": [0.5, 10.0],
+  "spindle_rpm_range": [10, 120],
+  "cam_amplitude_range_deg": [1.0, 31.3],
+  "cam_offset_range_deg": [-30.0, 30.0],
+  "force_modulation": {
+    "supported": true,
+    "max_harmonics": 3,
+    "max_amplitude_n": 24.0,
+    "notes": "m=2 astigmatism and m=3 trefoil are proven channels. m=1 coma is unreliable (score 0.09)."
+  },
+  "supported_dither_profiles": ["none", "default"],
+  "segment_duration_limits": {
+    "min_s": 30,
+    "max_s": 7200
+  },
+  "pause_resume_support": true,
+  "telemetry_channels": [
+    { "name": "table_rpm", "unit": "RPM", "sample_rate_hz": 100 },
+    { "name": "spindle_rpm", "unit": "RPM", "sample_rate_hz": 100 },
+    { "name": "force_n", "unit": "N", "sample_rate_hz": 100 },
+    { "name": "arm_angle_deg", "unit": "degrees", "sample_rate_hz": 100 },
+    { "name": "table_angle_deg", "unit": "degrees", "sample_rate_hz": 100 },
+    { "name": "timestamp_ms", "unit": "ms", "sample_rate_hz": 100 }
+  ],
+  "safety_limits": {
+    "max_force_n": 200,
+    "max_table_rpm": 10.0,
+    "max_spindle_rpm": 120,
+    "notes": "Force hard-limited by load cell interlock. RPM limits are VFD/servo configured."
+  },
+  "known_constraints": [
+    "Cam amplitude is not servo-programmable — must be set mechanically before run.",
+    "Force modulation bandwidth limited to ~5 Hz by actuator response.",
+    "Table encoder is absolute but may have 1-2 count jitter.",
+    "Serial interface to Teensy limits command update rate to ~50 Hz effective."
+  ],
+  "unknowns": [
+    "Exact force modulation phase accuracy at m=3 harmonic — not yet validated on hardware.",
+    "Thermal drift effect on force sensor over runs longer than 1 hour.",
+    "Arm pivot play magnitude under varying force loads."
+  ]
+}