@karedo-hq/agents 0.1.1 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karedo-hq/agents",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Centralized agent skills, rules, and commands for our engineering team",
   "type": "module",
   "bin": {

package/rules/web/{api-layer.mdc → data-fetching-and-server-actions.mdc}

@@ -1,7 +1,8 @@
 ---
-description: How to create data-fetching functions and server actions on the frontend.
+description: How to handle frontend data-fetching and actions.
 alwaysApply: false
 ---
+
 # API Layer Patterns
 
 ## File Organization
@@ -56,11 +57,42 @@ headers: {
 
 ---
 
-## Client-Side Fetching
+## Data Fetching Strategy
+
+**Rule:** Server-first for page-level data; React Query hooks for nested interactive data.
+
+### Server-Side (Default)
+
+- Pages, tables, list views → fetch in RSC with URL-based pagination
+- Keeps payloads explicit and server rendering deterministic
+- Use `preparePaginationParams(dto)` for query string construction
+
+### Client-Side (Nested Interactive Components)
+
+- Comboboxes, dialogs, embedded forms/pickers → don't prop-drill giant lists
+- Create `useX` / `useInfiniteX` hooks in feature's `lib/hooks/`
+- Wrap `useQuery` / `useInfiniteQuery` from `@tanstack/react-query`
+- Handle pagination client-side (infinite scroll, search-as-you-type)
+- Use debounced search for text input filtering
+- Never use `useEffect(() => fetch().then(), [])` pattern
+
+### Anti-Pattern: MAX_QUERY_LIMIT
+
+Do NOT use `limit: MAX_QUERY_LIMIT` to feed dropdowns/comboboxes with "all" data.
+
+**Problems:**
+
+- Huge payloads for data the UI only partially needs
+- More memory + CPU on both backend and browser
+- Slower server renders / bigger RSC waterfalls
+- Worse UX for forms/dialogs that block on heavy lists
+
+**Signal to refactor:** If you see `MAX_QUERY_LIMIT` in a query feeding a nested UI selector, convert it to a React Query hook with pagination.
+
+**Examples:**
 
-- Use react-query for automatic request deduplication on client components.
-- Never use `useEffect(() => fetch().then(), [])` pattern.
-- Create query hooks when server props are impractical for nested client components.
+- `app/dashboard/contacts/lib/hooks/use-organization-contacts.ts` — hook pattern with `useInfiniteQuery`
+- `app/dashboard/clients/components/update-client-health-insurance-form.tsx` — combobox consuming the hook with infinite scroll
 
 ---