feat: phase 1 export trim — remove experimental block builders from public API (#166)

Remove buildQueryExperimental and buildGuidedQueryExperimental from package root and /alliance re-exports. PineconeClient return types and Zod response schemas remain public. Add MIGRATION.md guidance, CHANGELOG entry, and export-surface regression test.

Co-authored-by: zho <jornathanm910923@gmail.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

Author: 3 people

CHANGELOG.md

@@ -24,6 +24,18 @@ Tagged releases are published to npm from GitHub Actions when a **GitHub Release
 - **Breaking (core):** `resolveConfig` requires a Pinecone index name and no longer applies Alliance index/rerank defaults. Removed exported `DEFAULT_INDEX_NAME` and `DEFAULT_RERANK_MODEL` from the package root. Rerank is opt-in when `PINECONE_RERANK_MODEL` / `rerankModel` is unset.
 - **Breaking (core):** `setupCoreServer` MCP `instructions` use `CORE_SERVER_INSTRUCTIONS` (no `guided_query` / `suggest_query_params`). `resolveConfig` defaults `disableSuggestFlow` to `true` so `query` / `count` / `query_documents` work without Alliance tools. Alliance CLI / `resolveAllianceConfig` unchanged: gate on by default, `ALLIANCE_SERVER_INSTRUCTIONS`.
 - **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).
+
+### 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.
+- Stable vs experimental response field taxonomy documented in [docs/TOOLS.md](docs/TOOLS.md) and [docs/deprecation-policy.md](docs/deprecation-policy.md#stable-vs-experimental-mcp-response-fields).
+- Formal deprecation policy ([docs/deprecation-policy.md](docs/deprecation-policy.md)) and breaking-change release notes template ([docs/templates/breaking-change-release-notes.md](docs/templates/breaking-change-release-notes.md)).
+
+### Removed
+
+- **Breaking (library):** `buildQueryExperimental` and `buildGuidedQueryExperimental` are no longer re-exported from `@will-cppa/pinecone-read-only-mcp` or `@will-cppa/pinecone-read-only-mcp/alliance`. They were internal helpers used to assemble the `experimental` block on `query` / `query_documents` / `guided_query` success payloads. The assembled fields and Zod schemas (`queryResponseSchema`, `QueryExperimental`, etc.) are unchanged — see [Unreleased stable vs experimental](docs/MIGRATION.md#unreleased-stable-vs-experimental-response-fields).
+- **No change:** `HybridQueryResult`, `HybridLegFailed`, and `KeywordIndexNamespacesResult` remain exported as the declared return types of public `PineconeClient` methods.
 
 ## [0.2.0] - 2026-05-29
 

docs/MIGRATION.md

@@ -69,6 +69,23 @@ 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: trimmed library exports
+
+**Who is affected:** Library embedders that imported `buildQueryExperimental` or `buildGuidedQueryExperimental` from `@will-cppa/pinecone-read-only-mcp` or `/alliance`.
+
+**Before:**
+
+```ts
+import { buildQueryExperimental } from '@will-cppa/pinecone-read-only-mcp';
+```
+
+**After:** These helpers are internal to the server. Options:
+
+1. Invoke the relevant MCP tool handler and parse the success payload with `queryResponseSchema` / `guidedQueryResponseSchema`.
+2. Build the `experimental` object yourself to match `QueryExperimental` if you control the response shape.
+
+`PineconeClient.query()` return types (`HybridQueryResult`, etc.) and all Zod response schemas remain on the public surface.
+
 ## Unreleased: `ServerContext` instance APIs (phase 1)
 
 **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.

src/core/__tests__/public-exports.test.ts

@@ -0,0 +1,9 @@
+import { describe, expect, it } from 'vitest';
+import * as core from '../index.js';
+
+describe('public export surface', () => {
+  it('does not export internal experimental block builders', () => {
+    expect('buildQueryExperimental' in core).toBe(false);
+    expect('buildGuidedQueryExperimental' in core).toBe(false);
+  });
+});

src/core/index.ts

@@ -26,8 +26,6 @@ export type { MetadataFilterValidationError } from './server/metadata-filter.js'
 export { toolErrorSchema } from './server/tool-error.js';
 export type { ToolError, ToolErrorCode } from './server/tool-error.js';
 export {
-  buildGuidedQueryExperimental,
-  buildQueryExperimental,
   countResponseSchema,
   generateUrlsResponseSchema,
   guidedQueryResponseSchema,