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

Doku: Nutzeranleitung (E83) in Entscheidungen, Plan, Changelog und README

Kai-Jungsthoefel2faa642bc7f5
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9554915..edd2df3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,10 @@ eigenen Abschnitt mit Datum und Git-Tag.
## [Unveröffentlicht]
+### Neu
+
+- Hilfe: Der Knopf „Help“ in der Leiste (auch auf der Startseite, Taste F1) öffnet eine kurze Anleitung zu allen Bereichen der App, mit Screenshots, auf denen die Elemente nummeriert sind. Dieselbe Anleitung bekommt der Agent als Skill „Using the app“ (ab Werk „On demand“) samt Bildern, damit er Fragen zur Bedienung beantworten kann (E83).
+
### Behoben
- Markup: Die Zeichenfläche passt sich dem Viewer an. Wird er größer, etwa weil die PDF daneben geschlossen wird, wächst sie mit, statt klein in der Ecke zu bleiben. Mausrad zoomt um den Zeiger (bis 8-fach), Ziehen mit der rechten oder mittleren Maustaste verschiebt, Ctrl+0 passt wieder ein. Das Bild für den Agenten bleibt dabei in voller Auflösung.
diff --git a/CLAUDE.md b/CLAUDE.md
index 96ed715..798f4a3 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -14,7 +14,7 @@ Eine Desktop-App (Electron, TypeScript), in der ein Nutzer mit einem CLI-Agenten
| Pfad | Inhalt |
|---|---|
-| `app/` | Electron-App. `src/main/` Hauptprozess (`projects.ts` Speichern/Öffnen/Verlauf/Export, `git.ts`, `zip.ts`, `build.ts` (mit vorgewärmtem Python-Prozess), `previews.ts`, `measure.ts`, `skills.ts`, `skilllibrary.ts` (eigene Skills, E78), `settings.ts` (Einstellungen der App in `settings.json`, E81), `storage.ts` (Speicherplatz der App-Daten, E81), `about.ts` (Versionen und Komponenten, E81), `params.ts` (Werte des Parameter-Panels, E74), `workspace.ts`, `terminals.ts`, `packages.ts` (Projektumgebung, E67), `files.ts`, `dxf.ts` (DXF-Ansicht über `soma dxfview`, E80), `bridge.ts` Verbindung für `soma render`, `render.ts` Render-Fenster, `animations.ts`), `src/preload/`, `src/renderer/` (`main.ts` Verdrahtung, `viewer.ts`, `viewcube.ts`, `sectiontool.ts`, `explodetool.ts`, `busy.ts`, `skills.ts`, `settings.ts` (Einstellungen, E78), `settingspages.ts` (Reiter Viewer, Storage, About, E81), `params.ts`, `markup.ts`, `measuretool.ts`, `tree.ts` (Strukturbaum im Viewer, E82), `code.ts`, `pdfview.ts`, `dxfview.ts` (DXF im Code-Panel, E80), `markdown.ts`, `filetree.ts`, `versions.ts`, `terminals.ts`, `ui.ts`, `icons.ts`, für Animation und Analyse `animtool.ts`, `animpanel.ts`, `animdata.ts`, `overlay.ts`, `resulttool.ts`, `resultview.ts`, `analysispanel.ts`, `videoview.ts`, `render.ts`/`render.html` im Render-Fenster), `src/shared/types.ts` (IPC-Vertrag), `src/shared/settings.ts` (Einstellungen: Vorgaben, Prüfung, Mausbelegungen, E81), `src/shared/editable.ts`, `resources/template/` (Vorlage für Nutzerprojekte inkl. `AGENTS.md`), `resources/skills/` (mitgelieferte Skills), `resources/icon.*` (App-Icon, erzeugt mit `scripts/make-icon.py`), `test/` |
+| `app/` | Electron-App. `src/main/` Hauptprozess (`projects.ts` Speichern/Öffnen/Verlauf/Export, `git.ts`, `zip.ts`, `build.ts` (mit vorgewärmtem Python-Prozess), `previews.ts`, `measure.ts`, `skills.ts`, `skilllibrary.ts` (eigene Skills, E78), `help.ts` (Anleitung, E83), `settings.ts` (Einstellungen der App in `settings.json`, E81), `storage.ts` (Speicherplatz der App-Daten, E81), `about.ts` (Versionen und Komponenten, E81), `params.ts` (Werte des Parameter-Panels, E74), `workspace.ts`, `terminals.ts`, `packages.ts` (Projektumgebung, E67), `files.ts`, `dxf.ts` (DXF-Ansicht über `soma dxfview`, E80), `bridge.ts` Verbindung für `soma render`, `render.ts` Render-Fenster, `animations.ts`), `src/preload/`, `src/renderer/` (`main.ts` Verdrahtung, `viewer.ts`, `viewcube.ts`, `sectiontool.ts`, `explodetool.ts`, `busy.ts`, `skills.ts`, `help.ts` (Hilfe-Fenster, E83), `settings.ts` (Einstellungen, E78), `settingspages.ts` (Reiter Viewer, Storage, About, E81), `params.ts`, `markup.ts`, `measuretool.ts`, `tree.ts` (Strukturbaum im Viewer, E82), `code.ts`, `pdfview.ts`, `dxfview.ts` (DXF im Code-Panel, E80), `markdown.ts`, `filetree.ts`, `versions.ts`, `terminals.ts`, `ui.ts`, `icons.ts`, für Animation und Analyse `animtool.ts`, `animpanel.ts`, `animdata.ts`, `overlay.ts`, `resulttool.ts`, `resultview.ts`, `analysispanel.ts`, `videoview.ts`, `render.ts`/`render.html` im Render-Fenster), `src/shared/types.ts` (IPC-Vertrag), `src/shared/settings.ts` (Einstellungen: Vorgaben, Prüfung, Mausbelegungen, E81), `src/shared/editable.ts`, `resources/template/` (Vorlage für Nutzerprojekte inkl. `AGENTS.md`), `resources/skills/` (mitgelieferte Skills, darunter `soma-app.md`: die Nutzeranleitung für Hilfe und Agent, E83), `resources/help/` (Bilder der Anleitung), `resources/icon.*` (App-Icon, erzeugt mit `scripts/make-icon.py`), `test/` |
| `design/ui-entwurf-2.html` | Freigegebener Oberflächenentwurf 2 „Aufgeräumt“ (E62), im Browser öffnen, Pfeiltasten blättern. Maßstab für Aufbau, Farben und Texte der Oberfläche. Bild 6 ist das Parameter-Panel (umgesetzt mit E74, Werte des Nutzers getrennt vom Code) |
| `design/strukturbaum-entwurf.html` | Freigegebener Entwurf für den Strukturbaum im Viewer und die Reiter Analysis und Animation (E82), umgesetzt. Ersetzt in Entwurf 2 den Reiter Bauteile und den Umschalter oben links, enthält den ruhigen Bericht der Analyse. Maßstab für Baum, Reiter und Bericht |
| `design/ui-entwurf.html` | Erster Oberflächenentwurf (E38), Farben und Bausteine gelten weiter, der Aufbau ist durch Entwurf 2 ersetzt |
@@ -57,6 +57,7 @@ node test/run-all.mjs smoke editor # einzelne Suiten parallel, nach npm run bu
- Nach Änderungen `npm run typecheck` und `npm test`. Die npm-Skripte bauen vorher. `node test/*.mjs` ohne Build testet veraltete `dist/`-Dateien.
- Testfenster bleiben unsichtbar (`SOMA_HIDDEN=1`), sonst blitzen beim Nutzer Fenster auf. Unsichtbare Fenster zeichnen nicht neu: Für frische Screenshots `SMOKE_VISIBLE=offscreen`. Bei Änderungen an der Oberfläche `SMOKE_VISIBLE=offscreen` plus `SMOKE_SHOTS=1` und die Bilder in `app/test/shots/` ansehen.
+- Nutzeranleitung (E83): Ändert sich die Oberfläche, `npm run help:shots` laufen lassen, die Bilder in `app/resources/help/` ansehen und den Text in `app/resources/skills/soma-app.md` nachziehen. Ausschnitte und Nummern stehen in `app/test/helpshots-spec.mjs`, die Bezeichnungen dort und unter den Bildern müssen gleich sein.
- Oberfläche: Farben mit fester Bedeutung (Orange Aktion und Auswahl, Violett Vorschau, Grün/Gelb/Rot Status), Tokens stehen oben in `style.css`. Symbole nur über `icons.ts`, keine Emoji. Menüeinträge, die Tests oder Kurzbefehle brauchen, stehen fest in `index.html`.
- Native Dialoge im Test über `app.answers([...])` beantworten (`src/main/dialogs.ts`).
- Steuerung per eigenem CDP-Client (`test/cdp.mjs`). puppeteer-core funktioniert mit Electron 44 nicht, `Input.dispatchMouseEvent` und `Page.captureScreenshot` hängen in unsichtbaren Fenstern.
diff --git a/DECISIONS.md b/DECISIONS.md
index ffc80cc..7371d6f 100644
--- a/DECISIONS.md
+++ b/DECISIONS.md
@@ -85,3 +85,5 @@
| 80 | DXF-Ansicht | **DXF-Dateien öffnen in SOMA: Ein Klick im Dateibaum zeigt sie als Reiter im Code-Panel, zum Ansehen (zoomen, verschieben, Layer ein- und ausblenden), nicht zum Bearbeiten** | Wunsch des Nutzers („Können wir einen einfachen DXF Viewer einbauen?“). Bisher gab es für DXF nur „Open with default app“. Auslegung (nicht ausdrücklich bestätigt): im Code-Panel neben der PDF-Ansicht statt im Viewer, gezeichnet von ezdxf in Python (dasselbe Zeichenmodul wie für PDF und Bild der technischen Zeichnungen, E76, keine neuen Pakete) statt mit einer JavaScript-Bibliothek, dunkler Grund wie im Modellbereich eines CAD-Programms, „Mark up view“ gibt den sichtbaren Ausschnitt mit seinen Koordinaten an den Agenten. Umsetzung und Auslegungen in PLAN.md, Abschnitte 10 und 11 |
| 81 | Einstellungen: Viewer, Speicher, Info | **Die Einstellungen bekommen neben „Skills“ die Reiter „Viewer“, „Storage“ und „About“.** Viewer: Mausbelegung nach bekannten CAD-Programmen, Zoomrichtung umkehren, perspektivisch oder orthografisch, Darstellung beim Öffnen eines Modells (Kanten, Drahtgitter, Transparent), Nachkommastellen beim Messen. Storage: Größe der App-Daten je Bereich, Ordner öffnen, Vorschau-Cache leeren, Sicherungen nur zeigen. About: Versionen, Komponenten mit Lizenz, gefundene Agenten, Ordner, Systemangaben kopieren. **Für die Skills ändert sich nichts** | Wunsch des Nutzers („Lets expand the settings window“), ausgewählt aus meiner Liste mit sieben Reitern: „Alles in Viewer“, „Alles in Storage“, „Alles in About“. App-weite Standardwerte für Skill-Einstellungen waren zuerst gewünscht und sind wieder verworfen: „bei den skills brauchen wir nix ändern da man ja bei editieren der skills die standard werte ändern kann“ (die Werte im Kopf eines bearbeiteten Skills gelten für neue Modelle). Die übrigen Vorschläge (General, Agent & Terminal, Build & Python) bleiben offen. Auslegungen in PLAN.md, Abschnitte 10 und 11 |
| 82 | Strukturbaum im Viewer, Reiter Analyse und Animation | **Die Bauteile wandern aus der Seitenleiste als Strukturbaum ganz oben links in den Viewer, wie in CATIA: eingeklappt nur der Name des Modells, ohne Hintergrund, aufgeklappt mit Baumstrichen und direkt vor jedem Namen je einem Knopf für Ausblenden und Transparent. Der Baum ist in Modell, Analyse und Animation derselbe. Analysis und Animation werden eigene Reiter, die Leiste zeigt Parameters und Files, dann Analysis und Animation, dann Skills, getrennt durch Striche. Der Reiter Parts und der Umschalter oben links entfallen.** Entwurf in `design/strukturbaum-entwurf.html` | Wunsch des Nutzers nach der Kritik am Ergebnis-Panel der FEM und drei Runden Entwurf („Analyse und Animation kommen in die linke Leiste, dafür verschwindet Modell aus der Leiste und wird links im Viewer angeordnet … eher wie Catia“, „Der Dateibaum soll gar keinen Hintergrund haben, damit er möglichst wenig im Weg ist“, „das ‚Modell‘ oben brauchen wir doch nicht mehr“, „erst die Baumstriche, dann vor dem Namen des Objekts/Gruppe die Knöpfe“), freigegeben mit „gefällt mir“. Ersetzt in E62 die Bauteile in der Seitenleiste und den Umschalter oben links. Zum Entwurf gehört der ruhige Bericht der Analyse (eine Zahl groß, Annahmen je eine Zeile zum Aufklappen, Farbe nur als Statuszeichen). Verworfen aus meinen Entwürfen: ein Kontext-Reiter, der dem Viewer folgt, Rechtsklick auf Körper im Bild, Augen im Bericht, Knöpfe in fester Spalte. Noch nicht umgesetzt. Auslegungen in PLAN.md, Abschnitt 11 |
+| 83 | CalculiX als Rechenwerk der FEM | **Die FEM rechnet künftig mit CalculiX (`ccx`) statt mit dem eigenen Solver. CalculiX wird mitgeliefert, aus den Paketen von conda-forge (mit OpenBLAS, nicht MKL), je Betriebssystem beim Bauen des Installers geholt.** Der Lastfall bleibt in `analyses/*.py`, neue Fähigkeiten (Kontakt, Schrauben, Eigenfrequenzen …) kommen auf diesem Weg dazu | Vorschlag nach der Frage des Nutzers, wie die FEM besser wird (Kontaktflächen), freigegeben mit „finde ich gut“ nach einem Testlauf unter Windows: gleiches Netz und gleiche Lasten, Verschiebungen gleich bis auf 1e-6, bei 10 000 bis 250 000 Unbekannten 2- bis 3-mal schneller als pyamg, bei 440 000 etwa gleich (CalculiX 3 GB Speicher). Windows: 11 Dateien, 53 MB (16 MB gezippt). Auslegung (nicht ausdrücklich bestätigt): Spannungen weiter selbst aus den Verschiebungen rechnen (CalculiX mittelt über Werkstoffgrenzen), eigener Solver als Rückfallweg, wenn `ccx` fehlt oder abbricht. Ersetzt in E65 das eigene Rechenwerk |
+| 83 | Nutzeranleitung | **Eine Nutzeranleitung in zwei Formen aus einer Quelle: in der App (Knopf „Help“) und als Skill für den Agenten, damit er Fragen zur App beantworten kann.** Kurz und knackig. Die Oberfläche erklären Screenshots mit Nummern an den Elementen, darunter je eine nummerierte Liste. Die Quelle ist Markdown (der Skill `soma-app.md`), nicht HTML, Teile nur für den Agenten stehen zwischen `<!-- agent -->` und `<!-- /agent -->`. Der Agent sieht die Bilder über ihre Pfade an, ASCII-Skizzen und Textbeschreibungen der Oberfläche entfallen | Wunsch des Nutzers („Okay wir brauchen eine Nutzeranleitung. In 2 Formen“, „kurz und Knackig“, „nur eine Quelle aus der der Ageten skill erzeugt wird“). Die Idee des Nutzers war eine HTML mit Abschnitten nur für den Skill, mein Gegenvorschlag Markdown (Skills sind Markdown, die App zeigt Markdown schon an). Dazu der Hinweis „wir können davon ausgehen das der Agent Bilder verstehen kann“ und „Um das GUI zu erklären am besten screenshots benutzen mit Zahlen auf den elementen“, freigegeben mit „Ja klingt gut“. Auslegungen (nicht ausdrücklich bestätigt) und Umsetzung in PLAN.md, Abschnitte 10 und 11 |
diff --git a/PLAN.md b/PLAN.md
index 574bfc9..08019d9 100644
--- a/PLAN.md
+++ b/PLAN.md
@@ -539,6 +539,14 @@ Alle Codeblöcke der Skills sind gegen die Basisumgebung geprüft (Überhangsuch
- **Daten (`python/soma/fem.py`):** Die Ergebnisse der FEM nennen je Werkstoff jetzt auch Querdehnzahl und Dichte, und beim Netz, ob die Größe automatisch kam (`mesh.auto`). Ältere Ergebnisse zeigen den Bericht ohne diese Zeilen.
- **Grenzen:** Der Baum merkt sich Auf- und Zuklappen nur bis zum Neustart. Mehr als eine Spitze je Größe wird nicht beschriftet. Getestet unter Windows.
+*Nutzeranleitung (E83, Wunsch des Nutzers; Prüfungen in `app/test/unit.mjs` und `skills.mjs`):*
+
+- **Eine Quelle:** Die Anleitung ist der mitgelieferte Skill `app/resources/skills/soma-app.md` („Using the app“, Kategorie Way of working, ab Werk „Bei Bedarf“, Anlass: der Nutzer fragt nach der Bedienung). Je Bereich ein Abschnitt `##` mit Bild und nummerierter Liste, die Nummern im Bild entsprechen der Liste. Die Hilfe der App zeigt denselben Text ohne Kopf, ohne Hauptüberschrift und ohne die Teile zwischen `<!-- agent -->` und `<!-- /agent -->` (`app/src/shared/help.ts`). Dort steht nur eine kurze Anweisung an den Agenten: Bilder öffnen, Knöpfe beim Namen nennen, nichts erfinden.
+- **Bilder (`app/resources/help/*.png`):** erzeugt aus der echten App mit `npm run help:shots` (`app/test/helpshots.mjs`, Fenster außerhalb des Bildschirms, Terminal mit kurzem Prompt ohne Benutzerpfad). Ausschnitt und Nummern je Bild stehen in `app/test/helpshots-spec.mjs`: Selektor, Stelle der Nummer, gestrichelter Rahmen für Bereiche. Gelbe Nummern mit dunklem Rand, damit sie sich von Orange (Auswahl) abheben. Elf Bilder, zusammen rund 2.3 MB. `npm run test:unit` prüft, dass jedes Bild benutzt wird und vorhanden ist und dass die fetten Bezeichnungen unter jedem Bild genau den Markierungen entsprechen.
+- **Für den Agenten:** Der Skill kommt wie jeder andere nach `.soma/skills/`. Die Bilder kopiert die App nach `.soma/help/`, sobald der Skill an ist, beim Öffnen eines Modells und beim Umstellen der Stufe (`app/src/main/help.ts`, nur abweichende Dateien). Der Text verweist relativ auf `../help/<bild>.png`, das stimmt von der Kopie aus und in der Markdown-Ansicht der App. `.soma/help/` ist ein Zwischenergebnis wie `.soma/drawings/`: in der `.gitignore` der Vorlage, in `.git/info/exclude` älterer Projekte, nicht in der Modelldatei.
+- **In der App (`app/src/renderer/help.ts`):** Fenster wie die Einstellungen, links die Abschnitte, rechts einer davon mit derselben Markdown-Ansicht wie Notizen. Knopf „Help“ in der Leiste (bisher ausgegraut) und auf der Startseite, F1 öffnet und schließt, Escape schließt, Pfeiltasten wechseln den Abschnitt. Ein Klick auf ein Bild zeigt es in voller Größe. Die Hilfe liest immer die mitgelieferte Fassung, nicht eine in den Einstellungen bearbeitete.
+- **Grenzen:** Analyse und Animation haben kein Bild (sie brauchen Ergebnisse des Agenten). Nach Änderungen an der Oberfläche müssen Bilder und Text von Hand nachgezogen werden, der Test fängt nur fehlende Elemente und abweichende Bezeichnungen. Getestet unter Windows.
+
*Offen in Phase 1:* Auto-Start des Agenten ohne Resume, Agent-Test mit weiteren Agenten und längeren Sitzungen, Bündelung von Python und Installer, macOS und Linux.
**Danach:** Zukaufteile wie NEMA-17-Motoren und V-Slot-Profile (E48, Wunsch des Nutzers), Versions-Schieber, `soma check` und Projekt-Check, MCP-Server. **Später:** Volumen/Gewicht, Versionsvergleich, weitere Bereiche der Einstellungen, maßhaltiger Sketcher (nur bei Bedarf).
@@ -569,7 +577,7 @@ Alle Codeblöcke der Skills sind gegen die Basisumgebung geprüft (Überhangsuch
- Nach „Wiederherstellen“ bleibt die Vorschau bis zum Ende des folgenden Builds stehen, auch wenn er fehlschlägt (dann mit Fehlerkarte über dem wiederhergestellten Stand)
- Vorgewärmter Python-Prozess (E66): einer für die ganze App läuft ständig mit geladenem cadquery (Speicher gegen rund 3 s je Auftrag), schon ab dem Start. Er wird bei jeder Entnahme für den nächsten angelegt und beendet sich, wenn die App ihn verwirft oder abstürzt (stdin geschlossen). Nach dem Ergebnis beendet sich `soma build` sofort (`os._exit`), das Aufräumen von OCP und vtk kostete knapp 1 s
- Angezeigt wird nur die Gesamtdauer eines Builds vom Start bis zum Ergebnis, nicht mehr die Summe der Teilzeiten (die zeigte 0,1 s, obwohl man 4 s wartete). `soma build` im Terminal meldet ebenfalls die Gesamtzeit
-- Oberfläche (E38): Funktionen, die noch fehlen (inzwischen nur noch Pakete, Hilfe, Optionen), stehen schon ausgegraut mit Hinweis da. Nur dunkles Farbschema. Das „⋯“-Menü aus dem Entwurf entfällt (alles steht im Dokumentmenü)
+- Oberfläche (E38): Funktionen, die noch fehlen (inzwischen nur noch Pakete), stehen schon ausgegraut mit Hinweis da. Nur dunkles Farbschema. Das „⋯“-Menü aus dem Entwurf entfällt (alles steht im Dokumentmenü)
- Dateien, die man irgendwo ins Fenster zieht, landen in `inputs/` (Electron würde sie sonst als Seite öffnen). Bei gleichem Namen „name (2).ext“
- Gezogene Ordner kommen mit allen Unterordnern nach `inputs/<Ordner>/` (bei gleichem Namen „Ordner (2)“). Verknüpfungen und `.git`-Ordner darin bleiben draußen und werden gemeldet (ein eingebettetes Repository würde Git nur als Verweis ablegen). Grenze wie bei Dateien 500 MB, dazu höchstens 10 000 Dateien. Ist der Ordner zu groß, wird gar nichts kopiert
- Die Startseite erscheint bei jedem Start und über das Logo (E69). Ein Modell, das nach einem Absturz ungespeichert liegen blieb, öffnet die App nicht mehr von selbst, es steht auf der Startseite
@@ -656,6 +664,7 @@ Alle Codeblöcke der Skills sind gegen die Basisumgebung geprüft (Überhangsuch
- Bei der Umsetzung von E82 ohne Rückfrage entschieden: Die Seitenleiste startet zu (vorher mit den Bauteilen), eine gemerkte Ansicht „Bauteile“ älterer Versionen öffnet nichts, Analysis und Animation werden nicht über einen Neustart gemerkt (ein Ergebnis zeigt sich nur auf Wunsch). Bericht und Ablauf machen die Seitenleiste mindestens 352 px breit wie im Entwurf. Gruppen beginnen zugeklappt, Aufklappen zeigt eine Ebene (Wunsch des Nutzers nach der ersten Durchsicht). Der Punkt am Reiter verschwindet beim Öffnen des Reiters, „new“ in der Liste erst beim Öffnen des Eintrags. „Show the spot“ verschiebt die Ansicht zur Stelle, ohne zu zoomen, ein ausgeblendetes Teil bleibt ausgeblendet (Meldung statt Einblenden). In der Leiste kommt Displacement als dritte Größe dazu (im Entwurf gezeigt, vorher nicht vorhanden), ohne Grenzwert, Farbe über die Spanne. Die Beschriftung im Bild folgt der Größe („Min“ Sicherheit, „Max“ Spannung oder Verschiebung). Schritte der Animation aus den Untertiteln, ohne Untertitel aus dem Ablauf der Datei. Zu einer Animation gehören die Videos in `renders/`, deren Name mit ihrer Kennung beginnt. Das Menü „…“ im Bericht enthält „Copy command“ und „Show the model“. Die angeklickte Stelle steht unten im Bericht über den Knöpfen
- `npm test` läuft über `test/run-all.mjs` mit vier Suiten gleichzeitig und freien Ports (5,5 bis 7 statt 8,5 Minuten, die Animation bestimmt die Dauer und wird unter Last 2 bis 3 Mal langsamer), Watchdog dann 15 Minuten. `soma` lädt cadquery erst in Befehlen, die es brauchen (`soma --version` 0,7 statt 4,4 s)
- Markup-Ansicht: Die Zeichenfläche behält Größe und Seitenverhältnis von der Aufnahme (das Bild für den Agenten ändert sich nicht), wird aber in den Viewer eingepasst und wächst mit ihm. Mausrad zoomt um den Zeiger von eingepasst bis 8-fach, rechte oder mittlere Maustaste verschiebt (die linke bleibt dem Zeichnen), Ctrl+0 passt wieder ein. Die Fangradien der Griffe gelten in Bildschirmpixeln, Strichstärke und Schrift in Pixeln der Zeichenfläche (sie wachsen beim Zoomen also mit)
+- Nutzeranleitung (E83): Quelle in Markdown statt HTML (Gegenvorschlag, mit „Ja klingt gut“ freigegeben). Die Quelle ist der Skill selbst statt einer eigenen Datei, aus der der Skill erst erzeugt würde: So gibt es nichts zu erzeugen und nichts zu vergessen. Skill ab Werk „Bei Bedarf“ in „Way of working“, nicht „Immer“ (Bedienfragen sind selten, der Text wäre sonst bei jeder Änderung im Kontext). Anleitung auf Englisch wie die App (E73). Hilfe als Fenster über der App wie die Einstellungen statt als Reiter im Code-Panel, F1 als Taste. Bilder per Skript aus der echten App, eingecheckt in `app/resources/help/` (rund 2.3 MB), statt beim Bauen oder Start erzeugt. Im Projekt unter `.soma/help/`, nicht im Verlauf, damit jedes Modell nicht um die Bilder wächst. Die Bilder bleiben im Projekt, wenn der Skill ausgeschaltet wird (stören nicht, Zwischenergebnis)
- Rolle `reference` und ihre Standardwerte (E34)
- Hinweis beim ersten Start, dass der Agent mit den Rechten des Nutzers läuft (E29)
diff --git a/README.md b/README.md
index 755cf8a..ce6917e 100644
--- a/README.md
+++ b/README.md
@@ -52,6 +52,7 @@ Any CLI agent that can read files and run commands works: Claude Code, OpenCode,
- Draw on the 3D view, or drop in a photo of a hand sketch and draw on that, then hand the image to the agent
- `soma render` lets the agent look at its own work as images or contact sheets
- Skills: optional rule sets per model (3D printing, CNC, sheet metal, tolerances, joints, FEM …), switched on always or on demand. Edit them or add your own in the settings
+- A short built-in guide with numbered screenshots (F1). The agent gets the same guide as a skill, so you can also just ask it how the app works
**Project**
- A model is a single `.soma` file (a ZIP archive) with code, result and history. ZIP files open too, and the export menu writes the whole model as a ZIP