docs(vault): service and infrastructure pages stop restating endpoint facts

18 pages cut their per-endpoint shape, payload, port and window claims and link [[frank-archon]] / [[frank-dragoon]] / [[frank-zealot]] instead. Several of the cut claims had already drifted -- the stack page still described the kingjones ROCmFP4 era on ROCmFPX, OpenWebUI carried the 27B/3-slot bench narrative, Hermes named a retired max_model_len and the old service name, and the OMP harness page's live-window block had drifted off frank-zealot's real 262,144 (it is now labelled a dated worked example whose authority is the endpoint page). Two facts gain a single owner instead of two: the up{job=~"frank-.*"} scope lives in Infrastructure/Prometheus.md, and the blackbox/Anubis probe form in Architecture/Stale Signal Audit.md, each cited from the other page. Voice Packs and Frank TTS carried live-state claims that contradicted the engine page's 2026-10-18 deploy record (nothing listening on 7772/8880, model dir absent); they now point at the pages that own host state.
2026-10-19 00:56:02 -07:00
parent 219a097b39
commit 6bdfd2853e
18 changed files with 169 additions and 169 deletions
@@ -13,11 +13,10 @@ timestamp: 2026-08-26
 # Dankclaw Stack

 Dankclaw (192.168.0.143) runs the AI, search, development, and observability
-stack. Its LLM inference endpoint `frank-dragoon` (`:7770`) is a ROCmFPX
-llama.cpp fork serving the kingjones Qwen3.8-Flash-Next-ROCmFP4-STRIX GGUF on
-the card's pinned runtime; an NPU endpoint (`frank-npu`, `:7771`,
-FLM v1.0.1) serves sight+sound models. The completion endpoint
-`frank-medium` (ROCmFPX llama.cpp, `:7770`) runs on Dankserver (192.168.0.235).
+stack. Its LLM inference endpoints are bare-metal host services, not part of
+the container stack; each has its own page — shape, payload, eras and wire
+contract live there, nowhere else. See [[frank-dragoon]] and [[frank-zealot]]
+(both on this host) and [[frank-archon]] (Dankserver, 192.168.0.235).

 ```mermaid
 graph LR
@@ -28,9 +27,8 @@ graph LR
    C --> F[ComfyUI]
    C --> D[Grafana]
    S --> V[Gluetun VPN]
-    O --> L[llama.cpp dankserver :7770]
+    O --> L[LLM endpoints]
    O --> H[Hermes]
-    O --> E[frank-dragoon :7770]
 ```

 ## Services
@@ -48,18 +46,17 @@ graph LR
 | Seerr | `seerr.franksdank.cloud` (guarded) | Caddy routes post-auth to `seerr:5055` | [[Seerr]] |
 | Homepage | `franksdank.cloud` + `www.` (root site; guarded for admin actions) | served by Caddy itself from `/srv/homepage` | — |
 | Pi-hole | `pihole.franksdank.cloud` (basicauth edge, not the guard chain) | admin UI `8083`; DNS on `:53` LAN-wide | [[Pi-hole]] |
-| frank-dragoon (host service) | — | `7770` | [[deployment]] |
-| frank-npu (host service) | — | `7771` (`/v1/version` health) | [[frank-npu]] |
-| frank-medium (host service, Dankserver) | — | `7770` | [[frank-medium-rocmfpx]] |
+| frank-dragoon (host service) | — | `7770` | [[frank-dragoon]] |
+| frank-zealot (host service) | — | `7771` | [[frank-zealot]] |
+| frank-archon (host service, Dankserver) | — | `7770` | [[frank-archon]] |

-The LLM rows are bare-metal systemd services, not containers. This
-repo owns their scripts, units, and knowledge base (see
-[LLM fleet knowledge base](../LLM/index.md)). Current mapping (2026-09-03):
-`frank-dragoon` runs the kingjones Qwen3.8-Flash-Next-ROCmFP4-STRIX GGUF
-on the card's pinned `kingjones30/ROCmFPX` llama.cpp build;
-`frank-npu` runs FLM v1.0.1 on the XDNA2 NPU;
-`frank-medium` runs charlie12345/ROCmFPX llama.cpp serving
-kingjones777/Qwen3.8-27B-ROCmFPX-Q8_0-AGENT-GGUF on Dankserver.
+The LLM rows are bare-metal systemd services, not containers, and this repo
+owns their scripts, units and knowledge base (see
+[LLM fleet knowledge base](../LLM/index.md)). Which payload and runtime sits on
+each port is era state and lives on the endpoint page, not here. `frank-npu`
+(the XDNA2 NPU endpoint) and `frank-medium` (the predecessor of `frank-archon`
+on the Dankserver port) are both retired — see [[frank-npu]] and
+[[frank-medium-radiance-mxfp4]].

 ## Boot Persistence

@@ -29,7 +29,7 @@ render needs the app installed, not this endpoint.
 | | |
 | --- | --- |
 | Host | Dankclaw (`192.168.0.143`), rootless podman, user unit `frank-tts.service` |
-| Port | **7772**, published (`PublishPort=7772:7772`); the family is 7770 dragoon, 7771 zealot, 7772 tts |
+| Port | **7772**, published (`PublishPort=7772:7772`) — the rest of the `frank-*` port family is in [[Dankclaw Stack]] |
 | Routes | `GET /health`, `GET /v1/audio/voices`, `POST /v1/audio/speech`; everything else 404, and speech is POST-only |
 | Image | `localhost/franksdank/frank-tts:latest`, built from `dankclaw/voiceservice/Containerfile`, `Pull=never` |
 | Networks | `dankclaw_default` first (it owns the default route and the consumers), then `frank-tts-engine.network` (10.89.5.0/24, the bridge to the engine) |
@@ -142,9 +142,9 @@ types: [[Prometheus]] records that the existing HTML probes (`comfyui`, the two
 `services` targets) sit **down** with
 `received unsupported Content-Type … and no fallback_scrape_protocol specified`.
 A `/health` probe job would therefore be structurally never-green, and because
-`LlmEndpointDown` is scoped `up{job=~"frank-.*"} == 0`, a permanently red
-`frank-tts` target would page on Signal every few minutes for an endpoint that
-is fine — the frank-archon lesson pointed the other way. The engine cannot be
+`LlmEndpointDown` is scoped across the whole `frank-*` job family (the rule set
+lives on [[Prometheus]]), a permanently red `frank-tts` target would page on
+Signal every few minutes for an endpoint that is fine. The engine cannot be
 scraped at all: it publishes nothing. Status lives in `systemctl --user status`,
 `podman healthcheck run`, the two unit journals, and the homepage card, which
 probes `127.0.0.1:7772` for real now — the `wip: down` gate came off with the
@@ -78,9 +78,9 @@ is not durable. The tracked, sanitized configuration baseline is
  `/data/config.yaml` is not readable without `sudo`):
  `dankclaw-large` reaches `http://192.168.0.143:7770/v1` and exposes
  `frank-dragoon` — verified from the host with `curl
-  http://127.0.0.1:7770/v1/models` → single id `frank-dragoon`, `max_model_len
-  200704` (2026-10-18; write `127.0.0.1`, not `localhost`, because that port is
-  a rootless pasta publish and is IPv4-only);
+  http://127.0.0.1:7770/v1/models` → a single served id (2026-10-18; write
+  `127.0.0.1`, not `localhost`, because that port is a rootless pasta publish
+  and is IPv4-only);
  `dankserver-small` reaches `http://192.168.0.235:7770/v1` and, **as of
  2026-10-18, that endpoint serves only `frank-archon`** (`GET
  http://192.168.0.235:7770/v1/models` → `[{"id":"frank-archon"}]`). The name
@@ -88,7 +88,8 @@ is not durable. The tracked, sanitized configuration baseline is
  2026-09-15 — is retired-era: nothing on that endpoint answers to it today, so
  if the live `config.yaml` still names `frank-medium` the provider is dead
  weight and requests will 404 on a nonexistent model. Diff the live config
-  before trusting either name.
+  before trusting either name. Which payload sits behind each port, and the
+  served id it answers to, is on [[frank-dragoon]] and [[frank-archon]].
 - The live `config.yaml` contains secrets and user state and is not committed;
  the tracked example is the sanitized backup of its non-secret settings.

@@ -227,9 +228,10 @@ resp = call_llm(task="title_generation", messages=[...], max_tokens=64,

 What actually breaks, and the fix:

- **`response_format` (json_object / json_schema) is a hard 400 on every
-  local backend here** — neither FreeToken nor halogen implements constrained
-  decoding. Config cannot override it: `call_llm` merges the task's
+- **`response_format` (json_object / json_schema) is a hard 400 on the local
+  backends this task was written against** — what each endpoint accepts on the
+  wire is on [[frank-dragoon]] / [[frank-zealot]] / [[frank-archon]]. Config
+  cannot override it: `call_llm` merges the task's
  `extra_body` first and then `update()`s the caller's, so the hardcoded one
  wins. Only temperature and max_tokens have reactive retry paths.
 - **Fix: move that one task to the Responses transport**, which never
@@ -246,9 +248,8 @@ What actually breaks, and the fix:
          effort: none                 # mandatory, see below
  ```

-  Before copying this: as of 2026-10-18 `frank-zealot` is served on **Dankclaw
-  `:7771`**, and `http://192.168.0.235:7770/v1` — the endpoint this provider
-  name is recorded against — answers only `frank-archon`. The provider/model
+  Before copying this: which id is served on which port is endpoint state — see
+  [[frank-zealot]] and [[frank-archon]]. The provider/model
  pairing above is the shape that was landed in 2026; re-derive it from the live
  config before reusing it.

@@ -61,7 +61,7 @@ podman exec open-notebook curl -sS http://host.containers.internal:7771/v1/model

 **The blocker moved; it did not vanish.** frank-tts and frank-tts-engine are **deployed** (2026-10-18) and answer on 7772, so the voice leg works end to end — `podman exec open-notebook curl -sS http://frank-tts:7772/health` is the check to run the day the app exists. What still blocks a render is open-notebook itself: not installed on this host yet. When it is, the two provider rows above are the only wiring, and the seeded speaker profiles carrying OpenAI voice names are the first trap.

-**Why frank-zealot and not frank-dragoon:** podcast scriptwriting asks the model for a JSON-schema response (with a plain-JSON fallback). llama.cpp's OpenAI-compatible endpoint is a known-good target for that; frank-dragoon's halogen runtime has **unverified** structured-output behaviour, so it is the unproven alternative, not the fallback. `ESPERANTO_LLM_TIMEOUT=180` (the app's own default) covers an outline or transcript call on zealot comfortably; upstream's note is to keep it under 600 so a slow call fails with a clear error instead of a UI timeout.
+**Why frank-zealot and not frank-dragoon:** podcast scriptwriting asks the model for a JSON-schema response (with a plain-JSON fallback). The decision rests on each endpoint's documented request surface ([[frank-zealot]], [[frank-dragoon]]): zealot's is a known-good target for that call shape, dragoon's structured-output behaviour is **unverified**, so it is the unproven alternative, not the fallback. `ESPERANTO_LLM_TIMEOUT=180` (the app's own default) covers an outline or transcript call on zealot comfortably; upstream's note is to keep it under 600 so a slow call fails with a clear error instead of a UI timeout.

 ## Speakers and voices: 1–4, and the IDs are free text

@@ -39,30 +39,26 @@ As of 2026-10-07 the picker exposes **exactly one model: `frank-zealot`** *(unve
 `frank-dragoon`/`frank-zealot`/`frank-archon`, per the cards in
 `shared/homepage/services.json`)*.

-| Connection (`openai.api_configs` idx) | URL as recorded 2026-10-09 | Enabled | `model_ids` | Runtime | Host |
-|---|---|---|---|---|---|
-| 0 | `http://host.containers.internal:7770/v1` | no (2026-10-07) | `frank-dragoon` | halogen flash-server (Strix Halo iGPU) | Dankclaw |
-| 1 | `http://192.168.0.235:7770/v1` | no (2026-10-07) | `frank-archon` | radiance TP=2 (2× R9700) | Dankserver |
-| 2 | `http://host.containers.internal:7771/v1` | yes | `frank-zealot` | llama.cpp CUDA (RTX 3090; production shape 2×262,144 exact f16 KV per `scripts/frank-zealot.env`) | Dankclaw |
+| Connection (`openai.api_configs` idx) | URL as recorded 2026-10-09 | Enabled | `model_ids` | Endpoint page |
+|---|---|---|---|---|
+| 0 | `http://host.containers.internal:7770/v1` | no (2026-10-07) | `frank-dragoon` | [[frank-dragoon]] |
+| 1 | `http://192.168.0.235:7770/v1` | no (2026-10-07) | `frank-archon` | [[frank-archon]] |
+| 2 | `http://host.containers.internal:7771/v1` | yes | `frank-zealot` | [[frank-zealot]] |

 The URLs in the first column are the DB's recorded values and predate the 2026-08-22
 bridge move; on this network they are wrong — see the reachability gotcha below, which
-is the corrected law. Note also that the 2026-10-18 **bench window** on `:7771`
-closed the same day (production unit stopped 03:38 per the repo Benchmarking
-Policy while candidate arms held the port): the candidate — Ternary-Bonsai-2-**9B**
-PQ2_0 with the MTP head, deployed that afternoon at 3 × 262,144 q8_0 KV and
-resliced the same evening to **2 × 262,144 over exact f16 KV** — was **deployed
-as production**, so the
-picker row below was re-keyed to it (see the next paragraph).
+is the corrected law. The picker row for `frank-zealot` was re-keyed on 2026-10-18 after
+that day's payload swap (see [[frank-zealot]] for what was deployed and when).

 The `model` table carries exactly two decoration rows, `frank-zealot` and
 `frank-dragoon`. Both the context length and the description live **inside
 JSON columns** — `params` holds `{"context": {"length": …}}` and `meta` holds
 `{"description": …}`; there is no `context_length` or `description` column, so
-`sqlite3` one-liners against those names fail. Re-keyed 2026-10-18:
-`frank-zealot` → 262,144 with the Bonsai-2-9B description, and `frank-dragoon`
-→ 200,704 (its `params` had kept the pre-lowering 262,144 window from
-2026-10-17 while its own description already said 200,704). These rows are
+`sqlite3` one-liners against those names fail. `params.context.length` is a copy
+of the endpoint's per-slot window, so the authoritative number lives on the
+endpoint page ([[frank-zealot]], [[frank-dragoon]]) and the row must follow it —
+the 2026-10-18 re-key existed because `frank-dragoon`'s row still carried the
+window its payload had before that day's swap. These rows are
 live DB state, so a payload swap must re-key the database too, not only the
 repo. There is no `sqlite3` binary on Dankclaw — use `python3 -c` with the
 stdlib `sqlite3` module, and take a `Connection.backup()` snapshot first (the
@@ -106,10 +102,10 @@ Two gotchas make the wiring non-obvious:
 The Ollama connection is disabled (`ollama.enable=false`).

 > All three endpoints are bare-metal systemd services managed by this
-> repository. Model swaps, context sizing, and spec tuning happen there. See
-> the [LLM knowledge base](../LLM/index.md). Disabling a connection here only
-> hides it from this picker — the endpoint itself keeps serving every other
-> client (the harness, Hermes, API consumers).
+> repository; their shape, swaps and tuning live on
+> [[frank-dragoon]] / [[frank-zealot]] / [[frank-archon]]. Disabling a
+> connection here only hides it from this picker — the endpoint itself keeps
+> serving every other client (the harness, Hermes, API consumers).

 ## Container introspection (DB and backend python)

@@ -145,9 +141,9 @@ The Ollama connection is disabled (`ollama.enable=false`).
   models. Response key is `items`, not `data`.
 2. `POST /api/chat/completions` per model with a trivial prompt ("Reply
   with exactly one word: pong") → each returns content `pong`. Reasoning
-   models need a generous budget: frank-zealot (Qwen3.5 template) returns
-   empty content + `finish_reason: "length"` at `max_tokens 200` (the
-   thinking block eats it) and answers `pong` at 1500.
+   endpoints need a generous budget: thinking consumes `max_tokens`, so a short
+   one returns empty content + `finish_reason: "length"` (see
+   [[frank-zealot]]); `frank-zealot` answers `pong` at 1500.
 3. A 500 "Server Connection Error" → `podman logs open-webui` for
   `ClientConnectorError`: a network-reachability problem (host LAN IP vs
   `host.containers.internal`), not a model problem.
@@ -340,8 +336,8 @@ neither.

 - The image tracks upstream `main`; pin a digest in the quadlet unit if reproducible rollback matters more than tracking. (The old "CPU-only host" framing is stale: this APU runs the gfx1151 ROCm build — see [[ComfyUI]].)
 - The default admin account is created on first login; secure it immediately.
- If the backend is loading (3–8 minute model load), OpenWebUI shows connection errors until the model is ready.
- The on-host LLM services (Dankclaw `:7770`, `:7771`) are reached via the **host LAN IP `192.168.0.143`**, which is exactly what the deployed unit does (`open-webui.container:32`). The older "use `host.containers.internal`" advice is retired for this container: it is a slirp4netns/pasta-only name and the unit has been on the pinned bridge `systemd-open-webui` since 2026-08-22, where that name does not resolve (`open-webui.network:15-19`). Both endpoints are published on all interfaces today (`ss -ltn` → `*:7770`, `0.0.0.0:7771`; `curl http://192.168.0.143:7771/health` → 200, 2026-10-18). The Dankserver backend is a different host, reached via its LAN IP `192.168.0.235:7770`.
+- If the backend is loading, OpenWebUI shows connection errors until the endpoint is ready; each endpoint's boot budget is on its own page ([[frank-dragoon]], [[frank-zealot]], [[frank-archon]]).
+- Repeated from *The LLM backends*: the on-host endpoints are reached via the **host LAN IP**, never `host.containers.internal`.

 ## History

@@ -390,4 +386,4 @@ neither.
 - [[Frank TTS]] — the speech endpoint behind *Text-to-speech (frank-tts)*
 - [[Hermes]] — the agent OpenWebUI can talk to
 - [[SearXNG]] — the search engine on this host
- [LLM knowledge base](../LLM/index.md) — the vLLM and llama.cpp endpoints
+- [[frank-dragoon]] / [[frank-zealot]] / [[frank-archon]] — the endpoints behind the picker
@@ -36,14 +36,14 @@ it is not invisible.
 ## Why 64 GiB

 Dankclaw is shared. The 2026-09-12 decision measured `frank-dragoon` alone holding
-**103.5 GiB of the 121.2 GiB** host (`68.0` weights + `14.4` KV pool + `21.1`
-working), leaving roughly **7.1 GiB** for the then-28 co-tenant containers whose
-working set was ~4.3 GiB. That is a decision-time reading, not today's: on
+**103.5 GiB of the 121.2 GiB** host, leaving roughly **7.1 GiB** for the then-28
+co-tenant containers whose working set was ~4.3 GiB. How that total is split
+between weights, KV pool and working memory is the engine's own ledger — it lives
+on [[frank-dragoon]]. That is a decision-time reading, not today's: on
 2026-10-18 the host reports **91 GiB used / 29 GiB available of 121 GiB**
 (`free -h`), 30 containers are up (`podman ps -q | wc -l`), and the
 `frank-dragoon-halogen` container accounts for **70.33 GiB**
-(`podman stats --no-stream`, same day) on the current flash-server payload —
-a different model and KV shape than the one measured in September.
+(`podman stats --no-stream`, same day).
 The engine itself warned at the time that when the headroom runs out,
 frank-dragoon and its neighbours "can stall for minutes at a time at full CPU with
 no disk activity and no output". Swap is the valve that turns an OOM kill into slow
@@ -59,7 +59,7 @@ like this, **never `swapoff` before the replacement is online.** The old 8 GiB
 held 4 GiB of live pages, and `MemAvailable` read 73 GiB while only ~5 GiB was
 genuinely free — the pinned model weights are counted as reclaimable page
 cache, so the headline number is a lie by roughly the size of the model
-(see [[halogen-flash-server]]). Swapping off into that apparent space, with
+(see [[frank-dragoon]]). Swapping off into that apparent space, with
 nothing else to receive the pages, is how you invite the OOM killer.

 The ordering that avoids it — create and enable the new swap **first**, so the
@@ -113,10 +113,10 @@ frank-dragoon `health=200` throughout.

 ## Caveats

- **Swap cannot help the pinned weights.** frank-dragoon's ~68 GiB of weights are
-  held deliberately; paging them is a stall, not a relief. More swap does not
-  make the doubled KV pool affordable — see the reserve/pool ceiling in
-  [[halogen-flash-server]].
+- **Swap cannot help the pinned weights.** frank-dragoon's weights are pinned
+  deliberately; paging them is a stall, not a relief. More swap does not make a
+  larger KV pool affordable — see the reserve/pool ceiling in
+  [[frank-dragoon]].
 - **`vm.swappiness=60` is untested against this workload.** Under real
  pressure the kernel will happily page anonymous memory, and frank-dragoon's KV
  pool and working set *are* anonymous. Swapping the KV pool would be far worse
@@ -151,6 +151,6 @@ The old swapfile has therefore been purged; nothing on the host still holds it.

 ## See Also

- [[halogen-flash-server]] — the memory model that motivated this
+- [[frank-dragoon]] — the memory model that motivated this
 - [[Dankclaw System Specs]] — the Strix Halo box
 - [[Dankclaw Improvements]] — other host-level changes
@@ -233,12 +233,12 @@ loud, not a bug. Work through it in order:
  they have to be copied there once before a build.
 - `VOICE_PACK_TOOL` points at the trial's build tree
  (`/home/dank/voice-audition/qwentts/qwentts.cpp/build/qwen-codec`, checked out
-  at exactly `5916bf7c`), and the two GGUFs at
-  `/home/dank/models/Qwen3-TTS-GGUF/`, which is where the engine slice's
-  download script puts them — that directory does not exist yet, so until it
-  does the models have to come from the trial's `models/` directory.
- Nothing is deployed: nothing listens on 7772 or 8880 today, so building packs
-  is possible on that host while serving them is not.
+  at exactly `5916bf7c`), and the two GGUFs live at
+  `/home/dank/models/Qwen3-TTS-GGUF/`, the engine slice's fetch target — that
+  path and its fetch state belong to [[Frank TTS Engine]].
+- Whether the façade (7772) and the engine (8880) are up and serving is deploy
+  state on [[Frank TTS]] / [[Frank TTS Engine]] — read it there, not from this
+  census.

 ## Known gaps, on purpose