Beitragsleitfaden — Shell Sentinel

Diese Zusammenfassung fasst die internen Richtlinien für die Zusammenarbeit an Shell Sentinel zusammen: Projektstruktur, Dokumentationsstandards und Website-Pflege. Jeder Beitrag sollte diesen Leitlinien folgen, um die Produktkohärenz zu wahren.

Allgemeine Prinzipien

• Terminalorientierte Anwendung mit persistenten SSH/SFTP-Sitzungen und einem konversationellen KI-Assistenten.
• Python-3.12-Ökosystem, Textual-8.2.7-TUI, Strands Agents ≥1.45 und MCP-Tools wie Firecrawl.
• Abhängigkeiten über pyproject.toml und pip-tools-Lockfiles (make lock, make install).
• Tägliche Arbeit mit make install, make format, make lint, make test und make run.
• GitHub-Actions-CI (Lint + Tests auf Python 3.12) bei jedem Pull Request über .github/workflows/ci.yml.

Konfiguration und Inhalte

• Alle Konfiguration liegt in conf/ (keine fest verdrahteten Werte im Code).
• Neue Strings in conf/locales/ hinzufügen und mit _("schlüssel") referenzieren.
• Benutzerhandbücher in EN/ES/DE pflegen, sobald sich ein Ablauf ändert.
• Eigene Provider in der technischen Anleitung dokumentieren und von der Website verlinken.

Plugins und Erweiterbarkeit

• Plugins werden aus plugins/ geladen; jedes muss Befehle, Übersetzungen und lokale Dokumentation registrieren.
• Plugin-spezifische Dokumentation nicht mit allgemeinen Handbüchern vermischen.
• System-Prompts respektieren und keine parallelen SSH/SFTP-Verbindungen außerhalb der offiziellen Tools anlegen.

Richtlinie für Web-Dokumentation

• Die Website unter website/ ist Teil des Produkts und muss jede funktionale oder narrative Änderung widerspiegeln.
• Bei Änderungen an Handbüchern, Befehlen oder Providern Inhalte der Website synchronisieren (Abschnitte, Karten, Links und Übersetzungen).
• Online-Handbücher nutzen HTML-Seiten in website/manuals/; relevante Änderungen aus docs/ spiegeln.

Empfohlener Workflow

1. Virtualenv aktivieren (python3.12 -m venv .venv, dann source .venv/bin/activate).
2. Abhängigkeiten installieren (make install).
3. Nach Änderungen: make format, make lint, make test (Pflicht vor dem Öffnen eines PR).
4. TUI mit make run und Website mit make website-serve validieren.

Weitere Details im internen Richtlinienportal. Nach jedem Beitrag prüfen, dass Website, Handbücher und Repository konsistent bleiben.