# Knowledge Bases

The **Knowledge Base** (KB) is the RAG system: upload documents → chunk
→ embed (pgvector / app-level cosine for SQLite) → search via
`kb_search` tool during completions.

### KB CRUD

```
GET    /knowledge-bases             → { "data": [KB objects] }
POST   /knowledge-bases             ← { "name", "description", "scope", "team_id" }
GET    /knowledge-bases/:id         → KB object
PUT    /knowledge-bases/:id         ← partial update
DELETE /knowledge-bases/:id
```

KB object:

```json
{
  "id": "uuid",
  "name": "Product Docs",
  "description": "Internal product documentation",
  "scope": "personal|team|global",
  "owner_id": "uuid|null",
  "team_id": "uuid|null",
  "discoverable": true,
  "embedding_model": "text-embedding-3-small",
  "chunk_size": 512,
  "chunk_overlap": 50,
  "document_count": 12,
  "created_at": "...",
  "updated_at": "..."
}
```

### Documents

**Upload:**

```
POST /knowledge-bases/:id/documents
Content-Type: multipart/form-data
```

Field: `file`. Supported: PDF, DOCX, TXT, MD, HTML, CSV, XLSX, PPTX.
Returns the document object with `status: "pending"`.

**List:**

```
GET /knowledge-bases/:id/documents
```

Returns `{ "data": [document objects] }`.

**Status** (poll during processing):

```
GET /knowledge-bases/:id/documents/:docId/status
```

Status progression: `pending → chunking → embedding → ready | error`.

**Delete:**

```
DELETE /knowledge-bases/:id/documents/:docId
```

### Search

```
POST /knowledge-bases/:id/search
```

```json
{
  "query": "How do I configure SSO?",
  "limit": 5
}
```

Returns `{ "results": [{ "content", "score", "document_id", "metadata" }] }`.

### Rebuild

Re-chunks and re-embeds all documents:

```
POST /knowledge-bases/:id/rebuild
```

### Channel KB Bindings

A channel can have KBs explicitly bound to it (in addition to any KBs
coming from the active Persona or parent Project).

**Get:**

```
GET /channels/:id/knowledge-bases
```

Returns `{ "data": [ChannelKB objects] }`:

```json
{
  "kb_id": "uuid",
  "kb_name": "Product Docs",
  "enabled": true,
  "document_count": 12
}
```

**Set** (replace all):

```
PUT /channels/:id/knowledge-bases
```

```json
{ "kb_ids": ["kb-uuid-1", "kb-uuid-2"] }
```

### Discoverable KBs

The `discoverable` flag controls whether a KB appears in the user's KB
picker. Non-discoverable KBs are hidden from direct access but still
searchable through Persona bindings (enterprise KB mode).

**List discoverable** (for KB picker UI):

```
GET /knowledge-bases-discoverable
```

Returns `{ "data": [KB objects] }` — only KBs the user can see
(personal + team + discoverable global).

**Toggle discoverability** (admin-enforced in handler):

```
PUT /knowledge-bases/:id/discoverable
```

```json
{ "discoverable": false }
```

### KB Resolution Chain

When a completion fires, KBs are resolved in priority order:

```
Persona KBs → Project KBs → Channel KBs → Personal KBs
```

The `BuildKBHint` function assembles all applicable KBs into the
system prompt, and the `kb_search` tool searches across all of them.

### Persona KB Bindings

See §4.4. Persona-KB binding is the primary enterprise mechanism for
controlled KB access.

---