Skip to content

SCHEMA.md

Latest commit

 

History

History
81 lines (67 loc) · 3.57 KB

SCHEMA.md

File metadata and controls

81 lines (67 loc) · 3.57 KB
Raw
type doc
title Docs Bundle Schema
description OKF conventions specific to the docs/ bundle: page types, tag taxonomy, and frontmatter requirements.
tags
architecture
created 2026-07-08
updated 2026-07-08

Docs Bundle Schema

docs/ is an independent OKF v0.1 bundle (see SPEC.md for the normative, bundle-agnostic spec this file layers repo-specific convention on top of). It carries docs/index.md as its bundle-root catalog (okf_version: "0.1" frontmatter) and one index.md per topic folder. Wiki-directory-level concerns (the wiki/ symlink layer, cross-bundle wiki/index.md, why koan doesn't rely on the llm-wiki plugin) live in wiki/SCHEMA.md, not here.

Page types

  • doc — the default type. One doc per feature/subsystem/integration, following koan's existing topic-folder structure: architecture/, design/, messaging/, operations/, providers/, security/, setup/, users/.
  • overview — a routing/index doc for a whole tree: docs/README.md. Already a genuinely good, hand-curated prose index — this bundle does not replace it, index.md (§ below) adds a machine-oriented catalog alongside it.
  • reference — a cross-cutting reference page compiled by /brain ingest from external material (an article, a file, a captured idea). Lives under docs/reference/ (created lazily on first ingest). Always carries raw: (local provenance path under the git-ignored raw/ directory) and, when the source had one, resource: (the external URI — a durable citation, unlike raw: which isn't dereferenceable by other clones). Always ends its body with a # Citations section (docs/SPEC.md §6).

Add a new type only when a real category doesn't fit the above and needs distinct queryability — not for a one-off; use tags instead.

Tag taxonomy

One tag per topic folder, plus one for the new reference/ folder:

  • architecture — daemon runtime, mission lifecycle, providers, skills system, memory, shared state
  • design — durable decisions, design notes
  • messaging — Telegram/Slack/Matrix/Discord/GitHub/Jira integration
  • operations — maintenance, troubleshooting, dashboard, REST API, auto-update, RTK, skill evals
  • providers — CLI/local-model provider setup and behavior (shared with specs/components/providers.md — deliberate cross-link, both angles on the same subsystem)
  • security — security review, threat models, prompt guard
  • setup — installation, host runtime (Docker, Railway, systemd, launchd, ssh)
  • users — user manual, onboarding, quickstart, skill reference
  • reference — pages compiled by /brain ingest

Frontmatter requirements

Every page under docs/ (except the reserved index.md filename) must have:

---
type: doc   # doc | overview | reference
title: "Human-readable title"
description: "One-sentence summary"
tags: [topic-tag]
created: 2026-06-27
updated: 2026-07-02
---

created/updated are real dates from git history for that file, not the backfill date. description is OKF-recommended (not OKF-required, per SPEC.md §7) but is treated as required house style here — see docs/SPEC.md's note on created/updated replacing OKF's timestamp. reference pages additionally carry raw: and, where applicable, resource: (see "Page types" above).

Index files

docs/index.md (bundle root, okf_version: "0.1" frontmatter) and one index.md per topic folder are mechanically generated by scripts/okf_backfill.py indexes — never hand-edited. See wiki/SCHEMA.md's "Index structure" section for how these relate to wiki/index.md.