@jskit-ai/agent-docs 0.1.26 → 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
 
@@ -93,7 +93,8 @@ That is where things such as:
 - `label`
 - `order`
 - `icon`
-- a custom `componentToken`
+- `owner`
+- `surfaces`
 
 normally get adjusted.
 
@@ -145,21 +146,12 @@ Use this when the generated page link should go somewhere other than the generat
 Typical reasons:
 
 - you want the page in a different shell menu
-- you want the page link inside a specific existing outlet
+- you want the page link inside a specific existing semantic placement
 - you do not want the link to land in the normal top-level menu
 
 For example, if a page should appear in a settings menu rather than the shell drawer, `--link-placement` is the override that says so.
 
-#### `--link-component-token`
-
-Use this when the page link should render with a different link component than the default inferred one.
-
-In practice, this often means:
-
-- using a tab-style link instead of a normal menu link
-- using a local custom link token for a special shell section
-
-This matters most once you start targeting non-default outlets. A settings or tab host may want a different link renderer than the main shell drawer.
+The value should normally be semantic, such as `shell.primary-nav`, `page.section-nav`, or another `area.slot` placement from `jskit list-placements`. Concrete `host:position` outlets remain an escape hatch, not the default authoring path.
 
 #### `--link-to`
 
@@ -225,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:
 
@@ -255,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
 
@@ -330,12 +322,13 @@ But the placement it wrote was **not** another top-level shell link.
 Instead, it targeted the host outlet:
 
 ```text
-reports:sub-pages
+page.section-nav
 ```
 
-and used the tab-link renderer with:
+with the host owner and relative route:
 
 ```js
+owner: "reports",
 to: "./exports"
 ```
 
@@ -345,7 +338,7 @@ That is exactly the behavior you want:
 - `Exports` becomes a child tab under it
 - the child route renders under the parent instead of becoming another top-level menu entry
 
-This is also why `--link-placement`, `--link-component-token`, and `--link-to` are often unnecessary in the default nested case. Once the host exists, JSKIT already knows the likely child placement target, link renderer, and relative `to` value.
+This is also why `--link-placement` and `--link-to` are often unnecessary in the default nested case. Once the host exists, JSKIT already knows the likely semantic placement, owner, and relative `to` value. The link renderer comes from `src/placementTopology.js`.
 
 ## Nested pages under a file-route host
 
@@ -365,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.
@@ -443,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
 
@@ -476,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:
 
@@ -496,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`.
@@ -532,13 +527,15 @@ In the verified throwaway app, after generating `Alerts Widget`, I ran:
 ```bash
 npx jskit generate ui-generator outlet \
   src/components/AlertsWidgetElement.vue \
-  --target alerts-widget:actions
+  --target alerts-widget:actions \
+  --placement page.actions
 ```
 
-That command touched only one file:
+That command touched the Vue file and the topology file:
 
 ```text
 src/components/AlertsWidgetElement.vue
+src/placementTopology.js
 ```
 
 and injected:
@@ -561,13 +558,16 @@ Use `outlet` when you want:
 - later content to be targetable there
 - no routed child-page behavior
 
-After adding the outlet, `npx jskit list-placements` showed the new target immediately:
+After adding the outlet, `npx jskit list-placements` showed the new semantic placement immediately:
 
 ```text
-- alerts-widget:actions [src/components/AlertsWidgetElement.vue]
+- page.actions: ...
+- compact -> alerts-widget:actions
+- medium -> alerts-widget:actions
+- expanded -> alerts-widget:actions
 ```
 
-So `outlet` is the smallest possible way to make a Vue file part of the placement topology.
+So `outlet` is the smallest possible way to add a concrete recipient and expose it through the public placement topology in the same change.
 
 ### When `outlet` is the smaller correct tool
 
@@ -588,7 +588,7 @@ That is why `outlet` is often the better choice for:
 
 If you do **not** need `RouterView` and you do **not** need child routes, `outlet` is usually the cleaner tool.
 
-### Choosing a good custom `--target`
+### Choosing a good custom `--target` and `--placement`
 
 `--target` should be meaningful to humans, not just syntactically valid.
 
@@ -611,12 +611,20 @@ custom-area:slot1
 
 because the meaningful target name will later show up in:
 
-- `jskit list-placements`
-- placement entries
+- `jskit list-placements --concrete`
+- topology mappings
 - future generator commands
 
 So the target should describe the UI seam you are creating, not just satisfy the `host:position` format.
 
+`--placement` is the public authoring target that other entries should use. It should be semantic, such as:
+
+```text
+page.actions
+```
+
+Adding an outlet without adding a semantic mapping would leave a low-level recipient that normal generators and humans will not discover by default.
+
 ## `add-subpages` versus `outlet`
 
 This is the distinction that most often causes hesitation.
@@ -676,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 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
 
@@ -22,6 +22,7 @@ It now starts with a fast reproducible Quickstart, then steps back to the smalle
 
 ### App Extras
 
+- [Mobile Capacitor](/guide/app-extras/mobile-capacitor)
 - [Realtime](/guide/app-extras/realtime)
 - [Assistant](/guide/app-extras/assistant)
 
@@ -36,6 +37,6 @@ It now starts with a fast reproducible Quickstart, then steps back to the smalle
 
 - Start with `Quickstart` if you want the fastest route to a real workspace-enabled app and the first page-extension patterns.
 - Start with the rest of `App Setup` if you want to understand the base scaffold layer by layer.
-- Use `App Extras` once the base app structure is in place and you want optional runtime packages.
+- Use `App Extras` once the base app structure is in place and you want optional runtime packages such as the Android shell, realtime, or assistant.
 - Jump into `Generators` if you already understand the runtime packages and want app-owned scaffolding workflows.
 - Inside `Generators`, read `CRUD Generators` before `Advanced CRUDs`: the first chapter teaches the workflow, and the second explains the generated anatomy and customization points.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.26",
+  "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)