Research llama.cpp runtimes + SGLang; fix AGENTS.md OKF spec link

Fan out subagents to compare mainline llama.cpp, charlie12345/ROCmFPX,
and ik_llama.cpp, then add their findings to the project knowledge base:
- docs/Research/Llama Cpp Runtimes.md  (positioning + quantization + server fit)
- docs/Research/Llama Cpp Code Diff.md (code-level quant diff, table, recommendations)
- docs/Research/SGLang.md              (what SGLang is, comparison, our-boxes fit)
- docs/Research/index.md               (Research progressive-disclosure index)
Cross-linked from docs/index.md (root) and docs/LLM/index.md.

AGENTS.md:
- Add Documentation Authoring section: docs/ is an OKF bundle; point doc authors
  at the canonical spec in the system-config knowledge base
  (~/.pi/agent/docs/references/okf-spec.md), not the orphaned
  docs/references/okf-spec.md; consolidate read-index/one-concept-per-file/
  progressive-disclosure/citation rules.
- Map AGENTS.md to docs_completeness.bats in the focused pre-commit hook (it was
  last committed before the hook existed and had no mapping).
This commit is contained in:
Frank
2026-08-25 18:23:19 -07:00
parent 2693259227
commit 929796352a
8 changed files with 492 additions and 0 deletions
+26
View File
@@ -52,6 +52,32 @@ Retired scripts live in `old/` (reference only) and `.AGENTTRASH/`.
- `docs/` — knowledge base (Obsidian vault). `docs/LLM/` is the LLM fleet
- `tests/` — bats test suite
## Documentation Authoring
The `docs/` vault is the project knowledge base (Obsidian, wikilinks) and is an
OKF (Open Knowledge Format) knowledge bundle. Follow the OKF spec for every doc
you create or edit.
- **Canonical spec:** `~/.pi/agent/docs/references/okf-spec.md` — the OKF v0.1
spec in the **system-config knowledge base** at `~/.pi/agent/docs`. The repo's
own `docs/references/okf-spec.md` is deprecated/removed; use the system one. The
spec index and maintenance guide are
`~/.pi/agent/docs/references/index.md` and
`~/.pi/agent/docs/references/okf-maintenance.md`.
- **Read before you touch:** open the relevant `index.md` first
(`docs/index.md` → `docs/LLM/index.md`). Read the whole target file before
editing it.
- **One concept per file**, with YAML frontmatter that has a non-empty `type:`
field (`reference` / `guide` / `configuration` / `research`) plus `description`,
`tags`, and `timestamp`. Split broad topics; keep pages ~1–500 lines.
- **Progressive disclosure:** an `index.md` at each level links its children.
Every `docs/**/*.md` (except `index.md`) must be linked from
`docs/index.md` with `[[Title]]` — the docs-completeness test checks this.
- **Cross-link** siblings as `[[Title]]` wikilinks; cite external claims under a
`# Citations` section.
- **Always update docs** when a task changes behavior, then run
`./tests/run.sh` (the docs-completeness seam is in there) before commit.
## Git Workflow
All edits flow through git. Do not edit files on the remote machine directly.