docs: thêm hướng dẫn cấu hình OpenRouter end-to-end và bản đồ biến môi trường (env map) (fixes #415)

[CodingMinh]

Tóm tắt (Summary)

Fixes #415.

Pull Request này cung cấp tài liệu hướng dẫn (runbook) cấu hình OpenRouter end-to-end toàn diện, làm rõ ranh giới các environment variable prefixes giữa CLI/Desktop (FILECONV_*) và Web/Worker (MARKHAND_*), đồng thời cập nhật mẫu cấu hình deploy/.env.example.

Các thay đổi chính

1. Tài liệu runbook mới (docs/runbooks/openrouter-intern-setup.md):
   • Ranh giới environment variable prefixes (Prefix Boundary): Làm rõ sự khác biệt giữa FILECONV_* (dùng cho CLI cục bộ và Markhand desktop app, tự động fallback từ FILECONV_OCR_API_KEY sang FILECONV_LLM_API_KEY) và MARKHAND_* (dùng cho Web API và server background workers). Giải thích cơ chế cô lập mạng của Linux Landlock sandbox (CLONE_NEWNET): worker chạy fileconv trong sandbox hoàn toàn không có mạng và không nhận API key, các tác vụ Vision OCR được hoãn (deferred OCR) sang stage tiếp theo của worker ngoài sandbox.
   • Bản đồ biến môi trường OpenRouter toàn diện: Tài liệu hóa 30 biến môi trường thuộc 5 nhóm chức năng (Vision OCR CLI, Vision OCR Worker, Cloud Embeddings, Grounded Chat Q&A, và Hạ tầng/Readiness Probe).
   • Bảng đối chiếu Mock POC vs OpenRouter Thật: So sánh chi tiết giữa môi trường mock xác định, không tốn chi phí và cấu hình OpenRouter thật cho UAT/Production.
   • Chữ ký Index chuẩn (Pre-computed Index Signature): Kiểm chứng và tài liệu hóa chữ ký SHA-256 cho qwen/qwen3-embedding-8b (229680cc2d8df20a0776d3c06b31f88a9d0f201f2047b3849e2c9ea47545629f).
   • Checklist 10 bước onboarding cho thực tập sinh: Hướng dẫn tuần tự có thể tái lập từ clone mã nguồn, chạy mock stack, kiểm tra hành vi fail-closed của CLI, cấu hình OpenRouter key đến rà soát vệ sinh bí mật (secret hygiene).
2. Liên kết mục lục runbook (docs/runbooks/README.md):
   • Bổ sung liên kết đến openrouter-intern-setup.md trong danh mục runbooks.
3. Làm rõ cấu hình mẫu (deploy/.env.example):
   • Bổ sung chú thích giải thích ranh giới environment variable prefixes và ranh giới bảo mật sandbox.
   • Điền sẵn chữ ký index OpenRouter và khuyến nghị cấu hình batch trang cho OCR.

Danh mục tiêu chí nghiệm thu (Acceptance Criteria)

• Bảng bản đồ env ≥12 biến liên quan OpenRouter (thực tế 30 biến thuộc 5 nhóm)
• Phân biệt rõ ràng giữa mock POC và OpenRouter thật
• Checklist thiết lập 10 bước có thể tái lập (reproducible)
• Không rò rỉ secret (không commit file deploy/.env, đã chạy kiểm tra sanitization)
• Vượt qua kiểm tra chính sách phụ thuộc (python3 scripts/check-dependency-policy.py)

Minh chứng kiểm thử (Verification Evidence)

• Mock stack: Chạy COMPOSE_PROFILES=mock deploy/scripts/up.sh, toàn bộ dịch vụ Postgres, Qdrant, MinIO, Mock-Embedding đều báo healthy.
• CLI OCR fail-closed: Xác nhận lệnh báo lỗi rõ ràng DependencyMissing khi chưa cấu hình Vision OCR (không nuốt lỗi âm thầm).
• Tính toán chữ ký index: Xác nhận script deploy/scripts/print-index-signature.py trả về đúng SHA-256 229680cc2d8df20a0776d3c06b31f88a9d0f201f2047b3849e2c9ea47545629f.
• Chính sách & Định dạng: python3 scripts/check-dependency-policy.py đã vượt qua.