docs: scaffold polisher-control foundation

README.md

@@ -0,0 +1,64 @@
+# Polisher-Control
+
+Machine-side execution stack for the Fullum / GigaBIT swing-arm polisher.
+
+This repository is for Cédric's implementation work on the **controller, firmware,
+manual-mode UI support, telemetry, safety/interlocks, and run artifacts**. It is
+aligned with the broader Polisher Software Suite:
+
+```text
+polisher-sim   -> planning / digital twin / calibration / metrology intelligence
+polisher-post  -> validation + packaging of controller-safe jobs
+polisher-control -> safe machine execution + telemetry + operator workflow
+shared contracts -> schemas, logs, machine capabilities, provenance
+```
+
+## v1 finish line
+
+Normand can operate the polisher manually from the touchscreen, with:
+
+- safe force/table/spindle control;
+- KWR75B-CAN force/torque sensor integration;
+- ODrive S1 + M8325s spindle drive integration;
+- Teensy-side fast safety and setpoint/telemetry loop;
+- host-side state machine, logs, status, and data export;
+- synchronized telemetry at **>=100 Hz**;
+- manual-session logs usable by `polisher-sim` / `polisher-post` later;
+- safety/interlocks enforced and visible in logs.
+
+## What this repo must NOT become
+
+`polisher-control` does **not** own optical strategy. It must not interpret
+interferograms, optimize polishing passes, learn calibration parameters, or invent
+correction programs. Those decisions belong upstream in `polisher-sim` and
+`polisher-post`.
+
+The controller should be boring, deterministic, auditable, and conservative.
+
+## Start here
+
+1. Read [`docs/00-start-here.md`](docs/00-start-here.md).
+2. Read [`docs/02-v1-scope.md`](docs/02-v1-scope.md).
+3. Review the state machine and safety rules in [`docs/03-architecture.md`](docs/03-architecture.md).
+4. Use [`docs/08-commissioning-checklist.md`](docs/08-commissioning-checklist.md) during hardware bring-up.
+5. Track implementation using [`ROADMAP.md`](ROADMAP.md).
+
+## Repository map
+
+```text
+firmware/teensy/        Teensy 4.1 firmware scaffold and protocol/telemetry structs
+host/                   Python host-controller scaffold for RPi/PC side
+shared/schemas/         Contract schemas mirrored from the current software suite
+shared/machine/         Fullum-alpha machine capability profile draft
+docs/                   Cédric-facing implementation docs and checklists
+docs/nick-generated/    Nick-generated source-grounded guidance notes
+scripts/                Utility/validation scripts
+tests/                  Host-side contract/state-machine tests
+```
+
+## Current source alignment
+
+Generated: 2026-05-26. This foundation is a repo scaffold and implementation aid,
+not a replacement for the approved P11 source specifications. If this repo and
+the source specs disagree, ask Antoine before changing architecture, safety,
+telemetry contracts, or scope.