Skip to content

armgit / SOMA

Public Imported from GitHub
0

Desktop app for designing parametric 3D models in CadQuery together with the coding agent of your choice

Dokumentation: Idee, Plan und Entscheidungslog

Kai-Jungsthoefel65f8b4e7fab9
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..656af86
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,21 @@
+# Abhängigkeiten und Build-Ausgaben
+node_modules/
+app/dist/
+*.tsbuildinfo
+
+# Python
+__pycache__/
+*.pyc
+*.egg-info/
+.venv/
+venv/
+
+# Erzeugte Dateien des Phase-0-Prototyps (entstehen durch run_all.ps1 bzw. make_board_step.py neu)
+prototype/phase0/example/output/
+prototype/phase0/example/.cadide/
+prototype/phase0/example/exports/
+prototype/phase0/basic_example/
+
+# Betriebssystem und Editoren
+Thumbs.db
+.DS_Store
diff --git a/DECISIONS.md b/DECISIONS.md
new file mode 100644
index 0000000..cdca1e5
--- /dev/null
+++ b/DECISIONS.md
@@ -0,0 +1,43 @@
+# Entscheidungslog: CAD-IDE mit KI-Agenten
+
+> Chronologischer Log aller Entscheidungen aus der Planungsphase. Die Nummern werden im [PLAN.md](PLAN.md) referenziert. Spätere Entscheidungen können frühere präzisieren oder ersetzen (in der Spalte „Anmerkung" vermerkt). Stand: 2026-09-29
+
+| # | Thema | Entscheidung | Anmerkung |
+|---|---|---|---|
+| 1 | Basis | Eigene Desktop-App | Kein VS-Code-Fork/Extension. Framework siehe Entscheidung 23 |
+| 2 | Plattformen | Windows, macOS, Linux von Anfang an | Betrifft Python-Bundling, PTY-Terminal, Pfad-Wiederherstellung |
+| 3 | Zielgruppe | Nicht-Programmierer | Python + CAD-Framework werden mitgeliefert (isolierte Umgebung) |
+| 4 | Agent-Setup | Nutzer installiert Agent selbst, App hilft | Erkennung installierter Agenten, Startbuttons, Installationshinweise. Login/Abo beim Nutzer |
+| 5 | Chat-Historie | Nur Projektordner in der ZIP, Chats bleiben lokal | Stabiler Pfad pro Projekt hält Chats auf demselben Rechner erhalten. Auf anderen Rechnern gehen sie verloren (bewusst akzeptiert) |
+| 6 | Modellstruktur | `model.py` als fester Einstiegspunkt, `parts/` für Bauteile, `inputs/` für mitgebrachte Dateien (z. B. STEP), `output/model.step` als Hauptergebnis mit benannten Komponenten | Orientierung an CAD-Konzepten (Part/Assembly/Referenz/Parameter). Einfacher Fall = alles in `model.py`. Ordnernamen im Detail noch offen |
+| 7 | Git / Historie | Jedes Projekt bekommt ein Git-Repo (in der ZIP enthalten). Der **Agent committet selbst** nach sinnvollen Iterationen (Anweisung in `AGENTS.md`) | Nutzer bringt ohnehin einen CLI-Agenten mit, daher kein "unsichtbares Git" nötig |
+| 8 | Git & STEP | `output/model.step`, Skripte und `inputs/` werden getrackt. Abgeleitete Viewer-Daten (Tessellation/Meshes) und Cache in `.gitignore`. Beim Speichern der ZIP committet die App verbliebene Änderungen als **Auto-Snapshot** | Framework-Version wird im Projekt festgehalten (Reproduzierbarkeit) |
+| 9 | Viewer-Technik | Mesh-Viewer (three.js) + Python-Prozess für exakte Werte | Nach jedem Build wird STEP → GLB (mit Bauteilnamen, Farben, Flächen-/Kanten-IDs) tesselliert. Punkt-zu-Punkt und Bounding-Box im Viewer, exakte Messungen (Radius, Durchmesser, Flächenabstand) per Anfrage an Python/OCP. Kein zweiter CAD-Kern im Frontend |
+| 10 | Geometrie ⇄ Code-Mapping | Mitgelieferte **Hilfsbibliothek ist verbindlich**: `model.py` registriert jedes Bauteil über unsere Funktion (z. B. `add_part("Deckel", obj)`) und exportiert darüber. Die Bibliothek merkt sich Datei und Zeile, schreibt Namen in den STEP-Baum und Positionen in `output/model.map.json` | Mapping zunächst nur auf Bauteilebene. Später optional: Flächen-/Feature-Tags. Automatisches Topological-Naming-Tracing bewusst nicht im Scope. Funktionsnamen und API sind noch Entwurf |
+| 11 | Agent-Anbindung | MVP: Screenshots/Skizzen als Datei in `feedback/` (nicht in Git, nur auf Wunsch ins Projekt übernehmen); App fügt Pfad bzw. Auswahltext (Bauteilname, Datei, Zeilen) in die Eingabezeile des Terminals ein, Nutzer schickt selbst ab. Später: MCP-Server der App (Screenshot, Auswahl, Messungen abfragbar) | Agent-unabhängig, funktioniert mit jedem CLI-Agenten |
+| 12 | CAD-Framework | **CadQuery** (fest). OpenSCAD ausgeschlossen (kein STEP/B-Rep) | Begründung: Nutzer kennt CadQuery, größte Community und meiste Trainingsdaten/Datasets. build123d wäre Alternative gewesen (Labels/Farben im STEP belegt, schlankeres Paket, in einer Studie höhere Ausführungsquote). **Zu prüfen:** (a) STEP-Export mit Bauteilnamen bei `cq.Assembly` (Doku deutet auf Verlust im Standardmodus hin; `fused` wäre unbrauchbar) – notfalls eigener XCAF-Export über OCP in der Hilfsbibliothek; (b) Installationsgröße ohne VTK; (c) Python 3.11+ und Versions-Pinning. Gegenmaßnahmen für fehleranfällige Fluent-API: strikte `AGENTS.md`-Idiome, Beispiele, Feedback-Loop (ausführen, messen, rendern) |
+| 13 | Vorgehen / Phasen | **Phase 0:** technischer Prototyp ohne App (Hilfsbibliothek, STEP mit Bauteilnamen/Farben, GLB mit Flächen-IDs, Klick→Codezeile-Mapping, Python-Einbettung, einfacher Browser-Viewer). **Phase 1:** MVP-Kern als Desktop-App (Projekt neu/speichern/öffnen als ZIP mit Git, Editor, Terminal mit Agent, Viewer mit Bauteilbaum und Ein-/Ausblenden, Screenshot mit Markup, `AGENTS.md`). **Danach:** Messen, Schnittansicht, Versions-Schieber, Skills, MCP (siehe Entscheidung 22) | Riskanteste Annahmen werden in Phase 0 günstig geprüft |
+| 14 | Phase-0-Umfang | Fünf Prüfpunkte: (1) STEP mit Bauteilnamen/Farben (ca. 5 Bauteile, Baum nach Export + Reimport intakt); (2) GLB mit Flächen-IDs (eigener Mesher, Dreiecksbereich pro Fläche); (3) Klick im Browser-Viewer → Datei + Zeile aus `model.map.json`; (4) Import eines mitgebrachten STEP, Messen, Aussparung, Anzeige als Referenzobjekt; (5) isolierte Python-Umgebung mit CadQuery ohne VTK, Installationsgröße gemessen | Agent-Test (Agent baut Beispielmodell mit erster `AGENTS.md`) folgt in Phase 1 |
+| 15 | Grundlayout | Von links nach rechts: **Tree** → **Editor (optional, ein-/ausblendbar)** → **3D-Viewer / 2D-Sketch** (gleicher Bereich, umschaltbar) → **Terminal** rechts mit mehreren Tabs. **Top Bar** für Optionen und Operationen | Tree hat zwei Reiter: **Modell** (Bauteilbaum, Standard; Ein-/Ausblenden, Klick → Viewer + Codezeile) und **Dateien** (Dateibaum, Drag-and-drop für Inputs). **Versions-Schieber** als Leiste unter dem Viewer. Offen: Ist der Mittelbereich Tab-Umschaltung oder Split (Viewer/Sketch)? Docking später |
+| 16 | 2D-Sketching | Nur **Bild-Markup ohne Maßhaltigkeit**: Zeichnen auf Viewer-Screenshots und auf leerer Fläche (Freihand, geometrische Formen, Pfeile, Text). Ergebnis ist ein PNG in `feedback/`, Pfad wird dem Agenten übergeben. Maße stehen als Text daneben | Kein Constraint-Sketcher. Bei späterem Bedarf eigenes Teilprojekt |
+| 17 | Skills | Aktivierte Skills werden als Markdown nach `skills/` im Projekt kopiert und in der `AGENTS.md` aufgelistet (App pflegt die Liste bei An-/Abwahl). Agentenunabhängig, wandert mit ZIP und Git. MVP mit wenigen **mitgelieferten** Skills (z. B. 3D-Druck, Toleranzen, Gehäusebau) | Eigene Nutzer-Skills später. Aktivierung pro Projekt (Projekteinstellungen). Inhalt der Skills noch zu erarbeiten |
+| 18 | AGENTS.md | **Zwei getrennte Dateien:** app-verwaltete `AGENTS.md` (Konventionen, Skill-Liste, Git-Regeln, Hilfsbibliothek; wird bei App-Updates erneuert, Nutzer ändert sie nicht) und nutzerverwaltete Notizdatei (Arbeitsname z. B. `NOTES.md`; Projektnotizen von Nutzer/Agent, wird nie überschrieben). `AGENTS.md` verweist auf die Notizen. Für Claude Code zusätzlich `CLAUDE.md` als Verweis auf `AGENTS.md` | Risiko: Nicht jeder Agent folgt Verweisen zuverlässig, daher Verweis in `AGENTS.md` ganz oben und explizit formulieren; im Agent-Test prüfen. Versionsnummer in `AGENTS.md` für Updates. Dateiname der Notizen noch offen |
+| 19 | Terminal | **Freies Terminal** (normale Shell-Tabs im Projektordner) + **Startvorlagen** (Buttons starten erkannte Agenten wie Claude Code, OpenCode per Befehl) + **Auto-Start** des zuletzt benutzten Agenten beim Öffnen, **ohne automatisches Resume** (kein `--continue` o. Ä.). Mehrere Tabs möglich | Interpretation: Auto-Start bleibt, nur das Fortsetzen der Session entfällt. Falls Auto-Start ebenfalls nicht gewünscht ist, bitte korrigieren. Nutzer kann Sessions im Agenten selbst fortsetzen |
+| 20 | Build | **Auto-Build bei Änderung** von `model.py`/`parts/` (Hintergrund, Debounce, abbrechbar), **abschaltbar**; dann Build manuell per **Knopf** oder durch den **Agenten**. Gemeinsamer Build-Befehl für App und Agent (Arbeitsname `cadide build`, in `AGENTS.md` festgelegt) erzeugt STEP, GLB und Mapping aus einem Lauf | Grund für Abschaltbarkeit: Große Modelle bauen lange und würden die App lahmlegen. Offen: Standard an/aus, Statusanzeige und Fehlerpanel, Verhalten wenn ein Build läuft und die Datei sich erneut ändert |
+| 21 | Speichern/Öffnen | Jedes Projekt hat eine **feste ID (UUID)** in der ZIP (z. B. `project.json`). Arbeitsordner immer unter `<App-Daten>/workspaces/<uuid>/` (nicht im OS-Temp, damit er nicht aufgeräumt wird). Beim Öffnen: Ordner existiert nicht → ZIP entpacken; Ordner existiert mit ungespeicherten Änderungen oder Abweichung → **Rückfrage** (Wiederherstellen oder ZIP laden). **Speichern nur ausdrücklich** (kein Autosave in die ZIP), dazu Absturz-Wiederherstellung | Neue Projekte starten im Arbeitsordner ohne ZIP, bis der Nutzer erstmals speichert. Offen: Erkennung von Abweichungen (Zeitstempel oder Git-Commit), mehrere Fenster/Projekte parallel, Aufräumen alter Workspaces, Verhalten bei ZIP auf Netzlaufwerk |
+| 22 | Viewer-Umfang | **Phase 1 (MVP):** Navigation, Standardansichten (Vorne/Oben/Iso), Darstellungsmodi (schattiert, Kanten, Drahtgitter, Transparenz), Ein-/Ausblenden über den Modell-Tree, Klick auf Bauteil → Codezeile, **Screenshot mit Markup** (Kernvorteil ggü. normalen IDEs). **Danach:** Messen (Punkt-zu-Punkt, Bounding-Box, exakte Werte), Schnittansicht (wichtig für Gehäuse/Wandstärken), Versions-Schieber. **Später:** Volumen/Gewicht, Versionsvergleich, Explosionsansicht | Ändert Entscheidung 13: Screenshot/Markup rückt in Phase 1 vor, Messen und Schnitt folgen direkt danach |
+| 23 | Desktop-Framework | **Electron** (TypeScript). Terminal: xterm.js + node-pty. Python-Prozess für CAD als Kindprozess | Gründe: Einheitliches Chromium auf allen 3 OS (WebGL/three.js identisch), erprobtes Terminal, großes Ökosystem, Größe spielt wegen mitgeliefertem Python kaum eine Rolle. Konkretisiert Entscheidung 1 |
+| 24 | Python-Anbindung | **Langlebiger Python-Dienst pro Projekt** für die App (Modell und importierte STEP im Speicher, schnelle Messungen; Kommunikation z. B. JSON über stdin/stdout oder lokalen Socket) **plus** eigenständiger **Einmal-Prozess** für den Build-Befehl des Agenten (funktioniert auch ohne laufende App) | Offen: Abstürze/Neustart/Abbrechen des Dienstes; Pakete siehe Entscheidung 25 |
+| 25 | Python-Pakete | **Basisumgebung** (Python + CadQuery) bleibt unverändert. Pro Projekt eine **eigene Umgebung** im Arbeitsordner (nicht in der ZIP). Jedes Terminal startet mit **aktivierter Projektumgebung im PATH**, der Agent nutzt **normales `pip`/`python -m pip`**. Die App liest installierte Pakete per `pip freeze` aus (nach Build und beim Speichern), zieht die Basispakete ab und schreibt eine gepinnte **Paketliste** (z. B. `requirements.txt`) ins Projekt (ZIP und Git). Beim Öffnen auf einem anderen Rechner wird die Umgebung aus der Liste neu aufgebaut. App zeigt neu hinzugekommene Pakete an | Ersetzt den ursprünglichen Vorschlag `cadide add` (Idee des Nutzers, einfacher und robuster). Keine Bestätigung pro Paket. Offen: Agent nutzt anderes Python an der Umgebung vorbei (`--user`, voller Pfad), Offline-Fall, Paketcache, Installation beim Öffnen ohne Internet |
+| 26 | Ordnerstruktur | **Hauptordner:** `AGENTS.md`, `CLAUDE.md`, `NOTES.md`, `requirements.txt`, `model.py`, `parts/`, `inputs/`, `output/model.step`. **`.cadide/`:** `project.json` (ID, App-/Framework-Version, aktive Skills), `skills/`, `feedback/`, GLB-Cache, `model.map.json`. Dazu `.git/` und `.gitignore` | Präzisiert 6, 10, 11, 17: Skills, Feedback und Mapping liegen unter `.cadide/` (Pfade in diesen Zeilen entsprechend lesen). `output/model.step` bleibt im Hauptordner. Skills liegen in einem versteckten Ordner, `AGENTS.md` muss sie daher mit vollem Pfad nennen. Dateibaum der App kann App-Dateien ausblenden. Offen: was von `.cadide/` getrackt wird (`project.json`, `skills/` ja; `feedback/` und Cache nein) |
+| 27 | Projektzustand | Wichtiger Zustand (ID, Einstellungen, aktive Skills, Hauptdatei) liegt **doppelt**: `.cadide/project.json` im Projekt (wandert in die ZIP) und eine **Kopie in den App-Daten** (`<App-Daten>/workspaces/<uuid>/state.json`). Bei Löschung oder Beschädigung Wiederherstellung aus der Kopie; bei Abweichung Zeitstempel bzw. Rückfrage. ZIP ohne Kopie (anderer Rechner): Datei aus der ZIP gilt | Setzt Regel 4 des Leitprinzips um. Restrisiko: Arbeitsordner und App-Daten beide verloren, dann zählt nur die letzte ZIP |
+| 28 | Struktur-Check als CLI | Befehl **`cadide check`**: **nur prüfen und melden, nie automatisch reparieren** (kein `--fix`). Verständliche Ausgabe mit **konkreten Handlungshinweisen** (was ist falsch, was ist zu tun), zusätzlich maschinenlesbar. Der Agent behebt Probleme selbst anhand der Hinweise, mehrdeutige Fälle gehen als Frage an den Nutzer. **Derselbe Code** wie der Projekt-Check der App. `cadide build` führt vorab einen kurzen Check aus und gibt Warnungen mit aus. Die App prüft zusätzlich unabhängig vom Agenten (Öffnen, Bauen, Speichern) | Entscheidung des Nutzers: Der Agent kann den Workspace prüfen und sich Fehler anzeigen lassen und **repariert dann nach eigenem Ermessen**. Kein `--fix`, **kein Reparieren-Button** in der App (ersetzt den Vorschlag mit drei Reparaturklassen). **Offen:** (a) Ob das Wiederherstellen von `project.json` aus der App-Kopie (Entscheidung 27) trotzdem automatisch geschehen darf, oder nur gemeldet wird (Vorschlag: als App-Zustand automatisch wiederherstellen und dem Nutzer anzeigen); (b) Format der maschinenlesbaren Ausgabe |
+| 29 | Sicherheit | **Keine Sandbox, kein eigener Schutz vor dem Agenten.** Für Schutz sind **Nutzer und Agenten-Harness verantwortlich**. Das ist ein Grund, keinen eigenen Harness zu bauen (sonst wären wir für das Verhalten des Agenten verantwortlich). Die App startet Terminals im Projektordner mit der Projektumgebung, mehr nicht | Beim ersten Start ein klarer Hinweis, dass der Agent mit den Rechten des Nutzers läuft (Vorschlag, nicht bestätigt). Projekt-Check und Zustandskopie (27, 28) sind Robustheit, keine Sicherheit. Sandbox nicht geplant |
+| 30 | Ziel / Lizenz | **Open Source.** Konkrete Lizenz noch offen (MIT oder Apache-2.0 naheliegend, vereinbar mit CadQuery Apache-2.0, Electron/three.js/xterm.js MIT, OpenCascade LGPL). Folgen: Installer für 3 OS, Auto-Updates, öffentliches Repo, Doku, Community-Support | Zu prüfen: Lizenzen aller mitgelieferten Komponenten (Python, OCP/OpenCascade, VTK falls doch mitgeliefert, Git), Code-Signing für Windows/macOS, Updater |
+| 31 | Git-Bereitstellung | **Git wird mitgeliefert** (eingebettetes Git, z. B. dugite, für alle drei OS, gleiche Version bei allen Nutzern) und in den PATH der Terminals gelegt. Agent und App nutzen dasselbe `git` | Lizenztexte (Git ist GPL) beilegen. Offen: Konkrete Einbettung, Updates des Git-Binaries |
+| 32 | Auslieferung | **Nur eine Variante: „alles drin"** (Python, CadQuery, Git mitgeliefert). **Kein Bring-your-own** und keine Lite-Variante geplant | Grund: eine getestete Umgebung, keine Testmatrix aus fremden Versionen, passt zum Leitprinzip der Robustheit. Ein späterer Installer mit Nachladen der geprüften Umgebung bleibt denkbar, ist aber nicht geplant |
+| 33 | Importe / Fremd-STEP | Mitgebrachte Dateien werden einfach **in `inputs/` abgelegt** (Drag-and-drop im Dateien-Tab). Der **Agent bindet sie im Skript ein** (nur dort ist die Position festgelegt). Der Viewer kann **beliebige weitere STEP-Dateien anzeigen**, dann im Basismodus **ohne** Bauteilbaum-Mapping, Klick→Code und weitere Zusatzfunktionen. **Standardanzeige ist immer das Hauptmodell** (`output/model.step`) | Deckt sich mit Rückfallweg (Regel 2 des Leitprinzips). Rollen siehe Entscheidung 34 |
+| 34 | Export & Rollen | **`output/model.step` enthält immer alles**, auch Referenzen. **Export einzelner Bauteile** über einen **Befehl** (Arbeitsname `cadide export <Bauteil\|--all> --format <step\|stl\|…>`) und über das **Kontextmenü im Modell-Tree**, jeweils auf Basis der registrierten Bauteile und des gebauten Modells. Ausgabe nach `exports/`. Kein Exportcode im Skript nötig (bleibt erlaubt, ist aber nicht der vorgesehene Weg). Die Hilfsbibliothek kennt die Rolle **`reference`** (`add_part(..., role=...)`) nur als **Markierung**: halbtransparent im Viewer, eigener Ast im Tree, standardmäßig nicht in `--all` | **Offen/zu prüfen in Phase 0:** unterstützte Formate über STEP und STL hinaus (3MF, AMF, DXF, SVG); Verhalten bei veraltetem Modell (Hinweis oder vorher bauen); ob `exports/` getrackt wird. Rolle im Code gesetzt, kein Umwidmen per App. Rolle `reference` und Standardwerte sind Vorschlag und noch nicht ausdrücklich bestätigt |
+| 35 | Versions-Schieber: Zurückspringen | Der Schieber zeigt alte Stände als **Vorschau** (STEP per `git show`, Arbeitsordner unberührt). Ein Knopf **Stand wiederherstellen** kopiert die Dateien des gewählten Stands in den Arbeitsordner und legt einen **neuen Commit** an. Historie bleibt vollständig, kein Checkout/Reset, keine Branches. Warnung bzw. Sperre bei uncommitteten Änderungen | Konkretisiert 7, 8. Offen: Ob der Agent währenddessen weiterarbeitet (Sperre?), Umgang mit Änderungen des Agenten am Repo (Branch-Wechsel, Reset, History-Umschreiben, siehe Störfall-Tabelle), Beschriftung der Punkte (Commit-Nachricht, Vorschaubild) |
+| 36 | Updates | Die **Hilfsbibliothek** (Paket `cadide`) liegt in der **mitgelieferten Basisumgebung**, nicht im Projekt. Neue App-Versionen bringen sie mit, alte Projekte profitieren von Fixes. **`api_version` in `project.json`** sichert Abwärtskompatibilität. Beim Öffnen eines Projekts mit älterer Regelversion wird die app-verwaltete **`AGENTS.md`** (laut Entscheidung 18 ganz app-verwaltet, Notizen liegen getrennt) und **`skills/`** erneuert, **dem Nutzer angezeigt** und als **Commit gesichert** | Die Projektumgebung (25) muss die Basisumgebung sehen, damit `cadide` importierbar bleibt. Offen: Regeln für Abwärtskompatibilität der API (wie lange werden alte `api_version` unterstützt), was passiert, wenn ein Projekt eine **neuere** `api_version` hat als die App, Auto-Update der App selbst (Updater, Signierung) |
+| 37 | Installationsgröße | **Vorerst nicht optimieren.** Die volle CadQuery-Umgebung wird genommen, wie sie ist (inklusive aller VTK-Bibliotheken). | Präzisiert 31 und 32. Auslöser war die Messung in Phase 0: OCP hängt hart an VTK, `import cadquery` lädt alle 209 VTK-DLLs, gut 0,7 bis 1,0 GB installiert. Details in `prototype/phase0/ERGEBNISSE.md`. Optimierung (Casadi, VTK-Teilmenge, Komprimierung) bleibt für später |
diff --git a/IDEA.md b/IDEA.md
new file mode 100644
index 0000000..6927c31
--- /dev/null
+++ b/IDEA.md
@@ -0,0 +1,93 @@
+# Ursprungsidee: CAD-IDE mit KI-Agenten
+
+> Stand: 2026-09-29 · Status: Ursprungsidee (Konzeptphase, noch keine Umsetzung)
+
+## 1. Kurzbeschreibung
+
+Ein Desktop-Programm für CAD-Arbeit zusammen mit KI-Agenten. Der Nutzer entwirft 3D-Modelle im Dialog mit einem Coding-Agenten, der Code (z. B. CAD-Skripte) schreibt und ausführt. Das Ergebnis ist ein 3D-Modell (STEP), das direkt im Programm angezeigt, geprüft und per Feedback iterativ verbessert wird.
+
+Technisch ist das Programm im Kern eine **IDE mit integrierter Konsole**, in der der Nutzer den Coding-Agenten seiner Wahl laufen lässt (Claude Code, OpenCode, …). Darum herum liegen CAD-spezifische Werkzeuge und ein Workflow, der sich wie 3D-Modellierung anfühlt, nicht wie Softwareentwicklung.
+
+## 2. CAD-Grundlage: Code-basierte CAD-Frameworks
+
+Die 3D-Modelle entstehen **per Code** mit einem Coding-CAD-Framework. Der Agent schreibt und ändert das Skript, das Skript erzeugt die STEP-Datei, der Viewer zeigt sie an.
+
+Das Framework ist **fest vorgegeben** (kein Wechsel durch den Nutzer). Das vereinfacht Konventionen, `CLAUDE.md`/`AGENTS.md`, Skills und das Mapping zwischen Viewer und Code. **Welches Framework das ist, ist noch offen und muss geprüft werden.** Kandidaten: CadQuery (Favorit, da bereits im Fokus), build123d, OpenSCAD u. a.
+
+## 3. Grundprinzip: Kein eigener Harness
+
+Wir bauen **keinen eigenen Agenten-Harness**, sondern nutzen bestehende (Claude Code, OpenCode, …) in einer eingebetteten Konsole.
+
+**Vorteile**
+- Deutlich weniger Entwicklungsaufwand: Agentenlogik, Tool-Use, Kontextverwaltung usw. kommen fertig mit.
+- Maximale Flexibilität: Der Nutzer wählt den Agenten, den er kennt, bezahlt oder bevorzugt.
+- Wir profitieren automatisch von der Weiterentwicklung der Harnesses.
+
+## 4. Abgrenzung zu einer normalen IDE (z. B. VS Code)
+
+Was macht das Projekt mehr als „VS Code mit Terminal"? Sieben Kernunterschiede:
+
+### 4.1 Workflow: „3D-Modell" statt „Code-Projekt"
+
+- Ein „Projekt" ist eine **einzelne ZIP-Datei**, die frei verschoben, geteilt und archiviert werden kann.
+- Beim Neuanlegen wird zunächst in einem **temporären Verzeichnis** gearbeitet, bis der Nutzer das Modell speichert.
+- Beim Speichern wird der Projektordner als ZIP abgelegt.
+- Beim Öffnen wird **derselbe Temp-Ordner (gleicher Pfad) wiederhergestellt**. Dadurch bleiben Chatverläufe und Konfigurationen der KI-Agenten erhalten – diese werden von den Harnesses meist separat und mit Referenz auf den Arbeitsordner gespeichert.
+- Für den Nutzer fühlt es sich an wie „ein 3D-Modell erstellen und speichern", nicht wie „ein Coding-Projekt starten".
+
+### 4.2 Integrierte Agenten-Anweisungen (`CLAUDE.md` / `AGENTS.md`)
+
+- Eine mitgelieferte, von der Software verwaltete Anweisungsdatei erklärt dem Harness, wie er vorgehen soll, welche Möglichkeiten es gibt und welche Konventionen gelten.
+- Sie definiert u. a. die **Struktur von Code und Ausgabedateien** – Voraussetzung für viele weitere Funktionen der Software.
+
+### 4.3 Integrierter 3D-Viewer
+
+- Zeigt die **STEP-Datei direkt** an.
+- Objekte ein-/ausblenden, Visualisierungsoptionen.
+- **Messfunktionen** (Nachmessen am Modell).
+- Wenn möglich: **Objekt im Viewer anklicken → zugehörige Codestelle wird im Editor hervorgehoben** (Rückverfolgung Geometrie → Code).
+- **Screenshots** des Viewers mit einem Klick speichern und **in diesen Bildern skizzieren/markieren**, um dem Agenten visuell mitzuteilen, was geändert werden soll.
+
+### 4.4 2D-Sketching-Tool
+
+- Freihandzeichnen, geometrische Formen, Text usw.
+- Dient als visuelle Kommunikation mit dem Agenten (Skizzen, Anmerkungen, Vorlagen).
+
+### 4.5 Feste Dateistruktur und Namenskonventionen
+
+- Ein fest definiertes Layout im Projekt, damit die Software Inhalte eindeutig zuordnen kann.
+- Beispiel: Die Software weiß immer, **welches das Skript** ist und **welche die Haupt-Ausgabedatei** ist.
+
+### 4.6 Skills (weitere Markdown-Dateien)
+
+- Regelwerke für spezifische Anforderungen, z. B. **3D-Druck** und **Toleranzen**.
+- Werden nur angewendet, wenn der Nutzer sie für das Modell aktiviert hat.
+
+### 4.7 Integrationen mit gängigen KI-Harnesses (wenn möglich)
+
+- Z. B. markierter Code, Viewer-Auswahl oder Screenshots werden **direkt in den Chat des Agenten übernommen**.
+- Ziel: nahtlose Zusammenarbeit zwischen Editor/Viewer/Sketching und dem Agenten.
+
+## 5. Überblick der Bausteine
+
+| Baustein | Zweck |
+|---|---|
+| Code-Editor | Skripte ansehen und bearbeiten |
+| Eingebettete Konsole | Beliebiger Coding-Agent (Claude Code, OpenCode, …) |
+| 3D-Viewer (STEP) | Anzeigen, Messen, Ein-/Ausblenden, Auswahl, Screenshots |
+| 2D-Sketching | Skizzen und Markierungen als Feedback an den Agenten |
+| Projektverwaltung | Temp-Ordner ⇄ ZIP, wiederherstellbarer Arbeitskontext |
+| Agenten-Anweisungen | Integrierte `CLAUDE.md`/`AGENTS.md` mit Konventionen |
+| Skills | Zuschaltbare Regelwerke (3D-Druck, Toleranzen, …) |
+| Harness-Integrationen | Auswahl/Screenshots direkt in den Agenten-Chat |
+
+## 6. Offene Punkte für die nächste Phase
+
+Nicht Teil der Ursprungsidee, aber absehbar zu klären:
+
+- Technologiewahl (Desktop-Framework, Terminal-Einbettung, Editor-Komponente, 3D-Kernel/Viewer für STEP).
+- **Framework-Evaluation:** Welches Coding-CAD-Framework wird das feste Framework (CadQuery, build123d, OpenSCAD, …)? Mögliche Kriterien: Qualität des Agenten-generierten Codes, STEP-Export, Möglichkeit zur Zuordnung Geometrie ⇄ Code (Namen/Labels/Assemblies), Reife und Community, Lizenz, Verteilbarkeit mit der Software (Python-Einbettung), Performance.
+- Mapping Geometrie ⇄ Code (wie werden Objekte im STEP identifizierbar mit Codestellen verknüpft?).
+- Konkrete Ordnerstruktur und Namenskonventionen im Projekt.
+- Wie stabil und portabel ist die Wiederherstellung des Temp-Pfads (Pfadabhängigkeit der Agenten-Chatverläufe)?
+- Schnittstellen der einzelnen Harnesses für Integrationen (Kontext einfügen, Bilder übergeben).
diff --git a/PLAN.md b/PLAN.md
new file mode 100644
index 0000000..1c73a18
--- /dev/null
+++ b/PLAN.md
@@ -0,0 +1,234 @@
+# Plan: CAD-IDE mit KI-Agenten
+
+> Stand: 2026-09-29 · Status: **Phase 0 abgeschlossen** ([Ergebnisse](prototype/phase0/ERGEBNISSE.md)), **Phase 1 begonnen** (Schritt 1 läuft, siehe Abschnitt 10 und [app/README.md](app/README.md))
+> Ursprung: [IDEA.md](IDEA.md) · Begründungen und Historie: [DECISIONS.md](DECISIONS.md)
+> Zahlen in Klammern, z. B. (E12), verweisen auf Entscheidungen im Log.
+
+## 1. Vision
+
+Eine Desktop-App, in der ein Nutzer zusammen mit einem KI-Coding-Agenten seiner Wahl (Claude Code, OpenCode, …) 3D-Modelle entwirft. Technisch ist sie eine IDE mit Terminal, Editor und einem eingebauten 3D-Viewer. Sie fühlt sich aber an wie „ein 3D-Modell erstellen und speichern", nicht wie „ein Coding-Projekt starten". Ein Modell ist eine ZIP-Datei, die man frei verschieben kann.
+
+**Abgrenzung zu VS Code:** Modell-Workflow (ZIP, Versions-Schieber), integrierter STEP-Viewer mit Klick auf Code, Screenshot mit Markup als Rückmeldung an den Agenten, feste Projektstruktur, Skills für 3D-Druck und Toleranzen.
+
+**Zielgruppe:** Nicht-Programmierer, die einen eigenen CLI-Agenten mitbringen (E3, E4). **Ziel:** Open Source (E30). **Plattformen:** Windows, macOS, Linux von Anfang an (E2).
+
+## 2. Grundsätze
+
+1. **Kein eigener Harness** (E29). Agenten, Berechtigungen und Schutz vor dem Agenten liegen bei Nutzer und Agent, nicht bei uns. Keine Sandbox.
+2. **Agentenunabhängig.** Wir setzen nur auf Dateien, Text und Kommandozeile, nicht auf Eigenheiten einzelner Agenten. Tiefere Integration (MCP) kommt später (E11).
+3. **Der Code ist die Wahrheit.** Änderungen am Modell laufen über das Skript. Die App schreibt den Modellcode nicht selbst, sondern übergibt Aufträge an den Agenten (E11, E34).
+4. **Eine getestete Umgebung.** Python, CadQuery und Git werden mitgeliefert, kein Bring-your-own (E31, E32).
+5. **Robust gegen Abweichungen des Agenten**, siehe Abschnitt 9. Dieser Grundsatz gilt für alle anderen.
+
+## 3. Architektur
+
+```
++---------------------- Electron-App (TypeScript) ----------------------+
+| Oberfläche: Tree | Editor | 3D-Viewer / Sketch | Terminal-Tabs |
+| Hauptprozess: Projekte, ZIP, Git, Dateiüberwachung, Prozessverwaltung |
++-----------+-------------------------------+---------------------------+
+ | |
+ Terminals (xterm.js + node-pty) Python-Dienst pro Projekt (langlebig)
+ Shell im Projektordner, Modell im Speicher, Build, Mesher,
+ Projektumgebung im PATH, Messungen (OCP/OpenCascade)
+ mitgeliefertes git |
+ | |
+ CLI-Agent (Claude Code, …) Paket `cadide` (Basisumgebung)
+ nutzt `cadide build|check|export` Hilfsbibliothek + CLI
+```
+
+- **Desktop:** Electron, TypeScript (E23). Editor: Monaco oder CodeMirror (offen).
+- **Python-Dienst:** Pro Projekt ein langlebiger Prozess für die App (schnelle Messungen, Modell im Speicher). Der Build-Befehl des Agenten läuft zusätzlich als eigenständiger Einmal-Prozess und funktioniert auch ohne App (E24).
+- **CAD-Framework:** **CadQuery**, fest (E12). OpenSCAD ist ausgeschlossen (kein STEP, kein B-Rep).
+- **Viewer:** three.js zeigt ein GLB, das nach jedem Build aus der STEP-Datei erzeugt wird (Bauteilnamen, Farben, Flächen- und Kanten-IDs). Exakte Messwerte (Radius, Flächenabstand) fragt die App beim Python-Dienst ab. Es gibt keinen zweiten CAD-Kern im Frontend (E9).
+
+## 4. Projektformat
+
+**Ein Projekt ist eine ZIP-Datei.** Die App arbeitet in einem Arbeitsordner (E21):
+
+- Jedes Projekt hat eine feste **UUID**. Der Arbeitsordner liegt immer unter `<App-Daten>/workspaces/<uuid>/`, nicht im OS-Temp.
+- Neue Projekte starten im Arbeitsordner ohne ZIP, bis der Nutzer zum ersten Mal speichert.
+- **Speichern nur ausdrücklich**, kein Autosave in die ZIP. Dazu Absturz-Wiederherstellung.
+- **Öffnen:** Existiert der Arbeitsordner nicht, wird die ZIP entpackt. Existiert er mit ungespeicherten Änderungen oder Abweichungen, **fragt die App nach** (wiederherstellen oder ZIP laden).
+- Der stabile Pfad hält die **Agenten-Chats auf demselben Rechner** erhalten. Auf einem anderen Rechner gehen sie verloren, das ist bewusst akzeptiert (E5).
+
+**Ordnerstruktur (E26)**
+
+```
+<projekt>/
+├── AGENTS.md app-verwaltet: Regeln, Konventionen, Skill-Liste, Git-Regeln, Befehle
+├── CLAUDE.md Verweis auf AGENTS.md (für Claude Code)
+├── NOTES.md Nutzer/Agent, wird nie überschrieben (Arbeitsname)
+├── requirements.txt gepinnte Pakete, von der App aus `pip freeze` gepflegt
+├── model.py fester Einstiegspunkt
+├── parts/ Bauteile (optional)
+├── inputs/ mitgebrachte Dateien (z. B. STEP), Drag-and-drop im Dateien-Tab
+├── output/
+│ └── model.step Hauptergebnis mit allen Bauteilen, benannt, farbig
+├── exports/ Einzelexporte (Ort noch nicht festgelegt)
+├── .cadide/
+│ ├── project.json ID, App-/Framework-Version, api_version, aktive Skills, Hauptdatei
+│ ├── skills/ aktivierte Skills als Markdown
+│ ├── feedback/ Screenshots und Skizzen (nicht in Git)
+│ ├── model.map.json und GLB-Cache (nicht in Git)
+└── .git/ .gitignore
+```
+
+Einfacher Fall: alles steht in `model.py`. Bei wachsender Komplexität lagert der Agent Bauteile nach `parts/` aus (E6).
+
+**Git (E7, E8, E35)**
+
+- Jedes Projekt bekommt ein Git-Repo, das in der ZIP mitwandert. Das Git-Binary wird mitgeliefert (E31).
+- Der **Agent committet selbst** nach sinnvollen Iterationen (Anweisung in `AGENTS.md`). Beim Speichern legt die App verbliebene Änderungen als **Auto-Snapshot** an.
+- **Getrackt:** Skripte, `inputs/`, `output/model.step`, `requirements.txt`, `project.json`, `skills/`. **Nicht getrackt:** GLB-Cache, Mapping, `feedback/`.
+- **Versions-Schieber:** Leiste unter dem Viewer, Commits als Punkte, letzter Punkt ist der aktuelle Arbeitsstand. Alte Stände sind **Vorschau** (STEP per `git show`, Arbeitsordner bleibt unberührt). Der Knopf **„Stand wiederherstellen"** kopiert die Dateien und legt einen **neuen Commit** an. Es gibt keinen Checkout oder Reset und keine Branches.
+
+**Projektzustand (E27):** ID und Einstellungen liegen doppelt: in `.cadide/project.json` (ZIP) und als Kopie in den App-Daten. Bei Verlust dient die jeweils andere Quelle als Rückfall.
+
+## 5. Hilfsbibliothek und Befehle (`cadide`)
+
+Das Paket `cadide` liegt in der mitgelieferten **Basisumgebung**, nicht im Projekt. Neue App-Versionen bringen es mit, alte Projekte profitieren von Fixes. `api_version` in `project.json` sichert die Abwärtskompatibilität (E36). Die Namen sind Arbeitsnamen.
+
+| Baustein | Aufgabe |
+|---|---|
+| `add_part("Deckel", obj, role=...)` | Bauteil registrieren (verbindlich, E10). Merkt sich Datei und Zeile, schreibt Namen und Farbe in den STEP-Baum, Positionen und Anzeigename in `model.map.json`. **Namen in der STEP nur ASCII** (Umlaute werden umgeschrieben, sonst zerstört der Export sie), Namen müssen eindeutig sein. Rolle `reference` ist eine Markierung (halbtransparent, eigener Ast, nicht in `--all`) |
+| `cadide build` | Baut STEP, GLB und Mapping in einem Lauf. Gemeinsam für App und Agent. Führt vorab einen kurzen Check aus und gibt Warnungen mit aus (E20) |
+| `cadide check` | Prüft die Projektstruktur und **meldet nur**, mit konkreten Handlungshinweisen, auch maschinenlesbar. Kein `--fix`. Der Agent repariert nach eigenem Ermessen (E28) |
+| `cadide export <Bauteil\|--all> --format …` | Einzelexport auf Basis der registrierten Bauteile, auch per Kontextmenü im Tree. Formate (in Phase 0 geprüft): STEP, STL, 3MF, AMF, BREP, IGES, OBJ, VRML, GLB/GLTF. 2D: DXF (Schnitt), SVG (Projektion) (E34) |
+
+**Bauen (E20):** Auto-Build bei Änderung von `model.py` und `parts/` (Hintergrund, Debounce, abbrechbar). Er ist **abschaltbar**, weil große Modelle sonst die App bremsen. Dann baut der Nutzer per Knopf oder der Agent per Befehl.
+
+**Pakete (E25):** Die Basisumgebung bleibt unverändert. Jedes Projekt hat eine eigene Umgebung im Arbeitsordner (nicht in der ZIP), die die Basis sieht. Jedes Terminal startet mit **aktivierter Projektumgebung im PATH**, der Agent nutzt normales `pip`. Die App liest die Pakete per `pip freeze` aus und pflegt `requirements.txt`. Auf einem anderen Rechner wird die Umgebung daraus neu aufgebaut.
+
+## 6. Agenten-Anbindung
+
+- **Terminal (E19):** Freies Terminal mit mehreren Tabs im Projektordner. Startbuttons für erkannte Agenten. Der zuletzt benutzte Agent startet beim Öffnen automatisch, **ohne Resume**. Der Nutzer installiert den Agenten selbst, die App hilft mit Erkennung und Hinweisen (E4).
+- **`AGENTS.md` (E18):** Ganz app-verwaltet, Notizen stehen getrennt in `NOTES.md`. Beim Öffnen eines Projekts mit älterer Regelversion wird sie erneuert, dem Nutzer angezeigt und als Commit gesichert (E36). Der Verweis auf die Notizen steht ganz oben.
+- **Skills (E17):** Markdown-Regeln (z. B. 3D-Druck, Toleranzen, Gehäusebau), pro Projekt aktivierbar. Aktivierte Skills liegen in `.cadide/skills/` und stehen mit vollem Pfad in `AGENTS.md`. Zunächst nur mitgelieferte, eigene Nutzer-Skills später.
+- **Rückmeldung an den Agenten (E11):** Screenshots, Skizzen und Auswahlen (Bauteilname, Datei, Zeilen) landen als Datei in `.cadide/feedback/`. Die App fügt Pfad oder Text in die Eingabezeile des Terminals ein, der Nutzer schickt selbst ab. Später kommt ein MCP-Server der App dazu.
+
+## 7. Oberfläche und Viewer
+
+**Layout (E15):** Von links nach rechts **Tree** (Reiter *Modell* mit Bauteilbaum und *Dateien*), optionaler **Editor**, **3D-Viewer / 2D-Sketch** im Mittelbereich, **Terminal** rechts mit Tabs. Oben eine **Top Bar** für Optionen und Operationen. Der **Versions-Schieber** sitzt unter dem Viewer.
+
+**Viewer (E22, E33):**
+
+| Phase | Funktionen |
+|---|---|
+| **Phase 1 (MVP)** | Navigation, Standardansichten, Darstellungsmodi (schattiert, Kanten, Drahtgitter, Transparenz), Ein-/Ausblenden über den Tree, Klick auf Bauteil → Codezeile, **Screenshot mit Markup** |
+| **Danach** | Messen (Punkt-zu-Punkt, Bounding-Box, exakte Werte), Schnittansicht (wichtig für Gehäuse), Versions-Schieber |
+| **Später** | Volumen/Gewicht, Versionsvergleich, Explosionsansicht |
+
+Der Viewer zeigt auch **beliebige weitere STEP-Dateien** im Basismodus, ohne Mapping und Zusatzfunktionen. Standardanzeige ist immer das Hauptmodell.
+
+**2D-Sketching (E16):** Nur Bild-Markup ohne Maßhaltigkeit auf Viewer-Screenshots und leerer Fläche (Freihand, Formen, Pfeile, Text). Ergebnis ist ein PNG. Kein Constraint-Sketcher.
+
+## 8. Umgebung, Auslieferung, Lizenz
+
+- **Eine Variante „alles drin"** mit mitgeliefertem Python, CadQuery und Git (E31, E32). Kein Bring-your-own.
+- **Lizenz:** Open Source, konkrete Lizenz offen (MIT oder Apache-2.0 naheliegend). Lizenzen aller mitgelieferten Komponenten sind zu prüfen (E30).
+- **Auslieferung:** Installer für drei Betriebssysteme, Code-Signing und Auto-Update der App sind noch zu klären.
+
+## 9. Robustheit gegen Abweichungen des Agenten
+
+Agenten befolgen `AGENTS.md` nicht zuverlässig. Sie können Dateien verschieben oder löschen, eigene Umgebungen (z. B. `.venv`) anlegen, `AGENTS.md` ändern, Git umbauen oder an der App vorbei arbeiten. **Die App darf dadurch nicht kaputtgehen.**
+
+**Regeln (Entwurf, noch nicht ausdrücklich bestätigt)**
+
+1. **Der Arbeitsordner ist nicht vertrauenswürdig.** `AGENTS.md` ist eine Bitte, keine Garantie.
+2. **Jede Konvention braucht einen Rückfallweg.** Ohne Hilfsbibliothek zeigt der Viewer trotzdem die STEP-Datei, ohne Klick→Code.
+3. **Erkennen und erklären statt abstürzen.** Der **Projekt-Check** läuft beim Öffnen, Bauen und Speichern. Keine automatischen Reparaturen, kein Reparieren-Button (E28).
+4. **App-kritischer Zustand ist aus einer zweiten Quelle wiederherstellbar** (E27).
+5. **Nichts wird stillschweigend überschrieben oder zerstört.** Wo die App doch eingreift, gibt es vorher Backup oder Git-Stand und einen Hinweis.
+
+**Störfälle** (Reaktionen sind Richtungen, keine fertigen Spezifikationen)
+
+| Störfall | Mögliche Folge | Richtung |
+|---|---|---|
+| `model.py` fehlt, umbenannt oder verschoben | Kein Build | Einstiegspunkt in `project.json` wählbar, Hinweis |
+| Agent exportiert selbst oder ohne Hilfsbibliothek | Kein Mapping/GLB | STEP-Fallback im Viewer, Hinweis |
+| Mehrere oder anders benannte STEP-Dateien | Unklar, was angezeigt wird | Hauptausgabe in `project.json`, sonst Auswahlliste |
+| Agent legt `.venv` an und installiert dort | Build findet Pakete nicht, `.venv` landet in ZIP/Git | `.venv`/`venv` immer ausschließen, Build-Fehler mit Hinweis auf die Projektumgebung |
+| Agent nutzt anderes Python oder `pip --user` | Paketliste unvollständig | Abgleich beim Build, Warnung |
+| `AGENTS.md` verändert oder gelöscht | Regeln fehlen | Prüfsumme, im Check melden. Erneuerung nur beim Versions-Update (E36) |
+| `.cadide/` oder `project.json` gelöscht | ID und Einstellungen weg | Aus App-Daten bzw. ZIP wiederherstellen (siehe offene Punkte) |
+| `.git` gelöscht, neu initialisiert, History umgeschrieben, anderer Branch | Zeitleiste kaputt | Zeitleiste tolerant aus `git log`, Bruch im Check melden |
+| Agent committet nie oder zu oft, riesige Dateien | Leerer Schieber, große ZIP | Auto-Snapshot, Größenwarnung |
+| `inputs/` verändert | Mitgebrachte Datei verfälscht | Git-Stand, Hinweis |
+| Build hängt oder dauert endlos | App blockiert | Timeout, Abbrechen, Dienst neu starten |
+| Agent arbeitet außerhalb des Projektordners | Ergebnisse fehlen in der ZIP | Nicht verhinderbar, wo möglich erkennen |
+| Python-Dienst stürzt ab | Viewer/Messen tot | Automatischer Neustart, Meldung |
+
+## 10. Phasen
+
+**Phase 0: technischer Prototyp ohne App (E13, E14). Abgeschlossen**, alle Punkte bestanden. Details und Zahlen in [ERGEBNISSE.md](prototype/phase0/ERGEBNISSE.md), Code und Tests in `prototype/phase0/`:
+
+1. **STEP mit Namen und Farben:** `cq.Assembly.export` genügt, kein eigener XCAF-Export nötig. Nicht-ASCII-Namen werden beim Export zerstört, daher ASCII-Namen in der STEP.
+2. **GLB mit Flächen-IDs:** eigener Mesher (rund 150 Zeilen), alle IDs gegen OCC verifiziert. Die IDs gelten nur für einen Build. Der Python-Anteil ist nicht der Engpass, das Meshen in OCC ist es.
+3. **Klick → Datei und Zeile:** in echtem Browser bestanden, auf Ebene von Bauteil und Fläche. Verknüpft wird der `add_part`-Aufruf mit Zeilenbereich.
+4. **Fremd-STEP, Messen, Aussparung, Referenz:** bestanden, Abstände und Radien exakt über die IDs. Der Basismodus für fremde STEP-Dateien funktioniert. Getestet nur mit synthetischer Platine.
+5. **Umgebung:** VTK lässt sich nicht entfernen (OCP hängt hart daran). Installiert 0,76 bis 1,04 GB, vorerst hingenommen (E37).
+6. **Exportformate:** 12 Formate, PLY und X_T entfallen.
+
+**Phase 1: MVP-Kern als Desktop-App. In Arbeit.** Projekt neu, speichern und öffnen als ZIP mit Git. Editor, Terminal mit Agent, Viewer (Umfang siehe Abschnitt 7), Screenshot mit Markup, `AGENTS.md`, `cadide build`. Hier folgt auch der **Agent-Test**: Ein Agent baut mit erster `AGENTS.md` und Hilfsbibliothek ein Beispielmodell, geprüft wird u. a., ob er den Verweisen folgt.
+
+*Schritt 1, lauffähiges Gerüst (erledigt, Ende-zu-Ende-Test mit 21 Prüfungen in `app/test/smoke.mjs`):*
+
+- **App:** Electron und TypeScript, Layout aus Abschnitt 7 (Tree mit Reitern *Modell* und *Dateien*, Viewer, Terminal-Tabs, Top Bar, Statusleiste, verschiebbare Trennleisten). Arbeitsordner unter `<App-Daten>/workspaces/<uuid>/`, Projektzustand doppelt (E27), Projekt-Check meldet nur (E28).
+- **`cadide` (Python-Paket in `python/`):** `add_part` mit Datei und Zeilenbereich, `cadide build` (STEP, GLB, Mapping, `build.json`), `cadide export` (12 Formate). Fehler in `model.py` (Syntax, Laufzeit, doppelter Name, kein Bauteil, Einstiegspunkt fehlt) kommen mit Datei, Zeile und gekürztem Traceback zurück, der letzte gute Stand bleibt sichtbar.
+- **Build (E20):** Auto-Build beim Speichern, entprellt, abschaltbar. Änderungen während eines Builds führen zu genau einem Folgebuild. Zeitlimit und Abbruch sind eingebaut.
+- **Viewer:** Klick liefert Bauteil, Fläche und markierte Codezeile. Ein- und Ausblenden, Standardansichten, Kanten, Drahtgitter, Transparenz. Kamera, Sichtbarkeit und Auswahl bleiben über Rebuilds erhalten.
+- **Terminal:** Echte Shell (node-pty) im Projektordner mit `python`, `pip` und `cadide` der Basisumgebung im PATH. Startbuttons für erkannte Agenten (Claude Code, OpenCode, Codex, Gemini CLI).
+- **Vorlage:** `model.py`, erste `AGENTS.md`, `CLAUDE.md` (Verweis), `NOTES.md`, `.gitignore`.
+
+*Offen in Phase 1:* ZIP speichern und öffnen mit Nachfrage bei Abweichung und Absturz-Wiederherstellung, Git (mitgeliefert, Auto-Snapshot), Projektumgebung mit `pip freeze` und `requirements.txt` (bisher landet `pip install` noch in der gemeinsamen Basisumgebung), Editor, Screenshot mit Markup, Auto-Start des Agenten ohne Resume, Agent-Test, Bündelung von Python und Installer, macOS und Linux.
+
+**Danach:** Messen, Schnittansicht, Versions-Schieber, Skills, `cadide check` und Projekt-Check, MCP-Server. **Später:** Volumen/Gewicht, Versionsvergleich, Explosionsansicht, eigene Nutzer-Skills, maßhaltiger Sketcher (nur bei Bedarf).
+
+## 11. Offene Punkte
+
+**Noch nicht ausdrücklich bestätigt (Vorschläge von mir)**
+
+- `AGENTS.md` und die Kommentare der Vorlage sind **auf Englisch** (Agenten befolgen englische Anweisungen zuverlässiger), die Oberfläche ist deutsch
+- App-Daten liegen unter Windows in `%LOCALAPPDATA%\cadide`, nicht im Roaming-Profil (Arbeitsordner und Caches gehören nicht ins Netz)
+- Beim Öffnen eines Projekts wird sofort gebaut, damit der Viewer nicht leer ist
+- Änderung während eines Builds: laufenden Build fertig laufen lassen, danach genau ein weiterer (statt abbrechen und neu starten)
+
+- Rolle `reference` und ihre Standardwerte (E34)
+- Hinweis beim ersten Start, dass der Agent mit den Rechten des Nutzers läuft (E29)
+- Die fünf Robustheitsregeln in Abschnitt 9
+- `project.json` bei Verlust automatisch aus der App-Kopie wiederherstellen und anzeigen, oder nur melden (E27, E28)
+- Auto-Start des Agenten ohne Resume so verstanden, dass der Start bleibt (E19)
+
+**Zu klären**
+
+- **Namen:** Software, Befehl `cadide`, Notizdatei `NOTES.md`, Ordner `exports/` (Ort, getrackt oder nicht)
+- **Lizenz** der Software und Prüfung aller Komponenten
+- **Mittelbereich:** Tab-Umschaltung oder geteilte Ansicht zwischen Viewer und Sketch (E15)
+- **Build:** Auto-Build standardmäßig an oder aus, Statusanzeige, Fehlerpanel, Verhalten bei erneuter Änderung während des Builds (E20)
+- **Speichern/Öffnen:** Erkennung von Abweichungen (Zeitstempel oder Git), mehrere Projekte parallel, Aufräumen alter Workspaces, ZIP auf Netzlaufwerk (E21)
+- **Git:** Agent und App committen gleichzeitig, Sperre beim Wiederherstellen, Beschriftung der Punkte, Einbettung und Updates des Git-Binaries (E31, E35)
+- **Pakete:** Offline-Fall, Paketcache, Verhalten ohne Internet beim Öffnen (E25). Versionen fest pinnen (ein ungepinnter Install zieht inkompatible OCP- und multimethod-Versionen)
+- **Plattformen:** Phase 0 lief nur unter Windows. Python-Bundling, Bibliothekspfade und Wheels auf macOS und Linux sind ungetestet (E2)
+- **Echte Fremddateien:** Herstellerplatinen und große Baugruppen mit Stückliste in Phase 1 testen
+- **Netzlaufwerke (Windows):** Liegt das Programm auf einem Netzlaufwerk, starten die sandboxed Prozesse von Electron nicht. Die installierte App muss lokal liegen, Fehlermeldung ist vorhanden. Klären, wie der Installer damit umgeht und ob Firmenrechner mit umgeleiteten Profilen Probleme machen
+- **Updates:** Regeln für alte und neuere `api_version`, Auto-Update der App, Signierung (E36)
+- **Format** von `model.map.json` (Entwurf `version 0` aus Phase 0 steht) und der Ausgabe von `cadide check`
+- **Toleranz des Meshers:** Feste 0,05 mm passt für kleine Teile, große brauchen eine an der Größe orientierte Toleranz (siehe Leistungsmessung)
+- **Auswahlen des Agenten:** Flächen-IDs gelten nur pro Build, Verweise brauchen Bauteilname plus Geometrieangabe
+- **Inhalte** von `AGENTS.md` und den Skills, mit einem echten Agenten zu testen
+- **Projekt-Check:** Umfang und Spezifikation, Abdeckung aller Störfälle
+
+## 12. Größte Risiken
+
+| Risiko | Warum | Gegenmaßnahme |
+|---|---|---|
+| STEP-Namen mit CadQuery | **Erledigt in Phase 0:** Namen, Farben, Alpha bleiben erhalten. Nicht-ASCII-Namen werden zerstört | ASCII-Namen in der STEP, Anzeigename in `model.map.json` |
+| Codequalität der Agenten mit CadQuery | Verkettete API mit verstecktem Zustand, halluzinierte Aufrufe | Strikte Idiome in `AGENTS.md`, Beispiele, Feedback-Loop (bauen, messen, rendern) |
+| Agenten ignorieren die Konventionen | Nicht jeder Agent folgt `AGENTS.md` oder Verweisen | Robustheit (Abschnitt 9), Agent-Test in Phase 1 |
+| Klick auf Fläche und Code | Kein Framework liefert Flächen-IDs oder Zeilenbezug | **In Phase 0 bestätigt** mit eigenem Mesher und Hilfsbibliothek. Verknüpft wird der `add_part`-Aufruf (E10), nicht die Entstehungszeile der Fläche |
+| Installationsgröße und Einbettung | **Gemessen:** OCP hängt hart an VTK, installiert 0,76 bis 1,04 GB | Vorerst hingenommen (E37). Später: Casadi und VTK-Teilmenge prüfen, Komprimierung |
+| Nur Windows getestet | Bundling und Bibliotheken auf macOS und Linux ungeprüft, E2 verlangt alle drei | Früh in Phase 1 auf macOS und Linux nachziehen |
+| Modellgröße und Buildzeit | Große Teile brauchen 8 bis 10 s (Meshen in OCC), feine Toleranz bis 30 s | Auto-Build abschaltbar (E20), Toleranz nach Bauteilgröße |
+| Chats bei ZIP-Weitergabe | Agenten speichern Historie außerhalb des Projekts | Bewusst akzeptiert (E5) |
+| Git für Nicht-Programmierer | Agent und App teilen sich ein Repo | Nur Vorschau und Wiederherstellen als neuer Commit (E35) |