@acmekit/acmekit 2.13.86 → 2.13.88

package/dist/templates/app/.claude/rules/testing.md

@@ -8,7 +8,30 @@ paths:
 
 # Testing Rules
 
-## Critical — Read Before Writing Any Test
+## Pre-Flight Checklist (MANDATORY before writing any test)
+
+Complete these steps IN ORDER before writing a single line of test code:
+
+1. **Verify migrations are current.** Run `npx acmekit db:generate <module>` and `npx acmekit db:migrate` if you changed any model. `mode: "app"` runs real migrations — custom modules MUST have migration files or you get `TableNotFoundException`.
+
+2. **Verify jest config buckets.** Read `jest.config.js` and confirm the test type you need exists:
+   ```
+   integration:http    → integration-tests/http/
+   integration:app     → integration-tests/app/
+   integration:modules → src/modules/*/__tests__/
+   unit                → src/**/__tests__/*.unit.spec.ts
+   ```
+   If the bucket is missing, add the jest config entry BEFORE writing the test. A test file in a directory with no matching jest config is silently ignored.
+
+3. **Read the source code under test.** Read service methods, route handlers, workflow steps, subscriber handlers — understand actual method signatures, return types, and error paths.
+
+4. **Read mock interfaces.** When your test depends on auto-injected mocks (`MockEventBusService`, `MockLockingService`, `MockSecretsService`), read the mock source in `@acmekit/test-utils` to verify method names and signatures. Do NOT assume mock methods match the real service 1:1 — mocks have convenience methods (e.g., `setSecret()`, `getEmittedEvents()`) and may omit advanced features.
+
+5. **Identify the correct test tier.** Match your test to the right mode and file location (see Test Runner Selection below).
+
+---
+
+## Critical Rules
 
 **Single unified runner.** Use `integrationTestRunner` from `@acmekit/test-utils` with a `mode` parameter. The old names (`acmekitIntegrationTestRunner`, `moduleIntegrationTestRunner`) are deprecated aliases — NEVER use them.
 
@@ -520,29 +543,18 @@ expect(response.data).toEqual({
 
 ## Asserting Domain Events
 
-Both runners inject `MockEventBusService` under `Modules.EVENT_BUS` in module mode. Spy on the **prototype**, not an instance.
+`MockEventBusService` accumulates all emitted events. Use `.getEmittedEvents()` — no spy needed.
 
 ```typescript
-import { MockEventBusService } from "@acmekit/test-utils"
-
-let eventBusSpy: jest.SpyInstance
-
-beforeEach(() => {
-  eventBusSpy = jest.spyOn(MockEventBusService.prototype, "emit")
-})
-
-afterEach(() => {
-  eventBusSpy.mockClear()
-})
-
 it("should emit post.created event", async () => {
   await service.createPosts([{ title: "Event Test" }])
 
-  const events = eventBusSpy.mock.calls[0][0]
+  const eventBus = getContainer().resolve(Modules.EVENT_BUS)
+  const events = eventBus.getEmittedEvents()
   expect(events).toEqual(
     expect.arrayContaining([
       expect.objectContaining({
-        name: "post.created",
+        name: "post.created",  // NOTE: property is "name", NOT "eventName"
         data: expect.objectContaining({ id: expect.any(String) }),
       }),
     ])
@@ -550,6 +562,8 @@ it("should emit post.created event", async () => {
 })
 ```
 
+> `emitEventStep` maps `eventName` to `name` internally — always assert on `event.name`.
+
 ---
 
 ## Waiting for Subscribers
@@ -904,6 +918,61 @@ await expect(provider.process(badInput)).rejects.toThrow("validation")
 
 ---
 
+## Auto-Injected Infrastructure Mocks
+
+The test runner automatically injects mock implementations for infrastructure modules in plugin and module modes. You do NOT need to manually inject these:
+
+| Module | Mock class | Behavior |
+|---|---|---|
+| `Modules.EVENT_BUS` | `MockEventBusService` | Accumulates events — call `.getEmittedEvents()` to inspect |
+| `Modules.LOCKING` | `MockLockingService` | In-memory locking — `execute()` runs job immediately, acquire/release tracked |
+| `Modules.SECRETS` | `MockSecretsService` | In-memory store — pre-populate with `.setSecret(id, value)` |
+
+Override any mock via `injectedDependencies` if needed — user overrides take precedence.
+
+### Asserting emitted events (no spy needed)
+
+```typescript
+const eventBus = getContainer().resolve(Modules.EVENT_BUS)
+
+await createPostWorkflow(getContainer()).run({ input: { title: "Test" } })
+
+// Inspect emitted events directly — no jest.spyOn needed
+const events = eventBus.getEmittedEvents()
+const postEvent = events.find((e: any) => e.name === "post.created")
+expect(postEvent).toBeDefined()
+expect(postEvent.data).toEqual(expect.objectContaining({ id: expect.any(String) }))
+```
+
+> Event objects have `{ name, data, metadata?, options? }`. The property is `name`, NOT `eventName` — `emitEventStep` maps `eventName` to `name` internally.
+
+---
+
+## Client Routes Require API Key
+
+Routes under `/client/*` use `AcmeKitTypedRequest` (non-authenticated), but they are NOT fully public. AcmeKit middleware enforces a client API key header on all `/client/*` routes. "Public" means "no user authentication" — a client API key is still required.
+
+---
+
+## Known Environment Issues
+
+### Database Teardown Permission Errors
+
+**Symptom:** `permission denied for schema public` or `cannot drop schema` during test teardown (afterAll).
+
+**Cause:** PostgreSQL user lacks `CREATE`/`DROP` privileges on the `public` schema, or concurrent test processes hold locks.
+
+**Fix:**
+```bash
+# Grant full privileges to the test user (run once)
+psql -U postgres -c "GRANT ALL ON SCHEMA public TO <your_user>;"
+psql -U postgres -c "ALTER USER <your_user> CREATEDB;"
+```
+
+This is an environment setup issue, not a test code issue. If teardown fails but all tests passed, the test results are still valid.
+
+---
+
 ## Anti-Patterns — NEVER Do These
 
 ```typescript
@@ -1068,4 +1137,15 @@ const re = new RegExp("^(\\*|[0-9]+)(\\/[0-9]+)?$")
 const result = await provider.process(bad)
 expect(result.success).toBe(false)  // ❌ actually throws
 // RIGHT — read implementation first to check if it throws or returns
+
+// WRONG — using jest.spyOn to inspect emitted events
+jest.spyOn(MockEventBusService.prototype, "emit")  // ❌ fragile, complex extraction
+// RIGHT — use built-in event accumulation
+const eventBus = getContainer().resolve(Modules.EVENT_BUS)
+const events = eventBus.getEmittedEvents()
+
+// WRONG — checking event.eventName (emitEventStep maps eventName → name internally)
+expect(event.eventName).toBe("post.created")  // ❌ property doesn't exist
+// RIGHT
+expect(event.name).toBe("post.created")
 ```

package/dist/templates/app/.claude/rules/workflows.md

@@ -502,6 +502,8 @@ dismissRemoteLinkStep([{
 
 Always resolve services fresh from `container`. Never capture from closure in compensation.
 
+**Workflow steps have the full application container** — they can resolve ANY module. Module providers and services are scoped to their parent module and cannot resolve other modules. When a provider needs cross-module dependencies, the step resolves them and passes them through the service to the provider as method parameters (see `modules.md` → Provider Container Scoping).
+
 ```typescript
 // Typed resolution (preferred)
 const service = container.resolve<IBlogModuleService>(BLOG_MODULE)

package/dist/templates/app/.claude/skills/admin-customization/SKILL.md

@@ -376,6 +376,16 @@ Each widget file exports exactly one default component and one `config`.
 
 Widgets receive no props. Fetch all data internally using hooks.
 
+### Admin Dependencies
+
+Form-related packages are provided by acmekit — do NOT install them separately:
+
+- `react-hook-form` — import `useForm` from `"react-hook-form"` (available transitively)
+- `@hookform/resolvers` — import `zodResolver` from `"@hookform/resolvers/zod"` (available transitively)
+- `zod` — import as `import * as zod from "@acmekit/deps/zod"` (NOT `from "zod"`)
+
+**For plugins:** Add `react-hook-form` and `@hookform/resolvers` to `peerDependencies` (+ `devDependencies` mirror), never just `devDependencies`.
+
 ### Prefer Shared SDK Over Raw Fetch
 
 Use `src/admin/lib/sdk.ts` for backend calls so auth, path prefixes, and route typings stay consistent:

package/dist/templates/app/.claude/skills/write-test/SKILL.md

@@ -15,6 +15,13 @@ Generate tests for AcmeKit applications using `integrationTestRunner` with the c
 - HTTP integration tests: !`ls integration-tests/http/*.spec.ts 2>/dev/null || echo "(none)"`
 - App integration tests: !`ls integration-tests/app/*.spec.ts 2>/dev/null || echo "(none)"`
 
+## Pre-Flight Checklist (MANDATORY — do these BEFORE writing any test)
+
+1. **Verify migrations are current.** If model files changed, run `npx acmekit db:generate <module>` + `npx acmekit db:migrate`. Missing migrations cause `TableNotFoundException`.
+2. **Verify jest config buckets.** Read `jest.config.js` — confirm the bucket you need exists (`integration:http`, `integration:app`, `integration:modules`, `unit`). If missing, add the entry and create the directory first.
+3. **Read source code under test.** Understand method signatures, return types, error handling.
+4. **Read mock interfaces.** If using auto-injected mocks, read their source to verify method names. Don't guess from real service interfaces.
+
 ## Critical Gotchas — Every Test Must Get These Right
 
 1. **Unified runner only.** `import { integrationTestRunner } from "@acmekit/test-utils"`. NEVER use `acmekitIntegrationTestRunner` or `moduleIntegrationTestRunner` — those are deprecated.

package/dist/templates/app/CLAUDE.md

@@ -8,7 +8,8 @@ You are a senior AcmeKit framework developer. Build features using code generato
 
 - Edit files in `src/types/generated/` — overwritten by `npx acmekit generate types`
 - Import from `.acmekit/types/` or `src/types/generated/` directly — use `InferTypeOf` or barrel exports
-- Import `zod`, `awilix`, or `pg` directly — use `@acmekit/framework/zod`, `@acmekit/framework/awilix`, `@acmekit/framework/pg`
+- Import `zod`, `awilix`, or `pg` directly — backend: use `@acmekit/framework/zod`, `@acmekit/framework/awilix`, `@acmekit/framework/pg`; admin UI: use `@acmekit/deps/zod`
+- Add `react-hook-form` or `@hookform/resolvers` as dependencies — they are provided by acmekit
 - Use string literals for container keys — use `ContainerRegistrationKeys.*` and `Modules.*`
 - Call services directly for mutations in routes — use workflows
 - Put business logic in workflow steps — steps are thin wrappers; service methods own orchestration

package/dist/templates/plugin/.claude/agents/code-reviewer.md

@@ -76,8 +76,11 @@ For each match: if the method name has no `_` suffix it's a public method — wr
 ```
 grep -rn "Module(" src/modules/ | grep -v "ModuleProvider\|AcmeKitService"
 grep -rn "static identifier" src/modules/
+grep -rn "this\.container_\[" src/modules/
+grep -rn "container_\." src/modules/ | grep -v "logger\|options\|container_:"
 ```
 Check: any file with `ModuleProvider` that uses `Module()` instead → wrong export format.
+Check: providers resolving other modules from `this.container_` → module-scoped container can't see other modules. Cross-module deps must be passed as method params from the workflow step through the service.
 
 **If hasWorkflows:**
 ```
@@ -93,7 +96,9 @@ grep -rn "res\.json.*result\b" src/api/
 grep -rn "validators\.ts" src/api/
 grep -rn "import.*from.*\/service\"" src/api/
 grep -rn "validatedBody as any" src/api/
+grep -rn "req\.validatedQuery[^?]" src/api/
 ```
+For `req.validatedQuery`: verify every destructuring uses `?? {}` fallback (e.g., `req.validatedQuery ?? {}`). Without it, requests with no query string crash.
 
 **If hasSubscribers:**
 ```
@@ -109,7 +114,12 @@ grep -rn "await.*service\." src/jobs/
 ```
 grep -rn "^export default function " src/admin/
 grep -rn "zone:.*\`\|zone:.*\+" src/admin/
+grep -rn "from [\"']zod[\"']" src/admin/
+grep -rn "<SectionRow.*>" src/admin/ | grep "children\|>" | grep -v "/>"
+grep -rn "react-hook-form\|@hookform" package.json
+grep -rn "useDataTable" src/admin/
 ```
+For each `useDataTable` match with `filtering` config: check that the companion `useQuery` includes filter/search state in `queryKey` AND passes filter params in `queryFn`. A static `queryKey` like `["items"]` with filtering enabled means filters do nothing (server-side filtering, `manualFiltering: true`).
 
 ### Step 5 — Read matched files
 For every file with a hit, read it fully to confirm the issue in context.
@@ -155,6 +165,7 @@ Only work through sections for detected features. Explicitly skip and note secti
 - [ ] `PREFIX` and `IDENTIFIER_KEY` constants defined once in `constants.ts`, never hardcoded inline
 - [ ] `createProvidersLoader` used for modules accepting providers — no hand-rolled provider loops
 - [ ] Service resolves providers via `this.providers.resolve(id)` — NOT `(this as any).__container__`
+- [ ] Providers do NOT resolve other modules from `this.container_` (constructor or property access) — provider containers are module-scoped. Cross-module deps must be received as method parameters, resolved by the workflow step and passed through the parent module's service
 
 ### Workflows — only if hasWorkflows
 - [ ] Steps in `src/workflows/steps/<name>.ts` — one per file, not in workflow files
@@ -180,6 +191,7 @@ Only work through sections for detected features. Explicitly skip and note secti
 - [ ] `defineRouteConfig` with Zod body (`.strict()`) and/or query schemas
 - [ ] No `validators.ts` for new routes
 - [ ] `req.validatedBody`, `req.validatedQuery`, `req.queryConfig` — not `req.remoteQueryConfig`
+- [ ] `req.validatedQuery` destructured with `?? {}` fallback — undefined when request has no query string
 - [ ] Every method that uses `req.queryConfig` has BOTH `query` and `queryConfig` in its config — `queryConfig` without `query` is silently ignored
 - [ ] `additional_data` destructured without `as any` — `validatedBody` is already typed
 - [ ] Mutations: workflow → `query.graph()` refetch → return refetched data
@@ -217,6 +229,12 @@ Only work through sections for detected features. Explicitly skip and note secti
 - [ ] `usePrompt()` before destructive actions
 - [ ] API calls via shared SDK from `src/admin/lib/sdk.ts`
 - [ ] `useRouteModal().handleSuccess()` for navigation after create/edit
+- [ ] Zod imported from `@acmekit/deps/zod` — NOT bare `"zod"`
+- [ ] `SectionRow` uses only `title`, `value`, `actions` props — no `children` (use `value` for custom JSX)
+- [ ] `onRowClick` callback uses `row.original.id` — NOT `row.id` (runtime is TanStack `Row<TData>` despite type)
+- [ ] DataTable with `filtering` config: `useQuery` queryKey includes filter/search/pagination state — NOT static like `["items"]`
+- [ ] DataTable with `filtering` config: `queryFn` passes filter state as query params to API — NOT fetching unfiltered data
+- [ ] `react-hook-form` and `@hookform/resolvers` in `peerDependencies` (not only `devDependencies`) — they are provided by acmekit
 
 ### Middlewares — only if hasMiddlewares
 - [ ] Every middleware calls `next()`

package/dist/templates/plugin/.claude/agents/test-writer.md

@@ -8,10 +8,24 @@ maxTurns: 20
 
 You are an AcmeKit test engineer for plugins. Generate comprehensive integration tests using the unified `integrationTestRunner` with the correct mode and patterns.
 
-**BEFORE writing any test:**
-1. Read `.claude/rules/testing.md` — it contains anti-patterns, fixtures, lifecycle, and error handling rules you MUST follow
-2. Read the source code you're testing — understand service methods, models, workflows, and subscribers
-3. Identify the correct test tier (HTTP, plugin container, module, or unit)
+**MANDATORY PRE-FLIGHT CHECKLIST — complete ALL steps before writing any test code:**
+
+1. **Read `.claude/rules/testing.md`** — contains anti-patterns, fixtures, lifecycle, and error handling rules you MUST follow.
+
+2. **Build the plugin.** Run `pnpm build` (or verify `pnpm dev` is running). Stale `.acmekit/server/` output causes cryptic errors (`__joinerConfig is not a function`, missing services). The test runner loads compiled JS from `.acmekit/server/`, not TypeScript source.
+
+3. **Verify jest config buckets.** Read `jest.config.js` and confirm the test bucket you need exists:
+   - `integration:plugin` → `integration-tests/plugin/`
+   - `integration:http` → `integration-tests/http/`
+   - `integration:modules` → `src/modules/*/__tests__/`
+   - `unit` → `src/**/__tests__/*.unit.spec.ts`
+   If the bucket is missing, add it to `jest.config.js` and create the directory BEFORE writing the test.
+
+4. **Read the source code under test** — understand service methods, models, workflows, subscribers, route paths, validators, response shapes, and error handling.
+
+5. **Read mock interfaces.** If your test uses auto-injected mocks (`MockEventBusService`, `MockLockingService`, `MockSecretsService`), read their actual source to verify exact method names and signatures. Do NOT guess — mocks have convenience methods (e.g., `setSecret()`, `getEmittedEvents()`) not on real services, and may omit some real service methods.
+
+6. **Identify the correct test tier** (HTTP, plugin container, module, or unit).
 
 ---
 
@@ -471,31 +485,22 @@ describe("MyProvider", () => {
 
 ## Asserting Domain Events (container-only mode)
 
-Plugin mode (without HTTP) injects `MockEventBusService`. Spy on the **prototype**, not an instance.
+`MockEventBusService` accumulates emitted events — use `.getEmittedEvents()` directly, no spy needed.
 
 ```typescript
-import { MockEventBusService } from "@acmekit/test-utils"
-
-let eventBusSpy: jest.SpyInstance
-
-beforeEach(() => {
-  eventBusSpy = jest.spyOn(MockEventBusService.prototype, "emit")
-})
-
-afterEach(() => {
-  eventBusSpy.mockClear()
-})
+import { Modules } from "@acmekit/framework/utils"
 
 it("should emit greeting.created event", async () => {
   const service: any = container.resolve(GREETING_MODULE)
   await service.createGreetings([{ message: "Event Test" }])
 
-  // MockEventBusService.emit receives an ARRAY of events
-  const events = eventBusSpy.mock.calls[0][0]
+  // Access events directly from the mock event bus — no spy needed
+  const eventBus = container.resolve(Modules.EVENT_BUS)
+  const events = eventBus.getEmittedEvents()
   expect(events).toEqual(
     expect.arrayContaining([
       expect.objectContaining({
-        name: "greeting.created",
+        name: "greeting.created",  // NOTE: property is "name", NOT "eventName"
         data: expect.objectContaining({ id: expect.any(String) }),
       }),
     ])
@@ -503,6 +508,8 @@ it("should emit greeting.created event", async () => {
 })
 ```
 
+> `emitEventStep` maps `eventName` to `name` internally — always assert on `event.name`.
+
 ---
 
 ## What to Test
@@ -538,8 +545,8 @@ it("should emit greeting.created event", async () => {
 - Auth: 401 without JWT, 400 without client API key
 
 **Events (container mode):**
-- Spy on `MockEventBusService.prototype.emit` (prototype, not instance)
-- Access events via `eventBusSpy.mock.calls[0][0]` (array of event objects)
+- Use `container.resolve(Modules.EVENT_BUS).getEmittedEvents()` — no spy needed
+- Event objects have `{ name, data }` — property is `name`, NOT `eventName`
 
 ---
 
@@ -576,8 +583,8 @@ it("should emit greeting.created event", async () => {
 - Use realistic test data ("Launch Announcement", "Quarterly Report") not "test", "foo"
 - Pass body directly: `api.post(url, body, headers)` — NOT `{ body: {...} }`
 - Runners handle DB setup/teardown — no manual cleanup needed
-- Spy on `MockEventBusService.prototype` — not an instance
-- `jest.restoreAllMocks()` in `afterEach` when spying
+- Use `eventBus.getEmittedEvents()` for event assertions — no spy ceremony
+- Event property is `name`, NOT `eventName` (`emitEventStep` maps internally)
 - NEVER use JSDoc blocks or type casts in test files
 - **Always `beforeEach(() => jest.clearAllMocks())`** in unit tests — mock state leaks between describes
 - **Never reference file-level `const`/`let` inside `jest.mock()` factories** — TDZ error

package/dist/templates/plugin/.claude/rules/admin-components.md

@@ -36,10 +36,18 @@ useDataTable({
   filtering:   { state: DataTableFilteringState, onFilteringChange: (v) => void },
   pagination:  { state: DataTablePaginationState, onPaginationChange: (v) => void },
   rowSelection: { state: DataTableRowSelectionState, onRowSelectionChange: (v) => void, enableRowSelection?: boolean | ((row) => boolean) },
-  onRowClick:  (event, row) => void,
+  onRowClick:  (event, row) => void,  // see note below
 })
 ```
 
+**`onRowClick` row parameter:** The TypeScript signature declares `row: TData`, but at runtime `row` is a TanStack `Row<TData>` object. Access your data via `row.original`:
+
+```tsx
+onRowClick: (_event, row) => navigate(row.original.id),
+```
+
+This is a known type mismatch in `useDataTable`. TypeScript may report an error on `row.original` — cast if needed: `(row as any).original.id`.
+
 State types: `DataTablePaginationState`, `DataTableSortingState`, `DataTableFilteringState`, `DataTableRowSelectionState` — all from `@acmekit/ui`.
 
 **`DataTable.Table` emptyState shape:**
@@ -274,6 +282,8 @@ const useFilters = () => {
 
 **Best practice**: For API-loaded filter options, fetch with `{ limit: 1000 }` and conditionally add the filter only when data is available.
 
+**CRITICAL**: `useDataTable` uses server-side filtering (`manualFiltering: true`). Defining filters alone does NOT filter data — you MUST wire filter state to the API query. See the "DataTable Server-Side Filtering" section in the admin-data rules for the complete pattern (building `queryParams` from filter/search state, including them in `queryKey`, and passing as URL query params in `queryFn`).
+
 ---
 
 ## Forms — Form.Field Compound Component
@@ -284,7 +294,11 @@ const useFilters = () => {
 import { Form, Input, Textarea, Select, Switch } from "@acmekit/ui"
 import { useForm } from "react-hook-form"
 import { zodResolver } from "@hookform/resolvers/zod"
-import * as zod from "zod"
+import * as zod from "@acmekit/deps/zod"
+
+// NOTE: react-hook-form and @hookform/resolvers are provided by acmekit.
+// In plugins: list them in peerDependencies (NOT devDependencies).
+// In apps: they are available transitively — no extra dependency needed.
 
 const Schema = zod.object({
   title: zod.string().min(1, "Title is required"),
@@ -412,7 +426,7 @@ import { useForm } from "react-hook-form"
 import { zodResolver } from "@hookform/resolvers/zod"
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query"
 import { useParams } from "react-router-dom"
-import * as zod from "zod"
+import * as zod from "@acmekit/deps/zod"
 import { sdk } from "../../../../lib/sdk"
 
 const EditSchema = zod.object({
@@ -544,7 +558,7 @@ import { Button, RouteFocusModal, Form, Heading, Input, Text, Textarea, toast, K
 import { useForm } from "react-hook-form"
 import { zodResolver } from "@hookform/resolvers/zod"
 import { useMutation, useQueryClient } from "@tanstack/react-query"
-import * as zod from "zod"
+import * as zod from "@acmekit/deps/zod"
 import { sdk } from "../../../lib/sdk"
 
 const CreateSchema = zod.object({

package/dist/templates/plugin/.claude/rules/admin-data.md

@@ -75,6 +75,69 @@ const { data, isLoading } = useQuery({
 })
 ```
 
+### DataTable Server-Side Filtering
+
+**`useDataTable` uses `manualFiltering: true`** — it does NOT filter data client-side. Filter/search/pagination state must be sent to the API as query parameters. If you don't wire state to the query, changing filters has no effect.
+
+```tsx
+const [search, setSearch] = useState("")
+const [filtering, setFiltering] = useState<DataTableFilteringState>({})
+const [pagination, setPagination] = useState<DataTablePaginationState>({
+  pageIndex: 0,
+  pageSize: 20,
+})
+
+// Build query params from filter/search/pagination state
+const queryParams = useMemo(() => {
+  const params: Record<string, string> = {}
+
+  Object.entries(filtering).forEach(([key, value]) => {
+    if (value == null) return
+    if (Array.isArray(value) && value.length > 0) {
+      params[key] = value.join(",")
+    } else if (!Array.isArray(value)) {
+      params[key] = String(value)
+    }
+  })
+
+  if (search) {
+    params.q = search
+  }
+
+  return params
+}, [filtering, search])
+
+// Include queryParams in queryKey so React Query refetches on filter changes
+const { data, isLoading } = useQuery({
+  queryKey: ["wallets", queryParams],
+  queryFn: () => {
+    const qs = new URLSearchParams(queryParams).toString()
+    return sdk.admin.fetch(`/wallets${qs ? `?${qs}` : ""}`, {
+      method: "GET",
+    })
+  },
+})
+
+const table = useDataTable({
+  data: data?.wallets ?? [],
+  columns,
+  filters,
+  getRowId: (row) => row.id,
+  rowCount: data?.count ?? data?.wallets?.length ?? 0,
+  isLoading,
+  search: { state: search, onSearchChange: setSearch },
+  filtering: { state: filtering, onFilteringChange: setFiltering },
+  pagination: { state: pagination, onPaginationChange: setPagination },
+})
+```
+
+**Key rules:**
+- `queryKey` MUST include filter/search/pagination state — otherwise React Query won't refetch when filters change
+- `queryFn` MUST pass state as query parameters to the API
+- Multiselect filters produce `string[]` — serialize as comma-separated for query params
+- Radio filters produce `string` — pass directly
+- The API route must handle these params (see `api-routes.md` for array filter handling)
+
 ---
 
 ## Action Menus — ActionMenu Component
@@ -247,6 +310,10 @@ const confirmed = await prompt({
 **Entity types:**
 - Hand-writing `type Payment = { id: string; status: string; created_at: string }` instead of inferring from SDK. Hand-written types drift from response schemas: date fields should be `string | Date` (from `z.union`), nullable fields need `| null`, enum fields are `string` (not the user enum). Always use `type Payment = Awaited<ReturnType<typeof sdk.admin.fetch<"/admin/payments", "GET">>>["items"][0]`
 
+**Imports & dependencies:**
+- Importing `zod` from `"zod"` in admin code — use `import * as zod from "@acmekit/deps/zod"` to share the same zod instance as acmekit
+- Adding `react-hook-form` or `@hookform/resolvers` to `devDependencies` — they are provided by acmekit. In plugins: list them in `peerDependencies` (+ `devDependencies` mirror). In apps: they are available transitively, no extra dependency needed
+
 **Form context:**
 - Using `Form.Field`, `Form.Label`, `SwitchBox`, or any `Form.*` sub-component without a form provider — they call `useFormContext()` and crash with "Cannot destructure property 'getFieldState' of 'useFormContext(...)' as it is null". `RouteDrawer.Form` / `RouteFocusModal.Form` provide this automatically; standalone pages must wrap with `<Form {...form}>` from `@acmekit/ui`
 - Importing `FormProvider` from `react-hook-form` directly — causes dual-instance context mismatch. Always use `Form` from `@acmekit/ui` (it IS the FormProvider re-export)
@@ -265,6 +332,8 @@ const confirmed = await prompt({
 - Not using `size="small"` on ALL buttons (header actions, form buttons, table actions)
 
 **DataTable:**
+- **Static `queryKey` with filters** — using `queryKey: ["posts"]` when the table has filters/search/pagination. The `queryKey` MUST include filter/search/pagination state so React Query refetches when they change: `queryKey: ["posts", queryParams]`
+- **Not passing filter state to the API** — `useDataTable` uses `manualFiltering: true` (server-side). If the `queryFn` doesn't send filter values as query parameters, changing filters has zero effect on the displayed data
 - Passing `columns`, `filters`, `heading`, `emptyState` as props to `<DataTable>` — it only accepts `instance`. Use sub-components: `DataTable.Toolbar`, `DataTable.Table`, etc.
 - Using boolean flags like `enablePagination: true` in `useDataTable` — pass state objects: `pagination: { state, onPaginationChange }`
 - Using `table.getState().rowSelection` — use `table.getRowSelection()` instead
@@ -272,6 +341,7 @@ const confirmed = await prompt({
 - Passing `commands` as a prop to `<DataTable>` — pass to `useDataTable` hook and render `<DataTable.CommandBar>`
 - Using `Container className="divide-y p-0"` for DataTable pages — use `Container className="flex flex-col overflow-hidden p-0"` (DataTable needs flex layout)
 - Rendering a `DataTable.*` sub-component without its matching state in `useDataTable` — causes runtime crash. `.Search` requires `search`, `.SortingMenu` requires `sorting`, `.FilterMenu` requires `filters`, `.CommandBar` requires `commands` + `rowSelection`. Never add a sub-component without wiring its state.
+- Using `row.id` in `onRowClick` — `row` is a TanStack `Row<TData>` at runtime (despite the `TData` type signature). Access data via `row.original.id`. Cast if needed: `(row as any).original.id`.
 
 **Error handling:**
 - Using `toast.error` for query errors — throw them (`if (isError) throw error`) for error boundary
@@ -299,6 +369,9 @@ const confirmed = await prompt({
 - Not breaking large detail pages into section components — if a detail page has 3+ sections, each should be its own component in `components/`
 - Putting delete logic inline instead of extracting a reusable `useDelete*Action` hook when the same delete is used in multiple places
 
+**SectionRow:**
+- Passing `children` to `SectionRow` — it does NOT accept children. Use the `value` prop for custom JSX content (badges, copy buttons, formatted text). `SectionRow` only accepts `title`, `value`, and `actions`.
+
 **Wrong component for context:**
 - Using `StatusBadge` in DataTable columns — use `StatusCell` instead (dot indicator, truncation-safe)
 - Using raw `Switch` + manual label/description instead of `SwitchBox` for toggle settings

package/dist/templates/plugin/.claude/rules/admin-patterns.md

@@ -535,6 +535,26 @@ import { SectionRow } from "@acmekit/ui"
 
 **Props**: `title: string`, `value?: ReactNode | string | null`, `actions?: ReactNode`.
 
+**SectionRow does NOT accept `children`.** Pass custom JSX through the `value` prop instead:
+
+```tsx
+// WRONG — children is not a valid prop (TypeScript error)
+<SectionRow title="Address">
+  <div className="font-mono">{wallet.address}</div>
+</SectionRow>
+
+// RIGHT — use value prop for custom JSX content
+<SectionRow
+  title="Address"
+  value={
+    <div className="group flex items-center gap-x-2">
+      <Text size="small" className="font-mono">{wallet.address}</Text>
+      <Copy content={wallet.address} className="hidden group-hover:block" />
+    </div>
+  }
+/>
+```
+
 ---
 
 ## Component Organization — Scaling Beyond page.tsx

package/dist/templates/plugin/.claude/rules/api-routes.md

@@ -145,6 +145,24 @@ query: z.object({
 })
 ```
 
+**Query schemas — multiselect filter params:**
+- Admin DataTable multiselect filters send array values as comma-separated strings (e.g., `?status=active,draft`)
+- Use `z.preprocess` to split comma-separated strings into arrays:
+```typescript
+status: z.preprocess(
+  (v) => (typeof v === "string" ? v.split(",") : v),
+  z.array(z.string()).optional()
+),
+```
+- For enum arrays, chain with `z.enum()` inside the array:
+```typescript
+network: z.preprocess(
+  (v) => (typeof v === "string" ? v.split(",") : v),
+  z.array(z.enum(["mainnet", "testnet"])).optional()
+),
+```
+- In the handler, pass non-empty arrays to the service filter: `if (status?.length) listFilters.status = status`
+
 **Body schemas:**
 - `.strict()` on create/update bodies to reject unknown fields
 - `.nullish()` on fields that can be explicitly cleared to null (not just `.optional()`)
@@ -346,7 +364,7 @@ res.status(200).json({ id, object: "blog_post", deleted: true })
 | Property | Available on | Description |
 |---|---|---|
 | `req.validatedBody` | POST routes with `body` config | Validated request body |
-| `req.validatedQuery` | Routes with `query` config | Validated query params (all params) |
+| `req.validatedQuery` | Routes with `query` config | Validated query params (all params). **Can be `undefined` when request has no query string** — always destructure with `?? {}` fallback |
 | `req.filterableFields` | Routes with `query` config | Query params minus pagination/fields/order |
 | `req.queryConfig.fields` | Routes with `queryConfig` | Array of field strings to select |
 | `req.queryConfig.pagination` | Routes with `queryConfig` | `{ skip, take, order }` |
@@ -748,4 +766,10 @@ const { additional_data, ...body } = req.validatedBody as any  // ❌ defeats al
 
 // RIGHT — validatedBody is already typed from the body schema; no cast needed
 const { additional_data, ...body } = req.validatedBody  // ✅ type inferred from defineRouteConfig
+
+// WRONG — destructuring req.validatedQuery without fallback (undefined when no query params sent)
+const { enabled, ...filters } = req.validatedQuery  // ❌ crashes if request has no query string
+
+// RIGHT — always provide fallback when destructuring validatedQuery
+const { enabled, ...filters } = req.validatedQuery ?? {}  // ✅ safe when no query params
 ```