docs: investigate provider-native reasoning controls

[smolpaws]

Summary

• document provider/model-specific reasoning and thinking controls for OpenAI, Anthropic, Gemini, and LiteLLM/OpenAI-compatible routes
• record official-doc quotes plus live OpenAI GPT-5.6 and Gemini probe evidence
• propose a TypeScript capability/discriminated-profile API and migration plan away from the generic reasoningEffort field
• link the new design note from the docs index and transpile plan

Verification

• npm test

Notes

• This PR is docs/design only; request-builder and profile schema changes are intentionally left for follow-up implementation PRs.
• Anthropic and LiteLLM live probes are documented as remaining gaps because credentials/base URLs were unavailable in this environment.

This PR was created by an AI agent (OpenHands) on behalf of Engel Nyst.

Summary by CodeRabbit

• Documentation
  • Added a design note describing provider- and model-specific reasoning/thinking capabilities.
  • Documented proposed capability discovery, reasoning configuration, validation/normalization, and migration approach.
  • Added the reasoning capabilities document to the current documentation index.
  • Updated the transpilation roadmap with follow-up work to replace the legacy cross-provider reasoning settings abstraction.

[coderabbitai]

Warning

Review limit reached

@enyst, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 56 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: c3a2bc80-a4cf-4b85-b313-8e1d867d5acd

📥 Commits

Reviewing files that changed from the base of the PR and between a308641 and 20f66cd.

📒 Files selected for processing (1)

• docs/REASONING_CAPABILITIES.md

Walkthrough

The PR adds a design note documenting provider-specific reasoning controls, source evidence, live probe results, capability differences, and known gaps. It proposes capability discovery, provider-specific reasoning types, serializable configuration, upstream provider resolution, validation, normalization, and migration APIs. Repository documentation and the transpilation roadmap now reference this design note. No runtime implementation is added.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly reflects the doc/design investigation into provider-native reasoning controls.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

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.}

[gemini-code-assist]

Code Review

This pull request introduces a comprehensive design document, REASONING_CAPABILITIES.md, which details an investigation into provider-specific reasoning and thinking controls (OpenAI, Anthropic, Gemini, LiteLLM) and proposes a new TypeScript API shape to replace the current cross-provider reasoningEffort abstraction. The documentation updates also include linking this new document in the main README.md and integrating it into the TRANSPILE_PLAN.md. Feedback on the proposed API design highlights an inconsistency in the discriminator property names and literal values for Anthropic configurations between the ReasoningCapabilities and LLMReasoningConfig types, suggesting alignment to simplify mapping and validation logic.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[coderabbitai]

Actionable comments posted: 3

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: bd5a0b31-9dc9-437d-bb85-65f4f65c9784

📥 Commits

Reviewing files that changed from the base of the PR and between 14887f2 and 88fa190.

📒 Files selected for processing (3)

• docs/README.md
• docs/REASONING_CAPABILITIES.md
• docs/TRANSPILE_PLAN.md