@jskit-ai/agent-docs 0.1.16 → 0.1.18

package/guide/agent/app-extras/assistant.md

@@ -181,7 +181,7 @@ For example:
     require: "all",
     permissions: ["workspace.members.invite"]
   },
-  inputValidator: {
+  input: {
     schema: {
       type: "object",
       properties: {
@@ -191,7 +191,7 @@ For example:
       additionalProperties: false
     }
   },
-  outputValidator: {
+  output: {
     schema: {
       type: "object",
       properties: {

package/guide/agent/app-setup/initial-scaffolding.md

@@ -576,8 +576,6 @@ The core of that startup path looks like this:
 ```js
 async function createServer() {
   const app = Fastify({ logger: true });
-  registerTypeBoxFormats();
-  app.setValidatorCompiler(TypeBoxValidatorCompiler);
 
   app.get("/api/health", async () => {
     return {
@@ -610,7 +608,7 @@ async function createServer() {
 }
 ```
 
-The health route is built in, but the more important idea is that the server is already prepared to validate HTTP input, load the JSKIT provider runtime from the app itself, and constrain requests by surface.
+The health route is built in, but the more important idea is that the server is already prepared to validate HTTP input with Fastify's normal JSON Schema path, load the JSKIT provider runtime from the app itself, and constrain requests by surface.
 
 You will also notice `config/server.js`. In the base shell it is intentionally almost empty. It is there to reserve a clear place for server-side configuration as backend features are added, without pretending the starter app already has server behavior it does not yet need.
 

package/guide/agent/app-setup/multi-homing.md

@@ -591,12 +591,12 @@ registerProfileSyncLifecycleContributor(app, "workspaces.core.profileSyncLifecyc
   return Object.freeze({
     contributorId: "workspaces.core.profileSync",
     order: 100,
-    async afterIdentityProfileSynced({ profile, created, options } = {}) {
-      if (!created || !profile || typeof workspaceService?.provisionWorkspaceForNewUser !== "function") {
+    async afterIdentityProfileSynced({ profile, options } = {}) {
+      if (!profile || typeof workspaceService?.ensureProvisionedWorkspaceForAuthenticatedUser !== "function") {
         return;
       }
 
-      await workspaceService.provisionWorkspaceForNewUser(profile, options);
+      await workspaceService.ensureProvisionedWorkspaceForAuthenticatedUser(profile, options);
     }
   });
 });
@@ -604,7 +604,9 @@ registerProfileSyncLifecycleContributor(app, "workspaces.core.profileSyncLifecyc
 
 That means the workspace package does not need to patch auth directly to learn that a user was added. It listens through the `users-core` lifecycle registry instead.
 
-For this chapter's `tenancyMode = "personal"` setup, that contributor now does real work. When a brand-new JSKIT user is synchronized from auth, `workspaces-core` uses the lifecycle seam to provision that user's first personal workspace automatically.
+For this chapter's `tenancyMode = "personal"` setup, that contributor now does real work. When an authenticated JSKIT user is synchronized from auth, `workspaces-core` ensures that user's personal workspace exists.
+
+That detail matters for the retrofit path described earlier in this chapter. If the app started on `none`, then later switched to `personal`, the first sign-in after that switch still needs to backfill the personal workspace for the already-existing user record. The lifecycle contributor handles that because the workspace provision step is idempotent.
 
 - `users-core` owns the "user was synchronized" lifecycle
 - `workspaces-core` subscribes to that lifecycle through the registry
@@ -612,6 +614,27 @@ For this chapter's `tenancyMode = "personal"` setup, that contributor now does r
 
 So even in this chapter, the package boundary is already correct: users owns user creation/sync, and workspaces reacts through an extension point.
 
+### Workspace auth context comes from the auth policy resolver registry
+
+There is a second registry seam in this chapter that matters just as much for the runtime model.
+
+Workspace-aware routes do not hard-code workspace lookup inside the auth plugin itself. Instead, `workspaces-core` registers an auth policy context resolver contribution, and `auth-core` composes the registered resolvers at request time.
+
+The important consequence is:
+
+- `auth-core` stays generic
+- `workspaces-core` contributes workspace-specific context
+- the request only resolves workspace membership and permissions when a route actually asks for auth context or permissions
+
+So the flow is:
+
+1. a workspace-aware route declares auth and, when needed, permission requirements
+2. the auth policy runtime authenticates the actor
+3. the composed auth policy context resolver asks the workspace layer for the current workspace context
+4. the request gains normalized `workspace`, `membership`, and `permissions` values
+
+That is why the workspace package does not need to patch the auth plugin directly, and it is also why this setup scales better than a one-off global hook. It uses the same tagged-registry pattern as other JSKIT extension seams, but for request-time auth context instead of bootstrap payloads or lifecycle events.
+
 ### Why this chapter is the real routing pivot
 
 Earlier chapters added features inside a flat top-level app.

package/guide/agent/app-setup/working-with-the-jskit-cli.md

@@ -568,6 +568,7 @@ So `update` is for reapplying package-owned managed changes, not for generic dep
 The best guide example is the tenancy-mode recovery path from the multi-homing chapter. If you installed `workspaces-core` or `workspaces-web` while the app was still on `tenancyMode = "none"`, then later changed the app to `personal`, the missing gated scaffold does not backfill automatically. The recovery path is:
 
 ```bash
+npx jskit update package users-core
 npx jskit update package workspaces-core
 npx jskit update package workspaces-web
 ```

package/guide/agent/generators/advanced-cruds.md

@@ -211,9 +211,7 @@ packages/contacts/
   package.json
   package.descriptor.mjs
   src/server/ContactsProvider.js
-  src/server/actionIds.js
   src/server/actions.js
-  src/server/listConfig.js
   src/server/registerRoutes.js
   src/server/repository.js
   src/server/service.js
@@ -265,15 +263,61 @@ If you come from an ORM stack, this is the key adjustment:
 The resource file owns:
 
 - the resource name and table name
-- the id column
-- input and output validators
-- operation metadata for `list`, `view`, `create`, `patch`, and `delete`
+- the canonical `schema`
+- `searchSchema`
+- `defaultSort`
+- `autofilter`
 - lookup contract configuration
-- messages and realtime event declarations
-- field metadata when column overrides or richer metadata are needed
+- messages
+- field metadata, including which fields participate in `output`, `create`, `replace`, and `patch`
 
 This file is the bridge between the server and the client. The UI generator reads it, and the server runtime also depends on it.
 
+For a standard CRUD resource like `contacts`, the authored file is intentionally compact. It uses `defineCrudResource(...)` from `@jskit-ai/resource-crud-core`:
+
+```js
+import { defineCrudResource } from "@jskit-ai/resource-crud-core/shared/crudResource";
+
+const resource = defineCrudResource({
+  namespace: "contacts",
+  tableName: "contacts",
+  schema: {
+    name: {
+      type: "string",
+      maxLength: 190,
+      required: true,
+      search: true,
+      operations: {
+        output: { required: true },
+        create: { required: true },
+        patch: { required: false }
+      }
+    }
+  },
+  searchSchema: {
+    id: { type: "id", actualField: "id" }
+  },
+  defaultSort: ["-createdAt"],
+  autofilter: "workspace",
+  messages: {
+    saveSuccess: "Record saved."
+  },
+  contract: {
+    lookup: {
+      containerKey: "lookups"
+    }
+  }
+});
+```
+
+`defineCrudResource(...)` derives the standard CRUD operation contracts once at module load time and exposes them on `resource.operations`. That means:
+
+- you author the canonical resource shape once
+- JSKIT derives the standard `list` / `view` / `create` / `replace` / `patch` / `delete` contracts
+- routes, actions, client code, and generators can keep reading `resource.operations.*` without each resource file repeating that boilerplate
+
+For non-CRUD or heavily custom resources, use `defineResource(...)` from `@jskit-ai/resource-core` instead. That keeps standard CRUD derivation and custom operation bundles clearly separated.
+
 ### `src/shared/index.js`
 
 This is just the shared package barrel. It re-exports the resource contract and shared symbols.
@@ -292,22 +336,6 @@ It owns:
 
 It is wiring, not business logic. If you need to change how contacts are validated or saved, this is usually **not** the file to edit first.
 
-### `src/server/actionIds.js`
-
-This is the stable list of action ids:
-
-```js
-const actionIds = Object.freeze({
-  list: "crud.contacts.list",
-  view: "crud.contacts.view",
-  create: "crud.contacts.create",
-  update: "crud.contacts.update",
-  delete: "crud.contacts.delete"
-});
-```
-
-Keep this file boring. It is identity, not behavior.
-
 ### `src/server/actions.js`
 
 This is the action contract boundary.
@@ -344,33 +372,6 @@ In other words:
 
 Those are related, but not the same concern.
 
-### `src/server/listConfig.js`
-
-This is the baseline list behavior for the repository.
-
-It owns things like:
-
-- `defaultLimit`
-- `maxLimit`
-- `orderBy`
-- `searchColumns`
-
-One subtle but important detail: `searchColumns` are **database column names**, not camelCase resource field keys.
-
-Example:
-
-```js
-const LIST_CONFIG = Object.freeze({
-  searchColumns: ["full_name", "email", "phone"],
-  orderBy: [
-    {
-      column: "created_at",
-      direction: "desc"
-    }
-  ]
-});
-```
-
 ### `src/server/repository.js`
 
 This is the data-access layer.
@@ -656,6 +657,44 @@ const paths = usePaths();
 const reportsApiPath = computed(() => paths.api("/reports"));
 ```
 
+Use `requestQueryParams` when a runtime needs endpoint query parameters. Do not put query strings into `apiUrlTemplate`; URL templates are for path shape only.
+
+For routed CRUD edit forms, pass request query params through `addEditOptions`:
+
+```js
+const formRuntime = useCrudAddEdit({
+  resource: uiResource,
+  operationName: "patch",
+  formFields: UI_EDIT_FORM_FIELDS,
+  addEditOptions: {
+    apiUrlTemplate: "/products/:productId",
+    requestQueryParams: {
+      include: "serviceId,bookingSteps,bookingSteps.requiredRoleId"
+    }
+  }
+});
+```
+
+`requestQueryParams` may also be a callback. The add/edit callback receives the same scoped request context used by view/list, plus the current record id and model:
+
+```js
+const formRuntime = useCrudAddEdit({
+  resource: uiResource,
+  operationName: "patch",
+  formFields: UI_EDIT_FORM_FIELDS,
+  addEditOptions: {
+    apiUrlTemplate: "/products/:productId",
+    requestQueryParams({ recordId, model }) {
+      return {
+        include: "serviceId,bookingSteps,bookingSteps.requiredRoleId"
+      };
+    }
+  }
+});
+```
+
+For add/edit runtimes, these request query params apply to both the initial load and the save request path. That keeps the saved response shape aligned with the loaded form shape when an endpoint supports response includes.
+
 The safe mental model is:
 
 - do not raw `fetch(...)` for normal app work
@@ -663,6 +702,7 @@ The safe mental model is:
 - use the operation/runtime composable that matches the UI interaction
 - drop to `usersWebHttpClient.request(...)` only for exceptional low-level cases
 - use `usePaths().api(...)` when you need a custom scoped API path and the higher-level runtime does not already resolve it for you
+- keep `apiUrlTemplate` path-only and put endpoint query strings in `requestQueryParams`
 
 ### `_components/CrudAddEditForm.vue`
 
@@ -703,7 +743,7 @@ A generated CRUD works because several layers cooperate:
 4. the route executes an action from `actions.js`
 5. the action delegates to the service in `service.js`
 6. the service calls the repository in `repository.js`
-7. the repository uses `crud-core` helpers and the resource contract to talk to the database
+7. the repository uses the shared resource contract, `crud-core` helpers, and the internal JSON:API host to talk to the database
 8. the response comes back through validators and is rendered by the page
 
 That is why the generated route files are mostly containers: they are the outermost layer of a larger pipeline.
@@ -714,10 +754,10 @@ Use this rule of thumb when deciding where to edit:
 
 | Need | Primary owner | Why |
 | --- | --- | --- |
-| Change API/input/output contract | `contactResource.js` and `actions.js` | This is where operation shape and validators live |
+| Change API/input/output contract | `contactResource.js` first, then `actions.js` only if the action boundary must diverge | Standard CRUD validators are derived from the resource; `actions.js` owns channels, permissions, and any transport-specific input composition |
 | Change route path or HTTP transport | `registerRoutes.js` | This is the HTTP layer |
 | Change permissions or channels | `actions.js` | This is the action contract boundary |
-| Change default ordering, limits, or searchable DB columns | `listConfig.js` | This is list runtime configuration |
+| Change default ordering, searchable fields, or ownership autofilter | `contactResource.js` | The shared resource is the single source of truth for both CRUD contract and internal JSON:API resource config |
 | Change SQL, joins, parent filters, or advanced search | `repository.js` | This is the data-access layer |
 | Add cross-record or domain rules on save/delete | `service.js` | This is business logic |
 | Change page layout and display behavior | the route pages and app-owned composables | This is presentation |
@@ -788,8 +828,8 @@ The client runtime debounces the search input, writes the query string to `q`, a
 The generic CRUD stack already understands `q`.
 
 - `listSearchQueryValidator` reads and normalizes the `q` query param
-- the repository applies search to `list.searchColumns`
-- if `searchColumns` is not configured, CRUD falls back to a derived set of searchable string columns from the resource output schema
+- the repository applies search through `resource.searchSchema.q`
+- the generated CRUD starts with an explicit `q` search definition in `contactResource.js`, so you edit that definition directly when you want to narrow or expand the search surface
 
 For the tutorial `contacts` table, that usually means the columns behind:
 
@@ -800,27 +840,31 @@ For the tutorial `contacts` table, that usually means the columns behind:
 
 #### Best practices
 
-- Once the UX is stable, set explicit `searchColumns` instead of relying on the fallback.
-- Keep search focused on the columns users actually expect.
-- Remember that `searchColumns` are database columns.
+- Once the UX is stable, edit `contactResource.js` and set `resource.searchSchema.q.oneOf` explicitly instead of relying on the initial generated defaults.
+- Keep search focused on the fields users actually expect.
+- Remember that these are JSON:API/internal resource search keys, not a free-form UI concern.
 
-### Pattern 2: explicit `contacts` search columns
+### Pattern 2: explicit `contacts` search fields
 
-This is the first thing to do when the fallback search becomes too broad or too accidental.
+This is the first thing to do when the generated `q` search becomes too broad or too accidental.
 
 #### Server side
 
-Set the searchable columns explicitly in `listConfig.js`:
+Set the searchable fields explicitly in `contactResource.js`:
 
 ```js
-const LIST_CONFIG = Object.freeze({
-  searchColumns: ["full_name", "email", "phone"],
-  orderBy: [
-    {
-      column: "created_at",
-      direction: "desc"
+const resource = Object.freeze({
+  searchSchema: {
+    id: { type: "id", actualField: "id" },
+    q: {
+      type: "string",
+      oneOf: ["fullName", "email", "phone"],
+      filterOperator: "like",
+      splitBy: " ",
+      matchAll: true
     }
-  ]
+  },
+  defaultSort: ["-createdAt"]
 });
 ```
 
@@ -841,32 +885,58 @@ Do not treat the output schema as if it also defined database storage.
 In JSKIT CRUD:
 
 - the schema defines the API contract
-- `resource.fieldMeta` defines storage mapping
+- field definitions may also carry storage/lookup/ui metadata
 - the repository runtime owns computed SQL projections
 
 Use these rules:
 
-- for explicit DB column overrides, use `repository.column`
+- for explicit DB column overrides, use `actualField`
 - standard writable `date-time` fields are serialized automatically during CRUD writes
-- use `repository.writeSerializer` only for non-default DB write serialization
-- for computed output fields, use `repository.storage: "virtual"`
+- use `storage.writeSerializer` only for non-default DB write serialization
+- for computed output fields, use `storage: { virtual: true }`
 - do not put computed fields in create/patch write schemas
 
 Example field metadata:
 
 ```js
-RESOURCE_FIELD_META.push({
-  key: "createdAt",
-  repository: {
-    column: "created_at"
-  }
-});
-
-RESOURCE_FIELD_META.push({
-  key: "remainingBatchWeight",
-  repository: {
-    storage: "virtual"
-  }
+import { defineCrudResource } from "@jskit-ai/resource-crud-core/shared/crudResource";
+
+const resource = defineCrudResource({
+  namespace: "receivals",
+  tableName: "receivals",
+  schema: {
+    createdAt: {
+      type: "dateTime",
+      required: true,
+      actualField: "created_at",
+      operations: {
+        output: { required: true }
+      }
+    },
+    arrivalDatetime: {
+      type: "dateTime",
+      required: true,
+      storage: {
+        writeSerializer: "datetime-utc"
+      },
+      operations: {
+        output: { required: true },
+        create: { required: true },
+        patch: { required: false }
+      }
+    },
+    remainingBatchWeight: {
+      type: "number",
+      required: true,
+      storage: {
+        virtual: true
+      },
+      operations: {
+        output: { required: true }
+      }
+    }
+  },
+  crudOperations: ["list", "view", "create", "patch"]
 });
 ```
 
@@ -894,7 +964,7 @@ Once registered there:
 - generic CRUD `listByIds`
 - generic CRUD `listByForeignIds`
 
-and generic CRUD writes automatically serialize standard writable `date-time` fields during create/update payload mapping, so normal datetime DB formatting does not need per-field metadata or repository-specific `preparePayload` hooks. Keep `repository.writeSerializer` for non-default cases only.
+and generic CRUD writes automatically serialize standard writable `date-time` fields during create/update payload mapping, so normal datetime DB formatting does not need per-field metadata or repository-specific `preparePayload` hooks. Keep `storage.writeSerializer` for non-default cases only.
 
 all pick up the projection automatically, so you should not hand-patch `clearSelect()` / re-select logic into each method.
 
@@ -921,7 +991,7 @@ Instead:
 
 1. define the filters once in a shared CRUD-package module
 2. build the server runtime from that definition with `createCrudListFilters(...)`
-3. choose the route/action invalid-value contract explicitly with `createQueryValidator({ invalidValues: "reject" | "discard" })`
+3. choose the route/action invalid-value contract explicitly on each structured filter field with `createCrudListFilterQueryField(...)`
 4. build the client runtime from that same definition with `useCrudListFilters(...)`
 
 For example, a shared filter-definition module can look like this:
@@ -948,7 +1018,7 @@ export const CONTACTS_LIST_FILTER_DEFINITIONS = Object.freeze({
 For a generated CRUD, treat this as the concrete file plan:
 
 - create `packages/contacts/src/shared/contactListFilters.js`
-- update `packages/contacts/src/server/registerRoutes.js` so the list route query validator includes an explicit `createQueryValidator({ invalidValues: ... })` choice, unless you already extracted list-query composition into `packages/contacts/src/server/listQueryValidators.js`
+- update `packages/contacts/src/server/registerRoutes.js` so the list route query validator lists structured filter params explicitly with `createCrudListFilterQueryField(...)`, unless you already extracted list-query composition into `packages/contacts/src/server/listQueryValidators.js`
 - update `packages/contacts/src/server/actions.js` so the list action input validator includes that same explicit contract choice
 - update `packages/contacts/src/server/repository.js` so the list query path builds the `createCrudListFilters(...)` runtime and calls `applyQuery(...)`
 - update the app-owned list page or list-runtime composable, usually under `src/pages/.../contacts/` or `src/composables/...`, so it builds `useCrudListFilters(...)`, passes `queryParams` into `useCrudList(...)`, and renders chips / reset behavior from that runtime
@@ -1075,46 +1145,66 @@ const contactsListFiltersRuntime = createCrudListFilters(
 );
 ```
 
-There is no default query-validator mode and no `runtime.queryValidator` alias. Create the validator that matches the contract you want at that route or action boundary.
+There is no default query-validator mode or route-runtime alias. Keep the filter runtime for repository semantics, but author route/action query params explicitly.
 
 Strict contract example:
 
 ```js
-const contactsListFiltersQueryValidator = contactsListFiltersRuntime.createQueryValidator({
-  invalidValues: "reject" // malformed filter values should fail validation and return 400
-});
+const contactsListFilters = CONTACTS_LIST_FILTER_DEFINITIONS;
+
+const contactsListFiltersQueryValidator = {
+  schema: createCrudListFilterQuerySchema({
+    status: createCrudListFilterQueryField(contactsListFilters.status, {
+      invalidValues: "reject"
+    }),
+    arrivalDate: createCrudListFilterQueryField(contactsListFilters.arrivalDate, {
+      invalidValues: "reject"
+    })
+  }),
+  mode: "patch"
+};
 ```
 
 Lenient contract example:
 
 ```js
-const contactsListFiltersQueryValidator = contactsListFiltersRuntime.createQueryValidator({
-  invalidValues: "discard" // malformed filter values should be ignored and dropped by normalize()
-});
+const contactsListFiltersQueryValidator = {
+  schema: createCrudListFilterQuerySchema({
+    status: createCrudListFilterQueryField(CONTACTS_LIST_FILTER_DEFINITIONS.status, {
+      invalidValues: "discard"
+    }),
+    arrivalDate: createCrudListFilterQueryField(CONTACTS_LIST_FILTER_DEFINITIONS.arrivalDate, {
+      invalidValues: "discard"
+    })
+  }),
+  mode: "patch"
+};
 ```
 
-Wire the runtime into the list validator and the repository:
+Wire the explicit query contract into the list validator and the repository:
 
 ```js
-queryValidator: [
+const listRouteQueryValidator = composeSchemaDefinitions([
   listCursorPaginationQueryValidator,
   listSearchQueryValidator,
   contactsListFiltersQueryValidator,
   listParentFilterQueryValidator,
   lookupIncludeQueryValidator
-]
+], {
+  mode: "patch"
+});
 ```
 
-Use that same `contactsListFiltersQueryValidator` anywhere else the list query is validated, such as the list action input validator if your CRUD package validates query shape at both the route and action boundaries.
+Use that same explicit `contactsListFiltersQueryValidator` anywhere else the list query is validated, such as the composed list action input validator if your CRUD package validates query shape at both the route and action boundaries.
 
 Choose the invalid-value contract deliberately:
 
-- there is no default mode and no fallback alias, so every route or action that validates structured filters must call `createQueryValidator({ invalidValues: ... })` explicitly
+- there is no default mode and no fallback alias, so every structured filter field must choose `invalidValues: "reject"` or `invalidValues: "discard"` explicitly
 - use `invalidValues: "reject"` when malformed filter values should fail validation and produce a 400-style contract error
 - use `invalidValues: "discard"` when malformed filter values should be ignored and normalization should drop them
 - route query validation runs before auth, so this choice changes whether malformed unauthenticated requests fail at validation or fall through to auth
-- for normal HTTP CRUD handlers, route-level `discard` means the handler receives already-normalized query input, so the action layer will not see those discarded bad values again later
-- `jskit doctor` flags `createQueryValidator(...)` calls that do not spell out `invalidValues` directly at the call site
+- for normal HTTP CRUD handlers, route-level `discard` means the handler receives already-parsed filter values for the explicit fields you listed, so the action layer will not see those discarded bad values again later
+- the filter runtime is still a deliberate two-phase exception: schema parsing owns query-field values, then `applyQuery(...)` maps those parsed values back through filter keys and SQL semantics
 
 ```js
 async function list(query = {}, callOptions = {}) {
@@ -1130,11 +1220,11 @@ async function list(query = {}, callOptions = {}) {
 
 - Put the filter definitions in the CRUD package, not the page. Both server and client need them.
 - Keep the filter keys identical all the way through: definition key, query param key, and repository meaning.
-- Do not expect a default `runtime.queryValidator` to exist. Every structured-filter validator must be created explicitly with `createQueryValidator({ invalidValues: ... })`.
+- Prefer `createCrudListFilterQueryField(...)` plus `createCrudListFilterQuerySchema(...)` at route/action boundaries so accepted structured-filter params stay visible in app code.
 - Use `type: "presence"` for null/not-null filters such as assigned vs unassigned storage. Do not model those as custom enums plus `applyQuery(...)` overrides unless the SQL semantics are genuinely different from `whereNotNull(...)` / `whereNull(...)`.
 - Use `createCrudListFilters(...)` unless the list semantics are truly unusual.
 - Use `q` for free-text and explicit query params for structured filters.
-- Run `jskit doctor` after wiring filters. It flags inline/local filter-definition objects passed into `useCrudListFilters(...)` or `createCrudListFilters(...)`, and it flags `createQueryValidator(...)` calls that hide the invalid-value policy.
+- Run `jskit doctor` after wiring filters. It flags inline/local filter-definition objects passed into `useCrudListFilters(...)` or `createCrudListFilters(...)`.
 
 ### Pattern 4: lookup-backed structured filters
 
@@ -1294,14 +1384,18 @@ The CRUD stack can derive parent filter keys from the resource contract via `cre
 For the tutorial `addresses` table, the list search itself can stay very simple:
 
 ```js
-const LIST_CONFIG = Object.freeze({
-  searchColumns: ["label", "line_1", "line_2", "suburb", "state", "postcode"],
-  orderBy: [
-    {
-      column: "created_at",
-      direction: "desc"
+const resource = Object.freeze({
+  searchSchema: {
+    id: { type: "id", actualField: "id" },
+    q: {
+      type: "string",
+      oneOf: ["label", "line1", "line2", "suburb", "state", "postcode"],
+      filterOperator: "like",
+      splitBy: " ",
+      matchAll: true
     }
-  ]
+  },
+  defaultSort: ["-createdAt"]
 });
 ```
 
@@ -1410,14 +1504,14 @@ Touch:
 - `CrudAddEditFormFields.js`
 - the relevant page/table display
 
-Use `scaffold-field` when it fits, then review the generated result.
+Use `scaffold-field` when it fits, then review the generated result. It patches the canonical `schema` in the shared resource file; the standard CRUD validators are derived from that schema automatically.
 
 ### "I want a new boolean or enum list filter."
 
 Touch:
 
 - `packages/<crud>/src/shared/<crud>ListFilters.js` and make it the only authored filter-definition module
-- `packages/<crud>/src/server/registerRoutes.js` and `packages/<crud>/src/server/actions.js` so the list validator includes an explicit `createQueryValidator({ invalidValues: ... })` choice, or `packages/<crud>/src/server/listQueryValidators.js` if you extracted list-query composition there
+- `packages/<crud>/src/server/registerRoutes.js` and `packages/<crud>/src/server/actions.js` so the list validator lists structured filter params explicitly with `createCrudListFilterQueryField(...)`, or `packages/<crud>/src/server/listQueryValidators.js` if you extracted list-query composition there
 - `packages/<crud>/src/server/repository.js` so the list query applies the runtime
 - the app-owned list page or list-runtime composable that calls `useCrudList(...)`
 

package/guide/agent/generators/crud-generators.md

@@ -284,6 +284,30 @@ That file is the shared CRUD contract. The UI generator reads it to decide:
 
 So even though the server scaffold writes many files, the resource file is the bridge between the server and UI halves.
 
+### One install boundary to remember
+
+`crud-server-generator scaffold` also adds a new local app package dependency such as:
+
+```text
+@local/contacts
+```
+
+So before you build or run the app again, install that new local package:
+
+```bash
+npm install
+```
+
+If you are verifying the guide against a local JSKIT checkout and have already been using local package links, rerun:
+
+```bash
+npm run devlinks
+```
+
+The same rule applies after later server scaffolds such as `addresses` and `comments`. The UI generator can still read the generated resource file directly, but the app runtime needs the local package install boundary to be completed before the CRUD can boot normally.
+
+For standard CRUDs, that file is now intentionally compact. It uses `defineCrudResource(...)` from `@jskit-ai/resource-crud-core`, authors the canonical `schema` / `searchSchema` / `defaultSort` / `autofilter` shape once, and lets JSKIT derive the standard CRUD operation contracts from it.
+
 ### Step 3: scaffold the UI
 
 Once the resource file exists, generate the UI route tree:
@@ -566,6 +590,8 @@ Use this when:
 
 It is a maintenance tool, not the first step in the workflow.
 
+It patches the canonical `schema` inside the shared resource file. That matters because the standard CRUD validators are derived from that canonical schema; you are no longer maintaining separate authored `create` / `patch` / `view` validator blocks by hand.
+
 ## Summary
 
 The important thing is not memorizing commands. It is learning the three shapes:

package/guide/agent/index.md

@@ -16,8 +16,8 @@ It starts with the smallest scaffold, then explains how to work with the JSKIT C
 - [Authentication](/guide/app-setup/authentication)
 - [Database Layer](/guide/app-setup/database-layer)
 - [Users](/guide/app-setup/users)
-- [Console](/guide/app-setup/console)
 - [Multi-homing](/guide/app-setup/multi-homing)
+- [Console](/guide/app-setup/console)
 
 ### App Extras