Development

Layout

Skills

A skill is a doc under skills/ plus a [[skill]] entry in skills.toml with its id, tag, name and description. The tag groups it and selects it for the models whose tags list it. Docs refer to each other as <skill id> (<FILE>.md), which resolves both in the repo and in Open WebUI.

Templates — a doc whose entry sets template = true is rendered with Jinja before publishing, with the variables from [openwebui] of secrets.toml (reference Open WebUI). Docs without it are published verbatim, since e.g. CARDS.md quotes Anki’s own double-brace field syntax. skills.toml itself is always a template, which keeps deployment values such as the base model out of the repo.

Models — a [[model]] entry creates or updates one workspace model:

[[model]]
id = "kioku"
name = "Kioku"
base_model = "{{ base_model }}"
system = """..."""
tags = ["kioku", "diagrams"]
tools = ["server:mcp:kioku"]
terminal = true
disable_builtin = ["notes"]

Name, base model, description and system prompt are overwritten on every publish; tools, skills and filters are merged into what the model already has.

Tests

nix flake check boots a NixOS VM with real anki-sync-server and trilium-server instances and exercises every write path, backup restore, the full-sync policy, Trilium revisions and attachments, files by reference (sandbox paths, uploads, path escapes), auth and restarts. Forgejo Actions runs it on every push and pull request (.forgejo/workflows/ci.yml); there is no need to run it locally. The VM needs KVM, so the runner passes /dev/kvm to job containers. A push or pull request whose commits are all docs:, chore: or style: skips the test, unless one of them touches src/, nix/, flake.nix, flake.lock or pyproject.toml.

Deployment

The nixos repo pins this flake and runs the server from it. After pushing here, update the pin in the nixos repo, then rebuild the server there; rebuild desktop and laptop too when kioku-client.nix changed:

nix flake update kioku

publish-skills runs from a checkout of this repo, not from the deployment: rerun it after changing a doc or skills.toml (reference Open WebUI).

Anki version — the pin follows the nixos repo’s anki-suite input, shared with anki-sync-server (reference Server). Neither moves on a general nix flake update. Move them only deliberately, and run the VM test against the new pin before deploying:

nix flake update anki-suite

Documentation

The docs compile with tern and its pandoc template, installed into .tern/ and pinned in .tern/config.toml. Two installs of the template give two profiles: docs/ and the top-level README.md, both into docs-html/. After changing .tern/config.toml, reinstall:

nix develop path:.#docs --command tern -u

Then compile:

nix develop path:.#docs --command tern