> ## Documentation Index
> Fetch the complete documentation index at: https://agents.concierca.ch/llms.txt
> Use this file to discover all available pages before exploring further.

# Knowledge

> Knowledge base search, read, save, edit, and archive.

The **knowledge base** holds durable, higher-stakes entries (importance ≥ 5): SOPs, canonical facts, governance rules. Entries have a title, intro, markdown body, category, importance (5–10), tags and a scope layer (`user` | `department` | `global` | `provider`).

**Routing rule:** use `knowledge_search` for conceptual "what do we know about…" questions. For exact numbers, counts, prices or filtered records use `data_query` — never infer a number from semantic search.

**Governance model for shared writes:** a Company-Admin writes shared (global/department) entries directly, and so does a member of the named department (audited, status `saved`). Any other shared write becomes a **governance candidate** (status `pending_governance`) that an authorized human promotes in the app. `scope=provider` (white-label layer shared across the provider's companies) requires Provider-Admin.

***

## `knowledge_search`

Semantic recall over the knowledge base (title/intro free-text + category filter). Returns lean rows; fetch full content with `knowledge_get`.

| Name               | Type    | Required | Description                                                                           |
| ------------------ | ------- | -------- | ------------------------------------------------------------------------------------- |
| `search`           | string  | no       | Free-text term, case-insensitive over title/intro                                     |
| `category`         | string  | no       | Exact category filter                                                                 |
| `limit`            | number  | no       | Max rows (default 25, max 200)                                                        |
| `include_archived` | boolean | no       | Include soft-archived entries (default false) — the only path to see archived entries |

**Returns:** `{ knowledge: [...], count }`. Each row: `id, title, intro, category, category_id, scope, importance, tags, department_id, source, created_at, updated_at, valid_at, invalid_at, source_type, retrieval_class` (no body). By default only currently-valid, non-archived entries are returned.

**Permissions:** read; rights-filtered per user (private user-layer entries of others are never returned; admins see all).

```json theme={null}
{ "method": "tools/call", "params": { "name": "knowledge_search", "arguments": { "search": "refund policy", "limit": 10 } } }
```

## `knowledge_get`

One knowledge entry **with full content** — only if readable for this user.

| Name | Type   | Required | Description          |
| ---- | ------ | -------- | -------------------- |
| `id` | string | yes      | Knowledge entry uuid |

**Returns:** `{ knowledge }` — the full entry: all search columns plus `content` (the markdown body), `supersedes, source_id, source_uri, failure_count, consolidated_at`. Not readable/found → `{ error: "Knowledge entry not found" }`.

**Permissions:** read; rights-filtered.

```json theme={null}
{ "method": "tools/call", "params": { "name": "knowledge_get", "arguments": { "id": "<uuid>" } } }
```

## `knowledge_save`

Create a knowledge entry (durable, importance ≥ 5 — lower-stakes notes belong in `memory_save`). `scope=user` writes directly to **your private layer** (colleagues never see it; admins do). Shared scopes follow the governance model above.

| Name            | Type      | Required             | Description                                                                    |
| --------------- | --------- | -------------------- | ------------------------------------------------------------------------------ |
| `title`         | string    | yes                  | Entry title                                                                    |
| `body_markdown` | string    | yes                  | The entry's content body                                                       |
| `intro`         | string    | no                   | Short summary for lists/search                                                 |
| `importance`    | number    | no                   | ≥ 5 (default 5, max 10)                                                        |
| `tags`          | string\[] | no                   | Topic tags                                                                     |
| `category`      | string    | no                   | Must be a listed knowledge category (see `category_list {entity:"knowledge"}`) |
| `scope`         | string    | no                   | `user` \| `department` \| `global` (default) \| `provider`                     |
| `department`    | string    | no                   | Free-text label — kept on a governance candidate only                          |
| `department_id` | string    | for department scope | Being a member of it makes the write direct instead of a governance candidate  |

**Returns:** direct write → `{ status:"saved", layer, knowledge_id, audit }` (`layer` is the resolved scope; `audit` records actor/version). Governance-routed shared write → `{ status:"pending_governance", candidate_id, note, audit }` (no row yet — a human promotes it in the app).

**Permissions:** write; role/scope rules as above.

```json theme={null}
{ "method": "tools/call", "params": { "name": "knowledge_save", "arguments": {
  "title": "Refund policy 2026",
  "intro": "How refunds are approved and booked.",
  "body_markdown": "## Policy\n...",
  "category": "operations",
  "scope": "global"
} } }
```

## `knowledge_update`

Edit an existing entry **in place by id** (the by-id counterpart to `knowledge_save`, which creates). Patchable: title, intro, body\_markdown, importance, tags, category. The pre-edit state is snapshotted to the governance history (versioned, revertible) and the row's version is bumped under an optimistic lock.

| Name                              | Type      | Required | Description            |
| --------------------------------- | --------- | -------- | ---------------------- |
| `id`                              | string    | yes      | Knowledge uuid to edit |
| `title`, `intro`, `body_markdown` | string    | no       | Content fields         |
| `importance`                      | number    | no       | Importance             |
| `tags`                            | string\[] | no       | Tags                   |
| `category`                        | string    | no       | Category               |

**Returns:** `{ status:"updated", id, version, updated, note, audit }` — `version` is the bumped row version, `updated` lists the patched field names. A concurrent edit returns `{ error: "Edit conflict …" }`.

**Permissions:** write; **Company-Admin only** (the knowledge base is always shared).

```json theme={null}
{ "method": "tools/call", "params": { "name": "knowledge_update", "arguments": {
  "id": "<uuid>", "importance": 8, "body_markdown": "## Policy (updated)\n..."
} } }
```

## `knowledge_archive`

Archive an entry (soft + reversible) — hides it from `knowledge_search` and `data_query` without deleting; pass `unarchive:true` to restore. The pre-archive state is snapshotted.

| Name        | Type    | Required | Description               |
| ----------- | ------- | -------- | ------------------------- |
| `id`        | string  | yes      | Knowledge uuid            |
| `unarchive` | boolean | no       | Restore an archived entry |

**Returns:** `{ status:"archived"|"unarchived", id, archived_at, note, audit }` — `archived_at` is the new timestamp (or `null` on unarchive). The pre-toggle state is snapshotted.

**Permissions:** write; **Company-Admin only**.

```json theme={null}
{ "method": "tools/call", "params": { "name": "knowledge_archive", "arguments": { "id": "<uuid>" } } }
```