From 5e373c209628b06cdabf489ef1cde668cc3cc84b Mon Sep 17 00:00:00 2001
From: Mani Sarkar <sadhak001@gmail.com>
Date: Fri, 21 Aug 2026 14:44:27 +0100
Subject: [PATCH 1/7] docs(examples): add rag-params-finder external project
 guide

Add a thin SIE gallery landing that deep-links to neomatrix369/rag-params-finder
for clone/run and SIE setup, without vendoring the app.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 examples/README.md                            |  1 +
 examples/rag-params-finder/README.md          | 48 +++++++++++
 examples/rag-params-finder/getting-started.md | 52 ++++++++++++
 examples/rag-params-finder/sie-integration.md | 80 +++++++++++++++++++
 examples/rag-params-finder/troubleshooting.md | 43 ++++++++++
 examples/rag-params-finder/what-sie-does.md   | 67 ++++++++++++++++
 6 files changed, 291 insertions(+)
 create mode 100644 examples/rag-params-finder/README.md
 create mode 100644 examples/rag-params-finder/getting-started.md
 create mode 100644 examples/rag-params-finder/sie-integration.md
 create mode 100644 examples/rag-params-finder/troubleshooting.md
 create mode 100644 examples/rag-params-finder/what-sie-does.md

diff --git a/examples/README.md b/examples/README.md
index 393a20416..b74b02083 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -33,6 +33,7 @@ service keys.
 | [Reconstruct a bearing failure](./maintenance-triage-agent) | Turning the NTSB's three East Palestine detector readings into a cited temperature and alert sequence without adding a new causal claim | `extract`, `encode`, `score` | SIE endpoint; standalone `uv` project; exact NTSB illustrated report spread | Runnable agent example |
 | [Make a shelf gap auditable](./retail-shelf-audit) | Detecting one empty facing, deriving its notice and shelf-label crops by geometry, then preserving OCR evidence | `extract` | GPU SIE deployment; standalone `uv` project; CC0 supermarket shelf image and recorded direct-checkpoint evidence included | Runnable evaluation example |
 | [A behavioural gate that catches hijacked AI agents by their actions, not their credentials](./agent-action-monitor) | Judging a proposed AI agent action against that agent's own learned baseline in real time, before it reaches a downstream system | `encode`, `score`, `extract` | Docker Compose (gate + self-hosted SIE + n8n + mock downstream), no API key required | Runnable demo |
+| [Find the best RAG config before you build](./rag-params-finder) | Sweeping embeddings × chunking × retrieval on your data before building a RAG app | `encode`, `score` (optional rerank) | External repo; MongoDB local or Atlas/Postgres; SIE gateway or Docker | External project guide |
 
 For docs publishing, lead with the quickest runnable demos, then use the
 benchmark and evaluation examples for deeper technical users.
diff --git a/examples/rag-params-finder/README.md b/examples/rag-params-finder/README.md
new file mode 100644
index 000000000..b1f9708cb
--- /dev/null
+++ b/examples/rag-params-finder/README.md
@@ -0,0 +1,48 @@
+# Find the best RAG config before you build
+
+> Sweep embeddings × chunking × retrieval on **your** data — then ship the winning config first.
+
+This is an **external project guide**. The runnable app lives in
+[neomatrix369/rag-params-finder](https://github.com/neomatrix369/rag-params-finder)
+(MIT). This folder is the SIE-facing onboarding surface: short pages here, full
+detail in that repo.
+
+**SIE primitives used:** `encode` (embeddings via BGE-M3 / Stella-v5 / SPLADE-v3);
+optional `score` (SIE rerank). SIE is **opt-in** — the default stack runs without it.
+
+## Who this is for
+
+| You are… | Start here |
+|---|---|
+| New to SIE, found this in the gallery | [Getting started](./getting-started.md) → [SIE integration](./sie-integration.md) |
+| New to rag-params-finder, want SIE embeddings | Same path — then [What SIE does here](./what-sie-does.md) |
+
+Both audiences share one happy path: local MongoDB stack → enable a remote SIE
+gateway → one `example-sie.yaml` sweep → dashboard.
+
+## Start here
+
+1. [Getting started](./getting-started.md) — clone, prereqs, local Mongo path, dashboard
+2. [SIE integration](./sie-integration.md) — env vars, health checks, first SIE sweep
+3. [What SIE does here](./what-sie-does.md) — models, encode/rerank, vs Voyage/local
+4. [Troubleshooting](./troubleshooting.md) — short FAQ + deep-links
+
+**Canonical docs in the project:**
+[QUICKSTART](https://github.com/neomatrix369/rag-params-finder/blob/main/QUICKSTART.md) ·
+[SIE setup](https://github.com/neomatrix369/rag-params-finder/blob/main/docs/user-guide/sie-setup.md) ·
+[docs index](https://github.com/neomatrix369/rag-params-finder/blob/main/docs/README.md)
+
+## Ports cheat sheet
+
+| Service | Port | Notes |
+|---|---|---|
+| API | `8001` | rag-params-finder server |
+| Dashboard | `5374` | Experiments UI |
+| SIE (self-hosted only) | `8720` | Not started by `./start-services.sh` |
+
+## Attribution
+
+Built and maintained in
+[neomatrix369/rag-params-finder](https://github.com/neomatrix369/rag-params-finder)
+under the [MIT License](https://github.com/neomatrix369/rag-params-finder/blob/main/LICENSE).
+Screenshots and deeper guides live in that repository.
diff --git a/examples/rag-params-finder/getting-started.md b/examples/rag-params-finder/getting-started.md
new file mode 100644
index 000000000..5dc6365b2
--- /dev/null
+++ b/examples/rag-params-finder/getting-started.md
@@ -0,0 +1,52 @@
+# Getting started (without SIE yet)
+
+Goal: clone the external repo, start the local MongoDB stack, and open the
+dashboard. Enable SIE in [SIE integration](./sie-integration.md) after this works.
+
+**Source of truth:**
+[QUICKSTART.md](https://github.com/neomatrix369/rag-params-finder/blob/main/QUICKSTART.md)
+in the project repo.
+
+## Prerequisites
+
+- Git
+- Docker Desktop (running)
+- For host CLI later: Python 3.12+, [`uv`](https://docs.astral.sh/uv/)
+
+No Atlas account, Voyage key, or SIE credentials are required for this path.
+
+## Clone and start (MongoDB local)
+
+```bash
+git clone https://github.com/neomatrix369/rag-params-finder.git
+cd rag-params-finder
+cp .env.example .env
+./start-services.sh --mongodb-local
+```
+
+Open **http://localhost:5374**. The stack starts MongoDB Atlas Local, the API
+server (`:8001`), and the dashboard. SIE is **not** started — that is intentional.
+
+Verify the API:
+
+```bash
+curl -s http://localhost:8001/health
+```
+
+You should see the server healthy. With default `.env`, SIE reports as
+`"sie": "disabled"`.
+
+## Other storage paths
+
+| Path | When | Doc |
+|---|---|---|
+| Atlas cloud | You already have `MONGODB_URI` | [QUICKSTART Path B](https://github.com/neomatrix369/rag-params-finder/blob/main/QUICKSTART.md) |
+| Postgres / pgvector | Prefer Supabase or local Postgres | [Postgres setup](https://github.com/neomatrix369/rag-params-finder/blob/main/docs/user-guide/postgres-setup.md) |
+| Manual two-terminal | No Docker for the app | [QUICKSTART Path C](https://github.com/neomatrix369/rag-params-finder/blob/main/QUICKSTART.md) |
+
+Step-by-step install and first experiment:
+[getting-started.md](https://github.com/neomatrix369/rag-params-finder/blob/main/docs/user-guide/getting-started.md).
+
+## Next
+
+Wire SIE and run one sweep: [SIE integration](./sie-integration.md).
diff --git a/examples/rag-params-finder/sie-integration.md b/examples/rag-params-finder/sie-integration.md
new file mode 100644
index 000000000..e03a07feb
--- /dev/null
+++ b/examples/rag-params-finder/sie-integration.md
@@ -0,0 +1,80 @@
+# SIE integration
+
+SIE is **opt-in**. `./start-services.sh` and default Compose start the server +
+dashboard only — they never start SIE.
+
+**Source of truth:**
+[docs/user-guide/sie-setup.md](https://github.com/neomatrix369/rag-params-finder/blob/main/docs/user-guide/sie-setup.md).
+
+## Happy path — remote gateway (recommended)
+
+Finish [Getting started](./getting-started.md) first so `:8001` is up.
+
+In the project `.env`:
+
+```bash
+SIE_ENABLED=true
+SIE_ENDPOINT=https://your-sie-gateway.example.com
+SIE_API_KEY=your_gateway_token
+```
+
+Restart or reload the rag-params-finder server after changing `.env`.
+
+Check the gateway, then the app health:
+
+```bash
+curl -H "Authorization: Bearer $SIE_API_KEY" "$SIE_ENDPOINT/healthz"
+curl -s http://localhost:8001/health
+# → "sie":"reachable"
+```
+
+**First success:** `"sie":"reachable"`, then one sweep:
+
+```bash
+# from the rag-params-finder repo root, with CLI installed (see project QUICKSTART)
+rag-params-finder run --config configs/mongodb/example-sie.yaml
+```
+
+Config file:
+[configs/mongodb/example-sie.yaml](https://github.com/neomatrix369/rag-params-finder/blob/main/configs/mongodb/example-sie.yaml).
+On Postgres/Supabase use
+[configs/supabase/example-sie.yaml](https://github.com/neomatrix369/rag-params-finder/blob/main/configs/supabase/example-sie.yaml)
+instead.
+
+Compare results in the dashboard at **http://localhost:5374**.
+
+## Alternate — self-hosted Docker
+
+Use when you have no remote gateway. Needs Docker, disk for model weights, and
+usually `HF_TOKEN` on the **SIE container** (not for app routing).
+
+Typical host endpoint:
+
+```bash
+SIE_ENABLED=true
+SIE_ENDPOINT=http://localhost:8720
+# SIE_API_KEY usually unset for local unauthenticated server
+```
+
+Full `docker run` flags, warm-up (wait for encode **200**, not only `/healthz`),
+Apple Silicon notes, and Aim UI:
+[Self-hosted Docker in sie-setup.md](https://github.com/neomatrix369/rag-params-finder/blob/main/docs/user-guide/sie-setup.md).
+
+When the server runs in Docker and SIE on the host, use
+`http://host.docker.internal:8720` as `SIE_ENDPOINT`.
+
+## Env vars (same for remote and local)
+
+| Variable | Role |
+|---|---|
+| `SIE_ENABLED` | Master on/off (default `false`) |
+| `SIE_ENDPOINT` | HTTP base URL of the SIE gateway or local server |
+| `SIE_API_KEY` | Bearer token when the gateway requires auth |
+
+Details and smoke tests (including `POST /api/v1/sweep`):
+[sie-setup.md](https://github.com/neomatrix369/rag-params-finder/blob/main/docs/user-guide/sie-setup.md).
+
+## Next
+
+Understand models and primitives: [What SIE does here](./what-sie-does.md).
+Stuck? [Troubleshooting](./troubleshooting.md).
diff --git a/examples/rag-params-finder/troubleshooting.md b/examples/rag-params-finder/troubleshooting.md
new file mode 100644
index 000000000..7dc094765
--- /dev/null
+++ b/examples/rag-params-finder/troubleshooting.md
@@ -0,0 +1,43 @@
+# Troubleshooting (SIE-focused)
+
+Short FAQ for gallery readers. Full tables and recovery steps:
+[project troubleshooting](https://github.com/neomatrix369/rag-params-finder/blob/main/docs/user-guide/troubleshooting.md)
+(especially the SIE section) and
+[sie-setup.md](https://github.com/neomatrix369/rag-params-finder/blob/main/docs/user-guide/sie-setup.md).
+
+## `"sie": "disabled"` on `/health`
+
+`SIE_ENABLED` is false or unset (default). Set `SIE_ENABLED=true`, set
+`SIE_ENDPOINT`, reload the server.
+
+## `"sie": "unreachable"` (or preflight fails)
+
+- Wrong `SIE_ENDPOINT` (typo, http vs https, missing port)
+- Gateway auth: set `SIE_API_KEY` and use `Authorization: Bearer …` on `/healthz`
+- Local Docker: SIE not running, still warming up, or server-in-Docker needs
+  `host.docker.internal:8720`
+- Encode still returning **503** during model load — wait until encode returns **200**
+
+## Sweep with `provider: sie` fails immediately
+
+SIE guard runs preflight. Fix health/`SIE_ENABLED` first, then re-run. Confirm
+indexes for your storage backend (`vector_index_1024` + text index on Mongo for
+typical SIE configs — see project MongoDB setup).
+
+## `./start-services.sh` did not bring up SIE
+
+Expected. Start a remote gateway or follow self-hosted Docker in
+[sie-setup.md](https://github.com/neomatrix369/rag-params-finder/blob/main/docs/user-guide/sie-setup.md).
+
+## Dashboard up but no SIE experiments
+
+Use a SIE config such as
+[`configs/mongodb/example-sie.yaml`](https://github.com/neomatrix369/rag-params-finder/blob/main/configs/mongodb/example-sie.yaml),
+not a Voyage-only or local-only example.
+
+## Still stuck?
+
+1. [sie-setup.md](https://github.com/neomatrix369/rag-params-finder/blob/main/docs/user-guide/sie-setup.md) — known issues, warm-up, Aim UI  
+2. [troubleshooting.md](https://github.com/neomatrix369/rag-params-finder/blob/main/docs/user-guide/troubleshooting.md) — indexes, Docker, storage  
+3. Open an issue on
+   [neomatrix369/rag-params-finder](https://github.com/neomatrix369/rag-params-finder/issues)
diff --git a/examples/rag-params-finder/what-sie-does.md b/examples/rag-params-finder/what-sie-does.md
new file mode 100644
index 000000000..56e69dd0f
--- /dev/null
+++ b/examples/rag-params-finder/what-sie-does.md
@@ -0,0 +1,67 @@
+# What SIE does in rag-params-finder
+
+rag-params-finder sweeps **embedding × chunking × retrieval** combinations and
+ranks them by retrieval scores — before you build a RAG app. SIE is one embedding
+(and optional rerank) **provider**, alongside Voyage AI and local sentence-transformers.
+
+**Source of truth:**
+[sie-setup.md](https://github.com/neomatrix369/rag-params-finder/blob/main/docs/user-guide/sie-setup.md) ·
+[configuration.md](https://github.com/neomatrix369/rag-params-finder/blob/main/docs/user-guide/configuration.md).
+
+## SIE primitives
+
+| Primitive | Role in this project |
+|---|---|
+| `encode` | Open-source embeddings for sweep experiments (`provider: sie`) |
+| `score` | Optional SIE reranker (e.g. BGE reranker) when configured |
+
+No LLM generation is required for core sweeps — evaluation stays embedding-centric.
+
+## Models (SIE catalog used here)
+
+| Model | Typical use |
+|---|---|
+| BGE-M3 | Dense 1024-dim default when SIE is enabled for Tier-1 sweep |
+| Stella-v5 | Alternate dense encoder |
+| SPLADE-v3 | Sparse retrieval experiments |
+| BGE reranker | Optional rerank via SIE |
+
+Exact IDs and YAML knobs live in the project
+[`model_registry`](https://github.com/neomatrix369/rag-params-finder/blob/main/server/core/model_registry.py)
+and example configs under `configs/mongodb/` and `configs/supabase/`.
+
+## vs Voyage and local MiniLM
+
+| Provider | Needs | Good for |
+|---|---|---|
+| **SIE** | Gateway or Docker + `SIE_ENABLED` | Open-source SOTA models under one HTTP API |
+| **Voyage** | API key | Hosted Voyage embedding families |
+| **Local** (`sentence-transformers`) | CPU/GPU on the app host | Offline demos (`all-MiniLM-L6-v2`, etc.) |
+
+You can compare providers across sweeps; SIE does not replace the vector store
+(MongoDB Atlas Vector Search or Postgres/pgvector).
+
+## Architecture sketch
+
+```text
+Your corpus + questions
+        │
+        ▼
+rag-params-finder server  ──encode/rerank──►  SIE (remote or :8720)
+        │
+        ▼
+MongoDB / Postgres (vectors + scores)
+        │
+        ▼
+Dashboard :5374
+```
+
+## Screenshots
+
+SIE vs local experiment UIs are documented with images in the project
+[README screenshots](https://github.com/neomatrix369/rag-params-finder/blob/main/README.md#-screenshots).
+
+## Next
+
+Wire it up: [SIE integration](./sie-integration.md). Problems:
+[Troubleshooting](./troubleshooting.md).

From 4cb9cb8be411425eb8940c7616771bc367a45d84 Mon Sep 17 00:00:00 2001
From: Mani Sarkar <sadhak001@gmail.com>
Date: Fri, 21 Aug 2026 15:17:57 +0100
Subject: [PATCH 2/7] docs(examples): define External project guide status in
 gallery

Clarify the new gallery Status label used by docs-only external landings.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 examples/README.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/examples/README.md b/examples/README.md
index b74b02083..476b21a93 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -9,7 +9,8 @@ New to SIE? Start with the **[quickstart notebook](./quickstart.ipynb)** [![Open
 Use this table to pick the right starting point. "Runnable" means the
 example has code, sample data or data-fetch instructions, and a documented
 local path. "Advanced" examples may require a custom SIE image or third-party
-service keys.
+service keys. "External project guide" means docs-only onboarding that deep-links
+to a separately maintained repository (clone and run there).
 
 | Example | Best for | SIE primitives | Setup | Status |
 |---|---|---|---|---|

From 57a2c26ebbdf2ec1bf82c2d8af4b674c7a171a82 Mon Sep 17 00:00:00 2001
From: Mani Sarkar <sadhak001@gmail.com>
Date: Fri, 21 Aug 2026 15:35:28 +0100
Subject: [PATCH 3/7] docs(examples): address CodeRabbit review on
 rag-params-finder guide

Export MONGODB_URI before the SIE handoff, recreate Compose for env
reload, require encode readiness before sweeps, and document the
gitignored input PDF prerequisite for example-sie.yaml.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 examples/rag-params-finder/getting-started.md | 10 +++-
 examples/rag-params-finder/sie-integration.md | 57 +++++++++++++++++--
 2 files changed, 61 insertions(+), 6 deletions(-)

diff --git a/examples/rag-params-finder/getting-started.md b/examples/rag-params-finder/getting-started.md
index 5dc6365b2..cad608c8b 100644
--- a/examples/rag-params-finder/getting-started.md
+++ b/examples/rag-params-finder/getting-started.md
@@ -49,4 +49,12 @@ Step-by-step install and first experiment:
 
 ## Next
 
-Wire SIE and run one sweep: [SIE integration](./sie-integration.md).
+Before the host CLI / SIE handoff, export the URI the startup script printed
+(leave `.env` placeholders unchanged for Atlas Local):
+
+```bash
+# value also printed by ./start-services.sh --mongodb-local
+export MONGODB_URI="mongodb://localhost:27017/rag_params_finder?directConnection=true"
+```
+
+Then wire SIE and run one sweep: [SIE integration](./sie-integration.md).
diff --git a/examples/rag-params-finder/sie-integration.md b/examples/rag-params-finder/sie-integration.md
index e03a07feb..e511dfd64 100644
--- a/examples/rag-params-finder/sie-integration.md
+++ b/examples/rag-params-finder/sie-integration.md
@@ -8,7 +8,8 @@ dashboard only — they never start SIE.
 
 ## Happy path — remote gateway (recommended)
 
-Finish [Getting started](./getting-started.md) first so `:8001` is up.
+Finish [Getting started](./getting-started.md) first so `:8001` is up and
+`MONGODB_URI` is exported for the host CLI.
 
 In the project `.env`:
 
@@ -18,20 +19,66 @@ SIE_ENDPOINT=https://your-sie-gateway.example.com
 SIE_API_KEY=your_gateway_token
 ```
 
-Restart or reload the rag-params-finder server after changing `.env`.
+Reload the server so it picks up the new env (a plain restart is not enough for
+Compose — env is baked in at container create time):
 
-Check the gateway, then the app health:
+```bash
+# Compose (typical after ./start-services.sh)
+docker compose up -d --force-recreate server
+
+# Host-run server instead: reload or restart uvicorn
+```
+
+Source `.env` into the **current shell** before gateway curls (editing the file
+does not update existing variables):
+
+```bash
+set -a && source .env && set +a
+```
+
+### Readiness checks
+
+**1. Gateway process alive** (`/healthz` ≠ model ready):
 
 ```bash
 curl -H "Authorization: Bearer $SIE_API_KEY" "$SIE_ENDPOINT/healthz"
+# → ok
+```
+
+**2. Model can encode** — wait for HTTP **200** (503 during warm-up is expected):
+
+```bash
+until curl -sf -o /dev/null -X POST "$SIE_ENDPOINT/v1/encode/BAAI/bge-m3" \
+  -H "Authorization: Bearer $SIE_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"items":[{"text":"readiness probe"}]}'; do
+  echo "SIE encode not ready yet — waiting 10s..."
+  sleep 10
+done
+```
+
+**3. App sees SIE:**
+
+```bash
 curl -s http://localhost:8001/health
 # → "sie":"reachable"
 ```
 
-**First success:** `"sie":"reachable"`, then one sweep:
+### First success
+
+Provide an input PDF (`input_data/` is gitignored). Either copy a file to the
+path expected by the example config, or point `data_paths` at an existing PDF:
+
+```bash
+mkdir -p input_data/pdfs
+cp /path/to/your-document.pdf \
+  input_data/pdfs/The_Federal_Pell_Grant_Program.pdf
+# or edit data_paths in configs/mongodb/example-sie.yaml
+```
+
+Then run one sweep (CLI installed per project QUICKSTART):
 
 ```bash
-# from the rag-params-finder repo root, with CLI installed (see project QUICKSTART)
 rag-params-finder run --config configs/mongodb/example-sie.yaml
 ```
 

From 05290bdf5b7146afb28ff77f79c186b90de05e4f Mon Sep 17 00:00:00 2001
From: Mani Sarkar <sadhak001@gmail.com>
Date: Fri, 21 Aug 2026 15:49:49 +0100
Subject: [PATCH 4/7] docs(examples): preserve MONGODB_URI and bound encode
 wait

Avoid sourcing .env wholesale (it clobbers the host CLI Atlas Local
URI) and stop the encode readiness loop on terminal HTTP failures.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 examples/rag-params-finder/sie-integration.md | 40 ++++++++++++++-----
 1 file changed, 30 insertions(+), 10 deletions(-)

diff --git a/examples/rag-params-finder/sie-integration.md b/examples/rag-params-finder/sie-integration.md
index e511dfd64..29d0d7561 100644
--- a/examples/rag-params-finder/sie-integration.md
+++ b/examples/rag-params-finder/sie-integration.md
@@ -29,11 +29,15 @@ docker compose up -d --force-recreate server
 # Host-run server instead: reload or restart uvicorn
 ```
 
-Source `.env` into the **current shell** before gateway curls (editing the file
-does not update existing variables):
+Load only SIE vars into the **current shell** before gateway curls (do not
+`source .env` wholesale — that overwrites the host CLI `MONGODB_URI` export
+from [Getting started](./getting-started.md) with the Atlas placeholder):
 
 ```bash
-set -a && source .env && set +a
+export SIE_ENABLED=true
+export SIE_ENDPOINT=https://your-sie-gateway.example.com
+export SIE_API_KEY=your_gateway_token
+# keep the earlier MONGODB_URI export for Atlas Local host CLI
 ```
 
 ### Readiness checks
@@ -41,18 +45,34 @@ set -a && source .env && set +a
 **1. Gateway process alive** (`/healthz` ≠ model ready):
 
 ```bash
-curl -H "Authorization: Bearer $SIE_API_KEY" "$SIE_ENDPOINT/healthz"
+curl --connect-timeout 5 --max-time 15 \
+  -H "Authorization: Bearer $SIE_API_KEY" "$SIE_ENDPOINT/healthz"
 # → ok
 ```
 
-**2. Model can encode** — wait for HTTP **200** (503 during warm-up is expected):
+**2. Model can encode** — accept only HTTP **200**; retry **503** (warm-up);
+stop on terminal failures (e.g. **502**, **401**):
 
 ```bash
-until curl -sf -o /dev/null -X POST "$SIE_ENDPOINT/v1/encode/BAAI/bge-m3" \
-  -H "Authorization: Bearer $SIE_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{"items":[{"text":"readiness probe"}]}'; do
-  echo "SIE encode not ready yet — waiting 10s..."
+attempts=0
+max_attempts=60   # ~10 minutes at 10s interval
+while true; do
+  attempts=$((attempts + 1))
+  code=$(curl --connect-timeout 5 --max-time 30 -s -o /dev/null -w '%{http_code}' \
+    -X POST "$SIE_ENDPOINT/v1/encode/BAAI/bge-m3" \
+    -H "Authorization: Bearer $SIE_API_KEY" \
+    -H "Content-Type: application/json" \
+    -d '{"items":[{"text":"readiness probe"}]}' || true)
+  case "$code" in
+    200) echo "SIE encode ready"; break ;;
+    503) echo "SIE warm-up ($attempts/$max_attempts) — waiting 10s..." ;;
+    000) echo "SIE unreachable ($attempts/$max_attempts) — waiting 10s..." ;;
+    *) echo "SIE encode failed with HTTP $code — abort"; exit 1 ;;
+  esac
+  if [ "$attempts" -ge "$max_attempts" ]; then
+    echo "SIE encode not ready after $max_attempts attempts — abort"
+    exit 1
+  fi
   sleep 10
 done
 ```

From 2ae9b5f402551134ba1f8b7f3bcbdf647f20f9e6 Mon Sep 17 00:00:00 2001
From: Mani Sarkar <sadhak001@gmail.com>
Date: Fri, 21 Aug 2026 15:52:22 +0100
Subject: [PATCH 5/7] docs(examples): apply tripwire gallery lessons to
 rag-params-finder

Port CodeRabbit patterns from #244: separate local vs optional SIE paths,
encode/score primitive naming, config-specific Mongo indexes, and an
external-guide submission path in the gallery README.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 examples/README.md                            | 18 ++++++++++++++++--
 examples/rag-params-finder/README.md          |  7 ++++---
 examples/rag-params-finder/troubleshooting.md |  9 ++++++---
 examples/rag-params-finder/what-sie-does.md   |  2 +-
 4 files changed, 27 insertions(+), 9 deletions(-)

diff --git a/examples/README.md b/examples/README.md
index 476b21a93..9bed844f3 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -1,6 +1,10 @@
 # Examples
 
-A project gallery of full end-to-end applications built with SIE. Each project lives in its own subdirectory. Clone it, run it, learn from it.
+A project gallery of full end-to-end applications built with SIE. Most entries
+are self-contained under `examples/<name>/` — clone this repo, run them locally,
+and learn from them. Rows marked **External project guide** are docs-only
+landings that deep-link to a separately maintained repository (clone and run
+there).
 
 New to SIE? Start with the **[quickstart notebook](./quickstart.ipynb)** [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/superlinked/sie/blob/main/examples/quickstart.ipynb): encode, score, and extract in 5 minutes, then pick a project below.
 
@@ -43,14 +47,24 @@ benchmark and evaluation examples for deeper technical users.
 
 We welcome contributions. To add your project to the gallery:
 
+### Runnable examples (default)
+
 1. **Create a subdirectory** with a short, descriptive name (e.g. `wikipedia-search/`, `pdf-rag/`)
 2. **Include a README** that covers:
    - What the project does
    - How to run it (`docker compose up`, a script, etc.)
    - Which SIE features it uses (encode, score, extract, cluster, etc.)
-3. **Keep it self-contained** - include a `requirements.txt` or `package.json`, a docker-compose if needed, and sample data or instructions to fetch it
+3. **Keep it self-contained** — include a `requirements.txt` or `package.json`, a docker-compose if needed, and sample data or instructions to fetch it
 4. **Open a PR** against `main`
 
+### External project guides
+
+Use this path only when vendoring a runnable copy is impractical (large multi-service
+apps). Ship a thin `examples/<name>/` landing (README + short sibling pages) that
+deep-links to the external repo’s QUICKSTART/SIE setup, set Status to
+**External project guide**, and do **not** require in-tree `requirements.txt` /
+compose / sample data. See `examples/rag-params-finder/` for the shape.
+
 ### Review workflow
 
 Maintainers apply the `coderabbit-direct` label to eligible PRs that change content under `examples/**` or the root `README.md`. The label opts the PR into CodeRabbit review and allows CodeRabbit to formally approve it once review comments are resolved and required checks pass.
diff --git a/examples/rag-params-finder/README.md b/examples/rag-params-finder/README.md
index b1f9708cb..bbc162d2a 100644
--- a/examples/rag-params-finder/README.md
+++ b/examples/rag-params-finder/README.md
@@ -17,14 +17,15 @@ optional `score` (SIE rerank). SIE is **opt-in** — the default stack runs with
 | New to SIE, found this in the gallery | [Getting started](./getting-started.md) → [SIE integration](./sie-integration.md) |
 | New to rag-params-finder, want SIE embeddings | Same path — then [What SIE does here](./what-sie-does.md) |
 
-Both audiences share one happy path: local MongoDB stack → enable a remote SIE
-gateway → one `example-sie.yaml` sweep → dashboard.
+Both audiences share the same **local** starting path (MongoDB stack +
+dashboard). SIE is optional afterward: enable a remote gateway, then run one
+`example-sie.yaml` sweep.
 
 ## Start here
 
 1. [Getting started](./getting-started.md) — clone, prereqs, local Mongo path, dashboard
 2. [SIE integration](./sie-integration.md) — env vars, health checks, first SIE sweep
-3. [What SIE does here](./what-sie-does.md) — models, encode/rerank, vs Voyage/local
+3. [What SIE does here](./what-sie-does.md) — models, encode/score, vs Voyage/local
 4. [Troubleshooting](./troubleshooting.md) — short FAQ + deep-links
 
 **Canonical docs in the project:**
diff --git a/examples/rag-params-finder/troubleshooting.md b/examples/rag-params-finder/troubleshooting.md
index 7dc094765..e0130e3ad 100644
--- a/examples/rag-params-finder/troubleshooting.md
+++ b/examples/rag-params-finder/troubleshooting.md
@@ -20,9 +20,12 @@ Short FAQ for gallery readers. Full tables and recovery steps:
 
 ## Sweep with `provider: sie` fails immediately
 
-SIE guard runs preflight. Fix health/`SIE_ENABLED` first, then re-run. Confirm
-indexes for your storage backend (`vector_index_1024` + text index on Mongo for
-typical SIE configs — see project MongoDB setup).
+SIE guard runs preflight. Fix health/`SIE_ENABLED` first, then re-run. Index
+requirements come from the **selected config**, not from `provider: sie` alone.
+For [`configs/mongodb/example-sie.yaml`](https://github.com/neomatrix369/rag-params-finder/blob/main/configs/mongodb/example-sie.yaml)
+(dense BGE-M3 / Stella-v5), create `vector_index_1024` and `text_search_index`
+on Mongo — see project MongoDB setup. Sparse-only models can need different
+indexes; do not treat `vector_index_1024` as universal.
 
 ## `./start-services.sh` did not bring up SIE
 
diff --git a/examples/rag-params-finder/what-sie-does.md b/examples/rag-params-finder/what-sie-does.md
index 56e69dd0f..4b24b8ca7 100644
--- a/examples/rag-params-finder/what-sie-does.md
+++ b/examples/rag-params-finder/what-sie-does.md
@@ -47,7 +47,7 @@ You can compare providers across sweeps; SIE does not replace the vector store
 Your corpus + questions
         │
         ▼
-rag-params-finder server  ──encode/rerank──►  SIE (remote or :8720)
+rag-params-finder server  ──encode/score──►  SIE (remote or :8720)
         │
         ▼
 MongoDB / Postgres (vectors + scores)

From af93dac4d45c499f631cf4168d006b6e8c01dacb Mon Sep 17 00:00:00 2001
From: Mani Sarkar <sadhak001@gmail.com>
Date: Fri, 21 Aug 2026 15:57:28 +0100
Subject: [PATCH 6/7] docs(examples): fix encode wait bound and HF_TOKEN
 wording

Align the readiness-loop comment with the real ~40m worst-case budget,
and state that self-hosted SIE requires HF_TOKEN for model downloads.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 examples/rag-params-finder/sie-integration.md | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/examples/rag-params-finder/sie-integration.md b/examples/rag-params-finder/sie-integration.md
index 29d0d7561..a7a1d9d34 100644
--- a/examples/rag-params-finder/sie-integration.md
+++ b/examples/rag-params-finder/sie-integration.md
@@ -55,7 +55,9 @@ stop on terminal failures (e.g. **502**, **401**):
 
 ```bash
 attempts=0
-max_attempts=60   # ~10 minutes at 10s interval
+# 60 attempts × (up to 30s request + 10s sleep) ≈ 40 minutes worst case —
+# first-run model download/load can exceed a short 10-minute budget.
+max_attempts=60
 while true; do
   attempts=$((attempts + 1))
   code=$(curl --connect-timeout 5 --max-time 30 -s -o /dev/null -w '%{http_code}' \
@@ -113,7 +115,8 @@ Compare results in the dashboard at **http://localhost:5374**.
 ## Alternate — self-hosted Docker
 
 Use when you have no remote gateway. Needs Docker, disk for model weights, and
-usually `HF_TOKEN` on the **SIE container** (not for app routing).
+**requires** `HF_TOKEN` on the **SIE container** for Hugging Face weight
+downloads during warm-up (not used for app routing).
 
 Typical host endpoint:
 

From bc1357b3262c376e857d910658cb74a58a3ecbc6 Mon Sep 17 00:00:00 2001
From: Mani Sarkar <sadhak001@gmail.com>
Date: Fri, 21 Aug 2026 16:18:39 +0100
Subject: [PATCH 7/7] docs(examples): mention both SIE paths and fix Docker
 endpoint URL

Landing page now covers remote gateway or self-hosted SIE; troubleshooting
uses a full http://host.docker.internal URL and clarifies chunks indexes.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 examples/rag-params-finder/README.md          |  4 ++--
 examples/rag-params-finder/troubleshooting.md | 10 ++++++----
 2 files changed, 8 insertions(+), 6 deletions(-)

diff --git a/examples/rag-params-finder/README.md b/examples/rag-params-finder/README.md
index bbc162d2a..ab8a6fc91 100644
--- a/examples/rag-params-finder/README.md
+++ b/examples/rag-params-finder/README.md
@@ -18,8 +18,8 @@ optional `score` (SIE rerank). SIE is **opt-in** — the default stack runs with
 | New to rag-params-finder, want SIE embeddings | Same path — then [What SIE does here](./what-sie-does.md) |
 
 Both audiences share the same **local** starting path (MongoDB stack +
-dashboard). SIE is optional afterward: enable a remote gateway, then run one
-`example-sie.yaml` sweep.
+dashboard). SIE is optional afterward: configure a remote gateway or start
+self-hosted SIE, then run one `example-sie.yaml` sweep.
 
 ## Start here
 
diff --git a/examples/rag-params-finder/troubleshooting.md b/examples/rag-params-finder/troubleshooting.md
index e0130e3ad..f9d4f44ea 100644
--- a/examples/rag-params-finder/troubleshooting.md
+++ b/examples/rag-params-finder/troubleshooting.md
@@ -15,7 +15,7 @@ Short FAQ for gallery readers. Full tables and recovery steps:
 - Wrong `SIE_ENDPOINT` (typo, http vs https, missing port)
 - Gateway auth: set `SIE_API_KEY` and use `Authorization: Bearer …` on `/healthz`
 - Local Docker: SIE not running, still warming up, or server-in-Docker needs
-  `host.docker.internal:8720`
+  `http://host.docker.internal:8720`
 - Encode still returning **503** during model load — wait until encode returns **200**
 
 ## Sweep with `provider: sie` fails immediately
@@ -23,9 +23,11 @@ Short FAQ for gallery readers. Full tables and recovery steps:
 SIE guard runs preflight. Fix health/`SIE_ENABLED` first, then re-run. Index
 requirements come from the **selected config**, not from `provider: sie` alone.
 For [`configs/mongodb/example-sie.yaml`](https://github.com/neomatrix369/rag-params-finder/blob/main/configs/mongodb/example-sie.yaml)
-(dense BGE-M3 / Stella-v5), create `vector_index_1024` and `text_search_index`
-on Mongo — see project MongoDB setup. Sparse-only models can need different
-indexes; do not treat `vector_index_1024` as universal.
+(dense BGE-M3 / Stella-v5), create both indexes on the `chunks` collection:
+`vector_index_1024` for dense 1024-dim embeddings, and `text_search_index` for
+the separately swept sparse/hybrid retrievers — see project MongoDB setup.
+Sparse-only models can need different indexes; do not treat `vector_index_1024`
+as universal.
 
 ## `./start-services.sh` did not bring up SIE