docs 🔑 CF-Zugang unmissverständlich: MCP read-only vs CF_API_TOKEN-Write (fix fresh-session permission-trap)

Frische Sonnet-Delegations-Session lief in die '10000 Authentication error'-Falle:
sie versuchte CF-Writes über den read-only MCP. Root Cause: .claude.json referenziert
nur die MCP-URL, NIE den Token in mcp/cloudflare/.env → kalter Agent kennt den Write-Pfad nicht.

- Handoff-Prompt: prominenter 'CF-KOMMUNIKATION'-Block (2 getrennte Pfade, exakte curl-
  Kommandos, '10000 = kein Rechteproblem, Pfad wechseln'-Hinweis im Ablauf).
- cf-tunnel-mapping.md §11: gleiche Klarstellung als SSoT-Callout inkl. Verifikation
  (no-op vnet-PATCH: MCP→10000, curl→success). 'Claude hat zig Tunnel erstellt' = immer
  via curl+Token, NIE via MCP.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/cf-tunnel-mapping.md

@@ -285,6 +285,13 @@ Tokens: nur im Container-Env + jederzeit via `GET /accounts/…/cfd_tunnel/<id>/
 - Zero-downtime: neue Connectoren parallel hoch → CNAMEs → alte Container/Tunnel weg. Verifiziert: gitea/omada/vw/ds-bf 200, grafana 302, pve-mcp 400 (MCP-Bare-GET), bf-nas 2 Connectoren healthy.
 - **Writes gehen NUR über `CF_API_TOKEN` (curl/Bearer)** — der `cloudflare`-MCP (OAuth) ist read-only (Create-Tunnel → `10000 Authentication error`).
 
+> ⚠️ **CF-Zugang für frische Sessions — die häufigste Stolperfalle (2× reproduziert 2026-07-17):** Es gibt **zwei getrennte** CF-Zugänge, und `~/.claude.json` verweist NUR auf den read-only-MCP (`https://mcp.cloudflare.com/mcp`), **nicht** auf den Write-Token → ein frischer Agent weiß nichts vom Token und meldet fälschlich „fehlende Permissions".
+> - **`cloudflare`-MCP** (`mcp__cloudflare__docs/search/execute`, OAuth): **strikt read-only**. Reads/Spec-Suche/Batch super; **jeder** Write → `10000: Authentication error` (erwartet, KEIN echtes Rechteproblem).
+> - **`CF_API_TOKEN` in `mcp/cloudflare/.env`** (scoped, `valid & active`): **der Write-Pfad.** Damit wurde das komplette 3-Tunnel-HA gebaut. Verifiziert 2026-07-17 mit identischem no-op-vnet-PATCH: MCP → `10000`, curl+Token → `success:True`.
+> - **Muster:** `cd ~/dev/bf-network-r6/mcp/cloudflare && set -a; . ./.env; set +a` → dann `curl -H "Authorization: Bearer $CF_API_TOKEN" …/accounts/$CF_ACCOUNT_ID/<pfad>`. Keys im .env: `CF_API_TOKEN/CF_ACCOUNT_ID/CF_ZONE_ID/CF_{BF,PVE,MM}_TUNNEL_ID`.
+> - Alle Calls über `api.cloudflare.com` → **WARP-unabhängig** (Rollback klappt auch bei totem Privatpfad).
+> - **Klarstellung „Claude hat doch zig Tunnel erstellt/geändert":** ja — aber immer über curl+Token, **nie** über den MCP. Der MCP war nie der Write-Pfad.
+
 **hass-400 (2026-07-12 präzisiert):** `hass`/`vw`/`gitea` sind aktuell wieder auf **`bypass`** (App „hass, vw, gitea") → der 400 ist **rein** der Origin-Layer, **nicht Access**. HA-Log: „Received X-Forwarded-For header from an untrusted proxy **10.40.20.10**". Die reziproken bf-pve-Connectoren (macmini `.20.167`, NAS `.20.10`) fehlen in HAs `http.trusted_proxies`. **Fix** = beide IPs + `use_x_forwarded_for: true` + Core-Restart. **Kein SSH-Key auf HA `.20.105` → user-gated** (oder Zugang geben). Access-Härtung (bypass→WARP) bleibt der zweite, device-gated Schritt.
 
 ---