docs: distill the managed skill library into the vault (waves 1-7)

All ~173 managed skills read in full and merged, one polished reference
page per skill-cluster:

- LLM cross-cutting (17 pages): GGUF Compatibility, Llama Cpp Serving
  Sizing, Llama Cpp Multi-Device Splits, PCIe Link and Atomics, RDNA4
  Container Serving, RDNA4 MoE Expert Offload VRAM Budget, vLLM Boot
  Forensics, vLLM Porting and Compile Triage, LLM Bench Windows, LLM
  Performance Diagnosis, Model Swap and Rollback, Tcclaviger Fork Ops,
  Heterogeneous Split Triage, FreeToken Builds + deltas folded into the
  retired runbooks (GLM DFlash2 port laws, Lucebox dual-R9700, R9V
  qualification pipeline, FLM pack registration, ik hybrid envelope,
  frank-medium split rebalance, llama.cpp GGUF preflight, batch-ubatch
  split section, bench-window D-state/stale-read notes, second-endpoint
  bring-up).
- Architecture (3): Stale Signal Audit, Quadlet Lifecycle, Deploy State
  Triage.
- Operations (6 + index): Remote Job Runner, Payload and Disk Reclaim,
  Container Host Reachability, Fleet Ops Playbook, Fleet Audit and
  Posture, SSH and Remote Access.
- Infrastructure: Observability Provisioning + Homepage Status Probes;
  updates to Authentik, Anubis, LAN-DNS (per-client DoH bypass, Porkbun
  zone ops), Swap Configuration, OpenWebUI, Hermes (pre-existing page
  preserved and extended).
- FrankBook-Pro: ARR-Stack filled (API split, schema-first probing,
  auth-posture, auth-config trap); qBittorrent E2E verification.
- Desktop/Agent/Research: Noctalia and Niri, OMP Harness, Agent Docs and
  Edits, Command Center Dotfiles, PICO-8 Asset Standards.
- Indexes: LLM Cross-Cutting References section, Operations/ and Agent/
  index pages, root-index Skill Distillation section, AGENTS.md pointer.
- log.md carries the wave plan.

check-vault-links.py 0 unresolved (185 pages); ./tests/run.sh 366/366.
This commit is contained in:
Frank committed 2026-10-05 21:19:15 -07:00
1 parent 8618ec6dbe
commit 33eae71d33
43 files changed
+5436 -2

No files matched your search

@@ -190,6 +190,70 @@ repo env sets `R9V_ENABLE_PREFIX_CACHING=1` (commit `41e9189`), verified
on :7770 (`--enable-prefix-caching` in the container argv, health 200,
live completion answering).
## Authoring a new profile (the qualification pipeline)
Order matters at every step:
1. **Package manifest** `packages/models/<pkg>/package.json` — target shards
+ aux artifacts with sha256. Verify every target's byte count AND sha256
after fetch (`curl -fL -C -` per shard; never trust a fetch without `-f`).
2. **Placement bootstrap** from GGUF headers: parse all shards' tensor
tables (a KV-only shard1 is normal for split parts; each part carries its
own tensor table). Per-expert full per layer =
(`ffn_gate_exps` + `ffn_up_exps` + `ffn_down_exps`)/512; rank slices
rank0 = full×416//640, rank1 = full−rank0. Hot counts =
floor(measured_budget / per-expert total). **Anchor budgets to the
MEASURED hot_bytes of the qualified sibling profile, never invented.**
3. **Trim + validate**: `tools/trim_experts.py --hot-counts N,M`, then
`expert_budget.validate_manifest(m)` +
`expert_budget.expert_memory(m, slots, {cache_rank}, runtime=<runtime.json>)`
(runtime/catalog are keyword-only). Declared hot_bytes must match
computed or it raises.
4. **PLE derive** (containerized `tools/prepare_ple.py` with
`--expected-bytes/--expected-type/--expected-shape`); setup skips
re-derivation when the file exists with matching size.
5. **profile.env**: set values BEFORE `source dual-r9700/profile.env`
(set-first-wins; an empty string does NOT survive `:=`).
The canonical bootstrap.json wrapper schema is exactly
`{schema: "r9v.placement.v1", id, model_package, hardware, artifact_path,
artifact_sha256, scope}` with `hardware: "dual-r9700-32gb-asymmetric"`; the
wrapper `id` MUST equal the id in the profile.json placement descriptor
(setup rejects mismatches: "does not match profile placement"). Never
fabricate qualification metadata — use
`scope: "Unranked routing bootstrap only; does not certify fit or headroom"`.
GGUF parsing laws for the bootstrap: expert tensor names are
`blk.0.ffn_up_exps.weight` — split on "." gives FOUR parts, layer number is
parts[1] (a 3-part assumption crashes `int("")`); outer-KV value-type sizes
`{0:1,1:1,2:2,3:2,4:4,5:4,6:4,7:1,8:str,9:arr,10:8,11:8,12:8}`; tensor byte
extents from consecutive OFFSETS, never a type-size table (mis-buckets tails
silently); the PLE Q8_0 tensor on this arch is shape (160, 320001536),
54,400,261,120 B, an entire shard.
Setup/start: `./r9v setup <alias> --state-dir <dir> --model-dir <dir> --image
sha256:<digest> --local-image --reuse-from <sibling-model-dir>
--accept-model-license` (aux artifacts reuse byte-identical files; F16 vs
Q8 mmproj will not reuse). Start requires the SAME `--state-dir`; fixed
placement via `R9V_EXPERT_MANIFEST_PATH` skips headroom/catalog/seed raises.
The host-only doctor FAILs when another instance holds the cards (it wants
3 GiB free per rank; production at ~30 GiB/card is a hard wall) — a second
instance CANNOT coexist, so qualification requires a stop+mask window for
the incumbent, then unmask+restart.
**Qualification gate (unqualified → qualified):** first start runs the
workload battery (PONG / tool_calls / vision / long-ctx), the PLE pinning
proof (`VmLck` ≈ PLE bytes in `/proc/<container-pid>/status` when
RESIDENCY_MODE=pinned), and a VRAM headroom snapshot (floor 3.3 GiB). If
headroom is violated, lower hot counts via re-trim and re-derive
MAX_EFFECTIVE. Only then record state `ready: true` and author the runbook.
Remote-execution gotchas from the same windows: `nohup X &` inside an ssh
command races ssh teardown — the script can die before writing a byte; run
long remote scripts synchronously, or setsid + disown, or via a system
unit. zsh login shells abort on unquoted `===` separators; grep globs need
quoting through ssh+zsh layers.
## Ops
- **Restart**: `sudo systemctl restart frank-primary` (root unit; the serve