feat: expose guided_query in core and document core/Alliance gate def…

[jonathanMLDev]

Summary

Exposes guided_query on the core entry point (setupCoreServer / package root), documents the intentional disableSuggestFlow split between core and Alliance, and adds cross-entry-point tests to lock in that behavior.

• Move guided_query to src/core/server/tools/, register in setupCoreServer, update CORE_SERVER_INSTRUCTIONS, docs/TOOLS.md, and CHANGELOG.md. Alliance keeps a thin re-export; duplicate registration removed from setupAllianceServer.
• Keep divergent defaults (core gate off, Alliance gate on). Add JSDoc on resolveConfig / resolveAllianceConfig and extend docs/CONFIGURATION.md and docs/MIGRATION.md with the decision and cross-entry warning.
• Add src/__tests__/cross-entry-point.test.ts for default config values, FLOW_GATE behavior, and core guided_query registration.

Test plan

• npm run ci (281 tests, typecheck, lint, format, coverage)
• Core guided_query works via guided-query-tool.test.ts (core-only mocks)
• Cross-entry tests: core gate off / Alliance gate on / FLOW_GATE on Alliance query without prior suggest

Related issues

• Close guided_query Exposure to Core Consumers #160
• Close Divergent disableSuggestFlow Defaults Alignment #159
• Close Cross-Entry-Point Integration Test: Core vs Alliance Default Behavior #156

---

Summary by CodeRabbit

Release Notes

• New Features
  • guided_query is now part of the core tool surface (available via core setup) for single-call retrieval.
• Documentation
  • Clarified suggest-flow gate (disableSuggestFlow) behavior and added migration/config guidance for switching entry points.
  • Updated tool surface and instruction text for core vs Alliance, including updated quickstart guidance.
• Tests
  • Added cross-entry-point tests verifying default gate behavior and expected FLOW_GATE errors when suggest parameters aren’t prepared first.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 9236e8af-f407-4b20-b1f5-b68b55455b88

📥 Commits

Reviewing files that changed from the base of the PR and between 435dcdd and 98dc5c2.

📒 Files selected for processing (17)

• CHANGELOG.md
• README.md
• docs/CONFIGURATION.md
• docs/MIGRATION.md
• docs/TOOLS.md
• src/__tests__/cross-entry-point.test.ts
• src/alliance/config.ts
• src/alliance/setup.ts
• src/alliance/tools/guided-query-tool.ts
• src/constants.test.ts
• src/constants.ts
• src/core/config.ts
• src/core/server/redaction.test.ts
• src/core/server/tools/guided-query-tool.context.test.ts
• src/core/server/tools/guided-query-tool.test.ts
• src/core/server/tools/guided-query-tool.ts
• src/core/setup.ts

---

📝 Walkthrough

Walkthrough

Moves the guided_query tool implementation from src/alliance/tools/ into src/core/server/tools/, registers it in setupCoreServer, and reduces the Alliance layer to a single re-export. Documents the intentional disableSuggestFlow default divergence between core and Alliance entry points in config comments, constants, and docs. Adds cross-entry-point integration tests covering both default behaviors and guided_query registration.

Changes

guided_query Promotion to Core

Layer / File(s)	Summary
Core guided_query implementation src/core/server/tools/guided-query-tool.ts	Adds registerGuidedQueryTool with resolveGuidedToolName helper, full input schema, namespace routing/caching, suggestion computation, count and query execution branches (fast/detailed/full modes), and catch-all error handling returning structured JSON responses.
Core setup wiring and Alliance re-export src/core/setup.ts, src/alliance/tools/guided-query-tool.ts, src/alliance/setup.ts	setupCoreServer imports and registers registerGuidedQueryTool; src/alliance/tools/guided-query-tool.ts is reduced to a single re-export from core; setupAllianceServer removes its redundant registerGuidedQueryTool call.
Configuration defaults documentation src/core/config.ts, src/alliance/config.ts	JSDoc in both config files documents the default disableSuggestFlow values per entry point, specifying which flows bypass the suggest_query_params gate and how to enforce the gate via environment variable.
User-facing documentation and constants src/constants.ts, CHANGELOG.md, README.md, docs/CONFIGURATION.md, docs/MIGRATION.md, docs/TOOLS.md	CORE_SERVER_INSTRUCTIONS is updated to lead with guided_query as the primary single-call quickstart; ALLIANCE_INSTRUCTIONS_APPENDIX adjusted; docs add a configuration warning, migration subsection on suggest-flow gate divergence, and updated core/Alliance tool-surface table; CHANGELOG entries document the tool availability and breaking instruction changes.
Cross-entry-point tests and test import updates src/__tests__/cross-entry-point.test.ts, src/core/server/redaction.test.ts, src/core/server/tools/guided-query-tool.test.ts, src/core/server/tools/guided-query-tool.context.test.ts, src/constants.test.ts	New integration test asserts default disableSuggestFlow values, FLOW_GATE enforcement for Alliance, gate-free query in core, and guided_query registration via setupCoreServer. Existing tests update import paths to match the new core module location.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• cppalliance/pinecone-read-only-mcp-typescript#142: Threaded ctx into guided_query result formatting and registered URL builtins on context — directly overlaps with the Alliance layer simplification in this PR.
• cppalliance/pinecone-read-only-mcp-typescript#132: Updated registerGuidedQueryTool to support ServerContext, the same wiring this PR modifies when moving guided_query to core.
• cppalliance/pinecone-read-only-mcp-typescript#125: Modified core-vs-Alliance contract points including CORE_SERVER_INSTRUCTIONS and the suggest-flow gate defaults that this PR extends and documents.

Suggested reviewers

• AuraMindNest
• wpak-ai

Poem

🐰 Hip-hop, the query hops to core,
No Alliance gate to implore!
guided_query leaps the fence,
disableSuggestFlow makes sense—
One tool to rule, no ceremony more! 🎉

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: exposing guided_query in core and documenting the gate behavior difference between core and Alliance entry points.
Linked Issues check	✅ Passed	All three linked issues are addressed: #160 (guided_query exposure in core), #159 (divergent disableSuggestFlow defaults documented), and #156 (cross-entry-point integration tests created).
Out of Scope Changes check	✅ Passed	All changes align with the three linked issues. Updates to constants, configuration, documentation, tools, and tests directly support the PR's stated objectives without unrelated additions.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

❌ Patch coverage is 87.01299% with 10 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (main@435dcdd). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
src/core/server/tools/guided-query-tool.ts	86.66%	10 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #167   +/-   ##
=======================================
  Coverage        ?   87.56%           
=======================================
  Files           ?       40           
  Lines           ?     1664           
  Branches        ?      554           
=======================================
  Hits            ?     1457           
  Misses          ?      207           
  Partials        ?        0           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[jonathanMLDev]

@coderabbitai full review again

[coderabbitai]

@jonathanMLDev Sure! I'll kick off a full review of the PR now.

✅ Action performed

Full review finished.

[jonathanMLDev]

@coderabbitai full review again. don't skip

[coderabbitai]

@jonathanMLDev Sure! Kicking off a thorough full review of the PR now — nothing will be skipped.

(ʕ •ᴥ•ʔ)∫

✅ Action performed

Full review finished.