feat(frank-tts-engine): the arm A engine as a boot-persistent quadlet unit

Repo state only: nothing deployed, no host touched, no container started. - `frank-tts-engine` on Dankclaw: `qwentts.cpp` commit 5916bf7c79dbb4e66fc059cdc507a79a23a28bb4, resident `tts-server`, 1.7 B base talker Q4_K_M + Q8_0 tokenizer, container port 8880. It is deliberately NOT a fleet endpoint — `frank-tts` on 7772 is the endpoint consumers address. - Publishes NOTHING. A host-loopback publish would have been useless to the façade (netavark DNATs published ports only, so a bridge container cannot reach a host loopback bind — the shape that 502'd hermes) and would have been the one LAN-reachable surface of an unauthenticated synthesiser. Both voice containers sit on one committed quadlet network, `frank-tts-engine.network` pinned to 10.89.5.0/24 (next free /24 after open-notebook's 10.89.4.0/24), and peers address the engine by container name. Diagnostics and the deployer's health gate run inside the netns (`podman exec`, `wait_container_healthy`). - Cold-voice law honoured in the unit: the first request for a registered voice decodes its whole reference to snapshot codec state (6.2-8.0 s, first audio byte 5 530 ms), later ones restore in 0.5 ms, and the registry is memory-only. `ExecStartPost=-/usr/bin/podman exec frank-tts-engine /app/warm-voices.sh` with `TimeoutStartSec=900`; the `-` prefix keeps a failed warm from crash-looping the endpoint under `Restart=always`. It logs cold=/warm= per voice, so the under-a-second second request is proven on every boot. - Thread law recorded: `tts-server` has no `--threads`; src/backend.h uses hardware_concurrency()/2, so a cpuset pin silently changes the thread count. - Image builds from the pinned commit with the proven line (GGML_BLAS=OFF forced by this host, every GPU backend off, -j 8, no -DGGML_NATIVE because ggml defaults to -march=native for the building host). Two stages; the runtime stage COPYs both the entrypoint and the warmer, because a container that publishes nothing is reached with `podman exec`, not a port. - `scripts/download-frank-tts-engine-qwentts.sh` fetches the two GGUFs with byte and LFS-oid checks (talker 1 219 245 248 B, tokenizer 291 150 624 B); the deployer gates on --verify-only instead of pulling 1.4 GiB mid-deploy. - Registered in SERVICE_ORDER, DANKCLAW_SERVICES, the deploy-remote.sh dispatch, its pre-deploy requirement, deploy.sh's regex, the planner's path map (the whole `dankclaw/voiceservice/` tree mapped to nothing before this), and test-changed.sh ABOVE the `dankclaw/*.container` case whose `*` crosses `/`. - New seam tests/frank_tts_engine.bats (19): the Quadlet generator's own output for network/publish/boot/warm shape, entrypoint argv driven from the tracked env file, the warmer against a stub tts-server over a real socket (registration keys, ref_text absent, late engine, hung synthesis, name refusal), the fetcher's verifier, the pinned cmake line, and both routing tables. Suite: 422 passed. - Vault: [[Frank TTS Engine]] linked from the index; log.md entry for the day.
Merge pull request 'docs(tts): record the measured CPU engine A/B behind frank-tts' (#10 ) from docs/tts-engine-trials into main
2026-10-18 17:26:50 -07:00 · 2026-10-18 17:15:00 -07:00 · 2026-10-18 16:54:13 -07:00 · 2026-10-18 16:51:01 -07:00 · 2026-10-18 16:51:01 -07:00 · 2026-10-18 16:50:47 -07:00
25 changed files with 2918 additions and 25 deletions
@@ -79,3 +79,23 @@ MARRETA_APP_KEY=changeme
 # account on first boot from these values.
 MARRETA_ADMIN_EMAIL=admin@franksdank.cloud
 MARRETA_ADMIN_PASSWORD=changeme
+
+# open-notebook (podcast generator; internal-only, no vhost).
+# deploy-remote.sh seeds /home/dank/Containers/open-notebook/env from these
+# values (only if that file does not already exist) and refuses to start the
+# units while any of them is blank: a blank OPEN_NOTEBOOK_PASSWORD means
+# authentication OFF, and a blank encryption key means no provider credential
+# can be saved. The seed writes SURREAL_PASS too — the spelling the `surreal`
+# CLI reads — from SURREAL_PASSWORD, so the app and the database cannot be
+# given different values.
+# OPEN_NOTEBOOK_ENCRYPTION_KEY: encrypts the stored AI provider keys at rest.
+#   Generate: openssl rand -hex 32
+# Changing it after credentials are saved makes them undecryptable.
+OPEN_NOTEBOOK_ENCRYPTION_KEY=changeme
+# UI/API password. Every API route — including the episode-audio download the
+# app serves without a session — is open to the LAN while this is unset.
+OPEN_NOTEBOOK_PASSWORD=changeme
+# SurrealDB root password (the root user NAME comes from
+# scripts/open-notebook.env, so this file holds only the secret).
+#   Generate: openssl rand -base64 32
+SURREAL_PASSWORD=changeme
@@ -0,0 +1,84 @@
+# Quadlet unit: open-notebook's SurrealDB (rootless, boot-persistent).
+#
+# Install path on dankclaw: ~/.config/containers/systemd/open-notebook-surrealdb.container
+# Unit name: open-notebook-surrealdb.service (container name: open-notebook-surrealdb)
+#
+# WHAT IT IS. open-notebook's only datastore: notebooks, notes, sources,
+# provider credentials and podcast episodes all live here. The app talks to it
+# over the WebSocket RPC on the private bridge (SURREAL_URL in
+# scripts/open-notebook.env), which is why the container NAME is part of the
+# contract — renaming it breaks the app's database URL, not just this file.
+#
+# IMAGE. `surrealdb/surrealdb:v2` pinned by manifest-list digest, resolved from
+# the registry on 2026-10-18 (that digest is SurrealDB 2.7.0, image built
+# 2026-09-23; `v2` itself is a MOVING tag, so the digest — not the tag — is what
+# makes this reproducible). Upstream open-notebook's own compose file pins the
+# same `v2` tag, and its Dockerfile copies /surreal out of the same image for
+# the retired single-container variant, so v2 is the version this app is built
+# against. Pull=never + the documented pull step (docs: [[Open Notebook]]):
+#
+#   podman pull docker.io/surrealdb/surrealdb:v2@sha256:e5d7387e3727bbe2f7cd6d869e48cd34777272258572ead37c9656b25f745723
+#
+# NO PUBLISHED PORT. 8000 is deliberately not published: the app reaches it by
+# name on systemd-open-notebook, and a published 8000 would put the RPC with
+# the root credentials on every interface (upstream publishes 127.0.0.1:8000
+# "purely for local debugging" — a `podman exec` probe is enough here). The
+# binary binds 0.0.0.0:8000 INSIDE its own namespace via the image's
+# SURREAL_BIND env; without that image default it would bind loopback only and
+# the app could never connect, so no --bind flag belongs here.
+#
+# CREDENTIALS, AND WHY THEY ARE NOT IN THE COMMAND LINE. The `surreal start`
+# CLI reads its options from the environment (`--username` is [env:
+# SURREAL_USER=], `--password` is [env: SURREAL_PASS=] — verified against the
+# pinned image's own `start --help`), so the credentials arrive through the two
+# EnvironmentFile lines and the argv stays clean. Passing `--pass` instead —
+# what upstream's compose does — would put the database password in
+# /proc/<pid>/cmdline, readable by any `ps` on the host. Note the two
+# spellings: the DATABASE reads SURREAL_PASS, the APP reads SURREAL_PASSWORD,
+# and scripts/open-notebook.env declares both because they must hold the same
+# value; the deployer writes that pair when it seeds the host secret file.
+#
+# NO USER= OVERRIDE. The image runs as uid 65532 (Chainguard glibc-dynamic
+# base). With a NAMED volume that works unmodified: podman creates the volume's
+# backing directory owned by the container's user (measured with this digest —
+# the host directory lands on the mapped subuid and the store starts clean),
+# which is exactly why upstream's `user: root` line is not repeated here: that
+# line is commented in upstream as being "required for bind mounts", and this
+# unit has none. The consequence is that the DB files are NOT readable by dank
+# without `podman unshare` — accepted for a datastore nobody edits by hand;
+# episode AUDIO is a host directory for the opposite reason (see the app unit).
+#
+# HEALTH. The base image is distroless: no shell, no curl, no wget, so no
+# CMD-SHELL probe and no wget/curl probe is possible here (same class of unit
+# as loki, whose probe had to move into the image). SurrealDB ships its own
+# probe instead — `surreal is-ready` connects to ws://localhost:8000 by default
+# and needs no credentials — verified against this digest: it prints `OK` and
+# exits 0 while the server is up. Argument-only HealthCmd, like every unit on
+# this host, because the quadlet generator splits it on spaces.
+
+[Unit]
+Description=SurrealDB (open-notebook datastore)
+After=network-online.target
+Wants=network-online.target
+
+[Container]
+ContainerName=open-notebook-surrealdb
+Image=docker.io/surrealdb/surrealdb:v2@sha256:e5d7387e3727bbe2f7cd6d869e48cd34777272258572ead37c9656b25f745723
+Pull=never
+Network=open-notebook.network
+EnvironmentFile=/home/dank/serverAppConfigs/scripts/open-notebook.env
+EnvironmentFile=/home/dank/Containers/open-notebook/env
+Exec=start --log info rocksdb:/mydata/mydatabase.db
+Volume=open-notebook-db:/mydata
+HealthCmd=/surreal is-ready
+HealthInterval=30s
+HealthTimeout=10s
+HealthRetries=3
+HealthStartPeriod=20s
+
+[Service]
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=default.target
@@ -0,0 +1,101 @@
+# Quadlet unit: open-notebook (rootless, boot-persistent).
+#
+# Install path on dankclaw: ~/.config/containers/systemd/open-notebook.container
+# Unit name: open-notebook.service (container name: open-notebook)
+#
+# WHAT IT IS. The fleet's podcast generator: notes and sources go in, a
+# two-voice (up to four) episode MP3 comes out. One image runs THREE processes
+# under supervisord — the FastAPI API on 5055, the background worker that
+# writes and speaks the episode, and the Next.js UI on 8502 — so this one unit
+# owns the whole app, and the frontend refuses to start until the API answers
+# (the image's own wait-for-api.sh). Runbook: [[Open Notebook]].
+#
+# IMAGE. `lfnovo/open_notebook:v1-latest` pinned by manifest-list digest,
+# resolved from the registry on 2026-10-18; it is the tag upstream's own
+# docker-compose.yml pins for the multi-container shape. Do NOT reach for the
+# `-single` tags: that variant bundles SurrealDB inside the app image, is
+# deprecated upstream, and would give this host two databases. Pull=never, so
+# the pin is fetched by the documented one-time step (docs: [[Open Notebook]]),
+# which the deployer also runs when the image is absent:
+#
+#   podman pull docker.io/lfnovo/open_notebook:v1-latest@sha256:54b2025a4a4853c188f74b9b8246eca8c5480e5dd1babfa92db1038ff2f30212
+#
+# NETWORKS, in this order on purpose. The generated run line keeps file order,
+# so the DEFAULT ROUTE rides dankclaw_default: that is the network where this
+# host has measured that a bridge container can reach a host-namespace
+# listener through the gateway name (the Prometheus scrape of frank-zealot is
+# the proof — see [[Container Network Namespaces]]), and frank-tts lives there
+# too, so the TTS credential can be `http://frank-tts:7772/v1`. The private
+# systemd-open-notebook bridge is second and carries only the database; its
+# traffic is on-link, so losing the default route costs it nothing.
+#
+# PUBLISHED PORTS, and the 5055 collision. Upstream publishes 8502 and 5055,
+# and 5055 is exactly the port seerr already holds on this host
+# (`PublishPort=127.0.0.1:5055:5055`; `ss -ltn` on Dankclaw 2026-10-18 shows
+# 127.0.0.1:5055 taken). So the API leaves the container on host port 5056.
+# That forces one setting: the frontend auto-detects the API as
+# `<host-you-opened>:5055`, so API_URL in scripts/open-notebook.env must name
+# the remapped port explicitly, or the UI loads and every call fails. Both
+# ports are published on all interfaces because the consumer is a browser on
+# the LAN — the fleet's browser-facing services (open-webui, comfyui, gitea)
+# bind the same way, while loopback-only is reserved for services whose user
+# path is the guard chain. This service has NO vhost and no Caddy route: it is
+# internal-only until it is guarded, and its own password
+# (OPEN_NOTEBOOK_PASSWORD) is what stands in front of it. That password is not
+# decoration: with it unset the API answers everyone on the LAN, including the
+# unauthenticated episode-audio download.
+#
+# VOLUMES. `/app/data` is a named volume: uploads, the LangGraph SQLite
+# checkpoints and the extraction caches the image keeps under it
+# (UV_CACHE_DIR, HF_HOME) are app state nobody browses. The ONE exception is
+# finished audio, which is bind-mounted out of the container at
+# /home/dank/media/podcasts. That mount is interim and reversible: episode
+# destination is an open human-only decision (Gitea issue #7, label
+# `human-only` — agents must not work it), and until it lands, episodes are
+# ordinary files on the host. DATA_FOLDER is hard-coded `./data` in the app
+# (WORKDIR /app) and the DB stores audio paths RELATIVE to data/podcasts, so
+# covering that one subdirectory is enough and removing the line changes
+# nothing else. The image declares no USER, so the app runs as container root,
+# which in this host's rootless mapping (0 -> 1000, measured on this host —
+# see [[Seerr]]) writes those episode files as dank.
+#
+# HEALTH. `GET /health` on the API returns {"status":"healthy"} and is in the
+# password middleware's excluded-path list, so the probe stays honest after the
+# password is set (both read from api/main.py upstream). The image installs
+# curl and ffmpeg in the runtime layer, so the probe needs no shell — kept
+# argument-only for the generator's space-splitting. Note what this probe does
+# NOT prove: the route returns a static body, so it says the API serves, not
+# that the database answers. The DB has its own probe in its unit, and the
+# worker's failure to reach the database shows up as failed jobs, not as an
+# unhealthy container.
+
+[Unit]
+Description=open-notebook (podcast generator: API, worker, web UI)
+After=network-online.target open-notebook-surrealdb.service
+Wants=network-online.target open-notebook-surrealdb.service
+
+[Container]
+ContainerName=open-notebook
+Image=docker.io/lfnovo/open_notebook:v1-latest@sha256:54b2025a4a4853c188f74b9b8246eca8c5480e5dd1babfa92db1038ff2f30212
+Pull=never
+Network=dankclaw_default
+Network=open-notebook.network
+PublishPort=0.0.0.0:8502:8502
+PublishPort=0.0.0.0:5056:5055
+EnvironmentFile=/home/dank/serverAppConfigs/scripts/open-notebook.env
+EnvironmentFile=/home/dank/Containers/open-notebook/env
+Volume=open-notebook-data:/app/data
+Volume=/home/dank/media/podcasts:/app/data/podcasts
+HealthCmd=curl -fsS http://127.0.0.1:5055/health
+HealthInterval=30s
+HealthTimeout=10s
+HealthRetries=3
+HealthStartPeriod=60s
+
+[Service]
+Restart=always
+RestartSec=10
+TimeoutStartSec=900
+
+[Install]
+WantedBy=default.target
@@ -0,0 +1,34 @@
+# Quadlet network: private bridge for the open-notebook pair (rootless).
+#
+# Install path on dankclaw: ~/.config/containers/systemd/open-notebook.network
+# Unit name: open-notebook-network.service (podman network name:
+# systemd-open-notebook — quadlet prefixes "systemd-", so probe the runtime
+# name, never the filename; see [[Container Network Namespaces]]).
+#
+# WHY A PRIVATE BRIDGE. The app reaches its database by container name
+# (SURREAL_URL=ws://open-notebook-surrealdb:8000/rpc), and container DNS names
+# resolve only on the network that owns them. Putting SurrealDB here instead of
+# on dankclaw_default keeps the datastore reachable ONLY to the container that
+# owns it: 8000 is not published (an unpublished port is refused outright from
+# every other namespace anyway), and nothing else on the fleet-wide network can
+# dial it with the root credentials. Same reasoning as the gitea and authentik
+# database pairs.
+#
+# Kernel bridge, not slirp4netns: the 2026-08-22 open-webui incident (a dead
+# per-container userspace helper left a container that accepted TCP and reset
+# every request for two days, logging nothing). A bridge has no such helper.
+#
+# Subnet registry on dankclaw (rootless):
+#   10.88.0.0/16  default "podman" bridge
+#   10.89.0.0/24  gitea (systemd-gitea)
+#   10.89.1.0/24  compose stack (dankclaw_default)
+#   10.89.2.0/24  searxng (systemd-searxng)
+#   10.89.3.0/24  open-webui (systemd-open-webui)
+#   10.89.4.0/24  open-notebook (systemd-open-notebook)  <- this file
+# Pinned so the container IPs stay deterministic across reboots, like the
+# other pinned nets; 10.89.4.0/24 was the next unclaimed /24 in this registry.
+
+[Network]
+Driver=bridge
+Subnet=10.89.4.0/24
+Gateway=10.89.4.1
@@ -0,0 +1,131 @@
+# frank-tts-engine — the arm A TTS engine: qwentts.cpp's resident `tts-server`
+# (the CPU binary that frank-tts on :7772 forwards to). The runbook is
+# [[Frank TTS Engine]]; the fleet-facing endpoint is [[Frank TTS]].
+#
+# WHAT THIS IS. The upstream source is NOT vendored here: the image clones
+# ServeurpersoCom/qwentts.cpp at one pinned commit and builds it. Rebuilding is
+# therefore a network operation (github.com plus objects.githubusercontent.com
+# for the `ggml` submodule), and build_compose_image in scripts/deploy-remote.sh
+# skips it whenever this Containerfile's sha256 label already matches the built
+# image — the same offline-safe idiom as loki/alloy/comfyui, so a re-deploy of
+# an unchanged engine needs no network.
+#
+# THE PINNED COMMIT IS THE CONTRACT. 5916bf7c79dbb4e66fc059cdc507a79a23a28bb4
+# is the commit the 2026-10-18 CPU trial on Dankclaw measured (server-side TTFA
+# 94-112 ms, warm RTF 0.55-0.67, run spread +-0.01 — the numbers that won the
+# engine decision). Moving it means re-measuring, not just editing this line.
+# `ggml` is a submodule of the repo (the only one; vendor/cpp-httplib and
+# vendor/yyjson are ordinary directories in the tree), and the submodule commit
+# is recorded in the parent tree, so cloning the parent commit recursively is
+# reproducible without a second pin.
+#
+# THE BUILD LINE IS THE ONE PROVEN ON DANKCLAW, verbatim:
+#
+#   cmake -B build -DCMAKE_BUILD_TYPE=Release -DGGML_CCACHE=OFF \
+#       -DGGML_BACKEND_DL=OFF -DGGML_CPU_ALL_VARIANTS=OFF -DGGML_OPENMP=ON \
+#       -DGGML_BLAS=OFF -DGGML_CUDA=OFF -DGGML_HIP=OFF -DGGML_VULKAN=OFF \
+#       -DGGML_METAL=OFF -DGGML_SYCL=OFF -DGGML_RPC=OFF \
+#   && cmake --build build -j 8
+#
+# Every flag is load-bearing, so do not "tidy" it:
+#   GGML_BLAS=OFF is FORCED, not a preference — Dankclaw has libopenblas.so.0
+#     but no BLAS dev headers, so the upstream default (BLAS on) fails to
+#     configure. Upstream's own Dockerfile and buildcpu.sh both pass BLAS on,
+#     which is why this file does not copy them.
+#   GGML_CCACHE=OFF because a container build layer has no persistent ccache
+#     directory to hit; on, it only writes a useless one.
+#   GGML_OPENMP=ON is what makes the runtime need libgomp1 (installed below).
+#   GGML_BACKEND_DL=OFF / GGML_CPU_ALL_VARIANTS=OFF: upstream's images build
+#     every x86 ISA as a loadable backend so one image runs anywhere. This one
+#     is built on the machine that runs it, so the single native CPU backend is
+#     what was measured. That is also why no -DGGML_NATIVE is passed: ggml
+#     defaults it ON outside wasm/cross-compiles, i.e. -march=native for THIS
+#     host — correct while build host == run host, wrong if anyone ever builds
+#     this image elsewhere, which is why the fleet builds it on Dankclaw.
+#   CUDA/HIP/VULKAN/METAL/SYCL/RPC all OFF: this is a CPU endpoint (the trial
+#     ran on CPU; the box's GPUs belong to the text endpoints).
+#
+# BUILD SHARED LIBS, RUNTIME SMALL. BUILD_SHARED_LIBS defaults ON on Linux, so
+# tts-server links libggml*.so rather than swallowing them; the runtime stage
+# copies the binary and its shared objects out of the build tree and points
+# LD_LIBRARY_PATH at them, exactly as upstream's own Dockerfile does (the RPATH
+# baked at link time names the build directory, which does not exist here).
+#
+# BASE PINNED BY DIGEST, like every other image this fleet builds: the digest
+# is the multi-arch INDEX of ubuntu:24.04 as resolved from Docker Hub on
+# 2026-10-18; Dankclaw takes the amd64 entry. One base for both stages so there
+# is exactly one thing to re-resolve.
+#
+# NO HEALTHCHECK IN THIS FILE. The probe lives in the Quadlet unit
+# (HealthCmd=), which is the fleet pattern for anything with a shell — see the
+# alertmanager/prometheus units, and the opposite case in dankclaw/loki, whose
+# distroless image has no /bin/sh for the generator's CMD-SHELL wrapping.
+# `curl` is therefore installed in the runtime stage, for that probe only.
+
+ARG BASE_IMAGE=docker.io/library/ubuntu:24.04@sha256:68ee22004a9109b44973313b02ff7b1de250f1de0f5ecb628d73f579aaff33ac
+
+# ------------------------------------------------------------------ build
+FROM ${BASE_IMAGE} AS build
+
+RUN apt-get update -qq \
+    && apt-get install -y -qq --no-install-recommends \
+        ca-certificates cmake g++ git make \
+    && rm -rf /var/lib/apt/lists/*
+
+# Checked out detached at a full SHA, then the recorded submodule. No branch
+# name anywhere: a branch moves, this commit does not.
+ARG QWENTTS_COMMIT=5916bf7c79dbb4e66fc059cdc507a79a23a28bb4
+RUN git clone --no-checkout https://github.com/ServeurpersoCom/qwentts.cpp /src \
+    && git -C /src checkout --detach "${QWENTTS_COMMIT}" \
+    && git -C /src submodule update --init --depth 1 \
+    && git -C /src rev-parse HEAD \
+    && git -C /src submodule status
+
+WORKDIR /src
+RUN cmake -B build -DCMAKE_BUILD_TYPE=Release \
+        -DGGML_CCACHE=OFF \
+        -DGGML_BACKEND_DL=OFF \
+        -DGGML_CPU_ALL_VARIANTS=OFF \
+        -DGGML_OPENMP=ON \
+        -DGGML_BLAS=OFF \
+        -DGGML_CUDA=OFF \
+        -DGGML_HIP=OFF \
+        -DGGML_VULKAN=OFF \
+        -DGGML_METAL=OFF \
+        -DGGML_SYCL=OFF \
+        -DGGML_RPC=OFF \
+    && cmake --build build -j 8
+
+# ---------------------------------------------------------------- runtime
+FROM ${BASE_IMAGE}
+
+# libgomp1: the OpenMP runtime the build above links against. curl: the unit's
+# HealthCmd. ca-certificates: so that curl can speak https if anyone ever
+# points a probe at a URL with a scheme this host terminates elsewhere.
+RUN apt-get update -qq \
+    && apt-get install -y -qq --no-install-recommends \
+        ca-certificates curl libgomp1 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Same unprivileged uid as the frank-tts façade (10000): the voice packs and the
+# model directory are host state mounted read-only, and one uid across the pair
+# means one thing to remember about what is world-readable.
+RUN adduser --system --uid 10000 --home /app --shell /usr/sbin/nologin tts
+
+WORKDIR /app
+COPY --from=build /src/build/tts-server /src/build/*.so* /app/
+COPY dankclaw/voiceservice/tts-engine-start.sh /app/start.sh
+# The boot warmer lives INSIDE the image because the engine publishes no port:
+# the unit reaches it with `podman exec`, and the script needs the same curl,
+# base64 and /voices the engine's own namespace has. It is a sibling of
+# start.sh, not a second entrypoint — CMD stays the server.
+COPY dankclaw/voiceservice/tts-engine-warm.sh /app/warm-voices.sh
+RUN chmod 755 /app/start.sh /app/warm-voices.sh
+
+# The binary's RPATH points inside the build tree; this is what makes it find
+# the libggml*.so copied beside it.
+ENV LD_LIBRARY_PATH=/app
+
+USER tts
+EXPOSE 8880
+CMD ["/app/start.sh"]
@@ -0,0 +1,112 @@
+# Quadlet unit: frank-tts-engine (rootless, boot-persistent).
+#
+# Install path on dankclaw: ~/.config/containers/systemd/frank-tts-engine.container
+# Unit name: frank-tts-engine.service (container name: frank-tts-engine)
+#
+# WHAT IT IS. The arm A TTS engine: qwentts.cpp (pinned commit
+# 5916bf7c79dbb4e66fc059cdc507a79a23a28bb4) built into an image by
+# dankclaw/voiceservice/Containerfile.engine, running its resident `tts-server`
+# with the 1.7 B base talker Q4_K_M and the Q8_0 12 Hz tokenizer loaded ONCE at
+# startup. It is deliberately NOT a fleet endpoint: the endpoint consumers
+# address is **frank-tts on 7772** ([[Frank TTS]]), which resolves voice names,
+# re-encodes to mp3 and owns the timeout budget. Runbook: [[Frank TTS Engine]].
+#
+# WHY THIS ENGINE (Frank's call, 2026-10-18, criterion "whatever is better for
+# live output"): server-side time-to-first-audio 94-112 ms (86-451 ms end to
+# end through the façade), streaming that stays ahead of real time at warm RTF
+# 0.55-0.67, and a run-to-run spread of +-0.01 — against the mainline CLI path's
+# 0.93-0.99 at +-0.25, which crosses 1.0 often enough to stall a live stream.
+# The A/B that decided it is "Decision: arm A for live output" in
+# [[Local TTS and Voice Cloning]].
+#
+# IMAGE. Built locally by deploy-remote.sh (build_compose_image), like
+# loki/alloy/frank-tts. `Pull=never` plus the `localhost/` prefix are required:
+# this host's quadlet path cannot resolve a locally built tag from local storage
+# otherwise. The build is a network operation (it clones the pinned commit) and
+# is skipped when the Containerfile hash label already matches.
+#
+# NETWORK, AND WHY IT PUBLISHES NOTHING. The container sits on exactly one
+# network: the private `frank-tts-engine.network` (10.89.5.0/24). The façade
+# joins the same network and dials `http://frank-tts-engine:8880` — the
+# container DNS name, on the network that owns it. There is no `PublishPort` of
+# any kind, not even `127.0.0.1:8880`, and the reason is the lesson that 502'd
+# hermes: netavark DNATs published ports only, so a host-loopback publish is not
+# a path to a peer container — the façade could never have used it, and a bridge
+# container cannot reach the host's own loopback bind either (see
+# [[Container Network Namespaces]]). A publish would therefore buy exactly one
+# thing: an extra reachable surface on an engine that has no authentication, on
+# a box whose CPU is also carrying the text endpoints. Diagnostics do not need
+# it either — `podman exec frank-tts-engine curl http://127.0.0.1:8880/health`
+# speaks to the server from inside its own namespace, which is where the address
+# is valid.
+#
+# MEMORY / NO GPU. Peak RSS measured 5.7 GiB with both GGUFs resident
+# (2026-10-18 trial); no memory limit is set because the box has the room and a
+# limit would convert a busy moment into an OOM kill mid-utterance. No
+# /dev/kfd, no /dev/dri, no keep-groups: every GPU backend is compiled out of
+# the image, the endpoint is CPU-only by decision, and the GPUs on this host
+# belong to the text endpoints.
+#
+# THE VOICE MOUNT IS READ-ONLY AND IS FOR THE WARMER, NOT THE ENGINE. A voice
+# becomes known to the engine only through POST /v1/audio/voices, and the
+# registration is MEMORY ONLY — it does not survive a restart, which is exactly
+# why the warm hook below runs on every start. That hook runs INSIDE this
+# container (see ExecStartPost), so it reads the packs at /voices; `tts-server`
+# itself never opens the directory, it receives the reference audio as base64 in
+# the registration body. The façade mounts the same host directory read-only for
+# its own name list, so one directory stays the single source of a voice name.
+#
+# COLD-VOICE LAW, THE REASON EXECSTARTPOST EXISTS. The FIRST speech request for
+# a registered voice decodes the whole reference clip to snapshot codec state:
+# 6.2-8.0 s, first audio byte at 5,530 ms. Every later request restores the
+# snapshot in 0.5 ms. So the unit warms every voice at boot, serially (~6-8 s
+# each), and `TimeoutStartSec=900` is what keeps a growing voice library from
+# tripping systemd's default 90 s start deadline. The leading `-` on
+# ExecStartPost is load-bearing: with `Restart=always`, a warmer that exits
+# non-zero (a pack missing its reference.wav, the engine still loading past the
+# warmer's own patience) would restart the whole container and crash-loop the
+# endpoint forever. A failed warm must be a journal line, not a restart.
+#
+# The hook is `podman exec`, not a host script, because there is no address the
+# host could dial: this container publishes nothing (above). Exec-ing into it
+# also means the warmer inherits this unit's EnvironmentFile, so every knob it
+# has lives in scripts/frank-tts-engine.env beside the engine's own, and it sees
+# the same /voices and 127.0.0.1:8880 the engine does.
+#
+# HEALTH. `GET /health` answers `{"status":"ok"}` from the HTTP thread, not the
+# synthesis queue, so a busy engine still reads healthy and a dead one does not.
+# HealthStartPeriod covers the first model load. The command is argument-only
+# and needs /bin/sh — the generator wraps HealthCmd as CMD-SHELL — so the image
+# installs curl (see the opposite case in dankclaw/loki, whose distroless base
+# has no shell).
+
+[Unit]
+Description=frank-tts-engine (arm A qwentts.cpp TTS engine, internal :8880)
+After=network-online.target
+Wants=network-online.target
+
+[Container]
+ContainerName=frank-tts-engine
+Image=localhost/franksdank/frank-tts-engine:latest
+Pull=never
+Network=frank-tts-engine.network
+# No PublishPort, at all: the only reachable address this server has is the
+# bridge address the façade resolves by name. Diagnostics use `podman exec`.
+EnvironmentFile=/home/dank/serverAppConfigs/scripts/frank-tts-engine.env
+Volume=/home/dank/models/Qwen3-TTS-GGUF:/models:ro
+Volume=/home/dank/voices:/voices:ro
+HealthCmd=curl -fsS http://127.0.0.1:8880/health
+HealthInterval=30s
+HealthTimeout=10s
+HealthRetries=3
+HealthStartPeriod=120s
+
+[Service]
+Restart=always
+RestartSec=10
+# Model load (tens of seconds) plus one cold decode per registered voice.
+TimeoutStartSec=900
+ExecStartPost=-/usr/bin/podman exec frank-tts-engine /app/warm-voices.sh
+
+[Install]
+WantedBy=default.target
@@ -0,0 +1,52 @@
+# Quadlet network: the private bridge of the voice pair (rootless).
+#
+# Install path on dankclaw: ~/.config/containers/systemd/frank-tts-engine.network
+# Unit name: frank-tts-engine-network.service (podman network name:
+# systemd-frank-tts-engine — quadlet prefixes "systemd-", so probe the runtime
+# name, never the filename; see [[Container Network Namespaces]]).
+#
+# WHY A PRIVATE BRIDGE FOR A PAUSE THAT LOOKS PUBLIC-FACING. frank-tts (:7772,
+# published, the one endpoint consumers address) and frank-tts-engine (:8880,
+# never published, the arm A qwentts.cpp server behind it) could both have
+# stayed on the fleet-wide dankclaw_default and resolved each other by name.
+# They are split off anyway, for two reasons:
+#
+# 1. THE HOST-LOOPBACK TRAP. The phase-1 shape in `scripts/frank-tts.env` still
+#    names `host.containers.internal:8880` as the upstream, on the assumption the
+#    engine runs on the host and publishes `127.0.0.1:8880`. That cannot work:
+#    netavark DNATs published ports only, a published port is not on any podman
+#    bridge, and a container cannot reach the host's own loopback bind — the same
+#    shape that 502'd hermes, and the reason the signal-relay hop needs a host LAN
+#    bind instead ([[Container Network Namespaces]], [[Homepage Status Probes]]).
+#    Putting both containers on one committed network removes the guess: the
+#    façade dials the engine's container DNS name on the network that owns it, and
+#    the engine publishes nothing at all.
+#
+# 2. THE ENGINE HAS NO AUTH AND NO QUEUE LIMIT WORTH THE NAME. `tts-server`
+#    answers anyone who can open a socket, and at `--max-batch 1` a second
+#    caller simply waits behind the first. Left on dankclaw_default every
+#    container on that net — open-webui, hermes, the *arr proxies — could drive
+#    a CPU synthesiser that occupies every other core on a box that also serves
+#    two text endpoints. On this bridge the only dialer is frank-tts: the engine
+#    publishes no port, so not even the host has an address to reach it at, and
+#    diagnostics go through `podman exec` instead.
+#
+# Kernel bridge, not slirp4netns: the 2026-08-22 open-webui incident (a dead
+# per-container userspace helper left a container that accepted TCP and reset
+# every request for two days, logging nothing). A bridge has no such helper.
+#
+# Subnet registry on dankclaw (rootless):
+#   10.88.0.0/16  default "podman" bridge
+#   10.89.0.0/24  gitea (systemd-gitea)
+#   10.89.1.0/24  compose stack (dankclaw_default)
+#   10.89.2.0/24  searxng (systemd-searxng)
+#   10.89.3.0/24  open-webui (systemd-open-webui)
+#   10.89.4.0/24  open-notebook (systemd-open-notebook)
+#   10.89.5.0/24  voice pair (systemd-frank-tts-engine)  <- this file
+# Pinned so the two container IPs stay deterministic across reboots, like the
+# other pinned nets; 10.89.5.0/24 was the next unclaimed /24 in this registry.
+
+[Network]
+Driver=bridge
+Subnet=10.89.5.0/24
+Gateway=10.89.5.1
@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# tts-engine-start.sh — the entrypoint of the frank-tts-engine image
+# (dankclaw/voiceservice/Containerfile.engine). It exists for one reason: the
+# knobs of the arm A engine are command-line flags, while the fleet's knobs
+# live in scripts/frank-tts-engine.env and reach the container through
+# EnvironmentFile=. This is the translation layer, and nothing else — no
+# supervision, no retries, no logging of its own. PID 1 stays the server, so
+# `podman stop` and the unit's Restart=always drive it directly.
+#
+# THE FLAGS THAT ARE NOT HERE, and must stay absent:
+#
+#   --threads / -t   does not exist in this build. src/backend.h computes the
+#                    CPU thread count as std::thread::hardware_concurrency()/2
+#                    (the comment there: GEMM shares SIMD units across
+#                    hyperthreads), and there is no flag to override it. So a
+#                    CPU affinity pin (CPUQuota=, taskset, a cpuset) silently
+#                    changes the engine's thread count instead of just its
+#                    placement — pinning is deliberately not done anywhere in
+#                    this stack. See the env file header for the same warning
+#                    aimed at the operator.
+#   --device         left at its default. Every GPU backend is compiled out of
+#                    the image, so the default device pick can only land on
+#                    CPU; naming a device would add a way to be wrong.
+#
+# Everything defaults to the shape the 2026-10-18 trial measured, so an empty
+# environment still boots the decided configuration: 1.7 B talker Q4_K_M with
+# the Q8_0 tokenizer, one request at a time, on the private bridge.
+set -euo pipefail
+
+# The binary path. Overridable for one reason: the bats seam runs a stub
+# instead of a 1.2 GiB model. Operators never set it — the image ships exactly
+# one binary at /app/tts-server.
+: "${QWENTTS_BIN:=/app/tts-server}"
+
+# Paths are CONTAINER paths (the host directories they come from are named in
+# scripts/frank-tts-engine.env and mounted by the Quadlet unit).
+: "${QWENTTS_MODEL:=/models/qwen-talker-1.7b-base-Q4_K_M.gguf}"
+: "${QWENTTS_CODEC:=/models/qwen-tokenizer-12hz-Q8_0.gguf}"
+
+# Reported by GET /v1/models, and what scripts/frank-tts.env's
+# TTS_UPSTREAM_MODEL names. A model id, not a filename: the file name would
+# leak a quantization choice into every consumer's config.
+: "${QWENTTS_ALIAS:=frank-tts-engine}"
+
+# 0.0.0.0 inside the container is not "public". tts-server defaults to
+# 127.0.0.1, which inside a container netns is reachable by nothing — the
+# façade dials this container by its bridge address. The container publishes
+# 8880 on the host's loopback only (diagnostics and the boot warmer), so the
+# only namespace that can reach 0.0.0.0:8880 here is the private voice bridge.
+: "${QWENTTS_HOST:=0.0.0.0}"
+: "${QWENTTS_PORT:=8880}"
+
+# The language label used when a request omits one. `auto` is the upstream
+# default and what the trial ran.
+: "${QWENTTS_LANG:=auto}"
+
+# One request at a time. The server-side queue is a serialised FIFO at this
+# setting, which is what keeps the measured per-voice timings true; batching
+# on a CPU build splits the same cores between two syntheses and the warm RTF
+# margin (0.55-0.67 against real time 1.0) disappears. The engine's own
+# default is also 1; it is written here because it is a decision, not an
+# accident.
+: "${QWENTTS_MAX_BATCH:=1}"
+
+# Fail loudly BEFORE binding, so the journal says which artifact is missing
+# instead of the unit reporting a container that starts and dies. This is the
+# self-healing path: Restart=always re-runs it every RestartSec, and the same
+# sentence repeats until the operator fetches the weights
+# (scripts/download-frank-tts-engine-qwentts.sh).
+for artifact in "$QWENTTS_MODEL" "$QWENTTS_CODEC"; do
+    if [[ ! -r "$artifact" ]]; then
+        echo "frank-tts-engine: cannot read ${artifact}; run scripts/download-frank-tts-engine-qwentts.sh on the host (the /models mount is read-only and holds the two GGUF files)" >&2
+        exit 1
+    fi
+done
+
+exec "$QWENTTS_BIN" \
+    --model "$QWENTTS_MODEL" \
+    --codec "$QWENTTS_CODEC" \
+    --alias "$QWENTTS_ALIAS" \
+    --host "$QWENTTS_HOST" \
+    --port "$QWENTTS_PORT" \
+    --lang "$QWENTTS_LANG" \
+    --max-batch "$QWENTTS_MAX_BATCH"
@@ -0,0 +1,176 @@
+#!/usr/bin/env bash
+# tts-engine-warm.sh — the boot warmer of the arm A TTS engine, shipped inside
+# the frank-tts-engine image at /app/warm-voices.sh
+# (dankclaw/voiceservice/Containerfile.engine).
+#
+# WHO RUNS IT. Two callers, same binary:
+#
+#   1. The Quadlet unit, as
+#      `ExecStartPost=-/usr/bin/podman exec frank-tts-engine /app/warm-voices.sh`
+#      — after every start of the container, including every boot.
+#      `podman exec` rather than a host script because the engine publishes no
+#      port at all, so there is no address the host could dial; and because an
+#      exec inherits the unit's EnvironmentFile, which is what puts every knob of
+#      this script in scripts/frank-tts-engine.env next to the engine's own.
+#   2. scripts/deploy-remote.sh's deploy_frank_tts_engine, once per deploy, so a
+#      voice that did not warm becomes a deploy result instead of only a journal
+#      line (the unit's `-` prefix deliberately cannot fail the unit).
+#
+# WHY IT EXISTS AT ALL (the cold-voice law). The FIRST speech request for a
+# registered voice decodes the whole reference clip to snapshot its codec state:
+# 6.2-8.0 s, first audio byte at 5,530 ms. Every later request for that voice
+# restores the snapshot in 0.5 ms. Two facts make that a boot problem rather than
+# a curiosity: the voice registry is MEMORY ONLY (a restart forgets every voice),
+# and re-registering a voice does not warm it — only synthesizing does. So a boot
+# that registers the voices and stops leaves the first caller of the day paying
+# 5.5 s of silence. This script speaks one short sentence per voice instead, then
+# speaks a second one so the journal carries the warm number too: the line
+# `voice <name> cold=…ms warm=…ms` is the repo's standing proof that the second
+# request of a voice answers well under a second.
+#
+# THE VOICES. /voices — the host directory /home/dank/voices mounted read-only by
+# the unit, the same packs frank-tts mounts for its own name list. A pack is a
+# directory that contains reference.wav; everything else in it (manifest.json, the
+# engine's reference.spk / reference.rvq extraction, a 16 kHz variant) is not read
+# here. The registration payload is `{"name": <dir>, "wav_b64": <base64 of
+# reference.wav>}` with NO ref_text, which selects the embedding-only (x-vector)
+# voice — the shipped default, warm RTF ~0.57-0.63 against ICL's 0.67, and the one
+# this fleet can produce honestly because it has no trustworthy transcript for the
+# audition crops. Adding ref_text (with the codes) would flip that voice to
+# in-context-learning mode: better fidelity on a good transcript, slower, and only
+# worth it for batch work like a podcast render. That is a per-voice opt-in this
+# script deliberately does NOT exercise, and the door stays open: a pack that
+# wants ICL needs its text in the pack plus one key in the payload below.
+#
+# A lone `spk_b64` is a 400 (src/tts-server.h:480 — it is `wav_b64` or BOTH
+# `spk_b64` and `rvq_b64`), which is why the WAV travels and the .spk stays home.
+#
+# NOTHING HERE IS A SECRET, and nothing is logged that could be: the audio bytes
+# are discarded, the synthesized text comes from the env file, and the reference
+# clip is base64'd straight into the request body without ever being echoed.
+set -euo pipefail
+
+# The engine's own address, from inside its namespace. Loopback is valid HERE:
+# this script runs in the container, next to the server. There is deliberately no
+# host-visible address to use instead — the unit publishes nothing, because a
+# host-loopback publish would be unreachable from the façade anyway (netavark
+# DNATs published ports only) while adding a surface on an unauthenticated
+# server.
+: "${ENGINE_URL:=http://127.0.0.1:8880}"
+
+# Container path; the host directory behind it is named in the Quadlet unit.
+: "${VOICES_DIR:=/voices}"
+
+# How long to wait for the engine to answer /health. Model load dominates: the
+# two GGUFs (1.2 GiB + 291 MB) are read and the context built before the HTTP
+# thread binds, and a boot races every other unit on this box.
+: "${HEALTH_WAIT:=300}"
+
+# One short sentence, long enough to exercise the codec snapshot and short enough
+# that warming a library of voices is seconds, not minutes. Never varied per run:
+# the cold/warm numbers in the journal should mean the same thing every boot. The
+# synthesis asks for `wav`, the buffered path — the streamed path (`pcm`) is
+# different audio at the same seed, and `wav` is also what frank-tts asks for.
+: "${WARM_TEXT:=Warm up, one two three.}"
+
+# Per-request ceiling. A cold voice is 6-8 s by measurement; anything approaching
+# this is a stalled engine and should be reported rather than waited on forever —
+# systemd counts the whole warm pass against the unit's start deadline.
+: "${REQUEST_TIMEOUT:=120}"
+
+fail=0
+log() { printf 'frank-tts-engine-warm: %s\n' "$*"; }
+
+# Wait for /health. It answers from the HTTP thread, so a 200 means the server is
+# listening; it says nothing about voices, which is what the rest of this script
+# is for.
+ready=0
+for ((i = 1; i <= HEALTH_WAIT; i++)); do
+    if curl -fsS --max-time 5 "${ENGINE_URL}/health" >/dev/null 2>&1; then
+        ready=1
+        break
+    fi
+    sleep 1
+done
+if (( ready == 0 )); then
+    log "engine did not answer ${ENGINE_URL}/health within ${HEALTH_WAIT}s; nothing warmed"
+    exit 1
+fi
+
+if [[ ! -d "$VOICES_DIR" ]]; then
+    log "no voice directory at ${VOICES_DIR}; nothing to warm (frank-tts will answer 400 with an empty voice list until packs are built)"
+    exit 0
+fi
+
+warmed=0
+for dir in "$VOICES_DIR"/*/; do
+    [[ -d "$dir" ]] || continue
+    name="${dir%/}"
+    name="${name##*/}"
+    if [[ ! -f "${dir}reference.wav" ]]; then
+        continue          # not a pack; frank-tts refuses this name too
+    fi
+    # The engine lowercases every voice name (tts_voice_name) while frank-tts
+    # matches the directory name exactly, so a mixed-case pack would work by
+    # accident on one side and not the other. Refuse it loudly instead. Pack
+    # names are also JSON string content here, so the character class is what
+    # keeps a directory name from writing structure into the request body.
+    if [[ ! "$name" =~ ^[a-z0-9][a-z0-9._-]*$ ]]; then
+        log "voice '${name}': name must be lowercase [a-z0-9._-] (the engine lowercases names; the shim does not) — skipped"
+        fail=1
+        continue
+    fi
+
+    body="$(printf '{"name":"%s","wav_b64":"%s"}' "$name" "$(base64 -w0 "${dir}reference.wav")")"
+    if ! code="$(curl -sS --max-time "$REQUEST_TIMEOUT" -o /dev/null -w '%{http_code}' \
+            -H 'Content-Type: application/json' --data-binary "$body" \
+            "${ENGINE_URL}/v1/audio/voices")" || [[ "$code" != "200" ]]; then
+        log "voice '${name}': registration failed (HTTP ${code:-no response}) — the shim will answer 400 for this name"
+        fail=1
+        continue
+    fi
+
+    # The cold pass. Its output is discarded; the point is the codec snapshot it
+    # leaves inside the engine.
+    start=$(date +%s%3N)
+    if ! curl -fsS --max-time "$REQUEST_TIMEOUT" -o /dev/null \
+            -H 'Content-Type: application/json' \
+            --data-binary "{\"input\":\"${WARM_TEXT}\",\"voice\":\"${name}\",\"response_format\":\"wav\"}" \
+            "${ENGINE_URL}/v1/audio/speech"; then
+        log "voice '${name}': registered, but the warm synthesis failed — first live request stays cold"
+        fail=1
+        continue
+    fi
+    cold=$(( $(date +%s%3N) - start ))
+
+    # The warm pass, same request. This is the number the fleet actually
+    # experiences, and it is what "the second request answers under a second" is
+    # measured against.
+    start=$(date +%s%3N)
+    if ! curl -fsS --max-time "$REQUEST_TIMEOUT" -o /dev/null \
+            -H 'Content-Type: application/json' \
+            --data-binary "{\"input\":\"${WARM_TEXT}\",\"voice\":\"${name}\",\"response_format\":\"wav\"}" \
+            "${ENGINE_URL}/v1/audio/speech"; then
+        log "voice '${name}': warm synthesis failed after a cold one that worked"
+        fail=1
+        continue
+    fi
+    warm=$(( $(date +%s%3N) - start ))
+
+    log "voice ${name} cold=${cold}ms warm=${warm}ms"
+    warmed=$(( warmed + 1 ))
+done
+
+# Failure first, emptiness second, and not the other way round: a pass where
+# every voice failed also has `warmed == 0`, and reading that as "nothing to do,
+# success" is how an endpoint that answers 400 for every voice name gets deployed
+# on a Friday.
+if (( fail )); then
+    log "${warmed} voice(s) warm, at least one failed (see the lines above)"
+    exit 1
+fi
+if (( warmed == 0 )); then
+    log "no voice with a reference.wav under ${VOICES_DIR}; engine is up but speaks nothing"
+    exit 0
+fi
+log "${warmed} voice(s) registered and warm"
@@ -26,6 +26,7 @@ SERVICE_ORDER = (
    "marreta",
    "pihole",
    "open-webui",
+    "open-notebook",
    "gitea-postgres",
    "gitea-server",
    "comfyui",
@@ -61,6 +62,10 @@ SERVICE_ORDER = (
    "sonarr",
    "lidarr",
    "readarr",
+    # The voice pair keeps the inference family's ordering rule: the engine is
+    # a dependency of the 7772 facade, so it is planned (and therefore
+    # restarted) first.
+    "frank-tts-engine",
    "frank-dragoon",
    "frank-zealot",
    "frank-archon",
@@ -74,6 +79,7 @@ DANKCLAW_SERVICES = {
    "marreta",
    "pihole",
    "open-webui",
+    "open-notebook",
    "gitea-postgres",
    "gitea-server",
    "comfyui",
@@ -95,6 +101,7 @@ DANKCLAW_SERVICES = {
    "homepage",
    "frank-dragoon",
    "frank-zealot",
+    "frank-tts-engine",
 }

 DANKSERVER_SERVICES = {
@@ -316,6 +323,26 @@ def services_for_path(path: str, target: str) -> set[str]:
        if len(parts) >= 2 and parts[1] == "open-webui":
            _add(services, "open-webui")
            return services
+        if len(parts) >= 2 and parts[1] == "open-notebook":
+            # One deployable owns the app AND its SurrealDB, like the marreta
+            # app/companion pair: the app alone cannot write a note and the
+            # database alone is a volume nothing reads. Any change under the
+            # directory (unit, network, or the interim episode mount) therefore
+            # plans the pair, which deploy_open_notebook starts database-first.
+            _add(services, "open-notebook")
+            return services
+        if len(parts) >= 2 and parts[1] == "voiceservice":
+            # The voice stack's containers share one directory but are TWO
+            # deployables — the arm A engine and the 7772 façade in front of it
+            # — so this maps per file, the way the authentik trio does, and not
+            # per directory. Anything that is not named after one of the two
+            # services plans nothing, exactly as it did before the pair was
+            # registered.
+            if parts[-1] in {"frank-tts-engine.container", "frank-tts-engine.network",
+                             "Containerfile.engine", "tts-engine-start.sh",
+                             "tts-engine-warm.sh"}:
+                _add(services, "frank-tts-engine")
+            return services
        # frank-dragoon left the quadlet shape on 2026-09-19 (CIRU v4.4.1 host
        # build, root unit): its files live in scripts/ and map there.
        if len(parts) >= 2 and parts[1] == "observability":
@@ -419,6 +446,21 @@ def services_for_path(path: str, target: str) -> set[str]:
            # what the live frank-dragoon endpoint renders, so it plans
            # frank-dragoon.
            _add(services, "frank-dragoon")
+        if name == "frank-tts-engine.env":
+            # The engine's knobs are command-line flags, and this file is the
+            # repo's copy of them (the image entrypoint translates one line to
+            # one flag), so editing it is a restart of the engine. It also
+            # carries the boot warmer's three knobs, because the warmer is
+            # exec-ed into this container and inherits the same EnvironmentFile.
+            # A restart is what re-registers and re-warms every voice: the
+            # engine's voice registry is memory-only. (The warmer itself lives
+            # with the image, mapped above with the files it is built from, like
+            # the serve scripts of frank-zealot and frank-archon are mapped to
+            # the units that run them.)
+            # scripts/download-frank-tts-engine-qwentts.sh deliberately plans
+            # nothing: it fetches host-side state, like every other download
+            # script in this directory.
+            _add(services, "frank-tts-engine")
        if name in {"frank-archon.env", "frank-archon.service", "serve-frank-archon.sh"}:
            # llama.cpp frank-archon (2026-09-26, replacing the Lucebox
            # DS4.1 quadlet) keeps its unit, env and serve files here the
@@ -426,6 +468,12 @@ def services_for_path(path: str, target: str) -> set[str]:
            # serving Qwen3.8-Flash-Next Q8_0. The download script fetches
            # the payload, which is host-side state, so it selects nothing.
            _add(services, "frank-archon")
+        if name == "open-notebook.env":
+            # open-notebook's tunables live here — the only repo-tracked part of
+            # either container's environment (the credentials are seeded on the
+            # host, so they are never a deploy trigger). Changing it is a
+            # restart of the pair, which the single deployable performs.
+            _add(services, "open-notebook")
        # Deployment/test/benchmark scripts and other repo tooling do not
        # restart a runtime service.
        return services
@@ -90,7 +90,9 @@ service_is_allowed() {
        dankclaw:authentik-postgres|dankclaw:authentik-server|\
        dankclaw:authentik-worker|dankclaw:authentik-outpost|dankclaw:authentik-outpost-ldap|dankclaw:anubis|\
        dankclaw:caddy|dankclaw:homepage|dankclaw:seerr|dankclaw:marreta|\
+        dankclaw:open-notebook|\
        dankclaw:frank-dragoon|dankclaw:frank-zealot|\
+        dankclaw:frank-tts-engine|\
        dankserver:romm-mariadb|dankserver:romm-redis|dankserver:romm|\
        dankserver:copyparty|dankserver:jellyfin|dankserver:calibre-web|dankserver:calibre-server|dankserver:plex|dankserver:tautulli|\
        dankserver:prowlarr|dankserver:qbittorrent|dankserver:radarr|\
@@ -548,6 +550,14 @@ build_compose_image() {
            image="franksdank/$service:latest"
            containerfile="dankclaw/$service/Containerfile"
            ;;
+        frank-tts-engine)
+            # The arm A TTS engine (qwentts.cpp `tts-server`). Built from
+            # source at a pinned upstream commit, so the build needs network
+            # and the cfhash label below is what keeps an unchanged re-deploy
+            # offline: the clone only happens when this Containerfile changes.
+            image=franksdank/frank-tts-engine:latest
+            containerfile=dankclaw/voiceservice/Containerfile.engine
+            ;;
        *)
            return 0
            ;;
@@ -646,6 +656,151 @@ deploy_open_webui() {
    systemctl --user restart open-webui.service
 }

+# open-notebook is the fleet's podcast generator: one app container (API,
+# worker and web UI under supervisord) in front of a SurrealDB container, with
+# a private bridge between them. One handler owns the pair, because restarting
+# the app without its database yields a UI that answers /health and fails every
+# write; scripts/deploy-plan.py therefore maps every path of the pair here.
+#
+# Credentials follow the marreta convention (per-service file under the deploy
+# user's home, mode 600, seeded from dankclaw/.env) with one difference: they
+# are not optional. An empty OPEN_NOTEBOOK_PASSWORD is "authentication OFF",
+# not "unconfigured" — the API, episode audio included, then answers anyone on
+# the LAN — and an empty SURREAL_PASS lets the database come up with different
+# root credentials than the app will present. So this handler refuses to start
+# either unit until every key carries a value. An existing file is NEVER
+# rewritten: regenerating an operator-set password would desync it from the
+# credentials already stored in the database.
+seed_open_notebook_env() {
+    local dest=/home/dank/Containers/open-notebook/env
+    local var missing=0
+    for var in OPEN_NOTEBOOK_ENCRYPTION_KEY OPEN_NOTEBOOK_PASSWORD SURREAL_PASSWORD SURREAL_PASS; do
+        grep -q "^${var}=." "$dest" 2>/dev/null || missing=1
+    done
+    if [[ "$missing" == 0 ]]; then
+        return 0
+    fi
+    if [[ ! -e "$dest" ]]; then
+        if [[ ! -f dankclaw/.env ]]; then
+            echo "open-notebook: neither $dest nor dankclaw/.env exists; put OPEN_NOTEBOOK_ENCRYPTION_KEY, OPEN_NOTEBOOK_PASSWORD and SURREAL_PASSWORD in dankclaw/.env (see dankclaw/.env.example)" >&2
+            return 1
+        fi
+        mkdir -p /home/dank/Containers/open-notebook
+        {
+            awk -F= '/^OPEN_NOTEBOOK_ENCRYPTION_KEY=/ || /^OPEN_NOTEBOOK_PASSWORD=/ || /^SURREAL_PASSWORD=/ { print }' \
+                dankclaw/.env
+            # The `surreal` CLI reads SURREAL_PASS from the environment while
+            # the app reads SURREAL_PASSWORD. One value, written twice, so the
+            # pair can never be seeded with two different root passwords.
+            sed -n 's/^SURREAL_PASSWORD=/SURREAL_PASS=/p' dankclaw/.env
+        } > "$dest"
+        chmod 600 "$dest"
+    fi
+    for var in OPEN_NOTEBOOK_ENCRYPTION_KEY OPEN_NOTEBOOK_PASSWORD SURREAL_PASSWORD SURREAL_PASS; do
+        grep -q "^${var}=." "$dest" \
+            || { echo "open-notebook: $dest carries no value for ${var}; fill it in directly (or in dankclaw/.env before the first seed) — a blank value here means an unauthenticated service or a mismatched database password" >&2; return 1; }
+    done
+}
+
+# Both units ship Pull=never: the digest pins in the .container files are the
+# contract, and the generator must never re-resolve a moving tag at start. That
+# makes fetching a pin a precondition the deployer satisfies once per pin
+# change; the existence check keeps every later re-deploy offline-safe.
+ensure_pinned_image() {
+    local image="$1"
+    if podman image exists "$image"; then
+        echo "open-notebook: $image is already in local storage"
+        return 0
+    fi
+    echo "open-notebook: pulling pinned image $image"
+    podman pull "$image"
+}
+
+deploy_open_notebook() {
+    seed_open_notebook_env || return 1
+
+    ensure_pinned_image 'docker.io/surrealdb/surrealdb:v2@sha256:e5d7387e3727bbe2f7cd6d869e48cd34777272258572ead37c9656b25f745723' || return 1
+    ensure_pinned_image 'docker.io/lfnovo/open_notebook:v1-latest@sha256:54b2025a4a4853c188f74b9b8246eca8c5480e5dd1babfa92db1038ff2f30212' || return 1
+
+    # install_quadlet copies the sibling open-notebook.network with the app
+    # unit. That cp is load-bearing, not tidiness: when a referenced Network=
+    # file is absent the v1 generator refuses to produce the container unit at
+    # all ("requested Quadlet unit open-notebook.network was not found").
+    install_quadlet open-notebook-surrealdb dankclaw/open-notebook/quadlet open-notebook-surrealdb
+    install_quadlet open-notebook dankclaw/open-notebook/quadlet open-notebook
+    systemctl --user start open-notebook-network.service
+
+    # Interim episode destination (Gitea issue #7, `human-only`): finished
+    # episode audio is bind-mounted out to this host directory. Created here as
+    # the deploy user so the container's mapped root writes files dank can
+    # read, and so the dependency is explicit rather than podman's default.
+    mkdir -p /home/dank/media/podcasts
+
+    # No `systemctl --user enable`: generated Quadlet units cannot be enabled
+    # on this host (see deploy_authentik); boot persistence is the [Install]
+    # section inside each .container file. Database first, and both on every
+    # run — a stale app left attached to a recreated database is exactly the
+    # half-deployed state this handler exists to prevent.
+    systemctl --user restart open-notebook-surrealdb.service
+    wait_container_healthy open-notebook-surrealdb 90 || return 1
+    systemctl --user restart open-notebook.service
+    # The gate is the API's own health route: upstream serves `GET /health` on
+    # 5055 with {"status":"healthy"} and exempts it from the password
+    # middleware, so it stays a real answer once OPEN_NOTEBOOK_PASSWORD is set.
+    # Host port 5056, because seerr already holds 127.0.0.1:5055. The UI on
+    # 8502 is deliberately not gated: supervisord starts it only after the API
+    # answers (the image's wait-for-api.sh), so this gate already implies it.
+    wait_for_health open-notebook http://127.0.0.1:5056/health 180
+}
+
+# frank-tts-engine is the arm A TTS engine behind frank-tts: one Quadlet unit
+# plus the private bridge its unit defines (install_quadlet copies the sibling
+# frank-tts-engine.network — without that file the v1 generator refuses to
+# produce the container unit at all, the same trap documented above). The
+# façade that consumes it is a separate service on a separate port and a
+# separate handler.
+deploy_frank_tts_engine() {
+    # Weights BEFORE the build, and refuse rather than fetch. The payload is
+    # 1.4 GiB of GGUF with byte and sha256 checks; silently pulling it inside a
+    # deploy would turn a stalled network into a deploy that looks hung, and
+    # would hide which of the two failure modes the operator is in. The fetcher
+    # is idempotent, so re-running this handler after the fetch is cheap.
+    if ! scripts/download-frank-tts-engine-qwentts.sh --verify-only >/dev/null; then
+        echo "frank-tts-engine: the talker/tokenizer GGUFs are missing or wrong-sized under /home/dank/models/Qwen3-TTS-GGUF; run scripts/download-frank-tts-engine-qwentts.sh and re-deploy" >&2
+        return 1
+    fi
+
+    # Build first: Image= is a locally built tag with Pull=never, so the
+    # generator cannot start a container from it before it exists.
+    build_compose_image frank-tts-engine
+
+    install_quadlet frank-tts-engine dankclaw/voiceservice/quadlet frank-tts-engine
+    systemctl --user start frank-tts-engine-network.service
+    # No `systemctl --user enable` (generated Quadlet units cannot be enabled
+    # on this host); boot persistence is the [Install] section in the unit.
+    #
+    # `restart` blocks until the unit reaches started, which includes the
+    # ExecStartPost warm pass — a boot of this service is therefore already
+    # warm by the time the next line runs.
+    systemctl --user restart frank-tts-engine.service
+    # NOT wait_for_health: this container publishes nothing, so there is no URL
+    # the deployer can dial from the host. The unit's HealthCmd runs inside the
+    # container's own namespace, and podman's recorded health status is what the
+    # host can actually observe.
+    wait_container_healthy frank-tts-engine 150 || return 1
+
+    # The warmer runs a second time here on purpose. ExecStartPost carries a
+    # `-` prefix so a failed warm can never crash-loop the endpoint, which also
+    # means the unit cannot fail the deploy on it. This call is where a voice
+    # that did not warm becomes a deploy result, and where the per-voice
+    # cold=/warm= numbers land on the operator's console instead of only in the
+    # journal. The pass itself is idempotent and the second cold cost is gone:
+    # the voices are already warm, so this costs about a second per voice. It is
+    # exec-ed into the container for the same reason the health gate is: no host
+    # address exists.
+    podman exec frank-tts-engine /app/warm-voices.sh
+}
+
 deploy_comfyui() {
    # Build first: the unit's Image= resolves against local storage, so the
    # image has to exist before the generator starts a container from it.
@@ -1573,6 +1728,7 @@ deploy_service() {
        gluetun) deploy_gluetun ;;
        searxng-valkey) deploy_searxng_valkey ;;
        open-webui) deploy_open_webui ;;
+        open-notebook) deploy_open_notebook ;;
        pihole) deploy_pihole ;;
        gitea-postgres) deploy_gitea_unit gitea-postgres gitea-postgres ;;
        gitea-server) deploy_gitea_unit gitea-server gitea-server ;;
@@ -1591,6 +1747,7 @@ deploy_service() {
        frank-dragoon) deploy_llm_dragoon ;;
        frank-zealot) deploy_llm_zealot ;;
        frank-archon) deploy_llm_archon ;;
+        frank-tts-engine) deploy_frank_tts_engine ;;
        hermes|hermes-dashboard|hermes-webui) deploy_hermes ;;
        romm|romm-mariadb|romm-redis|mariadb|redis) deploy_romm_stack "$service" ;;
        jellyfin) deploy_jellyfin ;;
@@ -141,6 +141,8 @@ valid_service() {
        dankclaw:alertmanager|\
        dankclaw:node-exporter|dankclaw:authentik-postgres|dankclaw:authentik-server|\
        dankclaw:authentik-worker|dankclaw:authentik-outpost|dankclaw:authentik-outpost-ldap|dankclaw:anubis|dankclaw:seerr|\
+        dankclaw:open-notebook|\
+        dankclaw:frank-tts-engine|\
        dankclaw:frank-dragoon|dankclaw:frank-zealot|\
        dankserver:romm-mariadb|dankserver:romm-redis|dankserver:romm|\
        dankserver:copyparty|dankserver:jellyfin|dankserver:calibre-web|dankserver:calibre-server|dankserver:plex|dankserver:tautulli|\
@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+# Download the frank-tts-engine payload: the two GGUF files the arm A engine
+# (qwentts.cpp `tts-server`, dankclaw/voiceservice/Containerfile.engine) loads
+# once at startup — Serveurperso/Qwen3-TTS-GGUF's **1.7 B base talker at
+# Q4_K_M** and the **12 Hz tokenizer at Q8_0**. Public repo — no auth header,
+# and never a token on the command line (world-readable in /proc/<pid>/cmdline).
+#
+# THE BASE VARIANT IS MANDATORY, NOT A PREFERENCE. The engine refuses every
+# voice registration unless the loaded model reports type "base"
+# (tools/tts-server.cpp, register_voice): on a customvoice or voicedesign talker
+# the cloned-voice product does not exist. The 0.6 B talker (628,905,056 B for
+# its Q4_K_M) also exists and is NOT the decided artifact — 1.7 B is what live
+# output was measured with on 2026-10-18.
+#
+# Fresh downloads, no resume (the same rule the frank-zealot fetcher learned the
+# hard way: `curl -C -` once produced an oversized file on a multi-GB payload);
+# -f/--fail-with-body so an HTTP error is never a success; then exact byte count
+# and sha256 against the Hub's own LFS oid. This repo IS LFS, so the sha values
+# below are the pointer oids the Hub publishes — verified at fetch, not
+# computed locally. Idempotent: a complete, correctly-hashed file is skipped,
+# and `--verify-only` reports without downloading (that is the mode the deployer
+# and the runbook use to answer "are the weights there?").
+#
+# Both files together are 1.4 GiB and the engine mmaps them: peak RSS measured
+# 5.7 GiB with both resident. Nothing here is deleted on a swap — the previous
+# talker stays on disk, because the rollback for a bad engine build is to point
+# QWENTTS_MODEL at a different file, not to re-download 1.4 GiB under pressure.
+#
+# Usage:
+#   scripts/download-frank-tts-engine-qwentts.sh [DEST_DIR] [--verify-only]
+# Default DEST_DIR is the host directory the frank-tts-engine unit mounts
+# read-only at /models.
+set -euo pipefail
+
+DEST=""
+VERIFY_ONLY=0
+for arg in "$@"; do
+    case "$arg" in
+        --verify-only) VERIFY_ONLY=1 ;;
+        *) DEST="$arg" ;;
+    esac
+done
+DEST="${DEST:-/home/dank/models/Qwen3-TTS-GGUF}"
+
+# repo | hub-name | dest-name | bytes | sha256 (Hub LFS oid, resolved 2026-10-18)
+FILES=(
+  "Serveurperso/Qwen3-TTS-GGUF|qwen-talker-1.7b-base-Q4_K_M.gguf|qwen-talker-1.7b-base-Q4_K_M.gguf|1219245248|ea393ebaf2167ea23ce9fc18b093822851358a950d7075cd47ab4f6ce23e887d"
+  "Serveurperso/Qwen3-TTS-GGUF|qwen-tokenizer-12hz-Q8_0.gguf|qwen-tokenizer-12hz-Q8_0.gguf|291150624|1883beeed99348fc35e23dd225e9082f93f6f8c109330a33d935baa8acdbfd94"
+)
+
+mkdir -p "$DEST"
+status=0
+for entry in "${FILES[@]}"; do
+  IFS='|' read -r repo hubname destname size sha <<<"$entry"
+  url="https://huggingface.co/${repo}/resolve/main/${hubname}"
+  f="$DEST/$destname"
+  have=0
+  if [[ -f "$f" ]] && [[ "$(stat -c%s "$f")" == "$size" ]]; then
+    if sha256sum -c --quiet <(printf '%s  %s\n' "$sha" "$f"); then
+      have=1
+    fi
+  fi
+  if (( have )); then
+    echo "OK        $destname"
+    continue
+  fi
+  if (( VERIFY_ONLY )); then
+    echo "MISSING   $destname"
+    status=1
+    continue
+  fi
+  echo "FETCHING  $destname (from $repo)"
+  tmp="$f.part"
+  curl -fsSL --fail-with-body -o "$tmp" "$url"
+  mv "$tmp" "$f"
+  if [[ "$(stat -c%s "$f")" != "$size" ]]; then
+    echo "SIZE FAIL $destname ($(stat -c%s "$f") != $size)"
+    status=1
+    continue
+  fi
+  if ! sha256sum -c --quiet <(printf '%s  %s\n' "$sha" "$f"); then
+    echo "SHA FAIL  $destname"
+    status=1
+    continue
+  fi
+  echo "VERIFIED  $destname"
+done
+if (( status == 0 )); then
+  echo "DOWNLOAD_DONE $DEST"
+else
+  echo "DOWNLOAD_FAILED $DEST" >&2
+fi
+exit "$status"
@@ -0,0 +1,136 @@
+# frank-tts-engine.env — tunables for **frank-tts-engine**, the arm A TTS
+# engine on Dankclaw (qwentts.cpp `tts-server`, container port **8880**, never a
+# fleet endpoint). Read by the Quadlet unit
+# (dankclaw/voiceservice/quadlet/frank-tts-engine.container) as its only
+# EnvironmentFile=, which is why every path below is the value the CONTAINER
+# sees. The host directories those mounts come from are named in
+# dankclaw/voiceservice/quadlet/frank-tts-engine.container and
+# scripts/download-frank-tts-engine-qwentts.sh.
+#
+# WHAT SITS HERE AND WHAT DOES NOT. `tts-server` reads its configuration from
+# command-line flags only — it looks at no environment variable — so this file
+# is consumed by the image's entrypoint
+# (dankclaw/voiceservice/tts-engine-start.sh), which turns each key below into
+# the matching flag. Every value has a default baked into that script, and the
+# default equals the value below: this file exists so the decided shape is
+# written down in the repo and one line can be changed without a rebuild, not
+# because the engine would otherwise fail to boot.
+#
+# THE THREAD LAW (read this before reaching for CPUQuota=, CPUAffinity=,
+# taskset or a systemd slice). There is **no `-t`/`--threads` flag** in this
+# build: src/backend.h computes the CPU thread count as
+# `std::thread::hardware_concurrency() / 2` (its own comment: GEMM shares SIMD
+# units across hyperthreads). The engine therefore sizes its pools from what the
+# kernel *reports*, not from what it is allowed to use. Pin the container to a
+# cpuset and the thread count silently changes with it — different GEMM
+# tiling, different timings, no log line saying so, and the measured numbers
+# below stop describing the process you are running. Nothing in this fleet
+# pins this container; that is a decision, not an oversight.
+#
+# THE COLD-VOICE LAW (why the unit has an ExecStartPost at all). The first
+# speech request for a registered voice decodes the ENTIRE reference clip to
+# snapshot its codec state: 6.2-8.0 s total, first audio byte at 5,530 ms. Every
+# later request for that voice restores the snapshot in 0.5 ms. Registrations
+# live in memory only, so a restart loses them and re-registration alone does
+# NOT warm the voice — the warm pass has to synthesize something. So
+# dankclaw/voiceservice/tts-engine-warm.sh (in the image at
+# /app/warm-voices.sh) runs on every start and speaks one short sentence per
+# voice. Skip it and the first person to ask for audio that day waits 5.5 s in
+# silence. It runs INSIDE this container — `podman exec`, from the unit's
+# ExecStartPost — so it reads /voices here and the keys at the bottom of this
+# file are its knobs too.
+#
+# STREAMING IS NOT BUFFERED. The same seed gives audio that differs in 92.2 %
+# of samples (-41.6 dB RMS) between `response_format=pcm` (the streaming path,
+# codec chunks pushed as they decode) and `response_format=wav` (the buffered
+# path). Nothing in this stack may compare the two, cache one against the
+# other, or assume a seed pins output across `response_format`. frank-tts always
+# asks for `wav` and re-encodes to mp3 itself; the warmer below also asks for
+# `wav`, for that reason and because the streamed path would need a reader.
+#
+# THE ROUTE LIST, verbatim from tts-server at the pinned commit, so nobody
+# debugs against a route that does not exist: GET /health, GET /v1/models,
+# GET|POST /v1/audio/voices, DELETE /v1/audio/voices/{name},
+# POST /v1/audio/speech (response_format wav or pcm). Everything else is a bare
+# 404. Note two traps in that surface: `GET /v1/audio/voices` returns an empty
+# JSON object rather than the voice list at this commit (the handler builds the
+# array and never attaches it to the document), and a `POST /v1/audio/voices`
+# carrying `spk_b64` without `rvq_b64` is rejected outright — it is `wav_b64` or
+# BOTH of the pair.
+
+# --- the two weights (see scripts/download-frank-tts-engine-qwentts.sh) -------
+# Container paths; the host directory /home/dank/models/Qwen3-TTS-GGUF is
+# mounted read-only at /models. 1,219,245,248 B + 291,150,624 B, fetched from
+# https://huggingface.co/Serveurperso/Qwen3-TTS-GGUF and byte-checked at fetch.
+#
+# The 1.7 B talker is the decided artifact (Frank, 2026-10-18). A 0.6 B talker
+# exists at 628,905,056 B and is NOT what live output was measured with; the
+# Q4_K_M quantization is the size that leaves the measured RTF margin intact on
+# this box, and the tokenizer rides at Q8_0 because the codec is where clone
+# fidelity is lost first.
+#
+# It has to be the **base** variant, not customvoice/voicedesign: the engine
+# refuses any voice registration unless qt_model_type() reports "base"
+# (tools/tts-server.cpp, the register_voice lambda). Cloned voices — the whole
+# product — are impossible on the other two variants.
+QWENTTS_MODEL=/models/qwen-talker-1.7b-base-Q4_K_M.gguf
+QWENTTS_CODEC=/models/qwen-tokenizer-12hz-Q8_0.gguf
+
+# What GET /v1/models reports, and what scripts/frank-tts.env's
+# TTS_UPSTREAM_MODEL names. A model id, never a file name.
+QWENTTS_ALIAS=frank-tts-engine
+
+# 0.0.0.0 is required and is not an exposure decision: tts-server binds
+# 127.0.0.1 by default, and inside its own netns that address is reachable by no
+# one, not even the façade on the same bridge — which is why a host-loopback
+# publish would not have helped either (netavark DNATs published ports only, and
+# the unit publishes nothing at all). Binding 0.0.0.0 exposes the server to the
+# one network it is attached to: the private voice bridge
+# (systemd-frank-tts-engine, 10.89.5.0/24), whose only other member is frank-tts.
+QWENTTS_HOST=0.0.0.0
+QWENTTS_PORT=8880
+
+# Language label applied when a request omits one. `auto` is upstream's default
+# and what the trial ran; naming a language is a per-request field on
+# /v1/audio/speech, so this is only the fallback.
+QWENTTS_LANG=auto
+
+# Serialised FIFO: one synthesis at a time, everyone else queued. Warm RTF on
+# this box is 0.55-0.67 against real time 1.0, which is the entire margin a live
+# stream has; two concurrent syntheses split the same cores and the margin is
+# gone, with the added effect that the second caller's time-to-first-audio now
+# includes the first one's whole utterance. The façade's own budget
+# (SHIM_TIMEOUT=600, and open-notebook's ESPERANTO_TTS_TIMEOUT=660 sitting one
+# round-trip outside it) is what absorbs the queue.
+QWENTTS_MAX_BATCH=1
+
+# --- the boot warmer (dankclaw/voiceservice/tts-engine-warm.sh) --------------
+# These three are read by the warm hook, not by tts-server. They live here
+# because the hook is exec-ed into this container and therefore inherits this
+# same EnvironmentFile — one file, one restart, no second source of truth.
+
+# Container path of the voice packs; the host directory is /home/dank/voices,
+# mounted read-only by the unit and mounted (read-only, same source) by
+# frank-tts as well. A directory counts as a voice exactly when it contains
+# reference.wav, which is the same rule frank-tts applies.
+VOICES_DIR=/voices
+
+# How long the hook waits for /health before giving up. Model load dominates
+# this: both GGUFs are read and the context is built before the HTTP thread
+# binds, and a boot competes with every other unit on the box. 300 s is generous
+# against a cold cache; the unit's TimeoutStartSec (900 s) is what bounds the
+# whole pass, warming included.
+HEALTH_WAIT=300
+
+# The sentence each voice speaks to snapshot its codec state, and the text the
+# second (warm-timing) pass repeats. Fixed on purpose: the cold=/warm= numbers in
+# the journal are comparable across boots only if the input is the same. Kept
+# short because warming a library is serial — one cold decode per voice, 6-8 s
+# each, inside the unit's start deadline. Quoted because podman's env-file parser
+# and a shell `source` must both read the sentence as ONE value.
+WARM_TEXT="Warm up, one two three."
+
+# Per-request ceiling for the hook. A cold voice measures 6-8 s, so 120 s is
+# ~15x margin: reaching it means the engine is wedged, and systemd is still
+# waiting on this pass before it calls the unit started.
+REQUEST_TIMEOUT=120
@@ -0,0 +1,100 @@
+# open-notebook.env — configuration for **open-notebook**, the fleet's podcast
+# generator on Dankclaw (UI host port **8502**, API host port **5056**). Read by
+# BOTH Quadlet units (dankclaw/open-notebook/quadlet/) as the FIRST
+# EnvironmentFile= line, which is why every path and host name below is the
+# value the CONTAINER must see.
+#
+# TWO FILES, ONE ORDER. This file is tracked; it holds knobs, not credentials.
+# The three secret keys below are declared EMPTY on purpose — the `scripts/*.env`
+# gitignore exception exists for "paths and numbers, never credentials" — and the
+# real values live in the host file the deployer seeds at
+# /home/dank/Containers/open-notebook/env (mode 600, seeded from dankclaw/.env,
+# the same convention grafana/marreta/pihole follow). Both files are handed to
+# podman in EnvironmentFile= order and the LAST one wins (verified against the
+# generated run line), so the host file overrides these blanks. Do not reorder
+# the two lines.
+#
+# WHY THE DEPLOYER REFUSES TO START THESE UNITS WITHOUT THE SECRET FILE. An empty
+# OPEN_NOTEBOOK_PASSWORD is not "unconfigured", it is **authentication off**, and
+# the episode-audio download is one of the routes the API serves without a
+# session; an empty SURREAL_PASS lets the database come up with different root
+# credentials than the app will present; an empty OPEN_NOTEBOOK_ENCRYPTION_KEY
+# means no provider credential can be saved at all. So the guard is in
+# deploy-remote.sh (seed_open_notebook_env), not in the app's opinion.
+#
+# THE CPU-SHUTDOWN GUARD (the two knobs that matter most on this box). Defaults
+# are TTS_BATCH_SIZE=5 and OPEN_NOTEBOOK_WORKER_MAX_TASKS=5 — five parallel
+# synthesis requests from five parallel jobs. frank-tts answers each request by
+# spawning its own engine process (~8 GiB resident, 8 threads, measured in the
+# frank-tts CPU trial of 2026-10-18), so the defaults mean ~40 GiB and forty
+# threads aimed at a machine that also serves frank-dragoon and frank-zealot and
+# whose TTS engine runs on the SAME CPU. Both numbers are 1 here: one episode at
+# a time, one voice line synthesized at a time. That is a throughput choice, not
+# a correctness one — a podcast is a background job — and it is the difference
+# between a slow render and a box that stops answering the text endpoints
+# mid-sentence. Raise them only with a TTS engine that batches internally.
+#
+# THE TTS CLOCK. ESPERANTO_TTS_TIMEOUT is the worker's patience per DIALOGUE
+# LINE, not per episode: one episode is dozens of POSTs to /v1/audio/speech
+# (the app synthesises each speaker turn separately and concatenates the clips
+# with ffmpeg afterwards), and a CPU engine takes single-digit seconds for a
+# line, with the tail of a long turn well past the 300 s default. 660 sits one
+# round-trip OUTSIDE SHIM_TIMEOUT=600 in scripts/frank-tts.env — the shim's own
+# per-request ceiling — so a frank-tts give-up arrives as frank-tts's error and
+# not as open-notebook abandoning a synthesis still in flight. An abandoned
+# request does not cancel the engine process; it just leaves the episode stuck in
+# "generating" while the audio arrives.
+#
+# THE SCRIPTWRITER. ESPERANTO_LLM_TIMEOUT is the app's own default (180 s), kept
+# visible beside the TTS number because both belong to one podcast run: the
+# outline call and the transcript call are the slow text work, and frank-zealot
+# answers them well inside 180. Provider choice is made in the UI, not here —
+# see [[Open Notebook]] for the one-time credential provisioning — and it is
+# frank-zealot on purpose: script writing asks for a JSON-schema response, which
+# the OpenAI-compatible llama.cpp endpoint is known to serve, while halogen's
+# structured-output behaviour on frank-dragoon is UNVERIFIED. halogen remains
+# the unproven alternative, not the fallback.
+#
+# THE DATABASE COORDINATES. SURREAL_URL addresses the sibling container BY NAME
+# on systemd-open-notebook (container DNS is scoped to the owning network, so
+# this is the only form that works). NAMESPACE/DATABASE/USER are plain names.
+# SURREAL_PASSWORD and SURREAL_PASS are ONE value under two spellings: the app
+# reads SURREAL_PASSWORD, the `surreal` CLI reads SURREAL_PASS. Keep them equal;
+# the deployer writes both into the seeded file from a single SURREAL_PASSWORD in
+# dankclaw/.env, so hand-editing one line is the only way to desync them.
+
+SURREAL_URL=ws://open-notebook-surrealdb:8000/rpc
+SURREAL_NAMESPACE=open_notebook
+SURREAL_DATABASE=open_notebook
+SURREAL_USER=open_notebook
+# Secrets — filled on the host, never here (see the header).
+SURREAL_PASSWORD=
+SURREAL_PASS=
+OPEN_NOTEBOOK_ENCRYPTION_KEY=
+OPEN_NOTEBOOK_PASSWORD=
+
+# WHERE THE BROWSER FINDS THE API. The UI auto-detects `<host-you-opened>:5055`,
+# and 5055 on this host belongs to seerr, so the API leaves the container on 5056
+# and this line has to say so. Both origins are listed in CORS_ORIGINS because
+# the API is called cross-origin from the UI's own port: the LAN origin is the
+# normal one, the localhost one covers a browser opened on Dankclaw itself. The
+# app logs a warning at start while CORS_ORIGINS is unset and defaults to `*`,
+# which is a wildcard in front of an endpoint that serves every episode's audio.
+API_URL=http://192.168.0.143:5056
+CORS_ORIGINS=http://192.168.0.143:8502,http://localhost:8502
+
+# Concurrency: see "THE CPU-SHUTDOWN GUARD" above. Defaults are 5 and 5.
+TTS_BATCH_SIZE=1
+OPEN_NOTEBOOK_WORKER_MAX_TASKS=1
+
+# Timeouts: see "THE TTS CLOCK" and "THE SCRIPTWRITER" above.
+ESPERANTO_TTS_TIMEOUT=660
+ESPERANTO_LLM_TIMEOUT=180
+
+# Heavy extraction runtimes stay OFF, which is also what keeps boot fast: each
+# one installs a multi-gigabyte ML/Chromium stack into the image's venv on first
+# startup (cached on the /app/data volume after that). Podcast generation reads
+# notes and sources that are already text, so neither is needed here; enable one
+# deliberately, per the upstream docs, if source ingestion starts to matter.
+# OPEN_NOTEBOOK_ENABLE_DOCLING=true
+# OPEN_NOTEBOOK_ENABLE_CRAWL4AI=true
@@ -128,6 +128,31 @@ for path in "${CHANGED[@]}"; do
            add_test tests/docs_completeness.bats
            add_test tests/deployment_scoping.bats
            ;;
+        # open-notebook is the fleet's podcast generator: an app quadlet, the
+        # SurrealDB quadlet behind it, the private network between them, and the
+        # one env file both units read. Like the caddy block above, this case
+        # has to precede the dankclaw/*.container glob, whose `*` crosses `/`
+        # and would otherwise swallow dankclaw/open-notebook/quadlet/*.
+        dankclaw/open-notebook/*|scripts/open-notebook.env)
+            add_test tests/open_notebook.bats
+            add_test tests/docs_completeness.bats
+            add_test tests/deployment_scoping.bats
+            ;;
+        # The voice stack: the arm A engine unit, the private bridge it owns,
+        # its image and its entrypoint. Like the open-notebook block above,
+        # this case MUST precede the dankclaw/*.container glob — that `*`
+        # crosses `/`, so without this case
+        # dankclaw/voiceservice/quadlet/frank-tts-engine.container is routed to
+        # the open-webui/pihole/searxng seams and its own seam never runs.
+        # The façade's seam rides along: the two share a directory, a network
+        # and the request path a consumer takes.
+        dankclaw/voiceservice/*)
+            add_test tests/frank_tts_engine.bats
+            add_test tests/frank_tts_unit.bats
+            add_test tests/deployment_flow.bats
+            add_test tests/deployment_scoping.bats
+            add_test tests/docs_completeness.bats
+            ;;
        dankclaw/*.container|dankclaw/*.network)
            add_test tests/open_webui_quadlet.bats
            add_test tests/pihole.bats
@@ -187,6 +212,19 @@ for path in "${CHANGED[@]}"; do
        # as additions, with "no focused-test mapping".
        .AGENTTRASH/*|*/.AGENTTRASH/*)
            ;;
+        # The two voice env files both reach a container through a Quadlet unit
+        # (EnvironmentFile=), so they select the voice seams plus the
+        # script-syntax seam. This case has to precede the generic
+        # scripts/*.service and scripts/* fallbacks below, or a change to
+        # scripts/frank-tts-engine.env would run nothing but bash -n. The
+        # warmer is NOT here: it ships inside the engine image and is routed
+        # with the rest of dankclaw/voiceservice/* above.
+        scripts/frank-tts-engine.env|scripts/frank-tts.env)
+            add_test tests/frank_tts_engine.bats
+            add_test tests/frank_tts_unit.bats
+            add_test tests/deployment_scoping.bats
+            add_test tests/scripts_syntax.bats
+            ;;
        # frank-archon is llama.cpp (the unsloth b11030-mix prebuilt) on the
        # two R9700s as a ROOT unit — the 2026-09-26 swap that replaced the
        # Lucebox DS4.1 quadlet on :7770. Its env, unit and serve script all
@@ -0,0 +1,129 @@
+---
+type: reference
+description: "frank-tts-engine is the arm A TTS engine on Dankclaw: qwentts.cpp's resident tts-server with the 1.7 B base talker, on a private podman bridge behind frank-tts — repo-owned, not yet deployed."
+tags:
+  - dankclaw
+  - tts
+  - voice
+  - quadlet
+  - cpu
+timestamp: 2026-10-18
+---
+
+# Frank TTS Engine
+
+`frank-tts-engine` is the **arm A text-to-speech engine** on Dankclaw: [qwentts.cpp](https://github.com/ServeurpersoCom/qwentts.cpp)'s resident `tts-server` HTTP process, holding the Qwen3-TTS **1.7 B base talker (Q4_K_M)** and the **12 Hz tokenizer (Q8_0)** in RAM once and synthesizing from there. It listens on container port **8880** and is **deliberately not a fleet endpoint** — the endpoint consumers address is `frank-tts` on **7772**, which resolves voice names, re-encodes to mp3 and owns the timeout budget. This page is the engine runbook; the endpoint's contract lives with its own page.
+
+**Nothing here is deployed.** This page documents repo-owned configuration — the Quadlet unit and network, the image build, the weight fetcher, the boot warmer, the deployer path — and the measured facts those files were written against. No container, image, weight file or network exists on Dankclaw yet, and the engine publishes no port at all, so there is nothing for the homepage checker or a browser to reach. Deploying it is a deliberate next step, in the order at the bottom of this page.
+
+**Host:** Dankclaw (`192.168.0.143`), rootless Podman, user `dank` — **Port:** 8880, **never published** — **Network:** the private `systemd-frank-tts-engine` bridge (10.89.5.0/24) and no other — **Deployer:** `frank-tts-engine` — **Consumers:** `frank-tts` (7772) and, through it, every voice request in the fleet including [[Open Notebook]]'s podcast renders.
+
+## Facts (verified 2026-10-18 against the pinned upstream commit, the Hub, and the CPU trial on this host)
+
+| Item | Value |
+|------|-------|
+| Engine | `tts-server` from qwentts.cpp, pinned at commit `5916bf7c79dbb4e66fc059cdc507a79a23a28bb4` (`dankclaw/voiceservice/Containerfile.engine`). The source is **not vendored**: the image clones that commit and its recorded `ggml` submodule, so the build needs outbound HTTPS and the `cfhash` label is what keeps an unchanged re-deploy offline |
+| Build line | `cmake -B build -DCMAKE_BUILD_TYPE=Release -DGGML_CCACHE=OFF -DGGML_BACKEND_DL=OFF -DGGML_CPU_ALL_VARIANTS=OFF -DGGML_OPENMP=ON -DGGML_BLAS=OFF -DGGML_CUDA=OFF -DGGML_HIP=OFF -DGGML_VULKAN=OFF -DGGML_METAL=OFF -DGGML_SYCL=OFF -DGGML_RPC=OFF && cmake --build build -j 8` — the exact line the 2026-10-18 trial ran on this box. `GGML_BLAS=OFF` is **forced**: Dankclaw has `libopenblas.so.0` and no BLAS dev headers, so upstream's own `Dockerfile` and `buildcpu.sh` (both of which pass BLAS on) cannot be copied. No `-DGGML_NATIVE` is passed, and ggml defaults it on, so the binary is `-march=native` for the machine that built it: **build this image on the host that runs it** |
+| Image | built locally as `franksdank/frank-tts-engine:latest`, two stages from one digest-pinned base `docker.io/library/ubuntu:24.04@sha256:68ee22004a9109b44973313b02ff7b1de250f1de0f5ecb628d73f579aaff33ac` (index digest resolved 2026-10-18). Runtime stage: `libgomp1` (OpenMP is on), `curl` (the unit's `HealthCmd` runs as `/bin/sh -c`, and the warmer speaks HTTP), uid **10000**, `LD_LIBRARY_PATH=/app` because ggml builds shared by default and the link-time RPATH names the build tree |
+| Talker | `qwen-talker-1.7b-base-Q4_K_M.gguf`, **1 219 245 248 B**, sha256 `ea393ebaf2167ea23ce9fc18b093822851358a950d7075cd47ab4f6ce23e887d` (the Hub's LFS pointer oid) |
+| Tokenizer | `qwen-tokenizer-12hz-Q8_0.gguf`, **291 150 624 B**, sha256 `1883beeed99348fc35e23dd225e9082f93f6f8c109330a33d935baa8acdbfd94` |
+| Source of both | `https://huggingface.co/Serveurperso/Qwen3-TTS-GGUF`, fetched by `scripts/download-frank-tts-engine-qwentts.sh` into `/home/dank/models/Qwen3-TTS-GGUF`, mounted read-only at `/models`. It has to be the **base** variant: the engine refuses every voice registration unless the model reports type `base`, so on `customvoice`/`voicedesign` the cloned-voice product does not exist. A 0.6 B talker (628 905 056 B) exists and is **not** the decided artifact |
+| Memory | **5.7 GiB peak RSS** with both files resident (2026-10-18 trial). No `LimitMEMORY`/`MemoryMax`: a limit would turn a busy moment into an OOM kill in the middle of an utterance |
+| Concurrency | `--max-batch 1`: a serialised FIFO. Warm RTF on this box is 0.55–0.67 against real time 1.0, and that margin is the entire headroom a live stream has; two concurrent syntheses split the same cores and the second caller's first byte additionally waits for the first utterance to finish |
+| Network | `systemd-frank-tts-engine` (10.89.5.0/24, `dankclaw/voiceservice/quadlet/frank-tts-engine.network`) and **nothing else**, with **no `PublishPort` at all**. `frank-tts` joins the same bridge and dials `http://frank-tts-engine:8880` |
+| Voices | `/home/dank/voices` mounted read-only at `/voices`, and it is the **warmer** that reads it, not the server: `tts-server` receives reference audio as base64 in a registration body and keeps its registry in memory only |
+| Health | `GET /health` → `{"status":"ok"}`, served by the HTTP thread rather than the synthesis queue, so a busy engine still reads healthy. Probed by the unit (`HealthCmd`, 30 s interval, 120 s start period) **inside the container's namespace**, because there is no published port to probe from outside |
+| Routes | `GET /health`, `GET /v1/models`, `GET|POST /v1/audio/voices`, `DELETE /v1/audio/voices/{name}`, `POST /v1/audio/speech` (`response_format` = `wav` or `pcm`; **default `pcm`**). Everything else is a bare 404. `POST /v1/audio/speech` requires `input`; unknown `voice`, missing `input` and a bad `speed` are 400s, an empty generation is a 502 |
+
+## Why this engine, and not the alternatives
+
+The criterion Frank set on 2026-10-18 was **"whatever is better for live output"**, and live output is decided by time-to-first-audio and by whether the stream stays ahead of real time — not by benchmark throughput. RTF only has to stay under 1.0 with margin; what separates the arms is first-byte latency and **spread**. Measured on this host the same day (CPU; the full A/B is the section *"Decision: arm A for live output (2026-10-18)"* in [[Local TTS and Voice Cloning]], which is the source of these numbers):
+
+| Measure | Resident `tts-server` (arm A, chosen) | Mainline per-request CLI path (arm B) |
+|---|---|---|
+| first audio byte | **86–451 ms** end to end; **94–112 ms** server-side | model load, per request |
+| warm real-time factor while streaming | **0.55–0.67** | 0.93–0.99 |
+| run-to-run spread | **±0.01** | ±0.25 |
+| HTTP surface | serves `/v1/audio/speech` itself | none — façade CLI only |
+
+The spread is the whole argument: at ±0.01 the engine finishes synthesizing 1.5–1.8× faster than the audio plays, every run; at ±0.25 some runs fall behind real time and a live listener hears the stream stall mid-sentence. The rollback path stays in the repo untouched — `TTS_BACKEND=llama-tts-cli` in `scripts/frank-tts.env` still selects the per-request CLI engine, and that file's header documents what it costs.
+
+## Three laws this service lives under
+
+**1. The cold-voice law → the unit warms at boot.** The **first** speech request for a registered voice decodes the whole reference clip to snapshot its codec state: **6.2–8.0 s, first audio byte at 5 530 ms**. Every later request for that voice restores the snapshot in **0.5 ms**. Registrations live in memory only — a restart forgets every voice — and re-registering does **not** warm a voice, only synthesizing does. So `frank-tts-engine.container` carries
+
+```
+ExecStartPost=-/usr/bin/podman exec frank-tts-engine /app/warm-voices.sh
+TimeoutStartSec=900
+```
+
+and the warm pass runs on every start including boot. Without it, whoever asks for audio first that day pays 5.5 s of silence. The `-` prefix is load-bearing: with `Restart=always`, a warmer that exits non-zero would restart the container and crash-loop the endpoint forever. The hook is `podman exec` rather than a host script **because this container publishes nothing** — there is no address the host could dial — and a consequence worth knowing: an exec inherits the unit's `EnvironmentFile`, so the warmer's knobs (`VOICES_DIR`, `HEALTH_WAIT`, `WARM_TEXT`, `REQUEST_TIMEOUT`) live in `scripts/frank-tts-engine.env` beside the engine's own. The deployer runs the same hook a second time so a failed warm becomes a deploy result rather than only a journal line, and so the per-voice numbers land on the console:
+
+```
+frank-tts-engine-warm: voice narrator1 cold=6821ms warm=412ms
+frank-tts-engine-warm: 3 voice(s) registered and warm
+```
+
+**2. The thread law → nothing is ever pinned.** `tts-server` in this build has **no `-t`/`--threads` flag**: `src/backend.h` computes the CPU thread count as `std::thread::hardware_concurrency() / 2` (its comment: GEMM shares SIMD units across hyperthreads). Thread count therefore follows what the kernel *reports*, not what a cgroup *allows* — so `CPUQuota=`, `CPUAffinity=`, `taskset` or a slice silently changes the engine's GEMM tiling and its timings, with no log line. Nothing in this fleet pins this container. If a neighbour starves it, fix the neighbour.
+
+**3. Streaming is not buffered.** At the same seed, `response_format=pcm` (chunked, codec chunks pushed as they decode) and `response_format=wav` (buffered) differ in **92.2 % of samples**, −41.6 dB RMS. Nothing may compare the two paths, cache one against the other, or assume a seed pins output across `response_format`. `frank-tts` always asks for `wav`; the warmer asks for `wav`; the test seam is forbidden from pinning either.
+
+## The voice registry contract
+
+A voice becomes known to the engine through `POST /v1/audio/voices`, and only these shapes are accepted:
+
+- `{"name": …, "wav_b64": …}` — the reference clip travels as base64 WAV (the engine resamples to 24 kHz internally). **This is what the boot warmer sends.**
+- `{"name": …, "spk_b64": …, "rvq_b64": …}` — the extracted embedding plus the reference codec codes. **`spk_b64` alone is rejected** (`src/tts-server.h:480`): it is `wav_b64` or *both* of the pair.
+
+Whether a registered voice is *embedding-only* or *in-context-learning* is then decided by `ref_text`: `tools/tts-server.cpp:258` selects ICL only when **both** `ref_text` and the reference codes are present. Registering `{name, wav_b64}` with no `ref_text` therefore yields the **x-vector voice** — the shipped default (0.57–0.63 warm RTF against ICL's 0.67) and the only one this fleet can produce honestly, because the audition crops have no trustworthy transcript to put in `ref_text`. The ICL door stays open for batch work like the podcast render: a pack that wants it needs its text in the pack plus one key in the payload built by `dankclaw/voiceservice/tts-engine-warm.sh`.
+
+The packs themselves are host state at `/home/dank/voices/<name>/reference.wav` (24 kHz mono PCM), alongside the `reference.spk` / `reference.rvq` extraction and a manifest. Both halves of the voice stack read that directory — `frank-tts` for its name list, the warmer for its registrations — and `tts-server` never opens it. Two naming facts, both from the source: pack names must be **lowercase**, because `tts_voice_name` lowercases every name engine-side while the façade matches the directory name exactly (the warmer refuses anything outside `[a-z0-9._-]`); and `GET /v1/audio/voices` at this commit returns an empty JSON object rather than the voice list (the handler builds the array and never attaches it to the document), so **use the façade's `/v1/voices` for "which voices exist"** and treat the engine's listing route as broken, not empty.
+
+## Status visibility
+
+The engine is scraped by **nothing in Prometheus** and has **no homepage card**, and both are shape decisions rather than gaps. It exposes no metrics endpoint; and since it publishes no port, there is no address the host's status checker (`scripts/homepage-status.py`, which dials `host:port`) or the `dankclaw_default` Prometheus container could reach. That absence is the point of the network shape, not a cost of it (see [[Container Network Namespaces]] for the netavark rule that makes a host-loopback publish useless to a peer container anyway). Its up-state is visible in four places, and the runbook uses all of them:
+
+- `systemctl --user status frank-tts-engine` — the unit, including whatever the warm hook logged on the way to `active`.
+- `podman healthcheck run frank-tts-engine` — runs the unit's own `HealthCmd` against `/health` on demand and exits non-zero when the engine does not answer. This is also what `scripts/deploy-remote.sh` gates the deploy on (`wait_container_healthy`), precisely because there is no URL to gate on.
+- `podman exec frank-tts-engine curl -fsS http://127.0.0.1:8880/health` — loopback is valid **inside** the container's namespace, which is where the address lives.
+- The journal of the warm pass: `journalctl --user -u frank-tts-engine`, whose per-voice `cold=` / `warm=` lines are the only signal that voices are actually registered — a live HTTP listener with an empty registry still looks healthy.
+
+The **façade** on 7772 is the pair's public surface and carries the probe. Note the honest limit there: a façade that answers `/health` does **not** prove the engine behind it is alive — it reports its backend and its voice list, not an upstream ping. That is exactly why the warm pass is part of the deploy and not only of the boot.
+
+## Files this service owns
+
+| Path | Role |
+|---|---|
+| `dankclaw/voiceservice/Containerfile.engine` | two-stage build of the pinned commit, proven cmake line, digest-pinned base, ships both scripts |
+| `dankclaw/voiceservice/tts-engine-start.sh` | image entrypoint (`/app/start.sh`): env → flags, refuses to boot without weights |
+| `dankclaw/voiceservice/tts-engine-warm.sh` | boot warmer (`/app/warm-voices.sh`): register from `reference.wav`, speak one sentence, report cold/warm |
+| `dankclaw/voiceservice/quadlet/frank-tts-engine.container` | the unit: bridge only, no publish, env file, two read-only mounts, health probe, warm hook, `Restart=always` |
+| `dankclaw/voiceservice/quadlet/frank-tts-engine.network` | the private 10.89.5.0/24 bridge, with the subnet registry |
+| `scripts/frank-tts-engine.env` | paths and numbers only, with the thread law and the cold-voice law in its header |
+| `scripts/download-frank-tts-engine-qwentts.sh` | weight fetcher: no resume, byte count + LFS oid check, `--verify-only` |
+| `scripts/deploy-remote.sh` → `deploy_frank_tts_engine` | weights gate → build → quadlet → restart → container health → warm |
+| `tests/frank_tts_engine.bats` | the seam: generator output, entrypoint argv, warmer against a stub engine, planner and routing maps |
+
+## Deploy order (host steps, in order)
+
+Nothing below has been run. Steps 1–5 are this service; 6–7 are what unblocks the podcast pipeline.
+
+1. **Fetch the weights** — `scripts/download-frank-tts-engine-qwentts.sh` (1.4 GiB, byte + sha256 verified, idempotent; `--verify-only` is what the deployer calls).
+2. **Deploy the engine** — `./scripts/deploy.sh dankclaw frank-tts-engine`. Builds the image (needs github.com once), installs the unit and the network file, restarts, gates on the container's health status, then warms.
+3. **Confirm the endpoint is alive** — `podman exec frank-tts-engine curl -fsS http://127.0.0.1:8880/health` → `{"status":"ok"}`, and `systemctl --user status frank-tts-engine` showing the unit `active` with the warm pass behind it.
+4. **Confirm the voices are known** — the warmer's journal lines must name every pack; once the façade is up, `curl http://127.0.0.1:7772/v1/voices` is the authoritative list.
+5. **Prove the cold-voice law is paid at boot, not by a listener** — two identical synthesis requests for one voice, back to back, from inside the engine's namespace; the **second** must answer well under a second (`warm=` in the journal is already that number; the manual pair is the confirmation on the real artifact).
+6. Then the façade on **7772** (its own page): nothing may be published there until the engine answers, because open-notebook's render fails the moment the façade is up and the engine is not.
+7. Nothing on 7772 exists yet — that is why open-notebook's podcast render cannot run. See [[Open Notebook]].
+
+## Troubleshooting
+
+| Symptom | Meaning | Move |
+|---|---|---|
+| Unit restarts every 10 s, journal says `cannot read /models/…` | weights missing or the mount is empty | run the fetcher; re-deploy |
+| Unit `active`, but every voice name returns 400 from the façade | the engine restarted and lost its in-memory registry, or the warm pass failed | `journalctl --user -u frank-tts-engine` for the warmer's lines; `podman exec frank-tts-engine /app/warm-voices.sh` |
+| First request of the day is slow, the rest are fast | the warm pass did not run (the hook carries `-`, so it cannot fail the unit) | look for `did not answer` in the journal — the warmer gave up while the model was still loading |
+| Everything is ~2× slower after a systemd tweak | a cpuset/cap pin changed `hardware_concurrency()` and the engine resized its thread pools | remove the pin (law 2) |
+| `502` from the façade with `frank-tts upstream request failed` | the façade cannot resolve or reach the engine | `podman network inspect systemd-frank-tts-engine` and `podman inspect frank-tts --format '{{json .NetworkSettings.Networks}}'` — the façade must be attached to the bridge; a `127.0.0.1:8880` or `host.containers.internal:8880` upstream in `scripts/frank-tts.env` is the old shape and cannot work |
+| A voice is missing from the list | its directory has no `reference.wav`, or the name is not lowercase | fix the pack; both are refused loudly by design |
+| `podman exec` in the deploy says `no such file or directory` for `/app/warm-voices.sh` | the image predates the warmer | rebuild: `build_compose_image` skips on an unchanged `Containerfile.engine`, and the `COPY` of the warmer changed it |
@@ -0,0 +1,132 @@
+---
+type: reference
+description: "open-notebook is the fleet's podcast generator on Dankclaw: notes and sources in, a multi-speaker episode out — script written by frank-zealot, voices rendered by frank-tts, no cloud provider anywhere in the path."
+tags:
+  - dankclaw
+  - open-notebook
+  - podcasts
+  - quadlet
+timestamp: 2026-10-18
+---
+
+# Open Notebook
+
+open-notebook ([lfnovo/open-notebook](https://github.com/lfnovo/open-notebook)) is the notebook layer that turns existing notes and sources into a **spoken episode**: an outline, then a dialogue transcript, then one synthesized clip per speaker turn, concatenated with ffmpeg into an MP3. In the fleet it is the consumer that closes the loop Frank's audio stack was built for — the script is written by **frank-zealot**, the voices are rendered by **frank-tts**, and nothing leaves the LAN.
+
+**It is NOT deployed.** This page documents repo-owned configuration — the Quadlet units, the env file, the deployer path, the homepage card — and the contract those files were written against. On 2026-10-18 no `open-notebook` or `open-notebook-surrealdb` container exists on Dankclaw (`podman ps -a` census, 2026-10-18), and the homepage card ships `wip: "down"` with `showLink: false`, so the card is hidden and reported `wip-down`. Deploying it is a deliberate next step, not a pending one.
+
+**Host:** Dankclaw (rootless Podman, user `dank`) — **Ports:** 8502 UI and 5056 API, published on the LAN, **no vhost and no Caddy route** — **Deployer:** `open-notebook` (one service, two units) — **Docs:** https://github.com/lfnovo/open-notebook
+
+## Facts (verified 2026-10-18 against the pinned images, upstream source, and the live host)
+
+| Item | Value |
+|------|-------|
+| App image | `docker.io/lfnovo/open_notebook:v1-latest@sha256:54b2025a4a4853c188f74b9b8246eca8c5480e5dd1babfa92db1038ff2f30212` (`open-notebook.container:79`) — the tag upstream's own `docker-compose.yml:27` pins for the multi-container shape. `v1-latest` is a moving tag, so the manifest-list digest (resolved from the registry 2026-10-18) is what makes this reproducible |
+| Database image | `docker.io/surrealdb/surrealdb:v2@sha256:e5d7387e3727bbe2f7cd6d869e48cd34777272258572ead37c9656b25f745723` (`open-notebook-surrealdb.container:66`) — that digest is **SurrealDB 2.7.0** (image built 2026-09-23; measured by running the digest: `surreal version`) |
+| Do NOT use | the `-single` tags (`v1-latest-single`). That variant bundles SurrealDB inside the app image and is deprecated upstream; here it would give the host a second, hidden database |
+| Ports | container 8502 (Next.js UI) + 5055 (FastAPI API) → published `0.0.0.0:8502:8502` and `0.0.0.0:5056:5055` (`open-notebook.container:83-84`). **Host 5055 is taken**: seerr publishes `127.0.0.1:5055` (`dankclaw/seerr/quadlet/seerr.container`, and `ss -ltn` on Dankclaw shows `127.0.0.1:5055` live, 2026-10-18). The API therefore leaves on 5056, which is what forces `API_URL` (below) |
+| Database port | 8000 inside its own namespace, **never published** (`open-notebook-surrealdb.container` has no `PublishPort`). Upstream publishes `127.0.0.1:8000` for debugging (`docker-compose.yml:18`); this unit does not, and the seam asserts that it stays that way |
+| Data | `open-notebook-data:/app/data` (named volume: uploads, LangGraph SQLite checkpoints, extraction caches) **plus** the interim host bind `/home/dank/media/podcasts:/app/data/podcasts` (`open-notebook.container:87-88`); database in the `open-notebook-db` named volume |
+| Networks | app: `dankclaw_default` first, then the private `systemd-open-notebook` (10.89.4.0/24, `open-notebook.network:33`); database: the private bridge only. Order is load-bearing — the generated `--network` flags keep file order, so the default route rides the network where `host.containers.internal` is proven |
+| Units | `dankclaw/open-notebook/quadlet/open-notebook.container` → `open-notebook.service`; `open-notebook-surrealdb.container` → `open-notebook-surrealdb.service`; both `Restart=always`, `RestartSec=10` / `5`, `[Install] WantedBy=default.target` — boot-persistent per [[Quadlet Lifecycle]] (generated units cannot be `enable`d on this host; the `[Install]` section is what the v1 generator honors at user-manager start) |
+| Health | app: `curl -fsS http://127.0.0.1:5055/health` (`open-notebook.container:89`); database: `/surreal is-ready` (`open-notebook-surrealdb.container:73`) |
+| Env | `scripts/open-notebook.env` (repo, knobs) then `/home/dank/Containers/open-notebook/env` (host, secrets, mode 600) — two `EnvironmentFile=` lines per unit, repo file **first** because the last file wins |
+| Deployer | `deploy_open_notebook` in `scripts/deploy-remote.sh`: seed secrets → ensure both digest pins are in local storage → install both units + the network → `mkdir -p /home/dank/media/podcasts` → restart database, wait for its container health → restart app → `wait_for_health open-notebook http://127.0.0.1:5056/health 180` |
+
+## What the image actually runs
+
+One container, three processes under supervisord (`supervisord.conf` upstream): `uvicorn api.main:app --port 5055` (`:12`), the job worker (`:25`), and the Next.js frontend (`:39`). Two consequences the config depends on:
+
+- **One unit owns the whole app.** There is no separate worker or frontend container to scale or restart, and the frontend refuses to start until the API answers (`wait-for-api.sh && node server.js`, `supervisord.conf:39`) — so gating the API gates the UI.
+- **The worker's concurrency comes from the environment**, not a flag baked into the image: `--max-tasks ${OPEN_NOTEBOOK_WORKER_MAX_TASKS:-5}` (`supervisord.conf:25`). Setting it in the env file is a real change, not decoration.
+
+Also from the image itself: `WORKDIR /app` and `EXPOSE 8502 5055` (`Dockerfile:84`, `:126`), **no `USER` line** (the app runs as container root, which in this host's rootless map lands as `dank` — the [[Seerr]] UID note measured `0 → 1000` on this machine), and `curl` **and** `ffmpeg` installed in the runtime layer (`Dockerfile:74-76`) — curl makes the health probe possible without a shell wrapper, ffmpeg is how the per-line clips become one file.
+
+`DATA_FOLDER` is hard-coded `"./data"` (`open_notebook/config.py:5`) and `PODCASTS_FOLDER` is `"./data/podcasts"` (`:19`); the database stores each episode's audio path **relative** to that folder (`episodes/<uuid>/audio/<uuid>.mp3`), and the download route is `GET /api/podcasts/episodes/{id}/audio`. That is why covering one subdirectory with a bind mount is sufficient — nothing in the database has to change if the mount moves.
+
+## Provisioning the providers (after first boot; UI or REST, never a unit)
+
+Credentials are stored in the database, encrypted, and are **not expressible in env or a Quadlet file**. The sequence is one-time, in **Manage → Models**, and both entries use provider type **OpenAI Compatible** (upstream: any server that implements `/v1/audio/speech` works this way — `docs/5-CONFIGURATION/local-tts.md:5`).
+
+1. **TTS credential** — base URL **`http://frank-tts:7772/v1`**. The `/v1` is part of the URL: the client posts to `<base_url>/audio/speech`, so a base URL without `/v1` 404s on every dialogue line (`local-tts.md:72-80`, the base-URL table, always carries `/v1`). `frank-tts` resolves by container name because the app is attached to `dankclaw_default`, the network frank-tts's unit joins (`dankclaw/voiceservice/quadlet/frank-tts.container:51-52`). If frank-tts is ever moved off that network, the published-port form is `http://192.168.0.143:7772/v1` — a published port is dialable at the host's LAN address from any netns. The API-key field stays empty; frank-tts does not authenticate.
+2. **LLM credential** — base URL **`http://host.containers.internal:7771/v1`**, model row `frank-zealot`. frank-zealot is a **host process** on `0.0.0.0:7771` (`ss -ltn` on Dankclaw shows the listener with no container owning it, 2026-10-18), and on this netavark host a bridge container reaches the host's LAN IP only at a *published* port — which is why Prometheus scrapes the same endpoint as `host.containers.internal:7771` (`shared/prometheus/prometheus.yml:89-111`, "not their own LAN addresses"). See [[Container Network Namespaces]]. `http://192.168.0.143:7771/v1` is the variant to try only if the gateway name ever stops resolving; it is expected to be refused from a bridge netns.
+3. **Model rows are created by name.** Discovery is optional (see the next section): type the model id and confirm the add. One base URL per credential, so the TTS and LLM credentials are necessarily two separate configurations.
+
+**Verify reachability before saving**, from inside the container, because both addresses are netns-dependent:
+
+```bash
+podman exec open-notebook curl -sS http://frank-tts:7772/health
+podman exec open-notebook curl -sS http://host.containers.internal:7771/v1/models
+```
+
+**The blocker to state plainly:** frank-tts is built, named and tested but **not deployed** — nothing answers on 7772 (`ss -ltn`, Dankclaw, 2026-10-18; [[Local TTS and Voice Cloning]] records the same census). open-notebook deployed today writes scripts and fails at the first voice line. frank-tts ships first, or podcast generation waits.
+
+**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.
+
+## Speakers and voices: 1–4, and the IDs are free text
+
+A **speaker profile** carries one to four speakers (`docs/3-USER-GUIDE/creating-podcasts.md:27`), each with a personality and a **Voice ID that is typed exactly and passed through to the TTS request untouched** (`:29`) — there is no whitelist, no enum, no validation against a voice list. So the fleet's voice-pack names work verbatim:
+
+| Speaker | Voice ID to type |
+|---------|------------------|
+| Speaker 1 | `narrator1` |
+| Speaker 2 | `narrator2` |
+| Speaker 3 | `narrator3` |
+
+Those are the pack names frank-tts resolves from `/home/dank/voices` (`scripts/frank-tts.env` header: a voice is real exactly when `/voices/<name>/reference.wav` exists). Two traps, both from upstream's shipped defaults:
+
+- The three seeded speaker profiles carry **OpenAI voice names** (`nova`, `alloy`, …) and **no voice model at all** — they show a "Setup required" badge, and generation fails with a voice error until they are edited (`creating-podcasts.md:13`, `:33`; `local-tts.md:89`). Add a `narrator1`/`narrator2` pair (or a third/fourth) rather than editing the seeded ones in place.
+- Two speakers with the same voice are hard to follow (`creating-podcasts.md:89`). Distinct packs per speaker is the point of the 1–4 shape.
+
+## Two buttons that fail against frank-tts, and why that is cosmetic
+
+- **Test Connection** probes `GET <base_url>/models` (`open_notebook/ai/connection_tester.py:208-229`). frank-tts serves exactly two GET routes — `/health` and `/v1/audio/voices` — and 404s every other path (`dankclaw/voiceservice/app.py:228-238`). The button reports a failure against a healthy server.
+- **Discover Models** does the same `GET <base>/models` (`open_notebook/ai/model_discovery.py:26-28`) and finds nothing to list.
+- The TTS test path also synthesises with a **hard-coded voice `alloy`** for `openai_compatible` (`connection_tester.py:328-336`), which is not a fleet voice pack and would be refused even if the probe reached frank-tts.
+
+None of it blocks anything: model rows are added **by name** ("If a model isn't listed, type its id and click Add", `local-tts.md:82`) and the Voice ID field is free text. The failure is a missing `/models` route on a deliberately minimal shim, not a broken credential. The honest end-to-end test is a real generation job, or the `podman exec … curl /v1/audio/speech` call frank-tts's own seam documents.
+
+## The CPU guard, and why both numbers are 1
+
+Defaults are `TTS_BATCH_SIZE=5` and `OPEN_NOTEBOOK_WORKER_MAX_TASKS=5` (`docs/5-CONFIGURATION/environment-reference.md:129-130`) — five parallel synthesis requests from five parallel jobs. frank-tts spawns an engine process per request (about 8 GiB resident, 8 threads, from the frank-tts CPU trial of 2026-10-18; `scripts/frank-tts.env` pins `LLAMA_TTS_THREADS=8`), on a machine that also serves frank-dragoon and frank-zealot. Five of those is ~40 GiB and forty threads competing with two LLM endpoints for the same cores. `scripts/open-notebook.env:87-88` sets both to 1: one episode at a time, one voice line at a time. Upstream's own guidance is the same direction ("Set 1 for a local model on a single GPU", "Lower it … for rate-limited or single-threaded TTS servers").
+
+The clock next to it: `ESPERANTO_TTS_TIMEOUT` (`:91`) is patience **per dialogue line**, not per episode — a three-minute episode is dozens of separate POSTs, and the tail of a long turn on a CPU engine goes past upstream's 300 s default. It is set to **660, one round-trip outside `SHIM_TIMEOUT=600`** in `scripts/frank-tts.env` (frank-tts's own per-request ceiling): nested budgets go inside-out — the same rule that file states for `LLAMA_TIMEOUT` — so a frank-tts give-up arrives labelled as frank-tts's error instead of the worker's own timeout, and re-measuring frank-tts cannot silently strand this number below it. An abandoned request does not cancel the engine process; it only strands the episode in "generating".
+
+## Secrets, and the difference between blank and unset
+
+`OPEN_NOTEBOOK_PASSWORD` unset means **authentication off** (`environment-reference.md:46`) — every API route, including the episode-audio download, answers anyone who can reach the published port. That is a real exposure on a LAN-published service with no vhost and no guard chain in front of it, which is why `deploy_open_notebook` refuses to start either unit unless the seeded host file carries a value for all four secret keys (`OPEN_NOTEBOOK_ENCRYPTION_KEY`, `OPEN_NOTEBOOK_PASSWORD`, `SURREAL_PASSWORD`, `SURREAL_PASS`). `OPEN_NOTEBOOK_ENCRYPTION_KEY` is separately load-bearing: it is **required to save any provider credential**, and changing it later makes stored keys undecryptable (`:44`).
+
+The tracked file declares the secrets **empty** and the host file supplies them; podman applies `--env-file` arguments in order and the last one wins (verified against the generated `ExecStart` line, 2026-10-18). Reordering the two `EnvironmentFile=` lines in a unit would blank every credential — that is the trap the seam's ordering assertion exists for.
+
+The database has the same trap in a different spelling: the app reads `SURREAL_PASSWORD`, the `surreal` CLI reads `SURREAL_PASS` (its `start --help` prints `[env: SURREAL_PASS=]`; measured against the pinned digest). One value, written twice, by the seed function — so the pair cannot be given different root passwords. Both arrive through the environment, **not** through `Exec=`: `--pass` on the command line would put the database password in `/proc/<pid>/cmdline`, readable by any `ps` on the host. Measured with the pinned image: env-only credentials produce `Initialising credentials user=…`, the root user is created on first boot, a correct login authenticates and a wrong password is refused — no `--user`/`--pass` flags needed, and no `--bind` either, because the image's own `SURREAL_BIND=0.0.0.0:8000` is what makes the RPC reachable from another container at all.
+
+## Episode destination: interim, and reversible (issue #7)
+
+**Episode files currently exist in two places by design.** The app's own state stays in the `open-notebook-data` named volume; finished audio additionally lands on the host, because `/home/dank/media/podcasts` is bind-mounted over `/app/data/podcasts` (`open-notebook.container:88`). That is the **interim** answer to where episodes live: the destination is an open decision tracked as **Gitea issue #7, labelled `human-only` — agents must not work it.** Until Frank settles it, episode MP3s are ordinary files in his home directory, readable without `podman unshare`, which the database volume would require (measured with the pinned SurrealDB image).
+
+Reversibility is one line: delete the `Volume=/home/dank/media/podcasts:/app/data/podcasts` line and the episodes go back to living solely inside the named volume. Nothing else in the config assumes the bind. See [[Storage Policy]] for the repo's storage conventions this interim state deliberately bends.
+
+## Deploying, and the digest-pull step
+
+```bash
+# on Dankclaw, as dank — the pins are Pull=never, so fetch them first
+podman pull docker.io/surrealdb/surrealdb:v2@sha256:e5d7387e3727bbe2f7cd6d869e48cd34777272258572ead37c9656b25f745723
+podman pull docker.io/lfnovo/open_notebook:v1-latest@sha256:54b2025a4a4853c188f74b9b8246eca8c5480e5dd1babfa92db1038ff2f30212
+```
+
+`deploy_open_notebook` runs the same two pulls when the image is absent from local storage, so the manual step is only needed to pre-seed an offline host or to bump a pin. Then `scripts/deploy.sh --target dankclaw --service open-notebook`. Both `Pull=never` and the pin comment live in the unit files; upgrading means **editing the digest**, not repulling a tag — see [[Deployment Flow]].
+
+## Rollback
+
+- **Nothing deployed (today's state):** revert the commits. There is no host state to undo — no unit, no container, no volume, no `/home/dank/media/podcasts` directory beyond what the deployer would create.
+- **Deployed:** `systemctl --user stop open-notebook.service open-notebook-surrealdb.service`, then move the three files (`open-notebook.container`, `open-notebook-surrealdb.container`, `open-notebook.network`) out of `~/.config/containers/systemd/` into `~/.AGENTTRASH/` — never `rm` — and `systemctl --user daemon-reload`. The generated units disappear with their sources.
+- **Kept on purpose:** the `open-notebook-data` and `open-notebook-db` named volumes and `/home/dank/media/podcasts`. Episode audio and the notebook database are user data; removing them is a separate, deliberate act, and episode files are host files precisely so they can outlive the container.
+- **Homepage:** the card is `wip: "down"` + `showLink: false`, so retiring the service needs no card surgery beyond setting it back to that state.
+
+## Citations
+
+- Repo: `dankclaw/open-notebook/quadlet/{open-notebook.container,open-notebook-surrealdb.container,open-notebook.network}`, `scripts/open-notebook.env`, `dankclaw/.env.example`, `scripts/deploy-plan.py`, `scripts/deploy-remote.sh` (`seed_open_notebook_env`, `ensure_pinned_image`, `deploy_open_notebook`), `scripts/deploy.sh`, `scripts/test-changed.sh`, `tests/open_notebook.bats`, `shared/homepage/services.json`, `dankclaw/seerr/quadlet/seerr.container` (the 5055 collision), `dankclaw/voiceservice/{quadlet/frank-tts.container,app.py}`, `scripts/frank-tts.env`, `shared/prometheus/prometheus.yml`
+- Upstream `lfnovo/open-notebook` @ main, read 2026-10-18: `docker-compose.yml:3,10,11,18,27,29-30,39-43`, `Dockerfile:69-76,84,126,140,158`, `supervisord.conf:12,23-25,39`, `api/main.py:73,227-230,239-241,414`, `api/credentials_service.py:418-420,552`, `api/routers/credentials.py:426-429,433-437`, `open_notebook/config.py:5,19`, `open_notebook/podcasts/audio_paths.py`, `open_notebook/ai/connection_tester.py:208-238,326-336`, `open_notebook/ai/model_discovery.py:26-28`, `docs/3-USER-GUIDE/creating-podcasts.md:13,27,29,33,89`, `docs/5-CONFIGURATION/environment-reference.md:44,46,106,110,129,130`, `docs/5-CONFIGURATION/local-tts.md:5,45,72-82,89`
+- Registry (2026-10-18): `lfnovo/open_notebook` tags (`v1-latest`, `latest`, the `-single` set) and manifest-list digests; `surrealdb/surrealdb` `v2` → 2.7.0
+- Local measurements (2026-10-18, workstation, pinned digests): `surreal start --help` (credential and bind options carry `[env: SURREAL_*]`); running the pinned SurrealDB digest with env-only credentials (credential init in the log, correct login authenticates, wrong password refused, `/surreal is-ready` → `OK` exit 0, named volume owned by the mapped uid); the v1-compatible Quadlet generator dry-run of all three unit files (two `--env-file` in order, two `--network` in order, named volume + host bind, both health probes, `--pull never`)
+- Host evidence (Dankclaw, 2026-10-18, read-only): `ss -ltn` (`127.0.0.1:5055` held by seerr, `0.0.0.0:7771` a host listener, nothing on 7772/8502/5056/8000), `podman ps -a` (no open-notebook container, `dankclaw_default` present), subnet registry from `dankclaw/open-webui/quadlet/open-webui.network`
@@ -1,7 +1,7 @@
 ---
 type: research
 title: Local TTS and Voice Cloning
-description: How to create a new local TTS voice from sample files in oh-my-pi, the 2026 open-weight voice-cloning landscape, the full local AI audio stack, and a recommended homelab deployment.
+description: How to create a new local TTS voice from sample files in oh-my-pi, the 2026 open-weight voice-cloning landscape, the measured CPU engine A/B behind frank-tts and the arm A decision, the full local AI audio stack, and a recommended homelab deployment.
 tags:
  - research
  - tts
@@ -10,7 +10,7 @@ tags:
  - stt
  - vllm-omni
  - kokoro
-timestamp: 2026-10-18T00:00:00Z
+timestamp: 2026-10-18T16:05:00Z
 ---

 # Local TTS and Voice Cloning
@@ -47,13 +47,16 @@ greenfield: every fleet endpoint declares `input: [text, image]`
  local server needs a speech-role entry, not a patch.
 - **Fleet plan (2026-10-18): CPU-only on Dankclaw, not the 3090.** Gitea issue
  #2 rules out every GPU option (the 3090 has carried frank-zealot since
-  2026-10-17; both R9700s are frank-archon's), so the shape is a VoxCPM2 GGUF
-  engine on **8880** behind a voice-registry shim on **8890**
-  (`scripts/voiceshim.env`, `dankclaw/voiceservice/`) that speaks OpenAI
-  `/v1/audio/speech` and resolves voices by name. Nothing is deployed yet — on
-  2026-10-18 `voiceshim` has no unit installed and nothing answers on 8880 or
-  8890. STT (Parakeet TDT 1.1B, CC-BY-4.0) stays on CPU. **No RTF or quality
-  number has been measured for this shape**, so this page states none.
+  2026-10-17; both R9700s are frank-archon's). The shape is a TTS engine on
+  **8880** behind **frank-tts**, the fleet's speech endpoint on **7772**
+  (`scripts/frank-tts.env`, `dankclaw/voiceservice/`): one OpenAI
+  `/v1/audio/speech` façade that resolves a voice *by name* and never shows a
+  path. Nothing is deployed — no `frank-tts` unit and no container exist on the
+  host and nothing listens on 7772 or 8880 (checked 2026-10-18). STT (Parakeet
+  TDT 1.1B, CC-BY-4.0) stays on CPU. **The engine is chosen: arm A**
+  `qwentts.cpp` **resident `tts-server`, 1.7 B talker** — measured in
+  *Measured CPU engine A/B* below and picked on the live-output criterion in
+  [Decision: arm A for live output](#decision-arm-a-for-live-output-2026-10-18).

 ## Can Kokoro learn a new voice?

@@ -133,11 +136,11 @@ accepts only its built-in voice list, so a custom pack needs a patch.

 Paths for a Frank-cloned voice (2026-10-18):

-1. **Local server + speech role, no patch.** Register the local engine (or the
-   8890 voice shim) as a provider model on the `openai-speech` API and point
-   `modelRoles.speech` at it; the shim turns a voice *name* into a reference
-   clip and forwards it as base64 `reference_audio`
-   (`scripts/voiceshim.env:19-35`). Not deployed as of 2026-10-18.
+1. **Local server + speech role, no patch.** Register frank-tts (port 7772) as
+   a provider model on the `openai-speech` API and point `modelRoles.speech` at
+   it; the façade turns a voice *name* into that pack's reference clip and
+   forwards it as base64 `reference_audio` (`scripts/frank-tts.env`,
+   `TTS_BACKEND=omni-http`). Not deployed as of 2026-10-18.
 2. **xAI console custom voice — works today, zero code.** Record 2–3 min clean
   speech (≤120 s, 24 kHz 16-bit mono WAV) → console → `voice_id` → speech
   tool. Free (≤30 voices), cloud, US-only.
@@ -206,29 +209,161 @@ The CPU shape does not need a Python server at all:
  `VoxCPM2-Acoustic-F16.gguf`, Apache-2.0 card) or from the fork's own
  `tools/omni/voxcpm2/convert_voxcpm2_to_gguf.py`.

-Nothing has been measured on this fleet for any of these engines — no RTF, no
-latency, no MOS. That absence is the finding, not an omission.
+Arm B (`llama-tts`) and arm A (`qwentts.cpp`) have both been measured on this
+box — RTF, first-audio latency and RSS are in the next section. The other
+servers in the table above (vLLM-Omni, Kokoro-FastAPI, CosyVoice, F5-TTS,
+GPT-SoVITS) remain unmeasured here; that absence is still the finding.
+
+## Measured CPU engine A/B (2026-10-18)
+
+Both candidate upstreams for frank-tts were measured on Dankclaw's CPU — 8
+threads, no GPU touched, three runs per arm, seed 42, identical text, against
+the fleet's own audition voice packs.
+
+- **Arm A — [`ServeurpersoCom/qwentts.cpp`](https://github.com/ServeurpersoCom/qwentts.cpp)**
+  at commit `5916bf7c79dbb4e66fc059cdc507a79a23a28bb4` (2026-10-16), weights
+  from [`Serveurperso/Qwen3-TTS-GGUF`](https://huggingface.co/Serveurperso/Qwen3-TTS-GGUF):
+  `qwen-talker-1.7b-base-Q4_K_M.gguf` (1,219,245,248 B),
+  `qwen-talker-0.6b-base-Q4_K_M.gguf` (628,905,056 B),
+  `qwen-tokenizer-12hz-Q8_0.gguf` (291,150,624 B) — byte counts verified
+  against the Hub API. Builds with zero compiler warnings; `GGML_BLAS=OFF` is
+  forced on this host (only `libopenblas.so.0` exists, no dev headers, so the
+  vendor `buildcpu.sh` cannot configure).
+- **Arm B — mainline `llama-tts`** with `--tts-speaker-file`, i.e. the
+  `llama-tts-cli` backend `scripts/frank-tts.env` already implements.
+
+RTF is **seconds of compute per second of audio** (lower is better; below 1 is
+faster than real time).
+
+| Arm | RTF | Run spread | Peak RSS |
+|---|---|---|---|
+| A · 0.6 B talker, CLI | 0.44 | ±0.002 | 3.4 GiB |
+| A · 1.7 B, CLI, uncloned | 0.57–0.58 | ±0.006 | 4.7 GiB |
+| A · 1.7 B, CLI, embedding-only clone | 0.63 | ±0.02 | n/m |
+| A · 1.7 B, CLI, ICL clone | 0.92 | ±0.01 | n/m |
+| A · 1.7 B, resident `tts-server`, warm | 0.55–0.57 | ±0.01 | 5.7 GiB |
+| A · same, ICL voice warm / **cold (first request)** | 0.67 / **1.65** | one-shot | 5.7 GiB |
+| B · mainline `llama-tts` | 0.93–0.99 | ±0.25 | n/m |
+
+**Read RTF only within an arm.** Conditioning changes clip length — the same
+seed yields 18.00 s of audio embedding-only and 15.12 s under ICL — so the
+denominator is the arm's own audio duration.
+
+Arm A's resident server is ~1.7× faster than arm B and about 40× tighter in
+run-to-run spread, and it already serves the HTTP shape frank-tts's façade
+speaks: `/health`, `/v1/models`, `/v1/audio/voices` (GET/POST/DELETE),
+`/v1/audio/speech` (`wav`/`pcm`), chunked streaming with the first audio byte
+at 86–451 ms and a server-side time-to-first-audio of 94–112 ms. Arm B has no
+HTTP path at all — that is what the façade's CLI backend exists for.
+
+Four laws came out of the trial, each worth a line of configuration:
+
+- **Boot-warm every voice.** The first request for a registered voice decodes
+  the whole reference to snapshot codec state: 6.2–8.0 s, first audio byte at
+  5,530 ms. Later requests restore that state in 0.5 ms. An engine unit must
+  run one throwaway synthesis per voice at start, or the first request of the
+  day pays five seconds.
+- **Speaker artifacts are reusable and exact.** `qwen-codec` turns a reference
+  WAV into `.spk` (8,192 B x-vector) + `.rvq` (5,456–6,864 B, 16 codebooks × T,
+  11-bit packed) in 1.8–2.1 s at 1.3–1.5 GiB peak; replaying them yields a
+  **byte-identical** WAV and saves 1.4 s per request. That pair is the
+  engine-artifact term the voice-pack law in `scripts/frank-tts.env` reserves a
+  slot for — arm A pins it as `.spk` + `.rvq` beside `reference.wav`.
+- **Streaming is not bit-identical to buffered**, whatever the upstream README
+  claims: same text, seed and voice, 92.2 % of samples differ (peak delta
+  1139/32768, −41.6 dB RMS — inaudible). A fixed seed does not pin output
+  across `response_format`, so never mix the two paths in a cache or a golden
+  fixture.
+- **A voice cannot be registered from an embedding alone**: `POST
+  /v1/audio/voices` accepts `wav_b64` or **both** `spk_b64` and `rvq_b64`
+  (`src/tts-server.h:480`), so an embedding-only voice has to be sent as the
+  WAV, or the lone-`spk` path has to be upstreamed.
+
+**Likeness is not measurable at this resolution.** x-vector cosine against each
+speaker's own reference: ICL 0.9886 / 0.9901, embedding-only 0.9844 / 0.9812,
+uncloned 0.9228 — but **two different speakers score 0.9497** on the same
+metric. The whole clone effect lives in a 0.04-wide band and the
+ICL-over-embedding gap is inside noise, so the four audition clips
+(`/home/blank/voice-audition/qwentts-*.mp3`, each against its `armB-*.mp3`
+mainline partner, guide in `LISTEN-engine.md`) are the instrument. **The
+operator heard them on 2026-10-18 and passed every clone**, which removed the
+last axis measurement could not reach; the engine was then picked on
+live-output grounds ([Decision](#decision-arm-a-for-live-output-2026-10-18)).
+The cosine
+extractor is still worth keeping: it is engine-neutral (it scores mainline
+output through the same encoder) and it separates an uncloned voice cleanly.
+
+Two operational details. The engine takes 8 threads and exposes **no `-t`
+flag** — `src/backend.h` uses `hardware_concurrency()/2` and prints the choice
+at load, so pinning a cpuset on the quadlet changes that number implicitly. And
+ICL needs a reference transcript that did not exist: the fleet has no ASR
+endpoint and no audio input, so the crops were transcribed with
+`vosk-small-en-us` inside the work dir, and two of three transcripts came back
+suspect ("demon souls" for *Dark Souls*) — a reason to curate `ref_text` into
+the pack manifest instead of transcribing on the host.
+
+## Decision: arm A for live output (2026-10-18)
+
+Every audition pair passed, so likeness stopped being the tiebreak. The
+question became **which engine is better for live output** — the harness
+speaking a reply, an alert read aloud, a click-to-speak — and on that criterion
+RTF only has to stay under 1.0 with margin: what separates the arms is **time to
+first audio** and the **spread**, because an arm whose RTF can cross 1.0 stalls
+a live stream mid-sentence.
+
+| | arm A · `qwentts.cpp` `tts-server` | arm B · mainline `llama-tts` |
+|---|---|---|
+| first audio byte | 86–451 ms | model load, per request |
+| warm RTF | 0.55–0.67 | 0.93–0.99 |
+| run spread | ±0.01 | ±0.25 |
+| HTTP | serves `/v1/audio/speech` | none — façade CLI only |
+| RAM | 5.7 GiB resident | per-request, freed after |
+
+**Chosen: arm A, 1.7 B talker, resident `tts-server` in a `frank-tts-engine`
+container, with `TTS_BACKEND=llama-tts-cli` kept in the repo as the rollback.**
+Three consequences are configuration, not opinion: the unit **boot-warms every
+voice** (5.5 s cold first byte otherwise), it **does not pin a cpuset** casually
+(threads are `hardware_concurrency()/2`, no flag), and every pack registers with
+the **WAV** because the engine rejects a lone embedding.
+
+Two follow-ups stay open on purpose, and neither blocks the deploy:
+
+- **Talker size.** The 0.6 B arm measured 0.44 RTF at 3.4 GiB and has never
+  been auditioned — every clip above is 1.7 B. It is the lever for a CPU
+  co-tenancy problem, not a preemptive saving.
+- **ICL vs embedding-only.** Both passed the ear test. Embedding-only is the
+  shipped default: 0.57–0.63 vs 0.67 warm, and it needs no `ref_text`, which
+  this fleet cannot produce honestly (the ASR crops came back suspect). Packs
+  still carry `.spk` + `.rvq`, so ICL remains a per-voice opt-in for batch work
+  like the podcast render, where total time matters more than first byte.

 ## Recommended deployment (Dankclaw)

 As decided in Gitea issue #2, this stays **CPU-only on Dankclaw**: the RTX 3090
 has carried frank-zealot since 2026-10-17 and both R9700s are frank-archon's,
-so no card may be asked to co-host TTS. The shape is one engine plus a thin
-voice shim, and **nothing here is deployed as of 2026-10-18** — `systemctl
--user is-enabled voiceshim` reports `not-found` and nothing answers on 8880 or
-8890.
+so no card may be asked to co-host TTS. The shape is one engine plus one
+façade, and **nothing here is deployed as of 2026-10-18**: `frank-tts` has
+neither a unit nor a container on the host, and nothing listens on 7772 or
+8880.

 | Service | Image / install | Port | CPU | Notes |
 |---|---|---|---|---|
-| TTS engine | `llama-tts-server` (`tc-mb/llama.cpp-omni`) on a VoxCPM2 GGUF; `vllm/vllm-omni` + Qwen3-TTS only if a GPU is ever deliberately freed | 8880 | engine decision still open | OpenAI `/v1/audio/speech`; `n_gpu_layers` is there for a GPU boot |
-| Voice shim | `dankclaw/voiceservice/` (stdlib container) + `scripts/voiceshim.env` + `dankclaw/voiceservice/quadlet/voiceshim.container` | 8890 | yes | voice *name* → `reference.wav`, `voice`/`voice_id` on the wire, mp3 re-encode; backends `omni-http` (forwards base64 `reference_audio`) and `llama-tts-cli` (`--tts-speaker-file`, `nice 19`) |
+| TTS engine | **arm A `qwentts.cpp` `tts-server`** on the Qwen3-TTS GGUFs (decided 2026-10-18, above); arm B mainline `llama-tts` stays in the repo as the `llama-tts-cli` rollback; `vllm/vllm-omni` + Qwen3-TTS only if a GPU is ever deliberately freed | 8880 (container-internal) | open, evidence above | arm A serves OpenAI `/v1/audio/speech` itself and boot-warms each voice; arm B has no HTTP path and runs through the façade's CLI backend |
+| frank-tts | `dankclaw/voiceservice/` (stdlib container) + `scripts/frank-tts.env` + its quadlet | 7772 | yes | voice *name* → `/voices/<name>/reference.wav`, `voice`/`voice_id` on the wire, mp3 re-encode; backends `omni-http` (forwards base64 `reference_audio`) and `llama-tts-cli` (`--tts-speaker-file`, `nice 19`) |
 | STT (English) | Parakeet TDT 1.1B behind a FastAPI wrapper, or whisper.cpp server | 8882 | yes | CC-BY-4.0; LibriSpeech-clean WER 1.39 (model card) |
 | STT (multilingual, opt.) | faster-whisper `large-v3` int8 | 8883 | yes | MIT |
 | VAD | Silero (embedded) | — | yes | MIT; model file 2 327 524 B |

-8880/8890 are what `scripts/voiceshim.env:35,49` carry (`TTS_UPSTREAM=
-http://host.containers.internal:8880`, `SHIM_PORT=8890`); 8882-8883 for STT
-keep clear of the fleet's LLM ports 7770/7771.
+7772 is frank-tts's host port — the next slot in the fleet's model-endpoint
+family (7770 frank-dragoon, 7771 frank-zealot). The engine behind it keeps 8880,
+but **not as a host-loopback publish**: netavark DNATs published ports only, and
+a bridge container cannot reach a `127.0.0.1` bind on the host — that is the
+lesson that 502'd hermes (`AGENTS.md`). `host.containers.internal`
+(169.254.1.2) is the gateway, so it reaches a host service only when that
+service binds a routable address; `scripts/frank-tts.env` names it as the
+engine's address, which holds for a `0.0.0.0` bind and not for a loopback one.
+The deployed pair therefore shares one quadlet network and the façade addresses
+the engine by container name.

 ## Voice-creation workflow (the "from sample files" answer)

@@ -284,6 +419,10 @@ keep clear of the fleet's LLM ports 7770/7771.
  https://huggingface.co/openbmb/VoxCPM2
 - llama.cpp-omni TTS server: https://github.com/tc-mb/llama.cpp-omni ·
  https://raw.githubusercontent.com/tc-mb/llama.cpp-omni/master/tools/omni/voxcpm2/README.md
+- qwentts.cpp (arm A): https://github.com/ServeurpersoCom/qwentts.cpp at commit
+  `5916bf7c79dbb4e66fc059cdc507a79a23a28bb4` · weights
+  https://huggingface.co/Serveurperso/Qwen3-TTS-GGUF (byte counts against the
+  Hub API, 2026-10-18)
 - mainline `llama-tts`:
  https://raw.githubusercontent.com/ggml-org/llama.cpp/master/tools/tts/README.md ·
  Pocket-TTS weights: https://huggingface.co/kyutai/pocket-tts (CC-BY-4.0)
@@ -79,6 +79,8 @@ macOS mini) as quadlets inside its podman machine — not on Dankserver.
 - [[Postgres]] — Gitea database backend
 - [[Seerr]] — unified *arr request manager (guard-chained; fronts FrankBook-Pro's stack)
 - [[Marreta]] — content-cleaning proxy (guard-chained; shares SearXNG's Gluetun egress)
+- [[Open Notebook]] — podcast generator (scripts by frank-zealot, voices by frank-tts); repo-owned config, not deployed
+- [[Frank TTS Engine]] — the arm A TTS engine (`qwentts.cpp` resident `tts-server`, 1.7 B talker) behind frank-tts on a private bridge; repo-owned config, not deployed

 ## Infrastructure

@@ -2311,3 +2311,182 @@ every restart since the cutover.
  Kokoro-enum-only — so "the agent talks in my voice" needs that provider row or
  a `pi.registerProvider` extension, decided in phase 2.

+## 2026-10-18 — TTS engine picked: arm A `qwentts.cpp`, on the live-output criterion
+
+- Frank listened to the four audition pairs (`qwentts-*.mp3` against their
+  `armB-*.mp3` mainline partners) and **passed every clone**. That deleted the
+  only axis the A/B could not measure, and the question was reframed: **which
+  engine is better for live output**. On that criterion RTF only has to stay
+  under 1.0 with margin — the discriminators are time-to-first-audio and
+  run-to-run spread, because an arm whose RTF can cross 1.0 stalls a live
+  stream mid-sentence.
+- **Chosen: arm A `qwentts.cpp` @ `5916bf7`, the resident `tts-server`, 1.7 B
+  talker Q4_K_M + Q8_0 tokenizer, in a `frank-tts-engine` container on 8880.**
+  The `TTS_BACKEND=llama-tts-cli` path in `scripts/frank-tts.env` stays in the
+  repo as the rollback. The numbers that carried it: first audio byte 86–451 ms
+  against a per-request model load, warm RTF 0.55–0.67 against 0.93–0.99, spread
+  ±0.01 against ±0.25, and a native `/v1/audio/speech` against no HTTP path at
+  all. Three consequences are configuration, not preference: boot-warm every
+  voice, do not pin a cpuset (threads are `hardware_concurrency()/2`), register
+  every pack with its WAV (a lone embedding is rejected).
+- Two follow-ups deliberately **not** decided: the **0.6 B talker** (0.44 RTF,
+  3.4 GiB, never auditioned — every clip is 1.7 B) and **ICL vs
+  embedding-only** conditioning. Embedding-only is the shipped default because
+  it is cheaper and needs no `ref_text`, which this fleet cannot transcribe
+  honestly; `.spk` + `.rvq` still ride in every pack, so ICL remains a per-voice
+  opt-in for batch work where total time beats first byte.
+- **Addressing law corrected** in
+  [[Local TTS and Voice Cloning]]: the pair may not meet at a host-loopback
+  publish. netavark DNATs published ports only and a bridge container cannot
+  reach a host `127.0.0.1` bind — the lesson that 502'd hermes — so
+  `host.containers.internal:8880`, which `scripts/frank-tts.env` documents, is
+  correct only for a routable bind. The deployed pair shares one quadlet network
+  and the façade addresses the engine by container name.
+- **PR #12** (`feat/open-notebook-podcast` @ `114dd7a`, 8 commits, 403 tests) is
+  **merged** as `1eb8b21` (Frank's OK, given in session): open-notebook +
+  SurrealDB quadlets on the private bridge `10.89.4.0/24`, the API published on
+  **5056** because seerr holds `127.0.0.1:5055`, and `ESPERANTO_TTS_TIMEOUT`
+  moved 600 → **660** to sit one round-trip outside frank-tts's own
+  `SHIM_TIMEOUT`. Merged is not runnable: nothing listens on 7772 until the
+  voice stack lands, and the episode destination (`/home/dank/media/podcasts`)
+  stays interim pending Gitea #7.
+- Still in flight, not in this branch: `feat/frank-tts-engine` — the arm A image
+  build, the quadlet pair on one network, the boot-warm step, deployer /
+  planner / `test-changed.sh` routing, homepage and docs. This branch is also
+  where the two-branch overlap got resolved: merging `main` here conflicted on
+  `log.md` alone (both branches appended an entry) and took `index.md`,
+  `deploy-remote.sh`, `deploy-plan.py` and `test-changed.sh` clean.
+
+## 2026-10-18 — open-notebook: the podcast generator's config lands (nothing deployed)
+
+- Goal: **open-notebook** as the fleet's podcast generator on Dankclaw — notes
+  and sources in, a multi-speaker episode out, script written by
+  **frank-zealot**, voices rendered by **frank-tts**, no cloud provider
+  anywhere in the path. Repo-side only: no host touched, no container pulled or
+  started. Runbook: [[Open Notebook]].
+- **Two containers, not one.** `lfnovo/open_notebook:v1-latest` plus
+  `surrealdb/surrealdb:v2`, both **digest-pinned** with `Pull=never` and a
+  documented one-time `podman pull` — frank-dragoon's pinning style, because
+  `:latest` moving underneath a rootless service is how you get an unbootable
+  pod after an unrelated `systemctl-daemon-reload`. The registry round-trip is
+  what proved `v2` is SurrealDB **2.7.0** and that the app image is Debian
+  trixie with **curl and ffmpeg already inside** — which is how both health
+  probes can be argument-only: `curl -fsS …/health` (route is upstream's,
+  `api/main.py:239`, and it sits on the auth exclude list) and
+  `/surreal is-ready`, which I ran against the digest here: green in 2 s, and
+  it refuses to pass without `SURREAL_PASS` in the environment — a credential
+  that must never ride the command line, so `Exec=` carries flags only.
+- **Host 5055 was already spoken for.** seerr has held `127.0.0.1:5055` since
+  2026-10-14 (live `ss -ltn` agrees today), so the API publishes
+  `0.0.0.0:5056:5055`. open-notebook's frontend derives its API URL from the
+  window origin when `API_URL` is unset — the upstream env reference spells the
+  reverse-proxy symptom — so a silent remap would hang the UI on a port nobody
+  listens on, and `API_URL=http://192.168.0.143:5056` is set accordingly. 8502
+  publishes on `0.0.0.0` because this service carries its own password (the
+  episode-audio route is unauthenticated), unlike the loopback-and-proxied
+  observability stack; **8000 is published nowhere**, where upstream exposes it
+  on loopback with root credentials, and the seam forbids it.
+- **The CPU guard, pre-armed.** `frank-tts` spawns one ~8 GiB, 8-thread engine
+  per request on a box that also serves two LLMs, while open-notebook defaults
+  to `TTS_BATCH_SIZE=5` × `OPEN_NOTEBOOK_WORKER_MAX_TASKS=5` — a five-way
+  self-DoS. Both are pinned to `1` in `scripts/open-notebook.env`, and the
+  worker knob is only real because the image's own supervisord expands
+  `${OPEN_NOTEBOOK_WORKER_MAX_TASKS:-5}` (`supervisord.conf:25`). The TTS clock
+  goes to **660 — one round-trip outside** frank-tts's own `SHIM_TIMEOUT=600`, so
+  a shim give-up reads as the shim's error rather than the worker's; the seam
+  asserts the direction (`>`) against the frank-tts env instead of restating a
+  number. `ESPERANTO_LLM_TIMEOUT` stays at the app's 180 s default: frank-zealot
+  answers an outline or a transcript well inside it, and upstream says to keep it
+  under 600 so a slow call fails with a name on it.
+- **What a credential needs in order to exist:** `OPEN_NOTEBOOK_ENCRYPTION_KEY`
+  must be set before the UI can save *any* provider credential, and
+  `OPEN_NOTEBOOK_PASSWORD` must stay **absent** to remain auth-off — the app
+  reads `os.environ.get(…) is not None`, so `PASSWORD=` boots a login form
+  asking for the empty string. The repo env file carries both keys empty; the
+  deployer seeds `/home/dank/Containers/open-notebook/env` (600) from the host
+  vault and **refuses to start the pair while either secret is blank**, because
+  a half-configured open-notebook stores no credentials and fails quietly.
+- **Episode destination is interim, by decision.** The destination is **Gitea
+  issue #7, `human-only`** — agents must not work it. Until Frank settles it,
+  the app keeps its own named volume and `/home/dank/media/podcasts` is
+  bind-mounted over `/app/data/podcasts` (`DATA_FOLDER` is hard-coded `./data`),
+  so finished MP3s are ordinary files in his home directory instead of volume
+  contents needing `podman unshare` — the database volume demonstrably lands on
+  a mapped subuid, measured with the pinned image. One mount line; one deletion
+  undoes it.
+- **Two UI buttons will fail, and that is cosmetic.** Test Connection does
+  `GET <base>/models` and the TTS probe synthesises voice `alloy`; frank-tts
+  serves `/health` and `/v1/audio/speech` only. Model rows are created *by
+  name* and the voice field is free text, so `narrator1/2/3` is typed in and
+  never discovered. Documented, not worked around.
+- **Blocked on frank-tts, stated plainly:** phase 1 landed without deployer or
+  homepage registration and nothing listens on 7772 today, so a generation run
+  writes its script and then fails on the first voice. That is upstream's
+  creation-podcasts warning in fleet clothing.
+- Suite green: **403/403** (`./tests/run.sh`, wall 67 s) — 19 tests in the new
+  `tests/open_notebook.bats`, structure only: pins, boot persistence, the
+  unpublishable database port, the 5055→5056 remap plus the `API_URL` that has
+  to match it, the env-file read order, the guard knobs, the health gate naming
+  `/health`, planner routing, the homepage card hidden while undeployed.
+- Three deployer seams cost time and are now law-shaped: a service must be
+  registered in **five** places — `SERVICE_ORDER`, `DANKCLAW_SERVICES`, the
+  `deploy-remote.sh` dispatch case, its pre-deploy requirement, and
+  `deploy.sh`'s dispatch regex, where an omission silently plans an empty set
+  for `--only`; a `dankclaw/<svc>/*` case must precede the `dankclaw/*.container`
+  glob because that `*` crosses `/`; and the changed-path routing lives *inside*
+  the per-path loop, after the `scripts/*.env)` case, not at the top of the file.
+- Deliberately NOT done: the deploy (pulling 1.27 GiB to Dankclaw was not
+  asked for), any Caddy vhost or public exposure, audiobook/EPUB (issue #5), any
+  `frank-tts` code change, and the harbor templates on Dankserver —
+  `~/.harbor/compose.opennotebook.yml` pins the deprecated `-single` image,
+  carries no encryption key and injects the whole harbor env — left untouched,
+  read-only, as the record of what not to copy.
+
+## 2026-10-18 — frank-tts-engine: the arm A engine becomes deployable (nothing deployed)
+
+- Goal: turn the engine the day's A/B picked into a **repo-owned, boot-persistent,
+  self-healing container** — `frank-tts-engine`, `qwentts.cpp` commit
+  `5916bf7c79dbb4e66fc059cdc507a79a23a28bb4`, resident `tts-server`, 1.7 B base
+  talker Q4_K_M + Q8_0 tokenizer, container port 8880, and **not** a fleet
+  endpoint: the endpoint stays `frank-tts` on 7772. Runbook: [[Frank TTS Engine]].
+- **No `PublishPort` at all, which is the shape the merged A/B states as law.**
+  netavark DNATs published ports only, so a `127.0.0.1:8880` publish is not a path
+  to a peer container — the façade could never have used it (the trap that 502'd
+  hermes) — while being the one LAN-reachable surface of an unauthenticated
+  synthesiser. Both voice containers therefore sit on one committed quadlet
+  network, `frank-tts-engine.network` at **10.89.5.0/24** (the next free /24 after
+  open-notebook's 10.89.4.0/24), and the façade addresses the engine by container
+  name. Diagnostics moved to `podman exec`, including the deployer's health gate
+  (`wait_container_healthy`, not `wait_for_health`: there is no URL to dial).
+- **The boot warmer is a unit hook, not an operator habit.** Cold-voice law: the
+  first request for a registered voice decodes the whole reference to snapshot
+  codec state (6.2–8.0 s, first byte 5 530 ms), later ones restore in 0.5 ms; the
+  registry is memory-only and re-registering does not warm. So
+  `ExecStartPost=-/usr/bin/podman exec frank-tts-engine /app/warm-voices.sh` with
+  `TimeoutStartSec=900`, and the `-` prefix is what stops a failed warm from
+  crash-looping the endpoint under `Restart=always`. It logs `cold=` and `warm=`
+  per voice, so the under-a-second second request is proven on every boot.
+- **Thread law recorded before anyone tunes it away:** no `--threads` exists;
+  `src/backend.h` uses `hardware_concurrency()/2`, so a cpuset pin silently
+  changes the thread count. Nothing pins this container.
+- Image builds from the pinned commit with the **proven** line, verbatim —
+  `GGML_BLAS=OFF` is forced (this host has `libopenblas.so.0`, no dev headers),
+  every GPU backend off, `-j 8`, and no `-DGGML_NATIVE` because ggml's default is
+  `-march=native` for the building host: the image is built where it runs. Base
+  `ubuntu:24.04` pinned by index digest; two stages, because ggml builds shared
+  and the RPATH names the build tree.
+- Weights fetched by `scripts/download-frank-tts-engine-qwentts.sh` with byte and
+  LFS-oid checks (talker 1 219 245 248 B, tokenizer 291 150 624 B); the deployer
+  gates on `--verify-only` rather than pulling 1.4 GiB inside a deploy.
+- Registered in all five places the open-notebook entry just named as law, plus
+  the routing case above the `dankclaw/*.container` glob. New seam
+  `tests/frank_tts_engine.bats` (18 tests): the Quadlet **generator's own output**
+  for the network/publish/boot/warm shape, the entrypoint's argv driven from the
+  tracked env file, the warmer against a stub `tts-server` over a real socket
+  (registration keys, `ref_text` absent, late engine, hung synthesis, name
+  refusal), the fetcher's verifier, and both routing tables.
+- Deliberately NOT done: the deploy (no host touched, no container started, no
+  image built), any homepage card or Prometheus job for the engine — it publishes
+  nothing and exposes no metrics, so there is nothing to probe, which is said out
+  loud in the page rather than papered over. No ICL/`ref_text` work: the packs
+  keep `reference.spk`/`reference.rvq` so it stays a per-voice opt-in.
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 96 96"><polygon points="48,6 86,27 86,69 48,90 10,69 10,27" fill="#101a12" stroke="#7ee787" stroke-width="3"/><text x="48" y="60" font-family="monospace" font-size="30" font-weight="bold" fill="#7ee787" text-anchor="middle">ON</text></svg>
@@ -28,6 +28,19 @@
    "art_bg": "#f5f5f5",
    "warn": "Chats stay on Frank's server, but OpenWebUI's web search rides the same SearXNG path as the search app: obfuscated, not anonymous. The upstream search API keys are tied to Frank’s identity."
  },
+  {
+    "name": "open-notebook",
+    "category": "user",
+    "section": "AI",
+    "description": "Podcast generator — notes in, spoken episode out: script written by frank-zealot, voices rendered by frank-tts. No public route; LAN UI only once it is deployed.",
+    "url": "",
+    "docs": "",
+    "probe": "127.0.0.1:8502",
+    "method": "http",
+    "wip": "down",
+    "showLink": false,
+    "art": "/img/apps/mono-on.svg"
+  },
  {
    "name": "Gitea",
    "category": "user",
@@ -0,0 +1,656 @@
+#!/usr/bin/env bats
+# Seam: frank-tts-engine — the arm A TTS engine (qwentts.cpp `tts-server`) that
+# sits behind frank-tts. What is pinned here is the shape the fleet depends on,
+# observed through the tools that act on it: the Quadlet generator's own output,
+# the image entrypoint driven with a stub binary, the boot warmer driven against
+# a stub engine over a real socket, and the fetcher's own verifier.
+#
+# Nothing in this file synthesizes audio, builds an image, starts a container or
+# touches a fleet host. The engine's real behaviour (TTFA, RTF, the cold-voice
+# cost) was measured on Dankclaw on 2026-10-18 and is documented in
+# serverAppConfigs-docs/Dankclaw/Frank TTS Engine.md; a test that re-derived it
+# would need the weights, the CPU and the time the endpoint is meant to serve.
+#
+# What this seam refuses to assert, on purpose: any comparison between streamed
+# (`pcm`) and buffered (`wav`) audio. At the same seed those two paths differ in
+# 92.2 % of samples (-41.6 dB RMS), so a fixture that pinned one against the
+# other would be a bug waiting to be "fixed".
+
+load helpers
+
+UNIT="$REPO_ROOT/dankclaw/voiceservice/quadlet/frank-tts-engine.container"
+NETF="$REPO_ROOT/dankclaw/voiceservice/quadlet/frank-tts-engine.network"
+CF="$REPO_ROOT/dankclaw/voiceservice/Containerfile.engine"
+START="$REPO_ROOT/dankclaw/voiceservice/tts-engine-start.sh"
+ENVF="$REPO_ROOT/scripts/frank-tts-engine.env"
+WARM="$REPO_ROOT/dankclaw/voiceservice/tts-engine-warm.sh"
+FETCH="$REPO_ROOT/scripts/download-frank-tts-engine-qwentts.sh"
+PLANNER="$REPO_ROOT/scripts/deploy-plan.py"
+REMOTE="$REPO_ROOT/scripts/deploy-remote.sh"
+
+# The decided artifacts, exactly as the 2026-10-18 Hub census recorded them.
+TALKER="qwen-talker-1.7b-base-Q4_K_M.gguf"
+TALKER_BYTES=1219245248
+TALKER_SHA="ea393ebaf2167ea23ce9fc18b093822851358a950d7075cd47ab4f6ce23e887d"
+CODEC="qwen-tokenizer-12hz-Q8_0.gguf"
+CODEC_BYTES=291150624
+CODEC_SHA="1883beeed99348fc35e23dd225e9082f93f6f8c109330a33d935baa8acdbfd94"
+
+setup() {
+    TEST_TMP="$(mktemp -d)"
+    PIDS="$TEST_TMP/pids"
+    : > "$PIDS"
+    : > "$TEST_TMP/journal.jsonl"
+
+    # One real pack, and one directory that LOOKS like a pack but has no
+    # reference.wav so must never be offered as a voice. A third case — a pack
+    # whose name the two halves of the voice stack would resolve differently —
+    # is created only by the test that asserts on it, because every other run
+    # of the warmer has to be able to report success.
+    VOICES="$TEST_TMP/voices"
+    mkdir -p "$VOICES/narrator1" "$VOICES/justamanifest"
+    python3 -c 'import sys; sys.stdout.buffer.write(b"RIFF" + bytes(range(128)) * 2)' \
+        > "$VOICES/narrator1/reference.wav"
+    printf 'a manifest is not a voice\n' > "$VOICES/justamanifest/manifest.json"
+}
+
+teardown() {
+    while IFS= read -r pid; do
+        [ -n "$pid" ] && kill "$pid" 2>/dev/null || true
+    done < "$PIDS"
+    wait 2>/dev/null || true
+    rm -rf "$TEST_TMP"
+}
+
+# write_engine_stub — a stand-in for tts-server's HTTP surface, route for
+# route: GET /health, GET /v1/models, POST /v1/audio/voices, POST
+# /v1/audio/speech, and a bare 404 for anything else (that last part is the
+# point of the stub: a warmer dialing a route the engine does not have must
+# fail here, not in production). Every request is appended to $STUB_JOURNAL in
+# the order it arrived, with the registration reduced to its key set, its name
+# and the sha256 of the decoded wav — so "exactly which bytes were registered"
+# is observable without shipping a 1 MB fixture around.
+write_engine_stub() {
+    cat > "$TEST_TMP/stub_engine.py" <<'PY'
+import base64, hashlib, json, os, time
+from http.server import BaseHTTPRequestHandler, HTTPServer
+
+JOURNAL = os.environ["STUB_JOURNAL"]
+HANG = float(os.environ.get("STUB_HANG_SPEECH") or 0)
+
+
+class Stub(BaseHTTPRequestHandler):
+    def _record(self, entry):
+        with open(JOURNAL, "a") as fh:
+            fh.write(json.dumps(entry) + "\n")
+
+    def _reply(self, status, body, ctype="application/json"):
+        self.send_response(status)
+        self.send_header("content-type", ctype)
+        self.send_header("content-length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def do_GET(self):
+        self._record({"method": "GET", "path": self.path})
+        if self.path == "/health":
+            self._reply(200, b'{"status":"ok"}')
+        elif self.path == "/v1/models":
+            self._reply(200, b'{"object":"list","data":[{"id":"frank-tts-engine"}]}')
+        else:
+            self._reply(404, b'{"detail":"not found"}')
+
+    def do_POST(self):
+        length = int(self.headers.get("content-length") or 0)
+        raw = self.rfile.read(length) or b"{}"
+        try:
+            body = json.loads(raw)
+        except ValueError:
+            self._record({"method": "POST", "path": self.path, "invalid_json": True})
+            self._reply(400, b'{"error":{"message":"request body is not valid JSON"}}')
+            return
+        if self.path == "/v1/audio/voices":
+            wav = body.get("wav_b64") or ""
+            try:
+                digest = hashlib.sha256(base64.b64decode(wav)).hexdigest()
+            except Exception:
+                digest = "undecodable"
+            self._record({"method": "POST", "path": self.path,
+                          "keys": sorted(body), "name": body.get("name"),
+                          "wav_sha256": digest, "wav_b64_len": len(wav),
+                          "has_ref_text": "ref_text" in body})
+            self._reply(200, json.dumps({"name": body.get("name"),
+                                         "status": "registered"}).encode())
+        elif self.path == "/v1/audio/speech":
+            self._record({"method": "POST", "path": self.path,
+                          "voice": body.get("voice"),
+                          "response_format": body.get("response_format"),
+                          "input": body.get("input")})
+            # STUB_HANG_SPEECH stands in for an engine that takes the request
+            # and never answers it: the branch the warmer's ceiling guards.
+            if HANG:
+                time.sleep(HANG)
+            audio = b"RIFF" + b"\x00" * 64
+            self._reply(200, audio, "audio/wav")
+        else:
+            self._record({"method": "POST", "path": self.path})
+            self._reply(404, b'{"detail":"not found"}')
+
+    def log_message(self, *args):
+        pass
+
+
+server = HTTPServer(("127.0.0.1", int(os.environ.get("STUB_BOUND_PORT") or 0)), Stub)
+print(server.server_address[1], flush=True)
+server.serve_forever()
+PY
+}
+
+start_engine_stub() {
+    # start_engine_stub [port] — with a port the stub binds that exact one,
+    # which is what lets a test have a listener appear on an address the warmer
+    # is already dialing.
+    write_engine_stub
+    : > "$TEST_TMP/stub.log"
+    STUB_JOURNAL="$TEST_TMP/journal.jsonl" STUB_BOUND_PORT="${1:-}" \
+        STUB_HANG_SPEECH="${STUB_HANG_SPEECH:-}" \
+        python3 "$TEST_TMP/stub_engine.py" > "$TEST_TMP/stub.log" 2>&1 &
+    echo "$!" >> "$PIDS"
+    local waited=0
+    while [ "$waited" -lt 200 ]; do
+        STUB_PORT="$(head -n1 "$TEST_TMP/stub.log")"
+        [ -n "$STUB_PORT" ] && return 0
+        sleep 0.05
+        waited=$((waited + 1))
+    done
+    echo "the stub engine never bound a port:"
+    cat "$TEST_TMP/stub.log"
+    return 1
+}
+
+# quadlet_generator — locate the Quadlet generator the target host also has.
+# podman moved it over the releases the fleet runs, so try every known home and
+# skip the test if this box has none: the assertions below are only meaningful
+# against a real generator, not a guess at one.
+quadlet_generator() {
+    local candidate
+    for candidate in \
+        /usr/lib/systemd/system-generators/podman-system-generator \
+        /usr/libexec/podman/quadlet-generator \
+        /usr/lib/podman/quadlet-generator \
+        /usr/lib/podman/quadlet; do
+        [ -x "$candidate" ] && { printf '%s' "$candidate"; return 0; }
+    done
+    return 1
+}
+
+# render_units — run the generator in a throwaway HOME over a copy of the two
+# source files and print everything it emits. --dryrun prints instead of
+# writing, so this neither contacts the podman daemon nor creates a network.
+render_units() {
+    local gen home
+    gen="$(quadlet_generator)" || { echo "no Quadlet generator on this box"; return 1; }
+    home="$TEST_TMP/fakehome"
+    mkdir -p "$home/.config/containers/systemd"
+    cp "$NETF" "$UNIT" "$home/.config/containers/systemd/"
+    HOME="$home" "$gen" --user --dryrun > "$TEST_TMP/generated.txt" 2> "$TEST_TMP/generated.err"
+    cat "$TEST_TMP/generated.txt"
+}
+
+# free_port — an address with nothing bound to it, for the tests that need the
+# warmer to be dialing before a listener exists.
+free_port() {
+    python3 -c 'import socket
+s = socket.socket()
+s.bind(("127.0.0.1", 0))
+print(s.getsockname()[1])
+s.close()'
+}
+
+@test "the voice bridge is the next free pinned subnet and no two committed networks share one" {
+    # Two networks claiming one subnet is a boot-time collision that shows up as
+    # the later container failing to start, on the host, weeks from now. The
+    # registry lives in the network files' comments, so the subnets themselves
+    # are the only honest thing to compare.
+    mine="$(sed -nE 's/^Subnet=([0-9./]+)$/\1/p' "$NETF")"
+    [ "$mine" = "10.89.5.0/24" ] || { echo "expected 10.89.5.0/24, the next free /24, got: $mine"; false; }
+    run grep -hoE '^Subnet=[0-9./]+' "$REPO_ROOT"/dankclaw/*/quadlet/*.network "$REPO_ROOT"/dankserver/*/quadlet/*.network
+    dupes="$(printf '%s\n' "$output" | sort | uniq -d)"
+    [ -z "$dupes" ] || { echo "subnets claimed by more than one network file: $dupes"; false; }
+    printf '%s\n' "$output" | grep -qxF "Subnet=$mine"
+}
+
+@test "the Quadlet generator renders the engine on its private bridge, publishing nothing" {
+    rendered="$(render_units)" || { echo "$rendered"; skip "no Quadlet generator here"; }
+    line="$(printf '%s\n' "$rendered" | grep -E '^ExecStart=/usr/bin/podman run .*--name frank-tts-engine ')"
+    [ -n "$line" ] || { printf '%s\n' "$rendered"; false; }
+
+    # The data path: container DNS on the network the engine owns. One network
+    # and nothing else attached — the façade joins this one rather than the
+    # engine moving onto the fleet-wide bridge.
+    printf '%s' "$line" | grep -qE -- '--network systemd-frank-tts-engine( |$)'
+    [ "$(printf '%s' "$line" | grep -oE -- '--network [^ ]+' | wc -l)" = "1" ]
+
+    # NO publish of any kind, not even 127.0.0.1:8880. netavark DNATs published
+    # ports only, so a host-loopback publish is not a path to a peer container —
+    # the façade could never have used it (the trap that 502'd hermes), and it
+    # would be the one LAN-reachable surface of an unauthenticated synthesiser.
+    ! printf '%s' "$line" | grep -qE -- '--publish'
+
+    # Repo-owned config: the tracked env file, the read-only weights mount, the
+    # read-only voice packs the in-container warmer reads, and a health probe
+    # that survives the generator's CMD-SHELL wrapping because the image ships
+    # curl.
+    printf '%s' "$line" | grep -qF -- '--env-file /home/dank/serverAppConfigs/scripts/frank-tts-engine.env'
+    printf '%s' "$line" | grep -qF -- '-v /home/dank/models/Qwen3-TTS-GGUF:/models:ro'
+    printf '%s' "$line" | grep -qF -- '-v /home/dank/voices:/voices:ro'
+    printf '%s' "$line" | grep -qF -- '--health-cmd'
+    printf '%s' "$line" | grep -qF 'curl'
+
+
+    # Boot persistence and self-healing, as the generator actually emits them —
+    # and the warm hook: ExecStartPost must carry the `-` prefix, because
+    # Restart=always plus a failing warmer is a crash loop on the endpoint.
+    unit="$(printf '%s\n' "$rendered" | sed -n '/^---frank-tts-engine.service---$/,$p')"
+    printf '%s' "$unit" | grep -qE '^Restart=always$'
+    restart_sec="$(printf '%s' "$unit" | sed -nE 's/^RestartSec=([0-9]+)s?$/\1/p')"
+    [ -n "$restart_sec" ] && [ "$restart_sec" -le 30 ]
+    printf '%s' "$unit" | grep -qE '^WantedBy=default\.target$'
+    # The warm hook is an exec, because there is no host-visible address to run
+    # a host script against (see the publish assertions above).
+    printf '%s' "$unit" | grep -qE '^ExecStartPost=-/usr/bin/podman exec frank-tts-engine /app/warm-voices\.sh$'
+    # Warming a library is serialised: it must not fit inside the default 90 s.
+    start_deadline="$(printf '%s' "$unit" | sed -nE 's/^TimeoutStartSec=([0-9]+)$/\1/p')"
+    [ -n "$start_deadline" ] && [ "$start_deadline" -gt 90 ]
+}
+
+@test "the generator renders the bridge creation command with the pinned subnet" {
+    rendered="$(render_units)" || { echo "$rendered"; skip "no Quadlet generator here"; }
+    net="$(printf '%s\n' "$rendered" | sed -n '/^---frank-tts-engine-network.service---$/,$p')"
+    printf '%s' "$net" | grep -qE '^ExecStart=/usr/bin/podman network create --ignore --driver bridge --subnet 10\.89\.5\.0/24 --gateway 10\.89\.5\.1 systemd-frank-tts-engine$'
+    # The container unit must be tied to the network unit, not merely mention it:
+    # a referenced .network that the generator cannot find kills the container
+    # unit outright, and an untied one starts the container before the bridge.
+    unit="$(printf '%s\n' "$rendered" | sed -n '/^---frank-tts-engine.service---$/,$p')"
+    printf '%s' "$unit" | grep -qE '^Requires=frank-tts-engine-network\.service$'
+    printf '%s' "$unit" | grep -qE '^After=frank-tts-engine-network\.service$'
+}
+
+@test "the entrypoint turns the tracked env file into the engine's own flags" {
+    # Not a grep of the env file: source it the way podman's --env-file feeds
+    # it to the container, then require the stub binary to be handed the flags
+    # those values mean. A key the entrypoint forgot to translate shows up here
+    # as a missing argument, which is what "the knob does nothing" looks like.
+    cat > "$TEST_TMP/fake-tts-server" <<'FAKE'
+#!/usr/bin/env bash
+printf '%s\n' "$@" > "$ARGS_FILE"
+FAKE
+    chmod +x "$TEST_TMP/fake-tts-server"
+    mkdir -p "$TEST_TMP/models"
+    : > "$TEST_TMP/models/$TALKER"
+    : > "$TEST_TMP/models/$CODEC"
+
+    set -a
+    # shellcheck disable=SC1090
+    source "$ENVF"
+    set +a
+    # The env file names CONTAINER paths; the stub stands in for the mount.
+    export QWENTTS_MODEL="$TEST_TMP/models/$TALKER"
+    export QWENTTS_CODEC="$TEST_TMP/models/$CODEC"
+    export QWENTTS_BIN="$TEST_TMP/fake-tts-server"
+    export ARGS_FILE="$TEST_TMP/argv.txt"
+
+    run bash "$START"
+    [ "$status" -eq 0 ] || { echo "$output"; false; }
+    argv() { awk -v flag="$1" 'p { print; exit } $0 == flag { p = 1 }' "$ARGS_FILE"; }
+    [ "$(argv --model)" = "$TEST_TMP/models/$TALKER" ]
+    [ "$(argv --codec)" = "$TEST_TMP/models/$CODEC" ]
+    [ "$(argv --alias)" = "frank-tts-engine" ]
+    # 0.0.0.0 is the one value that makes the container reachable at all from
+    # the bridge; tts-server's own default (127.0.0.1) is unreachable in a netns.
+    [ "$(argv --host)" = "0.0.0.0" ]
+    [ "$(argv --port)" = "8880" ]
+    [ "$(argv --lang)" = "auto" ]
+    [ "$(argv --max-batch)" = "1" ]
+    # The two flags that must never appear: there is no thread count to set (it
+    # comes from hardware_concurrency()/2), and naming a device on an image with
+    # every GPU backend compiled out is only a new way to be wrong.
+    ! grep -qx -- '--device' "$ARGS_FILE"
+    ! grep -qE -- '^--?t$|^--threads$' "$ARGS_FILE"
+}
+
+@test "missing weights are a refusal that names the fetcher, before the port is bound" {
+    cat > "$TEST_TMP/fake-tts-server" <<'FAKE'
+#!/usr/bin/env bash
+echo "the engine binary must not run when its weights are absent" > "$RAN_FILE"
+FAKE
+    chmod +x "$TEST_TMP/fake-tts-server"
+    export RAN_FILE="$TEST_TMP/ran.txt"
+    export QWENTTS_MODEL="$TEST_TMP/nope/$TALKER"
+    export QWENTTS_CODEC="$TEST_TMP/nope/$CODEC"
+    export QWENTTS_BIN="$TEST_TMP/fake-tts-server"
+    run bash "$START"
+    [ "$status" -eq 1 ] || { echo "$output"; false; }
+    [ ! -e "$RAN_FILE" ] || { echo "the engine was started without its weights"; false; }
+    [[ "$output" == *"$TEST_TMP/nope/$TALKER"* ]] || { echo "$output"; false; }
+    [[ "$output" == *"download-frank-tts-engine-qwentts.sh"* ]]
+}
+
+@test "the boot warmer registers each pack from its reference.wav, embedding-only" {
+    start_engine_stub
+    run env ENGINE_URL="http://127.0.0.1:$STUB_PORT" VOICES_DIR="$VOICES" \
+        bash "$WARM"
+    [ "$status" -eq 0 ] || { echo "$output"; false; }
+    [[ "$output" == *"voice narrator1 cold="*"ms warm="*"ms"* ]] || { echo "$output"; false; }
+
+    # The registration is the whole product: name + wav_b64, and NOTHING else.
+    # ref_text present would flip the voice into in-context-learning mode (the
+    # slower voice) — so its absence is the shipped-default assertion.
+    python3 - "$TEST_TMP/journal.jsonl" "$VOICES/narrator1/reference.wav" <<'PY'
+import hashlib, json, sys
+entries = [json.loads(l) for l in open(sys.argv[1])]
+regs = [e for e in entries if e["path"] == "/v1/audio/voices"]
+assert len(regs) == 1, entries
+reg = regs[0]
+assert reg["name"] == "narrator1", reg
+assert reg["keys"] == ["name", "wav_b64"], reg
+assert reg["has_ref_text"] is False, reg
+want = hashlib.sha256(open(sys.argv[2], "rb").read()).hexdigest()
+assert reg["wav_sha256"] == want, (reg, want)
+PY
+
+    # Two speech calls for the one voice: the cold pass that creates the codec
+    # snapshot, then the warm pass whose number is the fleet's real experience.
+    # Both ask for `wav`, which is what frank-tts asks for too.
+    python3 - "$TEST_TMP/journal.jsonl" <<'PY'
+import json, sys
+entries = [json.loads(l) for l in open(sys.argv[1])]
+paths = [e["path"] for e in entries]
+assert paths[0] == "/health", paths
+assert paths[1] == "/v1/audio/voices", paths
+speech = [e for e in entries if e["path"] == "/v1/audio/speech"]
+assert len(speech) == 2, entries
+assert {s["voice"] for s in speech} == {"narrator1"}, speech
+assert {s["response_format"] for s in speech} == {"wav"}, speech
+PY
+}
+
+@test "a directory without reference.wav is not a voice, and a mixed-case name is refused" {
+    # `justamanifest` must be invisible; `Narrator2` must be loud. The engine
+    # lowercases every voice name (tts_voice_name) while frank-tts matches the
+    # directory name exactly, so a mixed-case pack is a voice that works on one
+    # side of the pair and not the other. Silence here is how a wrong-voice pack
+    # survives for weeks.
+    mkdir -p "$VOICES/Narrator2"
+    printf 'RIFFwrongcase' > "$VOICES/Narrator2/reference.wav"
+    start_engine_stub
+    run env ENGINE_URL="http://127.0.0.1:$STUB_PORT" VOICES_DIR="$VOICES" \
+        bash "$WARM"
+    [ "$status" -eq 1 ] || { echo "$output"; false; }
+    [[ "$output" == *"Narrator2"* ]]
+    [[ "$output" == *"lowercase"* ]]
+    run cat "$TEST_TMP/journal.jsonl"
+    [[ "$output" != *"justamanifest"* ]]
+    [[ "$output" != *"Narrator2"* ]]
+    # The refusal is a journal line plus a non-zero exit — not a crash: the
+    # narrator1 pack still got registered and warmed above the failure.
+    grep -q 'narrator1' "$TEST_TMP/journal.jsonl"
+}
+
+@test "an engine that never answers /health is reported, and nothing is registered" {
+    # HEALTH_WAIT is a deadline, not a retry-forever: an engine that dies on
+    # boot must produce one clear journal line and a non-zero exit (which the
+    # unit's `-` prefix turns into "nothing happened", not a crash loop).
+    port="$(free_port)"
+    run env ENGINE_URL="http://127.0.0.1:$port" VOICES_DIR="$VOICES" HEALTH_WAIT=1 \
+        bash "$WARM"
+    [ "$status" -eq 1 ] || { echo "$output"; false; }
+    [[ "$output" == *"/health"* ]] || { echo "$output"; false; }
+    [[ "$output" == *"did not answer"* ]]
+    [ ! -s "$TEST_TMP/journal.jsonl" ]
+}
+
+@test "the warmer waits for a late engine instead of racing model load" {
+    # Boot order: ExecStartPost fires the moment the container starts, while the
+    # two GGUFs (1.2 GiB + 291 MB) are still being read and the HTTP thread has
+    # not bound yet. The warmer is launched against an address with nothing on
+    # it, the listener appears a beat later, and the requirement is that the
+    # warmer notices and does the work — an early exit here is the day's first
+    # caller paying 5.5 s of silence for a voice nobody warmed.
+    port="$(free_port)"
+    ( ENGINE_URL="http://127.0.0.1:$port" VOICES_DIR="$VOICES" HEALTH_WAIT=60 \
+        bash "$WARM" > "$TEST_TMP/race.log" 2>&1; echo "$?" > "$TEST_TMP/race.rc" ) &
+    echo "$!" >> "$PIDS"
+    sleep 0.7
+    start_engine_stub "$port"
+    local waited=0
+    while [ ! -f "$TEST_TMP/race.rc" ] && [ "$waited" -lt 200 ]; do
+        sleep 0.05
+        waited=$((waited + 1))
+    done
+    [ -f "$TEST_TMP/race.rc" ] || { echo "warmer never finished:"; cat "$TEST_TMP/race.log"; false; }
+    [ "$(cat "$TEST_TMP/race.rc")" = "0" ] || { cat "$TEST_TMP/race.log"; false; }
+    grep -q '/v1/audio/voices' "$TEST_TMP/journal.jsonl"
+    grep -q '/v1/audio/speech' "$TEST_TMP/journal.jsonl"
+}
+
+@test "a synthesis that never returns is abandoned at REQUEST_TIMEOUT, not waited out" {
+    # systemd counts the WHOLE warm pass against TimeoutStartSec, so the price
+    # of a hung engine is paid by the unit: the endpoint stays "activating" and
+    # never reaches started. The warmer therefore puts a ceiling on every
+    # request. Here the engine registers the voice and then never answers the
+    # synthesis — the failure mode a wedged GEMM loop actually produces.
+    STUB_HANG_SPEECH=30
+    export STUB_HANG_SPEECH
+    start_engine_stub
+    run env ENGINE_URL="http://127.0.0.1:$STUB_PORT" VOICES_DIR="$VOICES" \
+        REQUEST_TIMEOUT=1 bash "$WARM"
+    [ "$status" -eq 1 ] || { echo "$output"; false; }
+    [[ "$output" == *"warm synthesis failed"* ]] || { echo "$output"; false; }
+    # It got as far as registering, so the stall — not a missing route — is
+    # what ended the pass.
+    grep -q '/v1/audio/voices' "$TEST_TMP/journal.jsonl"
+}
+
+@test "an empty voice root is an explanation, not a failure" {
+    # No packs yet is the state right after this unit is deployed and before the
+    # pack builder runs. Failing there would mark the engine deploy incomplete
+    # and, worse, read as a broken warmer to whoever is debugging a real one.
+    start_engine_stub
+    run env ENGINE_URL="http://127.0.0.1:$STUB_PORT" VOICES_DIR="$TEST_TMP/nodir" \
+        bash "$WARM"
+    [ "$status" -eq 0 ] || { echo "$output"; false; }
+    [[ "$output" == *"no voice directory"* ]]
+    # No registration, no synthesis. Health polls are expected — the stub
+    # journals them, and this is about what the warmer must NOT send.
+    run grep -c '/v1/audio' "$TEST_TMP/journal.jsonl"
+    [ "$output" = "0" ]
+}
+
+@test "the warmer's knobs come from the same env file the engine reads" {
+    # The warm hook is exec-ed into the container, so systemd hands it the unit's
+    # EnvironmentFile — one file for both. Sourcing it here is how that is
+    # reproduced without a container: if a key were renamed on one side only, the
+    # hook would silently fall back to its built-in default and the knob would do
+    # nothing, which no grep of either file alone can catch.
+    start_engine_stub
+    set -a
+    # shellcheck disable=SC1090
+    source "$ENVF"
+    set +a
+    [ -n "${WARM_TEXT:-}" ] || { echo "scripts/frank-tts-engine.env defines no WARM_TEXT"; false; }
+    run env ENGINE_URL="http://127.0.0.1:$STUB_PORT" VOICES_DIR="$VOICES" \
+        bash "$WARM"
+    [ "$status" -eq 0 ] || { echo "$output"; false; }
+    python3 - "$TEST_TMP/journal.jsonl" "$WARM_TEXT" <<'PY'
+import json, sys
+texts = {json.loads(l).get("input") for l in open(sys.argv[1])
+         if json.loads(l)["path"] == "/v1/audio/speech"}
+assert texts == {sys.argv[2]}, (texts, sys.argv[2])
+PY
+    # The engine-side keys are in the same file and must not collide with the
+    # warmer's: QWENTTS_PORT is what the server binds, ENGINE_URL is where the
+    # hook dials, and they are different values by design (container bind address
+    # versus in-namespace loopback).
+    grep -qE '^QWENTTS_PORT=8880$' "$ENVF"
+    grep -qE '^VOICES_DIR=/voices$' "$ENVF"
+}
+
+@test "the fetcher pins the decided weights and puts no credential on the wire" {
+    # The byte counts and the Hub pointer oids ARE the contract for the payload,
+    # the same way an image digest is: they came off the Hub on 2026-10-18 and a
+    # silent change means someone moved a file upstream.
+    run grep -h '^  "Serveurperso/Qwen3-TTS-GGUF|' "$FETCH"
+    [ "$(printf '%s\n' "$output" | grep -c .)" = "2" ]
+    printf '%s\n' "$output" | grep -qF "|$TALKER|$TALKER|$TALKER_BYTES|$TALKER_SHA"
+    printf '%s\n' "$output" | grep -qF "|$CODEC|$CODEC|$CODEC_BYTES|$CODEC_SHA"
+    # sha256 oids, not the 40-char git blob ids the same API also returns.
+    run grep -oE '\|[0-9a-f]{64}"$' "$FETCH"
+    [ "$(printf '%s\n' "$output" | grep -c .)" = "2" ]
+    # Public repo: no auth header, and no token in the invocation.
+    ! grep -qE 'HF_TOKEN|Authorization|--header' "$FETCH"
+    grep -qE 'curl -fsSL --fail-with-body' "$FETCH"
+}
+
+@test "the fetcher reports absent and wrong-sized weights as MISSING, non-zero" {
+    run bash "$FETCH" "$TEST_TMP/payload" --verify-only
+    [ "$status" -eq 1 ] || { echo "$output"; false; }
+    [[ "$output" == *"MISSING   $TALKER"* ]]
+    [[ "$output" == *"MISSING   $CODEC"* ]]
+    [[ "$output" == *"DOWNLOAD_FAILED"* ]]
+    # A partial download of the right NAME is still missing: the byte count is
+    # what gates, and a truncated GGUF would mmap fine and then produce noise.
+    mkdir -p "$TEST_TMP/payload"
+    head -c 4096 /dev/zero > "$TEST_TMP/payload/$TALKER"
+    : > "$TEST_TMP/payload/$CODEC"
+    run bash "$FETCH" "$TEST_TMP/payload" --verify-only
+    [ "$status" -eq 1 ]
+    [[ "$output" == *"MISSING   $TALKER"* ]]
+    [[ "$output" == *"MISSING   $CODEC"* ]]
+}
+
+@test "the image build is the pinned commit with the proven cmake line" {
+    # GGML_BLAS=OFF is forced by the host (libopenblas.so.0 present, no dev
+    # headers) and upstream's own Dockerfile passes it ON, so this file is not a
+    # copy of upstream on purpose. -j 8 and the OFF-for-every-GPU-backend list
+    # are what the 2026-10-18 trial ran.
+    grep -qE '^ARG QWENTTS_COMMIT=[0-9a-f]{40}$' "$CF"
+    grep -qF '5916bf7c79dbb4e66fc059cdc507a79a23a28bb4' "$CF"
+    grep -qE 'git -C /src checkout --detach' "$CF"
+    grep -qE 'submodule update --init' "$CF"   # ggml is a submodule; without it the build cannot configure
+    for flag in -DGGML_CCACHE=OFF -DGGML_BACKEND_DL=OFF -DGGML_CPU_ALL_VARIANTS=OFF \
+                -DGGML_OPENMP=ON -DGGML_BLAS=OFF -DGGML_CUDA=OFF -DGGML_HIP=OFF \
+                -DGGML_VULKAN=OFF -DGGML_METAL=OFF -DGGML_SYCL=OFF -DGGML_RPC=OFF; do
+        grep -qF -- "$flag" "$CF" || { echo "build line lost $flag"; false; }
+    done
+    grep -qE 'cmake --build build -j 8' "$CF"
+    # OpenMP on means the runtime stage needs the OpenMP runtime, and the probe
+    # runs as /bin/sh -c, so the runtime stage needs curl.
+    grep -qE 'libgomp1' "$CF"
+    grep -qE '^\s+ca-certificates curl libgomp1' "$CF"
+    # Both scripts ship in the image: the server's entrypoint, and the warmer the
+    # unit execs. A warmer that is not in the image makes the unit's
+    # ExecStartPost fail on every boot, silently (`-` prefix by design).
+    grep -qF 'COPY dankclaw/voiceservice/tts-engine-start.sh /app/start.sh' "$CF"
+    grep -qF 'COPY dankclaw/voiceservice/tts-engine-warm.sh /app/warm-voices.sh' "$CF"
+    grep -qE 'chmod 755 /app/start.sh /app/warm-voices.sh' "$CF"
+    ! grep -qE '^HEALTHCHECK' "$CF"            # the probe lives in the Quadlet unit
+    grep -qE '^USER tts$' "$CF"
+    # Base pinned by digest, both stages from one image.
+    grep -qE '^ARG BASE_IMAGE=docker\.io/library/ubuntu:24\.04@sha256:[0-9a-f]{64}$' "$CF"
+    [ "$(grep -cE '^FROM \$\{BASE_IMAGE\}' "$CF")" = "2" ]
+}
+
+@test "the planner maps every engine path to frank-tts-engine, and nothing to dankserver" {
+    run python3 "$PLANNER" --target dankclaw --paths \
+        dankclaw/voiceservice/quadlet/frank-tts-engine.container \
+        dankclaw/voiceservice/quadlet/frank-tts-engine.network \
+        dankclaw/voiceservice/Containerfile.engine \
+        dankclaw/voiceservice/tts-engine-start.sh \
+        scripts/frank-tts-engine.env \
+        dankclaw/voiceservice/tts-engine-warm.sh
+    [ "$status" -eq 0 ]
+    [ "$output" = "frank-tts-engine" ]
+
+    # Host-side payload and repo tooling restart nothing: the weights are host
+    # state, exactly like every other download script.
+    run python3 "$PLANNER" --target dankclaw --paths \
+        scripts/download-frank-tts-engine-qwentts.sh
+    [ "$status" -eq 0 ]
+    [ -z "$output" ]
+
+    # The engine is a Dankclaw container. On Dankserver these paths must plan
+    # nothing rather than queue a service that does not exist there.
+    run python3 "$PLANNER" --target dankserver --paths \
+        dankclaw/voiceservice/quadlet/frank-tts-engine.container \
+        scripts/frank-tts-engine.env
+    [ "$status" -eq 0 ]
+    [ -z "$output" ]
+}
+
+@test "changed-path routing selects this seam" {
+    # The regression this guards is real and was hit next door: the generic
+    # dankclaw/*.container case matches across `/`, so a quadlet path placed
+    # below it never reaches its own seam.
+    run "$REPO_ROOT/scripts/test-changed.sh" --list --paths \
+        dankclaw/voiceservice/quadlet/frank-tts-engine.container
+    [ "$status" -eq 0 ]
+    printf '%s\n' "$output" | grep -qx "tests/frank_tts_engine.bats"
+
+    run "$REPO_ROOT/scripts/test-changed.sh" --list --paths \
+        dankclaw/voiceservice/quadlet/frank-tts-engine.network
+    [ "$status" -eq 0 ]
+    printf '%s\n' "$output" | grep -qx "tests/frank_tts_engine.bats"
+
+    run "$REPO_ROOT/scripts/test-changed.sh" --list --paths scripts/frank-tts-engine.env
+    [ "$status" -eq 0 ]
+    printf '%s\n' "$output" | grep -qx "tests/frank_tts_engine.bats"
+    printf '%s\n' "$output" | grep -qx "tests/scripts_syntax.bats"
+}
+
+@test "both deployer entry points know the engine and its handler gates on health, then warm" {
+    grep -qF 'dankclaw:frank-tts-engine|' "$REMOTE"
+    grep -qF 'dankclaw:frank-tts-engine|' "$REPO_ROOT/scripts/deploy.sh"
+    grep -qF 'frank-tts-engine) deploy_frank_tts_engine ;;' "$REMOTE"
+    grep -qF 'containerfile=dankclaw/voiceservice/Containerfile.engine' "$REMOTE"
+
+    handler="$(sed -n '/^deploy_frank_tts_engine()/,/^}/p' "$REMOTE")"
+    [ -n "$handler" ] || { echo "no deploy_frank_tts_engine handler"; false; }
+    # Weights before build, build before start, health before warm: in that
+    # order, because each step's failure message is only true in that order.
+    local weights build quadlet start health warm pos_prev=-1 pos
+    weights="$(printf '%s' "$handler" | grep -n 'download-frank-tts-engine-qwentts.sh --verify-only' | head -1 | cut -d: -f1)"
+    build="$(printf '%s' "$handler" | grep -n 'build_compose_image frank-tts-engine' | head -1 | cut -d: -f1)"
+    quadlet="$(printf '%s' "$handler" | grep -n 'install_quadlet frank-tts-engine' | head -1 | cut -d: -f1)"
+    start="$(printf '%s' "$handler" | grep -n 'systemctl --user restart frank-tts-engine.service' | head -1 | cut -d: -f1)"
+    health="$(printf '%s' "$handler" | grep -n 'wait_container_healthy frank-tts-engine' | head -1 | cut -d: -f1)"
+    warm="$(printf '%s' "$handler" | grep -n 'podman exec frank-tts-engine /app/warm-voices.sh' | head -1 | cut -d: -f1)"
+    for pos in "$weights" "$build" "$quadlet" "$start" "$health" "$warm"; do
+        [ -n "$pos" ] || { echo "handler is missing a step (weights/build/quadlet/start/health/warm)"; false; }
+        [ "$pos" -gt "$pos_prev" ] || { echo "handler steps are out of order"; false; }
+        pos_prev="$pos"
+    done
+    # The gate is podman's recorded health, not a URL: this container publishes
+    # nothing, so the host has no address to dial.
+    printf '%s' "$handler" | grep -qE 'wait_container_healthy frank-tts-engine [0-9]+'
+    ! printf '%s' "$handler" | grep -qE 'wait_for_health frank-tts-engine'
+    # Generated Quadlet units cannot be enabled on this host: the handler must
+    # not try, and the unit carries [Install] instead.
+    ! printf '%s' "$handler" | grep -qE '^[[:space:]]*systemctl --user enable'
+}
+
+@test "the two scripts that ship in the image pass the repo's shell gates" {
+    # scripts_syntax.bats walks scripts/ only, and these two no longer live
+    # there: the entrypoint is the container's only way to read the env file,
+    # and the warmer is exec-ed by the unit. A syntax error in either is a
+    # container that never starts, or a deploy that reports an engine nobody
+    # told it to talk to, so they get the same gates as scripts/*.sh.
+    local s
+    for s in "$START" "$WARM"; do
+        bash -n "$s" || { echo "syntax error in $s"; false; }
+        [ -x "$s" ] || { echo "$s is not executable — git must record the mode"; false; }
+        if command -v shellcheck >/dev/null 2>&1; then
+            shellcheck -S error "$s" || { echo "shellcheck errors in $s"; false; }
+        fi
+    done
+}
@@ -0,0 +1,274 @@
+#!/usr/bin/env bats
+# Seam: open-notebook, the fleet's podcast generator on Dankclaw — the Quadlet
+# pair (app + SurrealDB), the private network between them, the env file both
+# units read, the deployer routing, and the homepage card. Runbook:
+# serverAppConfigs-docs/Dankclaw/Open Notebook.md.
+#
+# Structure only: what the files declare and what the deployer can see. Nothing
+# here starts a container, opens a socket, or touches the network — the app's
+# behaviour inside the image is upstream's contract, cited in the docs page.
+
+load helpers
+
+UNIT_DIR="dankclaw/open-notebook/quadlet"
+APP="$REPO_ROOT/$UNIT_DIR/open-notebook.container"
+DB="$REPO_ROOT/$UNIT_DIR/open-notebook-surrealdb.container"
+NET="$REPO_ROOT/$UNIT_DIR/open-notebook.network"
+ENVF="$REPO_ROOT/scripts/open-notebook.env"
+PLANNER="$REPO_ROOT/scripts/deploy-plan.py"
+REMOTE="$REPO_ROOT/scripts/deploy-remote.sh"
+# The host-side path the units read (they run on Dankclaw, not here), spelled
+# out once so the ordering test below compares against a real constant.
+HOST_TUNABLES="EnvironmentFile=/home/dank/serverAppConfigs/scripts/open-notebook.env"
+HOST_SECRETS="EnvironmentFile=/home/dank/Containers/open-notebook/env"
+
+# The pins are part of the contract, so a silent re-resolution to a different
+# build has to fail here rather than at the next deploy. Both digests were
+# resolved from the registry on 2026-10-18; the SurrealDB one is 2.7.0.
+APP_PIN="sha256:54b2025a4a4853c188f74b9b8246eca8c5480e5dd1babfa92db1038ff2f30212"
+DB_PIN="sha256:e5d7387e3727bbe2f7cd6d869e48cd34777272258572ead37c9656b25f745723"
+
+@test "open-notebook ships a network, a database unit and an app unit" {
+    [ -f "$NET" ]
+    [ -f "$DB" ]
+    [ -f "$APP" ]
+}
+
+@test "both units are boot-persistent and self-healing" {
+    for unit in "$APP" "$DB"; do
+        grep -qE '^Restart=(always|on-failure)$' "$unit" || {
+            echo "$(basename "$unit") has no Restart="; false; }
+        # "short RestartSec": a podcast service has no reason to wait minutes.
+        restart_sec="$(sed -n 's/^RestartSec=\([0-9]*\)s\?$/\1/p' "$unit")"
+        [ -n "$restart_sec" ] || {
+            echo "$(basename "$unit") has no RestartSec"; false; }
+        [ "$restart_sec" -le 30 ] || {
+            echo "$(basename "$unit") RestartSec=${restart_sec}s is not short"; false; }
+        grep -qE '^\[Install\]' "$unit"
+        grep -qE '^WantedBy=default\.target$' "$unit"
+    done
+}
+
+@test "both images are digest-pinned and never re-resolved at start" {
+    grep -qxF "Image=docker.io/lfnovo/open_notebook:v1-latest@$APP_PIN" "$APP"
+    grep -qxF "Image=docker.io/surrealdb/surrealdb:v2@$DB_PIN" "$DB"
+    grep -qxF 'Pull=never' "$APP"
+    grep -qxF 'Pull=never' "$DB"
+    # Pull=never is only honest if the fetch it depends on is written down where
+    # the operator reads the unit, and wired into the deployer's precondition.
+    grep -qF 'podman pull' "$APP"
+    grep -qF 'podman pull' "$DB"
+    grep -qF 'ensure_pinned_image' "$REMOTE"
+}
+
+@test "the database port is never published" {
+    # 8000 belongs to the private bridge. A published 8000 would put the RPC,
+    # root credentials included, on every interface of the host.
+    ! grep -qE '^PublishPort=' "$DB"
+    ! grep -qE '^PublishPort=.*:8000(:|$)' "$APP"
+}
+
+@test "the app publishes its UI and moves the API off the host port seerr holds" {
+    grep -qxF 'PublishPort=0.0.0.0:8502:8502' "$APP"
+    # seerr already binds 127.0.0.1:5055 on this host, so the API cannot leave
+    # the container on the host port upstream uses.
+    publish="$(grep -E '^PublishPort=[^:]+:[0-9]+:5055$' "$APP")"
+    [ -n "$publish" ] || { echo "no PublishPort mapping to the API's 5055"; false; }
+    mapping="${publish#PublishPort=}"          # e.g. 0.0.0.0:5056:5055
+    host_port="${mapping#*:}"
+    host_port="${host_port%%:*}"
+    [ "$host_port" != "5055" ] || {
+        echo "the API is published on host 5055, which seerr already holds"; false; }
+    # The frontend auto-detects the API as <host it was opened on>:5055, so a
+    # remap is only correct if API_URL names the published port.
+    api_url="$(sed -n 's/^API_URL=//p' "$ENVF")"
+    [ "$api_url" = "http://192.168.0.143:${host_port}" ] || {
+        echo "API_URL ($api_url) does not name the published API port ($host_port)"; false; }
+}
+
+@test "the pair shares one network and the app finds the database by container name" {
+    grep -qxF 'Network=open-notebook.network' "$DB"
+    grep -qxF 'Network=open-notebook.network' "$APP"
+    [ "$(grep -cE '^Network=' "$DB")" = "1" ]
+    # dankclaw_default is the app's second network and must come FIRST: the
+    # generated --network flags keep file order, so the default route (and the
+    # gateway name proven on that network) rides it.
+    [ "$(grep -cE '^Network=' "$APP")" = "2" ]
+    [ "$(grep -E '^Network=' "$APP" | head -1)" = "Network=dankclaw_default" ]
+    db_name="$(sed -n 's/^ContainerName=//p' "$DB")"
+    [ "$db_name" = "open-notebook-surrealdb" ]
+    grep -qxF "SURREAL_URL=ws://${db_name}:8000/rpc" "$ENVF"
+}
+
+@test "each unit reads the repo tunables first and the host secrets second" {
+    # podman applies --env-file in argument order and the LAST file wins, so
+    # swapping these two lines would blank every credential the app needs.
+    for unit in "$APP" "$DB"; do
+        files="$(grep -E '^EnvironmentFile=' "$unit")"
+        [ "$(echo "$files" | wc -l)" = "2" ] || {
+            echo "$(basename "$unit") must read exactly two env files"; false; }
+        [ "$(echo "$files" | head -1)" = "$HOST_TUNABLES" ] || {
+            echo "$(basename "$unit") must read the tracked env file first"; false; }
+        [ "$(echo "$files" | tail -1)" = "$HOST_SECRETS" ] || {
+            echo "$(basename "$unit") must read the host secret file last"; false; }
+    done
+}
+
+@test "the interim episode destination is mounted exactly once" {
+    # The bind that answers Gitea issue #7 provisionally: two of them is a
+    # shadowing bug, none is episode audio locked inside a named volume.
+    [ "$(grep -cE '^Volume=/home/dank/media/podcasts:/app/data/podcasts$' "$APP")" = "1" ]
+    # The app's own state stays in a named volume; the database gets its own.
+    grep -qE '^Volume=open-notebook-data:/app/data$' "$APP"
+    grep -qE '^Volume=open-notebook-db:/mydata$' "$DB"
+    # The deployer creates the host directory as the deploy user.
+    grep -qF 'mkdir -p /home/dank/media/podcasts' "$REMOTE"
+}
+
+@test "the env file declares the CPU-shutdown guard and both timeouts" {
+    # Upstream defaults are 5 and 5; frank-tts spawns ~8 GiB / 8 threads per
+    # request on a box that also serves two LLM endpoints.
+    grep -qxF 'TTS_BATCH_SIZE=1' "$ENVF"
+    grep -qxF 'OPEN_NOTEBOOK_WORKER_MAX_TASKS=1' "$ENVF"
+    # Per dialogue line, and strictly beyond frank-tts's own per-request
+    # ceiling: nested budgets go inside-out (the rule scripts/frank-tts.env
+    # states for LLAMA_TIMEOUT), so a shim give-up surfaces as frank-tts's
+    # error instead of the worker's own timeout. The seam reads the ceiling
+    # rather than restating it, so re-measuring frank-tts cannot leave this
+    # file silently behind.
+    tts="$(sed -n 's/^ESPERANTO_TTS_TIMEOUT=//p' "$ENVF")"
+    shim="$(sed -n 's/^SHIM_TIMEOUT=//p' "$REPO_ROOT/scripts/frank-tts.env")"
+    [ -n "$tts" ] || { echo "no ESPERANTO_TTS_TIMEOUT in the env file"; false; }
+    [ -n "$shim" ] || { echo "no SHIM_TIMEOUT in scripts/frank-tts.env"; false; }
+    [ "$tts" -gt "$shim" ] || {
+        echo "ESPERANTO_TTS_TIMEOUT=$tts is not beyond frank-tts SHIM_TIMEOUT=$shim"; false; }
+    # Upstream: keep the scriptwriting call under the web UI's ~600 s patience,
+    # or the failure arrives as a UI timeout with no name on it.
+    llm="$(sed -n 's/^ESPERANTO_LLM_TIMEOUT=//p' "$ENVF")"
+    [[ "$llm" =~ ^[0-9]+$ ]] && [ "$llm" -lt 600 ] || {
+        echo "ESPERANTO_LLM_TIMEOUT=$llm is not a number under 600"; false; }
+}
+
+@test "secrets stay declared-but-empty in the tracked env file" {
+    # scripts/*.env is un-ignored for "paths and numbers, never credentials":
+    # the values belong to the host file the deployer seeds.
+    for key in OPEN_NOTEBOOK_ENCRYPTION_KEY OPEN_NOTEBOOK_PASSWORD SURREAL_PASSWORD SURREAL_PASS; do
+        grep -qxF "${key}=" "$ENVF" || {
+            echo "$key is not declared, empty, in $ENVF"; false; }
+    done
+    has_no_leaked_secret "$ENVF"
+    has_no_leaked_sudo_pw "$ENVF"
+    # And the deployer treats blank as fatal, because blank means "auth off",
+    # not "unconfigured".
+    grep -qF 'seed_open_notebook_env' "$REMOTE"
+}
+
+@test "the database password never rides in a command line" {
+    # `surreal start` reads SURREAL_USER / SURREAL_PASS from the environment;
+    # --pass would put it in /proc/<pid>/cmdline for any ps on the host.
+    grep -qE '^Exec=start' "$DB"
+    ! grep -qE '^Exec=.*--(pass|user)' "$DB"
+}
+
+@test "both health probes are argument-only and name real paths" {
+    for unit in "$APP" "$DB"; do
+        cmd="$(sed -n 's/^HealthCmd=//p' "$unit")"
+        [ -n "$cmd" ] || { echo "$(basename "$unit") has no HealthCmd"; false; }
+        # The quadlet generator splits HealthCmd on spaces, so anything needing
+        # a shell (quotes, pipes, &&) would be silently mis-sent.
+        ! printf '%s' "$cmd" | grep -qE '["&;|`]'
+    done
+    # The API's own route, exempt from its password middleware upstream.
+    grep -qxF 'HealthCmd=curl -fsS http://127.0.0.1:5055/health' "$APP"
+    # The distroless database image has no shell and no curl; it ships a probe.
+    grep -qxF 'HealthCmd=/surreal is-ready' "$DB"
+}
+
+@test "the deployer gates open-notebook on the health path that actually answers" {
+    grep -qF 'open-notebook) deploy_open_notebook ;;' "$REMOTE"
+    gate="$(grep -E '^[[:space:]]*wait_for_health open-notebook ' "$REMOTE" | head -1)"
+    [ -n "$gate" ] || { echo "deploy_open_notebook has no wait_for_health gate"; false; }
+    # /health is the route upstream serves; the suite must not bless a guess.
+    printf '%s' "$gate" | grep -qE '/health( |$)'
+    # The gate is a host-loopback URL (the publish is wildcard, so 127.0.0.1
+    # answers) on the PUBLISHED port, never the container's 5055.
+    printf '%s' "$gate" | grep -qE 'http://127\.0\.0\.1:[0-9]+/health'
+    ! printf '%s' "$gate" | grep -qE ':5055/'
+    # The database is gated by its container health before the app is started.
+    grep -qE 'wait_container_healthy open-notebook-surrealdb' "$REMOTE"
+}
+
+@test "the deployer refuses to start the pair on blank secrets and never rewrites a seeded file" {
+    # Read the seed function itself: the refusal, and the no-clobber rule that
+    # protects a password an operator set by hand.
+    seed="$(sed -n '/^seed_open_notebook_env()/,/^}/p' "$REMOTE")"
+    [ -n "$seed" ]
+    printf '%s' "$seed" | grep -qF 'return 1'
+    printf '%s' "$seed" | grep -qF 'if [[ ! -e "$dest" ]]'
+    printf '%s' "$seed" | grep -qF 'chmod 600'
+    # One value, two spellings: the app reads SURREAL_PASSWORD, the CLI SURREAL_PASS.
+    printf '%s' "$seed" | grep -qF 'SURREAL_PASS='
+}
+
+@test "the planner maps every open-notebook path to the open-notebook service" {
+    run python3 "$PLANNER" --target dankclaw --paths \
+        dankclaw/open-notebook/quadlet/open-notebook.container \
+        dankclaw/open-notebook/quadlet/open-notebook-surrealdb.container \
+        dankclaw/open-notebook/quadlet/open-notebook.network \
+        scripts/open-notebook.env
+    [ "$status" -eq 0 ]
+    [ "$output" = "open-notebook" ]
+    # One deployable owns the pair: the unit files never plan separately.
+    run python3 "$PLANNER" --target dankclaw --paths \
+        dankclaw/open-notebook/quadlet/open-notebook-surrealdb.container
+    [ "$output" = "open-notebook" ]
+    # And the service belongs to dankclaw only.
+    run python3 "$PLANNER" --target dankserver --paths scripts/open-notebook.env
+    [ "$status" -eq 0 ]
+    [ -z "$output" ]
+}
+
+@test "changed-path routing selects this seam" {
+    run "$REPO_ROOT/scripts/test-changed.sh" --list --paths \
+        dankclaw/open-notebook/quadlet/open-notebook.container
+    [ "$status" -eq 0 ]
+    printf '%s\n' "$output" | grep -qx "tests/open_notebook.bats"
+
+    run "$REPO_ROOT/scripts/test-changed.sh" --list --paths scripts/open-notebook.env
+    [ "$status" -eq 0 ]
+    printf '%s\n' "$output" | grep -qx "tests/open_notebook.bats"
+}
+
+@test "both deployer entry points know the service" {
+    grep -qF 'dankclaw:open-notebook|' "$REMOTE"
+    grep -qF 'dankclaw:open-notebook|' "$REPO_ROOT/scripts/deploy.sh"
+}
+
+@test "the homepage card exists and stays hidden until the service is deployed" {
+    python3 - "$REPO_ROOT/shared/homepage/services.json" <<'PY'
+import json, os, sys
+data = json.load(open(sys.argv[1]))
+cards = [s for s in data if s["name"] == "open-notebook"]
+assert len(cards) == 1, f"expected exactly one open-notebook card, got {len(cards)}"
+card = cards[0]
+assert card["category"] == "user" and card["section"] == "AI", card
+assert card["probe"] == "127.0.0.1:8502", card["probe"]
+assert card["method"] == "http"
+# Not deployed yet: the card is reported wip-down and carries no link, so the
+# page shows no dead button (the Seerr precedent).
+assert card.get("wip") == "down", card.get("wip")
+assert card.get("showLink") is False, card.get("showLink")
+assert not card.get("url"), "a hidden card must not carry a url"
+art = card["art"].lstrip("/")
+assert os.path.exists(os.path.join(os.path.dirname(sys.argv[1]), art)), art
+PY
+}
+
+@test "the runbook page exists and names the interim mount's owning issue" {
+    page="$REPO_ROOT/serverAppConfigs-docs/Dankclaw/Open Notebook.md"
+    [ -f "$page" ]
+    grep -qF 'issue #7' "$page"
+    grep -qF 'human-only' "$page"
+    # The interim decision is one mount line; the page has to say how to undo it.
+    grep -qF '## Rollback' "$page"
+}
Author	SHA1	Message	Date
Frank	8d76854a1e	feat(frank-tts-engine): the arm A engine as a boot-persistent quadlet unit Repo state only: nothing deployed, no host touched, no container started. - `frank-tts-engine` on Dankclaw: `qwentts.cpp` commit 5916bf7c79dbb4e66fc059cdc507a79a23a28bb4, resident `tts-server`, 1.7 B base talker Q4_K_M + Q8_0 tokenizer, container port 8880. It is deliberately NOT a fleet endpoint — `frank-tts` on 7772 is the endpoint consumers address. - Publishes NOTHING. A host-loopback publish would have been useless to the façade (netavark DNATs published ports only, so a bridge container cannot reach a host loopback bind — the shape that 502'd hermes) and would have been the one LAN-reachable surface of an unauthenticated synthesiser. Both voice containers sit on one committed quadlet network, `frank-tts-engine.network` pinned to 10.89.5.0/24 (next free /24 after open-notebook's 10.89.4.0/24), and peers address the engine by container name. Diagnostics and the deployer's health gate run inside the netns (`podman exec`, `wait_container_healthy`). - Cold-voice law honoured in the unit: the first request for a registered voice decodes its whole reference to snapshot codec state (6.2-8.0 s, first audio byte 5 530 ms), later ones restore in 0.5 ms, and the registry is memory-only. `ExecStartPost=-/usr/bin/podman exec frank-tts-engine /app/warm-voices.sh` with `TimeoutStartSec=900`; the `-` prefix keeps a failed warm from crash-looping the endpoint under `Restart=always`. It logs cold=/warm= per voice, so the under-a-second second request is proven on every boot. - Thread law recorded: `tts-server` has no `--threads`; src/backend.h uses hardware_concurrency()/2, so a cpuset pin silently changes the thread count. - Image builds from the pinned commit with the proven line (GGML_BLAS=OFF forced by this host, every GPU backend off, -j 8, no -DGGML_NATIVE because ggml defaults to -march=native for the building host). Two stages; the runtime stage COPYs both the entrypoint and the warmer, because a container that publishes nothing is reached with `podman exec`, not a port. - `scripts/download-frank-tts-engine-qwentts.sh` fetches the two GGUFs with byte and LFS-oid checks (talker 1 219 245 248 B, tokenizer 291 150 624 B); the deployer gates on --verify-only instead of pulling 1.4 GiB mid-deploy. - Registered in SERVICE_ORDER, DANKCLAW_SERVICES, the deploy-remote.sh dispatch, its pre-deploy requirement, deploy.sh's regex, the planner's path map (the whole `dankclaw/voiceservice/` tree mapped to nothing before this), and test-changed.sh ABOVE the `dankclaw/.container` case whose `` crosses `/`. - New seam tests/frank_tts_engine.bats (19): the Quadlet generator's own output for network/publish/boot/warm shape, entrypoint argv driven from the tracked env file, the warmer against a stub tts-server over a real socket (registration keys, ref_text absent, late engine, hung synthesis, name refusal), the fetcher's verifier, the pinned cmake line, and both routing tables. Suite: 422 passed. - Vault: [[Frank TTS Engine]] linked from the index; log.md entry for the day.	2026-10-18 17:26:50 -07:00
dank	e13f875c94	Merge pull request 'docs(tts): record the measured CPU engine A/B behind frank-tts' (#10 ) from docs/tts-engine-trials into main	2026-10-18 17:15:00 -07:00
Frank	1d082a7f1d	Merge remote-tracking branch 'origin/main' into docs/tts-engine-trials # Conflicts: # serverAppConfigs-docs/log.md	2026-10-18 16:54:13 -07:00
Frank	5c8ac208a0	Merge remote-tracking branch 'origin/main' into docs/tts-engine-trials	2026-10-18 16:51:01 -07:00
Frank	dbc2c67bcb	docs(tts): record the arm A engine decision and the loopback-publish law Frank heard every audition pair and passed it, so likeness stopped being the tiebreak and the engine was picked on the live-output criterion: arm A qwentts.cpp 5916bf7, resident tts-server, 1.7 B talker, llama-tts-cli kept as the rollback. Records the discriminators (first audio byte, warm RTF, spread), the three consequences that are configuration (boot-warm every voice, no cpuset pin, WAV-only registration), the two follow-ups left open on purpose, and the corrected addressing law: a host-loopback publish is unreachable from a bridge container, so the pair shares one quadlet network.	2026-10-18 16:51:01 -07:00
dank	1eb8b2199a	Merge pull request 'feat(open-notebook): podcast pipeline on Dankclaw (blocked on frank-tts)' (#12 ) from feat/open-notebook-podcast into main	2026-10-18 16:50:47 -07:00
dank	0e4bb327da	Merge pull request 'docs: attribution footer for machine-opened issues and PRs' (#11 ) from chore/pr-attribution-trailer into main	2026-10-18 16:46:00 -07:00
Frank	114dd7a93e	fix(open-notebook): size the TTS clock outside frank-tts's own ceiling The env file first landed with ESPERANTO_TTS_TIMEOUT equal to SHIM_TIMEOUT=600. Equality is a race: both budgets expire at the same instant, so the case the number existed to prevent — the worker abandoning a synthesis frank-tts is still finishing — is exactly what happens on the tail of a long line. Nested budgets go inside-out, which is the rule scripts/frank-tts.env states for its own LLAMA_TIMEOUT; the client waits one round-trip longer than the server, so a frank-tts give-up arrives labelled as frank-tts's error. 660. The seam's assertion moves from equality to `>` for the same reason, and now also holds ESPERANTO_LLM_TIMEOUT under upstream's 600 s web-UI patience — above it the failure surfaces as a UI timeout with no name on it. The scriptwriting number itself stays at the app's 180 s default: frank-zealot answers an outline or a transcript well inside it, which corrects the earlier commit message's claim that both timeouts were raised past upstream's 300 s.	2026-10-18 16:31:49 -07:00
Frank	e2393bacad	docs(open-notebook): runbook, episode-destination interim, and the log entry Page registered in the vault index (the docs-completeness seam fails an unregistered page) and logged in the bundle change log. What the page owes the reader: the provider contract (frank-zealot for scripts with a /v1 base URL, frank-tts for voices with 1-4 speakers mapped to the narrator1/2/3 voice packs typed as free text), why Test Connection and Discover Models fail cosmetically against frank-tts rather than being a fault, the encryption key as the precondition for saving any credential, and the honest blocker — frank-tts is not deployed and nothing listens on 7772, so a generation run writes its script and fails on the first voice. Episode destination is stated as interim and cites Gitea issue #7 (human-only, agents must not work it): the app keeps its named volume, one bind mount puts finished MP3s under /home/dank/media/podcasts, and deleting that one line is the whole rollback. Rollback section also covers the full undo, including that the podman network only disappears once the units are gone.	2026-10-18 16:27:03 -07:00
Frank	ff11c37ee0	test(open-notebook): seam for the units, the env guards, and the wiring Structure only: what the units declare and how the scripts route them, never how the app behaves inside a container. 19 tests. The ones carrying real weight: the app unit has no publishable 8000 anywhere and the database unit publishes nothing at all; the API remap off host 5055 is only correct if API_URL names the same host port, so the seam parses the PublishPort and compares; each unit reads the repo tunable file before the host secret file, because podman's last-match-wins makes the order load-bearing; both health probes are argument-only (a shell string there is a unit that starts dead); the database password appears only as an env reference, never in Exec=; and the episode host bind appears exactly once, since a second mount would silently shadow the first. The deployer assertions read the functions themselves: the gate URL path is /health on the remapped port and must not name 5055, and the seed function contains the blank-secret refusal plus the no-clobber test. No test asserts a made-up endpoint or a cloud URL, and nothing touches the network.	2026-10-18 16:27:03 -07:00
Frank	0fe23c5233	build(scripts): route open-notebook paths to its own seam The case has to sit where it does: the dankclaw/.container glob's `` crosses `/`, so placed below it, dankclaw/open-notebook/quadlet/open-notebook.container matched that generic case and ran the open-webui/pihole/searxng seams instead of its own. Same reason the env path is grouped here — scripts/*.env would otherwise send it to the generic env seams.	2026-10-18 16:27:03 -07:00
Frank	716eefef5d	feat(homepage): open-notebook card, hidden until the service is deployed Internal-only: port 8502 direct, no vhost field, no Caddy change — exposure stays behind an explicit decision, and the app carries its own password. urlStatus=hidden is deliberate: the homepage probe runs on the gateway and the pair is not deployed, so a live card would render dead on day one. Flipping it to live is the only homepage change the deploy needs; the seam asserts the hidden state while the service is repo-only and requires the required card fields either way. mono-on.svg follows the mono-* icon set the sibling cards use, so the card does not fall back to the generic dot.	2026-10-18 16:26:52 -07:00
Frank	8816a9d498	feat(deploy): wire open-notebook through both deployers, gated on secrets Registration is load-bearing, not cosmetic: deploy-plan.py refuses any service it does not know, so SERVICE_ORDER + DANKCLAW_SERVICES are what let `--only` and `--auto` address the pair at all; the dispatch case in deploy-remote.sh runs it; the requirement in check_prerequisites gates a manual deploy; and the dispatch regex in deploy.sh's host-mode branch decides whether a changed path dispatches a service or falls through to "no service mapped" — an omission there is silent, which is exactly how the AGENTS.md deployer-registration law was earned. The deploy seeds /home/dank/Containers/open-notebook/env (0600) from the host env and refuses to start the pair while OPEN_NOTEBOOK_ENCRYPTION_KEY or OPEN_NOTEBOOK_PASSWORD is blank: without the key no provider credential saves and without the password the API — including the episode-audio route — is open to the LAN with no auth. A seeded file is never rewritten, so re-deploying cannot clobber a rotated key, which would silently make every stored credential undecryptable. SURREAL_PASS is derived from SURREAL_PASSWORD in the same write. The gate names paths that answer, not invented ones: the database is judged by its own container health status (/surreal is-ready, verified against the pinned digest) and the app by wait_for_health on /health at the published 5056 mapping — the route is upstream's and is on the auth middleware's exclude list, so it stays 200 after the password is set. 180 s covers Next.js build + startup and a degraded-but-listening first boot, matching the sibling LLM deploys. Both digest pins are checked against local storage before restart, because Pull=never means a missing image would otherwise surface as a unit stuck in "Start request queued" (the 203/EXEC trap's sibling). The interim episode directory is created before the app starts: a missing bind source makes podman create it as root-owned and the app's mkdir would then fail.	2026-10-18 16:26:52 -07:00
Frank	032229c1e2	feat(open-notebook): env contract — CPU guard, credential store, auth posture The two knobs that keep the box alive: TTS_BATCH_SIZE=1 and OPEN_NOTEBOOK_WORKER_MAX_TASKS=1. Upstream ships 5 x 5; frank-tts spawns one ~8 GiB, 8-thread engine process per synthesis request on a machine that also serves two LLMs, so a five-way fan-out is a self-inflicted shutdown. The worker knob is real, not decorative: the image's supervisord expands ${OPEN_NOTEBOOK_WORKER_MAX_TASKS:-5} into the worker command (supervisord.conf:25). Both ESPERANTO_* timeouts go above upstream's 300 s defaults, sized for CPU synthesis (SHIM_TIMEOUT=600, LLAMA_TTS_THREADS=8) — one episode is dozens of per-line /audio/speech calls and a timeout kills the episode, not the line. API_URL is forced for the 5055 -> 5056 remap; SURREAL_URL addresses the database by container name; CORS_ORIGINS is origin-form (scheme://host:port), the form the app compares against. OPEN_NOTEBOOK_PASSWORD stays absent here on purpose: the app treats a set-but-empty value as auth-on. Secrets stay placeholders in the tracked file and in dankclaw/.env.example, which lists SURREAL_PASSWORD rather than SURREAL_PASS — the deployer derives the surreal CLI's spelling from it when it seeds, so the app and the database cannot be handed different values.	2026-10-18 16:26:43 -07:00
Frank	09b0badaf5	feat(open-notebook): Quadlet pair — app + SurrealDB on a private bridge Two containers, because that is what upstream runs (docker-compose.yml:6,13): the app image under supervisord, plus SurrealDB. The `v1-latest-single` tag is not in play — it bundles its own database, is deprecated upstream, and would give the host a second hidden DB. Both images are digest-pinned with Pull=never and a documented one-time pull, the frank-dragoon posture: a Quadlet on :latest re-resolves on the first restart after an unrelated daemon-reload, and the failure is silent. Port map paid for by what is already on the host: seerr holds 127.0.0.1:5055 (since 2026-10-14, live `ss -ltn` agrees), so the API leaves on 5056 and the env file has to set API_URL to match, because the frontend derives the API URL from the window origin when it is unset. 8502 publishes on 0.0.0.0 — the service carries its own password and the episode-audio route is unauthenticated. 8000 is published nowhere, where upstream exposes it on loopback with root credentials. The app joins dankclaw_default first and the private systemd-open-notebook second: it reaches the published fleet endpoints through the former (host.containers.internal, the arrangement Prometheus is proven against) and finds its database by container name through the latter. Generated --network flags keep file order, so the tunable file is listed before the host secret file in both units — podman applies last-match-wins. No UserMapping: the app runs as root in its namespace (no USER in the Dockerfile) and writes only paths owned by that root. Exec= carries no database credential — `exec start --user --pass` puts it in world-readable argv; the image's own entrypoint passes it on stdin, so only the container env holds it.	2026-10-18 16:26:37 -07:00
Frank	0e7936f94e	docs(tts): record the measured CPU engine A/B behind frank-tts Both candidate :8880 engines were measured on Dankclaw's CPU (no GPU, no container, nothing deployed). arm A qwentts.cpp 5916bf7 resident at RTF 0.55-0.57 warm / 0.67 ICL / 1.65 cold; arm B mainline llama-tts at 0.93-0.99 with a +-0.25 spread. Records the four configuration laws the trial produced (boot-warm every voice, .spk+.rvq replay is byte-identical, streaming != buffered, /v1/audio/voices rejects a lone spk_b64), the likeness measurement's resolution limit, and re-keys the stale 8890/voiceshim shape on that page to frank-tts on 7772. The engine pick stays open: the likeness metric cannot rank clones, so the audition clips decide.	2026-10-18 16:19:51 -07:00
				`@@ -0,0 +1 @@`
				`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 96 96"><polygon points="48,6 86,27 86,69 48,90 10,69 10,27" fill="#101a12" stroke="#7ee787" stroke-width="3"/><text x="48" y="60" font-family="monospace" font-size="30" font-weight="bold" fill="#7ee787" text-anchor="middle">ON</text></svg>`