feat(url-state): migrate remaining view-state to nuqs + harness updates

Make the URL the single source of truth for shareable view-state across the
remaining sweep-confirmed sites:

- settings/mcp: replace initialServerId prop + effect-sync with a direct
  useQueryState (mcpServerId, history: push); stop prop-drilling from settings
- integrations: selectedCategory + debounced search; add Suspense boundary
- tables: debounced search + sort/dir + row-count/owner filters (activeTable
  stays route state — selecting a table navigates to tables/[tableId]); wire
  the existing loading.tsx as the Suspense fallback
- knowledge/[id]: pagination page param
- settings/recently-deleted: tab + sort/dir + debounced search
- settings/admin: committed search (q) + pagination offset
- settings/mothership: tab + environment
- skills: editingSkill object -> skillId deep-link (derive from useSkills); add
  Suspense boundary
- files: shareFileId deep-link added to files/search-params
- landing integrations + models directories: debounced search + category/
  provider filter; add Suspense boundaries

Harness: add a When-to-use decision table, the sort (sort+dir) convention, the
selected-entity deep-link pattern, and nuqs doc links to sim-url-state.md; add
the /you-might-not-need-url-state command and wire it into /cleanup.

Author: waleedlatif1

.claude/commands/cleanup.md

@@ -1,5 +1,5 @@
 ---
-description: Run all code quality skills in sequence — effects, memo, callbacks, state, React Query, and emcn design review
+description: Run all code quality skills in sequence — effects, memo, callbacks, state, url-state, React Query, and emcn design review
 argument-hint: [scope] [fix=true|false]
 ---
 
@@ -21,5 +21,6 @@ Run each of these skills in order on the specified scope, passing through the sc
 4. `/you-might-not-need-state $ARGUMENTS`
 5. `/react-query-best-practices $ARGUMENTS`
 6. `/emcn-design-review $ARGUMENTS`
+7. `/you-might-not-need-url-state $ARGUMENTS`
 
-After all skills have run, output a summary of what was found and fixed (or proposed) across all six passes.
+After all skills have run, output a summary of what was found and fixed (or proposed) across all seven passes.

.claude/commands/you-might-not-need-url-state.md

@@ -0,0 +1,45 @@
+---
+description: Analyze and fix URL/query-param state anti-patterns — manual useSearchParams reads, hand-built query mutations, view-state trapped in useState, and objects in the URL
+argument-hint: [scope] [fix=true|false]
+---
+
+# You Might Not Need URL State
+
+Arguments:
+- scope: what to analyze (default: your current changes). Examples: "diff to main", "PR #123", "app/workspace/[workspaceId]/tables/", "whole codebase"
+- fix: whether to apply fixes (default: true). Set to false to only propose changes.
+
+User arguments: $ARGUMENTS
+
+## Context
+
+Shareable client view-state (active tab/panel, filters, search query, sort, pagination, selected-entity id, an open "view" modal/drawer that is a destination) lives in the URL via [`nuqs`](https://nuqs.dev) — driven by a co-located `search-params.ts`, never read via `useSearchParams().get(...)` and never mutated by hand-built query strings. Remote data stays in React Query; high-frequency / large / ephemeral / socket-synced state stays in Zustand; purely local UI stays in `useState`.
+
+`.claude/rules/sim-url-state.md` is the source of truth — read it first.
+
+## References
+
+Read these before analyzing:
+1. `.claude/rules/sim-url-state.md` — the decision framework, conventions, debounced-input pattern, sort convention, selected-entity deep-link pattern, and the workflow-editor carve-out
+2. https://nuqs.dev/docs/parsers — parsers (`parseAsString`/`parseAsInteger`/`parseAsBoolean`/`parseAsStringLiteral`/`parseAsArrayOf`/`createParser`)
+3. https://nuqs.dev/docs/options — `withDefault`, `history`, `shallow`, `clearOnDefault`
+4. https://nuqs.dev/docs/server-side — `createSearchParamsCache` for server reads
+
+## Anti-patterns to detect
+
+1. **Manual param reads for state**: `useSearchParams().get(...)` or `new URLSearchParams(window.location.search)` used to *read* view-state. Replace with `useQueryState`/`useQueryStates` bound to a `search-params.ts`. (Read-once auth/invite/redirect tokens — `token`, `callbackUrl`, `redirect`, `error`, `invite_flow`, `code` — are NOT view-state; leave them on `useSearchParams`.)
+2. **Hand-built query mutation**: constructing a query string + `router.replace`/`router.push` to change a param on the current path. Use a nuqs setter. (A `router.push` that changes the route *path* is fine; an outbound `new URLSearchParams` building an `href`/`window.open`/download/API URL is fine.)
+3. **`window.history.replaceState`/`pushState`** to mutate a param.
+4. **URL state duplicated into a store/useState + synced with an effect** (or a `popstate` listener). The URL is the single source of truth; derive from it, don't mirror it.
+5. **Objects in the URL**: serializing a `TableDefinition`/`SkillDefinition`/etc. Store the id and derive the object from the loaded list (`items.find(i => i.id === id)`).
+6. **High-frequency / large state in the URL**: cursor, pan/zoom, un-debounced keystrokes, big JSON blobs. Debounce text search (local `useState` mirror + reconcile effect); keep canvas/presence/resize state in Zustand.
+7. **Shareable view-state trapped in `useState`**: a tab/filter/sort/pagination/selected-entity that should be a link but lives in local state. Migrate it to the URL.
+8. **Missing Suspense boundary**: a component newly calling `useQueryState`/`useQueryStates` whose page entry has no `<Suspense>` wrapper (Next.js requires it for `useSearchParams`). Add one with a real-chrome fallback.
+9. **`import { z }` for param validation in client code**: use nuqs parsers instead.
+
+## Steps
+
+1. Read `.claude/rules/sim-url-state.md` and the nuqs docs above to understand the guidelines
+2. Analyze the specified scope for the anti-patterns listed above
+3. For each finding, decide the correct home using the decision table — do not force URL state onto ephemeral/high-frequency/socket-synced state
+4. If fix=true, apply the fixes (co-locate a `search-params.ts`, wire `useQueryState(s)`, add the Suspense boundary, delete the replaced state + sync effects). If fix=false, propose the fixes without applying.

.claude/rules/sim-url-state.md

@@ -20,6 +20,15 @@ Pick exactly one home for each piece of state:
 
 Put state in the URL **only** when it is *all* of: shareable, deep-linkable, bookmarkable, survives reload + back/forward — **and** is discrete, low-frequency, and small. If it fails any of those, it does not go in the URL.
 
+### When to use what (decision table)
+
+| Home | Trigger | Example |
+| --- | --- | --- |
+| **URL (nuqs)** | Client view-state worth a link: tab, filter, search, sort, pagination, selected-entity id, an open "view" modal/drawer that is a destination | `?tab=licenses`, `?category=Communication`, `?page=3`, `?skillId=abc` |
+| **React Query** | Server/remote data fetched from an endpoint | `useMcpServers(workspaceId)`, `useSkills(workspaceId)` |
+| **Zustand** | Cross-component client state that must NOT be in the URL: high-frequency, large, ephemeral, socket-synced | canvas pan/zoom, live cursor, drag state, resize widths, unsaved buffers |
+| **`useState`** | Purely local single-component UI; also the snappy mirror of a debounced URL search | a hover flag, a transient dialog target, the live text of a debounced search box |
+
 ## Anti-patterns (forbidden)
 
 - Direct `useSearchParams().get(...)` or `new URLSearchParams(window.location.search)` to **read** state.
@@ -119,6 +128,38 @@ If a client param must be re-read server-side after a change, set `shallow: fals
 
 Keep local `useState` for snappy typing; push to the URL debounced, and reconcile from the URL with a ref-guarded effect so external URL changes (back/forward, deep link) flow back into the input without clobbering in-flight keystrokes. This is the established logs pattern — follow it rather than writing every keystroke to the URL.
 
+## Sort convention (`sort` + `dir`)
+
+Sortable lists use **two scalar params**, never a serialized `{column,direction}` object:
+
+```typescript
+const SORT_COLUMNS = ['name', 'created', 'updated'] as const
+const SORT_DIRECTIONS = ['asc', 'desc'] as const
+
+export const thingsParsers = {
+  sort: parseAsStringLiteral(SORT_COLUMNS).withDefault('updated'),
+  dir: parseAsStringLiteral(SORT_DIRECTIONS).withDefault('desc'),
+} as const
+```
+
+Both carry the shared filter options (`{ history: 'replace', clearOnDefault: true }`). The defaults must match the list's existing default sort exactly. If a UI exposes "no active sort" as `null`, derive that in the component (`sort === DEFAULT && dir === DEFAULT ? null : { column, direction }`) — the URL still holds the resolved values. "Clear sort" writes the defaults back (which `clearOnDefault` strips from the URL); never write `null`/garbage columns.
+
+## Selected-entity deep-link (store the id, derive the object)
+
+To deep-link a row/modal/drawer to one entity, store **only its id** and look the object up in the already-loaded list — never serialize the object into the URL:
+
+```typescript
+const [skillId, setSkillId] = useQueryState(skillIdParam.key, {
+  ...skillIdParam.parser,
+  history: 'push', // opening an entity is a destination; "back" closes it
+  clearOnDefault: true,
+})
+// Derive — do not duplicate into useState or sync with an effect:
+const editingSkill = skillId ? (skills.find((s) => s.id === skillId) ?? null) : null
+```
+
+Open the panel/modal when the id resolves to a loaded entity; closing it calls `setSkillId(null)`. Because this reads `useSearchParams` it needs a **Suspense** boundary on the page (see below). A separate "create new" flow has no id and stays in local `useState`.
+
 ## Read-then-strip deep links
 
 For an ephemeral deep-link that pre-opens a modal/drawer and should not linger in the URL (e.g. integrations `?connect=oauth`, knowledge `?addConnector=`), read the param, act on it once behind a `useRef` guard, then clear it: `setParam(null, { history: 'replace', scroll: false })`. See `apps/sim/app/workspace/[workspaceId]/integrations/[block]/integration-block-detail.tsx`.
@@ -138,3 +179,9 @@ Borderline candidates that *look* shareable but currently stay in Zustand becaus
 - **`focusedBlockId`** ("look at this block") — the only genuinely shareable candidate, but it is entangled with the persisted editor store and panel-open orchestration. Adding it is a *new feature*, not a migration; ship it deliberately (with runtime verification against a live socket), not as part of a sweep.
 
 Rule of thumb for the editor: if state is socket-coupled, high-frequency, viewport-related, or a persisted resize/preference, it stays in Zustand. When in doubt, leave it and flag it — do not force fragile URL state into the canvas.
+
+## Docs
+
+- Adapters (App Router `NuqsAdapter`): https://nuqs.dev/docs/adapters
+- Parsers & options (`parseAsString`/`parseAsInteger`/`parseAsBoolean`/`parseAsStringLiteral`/`parseAsArrayOf`/`createParser`, `withDefault`, `history`, `shallow`, `clearOnDefault`): https://nuqs.dev/docs/parsers and https://nuqs.dev/docs/options
+- Server-side reads (`createSearchParamsCache`): https://nuqs.dev/docs/server-side

apps/sim/app/(landing)/integrations/(shell)/page.tsx

@@ -1,3 +1,4 @@
+import { Suspense } from 'react'
 import type { Metadata } from 'next'
 import { Badge } from '@/components/emcn'
 import { SITE_URL } from '@/lib/core/utils/urls'
@@ -205,7 +206,9 @@ export default function IntegrationsPage() {
               All Integrations
             </h2>
           </div>
-          <IntegrationGrid integrations={allIntegrations} />
+          <Suspense fallback={null}>
+            <IntegrationGrid integrations={allIntegrations} />
+          </Suspense>
         </section>
 
         <div className='h-px w-full bg-[var(--landing-bg-elevated)]' />

apps/sim/app/(landing)/integrations/components/integration-grid.tsx

@@ -1,9 +1,15 @@
 'use client'
 
-import { useState } from 'react'
+import { useEffect, useRef, useState } from 'react'
+import { useQueryStates } from 'nuqs'
 import { ChipInput, Search } from '@/components/emcn'
 import { blockTypeToIconMap, formatIntegrationType, type Integration } from '@/lib/integrations'
 import { IntegrationRow } from '@/app/(landing)/integrations/components/integration-card'
+import {
+  integrationsDirectoryParsers,
+  integrationsDirectoryUrlKeys,
+} from '@/app/(landing)/integrations/search-params'
+import { useDebounce } from '@/hooks/use-debounce'
 
 const PILL_BASE =
   'rounded-[5px] border border-[var(--landing-border-strong)] px-[9px] py-0.5 text-[13.5px] text-[var(--landing-text)] transition-colors' as const
@@ -15,8 +21,29 @@ interface IntegrationGridProps {
 }
 
 export function IntegrationGrid({ integrations }: IntegrationGridProps) {
-  const [query, setQuery] = useState('')
-  const [activeCategory, setActiveCategory] = useState<string | null>(null)
+  const [{ search: urlQuery, category: urlCategory }, setDirectoryFilters] = useQueryStates(
+    integrationsDirectoryParsers,
+    integrationsDirectoryUrlKeys
+  )
+
+  const [query, setQuery] = useState(urlQuery)
+  const debouncedQuery = useDebounce(query, 300)
+
+  useEffect(() => {
+    setDirectoryFilters({ search: debouncedQuery.length > 0 ? debouncedQuery : null })
+  }, [debouncedQuery, setDirectoryFilters])
+
+  const lastSyncedUrlSearchRef = useRef(urlQuery)
+  useEffect(() => {
+    if (urlQuery === lastSyncedUrlSearchRef.current) return
+    lastSyncedUrlSearchRef.current = urlQuery
+    setQuery((current) => (current === urlQuery ? current : urlQuery))
+  }, [urlQuery])
+
+  const activeCategory = urlCategory.length > 0 ? urlCategory : null
+  const setActiveCategory = (category: string | null) => {
+    setDirectoryFilters({ category })
+  }
 
   const counts = new Map<string, number>()
   for (const i of integrations) {

apps/sim/app/(landing)/integrations/search-params.ts

@@ -0,0 +1,23 @@
+import { parseAsString } from 'nuqs/server'
+
+/**
+ * Co-located, typed URL query-param definitions for the public integrations
+ * directory. Both the client (`IntegrationGrid`) and any server component that
+ * reads these params consume this single source of truth.
+ *
+ * - `search` is the directory search term, written debounced from the local
+ *   input (logs pattern) — never on every keystroke.
+ * - `category` is the active integration-type filter. Categories are derived
+ *   from the data set, so a plain string is used; the empty default (no filter)
+ *   clears from the URL.
+ */
+export const integrationsDirectoryParsers = {
+  search: parseAsString.withDefault(''),
+  category: parseAsString.withDefault(''),
+} as const
+
+/** Filter/search view-state: clean URLs, no back-stack churn. */
+export const integrationsDirectoryUrlKeys = {
+  history: 'replace',
+  clearOnDefault: true,
+} as const

apps/sim/app/(landing)/models/(shell)/page.tsx

@@ -1,3 +1,4 @@
+import { Suspense } from 'react'
 import type { Metadata } from 'next'
 import { Badge } from '@/components/emcn'
 import { SITE_URL } from '@/lib/core/utils/urls'
@@ -225,7 +226,9 @@ export default function ModelsPage() {
                 All models
               </h2>
             </div>
-            <ModelDirectory />
+            <Suspense fallback={null}>
+              <ModelDirectory />
+            </Suspense>
           </section>
 
           <div className='h-px w-full bg-[var(--landing-bg-elevated)]' />

apps/sim/app/(landing)/models/components/model-directory.tsx

@@ -1,9 +1,11 @@
 'use client'
 
-import { useMemo, useState } from 'react'
+import { useEffect, useMemo, useRef, useState } from 'react'
 import Link from 'next/link'
+import { useQueryStates } from 'nuqs'
 import { Input } from '@/components/emcn'
 import { ChevronArrow, ProviderIcon } from '@/app/(landing)/models/components/model-primitives'
+import { modelDirectoryParsers, modelDirectoryUrlKeys } from '@/app/(landing)/models/search-params'
 import {
   type CatalogModel,
   type CatalogProvider,
@@ -12,10 +14,32 @@ import {
   MODEL_PROVIDERS_WITH_CATALOGS,
   MODEL_PROVIDERS_WITH_DYNAMIC_CATALOGS,
 } from '@/app/(landing)/models/utils'
+import { useDebounce } from '@/hooks/use-debounce'
 
 export function ModelDirectory() {
-  const [query, setQuery] = useState('')
-  const [activeProviderId, setActiveProviderId] = useState<string | null>(null)
+  const [{ search: urlQuery, provider: urlProvider }, setModelFilters] = useQueryStates(
+    modelDirectoryParsers,
+    modelDirectoryUrlKeys
+  )
+
+  const [query, setQuery] = useState(urlQuery)
+  const debouncedQuery = useDebounce(query, 300)
+
+  useEffect(() => {
+    setModelFilters({ search: debouncedQuery.length > 0 ? debouncedQuery : null })
+  }, [debouncedQuery, setModelFilters])
+
+  const lastSyncedUrlSearchRef = useRef(urlQuery)
+  useEffect(() => {
+    if (urlQuery === lastSyncedUrlSearchRef.current) return
+    lastSyncedUrlSearchRef.current = urlQuery
+    setQuery((current) => (current === urlQuery ? current : urlQuery))
+  }, [urlQuery])
+
+  const activeProviderId = urlProvider.length > 0 ? urlProvider : null
+  const setActiveProviderId = (providerId: string | null) => {
+    setModelFilters({ provider: providerId })
+  }
 
   const providerOptions = useMemo(
     () =>

apps/sim/app/(landing)/models/search-params.ts

@@ -0,0 +1,23 @@
+import { parseAsString } from 'nuqs/server'
+
+/**
+ * Co-located, typed URL query-param definitions for the public model directory.
+ * Both the client (`ModelDirectory`) and any server component that reads these
+ * params consume this single source of truth.
+ *
+ * - `search` is the directory search term, written debounced from the local
+ *   input (logs pattern) — never on every keystroke.
+ * - `provider` is the active provider filter. Provider ids are derived from the
+ *   data set, so a plain string is used; the empty default (no filter) clears
+ *   from the URL.
+ */
+export const modelDirectoryParsers = {
+  search: parseAsString.withDefault(''),
+  provider: parseAsString.withDefault(''),
+} as const
+
+/** Filter/search view-state: clean URLs, no back-stack churn. */
+export const modelDirectoryUrlKeys = {
+  history: 'replace',
+  clearOnDefault: true,
+} as const

apps/sim/app/workspace/[workspaceId]/files/files.tsx

@@ -173,10 +173,8 @@ export function Files() {
 
   const params = useParams()
   const router = useRouter()
-  const [{ folderId: currentFolderId, new: isNewFile }, setFilesParams] = useQueryStates(
-    filesParsers,
-    filesUrlKeys
-  )
+  const [{ folderId: currentFolderId, new: isNewFile, shareFileId }, setFilesParams] =
+    useQueryStates(filesParsers, filesUrlKeys)
   const workspaceId = params?.workspaceId as string
 
   const posthog = usePostHog()
@@ -274,7 +272,6 @@ export function Files() {
     folderIds: string[]
     name: string
   } | null>(null)
-  const [shareFileId, setShareFileId] = useState<string | null>(null)
 
   const listRename = useInlineRename({
     onSave: (rowId, name) => {
@@ -306,7 +303,7 @@ export function Files() {
   const shareModal = shareFile ? (
     <ShareModal
       open
-      onOpenChange={(open) => !open && setShareFileId(null)}
+      onOpenChange={(open) => !open && setFilesParams({ shareFileId: null })}
       workspaceId={workspaceId}
       fileId={shareFile.id}
       fileName={shareFile.name}
@@ -998,8 +995,8 @@ export function Files() {
 
   const handleShareSelected = useCallback(() => {
     const file = selectedFileRef.current
-    if (file) setShareFileId(file.id)
-  }, [])
+    if (file) setFilesParams({ shareFileId: file.id })
+  }, [setFilesParams])
 
   const handleBulkDelete = useCallback(() => {
     if (selectedFileIds.length === 0 && selectedFolderIds.length === 0) return
@@ -1247,9 +1244,9 @@ export function Files() {
 
   const handleContextMenuShare = useCallback(() => {
     const item = contextMenuItemRef.current
-    if (item?.kind === 'file') setShareFileId(item.file.id)
+    if (item?.kind === 'file') setFilesParams({ shareFileId: item.file.id })
     closeContextMenu()
-  }, [closeContextMenu])
+  }, [closeContextMenu, setFilesParams])
 
   const handleContextMenuDelete = useCallback(() => {
     const item = contextMenuItemRef.current