# AGENTS.md – Leitfaden fuer KI-Agenten & Beitragende

Kurzanleitung, um in diesem Repo sicher und konsistent zu arbeiten.

## Was ist das hier?

ETL-Pipeline fuer LLM/RAG: holt Wissen aus Confluence, Webseiten und PDFs,
klassifiziert es nach **Scope** (intern/extern/allgemein) und **Domaene/Tool**,
filtert vertrauliche Inhalte und gibt nur geprueftes Wissen frei.

Verbindliche Architektur & Wissensfluss: **`.kiro/steering/architecture.md`**
(bei Aenderungen am Fluss dort die Diagramme mitpflegen).

## Projektstruktur

```
config/tools.yaml      Tool-Katalog (manuell gepflegt; Strategien/Scopes/Optionen)
config/general.yaml    Allgemeines, tool-uebergreifendes Wissen (scope: allgemein)
config/filter_rules.json  Blacklist + Redaction
src/connectors/        Extract: confluence, web_crawler (crawler+sitemap), pdf_parser
src/transformers/      md_converter, tagger, content_filter
src/review/            Review-Gate (Routing approved/pending)
src/main.py            Orchestrator
src/site.py            GitLab-Pages-Seite -> public/ (Uebersicht, Hilfe, Chatbot, Wissensquellen)
scripts/bootstrap_tools.py  EINMALIG: Tool-Katalog aus Support-Seite erzeugen
tests/                 pytest (offline, kein Netz)
```

## Lokale Workflows

```bash
source .venv/bin/activate
ruff check src tests scripts        # Lint (muss gruen sein)
python -m pytest -q                 # Tests (muss gruen sein)
python -m src.main --config config/tools.yaml --data output --staging staging   # ETL-Lauf
python -m src.site --data output --staging staging --out public   # Pages-Vorschau (lokal)
```

Confluence braucht `CONFLUENCE_URL` + `CONFLUENCE_TOKEN` (PAT, Bearer) als Env.

## Goldene Regeln (MUST)

1. **Keine Secrets in Git/Code.** Tokens nur als Env-/CI-Variablen. `gitleaks` in CI.
2. **Nur freigegebenes Wissen verlaesst die Pipeline** (`review_status: approved`).
3. **`scope` ist Pflicht** an jedem Dokument; im Zweifel `intern` (restriktiv).
4. **Output-Struktur** ist `output/processed/<scope>/<domaene>[/<tool>]` – nicht aendern,
   ohne `architecture.md`, README und Tests anzupassen.
5. **`config/tools.yaml` wird manuell gepflegt** (Bootstrap nur einmalig).
6. Nach Codeaenderungen: `ruff` + `pytest` gruen, dann erst committen.

## Scope-Klassifikation (intern vs. extern)

- **Keine Trennung innerhalb einer Seite.** Klassifiziert wird pro Tool/Quelle.
- **Tool-`scope`** in `tools.yaml`: `intern` | `extern` | `allgemein` | `mixed`
  (mixed = Quellen mit unterschiedlichem Scope; im Zweifel zwei Seiten).
- **Source-`scope`**: `intern` | `extern` | `allgemein` | `"intern,extern"`
  (letzteres nutzt die ganze Seite fuer beide Scopes, dupliziert).
- Quellen ohne eigenen Scope erben den Tool-Scope (mixed => intern).
- Allgemeines Wissen steht in **`config/general.yaml`**.

## Vorsicht bei Confluence-Schreibzugriffen

Das Skript-Muster kann Confluence-Seiten anlegen/aendern (z.B. Option-A-Template).
Solche Schreibzugriffe sind **additiv oder versioniert/revertierbar** zu halten und
vorher anzukuendigen. Niemals Inhalte ungefragt loeschen.