Docs/v0.3.0 onboarding and ownership (#184)

* docs: sync README to v0.3.0 and add CODEOWNERS + CONTRIBUTING

Update consumer-facing install and MCP config pins to match package.json
0.3.0, add root CONTRIBUTING.md for GitHub onboarding, and route reviews
via CODEOWNERS for critical paths.

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

* docs: sync README to v0.3.0 and add CODEOWNERS + CONTRIBUTING

* docs: remove docs/CONTRIBUTING.md stub; link to root guide only

Single CONTRIBUTING.md at repo root; update docs index and deprecation-policy links.

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

---------

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

Author: 3 people

.github/CODEOWNERS

@@ -0,0 +1,8 @@
+# Default owners
+* @wpak-ai @jonathanMLDev
+
+# Critical paths (explicit for review routing)
+/src/ @wpak-ai @jonathanMLDev
+/src/alliance/ @wpak-ai @jonathanMLDev
+/package.json @wpak-ai @jonathanMLDev
+/.github/workflows/ @wpak-ai @jonathanMLDev

CHANGELOG.md

@@ -137,7 +137,8 @@ details. Newer shipped changes are recorded in this changelog by version.
 - Environment variable support
 - Full documentation and examples
 
-[Unreleased]: https://github.com/cppalliance/pinecone-read-only-mcp-typescript/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/cppalliance/pinecone-read-only-mcp-typescript/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/cppalliance/pinecone-read-only-mcp-typescript/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/cppalliance/pinecone-read-only-mcp-typescript/compare/v0.1.6...v0.2.0
 [0.1.6]: https://github.com/cppalliance/pinecone-read-only-mcp-typescript/compare/v0.1.1...v0.1.6
 [0.1.1]: https://github.com/cppalliance/pinecone-read-only-mcp-typescript/compare/v0.1.0...v0.1.1

CONTRIBUTING.md

@@ -0,0 +1,76 @@
+# Contributing
+
+Thank you for contributing to `@will-cppa/pinecone-read-only-mcp`. This guide covers local setup, architecture, and pull-request expectations.
+
+## Prerequisites
+
+- **Node.js ≥ 20.12** (see `engines` in `package.json` — Vitest 4 / coverage require it).
+- **npm** (lockfile is `package-lock.json`).
+- **Pinecone API key** (optional for unit tests; required for live integration-style runs and examples that call Pinecone).
+
+## Dev setup
+
+```bash
+git clone https://github.com/cppalliance/pinecone-read-only-mcp-typescript.git
+cd pinecone-read-only-mcp-typescript
+npm ci
+npm run build
+npm test
+```
+
+For the full local gate before pushing:
+
+```bash
+npm run ci
+```
+
+| Script | Purpose |
+| ------ | ------- |
+| `npm run build` | Clean `dist/` and `tsc` compile |
+| `npm run typecheck` | `tsc --noEmit` |
+| `npm run lint` | ESLint on `src/` |
+| `npm run lint:fix` | ESLint with `--fix` |
+| `npm run format` | Prettier write (`src/**/*.ts`, config JSON) |
+| `npm run format:check` | Prettier check |
+| `npm test` | Vitest once |
+| `npm run test:coverage` | Vitest + coverage thresholds (`vitest.config.ts`) |
+| `npm run ci` | Full local gate (typecheck, lint, format, build, coverage) |
+| `npm run docs:link-check` | Validate markdown links in README, CHANGELOG, and `docs/` |
+
+## Architecture overview
+
+The codebase is split into two layers. **`src/core/`** is the generic MCP–Pinecone bridge: `PineconeClient`, `resolveConfig`, `setupCoreServer`, and eight MCP tools including `guided_query`. Import from `@will-cppa/pinecone-read-only-mcp` (package root). **`src/alliance/`** is the C++ Alliance app layer: `suggest_query_params`, Boost/Slack URL builtins, and `setupAllianceServer` / `resolveAllianceConfig`. Import from `@will-cppa/pinecone-read-only-mcp/alliance` for the full 14-tool surface (CLI parity).
+
+Each deployment uses a **`ServerContext`** instance that owns config, the Pinecone client, namespaces cache, URL generator registry, and the suggest-flow gate. Prefer the instance-first pattern: `createServer(config)` → `ctx.setClient(...)` → `setupCoreServer({ context: ctx })` or `setupAllianceServer({ context: ctx })`. Module-level singleton facades (`setPineconeClient`, `getDefaultServerContext`, etc.) are deprecated since 0.3.0.
+
+The **suggest-flow gate** requires `suggest_query_params` before `query`, `count`, or `query_documents` for a namespace (unless disabled). Alliance defaults keep the gate **on**; core `resolveConfig` defaults `disableSuggestFlow` to **true** so generic embedders can query without Alliance tools. Tool handlers validate inputs with Zod and return structured **`ToolError`** JSON on failure — one of the project's quality standards for MCP consumers.
+
+Deep reference: [docs/CONFIGURATION.md](docs/CONFIGURATION.md), [docs/TOOLS.md](docs/TOOLS.md), [README.md](README.md#architecture).
+
+## PR conventions
+
+- **Branch naming:** `feature/…`, `docs/…`, `bugfix/…`, or `design/…` (short, descriptive slug).
+- Run **`npm run ci`** before pushing; CI must pass on the PR.
+- Keep changes focused; update **`CHANGELOG.md` `[Unreleased]`** for user-visible behavior.
+- Use the [pull request template](.github/PULL_REQUEST_TEMPLATE.md).
+- Documentation changes: run `npm run docs:link-check` if you touch many relative links.
+- PRs to `main` should receive review from a [CODEOWNERS](.github/CODEOWNERS) maintainer once branch protection is enabled.
+
+### Deprecations and breaking changes
+
+Follow [docs/deprecation-policy.md](docs/deprecation-policy.md). Deprecate with CHANGELOG + MIGRATION entries; use labeled `**Breaking (MCP):**` bullets for breaking releases while `0.y.z`.
+
+### Response field stability
+
+When changing MCP tool success shapes, put new fields under **`experimental`** unless promoted; update Zod schemas in `src/core/server/response-schemas.ts` and [docs/TOOLS.md](docs/TOOLS.md). See [docs/deprecation-policy.md § Stable vs experimental](docs/deprecation-policy.md#stable-vs-experimental-mcp-response-fields).
+
+## Code style
+
+- **TypeScript strict** (`strict`, `noUncheckedIndexedAccess`, etc.) — match surrounding code.
+- **ESLint** and **Prettier** — `npm run lint`, `npm run format:check` (configs at repo root).
+- **Zod** at MCP tool boundaries; explicit types on exported APIs.
+- **No `process.env` reads** in feature code outside `resolveConfig` / CLI — thread `ServerConfig`.
+- Tool errors: `jsonErrorResponse` with `ToolError` from `tool-error.ts`.
+- Tests beside sources as `*.test.ts`; use Vitest.
+
+Additional guides live under [`docs/`](docs/README.md) (TOOLS, CONFIGURATION, MIGRATION, CI_CD).

README.md

@@ -7,7 +7,11 @@
 
 A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that implements the MCP specification via `@modelcontextprotocol/sdk` v1.25+ and provides semantic search over Pinecone vector databases using hybrid search (dense + sparse) with reranking.
 
-**Current version: 0.2.0** (npm `latest` after publish). Pin `@0.2.0` in install and MCP config for reproducible upgrades.
+Current version: 0.3.0 (npm `latest` after publish). Pin `@0.3.0` in install and MCP config for reproducible upgrades.
+
+## Upgrading to 0.3.0
+
+Version **0.3.0** includes breaking MCP and library changes: experimental response fields nested under `experimental`, branded `CoreServerConfig` / `AllianceServerConfig`, legacy module-facade deprecations, and core `resolveConfig` requiring an index name with suggest-flow off by default. See [docs/MIGRATION.md](docs/MIGRATION.md) for before/after examples and the [CHANGELOG](CHANGELOG.md#030---2026-06-23) **Changed** section for the full list.
 
 ## Upgrading from 0.1.x
 
@@ -29,7 +33,7 @@ While the package is **`0.y.z`**, minor releases may include breaking changes ([
 | [docs/deprecation-policy.md](docs/deprecation-policy.md) | Release & deprecation policy           |
 | [docs/CI_CD.md](docs/CI_CD.md)                           | GitHub Actions, SBOM, Docker, releases |
 | [docs/RELEASING.md](docs/RELEASING.md)                   | npm publish via GitHub Releases        |
-| [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md)             | How to contribute                      |
+| [CONTRIBUTING.md](CONTRIBUTING.md)                       | How to contribute                      |
 | [docs/SECURITY.md](docs/SECURITY.md)                     | Vulnerability reporting                |
 
 ## Error responses
@@ -65,25 +69,25 @@ For successful `query`, `query_documents`, and `guided_query` payloads, **rerank
 ### As a Package
 
 ```bash
-npm install @will-cppa/pinecone-read-only-mcp@0.2.0
+npm install @will-cppa/pinecone-read-only-mcp@0.3.0
 ```
 
 Or using yarn:
 
 ```bash
-yarn add @will-cppa/pinecone-read-only-mcp@0.2.0
+yarn add @will-cppa/pinecone-read-only-mcp@0.3.0
 ```
 
 Or using pnpm:
 
 ```bash
-pnpm add @will-cppa/pinecone-read-only-mcp@0.2.0
+pnpm add @will-cppa/pinecone-read-only-mcp@0.3.0
 ```
 
 ### Global Installation
 
 ```bash
-npm install -g @will-cppa/pinecone-read-only-mcp@0.2.0
+npm install -g @will-cppa/pinecone-read-only-mcp@0.3.0
 ```
 
 ### From Source
@@ -249,7 +253,7 @@ Add to your `claude_desktop_config.json`:
   "mcpServers": {
     "pinecone-search": {
       "command": "npx",
-      "args": ["-y", "@will-cppa/pinecone-read-only-mcp@0.2.0"],
+      "args": ["-y", "@will-cppa/pinecone-read-only-mcp@0.3.0"],
       "env": {
         "PINECONE_API_KEY": "your-api-key-here",
         "PINECONE_INDEX_NAME": "your-index-name",
@@ -269,7 +273,7 @@ Or with explicit options:
       "command": "npx",
       "args": [
         "-y",
-        "@will-cppa/pinecone-read-only-mcp@0.2.0",
+        "@will-cppa/pinecone-read-only-mcp@0.3.0",
         "--api-key",
         "your-api-key-here",
         "--index-name",
@@ -302,7 +306,7 @@ For a global installation:
 Run the server using npx (no installation required):
 
 ```bash
-npx @will-cppa/pinecone-read-only-mcp@0.2.0 --api-key YOUR_API_KEY --index-name YOUR_INDEX
+npx @will-cppa/pinecone-read-only-mcp@0.3.0 --api-key YOUR_API_KEY --index-name YOUR_INDEX
 ```
 
 Or if installed globally:
@@ -342,10 +346,10 @@ Run `pinecone-read-only-mcp --help` for the full option list.
 
 ```bash
 # install
-npm i @will-cppa/pinecone-read-only-mcp@0.2.0
+npm i @will-cppa/pinecone-read-only-mcp@0.3.0
 
 # run
-npx @will-cppa/pinecone-read-only-mcp@0.2.0 --api-key YOUR_API_KEY
+npx @will-cppa/pinecone-read-only-mcp@0.3.0 --api-key YOUR_API_KEY
 ```
 
 ### Deploy with Docker
@@ -751,14 +755,7 @@ npm run dev -- --api-key YOUR_API_KEY
 
 ### Contribution Guidelines
 
-1. Fork the repository
-2. Create a feature branch: `git checkout -b feature-name`
-3. Make your changes and add tests
-4. Ensure all tests pass: `npm test`
-5. Ensure code quality checks pass: `npm run lint && npm run format:check && npm run typecheck`
-6. Commit your changes: `git commit -am 'Add some feature'`
-7. Push to the branch: `git push origin feature-name`
-8. Submit a pull request
+See [CONTRIBUTING.md](CONTRIBUTING.md) for prerequisites, dev setup, architecture overview, PR conventions, and code style. Run `npm run ci` before opening a pull request.
 
 ## Dependencies
 

docs/CONTRIBUTING.md

@@ -7,7 +7,7 @@ Guides for operators, MCP client authors, and library embedders.
 | [TOOLS.md](./TOOLS.md) | All MCP tools, parameters, success/error shapes, suggest-flow |
 | [CONFIGURATION.md](./CONFIGURATION.md) | Environment variables, CLI flags, `resolveConfig`, precedence |
 | [SECURITY.md](./SECURITY.md) | API keys, log redaction, Docker hardening, reporting issues |
-| [CONTRIBUTING.md](./CONTRIBUTING.md) | Local dev, tests, lint/format, PR expectations |
+| [CONTRIBUTING.md](../CONTRIBUTING.md) | Local dev, tests, lint/format, PR expectations |
 | [CI_CD.md](./CI_CD.md) | GitHub Actions, CodeQL, SBOM, Codecov, releases |
 | [FAQ.md](./FAQ.md) | Common questions |
 | [MIGRATION.md](./MIGRATION.md) | Breaking changes and upgrade paths |

docs/README.md

@@ -10,7 +10,7 @@ For step-by-step upgrades, see [MIGRATION.md](./MIGRATION.md). For publish mecha
 
 ## Semantic versioning while `0.y.z`
 
-This package currently ships as **`0.y.z`**. Under [Semantic Versioning §4](https://semver.org/spec/v2.0.0.html#spec-item-4), **minor releases may include breaking changes** until the first `1.0.0` release. Consumers should **pin an exact version** (for example `@will-cppa/pinecone-read-only-mcp@0.2.0`) in `package.json`, MCP server config, and Docker tags.
+This package currently ships as **`0.y.z`**. Under [Semantic Versioning §4](https://semver.org/spec/v2.0.0.html#spec-item-4), **minor releases may include breaking changes** until the first `1.0.0` release. Consumers should **pin an exact version** (for example `@will-cppa/pinecone-read-only-mcp@0.3.0`) in `package.json`, MCP server config, and Docker tags.
 
 After **`1.0.0`**, this project intends to follow standard semver: breaking changes land only in **major** releases, and the deprecation window below becomes **binding** for removals that were previously announced as deprecated.
 
@@ -142,7 +142,7 @@ Each breaking bullet should state:
 - `old_name` on … — use `new_name` instead; removal targeted in **0.4.0** (deprecated **0.2.0**). See [MIGRATION.md](./MIGRATION.md#anchor).
 ```
 
-Contributors: see [CONTRIBUTING.md](./CONTRIBUTING.md) for PR expectations.
+Contributors: see [CONTRIBUTING.md](../CONTRIBUTING.md) for PR expectations.
 
 ## Release hygiene
 
@@ -156,6 +156,6 @@ Contributors: see [CONTRIBUTING.md](./CONTRIBUTING.md) for PR expectations.
 | -------- | ---- |
 | [MIGRATION.md](./MIGRATION.md) | Per-version upgrade how-to |
 | [CHANGELOG.md](../CHANGELOG.md) | Authoritative change list |
-| [CONTRIBUTING.md](./CONTRIBUTING.md) | PR and CHANGELOG expectations |
+| [CONTRIBUTING.md](../CONTRIBUTING.md) | PR and CHANGELOG expectations |
 | [RELEASING.md](./RELEASING.md) | npm publish via GitHub Releases |
 | [templates/breaking-change-release-notes.md](./templates/breaking-change-release-notes.md) | GitHub Release body template |