The embedder downloads `BAAI/bge-small-en-v1.5` (~130 MB) from HuggingFace on first run via `fastembed`'s default `hf-hub` cache. For air-gapped, metered, or firewalled environments this is a hard blocker and the failure mode is unclear.
The README mentions the model download once ("first server start downloads the embedding model (~130 MB once)") but does not name the cache directory, the env var that controls it, or the path to pre-populate for offline use.
Proposed changes
1. Document `HF_HOME` / `HUGGINGFACE_HUB_CACHE` in the README's "Quick start" and "Deployment" sections. One example per variable, with a one-liner for pre-warming the cache:
```bash
Pre-warm the model cache (run once, then start the server offline):
HF_HOME=/path/to/cache python -c \
"from huggingface_hub import snapshot_download; \
snapshot_download('BAAI/bge-small-en-v1.5')"
```
2. On startup, log a single line that names the cache directory the embedder is using and the model it expects:
```
INFO model_cache = /root/.cache/huggingface hub = BAAI/bge-small-en-v1.5
```
A user can then pre-populate that path ahead of time.
3. Add a `daimon doctor` subcommand (or extend `daimon health`) that reports:
- AVX2 support (yes/no)
- model cache present? (yes/no, with the path)
- first-run download will require network: yes/no (true if cache is empty, false if pre-populated)
- HF_HOME env var currently set:
Acceptance
- A fresh deployment to a sealed network can be made working by populating `~/.cache/huggingface/hub/models--BAAI--bge-small-en-v1.5/` ahead of time and starting the indexer.
- `daimon doctor` JSON output is structured and machine-parseable.
- README's "Deployment" section has a one-paragraph "Offline / air-gapped setup" subsection.
The embedder downloads `BAAI/bge-small-en-v1.5` (~130 MB) from HuggingFace on first run via `fastembed`'s default `hf-hub` cache. For air-gapped, metered, or firewalled environments this is a hard blocker and the failure mode is unclear.
The README mentions the model download once ("first server start downloads the embedding model (~130 MB once)") but does not name the cache directory, the env var that controls it, or the path to pre-populate for offline use.
Proposed changes
1. Document `HF_HOME` / `HUGGINGFACE_HUB_CACHE` in the README's "Quick start" and "Deployment" sections. One example per variable, with a one-liner for pre-warming the cache:
```bash
Pre-warm the model cache (run once, then start the server offline):
HF_HOME=/path/to/cache python -c \
"from huggingface_hub import snapshot_download; \
snapshot_download('BAAI/bge-small-en-v1.5')"
```
2. On startup, log a single line that names the cache directory the embedder is using and the model it expects:
```
INFO model_cache = /root/.cache/huggingface hub = BAAI/bge-small-en-v1.5
```
A user can then pre-populate that path ahead of time.
3. Add a `daimon doctor` subcommand (or extend `daimon health`) that reports:
Acceptance