@jskit-ai/agent-docs 0.1.27 → 0.1.28

package/patterns/filters.md

@@ -17,21 +17,35 @@ Ask first:
 - 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.
+Default JSKIT client pattern:
+1. Generated CRUD list pages include a page-local `listFilters.js` file next to `index.vue`.
+2. Put client filter definitions in that file with `defineCrudListFilters(...)`.
+3. The generated `index.vue` passes `listFilters` into `useCrudListScreen(...)`; the shared list screen builds `useCrudListFilters(listFilters)`, passes `filterRuntime.queryParams` into the list request, and renders `CrudListFilterSurface`.
+4. If `listFilters` is empty, the filter surface renders nothing and the page behaves like a normal searchable list.
+5. The AI/app author is responsible for ensuring the server accepts and applies the query params declared in `listFilters.js`.
+6. For lookup-backed filters, use `useCrudListFilterLookups(...)` when the page needs remote options or readable chip labels.
+
+Generated client shape:
+- `src/pages/<surface>/<resource>/listFilters.js`
+- `const listFilters = defineCrudListFilters({ ... })`
+- `useCrudListScreen({ ..., listFilters })`
+- shared screen runtime owns:
+- `const filterRuntime = useCrudListFilters(listFilters)`
+- `queryParams: filterRuntime.queryParams`
+- `<CrudListFilterSurface :filters="listFilters" :runtime="filterRuntime" />`
+
+Server-side pattern, only when implementing real backend filter semantics:
+1. Put reusable server-aware filter definitions in the CRUD package if the filter contract needs to be shared outside one generated page.
    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 `createCrudListFilterQueryField(...)` plus `createCrudListFilterQuerySchema(...)`, and use `applyQuery(...)` in the repository. There is no default validator mode or route-runtime 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 lists structured filter params explicitly with `createCrudListFilterQueryField(...)` inside `createCrudListFilterQuerySchema(...)`, 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(...)`
+- update the generated page-local `listFilters.js` first; only edit `index.vue` if a specialist lookup label/runtime integration is needed
+- for lookup-backed filters, wire `useCrudListFilterLookups(...)` beside the existing generated filter runtime instead of replacing `CrudListFilterSurface`
 
 Validation mode is part of the contract:
 - there is no default mode and no fallback alias, so every explicit structured filter field must choose `invalidValues: "reject"` or `invalidValues: "discard"` deliberately
@@ -72,11 +86,15 @@ Avoid:
 - hiding accepted structured filter params behind whole-query validator generation when the route/action contract can list them directly
 - 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
+- editing generated `.vue` files just to add basic filter controls; use the page-local `listFilters.js` seam first
 - 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
+- inline filter-definition objects passed into `useCrudListFilters(...)` or `createCrudListFilters(...)`; keep definitions in a named module
 
 Good shape:
+- `src/pages/home/customers/listFilters.js`
+- `const listFilters = defineCrudListFilters({ status: { type: "enum", ... } })`
+- generated page passes `listFilters` into `useCrudListScreen(...)`
+- shared screen runtime passes `filterRuntime.queryParams` into the list request
 - `packages/receivals/src/shared/receivalListFilters.js`
 - `createCrudListFilters(RECEIVAL_LIST_FILTER_DEFINITIONS, ...)`
 - `const listFilters = useCrudListFilters(RECEIVAL_LIST_FILTER_DEFINITIONS, { presets: [...] })`
@@ -89,7 +107,7 @@ Preset contract notes:
 - 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
+- one filter definition source of truth: generated page-local `listFilters.js` for client-only filters, or a shared CRUD-package module when server code imports the same definitions
 - server validator/repository logic derived from that source, with route/action query params still listed explicitly
 - client query params/chips/reset logic derived from that source
 - lookup-backed filters use the shared lookup helper, not a page-local mini-framework

package/patterns/generated-ui-contract-tracking.md

@@ -0,0 +1,62 @@
+# Generated UI Contract Tracking
+
+Use this file to track the generator-level UI contract work. Keep entries concrete and update the checklist as each slice lands.
+
+## Goal
+
+Generated JSKIT apps should feel like real adaptive apps by default, not framework demos. The contract must be enforced in generators, descriptors, docs, and tests so it does not drift.
+
+## Current Scope
+
+- [x] Centralize navigation role behavior beyond per-generator helpers.
+- [x] Improve product-aware navigation inference and CLI prompting.
+- [x] Audit generated/package UI templates for placeholder or instructional live-page copy.
+- [x] Formalize surface density rules for app, admin, console, and settings screens.
+- [x] Add shared typography/density primitives or generator support helpers where they reduce duplication.
+- [x] Enforce "no cards inside cards" for generated page architecture while preserving intentional tool/dialog cards.
+- [x] Expand UI verification from shell smoke coverage to generator-pattern smoke coverage for current page, CRUD, and shell outputs.
+- [x] Centralize the JSKIT design contract and make tests consume it.
+
+## Work Slices
+
+- [x] Slice 1: create the central contract/support seam and move navigation-role constants into it.
+- [x] Slice 2: wire `ui-generator` and `crud-ui-generator` to the shared contract.
+- [x] Slice 3: add template/content contract scans for placeholder copy, card-shell misuse, and missing responsive hooks.
+- [x] Slice 4: audit package templates that ship live UI and classify intentional cards.
+- [x] Slice 5a: extend generated app Playwright smoke coverage to assert the generated screen contract.
+- [x] Slice 5b: enforce page, CRUD, and shell generator-pattern verification through shared source contracts plus responsive smoke checks.
+- [x] Slice 6: update distributed agent docs and regenerated references/catalog outputs.
+
+## Verification Checklist
+
+- [x] `npm run lint`
+- [x] `npm run check:runtime-deps`
+- [x] `npm run jskit -- lint-descriptors`
+- [x] `npm run catalog:build`
+- [x] `npm run agent-docs:build`
+- [x] `npm test --workspace @jskit-ai/kernel`
+- [x] `npm test --workspace @jskit-ai/ui-generator`
+- [x] `npm test --workspace @jskit-ai/crud-ui-generator`
+- [x] `npm test --workspace @jskit-ai/shell-web`
+- [x] `npm test --workspace @jskit-ai/users-web`
+- [x] `npm test --workspace @jskit-ai/workspaces-web`
+- [x] `npm test --workspace @jskit-ai/jskit-cli`
+- [x] `npm test --workspace @jskit-ai/create-app`
+- [x] `npm test --workspace @jskit-ai/agent-docs`
+- [x] `git diff --check`
+
+## Notes
+
+- Do not weaken semantic placement defaults while adding navigation inference.
+- Do not turn the contract into runtime business logic; it is generator and template policy.
+- Do not remove intentional cards from specialist UI components just to satisfy a broad scan.
+- Keep generated files deterministic and update catalog/agent-doc outputs when descriptors or exported symbols change.
+- Kernel shared UI contract must stay surface-id agnostic. Concrete mappings like admin/console to operator profile belong in generators or package templates.
+- Item 3 is complete for current generated surfaces: page, CRUD, shell, and starter outputs require compact/medium/expanded coverage, horizontal overflow checks, generated screen checks, and 48px tap target checks. Calendar/grid/bottom-sheet specialist generators remain future scope until those generators exist.
+- Item 5 is complete for current generators: `primary`, `secondary`, `utility`, `detail`, `workflow`, and `none` are centralized in the generated UI contract, generators consume that contract, and `utility` resolves to seeded `shell.global-actions` topology.
+- Item 6 is complete for the default shell: compact app bars use compact density and bounded top-left/top-right regions, while primary navigation remains in semantic bottom navigation instead of app-bar chrome.
+- CRUD filters are client-side by default: generated list pages create a page-local `listFilters.js` and pass it into `useCrudListScreen(...)`; the shared list screen wires `filterRuntime.queryParams` into the list request and renders `CrudListFilterSurface`. Server filter behavior remains explicit app/package work.
+- CRUD bulk actions are client-side by default: generated list pages create a page-local `listBulkActions.js` and pass it into `useCrudListScreen(...)`; the shared list screen wires `useCrudListBulkActions(...)` and keeps selection controls hidden until actions are declared.
+- Generated CRUD page templates delegate their screen chrome to shared `users-web` screen components (`CrudListScreen`, `CrudViewScreen`, and `CrudAddEditScreen`) so list/view/form load states, retry actions, responsive shell layout, filters, and bulk actions do not drift across generated pages.
+- Routine resource-load errors stay local to the generated screen and retry affordance. Action feedback uses the shell error policy through `action-feedback`.
+- `page.supporting-content` is a semantic supporting region in the default shell. Compact layout renders it as a closed bottom sheet; medium/expanded layouts render it as a closed side panel.

package/patterns/page-scaffolding.md

@@ -18,14 +18,31 @@ Rules:
 
 - Default to `jskit generate ui-generator page ...` for a new app-owned non-CRUD route page.
 - Let the generator create both the page file and the matching `src/placement.js` entry, then adapt the generated output if needed.
+- Choose the generated page's product navigation role deliberately. Use `--navigation-role primary` for main destinations, `secondary` for lower-priority shell links, and `detail`, `workflow`, or `none` when the page should not appear in navigation.
 - If the page link belongs in a non-default semantic slot, discover the public placement first with `jskit list-placements` and pass `--link-placement`.
 - If you need the concrete outlet inventory, use `jskit list-placements --concrete`; do not target concrete outlets by default.
 - If the page sits under an existing routed host, check whether `ui-generator page` can infer the correct `page.section-nav` owner before writing a custom link by hand.
 - If you do not use `ui-generator page`, state exactly why the generator does not fit before editing code.
 - For a small placeholder route inside an existing route family, update the workboard rather than rewriting the blueprint unless the durable route or surface plan changed.
+- Generated live pages must be usable screens, not instructional scaffolds. Do not ship copy such as "replace this", "use this area", or "this page is ready".
+- Prefer a page header plus a direct `v-sheet` working region. Do not wrap every generated page in a generic `v-card`.
+- If the screen is not implemented yet, use a product-shaped empty state with one clear next action or status, not developer instructions.
+- Primary navigation links belong in semantic placements such as `shell.primary-nav` or `page.section-nav`; do not place every generated route into one drawer by default.
+- Compact layouts must be checked first: no horizontal overflow, no unreachable primary action, and tap targets should be at least 48 px.
+
+Generated UI contract:
+
+- App-facing screens are phone-first and task-first; admin/console screens may be denser but still need responsive controls.
+- Navigation uses semantic placements by default. Raw `host:position` outlets are advanced infrastructure.
+- Page architecture is header plus direct work region, normally `v-sheet`; do not use generic page-level `v-card` shells.
+- Empty/loading/error states are product-shaped and resource-named.
+- Detail and workflow routes are not primary navigation by default.
+- Generated UI must have compact, medium, and expanded browser checks when it changes user-facing behavior.
 
 Avoid:
 
 - hand-writing both `src/pages/...` and `src/placement.js` for a normal non-CRUD page before checking `ui-generator`
 - treating a small page stub as permission to rewrite marketing copy, route architecture, or blueprint scope
 - claiming that no generator exists without checking the actual `jskit` generator inventory first
+- adding cards inside cards or repeating the page title inside a card title
+- treating Vuetify component defaults as the product architecture

package/patterns/placements.md

@@ -16,6 +16,65 @@ Check first:
 - package placement topology
 - linked component token props
 
+Mental model:
+
+- `src/placement.js` answers "what is being placed?"
+- `src/placementTopology.js` answers "where does this semantic placement render for compact, medium, and expanded layouts?"
+- `<ShellOutlet target="host:position" />` is the concrete recipient rendered by Vue.
+- Semantic ids use dot notation, for example `shell.primary-nav`, `shell.status`, `page.section-nav`, `page.supporting-content`, `settings.sections`.
+- Concrete outlet ids use colon notation, for example `shell-layout:primary-menu`, `shell-layout:top-right`, `home-settings:primary-menu`.
+- Authoring should target semantic placements by default. Concrete outlets are an advanced escape hatch.
+
+Placement entries:
+
+- Add entries with `addPlacement(...)` in `src/placement.js`.
+- Use `target: "area.slot"` for normal entries.
+- Use `owner` when the semantic placement is scoped to a specific host, for example `target: "page.section-nav", owner: "home-settings"`.
+- Use `kind: "link"` for navigation/menu/tab links. Do not add a link renderer token to the entry unless there is a deliberate override.
+- Use `kind: "component"` for widgets/sections/elements. These entries require `componentToken`.
+- Use `surfaces` to say where the entry is eligible. Missing or `["*"]` means any surface.
+- Use `order` for ordering. Equal order preserves source order.
+- Use `props` for the rendered component props, including labels, icons, `surface`, `scopedSuffix`, `unscopedSuffix`, or explicit `to`.
+- Use `when(context)` only for auth, permissions, feature flags, and runtime state. Do not use `when()` for layout adaptation.
+- Direct concrete placement must use `target: "host:position"` plus `internal: true`. Treat this as low-level infrastructure, not normal app authoring.
+
+Placement topology:
+
+- `src/placementTopology.js` should be append-friendly: keep a `placements` array, export `addPlacementTopology(value)`, and append `addPlacementTopology(...)` blocks at the bottom.
+- Every semantic placement topology entry needs `id`, optional `owner`, optional `description`, `surfaces`, and all three variants: `compact`, `medium`, and `expanded`.
+- Every variant needs an `outlet: "host:position"`.
+- Variant `renderers` maps semantic `kind` values to component tokens, for example `renderers: { link: "local.main.ui.surface-aware-menu-link-item" }`.
+- Renderer choice for semantic `kind: "link"` placements belongs in topology, not in each placement entry.
+- `default: true` marks the fallback semantic placement that page generators use when no nearer host applies.
+- Package topology is discovered too, but app topology with the same `id` and `owner` overrides package topology in CLI discovery.
+
+Runtime behavior:
+
+- The shell runtime loads `/src/placementTopology.js` and `/src/placement.js`.
+- Each `ShellOutlet` asks for placements by concrete `target`, current `surface`, and current layout class.
+- Layout classes are `compact`, `medium`, and `expanded`.
+- For semantic entries, runtime matches topology by `target`, `owner`, and `surface`, then chooses the current layout variant.
+- A semantic entry renders only when the selected variant's `outlet` equals the concrete `ShellOutlet target`.
+- Runtime resolves the component token as `entry.componentToken || variant.renderers[entry.kind]`.
+- Entries without a resolvable component token do not render.
+- `when()` receives placement context including `app`, `surface`, `target`, `layoutClass`, runtime context, local outlet context, and context contributors.
+
+CLI and generators:
+
+- `jskit list-placements` shows semantic placements by default.
+- `jskit list-placements --concrete` shows concrete `ShellOutlet` recipients.
+- `jskit list-placements --all` shows both.
+- `jskit list-placements --json` returns structured semantic and concrete placement data.
+- `ui-generator page`, CRUD UI list generation, and assistant page generation target semantic placements.
+- `--link-placement` for generated pages is a semantic placement id, not a concrete outlet id.
+- If a generated page is under a parent host with a mapped `ShellOutlet`, the generator infers the semantic placement and owner from topology.
+- `ui-generator add-subpages` upgrades a page into a routed child-page host and appends a `page.section-nav` topology entry for the generated concrete outlet.
+- `ui-generator outlet` injects a plain concrete `ShellOutlet` and appends the semantic topology mapping in the same command.
+- `ui-generator page` and `crud-ui-generator crud` accept `--navigation-role` so detail, workflow, and utility routes do not accidentally become primary navigation.
+- `page.supporting-content` is the default semantic place for supporting detail/content overlays. The default shell maps it to a closed compact bottom sheet and a closed medium/expanded side panel.
+- When adding a public concrete outlet by hand, add its semantic topology mapping in the same change.
+- If `jskit list-placements` reports unmapped concrete outlets, either add semantic topology for them or keep those outlets private/internal.
+
 Rules:
 
 - In JSKIT, tab-like links and shell/menu entries are often placement-owned, not page-owned.
@@ -25,6 +84,7 @@ Rules:
 - If the request is really about where a link appears, check the placement `target`, `owner`, `surfaces`, `order`, and `when` fields before changing UI markup.
 - Placement targets should be semantic by default, such as `shell.primary-nav` or `page.section-nav`; concrete `host:position` outlets are the advanced escape hatch.
 - Renderer choice for semantic `kind: "link"` placements belongs in topology, not in each placement entry.
+- Supporting detail content should target `page.supporting-content` rather than generating per-page bottom-sheet markup.
 - Adding a public concrete `ShellOutlet` should happen with a matching semantic topology entry in the same change.
 
 Avoid:

package/patterns/surfaces.md

@@ -19,12 +19,16 @@ Rules:
 - 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.
+- App surfaces should be phone-first and task-first: lower chrome, bottom primary navigation on compact layouts, and prominent task actions.
+- Admin and console surfaces can be denser and more utilitarian, but they still need responsive controls and must not become generic drawer-only mobile UIs.
+- Settings surfaces should expose section navigation, direct controls, and real saved state. Avoid fake overview cards and instructional placeholder copy.
+- Utility/status widgets belong in semantic status/action placements such as `shell.status` or `shell.global-actions`, not primary navigation.
 
 Ask explicitly about:
 
 - route pages
 - menu entries
-- top-left/top-right widgets
+- semantic shell widgets such as `shell.identity`, `shell.status`, and `shell.global-actions`
 - settings pages
 - CRUD screens
 - helper components that only make sense on one surface

package/patterns/ui-testing.md

@@ -10,6 +10,9 @@ Use when:
 Rules:
 
 - Any chunk that adds or changes user-facing UI must include a Playwright flow that exercises the changed behavior before the chunk is done.
+- Generator or package template UI changes must be checked at compact phone, tablet-ish medium, and expanded desktop widths.
+- For generated UI, the browser checks should cover horizontal overflow, clipped text, invisible text, duplicate navigation, broken route placement, and tap targets under 48 px.
+- Apps with `shell-web` installed should start from the generated `tests/e2e/adaptive-shell.spec.ts` smoke and extend it for feature-specific assertions.
 - Record that Playwright run with `jskit app verify-ui --command "<playwright command>" --feature "<label>" --auth-mode <mode>`.
 - `jskit doctor` expects `.jskit/verification/ui.json` to match the current dirty UI file set when UI files are changed.
 - For local pre-merge review, follow the recorded Playwright run with `jskit doctor --against <base-ref>` so `doctor` compares against the branch delta instead of only the local dirty worktree.

package/reference/autogen/KERNEL_MAP.md

@@ -124,6 +124,35 @@ Exports
 Exports
 - `formatDateTime(value, { fallback = "unknown" } = {})`
 
+### `support/generatedUiContract.js`
+Exports
+- `GENERATED_UI_FORBIDDEN_CARD_SHELL_PATTERNS`
+- `GENERATED_UI_FORBIDDEN_LIVE_COPY_PATTERNS`
+- `GENERATED_UI_NAVIGATION_ROLE_DEFAULT`
+- `GENERATED_UI_NAVIGATION_ROLE_LINK_PLACEMENTS`
+- `GENERATED_UI_NAVIGATION_ROLE_OPTION`
+- `GENERATED_UI_NAVIGATION_ROLE_VALUES`
+- `GENERATED_UI_NO_LINK_NAVIGATION_ROLES`
+- `GENERATED_UI_SOURCE_CONTRACT_PROFILES`
+- `GENERATED_UI_SURFACE_PROFILES`
+- `assertGeneratedUiSourceContract(source = "", options = {})`
+- `buildGeneratedUiScreenClassName(baseClassName = "", { surfaceProfile = "" } = {})`
+- `collectGeneratedUiSourceContractIssues(source = "", { profile = "", forbidLiveCopy = undefined, forbidCardShell = undefined, forbiddenPatterns = [], requiredPatterns = [] } = {})`
+- `inferGeneratedUiNavigationRole(options = {}, { dynamicRoutePolicy = "leaf", routePath = "" } = {})`
+- `isGeneratedUiNoLinkNavigationRole(value = "")`
+- `normalizeGeneratedUiNavigationRole(value = "")`
+- `resolveGeneratedUiSurfaceProfile(surfaceProfile = "")`
+- `resolveGeneratedUiNavigationRoleLinkPlacement(options = {}, inferenceContext = {})`
+- `shouldCreateGeneratedUiNavigationLink(options = {}, { allowLinkTo = false, dynamicRoutePolicy = "leaf", routePath = "" } = {})`
+Local functions
+- `matchesGeneratedUiContractPattern(source = "", pattern)`
+- `normalizeGeneratedUiContractPattern(patternEntry = {}, fallbackMessage = "")`
+- `normalizeGeneratedUiContractPatternList(patternEntries = [], fallbackMessage = "")`
+- `resolveGeneratedUiSourceContractProfile(profile = "")`
+- `hasExplicitGeneratedUiNavigationRole(options = {})`
+- `normalizeGeneratedUiRouteSegments(routePath = "")`
+- `isGeneratedUiDynamicRouteSegment(routeSegment = "")`
+
 ### `support/index.js`
 Exports
 - `isRecord`
@@ -235,7 +264,7 @@ Local functions
 Exports
 - `PLACEMENT_LAYOUT_CLASSES`
 - `describeShellOutletTargets(targets = [])`
-- `discoverShellOutletTargetsFromVueSource(source = "", { context = "shell layout" } = {})`
+- `discoverShellOutletTargetsFromVueSource(source = "", { context = "shell layout", enforceSingleDefault = true } = {})`
 - `findShellOutletTargetById(targets = [], targetId = "")`
 - `normalizePlacementKind(value = "")`
 - `normalizePlacementLayoutClass(value = "")`

package/reference/autogen/packages/assistant.md

@@ -54,7 +54,7 @@ Exports
 - `normalizeConfigScope(value = "")`
 - `loadAppConfig(appRoot = "")`
 - `resolveSurfaceDefinition(appConfig = {}, surfaceId = "", optionName = "surface")`
-- `assertAssistantSurfaceIsAvailable(appConfig = {}, surfaceId = "")`
+- `assertAssistantSurfaceIsAvailable(appConfig = {}, surfaceId = "", expected = {})`
 - `resolveAiConfigPrefix(surfaceId = "", explicitPrefix = "")`
 
 ### templates

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

@@ -25,19 +25,26 @@ Local functions
 - `toSingularKebab(value = "")`
 - `toPluralKebab(value = "")`
 - `toTitleFromKebab(value = "", fallback = "")`
+- `buildCrudListCopy(resourceLabels = {})`
 - `normalizeRelativeAppPath(value = "")`
 - `requireTargetRootOption(options = {})`
 - `resolveListTargetFile(targetRoot = "")`
 - `parseOperationsOption(options)`
 - `parseDisplayFieldsOption(options)`
 - `parseParentTitleOption(options)`
+- `shouldCreateNavigationLink(options = {}, inferenceContext = {})`
+- `resolveNavigationRoleLinkPlacement(options = {}, inferenceContext = {})`
 - `validateDisplayFieldsForOperation(selectedFieldKeys, fields, operationName)`
 - `filterDisplayFields(selectedFieldKeys, fields)`
 - `rewriteGeneratedBlockIndent(source = "", { trimPrefix = "", addPrefix = "" } = {})`
 - `hasLookupFormFields(fields = [])`
+- `hasLookupDisplayFields(fields = [])`
+- `buildListCardSlotProps(fields = [])`
+- `buildListRowSlotProps(fields = [])`
+- `buildCrudFieldsSlotProps(fields = [], { includeMode = false } = {})`
 - `buildLookupImportLine(fields = [])`
 - `buildLookupRuntimeSetup(fields = [], { formFieldsVariable = "", resourceNamespace = "", mode = "" } = {})`
-- `buildLookupFormProps(fields = [])`
+- `buildLookupFormProps(fields = [], { sourcePrefix = "" } = {})`
 - `buildLookupFormPropDefinitions({ createFields = [], editFields = [] } = {})`
 - `filterDefaultHiddenListFields(selectedFieldKeys, fields, { recordIdFieldKey = "" } = {})`
 - `ensureFields(fields, fallbackFields = createFieldDefinitions({}))`
@@ -45,8 +52,10 @@ Local functions
 - `resolveResourceNamespace(resource = {}, pageTarget = {}, options = {})`
 - `resolveResourceLabels(namespace = "", pageTarget = {})`
 - `resolveTargetRootRelativeRoutePath(pageTarget = {})`
+- `resolveNavigationInferenceRoutePath(pageTarget = {})`
 - `resolveMenuToPropLine(linkTo = "")`
 - `resolveMenuOwnerLine(owner = "")`
+- `buildMenuAppendBlock({ hasListOperation = false, menuMarker = "", pageLinkTarget = null, pageTarget = {} } = {})`
 - `resolveCrudRelativePath(namespace = "")`
 - `buildListParentTitleImportLine(parentTitleMode = "contextual")`
 - `buildListHeadingTitleSetup({ parentTitleMode = "contextual", resourceNamespace = "", routeTitle = "Records" } = {})`
@@ -70,6 +79,7 @@ Exports
 - `resolveNearestParentRouteParamKey(routePath = "", { recordIdParam = "recordId" } = {})`
 - `buildListHeaderColumns(fields = [])`
 - `buildListRowColumns(fields = [])`
+- `buildListCardFields(fields = [])`
 - `buildViewColumns(fields = [])`
 - `buildFormColumns(fields = [])`
 - `resolveRecordIdFieldKey(fields = [])`
@@ -132,9 +142,6 @@ Local functions
 ### `templates/src/pages/admin/ui-generator/AddEditForm.vue`
 Exports
 - None
-Local functions
-- `resolveFieldErrors(fieldKey)`
-- `resolveCancelTo(target)`
 
 ### `templates/src/pages/admin/ui-generator/AddEditFormFields.js`
 Exports
@@ -144,22 +151,26 @@ Exports
 ### `templates/src/pages/admin/ui-generator/EditElement.vue`
 Exports
 - None
-Local functions
-- `resolveFieldErrors(fieldKey)`
 
 ### `templates/src/pages/admin/ui-generator/EditWrapperElement.vue`
 Exports
 - None
 
+### `templates/src/pages/admin/ui-generator/listBulkActions.js`
+Exports
+- `listBulkActions`
+
 ### `templates/src/pages/admin/ui-generator/ListElement.vue`
 Exports
 - None
 
+### `templates/src/pages/admin/ui-generator/listFilters.js`
+Exports
+- `listFilters`
+
 ### `templates/src/pages/admin/ui-generator/NewElement.vue`
 Exports
 - None
-Local functions
-- `resolveFieldErrors(fieldKey)`
 
 ### `templates/src/pages/admin/ui-generator/NewWrapperElement.vue`
 Exports

package/reference/autogen/packages/kernel.md

@@ -288,6 +288,35 @@ Exports
 Exports
 - `formatDateTime(value, { fallback = "unknown" } = {})`
 
+### `shared/support/generatedUiContract.js`
+Exports
+- `GENERATED_UI_FORBIDDEN_CARD_SHELL_PATTERNS`
+- `GENERATED_UI_FORBIDDEN_LIVE_COPY_PATTERNS`
+- `GENERATED_UI_NAVIGATION_ROLE_DEFAULT`
+- `GENERATED_UI_NAVIGATION_ROLE_LINK_PLACEMENTS`
+- `GENERATED_UI_NAVIGATION_ROLE_OPTION`
+- `GENERATED_UI_NAVIGATION_ROLE_VALUES`
+- `GENERATED_UI_NO_LINK_NAVIGATION_ROLES`
+- `GENERATED_UI_SOURCE_CONTRACT_PROFILES`
+- `GENERATED_UI_SURFACE_PROFILES`
+- `assertGeneratedUiSourceContract(source = "", options = {})`
+- `buildGeneratedUiScreenClassName(baseClassName = "", { surfaceProfile = "" } = {})`
+- `collectGeneratedUiSourceContractIssues(source = "", { profile = "", forbidLiveCopy = undefined, forbidCardShell = undefined, forbiddenPatterns = [], requiredPatterns = [] } = {})`
+- `inferGeneratedUiNavigationRole(options = {}, { dynamicRoutePolicy = "leaf", routePath = "" } = {})`
+- `isGeneratedUiNoLinkNavigationRole(value = "")`
+- `normalizeGeneratedUiNavigationRole(value = "")`
+- `resolveGeneratedUiSurfaceProfile(surfaceProfile = "")`
+- `resolveGeneratedUiNavigationRoleLinkPlacement(options = {}, inferenceContext = {})`
+- `shouldCreateGeneratedUiNavigationLink(options = {}, { allowLinkTo = false, dynamicRoutePolicy = "leaf", routePath = "" } = {})`
+Local functions
+- `matchesGeneratedUiContractPattern(source = "", pattern)`
+- `normalizeGeneratedUiContractPattern(patternEntry = {}, fallbackMessage = "")`
+- `normalizeGeneratedUiContractPatternList(patternEntries = [], fallbackMessage = "")`
+- `resolveGeneratedUiSourceContractProfile(profile = "")`
+- `hasExplicitGeneratedUiNavigationRole(options = {})`
+- `normalizeGeneratedUiRouteSegments(routePath = "")`
+- `isGeneratedUiDynamicRouteSegment(routeSegment = "")`
+
 ### `shared/support/index.js`
 Exports
 - `isRecord`
@@ -399,7 +428,7 @@ Local functions
 Exports
 - `PLACEMENT_LAYOUT_CLASSES`
 - `describeShellOutletTargets(targets = [])`
-- `discoverShellOutletTargetsFromVueSource(source = "", { context = "shell layout" } = {})`
+- `discoverShellOutletTargetsFromVueSource(source = "", { context = "shell layout", enforceSingleDefault = true } = {})`
 - `findShellOutletTargetById(targets = [], targetId = "")`
 - `normalizePlacementKind(value = "")`
 - `normalizePlacementLayoutClass(value = "")`
@@ -667,7 +696,7 @@ Local functions
 
 ### `client/moduleBootstrap.js`
 Exports
-- `bootClientModules({ clientModules = [], app, pinia = null, router, surfaceRuntime, surfaceMode, env, logger = console } = {})`
+- `bootClientModules({ clientModules = [], app, pinia = null, queryClient = null, router, surfaceRuntime, surfaceMode, env, logger = console } = {})`
 Local functions
 - `normalizePackageId(value)`
 - `toRouteSnapshot(route)`
@@ -684,7 +713,7 @@ Local functions
 - `assertRoutesDeclaredInDescriptor({ packageId, source, normalizedRoutes = [], descriptorRouteDeclarations = null } = {})`
 - `resolveDescriptorClientRoutes({ packageId, descriptorUiRoutes = [], routeComponents = {}, logger = null } = {})`
 - `normalizeClientModuleEntries(clientModules)`
-- `createClientRuntimeApp({ profile = "client", app, pinia = null, router, env, logger, surfaceRuntime, surfaceMode } = {})`
+- `createClientRuntimeApp({ profile = "client", app, pinia = null, queryClient = null, router, env, logger, surfaceRuntime, surfaceMode } = {})`
 
 ### `client/pageRedirects.js`
 Exports
@@ -697,7 +726,7 @@ Exports
 - `resolveClientBootstrapDebugEnabled({ env = {}, debugEnabled = undefined, debugEnvKey = "VITE_JSKIT_CLIENT_DEBUG" } = {})`
 - `createClientBootstrapLogger({ env = {}, logger = console, debugEnabled = undefined, debugEnvKey = "VITE_JSKIT_CLIENT_DEBUG" } = {})`
 - `createSurfaceShellRouter({ createRouter, history, routes = [], surfaceRuntime, surfaceMode, fallbackRoute = null, notFoundComponent = null, guard = false } = {})`
-- `bootstrapClientShellApp({ createApp, rootComponent, appConfig = {}, appPlugins = [], pinia = null, router, bootClientModules, surfaceRuntime, surfaceMode, env = {}, fallbackRoute = null, logger = console, createBootstrapLogger = null, debugEnabled = undefined, debugEnvKey = "VITE_JSKIT_CLIENT_DEBUG", debugMessage = "Client modules bootstrapped before router install.", onAfterModulesBootstrapped = null, onAfterRouterReady = null, mountSelector = "#app" } = {})`
+- `bootstrapClientShellApp({ createApp, rootComponent, appConfig = {}, appPlugins = [], pinia = null, queryClient = null, router, bootClientModules, surfaceRuntime, surfaceMode, env = {}, fallbackRoute = null, logger = console, createBootstrapLogger = null, debugEnabled = undefined, debugEnvKey = "VITE_JSKIT_CLIENT_DEBUG", debugMessage = "Client modules bootstrapped before router install.", onAfterModulesBootstrapped = null, onAfterRouterReady = null, mountSelector = "#app" } = {})`
 Local functions
 - `installAppPlugins(app, appPlugins = [])`
 
@@ -1357,6 +1386,7 @@ Exports
 - `resolveNearestParentSubpagesHost`
 - `resolvePageLinkTargetDetails`
 - `discoverPlacementTopologyFromApp`
+- `discoverShellOutletSourcePathsFromApp`
 - `discoverShellOutletTargetsFromApp`
 - `resolveSemanticPlacementTargetFromApp`
 - `resolveShellOutletPlacementTargetFromApp`
@@ -1399,7 +1429,7 @@ Local functions
 - `normalizePlacementTargetId(target = {})`
 - `resolveConcreteTargetOwner(target = "")`
 - `topologyPlacementTargetsConcreteOutlet(placement = {}, target = "")`
-- `resolveSemanticPlacementTargetForConcreteOutlet({ appRoot, concreteTarget = "", surface = "" } = {})`
+- `resolveSemanticPlacementTargetForConcreteOutlet({ appRoot, concreteTarget = "", surface = "", context = "page target" } = {})`
 - `resolveRelativeLinkToFromParent(pageTarget = {}, parentHost = null)`
 - `resolveRelativeLinkToFromNearestIndexOwner(pageTarget = {})`
 - `resolveInferredPageLinkTo({ explicitLinkTo = "", pageTarget = {}, parentHost = null, preservesRelativeSubpageLinks = false, suppressImplicitRelativeLinks = false } = {})`
@@ -1418,6 +1448,7 @@ Exports
 ### `server/support/shellOutlets.js`
 Exports
 - `discoverPlacementTopologyFromApp({ appRoot } = {})`
+- `discoverShellOutletSourcePathsFromApp({ appRoot, sourceRoot = "src" } = {})`
 - `discoverShellOutletTargetsFromApp({ appRoot, sourceRoot = "src" } = {})`
 - `resolveSemanticPlacementTargetFromApp({ appRoot, placement = "", owner = "", surface = "", context = "ui-generator" } = {})`
 - `resolveShellOutletPlacementTargetFromApp({ appRoot, placement = "", context = "ui-generator" } = {})`
@@ -1425,7 +1456,7 @@ Local functions
 - `parseTagAttributes(attributesSource = "")`
 - `isDefaultEnabled(value)`
 - `normalizeAppRouteOutletTarget({ outlet = {}, sourcePath = "" } = {})`
-- `discoverRouteMetaOutletTargetsFromVueSource(source = "", { context = "shell layout" } = {})`
+- `discoverRouteMetaOutletTargetsFromVueSource(source = "", { context = "shell layout", enforceSingleDefault = true } = {})`
 - `collectVueFilePaths(rootDirectoryPath)`
 - `readInstalledPackageStates(appRoot)`
 - `normalizePackageOutletTarget({ packageId = "", outlet = {}, descriptorPath = "" } = {})`
@@ -1434,6 +1465,7 @@ Local functions
 - `loadAppPlacementTopology(appRoot)`
 - `collectInstalledPackagePlacementTopology(appRoot)`
 - `findSemanticPlacementById(placements = [], { id = "", owner = "", surface = "" } = {})`
+- `collectAppSourceShellOutletTargets({ appRoot, sourceRoot = "src", enforceSingleDefault = true, context = "discoverShellOutletTargetsFromApp" } = {})`
 
 ### `server/support/SupportCoreServiceProvider.js`
 Exports

package/reference/autogen/packages/realtime.md

@@ -42,6 +42,7 @@ Local functions
 Exports
 - `RealtimeClientProvider`
 Local functions
+- `isCapacitorRuntimeAvailable(app)`
 - `resolveRealtimeClientConfig(app)`
 
 ### `src/client/runtime.js`

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

@@ -39,6 +39,7 @@ Exports
 - None
 Local functions
 - `resolveSeverityColor(severity = "error")`
+- `resolveSeverityIcon(severity = "error")`
 - `resolveTimeout(entry)`
 - `dismiss(entry)`
 - `runAction(entry)`
@@ -48,6 +49,17 @@ Local functions
 ### `src/client/components/ShellLayout.vue`
 Exports
 - None
+Local functions
+- `handlePullPointerDown(event)`
+- `handlePullPointerMove(event)`
+- `handlePullPointerEnd(event)`
+- `handlePullPointerCancel(event)`
+- `cancelPullRefresh()`
+- `refreshFromPullGesture()`
+- `canStartPullRefresh(event)`
+- `isPrimaryTouchPointer(event)`
+- `isAtPageTop()`
+- `isPullRefreshIgnoredTarget(target)`
 
 ### `src/client/components/ShellMenuLinkItem.vue`
 Exports
@@ -61,6 +73,21 @@ Exports
 Exports
 - None
 
+### `src/client/components/ShellRouteTransition.vue`
+Exports
+- None
+Local functions
+- `handlePointerDown(event)`
+- `handlePointerMove(event)`
+- `handlePointerEnd(event)`
+- `handlePointerCancel(event)`
+- `navigateBySwipe(offset = 0)`
+- `isAcceptedSwipe({ deltaX = 0, deltaY = 0, elapsed = 1, velocity = null } = {})`
+- `normalizeComparablePathname(value = "")`
+- `pathMatchesNavigationEntry(pathname = "", entry = {})`
+- `isPrimaryPointerEvent(event)`
+- `isSwipeIgnoredTarget(target)`
+
 ### `src/client/components/ShellSurfaceAwareMenuLinkItem.vue`
 Exports
 - None
@@ -96,16 +123,18 @@ Exports
 Exports
 - `ERROR_CHANNELS`
 - `ERROR_SEVERITIES`
+- `ERROR_INTENTS`
 - `isRecord`
 - `normalizeText(value, fallback = "")`
 - `normalizeChannel(value, fallback = "")`
 - `normalizeSeverity(value, fallback = "error")`
+- `normalizeErrorIntent(value, fallback = "")`
 - `normalizeNonNegativeInteger(value, fallback = 0)`
 - `normalizeAction(value)`
 
 ### `src/client/error/policy.js`
 Exports
-- `createDefaultErrorPolicy({ defaultChannel = "snackbar", unauthorizedChannel = "banner", serverErrorChannel = "dialog", defaultSeverity = "error" } = {})`
+- `createDefaultErrorPolicy({ defaultChannel = "snackbar", resourceLoadChannel = "silent", actionFeedbackChannel = "snackbar", appRecoverableChannel = "banner", blockingChannel = "dialog", defaultSeverity = "error" } = {})`
 
 ### `src/client/error/presentationDefaults.js`
 Exports
@@ -143,6 +172,7 @@ Exports
 - `ShellLayout`
 - `ShellOutlet`
 - `ShellOutletMenuWidget`
+- `ShellRouteTransition`
 - `ShellErrorHost`
 - `ShellMenuLinkItem`
 - `ShellSurfaceAwareMenuLinkItem`
@@ -267,14 +297,16 @@ Local functions
 ### `src/client/providers/ShellWebClientProvider.js`
 Exports
 - `ShellWebClientProvider`
+- `resolveAppPlacementTopologyExport(exported, logger)`
 Local functions
-- `createShellWebQueryClient()`
 - `isMissingDynamicModule(error, moduleSpecifier)`
 - `loadAppPlacementDefinitions(logger)`
 - `loadAppPlacementTopology(logger)`
 - `createErrorConfigToolkit(errorRuntime)`
 - `loadAppErrorConfig(logger, errorRuntime)`
 - `applyAppErrorConfig(errorRuntime, errorConfig = {})`
+- `isPullRefreshQuery(query = null)`
+- `createShellRefreshRuntime({ app, logger = null } = {})`
 - `installVueErrorBridge(vueApp, errorRuntime, logger)`
 - `installRouterErrorBridge(app, errorRuntime, logger)`
 
@@ -350,7 +382,7 @@ Exports
 
 ### `templates/src/components/ShellLayout.vue`
 Exports
-- None
+- `default`
 
 ### `templates/src/error.js`
 Exports