huge documentaton restructure for docusaurus

docs/archive/process/todo/event-join-token-hardening.md

@@ -0,0 +1,39 @@
+# Event Join Token Hardening TODO
+
+## Goal
+Replace slug-based guest access with opaque, revocable join tokens and provide printable QR layouts tied to those tokens.
+
+## Status (Stand 12.10.2025)
+- **Phase 1 – Data & Backend:** vollständig abgeschlossen.
+- **Phase 2 – Guest PWA:** Aufgaben zu Fehlerzuständen und Regressionstests noch offen.
+- **Phase 3 – Tenant Admin UX:** Layout-Downloads und Abschaltung des alten Slug-QR-Flows noch offen.
+- **Phase 4 – Migration & Cleanup:** alle Aufgaben offen.
+
+## Phase 1 – Data & Backend
+- [x] Create `event_join_tokens` table (token, event_id, usage_limit/count, expires_at, revoked_at, created_by).
+- [x] Add Eloquent model + relations (`Event::joinTokens()`), factory, and seed helper.
+- [x] Implement service for token generation/rotation (secure RNG, audit logging).
+- [x] Expose tenant API endpoints for listing/creating/revoking tokens.
+- [x] Introduce middleware/controller updates so guest API resolves `/e/{token}` → event.
+- [x] Add rate limiting + logging for invalid token attempts.
+
+## Phase 2 – Guest PWA
+- [x] Update router and data loaders to use `:token` paths.
+- [x] Adjust storage/cache keys to use token identifiers.
+- [x] Display friendly error states for expired/invalid tokens.
+- [x] Regression-test photo upload, likes, and stats flows via token.
+
+## Phase 3 – Tenant Admin UX
+- [x] Build “QR & Invites” management UI (list tokens, usage stats, rotate/revoke).
+- [x] Hook Filament action + PWA screens to call new token endpoints.
+- [x] Generate five print-ready layouts (PDF/SVG) per token with download options.
+- [x] Deprecate slug-based QR view; link tenants to new flow.
+
+## Phase 4 – Migration & Cleanup
+- [x] Remove slug parameters from public endpoints (legacy slug URLs now return invalid_token).
+- [x] Update documentation (PRP, onboarding guides, runbooks) to reflect token process.
+- [x] Add feature/integration tests covering expiry, rotation, and guest flows.
+
+## Open Questions
+- Decide on default token lifetime and rotation cadence.
+- Confirm whether guest tokens should embed locale or package metadata.

docs/archive/process/todo/package-limit-experience-overhaul.md

@@ -0,0 +1,67 @@
+# Package Limit Experience Overhaul
+
+**Status:** Planned  
+**Owner:** Codegen Agent  
+**Related Areas:** Packages, Tenant Admin PWA, Guest PWA, Notifications
+
+## Motivation
+- Uneinheitliche Limit-Prüfungen (Public Upload vs. Admin Upload vs. Event-Erstellung).
+- Fehlende, generische oder kryptische Fehlermeldungen im Admin-Frontend.
+- Keine Frühwarnungen bei 80 %/95 % Auslastung, kein Countdown für Galerien.
+- Fehlende Automatisierung für E-Mail-/In-App-Warnungen bei kritischen Zuständen.
+
+## High-Level Goals
+1. Konsistente Limit-Prüfungen & Fehlercodes im Backend.
+2. Verbesserte UX in Guest & Tenant Admin PWA (Warnungen, klare Fehlermeldungen).
+3. Proaktive Benachrichtigungen (E-Mail, In-App) bei bevorstehenden Grenzwerten / Ablauf.
+4. Monitoring, Dokumentation, Tests für alle neuen Abläufe.
+
+## Work Breakdown
+
+### 1. Backend Unification
+- [x] Paket-Limit-Service erstellen (Fotos, Gäste, Aufgaben, Events/Jahr, Galerie-Laufzeit). *(Initial evaluator + Middleware Integration für Events/Fotos)*
+- [x] Public Uploads um Paketlimit-Prüfung erweitern (inkl. Events ohne Aktivpaket blockieren). *(Guest Upload prüft & erhöht Zähler)*
+- [x] Konsistentes Fehler-Response-Schema (`code`, `title`, `message`, `meta`) implementieren.
+- [x] Domain-Events für Grenzwerte & Ablaufzustände emitten.
+- [x] Feature-/Unit-Tests für neue Services & Events.
+
+### 2. Threshold Detection & Storage
+- [x] Schwellenwerte konfigurieren (Fotos/Gäste, Gallery D-7/D-1).
+- [x] Scheduler/Jobs für regelmäßige Galerie-Checks.
+- [x] Persistenz für Galerie-Benachrichtigungen (warning/expired timestamps).
+
+### 3. Guest PWA Improvements
+- [x] Limit-Status im Upload-Flow anzeigen (Warnbanner + Sperrzustände).
+- [x] Upload-Fehlercodes auswerten und freundliche Dialoge zeigen.
+- [x] Galerie-Countdown/Badge für Ablaufdatum + Call-to-Action.
+- [x] E2E-Tests für Limitwarnungen & abgelaufene Galerie aktualisieren.
+
+### 4. Tenant Admin PWA Improvements
+- [x] Dashboard-Karten & Event-Header mit Ampelsystem für Limitfortschritt.
+- [x] Event-Formular: Warnhinweise bei 80 %/95 % + Upgrade-CTA.
+- [x] Globale Fehlerzustände aus Fehlerkontrakt (Toast/Dialog).
+- [x] Übersetzungen für alle neuen Messages hinzufügen.
+
+- [x] E-Mail-Schablonen & Notifications für Foto- und Gäste-Schwellen/Limits.
+- [x] Galerie-Warnungen (D-7/D-1) & Ablauf-Mails + Cron Task.
+- [x] Weitere Benachrichtigungen (Paket-Ablauf, Reseller-Eventlimit, Credits fast leer).
+- [x] Opt-in/Opt-out-Konfiguration pro Tenant implementieren.
+- [x] In-App/Toast-Benachrichtigungen für Admin UI (und optional Push/Slack intern).
+- [x] Audit-Log & Retry-Logik für gesendete Mails.
+
+### 6. Monitoring, Docs & Support
+- [x] Prometheus/Grafana-Metriken für Paketnutzung & Warns triggern. *(`PackageLimitMetrics` + `php artisan metrics:package-limits` Snapshot)*
+- [x] PRP & API-Doku mit neuem Fehlerschema & Limitverhalten aktualisieren.
+- [x] Support-Playbook & FAQ für Limitwarnungen erweitern. *(docs/prp/06 Tenant Admin Playbook Abschnitt)*
+
+## Dependencies & Notes
+- Bestehende Credit-Logik parallel weiter unterstützen (Legacy-Kunden).
+- Paddle/E-Mail-Dienste müssen auf Sandbox getestet werden.
+- Mehrsprachigkeit (de/en) sicherstellen.
+
+## Definition of Done
+- Alle relevanten Grenzwerte serverseitig validiert und getestet.
+- Frontends zeigen spezifische Warnungen + Handlungsanweisungen.
+- Benachrichtigungssystem verschickt Mails bei konfigurierten Schwellen.
+- Monitoring & Dokumentation sind aktualisiert.
+- Regressionstests und neue Tests laufen grün.

docs/archive/process/todo/tenant-admin-onboarding-fusion.md

@@ -0,0 +1,50 @@
+# Tenant Admin Onboarding Fusion TODO
+Created: 2025-10-10
+Owner: Codex (handoff)
+
+## Context
+- Blend the immersive welcome + ordering journey from fotospiel-tenant-app/tenant-admin-app with the new management modules under /event-admin.
+- Align with the detailed PRP (docs/prp/tenant-app-specs/*.md) and onboarding plan notes (docs/process/changes/2025-10-10-tenant-admin-onboarding-plan.md).
+- Preserve existing dashboard/events/tasks/billing screens while introducing a guided first-run experience and mobile-first polish.
+
+## References
+- docs/prp/tenant-app-specs/README.md
+- docs/prp/tenant-app-specs/pages-ui.md
+- docs/prp/tenant-app-specs/functional-specs.md
+- docs/process/changes/2025-10-10-tenant-admin-onboarding-plan.md
+- resources/js/admin/router.tsx
+- resources/js/admin/components/AdminLayout.tsx
+- resources/js/admin/pages/DashboardPage.tsx
+- fotospiel-tenant-app/tenant-admin-app/src/App.tsx (legacy welcome flow)
+
+## Priority: Now ( unblock design + scope )
+- [x] Audit the legacy Capacitor app assets (intro carousel, package picker, CTA cards, animation helpers) and list what should be ported or rebuilt in Tailwind/React. Capture findings in docs/process/changes/2025-10-10-tenant-admin-onboarding-plan.md with component parity notes. See "Component Audit - 2025-10-10".
+- [x] Define shared onboarding design primitives inside Laravel PWA (e.g. gradient backgrounds, full-height hero layout, swipeable stepper). Propose implementation sketch for new components such as TenantWelcomeLayout and WelcomeStepCard. Documented under "Proposed Laravel PWA Welcome Primitives".
+
+## Priority: Next ( build the welcome flow )
+- [x] Introduce /event-admin/welcome/* routes and constants, plus a lightweight layout distinct from AdminLayout. Update resources/js/admin/router.tsx and resources/js/admin/constants.ts accordingly.
+- [x] Implement onboarding steps (Hero, HowItWorks, PackageSelection, OrderSummary, FirstEventSetup) that reuse existing APIs (getTenantPackagesOverview, createEvent, checkout helpers). Landing, package, summary, and setup screens are live; summary links to Billing for payments, direct in-flow checkout still TBD.
+- [x] Persist onboarding progress (e.g. useOnboardingProgress in auth context or dedicated store) and add guard logic so tenants without active events land on the welcome flow after login. Provide a way to resume the flow from the dashboard CTA.
+- [x] Refresh DashboardPage.tsx to surface the new welcome CTA ("Plan your first event") and quick links back into the guided flow without breaking existing management cards. Guided setup card and header action now link to `/event-admin/welcome`.
+
+## Priority: Later ( polish + delivery )
+- [x] Align theming, typography, and transitions with the legacy mobile look (consider porting key styles from fotospiel-tenant-app/tenant-admin-app/src/styles). Tenant admin layout now reuses marketing brand palette, fonts, and gradient utilities; Tailwind variables capture the shared tokens.
+- [x] Review PWA manifest/offline setup so die kombinierte Welcome+Management-Experience TWA-/Capacitor-ready ist (Manifest + `admin-sw.js` dokumentiert).
+- [x] Extend docs: PRP-Onboarding-Abschnitte aktualisiert, Screenshots unter `docs/screenshots/tenant-admin-onboarding/` ergänzt, Testscope notiert.
+- [x] Add automated coverage: Vitest + Testing Library für Welcome Landing, Dashboard-Guard und Checkout-Komponenten; `npm run test:unit` führt Suite aus.
+- [x] Finalise direct checkout: Paddle-Flows markieren Fortschritt, API-Mocks + Unit-Tests decken Erfolgs- und Fehlerpfade ab.
+- [x] Lokalisierung ausbauen: Landing-, Packages-, Summary- und Event-Setup-Screens sind nun DE/EN übersetzt; Copy-Review für weitere Module (Tasks/Billing/Members) bleibt offen.
+
+## Risks & Open Questions
+- Confirm checkout UX expectations (Stripe vs Paddle) before wiring package purchase into onboarding.
+- Validate whether onboarding flow must be localized at launch; coordinate mit den neuen i18n JSONs und fehlenden Übersetzungen.
+- Determine deprecation plan for fotospiel-tenant-app/tenant-admin-app once the merged flow ships.
+
+## Priority: Immediate (Tenant admin refresh 2025-10-18)
+- [x] Replace the `/event-admin/login` landing with a public welcome screen that explains Fotospiel for non-technical couples, keeps the login button, and updates `resources/js/admin/router.tsx`, `constants.ts`, and new `WelcomeTeaserPage`.
+- [x] Align authentication by migrating the tenant-admin flow to Sanctum PATs, dropping `VITE_OAUTH_CLIENT_ID`, updating the exchange endpoints, and documenting the env expectations in `docs/prp/tenant-app-specs/api-usage.md` / `13-backend-authentication.md`.
+- [x] Rebrand the Filament tenant panel away from “Admin” by adjusting `AdminPanelProvider` (brand name, home URL, navigation visibility) and registering a new onboarding home page.
+- [x] Build the Filament onboarding wizard (welcome → task package selection → event name → color palette → QR layout) with persisted progress on the tenant record and guards that hide legacy resource menus until completion.
+- [x] Expose QR invite generation in Filament via a dedicated page/component that reuses the join-token flow from `EventDetailPage.tsx`, ensuring tokens stay in sync between PWA and Filament.
+- [x] Update PRP/docs to cover die neue Welcome Journey, OAuth-Ausrichtung, Filament-Onboarding und QR-Tooling; Regression Notes + Tests dokumentiert.
+