@jskit-ai/agent-docs 0.1.5 → 0.1.7

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

@@ -613,6 +613,57 @@ The safe mental model is:
 - use command runtimes for actions
 - keep the server as the source of truth for derived state
 
+### Choosing the right client request seam
+
+When you need client-side HTTP work in JSKIT, do not start with raw `fetch(...)`.
+
+Choose the highest-level runtime that matches the interaction:
+
+```js
+// 1. Button/toggle/small mutation
+const command = useCommand({ ... });
+
+// 2. List endpoint
+const list = useList({ ... });
+
+// 3. Single-record endpoint
+const view = useView({ ... });
+
+// 4. Form save flow
+const form = useAddEdit({ ... });
+
+// 5. Truly custom endpoint
+const resource = useEndpointResource({ ... });
+```
+
+Use the CRUD wrappers when they fit:
+
+- `useCrudList()` for routed CRUD lists
+- `useCrudView()` for routed CRUD record loading
+- `useCrudAddEdit()` for routed CRUD forms
+
+Why this is the standard JSKIT shape:
+
+- `useCommand()` resolves the correct scoped API path for the current route and surface.
+- The higher-level list, view, add/edit, and command runtimes send requests through the standard HTTP runtime instead of ad hoc request code.
+- The default client runtime uses `usersWebHttpClient`, which already handles credentials and CSRF token behavior.
+- `useEndpointResource()` gives the shared endpoint primitive for loading, saving, and standard load/save error handling. Higher-level runtimes like `useCommand()` and `useAddEdit()` layer UI feedback and field-error behavior on top of that primitive.
+
+If you need a custom scoped endpoint path outside the higher-level runtimes, prefer `usePaths().api(...)` rather than hand-building scoped URLs:
+
+```js
+const paths = usePaths();
+const reportsApiPath = computed(() => paths.api("/reports"));
+```
+
+The safe mental model is:
+
+- do not raw `fetch(...)` for normal app work
+- do not invent ad hoc local AJAX helpers
+- 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
+
 ### `_components/CrudAddEditForm.vue`
 
 This is the shared rendering shell for the add/edit form.
@@ -678,7 +729,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 +737,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 +834,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"
+  }
+});
+```
+
+#### Exact file checklist
+
+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:
 
-Keep filter state in a small app-owned composable, then pass it into `useCrudList()` as `queryParams`.
+- `packages/contacts/src/shared/contactListFilters.js`
 
-Example shape:
+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 +900,7 @@ const records = useCrudList({
     enabled: true,
     mode: "query"
   },
-  queryParams: computed(() => ({
-    ...listFilters.filters
-  })),
+  queryParams: listFilters.queryParams,
   syncToRoute: {
     enabled: true,
     search: true,
@@ -814,65 +910,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(...)`
 
-- visible in the URL
-- restorable on refresh
-- preserved when opening a record and coming back
+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.
+
+`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 +1200,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 +1240,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 +1343,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.7",
   "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,36 @@
+# 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`
+- ajax, fetch, API call, request, endpoint, HTTP client, `useList()`, `useView()`, `useAddEdit()`, `useEndpointResource()`, `usersWebHttpClient`
+  - `client-requests.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)
+- [client-requests.md](./client-requests.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/client-requests.md

@@ -0,0 +1,56 @@
+# Client Request Patterns
+
+Use when:
+
+- deciding which JSKIT client function to use for HTTP work
+- custom endpoint reads or writes
+- AJAX questions
+- replacing raw `fetch(...)` calls
+- choosing between `useCommand()`, `useList()`, `useView()`, `useAddEdit()`, and `useEndpointResource()`
+
+Rules:
+
+- Prefer the highest-level JSKIT runtime that matches the UI interaction.
+- Do not hand-roll local AJAX helpers when an existing JSKIT runtime already fits.
+- Do not use raw `fetch(...)` for normal app work.
+- Use `usePaths().api(...)` for custom scoped API paths instead of concatenating route params into URLs by hand.
+- Drop to `usersWebHttpClient.request(...)` only for exceptional low-level cases.
+
+Choose the function like this:
+
+```js
+// 1. Button/toggle/small mutation
+const command = useCommand({ ... });
+
+// 2. List endpoint
+const list = useList({ ... });
+
+// 3. Single-record endpoint
+const view = useView({ ... });
+
+// 4. Form save flow
+const form = useAddEdit({ ... });
+
+// 5. Truly custom endpoint
+const resource = useEndpointResource({ ... });
+```
+
+Use the CRUD wrappers when they fit:
+
+- `useCrudList()` for routed CRUD lists
+- `useCrudView()` for routed CRUD record loading
+- `useCrudAddEdit()` for routed CRUD forms
+
+Why this is the standard JSKIT shape:
+
+- `useCommand()` resolves the scoped API path for the current route and surface.
+- The higher-level list, view, add/edit, and command runtimes send requests through the shared HTTP runtime.
+- `usersWebHttpClient` already handles credentials and CSRF behavior.
+- `useEndpointResource()` is the shared endpoint primitive for loading, saving, and standard load/save error handling. Higher-level runtimes add UI feedback and field-error handling on top.
+
+Avoid:
+
+- raw `fetch(...)` for standard page or component work
+- page-local HTTP helpers that duplicate JSKIT runtime seams
+- manually concatenating scoped route params into API URLs
+- using a lower-level seam when a higher-level routed CRUD or command runtime already fits

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,12 +15,43 @@ 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`
 - `node_modules/@jskit-ai/agent-docs/templates/WORKBOARD.md`
 - `node_modules/@jskit-ai/agent-docs/skills/jskit-review/SKILL.md` for review passes when your Codex environment supports packaged skills
 
+## Mandatory Start Gate
+
+Before any non-trivial change:
+
+1. Read this file and the workflow files above in the current turn. Do not rely on memory alone.
+2. If the task involves JSKIT UI, routing, surfaces, CRUDs, filters, placements, live actions, or similar implementation details, scan `node_modules/@jskit-ai/agent-docs/patterns/INDEX.md` and read the relevant pattern files before editing.
+3. For substantial or multi-chunk work, create or update `.jskit/WORKBOARD.md` before editing.
+4. Before editing, print a compact read receipt with:
+   - `Read receipt: ...`
+   - `Active chunk: ...`
+   - `Generator decision: ...`
+   - `Relevant patterns: ...`
+   - `Active rules from docs: ...`
+5. When files need to be created, prefer `jskit generate ...` over creating them from scratch, even if the generated output will need follow-up adaptation. If not using a generator, say why.
+6. Do not edit code until the read receipt is printed and the workboard step is complete when it applies.
+
+## Mandatory Done Gate
+
+Before calling a chunk done, report:
+
+- `Deslop review: ...`
+- `JSKIT review: ...`
+- `Material/Vuetify review: ...`
+- `Verification: ...`
+- `Files changed: ...`
+- `Commands run: ...`
+- `Remaining unverified: ...`
+
+If a feature spans more than one chunk, repeat those passes on the whole changeset after the final chunk.
+
 Core rules:
 
 - Inspect the workspace before assuming a JSKIT app exists.
@@ -41,7 +72,6 @@ Core rules:
 - For CRUD chunks, ask the developer which operations are allowed, which fields belong in the list view if one exists, and the intended look of the view and edit/new forms before generating code.
 - Every user-facing screen must pass a Material Design and Vuetify quality review before the chunk is considered done.
 - Do not implement app features before the blueprint has the database, surfaces, ownership model, and route/screen plan written down.
-- For substantial or multi-chunk work, create or update `.jskit/WORKBOARD.md` as the per-request execution tracker.
 - Break planned work into reviewable chunks before implementing. One CRUD is usually one chunk, but auth/platform setup, shell work, and cross-cutting integrations can be their own chunks.
 - Do not move to the next chunk until the current chunk has passed implementation, deslop review, JSKIT best-practices review, Material Design/Vuetify review, and verification.
 - If a feature spans more than one chunk, run a final whole-changeset deslop pass, JSKIT pass, Material Design/Vuetify pass, and verification pass after the last chunk.