docs: rebuild KB in OKF v0.1 with live-verified facts

Copy of the legacy ~/.pi/agent/docs tree rebuilt as the command-center knowledge base: concept files promoted to path identity, index listings stripped of frontmatter, all wikilinks/relative links resolved, every checkable claim verified against the live fleet (Dankserver = Ryzen 7 7700X + RTX 3090; Strix Halo is Dankclaw), unverifiable claims tagged. kb-lint exits 0.
2026-08-28 07:57:13 -07:00
1 parent 552d1ef8bf
commit 02883d3ed2
@@ -0,0 +1,154 @@
+---
+type: reference
+title: Open Knowledge Format (OKF) v0.1 Specification
+description: Complete specification for OKF knowledge bundles — a directory of markdown files with YAML frontmatter.
+resource: https://github.com/GoogleCloudPlatform/open-knowledge-format
+tags:
+  - okf
+  - documentation
+  - knowledge-bundle
+  - specification
+verified: 2026-08-28
+timestamp: 2026-01-15
+---
+
+> **Note:** Google Cloud published OKF v0.2 at [GoogleCloudPlatform/open-knowledge-format](https://github.com/GoogleCloudPlatform/open-knowledge-format) with additional frontmatter families for provenance, trust, and attestation. This document covers the v0.1 format used by this knowledge bundle.
+
+# Open Knowledge Format (OKF) v0.1
+
+OKF is the answer to "everyone has knowledge, but nobody speaks the same language." Every agent, catalog, wiki, and metadata store represents knowledge differently — and every agent builder is reinventing the context-assembly wheel.
+
+OKF v0.1 formalizes the "LLM wiki" pattern into a portable, interoperable format. The entire specification is simple enough to fit on a single page:
+
+> **A directory of markdown files with YAML frontmatter.**
+
+That's it. No schema registry. No central authority. No SDK. No runtime. If you can `cat` a file, you can read OKF. If you can `git clone` a repo, you can ship it.
+
+---
+
+## What's in a Bundle?
+
+An OKF knowledge bundle is a directory tree. Every concept is one file. The file path is the concept's identity.
+
+```
+my-bundle/
+├── index.md                      # Optional directory listing
+├── log.md                        # Optional update history
+├── concept-one.md                # A concept at the root level
+└── subdirectory/
+    ├── index.md                  # Optional subdirectory listing
+    ├── concept-two.md            # A concept in a subdirectory
+    └── another-concept.md        # Another concept
+```
+
+**Reserved filenames** (MUST NOT use for concepts):
+
+| Filename | Purpose |
+|----------|---------|
+| `index.md` | Directory listing for progressive disclosure |
+| `log.md` | Chronological update history |
+
+---
+
+## Anatomy of a Concept Document
+
+```yaml
+---
+type: <Type name>                  # REQUIRED
+title: <Optional display name>
+description: <Optional one-line summary>
+resource: <Optional canonical URI>
+tags: [<tag>, <tag>, …]            # Optional
+timestamp: <ISO 8601 datetime>     # Optional
+---
+```
+
+### Required Fields
+
+| Field | Required? | What it does |
+|-------|-----------|-------------|
+| `type` | **Yes** | Identifies the kind of concept. Used for routing, filtering, presentation. |
+| `title` | No | Human-readable display name. |
+| `description` | No | Single-sentence summary. Used by index generators, search snippets, previews. |
+| `resource` | No | URI identifying the underlying asset. |
+| `tags` | No | YAML list for cross-cutting categorization. |
+| `timestamp` | No | ISO 8601 datetime of last meaningful change. |
+
+---
+
+## Index Files — Progressive Disclosure
+
+An `index.md` in any directory lets a human or agent see what's available:
+
+```markdown
+# Sales Tables
+
+* [Orders](tables/orders.md) - One row per completed customer order.
+* [Customers](tables/customers.md) - Customer account information.
+```
+
+**Rules:** No frontmatter. Relative paths. One section per heading. Entries include description from linked concept's frontmatter.
+
+---
+
+## Log Files — Change History
+
+```markdown
+# Directory Update Log
+
+## 2026-05-22
+* **Update**: Added new reference for [Customer Metrics](/tables/customer-metrics.md).
+* **Creation**: Established the [Dataplex Playbook](/playbooks/dataplex.md).
+```
+
+- Date headings MUST use `YYYY-MM-DD`
+- Entries grouped newest-first
+- Leading bold word is a convention, not a requirement
+
+---
+
+## Cross-linking
+
+**Absolute (bundle-relative) links — RECOMMENDED:**
+
+```markdown
+See the [customers table](/tables/customers.md) for the join key.
+```
+
+**Relative links:**
+
+```markdown
+See the [neighboring concept](./other.md).
+```
+
+Consumers MUST tolerate broken links.
+
+---
+
+## Conformance Rules
+
+A bundle is **conformant** with OKF v0.1 if and only if:
+
+1. **Every non-reserved `.md` file** contains a parseable YAML frontmatter block.
+2. **Every frontmatter block** contains a non-empty `type` field.
+3. **Every reserved filename** follows the structure described here when present.
+
+Everything else is soft guidance. Consumers MUST NOT reject a bundle because of missing optional fields, unknown types, or broken links.
+
+---
+
+## Common Mistakes
+
+- ❌ Forgetting the `type` field — this is the only strictly required field
+- ❌ Using `type: file` or `type: document` — be specific: `type: BigQuery Table`, `type: API Endpoint`
+- ❌ Putting frontmatter in `index.md` — index files are directory listings, not concepts
+- ❌ Using relative links for concepts in different directories — use absolute paths
+- ❌ Writing one giant `index.md` that lists everything — use `index.md` at multiple levels
+- ❌ Skipping `# Citations` for factual claims — cite external sources under `# Citations`
+
+---
+
+## See Also
+
+- [OKF Bundle Maintenance](okf-maintenance.md) — How to keep your bundle from rotting.
+- [Root Index](/index.md) — This bundle's structure and navigation.