From 4775497dc7cb40d8d37f208fd5fa183e35a77b17 Mon Sep 17 00:00:00 2001
From: colinislit <colin@ikbenlit.nl>
Date: Mon, 1 Dec 2025 15:45:44 +0100
Subject: [PATCH] feat: add docs chat widget UI components (E3)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add useDocsChat hook with message state, streaming, error handling
- Add ChatMessages component with auto-scroll and streaming cursor
- Add ChatInput component with Enter/Shift+Enter support
- Add DocsChatWidget floating container with amber styling
- Add AI integration specs (PRD, FO, bouwplan)

Implements Epic 3 of AI Documentatie Assistent feature.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 components/docs-chat/chat-input.tsx           |  98 +++++
 components/docs-chat/chat-messages.tsx        | 150 +++++++
 components/docs-chat/docs-chat-widget.tsx     | 116 +++++
 components/docs-chat/index.ts                 |   5 +
 components/docs-chat/use-docs-chat.ts         | 208 +++++++++
 .../bouwplan-ai-docs-assistent-v1.md          | 321 ++++++++++++++
 .../ai-integratie/fo-ai-docs-assistent-v1.md  | 386 +++++++++++++++++
 .../ai-integratie/prd-ai-docs-assistent-v1.md | 403 ++++++++++++++++++
 .../prd-ai-prefill-behandelplan-v1.md         | 349 +++++++++++++++
 9 files changed, 2036 insertions(+)
 create mode 100644 components/docs-chat/chat-input.tsx
 create mode 100644 components/docs-chat/chat-messages.tsx
 create mode 100644 components/docs-chat/docs-chat-widget.tsx
 create mode 100644 components/docs-chat/index.ts
 create mode 100644 components/docs-chat/use-docs-chat.ts
 create mode 100644 docs/specs/ai-integratie/bouwplan-ai-docs-assistent-v1.md
 create mode 100644 docs/specs/ai-integratie/fo-ai-docs-assistent-v1.md
 create mode 100644 docs/specs/ai-integratie/prd-ai-docs-assistent-v1.md
 create mode 100644 docs/specs/ai-integratie/prd-ai-prefill-behandelplan-v1.md

diff --git a/components/docs-chat/chat-input.tsx b/components/docs-chat/chat-input.tsx
new file mode 100644
index 0000000..013d37f
--- /dev/null
+++ b/components/docs-chat/chat-input.tsx
@@ -0,0 +1,98 @@
+'use client'
+
+import { useRef, useState } from 'react'
+import { Send } from 'lucide-react'
+
+import { cn } from '@/lib/utils'
+
+interface ChatInputProps {
+  onSend: (message: string) => void
+  disabled?: boolean
+  placeholder?: string
+}
+
+/**
+ * Chat input component with textarea, send button, Enter/Shift+Enter support
+ *
+ * - Enter: send message
+ * - Shift+Enter: new line
+ * - Auto-resize textarea
+ */
+export function ChatInput({
+  onSend,
+  disabled = false,
+  placeholder = 'Stel een vraag...',
+}: ChatInputProps) {
+  const [value, setValue] = useState('')
+  const textareaRef = useRef<HTMLTextAreaElement>(null)
+
+  const handleSubmit = () => {
+    const trimmed = value.trim()
+    if (!trimmed || disabled) return
+
+    onSend(trimmed)
+    setValue('')
+
+    // Reset textarea height
+    if (textareaRef.current) {
+      textareaRef.current.style.height = 'auto'
+    }
+  }
+
+  const handleKeyDown = (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
+    if (e.key === 'Enter' && !e.shiftKey) {
+      e.preventDefault()
+      handleSubmit()
+    }
+  }
+
+  const handleChange = (e: React.ChangeEvent<HTMLTextAreaElement>) => {
+    setValue(e.target.value)
+
+    // Auto-resize
+    const textarea = e.target
+    textarea.style.height = 'auto'
+    textarea.style.height = `${Math.min(textarea.scrollHeight, 120)}px`
+  }
+
+  const canSend = value.trim().length > 0 && !disabled
+
+  return (
+    <div className="border-t border-slate-200 p-3 bg-white">
+      <div className="flex items-end gap-2">
+        <textarea
+          ref={textareaRef}
+          value={value}
+          onChange={handleChange}
+          onKeyDown={handleKeyDown}
+          placeholder={placeholder}
+          disabled={disabled}
+          rows={1}
+          className={cn(
+            'flex-1 resize-none rounded-xl border border-slate-200 px-4 py-2.5',
+            'text-sm placeholder:text-slate-400',
+            'focus:outline-none focus:ring-2 focus:ring-amber-500/50 focus:border-amber-500',
+            'disabled:opacity-50 disabled:cursor-not-allowed',
+            'max-h-[120px]'
+          )}
+        />
+        <button
+          type="button"
+          onClick={handleSubmit}
+          disabled={!canSend}
+          className={cn(
+            'flex items-center justify-center',
+            'w-10 h-10 rounded-xl',
+            'transition-all duration-200',
+            canSend
+              ? 'bg-amber-500 hover:bg-amber-600 text-white shadow-sm'
+              : 'bg-slate-100 text-slate-400 cursor-not-allowed'
+          )}
+          aria-label="Verstuur bericht"
+        >
+          <Send className="w-4 h-4" />
+        </button>
+      </div>
+    </div>
+  )
+}
diff --git a/components/docs-chat/chat-messages.tsx b/components/docs-chat/chat-messages.tsx
new file mode 100644
index 0000000..c23bdac
--- /dev/null
+++ b/components/docs-chat/chat-messages.tsx
@@ -0,0 +1,150 @@
+'use client'
+
+import { useEffect, useRef } from 'react'
+
+import { cn } from '@/lib/utils'
+
+import type { ChatMessage } from './use-docs-chat'
+
+interface ChatMessagesProps {
+  messages: ChatMessage[]
+  isStreaming: boolean
+}
+
+/**
+ * Message list component with auto-scroll and streaming cursor
+ *
+ * UI Specs (uit FO):
+ * - User messages: rechts, bg-amber-100, rounded
+ * - Assistant messages: links, bg-slate-100, rounded
+ * - Streaming: pulserende cursor ▊
+ */
+export function ChatMessages({ messages, isStreaming }: ChatMessagesProps) {
+  const scrollRef = useRef<HTMLDivElement>(null)
+
+  // Auto-scroll to bottom on new messages
+  useEffect(() => {
+    if (scrollRef.current) {
+      scrollRef.current.scrollTop = scrollRef.current.scrollHeight
+    }
+  }, [messages])
+
+  return (
+    <div
+      ref={scrollRef}
+      className="flex-1 overflow-y-auto p-4 space-y-3"
+    >
+      {messages.map((message) => (
+        <MessageBubble
+          key={message.id}
+          message={message}
+          isStreaming={isStreaming && message.role === 'assistant' && message === messages[messages.length - 1]}
+        />
+      ))}
+    </div>
+  )
+}
+
+interface MessageBubbleProps {
+  message: ChatMessage
+  isStreaming: boolean
+}
+
+function MessageBubble({ message, isStreaming }: MessageBubbleProps) {
+  const isUser = message.role === 'user'
+
+  return (
+    <div
+      className={cn(
+        'flex',
+        isUser ? 'justify-end' : 'justify-start'
+      )}
+    >
+      <div
+        className={cn(
+          'max-w-[85%] rounded-2xl px-4 py-2 text-sm',
+          isUser
+            ? 'bg-amber-100 text-amber-900 rounded-br-md'
+            : 'bg-slate-100 text-slate-900 rounded-bl-md'
+        )}
+      >
+        <MessageContent content={message.content} isStreaming={isStreaming} />
+      </div>
+    </div>
+  )
+}
+
+interface MessageContentProps {
+  content: string
+  isStreaming: boolean
+}
+
+function MessageContent({ content, isStreaming }: MessageContentProps) {
+  if (!content && isStreaming) {
+    return <StreamingCursor />
+  }
+
+  // Split content into paragraphs and render with proper spacing
+  const paragraphs = content.split('\n\n')
+
+  return (
+    <div className="space-y-2">
+      {paragraphs.map((paragraph, idx) => (
+        <p key={idx} className="whitespace-pre-wrap leading-relaxed">
+          {renderInlineFormatting(paragraph)}
+          {isStreaming && idx === paragraphs.length - 1 && <StreamingCursor />}
+        </p>
+      ))}
+    </div>
+  )
+}
+
+/**
+ * Render basic inline formatting (bold, bullet points)
+ */
+function renderInlineFormatting(text: string) {
+  // Handle bullet points
+  const lines = text.split('\n')
+
+  return lines.map((line, idx) => {
+    const isBullet = line.startsWith('• ') || line.startsWith('- ')
+
+    if (isBullet) {
+      return (
+        <span key={idx} className="block pl-2">
+          {line}
+          {idx < lines.length - 1 && '\n'}
+        </span>
+      )
+    }
+
+    // Handle **bold** text
+    const parts = line.split(/(\*\*[^*]+\*\*)/)
+    const formatted = parts.map((part, partIdx) => {
+      if (part.startsWith('**') && part.endsWith('**')) {
+        return (
+          <strong key={partIdx} className="font-semibold">
+            {part.slice(2, -2)}
+          </strong>
+        )
+      }
+      return part
+    })
+
+    return (
+      <span key={idx}>
+        {formatted}
+        {idx < lines.length - 1 && '\n'}
+      </span>
+    )
+  })
+}
+
+/**
+ * Pulsating streaming cursor
+ */
+function StreamingCursor() {
+  return (
+    <span className="inline-block w-2 h-4 ml-0.5 bg-amber-500 animate-pulse rounded-sm" />
+  )
+}
diff --git a/components/docs-chat/docs-chat-widget.tsx b/components/docs-chat/docs-chat-widget.tsx
new file mode 100644
index 0000000..5bb6e46
--- /dev/null
+++ b/components/docs-chat/docs-chat-widget.tsx
@@ -0,0 +1,116 @@
+'use client'
+
+import { useState } from 'react'
+import { Sparkles, X } from 'lucide-react'
+
+import { cn } from '@/lib/utils'
+
+import { ChatInput } from './chat-input'
+import { ChatMessages } from './chat-messages'
+import { useDocsChat } from './use-docs-chat'
+
+/**
+ * Floating chat widget for documentation assistant
+ *
+ * UI Specs (uit FO):
+ * - Trigger button: 56x56px, amber gradient, Sparkles icon, fixed bottom-6 right-6
+ * - Panel: 384px breed, max 80vh, slide-in animatie
+ */
+export function DocsChatWidget() {
+  const [isOpen, setIsOpen] = useState(false)
+  const { messages, isLoading, isStreaming, error, sendMessage, clearError } = useDocsChat()
+
+  return (
+    <>
+      {/* Floating trigger button */}
+      <button
+        type="button"
+        onClick={() => setIsOpen(true)}
+        className={cn(
+          'fixed bottom-6 right-6 z-50',
+          'w-14 h-14 rounded-full',
+          'bg-gradient-to-br from-amber-400 to-amber-600',
+          'text-white shadow-lg',
+          'flex items-center justify-center',
+          'hover:from-amber-500 hover:to-amber-700',
+          'hover:scale-105 hover:shadow-xl',
+          'transition-all duration-200',
+          'focus:outline-none focus:ring-2 focus:ring-amber-500 focus:ring-offset-2',
+          isOpen && 'scale-0 opacity-0'
+        )}
+        aria-label="Open documentatie assistent"
+      >
+        <Sparkles className="w-6 h-6" />
+      </button>
+
+      {/* Chat panel */}
+      <div
+        className={cn(
+          'fixed bottom-6 right-6 z-50',
+          'w-96 max-h-[80vh]',
+          'bg-white rounded-2xl shadow-2xl',
+          'flex flex-col overflow-hidden',
+          'border border-slate-200',
+          'transition-all duration-300 ease-out',
+          isOpen
+            ? 'opacity-100 translate-y-0 scale-100'
+            : 'opacity-0 translate-y-4 scale-95 pointer-events-none'
+        )}
+      >
+        {/* Header */}
+        <div className="flex items-center justify-between px-4 py-3 border-b border-slate-200 bg-gradient-to-r from-amber-50 to-amber-100/50">
+          <div className="flex items-center gap-2">
+            <div className="w-8 h-8 rounded-full bg-gradient-to-br from-amber-400 to-amber-600 flex items-center justify-center">
+              <Sparkles className="w-4 h-4 text-white" />
+            </div>
+            <div>
+              <h2 className="font-semibold text-slate-900 text-sm">
+                Documentatie Assistent
+              </h2>
+              <p className="text-xs text-slate-500">
+                Stel vragen over het EPD
+              </p>
+            </div>
+          </div>
+          <button
+            type="button"
+            onClick={() => setIsOpen(false)}
+            className={cn(
+              'w-8 h-8 rounded-lg',
+              'flex items-center justify-center',
+              'text-slate-400 hover:text-slate-600',
+              'hover:bg-slate-100',
+              'transition-colors duration-150'
+            )}
+            aria-label="Sluit chat"
+          >
+            <X className="w-5 h-5" />
+          </button>
+        </div>
+
+        {/* Error banner */}
+        {error && (
+          <div className="px-4 py-2 bg-red-50 border-b border-red-100 flex items-center justify-between">
+            <p className="text-sm text-red-600">{error}</p>
+            <button
+              type="button"
+              onClick={clearError}
+              className="text-red-400 hover:text-red-600 text-xs"
+            >
+              Sluiten
+            </button>
+          </div>
+        )}
+
+        {/* Messages */}
+        <ChatMessages messages={messages} isStreaming={isStreaming} />
+
+        {/* Input */}
+        <ChatInput
+          onSend={sendMessage}
+          disabled={isLoading || isStreaming}
+        />
+      </div>
+    </>
+  )
+}
diff --git a/components/docs-chat/index.ts b/components/docs-chat/index.ts
new file mode 100644
index 0000000..d81a05d
--- /dev/null
+++ b/components/docs-chat/index.ts
@@ -0,0 +1,5 @@
+export { DocsChatWidget } from './docs-chat-widget'
+export { ChatMessages } from './chat-messages'
+export { ChatInput } from './chat-input'
+export { useDocsChat } from './use-docs-chat'
+export type { ChatMessage } from './use-docs-chat'
diff --git a/components/docs-chat/use-docs-chat.ts b/components/docs-chat/use-docs-chat.ts
new file mode 100644
index 0000000..5f6f6e0
--- /dev/null
+++ b/components/docs-chat/use-docs-chat.ts
@@ -0,0 +1,208 @@
+'use client'
+
+import { useCallback, useState } from 'react'
+
+/**
+ * Chat message type
+ */
+export interface ChatMessage {
+  id: string
+  role: 'user' | 'assistant'
+  content: string
+}
+
+/**
+ * Hook state
+ */
+interface UseDocsChatState {
+  messages: ChatMessage[]
+  isLoading: boolean
+  isStreaming: boolean
+  error: string | null
+}
+
+/**
+ * Hook return type
+ */
+interface UseDocsChatReturn extends UseDocsChatState {
+  sendMessage: (content: string) => Promise<void>
+  clearMessages: () => void
+  clearError: () => void
+}
+
+/**
+ * Generate unique message ID
+ */
+function generateId(): string {
+  return `msg_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`
+}
+
+/**
+ * Welcome message shown on first load
+ */
+const WELCOME_MESSAGE: ChatMessage = {
+  id: 'welcome',
+  role: 'assistant',
+  content:
+    'Hallo! Ik ben de documentatie assistent voor het Mini-EPD. Stel me een vraag over het systeem, bijvoorbeeld:\n\n• Hoe maak ik een intake aan?\n• Hoe werkt de spraakherkenning?\n• Waar vind ik het behandelplan?',
+}
+
+/**
+ * Custom hook for docs chat functionality
+ *
+ * Features:
+ * - Message state management
+ * - Streaming responses from Claude API
+ * - Loading and error states
+ * - Welcome message on init
+ *
+ * @example
+ * const { messages, isLoading, sendMessage } = useDocsChat()
+ * await sendMessage("Hoe maak ik een intake aan?")
+ */
+export function useDocsChat(): UseDocsChatReturn {
+  const [state, setState] = useState<UseDocsChatState>({
+    messages: [WELCOME_MESSAGE],
+    isLoading: false,
+    isStreaming: false,
+    error: null,
+  })
+
+  const sendMessage = useCallback(async (content: string) => {
+    const trimmedContent = content.trim()
+    if (!trimmedContent) return
+
+    // Add user message
+    const userMessage: ChatMessage = {
+      id: generateId(),
+      role: 'user',
+      content: trimmedContent,
+    }
+
+    // Prepare assistant message placeholder
+    const assistantMessage: ChatMessage = {
+      id: generateId(),
+      role: 'assistant',
+      content: '',
+    }
+
+    setState((prev) => ({
+      ...prev,
+      messages: [...prev.messages, userMessage, assistantMessage],
+      isLoading: true,
+      isStreaming: false,
+      error: null,
+    }))
+
+    try {
+      // Get message history (excluding welcome and current messages)
+      const history = state.messages
+        .filter((m) => m.id !== 'welcome')
+        .map((m) => ({ role: m.role, content: m.content }))
+
+      const response = await fetch('/api/docs/chat', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          messages: history,
+          userMessage: trimmedContent,
+        }),
+      })
+
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({}))
+        throw new Error(errorData.error || `Fout: ${response.status}`)
+      }
+
+      if (!response.body) {
+        throw new Error('Geen response body ontvangen')
+      }
+
+      // Start streaming
+      setState((prev) => ({
+        ...prev,
+        isLoading: false,
+        isStreaming: true,
+      }))
+
+      const reader = response.body.getReader()
+      const decoder = new TextDecoder()
+      let accumulatedContent = ''
+
+      while (true) {
+        const { done, value } = await reader.read()
+        if (done) break
+
+        const chunk = decoder.decode(value, { stream: true })
+        const lines = chunk.split('\n')
+
+        for (const line of lines) {
+          if (!line.startsWith('data: ')) continue
+
+          const data = line.slice(6)
+          if (data === '[DONE]') continue
+
+          try {
+            const parsed = JSON.parse(data)
+
+            // Handle content_block_delta events
+            if (parsed.type === 'content_block_delta' && parsed.delta?.text) {
+              accumulatedContent += parsed.delta.text
+
+              setState((prev) => ({
+                ...prev,
+                messages: prev.messages.map((m) =>
+                  m.id === assistantMessage.id
+                    ? { ...m, content: accumulatedContent }
+                    : m
+                ),
+              }))
+            }
+          } catch {
+            // Ignore parse errors for non-JSON lines
+          }
+        }
+      }
+
+      // Streaming complete
+      setState((prev) => ({
+        ...prev,
+        isStreaming: false,
+      }))
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : 'Er ging iets mis'
+
+      setState((prev) => ({
+        ...prev,
+        isLoading: false,
+        isStreaming: false,
+        error: errorMessage,
+        // Remove empty assistant message on error
+        messages: prev.messages.filter(
+          (m) => m.id !== assistantMessage.id || m.content.length > 0
+        ),
+      }))
+    }
+  }, [state.messages])
+
+  const clearMessages = useCallback(() => {
+    setState({
+      messages: [WELCOME_MESSAGE],
+      isLoading: false,
+      isStreaming: false,
+      error: null,
+    })
+  }, [])
+
+  const clearError = useCallback(() => {
+    setState((prev) => ({ ...prev, error: null }))
+  }, [])
+
+  return {
+    ...state,
+    sendMessage,
+    clearMessages,
+    clearError,
+  }
+}
diff --git a/docs/specs/ai-integratie/bouwplan-ai-docs-assistent-v1.md b/docs/specs/ai-integratie/bouwplan-ai-docs-assistent-v1.md
new file mode 100644
index 0000000..3b7cb01
--- /dev/null
+++ b/docs/specs/ai-integratie/bouwplan-ai-docs-assistent-v1.md
@@ -0,0 +1,321 @@
+# Mission Control — Bouwplan AI Documentatie Assistent
+
+**Projectnaam:** Mini-ECD – AI Documentatie Assistent
+**Versie:** v1.0
+**Datum:** 01-12-2025
+**Auteur:** Colin van der Heijden
+
+---
+
+## 1. Doel en context
+
+**Doel:** Een floating chat widget bouwen die eindgebruikers van het EPD helpt door vragen te beantwoorden op basis van de systeemdocumentatie.
+
+**Context:** Dit is de eerste AI-integratie in het Mini-ECD prototype. Het dient als fundament voor toekomstige AI features (zoals AI Pre-fill Behandelplan). De widget maakt documentatie direct toegankelijk via een conversatie-interface.
+
+**Relatie met andere documenten:**
+- PRD: `prd-ai-docs-assistent-v1.md` — Wat en waarom
+- FO: `fo-ai-docs-assistent-v1.md` — Hoe het werkt voor gebruikers
+
+---
+
+## 2. Uitgangspunten
+
+### 2.1 Technische Stack
+
+| Laag | Technologie |
+|------|-------------|
+| **Frontend** | Next.js 14.2 + React + Tailwind CSS |
+| **Backend** | Next.js API Routes (App Router) |
+| **Database** | Supabase PostgreSQL (alleen voor auth check) |
+| **AI** | Claude API (claude-sonnet-4-20250514) met streaming |
+| **Hosting** | Vercel |
+| **Icons** | Lucide React (Sparkles, X, Send) |
+
+### 2.2 Projectkaders
+
+| Aspect | Waarde |
+|--------|--------|
+| **Bouwtijd** | 1-2 dagen |
+| **Team** | 1 developer |
+| **Data** | Alleen bestaande MDX documentatie |
+| **Scope** | MVP — chat widget met streaming responses |
+| **Persistentie** | Sessie-only (geen database opslag) |
+
+### 2.3 Programmeer Uitgangspunten
+
+**Code Quality Principles:**
+
+- **DRY** — Herbruikbare hook voor chat state, centrale prompt configuratie
+- **KISS** — Eenvoudige fetch naar Claude API, geen SDK overhead
+- **SOC** — UI componenten gescheiden van API logic en knowledge base
+- **YAGNI** — Geen RAG, geen database opslag, geen multi-provider support
+
+**Security:**
+- API key alleen server-side (Next.js API route)
+- Widget alleen voor ingelogde gebruikers
+- Geen logging van conversaties
+
+---
+
+## 3. Epics & Stories Overzicht
+
+| Epic ID | Titel | Doel | Status | Stories |
+|---------|-------|------|--------|---------|
+| E0 | Knowledge Base Content | FAQ's en guidelines in markdown | ✅ Done | 2 |
+| E1 | Knowledge Services | CategoryDetector, KnowledgeLoader, PromptBuilder | ✅ Done | 3 |
+| E2 | API Endpoint | Streaming Claude integratie | ✅ Done | 1 |
+| E3 | Chat UI Components | Widget, messages, input | ✅ Done | 4 |
+| E4 | Integratie & Testing | Widget in EPD, testen | ⏳ To Do | 2 |
+
+**Totaal:** 12 stories, ~18 story points
+
+---
+
+## 4. Epics & Stories (Uitwerking)
+
+### Epic 0 — Knowledge Base Content
+
+**Epic Doel:** Gestructureerde FAQ's en guidelines in markdown bestanden.
+
+| Story ID | Beschrijving | Acceptatiecriteria | Status | SP |
+|----------|--------------|---------------------|--------|-----|
+| E0.S1 | FAQ markdown bestanden | 6 FAQ bestanden met Q&A per categorie | ✅ | 2 |
+| E0.S2 | Guidelines bestanden | 2 guideline bestanden (interface, technisch) | ✅ | 1 |
+
+**Deliverables:**
+```
+lib/docs/knowledge/
+├── faq_clientbeheer.md      # Cliënt aanmaken, zoeken, verwijderen
+├── faq_intake.md            # Intake starten, notities, spraak
+├── faq_screening.md         # Screening resultaten, vragenlijsten
+├── faq_behandelplan.md      # Plan maken, doelen, interventies
+├── faq_spraak.md            # Microfoon, dicteren, transcriptie
+├── faq_inloggen.md          # Login, wachtwoord, rechten
+├── guidelines_interface.md   # UI uitleg, navigatie, menu's
+└── guidelines_technisch.md   # FHIR API, data model (devs)
+```
+
+---
+
+### Epic 1 — Knowledge Services
+
+**Epic Doel:** Intelligente services voor dynamische knowledge loading.
+
+| Story ID | Beschrijving | Acceptatiecriteria | Status | SP |
+|----------|--------------|---------------------|--------|-----|
+| E1.S1 | CategoryDetector | Keyword matching om relevante categorieën te bepalen | ✅ | 2 |
+| E1.S2 | KnowledgeLoader | Laadt alleen relevante markdown bestanden | ✅ | 2 |
+| E1.S3 | PromptBuilder | Combineert base prompt + relevante knowledge | ✅ | 2 |
+
+**Deliverables:**
+```
+lib/docs/
+├── category-detector.ts    # Analyseert vraag → categorieën
+├── knowledge-loader.ts     # Laadt relevante knowledge
+└── prompt-builder.ts       # Bouwt geoptimaliseerde prompt
+```
+
+**Category Mapping:**
+```typescript
+const CATEGORY_KEYWORDS: Record<Category, string[]> = {
+  clientbeheer: ['cliënt', 'patient', 'aanmaken', 'zoeken', 'dossier'],
+  intake: ['intake', 'gesprek', 'notitie', 'verslag'],
+  screening: ['screening', 'vragenlijst', 'score', 'resultaat'],
+  behandelplan: ['behandelplan', 'doel', 'interventie', 'plan'],
+  spraak: ['spraak', 'microfoon', 'dicteren', 'stem', 'transcriptie'],
+  inloggen: ['inloggen', 'wachtwoord', 'login', 'account'],
+  interface: ['menu', 'knop', 'scherm', 'navigatie', 'waar vind'],
+  technisch: ['api', 'fhir', 'endpoint', 'database', 'developer']
+};
+```
+
+**Flow:**
+```
+Vraag: "Hoe maak ik een intake aan?"
+         ↓
+CategoryDetector → ['intake']
+         ↓
+KnowledgeLoader → laadt faq_intake.md
+         ↓
+PromptBuilder → base prompt + intake FAQ
+         ↓
+Claude API → streaming response
+```
+
+---
+
+### Epic 2 — API Endpoint
+
+**Epic Doel:** Streaming API endpoint met dynamische knowledge.
+
+| Story ID | Beschrijving | Acceptatiecriteria | Status | SP |
+|----------|--------------|---------------------|--------|-----|
+| E2.S1 | Streaming endpoint | `POST /api/docs/chat` met dynamic knowledge, SSE stream | ✅ | 3 |
+
+**Deliverables:**
+```
+app/api/docs/chat/
+  route.ts               # Streaming API endpoint
+```
+
+**API Contract:**
+```typescript
+// Request
+POST /api/docs/chat
+{
+  messages: Array<{ role: 'user' | 'assistant', content: string }>,
+  userMessage: string
+}
+
+// Response: Server-Sent Events stream
+event: content_block_delta
+data: {"delta":{"text":"..."}}
+```
+
+---
+
+### Epic 3 — Chat UI Components
+
+**Epic Doel:** Complete chat widget UI volgens FO specificaties.
+
+| Story ID | Beschrijving | Acceptatiecriteria | Status | SP |
+|----------|--------------|---------------------|--------|-----|
+| E3.S1 | Chat state hook | `use-docs-chat.ts` met messages, loading, sendMessage, streaming | ✅ | 2 |
+| E3.S2 | Message list component | `chat-messages.tsx` met styling, auto-scroll, streaming cursor | ✅ | 1 |
+| E3.S3 | Input component | `chat-input.tsx` met textarea, send, Enter/Shift+Enter | ✅ | 1 |
+| E3.S4 | Widget container | `docs-chat-widget.tsx` met trigger, panel, header, animaties | ✅ | 2 |
+
+**Deliverables:**
+```
+components/docs-chat/
+  use-docs-chat.ts       # Custom hook
+  chat-messages.tsx      # Message list
+  chat-input.tsx         # Input area
+  docs-chat-widget.tsx   # Main container
+```
+
+**UI Specs (uit FO):**
+
+| Element | Specificatie |
+|---------|--------------|
+| Trigger button | 56x56px, amber gradient, Sparkles icon, `fixed bottom-6 right-6` |
+| Panel | 384px breed, max 80vh, slide-in animatie |
+| User messages | Rechts, `bg-amber-100`, rounded |
+| Assistant messages | Links, `bg-slate-100`, rounded |
+| Streaming | Pulserende cursor `▊` |
+
+---
+
+### Epic 4 — Integratie & Testing
+
+**Epic Doel:** Widget geïntegreerd in EPD en getest.
+
+| Story ID | Beschrijving | Acceptatiecriteria | Status | SP |
+|----------|--------------|---------------------|--------|-----|
+| E4.S1 | Widget integratie | `DocsChatWidget` in EPD layout, alleen ingelogde users | ⏳ | 1 |
+| E4.S2 | Smoke tests | Happy flow, error states, category detection werkt | ⏳ | 1 |
+
+**Te wijzigen bestand:**
+```
+app/epd/components/epd-layout-client.tsx
+```
+
+---
+
+## 5. Kwaliteit & Testplan
+
+### Test Types
+
+| Test Type | Scope | Methode |
+|-----------|-------|---------|
+| Unit | Knowledge base loader | Console test |
+| Integration | API endpoint | curl/Postman |
+| Smoke | Volledige flow | Manual in browser |
+
+### Manual Test Checklist
+
+- [ ] Widget trigger button zichtbaar in EPD
+- [ ] Klik opent chat panel met animatie
+- [ ] Welkomstbericht wordt getoond
+- [ ] Vraag versturen werkt (Enter + button)
+- [ ] Streaming response verschijnt woord-voor-woord
+- [ ] Vervolgvraag behoudt context
+- [ ] X-knop sluit panel
+- [ ] Conversatie blijft behouden na sluiten/openen
+- [ ] Error state toont bij API failure
+- [ ] Widget verdwijnt bij uitloggen
+
+### Acceptatiecriteria (uit PRD)
+
+| Criterium | Target |
+|-----------|--------|
+| First token | < 2 seconden |
+| Volledige response | < 30 seconden |
+| Error rate | < 5% |
+
+---
+
+## 6. Demo & Presentatieplan
+
+**Duur:** 3 minuten
+**Scenario:**
+
+1. **Intro** (30s): "Dit is de documentatie assistent"
+2. **Vraag 1** (45s): "Hoe maak ik een intake aan?" → streaming antwoord
+3. **Vraag 2** (45s): "En hoe gebruik ik spraakherkenning?" → context behouden
+4. **Edge case** (30s): "Wat is de beste behandeling?" → "weet ik niet" response
+5. **Afsluiting** (30s): Widget sluiten, conversatie behouden
+
+---
+
+## 7. Risico's & Mitigatie
+
+| Risico | Kans | Impact | Mitigatie |
+|--------|------|--------|-----------|
+| AI hallucineert | Middel | Hoog | Strikte system prompt, FAQ's eerst, "alleen uit docs" regel |
+| Trage response | Laag | Middel | Streaming UX, timeout na 30s |
+| Context te groot | Laag | Middel | ~119KB past in context window, monitoring |
+| API rate limits | Laag | Middel | Sessie-based (geen caching nodig) |
+
+---
+
+## 8. Referenties
+
+### Mission Control Documents
+
+- **PRD:** `prd-ai-docs-assistent-v1.md`
+- **FO:** `fo-ai-docs-assistent-v1.md`
+- **Gerelateerd:** `prd-ai-prefill-behandelplan-v1.md`
+
+### Bestaande Code Patterns
+
+| Bestand | Pattern |
+|---------|---------|
+| `app/api/reports/classify/route.ts` | Claude API fetch pattern |
+| `lib/mdx/documentatie.ts` | MDX loading met gray-matter |
+| `components/ui/ai-button.tsx` | Amber AI styling |
+
+### Externe Referenties
+
+- [Claude API Docs](https://docs.anthropic.com)
+- [Anthropic Streaming](https://docs.anthropic.com/en/api/streaming)
+
+---
+
+## 9. Glossary
+
+| Term | Betekenis |
+|------|-----------|
+| SSE | Server-Sent Events (streaming protocol) |
+| Knowledge Base | Verzameling documentatie voor AI context |
+| FAQ | Frequently Asked Questions |
+| Streaming | Real-time response, woord-voor-woord |
+
+---
+
+**Versiehistorie:**
+
+| Versie | Datum | Auteur | Wijziging |
+|--------|-------|--------|-----------|
+| v1.0 | 01-12-2025 | Colin van der Heijden | Initiële versie |
diff --git a/docs/specs/ai-integratie/fo-ai-docs-assistent-v1.md b/docs/specs/ai-integratie/fo-ai-docs-assistent-v1.md
new file mode 100644
index 0000000..fcc3097
--- /dev/null
+++ b/docs/specs/ai-integratie/fo-ai-docs-assistent-v1.md
@@ -0,0 +1,386 @@
+# Functioneel Ontwerp (FO) – AI Documentatie Assistent
+
+**Projectnaam:** Mini-ECD – AI Documentatie Assistent
+**Versie:** v1.0
+**Datum:** 01-12-2025
+**Auteur:** Colin van der Heijden
+
+---
+
+## 1. Doel en relatie met het PRD
+
+**Doel van dit document:**
+Dit Functioneel Ontwerp beschrijft **hoe** de AI Documentatie Assistent functioneel werkt — wat de gebruiker ziet, doet en ervaart. Waar het PRD (`prd-ai-docs-assistent-v1.md`) uitlegt *wat en waarom*, laat dit FO zien *hoe dit in de praktijk werkt*.
+
+**Toelichting aan de lezer:**
+De AI Documentatie Assistent is een floating chat widget die eindgebruikers van het EPD helpt door vragen te beantwoorden op basis van de systeemdocumentatie. Dit is de eerste AI-integratie in het Mini-ECD prototype en dient als fundament voor toekomstige AI features.
+
+---
+
+## 2. Overzicht van de belangrijkste onderdelen
+
+1. **Floating Trigger Button** — Amber knop rechtsonder om widget te openen
+2. **Chat Panel** — Uitklapbaar gesprekspaneel
+3. **Message List** — Weergave van conversatie (gebruiker + assistent)
+4. **Input Area** — Tekstveld voor vragen stellen
+5. **Streaming Response** — Real-time weergave van AI antwoorden
+
+---
+
+## 3. Userstories
+
+| ID | Rol | Doel / Actie | Verwachte waarde | Prioriteit |
+|----|------|---------------|------------------|-------------|
+| US-01 | Behandelaar | Vraag stellen over EPD functie | Direct antwoord zonder zoeken | Hoog |
+| US-02 | Verpleegkundige | Uitleg krijgen over onbekende functie | Zelfstandig werken zonder collega's te storen | Hoog |
+| US-03 | Nieuwe medewerker | Systeem leren kennen via vragen | Interactieve onboarding | Hoog |
+| US-04 | Behandelaar | Vervolgvraag stellen | Context behouden in gesprek | Middel |
+| US-05 | Developer | Technische vraag over API | Snelle referentie zonder docs te openen | Middel |
+| US-06 | Alle gebruikers | Widget sluiten | Terug naar werk zonder afleiding | Hoog |
+
+**User Story Details:**
+
+> **US-01:** Als behandelaar wil ik een vraag kunnen stellen over het EPD zodat ik direct antwoord krijg zonder door documentatie te hoeven zoeken.
+
+> **US-02:** Als verpleegkundige wil ik uitleg kunnen vragen over een functie die ik niet ken zodat ik zelfstandig verder kan werken.
+
+> **US-03:** Als nieuwe medewerker wil ik via vragen het systeem leren kennen zodat ik sneller productief ben.
+
+---
+
+## 4. Functionele werking per onderdeel
+
+### 4.1 Floating Trigger Button
+
+**Locatie:** Rechtsonder in het scherm, altijd zichtbaar binnen EPD (`/epd/*` routes)
+
+**Gedrag:**
+- Amber gradient knop (56x56px) met Sparkles icon
+- Hover: lichte kleurverandering
+- Klik: opent chat panel, knop verdwijnt
+- Altijd bovenop andere content (z-index: 50)
+
+**States:**
+| State | Weergave |
+|-------|----------|
+| Default | Amber gradient met wit icon |
+| Hover | Donkerder amber |
+| Widget open | Knop verborgen |
+
+---
+
+### 4.2 Chat Panel
+
+**Afmetingen:** 384px breed × max 80vh hoog
+
+**Structuur:**
+```
+┌────────────────────────────────────┐
+│ Header: titel + sluit-knop         │
+├────────────────────────────────────┤
+│                                    │
+│ Message List (scrollbaar)          │
+│                                    │
+│                                    │
+├────────────────────────────────────┤
+│ Input Area: tekstveld + verzenden  │
+└────────────────────────────────────┘
+```
+
+**Header:**
+- Sparkles icon + "Documentatie Assistent" tekst
+- X-knop rechts om te sluiten
+- Amber/amber-100 achtergrond gradient
+
+**Gedrag bij openen:**
+1. Panel verschijnt met slide-in animatie (van onder)
+2. Welkomstbericht wordt getoond (indien eerste keer)
+3. Focus gaat naar input veld
+
+**Gedrag bij sluiten:**
+- Klik op X-knop → panel verdwijnt
+- Trigger button verschijnt weer
+- Conversatie blijft behouden (sessie)
+
+---
+
+### 4.3 Message List
+
+**Weergave van berichten:**
+
+| Type | Positie | Styling |
+|------|---------|---------|
+| Gebruiker | Rechts uitgelijnd | `bg-amber-100`, rounded |
+| Assistent | Links uitgelijnd | `bg-slate-100`, rounded |
+
+**Welkomstbericht (eerste bericht):**
+```
+Hallo! Ik ben de documentatie assistent voor het Mini-ECD.
+
+Stel gerust vragen over hoe het systeem werkt, bijvoorbeeld:
+• Hoe maak ik een nieuwe intake aan?
+• Hoe werkt de spraakherkenning?
+• Waar vind ik de screening resultaten?
+```
+
+**Scroll gedrag:**
+- Automatisch scrollen naar nieuwste bericht
+- Gebruiker kan omhoog scrollen door historie
+- Bij nieuw bericht: scroll naar beneden
+
+**Streaming weergave:**
+- Tekst verschijnt woord-voor-woord
+- Pulserende cursor aan einde tijdens streaming
+- Cursor verdwijnt wanneer response compleet is
+
+---
+
+### 4.4 Input Area
+
+**Componenten:**
+- Textarea (auto-resize, max 4 regels)
+- Verzend-knop (amber, pijl icon)
+
+**Interacties:**
+
+| Actie | Resultaat |
+|-------|-----------|
+| Enter | Verstuur bericht |
+| Shift + Enter | Nieuwe regel |
+| Klik verzend-knop | Verstuur bericht |
+| Leeg bericht versturen | Geen actie |
+
+**States:**
+
+| State | Textarea | Verzend-knop |
+|-------|----------|--------------|
+| Idle | Enabled, placeholder | Enabled (amber) |
+| Typing | Enabled, tekst zichtbaar | Enabled |
+| Loading | Disabled | Disabled (grijs) |
+| Error | Enabled | Enabled |
+
+**Placeholder tekst:** "Stel een vraag..."
+
+---
+
+### 4.5 Streaming Response
+
+**Proces:**
+1. Gebruiker verstuurt vraag
+2. Input wordt disabled
+3. Nieuw assistent-bericht verschijnt (leeg)
+4. Tekst streamt woord-voor-woord in
+5. Bij completion: input wordt enabled
+
+**Visuele feedback tijdens streaming:**
+- Pulserende cursor (`▊`) aan einde van tekst
+- Tekst verschijnt met ~50ms interval per chunk
+
+**Timeout:**
+- Na 30 seconden zonder response: toon foutmelding
+- Gebruiker kan opnieuw proberen
+
+---
+
+## 5. UI-overzicht (visuele structuur)
+
+### Widget Gesloten
+```
+┌─────────────────────────────────────────────────┐
+│                                                 │
+│              EPD Interface                      │
+│                                                 │
+│                                                 │
+│                                                 │
+│                                         ┌─────┐ │
+│                                         │ ✨  │ │
+│                                         └─────┘ │
+└─────────────────────────────────────────────────┘
+                                          ↑
+                                    Trigger Button
+```
+
+### Widget Open
+```
+┌─────────────────────────────────────────────────┐
+│                                                 │
+│              EPD Interface                      │
+│                                                 │
+│                        ┌────────────────────────┤
+│                        │ ✨ Docs Assistent   ✕ │
+│                        ├────────────────────────┤
+│                        │ Welkomstbericht...     │
+│                        │                        │
+│                        │ ┌──────────────────┐   │
+│                        │ │ Hoe maak ik...   │←──│── User
+│                        │ └──────────────────┘   │
+│                        │                        │
+│                        │ ┌──────────────────┐   │
+│                        │ │ Om een intake... │←──│── Assistant
+│                        │ │ ...              │   │
+│                        │ └──────────────────┘   │
+│                        ├────────────────────────┤
+│                        │ [Stel een vraag...] ➤  │
+│                        └────────────────────────┘
+└─────────────────────────────────────────────────┘
+```
+
+---
+
+## 6. Interacties met AI (functionele beschrijving)
+
+| Locatie | AI-actie | Trigger | Output |
+|---------|----------|---------|--------|
+| Chat widget | Vraag beantwoorden | Gebruiker verstuurt bericht | Streaming tekst-antwoord |
+| Chat widget | Vervolgvraag beantwoorden | Gebruiker stuurt vervolgvraag | Context-aware antwoord |
+| Chat widget | Buiten scope afhandelen | Vraag niet in documentatie | Eerlijk "weet ik niet" + suggesties |
+
+### AI Gedragsregels
+
+**Wel doen:**
+- Antwoorden baseren op de 14 MDX documentatiebestanden
+- Nederlands schrijven
+- Bullet points gebruiken voor stappen
+- Verwijzen naar specifieke menu's en knoppen
+- Eerlijk zeggen als informatie ontbreekt
+
+**Niet doen:**
+- Informatie verzinnen die niet in de documentatie staat
+- Medisch advies geven
+- Behandelsuggesties doen
+- Engels antwoorden (tenzij gevraagd)
+
+### Beschikbare Knowledge Base
+
+De assistent heeft toegang tot deze documentatie:
+
+| Bestand | Onderwerp |
+|---------|-----------|
+| `authentication.mdx` | Inloggen en authenticatie |
+| `client-management.mdx` | Cliëntbeheer |
+| `intake-system.mdx` | Intake proces |
+| `screening-system.mdx` | Screening functionaliteit |
+| `treatment-planning.mdx` | Behandelplannen |
+| `interface-design.mdx` | UI uitleg |
+| `spraakgestuurde-verslaglegging.mdx` | Spraakfuncties (NL) |
+| `voice-controlled-reporting.mdx` | Spraakfuncties (EN) |
+| `verpleegkundige-overdracht.mdx` | Overdracht workflow |
+| `fhir-datamodel.mdx` | Data model |
+| `fhir-api.mdx` | API documentatie |
+| `release-notes-system.mdx` | Release notes |
+| `build-errors-fix.mdx` | Troubleshooting |
+| `webpack-module-resolution.mdx` | Technische docs |
+
+---
+
+## 7. Gebruikersrollen en rechten
+
+| Rol | Toegang tot widget | Beperkingen |
+|-----|-------------------|-------------|
+| Behandelaar | Ja, binnen EPD | Geen |
+| Verpleegkundige | Ja, binnen EPD | Geen |
+| Admin | Ja, binnen EPD | Geen |
+| Niet-ingelogd | Nee | Widget niet zichtbaar |
+
+**Authenticatie:** Widget is alleen zichtbaar voor ingelogde gebruikers binnen `/epd/*` routes.
+
+---
+
+## 8. Error States en Edge Cases
+
+### Error States
+
+| Situatie | Weergave | Gebruikersactie |
+|----------|----------|-----------------|
+| API timeout (>30s) | "Het duurt langer dan verwacht. Probeer het opnieuw." | Retry knop |
+| API error | "Er ging iets mis. Probeer het later opnieuw." | Retry knop |
+| Netwerk offline | "Geen internetverbinding." | - |
+| Rate limit | "Te veel verzoeken. Wacht even." | Automatisch retry |
+
+### Edge Cases
+
+| Situatie | Gedrag |
+|----------|--------|
+| Zeer lange vraag (>2000 chars) | Vraag wordt afgekapt met waarschuwing |
+| Lege vraag | Verzenden geblokkeerd |
+| Alleen spaties | Behandeld als lege vraag |
+| Snelle opeenvolgende vragen | Vorige request wordt geannuleerd |
+| Browser tab wisselen | Streaming gaat door |
+| Page refresh | Conversatie verloren (sessie-based) |
+
+---
+
+## 9. Bijlagen & Referenties
+
+### Project Documentatie
+
+- PRD AI Documentatie Assistent (`prd-ai-docs-assistent-v1.md`)
+- PRD AI Pre-fill Behandelplan (`prd-ai-prefill-behandelplan-v1.md`)
+- UX Stylesheet (`ux-stylesheet.md`)
+- Technisch Ontwerp Mini-ECD (`to-mini-ecd-v1_2.md`)
+
+### Externe Referenties
+
+- [Claude API Documentation](https://docs.anthropic.com)
+- [Anthropic Streaming Guide](https://docs.anthropic.com/en/api/streaming)
+
+---
+
+## Appendix A: Conversatie Voorbeelden
+
+### Voorbeeld 1: Intake Vraag
+
+**Gebruiker:** "Hoe maak ik een nieuwe intake aan?"
+
+**Assistent:**
+```
+Om een nieuwe intake aan te maken:
+
+1. Ga naar het cliëntdossier via **Cliënten** in het hoofdmenu
+2. Selecteer de gewenste cliënt
+3. Klik op het tabblad **Intake**
+4. Klik op de knop **Nieuwe Intake**
+5. Vul de intake-informatie in het formulier
+6. Klik op **Opslaan** om de intake te bewaren
+
+Je kunt ook spraakherkenning gebruiken om de intake
+in te spreken via de microfoon-knop.
+```
+
+### Voorbeeld 2: Buiten Scope
+
+**Gebruiker:** "Wat is de beste behandeling voor depressie?"
+
+**Assistent:**
+```
+Die informatie heb ik niet. Ik kan alleen helpen met
+vragen over hoe het Mini-ECD systeem werkt.
+
+Misschien kan ik je helpen met:
+• Hoe maak ik een behandelplan aan?
+• Hoe voeg ik een diagnose toe?
+• Hoe werkt de screening functie?
+```
+
+### Voorbeeld 3: Technische Vraag
+
+**Gebruiker:** "Welke FHIR resources worden ondersteund?"
+
+**Assistent:**
+```
+Het Mini-ECD ondersteunt de volgende FHIR R4 resources:
+
+**Kern resources:**
+• Patient — Cliëntgegevens
+• Practitioner — Behandelaren
+• Encounter — Contactmomenten
+• Condition — Diagnoses/problemen
+• Observation — Metingen en observaties
+• CarePlan — Behandelplannen
+
+Zie de API documentatie voor endpoints en voorbeelden.
+```
+
+---
+
+*Document gegenereerd als onderdeel van AI Speedrun — Week 3*
diff --git a/docs/specs/ai-integratie/prd-ai-docs-assistent-v1.md b/docs/specs/ai-integratie/prd-ai-docs-assistent-v1.md
new file mode 100644
index 0000000..4bbc861
--- /dev/null
+++ b/docs/specs/ai-integratie/prd-ai-docs-assistent-v1.md
@@ -0,0 +1,403 @@
+# Product Requirements Document (PRD) — AI Documentatie Assistent
+
+**Projectnaam:** Mini-ECD – AI Documentatie Assistent
+**Versie:** v1.0
+**Datum:** 01-12-2025
+**Auteur:** Colin Lit
+**Status:** Draft – Ready for Review
+
+---
+
+## 1. Doelstelling
+
+**Doel van deze sectie:** Beschrijf waarom dit product wordt gebouwd en wat het beoogde resultaat is.
+
+**Toelichting:** Een intelligente chat-assistent die eindgebruikers van het EPD helpt door vragen te beantwoorden op basis van de systeemdocumentatie. De focus ligt op het direct beschikbaar maken van informatie zonder dat gebruikers zelf door documentatie hoeven te zoeken.
+
+> **Kernbelofte:** Direct antwoord op vragen over het EPD systeem, 24/7 beschikbaar via een handige chat widget.
+
+**Type:** MVP Feature binnen Mini-ECD Prototype — Eerste AI-integratie als opstap naar complexere features (zoals AI Pre-fill Behandelplan)
+
+**Relatie tot andere features:** Dit is de eerste AI-integratie die:
+1. De Claude API infrastructuur opzet
+2. Streaming responses implementeert
+3. AI UI patterns (amber thema) in productie brengt
+4. Als fundament dient voor toekomstige AI features
+
+---
+
+## 2. Doelgroep
+
+**Doel:** Schets wie de eindgebruikers en stakeholders zijn.
+
+### Primaire gebruikers
+
+| Rol | Behoefte | Pijnpunt nu |
+|-----|----------|-------------|
+| **GGZ Behandelaar** | Snel antwoord op "hoe werkt X?" | Documentatie doorzoeken kost tijd |
+| **Verpleegkundige** | Hulp bij onbekende functies | Moet collega's vragen of zelf uitzoeken |
+| **Nieuwe medewerker** | Systeem leren kennen | Geen interactieve onboarding |
+
+### Secundaire stakeholders
+
+- **Demo-bezoekers:** Product owners/managers die AI-mogelijkheden willen zien
+- **Developers:** Technische professionals geïnteresseerd in AI-integratie patterns
+- **Support team:** (toekomst) Minder support tickets door self-service
+
+---
+
+## 3. Kernfunctionaliteiten (MVP-scope)
+
+**Doel:** Afbakenen van de minimale werkende functies.
+
+### 3.1 Floating Chat Widget
+
+| Aspect | Specificatie |
+|--------|--------------|
+| **Positie** | Rechtsonder in EPD interface |
+| **Trigger** | Amber knop met Sparkles icon |
+| **Paneel** | 384px breed, max 80vh hoog |
+| **Animatie** | Slide-in van onder + fade |
+
+### 3.2 Documentatie-gebaseerde Antwoorden
+
+| Aspect | Specificatie |
+|--------|--------------|
+| **Knowledge Base** | 14 MDX bestanden in `/content/nl/documentatie/` |
+| **Taal** | Nederlands (input en output) |
+| **Scope** | Alleen informatie uit documentatie |
+| **Eerlijkheid** | "Weet ik niet" bij ontbrekende info |
+
+**Beschikbare documentatie:**
+- `authentication.mdx` - Inloggen en authenticatie
+- `client-management.mdx` - Cliëntbeheer
+- `intake-system.mdx` - Intake proces
+- `screening-system.mdx` - Screening functionaliteit
+- `treatment-planning.mdx` - Behandelplannen
+- `interface-design.mdx` - UI uitleg
+- `spraakgestuurde-verslaglegging.mdx` - Spraakfuncties
+- `voice-controlled-reporting.mdx` - Voice features (EN)
+- `verpleegkundige-overdracht.mdx` - Overdracht workflow
+- `fhir-datamodel.mdx` - Data model uitleg
+- `fhir-api.mdx` - API documentatie
+- `release-notes-system.mdx` - Release notes
+- `build-errors-fix.mdx` - Troubleshooting
+- `webpack-module-resolution.mdx` - Technische docs
+
+### 3.3 Streaming Responses
+
+| Aspect | Specificatie |
+|--------|--------------|
+| **Model** | Claude claude-sonnet-4-20250514 |
+| **Streaming** | Server-Sent Events (SSE) |
+| **UX** | Tekst verschijnt woord-voor-woord |
+| **Timeout** | 30 seconden max |
+
+### 3.4 Sessie-based Conversatie
+
+| Aspect | Specificatie |
+|--------|--------------|
+| **Persistentie** | Alleen tijdens browser sessie |
+| **Context** | Volledige conversatie wordt meegestuurd |
+| **Welkomstbericht** | Automatisch bij openen widget |
+| **Opslag** | React state (geen database) |
+
+---
+
+## 4. Gebruikersflows (Demo- en MVP-flows)
+
+**Doel:** Laten zien hoe de gebruiker stap-voor-stap door het systeem gaat.
+
+### Flow 1: Happy Path — Vraag Stellen
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ 1. Gebruiker werkt in EPD en heeft vraag                    │
+│    ↓                                                        │
+│ 2. Klikt op amber chat-knop rechtsonder                     │
+│    ↓                                                        │
+│ 3. Widget opent met welkomstbericht                         │
+│    ↓                                                        │
+│ 4. Typt vraag: "Hoe maak ik een intake aan?"               │
+│    ↓                                                        │
+│ 5. Ziet streaming antwoord verschijnen                      │
+│    ↓                                                        │
+│ 6. Stelt eventueel vervolgvraag                             │
+│    ↓                                                        │
+│ 7. Sluit widget en gaat verder met werk                     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Doorlooptijd:** < 30 seconden voor antwoord
+
+### Flow 2: Vraag Buiten Scope
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ 1. Gebruiker vraagt: "Wat is de beste behandeling voor X?"  │
+│    ↓                                                        │
+│ 2. Assistent antwoordt:                                     │
+│    "Die informatie heb ik niet. Ik kan alleen helpen met    │
+│     vragen over hoe het EPD systeem werkt. Probeer:         │
+│     - Hoe maak ik een behandelplan?                         │
+│     - Hoe werkt de screening?"                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Flow 3: Technische Vraag
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ 1. Developer vraagt: "Hoe werkt de FHIR API?"              │
+│    ↓                                                        │
+│ 2. Assistent geeft technische uitleg uit fhir-api.mdx       │
+│    ↓                                                        │
+│ 3. Verwijst naar relevante endpoints en voorbeelden         │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 5. Niet in Scope
+
+**Doel:** Duidelijk maken wat (nog) niet wordt gebouwd.
+
+| Feature | Reden |
+|---------|-------|
+| Conversatie opslaan in database | Complexiteit, privacy overwegingen |
+| Meerdere AI providers | Alleen Claude voor nu |
+| RAG / Vector search | Documentatie past in context window |
+| Proactieve suggesties | Focus op vraag-antwoord eerst |
+| Voice input | Aparte feature (spraakherkenning bestaat al) |
+| Multi-language | Alleen Nederlands voor MVP |
+| Admin dashboard voor prompts | Hardcoded prompts voor nu |
+| Feedback/rating systeem | Post-MVP |
+
+---
+
+## 6. Succescriteria
+
+**Doel:** Objectieve meetlat voor een geslaagde oplevering.
+
+| Criterium | Target | Meetmethode |
+|-----------|--------|-------------|
+| **Response Time** | First token < 2 sec | Console timing |
+| **Antwoord Kwaliteit** | Relevant en correct | User feedback |
+| **Widget Laadtijd** | < 100ms | Performance metrics |
+| **Error Rate** | < 5% API failures | Error logging |
+| **Demo Doorlooptijd** | Vraag → Antwoord < 30 sec | Live demo |
+| **Beschikbaarheid** | Widget altijd zichtbaar in EPD | Visual check |
+
+---
+
+## 7. Risico's & Mitigatie
+
+**Doel:** Risico's vroeg signaleren en plannen hoe ermee om te gaan.
+
+| Risico | Impact | Mitigatie |
+|--------|--------|-----------|
+| **AI hallucineert informatie** | Hoog | Strikte system prompt; "alleen uit docs"; duidelijk AI label |
+| **Documentatie te groot voor context** | Middel | ~119KB past; monitoring van token usage |
+| **API rate limits / kosten** | Middel | Geen caching nodig (sessie-based); prompt optimalisatie |
+| **Trage response (>5s)** | Middel | Streaming UX; skeleton loader; timeout handling |
+| **Privacy vragen in chat** | Laag | Geen logging; sessie-only; duidelijke scope communicatie |
+
+---
+
+## 8. Roadmap / Vervolg (Post-MVP)
+
+**Doel:** Richting geven aan toekomstige uitbreidingen.
+
+### Fase 2: Enhanced Assistant (Q1 2026)
+
+1. **Conversatie Persistentie** — Gesprekken opslaan per gebruiker
+2. **Feedback Systeem** — Thumbs up/down op antwoorden
+3. **Suggestie Chips** — Voorgestelde vragen tonen
+4. **Context Awareness** — Weet op welke pagina gebruiker zit
+
+### Fase 3: Proactive Help (Q2 2026)
+
+5. **Onboarding Flow** — Guided tour via chat
+6. **Error Recovery** — Automatisch hulp bij errors
+7. **Tooltip Integration** — AI uitleg bij complexe UI elementen
+
+### Fase 4: Advanced AI (Q2-Q3 2026)
+
+8. **AI Pre-fill Behandelplan** — Zie `prd-ai-prefill-behandelplan-v1.md`
+9. **Multi-provider Support** — OpenAI/Gemini fallback
+10. **RAG Implementation** — Voor grotere knowledge bases
+
+---
+
+## 9. Bijlagen & Referenties
+
+**Doel:** Bronnen koppelen voor context en consistentie.
+
+### Project Documentatie
+
+- PRD AI Pre-fill Behandelplan (`prd-ai-prefill-behandelplan-v1.md`)
+- PRD Mini-ECD v1.2 (`prd-mini-ecd-v1_2.md`)
+- Functioneel Ontwerp v2 (`fo-mini-ecd-v2.md`)
+- UX Stylesheet (`ux-stylesheet.md`)
+
+### Externe Referenties
+
+- [Claude API Documentation](https://docs.anthropic.com)
+- [Anthropic Streaming Guide](https://docs.anthropic.com/en/api/streaming)
+
+---
+
+## Appendix A: Technische Specificatie
+
+### A.1 Architectuur
+
+```
+┌─────────────────┐     ┌──────────────────┐     ┌─────────────┐
+│  DocsChatWidget │────▶│ /api/docs/chat   │────▶│ Claude API  │
+│  (React State)  │◀────│ (Streaming SSE)  │◀────│ (streaming) │
+└─────────────────┘     └──────────────────┘     └─────────────┘
+                               │
+                               ▼
+                        ┌──────────────────┐
+                        │ knowledge-base.ts│
+                        │ (laadt 14 MDX)   │
+                        └──────────────────┘
+```
+
+### A.2 Bestandsstructuur
+
+**Nieuwe bestanden:**
+
+```
+lib/
+  docs/
+    knowledge-base.ts         # Documentatie loader
+
+app/
+  api/
+    docs/
+      chat/
+        route.ts              # Streaming API endpoint
+
+components/
+  docs-chat/
+    docs-chat-widget.tsx      # Floating widget container
+    chat-messages.tsx         # Message list component
+    chat-input.tsx            # Input met send button
+    use-docs-chat.ts          # Custom hook voor state
+```
+
+**Te wijzigen:**
+
+```
+app/epd/components/epd-layout-client.tsx  # Widget toevoegen
+```
+
+### A.3 API Endpoint
+
+```
+POST /api/docs/chat
+```
+
+**Request:**
+```json
+{
+  "messages": [
+    { "role": "user", "content": "Hoe maak ik een intake?" },
+    { "role": "assistant", "content": "Om een intake aan te maken..." }
+  ],
+  "userMessage": "En hoe voeg ik notities toe?"
+}
+```
+
+**Response:** Server-Sent Events stream
+
+```
+event: content_block_delta
+data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"Om "}}
+
+event: content_block_delta
+data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"notities "}}
+...
+```
+
+### A.4 System Prompt
+
+```
+Je bent een vriendelijke documentatie assistent voor het Mini-ECD,
+een GGZ EPD (Elektronisch Patiënt Dossier) systeem.
+
+## Jouw rol
+- Beantwoord vragen over hoe het EPD systeem werkt
+- Help gebruikers functies te vinden en te gebruiken
+- Verwijs naar relevante documentatie secties
+
+## Belangrijke regels
+- Je ENIGE kennisbron is de onderstaande documentatie
+- Beantwoord vragen ALLEEN op basis van deze informatie
+- Als informatie ontbreekt: zeg eerlijk dat je het niet weet
+- Verzin NOOIT informatie die niet in de documentatie staat
+- Geef GEEN medisch advies of behandelsuggesties
+
+## Jouw publiek
+Zorgprofessionals (behandelaars, verpleegkundigen) die het EPD gebruiken.
+
+## Stijl
+- Schrijf in het Nederlands
+- Wees beknopt maar vriendelijk
+- Gebruik bullet points voor stappen
+- Verwijs naar specifieke menu's en knoppen waar relevant
+
+---
+DOCUMENTATIE:
+
+{content van alle 14 MDX bestanden}
+
+---
+```
+
+### A.5 Component Specificaties
+
+**DocsChatWidget:**
+- Positie: `fixed bottom-6 right-6`
+- Z-index: `z-50`
+- Trigger: 56x56px amber gradient button
+- Panel: 384px breed, max 80vh hoog
+- Animatie: `animate-in slide-in-from-bottom-4 fade-in`
+
+**ChatMessages:**
+- Scroll: `overflow-y-auto`
+- User bubbles: rechts, `bg-amber-100`
+- Assistant bubbles: links, `bg-slate-100`
+- Streaming indicator: pulserende cursor
+
+**ChatInput:**
+- Textarea: auto-resize, max 4 regels
+- Send button: amber, disabled tijdens loading
+- Enter: verstuur (Shift+Enter: nieuwe regel)
+
+---
+
+## Appendix B: UI States
+
+### Widget States
+
+| State | Weergave | Actie |
+|-------|----------|-------|
+| **Gesloten** | Amber floating button | Klik → Open |
+| **Open - Idle** | Chat panel met welkomst | Type vraag |
+| **Open - Loading** | Streaming indicator | Wacht |
+| **Open - Streaming** | Tekst verschijnt | Lees |
+| **Open - Error** | Foutmelding | Retry knop |
+
+### Welkomstbericht
+
+> "Hallo! Ik ben de documentatie assistent voor het Mini-ECD.
+> Stel gerust vragen over hoe het systeem werkt, bijvoorbeeld:
+> - Hoe maak ik een nieuwe intake aan?
+> - Hoe werkt de spraakherkenning?
+> - Waar vind ik de screening resultaten?"
+
+---
+
+*Document gegenereerd als onderdeel van AI Speedrun — Week 3*
diff --git a/docs/specs/ai-integratie/prd-ai-prefill-behandelplan-v1.md b/docs/specs/ai-integratie/prd-ai-prefill-behandelplan-v1.md
new file mode 100644
index 0000000..d0ecfe4
--- /dev/null
+++ b/docs/specs/ai-integratie/prd-ai-prefill-behandelplan-v1.md
@@ -0,0 +1,349 @@
+# 📄 Product Requirements Document (PRD) — AI Pre-fill Behandelplan
+
+**Projectnaam:** Mini-ECD – AI Pre-fill Behandelplan  
+**Versie:** v1.0  
+**Datum:** 30-11-2025  
+**Auteur:** Colin Lit
+**Status:** Draft – Ready for Review
+
+---
+
+## 1. Doelstelling
+
+🎯 **Doel van deze sectie:** Beschrijf waarom dit product wordt gebouwd en wat het beoogde resultaat is.
+
+📘 **Toelichting:** Een intelligent pre-fill systeem dat automatisch behandelplanconcepten genereert op basis van intake-notities en probleemprofielen. De focus ligt op het drastisch verminderen van administratieve last terwijl klinische kwaliteit behouden blijft.
+
+> **Kernbelofte:** Van 30+ minuten handmatig behandelplan schrijven naar <5 minuten review en publiceren.
+
+**Type:** MVP Feature binnen Mini-ECD Prototype (Week 3-4 AI Speedrun)
+
+---
+
+## 2. Doelgroep
+
+🎯 **Doel:** Schets wie de eindgebruikers en stakeholders zijn.
+
+### Primaire gebruikers
+
+| Rol | Behoefte | Pijnpunt nu |
+|-----|----------|-------------|
+| **GGZ Behandelaar** | Snel bruikbaar behandelplan | 30+ min typen per plan |
+| **Regiebehandelaar** | Review & accorderen | Wachten op aanlevering |
+
+### Secundaire stakeholders
+
+- **Demo-bezoekers:** Product owners/managers die AI-mogelijkheden willen zien
+- **Developers:** Technische professionals geïnteresseerd in AI-integratie patterns
+- **Zorgverzekeraars:** (toekomst) Compliance met zorgstandaarden
+
+---
+
+## 3. Kernfunctionaliteiten (MVP-scope)
+
+🎯 **Doel:** Afbakenen van de minimale werkende functies.
+
+### 3.1 Automatische Draft Generatie
+
+| Aspect | Specificatie |
+|--------|--------------|
+| **Trigger** | Probleemprofiel opgeslagen → AI genereert draft |
+| **Input** | Intake-notities + DSM-categorie + Severity |
+| **Output** | Concept behandelplan (4 secties) |
+| **Timing** | On-demand bij navigatie naar Behandelplan tab |
+
+### 3.2 SMART Doelen Generatie
+
+1. AI extraheert concrete klachten uit intake-notities
+2. Genereert 2-4 SMART-doelen afgestemd op DSM-categorie en severity
+3. Elk doel bevat:
+   - **S**pecifiek gedrag/situatie
+   - **M**eetbaar criterium (frequentie, intensiteit)
+   - **A**cceptabel voor cliënt
+   - **R**ealistisch binnen behandelkader
+   - **T**ijdgebonden (X weken)
+
+**Voorbeeld output:**
+> "Cliënt ervaart maximaal 1 paniekaanval per week (nu: 3x/week) binnen 8 weken behandeling"
+
+### 3.3 Evidence-based Interventie Mapping
+
+| DSM-Categorie | Primaire Interventies | Severity → Intensiteit |
+|---------------|----------------------|------------------------|
+| Angststoornissen | CGT, Exposure, ACT | Hoog → 12-16 sessies |
+| Stemmingsklachten | CGT, IPT, Gedragsactivatie | Middel → 8-12 sessies |
+| Trauma/PTSS | EMDR, Narratieve therapie | Hoog → 12+ sessies |
+| Persoonlijkheid | Schematherapie, MBT | Hoog → 20+ sessies |
+
+### 3.4 Micro-AI Regeneratie
+
+- Per sectie/item een **[↻ Regenereer]** knop
+- Behandelaar kan specifieke onderdelen laten hergenereren
+- Behoudt context van overige secties
+- Optioneel: korte instructie meegeven ("maak concreter", "focus op werk")
+
+### 3.5 *(Stretch)* ROM Score Integratie
+
+- Indien ROM-scores beschikbaar: meenemen in doelbepaling
+- Baseline scores automatisch toevoegen aan meetmomenten
+- Suggestie voor ROM-instrument bij evaluatiemomenten
+
+---
+
+## 4. Gebruikersflows (Demo- en MVP-flows)
+
+🎯 **Doel:** Laten zien hoe de gebruiker stap-voor-stap door het systeem gaat.
+
+### Flow 1: Happy Path — Intake → Behandelplan
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ 1. Behandelaar voltooit intake en slaat notities op        │
+│    ↓                                                        │
+│ 2. Klikt [AI › Analyseer intake]                           │
+│    ↓                                                        │
+│ 3. Probleemprofiel wordt gegenereerd (DSM + Severity)      │
+│    ↓                                                        │
+│ 4. Accepteert/bewerkt profiel → Slaat op                   │
+│    ↓                                                        │
+│ 5. Navigeert naar Behandelplan tab                         │
+│    ↓                                                        │
+│ 6. Ziet: "⚡ AI heeft een concept klaargezet"              │
+│    ↓                                                        │
+│ 7. Reviewt SMART-doelen, past aan indien nodig             │
+│    ↓                                                        │
+│ 8. Klikt [Accepteer & Publiceer] → Plan v1 actief          │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Doorlooptijd:** < 3 minuten (vs. 30+ minuten traditioneel)
+
+### Flow 2: Regeneratie van specifiek onderdeel
+
+1. Behandelaar vindt Doel 2 niet passend
+2. Klikt **[↻ Regenereer]** bij Doel 2
+3. AI genereert alternatief doel met zelfde context
+4. Behandelaar selecteert nieuw voorstel of bewerkt handmatig
+
+### Flow 3: Handmatige start (geen AI)
+
+1. Behandelaar opent Behandelplan zonder probleemprofiel
+2. Ziet melding: *"Geen concept beschikbaar. Vul eerst probleemprofiel in of start handmatig."*
+3. Keuze: **[Naar Probleemprofiel]** of **[Start leeg plan]**
+
+---
+
+## 5. Niet in Scope
+
+🎯 **Doel:** Duidelijk maken wat (nog) niet wordt gebouwd.
+
+| Feature | Reden |
+|---------|-------|
+| Volledige DSM-5 classificatie | Alleen DSM-light (6 categorieën) voor prototype |
+| Multi-disciplinaire plannen (MDO) | Complexiteit, geen meerwaarde voor demo |
+| DBC/ZPM declaratie-koppeling | Vereist externe integraties |
+| Real-time collaboration | Technisch complex, lage prioriteit |
+| Volledige ROM-vragenlijst afname | Alleen scores indien al beschikbaar |
+| Productie audit logging | Demo-only, geen compliance vereist |
+| Meerdere AI providers | Alleen Claude voor nu |
+
+---
+
+## 6. Succescriteria
+
+🎯 **Doel:** Objectieve meetlat voor een geslaagde oplevering.
+
+| Criterium | Target | Meetmethode |
+|-----------|--------|-------------|
+| **AI Response Time** | < 5 seconden | Console timing |
+| **Draft Kwaliteit** | ≥ 80% bruikbaar zonder grote edits | User feedback |
+| **Tijdsbesparing** | Van 30+ min → < 5 min | Stopwatch demo |
+| **Demo Doorlooptijd** | Intake → Plan in < 3 min | Live demo |
+| **Error Rate** | < 5% API failures | Error logging |
+| **User Acceptance** | Min. 2 testers positief | Feedback forms |
+
+---
+
+## 7. Risico's & Mitigatie
+
+🎯 **Doel:** Risico's vroeg signaleren en plannen hoe ermee om te gaan.
+
+| Risico | Impact | Mitigatie |
+|--------|--------|-----------|
+| **AI output klinisch onbruikbaar** | 🔴 Hoog | Prompts testen met GGZ-professionals; few-shot examples; "AI Concept" label |
+| **Hallucinaties in doelen/interventies** | 🟡 Middel | Strikte JSON schema validatie; verplichte menselijke review |
+| **API rate limits / kosten** | 🟡 Middel | Caching van drafts; prompt optimalisatie voor tokens |
+| **Trage response (>10s)** | 🟡 Middel | Streaming response; skeleton loaders; timeout handling |
+| **Scope creep ("nog even dit erbij")** | 🟡 Middel | Strikte PRD; "Post-MVP" parkeren |
+| **Privacy concerns demo-data** | 🟢 Laag | Alleen fictieve cliëntdata gebruiken |
+
+---
+
+## 8. Roadmap / Vervolg (Post-MVP)
+
+🎯 **Doel:** Richting geven aan toekomstige uitbreidingen.
+
+### Fase 2: Enhanced AI (Q1 2026)
+
+1. **Background Generation** — Draft al genereren bij opslaan probleemprofiel
+2. **Template Bibliotheek** — Voorgedefinieerde templates per diagnose
+3. **Prompt Tuning** — A/B testen van verschillende prompt strategieën
+
+### Fase 3: Clinical Intelligence (Q2 2026)
+
+4. **Sessie-over-Sessie Tracking** — AI vergelijkt voortgang vs. doelen
+5. **ROM Integratie** — Automatische vragenlijst afname en scoring
+6. **Risico Detectie** — Flagging bij zorgwekkende patronen
+
+### Fase 4: Compliance & Scale (Q3 2026)
+
+7. **Zorgstandaard Compliance** — Check tegen GGZ richtlijnen
+8. **Multi-provider Support** — OpenAI/Gemini fallback
+9. **Audit Trail** — Volledige logging voor verantwoording
+
+---
+
+## 9. Bijlagen & Referenties
+
+🎯 **Doel:** Bronnen koppelen voor context en consistentie.
+
+### Project Documentatie
+
+- PRD Mini-ECD v1.2 (`prd-mini-ecd-v1_2.md`)
+- Functioneel Ontwerp v2 (`fo-mini-ecd-v2.md`)
+- Technisch Ontwerp (`to-mini-ecd-v1_2.md`)
+- UX Stylesheet (`ux-stylesheet.md`)
+- Live Transcriptie FO (`fo-live-transcriptie-v1.md`)
+- FHIR GGZ Schema (`20241121_fhir_ggz_schema.sql`)
+
+### Externe Referenties
+
+- [Claude API Documentation](https://docs.anthropic.com)
+- [GGZ Zorgstandaarden](https://www.ggzstandaarden.nl)
+- [SMART Doelen Framework](https://www.ggzstandaarden.nl/generieke-modules/individueel-zorgplan)
+
+---
+
+## Appendix A: Technische Specificatie
+
+### A.1 Data Flow
+
+```
+┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐
+│  Intake Notities │────▶│                  │────▶│  Behandelplan    │
+│  (document_ref)  │     │   Claude API     │     │  Draft (JSONB)   │
+├──────────────────┤     │                  │     ├──────────────────┤
+│  Probleemprofiel │────▶│  /v1/messages    │     │  - doelen[]      │
+│  (DSM + Severity)│     │                  │     │  - interventies[]│
+└──────────────────┘     └──────────────────┘     │  - frequentie    │
+                                                   │  - meetmomenten[]│
+                                                   └──────────────────┘
+```
+
+### A.2 API Endpoint
+
+```
+POST /api/ai/generate-behandelplan
+```
+
+**Request:**
+```json
+{
+  "clientId": "uuid",
+  "intakeIds": ["uuid", "uuid"],
+  "probleemProfiel": {
+    "categorie": "Angststoornissen",
+    "severity": "Hoog",
+    "opmerkingen": "Paniekaanvallen 3x/week, vermijding openbare ruimtes"
+  }
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "draft": {
+    "doelen": [
+      {
+        "id": "doel-1",
+        "tekst": "Frequentie paniekaanvallen verminderen van 3x/week naar max 1x/week",
+        "tijdslimiet": "8 weken",
+        "meetbaar": "Dagboekregistratie"
+      }
+    ],
+    "interventies": [
+      {
+        "id": "int-1",
+        "naam": "Cognitieve Gedragstherapie (CGT)",
+        "sessies": 12,
+        "rationale": "Evidence-based voor paniekstoornis"
+      }
+    ],
+    "frequentie": "Wekelijks, 50 minuten per sessie",
+    "meetmomenten": [
+      { "moment": "Baseline", "week": 0 },
+      { "moment": "Tussentijds", "week": 4 },
+      { "moment": "Tussentijds", "week": 8 },
+      { "moment": "Afsluiting", "week": 12 }
+    ]
+  },
+  "metadata": {
+    "model": "claude-sonnet-4-20250514",
+    "tokens_used": 1847,
+    "generation_time_ms": 3200
+  }
+}
+```
+
+### A.3 Claude Prompt Template (Conceptueel)
+
+```
+Je bent een ervaren GGZ-behandelaar die behandelplannen opstelt volgens 
+de Nederlandse zorgstandaarden.
+
+## Context
+- Intake notities: {intakeContent}
+- DSM-categorie: {categorie}
+- Severity: {severity}
+- Aanvullende opmerkingen: {opmerkingen}
+
+## Opdracht
+Genereer een behandelplan concept met:
+
+1. **SMART Doelen** (2-4 stuks)
+   - Specifiek, Meetbaar, Acceptabel, Realistisch, Tijdgebonden
+   - Gebaseerd op de hoofdklachten uit de intake
+   
+2. **Interventies**
+   - Evidence-based methoden passend bij de diagnose
+   - Inclusief geschat aantal sessies
+   
+3. **Frequentie en Duur**
+   - Behandelintensiteit afgestemd op severity
+   
+4. **Meetmomenten**
+   - Evaluatieschema voor voortgangsbewaking
+
+## Output Format
+Antwoord ALLEEN met valid JSON volgens het schema.
+```
+
+---
+
+## Appendix B: UI States
+
+### Behandelplan Tab States
+
+| State | Weergave | Actie |
+|-------|----------|-------|
+| **Geen profiel** | "Vul eerst probleemprofiel in" | [Naar Profiel] |
+| **Generating** | Skeleton loader + "AI genereert..." | Wacht |
+| **Draft ready** | "⚡ AI Concept" badge + content | Review/Edit |
+| **Error** | "Genereren mislukt" + retry | [Probeer opnieuw] |
+| **Concept** | Oranje badge, bewerkbaar | [Publiceer] |
+| **Gepubliceerd** | Groene badge, read-only | [Nieuwe versie] |
+
+---
+
+*Document gegenereerd als onderdeel van AI Speedrun — Week 3*