Phase 5 vollständig planen und native Exporte abgrenzen

openspec/changes/phase-5-07-hilfesystem/design.md

@@ -0,0 +1,28 @@
+## Context
+
+Die Hilfe soll laut PLAN.md die tatsächlich implementierte Dokumentation unter docs anzeigen. Fensterverwaltung und F1-Befehlsweg stammen aus 02; Token-/Prozedurkontext aus 03. Die existierenden Markdown-Dateien enthalten Tabellen, Codeblöcke, Überschriften und relative Verweise. Es gibt noch keinen Markdown-Hilferenderer.
+
+## Goals / Non-Goals
+
+**Goals:** Eine Dokumentationsquelle für CLI-Leser und IDE, offline paketiert, stabile Link- und Kontextziele.
+
+**Non-Goals:** Browser, Webserver, HTML-/JavaScript-Ausführung, Download von Hilfethemen oder separate handgepflegte Kopie der Referenztexte.
+
+## Decisions
+
+1. Die relevanten docs-Dateien werden beim Build direkt eingebettet. Ein kleiner Themenkatalog ordnet Dateipfad und Überschriftenanker den Inhalten zu. Er enthält Index/Contents und Kontextaliasse, aber keine duplizierten Erklärungstexte. Include-Struktur und Katalogprüfung müssen fehlende Dokumente beim Build/Test sichtbar machen. Eine Laufzeitinstallation benötigt keinen Checkout.
+2. Markdown wird in logische Blöcke und Inline-Spans übersetzt und mit vorhandenen ratatui-Mitteln gerendert. Vor Implementierung kurz vorhandene Workspace-Abhängigkeiten prüfen; falls kein Parser verfügbar ist, ist ein einzelner fokussierter CommonMark-Parser zweckmäßiger als ein eigener Parser für Tabellen, Escapes, Code und Links. Keine volle Terminal-Markdown-Anwendung als Subprozess. Bibliothekswahl wird erst in der Umsetzung nach API-/Lizenzprüfung festgelegt, der Vertrag bleibt unabhängig davon.
+3. Fensterbreite bestimmt Fließtextumbruch; Code und breite Tabellen verwenden horizontales Scrollen. Der Leseanker besteht aus Thema, Block/Offset und fokussiertem Link, nicht aus einer alten Bildschirmzeile. Unicode-Breiten kommen aus der vorhandenen Darstellung. Resize berechnet nur das Layout neu.
+4. Interne Ziele werden relativ zur Quelldatei normalisiert und gegen eingebettete Dateien/Anker aufgelöst. Pfade außerhalb der eingebetteten Dokumente werden nicht als beliebige lokale Dateien gelesen. Externe Links erhalten eine sichtbare URL und Hinweis, öffnen aber nicht automatisch Browser oder Shell. Unbekannte/fehlende interne Ziele sind prüfbare Fehler, keine stillen Nullaktionen.
+5. Kontextauflösung verwendet normalisierte Token mit Typ-Suffixen, Forms-Klasse/Property und konkrete IDE-Befehls-ID. Bei Mehrdeutigkeit erscheint die Trefferliste, ohne Treffer der Index mit übernommenem Suchwort. Designer liefert einfache Kontextdaten über den Rahmen; 07 benötigt seine Implementierung nicht als Compilerabhängigkeit, 08 prüft die echte Integration.
+6. Besuchshistorie speichert maximal 20 Rücksprungzustände einschließlich Leseposition. Ctrl+F1 geht in der Reihenfolge des Contents-Katalogs zum nächsten Thema und bleibt am Ende mit erkennbarem Hinweis stehen. Esc stellt den vorherigen Fokus wieder her. Tutorial, Keyboard und Using Help sind normale Markdown-Seiten; About verwendet die Paketversion des gebauten Programms.
+
+## Risks / Trade-offs
+
+- Anker ändern sich bei Dokumentpflege → Linkprüfung über alle eingebetteten Inhalte und Kontextaliasse.
+- Eingebettete Dateien vergrößern das Binary → nur Dokumentation, keine Originalarchive oder Testdaten einbetten; keine Laufzeit-Netzwerkabhängigkeit.
+- Eigener Markdownparser wächst → vorhandene/fokussierte Parserbibliothek verwenden, Darstellung bleibt kleines IDE-Modul.
+
+## Migration Plan
+
+Dokumenttexte bleiben unter docs die Quelle. Fehlende Bedienungsseiten werden dort ergänzt und in den Katalog aufgenommen. Keine Benutzerdatenmigration; neue Releases liefern die passende Hilfe automatisch mit.