Formats#
AI Generated, Human Reviewed at: 2026-11-16T19:43:09Z
Bowerbird is not tied to one way of keeping knowledge. A kbmcp.yaml at the root of a folder says what the folder
holds, with one line:
format: markdown # markdown | adr | okf | skos | asciidoc | seal-only
All six share the same ideas: the folder is a git repository, kbmcp.yaml is committed with it, and a human's
review is recorded against the exact bytes they reviewed (see Sealing).
seal is what guarantees a person was in the loop, for stored knowledge and for decisions alike. Renaming a file with
move keeps its seal when its text is unchanged.
Each format exists for a reason. Pick whichever fits what you keep; you can change your mind later (see Changing your mind).
- Choose Markdown if you have notes, runbooks or docs, want to ask questions of them and know which a person has checked.
- Choose ADR if you record decisions and want a person's review to be what makes one accepted.
- Choose OKF if your knowledge needs sources, trust and freshness, kept by people and agents, and you want every tool.
- Choose SKOS if you keep a controlled vocabulary: a glossary, taxonomy or thesaurus.
- Choose AsciiDoc if your manuals and guides are written in AsciiDoc.
- Choose Seal-only if you need a guaranteed human review of code, configuration or any text files, and no search.
Changing your mind#
Change the format line and run kb reindex; nothing else moves. Reviews are not converted between formats: an OKF
concept keeps its verified entries in its own frontmatter, while the other formats keep theirs in
.waxseals.yaml, so after a switch the notes may need sealing again.
Tools by format#
Which tools a server offers, by role. The role is what roles: in kbmcp.yaml turns on (all five are on by default;
--role or KB_ROLE picks one for a single server). Naming a role that is off refuses to start.
✓ a server offers it. CLI command line only (written for OKF files, so not offered outside OKF). — nothing to act on (seal-only indexes nothing).
seal#
| Markdown | ADR | OKF | SKOS | AsciiDoc | Seal-only | |
|---|---|---|---|---|---|---|
seal |
✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
read#
| Markdown | ADR | OKF | SKOS | AsciiDoc | Seal-only | |
|---|---|---|---|---|---|---|
dirs |
✓ | ✓ | ✓ | CLI | CLI | CLI |
get |
✓ | ✓ | ✓ | CLI | CLI | CLI |
heatmap |
✓ | ✓ | ✓ | CLI | ✓ | CLI |
links |
✓ | ✓ | ✓ | CLI | CLI | CLI |
list |
✓ | ✓ | ✓ | CLI | CLI | CLI |
log |
CLI | CLI | ✓ | CLI | CLI | CLI |
passages |
✓ | ✓ | ✓ | ✓ | ✓ | — |
search |
✓ | ✓ | ✓ | CLI | CLI | — |
status |
✓ | ✓ | ✓ | CLI | CLI | CLI |
vocab |
CLI | CLI | ✓ | CLI | CLI | CLI |
write#
| Markdown | ADR | OKF | SKOS | AsciiDoc | Seal-only | |
|---|---|---|---|---|---|---|
cite |
CLI | CLI | ✓ | CLI | CLI | CLI |
create |
CLI | CLI | ✓ | CLI | CLI | CLI |
fix |
CLI | CLI | ✓ | CLI | CLI | CLI |
lint |
CLI | CLI | ✓ | CLI | CLI | CLI |
record |
CLI | CLI | ✓ | CLI | CLI | CLI |
set |
CLI | CLI | ✓ | CLI | CLI | CLI |
structure#
| Markdown | ADR | OKF | SKOS | AsciiDoc | Seal-only | |
|---|---|---|---|---|---|---|
archive |
CLI | CLI | ✓ | CLI | CLI | CLI |
bundles |
CLI | CLI | ✓ | CLI | CLI | CLI |
dirs |
✓ | ✓ | ✓ | CLI | CLI | CLI |
ingest |
CLI | CLI | ✓ | CLI | CLI | CLI |
migrate |
CLI | CLI | ✓ | CLI | CLI | CLI |
move |
CLI | ✓ | ✓ | CLI | CLI | CLI |
rename |
CLI | CLI | ✓ | CLI | CLI | CLI |
split |
CLI | CLI | ✓ | CLI | CLI | CLI |
unarchive |
CLI | CLI | ✓ | CLI | CLI | CLI |
web |
CLI | CLI | ✓ | CLI | CLI | CLI |
lifecycle#
| Markdown | ADR | OKF | SKOS | AsciiDoc | Seal-only | |
|---|---|---|---|---|---|---|
baseline |
CLI | CLI | ✓ | CLI | CLI | CLI |
config |
✓ | ✓ | ✓ | CLI | CLI | CLI |
index |
CLI | CLI | ✓ | CLI | CLI | CLI |
init |
✓ | ✓ | ✓ | CLI | CLI | CLI |
provenance |
CLI | CLI | ✓ | CLI | CLI | CLI |
recheck_apply |
CLI | CLI | ✓ | CLI | CLI | CLI |
recheck_plan |
CLI | CLI | ✓ | CLI | CLI | CLI |
reindex |
✓ | ✓ | ✓ | ✓ | ✓ | — |
upgrade |
CLI | CLI | ✓ | CLI | CLI | CLI |
| Markdown | ADR | OKF | SKOS | AsciiDoc | Seal-only | |
|---|---|---|---|---|---|---|
| Tools offered | 12 | 13 | 35 | 3 | 4 | 1 |
(dirs sits in both read and structure, so it counts once. The 35 are all of Tools.)