Publish curated RAGcore source from 7f477cb6d5de82ea710644fc9a41da53fb455545

README.md

@@ -48,8 +48,12 @@ For folder/Git sources, mount only the intended corpus read-only into the worker
 ## Integrate
 
 ```python
+import os
 from ragcore_sdk import RAGCoreClient
 
+# Supply a scoped credential through your environment; never hard-code it.
+service_token = os.environ["RAGCORE_SERVICE_TOKEN"]
+
 with RAGCoreClient(base_url="https://ragcore.example.test", token=service_token) as client:
     response = client.search(query="What is the retention policy?")
     for result in response.results:
@@ -58,6 +62,17 @@ with RAGCoreClient(base_url="https://ragcore.example.test", token=service_token)
 
 Install the Python SDK from `sdk/python`; the TypeScript SDK is in `sdk/typescript`. The [REST contract](docs/contracts/openapi.yaml) and [MCP specification](docs/11_MCP/MCP_SPECIFICATION.md) describe supported operations and authentication.
 
+## Troubleshoot an empty result set
+
+| Check | Why it matters |
+| --- | --- |
+| Ingestion job completed and the document is published | Accepted uploads are not necessarily searchable yet. |
+| Active embedding profile and reachable provider | The index must match the selected embedding configuration. |
+| Caller has a grant to the intended knowledge space | Search applies authorization rather than exposing the entire corpus. |
+| Query filters and source versions | A valid filter can intentionally exclude otherwise relevant documents. |
+
+If optional answer generation is unavailable, use search or context retrieval and inspect the returned citations. Do not replace missing evidence with an uncited answer. Keep PostgreSQL and immutable blobs in the recovery plan; a vector-index backup alone is not a complete source backup.
+
 ## Production considerations
 
 Use HTTPS, a deliberately trusted reverse proxy, independent secrets and configured OIDC roles. Keep PostgreSQL and Qdrant private. Production validation rejects weak credentials and unsafe storage/network settings. PostgreSQL and blobs are authoritative; Qdrant is rebuildable. On Unraid, place active database/vector storage on direct pool paths. Review the [deployment guide](docs/09_OPERATIONS/UNRAID_DEPLOYMENT.md), [backup/restore guide](docs/09_OPERATIONS/BACKUP_RESTORE.md) and [security controls](docs/07_SECURITY/SECURITY_CONTROLS.md) before deployment.