feat: make GEMINI_AUTH=oauth authenticate in Docker

OAuth cannot be done interactively in the headless container, so the login
must be seeded into the mounted ~/.gemini. Three problems are fixed:

- Mount fragility on the Windows Docker Desktop target: the creds mount
  defaulted to ${HOME}/.config/javis/gemini, but ${HOME} is often unset when
  compose runs outside a WSL shell, silently mounting the wrong dir. Default is
  now the project-local ./docker/gemini-oauth (cross-platform), GEMINI_OAUTH_DIR
  still overrides.
- No visibility: when oauth is selected but no login is seeded, the path
  silently degraded to DDG/Brave. Added gemini_oauth_ready() + a one-time debug
  hint and a startup entrypoint warning (skipped on the browser role, fail-open).
- Seeding guidance: oauth_creds.json is the essential credential (refresh token;
  GOOGLE_GENAI_USE_GCA=true forces OAuth), which is what the readiness check and
  warning verify; docs recommend copying the whole ~/.gemini for convenience.

Adds docker/gemini-oauth/ seed dir (.gitkeep) with the login files gitignored,
GEMINI_OAUTH_DIR in .env.example, and updates DEPLOY.md, stream_browser_modes.md
and llm_contexts.md. Covered by 3 new tests (10 passed total).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

docker-compose.yml

@@ -129,15 +129,26 @@ services:
       - javis_data:/data                         # jarvis db + memory
       - whisper_cache:/root/.cache/huggingface   # cached Whisper models
       - piper_voices:/opt/piper-voices           # TTS voices
-      # Gemini account login for GEMINI_AUTH=oauth real-time search. Mounts a
-      # DEDICATED dir holding only the Gemini OAuth creds (not the whole
-      # ~/.gemini), so the container can refresh its token without exposing
-      # unrelated host state. Seed it once with the host login:
-      #   mkdir -p ~/.config/javis/gemini
-      #   cp ~/.gemini/oauth_creds.json ~/.config/javis/gemini/
-      # Override GEMINI_OAUTH_DIR to point elsewhere. Only used when
-      # GEMINI_AUTH=oauth.
-      - ${GEMINI_OAUTH_DIR:-${HOME}/.config/javis/gemini}:/root/.gemini
+      # Gemini account login for GEMINI_AUTH=oauth real-time search. Bind-mounts a
+      # PROJECT-LOCAL dir (./docker/gemini-oauth) into the CLI's ~/.gemini. A
+      # project-relative path is used on purpose: it resolves identically on Linux
+      # and on Windows Docker Desktop, unlike ${HOME} which is frequently unset
+      # when compose is invoked outside a WSL shell (PowerShell/cmd), silently
+      # mounting the wrong dir. The mount is writable so the CLI refreshes its
+      # token in place.
+      #
+      # Seed it ONCE from a machine that has a browser + the logged-in Gemini CLI
+      # (`npm i -g @google/gemini-cli`, then `gemini` -> "Sign in with Google"):
+      #     cp -r ~/.gemini/. docker/gemini-oauth/      # Linux / WSL
+      # `oauth_creds.json` is the essential credential (holds the refresh token);
+      # with GOOGLE_GENAI_USE_GCA=true the CLI forces OAuth, so that one file is
+      # what the readiness check + entrypoint warning verify. Copying the WHOLE
+      # ~/.gemini is simplest and also carries the cached account/settings. To
+      # reuse an existing host login without copying, set in .env:
+      #     GEMINI_OAUTH_DIR=~/.gemini
+      # If unseeded, the path fail-opens to the DDG/Brave cascade and the
+      # entrypoint logs a warning. Only consumed when GEMINI_AUTH=oauth.
+      - ${GEMINI_OAUTH_DIR:-./docker/gemini-oauth}:/root/.gemini
 
 volumes:
   ollama_models: