# Documentation

## Getting it running

- **[install-ubuntu-desktop.md](install-ubuntu-desktop.md)** — start to finish on a clean
  machine. Read this one first.
- **[deployment/](deployment/README.md)** — compose files for the three services that live
  outside this repo: Ollama, Open WebUI and Gitea.
- **[open-webui.md](open-webui.md)** — registering the tool server and configuring the model.

## Using and tuning it

- **[configuration.md](configuration.md)** — every file in `configs/`, every setting.
- **[tools.md](tools.md)** — all 22 tools, what each needs, and how to switch one off.
- **[advanced-params.md](advanced-params.md)** — recommended parameters for both models, and
  the three timeouts that must agree.
- **[filters.md](filters.md)** — the five optional Open WebUI plugins.
- **[verifying.md](verifying.md)** — `./verify.py`: what is set up, what is switched off,
  and what is broken.
- **[operating.md](operating.md)** — logs, rate limits, the cache, restarting things
  safely, known constraints and a troubleshooting table.
- **[../logs/](../logs/README.md)** — every component writes its own log file there; one
  page saying which is which.
- **[setup/](setup/)** — one short page per tool that needs anything beyond
  `docker compose up`:
  [searxng](setup/searxng.md) ·
  [octave](setup/octave.md) ·
  [vm-agent](setup/vm-agent.md) ·
  [gitea](setup/gitea.md) ·
  [contact](setup/contact.md) ·
  [github-token](setup/github-token.md) ·
  [stackexchange](setup/stackexchange.md) ·
  [nvd](setup/nvd.md)

## The VM sub-agent

- **[vm-agent/overview.md](vm-agent/overview.md)** — what it is and how the isolation works.
- **[setup/vm-agent.md](setup/vm-agent.md)** — the setup checklist.
- **[vm-agent/base-images.md](vm-agent/base-images.md)** — installation media, building a
  base image, and what "frozen" means.
- **[vm-agent/troubleshooting.md](vm-agent/troubleshooting.md)** — including how to find out
  what a session actually did.

## Why it is the way it is

- **[TUNING.md](TUNING.md)** — the change log. Every entry is one change: what it was meant
  to fix, and what measurably happened afterwards. It is long, and it is the most useful
  document here if you intend to modify anything.
- **[testing/](testing/README.md)** — the corpus those measurements came from: forty graded
  prompts with rubrics, transcripts and scores.