dev-booster 1.17.2 → 1.18.1

package/template/.devbooster/hub/knowledge/tanstack-patterns.md

@@ -0,0 +1,278 @@
+# TanStack Query Patterns
+
+> **Purpose:** Practical TanStack Query v5 patterns for correct caching, mutations, cancellation, SSR hydration, and `QueryClient` lifecycle.
+> **Primary official sources:** [Query keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) · [Query invalidation](https://tanstack.com/query/latest/docs/framework/react/guides/query-invalidation) · [Caching](https://tanstack.com/query/latest/docs/framework/react/guides/caching) · [SSR and hydration](https://tanstack.com/query/latest/docs/framework/react/guides/ssr) · [Optimistic updates](https://tanstack.com/query/latest/docs/framework/react/guides/optimistic-updates)
+
+## Project Convention Decision Rule
+
+Before applying this guidance, verify the installed versions, local rules, existing query and mutation hooks, query-key conventions, `QueryClient` lifecycle, configuration, and tests. Preserve a valid established project convention; do not replace it only because another documented approach is also valid. Use official sources to verify API behavior, compatibility, constraints, and migrations. Recommend a change only when the developer requests it or evidence shows the current approach is incompatible, unsafe, deprecated, broken, or responsible for a verified issue.
+
+---
+
+## Table of Contents
+
+1. [Use stable, complete query keys](#use-stable-complete-query-keys)
+2. [Invalidate affected queries after mutations](#invalidate-affected-queries-after-mutations)
+3. [Choose `staleTime` and `gcTime` for different concerns](#choose-staletime-and-gctime-for-different-concerns)
+4. [Prefetch and hydrate SSR data deliberately](#prefetch-and-hydrate-ssr-data-deliberately)
+5. [Write query functions that consume `AbortSignal`](#write-query-functions-that-consume-abortsignal)
+6. [Make mutation errors and optimistic rollbacks explicit](#make-mutation-errors-and-optimistic-rollbacks-explicit)
+7. [Create a stable `QueryClient`](#create-a-stable-queryclient)
+8. [Prefer Existing Query Ownership Over a Parallel Effect](#prefer-existing-query-ownership-over-a-parallel-effect)
+9. [Render Query States Deliberately](#render-query-states-deliberately)
+
+---
+
+## Use stable, complete query keys
+
+### Problem / symptom
+Different data is served from one cache entry, or a query fails to refetch when a parameter changes. Common causes are a missing parameter in `queryKey` or inconsistent key shapes across the codebase.
+
+### Fix
+Use a serializable array key that uniquely describes the returned data. Include every changing variable read by the query function. Object property order does not affect hashing; array item order does.
+
+```tsx
+const itemKeys = {
+  all: ['items'] as const,
+  list: (filters: { status?: string }) => ['items', { filters }] as const,
+  detail: (id: string) => ['items', id] as const,
+}
+
+useQuery({
+  queryKey: itemKeys.detail(id),
+  queryFn: () => fetchItem(id),
+})
+```
+
+A key factory is optional; the requirement is stable, complete, consistently shaped keys.
+
+### Verify first
+- Compare all variables used by `queryFn` with the `queryKey`.
+- Change each variable and confirm a distinct cache entry or expected refetch occurs.
+- Confirm list and detail keys support the invalidation scope that mutations require.
+
+*Source: [Query keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys)*
+
+---
+
+## Invalidate affected queries after mutations
+
+### Problem / symptom
+A mutation succeeds but visible data remains stale, or invalidation refetches unrelated data unnecessarily.
+
+### Fix
+On mutation success or settlement, invalidate the smallest key prefix that represents all data changed by the mutation. `invalidateQueries` marks matching queries stale and background-refetches matching active queries; invalidation overrides configured `staleTime`.
+
+```tsx
+const queryClient = useQueryClient()
+
+useMutation({
+  mutationFn: updateItem,
+  onSuccess: (_item, variables) =>
+    Promise.all([
+      queryClient.invalidateQueries({ queryKey: itemKeys.detail(variables.id) }),
+      queryClient.invalidateQueries({ queryKey: itemKeys.all }),
+    ]),
+})
+```
+
+Use `{ exact: true }` only when the mutation genuinely affects one exact key. If the mutation response completely and correctly represents a cached resource, `setQueryData` can update that specific entry instead of a refetch.
+
+### Verify first
+- List every query view affected by create, update, and delete paths.
+- Confirm the invalidation key matches each intended query and excludes unrelated ones.
+- Confirm the mutation waits for any required invalidation promise when pending state should include the refetch.
+
+*Source: [Query invalidation](https://tanstack.com/query/latest/docs/framework/react/guides/query-invalidation) · [Invalidation from mutations](https://tanstack.com/query/latest/docs/framework/react/guides/invalidations-from-mutations)*
+
+---
+
+## Choose `staleTime` and `gcTime` for different concerns
+
+### Problem / symptom
+`gcTime` is increased to stop refetching, or `staleTime` is increased to retain data for remounts. The result is an incorrect freshness policy or unexpected memory use.
+
+### Fix
+`staleTime` controls how long fetched data is considered fresh. `gcTime` controls how long an **inactive** query remains in cache before garbage collection. They are independent:
+
+| Setting | Controls | Default described by the docs |
+| --- | --- | --- |
+| `staleTime` | Freshness and eligibility for automatic refetch behavior | `0` (immediately stale) |
+| `gcTime` | Retention after the final observer unmounts | 5 minutes in the browser |
+
+Set `staleTime` from the acceptable age of the data, not from navigation frequency. Set `gcTime` from the value of retaining inactive data versus memory cost.
+
+### Verify first
+- Determine the maximum acceptable data age for each query before choosing `staleTime`.
+- Unmount and remount a query before and after `gcTime` to distinguish retention from freshness.
+- For SSR, note that default server `gcTime` is `Infinity`; do not set it to `0`, which can remove hydrated data before rendering completes.
+
+*Source: [Caching examples](https://tanstack.com/query/latest/docs/framework/react/guides/caching) · [SSR memory and staleness](https://tanstack.com/query/latest/docs/framework/react/guides/ssr#tips-tricks-and-caveats)*
+
+---
+
+## Prefetch and hydrate SSR data deliberately
+
+### Problem / symptom
+SSR markup renders data but the browser immediately fetches it again, displays different initial output, or a server cache leaks data between requests.
+
+### Fix
+For data required in initial markup, create a request-local `QueryClient` during the framework's preload/loader phase, `prefetchQuery` the required queries, `dehydrate` it, then render the client tree under `HydrationBoundary` with that state. The browser provider must create one stable client instance per application lifecycle. Set a nonzero `staleTime` when immediate background refetch after hydration is not desired.
+
+```tsx
+// Server preload phase
+const queryClient = new QueryClient()
+await queryClient.prefetchQuery({ queryKey: ['items'], queryFn: fetchItems })
+const dehydratedState = dehydrate(queryClient)
+
+// Rendered client tree
+<HydrationBoundary state={dehydratedState}>
+  <Items />
+</HydrationBoundary>
+```
+
+Use `fetchQuery` rather than `prefetchQuery` when server rendering must surface a failure for framework-level handling: `prefetchQuery` does not throw, and dehydration includes successful queries by default.
+
+### Verify first
+- Confirm the server prefetch key exactly matches the browser query key.
+- Confirm the dehydration payload is serialized safely by the framework and contains only data safe to deliver to the browser.
+- Test a cold request and a client-side navigation; measure whether critical data refetches according to the selected `staleTime`.
+
+*Source: [Server rendering and hydration](https://tanstack.com/query/latest/docs/framework/react/guides/ssr)*
+
+---
+
+## Write query functions that consume `AbortSignal`
+
+### Problem / symptom
+Superseded or unused requests continue consuming network and server resources, or manual cancellation does not cancel the underlying request.
+
+### Fix
+TanStack Query passes an `AbortSignal` to each query function. Pass it to `fetch` or a supported HTTP client. When the signal is consumed and aborted, the query promise is cancelled and the query state reverts to its previous state.
+
+```tsx
+useQuery({
+  queryKey: itemKeys.detail(id),
+  queryFn: async ({ signal }) => {
+    const response = await fetch(`/api/items/${id}`, { signal })
+    if (!response.ok) throw new Error('Unable to load item')
+    return response.json()
+  },
+})
+```
+
+By default, an unused query is not cancelled merely because it unmounts; its resolved result can still populate the cache. Consuming the signal opts the request into cancellation behavior.
+
+### Verify first
+- Confirm the HTTP library accepts and forwards `AbortSignal`.
+- Start a request, unmount or call `cancelQueries`, and inspect whether the underlying request is aborted.
+- Ensure UI and error reporting distinguish an intentional cancellation from an actionable failure when that distinction matters.
+
+*Source: [Query cancellation](https://tanstack.com/query/latest/docs/framework/react/guides/query-cancellation)*
+
+---
+
+## Make mutation errors and optimistic rollbacks explicit
+
+### Problem / symptom
+An optimistic cache update is overwritten by an in-flight refetch, or a failed mutation leaves incorrect optimistic data visible.
+
+### Fix
+Use the simplest option first: render a temporary mutation result from `variables` when only one view needs it. For a shared optimistic cache update, cancel relevant queries, snapshot the previous value, update the cache in `onMutate`, restore the snapshot in `onError`, and invalidate in `onSettled`.
+
+```tsx
+useMutation({
+  mutationFn: updateItem,
+  onMutate: async (nextItem, context) => {
+    await context.client.cancelQueries({ queryKey: itemKeys.detail(nextItem.id) })
+    const previous = context.client.getQueryData(itemKeys.detail(nextItem.id))
+    context.client.setQueryData(itemKeys.detail(nextItem.id), nextItem)
+    return { previous }
+  },
+  onError: (_error, item, snapshot, context) => {
+    context.client.setQueryData(itemKeys.detail(item.id), snapshot?.previous)
+  },
+  onSettled: (_data, _error, item, _snapshot, context) =>
+    context.client.invalidateQueries({ queryKey: itemKeys.detail(item.id) }),
+})
+```
+
+Return the snapshot from `onMutate`; TanStack Query passes it to `onError` and `onSettled`. Retain mutation error state for a visible recovery path when appropriate.
+
+### Verify first
+- Force the mutation to fail after the optimistic update and confirm the precise previous value is restored.
+- Test a refetch racing with the mutation; confirm `cancelQueries` prevents it from overwriting the optimistic state.
+- Test concurrent mutations against the same key before assuming a single snapshot is sufficient.
+
+*Source: [Optimistic updates](https://tanstack.com/query/latest/docs/framework/react/guides/optimistic-updates)*
+
+---
+
+## Create a stable `QueryClient`
+
+### Problem / symptom
+Cache data disappears on every render, subscriptions reset, or all requests share cache data during SSR.
+
+### Fix
+Create one `QueryClient` for the application lifecycle, not during every component render. In a React client component, initialize it lazily in state. For SSR, create a request-local client in the preload phase; do not place a request-serving cache at module scope.
+
+```tsx
+function App() {
+  const [queryClient] = React.useState(() => new QueryClient())
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      <Routes />
+    </QueryClientProvider>
+  )
+}
+```
+
+An async Server Component may create a new client because it runs once on the server. The official ESLint rule can detect the render-time recreation pattern.
+
+### Verify first
+- Re-render the provider component and confirm the `QueryClient` identity remains stable.
+- For SSR, make two isolated requests and confirm their dehydration payloads cannot contain each other's data.
+- Enable `@tanstack/query/stable-query-client` where the ESLint plugin is used.
+
+*Source: [Stable Query Client ESLint rule](https://tanstack.com/query/latest/docs/eslint/stable-query-client) · [SSR setup](https://tanstack.com/query/latest/docs/framework/react/guides/ssr#initial-setup)*
+
+---
+
+## Prefer Existing Query Ownership Over a Parallel Effect
+
+### Decision
+When a project already uses TanStack Query for a resource, the query hook owns that server state. Do not add a parallel `useEffect` fetch, duplicate local cache, or second query-key convention for the same resource.
+
+### Verify first
+- Locate existing query-key factories, query hooks, API clients, and mutation invalidation rules.
+- Reuse the closest existing hook when its contract matches the screen’s data need.
+- Create a new hook only when the query has a distinct key, inputs, response contract, or reuse boundary.
+- Keep local state for local UI concerns; do not mirror query data into local state without a specific interaction reason.
+
+This preserves cache coherence, loading semantics, invalidation, and developer familiarity. A plain Effect remains appropriate only when the project does not use a query layer for that boundary or when the work is not server-state ownership.
+
+*Sources: [TanStack Query — Important Defaults](https://tanstack.com/query/latest/docs/framework/react/guides/important-defaults) · [React — Fetching data with Effects](https://react.dev/reference/react/useEffect#fetching-data-with-effects)*
+
+---
+
+## Render Query States Deliberately
+
+### Decision
+A query result needs an intentional UI for pending, error, empty, and success states. Preserve any shared loading, retry, empty-state, and error components already used by comparable screens.
+
+### Example
+```tsx
+if (query.isPending) return <ItemsSkeleton />
+if (query.isError) return <ErrorState onRetry={() => query.refetch()} />
+if (query.data.length === 0) return <EmptyState />
+return <ItemList items={query.data} />
+```
+
+### Verify first
+- Use the status names and behavior documented for the installed TanStack Query version.
+- Keep stale data visible during a background refetch when that matches the existing experience; do not replace it with a full-screen spinner without intent.
+- Distinguish an empty successful response from a failed request.
+- Make retry behavior and user-facing error treatment match project conventions and API semantics.
+
+*Sources: [TanStack Query — Queries](https://tanstack.com/query/latest/docs/framework/react/guides/queries) · [TanStack Query — Background Fetching Indicators](https://tanstack.com/query/latest/docs/framework/react/guides/background-fetching-indicators)*

package/template/.devbooster/hub/knowledge/testing-patterns.md

@@ -0,0 +1,164 @@
+# 🧪 Testing Patterns
+
+> **Purpose:** Build reliable unit, integration, and browser test coverage with reproducible validation.
+> **Primary official sources:** [Vitest Guide](https://vitest.dev/guide/) · [Jest Configuration](https://jestjs.io/docs/configuration) · [Playwright Best Practices](https://playwright.dev/docs/best-practices) · [Playwright Locators](https://playwright.dev/docs/locators) · [Testing Library Guiding Principles](https://testing-library.com/docs/guiding-principles/)
+
+## Project Convention Decision Rule
+
+Before applying this guidance, verify the installed versions, local rules, test runner, existing fixtures and helpers, CI configuration, and tests. Preserve a valid established project convention; do not replace it only because another documented approach is also valid. Use official sources to verify API behavior, compatibility, constraints, and migrations. Recommend a change only when the developer requests it or evidence shows the current approach is incompatible, unsafe, deprecated, broken, or responsible for a verified issue.
+
+---
+
+## Table of Contents
+
+1. [Choose the Smallest Test Scope That Proves the Behavior](#choose-the-smallest-test-scope-that-proves-the-behavior)
+2. [Test Environment Does Not Match the Code](#test-environment-does-not-match-the-code)
+3. [Tests Depend on Time, Randomness, or Live Network State](#tests-depend-on-time-randomness-or-live-network-state)
+4. [Browser Tests Use Fragile Locators or Share State](#browser-tests-use-fragile-locators-or-share-state)
+5. [CI and Local Browser or Runtime Environments Differ](#ci-and-local-browser-or-runtime-environments-differ)
+6. [Validation Matrix](#validation-matrix)
+7. [Test Async UI States Through Observable Behavior](#test-async-ui-states-through-observable-behavior)
+
+---
+
+## Choose the Smallest Test Scope That Proves the Behavior
+
+### Problem
+Tests either duplicate implementation details in isolated units or use slow end-to-end flows for every behavior.
+
+### Verify first
+State the behavior and boundary being proved: pure logic, a component interaction, an API integration, or an essential user journey. A test’s scope should match the risk it is intended to detect.
+
+### Fix
+Use a practical test pyramid:
+
+| Scope | Best for | Avoid using it for |
+|---|---|---|
+| Unit | Pure functions, validation, reducers, formatting | Browser integration details |
+| Integration | Component behavior, module boundaries, request handling | Full deployment and browser compatibility |
+| End-to-end | Critical user journeys across real browser boundaries | Exhaustive branch coverage |
+
+Prefer assertions observable to users over internal implementation state. Keep a small set of high-value browser journeys and place most coverage below that layer.
+
+*Sources: [Testing Library — Guiding Principles](https://testing-library.com/docs/guiding-principles/), [Playwright — Best Practices](https://playwright.dev/docs/best-practices)*
+
+---
+
+## Test Environment Does Not Match the Code
+
+### Symptom
+Tests fail on `window`, `document`, storage, or layout APIs—or browser-oriented tests run in a slower environment without need.
+
+### Verify first
+Identify the APIs exercised by the test. Node is appropriate for server and pure logic. A DOM environment is required for code that accesses browser globals, but simulated DOM behavior is not equivalent to a real browser.
+
+### Fix
+Set the environment deliberately per project or test group. In Vitest, configure `environment` or an environment annotation; in Jest, select the appropriate `testEnvironment`. Use Playwright for behavior that depends on an actual browser engine, browser navigation, or real layout behavior.
+
+```ts
+// vitest.config.ts
+export default {
+  test: { environment: 'jsdom' },
+}
+```
+
+Verify the selected environment's version and supported APIs before adding arbitrary global mocks.
+
+*Sources: [Vitest — Environment](https://vitest.dev/guide/environment.html), [Jest — testEnvironment](https://jestjs.io/docs/configuration#testenvironment-string)*
+
+---
+
+## Tests Depend on Time, Randomness, or Live Network State
+
+### Symptom
+Tests are flaky, pass alone but fail in a suite, or fail only in CI.
+
+### Verify first
+Look for wall-clock time, timers, random IDs, locale/time zone, shared mutable state, and outgoing network calls. Treat each as an uncontrolled input until explicitly fixed or mocked.
+
+### Fix
+Control inputs at the test boundary:
+
+- Use fake timers only when the behavior is timer-driven; advance time intentionally and restore real timers after the test.
+- Inject or seed random values when identifiers affect assertions.
+- Mock network requests at the client boundary and assert both success and failure behavior; do not call live external services from ordinary tests.
+- Reset mocks, module state, storage, and environment changes between tests.
+
+When using fake timers with asynchronous code, follow the test runner's documented async timer APIs and verify pending work has settled before asserting.
+
+*Sources: [Vitest — Mocking Timers](https://vitest.dev/guide/mocking.html#timers), [Jest — Timer Mocks](https://jestjs.io/docs/timer-mocks), [Playwright — Network](https://playwright.dev/docs/network)*
+
+---
+
+## Browser Tests Use Fragile Locators or Share State
+
+### Symptom
+A Playwright test breaks after markup or styling changes, or passes/fails depending on test order.
+
+### Verify first
+Check whether the locator expresses user-visible meaning and whether the test starts with an independent account, storage state, data record, and browser context.
+
+### Fix
+Prefer Playwright’s user-facing locators: `getByRole`, `getByLabel`, `getByText`, and `getByTestId` when a stable test contract is needed. Avoid long CSS/XPath selectors tied to DOM structure. Rely on Playwright’s locator auto-waiting rather than arbitrary sleeps.
+
+Keep tests isolated: create unique data or reset it through supported setup/teardown, and avoid state carried from another test. Reuse authenticated storage state only when it is created and managed as a deliberate fixture.
+
+*Sources: [Playwright — Locators](https://playwright.dev/docs/locators), [Playwright — Test Isolation](https://playwright.dev/docs/browser-contexts), [Playwright — Best Practices](https://playwright.dev/docs/best-practices)*
+
+---
+
+## CI and Local Browser or Runtime Environments Differ
+
+### Symptom
+The suite passes locally but fails in CI, or only a particular browser fails.
+
+### Verify first
+Compare Node version, package-manager lockfile mode, operating system, browser version, environment variables, time zone/locale, and test command. Confirm whether CI runs the same browser projects and build artifact as local validation.
+
+### Fix
+Pin and declare the runtime expected by the toolchain, install from the lockfile in CI, and install the browser binaries required by the Playwright version in use. Run the same focused command locally before changing assertions. Treat a browser-specific failure as evidence to investigate, not as a reason to remove that browser project.
+
+*Sources: [Playwright — Continuous Integration](https://playwright.dev/docs/ci), [Node.js — Releases](https://nodejs.org/en/about/previous-releases)*
+
+---
+
+## Validation Matrix
+
+Run the narrowest relevant checks first, then the complete required matrix before merging:
+
+| Change type | Required validation |
+|---|---|
+| Pure logic or utility | Targeted unit test, typecheck |
+| Component behavior | Targeted component/integration test, typecheck, lint |
+| Request or state boundary | Success/failure integration tests, lint, typecheck, build |
+| User journey or routing | Targeted Playwright test against the intended build/runtime, lint, typecheck, build |
+| Toolchain or dependency change | Full test suite, lint, typecheck, production build, relevant browser tests |
+
+### Verify first
+Use the scripts and configuration that the repository actually defines. A passing test command does not imply that linting, type checking, or the production build passed, and a passing DOM simulation does not replace browser coverage.
+
+### Minimum final check
+1. Run affected tests.
+2. Run lint.
+3. Run typecheck.
+4. Run the production build.
+5. Run affected browser tests when user-visible flows or browser behavior changed.
+
+*Sources: [Vitest — CLI](https://vitest.dev/guide/cli), [Jest — CLI](https://jestjs.io/docs/cli), [Playwright — Test CLI](https://playwright.dev/docs/test-cli)*
+
+---
+
+## Test Async UI States Through Observable Behavior
+
+### Decision
+When a feature loads, mutates, retries, or fails, test the user-observable state transitions that the project exposes: pending feedback, success data, empty results, actionable errors, and recovery. Do not assert internal hook calls or implementation-only state unless that is the public contract of a dedicated unit.
+
+### Verify first
+- Reuse the project’s test setup, request-mocking layer, render helpers, and query-client fixture.
+- Cover the states the screen actually supports; do not invent loading/error behavior absent from the product requirement.
+- Await stable UI transitions with the test runner’s documented async utilities rather than arbitrary sleeps.
+- For mutation flows, test failure and recovery as well as success when the user can retry or when optimistic UI is used.
+
+Use component/integration tests for most async UI behavior. Add browser coverage when routing, real browser behavior, or a critical end-to-end path is the risk being addressed.
+
+*Sources: [Testing Library — Async Methods](https://testing-library.com/docs/dom-testing-library/api-async/) · [Testing Library — Guiding Principles](https://testing-library.com/docs/guiding-principles/) · [Playwright — Auto-waiting](https://playwright.dev/docs/actionability)*

package/template/.devbooster/hub/knowledge/trpc-patterns.md

@@ -0,0 +1,212 @@
+# tRPC Patterns
+
+> **Purpose:** Practical tRPC v11 patterns for secure procedure boundaries, end-to-end type integrity, and observable HTTP transport.
+> **Primary official sources:** [Context](https://trpc.io/docs/server/context) · [Procedures](https://trpc.io/docs/server/procedures) · [Error handling](https://trpc.io/docs/server/error-handling) · [HTTP batch link](https://trpc.io/docs/client/links/httpBatchLink) · [Type inference](https://trpc.io/docs/client/vanilla/infer-types)
+
+## Project Convention Decision Rule
+
+Before applying this guidance, verify the installed versions, local rules, existing router and procedure abstractions, transport configuration, error contracts, and tests. Preserve a valid established project convention; do not replace it only because another documented approach is also valid. Use official sources to verify API behavior, compatibility, constraints, and migrations. Recommend a change only when the developer requests it or evidence shows the current approach is incompatible, unsafe, deprecated, broken, or responsible for a verified issue.
+
+---
+
+## Table of Contents
+
+1. [Keep authentication and authorization at procedure boundaries](#keep-authentication-and-authorization-at-procedure-boundaries)
+2. [Validate every procedure input on the server](#validate-every-procedure-input-on-the-server)
+3. [Map expected failures to `TRPCError`](#map-expected-failures-to-trpcerror)
+4. [Preserve server-to-client type inference](#preserve-server-to-client-type-inference)
+5. [Organize routers around reusable primitives and modules](#organize-routers-around-reusable-primitives-and-modules)
+6. [Make batching and transport observable](#make-batching-and-transport-observable)
+7. [Keep tRPC packages version-aligned](#keep-trpc-packages-version-aligned)
+
+---
+
+## Keep authentication and authorization at procedure boundaries
+
+### Problem / symptom
+A resolver checks authentication inconsistently, or trusts a user or permission value supplied in procedure input. This makes a protected route easy to omit during future work and leaves the authenticated value nullable throughout protected resolvers.
+
+### Fix
+Build request-derived context once per HTTP request. Export named base procedures: `publicProcedure`, an authenticated procedure that rejects missing identity, and narrower authorization procedures when a route needs a validated scope. Middleware can refine context, so `ctx.user` is non-null in downstream resolvers.
+
+```ts
+import { initTRPC, TRPCError } from '@trpc/server'
+
+const t = initTRPC.context<Context>().create()
+export const router = t.router
+export const publicProcedure = t.procedure
+
+export const protectedProcedure = t.procedure.use(({ ctx, next }) => {
+  if (!ctx.user) throw new TRPCError({ code: 'UNAUTHORIZED' })
+  return next({ ctx: { user: ctx.user } })
+})
+```
+
+Use input to identify the target resource, then authorize that target using trusted context and server-side data. Do not treat an input role, account identifier, or permission flag as proof of authorization.
+
+### Verify first
+- Confirm `createContext` is attached to the HTTP handler; tRPC creates it once per request, including one shared context for a batched request.
+- Confirm protected procedures cannot be called without an authenticated context.
+- Test an authenticated identity that lacks access to the target resource and expect `FORBIDDEN`.
+
+*Source: [Context](https://trpc.io/docs/server/context) · [Reusable base procedures](https://trpc.io/docs/server/procedures#reusable-base-procedures)*
+
+---
+
+## Validate every procedure input on the server
+
+### Problem / symptom
+A TypeScript type is used as if it validates network input, or a resolver assumes the caller sent a valid ID, pagination value, or object shape.
+
+### Fix
+Add `.input(...)` to every procedure that accepts input. The parser receives untrusted `unknown` input and must return a validated value or throw. Use a supported schema library or a custom parser; keep authorization separate from shape validation.
+
+```ts
+import { z } from 'zod'
+
+const byIdInput = z.object({ id: z.string().min(1) })
+
+export const itemRouter = router({
+  byId: protectedProcedure
+    .input(byIdInput)
+    .query(({ input }) => findItem(input.id)),
+})
+```
+
+Validation types improve developer feedback; the runtime parser is the security boundary.
+
+### Verify first
+- Send malformed input directly to the transport, not only through the typed client.
+- Confirm the resolver is not entered when parsing fails.
+- Confirm limits and domain constraints needed by downstream services are included in the schema.
+
+*Source: [Input parsers](https://trpc.io/docs/quickstart#3-using-input-parser-to-validate-procedure-inputs)*
+
+---
+
+## Map expected failures to `TRPCError`
+
+### Problem / symptom
+Expected conditions are thrown as generic errors, producing misleading `INTERNAL_SERVER_ERROR` responses; or detailed internal failures and stacks reach consumers.
+
+### Fix
+Throw `TRPCError` for expected API outcomes and use its documented code to express the condition. Keep unexpected errors as internal failures, observe them in the adapter's `onError`, and expose a safe message. tRPC maps its error codes to HTTP statuses and omits stack traces by default in production.
+
+```ts
+if (!item) {
+  throw new TRPCError({ code: 'NOT_FOUND', message: 'Item not found' })
+}
+if (!canEdit(ctx.user, item)) {
+  throw new TRPCError({ code: 'FORBIDDEN' })
+}
+```
+
+Use `errorFormatter` only when the client needs a deliberate, safe extension to the error shape. Avoid returning raw database, provider, or stack details.
+
+### Verify first
+- Assert `UNAUTHORIZED`, `FORBIDDEN`, validation, and missing-resource paths separately.
+- Check the production error response has no stack trace or confidential cause.
+- Confirm `onError` records path, operation type, and a safe correlation identifier without logging secrets.
+
+*Source: [Error codes and error handling](https://trpc.io/docs/server/error-handling)*
+
+---
+
+## Preserve server-to-client type inference
+
+### Problem / symptom
+The client duplicates request/response interfaces, imports server runtime code, or loses autocomplete after routers are split.
+
+### Fix
+Export the root router value and its type from the server boundary. Import `AppRouter` with `import type` on the client and give it to the tRPC client or integration. Derive any shared input/output type with `inferRouterInputs` and `inferRouterOutputs` rather than handwritten duplicates.
+
+```ts
+// server/app-router.ts
+export const appRouter = router({ item: itemRouter })
+export type AppRouter = typeof appRouter
+
+// client/trpc.ts
+import { createTRPCClient } from '@trpc/client'
+import type { AppRouter } from '../server/app-router'
+
+export const trpc = createTRPCClient<AppRouter>({ links: [] })
+```
+
+Treat the router type as a compile-time contract, not runtime data. The client must still handle transport, authorization, and server validation failures.
+
+### Verify first
+- Type-check a valid and invalid procedure call at the client boundary.
+- Confirm the router is exported as `typeof appRouter`, not a separately maintained interface.
+- Confirm the cross-boundary import is type-only and does not bundle server-only runtime dependencies.
+
+*Source: [Quickstart: client type inference](https://trpc.io/docs/quickstart#2-type-inference--autocomplete) · [Inferring types](https://trpc.io/docs/client/vanilla/infer-types)*
+
+---
+
+## Organize routers around reusable primitives and modules
+
+### Problem / symptom
+One large router mixes initialization, transport setup, authorization logic, and unrelated procedures. Changes create circular imports or inconsistent procedure behavior.
+
+### Fix
+Initialize tRPC once in a dedicated module and export small primitives such as `router`, `publicProcedure`, and `protectedProcedure`. Define feature routers in separate modules, compose them into an `appRouter`, and mount that root router in the transport adapter. This keeps common behavior in base procedures and procedure ownership in feature modules.
+
+```ts
+// trpc.ts: initialization and reusable base procedures
+// item-router.ts: item procedures
+// app-router.ts: router({ item: itemRouter }) and AppRouter export
+// http.ts: adapter, appRouter, createContext, onError
+```
+
+### Verify first
+- Confirm there is a single `initTRPC...create()` initialization per server application.
+- Confirm router composition does not import the HTTP adapter back into feature routers.
+- Confirm common authentication behavior is inherited through base procedures, not copied per resolver.
+
+*Source: [Quickstart: recommended separation](https://trpc.io/docs/quickstart#installation) · [Reusable base procedures](https://trpc.io/docs/server/procedures#reusable-base-procedures)*
+
+---
+
+## Make batching and transport observable
+
+### Problem / symptom
+Requests appear slow or fail with URI/payload errors, but telemetry only shows an HTTP request and cannot identify the individual operations hidden inside a batch.
+
+### Fix
+`httpBatchLink` batches individual operations into one HTTP request. Instrument both layers: record operation path/type/duration/errors through tRPC error handling or links, and record HTTP status, batch size, payload/URL limits, and request timing at the transport boundary. Set compatible limits deliberately.
+
+```ts
+httpBatchLink({
+  url: '/trpc',
+  maxItems: 10,
+  maxURLLength: 2083,
+})
+
+// Configure the adapter with a matching or higher maxBatchSize.
+```
+
+A client `maxItems` value at or below the server `maxBatchSize` splits large batches before the server rejects them. If per-operation transport isolation is required, use `httpLink` instead of batch transport.
+
+### Verify first
+- Use concurrent calls and confirm the expected number of HTTP requests and operations per batch.
+- Exercise a batch above the configured limit; verify the client splits it rather than receiving a server rejection.
+- Inspect observability data for a single failed operation in a mixed batch.
+
+*Source: [HTTP batch link](https://trpc.io/docs/client/links/httpBatchLink) · [Adapter `onError`](https://trpc.io/docs/server/error-handling#handling-errors)*
+
+---
+
+## Keep tRPC packages version-aligned
+
+### Problem / symptom
+Client and server compile against different tRPC API generations, causing missing exports, incompatible types, or transport behavior that differs from the selected documentation.
+
+### Fix
+Review every installed `@trpc/*` package used by the server and client together during an upgrade. Keep their versions compatible with the same tRPC documentation generation, update lockfiles in the same change, and run type-checking across both boundaries. The current official documentation cited here is v11.
+
+### Verify first
+- List resolved versions of `@trpc/server`, `@trpc/client`, and any installed framework integration packages.
+- Confirm no duplicate incompatible tRPC versions are resolved where a shared type contract is expected.
+- Type-check server and client after dependency resolution, then exercise one query and one mutation over the configured transport.
+
+*Source: [tRPC v11 Quickstart](https://trpc.io/docs/quickstart) · [tRPC documentation](https://trpc.io/docs)*