docs: close OKF conformance gaps found by night audit

- references/okf-spec.md: replace v0.2 note with the deltas verified
  against upstream SPEC.md 2026-10-19 (timestamp->generated.at and
  # Citations->sources are the two breaking changes; trust fields and
  root-index okf_version are additive; bundle stays v0.1).
- index.md: restore the agentic-web-research section lost in the
  2026-08-28 rebuild and link log.md (index-coverage doctrine).
- gen-keybinds.sh emits OKF frontmatter so its generated artifact
  (tools/niri/keybindings.md, regenerated, 120 bindings) passes kb-lint;
  test added red->green.
- fix the two broken [[niri]] wikilinks (handy, noctalia-shell).

Refs #29

omp-docs/index.md

@@ -48,7 +48,17 @@ Practice notes: SDLC, languages, infra tooling (Terraform, K8s, containers).
 Decision-support research: agentic web tooling, chezmoi evaluation,
 secrets-for-agents. Research docs inform decisions; they are not facts yet.
 
+## [Agentic web research](agentic-web-research/index.md)
+
+Self-hosted web-agent stack research: SearXNG tuning, VPN routing, agentic
+search practices, open models, MCP.
+
 ## [Inventory](inventory/index.md)
 
 Pre-pruning census of every userspace config on this box — the input for the
 pruning session.
+
+## [Change history](log.md)
+
+Chronological update history of this bundle — incident lessons land here first,
+then settle into concept pages.

omp-docs/references/okf-spec.md

@@ -8,11 +8,20 @@ tags:
   - documentation
   - knowledge-bundle
   - specification
-verified: 2026-08-28
+verified: 2026-10-19
 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.
+> **Note:** Google Cloud published OKF v0.2 at
+> [GoogleCloudPlatform/open-knowledge-format](https://github.com/GoogleCloudPlatform/open-knowledge-format)
+> (SPEC.md, verified 2026-10-19). v0.2 is a minor bump with two deliberate
+> breaking changes: `timestamp` is superseded by `generated: { by, at }`, and the
+> body `# Citations` list is superseded by a `sources` frontmatter family; it adds
+> optional trust/lifecycle fields (`verified: { by, at }`, `status`,
+> `stale_after`) and the `Attested Computation` type, and permits `okf_version:`
+> frontmatter in a bundle-root `index.md`. This bundle stays on v0.1 semantics
+> (kb-lint enforces them); the bundle-local `verified:` date stamp and `tags`
+> discipline are producer extensions compatible with both versions.
 
 # Open Knowledge Format (OKF) v0.1
 

omp-docs/tools/handy.md

@@ -229,5 +229,5 @@ See [[noctalia-shell]] for IPC integration patterns.
 ## See Also
 
 - [[noctalia-shell|noctalia-shell.md]] — Desktop environment integration
-- [[niri|niri/index.md]] — Compositor configuration
+- [niri](niri/index.md) — Compositor configuration
 - [`handy --help`](https://github.com/cjpais/Handy) — CLI reference

omp-docs/tools/niri/keybindings.md

@@ -1,3 +1,13 @@
+---
+type: reference
+title: Niri Keybindings
+description: Live keybinding cheat sheet generated from keybinds.kdl — do not edit by hand.
+tags:
+  - niri
+  - keybindings
+generated: { by: scripts/gen-keybinds.sh }
+---
+
 # Niri Keybindings
 
 > GENERATED by `scripts/gen-keybinds.sh` from `keybinds.kdl` — do not edit by hand.
@@ -64,10 +74,10 @@
 | `Mod+K` | focus-window-up |
 | `Mod+Down` | focus-window-down |
 | `Mod+J` | focus-window-down |
-| `Mod+CTRL+Left` | swap-window-left |
+| `Mod+CTRL+Left` | consume-or-expel-window-left |
-| `Mod+CTRL+H` | swap-window-left |
+| `Mod+CTRL+H` | consume-or-expel-window-left |
-| `Mod+CTRL+Right` | swap-window-right |
+| `Mod+CTRL+Right` | consume-or-expel-window-right |
-| `Mod+CTRL+L` | swap-window-right |
+| `Mod+CTRL+L` | consume-or-expel-window-right |
 | `Mod+CTRL+Alt+Left` | move-column-left |
 | `Mod+CTRL+Alt+H` | move-column-left |
 | `Mod+CTRL+Alt+Right` | move-column-right |
@@ -141,10 +151,10 @@
 | `Mod+CTRL+F` | expand-column-to-available-width |
 | `Mod+C` | center-column |
 | `Mod+CTRL+C` | center-visible-columns |
-| `Mod+Minus` | set-column-width "-10%" |
+| `Mod+Minus` | set-column-width "-5%" |
-| `Mod+Equal` | set-column-width "+10%" |
+| `Mod+Equal` | set-column-width "+5%" |
-| `Mod+Shift+Minus` | set-window-height "-10%" |
+| `Mod+Shift+Minus` | set-window-height "-5%" |
-| `Mod+Shift+Equal` | set-window-height "+10%" |
+| `Mod+Shift+Equal` | set-window-height "+5%" |
 
 ## Modes
 

omp-docs/tools/noctalia-shell.md

@@ -429,7 +429,7 @@ noctalia msg templates-apply
 
 ## See Also
 
-- [[niri|niri/index.md]] — Compositor configuration
+- [niri](niri/index.md) — Compositor configuration
 - [[displays|displays]] — Display layout
 - [[cachyos|cachyos]] — Operating system documentation
 - [`noctalia msg --help`](https://github.com/Noctalia/noctalia) — Full command reference

scripts/.tmp-index-coverage.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python3
+"""Doctrine check: every dir has index.md; index links every sibling file/dir."""
+import re, sys
+from pathlib import Path
+kb = Path(sys.argv[1])
+issues = []
+dirs = sorted({p.parent for p in kb.rglob("*.md")})
+for d in dirs:
+    idx = d / "index.md"
+    if not idx.is_file() and d != kb:
+        issues.append(f"{d.relative_to(kb)}: no index.md")
+        continue
+    if not idx.is_file():
+        continue
+    text = idx.read_text(errors="replace")
+    linked = set()
+    for m in re.finditer(r"\]\((?!https?:|#)([^)#\s]+?)(?:#[^)]*)?\)", text):
+        t = m.group(1)
+        target = (d / t).resolve() if not t.startswith("/") else (kb / t.lstrip("/")).resolve()
+        linked.add(target)
+    # wikilinks too
+    wl_names = {m.group(1).strip().rsplit("/", 1)[-1] for m in re.finditer(r"\[\[([^\]|#]+)", text)}
+    for sib in sorted(d.iterdir()):
+        if sib.suffix != ".md" or sib.name == "index.md":
+            continue
+        if sib.resolve() not in linked and sib.stem not in wl_names:
+            issues.append(f"{d.relative_to(kb)}/index.md: does not link {sib.name}")
+    # subdirs of d linked as their index?
+    for sub in sorted(d.iterdir()):
+        if sub.is_dir() and (sub / "index.md").is_file():
+            subidx = (sub / "index.md").resolve()
+            dirref = sub.resolve()
+            if subidx not in linked and dirref not in linked:
+                # also accept link to sub/ or sub/index.md or wikilink to dir name
+                if not re.search(re.escape(sub.name) + r"[/)]", text):
+                    issues.append(f"{d.relative_to(kb)}/index.md: does not link subdir {sub.name}/")
+for i in issues:
+    print(i)
+print(f"index-coverage: {len(issues)} issue(s)")
+sys.exit(1 if issues else 0)

scripts/gen-keybinds.sh

@@ -27,6 +27,16 @@ KBD="${KBD:-$HOME/.config/niri/cfg/keybinds.kdl}"
 [ -f "$KBD" ] || { echo "error: no such file: $KBD" >&2; exit 1; }
 
 gen() {
+  echo "---"
+  echo "type: reference"
+  echo "title: Niri Keybindings"
+  echo "description: Live keybinding cheat sheet generated from $(basename "$KBD") — do not edit by hand."
+  echo "tags:"
+  echo "  - niri"
+  echo "  - keybindings"
+  echo "generated: { by: scripts/gen-keybinds.sh }"
+  echo "---"
+  echo
   echo "# Niri Keybindings"
   echo
   echo "> GENERATED by \`scripts/gen-keybinds.sh\` from \`$(basename "$KBD")\` — do not edit by hand."

tests/gen-keybinds.bats

@@ -63,6 +63,13 @@ teardown() {
   grep -q 'GENERATED' "$TMP/out/keybindings.md"
 }
 
+@test "output begins with OKF frontmatter so the artifact passes kb-lint" {
+  run "$GEN" "$TMP/keybinds.kdl"
+  [ "${lines[0]}" = '---' ]
+  [[ "${lines[1]}" == 'type: reference' ]]
+  grep -q '^generated:' <<<"$output"
+}
+
 @test "missing input file fails loudly" {
   run "$GEN" "$TMP/nope.kdl"
   [ "$status" -ne 0 ]