Developer docs Guides

Knowledge bases

A Markdown-native knowledge base your team reads and writes: OKF concepts with types, links, and citations — queryable from any script.

What a knowledge base is

A knowledge-base workspace stores the project’s living documentation as OKF (Open Knowledge Format) concepts — plain Markdown files with YAML frontmatter, one idea per file. A playbook, a business rule, an excerpt from a policy PDF: anything the team should remember becomes a concept.

Concept format

Frontmatter carries type, title, description, and tags. Wiki-style links connect related concepts, and an optional # Citations section tracks sources:

---
type: Business Rule
title: Refunds need a second approval
description: When a refund requires a second sign-off.
tags: [payments, policy]
---

Refunds over 500 USD park in pending_approval until a
second reviewer signs off.

Related: [Approval gates](approval-gates.md)

# Citations
- payments-policy.pdf, page 12

Concept types

Type	Use for
Source Document	A whole external document, kept as reference
Source Section	An excerpt or section of a source
Topic	A subject the team maintains understanding around
Playbook	A step-by-step procedure the team repeats
Business Rule	A policy or invariant decisions must respect
Query Analysis	An analyzed question with findings

Documents convert themselves

Upload a PDF, Word, PowerPoint, Excel, OpenDocument, RTF, ePub, or CSV file to a knowledge-base workspace and it converts to Markdown automatically — encrypted or malformed files are rejected with a clear error. Markdown and plain-text files are stored as-is.

Search and lint from scripts

The okf object in the workflow module queries the project’s knowledge-base workspace. Pass workspace_id to target a different one:

hits = okf.search("refund policy")   # concept summaries
for h in hits:
    print(h["title"], "-", h.get("description", ""))

issues = okf.lint()                  # health report
for i in issues:
    print(i["issue_type"], i["concept_id"], i["message"])

Health checks

lint() reports four kinds of issues: broken wiki links, orphan concepts nothing links to, concepts missing a type or citations, and duplicate titles. Run it after bulk edits to keep the base trustworthy.