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/2] 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 d5bb408e311b0043f51511ce1268c30688602eeb Mon Sep 17 00:00:00 2001
From: Mani Sarkar <sadhak001@gmail.com>
Date: Fri, 21 Aug 2026 14:49:05 +0100
Subject: [PATCH 2/2] docs(examples): add tripwire external project guide

Add a thin SIE gallery landing that deep-links to neomatrix369/tripwire for
Mock/Live setup and optional SIE tiered routing, without vendoring the app.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 examples/README.md                   |  1 +
 examples/tripwire/README.md          | 49 +++++++++++++++++++++
 examples/tripwire/getting-started.md | 58 +++++++++++++++++++++++++
 examples/tripwire/sie-integration.md | 64 ++++++++++++++++++++++++++++
 examples/tripwire/troubleshooting.md | 40 +++++++++++++++++
 examples/tripwire/what-sie-does.md   | 55 ++++++++++++++++++++++++
 6 files changed, 267 insertions(+)
 create mode 100644 examples/tripwire/README.md
 create mode 100644 examples/tripwire/getting-started.md
 create mode 100644 examples/tripwire/sie-integration.md
 create mode 100644 examples/tripwire/troubleshooting.md
 create mode 100644 examples/tripwire/what-sie-does.md

diff --git a/examples/README.md b/examples/README.md
index b74b02083..dc3715265 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -34,6 +34,7 @@ service keys.
 | [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 |
+| [Scan AI skills and MCP servers, then triage with SIE](./tripwire) | Discovering and scanning AI skills/MCP servers, then optionally routing findings with Superlinked SIE | `generate` | External repo; Mock demo local; Live needs Supabase + Modal; SIE keys optional | 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/tripwire/README.md b/examples/tripwire/README.md
new file mode 100644
index 000000000..0e27007c3
--- /dev/null
+++ b/examples/tripwire/README.md
@@ -0,0 +1,49 @@
+# Scan AI skills and MCP servers, then triage with SIE
+
+> Tripwire is a metal detector for AI tools — discover, scan in isolation, review
+> findings in one dashboard. Optional Superlinked SIE routes findings after Live scans.
+
+This is an **external project guide**. The runnable app lives in
+[neomatrix369/tripwire](https://github.com/neomatrix369/tripwire).
+This folder is the SIE-facing onboarding surface: short pages here, full detail
+in that repo.
+
+**SIE primitives used:** `generate` (chat completions via OpenAI-compatible
+`/v1/chat/completions` for post-scan triage). SIE is **optional** — Mock demo and
+Live scans work without it; routing runs only when `SIE_*` keys are set.
+
+## 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 Tripwire, want SIE triage | Same path — then [What SIE does here](./what-sie-does.md) |
+
+Happy path for SIE: Mock demo first → Live scan (Supabase + Modal) → enable
+hosted SIE → `tripwire route` (or auto-route after scan).
+
+## Start here
+
+1. [Getting started](./getting-started.md) — clone, Mock demo, then Live prerequisites
+2. [SIE integration](./sie-integration.md) — `SIE_*` keys, verify, route a batch
+3. [What SIE does here](./what-sie-does.md) — tiered router, Model Studio escalation
+4. [Troubleshooting](./troubleshooting.md) — short FAQ + deep-links
+
+**Canonical docs in the project:**
+[QUICKSTART](https://github.com/neomatrix369/tripwire/blob/main/QUICKSTART.md) ·
+[Tiered router / SIE](https://github.com/neomatrix369/tripwire/blob/main/docs/user-guide/tiered-router-setup.md) ·
+[docs hub](https://github.com/neomatrix369/tripwire/blob/main/docs/README.md)
+
+## Ports cheat sheet
+
+| Service | Port | Notes |
+|---|---|---|
+| Dashboard | `8765` | `node scripts/serve-dashboard.mjs` |
+| SIE | Hosted | `https://api.superlinked.com` or EU endpoint — not self-hosted by default |
+
+## Attribution
+
+Built and maintained in
+[neomatrix369/tripwire](https://github.com/neomatrix369/tripwire)
+([license](https://github.com/neomatrix369/tripwire/blob/main/LICENSE)).
+Architecture and deeper guides live in that repository.
diff --git a/examples/tripwire/getting-started.md b/examples/tripwire/getting-started.md
new file mode 100644
index 000000000..346fb1bbb
--- /dev/null
+++ b/examples/tripwire/getting-started.md
@@ -0,0 +1,58 @@
+# Getting started (Mock first, then Live)
+
+Goal: install the Tripwire CLI and see the Mock dashboard before adding cloud
+accounts or SIE.
+
+**Source of truth:**
+[QUICKSTART.md](https://github.com/neomatrix369/tripwire/blob/main/QUICKSTART.md).
+
+## Prerequisites
+
+- Node.js **22**
+- Python **3.12** (scanners / tooling)
+- Git and npm
+
+Details: [prerequisites.md](https://github.com/neomatrix369/tripwire/blob/main/docs/user-guide/prerequisites.md).
+
+## Mock demo (no cloud accounts)
+
+```bash
+git clone https://github.com/neomatrix369/tripwire.git
+cd tripwire
+cd cli && npm install && npm link && cd ..
+
+tripwire scan --dry-discover ./fixtures/skills/safe-csv-cleaner
+node scripts/serve-dashboard.mjs
+```
+
+Open **http://127.0.0.1:8765/** → choose **Mock (demo data)** in Guard.
+
+More commands:
+[setup-commands.md](https://github.com/neomatrix369/tripwire/blob/main/docs/user-guide/setup-commands.md).
+
+## Live path (before SIE)
+
+SIE routing expects a completed **Live** scan batch. Minimum Viable Live:
+**Supabase + Modal** (scanner vendor keys are optional and soft-skip if missing).
+
+1. Accounts: [supabase-setup](https://github.com/neomatrix369/tripwire/blob/main/docs/user-guide/supabase-setup.md) →
+   [modal-setup](https://github.com/neomatrix369/tripwire/blob/main/docs/user-guide/modal-setup.md)
+2. Keys: [env-vars.md](https://github.com/neomatrix369/tripwire/blob/main/docs/user-guide/env-vars.md)
+3. Bootstrap:
+
+```bash
+cp .env.example .env
+# fill SUPABASE_* and MODAL_TOKEN_* (and scanners you want)
+tripwire setup
+./scripts/setup-modal.sh
+tripwire scan ./fixtures/skills/safe-csv-cleaner
+node scripts/serve-dashboard.mjs
+# Open Live (Supabase) in the dashboard
+```
+
+Full Live checklist:
+[QUICKSTART — Live](https://github.com/neomatrix369/tripwire/blob/main/QUICKSTART.md#live-advanced).
+
+## Next
+
+Enable Superlinked routing: [SIE integration](./sie-integration.md).
diff --git a/examples/tripwire/sie-integration.md b/examples/tripwire/sie-integration.md
new file mode 100644
index 000000000..4c4e2fd00
--- /dev/null
+++ b/examples/tripwire/sie-integration.md
@@ -0,0 +1,64 @@
+# SIE integration (tiered router)
+
+SIE is **optional**. Missing `SIE_*` keys causes auto-route to warn and skip; the
+scan itself still succeeds.
+
+**Source of truth:**
+[docs/user-guide/tiered-router-setup.md](https://github.com/neomatrix369/tripwire/blob/main/docs/user-guide/tiered-router-setup.md).
+
+Finish a Live scan path from [Getting started](./getting-started.md) before
+relying on routing in the product UI.
+
+## Happy path — hosted Superlinked gateway
+
+1. Sign in at [console.superlinked.com](https://console.superlinked.com) → **Keys**.
+2. Put values in the **repo-root** `.env` (CLI does **not** load `prototypes/.env`):
+
+```bash
+SIE_ENDPOINT=https://api.superlinked.com
+# EU: https://eu.api.superlinked.com
+SIE_API_KEY=sk-sie-…
+# optional
+SIE_MODEL=gen-4b
+```
+
+Key map:
+[env-vars — tiered router](https://github.com/neomatrix369/tripwire/blob/main/docs/user-guide/env-vars.md#optional--tiered-router-sie--model-studio).
+
+## Verify SIE alone
+
+```bash
+cd prototypes/sie-studio
+python3 sie_studio.py list
+python3 sie_studio.py generate "Reply with one word: ok" --model gen-4b
+```
+
+Sample CLI notes:
+[prototypes/sie-studio](https://github.com/neomatrix369/tripwire/blob/main/prototypes/sie-studio/README.md).
+
+## Route after a Live scan
+
+```bash
+tripwire scan ./fixtures/skills/safe-csv-cleaner   # auto-routes when SIE_* set
+# or
+tripwire route --batch-id <batch_id>
+node scripts/serve-dashboard.mjs
+```
+
+Look for pathway strips (Scan → SIE → …) and filters (**Escalated** / **SIE-only**):
+[reading-router-results.md](https://github.com/neomatrix369/tripwire/blob/main/docs/user-guide/reading-router-results.md).
+
+**First success:** a batch shows SIE routing strips in the Live dashboard (or
+`tripwire route` completes without skipping for missing keys).
+
+## Optional — Model Studio escalation
+
+Alibaba Cloud Model Studio runs only when SIE signals conflict, unusual status,
+or low confidence. Configure after Part A in
+[tiered-router-setup.md](https://github.com/neomatrix369/tripwire/blob/main/docs/user-guide/tiered-router-setup.md)
+(`DASHSCOPE_*` / `ALIBABA_OPENAI_BASE_URL`). Review billing/quotas first.
+
+## Next
+
+Understand the router design: [What SIE does here](./what-sie-does.md).
+Stuck? [Troubleshooting](./troubleshooting.md).
diff --git a/examples/tripwire/troubleshooting.md b/examples/tripwire/troubleshooting.md
new file mode 100644
index 000000000..e88b07870
--- /dev/null
+++ b/examples/tripwire/troubleshooting.md
@@ -0,0 +1,40 @@
+# Troubleshooting (SIE / router-focused)
+
+Short FAQ for gallery readers. Full guides:
+[tiered-router-setup.md](https://github.com/neomatrix369/tripwire/blob/main/docs/user-guide/tiered-router-setup.md),
+[setup-commands — when it fails](https://github.com/neomatrix369/tripwire/blob/main/docs/user-guide/setup-commands.md#when-it-fails),
+[env-vars.md](https://github.com/neomatrix369/tripwire/blob/main/docs/user-guide/env-vars.md).
+
+## Route warns and skips
+
+`SIE_ENDPOINT` and/or `SIE_API_KEY` missing from **repo-root** `.env`. The CLI
+does not load `prototypes/.env`. Scan can still succeed.
+
+## `sie_studio.py` fails but `.env` looks fine
+
+Confirm keys are in `prototypes/.env` for the sample CLI, or export the same
+variables in the shell. Product routing still needs root `.env`.
+
+## No pathway strips in the dashboard
+
+- You are on **Mock** — switch to **Live (Supabase)** after a real scan
+- Batch was never routed — run `tripwire route --batch-id …` or re-scan with
+  `SIE_*` set
+- Read filters: [reading-router-results.md](https://github.com/neomatrix369/tripwire/blob/main/docs/user-guide/reading-router-results.md)
+
+## Live scan “all clear” but a scanner was missing
+
+Missing scanner keys **soft-skip** that engine — not a clean bill of health.
+MVP Live only needs Supabase + Modal.
+
+## Model Studio never runs
+
+Expected unless SIE escalates. Configure Part B only after SIE works; check
+`DASHSCOPE_*` / region endpoint in tiered-router-setup.
+
+## Still stuck?
+
+1. [QUICKSTART](https://github.com/neomatrix369/tripwire/blob/main/QUICKSTART.md)  
+2. [docs hub](https://github.com/neomatrix369/tripwire/blob/main/docs/README.md)  
+3. Open an issue on
+   [neomatrix369/tripwire](https://github.com/neomatrix369/tripwire/issues)
diff --git a/examples/tripwire/what-sie-does.md b/examples/tripwire/what-sie-does.md
new file mode 100644
index 000000000..0c571b71a
--- /dev/null
+++ b/examples/tripwire/what-sie-does.md
@@ -0,0 +1,55 @@
+# What SIE does in Tripwire
+
+Tripwire discovers AI skills and MCP servers, runs isolated safety scanners
+(Modal + Cisco / Snyk / Tessl, etc.), stores findings in Supabase, and shows them
+in one dashboard. **SIE is a post-scan tiered router**, not part of the core
+scan path.
+
+**Source of truth:**
+[tiered-router-setup.md](https://github.com/neomatrix369/tripwire/blob/main/docs/user-guide/tiered-router-setup.md) ·
+[ADR-0016](https://github.com/neomatrix369/tripwire/blob/main/docs/adr/0016-tiered-router-sie-model-studio.md).
+
+## SIE primitives
+
+| Primitive | Role in this project |
+|---|---|
+| `generate` | Triage scanner findings via OpenAI-compatible chat (`/v1/chat/completions`) |
+
+Default model override: `SIE_MODEL` (default `gen-4b`). Endpoint + API key from
+`SIE_ENDPOINT` / `SIE_API_KEY`.
+
+## Flow
+
+```text
+Discover → Scan (Modal / scanners) → Store (Supabase)
+                                      │
+                                      ▼
+                         SIE triage (optional)
+                                      │
+                    escalate? ──yes──► Model Studio
+                         │
+                         ▼
+                    Dashboard pathway strips
+```
+
+Router findings use `scanner_source=tiered_router` and are excluded from severity
+rollups — triage is separate from scanner severity.
+
+## vs Mock and Live without SIE
+
+| Mode | Needs SIE? |
+|---|---|
+| Mock demo | No |
+| Live scan + dashboard | No |
+| Auto-route / `tripwire route` | Yes (`SIE_*`) |
+| Model Studio second hop | SIE + Model Studio keys |
+
+## Sample prototypes
+
+- [prototypes/sie-studio](https://github.com/neomatrix369/tripwire/tree/main/prototypes/sie-studio) — list / generate against SIE
+- [prototypes/model-studio](https://github.com/neomatrix369/tripwire/tree/main/prototypes/model-studio) — escalation sample
+
+## Next
+
+Wire keys and route: [SIE integration](./sie-integration.md). Problems:
+[Troubleshooting](./troubleshooting.md).