Establish a safe foundation before implementing the geology RAG system

The project begins with architecture, data governance, reproducible evaluation, deployment boundaries, and secret-handling contracts so later code has measurable acceptance criteria.

Constraint: Real provider credentials, workspace identities, and restricted geological data must never enter Git

Rejected: Add placeholder runnable services in the design commit | would imply unverified implementation readiness

Confidence: high

Scope-risk: narrow

Reversibility: clean

Directive: Run make verify before every commit and update ADRs when architecture boundaries change

Tested: Secret scan, Markdown links, YAML parse, shell syntax, and staged diff validation

Not-tested: Application runtime is intentionally deferred to the implementation stage

.env.example

@@ -0,0 +1,41 @@
+# This file contains placeholders only. Never put a real API key here.
+APP_ENV=development
+APP_NAME=geological-rag
+APP_SECRET_KEY_FILE=/run/secrets/app_secret_key
+
+POSTGRES_DB=geological_rag
+POSTGRES_HOST=db
+POSTGRES_PORT=5432
+POSTGRES_BOOTSTRAP_USER=postgres
+POSTGRES_MIGRATOR_USER=geological_rag_migrator
+POSTGRES_APP_USER=geological_rag_app
+POSTGRES_BOOTSTRAP_PASSWORD_FILE=/run/secrets/postgres_bootstrap_password
+POSTGRES_MIGRATOR_PASSWORD_FILE=/run/secrets/postgres_migrator_password
+POSTGRES_APP_PASSWORD_FILE=/run/secrets/postgres_app_password
+
+UPLOAD_ROOT=/data/uploads
+MAX_UPLOAD_MB=100
+
+# The actual workspace host is local deployment configuration and is not committed.
+BAILIAN_OPENAI_BASE_URL=https://<workspace-id>.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
+BAILIAN_NATIVE_BASE_URL=https://<workspace-id>.cn-beijing.maas.aliyuncs.com/api/v1
+BAILIAN_RERANK_BASE_URL=https://<workspace-id>.cn-beijing.maas.aliyuncs.com/compatible-api/v1
+DASHSCOPE_API_KEY_FILE=/run/secrets/bailian_api_key
+
+EMBEDDING_MODEL=text-embedding-v4
+EMBEDDING_DIMENSION=1024
+RERANK_MODEL=qwen3-rerank
+LLM_MODEL=deepseek-v4-flash
+
+CHUNK_TARGET_TOKENS=512
+CHUNK_MAX_TOKENS=800
+CHUNK_OVERLAP_TOKENS=64
+VECTOR_TOP_K=50
+RERANK_TOP_N=10
+CONTEXT_TOP_N=8
+MAX_CONTEXT_TOKENS=10000
+
+MODEL_TIMEOUT_SECONDS=90
+MODEL_MAX_RETRIES=3
+MODEL_MAX_CONCURRENCY=4
+WORKER_CAPABILITIES=document_parse,embedding,rerank,evaluation