fix(docs): new router

[icecrasher321]

Summary

Update router docs to match port based routing.

Type of Change

• Documentation

Testing

Read

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
docs	Ready	Preview, Comment	Jan 10, 2026 1:37am

[greptile-apps]

Greptile Overview

Greptile Summary

This PR updates the Router block documentation to reflect the new port-based routing architecture (Router V2). The changes successfully document the key architectural shift from block-based routing to route-based routing with separate output ports.

Key Changes

Documentation Structure Updates:

• Updated the main description to explain that each route creates a separate output port
• Renamed "Content/Prompt" to "Context" to match the V2 implementation
• Replaced "Target Blocks" section with comprehensive "Routes" section explaining route titles and descriptions
• Updated all example use cases to show the port-based routing visualization
• Revised best practices to focus on route descriptions rather than target block descriptions
• Updated output variables to include <router.context> and <router.selectedRoute>

Visual Update:

• New router.png image showing the Router block with multiple output ports (Context, Route 1, Error)

Implementation Alignment

The documentation changes accurately reflect the RouterV2Block implementation in apps/sim/blocks/blocks/router.ts:

• ✅ Context field correctly documented (maps to context input)
• ✅ Routes configuration correctly explained (maps to routes input with id, title, value)
• ✅ Output variables match the code: context, selectedRoute, selected_path, tokens, cost, model
• ✅ Port-based routing mechanism correctly described (connections via router-{routeId} handles)

Issues Found

Model Name Inconsistencies:
The documentation lists several model names that don't match the actual model IDs defined in apps/sim/providers/models.ts:

• "gpt-4.1" doesn't exist (should be gpt-5.1, gpt-5, etc.)
• "Claude 3.7 Sonnet" uses inconsistent naming (actual models: claude-sonnet-4-5, claude-opus-4-5, etc.)
• This issue also exists in other block documentation files (agent.mdx, evaluator.mdx, guardrails.mdx)

These are documentation-only issues that don't affect functionality, but should be corrected for accuracy and consistency.

Confidence Score: 4/5

• This documentation PR is safe to merge with minor improvements recommended for model name accuracy
• Score of 4 reflects that the documentation accurately describes the port-based routing architecture and correctly documents the Router V2 implementation. The changes are well-structured, comprehensive, and align with the actual code implementation. The only issues are style-related model name inconsistencies that don't affect functionality but should be corrected for accuracy. The image update correctly visualizes the new port-based approach.
• apps/docs/content/docs/en/blocks/router.mdx - Update model names to match actual model IDs in the codebase for consistency and accuracy

Important Files Changed

File Analysis

Filename	Score	Overview
apps/docs/content/docs/en/blocks/router.mdx	3/5	Updated documentation for port-based router with route configuration, but contains inaccurate model names that don't match the actual model IDs in the codebase
apps/docs/public/static/blocks/router.png	5/5	Updated image showing router block with multiple output ports for route-based routing

Sequence Diagram

sequenceDiagram
    participant User
    participant RouterBlock as Router Block (V2)
    participant LLM as AI Model
    participant Route1 as Route 1 Port
    participant Route2 as Route 2 Port
    participant RouteN as Route N Port
    participant DownstreamBlock as Downstream Block

    User->>RouterBlock: Provide context input
    RouterBlock->>RouterBlock: Load route definitions<br/>(title, description, id)
    RouterBlock->>LLM: Send context + route descriptions
    Note over RouterBlock,LLM: System prompt with all routes<br/>and their descriptions
    LLM->>LLM: Analyze context against<br/>route descriptions
    LLM->>RouterBlock: Return selected route ID
    RouterBlock->>RouterBlock: Validate route selection
    alt Route 1 Selected
        RouterBlock->>Route1: Output via route-{id} handle
        Route1->>DownstreamBlock: Continue workflow
    else Route 2 Selected
        RouterBlock->>Route2: Output via route-{id} handle
        Route2->>DownstreamBlock: Continue workflow
    else Route N Selected
        RouterBlock->>RouteN: Output via route-{id} handle
        RouteN->>DownstreamBlock: Continue workflow
    end
    RouterBlock->>User: Return outputs:<br/>context, selectedRoute,<br/>selected_path, tokens, cost

Loading

[greptile-apps]

_{3 files reviewed, 3 comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

Additional Comments (3)

apps/docs/content/docs/en/blocks/router.mdx
The model names listed here don't match the actual model IDs in the codebase. Based on apps/sim/providers/models.ts:

• "gpt-4.1" does not exist - available OpenAI models include: gpt-4o, gpt-5.2, gpt-5.1, gpt-5, gpt-5-mini, o1, o3, o4-mini
• "Claude 3.7 Sonnet" - the actual Anthropic model IDs are: claude-sonnet-4-5 (default), claude-sonnet-4-0, claude-opus-4-5, claude-opus-4-1, claude-opus-4-0, claude-3-7-sonnet-latest

This inconsistency appears across multiple block documentation files (agent.mdx, evaluator.mdx, guardrails.mdx) and should be addressed for accuracy. The documentation should either:

1. Use the exact model IDs as they appear in the code
2. Or consistently use marketing names if that's the intended approach, but ensure they're accurate

- **OpenAI**: GPT-4o, o1, o3, o4-mini, GPT-5.2, GPT-5.1, GPT-5
- **Anthropic**: Claude Sonnet 4.5, Claude Opus 4.5, Claude Opus 4.1

Prompt To Fix With AI

This is a comment left during a code review.
Path: apps/docs/content/docs/en/blocks/router.mdx
Line: 57:58

Comment:
The model names listed here don't match the actual model IDs in the codebase. Based on `apps/sim/providers/models.ts`:

- "gpt-4.1" does not exist - available OpenAI models include: `gpt-4o`, `gpt-5.2`, `gpt-5.1`, `gpt-5`, `gpt-5-mini`, `o1`, `o3`, `o4-mini`
- "Claude 3.7 Sonnet" - the actual Anthropic model IDs are: `claude-sonnet-4-5` (default), `claude-sonnet-4-0`, `claude-opus-4-5`, `claude-opus-4-1`, `claude-opus-4-0`, `claude-3-7-sonnet-latest`

This inconsistency appears across multiple block documentation files (agent.mdx, evaluator.mdx, guardrails.mdx) and should be addressed for accuracy. The documentation should either:
1. Use the exact model IDs as they appear in the code
2. Or consistently use marketing names if that's the intended approach, but ensure they're accurate

```suggestion
- **OpenAI**: GPT-4o, o1, o3, o4-mini, GPT-5.2, GPT-5.1, GPT-5
- **Anthropic**: Claude Sonnet 4.5, Claude Opus 4.5, Claude Opus 4.1
```

How can I resolve this? If you propose a fix, please make it concise.

---

apps/docs/content/docs/en/blocks/router.mdx
The Google model names are generally correct but could be more comprehensive. Based on apps/sim/providers/models.ts, available Gemini models include:

• gemini-3-pro-preview
• gemini-2.5-pro ✓ (correctly listed)
• gemini-2.5-flash
• gemini-2.5-flash-lite
• gemini-2.0-flash ✓ (correctly listed)
• gemini-2.0-flash-lite

Consider adding the Flash variants for more complete documentation:

- **Google**: Gemini 3 Pro Preview, Gemini 2.5 Pro, Gemini 2.5 Flash, Gemini 2.0 Flash

_{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

Prompt To Fix With AI

This is a comment left during a code review.
Path: apps/docs/content/docs/en/blocks/router.mdx
Line: 59:59

Comment:
The Google model names are generally correct but could be more comprehensive. Based on `apps/sim/providers/models.ts`, available Gemini models include:

- `gemini-3-pro-preview`
- `gemini-2.5-pro` ✓ (correctly listed)
- `gemini-2.5-flash`
- `gemini-2.5-flash-lite`
- `gemini-2.0-flash` ✓ (correctly listed)
- `gemini-2.0-flash-lite`

Consider adding the Flash variants for more complete documentation:

```suggestion
- **Google**: Gemini 3 Pro Preview, Gemini 2.5 Pro, Gemini 2.5 Flash, Gemini 2.0 Flash
```

<sub>Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!</sub>

How can I resolve this? If you propose a fix, please make it concise.

---

apps/docs/content/docs/en/blocks/router.mdx
The model recommendation references "Claude 3.7 Sonnet" which doesn't match the actual model naming in the codebase. The default model used in the router implementation is claude-sonnet-4-5 (see apps/sim/blocks/blocks/router.ts line 315).

Consider updating to match the actual model names:

Use models with strong reasoning capabilities like GPT-4o or Claude Sonnet 4.5 for best results.

Prompt To Fix With AI

This is a comment left during a code review.
Path: apps/docs/content/docs/en/blocks/router.mdx
Line: 63:63

Comment:
The model recommendation references "Claude 3.7 Sonnet" which doesn't match the actual model naming in the codebase. The default model used in the router implementation is `claude-sonnet-4-5` (see `apps/sim/blocks/blocks/router.ts` line 315).

Consider updating to match the actual model names:

```suggestion
Use models with strong reasoning capabilities like GPT-4o or Claude Sonnet 4.5 for best results.
```

How can I resolve this? If you propose a fix, please make it concise.