{"owner":"Kiranism","repo":"next-shadcn-dashboard-starter","hasSkills":true,"totalSkillsCount":234,"totalTokensCount":197706,"categories":["anthropic-skill","root-instruction","claude-rule"],"hasMcp":false,"mcpConfig":null,"found":[".agents/skills/kiranism-shadcn-dashboard/SKILL.md",".agents/skills/kiranism-shadcn-dashboard/references/charts-guide.md",".agents/skills/kiranism-shadcn-dashboard/references/forms-guide.md",".agents/skills/kiranism-shadcn-dashboard/references/mock-api-guide.md",".agents/skills/kiranism-shadcn-dashboard/references/query-abstractions.md",".agents/skills/kiranism-shadcn-dashboard/references/theming-guide.md",".agents/skills/next-best-practices/SKILL.md",".agents/skills/next-best-practices/async-patterns.md",".agents/skills/next-best-practices/bundling.md",".agents/skills/next-best-practices/data-patterns.md",".agents/skills/next-best-practices/debug-tricks.md",".agents/skills/next-best-practices/directives.md",".agents/skills/next-best-practices/error-handling.md",".agents/skills/next-best-practices/file-conventions.md",".agents/skills/next-best-practices/font.md",".agents/skills/next-best-practices/functions.md",".agents/skills/next-best-practices/hydration-error.md",".agents/skills/next-best-practices/image.md",".agents/skills/next-best-practices/metadata.md",".agents/skills/next-best-practices/parallel-routes.md",".agents/skills/next-best-practices/route-handlers.md",".agents/skills/next-best-practices/rsc-boundaries.md",".agents/skills/next-best-practices/runtime-selection.md",".agents/skills/next-best-practices/scripts.md",".agents/skills/next-best-practices/self-hosting.md",".agents/skills/next-best-practices/suspense-boundaries.md",".agents/skills/shadcn/SKILL.md",".agents/skills/shadcn/cli.md",".agents/skills/shadcn/customization.md",".agents/skills/shadcn/evals/evals.json",".agents/skills/shadcn/mcp.md",".agents/skills/shadcn/registry.md",".agents/skills/shadcn/rules/base-vs-radix.md",".agents/skills/shadcn/rules/chat.md",".agents/skills/shadcn/rules/composition.md",".agents/skills/shadcn/rules/forms.md",".agents/skills/shadcn/rules/icons.md",".agents/skills/shadcn/rules/styling.md",".agents/skills/tanstack-form/SKILL.md",".agents/skills/tanstack-query/SKILL.md",".agents/skills/tanstack-query/resources/cache-strategies.md",".agents/skills/tanstack-query/resources/data-fetching.md",".agents/skills/tanstack-query/resources/mutation-patterns.md",".agents/skills/tanstack-query/skill-rules-fragment.json",".agents/skills/vercel-composition-patterns/AGENTS.md",".agents/skills/vercel-composition-patterns/README.md",".agents/skills/vercel-composition-patterns/SKILL.md",".agents/skills/vercel-composition-patterns/rules/_sections.md",".agents/skills/vercel-composition-patterns/rules/_template.md",".agents/skills/vercel-composition-patterns/rules/architecture-avoid-boolean-props.md",".agents/skills/vercel-composition-patterns/rules/architecture-compound-components.md",".agents/skills/vercel-composition-patterns/rules/patterns-children-over-render-props.md",".agents/skills/vercel-composition-patterns/rules/patterns-explicit-variants.md",".agents/skills/vercel-composition-patterns/rules/react19-no-forwardref.md",".agents/skills/vercel-composition-patterns/rules/state-context-interface.md",".agents/skills/vercel-composition-patterns/rules/state-decouple-implementation.md",".agents/skills/vercel-composition-patterns/rules/state-lift-state.md",".agents/skills/vercel-react-best-practices/AGENTS.md",".agents/skills/vercel-react-best-practices/README.md",".agents/skills/vercel-react-best-practices/SKILL.md",".agents/skills/vercel-react-best-practices/rules/_sections.md",".agents/skills/vercel-react-best-practices/rules/_template.md",".agents/skills/vercel-react-best-practices/rules/advanced-event-handler-refs.md",".agents/skills/vercel-react-best-practices/rules/advanced-init-once.md",".agents/skills/vercel-react-best-practices/rules/advanced-use-latest.md",".agents/skills/vercel-react-best-practices/rules/async-api-routes.md",".agents/skills/vercel-react-best-practices/rules/async-defer-await.md",".agents/skills/vercel-react-best-practices/rules/async-dependencies.md",".agents/skills/vercel-react-best-practices/rules/async-parallel.md",".agents/skills/vercel-react-best-practices/rules/async-suspense-boundaries.md",".agents/skills/vercel-react-best-practices/rules/bundle-barrel-imports.md",".agents/skills/vercel-react-best-practices/rules/bundle-conditional.md",".agents/skills/vercel-react-best-practices/rules/bundle-defer-third-party.md",".agents/skills/vercel-react-best-practices/rules/bundle-dynamic-imports.md",".agents/skills/vercel-react-best-practices/rules/bundle-preload.md",".agents/skills/vercel-react-best-practices/rules/client-event-listeners.md",".agents/skills/vercel-react-best-practices/rules/client-localstorage-schema.md",".agents/skills/vercel-react-best-practices/rules/client-passive-event-listeners.md",".agents/skills/vercel-react-best-practices/rules/client-swr-dedup.md",".agents/skills/vercel-react-best-practices/rules/js-batch-dom-css.md",".agents/skills/vercel-react-best-practices/rules/js-cache-function-results.md",".agents/skills/vercel-react-best-practices/rules/js-cache-property-access.md",".agents/skills/vercel-react-best-practices/rules/js-cache-storage.md",".agents/skills/vercel-react-best-practices/rules/js-combine-iterations.md",".agents/skills/vercel-react-best-practices/rules/js-early-exit.md",".agents/skills/vercel-react-best-practices/rules/js-flatmap-filter.md",".agents/skills/vercel-react-best-practices/rules/js-hoist-regexp.md",".agents/skills/vercel-react-best-practices/rules/js-index-maps.md",".agents/skills/vercel-react-best-practices/rules/js-length-check-first.md",".agents/skills/vercel-react-best-practices/rules/js-min-max-loop.md",".agents/skills/vercel-react-best-practices/rules/js-set-map-lookups.md",".agents/skills/vercel-react-best-practices/rules/js-tosorted-immutable.md",".agents/skills/vercel-react-best-practices/rules/rendering-activity.md",".agents/skills/vercel-react-best-practices/rules/rendering-animate-svg-wrapper.md",".agents/skills/vercel-react-best-practices/rules/rendering-conditional-render.md",".agents/skills/vercel-react-best-practices/rules/rendering-content-visibility.md",".agents/skills/vercel-react-best-practices/rules/rendering-hoist-jsx.md",".agents/skills/vercel-react-best-practices/rules/rendering-hydration-no-flicker.md",".agents/skills/vercel-react-best-practices/rules/rendering-hydration-suppress-warning.md",".agents/skills/vercel-react-best-practices/rules/rendering-resource-hints.md",".agents/skills/vercel-react-best-practices/rules/rendering-script-defer-async.md",".agents/skills/vercel-react-best-practices/rules/rendering-svg-precision.md",".agents/skills/vercel-react-best-practices/rules/rendering-usetransition-loading.md",".agents/skills/vercel-react-best-practices/rules/rerender-defer-reads.md",".agents/skills/vercel-react-best-practices/rules/rerender-dependencies.md",".agents/skills/vercel-react-best-practices/rules/rerender-derived-state-no-effect.md",".agents/skills/vercel-react-best-practices/rules/rerender-derived-state.md",".agents/skills/vercel-react-best-practices/rules/rerender-functional-setstate.md",".agents/skills/vercel-react-best-practices/rules/rerender-lazy-state-init.md",".agents/skills/vercel-react-best-practices/rules/rerender-memo-with-default-value.md",".agents/skills/vercel-react-best-practices/rules/rerender-memo.md",".agents/skills/vercel-react-best-practices/rules/rerender-move-effect-to-event.md",".agents/skills/vercel-react-best-practices/rules/rerender-no-inline-components.md",".agents/skills/vercel-react-best-practices/rules/rerender-simple-expression-in-memo.md",".agents/skills/vercel-react-best-practices/rules/rerender-split-combined-hooks.md",".agents/skills/vercel-react-best-practices/rules/rerender-transitions.md",".agents/skills/vercel-react-best-practices/rules/rerender-use-deferred-value.md",".agents/skills/vercel-react-best-practices/rules/rerender-use-ref-transient-values.md",".agents/skills/vercel-react-best-practices/rules/server-after-nonblocking.md",".agents/skills/vercel-react-best-practices/rules/server-auth-actions.md",".agents/skills/vercel-react-best-practices/rules/server-cache-lru.md",".agents/skills/vercel-react-best-practices/rules/server-cache-react.md",".agents/skills/vercel-react-best-practices/rules/server-dedup-props.md",".agents/skills/vercel-react-best-practices/rules/server-hoist-static-io.md",".agents/skills/vercel-react-best-practices/rules/server-parallel-fetching.md",".agents/skills/vercel-react-best-practices/rules/server-serialization.md",".agents/skills/web-design-guidelines/SKILL.md",".claude/skills/kiranism-shadcn-dashboard/SKILL.md",".claude/skills/kiranism-shadcn-dashboard/references/theming-guide.md",".claude/skills/next-best-practices/SKILL.md",".claude/skills/next-best-practices/async-patterns.md",".claude/skills/next-best-practices/bundling.md",".claude/skills/next-best-practices/data-patterns.md",".claude/skills/next-best-practices/debug-tricks.md",".claude/skills/next-best-practices/directives.md",".claude/skills/next-best-practices/error-handling.md",".claude/skills/next-best-practices/file-conventions.md",".claude/skills/next-best-practices/font.md",".claude/skills/next-best-practices/functions.md",".claude/skills/next-best-practices/hydration-error.md",".claude/skills/next-best-practices/image.md",".claude/skills/next-best-practices/metadata.md",".claude/skills/next-best-practices/parallel-routes.md",".claude/skills/next-best-practices/route-handlers.md",".claude/skills/next-best-practices/rsc-boundaries.md",".claude/skills/next-best-practices/runtime-selection.md",".claude/skills/next-best-practices/scripts.md",".claude/skills/next-best-practices/self-hosting.md",".claude/skills/next-best-practices/suspense-boundaries.md",".claude/skills/vercel-composition-patterns/AGENTS.md",".claude/skills/vercel-composition-patterns/README.md",".claude/skills/vercel-composition-patterns/SKILL.md",".claude/skills/vercel-composition-patterns/rules/_sections.md",".claude/skills/vercel-composition-patterns/rules/_template.md",".claude/skills/vercel-composition-patterns/rules/architecture-avoid-boolean-props.md",".claude/skills/vercel-composition-patterns/rules/architecture-compound-components.md",".claude/skills/vercel-composition-patterns/rules/patterns-children-over-render-props.md",".claude/skills/vercel-composition-patterns/rules/patterns-explicit-variants.md",".claude/skills/vercel-composition-patterns/rules/react19-no-forwardref.md",".claude/skills/vercel-composition-patterns/rules/state-context-interface.md",".claude/skills/vercel-composition-patterns/rules/state-decouple-implementation.md",".claude/skills/vercel-composition-patterns/rules/state-lift-state.md",".claude/skills/vercel-react-best-practices/AGENTS.md",".claude/skills/vercel-react-best-practices/README.md",".claude/skills/vercel-react-best-practices/SKILL.md",".claude/skills/vercel-react-best-practices/rules/_sections.md",".claude/skills/vercel-react-best-practices/rules/_template.md",".claude/skills/vercel-react-best-practices/rules/advanced-event-handler-refs.md",".claude/skills/vercel-react-best-practices/rules/advanced-init-once.md",".claude/skills/vercel-react-best-practices/rules/advanced-use-latest.md",".claude/skills/vercel-react-best-practices/rules/async-api-routes.md",".claude/skills/vercel-react-best-practices/rules/async-defer-await.md",".claude/skills/vercel-react-best-practices/rules/async-dependencies.md",".claude/skills/vercel-react-best-practices/rules/async-parallel.md",".claude/skills/vercel-react-best-practices/rules/async-suspense-boundaries.md",".claude/skills/vercel-react-best-practices/rules/bundle-barrel-imports.md",".claude/skills/vercel-react-best-practices/rules/bundle-conditional.md",".claude/skills/vercel-react-best-practices/rules/bundle-defer-third-party.md",".claude/skills/vercel-react-best-practices/rules/bundle-dynamic-imports.md",".claude/skills/vercel-react-best-practices/rules/bundle-preload.md",".claude/skills/vercel-react-best-practices/rules/client-event-listeners.md",".claude/skills/vercel-react-best-practices/rules/client-localstorage-schema.md",".claude/skills/vercel-react-best-practices/rules/client-passive-event-listeners.md",".claude/skills/vercel-react-best-practices/rules/client-swr-dedup.md",".claude/skills/vercel-react-best-practices/rules/js-batch-dom-css.md",".claude/skills/vercel-react-best-practices/rules/js-cache-function-results.md",".claude/skills/vercel-react-best-practices/rules/js-cache-property-access.md",".claude/skills/vercel-react-best-practices/rules/js-cache-storage.md",".claude/skills/vercel-react-best-practices/rules/js-combine-iterations.md",".claude/skills/vercel-react-best-practices/rules/js-early-exit.md",".claude/skills/vercel-react-best-practices/rules/js-flatmap-filter.md",".claude/skills/vercel-react-best-practices/rules/js-hoist-regexp.md",".claude/skills/vercel-react-best-practices/rules/js-index-maps.md",".claude/skills/vercel-react-best-practices/rules/js-length-check-first.md",".claude/skills/vercel-react-best-practices/rules/js-min-max-loop.md",".claude/skills/vercel-react-best-practices/rules/js-set-map-lookups.md",".claude/skills/vercel-react-best-practices/rules/js-tosorted-immutable.md",".claude/skills/vercel-react-best-practices/rules/rendering-activity.md",".claude/skills/vercel-react-best-practices/rules/rendering-animate-svg-wrapper.md",".claude/skills/vercel-react-best-practices/rules/rendering-conditional-render.md",".claude/skills/vercel-react-best-practices/rules/rendering-content-visibility.md",".claude/skills/vercel-react-best-practices/rules/rendering-hoist-jsx.md",".claude/skills/vercel-react-best-practices/rules/rendering-hydration-no-flicker.md",".claude/skills/vercel-react-best-practices/rules/rendering-hydration-suppress-warning.md",".claude/skills/vercel-react-best-practices/rules/rendering-resource-hints.md",".claude/skills/vercel-react-best-practices/rules/rendering-script-defer-async.md",".claude/skills/vercel-react-best-practices/rules/rendering-svg-precision.md",".claude/skills/vercel-react-best-practices/rules/rendering-usetransition-loading.md",".claude/skills/vercel-react-best-practices/rules/rerender-defer-reads.md",".claude/skills/vercel-react-best-practices/rules/rerender-dependencies.md",".claude/skills/vercel-react-best-practices/rules/rerender-derived-state-no-effect.md",".claude/skills/vercel-react-best-practices/rules/rerender-derived-state.md",".claude/skills/vercel-react-best-practices/rules/rerender-functional-setstate.md",".claude/skills/vercel-react-best-practices/rules/rerender-lazy-state-init.md",".claude/skills/vercel-react-best-practices/rules/rerender-memo-with-default-value.md",".claude/skills/vercel-react-best-practices/rules/rerender-memo.md",".claude/skills/vercel-react-best-practices/rules/rerender-move-effect-to-event.md",".claude/skills/vercel-react-best-practices/rules/rerender-no-inline-components.md",".claude/skills/vercel-react-best-practices/rules/rerender-simple-expression-in-memo.md",".claude/skills/vercel-react-best-practices/rules/rerender-split-combined-hooks.md",".claude/skills/vercel-react-best-practices/rules/rerender-transitions.md",".claude/skills/vercel-react-best-practices/rules/rerender-use-deferred-value.md",".claude/skills/vercel-react-best-practices/rules/rerender-use-ref-transient-values.md",".claude/skills/vercel-react-best-practices/rules/server-after-nonblocking.md",".claude/skills/vercel-react-best-practices/rules/server-auth-actions.md",".claude/skills/vercel-react-best-practices/rules/server-cache-lru.md",".claude/skills/vercel-react-best-practices/rules/server-cache-react.md",".claude/skills/vercel-react-best-practices/rules/server-dedup-props.md",".claude/skills/vercel-react-best-practices/rules/server-hoist-static-io.md",".claude/skills/vercel-react-best-practices/rules/server-parallel-fetching.md",".claude/skills/vercel-react-best-practices/rules/server-serialization.md",".claude/skills/web-design-guidelines/SKILL.md","AGENTS.md","CLAUDE.md"],"skills":{".agents/skills/kiranism-shadcn-dashboard/SKILL.md":"---\nname: kiranism-shadcn-dashboard\ndescription: |\n Guide for building features, pages, tables, forms, themes, and navigation in this Next.js 16 shadcn dashboard template. Use this skill whenever the user wants to add a new page, create a feature module, build a data table, add a form, configure navigation items, add a theme, set up RBAC access control, or work with the dashboard's patterns and conventions. Also triggers when adding routes under /dashboard, working with Clerk auth/orgs/billing, creating mock APIs, or modifying the sidebar. Even if the user doesn't mention \"dashboard\" explicitly — if they're adding UI, pages, or features to this project, use this skill.\n---\n\n# Dashboard Development Guide\n\nThis skill encodes the exact patterns and conventions used in this Next.js 16 + shadcn/ui admin dashboard template.\n\n## Quick Reference: What Goes Where\n\n| Task | Location |\n| --------------------- | --------------------------------------- |\n| New page | `src/app/dashboard//page.tsx` |\n| New feature module | `src/features//` |\n| Feature components | `src/features//components/` |\n| API types | `src/features//api/types.ts` |\n| Service layer | `src/features//api/service.ts` |\n| Query options | `src/features//api/queries.ts` |\n| Mutation options | `src/features//api/mutations.ts` |\n| Zod schemas | `src/features//schemas/.ts` |\n| Filter/select options | `src/features//constants/` |\n| Nav config | `src/config/nav-config.ts` |\n| Types | `src/types/index.ts` |\n| Mock data | `src/constants/mock-api-.ts` |\n| Search params | `src/lib/searchparams.ts` |\n| Query client | `src/lib/query-client.ts` |\n| Theme CSS | `src/styles/themes/.css` |\n| Theme registry | `src/components/themes/theme.config.ts` |\n| Custom hook | `src/hooks/` |\n| Icons registry | `src/components/icons.tsx` |\n\n---\n\n## Adding a New Feature (End-to-End)\n\nWhen a user asks to add a feature (e.g., \"add an orders page\"), follow these steps in order. Each step below shows the minimal pattern — see reference files for full templates.\n\n### Step 1: Mock API (`src/constants/mock-api-.ts`)\n\nSee [references/mock-api-guide.md](references/mock-api-guide.md) for the complete template. Key structure:\n\n```tsx\nimport { faker } from '@faker-js/faker';\nimport { matchSorter } from 'match-sorter';\nimport { delay } from './mock-api';\n\nexport type Order = {\n id: number;\n customer: string;\n status: string;\n total: number;\n created_at: string;\n updated_at: string;\n};\n\nexport const fakeOrders = {\n records: [] as Order[],\n initialize() {\n /* generate with faker */\n },\n async getOrders({ page, limit, search, sort }) {\n /* filter, sort, paginate, return { items, total_items } */\n },\n async getOrderById(id: number) {\n /* find by id */\n },\n async createOrder(data) {\n /* push to records */\n },\n async updateOrder(id, data) {\n /* merge into record */\n },\n async deleteOrder(id) {\n /* filter out */\n }\n};\nfakeOrders.initialize();\n```\n\nEvery method should call `await delay(800)` to simulate network latency. Use `matchSorter` for search. Return `{ items, total_items }` from list methods.\n\n### Step 2: API Layer (`src/features//api/`)\n\nEach feature has 4 API files: **types** → **service** → **queries** → **mutations**.\n\n**Types** (`api/types.ts`) — re-export the entity type from mock API, plus filter/response/payload types:\n\n```tsx\nexport type { Order } from '@/constants/mock-api-orders';\nexport type OrderFilters = { page?: number; limit?: number; search?: string; sort?: string };\nexport type OrdersResponse = { items: Order[]; total_items: number };\nexport type OrderMutationPayload = { customer: string; status: string; total: number };\n```\n\n**Service** (`api/service.ts`) — data access layer. One exported function per operation:\n\n```tsx\nimport { fakeOrders } from '@/constants/mock-api-orders';\nimport type { OrderFilters, OrdersResponse, OrderMutationPayload } from './types';\n\nexport async function getOrders(filters: OrderFilters): Promise {\n return fakeOrders.getOrders(filters);\n}\nexport async function getOrderById(id: number) {\n return fakeOrders.getOrderById(id);\n}\nexport async function createOrder(data: OrderMutationPayload) {\n return fakeOrders.createOrder(data);\n}\nexport async function updateOrder(id: number, data: OrderMutationPayload) {\n return fakeOrders.updateOrder(id, data);\n}\nexport async function deleteOrder(id: number) {\n return fakeOrders.deleteOrder(id);\n}\n```\n\n**Queries** (`api/queries.ts`) — query key factory + query options:\n\n```tsx\nimport { queryOptions } from '@tanstack/react-query';\nimport { getOrders, getOrderById } from './service';\nimport type { Order, OrderFilters } from './types';\n\nexport type { Order };\n\nexport const orderKeys = {\n all: ['orders'] as const,\n list: (filters: OrderFilters) => [...orderKeys.all, 'list', filters] as const,\n detail: (id: number) => [...orderKeys.all, 'detail', id] as const\n};\n\nexport const ordersQueryOptions = (filters: OrderFilters) =>\n queryOptions({\n queryKey: orderKeys.list(filters),\n queryFn: () => getOrders(filters)\n });\n\nexport const orderByIdOptions = (id: number) =>\n queryOptions({\n queryKey: orderKeys.detail(id),\n queryFn: () => getOrderById(id)\n });\n```\n\n**Mutations** (`api/mutations.ts`) — use `mutationOptions` + `getQueryClient()` (not custom hooks with `useQueryClient()`):\n\n```tsx\nimport { mutationOptions } from '@tanstack/react-query';\nimport { getQueryClient } from '@/lib/query-client';\nimport { createOrder, updateOrder, deleteOrder } from './service';\nimport { orderKeys } from './queries';\nimport type { OrderMutationPayload } from './types';\n\nexport const createOrderMutation = mutationOptions({\n mutationFn: (data: OrderMutationPayload) => createOrder(data),\n onSuccess: () => {\n getQueryClient().invalidateQueries({ queryKey: orderKeys.all });\n }\n});\n\nexport const updateOrderMutation = mutationOptions({\n mutationFn: ({ id, values }: { id: number; values: OrderMutationPayload }) =>\n updateOrder(id, values),\n onSuccess: () => {\n getQueryClient().invalidateQueries({ queryKey: orderKeys.all });\n }\n});\n\nexport const deleteOrderMutation = mutationOptions({\n mutationFn: (id: number) => deleteOrder(id),\n onSuccess: () => {\n getQueryClient().invalidateQueries({ queryKey: orderKeys.all });\n }\n});\n```\n\n`mutationOptions` is the right abstraction because it works outside React (event handlers, tests, utilities), composes via spread at the call site, and uses `getQueryClient()` which handles both SSR (fresh per request) and client (singleton) correctly. See [references/query-abstractions.md](references/query-abstractions.md) for the full rationale.\n\n### Step 3: Zod Schema (`src/features//schemas/.ts`)\n\n```tsx\nimport { z } from 'zod';\n\nexport const orderSchema = z.object({\n customer: z.string().min(2, 'Customer name must be at least 2 characters'),\n status: z.string().min(1, 'Please select a status'),\n total: z.number({ message: 'Total is required' })\n});\n\nexport type OrderFormValues = z.infer;\n```\n\n### Step 4: Feature Components\n\nCreate `src/features//components/` with:\n\n**Listing page** (server component — `-listing.tsx`):\n\n```tsx\nimport { HydrationBoundary, dehydrate } from '@tanstack/react-query';\nimport { getQueryClient } from '@/lib/query-client';\nimport { searchParamsCache } from '@/lib/searchparams';\nimport { ordersQueryOptions } from '../api/queries';\nimport { OrderTable, OrderTableSkeleton } from './orders-table';\nimport { Suspense } from 'react';\n\nexport default function OrderListingPage() {\n const page = searchParamsCache.get('page');\n const search = searchParamsCache.get('name');\n const pageLimit = searchParamsCache.get('perPage');\n const sort = searchParamsCache.get('sort');\n\n const filters = {\n page,\n limit: pageLimit,\n ...(search && { search }),\n ...(sort.length > 0 && { sort: JSON.stringify(sort) })\n };\n\n const queryClient = getQueryClient();\n void queryClient.prefetchQuery(ordersQueryOptions(filters));\n\n return (\n \n }>\n \n \n \n );\n}\n```\n\n**Table + skeleton** (client component — `orders-table/index.tsx`):\n\n```tsx\n'use client';\nimport { useSuspenseQuery } from '@tanstack/react-query';\nimport { parseAsInteger, parseAsString, useQueryStates } from 'nuqs';\nimport { getSortingStateParser } from '@/lib/data-table-parsers';\nimport { useDataTable } from '@/hooks/use-data-table';\nimport { DataTable } from '@/components/data-table/data-table';\nimport { DataTableToolbar } from '@/components/data-table/data-table-toolbar';\nimport { Skeleton } from '@/components/ui/skeleton';\nimport { ordersQueryOptions } from '../../api/queries';\nimport { columns } from './columns';\n\nexport function OrderTable() {\n const [params] = useQueryStates({\n page: parseAsInteger.withDefault(1),\n perPage: parseAsInteger.withDefault(10),\n name: parseAsString,\n sort: getSortingStateParser().withDefault([]) // same parser as searchParamsCache\n });\n\n const filters = {\n page: params.page,\n limit: params.perPage,\n ...(params.name && { search: params.name }),\n ...(params.sort.length > 0 && { sort: JSON.stringify(params.sort) })\n };\n\n const { data } = useSuspenseQuery(ordersQueryOptions(filters));\n\n const { table } = useDataTable({\n data: data.items,\n columns,\n pageCount: Math.ceil(data.total_items / params.perPage),\n shallow: true,\n debounceMs: 500,\n initialState: { columnPinning: { start: [], end: ['actions'] } }\n });\n\n return (\n \n \n \n );\n}\n\nexport function OrderTableSkeleton() {\n return (\n
\n \n \n
\n );\n}\n```\n\n**Column definitions** (`orders-table/columns.tsx`):\n\nEach column needs `id`, `accessorKey` (or `accessorFn`), `header` with `DataTableColumnHeader`, and optionally `meta` for filtering + `enableColumnFilter: true`. Type columns as `ColumnDef[]` (TanStack Table v9; `DataTableFeatures` from `@/lib/data-table-features` types `meta`).\n\n```tsx\nexport const columns: ColumnDef[] = [\n {\n id: 'customer',\n accessorKey: 'customer',\n header: ({ column }) => ,\n meta: { label: 'Customer', placeholder: 'Search...', variant: 'text', icon: Icons.text },\n enableColumnFilter: true\n },\n {\n id: 'status',\n accessorKey: 'status',\n header: ({ column }) => ,\n cell: ({ cell }) => (\n \n {cell.getValue()}\n \n ),\n enableColumnFilter: true,\n meta: { label: 'Status', variant: 'multiSelect', options: STATUS_OPTIONS }\n },\n { id: 'actions', cell: ({ row }) => }\n];\n```\n\nFilter `meta.variant` options: `text`, `number`, `range`, `date`, `dateRange`, `select`, `multiSelect`, `boolean`. For multiSelect, provide `options: { value, label, icon? }[]`.\n\n**Cell actions** (`orders-table/cell-action.tsx`):\n\nPattern: `DropdownMenu` with edit/delete items + `AlertModal` for delete confirmation + `useMutation` for the delete API call.\n\n```tsx\nimport { deleteOrderMutation } from '../../api/mutations';\n\nexport const CellAction: React.FC<{ data: Order }> = ({ data }) => {\n const [deleteOpen, setDeleteOpen] = useState(false);\n const deleteMutation = useMutation({\n ...deleteOrderMutation,\n onSuccess: () => {\n toast.success('Deleted');\n setDeleteOpen(false);\n }\n });\n return (\n <>\n setDeleteOpen(false)}\n onConfirm={() => deleteMutation.mutate(data.id)}\n loading={deleteMutation.isPending}\n />\n \n \n \n \n \n Actions\n router.push(`/dashboard/orders/${data.id}`)}>\n Edit\n \n setDeleteOpen(true)}>\n Delete\n \n \n \n \n );\n};\n```\n\nFor **sheet-based editing** (like Users), replace `router.push` with opening a `` — see the Forms section below.\n\n### Step 5: Page Route (`src/app/dashboard//page.tsx`)\n\n```tsx\nimport PageContainer from '@/components/layout/page-container';\nimport OrderListingPage from '@/features/orders/components/order-listing';\nimport { searchParamsCache } from '@/lib/searchparams';\nimport type { SearchParams } from 'nuqs/server';\n\nexport const metadata = { title: 'Dashboard: Orders' };\ntype PageProps = { searchParams: Promise };\n\nexport default async function Page(props: PageProps) {\n const searchParams = await props.searchParams;\n searchParamsCache.parse(searchParams);\n\n return (\n \n \n \n );\n}\n```\n\n**PageContainer props**: `scrollable`, `pageTitle`, `pageDescription`, `pageHeaderAction` (React node for the top-right button), `infoContent` (help sidebar), `access` + `accessFallback` (RBAC gating).\n\n**Detail/Edit page** (`src/app/dashboard//[id]/page.tsx`):\n\n```tsx\nimport PageContainer from '@/components/layout/page-container';\nimport OrderViewPage from '@/features/orders/components/order-view-page';\n\nexport const metadata = { title: 'Dashboard: Order Details' };\ntype PageProps = { params: Promise<{ id: string }> };\n\nexport default async function Page(props: PageProps) {\n const { id } = await props.params;\n return (\n \n \n \n );\n}\n```\n\n**View page component** (client — handles new vs edit):\n\n```tsx\n'use client';\nimport { useSuspenseQuery } from '@tanstack/react-query';\nimport { notFound } from 'next/navigation';\nimport { orderByIdOptions } from '../api/queries';\nimport OrderForm from './order-form';\n\nexport default function OrderViewPage({ orderId }: { orderId: string }) {\n if (orderId === 'new') return ;\n const { data } = useSuspenseQuery(orderByIdOptions(Number(orderId)));\n if (!data) notFound();\n return ;\n}\n```\n\n### Step 6: Search Params (`src/lib/searchparams.ts`)\n\nAdd any new filter keys. Existing params: `page`, `perPage`, `name`, `gender`, `category`, `role`, `sort`.\n\n### Step 7: Navigation (`src/config/nav-config.ts`)\n\n```tsx\n{ title: 'Orders', url: '/dashboard/orders', icon: 'product', items: [] }\n```\n\n### Step 8: Icons (`src/components/icons.tsx`)\n\nTo register a new icon, import from `@tabler/icons-react` and add to the `Icons` object:\n\n```tsx\nimport { IconShoppingCart } from '@tabler/icons-react';\nexport const Icons = { /* ...existing */ cart: IconShoppingCart };\n```\n\nNever import `@tabler/icons-react` anywhere else. Always use `Icons.keyName`.\n\n**Existing icon keys** (partial): `dashboard`, `product`, `kanban`, `chat`, `forms`, `user`, `teams`, `billing`, `settings`, `add`, `edit`, `trash`, `search`, `check`, `close`, `clock`, `ellipsis`, `text`, `calendar`, `upload`, `spinner`, `chevronDown/Left/Right/Up`, `sun`, `moon`, `palette`, `pro`, `workspace`, `notification`.\n\n---\n\n## Forms\n\nForms use **TanStack Form + Zod** with `useAppForm` + `useFormFields()` and `useMutation` for submission. See [references/forms-guide.md](references/forms-guide.md) for all field types, validation strategies, multi-step forms, and advanced patterns.\n\n### Page Form (Create/Edit on a dedicated route)\n\nThe full pattern is shown in Steps 1-4 above. The key structure:\n\n1. **Schema** — Zod schema + inferred type in `schemas/.ts`\n2. **Form component** — `useAppForm({ defaultValues, validators: { onSubmit: schema }, onSubmit })` + `useFormFields()` for typed fields\n3. **Mutations** — `useMutation({ ...createOrderMutation, onSuccess: () => { toast(); router.push() } })`, spread shared mutation options from `api/mutations.ts` and layer on UI callbacks\n4. **View page** — client component that checks `id === 'new'` for create vs `useSuspenseQuery(byIdOptions)` for edit\n\n### Sheet Form (Inline create/edit in a side panel)\n\nFor features where a separate page is overkill (like Users). The sheet manages open state; the form uses a `form` attribute to connect to the sheet footer's submit button.\n\n```tsx\n'use client';\nimport { Sheet, SheetContent, SheetFooter, SheetHeader, SheetTitle } from '@/components/ui/sheet';\n\nexport function OrderFormSheet({\n order,\n open,\n onOpenChange\n}: {\n order?: Order;\n open: boolean;\n onOpenChange: (open: boolean) => void;\n}) {\n const isEdit = !!order;\n const mutation = useMutation({\n ...(isEdit ? updateOrderMutation : createOrderMutation),\n onSuccess: () => {\n onOpenChange(false);\n }\n });\n const form = useAppForm({\n defaultValues: { customer: order?.customer ?? '' /* ... */ } as OrderFormValues,\n validators: { onSubmit: orderSchema },\n onSubmit: async ({ value }) => {\n await mutation.mutateAsync(value);\n }\n });\n const { FormTextField, FormSelectField } = useFormFields();\n\n return (\n \n \n \n {isEdit ? 'Edit' : 'New'} Order\n \n
\n \n \n \n \n \n \n
\n \n \n \n \n \n \n );\n}\n```\n\nFor cell actions, add `const [editOpen, setEditOpen] = useState(false)` and render `` with a ` setEditOpen(true)}>`. For the page header \"Add\" button, create a trigger component that manages `open` state and renders the sheet.\n\n**Available field components** from `useFormFields()`: `FormTextField`, `FormTextareaField`, `FormSelectField`, `FormCheckboxField`, `FormSwitchField`, `FormRadioGroupField`, `FormSliderField`, `FormFileUploadField`.\n\n---\n\n## Data Fetching with React Query\n\nThe pattern is: server prefetch → HydrationBoundary → client useSuspenseQuery.\n\n1. **Server**: `void queryClient.prefetchQuery(options)` — fire-and-forget during SSR streaming\n2. **Client**: `useSuspenseQuery(options)` — picks up dehydrated data, suspends until resolved\n3. **HydrationBoundary + dehydrate**: bridges server cache → client cache\n4. **Suspense fallback**: skeleton shown while data streams\n\n**Why `useSuspenseQuery` not `useQuery`:** `useQuery` doesn't integrate with Suspense — it shows loading even when data is prefetched. `useSuspenseQuery` picks up the dehydrated pending query. Once cached (within `staleTime: 60s`), subsequent visits are instant.\n\n**Mutations** use `mutationOptions` + `getQueryClient()` in `mutations.ts`, composed via spread at the call site:\n\n```tsx\n// In mutations.ts — shared config\nexport const createOrderMutation = mutationOptions({\n mutationFn: (data) => createOrder(data),\n onSuccess: () => {\n getQueryClient().invalidateQueries({ queryKey: orderKeys.all });\n }\n});\n\n// In component — spread + layer UI callbacks\nconst mutation = useMutation({\n ...createOrderMutation,\n onSuccess: () => toast.success('Created')\n});\n```\n\nSee [references/query-abstractions.md](references/query-abstractions.md) for why `mutationOptions`/`queryOptions` are the right abstraction over custom hooks.\n\n---\n\n## Navigation & RBAC\n\nConfigure in `src/config/nav-config.ts`. Items are filtered client-side in `src/hooks/use-nav.ts` using Clerk.\n\n**Access control properties** on nav items:\n\n- `requireOrg: boolean` — requires active Clerk organization\n- `permission: string` — requires specific Clerk permission\n- `role: string` — requires specific Clerk role\n- `plan: string` — requires subscription plan (server-side)\n- `feature: string` — requires feature flag (server-side)\n\nItems without `access` are visible to everyone. All client-side checks are synchronous — no loading states.\n\n---\n\n## Themes\n\nSee [references/theming-guide.md](references/theming-guide.md) for the complete guide. Quick steps:\n\n1. Create `src/styles/themes/.css` with OKLCH color tokens + `@theme inline` block\n2. Import in `src/styles/theme.css`\n3. Register in `THEMES` array in `src/components/themes/theme.config.ts`\n4. (Optional) Add Google Fonts in `src/components/themes/font.config.ts`\n\n---\n\n## Code Conventions\n\n- **`cn()`** for class merging — never concatenate className strings\n- **Server components by default** — only add `'use client'` when needed\n- **React Query** — `void prefetchQuery()` on server + `useSuspenseQuery` on client\n- **API layer** — `types.ts` → `service.ts` → `queries.ts` → `mutations.ts` per feature; `queryOptions`/`mutationOptions` as base abstractions (not custom hooks); `getQueryClient()` in mutations (not `useQueryClient()`); key factories (`entityKeys.all/list/detail`); components never import mock APIs directly\n- **nuqs** — `searchParamsCache` on server, `useQueryStates` on client with `shallow: true`\n- **Icons** — only from `@/components/icons`, never from `@tabler/icons-react` directly\n- **Forms** — `useAppForm` + `useFormFields()` from `@/components/ui/tanstack-form`\n- **Page headers** — `PageContainer` props, never import `` manually\n- **Sort parser** — use `getSortingStateParser` from `@/lib/data-table-parsers` (same parser as `useDataTable`)\n- **Formatting** — single quotes, JSX single quotes, no trailing comma, 2-space indent\n",".agents/skills/kiranism-shadcn-dashboard/references/charts-guide.md":"# Charts & Analytics Guide\n\n## Table of Contents\n\n1. [Overview Architecture](#overview-architecture)\n2. [Parallel Routes Pattern](#parallel-routes-pattern)\n3. [Chart Components](#chart-components)\n4. [Stats Cards](#stats-cards)\n5. [Skeleton Loading](#skeleton-loading)\n6. [Adding a New Chart Section](#adding-a-new-chart-section)\n\n---\n\n## Overview Architecture\n\nThe analytics dashboard at `/dashboard/overview` uses **Next.js parallel routes** to load multiple chart sections independently. Each chart slot streams in as its data becomes ready — no waterfall, no blocking.\n\n**File structure:**\n\n```\nsrc/app/dashboard/overview/\n├── layout.tsx # Composes all slots into a grid\n├── @area_stats/\n│ ├── page.tsx # Async server component (fetches data)\n│ ├── loading.tsx # Skeleton shown while streaming\n│ └── error.tsx # Error boundary if fetch fails\n├── @bar_stats/\n│ ├── page.tsx\n│ ├── loading.tsx\n│ └── error.tsx\n├── @pie_stats/\n│ ├── page.tsx\n│ ├── loading.tsx\n│ └── error.tsx\n└── @sales/\n ├── page.tsx\n ├── loading.tsx\n └── error.tsx\n\nsrc/features/overview/components/\n├── area-graph.tsx # Client chart component\n├── area-graph-skeleton.tsx # Matching skeleton\n├── bar-graph.tsx\n├── bar-graph-skeleton.tsx\n├── pie-graph.tsx\n├── pie-graph-skeleton.tsx\n├── recent-sales.tsx\n└── recent-sales-skeleton.tsx\n```\n\n---\n\n## Parallel Routes Pattern\n\n### Layout (`layout.tsx`)\n\nThe layout receives each parallel route as a prop and arranges them in a grid:\n\n```tsx\nexport default function OverviewLayout({\n sales,\n pie_stats,\n bar_stats,\n area_stats\n}: {\n sales: React.ReactNode;\n pie_stats: React.ReactNode;\n bar_stats: React.ReactNode;\n area_stats: React.ReactNode;\n}) {\n return (\n \n {/* Stats cards row */}\n
\n \n \n Total Revenue\n \n \n \n
$45,231.89
\n

+20.1% from last month

\n \n \n {/* ...more stat cards */}\n
\n\n {/* Charts grid — each slot loads independently */}\n
\n
{area_stats}
\n
{sales}
\n
{bar_stats}
\n
{pie_stats}
\n
\n \n );\n}\n```\n\n### Slot Page (`@area_stats/page.tsx`)\n\nEach slot is an async server component that fetches data then renders the chart:\n\n```tsx\nimport { delay } from '@/constants/mock-api';\nimport { AreaGraph } from '@/features/overview/components/area-graph';\n\nexport default async function AreaStatsPage() {\n await delay(2000); // Simulates API fetch\n return ;\n}\n```\n\n### Slot Loading (`@area_stats/loading.tsx`)\n\n```tsx\nimport { AreaGraphSkeleton } from '@/features/overview/components/area-graph-skeleton';\n\nexport default function Loading() {\n return ;\n}\n```\n\n### Slot Error (`@area_stats/error.tsx`)\n\n```tsx\n'use client';\nimport { Alert, AlertDescription, AlertTitle } from '@/components/ui/alert';\nimport { Icons } from '@/components/icons';\n\nexport default function AreaStatsError({ error }: { error: Error }) {\n return (\n \n \n Error\n Failed to load area stats: {error.message}\n \n );\n}\n```\n\nEach slot can fail independently without affecting others.\n\n---\n\n## Chart Components\n\nAll chart components are `'use client'` and use **Recharts** wrapped in shadcn's `ChartContainer`.\n\n### Chart Config\n\nEvery chart defines a config object mapping data keys to labels and theme colors:\n\n```tsx\nimport {\n type ChartConfig,\n ChartContainer,\n ChartTooltip,\n ChartTooltipContent\n} from '@/components/ui/chart';\n\nconst chartConfig = {\n desktop: { label: 'Desktop', color: 'var(--chart-1)' },\n mobile: { label: 'Mobile', color: 'var(--chart-2)' }\n} satisfies ChartConfig;\n```\n\nTheme colors `--chart-1` through `--chart-5` are defined in each theme's CSS file and automatically adapt to light/dark mode.\n\n### Area Chart Example\n\n```tsx\n'use client';\nimport { Area, AreaChart, CartesianGrid, XAxis } from 'recharts';\nimport {\n type ChartConfig,\n ChartContainer,\n ChartTooltip,\n ChartTooltipContent\n} from '@/components/ui/chart';\nimport { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';\nimport { Badge } from '@/components/ui/badge';\nimport { Icons } from '@/components/icons';\n\nconst chartData = [\n { month: 'January', desktop: 186, mobile: 80 },\n { month: 'February', desktop: 305, mobile: 200 }\n // ...more months\n];\n\nconst chartConfig = {\n desktop: { label: 'Desktop', color: 'var(--chart-1)' },\n mobile: { label: 'Mobile', color: 'var(--chart-2)' }\n} satisfies ChartConfig;\n\nexport function AreaGraph() {\n return (\n \n \n Area Chart - Stacked\n \n +12.5%\n \n \n \n \n \n \n value.slice(0, 3)}\n />\n } />\n \n \n \n \n \n \n );\n}\n```\n\n### Bar Chart Pattern\n\nSame structure, using `BarChart` + `Bar`:\n\n```tsx\n\n \n \n \n } />\n \n \n \n\n```\n\n### Pie/Donut Chart Pattern\n\n```tsx\n\n \n } />\n \n \n \n \n\n```\n\n---\n\n## Stats Cards\n\nStats cards are simple server-rendered `Card` components at the top of the layout — no parallel routes needed since they render instantly:\n\n```tsx\n\n \n Total Revenue\n \n \n \n
$45,231.89
\n

+20.1% from last month

\n \n\n```\n\nFor dynamic stats that need data fetching, wrap in their own Suspense boundary or parallel route slot.\n\n---\n\n## Skeleton Loading\n\nEach chart has a matching skeleton component. Pattern:\n\n```tsx\nimport { Card, CardContent, CardHeader } from '@/components/ui/card';\nimport { Skeleton } from '@/components/ui/skeleton';\n\nexport function AreaGraphSkeleton() {\n return (\n \n \n \n \n \n \n \n \n \n );\n}\n```\n\nMatch the skeleton dimensions to the actual chart for smooth visual transitions.\n\n---\n\n## Adding a New Chart Section\n\nTo add a new chart (e.g., line chart for user growth):\n\n### 1. Create the chart component\n\n`src/features/overview/components/line-graph.tsx`:\n\n```tsx\n'use client';\nimport { Line, LineChart, CartesianGrid, XAxis } from 'recharts';\nimport {\n type ChartConfig,\n ChartContainer,\n ChartTooltip,\n ChartTooltipContent\n} from '@/components/ui/chart';\n\nconst chartConfig = {\n users: { label: 'Users', color: 'var(--chart-3)' }\n} satisfies ChartConfig;\n\nconst chartData = [\n /* monthly user data */\n];\n\nexport function LineGraph() {\n return (\n \n \n User Growth\n \n \n \n \n \n \n } />\n \n \n \n \n \n );\n}\n```\n\n### 2. Create matching skeleton\n\n`src/features/overview/components/line-graph-skeleton.tsx`\n\n### 3. Create parallel route slot\n\n```\nsrc/app/dashboard/overview/@line_stats/\n├── page.tsx → async, fetches data, returns \n├── loading.tsx → returns \n├── error.tsx → error alert\n└── default.tsx → return null (fallback when route doesn't match)\n```\n\n`default.tsx` is required for parallel routes — return `null` or a fallback:\n\n```tsx\nexport default function Default() {\n return null;\n}\n```\n\n### 4. Add slot to layout\n\nUpdate `src/app/dashboard/overview/layout.tsx`:\n\n```tsx\nexport default function OverviewLayout({\n sales,\n pie_stats,\n bar_stats,\n area_stats,\n line_stats // ← add new slot\n}: {\n /* ...types */\n}) {\n return (\n
\n {/* existing charts */}\n
{line_stats}
\n
\n );\n}\n```\n\n### Available Recharts Components\n\nCommon chart types to use with `ChartContainer`:\n\n- `AreaChart` + `Area` — filled area charts (stacked or standalone)\n- `BarChart` + `Bar` — vertical/horizontal bars\n- `LineChart` + `Line` — line/trend charts\n- `PieChart` + `Pie` — pie/donut charts\n- `RadarChart` + `Radar` — radar/spider charts\n- `RadialBarChart` + `RadialBar` — radial progress bars\n\nAll support `ChartTooltip`, `ChartLegend`, and theme-aware colors via `var(--chart-N)`.\n",".agents/skills/kiranism-shadcn-dashboard/references/forms-guide.md":"# Forms Guide\n\n## Table of Contents\n\n1. [Architecture](#architecture)\n2. [Field Types](#field-types)\n3. [Usage Patterns](#usage-patterns)\n4. [Validation Strategies](#validation-strategies)\n5. [Sheet/Dialog Forms](#sheetdialog-forms)\n6. [Multi-Step Forms](#multi-step-forms)\n7. [Advanced Patterns](#advanced-patterns)\n\n---\n\n## Architecture\n\nThe form system is built on **TanStack Form + Zod** with a composable field layer.\n\n**Key files:**\n\n- `src/components/ui/tanstack-form.tsx` — exports `useAppForm`, `useFormFields()`, composed fields\n- `src/components/ui/form-context.tsx` — contexts, `createFormField`, structural components\n- `src/components/forms/fields/*.tsx` — 8 field type implementations\n\n**Key exports:**\n\n```tsx\nimport { useAppForm, useFormFields } from '@/components/ui/tanstack-form';\n```\n\n- `useAppForm(config)` — creates a form instance with `defaultValues`, `validators`, `onSubmit`\n- `useFormFields()` — returns all 8 typed field components with name autocomplete from `T`\n- `form.AppForm` — context provider wrapper\n- `form.Form` — `
` element that handles submit\n- `form.SubmitButton` — auto-disabled when form is invalid or submitting\n- `form.AppField` — low-level render prop for custom fields\n\n---\n\n## Field Types\n\nAll fields accept: `name`, `label`, `description`, `required`, `disabled`, `validators`, `listeners`, `className`.\n\n| Component | Props | Notes |\n| --------------------- | --------------------------------------------------------------------------------------------- | --------------------------------------- |\n| `FormTextField` | `type` (text/email/number/password/tel/url), `placeholder`, `min`, `max`, `step`, `maxLength` | For numbers use `type='number'` |\n| `FormTextareaField` | `placeholder`, `rows`, `maxLength` | Multiline text |\n| `FormSelectField` | `options: {value, label}[]`, `placeholder` | Single select dropdown |\n| `FormCheckboxField` | `options?: {value, label}[]` | Single checkbox or multi-checkbox group |\n| `FormSwitchField` | — | Toggle switch |\n| `FormRadioGroupField` | `options: {value, label}[]`, `orientation` | Radio button group |\n| `FormSliderField` | `min`, `max`, `step` | Range slider |\n| `FormFileUploadField` | `maxSize`, `maxFiles`, `accept` | Drag-and-drop with preview |\n\n---\n\n## Usage Patterns\n\n### Pattern 1: `useFormFields()` (Recommended)\n\nType-safe field components with name autocomplete:\n\n```tsx\nconst { FormTextField, FormSelectField } = useFormFields();\n\n\n\n\n```\n\n### Pattern 2: `form.AppField` render prop\n\nFull control for custom field rendering:\n\n```tsx\n\n {(field) => (\n \n \n \n \n \n \n )}\n\n```\n\n### Pattern 3: Direct import (no type safety)\n\nFor quick prototyping:\n\n```tsx\nimport { FormTextField } from '@/components/ui/tanstack-form';\n;\n```\n\n---\n\n## Validation Strategies\n\n### Field-level (recommended for UX)\n\n```tsx\n\n```\n\n### Form-level (catch-all on submit)\n\n```tsx\nconst form = useAppForm({\n validators: { onSubmit: orderSchema }, // Validates entire form on submit\n onSubmit: async ({ value }) => {\n /* ... */\n }\n});\n```\n\n### Async validation (server-side checks)\n\n```tsx\n {\n const exists = await checkUsername(value);\n return exists ? 'Username taken' : undefined;\n }\n }}\n asyncDebounceMs={500}\n/>\n```\n\n### Linked field validation\n\nFor dependent fields (e.g., confirm password):\n\n```tsx\n {\n const password = fieldApi.form.getFieldValue('password');\n return value !== password ? 'Passwords must match' : undefined;\n }\n }}\n/>\n```\n\n---\n\n## Sheet/Dialog Forms\n\nThe key pattern for forms inside sheets or dialogs: give the `` an `id`, and use that `id` on the submit button's `form` attribute. This allows the submit button to live outside the form element (e.g., in `SheetFooter`).\n\n```tsx\n\n \n {/* fields */}\n \n;\n\n{\n /* In SheetFooter — button is outside the but still submits it */\n}\n\n \n;\n```\n\nOn success, call `onOpenChange(false)` to close the sheet and `form.reset()` for create forms.\n\n---\n\n## Multi-Step Forms\n\nUse `withFieldGroup` + `useAppForm` with `StepButton`:\n\n```tsx\n// Define field groups for each step\nconst Step1 = withFieldGroup({\n fields: ['name', 'email'],\n render: ({ form }) => {\n const { FormTextField } = useFormFields();\n return (\n <>\n \n \n \n \n );\n }\n});\n\nconst Step2 = withFieldGroup({\n fields: ['address', 'city'],\n render: ({ form }) => {\n const { FormTextField } = useFormFields();\n return (\n <>\n \n \n \n \n \n );\n }\n});\n```\n\nUse the `useStepper` hook from `src/hooks/use-stepper.tsx` to manage step state.\n\n---\n\n## Advanced Patterns\n\n### Nested objects (dot notation)\n\n```tsx\n\n\n```\n\n### Dynamic array rows\n\n```tsx\n\n {(field) => (\n <>\n {field.state.value.map((_, i) => (\n \n {(subField) => }\n \n ))}\n \n \n )}\n\n```\n\n### Side effects with listeners\n\n```tsx\n {\n // Reset city when country changes\n form.setFieldValue('city', '');\n }\n }}\n/>\n```\n\n### Custom field with `form.AppField`\n\nFor fields not covered by the built-in 8 types:\n\n```tsx\n\n {(field) => (\n \n \n \n field.handleChange(e.target.value)}\n />\n \n \n \n )}\n\n```\n\n### Form-level errors\n\nDisplay errors that apply to the whole form (e.g., server errors):\n\n```tsx\nimport { FormErrors } from '@/components/ui/form-context';\n\n\n \n {/* Renders form-level validation errors */}\n {/* fields... */}\n \n;\n```\n",".agents/skills/kiranism-shadcn-dashboard/references/mock-api-guide.md":"# Mock API Guide\n\n## Table of Contents\n\n1. [Structure](#structure)\n2. [Full Template](#full-template)\n3. [Key Patterns](#key-patterns)\n4. [Integrating with React Query](#integrating-with-react-query)\n\n---\n\n## Structure\n\nEach mock API file lives in `src/constants/mock-api-.ts` and is a self-contained in-memory database. It uses:\n\n- **faker** for generating sample data\n- **match-sorter** for fuzzy search across fields\n- **delay** (from `./mock-api`) to simulate network latency\n\nThe `delay` function is exported from `src/constants/mock-api.ts`:\n\n```tsx\nexport async function delay(ms: number) {\n return new Promise((resolve) => setTimeout(resolve, ms));\n}\n```\n\n---\n\n## Full Template\n\n```tsx\nimport { faker } from '@faker-js/faker';\nimport { matchSorter } from 'match-sorter';\nimport { delay } from './mock-api';\n\n// 1. Define the entity type\nexport type Order = {\n id: number;\n customer: string;\n email: string;\n status: string;\n total: number;\n created_at: string;\n updated_at: string;\n};\n\n// 2. Create the fake database object\nexport const fakeOrders = {\n records: [] as Order[],\n\n // 3. Initialize with faker data\n initialize() {\n const statuses = ['pending', 'processing', 'completed', 'cancelled'];\n for (let i = 1; i <= 20; i++) {\n this.records.push({\n id: i,\n customer: faker.person.fullName(),\n email: faker.internet.email(),\n status: faker.helpers.arrayElement(statuses),\n total: parseFloat(faker.commerce.price({ min: 10, max: 500 })),\n created_at: faker.date.between({ from: '2023-01-01', to: Date.now() }).toISOString(),\n updated_at: faker.date.recent().toISOString()\n });\n }\n },\n\n // 4. Get all with optional search (used internally)\n async getAll({ search }: { search?: string } = {}) {\n let items = [...this.records];\n if (search) {\n items = matchSorter(items, search, {\n keys: ['customer', 'email']\n });\n }\n return items;\n },\n\n // 5. Paginated list with filtering and sorting\n async getOrders(params: {\n page?: number;\n limit?: number;\n search?: string;\n statuses?: string;\n sort?: string;\n }) {\n await delay(800);\n const { page = 1, limit = 10, search, statuses, sort } = params;\n\n let items = await this.getAll({ search });\n\n // Filter by comma-separated values\n if (statuses) {\n const statusList = statuses.split('.');\n items = items.filter((item) => statusList.includes(item.status));\n }\n\n // Sort by column\n if (sort) {\n const parsedSort = JSON.parse(sort) as { id: string; desc: boolean }[];\n if (parsedSort.length > 0) {\n const { id, desc } = parsedSort[0];\n items.sort((a, b) => {\n const aVal = a[id as keyof Order];\n const bVal = b[id as keyof Order];\n if (aVal < bVal) return desc ? 1 : -1;\n if (aVal > bVal) return desc ? -1 : 1;\n return 0;\n });\n }\n }\n\n // Paginate\n const total_items = items.length;\n items = items.slice((page - 1) * limit, page * limit);\n\n return { items, total_items };\n },\n\n // 6. Get single record by ID\n async getOrderById(id: number) {\n await delay(800);\n return this.records.find((r) => r.id === id) || null;\n },\n\n // 7. Create\n async createOrder(data: Omit) {\n await delay(800);\n const newRecord: Order = {\n ...data,\n id: this.records.length + 1,\n created_at: new Date().toISOString(),\n updated_at: new Date().toISOString()\n };\n this.records.push(newRecord);\n return newRecord;\n },\n\n // 8. Update\n async updateOrder(id: number, data: Partial) {\n await delay(800);\n const idx = this.records.findIndex((r) => r.id === id);\n if (idx === -1) return null;\n this.records[idx] = {\n ...this.records[idx],\n ...data,\n updated_at: new Date().toISOString()\n };\n return this.records[idx];\n },\n\n // 9. Delete\n async deleteOrder(id: number) {\n await delay(800);\n this.records = this.records.filter((r) => r.id !== id);\n return true;\n }\n};\n\n// 10. Auto-initialize on import\nfakeOrders.initialize();\n```\n\n---\n\n## Key Patterns\n\n### Search with match-sorter\n\nAlways specify which fields to search across:\n\n```tsx\nmatchSorter(items, search, { keys: ['customer', 'email', 'status'] });\n```\n\n### Comma-separated filter values\n\nFor multi-select filters (roles, statuses), the URL param uses `.` as delimiter:\n\n```tsx\nif (statuses) {\n const list = statuses.split('.');\n items = items.filter((item) => list.includes(item.status));\n}\n```\n\n### Computed column sorting\n\nWhen a table has a computed column (e.g., combining first_name + last_name into \"name\"), handle it in the sort logic:\n\n```tsx\nif (id === 'name') {\n const aName = `${a.first_name} ${a.last_name}`;\n const bName = `${b.first_name} ${b.last_name}`;\n return desc ? bName.localeCompare(aName) : aName.localeCompare(bName);\n}\n```\n\n### Return shape\n\nList methods must return `{ items, total_items }` (or `{ products, total }` etc. — match the query option expectations). The total is the count **before** pagination, used for `pageCount` calculation.\n\n---\n\n## Integrating with the API Layer\n\nThe mock API is only imported in `service.ts`. Queries and components import from the service and types files:\n\n```\nmock-api-orders.ts → api/service.ts → api/queries.ts → components\n(data source) (data access) (key factory + (useSuspenseQuery\n queryOptions) + useMutation)\n```\n\n**service.ts** imports from the mock API:\n\n```tsx\nimport { fakeOrders } from '@/constants/mock-api-orders';\nimport type { OrderFilters, OrdersResponse } from './types';\n\nexport async function getOrders(filters: OrderFilters): Promise {\n return fakeOrders.getOrders(filters);\n}\nexport async function createOrder(data: OrderMutationPayload) {\n return fakeOrders.createOrder(data);\n}\n```\n\n**queries.ts** imports from service, uses key factories:\n\n```tsx\nimport { getOrders } from './service';\nimport type { OrderFilters } from './types';\n\nexport const orderKeys = {\n all: ['orders'] as const,\n list: (filters: OrderFilters) => [...orderKeys.all, 'list', filters] as const,\n detail: (id: number) => [...orderKeys.all, 'detail', id] as const\n};\n\nexport const ordersQueryOptions = (filters: OrderFilters) =>\n queryOptions({ queryKey: orderKeys.list(filters), queryFn: () => getOrders(filters) });\n```\n\n**Mutations** in components use service functions + key factories:\n\n```tsx\nimport { createOrder } from '../api/service';\nimport { orderKeys } from '../api/queries';\n\nconst mutation = useMutation({\n mutationFn: (data) => createOrder(data),\n onSuccess: () => queryClient.invalidateQueries({ queryKey: orderKeys.all })\n});\n```\n",".agents/skills/kiranism-shadcn-dashboard/references/query-abstractions.md":"# TanStack Query Abstractions (v5)\n\nThe core insight: **`queryOptions` and `mutationOptions` are the right abstraction — not custom hooks.**\n\n---\n\n## Query Abstraction\n\n### The Pattern\n\n```ts\n// queries/invoice.ts\nimport { queryOptions } from '@tanstack/react-query';\n\nexport function invoiceOptions(id: number) {\n return queryOptions({\n queryKey: ['invoice', id],\n queryFn: () => fetchInvoice(id)\n });\n}\n\nexport function invoiceListOptions(filters: InvoiceFilters) {\n return queryOptions({\n queryKey: ['invoices', filters],\n queryFn: () => fetchInvoices(filters),\n staleTime: 30_000\n });\n}\n```\n\n### Usage — always compose at the call site\n\n```ts\n// basic\nconst { data } = useQuery(invoiceOptions(id));\n\n// with suspense — same options, different hook\nconst { data } = useSuspenseQuery(invoiceOptions(id));\n\n// with extra options spread on top — full type inference, no TS pain\nconst { data } = useQuery({\n ...invoiceOptions(id),\n select: (invoice) => invoice.createdAt, // data infers as string | undefined\n enabled: !!id\n});\n\n// prefetch in a route loader (works outside React — this is why hooks are wrong)\nawait queryClient.prefetchQuery(invoiceOptions(id));\n\n// read from cache imperatively — queryKey is typed via DataTag symbol\nconst invoice = queryClient.getQueryData(invoiceOptions(id).queryKey);\n\n// invalidate\nqueryClient.invalidateQueries({ queryKey: invoiceOptions(id).queryKey });\n```\n\n### Why NOT a custom hook\n\nCustom hooks like `useInvoice(id)` have three critical problems:\n\n1. **Hooks only work in components/hooks** — but queries are now used in route loaders, server prefetching, event handlers, and server components. `queryOptions` is just a plain function — works anywhere.\n2. **They share logic, not configuration** — what you actually want to share is the `queryKey` + `queryFn` config. Hooks are the wrong primitive for that.\n3. **They lock you to one hook** — you can't use `useInvoice()` with `useSuspenseQuery`, `useQueries`, or imperative `queryClient` methods.\n\n### Why NOT `UseQueryOptions` type directly\n\n```ts\n// BAD — data becomes unknown\nfunction useInvoice(id: number, options?: Partial) { ... }\n\n// STILL BAD — select breaks with TS error\nfunction useInvoice(id: number, options?: Partial>) { ... }\n// select: (invoice) => invoice.createdAt\n// Error: Type 'string' is not assignable to type 'Invoice'\n```\n\n`queryOptions` solves this via a `DataTag` symbol on the queryKey — full inference, zero manual generics.\n\n### Custom hooks are still fine on top\n\nIf a component always uses the same composition, a hook is fine — but build it _on top of_ `queryOptions`:\n\n```ts\n// OK — hook built on queryOptions\nfunction useInvoice(id: number) {\n return useQuery(invoiceOptions(id));\n}\n\n// OK — hook that adds per-feature defaults\nfunction useInvoiceWithSuspense(id: number) {\n return useSuspenseQuery(invoiceOptions(id));\n}\n```\n\n---\n\n## Mutation Abstraction\n\n### The Pattern\n\n```ts\n// mutations/invoice.ts\nimport { mutationOptions } from '@tanstack/react-query';\nimport { getQueryClient } from '@/lib/query-client';\n\nexport const createInvoiceMutation = mutationOptions({\n mutationFn: (data: CreateInvoiceInput) => createInvoice(data),\n onSuccess: () => {\n getQueryClient().invalidateQueries({ queryKey: ['invoices'] });\n }\n});\n\nexport const updateInvoiceMutation = mutationOptions({\n mutationFn: ({ id, ...data }: UpdateInvoiceInput) => updateInvoice(id, data),\n onSuccess: (updated) => {\n const qc = getQueryClient();\n qc.setQueryData(invoiceOptions(updated.id).queryKey, updated);\n qc.invalidateQueries({ queryKey: ['invoices'] });\n }\n});\n```\n\n> **Note on queryClient**: Import `getQueryClient()` directly — do NOT pass `queryClient` as a function argument. The `getQueryClient()` pattern handles both SSR (fresh per request) and client (singleton) correctly.\n\n### Usage\n\n```ts\n// basic\nconst { mutate } = useMutation(createInvoiceMutation);\n\n// composed — add per-usage callbacks on top\nconst { mutate } = useMutation({\n ...createInvoiceMutation,\n onError: (err) => toast.error(err.message),\n onSuccess: (data) => {\n // this runs AFTER the shared onSuccess above\n router.push(`/invoices/${data.id}`);\n }\n});\n```\n\n---\n\n## Rules Summary\n\n| Rule | Reason |\n| ------------------------------------------------------------- | ---------------------------------------------------------------------- |\n| Use `queryOptions()` not custom hooks as the base abstraction | Works everywhere — loaders, server, imperative calls |\n| Keep options factories lean — no extra config params | Best abstractions are not configurable |\n| Compose extra options at the call site via spread | Full TS inference without manual generics |\n| Import `getQueryClient()` in mutation files | Handles SSR/client correctly without prop drilling |\n| Co-locate `queryKey` inside `queryOptions` | Typed key reuse in `invalidateQueries`, `setQueryData`, `getQueryData` |\n| Custom hooks are fine — but built ON TOP of `queryOptions` | Hooks for component convenience, `queryOptions` for sharing config |\n",".agents/skills/kiranism-shadcn-dashboard/references/theming-guide.md":"# Theme Creation Guide\n\n## Table of Contents\n\n1. [Create Theme CSS](#1-create-theme-css)\n2. [Import Theme](#2-import-theme)\n3. [Register Theme](#3-register-theme)\n4. [Add Custom Fonts](#4-add-custom-fonts-optional)\n5. [Set as Default](#5-set-as-default-optional)\n6. [Required Tokens](#required-tokens)\n7. [Color Format Reference](#color-format-reference)\n\n---\n\n## 1. Create Theme CSS\n\nCreate `src/styles/themes/.css`:\n\n```css\n/* Light mode */\n[data-theme='your-theme'] {\n --background: oklch(1 0 0);\n --foreground: oklch(0.145 0 0);\n --card: oklch(...);\n --card-foreground: oklch(...);\n --popover: oklch(...);\n --popover-foreground: oklch(...);\n --primary: oklch(...);\n --primary-foreground: oklch(...);\n --secondary: oklch(...);\n --secondary-foreground: oklch(...);\n --muted: oklch(...);\n --muted-foreground: oklch(...);\n --accent: oklch(...);\n --accent-foreground: oklch(...);\n --destructive: oklch(...);\n --destructive-foreground: oklch(...);\n --border: oklch(...);\n --input: oklch(...);\n --ring: oklch(...);\n --chart-1: oklch(...);\n --chart-2: oklch(...);\n --chart-3: oklch(...);\n --chart-4: oklch(...);\n --chart-5: oklch(...);\n --sidebar: oklch(...);\n --sidebar-foreground: oklch(...);\n --sidebar-primary: oklch(...);\n --sidebar-primary-foreground: oklch(...);\n --sidebar-accent: oklch(...);\n --sidebar-accent-foreground: oklch(...);\n --sidebar-border: oklch(...);\n --sidebar-ring: oklch(...);\n --font-sans: 'Font Name', sans-serif;\n --font-mono: 'Mono Font', monospace;\n --radius: 0.5rem;\n --spacing: 0.25rem;\n}\n\n/* Dark mode */\n[data-theme='your-theme'].dark {\n --background: oklch(0.145 0 0);\n --foreground: oklch(0.985 0 0);\n /* ... all tokens with dark values */\n}\n\n/* Tailwind integration (required) */\n[data-theme='your-theme'] {\n @theme inline {\n --color-background: var(--background);\n --color-foreground: var(--foreground);\n --color-card: var(--card);\n --color-card-foreground: var(--card-foreground);\n --color-popover: var(--popover);\n --color-popover-foreground: var(--popover-foreground);\n --color-primary: var(--primary);\n --color-primary-foreground: var(--primary-foreground);\n --color-secondary: var(--secondary);\n --color-secondary-foreground: var(--secondary-foreground);\n --color-muted: var(--muted);\n --color-muted-foreground: var(--muted-foreground);\n --color-accent: var(--accent);\n --color-accent-foreground: var(--accent-foreground);\n --color-destructive: var(--destructive);\n --color-destructive-foreground: var(--destructive-foreground);\n --color-border: var(--border);\n --color-input: var(--input);\n --color-ring: var(--ring);\n --color-chart-1: var(--chart-1);\n --color-chart-2: var(--chart-2);\n --color-chart-3: var(--chart-3);\n --color-chart-4: var(--chart-4);\n --color-chart-5: var(--chart-5);\n --color-sidebar: var(--sidebar);\n --color-sidebar-foreground: var(--sidebar-foreground);\n --color-sidebar-primary: var(--sidebar-primary);\n --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);\n --color-sidebar-accent: var(--sidebar-accent);\n --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);\n --color-sidebar-border: var(--sidebar-border);\n --color-sidebar-ring: var(--sidebar-ring);\n --font-sans: var(--font-sans);\n --font-mono: var(--font-mono);\n --font-serif: var(--font-serif);\n --radius-sm: calc(var(--radius) - 4px);\n --radius-md: calc(var(--radius) - 2px);\n --radius-lg: var(--radius);\n --radius-xl: calc(var(--radius) + 4px);\n }\n}\n```\n\n## 2. Import Theme\n\nAdd to `src/styles/theme.css`:\n\n```css\n@import './themes/your-theme.css';\n```\n\n## 3. Register Theme\n\nAdd to `THEMES` array in `src/components/themes/theme.config.ts`:\n\n```typescript\n{ name: 'Your Theme', value: 'your-theme' }\n```\n\nThe `value` must exactly match the `data-theme` attribute in your CSS.\n\n## 4. Add Custom Fonts (Optional)\n\nOnly if using a Google Font not already loaded.\n\nIn `src/components/themes/font.config.ts`:\n\n```typescript\nimport { Your_Font } from 'next/font/google';\n\nconst fontYourName = Your_Font({\n subsets: ['latin'],\n weight: ['400', '500', '700'],\n variable: '--font-your-name'\n});\n\nexport const fontVariables = cn(\n // ... existing fonts\n fontYourName.variable\n);\n```\n\nIn your theme CSS, use the font's **display name** (not the CSS variable):\n\n```css\n--font-sans: 'Your Font', sans-serif;\n```\n\n## 5. Set as Default (Optional)\n\nIn `src/components/themes/theme.config.ts`:\n\n```typescript\nexport const DEFAULT_THEME = 'your-theme';\n```\n\n## Required Tokens\n\nMinimum required: `--background`, `--foreground`, `--card` & `--card-foreground`, `--popover` & `--popover-foreground`, `--primary` & `--primary-foreground`, `--secondary` & `--secondary-foreground`, `--muted` & `--muted-foreground`, `--accent` & `--accent-foreground`, `--destructive` & `--destructive-foreground`, `--border`, `--input`, `--ring`, `--radius`.\n\nOptional: `--chart-*`, `--sidebar-*`, `--font-*`, `--shadow-*`, `--tracking-normal`, `--spacing`.\n\n## Color Format Reference\n\nOKLCH: `oklch(lightness chroma hue)`\n\n- Lightness: 0-1 (0=black, 1=white)\n- Chroma: 0+ (0=gray, higher=saturated)\n- Hue: 0-360 (0=red, 120=green, 240=blue)\n\nSee `src/styles/themes/claude.css` for a complete example.\n",".agents/skills/next-best-practices/SKILL.md":"---\nname: next-best-practices\ndescription: Next.js best practices - file conventions, RSC boundaries, data patterns, async APIs, metadata, error handling, route handlers, image/font optimization, bundling\nuser-invocable: false\n---\n\n# Next.js Best Practices\n\nApply these rules when writing or reviewing Next.js code.\n\n## File Conventions\n\nSee [file-conventions.md](./file-conventions.md) for:\n\n- Project structure and special files\n- Route segments (dynamic, catch-all, groups)\n- Parallel and intercepting routes\n- Middleware rename in v16 (middleware → proxy)\n\n## RSC Boundaries\n\nDetect invalid React Server Component patterns.\n\nSee [rsc-boundaries.md](./rsc-boundaries.md) for:\n\n- Async client component detection (invalid)\n- Non-serializable props detection\n- Server Action exceptions\n\n## Async Patterns\n\nNext.js 15+ async API changes.\n\nSee [async-patterns.md](./async-patterns.md) for:\n\n- Async `params` and `searchParams`\n- Async `cookies()` and `headers()`\n- Migration codemod\n\n## Runtime Selection\n\nSee [runtime-selection.md](./runtime-selection.md) for:\n\n- Default to Node.js runtime\n- When Edge runtime is appropriate\n\n## Directives\n\nSee [directives.md](./directives.md) for:\n\n- `'use client'`, `'use server'` (React)\n- `'use cache'` (Next.js)\n\n## Functions\n\nSee [functions.md](./functions.md) for:\n\n- Navigation hooks: `useRouter`, `usePathname`, `useSearchParams`, `useParams`\n- Server functions: `cookies`, `headers`, `draftMode`, `after`\n- Generate functions: `generateStaticParams`, `generateMetadata`\n\n## Error Handling\n\nSee [error-handling.md](./error-handling.md) for:\n\n- `error.tsx`, `global-error.tsx`, `not-found.tsx`\n- `redirect`, `permanentRedirect`, `notFound`\n- `forbidden`, `unauthorized` (auth errors)\n- `unstable_rethrow` for catch blocks\n\n## Data Patterns\n\nSee [data-patterns.md](./data-patterns.md) for:\n\n- Server Components vs Server Actions vs Route Handlers\n- Avoiding data waterfalls (`Promise.all`, Suspense, preload)\n- Client component data fetching\n\n## Route Handlers\n\nSee [route-handlers.md](./route-handlers.md) for:\n\n- `route.ts` basics\n- GET handler conflicts with `page.tsx`\n- Environment behavior (no React DOM)\n- When to use vs Server Actions\n\n## Metadata & OG Images\n\nSee [metadata.md](./metadata.md) for:\n\n- Static and dynamic metadata\n- `generateMetadata` function\n- OG image generation with `next/og`\n- File-based metadata conventions\n\n## Image Optimization\n\nSee [image.md](./image.md) for:\n\n- Always use `next/image` over ``\n- Remote images configuration\n- Responsive `sizes` attribute\n- Blur placeholders\n- Priority loading for LCP\n\n## Font Optimization\n\nSee [font.md](./font.md) for:\n\n- `next/font` setup\n- Google Fonts, local fonts\n- Tailwind CSS integration\n- Preloading subsets\n\n## Bundling\n\nSee [bundling.md](./bundling.md) for:\n\n- Server-incompatible packages\n- CSS imports (not link tags)\n- Polyfills (already included)\n- ESM/CommonJS issues\n- Bundle analysis\n\n## Scripts\n\nSee [scripts.md](./scripts.md) for:\n\n- `next/script` vs native script tags\n- Inline scripts need `id`\n- Loading strategies\n- Google Analytics with `@next/third-parties`\n\n## Hydration Errors\n\nSee [hydration-error.md](./hydration-error.md) for:\n\n- Common causes (browser APIs, dates, invalid HTML)\n- Debugging with error overlay\n- Fixes for each cause\n\n## Suspense Boundaries\n\nSee [suspense-boundaries.md](./suspense-boundaries.md) for:\n\n- CSR bailout with `useSearchParams` and `usePathname`\n- Which hooks require Suspense boundaries\n\n## Parallel & Intercepting Routes\n\nSee [parallel-routes.md](./parallel-routes.md) for:\n\n- Modal patterns with `@slot` and `(.)` interceptors\n- `default.tsx` for fallbacks\n- Closing modals correctly with `router.back()`\n\n## Self-Hosting\n\nSee [self-hosting.md](./self-hosting.md) for:\n\n- `output: 'standalone'` for Docker\n- Cache handlers for multi-instance ISR\n- What works vs needs extra setup\n\n## Debug Tricks\n\nSee [debug-tricks.md](./debug-tricks.md) for:\n\n- MCP endpoint for AI-assisted debugging\n- Rebuild specific routes with `--debug-build-paths`\n",".agents/skills/next-best-practices/async-patterns.md":"# Async Patterns\n\nIn Next.js 15+, `params`, `searchParams`, `cookies()`, and `headers()` are asynchronous.\n\n## Async Params and SearchParams\n\nAlways type them as `Promise<...>` and await them.\n\n### Pages and Layouts\n\n```tsx\ntype Props = { params: Promise<{ slug: string }> };\n\nexport default async function Page({ params }: Props) {\n const { slug } = await params;\n}\n```\n\n### Route Handlers\n\n```tsx\nexport async function GET(request: Request, { params }: { params: Promise<{ id: string }> }) {\n const { id } = await params;\n}\n```\n\n### SearchParams\n\n```tsx\ntype Props = {\n params: Promise<{ slug: string }>;\n searchParams: Promise<{ query?: string }>;\n};\n\nexport default async function Page({ params, searchParams }: Props) {\n const { slug } = await params;\n const { query } = await searchParams;\n}\n```\n\n### Synchronous Components\n\nUse `React.use()` for non-async components:\n\n```tsx\nimport { use } from 'react';\n\ntype Props = { params: Promise<{ slug: string }> };\n\nexport default function Page({ params }: Props) {\n const { slug } = use(params);\n}\n```\n\n### generateMetadata\n\n```tsx\ntype Props = { params: Promise<{ slug: string }> };\n\nexport async function generateMetadata({ params }: Props): Promise {\n const { slug } = await params;\n return { title: slug };\n}\n```\n\n## Async Cookies and Headers\n\n```tsx\nimport { cookies, headers } from 'next/headers';\n\nexport default async function Page() {\n const cookieStore = await cookies();\n const headersList = await headers();\n\n const theme = cookieStore.get('theme');\n const userAgent = headersList.get('user-agent');\n}\n```\n\n## Migration Codemod\n\n```bash\nnpx @next/codemod@latest next-async-request-api .\n```\n",".agents/skills/next-best-practices/bundling.md":"# Bundling\n\nFix common bundling issues with third-party packages.\n\n## Server-Incompatible Packages\n\nSome packages use browser APIs (`window`, `document`, `localStorage`) and fail in Server Components.\n\n### Error Signs\n\n```\nReferenceError: window is not defined\nReferenceError: document is not defined\nReferenceError: localStorage is not defined\nModule not found: Can't resolve 'fs'\n```\n\n### Solution 1: Mark as Client-Only\n\nIf the package is only needed on client:\n\n```tsx\n// Bad: Fails - package uses window\nimport SomeChart from 'some-chart-library';\n\nexport default function Page() {\n return ;\n}\n\n// Good: Use dynamic import with ssr: false\nimport dynamic from 'next/dynamic';\n\nconst SomeChart = dynamic(() => import('some-chart-library'), {\n ssr: false\n});\n\nexport default function Page() {\n return ;\n}\n```\n\n### Solution 2: Externalize from Server Bundle\n\nFor packages that should run on server but have bundling issues:\n\n```js\n// next.config.js\nmodule.exports = {\n serverExternalPackages: ['problematic-package']\n};\n```\n\nUse this for:\n\n- Packages with native bindings (sharp, bcrypt)\n- Packages that don't bundle well (some ORMs)\n- Packages with circular dependencies\n\n### Solution 3: Client Component Wrapper\n\nWrap the entire usage in a client component:\n\n```tsx\n// components/ChartWrapper.tsx\n'use client';\n\nimport { Chart } from 'chart-library';\n\nexport function ChartWrapper(props) {\n return ;\n}\n\n// app/page.tsx (server component)\nimport { ChartWrapper } from '@/components/ChartWrapper';\n\nexport default function Page() {\n return ;\n}\n```\n\n## CSS Imports\n\nImport CSS files instead of using `` tags. Next.js handles bundling and optimization.\n\n```tsx\n// Bad: Manual link tag\n;\n\n// Good: Import CSS\nimport './styles.css';\n\n// Good: CSS Modules\nimport styles from './Button.module.css';\n```\n\n## Polyfills\n\nNext.js includes common polyfills automatically. Don't load redundant ones from polyfill.io or similar CDNs.\n\nAlready included: `Array.from`, `Object.assign`, `Promise`, `fetch`, `Map`, `Set`, `Symbol`, `URLSearchParams`, and 50+ others.\n\n```tsx\n// Bad: Redundant polyfills\n;\n\n// Good: Next.js Script component\nimport Script from 'next/script';\n\n\n```\n\n## Don't Put Script in Head\n\n`next/script` should not be placed inside `next/head`. It handles its own positioning.\n\n```tsx\n// Bad: Script inside Head\nimport Head from 'next/head'\nimport Script from 'next/script'\n\n\n \n\n// Good: Next.js component\nimport { GoogleAnalytics } from '@next/third-parties/google'\n\nexport default function Layout({ children }) {\n return (\n \n {children}\n \n \n )\n}\n```\n\n## Google Tag Manager\n\n```tsx\nimport { GoogleTagManager } from '@next/third-parties/google';\n\nexport default function Layout({ children }) {\n return (\n \n \n {children}\n \n );\n}\n```\n\n## Other Third-Party Scripts\n\n```tsx\n// YouTube embed\nimport { YouTubeEmbed } from '@next/third-parties/google';\n\n;\n\n// Google Maps\nimport { GoogleMapsEmbed } from '@next/third-parties/google';\n\n;\n```\n\n## Quick Reference\n\n| Pattern | Issue | Fix |\n| --------------------------------------------- | -------------------------- | ------------------------- |\n| `;\n\n// Good: Next.js Script component\nimport Script from 'next/script';\n\n\n```\n\n## Don't Put Script in Head\n\n`next/script` should not be placed inside `next/head`. It handles its own positioning.\n\n```tsx\n// Bad: Script inside Head\nimport Head from 'next/head'\nimport Script from 'next/script'\n\n\n \n\n// Good: Next.js component\nimport { GoogleAnalytics } from '@next/third-parties/google'\n\nexport default function Layout({ children }) {\n return (\n \n {children}\n \n \n )\n}\n```\n\n## Google Tag Manager\n\n```tsx\nimport { GoogleTagManager } from '@next/third-parties/google';\n\nexport default function Layout({ children }) {\n return (\n \n \n {children}\n \n );\n}\n```\n\n## Other Third-Party Scripts\n\n```tsx\n// YouTube embed\nimport { YouTubeEmbed } from '@next/third-parties/google';\n\n;\n\n// Google Maps\nimport { GoogleMapsEmbed } from '@next/third-parties/google';\n\n;\n```\n\n## Quick Reference\n\n| Pattern | Issue | Fix |\n| --------------------------------------------- | -------------------------- | ------------------------- |\n| `;\n\n// Good: Next.js Script component\nimport Script from 'next/script';\n\n\n```\n\n## Don't Put Script in Head\n\n`next/script` should not be placed inside `next/head`. It handles its own positioning.\n\n```tsx\n// Bad: Script inside Head\nimport Head from 'next/head'\nimport Script from 'next/script'\n\n\n \n\n// Good: Next.js component\nimport { GoogleAnalytics } from '@next/third-parties/google'\n\nexport default function Layout({ children }) {\n return (\n \n {children}\n \n \n )\n}\n```\n\n## Google Tag Manager\n\n```tsx\nimport { GoogleTagManager } from '@next/third-parties/google';\n\nexport default function Layout({ children }) {\n return (\n \n \n {children}\n \n );\n}\n```\n\n## Other Third-Party Scripts\n\n```tsx\n// YouTube embed\nimport { YouTubeEmbed } from '@next/third-parties/google';\n\n;\n\n// Google Maps\nimport { GoogleMapsEmbed } from '@next/third-parties/google';\n\n;\n```\n\n## Quick Reference\n\n| Pattern | Issue | Fix |\n| --------------------------------------------- | -------------------------- | ------------------------- |\n| `;\n\n// Good: Next.js Script component\nimport Script from 'next/script';\n\n\n```\n\n## Don't Put Script in Head\n\n`next/script` should not be placed inside `next/head`. It handles its own positioning.\n\n```tsx\n// Bad: Script inside Head\nimport Head from 'next/head'\nimport Script from 'next/script'\n\n\n \n\n// Good: Next.js component\nimport { GoogleAnalytics } from '@next/third-parties/google'\n\nexport default function Layout({ children }) {\n return (\n \n {children}\n \n \n )\n}\n```\n\n## Google Tag Manager\n\n```tsx\nimport { GoogleTagManager } from '@next/third-parties/google';\n\nexport default function Layout({ children }) {\n return (\n \n \n {children}\n \n );\n}\n```\n\n## Other Third-Party Scripts\n\n```tsx\n// YouTube embed\nimport { YouTubeEmbed } from '@next/third-parties/google';\n\n;\n\n// Google Maps\nimport { GoogleMapsEmbed } from '@next/third-parties/google';\n\n;\n```\n\n## Quick Reference\n\n| Pattern | Issue | Fix |\n| --------------------------------------------- | -------------------------- | ------------------------- |\n| `