2026-04-25 — R-3 HF_TOKEN canonical path documented (voice/.env)

What changed

• voice/.env.example — adds HF_TOKEN= with a comment block explaining where the token is consumed: weight provisioning (voice/scripts/provision-weights.sh, R-4 #664) and voice-agent runtime turn-detector lazy download (removed once R-9 #669 bakes the model into the image). Explicitly notes the token is NOT consumed by vllm-guard or vllm-voxtral — those services load weights from the local /models/ volume mount.
• voice/docker-compose.yml — adds a "Secret surface" comment block in the file header that documents the canonical paths for HF_TOKEN, LIVEKIT_API_*, DEEPGRAM_API_KEY, and MISTRAL_API_KEY. This makes the consumption pattern explicit at the place where new contributors will ask "where does this env come from?".

No runtime behaviour changes. No new env wiring on vllm-guard or vllm-voxtral — those services load from disk and have no current runtime consumption of HF_TOKEN. Adding phantom HF_TOKEN: ${HF_TOKEN} lines there would be config that pretends to do something it doesn't.

Why

R-3 (#663) of the voice deploy repair epic (#660) calls for a single canonical place for the Hugging Face token, with a clear statement of which surfaces consume it. The 2026-04-22 R-3 audit found three competing patterns:

1. voice/.env line read by compose env_file: → consumed by voice-agent. Canonical.
2. ~/.cache/huggingface/token (37 bytes) on the EC2 host → not mounted into any container. Orphan; delete in EC2 cleanup step.
3. Operator-shell export HF_TOKEN=... → used for ad-hoc hf CLI calls during weight provisioning. Will be unified under the provision script in R-4 #664.

This entry establishes #1 as the single source of truth in the repo. R-4 will wire the provision script to read from voice/.env so #3 stops being a separate surface.

#526 ("huggingface-cli login interaktiv") closes here as well: the canonical pattern for fragjulia is HF_TOKEN in .env + non-interactive download via the provision script. No interactive hf auth login step.

Scope

Documentation and surface-area declaration only. No image rebuilds, no compose recreates, no token rotation. Token rotation is tracked separately in #654 (deferred per operator).

Follow-ups

• R-4 #664 (PR-E in the bring-up plan) — provision script consumes HF_TOKEN from this canonical path.
• R-9 #669 (PR-C) — bakes livekit-plugins-turn-detector model into the agent image, eliminating the runtime HF download path. Once merged, voice-agent no longer needs HF_TOKEN at runtime; .env retention is provisioning-only.
• #654 — actual rotation of the leaked HF token. Deferred; not blocking the bring-up.