docs(examples): generic quickstart + alliance examples layout

.env.example

@@ -1,13 +1,14 @@
 # Pinecone Read-Only MCP Configuration
+# Generic onboarding: see examples/quickstart/.env.example and examples/quickstart/README.md
 
 # Required: Your Pinecone API key
 PINECONE_API_KEY=your-pinecone-api-key-here
 
 # Optional: Dense (hybrid) Pinecone index name (default: rag-hybrid when unset)
 # PINECONE_INDEX_NAME=rag-hybrid
 
-# Optional: Reranking model (default: bge-reranker-v2-m3 when unset)
-PINECONE_RERANK_MODEL=bge-reranker-v2-m3
+# Optional: Reranking model (CLI defaults to bge-reranker-v2-m3 when unset; see docs/CONFIGURATION.md)
+# PINECONE_RERANK_MODEL=bge-reranker-v2-m3
 
 # Optional: Default number of results to return (default: 10)
 PINECONE_TOP_K=10

README.md

@@ -84,6 +84,10 @@ npm install
 npm run build
 ```
 
+## Quick start
+
+To try the server on **your own** Pinecone project (free tier, no Alliance index), follow [examples/quickstart/README.md](examples/quickstart/README.md): create two integrated-embedding indexes, copy [examples/quickstart/.env.example](examples/quickstart/.env.example), seed sample data, and run the MCP demo. Use an explicit `PINECONE_INDEX_NAME` in that flow rather than relying on Alliance default index names.
+
 ## Architecture
 
 The codebase is split into two layers:
@@ -119,7 +123,7 @@ Treat **`setupCoreServer()` / `setupAllianceServer()` as one logical server per
 - **Generic bridge only:** `import { setupCoreServer, teardownServer, ... } from '@will-cppa/pinecone-read-only-mcp'`
 - **Full Alliance surface (CLI parity):** `import { setupAllianceServer } from '@will-cppa/pinecone-read-only-mcp/alliance'`
 
-Recommended pattern: `resolveConfig({ apiKey, indexName, ... })` → `setPineconeClient(new PineconeClient(...))` → `await setupAllianceServer(config)` → connect one MCP transport. See [examples/library-embedding-demo.ts](examples/library-embedding-demo.ts) and [docs/TOOLS.md](docs/TOOLS.md#suggest-flow-gate).
+For the **generic bridge only**, see [examples/quickstart/mcp-demo.ts](examples/quickstart/mcp-demo.ts) (`setupCoreServer`). For the **full Alliance surface**, use `resolveConfig({ apiKey, indexName, ... })` → `setPineconeClient(new PineconeClient(...))` → `await setupAllianceServer(config)` → connect one MCP transport. See [examples/alliance/library-embedding-demo.ts](examples/alliance/library-embedding-demo.ts) and [docs/TOOLS.md](docs/TOOLS.md#suggest-flow-gate).
 
 ### Custom URL generators
 
@@ -152,18 +156,22 @@ const myDocs: UrlGeneratorFn = (metadata): UrlGenerationResult => {
 registerUrlGenerator('product-docs', myDocs);
 ```
 
-A fuller embedding sample lives in [examples/custom-url-generator.ts](examples/custom-url-generator.ts).
+A fuller embedding sample lives in [examples/alliance/custom-url-generator.ts](examples/alliance/custom-url-generator.ts).
 
 ### Examples
 
-| File                                                                     | Description                                                                    |
-| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------ |
-| [examples/suggest-flow-demo.ts](examples/suggest-flow-demo.ts)           | Manual **suggest_query_params → query** flow with namespace consistency notes. |
-| [examples/guided-query-demo.ts](examples/guided-query-demo.ts)           | **guided_query** orchestration and how to read `decision_trace`.               |
-| [examples/library-embedding-demo.ts](examples/library-embedding-demo.ts) | Programmatic **setupAllianceServer** wiring without the CLI binary.            |
-| [examples/custom-url-generator.ts](examples/custom-url-generator.ts)     | Custom **URL generator** registration for `generate_urls` / row enrichment.    |
+**Generic quickstart** — [examples/quickstart/](examples/quickstart/) (setup guide, seed script, `setupCoreServer` MCP demo).
+
+**Alliance / advanced** — [examples/alliance/](examples/alliance/):
+
+| File | Description |
+| ---- | ----------- |
+| [examples/alliance/suggest-flow-demo.ts](examples/alliance/suggest-flow-demo.ts) | Manual **suggest_query_params → query** flow |
+| [examples/alliance/guided-query-demo.ts](examples/alliance/guided-query-demo.ts) | **guided_query** and `decision_trace` |
+| [examples/alliance/library-embedding-demo.ts](examples/alliance/library-embedding-demo.ts) | **setupAllianceServer** without the CLI |
+| [examples/alliance/custom-url-generator.ts](examples/alliance/custom-url-generator.ts) | Custom **URL generator** registration |
 
-Run with `npx tsx examples/<file>.ts` from a checkout (requires valid Pinecone env for live paths).
+Run with `npx tsx examples/<path>.ts` from a checkout (requires valid Pinecone env for live paths). See [examples/README.md](examples/README.md).
 
 ### Claude Desktop Configuration
 
@@ -177,7 +185,7 @@ Add to your `claude_desktop_config.json`:
       "args": ["-y", "@will-cppa/pinecone-read-only-mcp"],
       "env": {
         "PINECONE_API_KEY": "your-api-key-here",
-        "PINECONE_INDEX_NAME": "your-index-name"
+        "PINECONE_INDEX_NAME": "your-index-name",
         "PINECONE_RERANK_MODEL": "your-rerank-model"
       }
     }

docs/CONFIGURATION.md

@@ -62,7 +62,7 @@ For the full Alliance tool surface (including `suggest_query_params`, `guided_qu
 2. Construct `PineconeClient` and `setPineconeClient(client)` before `setupAllianceServer(config)` (mirrors `src/index.ts`).
 3. `await setupAllianceServer(config)` (or `setupCoreServer` for generic tools only) then connect an MCP transport.
 
-See [README deployment model](../README.md#deployment-model) and [examples/library-embedding-demo.ts](../examples/library-embedding-demo.ts).
+See [README deployment model](../README.md#deployment-model), [examples/quickstart/README.md](../examples/quickstart/README.md) (generic), and [examples/alliance/library-embedding-demo.ts](../examples/alliance/library-embedding-demo.ts) (Alliance surface).
 
 ---
 

examples/README.md

@@ -1,12 +1,36 @@
 # Examples
 
-| File                                                     | Description                                                                                                      |
-| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| [custom-url-generator.ts](./custom-url-generator.ts)     | Embed the MCP server, register a **custom URL generator**, and call `setupAllianceServer()` (full tool surface). |
-| [suggest-flow-demo.ts](./suggest-flow-demo.ts)           | Document the **suggest_query_params → query** gate sequence and trimmed namespace usage.                         |
-| [guided-query-demo.ts](./guided-query-demo.ts)           | Document **guided_query** and the **`decision_trace`** payload.                                                  |
-| [library-embedding-demo.ts](./library-embedding-demo.ts) | Minimal **library embedding** (`resolveConfig`, `setPineconeClient`, `setupAllianceServer`).             |
+## Generic quickstart (start here)
 
-**Required env for live runs:** `PINECONE_API_KEY`. Optional: `PINECONE_INDEX_NAME` (default `rag-hybrid`), `PINECONE_RERANK_MODEL` (default `bge-reranker-v2-m3`).
+Run the MCP server against **your own** Pinecone indexes — no Alliance instance required.
 
-Run with `npm run build` then `npx tsx examples/<file>.ts` from the repo root (examples resolve the package via `dist/core` and `dist/alliance`).
+| Path | Description |
+| ---- | ----------- |
+| [quickstart/README.md](./quickstart/README.md) | Setup guide: create indexes, seed data, run MCP demo |
+| [quickstart/seed-data.ts](./quickstart/seed-data.ts) | Upsert sample records into dense + sparse indexes |
+| [quickstart/mcp-demo.ts](./quickstart/mcp-demo.ts) | `list_namespaces`, `count`, `query` via `setupCoreServer` |
+
+```bash
+cp examples/quickstart/.env.example examples/quickstart/.env
+# edit .env, then:
+npx tsx examples/quickstart/seed-data.ts
+npx tsx examples/quickstart/mcp-demo.ts
+```
+
+## Alliance / advanced
+
+| Path | Description |
+| ---- | ----------- |
+| [alliance/README.md](./alliance/README.md) | Full tool surface (`suggest_query_params`, `guided_query`, URL builtins) |
+| [alliance/suggest-flow-demo.ts](./alliance/suggest-flow-demo.ts) | Suggest-then-query gate sequence |
+| [alliance/guided-query-demo.ts](./alliance/guided-query-demo.ts) | `guided_query` orchestration |
+| [alliance/library-embedding-demo.ts](./alliance/library-embedding-demo.ts) | Library embedding with `setupAllianceServer` |
+| [alliance/custom-url-generator.ts](./alliance/custom-url-generator.ts) | Custom URL generator registration |
+
+## Shared utilities
+
+| File | Description |
+| ---- | ----------- |
+| [mcp-linked-transport.ts](./mcp-linked-transport.ts) | In-memory MCP transport pair for examples |
+
+**Build first:** `npm run build`, then `npx tsx examples/...` from the repo root. Examples resolve the package via `dist/core` and `dist/alliance` (see [tsconfig.json](./tsconfig.json) path aliases).

examples/alliance/README.md

@@ -0,0 +1,36 @@
+# Alliance / advanced examples
+
+These examples target the **full** MCP surface via `setupAllianceServer` from `@will-cppa/pinecone-read-only-mcp/alliance`:
+
+- `suggest_query_params` and the suggest-flow gate
+- `guided_query` with `decision_trace`
+- Built-in URL generators for `mailing` and `slack-Cpplang`
+
+They assume a Pinecone index you control with compatible data (not necessarily the C++ Alliance production index). To bootstrap a **neutral** index from scratch, start with [examples/quickstart/README.md](../quickstart/README.md).
+
+## Required environment
+
+| Variable | Required | Notes |
+| -------- | -------- | ----- |
+| `PINECONE_API_KEY` | Yes | For live runs |
+| `PINECONE_INDEX_NAME` | Yes | Your dense index name |
+
+Optional: `PINECONE_RERANK_MODEL`, `PINECONE_SPARSE_INDEX_NAME`, etc. See [docs/CONFIGURATION.md](../../docs/CONFIGURATION.md). CLI-only configs that set only `PINECONE_API_KEY` still use documented defaults (`rag-hybrid`, `bge-reranker-v2-m3`).
+
+## Files
+
+| File | Description |
+| ---- | ----------- |
+| [suggest-flow-demo.ts](./suggest-flow-demo.ts) | Manual **suggest_query_params → query** flow |
+| [guided-query-demo.ts](./guided-query-demo.ts) | **guided_query** and `decision_trace` |
+| [library-embedding-demo.ts](./library-embedding-demo.ts) | Programmatic **setupAllianceServer** wiring |
+| [custom-url-generator.ts](./custom-url-generator.ts) | Custom **URL generator** registration |
+| [demo-mock-pinecone-client.ts](./demo-mock-pinecone-client.ts) | Mock client with `mailing` namespace (no network) |
+
+Run from the repo root after `npm run build`:
+
+```bash
+npx tsx examples/alliance/suggest-flow-demo.ts
+```
+
+Shared in-process MCP transport helper: [../mcp-linked-transport.ts](../mcp-linked-transport.ts).

examples/quickstart/.env.example

@@ -0,0 +1,13 @@
+# Copy to examples/quickstart/.env (or repo root .env) before running seed-data / mcp-demo.
+
+PINECONE_API_KEY=your-pinecone-api-key-here
+PINECONE_INDEX_NAME=my-mcp-demo
+
+# Optional; default is {PINECONE_INDEX_NAME}-sparse
+# PINECONE_SPARSE_INDEX_NAME=my-mcp-demo-sparse
+
+# Required for core-only demos (no suggest_query_params tool on setupCoreServer)
+PINECONE_DISABLE_SUGGEST_FLOW=true
+
+# Optional rerank (omit if your Pinecone project does not support the model)
+# PINECONE_RERANK_MODEL=your-rerank-model-id

examples/quickstart/README.md

@@ -0,0 +1,93 @@
+# Quickstart — generic Pinecone (no Alliance instance)
+
+This guide walks through running the **core** MCP tools against **your own** Pinecone project and indexes. You do not need access to the C++ Alliance `rag-hybrid` index or Alliance-specific namespaces.
+
+## Prerequisites
+
+- [Pinecone](https://www.pinecone.io/) account (free tier is fine)
+- **Node.js 20.12+**
+- This repository built locally:
+
+```bash
+npm install
+npm run build
+```
+
+## 1. Create two integrated-embedding indexes
+
+The server performs **hybrid** search on a **dense** index and a **sparse** index named `{dense}-sparse` by default (see [`PineconeClient.getSparseIndexName()`](../../src/core/pinecone-client.ts)).
+
+In the [Pinecone console](https://app.pinecone.io/), create **two** indexes configured for **integrated embedding** (hosted model, text field mapped to `chunk_text`). Example names (use your own):
+
+| Index | Role | Example name |
+| ----- | ---- | -------------- |
+| Dense | Hybrid dense leg + `list_namespaces` metadata sampling | `my-mcp-demo` |
+| Sparse | Hybrid sparse leg + `keyword_search` | `my-mcp-demo-sparse` |
+
+Use the **same embedding model** (or compatible setup) on both indexes so hybrid merge behaves predictably. Pinecone’s [create index for model](https://docs.pinecone.io/guides/index-data/create-an-index#integrated-embedding) flow applies; the SDK example uses `fieldMap: { text: 'chunk_text' }`.
+
+> **Note:** Index creation is manual in this quickstart so the seed script stays portable. If your console labels differ, align record fields with `chunk_text`, `document_number`, and `title` as in `seed-data.ts`.
+
+## 2. Configure environment
+
+```bash
+cp examples/quickstart/.env.example examples/quickstart/.env
+```
+
+Edit `.env`:
+
+- `PINECONE_API_KEY` — your API key
+- `PINECONE_INDEX_NAME` — dense index name (e.g. `my-mcp-demo`)
+- `PINECONE_DISABLE_SUGGEST_FLOW=true` — required for `setupCoreServer` (no `suggest_query_params` tool)
+
+Optional: `PINECONE_SPARSE_INDEX_NAME` if the sparse index is not `{dense}-sparse`.
+
+## 3. Seed sample data
+
+Inserts 15 neutral programming snippets into namespace `quickstart` on **both** indexes:
+
+```bash
+npx tsx examples/quickstart/seed-data.ts
+```
+
+Dry run (no API calls):
+
+```bash
+npx tsx examples/quickstart/seed-data.ts --dry-run
+```
+
+Wait a few seconds for Pinecone to finish indexing.
+
+## 4. Run the MCP demo
+
+In-process demo using `setupCoreServer` and core tools `list_namespaces`, `count`, and `query`:
+
+```bash
+npx tsx examples/quickstart/mcp-demo.ts
+```
+
+## 5. Optional: CLI (stdio MCP)
+
+After seeding, you can run the published binary with the same env (still disable the suggest-flow gate for ad-hoc `query` without Alliance tools):
+
+```bash
+export PINECONE_API_KEY=...
+export PINECONE_INDEX_NAME=my-mcp-demo
+export PINECONE_DISABLE_SUGGEST_FLOW=true
+npx @will-cppa/pinecone-read-only-mcp
+```
+
+For the **full** Alliance tool surface (`suggest_query_params`, `guided_query`, built-in URL generators), see [examples/alliance/README.md](../alliance/README.md).
+
+## Troubleshooting
+
+| Symptom | Check |
+| ------- | ----- |
+| `FLOW_GATE` on `query` / `count` | Set `PINECONE_DISABLE_SUGGEST_FLOW=true` or use Alliance server + `suggest_query_params` |
+| Empty `list_namespaces` | Run `seed-data.ts`; confirm namespace `quickstart` and index names in `.env` |
+| Upsert / search errors | Indexes must support integrated embedding and `chunk_text` as the text field |
+| Hybrid partial results | Both dense and sparse indexes must contain the same record IDs in the same namespace |
+
+## Alliance-specific examples
+
+Advanced demos (suggest-flow, guided query, custom URL generators) live under [examples/alliance/](../alliance/).