deprecate legacy module facades

CHANGELOG.md

@@ -26,6 +26,10 @@ Tagged releases are published to npm from GitHub Actions when a **GitHub Release
 - **Alliance CLI / `resolveAllianceConfig`:** When index or rerank env/CLI values are omitted, defaults remain `rag-hybrid` and `bge-reranker-v2-m3` (API-key-only MCP configs unchanged). See [examples/alliance/.env.example](examples/alliance/.env.example).
 - **Breaking (library):** Trimmed public re-exports — `buildQueryExperimental` and `buildGuidedQueryExperimental` removed from package root and `/alliance` entry. See [MIGRATION.md](docs/MIGRATION.md#unreleased-trimmed-library-exports).
 
+### Deprecated
+
+- Module-level singleton facades — use `ServerContext` instance methods via `createServer(config)` and `{ context: ctx }` at setup instead. Deprecated in the **next minor release** (see `[Unreleased]` until version is tagged); earliest removal **two minor releases later** per [deprecation-policy.md](docs/deprecation-policy.md#deprecation-window). Affected symbols: `getPineconeClient`, `setPineconeClient`, `clearPineconeClient`, `getServerConfig`, `setServerConfig`, `resetServerConfig`, `registerUrlGenerator`, `unregisterUrlGenerator`, `generateUrlForNamespace`, `hasUrlGenerator`, `resetUrlGenerationRegistry`, `markSuggested`, `requireSuggested`, `resetSuggestionFlow`, `getNamespacesWithCache`, `invalidateNamespacesCache`, `getDefaultServerContext`. See [MIGRATION.md § Legacy module-facade deprecations](docs/MIGRATION.md#unreleased-legacy-module-facade-deprecations) and [deprecation-policy.md](docs/deprecation-policy.md#active-deprecations-legacy-module-facades).
+
 ### Added
 
 - Zod schemas for all nine MCP tool success responses (`queryResponseSchema`, `guidedQueryResponseSchema`, etc.) exported from the package root for client-side validation. Success payloads are runtime-validated before return.

README.md

@@ -95,6 +95,14 @@ npm install
 npm run build
 ```
 
+## Stability
+
+This package ships as **`0.y.z`**. Under [semver §4](https://semver.org/spec/v2.0.0.html#spec-item-4), **minor versions may contain breaking changes** until `1.0.0`. Pin an exact version or use `~` (tilde) ranges — not `^` (caret) — until 1.0 to avoid absorbing breaking minors automatically.
+
+Breaking changes include: type signature changes, tool schema changes, default behavior changes, and removed exports.
+
+See [docs/deprecation-policy.md](docs/deprecation-policy.md) for the full deprecation window (minimum two minors before removal).
+
 ## 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.
@@ -129,7 +137,7 @@ Each **`ServerContext`** owns its own suggest-flow gate, namespaces cache, URL g
 
 Pass `config` at setup only when the context is not yet configured; after `createServer` + `setClient`, pass `{ context: ctx }` only.
 
-Legacy module getters (`setPineconeClient`, `registerUrlGenerator`, etc.) still delegate to a process-default context when you omit `context` at setup.
+Module-level singleton facades (`setPineconeClient`, `registerUrlGenerator`, `getDefaultServerContext`, etc.) are **deprecated** — they delegate to a process-default context when you omit `context` at setup. Prefer explicit `ServerContext` per [Library embedding](#library-embedding). See [docs/deprecation-policy.md](docs/deprecation-policy.md#active-deprecations-legacy-module-facades).
 
 ### Library embedding
 
@@ -145,21 +153,35 @@ ctx.setClient(new PineconeClient({ /* ... */ }));
 const server = await setupAllianceServer({ context: ctx });
 ```
 
-Use **`await using server = await setupAllianceServer({ context: ctx })`** for automatic teardown, or call **`ctx.teardown()`** when done. For legacy single-server flows that rely on the process-default context, **`teardownServer()`** resets that default before re-initializing.
+Use **`await using server = await setupAllianceServer({ context: ctx })`** for automatic teardown, or call **`ctx.teardown()`** when done.
 
 For the **generic bridge only**, see [examples/quickstart/mcp-demo.ts](examples/quickstart/mcp-demo.ts). For the **full Alliance surface**, see [examples/alliance/library-embedding-demo.ts](examples/alliance/library-embedding-demo.ts) and [docs/TOOLS.md](docs/TOOLS.md#suggest-flow-gate).
 
+#### Legacy (deprecated)
+
+Process-default / facade-based setup remains available during the deprecation window (removal per [deprecation-policy.md](docs/deprecation-policy.md) — two minors after the deprecation minor):
+
+```ts
+import { PineconeClient, setPineconeClient } from '@will-cppa/pinecone-read-only-mcp';
+import { resolveAllianceConfig, setupAllianceServer } from '@will-cppa/pinecone-read-only-mcp/alliance';
+
+setPineconeClient(new PineconeClient({ /* ... */ }));
+const server = await setupAllianceServer(resolveAllianceConfig({ apiKey: '...' }));
+// Call teardownServer() before re-initializing the process-default context.
+```
+
+Do not use this pattern for new code or multi-tenant embedding. See [docs/MIGRATION.md](docs/MIGRATION.md#unreleased-legacy-module-facade-deprecations).
+
 ### Custom URL generators
 
 Namespaces other than `mailing` and `slack-Cpplang` (or different URL rules for any namespace) can use programmatic registration — no fork required.
 
-Import `registerUrlGenerator` and types `UrlGeneratorFn` / `UrlGenerationResult` from `@will-cppa/pinecone-read-only-mcp`. Register **additional** namespaces before tools that emit URLs run. Built-in `mailing` / `slack-Cpplang` generators are installed by `setupAllianceServer` (not by `setupCoreServer`).
+Register **additional** namespaces on your `ServerContext` before tools that emit URLs run. Built-in `mailing` / `slack-Cpplang` generators are installed by `setupAllianceServer` (not by `setupCoreServer`).
 
 ```ts
 import {
   createServer,
   PineconeClient,
-  registerUrlGenerator,
   type UrlGenerationResult,
   type UrlGeneratorFn,
 } from '@will-cppa/pinecone-read-only-mcp';
@@ -184,7 +206,7 @@ const myDocs: UrlGeneratorFn = (metadata): UrlGenerationResult => {
     : { url: null, method: 'unavailable', reason: 'doc_id missing' };
 };
 
-registerUrlGenerator('product-docs', myDocs);
+ctx.registerUrlGenerator('product-docs', myDocs);
 ```
 
 A fuller embedding sample lives in [examples/alliance/custom-url-generator.ts](examples/alliance/custom-url-generator.ts).

docs/MIGRATION.md

@@ -69,6 +69,102 @@ When no experimental fields apply, the `experimental` key is **omitted** (not an
 
 **Promotion:** Moving a field from `experimental` to stable requires CHANGELOG, TOOLS.md, and schema updates per [deprecation-policy.md § Stable vs experimental](./deprecation-policy.md#stable-vs-experimental-mcp-response-fields).
 
+## Unreleased: Legacy module-facade deprecations
+
+**Rationale:** Module-level singleton facades (`setPineconeClient`, `registerUrlGenerator`, `getDefaultServerContext`, etc.) delegate to a process-global `ServerContext`. They complicate multi-tenant embedding and hide initialization order. They are marked `@deprecated` in JSDoc; earliest removal is **two minor releases after** the deprecation minor (see [deprecation-policy.md § Deprecation window](./deprecation-policy.md#deprecation-window)).
+
+**Who is affected:** Library embedders importing facade functions from `@will-cppa/pinecone-read-only-mcp` or `/alliance`.
+
+**Recommended pattern:** `createServer(config)` → `ctx.setClient(...)` → `setupCoreServer({ context: ctx })` or `setupAllianceServer({ context: ctx })`.
+
+### Client
+
+**Before (deprecated):**
+
+```ts
+import { PineconeClient, setPineconeClient } from '@will-cppa/pinecone-read-only-mcp';
+
+setPineconeClient(new PineconeClient({ /* ... */ }));
+```
+
+**After:**
+
+```ts
+import { createServer, PineconeClient, resolveConfig } from '@will-cppa/pinecone-read-only-mcp';
+
+const config = resolveConfig({ apiKey: '...', indexName: 'my-index' });
+const ctx = createServer(config);
+ctx.setClient(new PineconeClient({ /* ... */ }));
+```
+
+### Config
+
+**Before (deprecated):** `getServerConfig()` / `setServerConfig(config)` / `resetServerConfig()`.
+
+**After:** `ctx.getConfig()` / `ctx.setConfig(config)` / `ctx.teardown()`.
+
+### URL registry
+
+**Before (deprecated):**
+
+```ts
+import { registerUrlGenerator } from '@will-cppa/pinecone-read-only-mcp';
+
+registerUrlGenerator('my-ns', myGenerator);
+```
+
+**After:**
+
+```ts
+ctx.registerUrlGenerator('my-ns', myGenerator);
+```
+
+Same for `unregisterUrlGenerator`, `generateUrlForNamespace`, `hasUrlGenerator`, and `resetUrlGenerationRegistry` → `ctx.unregisterUrlGenerator`, `ctx.generateUrlForNamespace`, `ctx.hasUrlGenerator`, `ctx.resetUrlGenerators`.
+
+### Suggest-flow gate
+
+**Before (deprecated):** `markSuggested`, `requireSuggested`, `resetSuggestionFlow`.
+
+**After:** `ctx.markSuggested`, `ctx.requireSuggested`, `ctx.resetSuggestionFlow`.
+
+### Namespaces cache
+
+**Before (deprecated):** `getNamespacesWithCache()`, `invalidateNamespacesCache()`.
+
+**After:** `ctx.getNamespacesWithCache()`, `ctx.invalidateNamespacesCache()`.
+
+### Process-default context
+
+**Before (deprecated):**
+
+```ts
+import { getDefaultServerContext, setupCoreServer } from '@will-cppa/pinecone-read-only-mcp';
+
+await setupCoreServer(config); // uses process default
+const ctx = getDefaultServerContext();
+```
+
+**After:**
+
+```ts
+const ctx = createServer(config);
+ctx.setClient(client);
+await setupCoreServer({ context: ctx });
+```
+
+### Teardown
+
+**Before:** `teardownServer()` resets the process-default context.
+
+**After:** `await ctx.teardown()` or `await using server = await setupAllianceServer({ context: ctx })` for automatic cleanup. `teardownServer()` remains available during the deprecation window for legacy single-server flows; prefer per-context lifecycle for new code.
+
+### CLI and tests
+
+- **CLI:** unchanged — the binary uses internal setup paths.
+- **Test fakes:** pass a dedicated `ServerContext` via `createIsolatedContext` or `createServer` + `{ context: ctx }` at setup instead of mutating process globals.
+
+See [deprecation-policy.md § Active deprecations](./deprecation-policy.md#active-deprecations-legacy-module-facades) for the full inventory.
+
 ## Unreleased: trimmed library exports
 
 **Who is affected:** Library embedders that imported `buildQueryExperimental` or `buildGuidedQueryExperimental` from `@will-cppa/pinecone-read-only-mcp` or `/alliance`.
@@ -86,11 +182,11 @@ import { buildQueryExperimental } from '@will-cppa/pinecone-read-only-mcp';
 
 `PineconeClient.query()` return types (`HybridQueryResult`, etc.) and all Zod response schemas remain on the public surface.
 
-## Unreleased: `ServerContext` instance APIs (phase 1)
+## Unreleased: `ServerContext` instance APIs (initial)
 
-**Rationale:** Process-global singletons (Pinecone client slot, config, URL registry, suggest-flow gate, namespaces cache) complicate testing and multi-tenant embedding. Phase 1 introduces an opt-in **`ServerContext`** without removing legacy getters.
+**Rationale:** Process-global singletons (Pinecone client slot, config, URL registry, suggest-flow gate, namespaces cache) complicate testing and multi-tenant embedding. The initial milestone introduces an opt-in **`ServerContext`**; legacy module facades are deprecated (see [Legacy module-facade deprecations](#unreleased-legacy-module-facade-deprecations)).
 
-**Now (0.2.x — unchanged for existing embedders):**
+**Deprecated (migrate before removal):**
 
 ```ts
 import { PineconeClient, setPineconeClient } from '@will-cppa/pinecone-read-only-mcp';
@@ -108,9 +204,9 @@ setPineconeClient(
 const server = await setupAllianceServer(config);
 ```
 
-Module-level helpers (`getPineconeClient`, `registerUrlGenerator`, `requireSuggested`, etc.) continue to work; they delegate to a process-default context.
+Module-level helpers (`getPineconeClient`, `registerUrlGenerator`, `requireSuggested`, etc.) still work during the deprecation window; they delegate to a process-default context.
 
-**New (recommended — phase 4 explicit context at setup):** For one-shot client injection at construction, see [ServerContext composition API](#unreleased-servercontext-composition-api) (`createServer(config, { client })` or `createIsolatedContext`).
+**Recommended (instance-first):** For one-shot client injection at construction, see [ServerContext composition API](#unreleased-servercontext-composition-api) (`createServer(config, { client })` or `createIsolatedContext`).
 
 ```ts
 import { createServer, PineconeClient } from '@will-cppa/pinecone-read-only-mcp';
@@ -178,7 +274,7 @@ import { registerQueryTool, registerCountTool, registerListNamespacesTool } from
 registerQueryTool(server, ctx);
 ```
 
-**Later (future minors/major):** Legacy module getters will be marked `### Deprecated` per [deprecation-policy.md](./deprecation-policy.md).
+**Later:** Legacy module getters will be removed at the earliest removal minor per [deprecation-policy.md](./deprecation-policy.md).
 
 See also [deprecation-policy.md § Future instance APIs](./deprecation-policy.md#future-instance-apis-servercontext).
 
@@ -222,7 +318,7 @@ await setupCoreServer({ context: ctx });
 
 Suggest-flow gate settings (`disableSuggestFlow`, `cacheTtlMs`) remain on `ServerConfig`, not on composition.
 
-See also [ServerContext instance APIs (phase 1)](#unreleased-servercontext-instance-apis-phase-1) for legacy vs explicit-context setup.
+See also [ServerContext instance APIs (initial)](#unreleased-servercontext-instance-apis-initial) for legacy vs explicit-context setup.
 
 ---