# Knowledge bases

A knowledge base holds **entries**, and an entry is Markdown you write — from
the CLI or in the inbox. Vatio does not read websites: if the answer lives on a
page, put what the agent needs in an entry.

```bash
vatio kb create docs
vatio kb write docs horarios horarios.md
vatio kb show docs
vatio kb publish docs                      # take what you wrote live
```

Create one base per set of entries you want kept apart.

Reference the base on the agent that reads it, and give it `knowledge_lookup`:

```yaml
agent:
  instructions: |
    Search knowledge_lookup before answering questions about Acme's policies.
    If the results do not answer the question, say so.
  tools: [knowledge_lookup]
  knowledge: [docs]
```

Run `vatio push` after changing these references. A referenced base must
already exist — a misspelled name fails the push rather than quietly becoming
an empty base. Removing a reference does not delete its content.

## Entries

```bash
vatio kb write docs refunds refunds.md   # creates it, or replaces what is there
vatio kb cat docs refunds                # exactly what Vatio holds
vatio kb cat docs refunds | edit | vatio kb write docs refunds
```

`vatio kb write BASE ENTRY [FILE]` puts Markdown under a name, reading stdin
when no file is given. The entry's title comes from its own `# heading`.
Headings divide an entry into searchable sections; write each one so it can
answer a question on its own.

Use `vatio kb show docs` to check which entries are ready to answer from.
Indexing is asynchronous: an entry shows as ready once its sections have been
embedded. Test retrieval in a conversation afterwards.

`vatio kb rm-entry BASE ENTRY` deletes one entry. `vatio kb rm BASE` deletes a
base only when no deployed agent references it.

## Preview and live

The entries are what **live** answers from. An edit in the inbox changes live
directly, and every change is kept as a numbered version of its entry, with who
made it and from where. The inbox is where supervisors and developers edit
entries and upload a file into an entry; the CLI does all of it too.

**Preview** keeps its own changes on top of live and reads everything else
from it. `vatio kb write`, `cat`, `rm-entry`, `show` and `status` work in
preview, so a change is written there, tried there, and goes live when preview
does:

```bash
vatio kb write docs horarios horarios.md   # only preview answers with it
vatio kb status docs                       # what live does not have yet
vatio publish                              # the agent and these entries, together
```

`vatio kb publish docs` takes one base's changes live on their own, without
the agent. `--env live` reads and writes live directly.

### Conflicts

When live changes an entry after preview changed it too — a supervisor fixed
it in the inbox, say — publishing preview would overwrite a change nobody
working on preview has read. So it is refused, and `vatio kb status` names the
entry. Read it from live, write your change on top, and the conflict clears:

```bash
vatio kb cat docs horarios --env live > horarios.md
$EDITOR horarios.md
vatio kb write docs horarios horarios.md
```

Or resolve it side by side in the inbox: under **Test**, preview has a page
with the diff of every entry it changed (`vatio env` prints its link). For a conflict it shows
what live changed and what preview changed, and offers three ways out: keep
preview's version on top of live, take live's, or combine both by hand.

### History

`vatio kb history docs` lists every version that reached live, newest first.
Going back is writing an old version again, which becomes the newest:

```bash
vatio kb cat docs horarios --version 3 > horarios.md
vatio kb write docs horarios horarios.md --env live
```

The inbox does this with one button on the entry's history.