diff --git a/docs/router/framework/react/debugging/README.md b/docs/router/framework/react/debugging/README.md
new file mode 100644
index 00000000000..9d1f12c1df9
--- /dev/null
+++ b/docs/router/framework/react/debugging/README.md
@@ -0,0 +1,40 @@
+# Debugging & Troubleshooting
+
+This directory contains troubleshooting guides and debugging help for common TanStack Router issues. Each guide is designed to be:
+
+- **Problem-focused**: Organized by symptoms and error messages
+- **Solution-oriented**: Multiple approaches for different scenarios
+- **Searchable**: Easy to find solutions by error message or problem type
+- **Reference-style**: Quick lookup rather than step-by-step tutorials
+
+## Available Debugging Guides
+
+- [Build and Bundler Issues](./build-issues.md) - Troubleshoot compilation, bundling, and type generation problems
+- [Router Issues](./router-issues.md) - Debug navigation, routing, and state management problems
+
+## Using These Guides
+
+Each debugging guide follows a consistent structure:
+
+1. **Quick Diagnosis** - Common symptoms and how to identify the issue
+2. **Error Message → Solution** - Direct mappings from error messages to fixes
+3. **By Problem Type** - Organized sections for different categories of issues
+4. **Advanced Debugging** - Tools and techniques for complex problems
+5. **Prevention Tips** - Best practices to avoid these issues
+
+## Contributing
+
+When adding new debugging content:
+
+1. Organize by error message or symptom first
+2. Provide multiple solution approaches when possible
+3. Include error message snippets for searchability
+4. Link to relevant how-to guides for setup instructions
+5. Focus on "what's wrong and how to fix it" rather than "how to set up"
+
+## Difference from How-To Guides
+
+- **How-To Guides**: Step-by-step instructions to accomplish a specific task
+- **Debugging Guides**: Problem-solving reference for when things go wrong
+
+For setup and implementation instructions, see the [How-To Guides](../how-to/) directory.
diff --git a/docs/router/framework/react/how-to/README.md b/docs/router/framework/react/how-to/README.md
index dabd1637519..fa55e285882 100644
--- a/docs/router/framework/react/how-to/README.md
+++ b/docs/router/framework/react/how-to/README.md
@@ -11,6 +11,7 @@ This directory contains focused, step-by-step instructions for common TanStack R
 
 - [Install TanStack Router](./install.md) - Basic installation steps
 - [Deploy to Production](./deploy-to-production.md) - Deploy your app to hosting platforms
+- [Integrate with Popular UI Libraries](./integrate-ui-libraries.md) - Set up Shadcn/ui, Material-UI, Framer Motion, and Chakra UI
 
 ## Using These Guides
 
diff --git a/docs/router/framework/react/how-to/integrate-ui-libraries.md b/docs/router/framework/react/how-to/integrate-ui-libraries.md
new file mode 100644
index 00000000000..496cd8fda7f
--- /dev/null
+++ b/docs/router/framework/react/how-to/integrate-ui-libraries.md
@@ -0,0 +1,794 @@
+# How to Integrate with Popular UI Libraries
+
+This guide covers integration of TanStack Router with popular React UI libraries, including solutions for common compatibility issues and animation problems.
+
+## Quick Start
+
+**Time Required:** 30-60 minutes depending on library  
+**Difficulty:** Intermediate  
+**Prerequisites:** Basic TanStack Router setup, chosen UI library installed
+
+### What You'll Accomplish
+
+- Set up type-safe navigation components with your UI library
+- Fix animation and compatibility issues
+- Implement proper styling integration
+- Handle component composition patterns
+- Resolve common integration problems
+
+---
+
+## Shadcn/ui Integration
+
+Shadcn/ui is one of the most popular component libraries, but requires specific setup to work properly with TanStack Router.
+
+### Installation and Setup
+
+**1. Install Shadcn/ui in your TanStack Router project**
+
+```bash
+# Using the TanStack Router template with Shadcn/ui
+npx create-tsrouter-app@latest my-app --template file-router --tailwind --add-ons shadcn
+
+# Or add to existing project
+npx shadcn@latest init
+```
+
+**2. Configure components.json for TanStack Router**
+
+```json
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "default",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "tailwind.config.js",
+    "css": "src/app/globals.css",
+    "baseColor": "slate",
+    "cssVariables": true
+  },
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils"
+  }
+}
+```
+
+### Fixing Animation Issues
+
+**Problem:** Shadcn/ui animations (like Sheet, Dialog, etc.) don't work with TanStack Router.
+
+**Solution:** Ensure proper portal and animation context setup:
+
+**1. Update your root route to include animation context**
+
+```tsx
+// src/routes/__root.tsx
+import { createRootRoute, Outlet } from '@tanstack/react-router'
+import { TanStackRouterDevtools } from '@tanstack/react-router-devtools'
+
+export const Route = createRootRoute({
+  component: () => (
+    <>
+      {/* Ensure proper DOM structure for portals */}
+      <div id="root-content">
+        <Outlet />
+      </div>
+      {/* Portal root for overlays */}
+      <div id="portal-root"></div>
+      <TanStackRouterDevtools />
+    </>
+  ),
+})
+```
+
+**2. Create a custom Sheet component with proper animation setup**
+
+```tsx
+// src/components/ui/router-sheet.tsx
+import * as React from 'react'
+import {
+  Sheet,
+  SheetContent,
+  SheetDescription,
+  SheetHeader,
+  SheetTitle,
+  SheetTrigger,
+} from '@/components/ui/sheet'
+
+interface RouterSheetProps {
+  children: React.ReactNode
+  trigger: React.ReactNode
+  title: string
+  description?: string
+}
+
+export function RouterSheet({
+  children,
+  trigger,
+  title,
+  description,
+}: RouterSheetProps) {
+  const [open, setOpen] = React.useState(false)
+
+  return (
+    <Sheet open={open} onOpenChange={setOpen}>
+      <SheetTrigger asChild>{trigger}</SheetTrigger>
+      <SheetContent>
+        <SheetHeader>
+          <SheetTitle>{title}</SheetTitle>
+          {description && <SheetDescription>{description}</SheetDescription>}
+        </SheetHeader>
+        {children}
+      </SheetContent>
+    </Sheet>
+  )
+}
+```
+
+**3. Use animations with proper key management**
+
+```tsx
+// src/routes/posts/index.tsx
+import { createFileRoute } from '@tanstack/react-router'
+import { RouterSheet } from '@/components/ui/router-sheet'
+import { Button } from '@/components/ui/button'
+
+export const Route = createFileRoute('/posts/')({
+  component: PostsPage,
+})
+
+function PostsPage() {
+  return (
+    <div className="p-4">
+      <RouterSheet
+        trigger={<Button>Open Menu</Button>}
+        title="Navigation Menu"
+        description="Navigate through your posts"
+      >
+        <div className="space-y-4">
+          {/* Sheet content with animations will work properly */}
+          <p>This sheet animates correctly with TanStack Router!</p>
+        </div>
+      </RouterSheet>
+    </div>
+  )
+}
+```
+
+### Navigation Components with Shadcn/ui
+
+**Create router-aware Shadcn/ui navigation components:**
+
+```tsx
+// src/components/ui/router-navigation.tsx
+import { Link } from '@tanstack/react-router'
+import { cn } from '@/lib/utils'
+import {
+  NavigationMenu,
+  NavigationMenuItem,
+  NavigationMenuLink,
+  NavigationMenuList,
+  navigationMenuTriggerStyle,
+} from '@/components/ui/navigation-menu'
+
+interface NavItem {
+  to: string
+  label: string
+  exact?: boolean
+}
+
+interface RouterNavigationProps {
+  items: NavItem[]
+  className?: string
+}
+
+export function RouterNavigation({ items, className }: RouterNavigationProps) {
+  return (
+    <NavigationMenu className={className}>
+      <NavigationMenuList>
+        {items.map((item) => (
+          <NavigationMenuItem key={item.to}>
+            <Link
+              to={item.to}
+              activeOptions={{ exact: item.exact }}
+              className={({ isActive }) =>
+                cn(
+                  navigationMenuTriggerStyle(),
+                  isActive && 'bg-accent text-accent-foreground',
+                )
+              }
+            >
+              {item.label}
+            </Link>
+          </NavigationMenuItem>
+        ))}
+      </NavigationMenuList>
+    </NavigationMenu>
+  )
+}
+```
+
+---
+
+## Material-UI (MUI) Integration
+
+Material-UI requires specific patterns for proper TypeScript integration and component composition.
+
+### Installation and Setup
+
+**1. Install Material-UI dependencies**
+
+```bash
+npm install @mui/material @emotion/react @emotion/styled @mui/icons-material
+```
+
+**2. Set up the theme provider**
+
+```tsx
+// src/components/theme-provider.tsx
+import { ThemeProvider, createTheme } from '@mui/material/styles'
+import CssBaseline from '@mui/material/CssBaseline'
+
+const theme = createTheme({
+  palette: {
+    mode: 'light',
+  },
+})
+
+export function MuiThemeProvider({ children }: { children: React.ReactNode }) {
+  return (
+    <ThemeProvider theme={theme}>
+      <CssBaseline />
+      {children}
+    </ThemeProvider>
+  )
+}
+```
+
+**3. Update your root route**
+
+```tsx
+// src/routes/__root.tsx
+import { createRootRoute, Outlet } from '@tanstack/react-router'
+import { MuiThemeProvider } from '@/components/theme-provider'
+
+export const Route = createRootRoute({
+  component: () => (
+    <MuiThemeProvider>
+      <Outlet />
+    </MuiThemeProvider>
+  ),
+})
+```
+
+### Creating Router-Compatible MUI Components
+
+**Problem:** MUI Link and Button components don't work properly with TanStack Router's type system.
+
+**Solution:** Use `createLink` to create properly typed MUI components:
+
+**1. Create typed MUI Link component**
+
+```tsx
+// src/components/ui/mui-router-link.tsx
+import { createLink } from '@tanstack/react-router'
+import { Link as MuiLink, type LinkProps } from '@mui/material/Link'
+import { forwardRef } from 'react'
+
+// Create a router-compatible MUI Link
+export const RouterLink = createLink(
+  forwardRef<HTMLAnchorElement, LinkProps>((props, ref) => {
+    return <MuiLink ref={ref} {...props} />
+  }),
+)
+```
+
+**2. Create typed MUI Button component**
+
+```tsx
+// src/components/ui/mui-router-button.tsx
+import { createLink } from '@tanstack/react-router'
+import { Button, type ButtonProps } from '@mui/material/Button'
+import { forwardRef } from 'react'
+
+// Create a router-compatible MUI Button
+export const RouterButton = createLink(
+  forwardRef<HTMLButtonElement, ButtonProps>((props, ref) => {
+    return <Button ref={ref} component="button" {...props} />
+  }),
+)
+```
+
+**3. Usage with full type safety**
+
+```tsx
+// src/routes/posts/$postId.tsx
+import { createFileRoute } from '@tanstack/react-router'
+import { Container, Typography, Box } from '@mui/material'
+import { RouterLink, RouterButton } from '@/components/ui/mui-router-link'
+
+export const Route = createFileRoute('/posts/$postId')({
+  component: PostPage,
+})
+
+function PostPage() {
+  const { postId } = Route.useParams()
+
+  return (
+    <Container>
+      <Typography variant="h4">Post {postId}</Typography>
+
+      {/* Fully typed router navigation */}
+      <Box sx={{ mt: 2, display: 'flex', gap: 2 }}>
+        <RouterLink to="/posts" color="primary" underline="hover">
+          Back to Posts
+        </RouterLink>
+
+        <RouterButton
+          to="/posts/$postId/edit"
+          params={{ postId }}
+          variant="contained"
+          color="primary"
+        >
+          Edit Post
+        </RouterButton>
+      </Box>
+    </Container>
+  )
+}
+```
+
+### Handling Active States with MUI
+
+**Create navigation with active state indicators:**
+
+```tsx
+// src/components/navigation/mui-nav-tabs.tsx
+import { useMatchRoute } from '@tanstack/react-router'
+import { Tabs, Tab, type TabsProps } from '@mui/material'
+import { RouterLink } from '@/components/ui/mui-router-link'
+
+interface NavTab {
+  label: string
+  to: string
+  value: string
+}
+
+interface MuiNavTabsProps extends Omit<TabsProps, 'value' | 'onChange'> {
+  tabs: NavTab[]
+}
+
+export function MuiNavTabs({ tabs, ...tabsProps }: MuiNavTabsProps) {
+  const matchRoute = useMatchRoute()
+
+  // Find active tab based on current route
+  const activeTab =
+    tabs.find((tab) => matchRoute({ to: tab.to, fuzzy: true }))?.value || false
+
+  return (
+    <Tabs value={activeTab} {...tabsProps}>
+      {tabs.map((tab) => (
+        <Tab
+          key={tab.value}
+          label={tab.label}
+          value={tab.value}
+          component={RouterLink}
+          to={tab.to}
+        />
+      ))}
+    </Tabs>
+  )
+}
+```
+
+---
+
+## Framer Motion Integration
+
+Framer Motion works well with TanStack Router but requires specific patterns for route animations.
+
+### Installation and Setup
+
+```bash
+npm install framer-motion
+```
+
+### Route Transition Animations
+
+**1. Create an animated route wrapper**
+
+```tsx
+// src/components/animated-route.tsx
+import { motion, type MotionProps } from 'framer-motion'
+import { ReactNode } from 'react'
+
+interface AnimatedRouteProps extends MotionProps {
+  children: ReactNode
+}
+
+const pageVariants = {
+  initial: { opacity: 0, x: -20 },
+  in: { opacity: 1, x: 0 },
+  out: { opacity: 0, x: 20 },
+}
+
+const pageTransition = {
+  type: 'tween',
+  ease: 'anticipate',
+  duration: 0.3,
+}
+
+export function AnimatedRoute({
+  children,
+  ...motionProps
+}: AnimatedRouteProps) {
+  return (
+    <motion.div
+      initial="initial"
+      animate="in"
+      exit="out"
+      variants={pageVariants}
+      transition={pageTransition}
+      {...motionProps}
+    >
+      {children}
+    </motion.div>
+  )
+}
+```
+
+**2. Use animations in your routes**
+
+```tsx
+// src/routes/posts/index.tsx
+import { createFileRoute } from '@tanstack/react-router'
+import { motion } from 'framer-motion'
+import { AnimatedRoute } from '@/components/animated-route'
+
+export const Route = createFileRoute('/posts/')({
+  component: PostsPage,
+})
+
+function PostsPage() {
+  return (
+    <AnimatedRoute>
+      <div className="container mx-auto p-4">
+        <motion.h1
+          initial={{ opacity: 0, y: -20 }}
+          animate={{ opacity: 1, y: 0 }}
+          transition={{ delay: 0.1 }}
+          className="text-3xl font-bold mb-6"
+        >
+          Posts
+        </motion.h1>
+
+        <motion.div
+          initial={{ opacity: 0 }}
+          animate={{ opacity: 1 }}
+          transition={{ delay: 0.2 }}
+          className="grid gap-4"
+        >
+          {/* Post cards with animations */}
+        </motion.div>
+      </div>
+    </AnimatedRoute>
+  )
+}
+```
+
+### Navigation Animations
+
+**Create animated navigation with Framer Motion:**
+
+```tsx
+// src/components/navigation/animated-nav.tsx
+import { Link, useMatchRoute } from '@tanstack/react-router'
+import { motion } from 'framer-motion'
+
+interface NavItem {
+  to: string
+  label: string
+}
+
+interface AnimatedNavProps {
+  items: NavItem[]
+}
+
+export function AnimatedNav({ items }: AnimatedNavProps) {
+  const matchRoute = useMatchRoute()
+
+  return (
+    <nav className="flex space-x-1 p-2 bg-gray-100 rounded-lg">
+      {items.map((item) => {
+        const isActive = matchRoute({ to: item.to, fuzzy: true })
+
+        return (
+          <Link
+            key={item.to}
+            to={item.to}
+            className="relative px-3 py-2 rounded-md text-sm font-medium transition-colors"
+          >
+            {isActive && (
+              <motion.div
+                layoutId="activeTab"
+                className="absolute inset-0 bg-white rounded-md shadow-sm"
+                initial={false}
+                transition={{ type: 'spring', bounce: 0.2, duration: 0.6 }}
+              />
+            )}
+            <span className="relative z-10">{item.label}</span>
+          </Link>
+        )
+      })}
+    </nav>
+  )
+}
+```
+
+---
+
+## Chakra UI Integration
+
+Chakra UI integrates smoothly with TanStack Router with minimal setup.
+
+### Installation and Setup
+
+```bash
+npm install @chakra-ui/react @emotion/react @emotion/styled framer-motion
+```
+
+**1. Set up Chakra provider**
+
+```tsx
+// src/routes/__root.tsx
+import { createRootRoute, Outlet } from '@tanstack/react-router'
+import { ChakraProvider } from '@chakra-ui/react'
+
+export const Route = createRootRoute({
+  component: () => (
+    <ChakraProvider>
+      <Outlet />
+    </ChakraProvider>
+  ),
+})
+```
+
+**2. Create router-compatible Chakra components**
+
+```tsx
+// src/components/ui/chakra-router-link.tsx
+import { createLink } from '@tanstack/react-router'
+import { Link as ChakraLink, Button } from '@chakra-ui/react'
+
+// Router-compatible Chakra Link
+export const RouterLink = createLink(ChakraLink)
+
+// Router-compatible Chakra Button
+export const RouterButton = createLink(Button)
+```
+
+**3. Usage example**
+
+```tsx
+// src/routes/about.tsx
+import { createFileRoute } from '@tanstack/react-router'
+import { Box, Heading, Text, VStack } from '@chakra-ui/react'
+import { RouterLink, RouterButton } from '@/components/ui/chakra-router-link'
+
+export const Route = createFileRoute('/about')({
+  component: AboutPage,
+})
+
+function AboutPage() {
+  return (
+    <Box p={8} maxW="container.md" mx="auto">
+      <VStack spacing={6} align="start">
+        <Heading>About Us</Heading>
+        <Text>Welcome to our application!</Text>
+
+        <RouterLink to="/" color="blue.500">
+          Back to Home
+        </RouterLink>
+
+        <RouterButton to="/contact" colorScheme="blue" variant="solid">
+          Contact Us
+        </RouterButton>
+      </VStack>
+    </Box>
+  )
+}
+```
+
+---
+
+## Common Problems
+
+### Animations Not Working
+
+**Problem:** UI library animations (especially modals, sheets, drawers) don't work properly.
+
+**Solutions:**
+
+1. **Ensure proper DOM structure for portals:**
+
+   ```tsx
+   // Add portal root in your HTML
+   <div id="portal-root"></div>
+
+   // Or in your root route
+   <div id="modal-root"></div>
+   ```
+
+2. **Check CSS-in-JS integration:**
+
+   ```tsx
+   // For Emotion-based libraries
+   import { CacheProvider } from '@emotion/react'
+   import createCache from '@emotion/cache'
+
+   const cache = createCache({ key: 'css' })
+
+   export function App() {
+     return <CacheProvider value={cache}>{/* Your app */}</CacheProvider>
+   }
+   ```
+
+3. **Use proper animation keys:**
+   ```tsx
+   // Ensure animations have stable keys
+   <motion.div key={router.state.location.pathname}>
+     <Outlet />
+   </motion.div>
+   ```
+
+### TypeScript Errors with Component Props
+
+**Problem:** TypeScript errors when using UI library components with TanStack Router props.
+
+**Solution:** Create properly typed wrapper components using `createLink`:
+
+```tsx
+// Type-safe wrapper pattern
+import { createLink } from '@tanstack/react-router'
+import { ComponentType, forwardRef } from 'react'
+
+function createRouterComponent<T extends ComponentType<any>>(Component: T) {
+  return createLink(
+    forwardRef((props, ref) => <Component ref={ref} {...props} />),
+  )
+}
+
+// Usage
+export const RouterButton = createRouterComponent(Button)
+export const RouterLink = createRouterComponent(Link)
+```
+
+### CSS Conflicts and Styling Issues
+
+**Problem:** UI library styles conflict with TanStack Router or application styles.
+
+**Solutions:**
+
+1. **CSS Module integration:**
+
+   ```tsx
+   // Use CSS Modules with UI libraries
+   import styles from './component.module.css'
+   import { Button } from '@mui/material'
+   ;<Button className={styles.customButton}>Click me</Button>
+   ```
+
+2. **Theme integration:**
+
+   ```tsx
+   // Extend UI library themes
+   const theme = createTheme({
+     components: {
+       MuiButton: {
+         styleOverrides: {
+           root: {
+             // Custom styles that work with router
+           },
+         },
+       },
+     },
+   })
+   ```
+
+3. **CSS-in-JS specificity:**
+   ```tsx
+   // Increase specificity for router-specific styles
+   const StyledButton = styled(Button)(({ theme }) => ({
+     '&.router-active': {
+       backgroundColor: theme.palette.primary.main,
+     },
+   }))
+   ```
+
+### Performance Issues with Large UI Libraries
+
+**Problem:** Bundle size or runtime performance issues.
+
+**Solutions:**
+
+1. **Tree shaking:**
+
+   ```tsx
+   // Import only what you need
+   import Button from '@mui/material/Button'
+   import TextField from '@mui/material/TextField'
+
+   // Instead of
+   import { Button, TextField } from '@mui/material'
+   ```
+
+2. **Code splitting with lazy loading:**
+
+   ```tsx
+   import { createLazyFileRoute } from '@tanstack/react-router'
+   import { lazy } from 'react'
+
+   const HeavyUIComponent = lazy(() => import('@/components/heavy-ui'))
+
+   export const Route = createLazyFileRoute('/heavy-page')({
+     component: () => (
+       <Suspense fallback={<div>Loading...</div>}>
+         <HeavyUIComponent />
+       </Suspense>
+     ),
+   })
+   ```
+
+---
+
+## Production Checklist
+
+Before deploying your app with UI library integration:
+
+### Performance
+
+- [ ] Tree shaking enabled for UI library imports
+- [ ] CSS-in-JS properly configured for SSR (if applicable)
+- [ ] Bundle size optimized with code splitting
+- [ ] Animation performance tested on slower devices
+
+### Functionality
+
+- [ ] All navigation components work with router state
+- [ ] Animations and transitions work on route changes
+- [ ] TypeScript compilation successful with UI library integration
+- [ ] Active states properly reflected in navigation components
+
+### Styling
+
+- [ ] Theme consistency across router and UI library
+- [ ] CSS conflicts resolved
+- [ ] Responsive design working with UI library components
+- [ ] Dark mode integration (if applicable)
+
+### Accessibility
+
+- [ ] Keyboard navigation works with router-integrated components
+- [ ] Screen reader compatibility maintained
+- [ ] Focus management working across route transitions
+- [ ] ARIA attributes properly maintained
+
+---
+
+<!-- Common Next Steps (commented out until guides exist)
+## Common Next Steps
+
+- [Set up authentication](./setup-authentication.md) - Add protected routes with your UI library
+- [Setup testing](./setup-testing.md) - Test UI library components with router
+- [Handle search parameters](./handle-search-parameters.md) - Integrate search state with UI components
+-->
+
+## Related Resources
+
+- [Shadcn/ui TanStack Router Installation](https://ui.shadcn.com/docs/installation/tanstack-router) - Official Shadcn/ui integration guide
+- [Material-UI with TypeScript](https://mui.com/material-ui/guides/typescript/) - MUI TypeScript integration
+- [Framer Motion Documentation](https://www.framer.com/motion/) - Animation library documentation
+- [Chakra UI Getting Started](https://chakra-ui.com/getting-started) - Chakra UI setup guide
+- [TanStack Router createLink API](../api/router#createlink) - Official API documentation for component integration
diff --git a/how-to-guides-implementation-plan.md b/how-to-guides-implementation-plan.md
index 21300827aee..2f1aef4be7a 100644
--- a/how-to-guides-implementation-plan.md
+++ b/how-to-guides-implementation-plan.md
@@ -81,27 +81,7 @@ This document outlines the multi-PR process for implementing the remaining how-t
 
 ---
 
-### Priority 3: Guide #4 - How to Fix Common Build and Bundler Issues
-
-**File:** `docs/router/framework/react/how-to/fix-build-issues.md`
-
-**Context for Agent:**
-
-- Check existing installation guides in `docs/router/framework/react/routing/` for bundler setup
-- Focus on troubleshooting rather than initial setup
-- Address type generation failures and module resolution errors
-
-**Content Requirements:**
-
-- Plugin setup for different bundlers (Vite, Webpack, ESBuild, Rspack)
-- Fixing TypeScript route generation
-- Resolving import/export errors
-- Optimizing bundle size
-- Common Problems: Type generation failures, build optimization, module resolution
-
----
-
-### Priority 4: Guide #5 - How to Integrate with Popular UI Libraries
+### Priority 3: Guide #4 - How to Integrate with Popular UI Libraries
 
 **File:** `docs/router/framework/react/how-to/integrate-ui-libraries.md`
 
@@ -120,7 +100,7 @@ This document outlines the multi-PR process for implementing the remaining how-t
 
 ---
 
-### Priority 5: Guide #6 - How to Set Up Authentication and Protected Routes
+### Priority 4: Guide #5 - How to Set Up Authentication and Protected Routes
 
 **File:** `docs/router/framework/react/how-to/setup-authentication.md`
 
@@ -141,13 +121,34 @@ This document outlines the multi-PR process for implementing the remaining how-t
 
 ---
 
-### Remaining Guides (Priority 6-11):
+### Remaining How-To Guides (Priority 5-8):
 
-**Priority 6:** Debug Common Router Issues (`debug-router-issues.md`)
-**Priority 7:** Set Up Testing (`setup-testing.md`)  
-**Priority 8:** Set Up Development Environment (`setup-dev-environment.md`)
-**Priority 9:** Handle Search Parameters and URL State (`handle-search-parameters.md`)
-**Priority 10:** Implement Advanced Routing Patterns (`advanced-routing-patterns.md`)
+**Priority 5:** Set Up Testing (`setup-testing.md`)  
+**Priority 6:** Set Up Development Environment (`setup-dev-environment.md`)
+**Priority 7:** Handle Search Parameters and URL State (`handle-search-parameters.md`)
+**Priority 8:** Implement Advanced Routing Patterns (`advanced-routing-patterns.md`)
+
+---
+
+## Debugging Guides (Separate Directory)
+
+The following guides have been moved to `docs/router/framework/react/debugging/` as they are troubleshooting/FAQ style rather than step-by-step how-to guides:
+
+**Debug Build and Bundler Issues** (`debugging/build-issues.md`)
+
+- Plugin setup troubleshooting for different bundlers (Vite, Webpack, ESBuild, Rspack)
+- Fixing TypeScript route generation failures
+- Resolving import/export errors
+- Bundle optimization problems
+- Module resolution debugging
+
+**Debug Common Router Issues** (`debugging/router-issues.md`)
+
+- Route matching problems
+- Type errors with parameters
+- Navigation not working as expected
+- Performance debugging
+- Common error patterns and solutions
 
 ---
 
@@ -195,18 +196,25 @@ Before marking any guide as complete:
 
 Update this section as guides are completed:
 
+**How-To Guides:**
+
 ```
 ✅ Guide #1: Deploy to Production - COMPLETED
 ⏳ Guide #2: Setup SSR - IN PROGRESS
-⏳ Guide #3: Migrate from React Router - PENDING
-⏳ Guide #4: Fix Build Issues - PENDING
-⏳ Guide #5: Integrate UI Libraries - PENDING
-⏳ Guide #6: Setup Authentication - PENDING
-⏳ Guide #7: Debug Router Issues - PENDING
-⏳ Guide #8: Setup Testing - PENDING
-⏳ Guide #9: Setup Dev Environment - PENDING
-⏳ Guide #10: Handle Search Parameters - PENDING
-⏳ Guide #11: Advanced Routing Patterns - PENDING
+⏳ Guide #3: Migrate from React Router - IN PROGRESS
+✅ Guide #4: Integrate UI Libraries - COMPLETED
+⏳ Guide #5: Setup Authentication - PENDING
+⏳ Guide #6: Setup Testing - PENDING
+⏳ Guide #7: Setup Dev Environment - PENDING
+⏳ Guide #8: Handle Search Parameters - PENDING
+⏳ Guide #9: Advanced Routing Patterns - PENDING
+```
+
+**Debugging Guides:**
+
+```
+⏳ Debug Build Issues - PENDING
+⏳ Debug Router Issues - PENDING
 ```
 
 This systematic approach ensures consistent quality and enables incremental progress across multiple agent sessions.
diff --git a/top-10-how-to-guides.md b/top-10-how-to-guides.md
index 5e834d8b3a8..41235a76a0e 100644
--- a/top-10-how-to-guides.md
+++ b/top-10-how-to-guides.md
@@ -1,6 +1,8 @@
-# Top 10 How-To Guides for TanStack Router
+# Top 9 How-To Guides for TanStack Router
 
-Based on analysis of GitHub issues, existing documentation, repository structure, and common developer pain points, here are the top 10 how-to guides that would most increase developer and AI productivity:
+Based on analysis of GitHub issues, existing documentation, repository structure, and common developer pain points, here are the top 9 how-to guides that would most increase developer and AI productivity:
+
+> **Note:** Build/bundler issues and router debugging have been moved to a separate [Debugging & Troubleshooting](docs/router/framework/react/debugging/) directory as they are problem-solving references rather than step-by-step how-to guides.
 
 ## ✅ 1. **How to Deploy TanStack Router to Production Hosting Platforms** - COMPLETED
 
@@ -49,28 +51,7 @@ Based on analysis of GitHub issues, existing documentation, repository structure
 
 ---
 
-## 4. **How to Fix Common Build and Bundler Issues**
-
-**Priority: High** - Blocking developer productivity
-
-**Key Pain Points:**
-
-- Webpack/Vite plugin configuration
-- Type generation failures
-- Build optimization problems
-- Module resolution errors
-
-**Content Should Cover:**
-
-- Plugin setup for different bundlers (Vite, Webpack, ESBuild, Rspack)
-- Fixing TypeScript route generation
-- Resolving import/export errors
-- Optimizing bundle size
-- Development vs production build differences
-
----
-
-## 5. **How to Integrate with Popular UI Libraries**
+## 4. **How to Integrate with Popular UI Libraries**
 
 **Priority: High** - Common integration challenges
 
@@ -90,7 +71,7 @@ Based on analysis of GitHub issues, existing documentation, repository structure
 
 ---
 
-## 6. **How to Set Up Authentication and Protected Routes**
+## 5. **How to Set Up Authentication and Protected Routes**
 
 **Priority: High** - Security-critical feature
 
@@ -110,28 +91,7 @@ Based on analysis of GitHub issues, existing documentation, repository structure
 
 ---
 
-## 7. **How to Debug Common Router Issues**
-
-**Priority: High** - Improves developer experience
-
-**Key Pain Points:**
-
-- Route matching problems
-- Type errors with parameters
-- Navigation not working as expected
-- Performance debugging
-
-**Content Should Cover:**
-
-- Using TanStack Router DevTools effectively
-- Debugging route matching failures
-- Troubleshooting navigation issues
-- Performance profiling and optimization
-- Common error patterns and solutions
-
----
-
-## 8. **How to Set Up Testing with TanStack Router**
+## 6. **How to Set Up Testing with TanStack Router**
 
 **Priority: Medium-High** - Critical for production apps
 
@@ -151,7 +111,7 @@ Based on analysis of GitHub issues, existing documentation, repository structure
 
 ---
 
-## 9. **How to Set Up Development Environment and Tooling**
+## 7. **How to Set Up Development Environment and Tooling**
 
 **Priority: Medium-High** - Onboarding efficiency
 
@@ -171,7 +131,7 @@ Based on analysis of GitHub issues, existing documentation, repository structure
 
 ---
 
-## 10. **How to Handle Search Parameters and URL State**
+## 8. **How to Handle Search Parameters and URL State**
 
 **Priority: Medium-High** - Common developer confusion
 
@@ -192,7 +152,7 @@ Based on analysis of GitHub issues, existing documentation, repository structure
 
 ---
 
-## 11. **How to Implement Advanced Routing Patterns**
+## 9. **How to Implement Advanced Routing Patterns**
 
 **Priority: Medium** - Advanced use cases