# Handoff — Stand 2026-05-24 > **Historical snapshot only (2026-05-25 cleanup).** This file is preserved > for audit/history. Do not treat its "start", "push", "deploy" or operator > instructions as current work. Use `PROGRESS.md`, `OPERATOR-CHECKLIST.md` > and the latest session notes for live status. **Vorgänger-Agent:** Claude Opus 4.7 (1M context) **Letzte aktive Session:** Bucket-1-Abbau + komplett-neue zentrale Observability/Sentry/Meilisearch/Loki-Infrastruktur. Viele Änderungen in der `toolctrl-labs/infra`-Repo (separates Gitea-Repo, NICHT der Boilerplate). **Ziel des Handoffs:** Nachfolger weiß in 5 Minuten wo wir stehen und was als Nächstes kommt. --- ## 0. Start hier (5-Minuten-Onboarding) **Lies in dieser Reihenfolge:** 1. Dieses Dokument komplett. 2. `HANDOFF-2026-05-21.md` für den davor liegenden archivierten Stand (#72-i18n + Lighthouse-CI-Rebuild + Worker-Crash-Fix). 3. **Wichtig: das `toolctrl-labs/infra`-Repo auf Gitea.** Die ganze zentrale Infra (Observability, Sentry, Meilisearch, Loki, WireGuard-Mesh) ist DORT dokumentiert, nicht im Boilerplate. Clone via `git clone https://git.tool-ctrl.de/toolctrl-labs/infra` und lies README.md + STANDARDS.md. 4. `.claude/CLAUDE.md` — React-Router-v7-Konventionen, strikt enforced. **Sofort-Sanity-Check:** ```bash git log --oneline -6 # HEAD = fa8b0e70, dahinter 1-2 lokale doc-commits dieser session git status -s # erwartet: packages/db/generated/** churn + ggf. neue handoff/progress edits git pull --rebase --autostash # andere Agenten arbeiten ggf. parallel ``` **Lokale unpushed Commits beachten:** Schon zu Session-Start lagen 2 Commits vor (`a3885ed5` Namespace-Split, `fa8b0e70` E2E-Locale-Switch für #72) die noch nicht auf `origin/main` sind. Plus die Doc-Edits dieser Session (PROGRESS.md + neues Handoff). Wenn du pushst, deployt Coolify automatisch — bei Doc-Only-Edits unkritisch, aber bewusst entscheiden. --- ## 1. Was diese Session bewegt hat ### 1.1 Bucket-1-Abbau (Operator-Pending-Items) | Item | Vorher | Jetzt | | --------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | #41 Read-Replica | „replica-deploy-pending" | als bewusst zurückgestellt dokumentiert (Single-DB-Fallback aktiv, kein Funktionsverlust) | | #78 Turnstile | nicht aufgesetzt | live aufgesetzt + per Negativ-Test verifiziert. Sicherheits-Fazit: aktuell nicht zwingend nötig weil keine öffentlichen Landingpages, aber Backend ist live | | #51 CDN | historical rollout parked | **backlogged** — Origin in Nürnberg + DACH-Audience + Cloudflare-Proxy reicht. Reaktivieren wenn internationale Kunden / große Media / Traffic-Spitzen | | #56 Stripe-Meter | „stripe-account-setup-pending" | **deferred** — noch keine zahlenden Overage-Kunden | | B3 (bcrypt-rehash) | nie live getestet | **verifiziert** — Login als `staging-admin@saas-ctrl.com` hat den Hash sauber von bcrypt auf argon2 umgesprungen. Dual-Mode-Code aus #28 funktioniert | | B5 Disk-Alert | „operator-config-pending" | **erledigt** — Coolify-Discord-Webhook aktiviert, Disk-Trigger an | | #23 Plugin Phase 3 (Cure53) | „operator-audit-pending" | **deferred** — Budget aktuell nicht da. Konsequenz im PROGRESS-Row notiert: Plugin-System geht NICHT in Produktion bis Audit + Sign-off durch sind | ### 1.2 Zentrale Infrastruktur neu aufgebaut **Was es vorher gab:** je Projekt eigener Side-Stack (Grafana+Prometheus auf Staging, Sentry auf Staging, Meilisearch auf Staging). Skalierte nicht für mehrere SaaS. **Was jetzt steht:** - **WireGuard-Mesh** `10.42.0.0/24` mit `control` als Hub, Peers `homeserver` (10.42.0.2), `boilerplate-staging` (10.42.0.3), `node1`/EX44 (10.42.0.4). IP-Forwarding und FORWARD-Chain auf control eingerichtet. ADR 008 im infra-Repo. - **Zentrales Grafana + Prometheus** auf `control` unter `https://grafana.saas-ctrl.com`. Scrapt jede Host-Node-Exporter + Docker-Stats-Exporter über das Mesh. Vier Project-Dashboards (Boilerplate, saas-ctrl.com, Homeserver, Hetzner Dedicated EX44). Admin-Pass auf `control:~/.cli-tokens/central-grafana-admin`. - **Zentrales Sentry** auf `node1`/EX44 unter `https://sentry.saas-ctrl.com`. Self-hosted Sentry-Stack hinter Caddy (TLS via Let's Encrypt). Org `sentry`, Team `boilerplate` mit Projekten `api`/`worker`/`web`. Boilerplate-Coolify-Envs zeigen auf neue DSNs + OTEL-Endpoint. SENTRY_AUTH_TOKEN rotiert in Coolify + Gitea-Secrets. Admin-Pass auf `control:~/.cli-tokens/central-sentry-admin`, DSNs unter `central-sentry-dsns`, Auth-Token unter `central-sentry-auth-token`. **Altes Sentry auf Staging läuft noch** — bewusst stehen gelassen, kann jetzt aber abgebaut werden, frisst ~4 GB RAM. - **Zentrales Meilisearch** auf `node1`/EX44 auf `10.42.0.4:7700`. Boilerplate-Apps zeigen via Coolify-Env auf den neuen. Alter Container auf Staging gestoppt + entfernt, Volume zur Sicherheit behalten. Master-Key auf `control:~/.cli-tokens/central-meilisearch-master-key`. **Beide Instanzen waren leer beim Switch** — niemand hatte auf Staging je Daten geschrieben die in Meili landen würden. - **Zentrales Loki + Promtail** auf jedem Host. Loki auf EX44 `10.42.0.4:3100`, Promtail auf allen vier Hosts schickt Container-Logs hin. Als Grafana-Datasource registriert. In Grafana → Explore → Loki auswählen → `{server="..."}`-Queries möglich. **Wichtige Lesson learned:** Docker port-publishing (`-p 10.42.0.4:7700:7700`) mit UFW + Docker-iptables auf EX44 funktioniert NICHT für Traffic von wg-Peers. Mittel zur Wahl auf EX44 ist `--net=host` plus explizites Binding auf die Mesh-IP. Pattern in infra-Repo dokumentiert. ### 1.3 Infra-Repo `toolctrl-labs/infra` massiv erweitert **Pushes:** `69636e7`, `6d26a84`, `dcf8ca1`, `174b9a9` auf `main`. - `README.md` — neue Sektionen: Central observability, WireGuard mesh, Central Sentry, Central Meilisearch, Central logs (Loki). Hosts-Übersicht aktualisiert (node1 hat jetzt Sentry, boilerplate-staging hinzugefügt, control hat zentrale Stacks). DNS-Records für grafana.saas-ctrl.com + sentry.saas-ctrl.com. - `STANDARDS.md` (neu) — verpflichtende Regeln für jeden SaaS im Estate. 11 Sections: zentrale Sentry-Nutzung, Host-Pflicht (Metrics+Logs), Per-Project-Dashboard, zentrale Meilisearch, Admin-SSO über Authentik, Repos in Gitea, Coolify-Konventionen, Cloudflare, Secrets, Backups, ADR-Norm. - `decisions/008-central-observability-and-sentry.md` (neu ADR) — begründet zentrale Architektur + WireGuard-Mesh (revisiert ADR 004). - `runbooks/add-host-to-central-observability.md` (neu) — Schritt-für-Schritt für neuen Host ans Mesh + Exporters + Prometheus-Targets. --- ## 2. Was JETZT als Nächstes zu tun ist ### Sofort sinnvoll, Bucket-1-Restposten: **B7 — Tenant-Snapshot-Verify** ist der einzige Bucket-1-Punkt der noch echt offen ist und den ein Agent ausführen kann. ABER hat zwei Hürden die vorher gelöst werden müssen: 1. Die `toolctrl-cli` ist nicht im Production-Image — auf Staging müsste der Repo geklont und Dependencies installiert werden, oder ein dediziertes CLI-Image gebaut werden. 2. S3/MinIO ist auf Staging nicht installiert. Entweder ein MinIO-Container dazustellen oder ein lokales Filesystem-Backend für die CLI nutzen (falls supportet). Empfehlung: MinIO auf Staging hinzufügen ist ein 20-Minuten-Job (analog zum Meilisearch-Pattern auf EX44, Host-Network mit Mesh-IP-Bind), dann CLI aus den Repo-Sources laufen lassen, snapshot+restore round-trippen, Row-Counts vergleichen. **Worker-Groups-Side-Finding (superseded)** — historical 2026-05-24 note: at that point staging only ran the `general` worker group. This was closed by the 2026-05-25 persistent worker-group provisioning; the current staging topology is five separate Coolify worker services (`general`, `mail`, `import`, `webhook`, `plugin`). See `docs/ops/worker-queues.md` and `docs/improvement-plan/archive/STAGING-ACCESS.md`. ### Bucket 2 — Code fertig, nur Live-Verifikation | # | Task | Was zu tun | | --- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | #19 | Magic-Link-Reset | Core flow + MailerSend smoke live-grün: token issued, queued, temporary mail worker completed provider send, consumed, replay rejected. **2026-05-25 addendum:** persistent Coolify worker-group provisioning landed; B-014 resolved and #19 closed. | | #26 | TOTP-MFA | Erledigt 2026-05-24: MFA-Enroll + TOTP-Challenge + Recovery-Code-Challenge + Cleanup auf Staging grün. | ### Bucket 3 — wartet auf Externe | # | Task | Was hängt | | --- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | #23 | Plugin Phase 3 | Cure53-Audit budget-deferred (siehe oben). Wenn Geld frei wird: `scripts/build-plugin-audit-package.sh` + Versand an Cure53 (oder Alternativvendor) | | #65 | Capacitor Mobile | Native Builds brauchen Mac+Xcode+Android-Studio. App-Store + Play-Store Submission. Apple Dev Account ($99/Jahr) + Google Play Console ($25 einmalig) | ### Bucket 4 — echte Code-Arbeit, die großen Tracks **Kleine deferrte Follow-ups (je < 1 Tag):** - #20 Magic-Link-Invitation — `User.passwordHash`-nullable-Migration - #27 Password-Policy — Login-Soft-Banner - #39 Pub/Sub Cache — Reconnect-Flush + Testcontainers-Integrationstest **Großtracks (ein Track pro fokussierter Session):** - **#38** Shared-Store: Session-Store sync→async — 2-3 Tage, **höchstes Risiko**, eigene saubere Session zwingend - **#42** Outbox completion — ~1 Woche, Call-Site-Migrationen + Admin-UI + CLI re-queue + E2E - **#53** Feature-Flag-Builder — Visual Rule-Builder-UI + Affected-Count-Endpoint + Kill-Switch + 4 v1-Callsites - **#55** AI-Cost Phase 2 — Admin- + Tenant-Web-UIs (Engine fertig) - **#59** Realtime-Collab — Snapshot/Cleanup-Cron + Presence-Bar-UI + Permission-Helper + Rows-/Workflow-Editor-Integration - **#21 + #22** Plugin Phase 1+2 — Hot-reload, Marketplace, sandboxed iframe, weitere 13 Hook-Points (NICHT prod-rollen ohne Cure53-Audit) - **#62** Storybook — Lost-Pixel Visual-Regression, Toolbar-Globals, Tailwind-v4-Pipeline - **#73** WCAG P2 — `no-autofocus` (88) per Einzelfall-Urteil; `verify-a11y-baseline.mjs` muss vorher repariert/erstellt werden - **#76** Test-Coverage — Per-Modul-Gates auf 85-95% kritische Pfade hochziehen - **#17** FileObject-Scan-Columns — von Bucket 1 reklassifiziert als echtes Code-Work: Scan-Spalten am `FileObject`-Model fehlen komplett, plus Scan-Result-Persistenz + User-Notification + Audit-Events sind nicht gebaut. Detail-MD `01-tech-debt-foundation/av-scanner-layer-2.md` ist Wahrheit, der Status-String im PROGRESS war irreführend ### Housekeeping (lose Enden dieser Session) - **Altes Sentry auf Staging stoppen** — `boilerplate-staging:/opt/sentry-stack/` läuft weiter und frisst ~4 GB RAM, obwohl alle Apps schon zum neuen umgelenkt sind. Wenn Verifizierung gesehen wurde dass das neue stabil ist, alten Stack mit `docker compose down` runterfahren. Volume bewusst behalten falls Rollback nötig. - **2 unpushed `#72`-Commits** auf Boilerplate (`a3885ed5`, `fa8b0e70`). Beide sind sauber, wurden aber nie gepusht. Wenn du sie weghaben willst, einfach `git push`. - **PROGRESS.md** hat in dieser Session 3 Doc-Edits bekommen (#41/#51/#23 Status-Deferrals). Auch noch nicht committed/gepusht. Ich committe sie zusammen mit diesem Handoff. - **Coolify-Env-Duplikate** — Coolify's API erzeugt mit PATCH neue Einträge statt zu updaten. Auf den 3 Boilerplate-Apps liegen ein paar duplizierte Envs (z.B. `SEED_ADMIN_EMAIL`/`SEED_ADMIN_PASSWORD`). Funktional fängt Coolify den letzten Wert ab, kosmetisch unsauber. Bei Gelegenheit über die Coolify-API per DELETE aufräumen. - **Marketing-VM** ist noch nicht im zentralen Monitoring. Kein SSH-Key registriert. Wenn das in den Mesh soll: Runbook in der `infra`-Repo unter `runbooks/add-host-to-central-observability.md`. --- ## 3. Konventionen (unverändert, aber wichtig) - Alle Commits direkt auf `main`. `git pull --rebase --autostash` vor Workflow-Start. - Lefthook pre-commit (test-density / eslint-baseline / secrets / lint-staged) und pre-push (full `pnpm typecheck`, ~50s) sind hart. - React Router v7: Route-Type-Imports IMMER `./+types/`, nie relativ. - Niemals `git add -A` — explizite Paths. `packages/db/generated/**` niemals mitcommitten. - `pnpm`, nicht npm. Tests via `npx vitest run `. - Co-Author-Trailer: `Co-Authored-By: Claude Opus 4.7 (1M context) ` - Push deployt auto via Coolify auf Staging. - **NEU: Wenn etwas Infra-mäßig ist, gehört es ins separate `toolctrl-labs/infra`-Repo, nicht ins Boilerplate.** Boilerplate-Repo ist nur für die SaaS-Codebase. --- ## 4. Operator-Profil-Notiz - B2B-SaaS, SEO irrelevant (alte Note bleibt gültig) - Antwortstil: kurz, plain, keine Tabellen-Wände, keine Emojis, keine inline-Code-Formatierung für Dinge die nicht Code sind (Pfade, URLs, Env-Var-Namen als Fließtext). Ein Item nach dem anderen abarbeiten, nicht alle Buckets gleichzeitig dumpen. --- **Ende des Handoffs.** Bei Unklarheit fragen, nicht raten.