feat: add kb specs

specs/DESIGN.md

@@ -10,7 +10,8 @@ specs/designs/
 ├── 01-data/           — external data sources (Git, Kubernetes)
 ├── 10-layout/         — overall UI designs
 ├── 11-models/         — model page designs
-└── 12-tools/          — tool page designs
+├── 12-tools/          — tool page designs
+└── 13-kbs/            — knowledge base page designs
 ```
 
 ---

specs/designs/13-kbs/detail.md

@@ -0,0 +1,60 @@
+# Knowledge Base Detail Page
+
+## Overview
+
+Single knowledge base detail view.
+
+Follows the layout of `specs/designs/10-layout/detail.md`, only the details are documented in this spec.
+
+## Page Name
+
+"{kb.name}" for title and breadcrumb
+
+## Page Header (always shown)
+
+```
+[Icon] KB Name                          [status badge] [Edit] [⋮]
+```
+
+- Icon: KB icon
+- KB name (primary)
+- Status badge (right, when `kb.status` is set)
+- Edit button: navigates to the edit page
+- ⋮ menu: includes Delete and a context action (`Test` for deployed KBs, `Deploy` otherwise)
+
+## Config Panel
+
+Always shown.
+
+- embedding model link (when set)
+- reranker model link (when set)
+
+## Documents Panel
+
+Always shown. Includes document search, upload action, and a document table.
+
+Table columns:
+
+- Name
+- Size
+- Type
+- Status — status badge
+- Actions: Download, Delete
+
+When the document list is empty, a single centered row reads `No documents`.
+
+## Deployment Panel
+
+Shows deployment/runtime configuration when present:
+
+- Deployment
+- Ingestion
+- Egestion
+
+## Management Tabs
+
+Always shown.
+
+## Delete Confirmation Dialog
+
+Destructive confirmation. On success, returns to the knowledge bases list.

specs/designs/13-kbs/domain.md

@@ -0,0 +1,55 @@
+# Knowledge Base Domain
+
+Knowledge bases are either external endpoints or managed deployments.
+
+## Core Fields
+
+All knowledge bases share these core fields:
+
+- identity: id, name
+- presentation: icon, description, tags
+- classification: mode
+- content: documents
+- placement: stack
+
+## KB Document
+
+Each document includes:
+
+- identity and relation: id, kb
+- presentation: name, description, tags
+- file metadata: type, sizeBytes, source
+- chunking configuration: chunking
+- optional indexing status
+
+## Document Types
+
+Supported document types:
+
+- text
+- markdown
+- html
+- pdf
+- docx
+
+## External Knowledge Base
+
+External knowledge bases include:
+
+- mode: external
+- optional availability status
+
+## Managed Knowledge Base
+
+Managed knowledge bases include:
+
+- optional embedding model reference
+- optional reranker model reference
+- runtime template
+- optional ingestion runtime template
+- optional egestion runtime template
+- optional deployment status
+
+## Knowledge Base Union
+
+- KnowledgeBase = ManagedKB | ExternalKB

specs/designs/13-kbs/form.md

@@ -0,0 +1,43 @@
+# Knowledge Base Form Page
+
+## Overview
+
+Shared `<KBForm>` handles both create and edit.
+
+Follows the form layout in `specs/designs/10-layout/form.md`, only the details are documented in this spec.
+
+## Form Layout
+
+Basic Information → Configuration → Deployment
+
+## Panels
+
+### Basic Information
+
+Beyond the standard Icon + Name fields described in the layout spec:
+
+- **Icon**
+- **Name**
+- **Description**
+- **Mode**: `Managed` (external option is present but disabled)
+- **Tags**: optional list input
+
+### Configuration
+
+- **Embedding Model** selector
+- **Reranker Model** selector
+- Optional **Ingestion Job** runtime settings
+- Optional **Egestion Job** runtime settings
+
+### Deployment
+
+- Optional container/runtime settings
+
+## Validation
+
+- Name is required
+
+## Breadcrumb
+
+- Create: `Knowledge Bases / [New Knowledge Base]`
+- Edit: `Knowledge Bases / Edit [{kb.name}]`

specs/designs/13-kbs/list.md

@@ -0,0 +1,74 @@
+# Knowledge Bases List Page
+
+## Overview
+
+Card grid list of all knowledge bases.
+
+Follows the layout of `specs/designs/10-layout/list.md`, only the details are documented in this spec.
+
+## Page Name
+
+"Knowledge Bases" for title and breadcrumb
+
+## Filters
+
+| Row  | Mode   | Values                          | Default | Extra                         |
+| ---- | ------ | ------------------------------- | ------- | ----------------------------- |
+| Mode | Single | All, External, Managed          | All     | shows count badge             |
+| Tags | Multi  | the tags present across all KBs | None    | row hidden when no tags exist |
+
+## Card Anatomy
+
+Cards are taller than the model and tool cards (256 px) to leave room for a documents preview.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ [icon]  KB Name                                  [status]   │
+│                                                             │
+│ Description text, clamped to three lines…                   │
+│                                                             │
+│ [tag] [tag]                                                 │
+│                                                             │
+│  📄 doc-one.pdf         📄 doc-two.md                       │
+│  📄 doc-three.txt       📄 doc-four.pdf                     │
+│  📄 doc-five.md         📄 +N more                          │
+└─────────────────────────────────────────────────────────────┘
+```
+
+The card is clickable as a whole and links to `/workloads/kbs/[id]`. When `onselect` is provided (e.g. inside a KB picker), the card renders as a button instead and calls the handler on click / Enter.
+
+### Header
+
+- Small icon (size 36)
+- KB name (line-clamp-2 if long)
+- Status badge (right, when set)
+
+### Body
+
+- Description, clamped to three lines
+
+### Tags
+
+- tag chips (only rendered when there are tags)
+
+### Documents Preview
+
+2-column grid in the footer, up to 5 documents listed with a `FileIcon`. Any further documents collapse into a `+N more` item.
+
+## Empty States
+
+**No knowledge bases at all:**
+
+```
+DatabaseIcon (muted)
+"No knowledge bases yet."
+[New Knowledge Base button]
+```
+
+**No match:**
+
+```
+DatabaseIcon (muted)
+"No knowledge bases match your filters."
+[Clear filters link]
+```

specs/designs/13-kbs/testing.md

@@ -0,0 +1,85 @@
+# Knowledge Base Test Page
+
+## Overview
+
+A sandbox for testing knowledge base retrieval by selecting a KB, running a query, and inspecting returned chunks.
+
+## Route
+
+`/utilities/testing/kb`
+
+Optional query parameter `?kb=<kbId>` pre-selects the KB on load (used when navigating from a KB's detail page).
+
+## Page Name
+
+"Retrieval" for title and breadcrumb
+
+## Page Layout
+
+```
+[Retrieval]                          (page title / breadcrumb)
+
+┌─────────────────────────────────────────────────────────────┐
+│  Knowledge Base                                             │
+│  [Selected KB button]                  [Select KB]          │
+└─────────────────────────────────────────────────────────────┘
+
+ (no selection)          (KB selected)
+┌──────────────┐         ┌──────────────────────────────────────┐
+│  Select a    │   →     │  Query panel                         │
+│  KB above    │         │                                      │
+└──────────────┘         └──────────────────────────────────────┘
+```
+
+## KB Selector
+
+The selected KB is shown in the top selector button (icon + name). If no KB is selected, the page shows a placeholder prompt to select one.
+
+## Query Panel
+
+Sends a query to the test endpoint and displays returned chunks ranked by relevance.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Query                                                      │
+│                                                             │
+│  ┌───────────────────────────────────────────────────────┐  │
+│  │  Enter your query…  (textarea, min 3 rows)            │  │
+│  └───────────────────────────────────────────────────────┘  │
+│                                                             │
+│  ▸ Parameters  (collapsible)                                 │
+│     Top K      [  5  ]                                       │
+│     Threshold  [ 0.7 ]                                      │
+│                                                [Query →]    │
+│                                                             │
+│  Result                                                     │
+│  ┌───────────────────────────────────────────────────────┐  │
+│  │  Chunks: 4   Latency: 87 ms                           │  │
+│  │  ┌─────────────────────────────────────────────────┐  │  │
+│  │  │  #1  [0.94]  doc-id                             │  │  │
+│  │  │       "The quick brown fox…"                    │  │  │
+│  │  ├─────────────────────────────────────────────────┤  │  │
+│  │  │  #2  [0.81]  doc-id                             │  │  │
+│  │  │       "Lorem ipsum dolor…"                      │  │  │
+│  │  ├─────────────────────────────────────────────────┤  │  │
+│  │  │  #3  [0.67]  doc-id                             │  │  │
+│  │  │       "Sit amet consectetur…"                   │  │  │
+│  │  └─────────────────────────────────────────────────┘  │  │
+│  └───────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+Behavior:
+
+- Query is disabled when the query text is empty.
+- Top K and threshold are editable query parameters.
+- Results show latency and chunk count.
+- Each chunk shows rank, score, document id, and content.
+- If there are no chunks, the result shows `No results`.
+- Request errors are shown inline.
+
+## API Behavior
+
+### `POST /api/workspaces/[workspaceId]/kbs/[id]/test`
+
+Runs retrieval against the selected KB and returns ranked chunks with latency. If the KB endpoint is unavailable or the request fails, an error is returned.