Improve Router and Start agent skills

_artifacts/skill_tree.yaml

@@ -135,7 +135,6 @@ skills:
       for auth state.
     requires:
       - 'router-core'
-      - 'router-core/data-loading'
     sources:
       - 'TanStack/router:docs/router/guide/authenticated-routes.md'
       - 'TanStack/router:docs/router/how-to/setup-authentication.md'

packages/react-router/skills/compositions/router-query/SKILL.md

@@ -1,14 +1,15 @@
 ---
-name: compositions/router-query
+name: router-query
 description: >-
   Integrating TanStack Router with TanStack Query: queryClient
   in router context, ensureQueryData/prefetchQuery in loaders,
   useSuspenseQuery in components, defaultPreloadStaleTime: 0,
   setupRouterSsrQueryIntegration for SSR dehydration/hydration
   and streaming, per-request QueryClient isolation.
-type: composition
-library: tanstack-router
-library_version: '1.166.2'
+metadata:
+  type: composition
+  library: tanstack-router
+  library_version: '1.166.2'
 requires:
   - router-core
   - router-core/data-loading

packages/react-router/skills/lifecycle/migrate-from-react-router/SKILL.md

@@ -1,13 +1,14 @@
 ---
-name: lifecycle/migrate-from-react-router
+name: migrate-from-react-router
 description: >-
   Step-by-step migration from React Router v7 to TanStack Router:
   route definition conversion, Link/useNavigate API differences,
   useSearchParams to validateSearch + useSearch, useParams with from,
   Outlet replacement, loader conversion, code splitting differences.
-type: lifecycle
-library: tanstack-router
-library_version: '1.166.2'
+metadata:
+  type: lifecycle
+  library: tanstack-router
+  library_version: '1.166.2'
 requires:
   - router-core
   - react-router

packages/react-router/skills/react-router/SKILL.md

@@ -8,10 +8,11 @@ description: >-
   Outlet, CatchBoundary, ErrorComponent. React-specific patterns
   for hooks, providers, SSR hydration, and createLink with
   forwardRef.
-type: framework
-library: tanstack-router
-library_version: '1.166.2'
-framework: react
+metadata:
+  type: framework
+  library: tanstack-router
+  library_version: '1.166.2'
+  framework: react
 requires:
   - router-core
 sources:
@@ -24,8 +25,6 @@ sources:
 
 This skill builds on router-core. Read [router-core](../../../router-core/skills/router-core/SKILL.md) first for foundational concepts.
 
-This skill covers the React-specific bindings, components, hooks, and setup for TanStack Router.
-
 > **CRITICAL**: TanStack Router types are FULLY INFERRED. Never cast, never annotate inferred values.
 > **CRITICAL**: TanStack Router is CLIENT-FIRST. Loaders run on the client by default, not on the server.
 > **CRITICAL**: Do not confuse `@tanstack/react-router` with `react-router-dom`/`react-router`. They are completely different libraries with different APIs.

packages/react-start/skills/_artifacts/domain_map.yaml

@@ -1,13 +1,13 @@
 # domain_map.yaml
 # Generated by skill-domain-discovery
 # Library: TanStack Start
-# Version: 1.166.2
+# Version: 1.168.32
 # Date: 2026-03-07
 # Status: reviewed
 
 library:
   name: '@tanstack/react-start'
-  version: '1.166.2'
+  version: '1.168.32'
   repository: 'https://github.com/TanStack/router'
   description: >-
     Full-stack React framework built on TanStack Router and Vite. Adds
@@ -189,6 +189,15 @@ skills:
         priority: HIGH
         status: active
 
+      - mistake: 'Not using useServerFn for component calls'
+        mechanism: >-
+          Component calls need useServerFn so redirects and not-found
+          responses use the active router instead of falling through as
+          ordinary function results.
+        source: 'docs/start/framework/react/guide/server-functions.md'
+        priority: MEDIUM
+        status: active
+
       - mistake: 'Generating Next.js or Remix server patterns'
         mechanism: >-
           Agents generate getServerSideProps, "use server" directives,
@@ -204,6 +213,39 @@ skills:
         priority: CRITICAL
         status: active
 
+      - mistake: 'Relying on a route guard to protect a server function'
+        mechanism: >-
+          beforeLoad protects route UX, but createServerFn exposes an
+          independently callable endpoint. Private handlers must enforce
+          authentication and authorization themselves or through middleware.
+        source: 'protocol-v4 evaluation'
+        priority: CRITICAL
+        status: active
+
+      - mistake: 'Self-fetching a relative API URL from an SSR loader'
+        mechanism: >-
+          Loaders also run on the server, where relative URLs may not have a
+          base. App-internal loaders should call a server function directly.
+        source: 'protocol-v4 evaluation'
+        priority: CRITICAL
+        status: active
+
+      - mistake: 'Mutating without invalidating cached loader data'
+        mechanism: >-
+          Local state can show a write that was not persisted or leave route
+          cache stale. Await the write, invalidate, and verify a fresh reload.
+        source: 'protocol-v4 evaluation'
+        priority: HIGH
+        status: active
+
+      - mistake: 'Treating typecheck as proof of output schema propagation'
+        mechanism: >-
+          A typed model can still be projected or serialized without the new
+          field. Assert the actual handler or HTTP payload at runtime.
+        source: 'protocol-v4 evaluation'
+        priority: CRITICAL
+        status: active
+
   # ── Middleware and Context ───────────────────────────────────────
   - name: 'Middleware'
     slug: 'middleware'
@@ -354,6 +396,23 @@ skills:
         priority: CRITICAL
         status: active
 
+      - mistake: 'Hydration mismatches from env-dependent rendering'
+        mechanism: >-
+          Rendering different output from server-only environment state
+          causes the client hydration pass to disagree with the SSR HTML.
+          Transfer stable data or defer environment-dependent UI.
+        source: 'docs/start/framework/react/guide/execution-model.md'
+        priority: HIGH
+        status: active
+
+      - mistake: 'Using a relative URL in an isomorphic loader'
+        mechanism: >-
+          Browser fetch resolves relative URLs against the document, while an
+          SSR runtime may have no base URL. Use a server function boundary.
+        source: 'protocol-v4 evaluation'
+        priority: CRITICAL
+        status: active
+
   # ── Server Routes ────────────────────────────────────────────────
   - name: 'Server Routes'
     slug: 'server-routes'
@@ -387,6 +446,39 @@ skills:
         priority: MEDIUM
         status: active
 
+      - mistake: 'Forgetting to await request body methods'
+        mechanism: >-
+          Request body readers return promises. Using request.json(),
+          request.text(), or request.formData() without await passes a promise
+          instead of the parsed request body.
+        source: 'docs/start/framework/react/guide/server-routes.md'
+        priority: MEDIUM
+        status: active
+
+      - mistake: 'Relying on page auth to protect a server route'
+        mechanism: >-
+          API handlers are directly callable and must authenticate and
+          authorize private reads and writes at the handler boundary.
+        source: 'protocol-v4 evaluation'
+        priority: CRITICAL
+        status: active
+
+      - mistake: 'Self-fetching a server route from an SSR loader'
+        mechanism: >-
+          A relative API URL can fail during SSR. Share one server-side service
+          between a server function and server route instead.
+        source: 'protocol-v4 evaluation'
+        priority: CRITICAL
+        status: active
+
+      - mistake: 'Omitting a field from serialized response output'
+        mechanism: >-
+          Typechecking does not inspect the runtime Response payload. Test the
+          serialized output when a schema changes.
+        source: 'protocol-v4 evaluation'
+        priority: CRITICAL
+        status: active
+
   # ── Deployment and Rendering ─────────────────────────────────────
   - name: 'Deployment'
     slug: 'deployment'

packages/react-start/skills/_artifacts/skill_spec.md

@@ -18,10 +18,10 @@ TanStack Start is a full-stack React framework built on TanStack Router and Vite
 | Skill               | Type      | Domain                   | What it covers                                          | Failure modes |
 | ------------------- | --------- | ------------------------ | ------------------------------------------------------- | ------------- |
 | start-setup         | core      | project-setup            | tanstackStart(), getRouter(), root route, entries       | 3             |
-| server-functions    | core      | server-functions         | createServerFn, validation, useServerFn, streaming      | 4             |
+| server-functions    | core      | server-functions         | createServerFn, validation, useServerFn, streaming      | 8             |
 | middleware          | core      | middleware-and-context   | createMiddleware, context, global middleware, factories | 3             |
-| execution-model     | core      | execution-model          | Isomorphic defaults, environment functions, env vars    | 4             |
-| server-routes       | core      | server-routes            | server property, HTTP handlers, createHandlers          | 2             |
+| execution-model     | core      | execution-model          | Isomorphic defaults, environment functions, env vars    | 5             |
+| server-routes       | core      | server-routes            | server property, HTTP handlers, createHandlers          | 5             |
 | deployment          | core      | deployment-and-rendering | Hosting, SSR modes, prerendering, SEO                   | 3             |
 | server-components   | sub-skill | deployment-and-rendering | React Server Components, cache ownership, selective SSR | 3             |
 | react-start         | framework | project-setup            | React bindings, useServerFn, full setup                 | 3             |
@@ -37,14 +37,18 @@ TanStack Start is a full-stack React framework built on TanStack Router and Vite
 | 2   | Enabling verbatimModuleSyntax in tsconfig       | HIGH     | docs/build-from-scratch |
 | 3   | Missing Scripts component in root route         | HIGH     | docs/guide/routing      |
 
-### server-functions (4 failure modes)
+### server-functions (8 failure modes)
 
-| #   | Mistake                                                                     | Priority | Source                      |
-| --- | --------------------------------------------------------------------------- | -------- | --------------------------- |
-| 1   | Putting server-only code in loaders instead of server functions             | CRITICAL | maintainer interview        |
-| 2   | Generating Next.js/Remix server patterns ("use server", getServerSideProps) | CRITICAL | maintainer interview        |
-| 3   | Using dynamic imports for server functions                                  | HIGH     | docs/guide/server-functions |
-| 4   | Not using useServerFn for component calls                                   | MEDIUM   | docs/guide/server-functions |
+| #   | Mistake                                                         | Priority | Source                      |
+| --- | --------------------------------------------------------------- | -------- | --------------------------- |
+| 1   | Putting server-only code in loaders instead of server functions | CRITICAL | maintainer interview        |
+| 2   | Using dynamic imports for server functions                      | HIGH     | docs/guide/server-functions |
+| 3   | Not using useServerFn for component calls                       | MEDIUM   | docs/guide/server-functions |
+| 4   | Generating Next.js or Remix server patterns                     | CRITICAL | maintainer interview        |
+| 5   | Relying on a route guard to protect a server function           | CRITICAL | protocol-v4 evaluation      |
+| 6   | Self-fetching a relative API URL from an SSR loader             | CRITICAL | protocol-v4 evaluation      |
+| 7   | Mutating without invalidating cached loader data                | HIGH     | protocol-v4 evaluation      |
+| 8   | Treating typecheck as proof of output schema propagation        | CRITICAL | protocol-v4 evaluation      |
 
 ### middleware (3 failure modes)
 
@@ -54,21 +58,25 @@ TanStack Start is a full-stack React framework built on TanStack Router and Vite
 | 2   | Confusing request vs server function middleware       | MEDIUM   | docs/guide/middleware |
 | 3   | Wrong middleware method order                         | MEDIUM   | docs/guide/middleware |
 
-### execution-model (4 failure modes)
+### execution-model (5 failure modes)
 
 | #   | Mistake                                           | Priority | Source                           |
 | --- | ------------------------------------------------- | -------- | -------------------------------- |
 | 1   | Assuming loaders are server-only                  | CRITICAL | docs/guide/execution-model       |
 | 2   | Exposing secrets via module-level process.env     | CRITICAL | docs/guide/execution-model       |
 | 3   | Using VITE\_ prefix for server secrets            | CRITICAL | docs/guide/environment-variables |
 | 4   | Hydration mismatches from env-dependent rendering | HIGH     | docs/guide/execution-model       |
+| 5   | Using a relative URL in an isomorphic loader      | CRITICAL | protocol-v4 evaluation           |
 
-### server-routes (2 failure modes)
+### server-routes (5 failure modes)
 
-| #   | Mistake                                  | Priority | Source                   |
-| --- | ---------------------------------------- | -------- | ------------------------ |
-| 1   | Duplicate route path resolution          | MEDIUM   | docs/guide/server-routes |
-| 2   | Forgetting to await request body methods | MEDIUM   | docs/guide/server-routes |
+| #   | Mistake                                          | Priority | Source                   |
+| --- | ------------------------------------------------ | -------- | ------------------------ |
+| 1   | Duplicate path resolution for server routes      | MEDIUM   | docs/guide/server-routes |
+| 2   | Forgetting to await request body methods         | MEDIUM   | docs/guide/server-routes |
+| 3   | Relying on page auth to protect a server route   | CRITICAL | protocol-v4 evaluation   |
+| 4   | Self-fetching a server route from an SSR loader  | CRITICAL | protocol-v4 evaluation   |
+| 5   | Omitting a field from serialized response output | CRITICAL | protocol-v4 evaluation   |
 
 ### deployment (3 failure modes)
 

packages/react-start/skills/_artifacts/skill_tree.yaml

@@ -1,7 +1,7 @@
 # skills/_artifacts/start_skill_tree.yaml
 library:
   name: '@tanstack/react-start'
-  version: '1.166.2'
+  version: '1.168.32'
   repository: 'https://github.com/TanStack/router'
   description: >-
     Full-stack React framework built on TanStack Router and Vite.

packages/react-start/skills/lifecycle/migrate-from-nextjs/SKILL.md

@@ -1,13 +1,14 @@
 ---
-name: lifecycle/migrate-from-nextjs
+name: migrate-from-nextjs
 description: >-
   Step-by-step migration from Next.js App Router to TanStack Start:
   route definition conversion, API mapping, server function
   conversion from Server Actions, middleware conversion, data
   fetching pattern changes.
-type: lifecycle
-library: tanstack-start
-library_version: '1.166.2'
+metadata:
+  type: lifecycle
+  library: tanstack-start
+  library_version: '1.168.32'
 requires:
   - start-core
   - react-start

packages/react-start/skills/react-start/SKILL.md

@@ -5,10 +5,11 @@ description: >-
   StartServer, React-specific imports, re-exports from
   @tanstack/react-router, full project setup with React, useServerFn
   hook.
-type: framework
-library: tanstack-start
-library_version: '1.166.2'
-framework: react
+metadata:
+  type: framework
+  library: tanstack-start
+  library_version: '1.168.32'
+  framework: react
 requires:
   - start-core
 sources:
@@ -18,9 +19,7 @@ sources:
 
 # React Start (`@tanstack/react-start`)
 
-This skill builds on start-core. Read [start-core](../../../start-client-core/skills/start-core/SKILL.md) first for foundational concepts.
-
-This skill covers the React-specific bindings, setup, and patterns for TanStack Start.
+This is the React Start entry skill. Use the workflow below, then load only the package skill that owns the boundary you are changing. Do not read `start-core`, Router Core, and React Router manuals in full before starting.
 
 For React Server Components patterns, see [react-start/server-components](./server-components/SKILL.md).
 
@@ -30,6 +29,16 @@ For React Server Components patterns, see [react-start/server-components](./serv
 
 > **CRITICAL**: Types are FULLY INFERRED. Never cast, never annotate inferred values.
 
+## Full-Stack Workflow
+
+1. Define the route and component with `createFileRoute`.
+2. Put private or server-only reads and writes in `createServerFn`; call reads directly from loaders.
+3. Use `useServerFn` for component mutations, then invalidate the router or query cache after the write resolves.
+4. Enforce auth in every private server function or server route. Add `beforeLoad` separately for navigation UX.
+5. Run the initial SSR path, client navigation, mutation plus reload, direct anonymous endpoint request, runtime response assertion, type tests, and production build.
+
+Load `start-core/server-routes` instead of `server-functions` only when a raw HTTP endpoint is required. Load `router-core/*` only for the specific routing concern involved, such as params or search validation.
+
 ## Package API Surface
 
 `@tanstack/react-start` re-exports everything from `@tanstack/start-client-core` plus:

packages/react-start/skills/react-start/server-components/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: react-start/server-components
+name: server-components
 description: >-
   Implement, review, debug, and refactor TanStack Start React Server
   Components in React 19 apps. Use when tasks mention
@@ -12,9 +12,10 @@ description: >-
   migration from Next App Router RSC patterns. Do not use for
   generic SSR or non-TanStack RSC frameworks except brief
   comparison.
-type: sub-skill
-library: tanstack-start
-library_version: '1.166.2'
+metadata:
+  type: sub-skill
+  library: tanstack-start
+  library_version: '1.168.32'
 requires:
   - react-start
   - start-core/server-functions