From 03088cff842fcefa449718b8470f6e940d084ab4 Mon Sep 17 00:00:00 2001
From: Public Source Publisher <public-source@itworx.tech>
Date: Thu, 1 Oct 2026 15:44:54 +0000
Subject: [PATCH] Publish curated RAGcore source from
 7f477cb6d5de82ea710644fc9a41da53fb455545

---
 PUBLIC_SOURCE_EXPORT.md     |  2 +-
 PUBLIC_SOURCE_MANIFEST.json |  6 +++---
 README.md                   | 15 +++++++++++++++
 3 files changed, 19 insertions(+), 4 deletions(-)

diff --git a/PUBLIC_SOURCE_EXPORT.md b/PUBLIC_SOURCE_EXPORT.md
index 3643e5f..a9ef0e6 100644
--- a/PUBLIC_SOURCE_EXPORT.md
+++ b/PUBLIC_SOURCE_EXPORT.md
@@ -1,3 +1,3 @@
 # Public source export
 
-This source snapshot was generated from the private canonical repository at revision `56e6df19135a64e363914b03727df19ec15d209d`. It contains no private Git history or operational evidence. Changes are published from the canonical repository.
+This source snapshot was generated from the private canonical repository at revision `7f477cb6d5de82ea710644fc9a41da53fb455545`. It contains no private Git history or operational evidence. Changes are published from the canonical repository.
diff --git a/PUBLIC_SOURCE_MANIFEST.json b/PUBLIC_SOURCE_MANIFEST.json
index 0fedd7d..8162447 100644
--- a/PUBLIC_SOURCE_MANIFEST.json
+++ b/PUBLIC_SOURCE_MANIFEST.json
@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "sourceRevision": "56e6df19135a64e363914b03727df19ec15d209d",
+  "sourceRevision": "7f477cb6d5de82ea710644fc9a41da53fb455545",
   "files": [
     {
       "path": ".dockerignore",
@@ -44,8 +44,8 @@
     },
     {
       "path": "README.md",
-      "sha256": "0f153c515d49d8982ad3e9391cd63ea03d5e7b8ee3f422c916b41aa83960f017",
-      "bytes": 5288
+      "sha256": "27fb5feb00d390693467ea6e5df09fa302b5defdc93718fdee15960b2bf522f4",
+      "bytes": 6258
     },
     {
       "path": "SECURITY.md",
diff --git a/README.md b/README.md
index e725b76..3f1fd0e 100644
--- a/README.md
+++ b/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.