@acmekit/acmekit 2.13.89 → 2.13.90

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

@@ -420,6 +420,8 @@ File: `src/admin/routes/custom/[id]/edit/page.tsx`
 
 **Critical structure**: Use `RouteDrawer.Form` wrapping `KeyboundForm` — this handles dirty form blocking on close and Cmd/Ctrl+Enter submit. The `KeyboundForm` wraps BOTH `RouteDrawer.Body` AND `RouteDrawer.Footer` so `type="submit"` works. Use `useRouteModal()` for `handleSuccess` to close the modal after success.
 
+**IMPORTANT**: `useRouteModal()` must be called in a **child component** rendered inside `<RouteDrawer>`, not in the same component that renders it. The `RouteModalProvider` context is created inside `RouteDrawer`, so calling the hook in the parent component crashes with "useRouteModal must be used within a RouteModalProvider".
+
 ```tsx
 import { Button, RouteDrawer, Form, Heading, Input, Textarea, toast, KeyboundForm, useRouteModal } from "@acmekit/ui"
 import { useForm } from "react-hook-form"
@@ -434,39 +436,54 @@ const EditSchema = zod.object({
   description: zod.string().optional(),
 })
 
+// Page component — renders RouteDrawer, delegates form to child
 const EditPostPage = () => {
   const { id } = useParams()
-  const queryClient = useQueryClient()
-  const { handleSuccess } = useRouteModal()
 
   const { data, isLoading, isError, error } = useQuery({
     queryKey: ["posts", id],
     queryFn: () => sdk.admin.fetch("/posts/:id", { method: "GET", params: { id: id! } }),
   })
 
-  // Throw query errors to error boundary
   if (isError) {
     throw error
   }
 
+  return (
+    <RouteDrawer>
+      <RouteDrawer.Header>
+        <Heading>Edit Post</Heading>
+      </RouteDrawer.Header>
+      {!isLoading && data?.post && (
+        <EditPostForm post={data.post} />
+      )}
+    </RouteDrawer>
+  )
+}
+
+// Form component — useRouteModal() is valid here (inside RouteDrawer)
+const EditPostForm = ({ post }: { post: { id: string; title: string; description?: string } }) => {
+  const queryClient = useQueryClient()
+  const { handleSuccess } = useRouteModal()
+
   const form = useForm<zod.infer<typeof EditSchema>>({
     defaultValues: {
-      title: data?.post?.title ?? "",
-      description: data?.post?.description ?? "",
+      title: post.title ?? "",
+      description: post.description ?? "",
     },
     resolver: zodResolver(EditSchema),
   })
 
   const { mutateAsync, isPending } = useMutation({
     mutationFn: (payload: zod.infer<typeof EditSchema>) =>
-      sdk.admin.fetch("/posts/:id", { method: "POST", params: { id: id! }, body: payload }),
+      sdk.admin.fetch("/posts/:id", { method: "POST", params: { id: post.id }, body: payload }),
   })
 
   const handleSubmit = form.handleSubmit(async (values) => {
     await mutateAsync(values, {
       onSuccess: () => {
         queryClient.invalidateQueries({ queryKey: ["posts"] })
-        queryClient.invalidateQueries({ queryKey: ["posts", id] })
+        queryClient.invalidateQueries({ queryKey: ["posts", post.id] })
         toast.success("Post updated")
         handleSuccess()
       },
@@ -475,57 +492,50 @@ const EditPostPage = () => {
   })
 
   return (
-    <RouteDrawer>
-      <RouteDrawer.Header>
-        <Heading>Edit Post</Heading>
-      </RouteDrawer.Header>
-      {!isLoading && data?.post && (
-        <RouteDrawer.Form form={form}>
-          <KeyboundForm onSubmit={handleSubmit} className="flex flex-1 flex-col">
-            <RouteDrawer.Body>
-              <div className="flex flex-col gap-y-4">
-                <Form.Field
-                  control={form.control}
-                  name="title"
-                  render={({ field }) => (
-                    <Form.Item>
-                      <Form.Label>Title</Form.Label>
-                      <Form.Control>
-                        <Input autoComplete="off" {...field} />
-                      </Form.Control>
-                      <Form.ErrorMessage />
-                    </Form.Item>
-                  )}
-                />
-                <Form.Field
-                  control={form.control}
-                  name="description"
-                  render={({ field }) => (
-                    <Form.Item>
-                      <Form.Label optional>Description</Form.Label>
-                      <Form.Control>
-                        <Textarea {...field} />
-                      </Form.Control>
-                      <Form.ErrorMessage />
-                    </Form.Item>
-                  )}
-                />
-              </div>
-            </RouteDrawer.Body>
-            <RouteDrawer.Footer>
-              <div className="flex items-center justify-end gap-x-2">
-                <RouteDrawer.Close asChild>
-                  <Button size="small" variant="secondary">Cancel</Button>
-                </RouteDrawer.Close>
-                <Button size="small" type="submit" isLoading={isPending}>
-                  Save
-                </Button>
-              </div>
-            </RouteDrawer.Footer>
-          </KeyboundForm>
-        </RouteDrawer.Form>
-      )}
-    </RouteDrawer>
+    <RouteDrawer.Form form={form}>
+      <KeyboundForm onSubmit={handleSubmit} className="flex flex-1 flex-col">
+        <RouteDrawer.Body>
+          <div className="flex flex-col gap-y-4">
+            <Form.Field
+              control={form.control}
+              name="title"
+              render={({ field }) => (
+                <Form.Item>
+                  <Form.Label>Title</Form.Label>
+                  <Form.Control>
+                    <Input autoComplete="off" {...field} />
+                  </Form.Control>
+                  <Form.ErrorMessage />
+                </Form.Item>
+              )}
+            />
+            <Form.Field
+              control={form.control}
+              name="description"
+              render={({ field }) => (
+                <Form.Item>
+                  <Form.Label optional>Description</Form.Label>
+                  <Form.Control>
+                    <Textarea {...field} />
+                  </Form.Control>
+                  <Form.ErrorMessage />
+                </Form.Item>
+              )}
+            />
+          </div>
+        </RouteDrawer.Body>
+        <RouteDrawer.Footer>
+          <div className="flex items-center justify-end gap-x-2">
+            <RouteDrawer.Close asChild>
+              <Button size="small" variant="secondary">Cancel</Button>
+            </RouteDrawer.Close>
+            <Button size="small" type="submit" isLoading={isPending}>
+              Save
+            </Button>
+          </div>
+        </RouteDrawer.Footer>
+      </KeyboundForm>
+    </RouteDrawer.Form>
   )
 }
 
@@ -553,6 +563,8 @@ File: `src/admin/routes/custom/create/page.tsx`
 
 **Critical structure**: Use `RouteFocusModal.Form` wrapping `KeyboundForm` — this handles dirty form blocking on close and Cmd/Ctrl+Enter submit. The `KeyboundForm` wraps Header + Body + Footer. Use `useRouteModal()` for `handleSuccess` to close the modal after success.
 
+**IMPORTANT**: `useRouteModal()` must be called in a **child component** rendered inside `<RouteFocusModal>`, not in the same component that renders it. The `RouteModalProvider` context is created inside `RouteFocusModal`, so calling the hook in the parent component crashes with "useRouteModal must be used within a RouteModalProvider".
+
 ```tsx
 import { Button, RouteFocusModal, Form, Heading, Input, Text, Textarea, toast, KeyboundForm, useRouteModal } from "@acmekit/ui"
 import { useForm } from "react-hook-form"
@@ -566,7 +578,17 @@ const CreateSchema = zod.object({
   description: zod.string().optional(),
 })
 
+// Page component — renders RouteFocusModal, delegates form to child
 const CreatePostPage = () => {
+  return (
+    <RouteFocusModal>
+      <CreatePostForm />
+    </RouteFocusModal>
+  )
+}
+
+// Form component — useRouteModal() is valid here (inside RouteFocusModal)
+const CreatePostForm = () => {
   const queryClient = useQueryClient()
   const { handleSuccess } = useRouteModal()
 
@@ -592,61 +614,59 @@ const CreatePostPage = () => {
   })
 
   return (
-    <RouteFocusModal>
-      <RouteFocusModal.Form form={form}>
-        <KeyboundForm onSubmit={handleSubmit} className="flex flex-1 flex-col overflow-hidden">
-          <RouteFocusModal.Header />
-          <RouteFocusModal.Body className="flex flex-1 flex-col items-center overflow-y-auto py-16">
-            <div className="flex w-full max-w-[720px] flex-col gap-y-8">
-              <div>
-                <Heading>Create Post</Heading>
-                <Text size="small" className="text-ui-fg-subtle">
-                  Add a new blog post.
-                </Text>
-              </div>
-              <div className="grid grid-cols-1 gap-4 md:grid-cols-2">
-                <Form.Field
-                  control={form.control}
-                  name="title"
-                  render={({ field }) => (
-                    <Form.Item>
-                      <Form.Label>Title</Form.Label>
-                      <Form.Control>
-                        <Input autoComplete="off" {...field} />
-                      </Form.Control>
-                      <Form.ErrorMessage />
-                    </Form.Item>
-                  )}
-                />
-                <Form.Field
-                  control={form.control}
-                  name="description"
-                  render={({ field }) => (
-                    <Form.Item>
-                      <Form.Label optional>Description</Form.Label>
-                      <Form.Control>
-                        <Textarea {...field} />
-                      </Form.Control>
-                      <Form.ErrorMessage />
-                    </Form.Item>
-                  )}
-                />
-              </div>
+    <RouteFocusModal.Form form={form}>
+      <KeyboundForm onSubmit={handleSubmit} className="flex flex-1 flex-col overflow-hidden">
+        <RouteFocusModal.Header />
+        <RouteFocusModal.Body className="flex flex-1 flex-col items-center overflow-y-auto py-16">
+          <div className="flex w-full max-w-[720px] flex-col gap-y-8">
+            <div>
+              <Heading>Create Post</Heading>
+              <Text size="small" className="text-ui-fg-subtle">
+                Add a new blog post.
+              </Text>
             </div>
-          </RouteFocusModal.Body>
-          <RouteFocusModal.Footer>
-            <div className="flex items-center justify-end gap-x-2">
-              <RouteFocusModal.Close asChild>
-                <Button size="small" variant="secondary">Cancel</Button>
-              </RouteFocusModal.Close>
-              <Button size="small" type="submit" isLoading={isPending}>
-                Create
-              </Button>
+            <div className="grid grid-cols-1 gap-4 md:grid-cols-2">
+              <Form.Field
+                control={form.control}
+                name="title"
+                render={({ field }) => (
+                  <Form.Item>
+                    <Form.Label>Title</Form.Label>
+                    <Form.Control>
+                      <Input autoComplete="off" {...field} />
+                    </Form.Control>
+                    <Form.ErrorMessage />
+                  </Form.Item>
+                )}
+              />
+              <Form.Field
+                control={form.control}
+                name="description"
+                render={({ field }) => (
+                  <Form.Item>
+                    <Form.Label optional>Description</Form.Label>
+                    <Form.Control>
+                      <Textarea {...field} />
+                    </Form.Control>
+                    <Form.ErrorMessage />
+                  </Form.Item>
+                )}
+              />
             </div>
-          </RouteFocusModal.Footer>
-        </KeyboundForm>
-      </RouteFocusModal.Form>
-    </RouteFocusModal>
+          </div>
+        </RouteFocusModal.Body>
+        <RouteFocusModal.Footer>
+          <div className="flex items-center justify-end gap-x-2">
+            <RouteFocusModal.Close asChild>
+              <Button size="small" variant="secondary">Cancel</Button>
+            </RouteFocusModal.Close>
+            <Button size="small" type="submit" isLoading={isPending}>
+              Create
+            </Button>
+          </div>
+        </RouteFocusModal.Footer>
+      </KeyboundForm>
+    </RouteFocusModal.Form>
   )
 }
 

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

@@ -313,6 +313,7 @@ const confirmed = await prompt({
 **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
+- Installing `@hookform/resolvers@5.x` — this version requires Zod v4 (`zod/v4/core`), but AcmeKit ships Zod v3. Causes `Could not resolve "zod/v4/core"` at build time. Never install your own version — use what AcmeKit provides
 
 **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`
@@ -326,6 +327,7 @@ const confirmed = await prompt({
 - Using `onClick={handleSubmit}` on submit button — use `type="submit"` inside a `KeyboundForm` tag
 - Missing `className="flex flex-1 flex-col"` on the `KeyboundForm` tag (breaks layout)
 - Missing `overflow-hidden` on RouteFocusModal's `KeyboundForm` tag
+- Calling `useRouteModal()` in the same component that renders `RouteFocusModal`/`RouteDrawer` — the hook must be in a **child component** rendered inside the modal/drawer (the provider mounts inside it)
 - Using `navigate("..")` to close overlays instead of `handleSuccess()` from `useRouteModal()`
 - Putting footer buttons directly in Footer — wrap in `<div className="flex items-center justify-end gap-x-2">`
 - Using grid layout in Drawer forms — drawers are narrow, use single column `flex flex-col gap-y-4`

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

@@ -867,7 +867,17 @@ import { sdk } from "../../../../lib/sdk"
 type Currency = { code: string; name: string }
 const columnHelper = createDataTableColumnHelper<Currency>()
 
+// Page component — renders RouteFocusModal, delegates form to child
 const AddCurrenciesPage = () => {
+  return (
+    <RouteFocusModal>
+      <AddCurrenciesForm />
+    </RouteFocusModal>
+  )
+}
+
+// Form component — useRouteModal() is valid here (inside RouteFocusModal)
+const AddCurrenciesForm = () => {
   const queryClient = useQueryClient()
   const { handleSuccess } = useRouteModal()
 
@@ -924,37 +934,35 @@ const AddCurrenciesPage = () => {
   })
 
   return (
-    <RouteFocusModal>
-      <RouteFocusModal.Form form={form}>
-        <KeyboundForm onSubmit={handleSubmit} className="flex h-full flex-col overflow-hidden">
-          <RouteFocusModal.Header>
-            <div className="flex flex-1 items-center justify-between">
-              {form.formState.errors.currencies && (
-                <Hint variant="error">{form.formState.errors.currencies.message}</Hint>
-              )}
-            </div>
-          </RouteFocusModal.Header>
-          <RouteFocusModal.Body className="flex flex-1 flex-col overflow-hidden">
-            <DataTable instance={table}>
-              <DataTable.Table emptyState={{
-                empty: { heading: "No currencies available" },
-              }} />
-              <DataTable.Pagination />
-            </DataTable>
-          </RouteFocusModal.Body>
-          <RouteFocusModal.Footer>
-            <div className="flex items-center justify-end gap-x-2">
-              <RouteFocusModal.Close asChild>
-                <Button size="small" variant="secondary">Cancel</Button>
-              </RouteFocusModal.Close>
-              <Button size="small" type="submit" isLoading={isPending}>
-                Save
-              </Button>
-            </div>
-          </RouteFocusModal.Footer>
-        </KeyboundForm>
-      </RouteFocusModal.Form>
-    </RouteFocusModal>
+    <RouteFocusModal.Form form={form}>
+      <KeyboundForm onSubmit={handleSubmit} className="flex h-full flex-col overflow-hidden">
+        <RouteFocusModal.Header>
+          <div className="flex flex-1 items-center justify-between">
+            {form.formState.errors.currencies && (
+              <Hint variant="error">{form.formState.errors.currencies.message}</Hint>
+            )}
+          </div>
+        </RouteFocusModal.Header>
+        <RouteFocusModal.Body className="flex flex-1 flex-col overflow-hidden">
+          <DataTable instance={table}>
+            <DataTable.Table emptyState={{
+              empty: { heading: "No currencies available" },
+            }} />
+            <DataTable.Pagination />
+          </DataTable>
+        </RouteFocusModal.Body>
+        <RouteFocusModal.Footer>
+          <div className="flex items-center justify-end gap-x-2">
+            <RouteFocusModal.Close asChild>
+              <Button size="small" variant="secondary">Cancel</Button>
+            </RouteFocusModal.Close>
+            <Button size="small" type="submit" isLoading={isPending}>
+              Save
+            </Button>
+          </div>
+        </RouteFocusModal.Footer>
+      </KeyboundForm>
+    </RouteFocusModal.Form>
   )
 }
 

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

@@ -422,6 +422,34 @@ const SettingsPage = () => {
 }
 ```
 
+### Never Install react-hook-form, @hookform/resolvers, or zod Directly
+
+These packages are **provided by AcmeKit** at specific pinned versions. Installing your own version causes version conflicts:
+
+- `@hookform/resolvers@5.x` requires `zod/v4/core` (Zod v4) — AcmeKit ships Zod v3 → **build fails** with `Could not resolve "zod/v4/core"`
+- `react-hook-form` dual instances → `useFormContext()` returns `null` → form fields crash
+- Bare `zod` import → **build fails** in plugins with `Could not resolve "zod"`
+
+**For plugins**: `react-hook-form` and `@hookform/resolvers` go in `peerDependencies` + `devDependencies` only (never `dependencies`). Match the host app's versions.
+
+**For apps**: Do not add these packages at all — they come from `@acmekit/ui`.
+
+**Imports**:
+- Admin UI: `import * as zod from "@acmekit/deps/zod"` — never bare `"zod"`
+- Backend: `import { z } from "@acmekit/framework/zod"` — never bare `"zod"`
+- `useForm` from `react-hook-form` and `zodResolver` from `@hookform/resolvers/zod` — these are provided by the host
+
+### Vite "Outdated Optimize Dep" 504 Errors
+
+After changing plugin dependencies, Vite's pre-bundled dependency cache becomes stale. The browser shows `504 (Outdated Optimize Dep)` for multiple modules.
+
+**Fix**: Stop the dev server, delete `.vite/deps/` in the host app's `node_modules/`, and restart:
+
+```bash
+rm -rf node_modules/.vite/deps
+# restart dev server
+```
+
 ---
 
 ## Key Rules

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

@@ -42,7 +42,7 @@ Co-locate validation, query config, response schemas, rate limiting, and RBAC po
 When extending generated CRUD routes, keep the existing `query-config.ts` / `helpers.ts` structure and only adjust fields, filters, workflow calls, or refetch logic.
 
 ```typescript
-import { z } from "zod"
+import { z } from "@acmekit/framework/zod"
 import {
   defineRouteConfig,
   AuthenticatedAcmeKitTypedRequest,
@@ -532,8 +532,9 @@ createProductsWorkflow.hooks.productsCreated(
 
 ## Zod Import Note
 
-- In route files (`defineRouteConfig`): `import { z } from "zod"` works
-- In `middlewares.ts` (`additionalDataValidator`): use `import { z } from "@acmekit/framework/zod"`
+- **Always** use `import { z } from "@acmekit/framework/zod"` — never bare `"zod"`
+- Bare `"zod"` may resolve in apps but **fails in plugins** (zod is not a direct dependency)
+- This applies to both route files and `middlewares.ts`
 
 ## Common Imports
 
@@ -546,8 +547,7 @@ import {
   defineMiddlewares,
   AcmeKitNextFunction,
 } from "@acmekit/framework/http"
-import { z } from "zod"
-import { z as frameworkZod } from "@acmekit/framework/zod"  // for middlewares.ts
+import { z } from "@acmekit/framework/zod"
 import { ContainerRegistrationKeys, AcmeKitError } from "@acmekit/framework/utils"
 ```
 
@@ -737,11 +737,10 @@ export const POST = async (req, res) => {
 // RIGHT — use :param format
 { matcher: "/custom/:id", middlewares: [...] }  // ✅
 
-// WRONG — using bare zod in middlewares.ts
-import { z } from "zod"  // ❌ in middlewares.ts
-additionalDataValidator: { brand: z.string() }
+// WRONG — bare "zod" import (fails in plugins, not a direct dependency)
+import { z } from "zod"  // ❌ never use bare zod
 
-// RIGHT — use framework zod in middlewares.ts
+// RIGHT — always use framework re-export
 import { z } from "@acmekit/framework/zod"  // ✅
 
 // WRONG — no .strict() on body schema (allows extra fields through)
@@ -772,4 +771,26 @@ const { enabled, ...filters } = req.validatedQuery  // ❌ crashes if request ha
 
 // RIGHT — always provide fallback when destructuring validatedQuery
 const { enabled, ...filters } = req.validatedQuery ?? {}  // ✅ safe when no query params
+
+// WRONG — seeding/syncing data inside a route handler (runs on every request)
+export const GET = async (req, res) => {
+  const service = req.scope.resolve(MY_MODULE)
+  await service.syncProviders()  // ❌ data mutation on every GET — slow, side-effectful
+  const data = await query.graph({ entity: "my_entity" })
+  res.json({ items: data })
+}
+
+// RIGHT — routes are pure query/mutation handlers, no seeding or syncing
+// Seed data via: createProvidersLoader onRegistered, onPluginStart, or scripts
+export const GET = async (req, res) => {
+  const data = await query.graph({ entity: "my_entity" })
+  res.json({ items: data })  // ✅ just reads data
+}
+
+// WRONG — importing service class directly in route file for type
+import type MyModuleService from "../../../modules/my/service"  // ❌ tight coupling
+const svc = req.scope.resolve<MyModuleService>(MY_MODULE)
+
+// RIGHT — resolve via module constant, type-cast loosely if needed
+const svc: any = req.scope.resolve(MY_MODULE)  // ✅
 ```

package/dist/templates/plugin/.claude/rules/modules.md

@@ -192,7 +192,7 @@ export default class MyModuleService {
 
 **When to use loaders:** Register external connections at startup; validate required options (throw on missing to prevent startup). Loaders are idempotent — check `container.hasRegistration("key")` before re-registering.
 
-**Don't use loaders for:** Scheduled tasks → use jobs. Event-triggered logic → use subscribers.
+**Don't use loaders for:** Scheduled tasks → use jobs. Event-triggered logic → use subscribers. Database mutations (INSERT/UPDATE/DELETE) → use scripts, subscribers, or seed data (exception: `onRegistered` in `createProvidersLoader` is designed for DB seeding via service methods). Never resolve `PG_CONNECTION` for raw SQL in loaders — use service methods instead.
 
 ## Module Options Validation
 
@@ -262,6 +262,73 @@ export default Module(RELAYER_MODULE, {
 })
 ```
 
+### createProvidersLoader — Full API
+
+`createProvidersLoader` accepts a `ProvidersConfig` object with these options:
+
+| Option | Required | Default | Purpose |
+|--------|----------|---------|---------|
+| `prefix` | Yes | — | Container registration key prefix (e.g., `"pp_"`, `"cr_"`) |
+| `identifiersKey` | Yes | — | Key for tracking registered provider IDs |
+| `moduleName` | No | `"module"` | Label for log/error messages |
+| `keyFormat` | No | `"prefixId"` | `"prefixId"` → key=`{prefix}{id}`, or `"prefixIdentifierId"` → key=`{prefix}{identifier}_{id}` |
+| `defaults` | No | `[]` | Built-in providers shipped with the module (see below) |
+| `defaultProviderKey` | No | — | Container key to register the elected default provider ID |
+| `requireDefault` | No | `false` | Throw at startup if no default provider is found |
+| `onRegistered` | No | — | Async hook called after all providers are registered |
+
+**`defaults`** — each entry is a `DefaultProviderConfig`:
+
+```typescript
+{
+  service: ProviderClass,      // must have static `identifier`
+  id: string,                  // registration ID
+  options?: Record | ((moduleOptions) => Record),  // static or derived from module options
+  condition?: (moduleOptions) => boolean,           // skip this default if returns false
+}
+```
+
+**`onRegistered`** — receives `{ container, providers, registeredDefaults }`:
+
+```typescript
+onRegistered: async ({ container, providers, registeredDefaults }) => {
+  // container: module-scoped AcmeKitContainer (module's own service is resolvable here)
+  // providers: user-configured ModuleProvider[] from config
+  // registeredDefaults: Array<{ id, options }> — only defaults that passed condition
+}
+```
+
+**Example with defaults and onRegistered** (from core modules):
+
+```typescript
+createProvidersLoader({
+  prefix: PAYMENT_PROVIDER_PREFIX,
+  identifiersKey: PAYMENT_PROVIDER_IDENTIFIER_KEY,
+  moduleName: PAYMENT_MODULE,
+  defaults: [
+    {
+      service: SystemProvider,
+      id: "system",
+      condition: (opts) => opts.enableSystemProvider !== false,
+    },
+  ],
+  onRegistered: async ({ container, registeredDefaults }) => {
+    // Sync DB rows for registered providers via service methods
+    const service: any = container.resolve(PAYMENT_MODULE)
+    for (const provider of registeredDefaults) {
+      const existing = await service.listPaymentProviders({ id: [provider.id] })
+      if (!existing.length) {
+        await service.createPaymentProviders([
+          { id: provider.id, is_enabled: true },
+        ])
+      }
+    }
+  },
+})
+```
+
+**Important**: Even inside `onRegistered`, always use service methods for DB mutations — never raw SQL via `PG_CONNECTION`.
+
 ### Service (resolving providers)
 
 Use the leading `TProvider` generic to get a typed `this.providers` registry.
@@ -767,4 +834,54 @@ AcmeKitService({ providers: { prefix: "cr_", identifiersKey: "chain_relayer_prov
 
 // RIGHT — define constants once in constants.ts, import everywhere
 import { CHAIN_RELAYER_PROVIDER_PREFIX, CHAIN_RELAYER_IDENTIFIER_KEY } from "./constants"
+
+// WRONG — using raw SQL / PG_CONNECTION for data mutations
+const pgConnection = container.resolve(ContainerRegistrationKeys.PG_CONNECTION)
+await pgConnection.raw(
+  `INSERT INTO payment_provider (id) VALUES (?)`,  // ❌ bypasses ORM, service layer, events
+  [id]
+)
+
+// RIGHT — use the module's service methods for all data mutations
+const service = container.resolve(PAYMENT_MODULE)
+await service.createPaymentProviders([{ id: "pp_system", is_enabled: true }])  // ✅
+
+// WRONG — using raw SQL in onRegistered to seed provider rows
+onRegistered: async ({ container, registeredDefaults }) => {
+  const pg = container.resolve(ContainerRegistrationKeys.PG_CONNECTION)
+  await pg.raw(`INSERT INTO ...`, [id])  // ❌ bypasses ORM
+}
+
+// RIGHT — use service methods in onRegistered
+onRegistered: async ({ container, registeredDefaults }) => {
+  const service: any = container.resolve(MY_MODULE)
+  for (const provider of registeredDefaults) {
+    const existing = await service.listMyProviders({ id: [provider.id] })
+    if (!existing.length) {
+      await service.createMyProviders([{ id: provider.id, is_enabled: true }])  // ✅
+    }
+  }
+}
+
+// WRONG — lazy-syncing / seeding data inside a GET route handler
+export const GET = async (req, res) => {
+  const service = req.scope.resolve(PAYMENT_MODULE)
+  await service.syncRegisteredProviders()  // ❌ runs on EVERY request
+  const { data } = await query.graph({ entity: "payment_provider" })
+  res.json({ items: data })
+}
+
+// RIGHT — seed data once at startup (onPluginStart) or via script, route just queries
+export const GET = async (req, res) => {
+  const { data } = await query.graph({ entity: "payment_provider" })
+  res.json({ items: data })  // ✅ pure query, no side effects
+}
+
+// WRONG — importing service class directly in route file
+import type PaymentModuleService from "../../../modules/payment/service"  // ❌
+const service = req.scope.resolve<PaymentModuleService>(PAYMENT_MODULE)
+
+// RIGHT — resolve with module constant, cast to interface if needed
+const service: any = req.scope.resolve(PAYMENT_MODULE)  // ✅
+// or use the generated interface type from @types if available
 ```