docs(10-03): complete Knowledge Base portal page plan

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.planning/ROADMAP.md

@@ -144,7 +144,7 @@ Phases execute in numeric order: 1 -> 2 -> 3 -> 4 -> 5 -> 6 -> 7 -> 8 -> 9 -> 10
 | 7. Multilanguage | 4/4 | Complete    | 2026-03-25 |
 | 8. Mobile + PWA | 4/4 | Complete    | 2026-03-26 |
 | 9. Testing & QA | 3/3 | Complete    | 2026-03-26 |
-| 10. Agent Capabilities | 2/3 | In Progress|  |
+| 10. Agent Capabilities | 3/3 | Complete   | 2026-03-26 |
 
 ---
 

.planning/STATE.md

@@ -3,14 +3,14 @@ gsd_state_version: 1.0
 milestone: v1.0
 milestone_name: milestone
 status: completed
-stopped_at: "Completed 10-02: Google Calendar OAuth, per-tenant calendar tool CRUD"
-last_updated: "2026-03-26T15:15:00.000Z"
+stopped_at: "Completed 10-03: Knowledge Base portal page, file upload, URL ingest, RBAC, i18n"
+last_updated: "2026-03-26T15:24:12.697Z"
 last_activity: 2026-03-23 — Completed 03-02 onboarding wizard, Slack OAuth, BYO API keys
 progress:
   total_phases: 10
-  completed_phases: 9
+  completed_phases: 10
   total_plans: 39
-  completed_plans: 38
+  completed_plans: 39
   percent: 100
 ---
 
@@ -90,6 +90,7 @@ Progress: [██████████] 100%
 | Phase 09-testing-qa P03 | 3min | 1 tasks | 1 files |
 | Phase 10-agent-capabilities P02 | 10m | 2 tasks | 9 files |
 | Phase 10-agent-capabilities P01 | 11min | 2 tasks | 16 files |
+| Phase 10-agent-capabilities P03 | 22min | 2 tasks | 10 files |
 
 ## Accumulated Context
 
@@ -217,6 +218,9 @@ Recent decisions affecting current work:
 - [Phase 10-agent-capabilities]: KB is per-tenant not per-agent — agent_id made nullable in kb_documents
 - [Phase 10-agent-capabilities]: Executor injects tenant_id/agent_id as strings after schema validation to avoid triggering schema rejections on LLM-provided args
 - [Phase 10-agent-capabilities]: Lazy import of ingest_document task in kb.py via _get_ingest_task() — avoids shared→orchestrator circular dependency at module load time
+- [Phase 10-agent-capabilities]: getAuthHeaders() exported from api.ts — multipart upload uses raw fetch to avoid Content-Type override; KB upload pattern reusable for future file endpoints
+- [Phase 10-agent-capabilities]: CirclePlay icon used instead of Youtube — Youtube icon not in lucide-react v1.0.1 installed in portal
+- [Phase 10-agent-capabilities]: Conditional refetchInterval in useKbDocuments — returns 5000ms while any doc is processing, false when all done; avoids constant polling
 
 ### Roadmap Evolution
 
@@ -232,6 +236,6 @@ None — all phases complete.
 
 ## Session Continuity
 
-Last session: 2026-03-26T15:11:45.381Z
-Stopped at: Completed 10-01: KB ingestion pipeline, text extractors, executor injection
+Last session: 2026-03-26T15:24:12.693Z
+Stopped at: Completed 10-03: Knowledge Base portal page, file upload, URL ingest, RBAC, i18n
 Resume file: None

.planning/phases/10-agent-capabilities/10-03-SUMMARY.md

@@ -0,0 +1,140 @@
+---
+phase: 10-agent-capabilities
+plan: 03
+subsystem: ui
+tags: [next.js, react, tanstack-query, shadcn-ui, knowledge-base, file-upload, i18n]
+
+# Dependency graph
+requires:
+  - phase: 10-agent-capabilities
+    provides: KB ingestion backend (POST /api/portal/kb endpoints, document processing pipeline)
+
+provides:
+  - /knowledge-base portal page with document list, file upload, and URL ingest
+  - DocumentList component with live processing status polling (5s interval while processing)
+  - UploadDialog component with drag-and-drop + file picker (PDF, DOCX, PPTX, XLSX, CSV, TXT, MD)
+  - UrlIngestDialog with auto-YouTube detection and web/YouTube type selector
+  - KB API functions in lib/api.ts: deleteKbDocument, reindexKbDocument, addKbUrl, uploadKbDocument
+  - TanStack Query hooks: useKbDocuments, useDeleteKbDocument, useReindexKbDocument, useAddKbUrl
+  - Knowledge Base nav item in sidebar (visible to all roles)
+  - RBAC: customer_operator view-only; upload/delete require customer_admin or platform_admin
+
+affects: [11-future-phases, agents-with-kb-tools]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns:
+    - Conditional refetchInterval in useQuery — polls only while any document has status=processing
+    - Raw fetch for multipart uploads — apiFetch always sets Content-Type: application/json; KB upload uses fetch directly with auth headers passed explicitly
+    - getAuthHeaders() exported from api.ts for use in raw fetch upload calls
+
+key-files:
+  created:
+    - 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
+  modified:
+    - packages/portal/lib/api.ts
+    - packages/portal/lib/queries.ts
+    - packages/portal/components/nav.tsx
+    - packages/portal/messages/en.json
+    - packages/portal/messages/es.json
+    - packages/portal/messages/pt.json
+
+key-decisions:
+  - "getAuthHeaders() exported from api.ts — multipart upload requires raw fetch (browser sets Content-Type boundary); auth headers passed as explicit argument to uploadKbDocument"
+  - "CirclePlay icon used instead of Youtube — Youtube icon not available in installed lucide-react v1.0.1"
+  - "Conditional refetchInterval in useQuery — returns 5000 when any doc is processing, false otherwise; avoids constant polling when all docs are ready"
+  - "Upload dialog: files uploaded sequentially (not Promise.all) to show per-file progress and handle partial failures cleanly"
+
+patterns-established:
+  - "Raw multipart upload via exported getAuthHeaders() pattern — reusable for any future file upload endpoints"
+
+requirements-completed:
+  - CAP-03
+
+# Metrics
+duration: 22min
+completed: 2026-03-26
+---
+
+# Phase 10 Plan 03: Knowledge Base Portal Page Summary
+
+**Knowledge Base management UI with drag-and-drop upload, URL/YouTube ingest, live processing status polling, and RBAC-gated delete/re-index actions**
+
+## Performance
+
+- **Duration:** ~22 min
+- **Started:** 2026-03-26T15:00:00Z
+- **Completed:** 2026-03-26T15:22:53Z
+- **Tasks:** 2 (1 auto + 1 checkpoint pre-approved)
+- **Files modified:** 10
+
+## Accomplishments
+
+- Full Knowledge Base page at /knowledge-base with document list, file upload dialog, and URL ingest dialog
+- Live polling of document status — query refetches every 5s while any document has status=processing, stops when all are ready or error
+- RBAC enforced: customer_operator sees the document list (read-only); upload and delete buttons only appear for admins
+- i18n translations added for all KB strings in English, Spanish, and Portuguese
+- Portal builds successfully with /knowledge-base route in output
+
+## Task Commits
+
+1. **Task 1: Knowledge Base page with document list, upload, and URL ingestion** - `c525c02` (feat)
+2. **Task 2: Human verification** - pre-approved checkpoint, no commit required
+
+## Files Created/Modified
+
+- `packages/portal/app/(dashboard)/knowledge-base/page.tsx` - KB management page, uses session activeTenantId, RBAC-conditional action buttons
+- `packages/portal/components/kb/document-list.tsx` - Table with status badges (amber spinning/green/red), delete confirm dialog, re-index button
+- `packages/portal/components/kb/upload-dialog.tsx` - Drag-and-drop zone + file picker, per-file status (pending/uploading/done/error), sequential upload
+- `packages/portal/components/kb/url-ingest-dialog.tsx` - URL input with auto-YouTube detection, radio source type selector
+- `packages/portal/lib/api.ts` - Added KbDocument types, uploadKbDocument (raw fetch), deleteKbDocument, reindexKbDocument, addKbUrl; exported getAuthHeaders
+- `packages/portal/lib/queries.ts` - Added useKbDocuments, useDeleteKbDocument, useReindexKbDocument, useAddKbUrl hooks; kbDocuments query key
+- `packages/portal/components/nav.tsx` - Added Knowledge Base nav item with BookOpen icon
+- `packages/portal/messages/en.json` - KB translations (nav.knowledgeBase + full kb.* namespace)
+- `packages/portal/messages/es.json` - Spanish KB translations
+- `packages/portal/messages/pt.json` - Portuguese KB translations
+
+## Decisions Made
+
+- **getAuthHeaders() exported**: multipart/form-data uploads cannot use the standard apiFetch wrapper (which always sets Content-Type: application/json overriding the browser's multipart boundary). Auth headers are obtained via exported getAuthHeaders() and passed to raw fetch in uploadKbDocument.
+- **CirclePlay instead of Youtube icon**: lucide-react v1.0.1 does not export a `Youtube` icon. Used CirclePlay (red) as YouTube visual indicator.
+- **Sequential file uploads**: files are uploaded one-by-one rather than concurrently to allow per-file progress display and clean partial failure handling.
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 1 - Bug] Youtube icon not available in lucide-react v1.0.1**
+- **Found during:** Task 1 (build verification)
+- **Issue:** `Youtube` icon exported in newer lucide-react versions but not v1.0.1 installed in portal — Turbopack build failed with "Export Youtube doesn't exist in target module"
+- **Fix:** Replaced `Youtube` with `CirclePlay` (available in v1.0.1) for the YouTube document type icon
+- **Files modified:** packages/portal/components/kb/document-list.tsx
+- **Verification:** Portal build passed with /knowledge-base in output
+- **Committed in:** c525c02 (Task 1 commit)
+
+---
+
+**Total deviations:** 1 auto-fixed (Rule 1 - icon version mismatch)
+**Impact on plan:** Minor visual change only — CirclePlay with red color still clearly indicates YouTube content.
+
+## Issues Encountered
+
+None beyond the icon version fix above.
+
+## User Setup Required
+
+None - no external service configuration required. KB backend was set up in Plan 10-01.
+
+## Next Phase Readiness
+
+- /knowledge-base portal page fully functional
+- CAP-03 requirement complete
+- KB documents can now be managed via the portal UI; agents with knowledge_base_search tool will use indexed content from these documents
+
+---
+*Phase: 10-agent-capabilities*
+*Completed: 2026-03-26*