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.

omp-docs/references/okf-maintenance.md

@@ -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.