v0.50.260 Batch Release — Docker reliability overhaul

Summary

Nathan flagged Docker UX as a recurring pain point. This batch absorbs PR #1428 (the immediate fix for #1399) AND ships a broader reliability pass touching all 3 compose files, the README, a new .env.docker.example template, and a new comprehensive docs/docker.md guide.

Constituent PR

Broader Docker improvements (this batch)

• All 3 compose files now document HERMES_SKIP_CHMOD and HERMES_HOME_MODE escape hatches inline (the v0.50.254 fix for Webui is overriding HERMES_HOME_MODE file permission setting #1389 wasn't surfaced for Docker users)
• New .env.docker.example — Docker-specific template with UID/GID, paths, password, and permission-handling escape hatches. UID/GID uncommented with placeholder values per Opus advisor (so macOS users don't skim past the warning)
• New docs/docker.md — comprehensive guide covering all 3 compose files, common failure modes (with one-line fixes), bind-mount migration recipe, multi-container architecture diagram, macOS Docker Desktop file-sharing implementation note, and pointer to the community all-in-one image (caveated as third-party)
• README Docker section rewritten — clearer 5-minute quickstart, failure-mode table with one-line fixes, pointer to docs/docker.md. Stale /root/.hermes reference removed (current agent images use /home/hermes/.hermes)
• .gitignore updated — explicitly allowlist .env.docker.example and docs/docker.md so the new files actually ship

Pre-applied Opus advisor follow-up — MUST-FIX

Opus caught a real footgun in my initial draft: HERMES_HOME_MODE has DIFFERENT semantics in the WebUI vs. the agent image:

• WebUI: credential-FILE mode threshold (e.g. 0640 allows group bits on .env)
• Agent: HERMES_HOME directory mode (default 0700)

0640 on a directory has no owner-execute bit, so the agent can't traverse its own home → bricked. My initial draft recommended HERMES_HOME_MODE=0640 as the example value in agent service blocks. Fixed across all 4 surfaces:

• docker-compose.two-container.yml agent block now recommends 0750
• docker-compose.three-container.yml agent + dashboard blocks recommend 0750
• .env.docker.example adds an explicit MULTI-CONTAINER WARNING
• docs/docker.md failure mode Hermes Web UI — Sprints 11-14: multi-provider models, settings, sessi… #2 calls out the asymmetry

Opus also flagged that the WebUI service blocks should annotate that 0640 IS correct for the WebUI but NOT to copy to the agent — done.

Tests

• 3627 passed, 0 failed (master 3615, +12 from new test_v050260_docker_invariants.py)
• Browser tests + Phase 2 API sanity → ALL CHECKS PASSED

12 regression tests in tests/test_v050260_docker_invariants.py:

• UID/GID alignment in all 3 compose files (positive + negative-pattern guards)
• All compose files document the escape hatches
• .env.docker.example exists and documents critical vars
• docs/docker.md exists and references each known failure mode by issue number
• README has no stale /root/.hermes references and links to docs/docker.md
• All compose files parse as valid YAML
• Agent service blocks do NOT recommend HERMES_HOME_MODE=0640 (Opus catch)
• Compose files explicitly warn about the directory vs file mode asymmetry
• .env.docker.example includes the MULTI-CONTAINER WARNING

Why ship without independent review

Per Nathan's directive: "you have my approval. You don't need an independent review, so just use yourself and the Opus Advisor Claude Code, and then go ahead and merge those in."

The change set is large by Docker-overhaul standards but:

• 12 LOC behavior change (PR fix: align agent UID/GID with webui in compose files (#1399) #1428's UID alignment) — empirically tested by the contributor
• All other changes are documentation + tests, no behavior change
• Opus advisor caught the only real footgun (HERMES_HOME_MODE asymmetry) and I applied the fix
• 12 regression tests cover the invariants

What's NOT in this batch

• feat(deepseek): add V4 Pro/Flash [1m] variants to model dropdown #1418 (DeepSeek 1M variants) — still held: agent PR #18534 still open
• A custom all-in-one image — sunnysktsang's hermes-suite already exists; bundling our own would compete
• Resolving the architectural Two containers = tools running in the webUI container #681 (tools-in-wrong-container) — known limit, documented honestly
• Cross-repo PR to align WANTED_UID (webui) vs HERMES_UID (agent) env var names — flagged as future work
• All other open PRs are draft, hold-labeled, or awaiting contributor response