docs(10): create phase plan

2026-03-25 23:33:27 -06:00
parent 95d05f5f88
commit eae4b0324d
4 changed files with 805 additions and 6 deletions
--- a/.planning/phases/10-agent-capabilities/10-03-PLAN.md
+++ b/.planning/phases/10-agent-capabilities/10-03-PLAN.md
@@ -0,0 +1,197 @@
+---
+phase: 10-agent-capabilities
+plan: 03
+type: execute
+wave: 2
+depends_on: ["10-01"]
+files_modified:
+  - packages/portal/app/(dashboard)/knowledge-base/page.tsx
+  - packages/portal/components/kb/document-list.tsx
+  - packages/portal/components/kb/upload-dialog.tsx
+  - packages/portal/components/kb/url-ingest-dialog.tsx
+  - packages/portal/components/nav/sidebar.tsx
+  - packages/portal/lib/api.ts
+autonomous: false
+requirements:
+  - CAP-03
+
+must_haves:
+  truths:
+    - "Operators can see a Knowledge Base page in the portal navigation"
+    - "Operators can upload files via drag-and-drop or file picker dialog"
+    - "Operators can add URLs (web pages) and YouTube URLs for ingestion"
+    - "Uploaded documents show processing status (processing, ready, error) with live polling"
+    - "Operators can delete documents from the knowledge base"
+    - "Operators can re-index a document"
+    - "Customer operators can view the KB but not upload or delete (RBAC)"
+  artifacts:
+    - path: "packages/portal/app/(dashboard)/knowledge-base/page.tsx"
+      provides: "KB management page with document list, upload, and URL ingestion"
+      min_lines: 50
+    - path: "packages/portal/components/kb/document-list.tsx"
+      provides: "Document list component with status badges and action buttons"
+    - path: "packages/portal/components/kb/upload-dialog.tsx"
+      provides: "File upload dialog with drag-and-drop and file picker"
+  key_links:
+    - from: "packages/portal/app/(dashboard)/knowledge-base/page.tsx"
+      to: "/api/portal/kb/{tenant_id}/documents"
+      via: "TanStack Query fetch + polling"
+      pattern: "useQuery.*kb.*documents"
+    - from: "packages/portal/components/kb/upload-dialog.tsx"
+      to: "/api/portal/kb/{tenant_id}/documents"
+      via: "FormData multipart POST"
+      pattern: "FormData.*upload"
+---
+
+<objective>
+Build the Knowledge Base management page in the portal where operators can upload documents, add URLs, view processing status, and manage their tenant's knowledge base.
+
+Purpose: Completes CAP-03 by providing the user-facing interface for document management. Operators need to see what's in their KB, upload new content, and monitor ingestion status.
+
+Output: Fully functional /knowledge-base portal page with file upload, URL/YouTube ingestion, document list with status polling, delete, and re-index.
+</objective>
+
+<execution_context>
+@/home/adelorenzo/.claude/get-shit-done/workflows/execute-plan.md
+@/home/adelorenzo/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/phases/10-agent-capabilities/10-CONTEXT.md
+@.planning/phases/10-agent-capabilities/10-01-SUMMARY.md
+
+<interfaces>
+<!-- KB API endpoints from Plan 01 -->
+POST /api/portal/kb/{tenant_id}/documents — multipart file upload, returns 201 {id, filename, status}
+POST /api/portal/kb/{tenant_id}/documents/url — JSON {url, source_type}, returns 201 {id, source_url, status}
+GET  /api/portal/kb/{tenant_id}/documents — returns [{id, filename, source_url, content_type, status, error_message, chunk_count, created_at}]
+DELETE /api/portal/kb/{tenant_id}/documents/{document_id} — returns 204
+POST /api/portal/kb/{tenant_id}/documents/{document_id}/reindex — returns 200
+
+<!-- Portal patterns -->
+- TanStack Query for data fetching (useQuery, useMutation)
+- shadcn/ui components (Button, Dialog, Badge, Table, etc.)
+- Tailwind CSS for styling
+- next-intl useTranslations() for i18n
+- RBAC: session.user.role determines admin vs operator capabilities
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Knowledge Base page with document list, upload, and URL ingestion</name>
+  <files>
+    packages/portal/app/(dashboard)/knowledge-base/page.tsx,
+    packages/portal/components/kb/document-list.tsx,
+    packages/portal/components/kb/upload-dialog.tsx,
+    packages/portal/components/kb/url-ingest-dialog.tsx,
+    packages/portal/lib/api.ts,
+    packages/portal/components/nav/sidebar.tsx
+  </files>
+  <action>
+    1. **Add KB link to navigation** (`sidebar.tsx` or equivalent nav component):
+       - Add "Knowledge Base" link to sidebar nav, visible for platform_admin and customer_admin roles
+       - customer_operator can view (read-only) — add to nav but upload/delete buttons hidden
+       - Icon: use a document/book icon from lucide-react
+
+    2. **KB page** (`packages/portal/app/(dashboard)/knowledge-base/page.tsx`):
+       - Server Component wrapper that renders the client KB content
+       - Page title: "Knowledge Base" with subtitle showing tenant context
+       - Two action buttons for admins: "Upload Files" (opens upload dialog), "Add URL" (opens URL dialog)
+       - Document list component below actions
+       - Use tenant_id from session/route context (same pattern as other dashboard pages)
+
+    3. **Document list** (`packages/portal/components/kb/document-list.tsx`):
+       - Client component using useQuery to fetch GET /api/portal/kb/{tenant_id}/documents
+       - Poll every 5 seconds while any document has status='processing' (refetchInterval: 5000 conditional)
+       - Table with columns: Name (filename or source_url), Type (file/url/youtube), Status (badge), Chunks, Date, Actions
+       - Status badges: "Processing" (amber/spinning), "Ready" (green), "Error" (red with tooltip showing error_message)
+       - Actions per row (admin only): Delete button, Re-index button
+       - Empty state: "No documents in knowledge base yet. Upload files or add URLs to get started."
+       - Delete: useMutation calling DELETE endpoint, invalidate query on success, confirm dialog before delete
+       - Re-index: useMutation calling POST reindex endpoint, invalidate query on success
+
+    4. **Upload dialog** (`packages/portal/components/kb/upload-dialog.tsx`):
+       - shadcn/ui Dialog component
+       - Drag-and-drop zone (onDragOver, onDrop handlers) with visual feedback
+       - File picker button (input type="file" with accept for supported extensions: .pdf,.docx,.pptx,.xlsx,.csv,.txt,.md)
+       - Support multiple file selection
+       - Show selected files list before upload
+       - Upload button: for each file, POST FormData to /api/portal/kb/{tenant_id}/documents
+       - Show upload progress (file-by-file)
+       - Close dialog and invalidate document list query on success
+       - Error handling: show toast on failure
+
+    5. **URL ingest dialog** (`packages/portal/components/kb/url-ingest-dialog.tsx`):
+       - shadcn/ui Dialog component
+       - Input field for URL
+       - Radio or select for source type: "Web Page" or "YouTube Video"
+       - Auto-detect: if URL contains youtube.com or youtu.be, default to YouTube
+       - Submit: POST to /api/portal/kb/{tenant_id}/documents/url
+       - Close dialog and invalidate document list query on success
+
+    6. **API client updates** (`packages/portal/lib/api.ts`):
+       - Add KB API functions: fetchKbDocuments, uploadKbDocument, addKbUrl, deleteKbDocument, reindexKbDocument
+       - Use the same fetch wrapper pattern as existing API calls
+
+    7. **i18n**: Add English, Spanish, and Portuguese translations for KB page strings (following existing i18n pattern with next-intl message files). Add keys like: kb.title, kb.upload, kb.addUrl, kb.empty, kb.status.processing, kb.status.ready, kb.status.error, kb.delete.confirm, etc.
+  </action>
+  <verify>
+    <automated>cd /home/adelorenzo/repos/konstruct/packages/portal && npx next build 2>&1 | tail -5</automated>
+  </verify>
+  <done>Knowledge Base page exists at /knowledge-base with document list, file upload dialog (drag-and-drop + picker), URL/YouTube ingest dialog, status polling, delete, and re-index. Navigation updated. i18n strings added for all three languages. Portal builds successfully.</done>
+</task>
+
+<task type="checkpoint:human-verify" gate="blocking">
+  <name>Task 2: Human verification of Knowledge Base portal page</name>
+  <files>packages/portal/app/(dashboard)/knowledge-base/page.tsx</files>
+  <action>
+    Verify the Knowledge Base management page in the portal:
+    - File upload via drag-and-drop and file picker (PDF, DOCX, PPTX, XLSX, CSV, TXT, MD)
+    - URL ingestion (web pages via Firecrawl, YouTube transcripts)
+    - Document list with live processing status (processing/ready/error)
+    - Delete and re-index actions
+    - RBAC: admins can upload/delete, operators can only view
+
+    Steps:
+    1. Navigate to the portal and confirm "Knowledge Base" appears in the sidebar navigation
+    2. Click Knowledge Base — verify the page loads with empty state message
+    3. Click "Upload Files" — verify drag-and-drop zone and file picker appear
+    4. Upload a small PDF or TXT file — verify it appears in the document list with "Processing" status
+    5. Wait for processing to complete — verify status changes to "Ready" with chunk count
+    6. Click "Add URL" — verify URL input dialog with web/YouTube type selector
+    7. Add a URL — verify it appears in the list and processes
+    8. Click delete on a document — verify confirmation dialog, then document removed
+    9. If logged in as customer_operator — verify upload/delete buttons are hidden but document list is visible
+  </action>
+  <verify>Human verification of KB page functionality and RBAC</verify>
+  <done>KB page approved by human testing — upload, URL ingest, status polling, delete, re-index, and RBAC all working</done>
+</task>
+
+</tasks>
+
+<verification>
+- Portal builds: `cd packages/portal && npx next build`
+- KB page renders at /knowledge-base
+- Document upload triggers backend ingestion
+- Status polling shows processing -> ready transition
+- RBAC enforced on upload/delete actions
+</verification>
+
+<success_criteria>
+- Knowledge Base page accessible in portal navigation
+- File upload works with drag-and-drop and file picker
+- URL and YouTube ingestion works
+- Document list shows live processing status with polling
+- Delete and re-index work
+- RBAC enforced (admin: full access, operator: view only)
+- All three languages have KB translations
+- Human verification approved
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/10-agent-capabilities/10-03-SUMMARY.md`
+</output>