Runbook für den Engineering-Harness

Status: wie an diesem Repository gearbeitet wird (Menschen und Coding-Agenten). Regeln: AGENTS.md.

Einrichtung

make setup               # uv sync, docs-site npm ci, submodules, harness install (hooks, skills, MCP config)

Voraussetzungen: uv ≥ 0.9, Python 3.12 (von uv verwaltet), Node 26 (.nvmrc), PlatformIO (pipx install platformio), Blender 4 für Renderings, Docker für Gazebo, Pango für das PDF (brew install pango).

Prüfungen

Stufe	Befehl	Belegt	Dauer
Q0	make check-fast	ruff, mypy (strikt für core/ntx/workspace), import-linter-Schichten, Drift generierter Dateien (Geometrie-Bindings, Elektronikbericht, NT-X-Assets), Python-Tests mit Coverage, native Firmware-Tests	~1 min
Q1	make verify	CAD: Bohrungsstapel → Befestigungselemente, Durchdringung (4 Posen), Sensor-Sichtfeld, Bewegungsbereichs-Sweep, Passungen/Toleranzen, Festigkeit (Biegung/Knickung der Koppeln, Schraubenscherung, Lochleibung, Lager, Vorbohr-Drehmomente), Freigang in Bewegung	~10 min
Q1	make printability	jedes gedruckte Teil und jede 3MF-Druckplatte mit PrusaSlicer und hardware/print/prusaslicer.ini gesliced (Fehler, Konflikte, Stabilitätsprobleme, fehlende Teile führen zum Abbruch), Wandstärken-Scan, Filament und Zeit	~1 min, benötigt PrusaSlicer
Q1	make check	Q0 + verify + printability + Stücklisten-Abdeckung + CAD-Tests + Docs-Build + Harness-Prüfungen	~13 min
Q2	make smoke	MuJoCo-Laufvideo, MCP-Server über stdio, NT-X-Erweiterung im NT-X-Harness	~2 min
Q2	make sim-gazebo, make rl-smoke	ROS-2- + Gazebo-Lauftest in Docker; PPO-Pipeline	5–10 min
Q3	Hardware	ein gebauter Roboter: Stehen, Laufen, gemessener Strom/gemessene Laufzeit	—

Der Pre-Commit-Hook führt den Harness-Selbsttest aus; die CI (.github/workflows/quality.yml) führt Q0 und den Docs-Build aus.

Hardware ändern

1. Bearbeiten Sie die Quelle: ein CadQuery-Teil in packages/strido-cad/src/strido_cad/parts.py, eine Platzierung, hardware/*.yaml.
2. make cad, wenn sich Kinematik oder Grenzen ändern können, sonst make models.
3. make verify — korrigieren Sie die Geometrie, bis sie besteht; erweitern Sie niemals hardware/verification/*.yaml, nur damit sie besteht. Halten Sie jede bewusste Regeländerung in docs/decisions.md fest.
4. make publish — Druckpaket, Stückliste, Anleitung, Renderings, 3D-Ansicht, Buch.
5. make check-fast, den Lauf in docs/verification.md festhalten.

Agenten-Werkzeuge

• Skills (.agents/skills/): strido-hardware, strido-verification, strido-bringup, strido-docs, strido-ntx, dazu die Harness-Skills (software-engineering, …).
• MCP (.mcp.json, .codex/config.toml): strido-hardware (Teilegrößen, Befestigungselemente, Passungen, Freigänge, Gelenkgrenzen, Pinbelegung, Stückliste, Verifikationsstatus), codegraph (Code-Index).
• CLI: uv run strido part electronics_deck, strido pinout lcd, strido fits --status warn, strido clearances --max-gap 1.

Release

make publish && make package schreibt dist/strido-<version>.zip (Repository + PDF + Laufvideo). Tag strido-v<version>.

Dokumentationsseite auf Cortex

Die Website läuft öffentlich unter strido.cortex.a2olabs.com, auf Englisch und Deutsch (/de/). Das Image (docs-site/Dockerfile, docker-compose.docs.yml + docker-compose.cortex.yml) baut die Website aus dem Repository und bündelt die Downloads: das Bausatz-ZIP (jede STL, die 3MF-Platten, Slicer-Profil, Druckliste, Buch-PDF, Stückliste), das Buch-PDF, das 3D-Modell, das Agent-Skill-ZIP und llms.txt. Ein zweiter Dienst, assistant, beantwortet die KI-Leiste und den MCP-Server /mcp aus denselben Seiten; er erreicht das Modell über Cortex Keyring (models in .cortex/app.yml) und speichert Unterhaltungen in einem Docker-Volume. Die eigene Gateway-Route der App (.cortex/access/caddy/sso/) liefert die Website an alle aus und leitet /api/* und /mcp hinter Cortex-SSO (oder einem Cortex-App-Token) an den Assistenten weiter, sodass die Modellnutzung bei angemeldeten Nutzern bleibt.

make docs & make assistant                                  # local: site with live AI bar on http://127.0.0.1:4173/
docker compose -f docker-compose.docs.yml up --build       # local images: site :4392, assistant :4393
make i18n                                                   # after English changes: new German segments to translate
git push                                                      # Cortex builds from GitHub, not from the checkout
cortex deploy --ref "$(git rev-parse HEAD)"
cortex jobs watch <job-id>
cortex apps show strido

Das Repository ist öffentlich unter github.com. Veröffentliche erst nach make publish und make printability, damit die Downloads zur verifizierten CAD passen.