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.)