Dauer: 4-6 Wochen Tasks: 3 (MVP → V1 → V2) Ziel: Den heute hart deaktivierten Chatbot (apps/web/app/modules/chatbot/lib/chatbot-stream.server.ts:41 returnt unconditionally 503 "AI provider runtime is not configured yet.") in einen modularen, SaaS-bewussten, capability-gestaffelten Chatbot verwandeln. Drei Ausbaustufen, jede für sich produktionsreif. Nicht alles auf einmal — saubere Trennung damit Tenants schon nach MVP echten Wert haben, V1 die Risk-Surface durch Allow-List + Audit klein hält und V2 erst dann RAG + Cost-Tracking zünden lässt, wenn die dafür nötige Infrastruktur (Phase 04 und Phase 05) wirklich steht.

Warum 3-stufig

Wert früh liefern. MVP (Master-Switch + 3 read-only Capabilities) ist in 3-4 Tagen baubar und gibt Tenants sofort einen Self-Service-Helfer für Produktfragen, KB-Suche und Account-Basics — ohne dass wir RAG-Infrastruktur, Cost-Quotas oder Per-User-Permissions brauchen.
Risk inkrementell aufdrehen. Schreibende und admin-nahe Tools (data_write, workflow_trigger, admin_actions, external_tools) kommen erst in V1, dann hinter Per-User-Allow-List + Per-Capability Rate-Limits + Audit-Log. Wir öffnen die Angriffsfläche nicht in einem Rutsch.
Schwere Abhängigkeiten kapseln. V2 (RAG + Cost-Tracking) braucht Phase 04 (meilisearch.md, vector-store.md, embedding-pipeline.md) und Phase 05 (ai-cost-phase-1/2/3.md) komplett. Würden wir das in MVP packen, müsste der ganze Chatbot warten bis Search/RAG steht — Wert-Lieferung würde 8+ Wochen verschoben.
Klare Rollback-Punkte. Jede Stufe hat einen eigenen Feature-Flag-Subschalter (chatbot, chatbot.user_allowlist, chatbot.rag). Wenn V1 oder V2 Probleme machen, lässt sich die jeweilige Stufe deaktivieren ohne MVP zu reißen.

Modulares Design (gilt über alle 3 Stufen)

┌─────────────────────────────────────────────────────────────────┐
│  Tenant-Settings UI (/app/$tenant/settings/ai-chatbot)         │
│  - Master-Switch (Feature-Flag chatbot)                         │
│  - Capability-Matrix (8 Toggles, V1+)                           │
│  - User-Allow-List (V1+) + Per-User-Overrides (V2)              │
└──────────────┬──────────────────────────────────────────────────┘
               │ liest/schreibt
               ▼
┌─────────────────────────────────────────────────────────────────┐
│  TenantChatbotAccess (Prisma, ab V1) +                          │
│  Feature-Flags-Engine (Task #53, ab MVP)                        │
└──────────────┬──────────────────────────────────────────────────┘
               │ enforced durch
               ▼
┌─────────────────────────────────────────────────────────────────┐
│  Capability-Resolver (lib/chatbot-capabilities.server.ts)      │
│  - resolveCapabilitiesForUser({tenantId, userId})              │
│  - returnt erlaubte Capability-Liste                           │
└──────────────┬──────────────────────────────────────────────────┘
               │ konfiguriert
               ▼
┌─────────────────────────────────────────────────────────────────┐
│  chatbot-stream.server.ts (refactored)                          │
│  - System-Prompt-Builder (Tenant + User + RAG-Context ab V2)    │
│  - Capability-gated Tool-Registry (3 in MVP, 8 in V1+)          │
│  - High-Risk-Tool-Audit (V1+)                                   │
│  - Cost-Tracking pro Tool-Call (V2)                             │
└─────────────────────────────────────────────────────────────────┘

Die 8 Capabilities (final in V1, vorbereitet ab MVP):

ID	Name	Risk	MVP	V1	V2
`qa_help`	Produktfragen via Static-Docs	low	✅	✅	✅
`kb_search`	Tenant-KB-Search (Postgres-FTS/Meilisearch)	low	✅	✅	✅
`account_info`	Plan, Credits, simple Account-Queries	low	✅	✅	✅
`data_read`	Tenant-Daten lesen (CRM, Rows, Notes)	medium	—	✅	✅
`data_write`	Tenant-Daten schreiben	high	—	✅	✅
`workflow_trigger`	Workflows starten	high	—	✅	✅
`admin_actions`	Tenant-Admin-Operationen	high	—	✅	✅
`external_tools`	MCP-Tools, externe Integrationen	high	—	✅	✅

Task-Reihenfolge

#	Task-ID	Datei	Estimated	Parallelisierbar
1	#13	`chatbot-mvp.md`	3-4 Tage	— (Foundation)
2	#14	`chatbot-v1.md`	1 Woche	— (braucht MVP)
3	#15	`chatbot-v2.md`	2 Wochen	— (braucht V1 + Phase 04 + Phase 05 Cost)

Sequenziell. Keine Parallelisierung innerhalb der Phase, weil jede Stufe auf der Capability-Architektur der vorigen aufbaut. Externe Parallelität (Phase 04, Phase 05) erfolgt vor V2-Start.

Dependency-Graph (extern + intern)

   Phase 05 feature-flags.md (#53) ───┐
                                       │
                                       ▼
                              #13 chatbot-mvp.md
                              (Master-Switch + 3 Capabilities)
                                       │
                                       ▼
   Phase 10 audit-compliance-export.md ─┐
                                         │
                                         ▼
                              #14 chatbot-v1.md
                              (Allow-List + 8 Capabilities + Audit)
                                       │
   Phase 04 meilisearch.md (#48) ──┐    │
   Phase 04 vector-store.md (#49) ─┤    │
   Phase 04 embedding-pipeline.md (#50)─┤
   Phase 05 ai-cost-phase-1.md (#54) ──┤
   Phase 05 ai-cost-phase-2.md (#55) ──┤
   Phase 05 ai-cost-phase-3.md (#56) ──┤
                                        ▼
                              #15 chatbot-v2.md
                              (RAG + Cost-Tracking + Per-User-Overrides)

Phase Done-Definition

Diese Phase ist completed wenn:

Alle 3 Tasks completed in PROGRESS.md
pnpm lint, pnpm typecheck, pnpm test grün
chatbot-stream.server.ts enthält keinen unconditionalen 503-Return mehr; Routing geht über Feature-Flag + Capability-Resolver
apps/web/app/routes/app.$tenant/settings/ai-chatbot.tsx (oder gleichwertig) bietet Master-Switch, Capability-Matrix und User-Allow-List
TenantChatbotAccess Prisma-Model ab V1 vorhanden inkl. Migration
Alle 8 Capabilities sind als LLM-Tools registriert und werden capability-gated exposed
AuditEvent wird für jeden High-Risk-Tool-Call geschrieben (V1+)
AICostEvent wird pro Chatbot-Generation mit capability-Feld geschrieben (V2)
RAG-Retrieval (Top-K=5 default) ist im System-Prompt-Builder integriert und nutzt chatbot_rag-Collection (V2)
Doku-Files: docs/features/chatbot.md, docs/features/chatbot-capabilities.md, docs/operations/chatbot-rollout.md
Staging-Deployment auf agent/phase-07-final: Tenant-A hat MVP-Setup, Tenant-B hat V1 mit Allow-List, Tenant-C hat V2 mit RAG — jeweils smoke-getestet
Tenant-Isolation-Test: Chatbot von Tenant A kann via keiner Capability auf Daten von Tenant B zugreifen (positiv- und negativ-Test pro Capability)
Indirect-Prompt-Injection-Test: KB-Article mit eingebettetem Tool-Aufruf wird nicht ausgeführt (siehe Security-Notes der Detail-MDs)
gsd-code-reviewer-Subagent hat alle Phase-07-Commits reviewed; Findings adressiert
Phase-Summary in dieser README.md ergänzt

Phase Summary

(Wird nach Abschluss der Phase vom ausführenden Agent ergänzt.)

Lessons Learned

(Wird nach Abschluss ergänzt — insbesondere: Tool-Call-Token-Budget-Findings, RAG-Top-K-Tuning, Capability-UI-UX-Erkenntnisse, Audit-Log-Volumen pro High-Risk-Tool, Prompt-Injection-Mitigationen die tatsächlich gegriffen haben.)

Verweise

Detail-MD-Template: ../DETAIL-MD-TEMPLATE.md
Agent-Workflow: ../AGENT-INSTRUCTIONS.md
Execution-Order: ../00-execution-order.md
Live-Status: ../PROGRESS.md
Vorgänger-Phasen: ../04-search-rag/README.md, ../05-business-features/README.md
Nachfolger-Phase: ../08-mobile-cli-storybook-sdk/README.md