dank/command-center
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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.
This commit is contained in:
Frank
2026-08-28 07:57:13 -07:00
parent 552d1ef8bf
commit 02883d3ed2
116 changed files with 13008 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
omp-docs/references/index.md
+10
View File
@@ -0,0 +1,10 @@
# Reference Material
Keep your OKF knowledge bundle from rotting — change tracking, frontmatter discipline, staleness detection, and automation.
## Concept Files
| File | Type | Description |
|------|------|-------------|
| [okf-maintenance.md](okf-maintenance.md) | guide | Keep your OKF knowledge bundle from rotting — change tracking, frontmatter discipline, staleness detection, and automation. |
| [okf-spec.md](okf-spec.md) | reference | Complete specification for OKF knowledge bundles — a directory of markdown files with YAML frontmatter. |
omp-docs/references/okf-maintenance.md
+147
View File
@@ -0,0 +1,147 @@
---
type: guide
title: OKF Bundle Maintenance
description: Keep your OKF knowledge bundle from rotting — change tracking, frontmatter discipline, staleness detection, and automation.
tags:
- okf
- maintenance
- documentation
- best-practices
- unverified
timestamp: 2026-01-15
---
# OKF Bundle Maintenance
Knowledge bundles rot. It is the nature of knowledge to attract cobwebs, much like an unvisited pantry attracts spiders that are frankly doing you a favor by reminding you it has been a while. An OKF bundle maintained by agents is no exception — files drift out of sync, frontmatter becomes decorative, and `index.md` turns into a ghost town where links go to die.
**The core principle:** if you do not track changes, you do not know when they happened. If you do not have a changelog, you are the person who finds the broken thermostat and wonders why it is set to "volcano."
---
## Change Tracking with `log.md`
Every OKF bundle has a `log.md` file. It is not optional. It is the bundle's memory.
**Format:** Date-grouped entries, newest first. One line per change with timestamp, file path, and what changed.
```markdown
# Bundle Change Log
## 2026-01-15
- `/docs/ghostty.md` — Updated keybind table after v1.2 release
- `/docs/pi-permission-system/` — Added `policy.md` and `audit.md`
- `/docs/index.md` — Synced with directory contents
```
**Rules:**
- **Newest entries first.** Putting old entries at the top inverts the timeline and makes it impossible to see what just happened.
- **One line per change.** A single line is sufficient. The git history is there if someone wants the gory details.
- **Group by date.** Batch all changes from the same day together.
- **Always date-stamp the section.** Use `## YYYY-MM-DD`.
- **Mention `index.md` whenever you change a bundle.** If you added or removed a file, update the index and note it in the log.
### Common Mistakes
- ❌ Writing `"Updated ghostty.md"` — Updated it with what? Be specific.
- ❌ Forgetting to write to `log.md` — This is the equivalent of doing surgery without keeping a record.
- ❌ Using relative paths — Use absolute paths (`/docs/ghostty.md`).
- ❌ Leaving stale entries from manual edits — The log is the single source of truth.
---
## Frontmatter Discipline
Frontmatter is the metadata layer. It is not decoration.
### Required field:
- `type` — The concept type. The only strictly required frontmatter field.
### Strongly recommended:
- `description` — The preview text. Without it, the file is invisible and confusing.
- `tags` — Use for cross-cutting concerns. Tags hold things together across categories.
- `timestamp` — Include for staleness detection. A file with a timestamp from 2023 is more likely stale than one from 2026.
- `title` — Optional but helpful.
### Rules:
- ✅ Every concept file must have a `description`.
- ✅ Use `tags` liberally but consistently.
- ✅ Include `timestamp` on every file.
- ✅ Pick descriptive `type` values: `reference`, `guide`, `configuration`, `tutorial`.
- ❌ Don't use `type: file` or `type: document` — be specific.
- ❌ Never leave `description` blank or copy the title.
---
## One Thing Per File
OKF is built on the principle that a file is one concept.
**Splitting criteria:**
- ✅ One topic, one file. If the content can be summarized in one sentence without using "and," it belongs in one file.
- ✅ Give each file its own `type`.
- ✅ Keep each file between 1 and 500 lines. Under 1 = over-split. Over 500 = under-split.
- ❌ Don't create a file called `misc.md` — `misc` is a graveyard, not a category.
- ❌ Don't use `# Other` or `# Additional Notes` sections — these are taping things to the wall.
---
## Auto-Generation Strategies
### Index files as living documents:
```bash
find docs/bundle-name/ -name '*.md' ! -name 'log.md' -type f | \
sort | \
awk '{print "- " $0}' > docs/bundle-name/index.md
```
### Staleness detection:
```bash
# Find files older than 90 days
find docs/ -name '*.md' ! -name 'index.md' ! -name 'log.md' \
-mtime +90 -type f -print
# Find files missing timestamp
find docs/ -name '*.md' ! -name 'index.md' ! -name 'log.md' \
-type f -exec grep -L '^timestamp:' {} \;
# Find files missing description
find docs/ -name '*.md' ! -name 'index.md' ! -name 'log.md' \
-type f -exec grep -L '^description:' {} \;
```
---
## Version Control Best Practices
- ✅ One logical change per commit
- ✅ Write meaningful commit messages ("Updated file" is not a commit message. It is a shrug in text form.)
- ❌ Don't commit entire bundle dumps — a commit touching 50 files is a data dump, not a change
### Useful git commands:
```bash
git blame -L 1,30 docs/ghostty.md # Who changed what and when
git log --oneline -n 10 -- docs/pi-permission-system/ # Last commits in a directory
git status --short # What is uncommitted
```
---
## Knowing When Something Is Stale
| Signal | Threshold | Action |
|--------|-----------|--------|
| `timestamp` field older than 6 months | Auto-flag | Review and update or archive |
| File not modified in 12 months | Auto-flag | Assess whether still relevant |
| `index.md` count differs from file count | Always | Fix immediately |
| `log.md` has no entries for 30+ days | Context-dependent | Normal if no changes made |
---
## See Also
- [OKF v0.1 Specification](okf-spec.md) — The complete format specification.
- [Root Index](/index.md) — This bundle's structure and navigation.
omp-docs/references/okf-spec.md
+154
View File
@@ -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.