docs(onboarding): make .env.example the canonical dev template (closes #260)

[dchaudhari7177]

Addresses #260 (auto-close keyword kept in the title only, per CLAUDE.md).

Documentation and one template file. No code, no compose change.

.env.example becomes the dev template

It now carries DEBUG, DUCKDB_SERVICE_URL and a commented HIGHFIVE_API_KEY, each annotated with which service reads it and the fact that all three are optional. Gone: the "Production Environment Variables" heading, NODE_ENV=production, PORT=3001, the production VITE_API_URL, and HIGHFIVE_API_KEY=your_secure_production_key_here — the placeholder that was becoming the admin password of every fresh dev box.

Production wording now points exclusively at .env.production.example, which is what docker-compose.prod.yml actually consumes, and the header says so explicitly so nobody copies the wrong one.

Four restatements become four pointers

File	Was	Now
CLAUDE.md	inline "Required .env" block	cp .env.example .env + pointer
CONTRIBUTING.md	its own inline block	same
docs/07-deployment-view/docker-compose.md	a third inline block	same, plus the correct service list
docs/troubleshooting.md	a fourth inline block	same, plus a correction (below)

Also fixed: docker-compose.md said cd hivehive after cloning highfive.git.

Two things I found beyond the issue

troubleshooting.md was actively wrong. It said the .env "must contain at minimum" DEBUG and DUCKDB_SERVICE_URL. Both are optional — image-service/app.py:512 and duckdb-service/app.py:123 are os.getenv("DEBUG", "false"), and image-service/app.py:159 defaults DUCKDB_SERVICE_URL to the service name. So the one doc a stuck contributor reaches for was sending them to fix a non-problem. It now says to restore from the template, and that a service dying on a malformed .env is failing on a parse error (docker compose config shows it), not a missing value.

A fifth restatement exists that I did not touch: .claude/skills/esp32-onboarding/SKILL.md:32 tells the agent to confirm .env contains DEBUG=true and DUCKDB_SERVICE_URL=.... Same drift, but it is agent tooling rather than contributor docs, so I left the call to you — happy to fold it in.

Claims verified against the tree

• env_file: - .env appears at docker-compose.yml:10 (backend), :78 (image-service), :131 (duckdb-service); the homepage service has no env_file, so VITE_API_URL never reached it. The docs now say exactly this — the old CONTRIBUTING wording ("used by image-service and duckdb-service") omitted backend.
• The optionality claims are read off the os.getenv defaults cited above, not assumed.

Docs gate

docs/11-risks-and-technical-debt/README.md gains a Lessons-learned entry in the required format. The general lesson: a file that ships as a template is the canonical description of itself — docs link to it, they do not restate it. Five copies meant no single one was wrong enough to notice, and the compose environment: overrides hid the mismatch, which is structurally the same failure as the inert-security-control incident already recorded in that chapter.

make check-citations → 7 OK, 0 problems.

Note: my other open PR (#263) also appends to the Lessons-learned section. I inserted at a different anchor so the two should not textually conflict, but if they do it is a one-line rebase — say the word.

One deviation to flag

CLAUDE.md's end-of-implementation gate asks for the senior-reviewer subagent. I could not run it in my environment, so this has not been through that gate. Everything else — make check-citations, the docs update, branch and commit conventions, the no-auto-close-keyword-in-bodies rule — has been followed.