Skip to content

docs: consistency-review fixes (env-var names, defaults, stale claims, fabricated content)

Jérôme Revillard requested to merge docs/consistency-fixes into main

Consistency review: 5 parallel reviewers verified every concrete doc claim against code. This MR fixes the CRITICAL/MAJOR findings — wrong env-var names, wrong defaults, stale claims, fabricated content, broken links.

Highest-impact fixes (operators would have been misled)

  • rag retrieval/pipeline: every retrieval knob var name was wrong (RETRIEVE_K → real RETRIEVER_ARANGO_K); copying them into .env would have silently no-op'd. TRAVERSAL_MAX_DEPTH 2→1; added RETRIEVER_HYBRID_RRF_K.
  • rag reranking: RERANKER_STRATEGY → RERANKING_STRATEGY; added missing slice_threshold; THRESHOLD 0.9→0.75; TOP_N 2→1; calibration default is none (sigmoid is opt-in — naively enabling compresses scores).
  • rag generation: LLM default granite-4.1-8b → real compose default Meta-Llama-3.1-8B-Instruct (granite-4.1-8b = recommended).
  • gpu.md: VLLM_MAX_MODEL_LEN T4 65536→2048, RTX6000→4096 (matched env.t4/env.rtx6000); GPU_UTIL reconciliation.
  • install-guide: deleted a public VLLM_MODEL_ID "to be removed" TODO row; stale model ids → real; Admin/ADMINadmin → genie-admin/GENIE_ADMIN_PASSWORD; retriever port 7025→7000.
  • integration-architecture: "observability not implemented (planned ELK)" → the real OTel+Victoria stack; wrong models (Granite-3.3-2b / BGE-M3) → real defaults.
  • mobile-architecture: rewrote a fabricated "Proxy" service layer (ChatbotProxy/ChatHistoryProxy/api_service.dart — none exist) to the real Riverpod-providers + services structure; split KeycloakConfig vs flavor configs.
  • observability/overview: @tracing.trace_span decorator (doesn't exist) → FastAPI auto-instrumentation + with_span; 10→9 dashboards; receiver names corrected.
  • operations/scaling: VLLM_GPU_UTIL → VLLM_GPU_UTILIZATION.

Also: dashboard-count fixes, "Story X.Y" BMAD refs removed, source-tree filename typo, mobile _index missing entry + locale/token counts, api-contracts broken ../.claude links removed, dev-guide app.js → createApp().

Build verified clean (0 errors).

Follow-ups (not in this MR — additive/larger rewrites)

  • api-contracts-backend.md: enumerate /admin/queries/inspect + /:queryId routes (doc incomplete, not wrong).
  • source-tree-analysis.md: Vue CLI vs Vite contradiction; top-level tree completeness.
  • mobile-architecture.md §6: version numbers vs pubspec.yaml.
  • integration-architecture.md: remove "Document History" scan artefact; ARANGO_USER hardcoded in snippet.
  • cross-page: layer-stack drawn 3× (project-overview/integration/architecture) — dedup; keycloak admin-user + cert matrix duplicated across compose/swarm/install.
  • audience-framing intros missing on state-management / theme-system / mobile-architecture.
  • install-guide.md: Confluence-conversion cleanup (backslash escapes, label lines), clone-URL consistency, proofreading.

Merge request reports