@jskit-ai/agent-docs 0.1.4 → 0.1.6

package/DISTR_AGENT.md

@@ -13,6 +13,7 @@ Use these references on demand:
 
 - `reference/autogen/KERNEL_MAP.md`
 - `reference/autogen/README.md`
+- `patterns/INDEX.md`
 - `guide/agent/index.md`
 - `site/guide/index.md` when compressed guidance is ambiguous or missing nuance
 - `templates/APP_BLUEPRINT.md`
@@ -28,6 +29,7 @@ Core rules:
   - `Why this sticks: ...`
   - `Not doing: ...`
 - Keep that checkpoint compact. Do not expand it into a long preamble unless the developer asks for detail.
+- When a request involves JSKIT UI, routing, surfaces, CRUDs, filters, placements, live actions, or similar implementation details, scan `patterns/INDEX.md` for matching keywords and read only the relevant pattern files.
 - Reuse existing JSKIT helpers and runtime seams before adding new local helpers.
 - A freshly scaffolded JSKIT app can still be in Stage 1. If platform decisions are not settled yet, continue with the initialize workflow before adding runtime packages.
 - Do not treat a missing `config.tenancyMode` line or an untouched minimal scaffold as a final tenancy decision.

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

@@ -678,7 +678,7 @@ The baseline generator output is only the start. As the tutorial's `contacts`, `
 
 - `src/server/listQueryValidators.js` when a list needs extra query filters beyond `q`
 - `src/server/service.test.js` once save/delete rules stop being trivial
-- `src/composables/contacts/useContactsListFilters.js` when the contacts page gains route-backed filter state
+- `packages/contacts/src/shared/contactListFilters.js` when the contacts CRUD gains structured list filters that both server and client should share
 - `src/composables/addresses/useAddressDisplay.js` when addresses need app-specific display formatting
 - `src/composables/comments/useCommentsListRuntime.js` when an embedded comments list needs local UI state
 
@@ -686,6 +686,7 @@ That is the right direction of growth:
 
 - server customizations stay in the CRUD package
 - presentation and page-specific UI state stay in app-owned client files
+- shared structured list filters live best in a CRUD-package shared module that both server and client can import
 
 ## Search and filters: the deep dive
 
@@ -782,18 +783,64 @@ Usually nothing changes. The client can keep sending `q`.
 - Do not dump every text column into search just because you can.
 - In this tutorial CRUD, `notes` is a good example of a field you might leave out if you want fast, predictable list search.
 
-### Pattern 3: structured `contacts` filters such as `hasEmail`, `hasPhone`, and `hasNotes`
+### Pattern 3: structured list filters from one shared definition
 
-This is the first extension that still fits the `contacts` table from the previous chapter with no schema changes.
+This is the default pattern once a CRUD list needs real filters.
 
-#### Client side
+Do not hand-build:
+
+- one filter shape in the page
+- a second filter shape in `listQueryValidators.js`
+- and a third filter shape in `repository.js`
+
+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" })`
+4. build the client runtime from that same definition with `useCrudListFilters(...)`
+
+For example, a shared filter-definition module can look like this:
+
+```js
+export const CONTACTS_LIST_FILTER_DEFINITIONS = Object.freeze({
+  onlyStaff: {
+    type: "flag",
+    label: "Staff"
+  },
+  onlyVip: {
+    type: "flag",
+    label: "VIP"
+  },
+  onlyArchived: {
+    type: "flag",
+    label: "Archived"
+  }
+});
+```
 
-Keep filter state in a small app-owned composable, then pass it into `useCrudList()` as `queryParams`.
+#### Exact file checklist
 
-Example shape:
+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/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
+
+The only file in that list that is normally **new** is the shared module:
+
+- `packages/contacts/src/shared/contactListFilters.js`
+
+The others are normally edits to the generated CRUD package and the app-owned page layer that already exist.
+
+#### Client side
+
+Build the filter runtime directly from the shared definitions:
 
 ```js
-const listFilters = useContactsListFilters();
+const listFilters = useCrudListFilters(CONTACTS_LIST_FILTER_DEFINITIONS);
 
 const records = useCrudList({
   resource: uiResource,
@@ -802,9 +849,7 @@ const records = useCrudList({
     enabled: true,
     mode: "query"
   },
-  queryParams: computed(() => ({
-    ...listFilters.filters
-  })),
+  queryParams: listFilters.queryParams,
   syncToRoute: {
     enabled: true,
     search: true,
@@ -814,65 +859,274 @@ const records = useCrudList({
 });
 ```
 
-This keeps the filters:
+That gives you, from one place:
+
+- `listFilters.values`
+- `listFilters.queryParams`
+- `listFilters.presets`
+- `listFilters.activeChips`
+- `listFilters.hasActiveFilters`
+- `listFilters.clearChip(...)`
+- `listFilters.clearFilters()`
+- `listFilters.toggle(...)` for flag filters
+- `listFilters.applyPreset(...)`
+- `listFilters.matchesPreset(...)`
+
+So the same runtime owns:
+
+- URL-synced query params
+- filter chips
+- reset logic
+- preset application
+- preset active-state matching
+- small flag toggles
+
+For relative-date quick filters, keep the date math in runtime presets instead of page-local helper state. `resolveValues(...)` runs at preset-apply time and receives `{ values, filters, presetKey, preset }`, so the preset can derive values from the current filter state and the normalized preset metadata:
+
+```js
+const listFilters = useCrudListFilters(
+  RECEIVAL_LIST_FILTER_DEFINITIONS,
+  {
+    presets: [
+      {
+        key: "today",
+        label: "Today",
+        resolveValues({ presetKey }) {
+          const today = formatDateInputValue(new Date());
+          return {
+            arrivalDate: {
+              from: today,
+              to: today
+            }
+          };
+        }
+      },
+      {
+        key: "last7",
+        label: "Last 7 Days",
+        resolveValues({ values }) {
+          const today = formatDateInputValue(new Date());
+          return {
+            arrivalDate: {
+              from: shiftDateInputValue(today, -6),
+              to: today
+            }
+          };
+        }
+      }
+    ]
+  }
+);
+```
+
+```vue
+<v-chip
+  v-for="preset in listFilters.presets"
+  :key="preset.key"
+  :variant="listFilters.matchesPreset(preset.key) ? 'flat' : 'outlined'"
+  @click="listFilters.applyPreset(preset.key, { mode: 'merge' })"
+>
+  {{ preset.label }}
+</v-chip>
+```
+
+Use `mode: "merge"` when a preset should only change one filter group, such as the arrival date range, and should not clear the rest of the page's active filters.
 
-- visible in the URL
-- restorable on refresh
-- preserved when opening a record and coming back
+`matchesPreset(...)` is strict by design. It compares the preset against the full current filter state after basic normalization, and it does **not** silently drop extra `enumMany` or `recordIdMany` values that were hydrated from the route and still appear as chips. If the URL contains `status=archived&status=bogus`, a preset for only `archived` should render as inactive until the extra `bogus` value is cleared.
 
 #### Server side
 
-Add a dedicated query validator:
+Build the server runtime from the same shared definitions:
 
 ```js
-const contactsListFiltersQueryValidator = Object.freeze({
-  schema: Type.Object(
-    {
-      hasEmail: Type.Optional(...),
-      hasPhone: Type.Optional(...),
-      hasNotes: Type.Optional(...)
-    },
-    { additionalProperties: false }
-  ),
-  normalize(payload = {}) {
-    const normalized = {};
-    if (Object.hasOwn(payload, "hasEmail")) normalized.hasEmail = 1;
-    if (Object.hasOwn(payload, "hasPhone")) normalized.hasPhone = 1;
-    if (Object.hasOwn(payload, "hasNotes")) normalized.hasNotes = 1;
-    return normalized;
+const contactsListFiltersRuntime = createCrudListFilters(
+  CONTACTS_LIST_FILTER_DEFINITIONS,
+  {
+    columns: {
+      onlyStaff: "is_staff",
+      onlyVip: "vip",
+      onlyArchived: "archived"
+    }
   }
+);
+```
+
+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.
+
+Strict contract example:
+
+```js
+const contactsListFiltersQueryValidator = contactsListFiltersRuntime.createQueryValidator({
+  invalidValues: "reject" // malformed filter values should fail validation and return 400
+});
+```
+
+Lenient contract example:
+
+```js
+const contactsListFiltersQueryValidator = contactsListFiltersRuntime.createQueryValidator({
+  invalidValues: "discard" // malformed filter values should be ignored and dropped by normalize()
 });
 ```
 
-Wire it into the route and action validators for the list operation, then apply the filter in `repository.js`:
+Wire the runtime into the list validator and the repository:
+
+```js
+queryValidator: [
+  listCursorPaginationQueryValidator,
+  listSearchQueryValidator,
+  contactsListFiltersQueryValidator,
+  listParentFilterQueryValidator,
+  lookupIncludeQueryValidator
+]
+```
+
+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.
+
+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
+- 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
 
 ```js
 async function list(query = {}, callOptions = {}) {
   return crudRepositoryList(repositoryRuntime, knex, query, options, callOptions, {
     modifyQuery(dbQuery, context = {}) {
-      const sourceQuery = context.query || {};
+      return contactsListFiltersRuntime.applyQuery(dbQuery, context.query || {});
+    }
+  });
+}
+```
 
-      if (sourceQuery.hasEmail !== undefined) {
-        dbQuery.whereNotNull("email").where("email", "<>", "");
-      }
-      if (sourceQuery.hasPhone !== undefined) {
-        dbQuery.whereNotNull("phone").where("phone", "<>", "");
+#### Best practices
+
+- 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: ... })`.
+- 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.
+
+### Pattern 4: lookup-backed structured filters
+
+This is the next real-world step: filters like `supplierContactId`, `locationId`, or `contactId` where the user needs:
+
+- remote autocomplete search
+- URL-synced selected ids
+- readable chip labels instead of raw ids
+
+The right pattern is:
+
+1. keep the lookup filter in the shared definitions
+2. use `useCrudListFilters(...)` for state, chips, and query params
+3. use `useCrudListFilterLookups(...)` for option loading and label resolution
+
+Example shared definition:
+
+```js
+export const RECEIVAL_LIST_FILTER_DEFINITIONS = Object.freeze({
+  supplierContactId: {
+    type: "recordIdMany",
+    label: "Supplier",
+    lookup: {
+      namespace: "contacts"
+    }
+  },
+  pollenTypeId: {
+    type: "recordIdMany",
+    label: "Pollen Type",
+    lookup: {
+      namespace: "pollen-types",
+      labelKey: "name"
+    }
+  }
+});
+```
+
+#### Exact file checklist
+
+Lookup-backed filters do **not** change the ownership model from Pattern 3. The file plan is still:
+
+- keep the shared definition in `packages/receivals/src/shared/receivalListFilters.js`
+- update the same server validator and repository files from Pattern 3
+- update the app-owned list page or list-runtime composable so it creates both `useCrudListFilters(...)` and `useCrudListFilterLookups(...)`
+- bind the lookup UI, such as `v-autocomplete`, from `filterLookups.resolveLookup(...)`
+
+Do **not** create a second page-local filter schema just because the UI needs remote autocomplete. The shared definition file stays the source of truth.
+
+#### Client side
+
+```js
+let filterLookups = null;
+
+const listFilters = useCrudListFilters(
+  RECEIVAL_LIST_FILTER_DEFINITIONS,
+  {
+    labelResolvers: {
+      supplierContactId(value) {
+        return filterLookups?.resolveLookupLabel("supplierContactId", value, "Supplier") || "";
       }
-      if (sourceQuery.hasNotes !== undefined) {
-        dbQuery.whereNotNull("notes").where("notes", "<>", "");
+    }
+  }
+);
+
+filterLookups = useCrudListFilterLookups(
+  RECEIVAL_LIST_FILTER_DEFINITIONS,
+  {
+    values: listFilters.values,
+    queryKeyPrefix: ["ui-generator", "receivals", "filters"],
+    placementSourcePrefix: "ui-generator.receivals.list.filters",
+    requestQueryParams: {
+      supplierContactId: { limit: 25 }
+    },
+    labelResolvers: {
+      supplierContactId(item = {}) {
+        return `${item.firstName} ${item.lastName}`.trim();
       }
     }
-  });
-}
+  }
+);
+
+const supplierFilterLookup = filterLookups.resolveLookup("supplierContactId");
 ```
 
+Then bind the autocomplete:
+
+```vue
+<v-autocomplete
+  v-model="listFilters.values.supplierContactId"
+  :items="supplierFilterLookup.options"
+  :search="supplierFilterLookup.searchQuery"
+  :loading="supplierFilterLookup.isLoading"
+  item-title="label"
+  item-value="value"
+  multiple
+  chips
+  no-filter
+  @update:search="supplierFilterLookup.setSearch"
+/>
+```
+
+#### Why this is better than a page-local `useList()` wrapper
+
+- the CRUD filter state still lives in `useCrudListFilters(...)`
+- the autocomplete loading logic lives in one reusable helper
+- the label resolution used by filter chips and the autocomplete stays consistent
+- a second screen can reuse the same pattern instead of rewriting it
+
 #### Best practices
 
-- Keep the client keys, validator keys, and repository keys identical.
-- Use dedicated query params for booleans and facets. Do not overload `q`.
-- Put SQL in the repository, not in the page.
+- Put lookup metadata in the shared filter definitions.
+- Use `useCrudListFilterLookups(...)` for remote filter autocompletes instead of building a custom `useList()` wrapper per screen.
+- Keep lookup label formatting on the client side. It is UI presentation, not repository logic.
+- Keep unusual SQL semantics, such as `pending = whereNull(...)`, in the server runtime `apply` override.
 
-### Pattern 4: free-text search plus structured `contacts` filters together
+### Pattern 5: free-text search plus structured filters together
 
 This is the most common real-world CRUD list.
 
@@ -895,7 +1149,7 @@ Let the generic list search handle `q`, and let your custom validator/repository
 - Preserve the current route query when linking to view/edit pages so users can return to the same filtered list state.
 - Let list changes reset pagination; `useCrudList()` already does this for search and query-param changes.
 
-### Pattern 5: parent-scoped child CRUD search for `addresses`
+### Pattern 6: parent-scoped child CRUD search for `addresses`
 
 For nested CRUDs such as the `addresses` resource from the previous chapter, parent scoping and search usually work together.
 
@@ -935,7 +1189,7 @@ That keeps child-list filtering grounded in the actual resource definition inste
 - Let the resource contract define parent filter shape.
 - Treat parent-scoped filtering as repository/query behavior, not as presentation logic.
 
-### Pattern 6: local-only search for embedded `comments`
+### Pattern 7: local-only search for embedded `comments`
 
 Sometimes server search is unnecessary.
 
@@ -1038,10 +1292,12 @@ Use `scaffold-field` when it fits, then review the generated result.
 
 Touch:
 
-- a client filter composable or page state
-- `useCrudList({ queryParams: ... })`
-- a dedicated server query validator
-- `repository.js`
+- `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/repository.js` so the list query applies the runtime
+- the app-owned list page or list-runtime composable that calls `useCrudList(...)`
+
+If the filter is lookup-backed, touch that same client file again to wire `useCrudListFilterLookups(...)`.
 
 ### "I want a new save rule."
 

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Distributed JSKIT agent workflows, guides, and generated reference maps.",
   "type": "module",
   "files": [
     "DISTR_AGENT.md",
     "guide",
+    "patterns",
     "reference",
     "skills",
     "templates",

package/patterns/INDEX.md

@@ -0,0 +1,33 @@
+# JSKIT Patterns Index
+
+Use this index as the first stop for recurring JSKIT implementation heuristics and workflow traps.
+
+How to use it:
+
+- Match the user request against the keywords below.
+- Open only the relevant pattern files.
+- Use patterns as implementation guidance, not as permission to skip normal scoping or user clarification.
+
+## Keyword Map
+
+- tabs, menu items, icons, shell links, profile links, subpage tabs, placements
+  - `placements.md`
+- surfaces, app/admin/home/console, "which surface", route ownership, placement visibility
+  - `surfaces.md`
+- child crud, nested crud, embedded list, subroute, separate page, parent/child layout
+  - `child-cruds.md`
+- CRUD links, record placeholders, `paths.page()`, `resolveViewUrl`, `resolveEditUrl`, `resolveParams`
+  - `crud-links.md`
+- live actions, checkbox, toggle, patch button, inline action, `useCommand()`
+  - `live-actions.md`
+- filter, filters, search facets, chips, date range, enum filter, lookup filter, `useCrudListFilters`, `createCrudListFilters`
+  - `filters.md`
+
+## Current Patterns
+
+- [placements.md](./placements.md)
+- [surfaces.md](./surfaces.md)
+- [child-cruds.md](./child-cruds.md)
+- [crud-links.md](./crud-links.md)
+- [live-actions.md](./live-actions.md)
+- [filters.md](./filters.md)

package/patterns/child-cruds.md

@@ -0,0 +1,30 @@
+# Child CRUD Layout Patterns
+
+Use when:
+
+- planning nested CRUDs
+- adding records under a parent record
+- deciding whether child records need their own page or stay inside the parent view
+
+Rules:
+
+- Before generating a child CRUD, ask how the user wants the child records laid out.
+- Do not assume one layout pattern by default.
+
+Clarify these options:
+
+- embedded in the parent view
+  - often a list rendered directly inside the parent page
+- embedded as child subroutes
+  - the parent page becomes a routed container or subpage host
+- totally separate route/page
+  - the child list/view/edit flow lives in its own route area
+
+Why this matters:
+
+- the answer changes route structure, placements, host containers, and which generator flow fits best
+- child CRUD layout mistakes are expensive to unwind later
+
+Avoid:
+
+- generating nested CRUD routes before the parent/child layout is agreed

package/patterns/crud-links.md

@@ -0,0 +1,36 @@
+# CRUD Link Resolution Patterns
+
+Use when:
+
+- customizing generated CRUD pages
+- wiring buttons or links on list/view/edit pages
+- building nested CRUD links
+
+Rules:
+
+- Use `paths.page()` for surface-aware navigation that only needs surface params.
+- Do not use `paths.page()` with CRUD record placeholders such as `:contactId`, `:addressId`, `:todoListId`, or `:todoItemId` in CRUD-bound route suffixes.
+- For CRUD-bound links, use the runtime that owns the current CRUD scope.
+
+Prefer:
+
+- list pages
+  - `records.resolveViewUrl(record)`
+  - `records.resolveEditUrl(record)`
+  - `records.resolveParams(template, extraParams)`
+- view pages
+  - `view.listUrl`
+  - `view.editUrl`
+  - `view.resolveParams(template, extraParams)`
+- add/edit pages
+  - `formRuntime.addEdit.resolveParams(template, extraParams)`
+
+Scope rule:
+
+- Use the runtime anchored to the record that owns the action.
+- On a parent record view with nested child routes, parent actions should still resolve from the parent `view` runtime even while a child route is active.
+
+Avoid:
+
+- `paths.page("/lists/:todoListId/items/new")`
+- `paths.page("/lists/:todoListId/edit")`

package/patterns/filters.md

@@ -0,0 +1,92 @@
+# Structured Filters
+
+Use when:
+- a CRUD list needs flags, enums, date ranges, record-id filters, or lookup-backed filters
+- the user asks to "add a filter", "make the list filterable", or "keep filters in the URL"
+- a screen mixes free-text search with structured facets
+
+Ask first:
+- which fields are filterable
+- whether each filter is a flag, enum, multi-enum, date/date-range, number-range, record id, or lookup-backed record id
+- whether filters must sync to the route query
+- whether the screen needs chips and clear/reset behavior
+- whether lookup filters need remote autocomplete search
+- whether there are presets such as "Today", "Last 7 Days", or "Only Archived"
+
+Default JSKIT pattern:
+1. Put shared filter definitions in the CRUD package.
+   Example path: `packages/<crud>/src/shared/<crud>ListFilters.js`
+2. Build the server runtime from that module with `createCrudListFilters(...)`.
+3. Build route/action validators explicitly with `createQueryValidator({ invalidValues: "reject" | "discard" })`, and use `applyQuery(...)` in the repository. There is no default validator mode and no `runtime.queryValidator` alias.
+4. Build the client runtime from the same shared definitions with `useCrudListFilters(...)`. Presets can use static `values` or dynamic `resolveValues({ values, filters, presetKey, preset })`.
+5. Pass `listFilters.queryParams` into `useCrudList(...)`.
+6. For lookup-backed filters, use `useCrudListFilterLookups(...)` instead of hand-rolling `useList()` in each page.
+
+Exact file checklist:
+- create `packages/<crud>/src/shared/<crud>ListFilters.js`
+- update `packages/<crud>/src/server/registerRoutes.js` and `packages/<crud>/src/server/actions.js` so the list query validator includes an explicit `createQueryValidator({ invalidValues: ... })` choice, or update `packages/<crud>/src/server/listQueryValidators.js` if that package already extracts list-query composition there
+- update `packages/<crud>/src/server/repository.js` so list queries call the runtime's `applyQuery(...)`
+- update the app-owned list page or list-runtime composable under `src/pages/...` or `src/composables/...` so it builds `useCrudListFilters(...)`, passes `queryParams` into `useCrudList(...)`, and binds chips / reset behavior
+- for lookup-backed filters, update that same client file to build `useCrudListFilterLookups(...)` and bind the lookup control from `resolveLookup(...)`
+
+Validation mode is part of the contract:
+- there is no default mode and no fallback alias, so every route/action boundary that validates structured filters must call `createQueryValidator({ invalidValues: ... })` explicitly
+- use `invalidValues: "reject"` when malformed filter values should fail validation and return 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 affects whether malformed unauthenticated requests fail at validation or fall through to auth
+- for normal HTTP CRUD handlers, route-level `discard` means the action layer receives already-normalized query input; do not assume route `discard` plus action `reject` will still reject malformed HTTP query strings later
+- `jskit doctor` flags `createQueryValidator(...)` calls that do not spell out `invalidValues` directly at the call site
+
+Keep separate:
+- free-text search uses `records.searchQuery` and `q`
+- structured filters use explicit query params through `useCrudListFilters(...)`
+
+Use `useCrudListFilterLookups(...)` when:
+- a filter is `recordId` or `recordIdMany`
+- the UI needs remote autocomplete search
+- chips should show readable labels instead of raw ids
+
+Use built-in `presence` when:
+- a filter means null vs not-null, such as assigned vs unassigned storage
+- the UI wants custom labels like "Assigned" / "Unassigned" but the transport contract can stay `present` / `missing`
+- you do **not** need custom SQL beyond `whereNotNull(...)` / `whereNull(...)`
+
+Use runtime presets when:
+- the page has quick filters such as "Today", "Last 7 Days", or "Only Archived"
+- the preset should reuse the same filter state/reset/query-param runtime as the rest of the page
+- relative-date presets need dynamic `resolveValues()` instead of hard-coded dates
+- the active-state UI should reflect the full current filter state through `matchesPreset(...)`, including extra route-hydrated values that still appear as chips
+
+Put unusual SQL semantics on the server:
+- examples: `pending` meaning `whereNull("ccp1_passed")`, or business-specific status buckets that combine multiple columns
+- implement those in `createCrudListFilters(..., { apply: { ... } })`
+- do not use custom `apply` just for null/not-null checks when `type: "presence"` fits
+
+Avoid:
+- local filter composables that duplicate the same keys the server already knows about
+- a custom validator shape that does not match the page state
+- assuming a default `runtime.queryValidator` exists; always create the validator explicitly with `createQueryValidator({ invalidValues: ... })`
+- hand-rolled preset apply/reset/active-state helpers when `useCrudListFilters(..., { presets })`, `applyPreset(...)`, and `matchesPreset(...)` fit
+- per-screen `useList()` wrappers for lookup-backed filters when `useCrudListFilterLookups(...)` fits
+- a second page-local filter-definition file when `packages/<crud>/src/shared/<crud>ListFilters.js` should be the source of truth
+- overloading `q` with structured filter meaning
+- local or inline filter-definition objects passed into `useCrudListFilters(...)` or `createCrudListFilters(...)`; `jskit doctor` expects those runtimes to import from a CRUD shared `*ListFilters` module
+
+Good shape:
+- `packages/receivals/src/shared/receivalListFilters.js`
+- `createCrudListFilters(RECEIVAL_LIST_FILTER_DEFINITIONS, ...)`
+- `const listFilters = useCrudListFilters(RECEIVAL_LIST_FILTER_DEFINITIONS, { presets: [...] })`
+- `const filterLookups = useCrudListFilterLookups(RECEIVAL_LIST_FILTER_DEFINITIONS, { values: listFilters.values, ... })`
+- `queryParams: listFilters.queryParams`
+
+Preset contract notes:
+- `resolveValues({ values, filters, presetKey, preset })` receives the current filter state and the normalized preset metadata, so relative-date presets can derive values at apply time without page-local helper state
+- `matchesPreset(...)` compares against the full current filter state after basic normalization; it does **not** silently drop extra `enumMany` or `recordIdMany` values that were hydrated from the route and still show up as active chips
+- if the URL contains `status=archived&status=bogus`, a preset for only `archived` should not render as active while the `bogus` chip is still visible
+
+Review checks:
+- one shared filter definition source of truth
+- server validator/repository logic derived from that source
+- client query params/chips/reset logic derived from that source
+- lookup-backed filters use the shared lookup helper, not a page-local mini-framework
+- `jskit doctor` stays clean for filter ownership and explicit validator policy