@jskit-ai/agent-docs 0.1.27 → 0.1.28

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

@@ -249,6 +249,8 @@ packages/contacts/
 
 src/pages/w/[workspaceSlug]/admin/contacts/
   index.vue
+  listBulkActions.js
+  listFilters.js
   new.vue
   [contactId]/index.vue
   [contactId]/edit.vue
@@ -439,6 +441,8 @@ src/pages/w/[workspaceSlug]/admin/contacts/
   new.vue
   [contactId]/index.vue
   [contactId]/edit.vue
+  listBulkActions.js
+  listFilters.js
   _components/CrudAddEditForm.vue
   _components/CrudAddEditFormFields.js
 ```
@@ -449,13 +453,13 @@ This is the list-page container.
 
 Its job is usually to:
 
-- call `useCrudList()`
-- bind `records.searchQuery`
-- render list rows
+- call `useCrudListScreen()`
+- pass page-local `listFilters` and `listBulkActions`
+- render the shared `CrudListScreen`
 - resolve list/view/edit/new URLs
 - pass route query state through when navigating deeper
 
-The actual list machinery lives uphill in `users-web` composables and the shared resource contract.
+The actual list machinery lives in `users-web` shared screen composables and the shared resource contract.
 
 ### `[contactId]/index.vue`
 
@@ -463,8 +467,8 @@ This is the view-page container.
 
 Its job is usually to:
 
-- call `useCrudView()`
-- render the selected record
+- call `useCrudViewScreen()`
+- render the shared `CrudViewScreen`
 - resolve "back" and "edit" navigation
 
 Again, the runtime behavior is mostly uphill. The page is a route-level composition layer.
@@ -475,9 +479,9 @@ These are add/edit route wrappers.
 
 They usually:
 
-- call `useCrudAddEdit()`
+- call `useCrudAddEditScreen()`
 - wire lookup runtime for lookup-backed fields
-- hand the form runtime into the shared form component
+- hand the form runtime into the shared `CrudAddEditScreen`
 
 These files are mostly containers. That is deliberate.
 
@@ -735,15 +739,14 @@ The safe mental model is:
 
 ### `_components/CrudAddEditForm.vue`
 
-This is the shared rendering shell for the add/edit form.
+This is the generated field bridge for the shared add/edit screen.
 
 It owns:
 
-- the card/surface layout
-- save/cancel buttons
 - which set of generated form fields is rendered in `new` vs `edit`
+- lookup field prop forwarding into those fields
 
-It does **not** own persistence logic.
+It does **not** own persistence logic or the shared screen chrome. `CrudAddEditScreen` from `users-web` owns the common title, load state, retry action, save/cancel action row, and form surface.
 
 ### `_components/CrudAddEditFormFields.js`
 
@@ -766,8 +769,8 @@ That is navigation wiring, not CRUD logic.
 
 A generated CRUD works because several layers cooperate:
 
-1. the route page calls `useCrudList()`, `useCrudView()`, or `useCrudAddEdit()`
-2. those composables use the shared resource contract and runtime helpers from `users-web`
+1. the route page calls `useCrudListScreen()`, `useCrudViewScreen()`, or `useCrudAddEditScreen()`
+2. those screen composables configure the lower-level list/view/add-edit runtimes from `users-web`
 3. the request hits the HTTP route from `registerRoutes.js`
 4. the route executes an action from `actions.js`
 5. the action delegates to the service in `service.js`
@@ -789,8 +792,9 @@ Use this rule of thumb when deciding where to edit:
 | Change default ordering, searchable fields, or ownership autofilter | `contactResource.js` | The shared resource is the single source of truth for both CRUD contract and internal JSON:API resource config |
 | Change SQL, joins, parent filters, or advanced search | `repository.js` | This is the data-access layer |
 | Add cross-record or domain rules on save/delete | `service.js` | This is business logic |
-| Change page layout and display behavior | the route pages and app-owned composables | This is presentation |
-| Change form field layout and inputs | `_components/CrudAddEditForm.vue` and `CrudAddEditFormFields.js` | This is the generated form layer |
+| Change shared CRUD screen chrome, load states, or retry behavior | `users-web` shared screen components | Generated pages consume the shared screen contract |
+| Change page-specific display behavior | the route pages, generated slots, and app-owned composables | This is presentation |
+| Change form field layout and inputs | `_components/CrudAddEditForm.vue` and `CrudAddEditFormFields.js` | This is the generated form field layer |
 
 ## How mature CRUDs grow
 
@@ -824,10 +828,10 @@ This is the default generated list-page pattern for the `contacts` resource from
 
 #### Client side
 
-Enable query search in the list page:
+The generated list page delegates search wiring to the shared list screen:
 
 ```js
-const records = useCrudList({
+const screen = useCrudListScreen({
   resource: uiResource,
   apiSuffix: "/contacts",
   search: {
@@ -841,15 +845,14 @@ const records = useCrudList({
 });
 ```
 
-Then bind the input:
+Then render the shared screen:
 
 ```vue
-<v-text-field
-  v-model="records.searchQuery"
-  :loading="records.isSearchDebouncing"
-/>
+<CrudListScreen :screen="screen" />
 ```
 
+The shared screen binds the search input and passes the search query into the list request.
+
 The client runtime debounces the search input, writes the query string to `q`, and trims the list back to the first page when search changes.
 
 #### Server side
@@ -1006,27 +1009,33 @@ Important limits:
 
 For the agent-facing quick rule, see `patterns/crud-repository-mapping.md`.
 
-### Pattern 3: structured list filters from one shared definition
+### Pattern 3: client-side structured list filters
+
+Generated CRUD list pages include a client-side filter seam by default. The generated page imports `./listFilters.js` and passes `listFilters` into `useCrudListScreen(...)`. The shared list screen builds the filter runtime, passes the resulting query params into the list request, and renders `CrudListFilterSurface`.
+
+If `listFilters.js` is empty, the filter surface renders nothing.
 
-This is the default pattern once a CRUD list needs real filters.
+Use this first when adding filters. The server still needs explicit support for any query params you declare; JSKIT does not infer server filter semantics from the UI.
 
 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`
+- custom chip/reset/query-param state
+- a second copy of the same client filter definitions
 
 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 on each structured filter field with `createCrudListFilterQueryField(...)`
-4. build the client runtime from that same definition with `useCrudListFilters(...)`
+1. edit the generated page-local `listFilters.js`
+2. let `useCrudListScreen(...)` wire the filter query params into the list request
+3. let `CrudListFilterSurface` render controls, chips, clear-one, and clear-all behavior
+4. add explicit server support separately for the same query params
 
-For example, a shared filter-definition module can look like this:
+For example, a generated page-local filter-definition module can look like this:
 
 ```js
-export const CONTACTS_LIST_FILTER_DEFINITIONS = Object.freeze({
+import { defineCrudListFilters } from "@jskit-ai/users-web/client/filters";
+
+const listFilters = defineCrudListFilters({
   onlyStaff: {
     type: "flag",
     label: "Staff"
@@ -1040,60 +1049,94 @@ export const CONTACTS_LIST_FILTER_DEFINITIONS = Object.freeze({
     label: "Archived"
   }
 });
+
+export { listFilters };
+```
+
+### Pattern 3B: client-side bulk list actions
+
+Generated CRUD list pages also include a client-side bulk-action seam by default. The generated page imports `./listBulkActions.js` and passes `listBulkActions` into `useCrudListScreen(...)`. The shared list screen builds the bulk-action runtime and renders `CrudListBulkActionSurface`.
+
+If `listBulkActions.js` is empty, selection controls and the bulk action bar stay hidden.
+
+Use this first when adding selected-record actions. JSKIT does not invent server operations such as delete, archive, approve, or export; the action definition owns that behavior.
+
+For example:
+
+```js
+import { defineCrudListBulkActions } from "@jskit-ai/users-web/client/bulkActions";
+
+const listBulkActions = defineCrudListBulkActions([
+  {
+    key: "archive",
+    label: "Archive",
+    async run({ selectedIds, clearSelection, reload }) {
+      await archiveContacts(selectedIds);
+      clearSelection();
+      await reload();
+    }
+  }
+]);
+
+export { listBulkActions };
 ```
 
+The generated runtime passes action handlers:
+
+- `selectedIds`
+- `ids` as an alias for `selectedIds`
+- `selectedRecords`
+- `clearSelection()`
+- `records`
+- `reload`
+
+Keep bulk action definitions page-local unless another page needs to share them.
+
 #### Exact file checklist
 
 For a generated CRUD, treat this as the concrete file plan:
 
+- edit `src/pages/.../contacts/listFilters.js`
+- make sure the matching server route/action/repository code already accepts and applies the declared query params
+
+If the filter contract should be shared with server code, promote it into a CRUD package module and import it from both sides:
+
 - create `packages/contacts/src/shared/contactListFilters.js`
 - update `packages/contacts/src/server/registerRoutes.js` so the list route query validator lists structured filter params explicitly with `createCrudListFilterQueryField(...)`, unless you already extracted list-query composition into `packages/contacts/src/server/listQueryValidators.js`
 - update `packages/contacts/src/server/actions.js` so the list action input validator includes that same explicit contract choice
 - update `packages/contacts/src/server/repository.js` so the list query path builds the `createCrudListFilters(...)` runtime and calls `applyQuery(...)`
-- update the app-owned list page or list-runtime composable, usually under `src/pages/.../contacts/` or `src/composables/...`, so it builds `useCrudListFilters(...)`, passes `queryParams` into `useCrudList(...)`, and renders chips / reset behavior from that runtime
-
-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:
+Generated CRUD list pages pass the page-local filter definitions into the shared list screen:
 
 ```js
-const listFilters = useCrudListFilters(CONTACTS_LIST_FILTER_DEFINITIONS);
+import { listFilters } from "./listFilters.js";
 
-const records = useCrudList({
+const screen = useCrudListScreen({
   resource: uiResource,
   apiSuffix: "/contacts?include=pets",
-  search: {
-    enabled: true,
-    mode: "query"
-  },
-  queryParams: listFilters.queryParams,
-  syncToRoute: {
-    enabled: true,
-    search: true,
-    queryParams: true,
-    queryParamBlacklist: ["include", "cursor", "limit"]
-  }
+  listFilters,
+  routeQueryBlacklist: Object.freeze(["include", "cursor", "limit"])
 });
 ```
 
-That gives you, from one place:
+```vue
+<CrudListScreen :screen="screen" />
+```
+
+Inside that shared screen runtime, `useCrudListFilters(...)` gives the list:
 
-- `listFilters.values`
-- `listFilters.queryParams`
-- `listFilters.presets`
-- `listFilters.activeChips`
-- `listFilters.hasActiveFilters`
-- `listFilters.clearChip(...)`
-- `listFilters.clearFilters()`
-- `listFilters.toggle(...)` for flag filters
-- `listFilters.applyPreset(...)`
-- `listFilters.matchesPreset(...)`
+- `filterRuntime.values`
+- `filterRuntime.queryParams`
+- `filterRuntime.presets`
+- `filterRuntime.activeChips`
+- `filterRuntime.hasActiveFilters`
+- `filterRuntime.clearChip(...)`
+- `filterRuntime.clearFilters()`
+- `filterRuntime.toggle(...)` for flag filters
+- `filterRuntime.applyPreset(...)`
+- `filterRuntime.matchesPreset(...)`
 
 So the same runtime owns:
 
@@ -1247,13 +1290,13 @@ async function list(query = {}, callOptions = {}) {
 
 #### Best practices
 
-- Put the filter definitions in the CRUD package, not the page. Both server and client need them.
+- Keep client-only filters in the generated page-local `listFilters.js`. Move definitions into a CRUD package only when server code or another page needs to share them.
 - Keep the filter keys identical all the way through: definition key, query param key, and repository meaning.
 - Prefer `createCrudListFilterQueryField(...)` plus `createCrudListFilterQuerySchema(...)` at route/action boundaries so accepted structured-filter params stay visible in app code.
 - Use `type: "presence"` for null/not-null filters such as assigned vs unassigned storage. Do not model those as custom enums plus `applyQuery(...)` overrides unless the SQL semantics are genuinely different from `whereNotNull(...)` / `whereNull(...)`.
 - Use `createCrudListFilters(...)` unless the list semantics are truly unusual.
 - Use `q` for free-text and explicit query params for structured filters.
-- Run `jskit doctor` after wiring filters. It flags inline/local filter-definition objects passed into `useCrudListFilters(...)` or `createCrudListFilters(...)`.
+- Run `jskit doctor` after wiring filters. It flags inline filter-definition objects passed into `useCrudListFilters(...)` or `createCrudListFilters(...)`.
 
 ### Pattern 4: lookup-backed structured filters
 
@@ -1265,7 +1308,7 @@ This is the next real-world step: filters like `supplierContactId`, `locationId`
 
 The right pattern is:
 
-1. keep the lookup filter in the shared definitions
+1. keep the lookup filter in `listFilters.js` or in shared definitions when server code also imports it
 2. use `useCrudListFilters(...)` for state, chips, and query params
 3. use `useCrudListFilterLookups(...)` for option loading and label resolution
 

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

@@ -262,7 +262,7 @@ npx jskit generate crud-server-generator scaffold \
 
 This creates an app-local package under `packages/contacts/`.
 
-If the table should be CRUD-owned now but should **not** expose public HTTP CRUD routes yet, add:
+If the table should already be CRUD-owned but should **not** expose public HTTP CRUD routes yet, add:
 
 ```bash
 --internal
@@ -322,7 +322,7 @@ npm run devlinks
 
 The same rule applies after later server scaffolds such as `addresses` and `comments`. The UI generator can still read the generated resource file directly, but the app runtime needs the local package install boundary to be completed before the CRUD can boot normally.
 
-For standard CRUDs, that file is now intentionally compact. It uses `defineCrudResource(...)` from `@jskit-ai/resource-crud-core`, authors the canonical `schema` / `searchSchema` / `defaultSort` / `autofilter` shape once, and lets JSKIT derive the standard CRUD operation contracts from it.
+For standard CRUDs, that file is intentionally compact. It uses `defineCrudResource(...)` from `@jskit-ai/resource-crud-core`, authors the canonical `schema` / `searchSchema` / `defaultSort` / `autofilter` shape once, and lets JSKIT derive the standard CRUD operation contracts from it.
 
 ### Step 3: scaffold the UI
 
@@ -498,7 +498,7 @@ It will be the block added for the `w/[workspaceSlug]/admin/contacts/[contactId]
 
 Depending on what outlets already exist in the app, that block may try to place `Addresses` in the shell menu or in the contact subpages outlet. For this example, remove it either way and keep navigation manual from the contact view.
 
-This is an intentional manual cleanup for now:
+This workflow has one intentional manual cleanup:
 
 - keep the routed pages
 - remove the auto menu link
@@ -657,7 +657,7 @@ If the contact view page should stay visible while child comment routes render u
 npx jskit generate ui-generator add-subpages \
   w/[workspaceSlug]/admin/contacts/[contactId]/index.vue \
   --title "Contact" \
-  --subtitle "View and manage this contact."
+  --subtitle "Contact activity and notes."
 ```
 
 That is the point where the comments example deliberately overlaps with the `ui-generator` chapter. This pattern needs both:
@@ -772,4 +772,4 @@ They become one workflow:
 2. scaffold the server/resource package
 3. scaffold only the UI shape that the feature actually needs
 
-The next chapter is [Advanced CRUDs](/guide/generators/advanced-cruds). Read it as the structural follow-on to this one: this chapter teaches how to generate the CRUD, and the next one teaches how to reason about the files you now own.
+The next chapter is [Advanced CRUDs](/guide/generators/advanced-cruds). Read it as the structural follow-on to this one: this chapter teaches how to generate the CRUD, and the next one teaches how to reason about the generated files the app owns.

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

@@ -80,7 +80,7 @@ The important default is this:
 - if JSKIT sees no nearer routed host, the new page gets a normal shell/menu placement
 - if JSKIT does see a nearer routed host, the new page gets linked into that host instead
 
-Open the app and you now have a real `/reports` page plus a real shell link for it.
+Open the app to see a real `/reports` page plus a real shell link for it.
 
 ### Customizing the generated menu link
 
@@ -217,7 +217,7 @@ After the command, the page gains three important pieces:
 - a `ShellOutlet` for the child-page tabs
 - `RouterView`
 
-That means the page can now keep rendering shared content while child routes render underneath it.
+That lets the page keep rendering shared content while child routes render underneath it.
 
 This is the first big distinction in this chapter:
 
@@ -247,7 +247,7 @@ The route page is still a normal page file. What changes is the inferred placeme
 - no parent host found -> shell/menu entry
 - nearest parent host found -> child link inside that host
 
-So JSKIT is not switching to a different generator. It is switching the inferred placement behavior because the route tree now has a routed host above the new page.
+So JSKIT is not switching to a different generator. The route tree has a routed host above the new page, so the inferred placement behavior follows that host.
 
 ### Making a child page the default landing route
 
@@ -358,7 +358,7 @@ Then upgrade that page into a host:
 npx jskit generate ui-generator add-subpages \
   home/contacts/[contactId].vue \
   --title "Contact" \
-  --subtitle "View and manage this contact."
+  --subtitle "Contact activity and notes."
 ```
 
 This time the parent is a file route, not an `index.vue` route.
@@ -436,13 +436,13 @@ This is different from `page` in a very important way:
 
 So if the thing you are adding should live *inside* an existing shell region, not at its own route, `placed-element` is the right command.
 
-By default, the element goes into:
+By default, the element targets the semantic status placement:
 
 ```text
-shell-layout:top-right
+shell.status
 ```
 
-That is why this is such a good command for widgets, status panels, and compact shell extensions.
+That is why this is such a good command for widgets, status panels, and compact shell extensions. The default shell topology maps `shell.status` to the concrete shell status outlet for each layout class.
 
 ### When `--surface` matters
 
@@ -469,19 +469,19 @@ A practical example is:
 npx jskit generate ui-generator placed-element \
   --name "Ops Panel" \
   --surface admin \
-  --placement shell-layout:top-right
+  --placement shell.status
 ```
 
-`shell-layout:top-right` can exist across several surfaces. If your app has several enabled surfaces, `--surface admin` tells JSKIT which one this element is actually meant for.
+`shell.status` can be global across several surfaces. If your app has several enabled surfaces, `--surface admin` tells JSKIT which one this element is actually meant for.
 
 So the rule of thumb is:
 
-- page-owned outlet target -> surface is often inferable
-- shared shell target in a multi-surface app -> pass `--surface`
+- page-owned semantic placement target -> surface is often inferable
+- shared shell semantic placement in a multi-surface app -> pass `--surface`
 
 ### `--placement`
 
-Use `--placement` when the default target `shell-layout:top-right` is not what you want.
+Use `--placement` when the default target `shell.status` is not what you want.
 
 This is the option that answers:
 
@@ -489,6 +489,8 @@ This is the option that answers:
 
 In practice, it is the first override you will use for `placed-element`.
 
+`--placement` expects a semantic placement id such as `shell.status`, `shell.global-actions`, or `settings.sections`. Concrete `host:position` outlets are exposed through topology, not used as normal placed-element authoring targets.
+
 ### `--path`
 
 Use `--path` when the component file should live somewhere other than `src/components`.
@@ -682,4 +684,4 @@ That is why the commands fit together cleanly:
 - `page` can then create nested child routes under those hosts
 - `placed-element` and `outlet` handle the non-routed side of the same UI system
 
-Once the UI you want is no longer just page structure and starts needing real database-backed list/view/new/edit behavior, move to the CRUD generators chapter.
+Once the UI you want needs real database-backed list/view/new/edit behavior instead of only page structure, move to the CRUD generators chapter.

package/guide/agent/index.md

@@ -4,7 +4,7 @@
 
 This guide is the main hands-on path through JSKIT.
 
-It now starts with a fast reproducible Quickstart, then steps back to the smaller scaffold-first chapters that explain how the app is assembled piece by piece. After that, it introduces the database-backed users layer, expands into console and workspace-aware app structure, and adds a small `App extras` section for optional runtime packages such as the Android Capacitor shell, realtime, and assistant. Finally, the guide breaks out generator-specific workflows into their own section.
+It starts with a fast reproducible Quickstart, then steps back to the smaller scaffold-first chapters that explain how the app is assembled piece by piece. After that, it introduces the database-backed users layer, expands into console and workspace-aware app structure, and adds a small `App extras` section for optional runtime packages such as the Android Capacitor shell, realtime, and assistant. Finally, the guide breaks out generator-specific workflows into their own section.
 
 ## Table of Contents
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.27",
+  "version": "0.1.28",
   "description": "Distributed JSKIT agent workflows, guides, and generated reference maps.",
   "type": "module",
   "files": [

package/patterns/INDEX.md

@@ -26,10 +26,12 @@ How to use it:
   - `page-redirects.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`
+- ajax, fetch, API call, request, endpoint, HTTP client, `useCrudListScreen()`, `useCrudViewScreen()`, `useCrudAddEditScreen()`, `useList()`, `useView()`, `useAddEdit()`, `useEndpointResource()`, `usersWebHttpClient`
   - `client-requests.md`
 - playwright, browser test, e2e, ui verification, authenticated ui test, test auth, dev login as, dev auth bypass
   - `ui-testing.md`
+- generated UI contract, design contract, navigation roles, density, placeholder copy, card shells, shared CRUD screens
+  - `generated-ui-contract-tracking.md`
 - filter, filters, search facets, chips, date range, enum filter, lookup filter, `useCrudListFilters`, `createCrudListFilters`
   - `filters.md`
 - `searchSchema`, `search: true`, `applyFilter`, server search, query validators, backend filters, internal JSON REST filters
@@ -49,6 +51,7 @@ How to use it:
 - [live-actions.md](./live-actions.md)
 - [client-requests.md](./client-requests.md)
 - [ui-testing.md](./ui-testing.md)
+- [generated-ui-contract-tracking.md](./generated-ui-contract-tracking.md)
 - [filters.md](./filters.md)
 - [server-search.md](./server-search.md)
 - [crud-repository-mapping.md](./crud-repository-mapping.md)

package/patterns/client-requests.md

@@ -6,7 +6,7 @@ Use when:
 - custom endpoint reads or writes
 - AJAX questions
 - replacing raw `fetch(...)` calls
-- choosing between `useCommand()`, `useList()`, `useView()`, `useAddEdit()`, and `useEndpointResource()`
+- choosing between shared CRUD screens, `useCommand()`, `useList()`, `useView()`, `useAddEdit()`, and `useEndpointResource()`
 
 Rules:
 
@@ -19,22 +19,31 @@ Rules:
 Choose the function like this:
 
 ```js
-// 1. Button/toggle/small mutation
+// 1. Generated CRUD route screen
+const screen = useCrudListScreen({ ... });
+
+// 2. Button/toggle/small mutation
 const command = useCommand({ ... });
 
-// 2. List endpoint
+// 3. List endpoint
 const list = useList({ ... });
 
-// 3. Single-record endpoint
+// 4. Single-record endpoint
 const view = useView({ ... });
 
-// 4. Form save flow
+// 5. Form save flow
 const form = useAddEdit({ ... });
 
-// 5. Truly custom endpoint
+// 6. Truly custom endpoint
 const resource = useEndpointResource({ ... });
 ```
 
+Use the shared CRUD screen wrappers when the route is a generated CRUD page:
+
+- `useCrudListScreen()` plus `CrudListScreen` for list route pages
+- `useCrudViewScreen()` plus `CrudViewScreen` for record view route pages
+- `useCrudAddEditScreen()` plus `CrudAddEditScreen` for generated new/edit route pages
+
 Use the CRUD wrappers when they fit:
 
 - `useCrudList()` for routed CRUD lists
@@ -55,6 +64,13 @@ Why this is the standard JSKIT shape:
 - Use `requestQueryParams` for endpoint query strings on list, view, and add/edit runtimes.
 - Keep `apiUrlTemplate` path-only. Do not put `?include=...` or other query strings in URL templates.
 
+Error presentation rules:
+
+- Resource load failures should stay local to the screen with the runtime's `loadError` state and a retry action.
+- Do not force global banners for ordinary list/view/add-edit load failures; the shell error policy treats `resource-load` as `silent` by default.
+- Use `useUiFeedback()` or `useCommand()` for user-triggered action feedback. Those flows report `action-feedback`, and the app-owned shell error policy decides the channel.
+- Use explicit shell error intents only for exceptional app-level cases: `app-recoverable` for recoverable shell/runtime failures and `blocking` for failures that require user attention.
+
 Avoid:
 
 - raw `fetch(...)` for standard page or component work
@@ -62,3 +78,4 @@ Avoid:
 - manually concatenating scoped route params into API URLs
 - using a lower-level seam when a higher-level routed CRUD or command runtime already fits
 - smuggling query params into `apiUrlTemplate`
+- reporting routine resource load errors through hand-written global snackbar/banner calls

package/patterns/crud-repository-mapping.md

@@ -80,7 +80,7 @@ const repositoryRuntime = createCrudResourceRuntime(resource, {
 });
 ```
 
-What CRUD core now does for you:
+What CRUD core does for you:
 - default select columns include only column-backed output fields
 - create/update write payloads serialize standard writable `date-time` fields centrally
 - create/update write payloads also apply any explicit field write serializers centrally

package/patterns/crud-scaffolding.md

@@ -19,12 +19,20 @@ Rules:
 - For a CRUD-backed entity, start with `jskit generate crud-server-generator scaffold ...`.
 - Unless the table is already owned by a JSKIT baseline package or is an explicit narrow exception recorded in `.jskit/table-ownership.json`, every persisted app-owned table must go through that server CRUD step first.
 - That server scaffold is the crucial first step even if no CRUD UI will be created yet.
-- If the table should be CRUD-owned now but should not expose public CRUD HTTP routes yet, scaffold it with `jskit generate crud-server-generator scaffold ... --internal` instead of dropping to direct knex or a hand-built pseudo-repository.
+- If the table should already be CRUD-owned but should not expose public CRUD HTTP routes yet, scaffold it with `jskit generate crud-server-generator scaffold ... --internal` instead of dropping to direct knex or a hand-built pseudo-repository.
 - Create the real table directly in the database before scaffolding. `crud-server-generator` reads the live table shape.
 - If `crud-server-generator` is going to own the CRUD, do not hand-write a separate CRUD migration for that table. The generator installs and manages the CRUD migration scaffold itself.
 - Do not scaffold CRUD UI, hand-build CRUD routes, or hand-build CRUD endpoints before the server CRUD package and shared resource file exist.
 - Treat the generated shared resource file as the canonical CRUD contract for later UI scaffolding and CRUD behavior changes.
 - `feature-server-generator` is not the default lane for ordinary persisted entities. Use it for workflows or orchestration that sit on top of CRUD-owned tables, or for rare explicit non-CRUD exceptions.
+- Generated CRUD UI must be compact-first. Lists need searchable cards on compact widths and tables only for medium/expanded layouts.
+- Generated CRUD list screens need real loading, empty, and error states. Empty copy should name the resource, such as "No customers yet", and offer the create action when available.
+- Generated CRUD view/new/edit screens should use page headers plus direct sheet panels. Do not use generic card shells as the page architecture.
+- Compact CRUD actions should be reachable without a drawer. Use a mobile-visible primary action or FAB for create flows.
+- Row actions should collapse into an overflow/action menu on compact widths and can be inline on wider layouts.
+- Bulk actions should be declared in the generated page-local `listBulkActions.js`. The generated list owns selection state, keeps selection controls hidden until actions exist, and exposes selected ids/records to action handlers.
+- Structured filters should use shared filter definitions and collapse to compact filter controls/sheets when they outgrow simple search. Do not stack dense desktop filter bars on phone widths.
+- Use `--navigation-role` for CRUD list placement intent. Main resources can stay `primary`; nested/detail/workflow CRUD routes should usually be `secondary`, `workflow`, or `none`.
 
 Meaning of `--internal`:
 
@@ -38,3 +46,4 @@ Avoid:
 - starting with `crud-ui-generator` before the server scaffold exists
 - hand-building CRUD routes or validators that duplicate the generated server resource contract
 - letting a new app-owned table exist in the live database without either generated CRUD ownership or a documented `.jskit/table-ownership.json` exception
+- accepting table-only CRUD UI as "done" when the route is visible on phone widths