@jskit-ai/agent-docs 0.1.118 → 0.1.119

package/guide/agent/app-setup/a-more-interesting-shell.md

@@ -681,13 +681,21 @@ navigation.
 
 The open drawer is content-aware by default. After the visible semantic
 placements and fonts settle, `ShellLayout` measures the rendered labels and
-uses one `navigationItemSpacing` value for the icon-to-label gap and the space
-between the widest label and the drawer edge. It defaults to 12 CSS pixels and
-can be set from 8–24px. The shell remeasures when placements, localization,
-fonts, spacing, the active surface, or the window layout change, and clamps
-unusually long labels to a safe range. The
-closed desktop rail remains 80 CSS pixels wide by default, with every icon and
-its Material selected-state indicator centred in the rail. Rail tooltips use
+uses Material's 12px outer item inset and one `navigationItemSpacing` value for
+the icon-to-label gap and the space between the widest label and the drawer
+edge. The spacing defaults to 12 CSS pixels and can be set from 8–24px. The
+shell remeasures when placements, localization, fonts, spacing, the active
+surface, or the window layout change, and clamps unusually long labels to a safe range. The
+surface label appears once in the top app bar; the drawer starts with its
+destinations instead of repeating that label as an uppercase subheader.
+
+The closed desktop rail remains 80 CSS pixels wide by default, with every icon
+and its Material selected-state indicator centred in the rail. The expanded
+drawer uses the same icon centreline, so toggling the drawer reveals or hides
+labels without making the icons jump sideways. The empty space around a 24px
+icon in the default rail is intentional Material touch/indicator space, not a
+second drawer padding. Products that deliberately need a denser rail can set
+`railWidth`; the shell still enforces a 48px minimum target. Rail tooltips use
 one explicit opaque theme color pair and open on pointer hover or keyboard
 focus.
 
@@ -720,6 +728,21 @@ unsafe share of the viewport or shrink below its touch targets. The app-owned
 `navigation-item-spacing`, so an application does not need to copy or restyle
 the drawer implementation.
 
+### Updating an existing shell app
+
+Commit the app's work and run:
+
+```bash
+npm run jskit:update
+```
+
+Keep the generated/app-owned `src/components/ShellLayout.vue` wrapper and let
+it continue forwarding attributes to the package component. No copied drawer,
+`.v-navigation-drawer` CSS, duplicate surface heading, or replacement smoke
+test is required. If the product intentionally wants a denser desktop rail,
+set the supported prop in that wrapper, for example `:rail-width="64"`; omit it
+to keep the Material 3 80px default.
+
 `useShellErrorPresentationStore()` exposes the current banner, snackbar, and dialog presentation state behind `ShellErrorHost`.
 
 The simplest direct store usage looks like this:

package/package.json

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

package/patterns/placements.md

@@ -58,8 +58,8 @@ Runtime behavior:
 - 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.
-- The standard `ShellLayout` uses one `navigationItemSpacing` value (12px by default) for the icon-to-label gap and the widest label's logical-end gap. It remeasures its content-aware width after placement, locale, font, surface, spacing, and layout changes. Use `drawerWidth` only when a product needs a fixed width; do not add consumer `.v-navigation-drawer` overrides.
-- On medium and expanded layouts, closing the standard drawer produces an 80px Material navigation rail by default. Use `railWidth` to configure that width, or `desktopDrawerClosedMode="hidden"` only when another discoverable navigation surface exists.
+- The standard `ShellLayout` uses Material's 12px outer item inset and one `navigationItemSpacing` value (12px by default) for the icon-to-label gap and widest label's logical-end gap. It remeasures its content-aware width after placement, locale, font, surface, spacing, and layout changes. The surface label belongs once in the top app bar; do not add or restore a duplicate drawer subheader. Use `drawerWidth` only when a product needs a fixed width; do not add consumer `.v-navigation-drawer` overrides.
+- On medium and expanded layouts, closing the standard drawer produces an 80px Material navigation rail by default. Expanded and collapsed icons share one centreline. Use `railWidth` to configure an intentionally denser rail, or `desktopDrawerClosedMode="hidden"` only when another discoverable navigation surface exists.
 - The shell link renderers own rail centring, selected-state treatment, and opaque theme-aware tooltips. Applications should keep supplying the same semantic placement records rather than creating rail-only links or tooltip CSS.
 
 CLI and generators:

package/skills/jskit/references/ui-operations.md

@@ -41,17 +41,18 @@ Doctor must continue to report a missing managed test.
 
 ## Adaptive shell drawer
 
-Use Vuetify Material navigation. Compact close dismisses the temporary drawer.
-Wider layouts default to `desktopDrawerClosedMode="rail"`, retaining primary
-navigation as a rail. Use `desktopDrawerClosedMode="hidden"` only when another
-discoverable navigation affordance exists. Do not create a second drawer/menu
-registry or imitate the rail with CSS.
-
-The drawer uses `navigationItemSpacing` (12px) for icon/label and widest-label/
-edge gaps. Its 80px rail centres complete 48px targets and theme-owned
-tooltips. Set `railWidth` (for example, `64`) for another density, or
-`drawerWidth` for a fixed open width. The app wrapper forwards all three; never
-override `.v-navigation-drawer` in an app.
+Use Vuetify Material navigation. Compact close dismisses the temporary drawer;
+wide layouts default to `desktopDrawerClosedMode="rail"`. Use `hidden` only
+with another navigation affordance.
+
+The drawer omits the app bar's surface label. Open and rail icons share a
+centreline. It uses a 12px outer item inset; `navigationItemSpacing` (12px)
+controls icon/label and label/end gaps. The 80px rail centres 48px targets; set
+`railWidth` (for example, `64`) for a denser rail or `drawerWidth` for a fixed
+drawer. The wrapper forwards these props; never override its CSS.
+
+Existing apps: commit work and run `npm run jskit:update`. Keep and adapt
+the app-owned shell wrapper and smoke test; do not copy or delete them.
 
 ## Browser verification