docs: accurate adoption modes + visibility limitation

USAGE.md

@@ -1,10 +1,15 @@
 # ci-templates — org-weites Quality-Gate
 
-Reusable Workflow fuer alle Repos (digiflo, sanube, keim, etb, swd, florian-projects).
+Reusable Workflow fuer alle Orgs. Scans (gitleaks/semgrep/trivy/actionlint) laufen per
+**Default**; Sprach-Linter (python/node/php) sind **opt-in**. **Report-only** per Default,
+`blocking: true` macht SAST/Vuln/Lint zum harten Gate. **Secrets (gitleaks) sind IMMER hart.**
 
-## Adoption (3 Zeilen pro Repo)
-Datei `.gitea/workflows/quality.yml` im Ziel-Repo anlegen:
+## WICHTIG — Sichtbarkeit (Gitea-Limitation, verifiziert 2026-08-25)
+Private reusable Workflows koennen von anderen Repos NICHT gelesen werden
+("no permission to read reusable workflow"). Zwei Adoptions-Modi:
 
+### A) ci-templates PUBLIC  (empfohlen fuer org-weit)
+Pro Repo `.gitea/workflows/quality.yml`:
 ```yaml
 name: quality
 on: [push, pull_request]
@@ -12,29 +17,22 @@ jobs:
   quality:
     uses: digiflo/ci-templates/.gitea/workflows/quality.yml@main
     with:
-      python: true      # je nach Repo: python/node/php auf true
-      # blocking: true   # spaeter: SAST/Vuln/Lint hart als Gate
+      python: true       # node: true / php: true je nach Repo
+      # blocking: true    # spaeter: hartes Gate
 ```
 
-## Was laeuft
-| Job | Tool | Default |
-|-----|------|---------|
-| secret-scan | gitleaks | **blockierend** (Secrets brechen immer ab) |
-| sast | semgrep (`p/ci`) | report-only |
-| vuln-scan | trivy fs (HIGH/CRITICAL) | report-only |
-| actionlint | actionlint | report-only |
-| python-lint | ruff (check+format) | opt-in, report-only |
-| node-lint | eslint | opt-in, report-only |
-| php-lint | php -l + phpstan | opt-in, report-only |
+### B) ci-templates PRIVAT -> lokale Kopie pro Repo
+Komplette `quality.yml` ins Ziel-Repo kopieren, lokal referenzieren
+(`uses: ./.gitea/workflows/quality.yml`). Nachteil: Updates muessen nachgezogen werden.
 
-`blocking: true` macht SAST/Vuln/Lint zum harten Gate. Zusammen mit Branch-Protection
-(Required status checks) auf `main` wird das erzwungen.
+## Inputs
+| Input | Default | Wirkung |
+|-------|---------|---------|
+| skip_secret_scan / skip_sast / skip_vuln | false | Scan abschalten |
+| python / node / php | false | Sprach-Linter aktivieren |
+| blocking | false | SAST/Vuln/Lint hart (Secrets immer hart) |
 
-## Constraint
-Runner ist `ct117-docker` (catthehacker-Image, gecached). **Keine neuen Docker-Hub-Images
-im Job ziehen** (unauth Pull-Limit) — alle Tools kommen als GitHub-Release-Binary / via pip.
-
-## Cross-Org-Nutzung
-Dieses Repo ist privat. Damit Repos anderer Orgs (sanube/keim/...) den Workflow ziehen
-koennen, entweder dieses Repo auf "public" (nur harmloses CI-YAML) stellen ODER pro Org
-eine Kopie. Innerhalb `digiflo` funktioniert es sofort.
+## Constraints
+- Runner `ct117-docker` (catthehacker, Debian/PEP668): pip mit `--break-system-packages`.
+- **KEINE** neuen Docker-Hub-Images im Job (unauth Pull-Limit) -> Tools via GitHub-Release/pip.
+- Fuer harte Gates zusaetzlich Branch-Protection (Required status checks) auf `main` setzen.