@jskit-ai/agent-docs 0.1.5 → 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.5",
+  "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

package/patterns/live-actions.md

@@ -0,0 +1,33 @@
+# Live Action Patterns
+
+Use when:
+
+- wiring checkboxes
+- toggles
+- archive/delete/reopen/publish actions
+- small inline PATCH/POST/DELETE actions
+
+Rules:
+
+- Prefer `useCommand()` for live actions.
+- Prefer form runtimes such as `useCrudAddEdit()` or `useAddEdit()` for real forms.
+- Prefer `useCrudList()` and `useCrudView()` for routed CRUD loading and URL resolution.
+
+Good live-action pattern:
+
+- build a narrow payload
+- call `command.run()`
+- disable only the busy control while the command is running
+- invalidate the relevant query key on success
+- keep derived business rules on the server
+
+Examples:
+
+- checkbox toggles
+- inline status changes
+- quick destructive or publish/unpublish actions
+
+Avoid:
+
+- manually hand-rolling fetch logic for a standard live action when `useCommand()` fits
+- pushing derived write rules into the client just because the action is small

package/patterns/placements.md

@@ -0,0 +1,28 @@
+# Placement Patterns
+
+Use when:
+
+- changing tab icons
+- changing menu link icons or labels
+- moving shell links
+- changing profile or settings menu entries
+- debugging why a visible link does not match the page component
+
+Check first:
+
+- app `src/placement.js`
+- package placement contributions
+- linked component token props
+
+Rules:
+
+- In JSKIT, tab-like links and shell/menu entries are often placement-owned, not page-owned.
+- When asked to change a tab or menu icon, inspect placement metadata before editing page components.
+- Look at placement `props`, especially fields such as `icon`, `prependIcon`, `appendIcon`, or props passed into the linked component token.
+- If the visible entry is contributed by a package, update the owning package placement contribution instead of patching a local page component.
+- If the request is really about where a link appears, check the placement `target`, `surfaces`, `order`, and `when` fields before changing UI markup.
+
+Avoid:
+
+- editing the routed page just to change a shell/tab/menu icon that is actually placement-owned
+- assuming a rendered tab label/icon lives in the page component

package/patterns/surfaces.md

@@ -0,0 +1,30 @@
+# Surface Patterns
+
+Use when:
+
+- adding a new screen or feature
+- generating pages
+- adding menu entries or widgets
+- deciding whether something belongs in `home`, `app`, `admin`, `console`, or another surface
+
+Check first:
+
+- the blueprint surface plan
+- existing route roots under `src/pages`
+- placement visibility by `surfaces`
+
+Rules:
+
+- Always ask which surface the feature belongs to before generating routes, placements, or related UI.
+- Do not silently default new functionality to `app`.
+- Surface choice is architectural, not cosmetic. It controls routes, access, placement visibility, and often data ownership expectations.
+- When a link or widget should only appear on certain surfaces, use placement `surfaces` first and keep runtime `when` conditions for behavior-specific gating.
+
+Ask explicitly about:
+
+- route pages
+- menu entries
+- top-left/top-right widgets
+- settings pages
+- CRUD screens
+- helper components that only make sense on one surface

package/reference/autogen/KERNEL_MAP.md

@@ -25,6 +25,33 @@ For the full repo inventory, read `reference/autogen/README.md` and the package
 Exports
 - `isContainerToken(value)`
 
+### `support/crudListFilters.js`
+Exports
+- `CRUD_LIST_FILTER_TYPE_FLAG`
+- `CRUD_LIST_FILTER_TYPE_ENUM`
+- `CRUD_LIST_FILTER_TYPE_ENUM_MANY`
+- `CRUD_LIST_FILTER_TYPE_RECORD_ID`
+- `CRUD_LIST_FILTER_TYPE_RECORD_ID_MANY`
+- `CRUD_LIST_FILTER_TYPE_DATE`
+- `CRUD_LIST_FILTER_TYPE_DATE_RANGE`
+- `CRUD_LIST_FILTER_TYPE_NUMBER_RANGE`
+- `CRUD_LIST_FILTER_TYPE_PRESENCE`
+- `CRUD_LIST_FILTER_TYPES`
+- `CRUD_LIST_FILTER_PRESENCE_PRESENT`
+- `CRUD_LIST_FILTER_PRESENCE_MISSING`
+- `CRUD_LIST_FILTER_PRESENCE_OPTIONS`
+- `defineCrudListFilters(definitions = {})`
+- `resolveCrudListFilterQueryKeys(definition = {})`
+- `resolveCrudListFilterOptionLabel(definition = {}, value = "", { fallback = "" } = {})`
+Local functions
+- `normalizeCrudListFilterType(value = "")`
+- `normalizeCrudListFilterOption(rawOption = null, { context = "filter option" } = {})`
+- `normalizeCrudListFilterOptions(rawOptions = [], { context = "filter options" } = {})`
+- `normalizeCrudListFilterPresenceOptions(rawOptions = [])`
+- `normalizeCrudListFilterLookup(rawLookup = null)`
+- `resolveCrudListFilterOptionSet(rawDefinition = {}, type = "")`
+- `normalizeCrudListFilterDefinition(rawKey = "", rawDefinition = null)`
+
 ### `support/crudLookup.js`
 Exports
 - `DEFAULT_CRUD_LOOKUP_CONTAINER_KEY`

package/reference/autogen/packages/assistant-runtime.md

@@ -55,6 +55,13 @@ Exports
 Exports
 - `AssistantClientProvider`
 
+### `src/client/support/workspaceScopeSupport.js`
+Exports
+- `EMPTY_WORKSPACE_WEB_SCOPE_SUPPORT`
+- `WORKSPACES_WEB_SCOPE_SUPPORT_INJECTION_KEY`
+- `isWorkspaceWebScopeSupport(value)`
+- `useWorkspaceWebScopeSupport({ required = false } = {})`
+
 ### `src/server/actionIds.js`
 Exports
 - `actionIds`
@@ -79,16 +86,16 @@ Exports
 Exports
 - `registerRoutes(app)`
 Local functions
-- `buildRouteParamsValidator(requiresWorkspace)`
-- `buildConversationMessagesRouteParamsValidator(requiresWorkspace)`
-- `readWorkspaceInput(request, requiresWorkspace)`
+- `buildRouteParamsValidator(requiresWorkspace, workspaceScopeSupport = null)`
+- `buildConversationMessagesRouteParamsValidator(requiresWorkspace, workspaceScopeSupport = null)`
+- `readWorkspaceInput(request, requiresWorkspace, workspaceScopeSupport = null)`
 - `requireAssistantSurface(appConfig = {}, targetSurfaceId = "")`
 - `requireHostSurfaceId(request)`
 - `shouldExposeAppErrorDetails(errorCode = "")`
 - `sendPreStreamErrorResponse(reply, error)`
-- `resolveRouteRequestState(request, { resolveCurrentAppConfig = () => ({}), kind = "runtime", requiresWorkspace = false } = {})`
-- `registerSettingsRoutes(router, resolveCurrentAppConfig, { requiresWorkspace = false } = {})`
-- `registerRuntimeRoutes(router, resolveCurrentAppConfig, { requiresWorkspace = false } = {})`
+- `resolveRouteRequestState(request, { resolveCurrentAppConfig = () => ({}), kind = "runtime", requiresWorkspace = false, workspaceScopeSupport = null } = {})`
+- `registerSettingsRoutes(router, resolveCurrentAppConfig, { requiresWorkspace = false, workspaceScopeSupport = null } = {})`
+- `registerRuntimeRoutes(router, resolveCurrentAppConfig, { requiresWorkspace = false, workspaceScopeSupport = null } = {})`
 
 ### `src/server/repositories/assistantConfigRepository.js`
 Exports
@@ -128,11 +135,11 @@ Local functions
 
 ### `src/server/services/assistantConfigService.js`
 Exports
-- `createService({ assistantConfigRepository, consoleService = null, appConfig = {}, resolveAppConfig = null } = {})`
+- `createService({ assistantConfigRepository, consoleService = null, appConfig = {}, resolveAppConfig = null, workspaceScopeSupport = null } = {})`
 
 ### `src/server/services/chatService.js`
 Exports
-- `createChatService({ aiClientFactory, transcriptService, serviceToolCatalog, assistantConfigService, appConfig = {}, resolveAppConfig = null } = {})`
+- `createChatService({ aiClientFactory, transcriptService, serviceToolCatalog, assistantConfigService, appConfig = {}, resolveAppConfig = null, workspaceScopeSupport = null } = {})`
 Local functions
 - `normalizeConversationId(value)`
 - `normalizeHistory(history = [])`
@@ -183,6 +190,12 @@ Local functions
 - `buildCatalogOptions(appConfig = {}, surfaceId = "")`
 - `requireContextSurfaceId(context = {})`
 
+### `src/server/support/workspaceScopeSupport.js`
+Exports
+- `WORKSPACES_SERVER_SCOPE_SUPPORT_TOKEN`
+- `isWorkspaceServerScopeSupport(value)`
+- `resolveWorkspaceServerScopeSupport(scope = null, { required = false, caller = "assistant-runtime" } = {})`
+
 ### `src/shared/assistantRuntimeConfig.js`
 Exports
 - `assistantRuntimeConfig`

package/reference/autogen/packages/crud-core.md

@@ -132,6 +132,28 @@ Local functions
 - `resolveRoleMatrixPolicy(matrix = {}, operation = "readable", input = {})`
 - `applyReadableFieldPolicyToRecord(record, allowedFields, outputRules = null, { context = "crudFieldAccess" } = {})`
 
+### `src/server/listFilters.js`
+Exports
+- `CRUD_LIST_FILTER_INVALID_VALUES_REJECT`
+- `CRUD_LIST_FILTER_INVALID_VALUES_DISCARD`
+- `createCrudListFilters(definitions = {}, { columns = {}, apply = {} } = {})`
+Local functions
+- `normalizeCrudListFilterInvalidValues(value = "")`
+- `createSingleOrMultiValueSchema(itemSchema)`
+- `firstValue(value)`
+- `normalizeDateFilterValue(value)`
+- `normalizeNumberFilterValue(value)`
+- `normalizeRecordIdFilterValue(value)`
+- `normalizeRecordIdFilterValues(value)`
+- `resolveAllowedOptionValues(filter = {})`
+- `normalizeAllowedTextValue(value, allowedValues = new Set())`
+- `normalizeAllowedTextValues(value, allowedValues = new Set())`
+- `addDaysToDateFilterValue(value = "", days = 0)`
+- `createFilterQuerySchema(filter = {}, { invalidValues = CRUD_LIST_FILTER_INVALID_VALUES_REJECT } = {})`
+- `normalizeFilterValue(filter = {}, source = {})`
+- `normalizeColumnsMap(columns = {})`
+- `applyDefaultFilterQuery(queryBuilder, filter = {}, value, column = "")`
+
 ### `src/server/listQueryValidators.js`
 Exports
 - `createCrudCursorPaginationQueryValidator(list = {})`

package/reference/autogen/packages/crud-ui-generator.md

@@ -82,6 +82,7 @@ Local functions
 - `toLookupRelation(fieldMetaMap = {}, fieldKey = "", { lookupContainerKey = "lookups" } = {})`
 - `resolveFormInputType(fieldType, fieldFormat)`
 - `resolveFormFieldComponent(fieldType, relation = null)`
+- `buildDefaultNullableBooleanOptions()`
 - `toPositiveInteger(value)`
 - `toAccessorExpression(baseName, fieldKey)`
 - `toOptionalAccessorExpression(baseName, fieldKey)`

package/reference/autogen/packages/kernel.md

@@ -199,6 +199,33 @@ Exports
 Exports
 - `isContainerToken(value)`
 
+### `shared/support/crudListFilters.js`
+Exports
+- `CRUD_LIST_FILTER_TYPE_FLAG`
+- `CRUD_LIST_FILTER_TYPE_ENUM`
+- `CRUD_LIST_FILTER_TYPE_ENUM_MANY`
+- `CRUD_LIST_FILTER_TYPE_RECORD_ID`
+- `CRUD_LIST_FILTER_TYPE_RECORD_ID_MANY`
+- `CRUD_LIST_FILTER_TYPE_DATE`
+- `CRUD_LIST_FILTER_TYPE_DATE_RANGE`
+- `CRUD_LIST_FILTER_TYPE_NUMBER_RANGE`
+- `CRUD_LIST_FILTER_TYPE_PRESENCE`
+- `CRUD_LIST_FILTER_TYPES`
+- `CRUD_LIST_FILTER_PRESENCE_PRESENT`
+- `CRUD_LIST_FILTER_PRESENCE_MISSING`
+- `CRUD_LIST_FILTER_PRESENCE_OPTIONS`
+- `defineCrudListFilters(definitions = {})`
+- `resolveCrudListFilterQueryKeys(definition = {})`
+- `resolveCrudListFilterOptionLabel(definition = {}, value = "", { fallback = "" } = {})`
+Local functions
+- `normalizeCrudListFilterType(value = "")`
+- `normalizeCrudListFilterOption(rawOption = null, { context = "filter option" } = {})`
+- `normalizeCrudListFilterOptions(rawOptions = [], { context = "filter options" } = {})`
+- `normalizeCrudListFilterPresenceOptions(rawOptions = [])`
+- `normalizeCrudListFilterLookup(rawLookup = null)`
+- `resolveCrudListFilterOptionSet(rawDefinition = {}, type = "")`
+- `normalizeCrudListFilterDefinition(rawKey = "", rawDefinition = null)`
+
 ### `shared/support/crudLookup.js`
 Exports
 - `DEFAULT_CRUD_LOOKUP_CONTAINER_KEY`

package/reference/autogen/packages/users-web.md

@@ -104,6 +104,7 @@ Local functions
 - `resolveStableFieldErrorList(fieldKey, message)`
 - `resolveFormFieldType(field = {})`
 - `resolveFormFieldFormat(field = {})`
+- `isNullableFormField(field = {})`
 - `padDateTimePart(value)`
 - `normalizeTimeWhitespace(value)`
 - `toTimeInputValue(value)`
@@ -112,6 +113,18 @@ Local functions
 - `resolveFormFieldInitialValue(field = {})`
 - `shouldSerializeClearedFieldAsNull(field = {})`
 
+### `src/client/composables/internal/crudListFilterLookupSupport.js`
+Exports
+- `normalizeLookupQueryKeyPrefix(value = [])`
+- `normalizeLookupLabelResolverMap(value = {})`
+- `normalizeLookupRequestQueryParamsMap(value = {})`
+- `resolveLookupSelectedValues(filter = {}, rawValue = undefined)`
+- `createLookupOptionsFromItems(items = [], filter = {}, labelResolver = null)`
+- `mergeSelectedLookupOptions(options = [], selectedValues = [], cachedOptions = new Map())`
+- `resolveLookupOptionLabel(options = [], cachedOptions = new Map(), value = "", fallback = "Option")`
+Local functions
+- `createLookupOptionFromItem(item = {}, filter = {}, labelResolver = null)`
+
 ### `src/client/composables/internal/crudListParentTitleSupport.js`
 Exports
 - `resolveCrudListParentDescriptor({ resource = {}, route = null, recordIdParam = "recordId" } = {})`
@@ -339,6 +352,28 @@ Exports
 Exports
 - `useCommand({ ownershipFilter = ROUTE_VISIBILITY_WORKSPACE, surfaceId = "", access = "auto", apiSuffix = "", runPermissions = [], writeMethod = "POST", placementSource = "users-web.command", fallbackRunError = "Unable to complete action.", fieldErrorKeys = [], clearOnRouteChange = true, model, parseInput, buildRawPayload, buildCommandPayload, buildCommandOptions, onRunSuccess, onRunError, suppressSuccessMessage = false, messages = {}, realtime = null } = {})`
 
+### `src/client/composables/useCrudListFilterLookups.js`
+Exports
+- `useCrudListFilterLookups(definitions = {}, { values = {}, adapter = null, recordIdParam = "recordId", queryKeyPrefix = [], placementSourcePrefix = "", requestQueryParams = {}, labelResolvers = {} } = {})`
+
+### `src/client/composables/useCrudListFilters.js`
+Exports
+- `useCrudListFilters(definitions = {}, { labelResolvers = {}, chipLabels = {}, presets = [] } = {})`
+Local functions
+- `normalizeFunctionMap(value = {})`
+- `createInitialFilterValue(filter = {})`
+- `normalizePresetEntries(presets = [])`
+- `resolvePresetValues(preset = {}, { values = {}, filters = {} } = {})`
+- `normalizePresetFilterValue(filter = {}, rawValue)`
+- `normalizeCurrentManyFilterValues(value)`
+- `matchArrayValues(currentValue = [], expectedValue = [])`
+- `matchesPresetFilterValue(filter = {}, currentValue, rawExpectedValue)`
+- `resetFilterValue(values, filter = {})`
+- `applyPresetFilterValue(values, filter = {}, rawValue)`
+- `createQueryParams(values, filterEntries = [])`
+- `resolveAtomicValueLabel(filter = {}, value = "", labelResolvers = {})`
+- `defaultChipLabel(filter = {}, value, labelResolvers = {})`
+
 ### `src/client/composables/useCrudListParentTitle.js`
 Exports
 - `useCrudListParentTitle({ listRuntime = null, resource = {}, adapter = null, recordIdParam = "recordId", queryKeyPrefix = ["users-web", "crud-list-parent-title"], placementSource = "users-web.crud-list-parent-title", fallbackLoadError = "Unable to load parent record.", notFoundMessage = "Parent record not found.", route = null, viewRuntimeFactory = useView } = {})`

package/reference/autogen/packages/workspaces-core.md

@@ -154,6 +154,10 @@ Exports
 - `readWorkspaceSlugFromRouteParams(params = {})`
 - `buildWorkspaceInputFromRouteParams(params = {})`
 
+### `src/server/support/workspaceServerScopeSupport.js`
+Exports
+- `createWorkspaceServerScopeSupport()`
+
 ### `src/server/workspaceBootstrapContributor.js`
 Exports
 - `createWorkspaceBootstrapContributor({ workspaceService, workspacePendingInvitationsService, usersRepository, workspaceInvitationsEnabled = false, appConfig = {}, tenancyProfile = null } = {})`

package/reference/autogen/packages/workspaces-web.md

@@ -313,6 +313,14 @@ Exports
 Exports
 - `buildWorkspaceQueryKey(kind = "", surfaceId = "", workspaceSlug = "")`
 
+### `src/client/support/workspaceScopeSupport.js`
+Exports
+- `WORKSPACES_WEB_SCOPE_SUPPORT_INJECTION_KEY`
+- `createWorkspaceScopeSupport()`
+- `readWorkspaceRouteScope(routeContext = {})`
+Local functions
+- `unwrapRefValue(value)`
+
 ### `src/shared/toolsOutletContracts.js`
 Exports
 - `DEFAULT_TOOLS_LINK_COMPONENT_TOKEN`

package/templates/app/AGENTS.md

@@ -15,6 +15,7 @@ Use these references on demand:
 
 - `node_modules/@jskit-ai/agent-docs/reference/autogen/KERNEL_MAP.md`
 - `node_modules/@jskit-ai/agent-docs/reference/autogen/README.md`
+- `node_modules/@jskit-ai/agent-docs/patterns/INDEX.md`
 - `node_modules/@jskit-ai/agent-docs/guide/agent/index.md`
 - `node_modules/@jskit-ai/agent-docs/site/guide/index.md` when compressed guidance is ambiguous or missing nuance
 - `node_modules/@jskit-ai/agent-docs/templates/APP_BLUEPRINT.md`
@@ -30,6 +31,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 `node_modules/@jskit-ai/agent-docs/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 the app was just created and 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.