Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

docs(open-knowledge): add "Supporting the Open Knowledge Format" workflow guide (#2141)

serafin-garcia2a871b2ae3ac
diff --git a/docs/content/workflows/meta.json b/docs/content/workflows/meta.json
index 7a8fe1e35..385a15e64 100644
--- a/docs/content/workflows/meta.json
+++ b/docs/content/workflows/meta.json
@@ -1,5 +1,5 @@
{
"title": "Workflows",
"icon": "LuWorkflow",
- "pages": ["karpathy-llm-wiki", "entity-vault"]
+ "pages": ["karpathy-llm-wiki", "entity-vault", "supporting-open-knowledge-format"]
}
diff --git a/docs/content/workflows/supporting-open-knowledge-format.mdx b/docs/content/workflows/supporting-open-knowledge-format.mdx
new file mode 100644
index 000000000..745da5863
--- /dev/null
+++ b/docs/content/workflows/supporting-open-knowledge-format.mdx
@@ -0,0 +1,47 @@
+---
+title: Supporting the Open Knowledge Format
+description: Scaffold a knowledge base that is conformant with Google's Open Knowledge Format (OKF) from the first commit — without enforcing anything.
+---
+Open Knowledge ships a starter pack named **`okf`** that scaffolds a knowledge base **conformant with Google's [Open Knowledge Format (OKF)](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) from the first commit** — without enforcing anything. You get a portable, OKF-ready bundle out of the box, and you stay free to author however you like.
+
+<Callout type="info">
+ **OKF here means Google's Open Knowledge _Format_** — a vendor-neutral file-format spec (a directory of markdown files with YAML frontmatter), announced by Google Cloud in June 2026. Read the [OKF v0.1 spec](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md).
+</Callout>
+
+## What the pack seeds
+
+Run it with `ok seed --pack okf`. It scaffolds:
+
+| Path | Purpose | Template |
+|---|---|---|
+| `concepts/` | Durable ideas and definitions | `concept` |
+| `references/` | External sources and citations | `reference` |
+| `notes/` | Working notes and observations | `note` |
+| `welcome.md` | A real typed concept, so a strict OKF consumer has something to accept | — (seeded file) |
+| `index.md` | Reserved OKF navigation hub | — (reserved) |
+| `log.md` | Reserved OKF change history | — (reserved) |
+
+Each of the three content folders (`concepts/`, `references/`, `notes/`) ships its **own template**, so new docs start with the right `type` and section skeleton already in place — you never hand-set the frontmatter. The conventions also ship as a project-local skill (`open-knowledge-pack-okf`) installed alongside the seed, so your agent learns the pack's discipline without a hand-written `CLAUDE.md`.
+
+## Conformance is pre-populated, not enforced
+
+This is the key design decision. OKF asks exactly one thing of every **non-reserved** document: a **non-empty `type`** in its frontmatter. Reserved `index.md` / `log.md` stay frontmatter-free, and links are standard markdown.
+
+The pack bakes those habits into the seeded content and documents them — but it changes nothing about how Open Knowledge itself behaves:
+
+- Open Knowledge's native frontmatter schema stays **open-shaped**.
+- Nothing is **linted** for OKF conformance.
+
+So three habits are all it takes to keep the KB handable to a strict OKF consumer as it grows:
+
+1. Every non-reserved doc carries a non-empty `type`.
+2. `index.md` / `log.md` stay lowercase and frontmatter-free.
+3. Links use standard markdown (`[text](./path.md)`).
+
+Open Knowledge also accepts `[[wiki-link]]` shorthand as a native superset, and the OKF export normalizes it to standard links — but seeded content uses standard links so the bundle is conformant as-is.
+
+## Further reading
+
+- **[Open Knowledge Format spec](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)** — the canonical OKF v0.1 specification (Google Cloud).
+- **[`STARTER_PACKS` registry](https://github.com/inkeep/open-knowledge/blob/main/packages/server/src/seed/starter.ts)** — canonical source for the `okf` pack content.
+- **[Karpathy's LLM wiki workflow](./karpathy-llm-wiki.mdx)** and **[Entity vault workflow](./entity-vault.mdx)** — other starter-pack-driven workflows in Open Knowledge.