# Handoff — Stand 2026-05-25 (Autonomer Nacht-Modus, Nonstop) > **Historical snapshot only (2026-05-25 cleanup).** This file is preserved > for audit/history. Do not treat its "nonstop", "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:** B7-Tenant-Snapshot-Verify komplett durchgezogen, alle vier losen Enden aus dem 2026-05-24-Handoff geschlossen. > Historical request captured verbatim for audit, superseded by the warning > above: "Operator schläft. Du arbeitest NONSTOP an dem Plan in Section 2, > machst alles durch was du machen kannst, deployst am Ende selbst und > verifizierst gegen Coolify + Gitea + Browser." --- ## 0. Start hier (5-Minuten-Onboarding, dann SOFORT loslegen) **Lies in dieser Reihenfolge:** 1. Dieses Dokument komplett bis zum Ende. 2. `HANDOFF-2026-05-24.md` für den davor liegenden archivierten Stand (Bucket-1-Abbau, zentrale Observability-Infra). 3. `.claude/CLAUDE.md` — React-Router-v7-Konventionen sind hart enforced. 4. Wenn du Infra anfasst: `toolctrl-labs/infra` auf Gitea (`git clone https://git.tool-ctrl.de/toolctrl-labs/infra`), README + STANDARDS. **Sofort-Sanity-Check:** ```bash git log --oneline -7 # HEAD muss d6e19aab sein (dieses handoff) # d6e19aab docs(handoff): 2026-05-25 — akkord-modus for nightshift agent # 377b96a4 feat(cli): wire tenant snapshot/restore + fix B7 PII gaps # 12f23558 docs(handoff): 2026-05-24 — central observability + Sentry + Meili + Loki # fa8b0e70 test(i18n): add e2e locale-switch coverage and label the locale picker (#72) # a3885ed5 feat(i18n): split billing/crm/auth/emailMarketing into per-area namespaces (#72) git status -s # erwartet: nur packages/db/generated/** churn git pull --rebase --autostash ``` **Push-Status zum Sessionsstart:** 5 lokale Commits liegen vor `origin/main`. Der Operator hat den Push aus dieser Session ausdrücklich an DICH delegiert — pushe sie GEMEINSAM mit deiner eigenen Arbeit ganz am Ende (siehe Section 4 „Deploy + Verifikation"). --- ## 1. Was die letzte Session erledigt hat ### 1.1 B7 — Tenant-Snapshot-Verify (vollständig) War der einzige echt offene Punkt aus Bucket 1. Drei Befunde: **A) Wiring-Lücke geschlossen.** Die `tenant snapshot`/`tenant restore`-Citty-Commands waren reine Arg-Validators. Jetzt: - `packages/cli/src/commands/tenant/prisma-runner.ts` — PrismaRunner + PrismaRestoreRunner gegen `@toolctrl/db`. Cursor-Pagination (PK `id`, `TenantSettingsRow` cursor `tenantId`). - `packages/cli/src/commands/tenant/json-codec.ts` — JSON-Replacer für Date/BigInt/Buffer/Decimal (über `this[key]`-Trick um toJSON-Mangling zu umgehen) plus DMMF-freie Schema-Parser für Decode. - `packages/cli/src/commands/tenant/env.ts` — BACKUP\_\*-Env-Resolver tailored auf Tenant-Ops (S3 + Encryption optional). - Snapshot/Restore-Commands rufen jetzt echte Runner auf. **B) PII-Leaks im Anonymizer gefunden.** Real-Tenant-Snapshot gegen Staging-DB `demo-pro-crm` per SSH-Tunnel ergab 2 plaintext-Email-Leaks: - `SupportTicket`-Map referenzierte schemafremde Keys `title`/`description` statt `subject`/`message`; `fromEmail` + `fromUrl` waren ungemappt. - `Event`-Map referenzierte `payload` statt des realen Feldes `data`. Beide gefixt. Neuer Snapshot grep-clean. **C) Restore-Design-Limit dokumentiert.** Restore in leere DB scheitert für 6 Modelle (TenantUser, TenantIpAddress, UserRole, Event, Log, SupportTicket — 32 Rows) wegen FK auf globales `User`-Model. Runbook `docs/ops/tenant-snapshot.md` erweitert um „Restore prerequisites: global rows are NOT in the snapshot". 6/12 Modelle mit Rows restoren clean. **Dieses Limit ist Task G in deinem Akkord-Plan.** Commit `377b96a4`. 317/319 Unit-Tests grün. Typecheck grün. `PROGRESS.md` Row #44 erweitert. ### 1.2 Vier lose Enden geschlossen - Altes Sentry auf `boilerplate-staging` runter, RAM 24Gi → 4.6Gi. - Marketing-VM im Mesh als `10.42.0.5`, `up=1` beide Jobs, infra-Repo Commit `66f1357` schon gepusht. - 63 Coolify-Env-Duplikate weg, kein Redeploy ausgelöst. - Coolify-Token liegt unter `~/.cli-tokens/coolify-token`, API auf `http://195.201.133.26:8000/api/v1`. --- ## 2. Historical Arbeitsplan — superseded ### 2.1 Goldene Regeln (jede einzelne ist nicht verhandelbar) 1. **STOPPE NICHT** bevor jeder Task in Section 2.2 entweder fertig committed ist oder als „nicht machbar" mit klarer Begründung in PROGRESS.md vermerkt ist. Wenn ein Task hängt — überspringe ihn, notiere warum, mache mit dem nächsten weiter. KEINE Pausen für Rückfragen, KEINE „darf ich…" — du hast volle Entscheidungsbefugnis innerhalb dieser Regeln. 2. **NUTZE TaskCreate / TaskUpdate / TaskList kontinuierlich.** Als allererstes nach dem Sanity-Check legst du für JEDEN Task in 2.2 ein TaskCreate an (status pending). Du markierst jeden als `in_progress` bevor du anfängst, `completed` wenn du fertig bist. Lass die Liste durchgängig aktuell — sie ist deine eigene Spur. 3. **NUTZE SUBAGENTS aggressiv.** Pro Task ist ein Subagent-Vorschlag in 2.2 angegeben. Wenn du `Plan` brauchst weil unklar — spawn `Plan`. Wenn du parallel arbeiten kannst — spawn mehrere `general-purpose` in einem Tool-Use-Block. Wenn du suchst — spawn `Explore` statt selbst zu greppen. Subagents geben dir Zusammenfassungen ohne deinen Kontext zu fluten. 4. **ATOMARE COMMITS pro Task.** Eine logische Änderung pro Commit. Co-Author-Trailer auf Claude. Conventional-Commit-Prefix. Lefthook läuft pre-commit, lass den durch — wenn er rot wird, fixe was er findet und re-committe, gib nicht auf. 5. **PUSHE ERST AM ENDE.** Alle deine Commits + die 5 schon-lokalen werden in EINEM Push am Schluss rausgeschickt, GEFOLGT VON Coolify-Deploy-Verifikation. Details in Section 4. 6. **PROGRESS.md nach jedem fertigen Task** updaten (Datum, Commit-Hashes, was tatsächlich landed, was deferred wurde und warum). Eine Zeile pro Task reicht wenn das in die existierende Row paßt. 7. **NIEMALS `git add -A`** — explizite Paths. `packages/db/generated/**` NIEMALS mitcommitten. 8. **Kein UI-Design-Urteil treffen.** Wenn ein Task „wie soll das aussehen?" verlangt: vorhandene UI-Primitives aus `packages/ui` recyclen, nichts Neues erfinden. Banner-Texte, Button-Labels — nimm das Offensichtliche (englisch oder das was die Codebase vorhandene Strings hat). 9. **Tests müssen grün bleiben.** `pnpm test` + `pnpm typecheck` müssen vor jedem Commit grün sein. Lefthook erzwingt typecheck pre-push. 10. **React Router v7 Konventionen einhalten** — Route-Type-Imports IMMER `./+types/`, nie relativ. ### 2.2 Tasks — in dieser Reihenfolge **Lege als ALLERERSTES TaskCreate für jeden dieser sieben Tasks an.** Markiere `in_progress` bevor du startest, `completed` wenn der Commit liegt. #### Task A — #20 Magic-Link-Invitation: `User.passwordHash` nullable **Detail-MD:** `docs/improvement-plan/01-tech-debt-foundation/magic-link-invitation.md` **Subagent:** `general-purpose`. Optional `Plan` vorab für Migration-Strategie. **Was zu tun:** 1. Prisma-Migration `User.passwordHash String?` (nullable). Existierende Hashes NICHT touchen. 2. Auth-Boundary: Login mit null passwordHash → Magic-Link-Flow statt 401. 3. Invitation-Flow: neuer User ohne passwordHash, sofort Magic-Link statt Passwort-Setzen-Email. 4. Tests: bestehende Login-Tests grün, neue Tests für null-passwordHash-Pfad. **Akzeptanz:** typecheck + tests grün, Detail-MD Progress-Log erweitert, PROGRESS Row updated. **Achtung:** User mit null passwordHash dürfen NICHT plötzlich passwortlos einloggbar werden wenn sie nicht explizit invited sind. Prüfe einen „wurde-eingeladen"-Marker, nicht nur das null. #### Task B — #27 Password-Policy Login-Soft-Banner **Detail-MD:** `docs/improvement-plan/01-tech-debt-foundation/password-policy.md` **Subagent:** `general-purpose`. **Was zu tun:** 1. Banner-Komponente die nach Login eingeblendet wird wenn das aktuelle Passwort die neue Policy nicht erfüllt. Vorhandene `packages/ui`-Primitives nutzen, nichts Neues designen. 2. Dismissible + „Remind me in 7 days"-Pattern aus Detail-MD. 3. Server-side: welche User-IDs „policy-non-compliant" sind (Funktion vermutlich da). 4. Tests für visible/dismissed States. **Akzeptanz:** Banner zeigt bei schwachem-Hash-Test-User, verschwindet nach Dismiss + Reload für 7 Tage. #### Task C — #39 Pub/Sub Cache Reconnect-Flush + Testcontainers **Detail-MD:** `docs/improvement-plan/03-scaling-infrastructure/pubsub-cache-invalidation.md` **Subagent:** `Explore` vorab um aktuellen Reconnect-Pfad zu kartieren, dann `general-purpose`. **Was zu tun:** 1. Bei Redis-Reconnect: lokale Cache-Einträge die zwischen Disconnect und Reconnect entstanden sein könnten flushen (oder invalidate-all auf Subscription-Channel-Topic). 2. Integrationstest mit `testcontainers` (Redis im Container starten, Verbindung killen, neue starten, asserten dass stale Reads weg sind). 3. Opt-in-Pattern wie `packages/db/src/outbox-claim.test.ts` (env `PUBSUB_TEST_REDIS_URL` o.ä.). **Akzeptanz:** Test grün lokal mit Container, skipped ohne env. #### Task D — #42 Outbox-Completion (ohne Admin-UI) **Detail-MD:** `docs/improvement-plan/03-scaling-infrastructure/outbox-pattern.md` **Subagent:** `Plan` vorab (Task ist groß) → dann mehrere `general-purpose` in Wellen (Call-Site-Migrationen können parallel). **Scope:** 1. Call-Site-Migrationen: jeden Outbox-Producer aus der Detail-MD auf `outboxDispatch` umstellen. 2. CLI `toolctrl-cli outbox requeue --event-id=X` und `outbox requeue --type=Y --since=Z`. 3. E2E: Producer schreibt Event → Worker dispatcht → Receiver empfängt → AuditEvent. **Bewusst raus:** Admin-UI (`/app/admin/outbox`) — Design-Entscheidung. Detail-MD annotieren („Admin-UI deferred — needs UX input"). #### Task E — #76 Test-Coverage Per-Modul-Gates **Detail-MD:** in `docs/improvement-plan/` — selbst finden (`grep -r "coverage" docs/improvement-plan` o.ä.). **Subagent:** `Explore` für Coverage-Status pro Modul, dann `general-purpose` pro Modul. **Was zu tun:** 1. Per-Modul Coverage-Gates aktivieren (vitest config in jedem Paket). 2. Kritische-Pfad-Module auf 85-95% hochziehen — Liste in Detail-MD. 3. Fehlende Tests schreiben statt Coverage künstlich drücken. NICHT in `packages/db/generated/**` testen, NICHT Mocks-only. **Akzeptanz:** Per-Modul-Gates aktiv und grün. #### Task F — #62 Storybook Lost-Pixel Setup **Detail-MD:** `docs/improvement-plan/08-mobile-cli-storybook-sdk/storybook.md` **Subagent:** `general-purpose`. **Was zu tun:** 1. `lost-pixel` als CI-Step gegen Storybook-Builds. 2. Toolbar-Globals (i18n-Locale-Switch, Theme-Switch) als Decorators. 3. Tailwind-v4-Pipeline für Storybook sauber. 4. Baseline-Snapshots committen. **Bewusst raus:** neue Stories schreiben. #### Task G — Globaler-Row-Extractor im Tenant-Snapshot (schließt B7-Limit) **Detail-MD:** `docs/improvement-plan/03-scaling-infrastructure/tenant-snapshot.md` (eigene Section am Ende ergänzen) **Subagent:** `Plan` für Design (welche globalen Models? `User` zwingend, weitere?), dann `general-purpose`. **Was zu tun:** 1. Beim Snapshot referenzierte `User`-Rows (+ andere globals nach Bedarf) mitextrahieren. Neuer Top-Level-Manifest-Eintrag `globals/User.jsonl` (cleaner als ins existierende Schema integrieren). 2. Restore: globals ZUERST replayen (FK-Reihenfolge), dann tenant-scoped. 3. Anonymizer-Coverage für neue globale Felder (User hat `email`, `firstName`, `lastName`, `phone`, etc. — alle anonymisieren). 4. Round-Trip-Integration-Test erweitern: Restore in WIRKLICH leere DB muss jetzt grün sein für alle 12 Models. 5. Runbook „Restore prerequisites"-Sektion entschärfen. **Akzeptanz:** Lokaler Round-Trip-Test gegen zwei frische pgvector-DBs ohne Vorab-Seed schreibt jetzt alle Models clean. PROGRESS Row #44 entsprechend aktualisieren. ### 2.3 Tabu — auf keinen Fall anfangen - **#19 Magic-Link-Reset live-verify** (braucht echte Email). - **#26 TOTP-MFA live-verify** (braucht echten Authenticator). - **#38 Shared-Store async Session** (höchstes Risiko, Operator-anwesend zwingend). - **#53 / #55 / #59** (UI-Design-Entscheidungen). - **#21 / #22 Plugin Phase 1+2** (Cure53-Audit-Block — Erweiterung jetzt sinnlos). - **#73 WCAG P2** (Einzelfall-Urteile). - **#17 FileObject-Scan-Columns** (zu groß, eigene Session). - **Worker-Groups Coolify-Services** (Coolify-Service-API kann Live-Apps stören — Operator macht händisch). Wenn ein Task in 2.2 nicht funktioniert: ÜBERSPRINGEN, in PROGRESS.md mit Begründung notieren, NÄCHSTEN nehmen. Nicht hängenbleiben. --- ## 3. Tools die du nutzen sollst - **TaskCreate / TaskUpdate / TaskList**: deine Aufgaben-Liste mit Checkboxen. Pflicht für Section 2.2. - **Agent-Tool (Subagents)**: `Plan` für Architektur-Fragen, `Explore` für Codebase-Suchen, `general-purpose` für Implementierung. Parallel-Spawn in einem Tool-Use-Block wenn unabhängig. - **Bash**: für git, pnpm, ssh, docker, curl, prisma-Migrationen. - **Read / Edit / Write**: für Code-Änderungen. - **Playwright** (CLI über Bash) für Browser-Smoke am Ende — siehe Section 4. - **gsd-Skills** wo passend (z.B. `gsd-add-tests` wenn du nach einem Großtask Tests nachholen willst). Skill-Liste siehst du in deinem System-Prompt. --- ## 4. Deploy + Verifikation am Ende (PFLICHT) Wenn alle Tasks aus 2.2 entweder `completed` oder „deferred mit Begründung" sind, mach das hier — auch das im Akkord ohne Stop: ### 4.1 Pre-flight ```bash cd /Users/raffaelsheikh/Documents/GitHub/boilerplate git status -s # Working tree sauber (nur generated churn) git log --oneline origin/main..HEAD # zeigt deine Commits + die 5 aus der vorigen Session pnpm typecheck # muss EXIT=0 sein pnpm test # alle suites grün ``` Wenn typecheck oder tests rot sind: fixe es. Push NICHT mit rotem Code. ### 4.2 Push ```bash git push origin main 2>&1 | tee /tmp/push.log ``` Push triggert Gitea-Webhook → Coolify-Auto-Deploy für die 3 boilerplate-Apps (web/api/worker). Lefthook pre-push fährt nochmal `pnpm typecheck` (~50s). ### 4.3 Coolify-Deploy verifizieren ```bash TOKEN=$(cat ~/.cli-tokens/coolify-token) for app in mrf8lj70kmy9hqprx9dd6w7q e109dzc3xzjxi54llfje4tob k6cibn0rkrrl7izw970ao1l4; do echo "== $app ==" curl -s -H "Authorization: Bearer $TOKEN" \ "http://195.201.133.26:8000/api/v1/applications/$app" \ | python3 -c "import sys,json; d=json.load(sys.stdin); print('status:', d.get('status'), 'last_online_at:', d.get('last_online_at'))" done ``` Status muss `running:healthy` werden für alle 3. Wenn ein Deploy hängt: warte aktiv per Polling (`until ; do sleep 10; done`-Pattern, NICHT mit kurzen sleeps zwischen Bash-Calls — Harness blockt das, nutze `Monitor`-Tool für lange Waits oder eine `until`-Schleife in einem einzelnen Bash-Call). Wenn Deploy nach 10 min nicht grün: in PROGRESS.md klar dokumentieren, im Coolify-UI-Frontend (über den Operator) zu untersuchen. Container-Restart-Verifikation: ```bash ssh boilerplate-staging "for c in mrf8lj70kmy9hqprx9dd6w7q-003059987808 e109dzc3xzjxi54llfje4tob-003103228130 k6cibn0rkrrl7izw970ao1l4-003119324400; do echo \"\$c: \$(docker inspect \$c --format '{{.State.Status}} since {{.State.StartedAt}}')\"; done" ``` (Container-Namen ändern sich pro Deploy — falls die alten weg sind, `docker ps --format '{{.Names}}'` für die neuen, dann obigen Befehl darauf.) ### 4.4 Gitea Push verifizieren ```bash curl -s "https://git.tool-ctrl.de/toolctrl-labs/boilerplate/commits/branch/main" | grep -oE "377b96a4|d6e19aab|" | head ``` (Oder kurzer ssh-check: `ssh git.tool-ctrl.de "cd /var/lib/gitea/git/toolctrl-labs/boilerplate.git && git log --oneline main -5"` — Path kann abweichen.) ### 4.5 Browser-Smoke gegen Live-Staging Playwright-Config liegt in `/Users/raffaelsheikh/Documents/GitHub/boilerplate/playwright.config.ts`. Staging-URL ist `https://boiler.saas-ctrl.com` (web), `https://admin.boiler.saas-ctrl.com` (admin), `https://app.boiler.saas-ctrl.com` (tenant-app falls separat). Mindest-Smoke-Tests: 1. **Login-Page lädt**: `curl -sI https://boiler.saas-ctrl.com/login | head -3` → HTTP 200. 2. **Login-Flow** mit Test-Credentials (Operator-Admin steht in `~/.cli-tokens/boilerplate-staging-admin`): Playwright-Skript das login → Dashboard sieht → Screenshot ablegt. Skript kannst du ad-hoc schreiben, z.B.: ```ts import { chromium } from "playwright"; const b = await chromium.launch(); const p = await b.newPage(); await p.goto("https://boiler.saas-ctrl.com/login"); await p.fill('input[name="email"]', process.env.SMOKE_EMAIL!); await p.fill('input[name="password"]', process.env.SMOKE_PASSWORD!); await p.click('button[type="submit"]'); await p.waitForURL(/dashboard|app|home/); await p.screenshot({ path: "/tmp/staging-smoke.png" }); await b.close(); ``` Run: `SMOKE_EMAIL=... SMOKE_PASSWORD=... pnpm tsx /tmp/smoke.ts` 3. **Healthcheck-Endpoint** falls vorhanden: `curl -s https://boiler.saas-ctrl.com/api/healthz` (oder `/health` — selbst finden). 4. **Sentry frisst Events**: schmeiß einen synthetischen Error via `curl -X POST https://boiler.saas-ctrl.com/api/_diag/throw` (falls so ein Endpoint existiert, sonst Login-mit-falschem-Passwort und das wird im Sentry sichtbar). Verifiziere im zentralen Sentry-UI ist eher Operator-Job, aber dass der Request mind. HTTP-Antwort gibt zeigt der curl. Wenn Smoke-Tests rot werden: in PROGRESS.md notieren, ein Rollback-Plan ist Operator-Entscheidung — NICHT alleine rollbacken. ### 4.6 Final-Handoff schreiben Schreib einen neuen `HANDOFF-2026-05-26.md` (oder das aktuelle Datum, falls dein Lauf länger geht) mit: - Was tatsächlich landed (Task-für-Task mit Commit-Hash) - Was deferred wurde + Grund - Smoke-Test-Ergebnisse (Screenshots-Pfade, curl-Outputs) - Was als Nächstes ansteht - Commit + push das Handoff auch (es ist Teil deiner Auslieferung) --- ## 5. Wenn etwas Unerwartetes passiert **Du stoppst trotzdem nicht.** Stattdessen: - Task überspringen, in PROGRESS.md eintragen warum, weiter mit nächstem. - Wenn ein push fehlschlägt (z.B. lefthook blockt wegen typecheck): fixe was er findet, retry. Wenn auch nach 3 Retries rot: dieser EINE Commit bleibt lokal, ALLE anderen pushst du trotzdem, Notiz im Final-Handoff. - Wenn Coolify-Deploy hängt: 10 min warten (mit until-loop oder Monitor-Tool), dann in PROGRESS dokumentieren und weitermachen mit der Verifikations-Sektion was geht. - Wenn Browser-Smoke rot wird: Screenshot ablegen, in PROGRESS verlinken, KEINEN Rollback machen. - Wenn der Token unter `~/.cli-tokens/coolify-token` nicht funktioniert: API direkt via `ssh control "..."` ansprechen geht nicht (Coolify-API ist nur extern), dann eben curl-Sequence mit voller URL + bearer manuell, der Token-Inhalt steht in der Datei. **Was du NIE machst:** - Rückfragen an den User (er schläft). - `git reset --hard` oder `git push --force` ohne dass es absolut zwingend ist. - Production-Touches (es gibt eh keine prod-VM aktuell, aber falls eine auftaucht: Hände weg). - Restore von Backups (das ist Operator-Pfad). - Sentry-Volumes löschen (Rollback-Optionalität schützen). --- ## 6. Operator-Profil - B2B-SaaS, SEO irrelevant. - Antwortstil im Final-Handoff: kurz, plain, keine Tabellen-Wände, keine Emojis. Pfade/URLs/Env-Vars als Fließtext, nicht inline-code. --- **Ende.** Lies das Dokument zu Ende, dann mache deinen TaskCreate-Aufruf für Task A bis G, markiere Task A als `in_progress`, und SOFORT loslegen.