System improvements

[ngoiyaeric]

Next.js 16 & Gemini 3.1: Strategic Advancement Report (May 2026)

Executive Summary

This report details the latest advancements in the Next.js 16 framework and the Gemini 3.1 Pro AI model. Based on the current QCX platform architecture (Next.js 15.3, React 19.1, Gemini 3.1 Pro Preview), several high-impact upgrade opportunities have been identified to enhance performance, reasoning capabilities, and agentic workflows.

---

1. Next.js 16: The Routing & Performance Overhaul

Next.js 16 (released May 2026) introduces a fundamental shift in how applications handle navigation and data prefetching [1].

Key Advancements

Feature	Description	Impact for QCX
Routing Overhaul	Complete rewrite of the navigation system for leaner, faster transitions.	Faster map-to-chat transitions and smoother UI.
Layout Deduplication	Shared layouts are downloaded only once during prefetching across multiple URLs.	Reduced bandwidth and faster multi-page navigation.
Incremental Prefetching	Only fetches missing cache segments instead of entire pages.	Significant reduction in total transfer size for complex dashboards.
Stable Turbopack	Turbopack is now the default for both dev and build without experimental flags.	Faster development cycles and optimized production builds.
React 19.2 Support	Native support for View Transitions, useEffectEvent, and Activity.	Enhanced animation capabilities for the geospatial UI.
React Compiler	Automatic memoization of components for performance gains.	Eliminates manual useMemo/useCallback overhead in complex components.

Upgrade Recommendations for QCX

1. Migrate to Next.js 16: Update package.json to next@16.x.
2. Leverage Cache Components: Replace experimental.dynamicIO with the new cacheComponents configuration for granular server-side caching.
3. Adopt React Compiler: Enable the React Compiler to automatically optimize the heavy geospatial UI components.
4. Rename Middleware: Rename middleware.ts to proxy.ts to align with the new Node.js runtime standards in v16.

---

2. Gemini 3.1 Pro: Reasoning & Agentic Excellence

Gemini 3.1 Pro (released February 2026) is a reasoning-optimized upgrade that excels in complex, multi-step task execution [2].

Key Advancements

Capability	Gemini 3.1 Pro Performance	Strategic Advantage
Abstract Reasoning	77.1% on ARC-AGI-2 (leads all models) [2].	Superior handling of complex geospatial logic and land classification.
Agentic Workflows	33.5% on APEX-Agents (nearly 2x Gemini 3 Pro) [2].	Highly reliable multi-step tool use for the researcher and taskManager.
Custom Tools Endpoint	New gemini-3.1-pro-preview-customtools endpoint.	Optimized specifically for bash, terminal, and custom API tool calls.
Expert Science	94.3% on GPQA Diamond [2].	Enhanced accuracy for technical geospatial and environmental analysis.
Context Caching	Native support for long-context caching.	Drastically reduces costs for long-running chat sessions with large histories.

Integration Recommendations for QCX

1. Switch to Custom Tools Endpoint: For the researcher agent, use the gemini-3.1-pro-preview-customtools endpoint to improve tool-calling reliability.
2. Implement Context Caching: Use context caching for the resolutionSearch agent when analyzing large satellite imagery datasets or long conversation histories.
3. Reasoning-First Prompts: Update system prompts to leverage the improved chain-of-thought reasoning for complex land feature predictions.
4. Batch API Usage: Utilize the new Batch API for non-real-time geospatial analysis to reduce costs by up to 50%.

---

3. QCX Platform: Strategic Update Roadmap

Phase 1: Core Infrastructure (Immediate)

• Upgrade to Next.js 16.2+: Gain the routing overhaul and stable Turbopack benefits.
• Update React to 19.2: Enable View Transitions for the map interface.
• Enable React Compiler: Optimize the Copilot and SearchRelated components automatically.

Phase 2: AI Intelligence (Short-term)

• Transition to customtools Endpoint: Improve the reliability of the geospatialQueryTool.
• Implement Context Caching: Optimize token usage for the researcher agent.
• Refine Reasoning Prompts: Update the resolutionSearch system prompt to utilize the 77.1% ARC-AGI-2 reasoning capabilities.

Phase 3: Performance & UX (Mid-term)

• Adopt Incremental Prefetching: Optimize the loading of the search results page.
• Implement View Transitions: Create seamless transitions between the map view and the chat panel.
• Leverage Build Adapters: Optimize the standalone Docker build process for faster deployments.

---

Conclusion

The combination of Next.js 16's routing efficiency and Gemini 3.1 Pro's reasoning power provides a significant competitive advantage for the QCX platform. By following this roadmap, the platform will achieve superior UI responsiveness and industry-leading AI analysis accuracy.

References

[1] Upgrading: Version 16 | Next.js
[2] Gemini 3.1 Pro: #1 Reasoning AI Benchmarks & API Guide | Google DeepMind

[ngoiyaeric]

@coderabbitai plan

[coderabbitai]

Coding Plan

Summary

• Perform a coordinated upgrade of Next.js to v16 and React to 19.2, including fixing the outdated eslint-config-next version and renaming middleware.ts to proxy.ts per v16 conventions
• Enable React Compiler to automatically optimize the heavily memoized copilot and search-related components, as well as the unmemoized resolution-carousel
• Extend the existing getModel() function with a usesTools parameter to route the researcher agent to the gemini-3.1-pro-preview-customtools endpoint while other agents use the standard endpoint
• Implement application-level context caching to reduce token costs for long conversations, and update system prompts in researcher and resolution-search agents to leverage Gemini 3.1 Pro's enhanced reasoning capabilities

Design Choices

Design Choice 1: Context Caching Implementation Approach

Options Considered:

1. Use Google's native @google/generative-ai SDK directly for context caching, bypassing the Vercel AI SDK for cached calls
2. Implement an application-level caching layer that stores and reuses conversation context, reducing tokens sent per request

Chosen Option: 2

Rationale: Application-level caching is more consistent with the existing Vercel AI SDK architecture and avoids maintaining two parallel SDK integrations for the same provider.

Design Choice 2: Customtools Endpoint Scope

Options Considered:

1. Create separate model functions for tool-using vs non-tool-using contexts
2. Extend getModel() with an optional parameter to indicate tool usage

Chosen Option: 2

Rationale: Extending getModel() with a usesTools parameter maintains the single source of truth for model selection and follows the existing pattern of parameterized model retrieval.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Core Framework Upgrade

This phase upgrades the application to Next.js 16 with React 19.2, enables React Compiler for automatic component optimization, and aligns the middleware with v16 conventions.

Task 1: Update Package Dependencies

Update all core framework packages to their Next.js 16 compatible versions.

• Update package.json to set next to ^16.2.0 and react/react-dom to ^19.2.0
• Update eslint-config-next from ^14.2.28 to ^16.x to match the Next.js version
• Update @types/react and @types/react-dom to versions compatible with React 19.2
• Run the package manager to install dependencies and resolve any peer dependency conflicts

Task 2: Update Next.js Configuration for v16

Modify the Next.js configuration to adopt v16 features and conventions.

• Update next.config.mjs to remove the --turbo CLI flag dependency since Turbopack is now stable and default in v16
• Add cacheComponents configuration if granular server-side caching is desired (replaces the experimental.dynamicIO pattern)
• Verify output: 'standalone' remains compatible with v16 build adapters
• Remove any deprecated experimental flags and update serverActions configuration to the v16 format if changed

Task 3: Rename Middleware to Proxy

Align with Next.js 16's Node.js runtime standards by renaming the middleware file.

• Rename middleware.ts to proxy.ts at the project root
• Update the matcher configuration and function signature if the v16 proxy API differs from the v15 middleware API
• Verify the Server Actions pass-through logic (next-action header check) continues to function correctly
• Test that the /settings route protection logic (currently a placeholder) works under the new proxy pattern

Task 4: Enable React Compiler

Enable automatic memoization to optimize heavy UI components without manual intervention.

• Update next.config.mjs to add experimental: { reactCompiler: true } (or the v16 stable path if it has moved out of experimental)
• Install babel-plugin-react-compiler if required by the v16 React Compiler integration
• The existing manual memoization in components/copilot.tsx and components/search-related.tsx can remain—the compiler will handle optimization regardless
• The unmemoized components/resolution-carousel.tsx will now be automatically optimized

🤖 Prompt for AI agents

Upgrade the QCX platform's core framework from Next.js 15/React 19.1 to Next.js
16/React 19.2 and enable the React Compiler for automatic component
optimization.

**1. Update `package.json` dependencies:**
- Set `next` to `^16.2.0`
- Set `react` and `react-dom` to `^19.2.0`
- Update `eslint-config-next` from `^14.2.28` to `^16.x`
- Update `@types/react` and `@types/react-dom` to React 19.2-compatible versions
- Run the package manager install and resolve any peer dependency conflicts

**2. Update `next.config.mjs`:**
- Remove any `--turbo` CLI flag dependency (Turbopack is now stable and default
in v16)
- Add `cacheComponents` configuration if granular server-side caching is desired
(replaces the `experimental.dynamicIO` pattern)
- Verify `output: 'standalone'` remains compatible with v16 build adapters
- Remove deprecated experimental flags and update `serverActions` configuration
to v16 format if changed
- Add `experimental: { reactCompiler: true }` (or the v16 stable path if it has
moved out of experimental)
- Install `babel-plugin-react-compiler` if required by the v16 React Compiler
integration

**3. Rename `middleware.ts` to `proxy.ts`:**
- Rename `middleware.ts` to `proxy.ts` at the project root
- Update the matcher configuration and function signature to match the v16 proxy
API if it differs from v15
- Ensure the Server Actions pass-through logic (`next-action` header check)
continues to function correctly
- Ensure the `/settings` route protection logic (currently a placeholder) works
under the new proxy pattern

**Notes:**
- Existing manual memoization in `components/copilot.tsx` and
`components/search-related.tsx` can remain; the React Compiler will handle
optimization regardless
- The unmemoized `components/resolution-carousel.tsx` will be automatically
optimized by the compiler

Phase 2: Gemini AI Intelligence Enhancements

This phase improves the Gemini 3.1 Pro integration by switching to the optimized customtools endpoint for tool-calling agents, implementing context caching for token efficiency, and updating system prompts to leverage enhanced reasoning.

Task 1: Update Model Selection for Customtools Endpoint

Modify the model selection logic to use the specialized customtools endpoint when tools are involved.

• Update getModel() in lib/utils/index.ts to accept an optional usesTools?: boolean parameter
• When usesTools is true and Gemini is the selected/detected provider, return gemini-3.1-pro-preview-customtools instead of gemini-3.1-pro-preview
• Update the caller in lib/agents/researcher.tsx to pass usesTools: true since it's the only agent with tool access
• Ensure non-tool-using agents (taskManager, inquire, writer, querySuggestor, resolutionSearch) continue using the standard endpoint

Task 2: Implement Context Caching Utilities

Create a caching layer to reduce token usage for long conversation histories.

• Create a new utility in lib/utils/ (e.g., context-cache.ts) to manage conversation context caching
• Implement a cache key strategy based on conversation ID and message count checkpoints
• Cache system prompts and stable conversation prefixes that don't change between requests
• Integrate the caching utility into the researcher agent where long conversation histories are most common
• Add cache invalidation logic when conversation context is modified (e.g., user edits or deletions)

Task 3: Update Researcher Agent Prompts for Reasoning

Refine the researcher system prompt to leverage Gemini 3.1 Pro's improved chain-of-thought reasoning.

• Update the system prompt in lib/agents/researcher.tsx to include explicit reasoning directives
• Add instructions for the model to break down complex geospatial queries into logical steps before tool invocation
• Include guidance for the model to explain its reasoning when selecting between multiple tools (search, retrieve, geospatialQueryTool, videoSearch)
• Maintain backward compatibility with the existing tool descriptions and response format expectations

Task 4: Update Resolution Search Agent for Enhanced Analysis

Update the satellite image analysis agent to utilize improved reasoning for land classification.

• Update the system prompt in lib/agents/resolution-search.tsx to emphasize structured reasoning for land feature classification
• Add explicit instructions for multi-step analysis: identify features → classify land types → extract coordinates → integrate news context
• Leverage the 77.1% ARC-AGI-2 reasoning capability by prompting for abstract pattern recognition in satellite imagery
• Ensure the Zod schema output format remains compatible with existing UI consumers

Task 5: Update Documentation

Update project documentation to reflect the new versions and configuration.

• Update GEMINI_3.1_PRO_INTEGRATION.md to document the customtools endpoint usage and when it applies
• Add documentation for the context caching utility and its configuration options
• Update any README or setup documentation to reflect Next.js 16 and React 19.2 requirements

🤖 Prompt for AI agents

Enhance the Gemini 3.1 Pro integration by routing tool-using agents to the
customtools endpoint, implementing an application-level context caching layer,
updating system prompts for improved reasoning, and updating documentation.

**1. Update `getModel()` in `lib/utils/index.ts`:**
- Add an optional `usesTools?: boolean` parameter to the function signature
- When `usesTools` is `true` and Gemini is the selected/detected provider,
return `gemini-3.1-pro-preview-customtools` instead of `gemini-3.1-pro-preview`
- All other providers and non-tool-using calls must remain unchanged

**2. Update `lib/agents/researcher.tsx`:**
- Pass `usesTools: true` when calling `getModel()`, as it is the only agent with
tool access
- Update the system prompt to include explicit reasoning directives:
- Instructions to break down complex geospatial queries into logical steps
before tool invocation
- Guidance to explain reasoning when selecting between multiple tools (search,
retrieve, geospatialQueryTool, videoSearch)
- Maintain backward compatibility with existing tool descriptions and response
format expectations
- Integrate the new context caching utility (see below) for long conversation
histories

**3. Create `lib/utils/context-cache.ts`:**
- Implement a cache key strategy based on conversation ID and message count
checkpoints
- Cache system prompts and stable conversation prefixes that don't change
between requests
- Add cache invalidation logic for when conversation context is modified (e.g.,
user edits or deletions)

**4. Update `lib/agents/resolution-search.tsx`:**
- Update the system prompt to emphasize structured reasoning for land feature
classification
- Add explicit instructions for multi-step analysis: identify features →
classify land types → extract coordinates → integrate news context
- Add prompting for abstract pattern recognition in satellite imagery
(leveraging ARC-AGI-2 reasoning capability)
- Ensure the Zod schema output format remains compatible with existing UI
consumers

**5. Update documentation:**
- Update `GEMINI_3.1_PRO_INTEGRATION.md` to document the customtools endpoint
usage and when it applies
- Add documentation for the context caching utility and its configuration
options
- Update README or setup documentation to reflect Next.js 16 and React 19.2
requirements

Research

The QCX platform is a Next.js 15.3.8 application with React 19.1.2, using the Vercel AI SDK to orchestrate multiple AI agents (researcher, taskManager, inquire, writer, resolutionSearch, querySuggestor). The central model selection logic lives in lib/utils/index.ts via getModel(), which supports Gemini, Grok, Bedrock, and OpenAI with fallback priority. Tools are defined in lib/agents/tools/ and injected only into the researcher agent. Heavy UI components like copilot.tsx and search-related.tsx use extensive manual memoization (5+ useCallback/useMemo hooks), while resolution-carousel.tsx has none. The current middleware.ts is a stub with hardcoded authentication. The eslint-config-next package is outdated at v14.x.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Upgrade the QCX platform's core framework from Next.js 15/React 19.1 to Next.js
16/React 19.2 and enable the React Compiler for automatic component
optimization.

**1. Update `package.json` dependencies:**
- Set `next` to `^16.2.0`
- Set `react` and `react-dom` to `^19.2.0`
- Update `eslint-config-next` from `^14.2.28` to `^16.x`
- Update `@types/react` and `@types/react-dom` to React 19.2-compatible versions
- Run the package manager install and resolve any peer dependency conflicts

**2. Update `next.config.mjs`:**
- Remove any `--turbo` CLI flag dependency (Turbopack is now stable and default
in v16)
- Add `cacheComponents` configuration if granular server-side caching is desired
(replaces the `experimental.dynamicIO` pattern)
- Verify `output: 'standalone'` remains compatible with v16 build adapters
- Remove deprecated experimental flags and update `serverActions` configuration
to v16 format if changed
- Add `experimental: { reactCompiler: true }` (or the v16 stable path if it has
moved out of experimental)
- Install `babel-plugin-react-compiler` if required by the v16 React Compiler
integration

**3. Rename `middleware.ts` to `proxy.ts`:**
- Rename `middleware.ts` to `proxy.ts` at the project root
- Update the matcher configuration and function signature to match the v16 proxy
API if it differs from v15
- Ensure the Server Actions pass-through logic (`next-action` header check)
continues to function correctly
- Ensure the `/settings` route protection logic (currently a placeholder) works
under the new proxy pattern

**Notes:**
- Existing manual memoization in `components/copilot.tsx` and
`components/search-related.tsx` can remain; the React Compiler will handle
optimization regardless
- The unmemoized `components/resolution-carousel.tsx` will be automatically
optimized by the compiler
===============================================================================

Task: 2

Enhance the Gemini 3.1 Pro integration by routing tool-using agents to the
customtools endpoint, implementing an application-level context caching layer,
updating system prompts for improved reasoning, and updating documentation.

**1. Update `getModel()` in `lib/utils/index.ts`:**
- Add an optional `usesTools?: boolean` parameter to the function signature
- When `usesTools` is `true` and Gemini is the selected/detected provider,
return `gemini-3.1-pro-preview-customtools` instead of `gemini-3.1-pro-preview`
- All other providers and non-tool-using calls must remain unchanged

**2. Update `lib/agents/researcher.tsx`:**
- Pass `usesTools: true` when calling `getModel()`, as it is the only agent with
tool access
- Update the system prompt to include explicit reasoning directives:
- Instructions to break down complex geospatial queries into logical steps
before tool invocation
- Guidance to explain reasoning when selecting between multiple tools (search,
retrieve, geospatialQueryTool, videoSearch)
- Maintain backward compatibility with existing tool descriptions and response
format expectations
- Integrate the new context caching utility (see below) for long conversation
histories

**3. Create `lib/utils/context-cache.ts`:**
- Implement a cache key strategy based on conversation ID and message count
checkpoints
- Cache system prompts and stable conversation prefixes that don't change
between requests
- Add cache invalidation logic for when conversation context is modified (e.g.,
user edits or deletions)

**4. Update `lib/agents/resolution-search.tsx`:**
- Update the system prompt to emphasize structured reasoning for land feature
classification
- Add explicit instructions for multi-step analysis: identify features →
classify land types → extract coordinates → integrate news context
- Add prompting for abstract pattern recognition in satellite imagery
(leveraging ARC-AGI-2 reasoning capability)
- Ensure the Zod schema output format remains compatible with existing UI
consumers

**5. Update documentation:**
- Update `GEMINI_3.1_PRO_INTEGRATION.md` to document the customtools endpoint
usage and when it applies
- Add documentation for the context caching utility and its configuration
options
- Update README or setup documentation to reflect Next.js 16 and React 19.2
requirements

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!