# Portabilität: UNIVERSAL
# Version: 2.0.0
# Zuletzt validiert: 2026-05-17
# Nächste Prüfung: 2026-08-17

BACH PATHS - Zentrale Pfadverwaltung
=====================================

bach_paths.py ist die "Single Source of Truth" für alle Pfade in BACH.
Keine hartcodierten Pfade mehr - alles zentral an einem Ort.

STANDORT
--------
system/hub/bach_paths.py

HAUPTFUNKTION: get_path(name)
-----------------------------
Die wichtigste Funktion - gibt den Pfad zu einem benannten Verzeichnis zurück.

Beispiele:
    from bach_paths import get_path

    tools_dir = get_path("tools")           # system/tools/
    template = get_path("bericht_template") # Vorlage für Berichte
    db = get_path("db")                     # bach.db Datenbank
    berichte = get_path("berichte")         # Berichte-Verzeichnis

IMPORT VON ÜBERALL
-------------------
Methode 1 - Wenn hub/ im sys.path (z.B. in hub/_services/):
    from bach_paths import BACH_ROOT, get_path

Methode 2 - Universal (funktioniert von überall):
    import sys
    from pathlib import Path

    # Finde bach_paths.py automatisch
    _current = Path(__file__).resolve()
    for _parent in [_current] + list(_current.parents):
        _hub = _parent / "system" / "hub"
        if _hub.exists():
            if str(_hub) not in sys.path:
                sys.path.insert(0, str(_hub))
            break

    from bach_paths import BACH_ROOT, get_path

VERFÜGBARE PFADE
-----------------
Hierarchie:     root, bach, system, hub
System:         data, gui, skills, dist
Skills:         tools, help, agents, experts, workflows, partners, services, templates
Data:           logs, backups, archive, trash, messages
Root:           user, docs, exports, extensions
Datenbanken:    db, bach_db, archive_db
User:           user_documents, persönlich
Steuer:         steuer, steuer_2025, belege, bundles
Partner:        gemini, claude, ollama
Berichte:       förderplanung, berichte, berichte_output, berichte_klienten, berichte_data, berichte_bundles, klienten, quarantine
Templates:      bericht_template
Extern:         wissensdatenbank

BEISPIEL: Tool-Import
---------------------
Problem: Tools liegen in system/tools/
Lösung mit bach_paths:

    try:
        from c_ocr_engine import ocr_pdf
    except ImportError:
        from bach_paths import get_path
        tools_dir = get_path("tools")
        if str(tools_dir) not in sys.path:
            sys.path.insert(0, str(tools_dir))
        from c_ocr_engine import ocr_pdf

BEISPIEL: Template-Pfad
-----------------------
    from bach_paths import get_path

    template_path = get_path("bericht_template")
    # -> C:/Users/.../BACH/system/skills/_templates/bericht_template_geiger_universal.docx

WEITERE FUNKTIONEN
------------------
list_paths()              - Alle verfügbaren Pfade als Dict
get_tool_path(name)       - Findet Tool in tools/ oder Unterordnern
get_partner_dir(partner)  - Partner-Verzeichnis (gemini, claude, ollama)
get_belege_path(anbieter) - Belege-Pfad mit optionalem Anbieter
resolve(relpath)          - Relativen Pfad aufloesen
validate()                - Alle kritischen Pfade prüfen

DB-OVERRIDES
------------
Pfade können in der DB überschrieben werden:

    from bach_paths import set_path_override, get_path_with_override

    # Override setzen
    set_path_override("wissensdatenbank", "D:/Meine/Datenbank")

    # Override nutzen
    path = get_path_with_override("wissensdatenbank")

CLI NUTZUNG
-----------
    python bach_paths.py templates           # Einzelnen Pfad abrufen
    python bach_paths.py --list              # Alle Pfade auflisten
    python bach_paths.py --validate          # Pfade validieren
    python bach_paths.py --set PATH name     # Override setzen (mit name)
    python bach_paths.py --overrides         # DB-Overrides anzeigen
    python bach_paths.py --json              # Ausgabe als JSON

VARIABLEN (für direkten Import)
--------------------------------
    from bach_paths import (
        BACH_ROOT,      # Repository-Root
        SYSTEM_ROOT,    # system/
        HUB_DIR,        # system/hub/
        DATA_DIR,       # system/data/
        SKILLS_DIR,     # system/skills/
        TOOLS_DIR,      # system/tools/
        BACH_DB,        # system/data/bach.db
        USER_DIR,       # user/
        BERICHTE_DIR,   # user/documents/foerderplaner/Berichte/
    )

SELF-HEALING
------------
bach_paths berechnet alle Pfade relativ zum eigenen Standort.
Wenn BACH verschoben wird, funktioniert alles weiterhin -
keine manuellen Anpassungen nötig.

PFAD-HEILUNG: NICHT NOETIG
--------------------------
bach_paths.py macht manuelle Pfad-Heilung überfluessig!
Alle Laufzeit-Pfade werden dynamisch berechnet.

Nur für Dokumentations-Updates (Help-Texte, Wiki, Markdown):
  bach --maintain docs-paths

SIEHE AUCH
----------
- bach path validate               Pfade prüfen
- bach --help path                 Path-Handler Doku
- bach --help tools/path_healer    Dokumentations-Pfad-Updater
