client-side-routing

name	client-side-routing
description	How to add routes without remounting the app shell. Use when adding a new route, fixing agent sidebar reloads on navigation, or choosing between `root.tsx` layout and pathless `_app.tsx` layout patterns.
scope	dev
metadata	{"internal":true}

Client-Side Routing

Rule

All templates are single-page apps using React Router. Navigation must not remount the app shell. The agent sidebar, document tree, and any other persistent chrome must survive route changes.

Why

If the shell unmounts on every navigation, the agent chat reconnects/reloads, destroying in-progress work and hammering the backend.

Hard Rule

The app shell (AgentSidebar + any top-level navigation) must be mounted ONCE, above the <Outlet />. Never wrap each page in its own <AppLayout> / <Layout>. React sees a different component at the outlet position on each nav and unmounts the entire subtree.

Two Correct Patterns

1. All routes need the shell

Mount <AppLayout> in root.tsx around <Outlet />:

// app/root.tsx
<AppLayout>
  < />
</>