Documentation
Reference pages by topic. Installation, quick start and the config reference are on the Install page; an example config with every option is in config.example.yaml.
| Scenario | When you need it |
|---|---|
| Notebook format (OKF) | what a notebook looks like on disk |
| Custom type presets | your notebooks need their own vocabulary of note types (ADR, Runbook, Incident…) |
| The dev-project preset | running a project: glossary, ADRs, specs, tickets, research, bugs |
| The personal-finance preset | household money with an agent as a financial assistant: accounts, debts, budget, goals, investments, reports |
| The agent-retros preset | retrospectives of agent work across projects: sessions, patterns, environment improvements |
| Several agents | Claude Code, opencode and others write to the same notebooks |
| Notebook and type lifecycle | an agent asks for a new notebook or type, a human decides |
| Notes and verification | writing, editing, etag conflicts, verified, stale_after |
| Adopting an existing bundle | you already have an OKF directory of notes |
| Network access and subnets | the server is not on localhost: LAN, Tailscale, reverse proxy |
| Review UI | a human reads and verifies notes and looks at diffs in the browser |
| Git publishing and backup | edit history, push to a private repository, doctor |
| Glossary | the project’s domain terms |
Core model
- Notebook: a directory
notebooks/<slug>/with Markdown notes and metadata in.okf/notebook.yaml. - Type: a kind of note (
Decision,Playbook…). Each type has a subdirectory, a set of frontmatter fields, required fields and an aging periodstale_after. - Preset: a ready-made set of types a notebook takes its vocabulary from at creation.
- Actor: who writes:
claude-code,opencode,external-harness(by token) orhuman(CLI and Review UI only). Identity and permissions come from the token alone; an agent does not choose them. - Creation policy (
off/proposal/direct): whether an agent may create notebooks and types by itself.