@jskit-ai/agent-docs 0.1.26 → 0.1.28

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

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,13 +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.
-- If the page link belongs in a non-default outlet, discover the outlet first with `jskit list-placements` and pass `--link-placement`.
-- If the page sits under an existing routed host, check whether `ui-generator page` can infer the correct child placement before writing a custom link by hand.
+- 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

@@ -11,18 +11,84 @@ Use when:
 Check first:
 
 - app `src/placement.js`
+- app `src/placementTopology.js`
 - package placement contributions
+- 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.
 - When asked to change a tab or menu icon, inspect placement metadata before editing page components.
 - Look at placement `props`, especially fields such as `icon`, `prependIcon`, `appendIcon`, or props passed into the linked component token.
 - If the visible entry is contributed by a package, update the owning package placement contribution instead of patching a local page component.
-- If the request is really about where a link appears, check the placement `target`, `surfaces`, `order`, and `when` fields before changing UI markup.
+- 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:
 
 - editing the routed page just to change a shell/tab/menu icon that is actually placement-owned
 - assuming a rendered tab label/icon lives in the page component
+- adding a public `ShellOutlet` without also exposing a semantic placement that maps to it

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`
@@ -174,6 +203,10 @@ Exports
 - `normalizeRecordId(value, { fallback = null } = {})`
 - `normalizeOpaqueId(value, { fallback = null } = {})`
 - `normalizeOneOf(value, allowedValues = [], fallback = "")`
+- `normalizeMobileAssetMode(value = "", { fallback = "bundled" } = {})`
+- `normalizeMobileCallbackPath(value = "", { fallback = "/auth/login" } = {})`
+- `normalizeMobileConfig(source = {})`
+- `normalizeMobileStrategy(value = "", { fallback = "" } = {})`
 - `ensureNonEmptyText(value, label = "value")`
 
 ### `support/permissions.js`
@@ -229,14 +262,26 @@ Local functions
 
 ### `support/shellLayoutTargets.js`
 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 = "")`
+- `normalizePlacementOwnerId(value = "")`
+- `normalizePlacementSurfaceId(value = "")`
+- `normalizePlacementSurfaces(value)`
+- `normalizePlacementTopologyDefinition(value = {}, { context = "placement topology" } = {})`
+- `normalizePlacementTopologyEntry(value = {}, { context = "placement topology" } = {})`
+- `normalizePlacementTopologyVariant(value = {}, { context = "placement topology variant" } = {})`
+- `normalizeSemanticPlacementId(value = "")`
 - `normalizeShellOutletTargetId(value = "")`
 - `normalizeShellOutletTargetRecord(value = {}, { context = "shell layout" } = {})`
+- `resolvePlacementTargetReference(value = "")`
 - `resolveShellOutletTargetParts({ target = "" } = {})`
 Local functions
 - `parseTagAttributes(attributesSource = "")`
+- `normalizePlacementRenderers(value = {})`
 - `isDefaultAttributeEnabled(value)`
 
 ### `support/sorting.js`

package/reference/autogen/README.md

@@ -23,9 +23,12 @@ Startup navigation stays in `KERNEL_MAP.md`.
 - [database-runtime-mysql](/packages/agent-docs/reference/autogen/packages/database-runtime-mysql.md)
 - [database-runtime-postgres](/packages/agent-docs/reference/autogen/packages/database-runtime-postgres.md)
 - [feature-server-generator](/packages/agent-docs/reference/autogen/packages/feature-server-generator.md)
+- [google-rewarded-core](/packages/agent-docs/reference/autogen/packages/google-rewarded-core.md)
+- [google-rewarded-web](/packages/agent-docs/reference/autogen/packages/google-rewarded-web.md)
 - [http-runtime](/packages/agent-docs/reference/autogen/packages/http-runtime.md)
 - [json-rest-api-core](/packages/agent-docs/reference/autogen/packages/json-rest-api-core.md)
 - [kernel](/packages/agent-docs/reference/autogen/packages/kernel.md)
+- [mobile-capacitor](/packages/agent-docs/reference/autogen/packages/mobile-capacitor.md)
 - [realtime](/packages/agent-docs/reference/autogen/packages/realtime.md)
 - [resource-core](/packages/agent-docs/reference/autogen/packages/resource-core.md)
 - [resource-crud-core](/packages/agent-docs/reference/autogen/packages/resource-crud-core.md)

package/reference/autogen/packages/assistant.md

@@ -27,6 +27,7 @@ Exports
 - `renderAssistantPageSummary(pageTarget = {}, { pageAlreadyExisted = false, pageOverwritten = false } = {})`
 Local functions
 - `resolveLinkToPropLine(linkTo = "")`
+- `resolveOwnerLine(owner = "")`
 - `resolveTemplateFilePath(relativePath = "")`
 
 ### `src/server/subcommands/page.js`
@@ -53,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/auth-web.md

@@ -51,7 +51,7 @@ Local functions
 
 ### `src/client/composables/loginView/useLoginViewActions.js`
 Exports
-- `useLoginViewActions({ state, validation, queryClient, errorRuntime } = {})`
+- `useLoginViewActions({ state, validation, queryClient, errorRuntime, oauthLaunchClient = null } = {})`
 
 ### `src/client/composables/loginView/useLoginViewState.js`
 Exports
@@ -84,6 +84,9 @@ Exports
 - `AuthProfileMenuLinkItem`
 - `useAuthStore`
 - `useAuthGuardRuntime`
+- `completeOAuthCallbackFromCurrentLocation`
+- `completeOAuthCallbackFromUrl`
+- `readOAuthCallbackParamsFromUrl`
 - `routeComponents`
 - `clientProviders`
 
@@ -152,9 +155,25 @@ Exports
 ### `src/client/runtime/inject.js`
 Exports
 - `AUTH_GUARD_RUNTIME_INJECTION_KEY`
+- `AUTH_OAUTH_LAUNCH_CLIENT_INJECTION_KEY`
 - `EMPTY_AUTH_GUARD_STATE`
 - `EMPTY_AUTH_GUARD_RUNTIME`
 - `useAuthGuardRuntime({ required = false } = {})`
+- `useAuthOAuthLaunchClient({ required = false } = {})`
+
+### `src/client/runtime/oauthCallbackRuntime.js`
+Exports
+- `completeOAuthCallbackFromCurrentLocation(options = {})`
+- `completeOAuthCallbackFromUrl({ url = "", fallbackReturnTo = "/", allowedReturnToOrigins = [], defaultProvider = "", request = authHttpRequest, refreshSession = async () => null } = {})`
+- `readOAuthCallbackParamsFromUrl(url = "")`
+Local functions
+- `parseCallbackUrl(url = "")`
+- `buildOAuthCompletePayload({ callbackParams = null, provider = "", hasSessionPair = false } = {})`
+
+### `src/client/runtime/oauthLaunchClient.js`
+Exports
+- `createBrowserOAuthLaunchClient({ location = null } = {})`
+- `isAuthOAuthLaunchClient(value = null)`
 
 ### `src/client/runtime/useLoginView.js`
 Exports

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,7 +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" } = {})`
@@ -69,6 +79,7 @@ Exports
 - `resolveNearestParentRouteParamKey(routePath = "", { recordIdParam = "recordId" } = {})`
 - `buildListHeaderColumns(fields = [])`
 - `buildListRowColumns(fields = [])`
+- `buildListCardFields(fields = [])`
 - `buildViewColumns(fields = [])`
 - `buildFormColumns(fields = [])`
 - `resolveRecordIdFieldKey(fields = [])`
@@ -131,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
@@ -143,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