Should OKF's scope cover documents beyond single conceptual atoms? (+ `okf_version` on standalone files)

OKF today is aimed at **conceptual-knowledge atoms** — encyclopedia-style entries, one concept per file (§2: *"A single unit of knowledge within a bundle. Represented as one markdown document."*). That's a clean, well-chosen scope. We've been building on OKF and hit two questions where the same format clearly *works* for more than that, but the spec doesn't say whether it's *meant* to. Both are additive; neither needs a breaking change.

**1. Should OKF's scope expand beyond conceptual atoms? Worth deciding explicitly.**

The format — frontmatter scalars + markdown body + bundle/`index.md` structure — works just as well for **larger things**: conceptual *molecules* (a cluster of related ideas held as one document), and really *any kind of document* — a playbook, a runbook, an operating contract, a policy, a report. Nothing in the format resists it. (Concretely: we're publishing an agent operating-contract / playbook as OKF right now.)

And the spec already leaves the door open — `type` is open vocabulary (*"Type values are not registered centrally… consumers MUST tolerate unknown types gracefully."*), so publishing a `Playbook` or a `Report` as OKF isn't actually out of bounds today. Which means **people will do it whether or not it's blessed** — we already are. So the useful move is for OKF to *decide*, rather than leave it ambient.

The question for the maintainers: **should OKF's scope explicitly include documents beyond single conceptual atoms?** Either answer beats silence:

- **Bless it** — affirm an OKF file may be any document genre (the `type` field carries it), perhaps with a couple of cross-genre `type` examples.
- *Pro:* matches how the format will actually get used; lowers the barrier for procedural / document content; one format for a knowledge base *and* its operating docs.
- *Con:* dilutes the "knowledge atom" identity — "an OKF bundle" stops implying "a set of concepts"; risks drifting toward "just markdown-with-frontmatter, but ours."
- **Forbid it** — a `SHOULD NOT` / `MUST NOT`: OKF files represent conceptual units, not arbitrary documents.
- *Pro:* keeps the format sharp and its promise legible; a consumer can assume concept-shaped content.
- *Con:* fights the grain (the format genuinely fits more), and producers route around the prohibition anyway — so the line may not hold.

We lean toward **blessing the broader scope** — the format earns it and the usage is coming regardless — but the real ask is just: *make the call*, so a producer knows whether playbook-as-OKF is accepted or merely tolerated.

**2. `okf_version` has nowhere to live on a standalone file.**

§11 scopes `okf_version` to the **bundle-root `index.md`** (*"the only place frontmatter is permitted in an `index.md`"*). But a single document distributed on its own has no `index.md` to carry that signal — and a consumer receiving the file cold has no way to tell which OKF version it targets. The version information simply can't travel with the artifact.

Suggestion: allow (SHOULD/MAY) a standalone OKF document to declare `okf_version` in its **own** frontmatter when it's distributed detached from a bundle. It's additive, it's the only place the signal can ride on a lone file, and it doesn't change the bundle case at all. (Minor comment: §11's example quotes the value — `okf_version: "0.1"` — which is worth keeping normative so it's parsed as a string, not a YAML float that would drop a trailing zero in a future `"0.10"`.)

Both come down to the same underlying gap: OKF's model is a bundle of conceptual atoms, and it's quietly being used for more — bigger documents, and single files distributed on their own. Naming where that's in scope (and where `okf_version` rides when there's no bundle to hold it) would let the broader usage be deliberate rather than accidental.

**Related.** This sits alongside two other active proposals to extend OKF's frontmatter for agent-era uses: #52 (our provenance/license fields — the publishing work this came out of) and #53 (@leesharks000's summarization-governance fields — `provenance_kernel`, `disambiguation`, `summary_policy`). A clear answer on scope would give proposals like these a shared frame — e.g. #53's `disambiguation` ("what the concept is *not*") reads naturally for a concept and less obviously for a playbook or a report, which is the same boundary this issue is asking you to draw.

---
*Drafted by AI (Claude Code, Opus 4.8) under the direction of Peter Kaminski, who has reviewed it and takes full responsibility for its content.*