# Portabilität: UNIVERSAL
# Version: 1.0.0
# Zuletzt validiert: 2026-03-04

TIME HANDLER
============================================================================

BESCHREIBUNG
============================================================================

Der Time Handler verwaltet das Zeit-Management-System in BACH. Er bietet
Funktionalitäten für Uhrzeit-Anzeigen, Timer, Countdowns und zeitbasierte
Profil-Verwaltung (Between). Alle Module verwenden die zentrale TimeManager
für koordinierte Operationen.

Basis-Verzeichnis: data/ (Zustandsdateien)
Module: tools/time_system.py


OPERATIONEN
============================================================================

CLOCK
-----
  bach clock on              - Uhrzeit-Anzeige aktivieren
  bach clock off             - Uhrzeit-Anzeige deaktivieren
  bach clock status          - Status der Uhrzeit-Anzeige prüfen
  bach clock interval <sek>  - Anzeige-Intervall in Sekunden setzen

TIMER
-----
  bach timer start [name]    - Timer starten (default: "default")
  bach timer stop [name]     - Timer stoppen
  bach timer list            - Alle aktiven Timer anzeigen
  bach timer clear           - Alle Timer löschen

COUNTDOWN
---------
  bach countdown start <name> <HH:MM:SS> [--after 'befehl']
                             - Countdown starten mit optionalem Befehl
                               (Kurzform: nur <HH:MM:SS> -> name="timer")
  bach countdown stop <name> - Countdown abbrechen
  bach countdown pause <name> - Countdown pausieren
  bach countdown resume <name> - Countdown fortsetzen
  bach countdown list        - Alle Countdowns anzeigen

BETWEEN
-------
  bach between on            - Between-Checks aktivieren
  bach between off           - Between-Checks deaktivieren
  bach between status        - Status anzeigen
  bach between use <name>    - Profil aktivieren
  bach between profile list  - Profile auflisten
  bach between profile show <name> - Profil Details anzeigen

BEAT
----
  bach beat                  - Alle Zeit-Infos anzeigen
  bach beat on               - Alle Zeit-Anzeigen aktivieren
  bach beat off              - Alle Zeit-Anzeigen deaktivieren
  bach beat interval <sek>   - Globales Intervall setzen


BEISPIELE
============================================================================

# Timer-Messung starten und nach 30 Sekunden abfragen
bach timer start work
# ... arbeiten ...
bach timer stop work

# Countdown mit Alarm: 5 Minuten Pause
bach countdown start pause 00:05:00 --after "echo Pause vorbei!"

# Between-Profile laden (z.B. Büro-Stunden)
bach between status
bach between use office-hours

# Globale Zeit-Status überprüfen
bach beat
bach beat on           # Alle Zeit-Module aktivieren
bach beat interval 60  # Alle 60 Sekunden aktualisieren


DATEIEN
============================================================================

Zustandsdateien (relative zu system/):

  data/.clock_state      - Uhrzeit-Anzeige Einstellungen
  data/.timer_state      - Timer Zustandsverwaltung
  data/.countdown_state  - Countdown Zustandsverwaltung
  data/.between_state    - Between Profil-Manager

Module:

  hub/time.py            - Handler-Implementierung
  tools/time_system.py   - TimeManager, ClockModule, TimerModule,
                           CountdownModule, BetweenManager


SIEHE AUCH
============================================================================

  Base Handler API:        docs/help/base.txt
  Konfiguration:           config/time_config.json
  Zeit-System Spezifikation: docs/TIME-SYSTEM.md
  Profil-Verwaltung:       docs/BETWEEN-PROFILES.md
