35 lines
2.5 KiB
Markdown
35 lines
2.5 KiB
Markdown
---
|
|
name: upstream-engine-reference-into-vault
|
|
description: "Author a multi-page reference for an upstream engine into the serverAppConfigs OKF vault, passing the docs seams."
|
|
---
|
|
|
|
# Upstream engine → vault reference set
|
|
|
|
Use when asked to "deeply read and document" an upstream inference engine (radiance, llama.cpp, halogen) into `serverAppConfigs-docs`. Distill a repo's docs + ABI + option registry into progressive-disclosure pages, not a transcript.
|
|
|
|
## Read order (source beats docs)
|
|
|
|
1. `README.md`, then `docs/` TOC; read the serving guide, tools reference, plugin guide, architecture guide, op vocabulary.
|
|
2. Find the **authoritative option table** in source (`core/config.cpp` for serve flags, `tools/<tool>.cpp` `usage()` for tools, `abi/*.h` for plugin fields). Docs lag: radiance's `TOOLS.md` omitted `--chat-template`, `--lora`, `--lora-map`.
|
|
3. Version/ABI: `CMakeLists.txt` project VERSION and `#define RAD_ABI_VERSION`; these are independent.
|
|
4. Read one complete real plugin/example end to end (e.g. `plugin/spechub/exports.cpp`, `arch/llama_fp8/llama_fp8.cpp`) before writing "how to write a plugin".
|
|
|
|
## Page set (one owner per fact)
|
|
|
|
Hub + Options + HTTP API + Conversion + Model Families + Plugins + Architecture Plugins + Tools + Operations. The engine pages own engine defaults/flags/ABI; the fleet endpoint page (e.g. `LLM/frank-archon.md`) keeps live shape, Eras, measured laws, rollback. Link, never restate.
|
|
|
|
State the upstream commit + release + ABI, and separately the fleet pin; a flag newer than the pin is a boot refusal, not a no-op.
|
|
|
|
## Vault mechanics that fail the seams
|
|
|
|
- Frontmatter: `type` ∈ reference/howto/tutorial/explanation, `description` non-blank, ≤120 chars, not the title, no fleet quantity; ISO `timestamp` not future.
|
|
- Every page ≤500 lines. Split rather than exempt.
|
|
- Tables: escape `|` inside cells as `\|` (pipes inside backticks still split GFM tables).
|
|
- Register pages: edit the directory `index.md` rows with the **exact** description, then `python3 scripts/gen-vault-index.py serverAppConfigs-docs` (must be a no-op on a second run).
|
|
- Run: `check-okf.py`, `check-vault-links.py`, `bats tests/docs_completeness.bats`; then `./tests/run.sh`.
|
|
- Do not add a second log/status file; the vault's `log.md` policy is owned by the repo.
|
|
|
|
## Commit
|
|
|
|
Branch `docs/<slug>` off `origin/main`; commit docs + generated indices together. If main moved, merge it (never rebase) and re-run the full suite. Report commit hash, page list, test evidence; ask before opening a PR.
|