Routing and providers
The root layout composes URL-state, query, tooltip, and application providers. Public authentication routes bypass protected context. Organization View uses /dashboard/[orgId], while Platform View uses /dashboard/platform with no active Organization.
API and query contracts
Use the shared API singleton, feature-local Zod schemas, and centralized query keys. The client sends cookies and transforms snake_case responses to camelCase. New Organization-scoped queries must include Organization identity in their key or join the provider eviction set used during a real Organization switch.
Loading and errors
Use route loading and error files for page-blocking router work. Component-owned queries keep their initial loading, retry, search, pagination, and refetch states local. A hook error does not automatically reach an App Router error boundary.
UI conventions
Prefer Server Components until client-owned behavior is required. Use branded ConfirmationDialog for confirmation flows and shared shadcn Select primitives for option selectors. Mutations invalidate affected list and detail families; avoid effect chains for user-triggered workflows.
Streaming exception
Agent logs use a dedicated Next route handler that proxies server-sent events and a feature hook that owns reconnection. Keep this explicit exception separate from the normal API client.