kb — Morphir Knowledge Base Assistant

Manages kb/, the Open Knowledge Format knowledge base. Bundles live under kb/bundles/, optionally grouped a level deeper. kb/AGENTS.md is the source of truth for the conventions; this skill automates the mechanical parts of following them.

The morphir kb command

Everything runs through the kb subcommand of the Morphir CLI. It takes the same subcommands, flags, defaults, JSON shapes and exit codes as the Scala kb tool from morphir-scala, so a playbook written against that tool runs here. Where the reference implementation was wrong it is corrected rather than reproduced — a filter you pass is a filter that applies, and --json means JSON.

morphir kb list

morphir kb check --verbose

Every command accepts --json. Progress output goes to stderr, so --json on stdout is clean and pipeable — prefer it when you need to consume the result rather than read it.

Full flag reference: → references/commands.md

Command	Does
list	Bundles and their concept counts; --bundle X lists that bundle's concepts
show --path /x.md	One document: frontmatter, outbound links, heading outline
search --query X	Search titles, descriptions, tags and paths; --body to include prose
check	Conformance and provenance findings; non-zero exit on errors
index	Builds the SQLite index; --status reports its freshness
refresh	Both kinds of derived state; narrow with refresh markdown / refresh db
query --sql	Read-only SQL over that index
sync …	Mirroring an upstream repository into a bundle — status, pull, push, diff
intent …	Intent lifecycle — new, list, show, the transition verbs, check
decision …	Decision Records — list, show
new-bundle	Scaffolds a bundle with index.md and log.md
add-concept	Scaffolds a concept and wires it into the index and log

When to use what

Adding content to an existing bundle. Run add-concept to create the file and wire it up, then write the body yourself. The scaffold deliberately leaves a TODO comment rather than plausible-looking prose.

→ references/authoring.md before writing the body.

Writing or reviewing prose. Every concept body is written in one of three registers, chosen by its type:. The style cards are tool-neutral and live at styles/; voice.md there applies to all registers and includes the banned-pattern list (no em-dashes, no AI filler), diagrams.md says when a Mermaid diagram or SVG should replace prose narration of a flow or structure, and altitude.md sizes documents to capability stories: one narrative-home Design Note per capability in flight, with every fine-grained concept reachable from it.

type:	Register	Card
Playbook, tutorial, orientation, guidance	article	styles/article.md
Design Note, Decision Record, Intent, synthesis	white-paper	styles/whitepaper.md
Reference, Specification Section, Glossary, Data Dictionary, version-pinned notes	reference	styles/reference.md

Delegate drafting to the kb-writer subagent and review to the kb-reviewer subagent (.claude/agents/kb-writer.md, kb-reviewer.md), naming the target file and register in the dispatch. Writing inline is fine for small edits; still apply the cards. Style applies to new and touched content only; do not sweep existing prose.

Creating a bundle. Run new-bundle, then add it to the Bundles table in kb/README.md and to the group's README.md if it is in a group. The command reminds you; it does not edit those files, because their wording is a judgement call.

Checking the knowledge base. Run check. It reports structural problems (missing type, broken links, unindexed concepts, frontmatter that does not parse) and provenance drift (commit-pinned sources whose reference checkout has moved on). Nothing here touches the network.

→ references/checks.md for the catalogue and how to fix each finding.

Searching and locating. search scans the markdown and is always current. For anything heavier — full-text search over bodies, "what links here", orphaned concepts, tag or provenance distributions — build the SQLite index once and query it.

morphir kb index

morphir kb search --query "entry point" --index

The index is derived state under .dev/kb/index.db, gitignored, and rebuilt from the markdown. It has no automatic invalidation — morphir kb index --status lists files changed since the last build.

Keeping derived state honest. morphir kb refresh does both halves in one pass: it rewrites index bullets that have drifted from their concept's description, then rebuilds the SQLite index if anything changed.

morphir kb refresh --dry-run

Narrow it when you only want one half — morphir kb refresh markdown or morphir kb refresh db, equivalently --no-db and --no-markdown. Reach for it after editing descriptions or adding concepts, and before relying on a query. --add-missing also appends entries for unindexed concepts, which is opt-in because it has to pick a section.

→ references/index-db.md for the schema, the views, and worked queries.

Managing intent. Features, enhancements and bugs are recorded as prose in the intent bundle, with a lifecycle whose obligations are enforced — most importantly, releasing requires linking the Capability it produced.

→ kb/CONTEXT.md for the vocabulary — states, kinds, and what each obliges; references/commands.md for flags.

Recording a decision. Architectural decisions are the knowledge base's third register, alongside Intent and Capability: past-tense, immutable, and superseded rather than edited. morphir kb decision list and morphir kb decision show read them; morphir kb check validates their supersession links.

→ references/decisions.md for the frontmatter, the checks and how to supersede one.

Mirroring an upstream repository. A bundle may declare a sync.yaml and carry upstream's own files rather than a paraphrase of them. Markdown lands as concepts with an injected, fenced block of kb-owned frontmatter; everything else lands as byte-identical assets. morphir kb sync push deletes exactly that fenced region, so what goes back upstream is what came from it.

morphir kb sync status

→ references/sync.md for the manifest, the lockfile and the state model.

Finding divergence in the content. check finds mechanical inconsistency. Contradictions between what two concepts assert — the thing that actually matters in a knowledge base — cannot be detected by a script.

→ references/divergence.md for that procedure.

Rules that the tooling assumes

• A bundle root is a directory whose index.md carries okf_version. That is how bundles are discovered.
• Only index.md and log.md are reserved. Every other .md file inside a bundle is a concept and needs type:. The reservation stops at a mirror boundary — inside a vendored subtree those names are upstream's own files.
• A grouping directory gets a README.md and never an index.md. README.md inside a bundle is an error.
• Sub-directory index.md files carry no frontmatter.
• Index bullets mirror the target concept's description. Changing one means changing the other.

Where the implementation lives

The morphir kb command is implemented in Rust, in the morphir-okf (format model and parsing) and morphir-kb (knowledge-base operations) crates under ecosystem/morphir-rust/crates/, wired into the CLI in crates/morphir. Develop and test it there with cargo test; this skill only documents the command surface.