[H-337] Fix Captain provider runtime and knowledge flow (#61)

* fix(H-337): configure Captain provider runtime

* fix(captain): make knowledge rebuild atomic

* fix(captain): scope retrieval provider failures

---------

Co-authored-by: Rogee <rogee@ipao.vip>

deploy/quickstart/.env.example

@@ -22,6 +22,13 @@ GOCHAT_ENV=development
 GOCHAT_SERVER_MODE=debug
 GOCHAT_JWT_SECRET=gochat_quickstart_change_me_minimum_32_chars
 
+# Optional Captain/Copilot runtime provider. Secrets stay in this ignored .env
+# and are never persisted to installation_configs. Leave all three blank to
+# keep AI generation disabled. Separate embeddings require the third value.
+GOCHAT_COPILOT_PROVIDER_CONFIG=
+GOCHAT_COPILOT_CHAT_API_KEY=
+GOCHAT_COPILOT_EMBEDDING_API_KEY=
+
 # Search
 MEILI_MASTER_KEY=gochat_dev
 GOCHAT_SEARCH_API_KEY=gochat_dev

deploy/quickstart/README.md

@@ -47,6 +47,20 @@ Default login after seeding:
 
 Change these values in `.env` before running the seed command if needed.
 
+## Optional Captain provider
+
+Set `GOCHAT_COPILOT_PROVIDER_CONFIG` and `GOCHAT_COPILOT_CHAT_API_KEY` in the
+ignored `.env` to enable Captain chat and embeddings. The JSON uses the same
+`chat`, `embedding`, `generation`, and `request` contract as the SuperAdmin
+Copilot provider settings API. Set `GOCHAT_COPILOT_EMBEDDING_API_KEY` only when
+`embedding.mode` is `separate`; runtime secrets are not written to the database.
+
+Example settings value (the key remains a separate `.env` variable):
+
+```json
+{"chat":{"provider":"openai_compatible","base_url":"https://provider.example.com/v1","model":"gpt-5.6-luna"},"embedding":{"mode":"reuse_chat_credentials","provider":"openai_compatible","base_url":"https://provider.example.com/v1","model":"text-embedding-3-small","dimensions":1536},"generation":{"temperature":0.7,"max_tokens":2048},"request":{"timeout_seconds":60,"max_retries":2}}
+```
+
 ## Useful Commands
 
 ```bash

deploy/quickstart/compose.yaml

@@ -93,6 +93,9 @@ services:
       GOCHAT_LOG_FORMAT: json
       GOCHAT_STORAGE_PROVIDER: local
       GOCHAT_STORAGE_LOCAL_PATH: /app/storage/uploads
+      GOCHAT_COPILOT_PROVIDER_CONFIG: ${GOCHAT_COPILOT_PROVIDER_CONFIG:-}
+      GOCHAT_COPILOT_CHAT_API_KEY: ${GOCHAT_COPILOT_CHAT_API_KEY:-}
+      GOCHAT_COPILOT_EMBEDDING_API_KEY: ${GOCHAT_COPILOT_EMBEDDING_API_KEY:-}
       SMTP_HOST: mailhog
       SMTP_PORT: 1025
     ports: