docs: correct .env.example and add navigation to the operator docs

[Mr-Sunglasses]

Summary

What changed? .env.example is rewritten into seven numbered sections with
its inaccurate claims corrected, and the operator docs gain the navigation
needed to find a deployment path without reading 900 lines top to bottom.

Why is it needed? Four statements in .env.example did not match the code,
and the two failure modes that cost the most setup time were undocumented.

Claims corrected, each checked against app/config.py, app/engines.py,
compose.yaml, and Dockerfile:

Claim in the file	Reality
macOS-only engines are "rejected here"	Nothing validates VOCAGATEWAY_ENGINE against the host. engine_runs_here is reached only from EngineFactory.validate(), i.e. the WebUI and PUT /v1/admin/config. VOCAGATEWAY_ENGINE=vocamac in a container starts fine and leaves /health/ready at 503.
BIND_HOST and PORT are "only meaningful under network_mode: host"	True of BIND_HOST only. VOCAGATEWAY_PORT is also the container-side target of the published mapping, so it is safe to change on the default bridge network.
VOCAGATEWAY_IMAGE runs "a prebuilt multi-architecture image"	It renames what gets built. up --build still builds locally and applies the tag; pulling needs docker compose pull + up --no-build. The native/cuda/vulkan services carry fixed tags and ignore it.
"direnv is set up not to export anything from here"	No .envrc is shipped (it is gitignored). What keeps .env out of a native run is the justfile's dotenv-load := false.

Two omissions added, both reproduced with docker compose config:

• An empty VOCAGATEWAY_TOKEN passes docker compose config on the shipped
  placeholder. Settings.from_env() then falls through to _generate_token(),
  which cannot write over the existing secret file, so the gateway runs on a
  secret it never prints — /health/live green, every authenticated request
  401.
• compose.yaml forwards only the keys it names, so VOCAGATEWAY_DATA_DIR,
  MODELS_DIR, CONFIG_FILE, TOKEN_FILE, and the macOS engine paths are read
  from .env and dropped. Confirmed absent from the resolved config. The
  VOCAGATEWAY_GIT_COMMIT* warning that previously lived only in the README is
  now here too.

Navigation:

• README gains Deploy in three steps and a Contents list. The Voca family and Consumers move below the deployment material so the quick starts
  are what a new reader meets first. No heading is renamed, so existing anchors
  still resolve.
• New docs/README.md index, linked from the README and AGENTS.md.
• Contents lists in deployment.md, configuration.md, and
  troubleshooting.md — the last grouped by symptom rather than a flat wall of
  20 headings.
• configuration.md's environment table gains an In .env? column
  recording what Compose forwards, pins, or ignores.

Also corrects the vocaphone submodule path to gateway/ (per AGENTS.md, which
flags server/ as wrong) and the matching stale server/.env reference in a
justfile comment.

Verification

• Every internal link and anchor across the nine markdown files resolves
  (checked programmatically, including the moved README sections)
• .env.example still works as a template: copied to a file, token
  appended, docker compose config --quiet passes
• Both new claims reproduced against docker compose config — repeated keys
  resolve last-wins; unlisted VOCAGATEWAY_* keys never reach the service
• just --list parses the edited justfile
• just test — not run: no Python, Dockerfile, or lockfile changed, so
  quality.yml and container.yml skip this PR by path filter
• Container build — not applicable
• Docs updated for setup, network, and configuration changes

Privacy and security

• No secrets, recordings, transcripts, or private hostnames added
• No weakening of bearer auth, upload limits, retention, or default binding.
  The security posture is documented more sharply, not relaxed: the empty
  token and the silently-ignored .env keys are now called out where an
  operator will see them.

[greptile-apps]

Mr-Sunglasses has reached the 50-credit limit for trial accounts. To continue receiving code reviews, upgrade your plan.

[netlify]

✅ Deploy Preview for voca-gateway canceled.

Name	Link
🔨 Latest commit	e690955
🔍 Latest deploy log	https://app.netlify.com/projects/voca-gateway/deploys/6a994a0804f6760008c494ca

[greptile-apps]

Mr-Sunglasses has reached the 50-credit limit for trial accounts. To continue receiving code reviews, upgrade your plan.