@jskit-ai/agent-docs 0.1.274 → 0.1.276

package/skills/jskit/references/patterns/server/feature-package/example/booking-engine/package.json

@@ -5,7 +5,7 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@jskit-ai/kernel": "0.2.9",
+    "@jskit-ai/kernel": "0.2.10",
     "json-rest-schema": "^1.0.17"
   },
   "exports": {

package/skills/jskit/references/patterns/shell/application-shell/PATTERN.md

@@ -66,7 +66,9 @@ placement registry, topology, and adaptive smoke helper exported by
 ## Example files
 
 `example/src/` contains the complete shell composition, standard link
-components, settings routes, placement registry, and topology. The browser
+components, settings routes, placement registry, and topology, and a not-found
+view the shell renders, so the top app bar carries its title and the
+navigation leads back into the app. The browser
 example under `example/tests/` exercises the public adaptive-shell contract.
 The `expected-existing/` files show the minimal foundation shapes replaced by
 the complete shell; they are reference inputs, not merge instructions.

package/skills/jskit/references/patterns/shell/application-shell/example/expected-existing/src/pages/home/index.vue

@@ -1,21 +1,8 @@
 <template>
-  <section class="home-start-screen d-flex flex-column ga-4">
-    <v-sheet rounded="lg" border class="home-start-screen__panel">
-      <p class="text-body-2 text-medium-emphasis mb-0">
-        Recent work, saved records, and next actions will appear here once this app has data.
-      </p>
-    </v-sheet>
+  <section class="d-flex flex-column align-center ga-4 py-16 text-center on-surface-variant">
+    <v-icon icon="$inbox" size="48" />
+    <p class="text-body-large mb-0">
+      Recent work, saved records, and next actions will appear here once this app has data.
+    </p>
   </section>
 </template>
-
-<style scoped>
-.home-start-screen {
-  --home-start-panel-padding: 1rem;
-  margin-inline: auto;
-  max-width: 48rem;
-}
-
-.home-start-screen__panel {
-  padding: var(--home-start-panel-padding);
-}
-</style>

package/skills/jskit/references/patterns/shell/application-shell/example/expected-existing/src/views/NotFound.vue

@@ -0,0 +1,14 @@
+<script setup>
+const title = "Not Found";
+const message = "The page you requested does not exist.";
+</script>
+
+<template>
+  <v-container class="fill-height d-flex align-center justify-center">
+    <section class="on-surface-variant text-center">
+      <v-icon icon="$searchOff" size="48" />
+      <h1 class="text-headline-small on-surface mt-4 mb-2">{{ title }}</h1>
+      <p class="text-body-large mb-0">{{ message }}</p>
+    </section>
+  </v-container>
+</template>

package/skills/jskit/references/patterns/shell/application-shell/example/src/pages/home/index.vue

@@ -1,7 +1,9 @@
 <script setup>
 import { computed } from "vue";
 import { useQuery } from "@tanstack/vue-query";
+import { usePaths } from "@jskit-ai/shell-web/client/navigation/usePaths";
 
+const paths = usePaths();
 const healthQuery = useQuery({
   queryKey: ["shell-web", "health"],
   queryFn: async () => {
@@ -28,63 +30,25 @@ const healthPending = computed(
 </script>
 
 <template>
-  <section class="home-surface-screen d-flex flex-column ga-4">
-    <div class="home-surface-screen__actions">
-      <v-btn color="primary" variant="flat" to="/home/settings/general">Settings</v-btn>
+  <section class="d-flex flex-column ga-4">
+    <v-card>
+      <v-list>
+        <v-list-item subtitle="Service health">
+          <template #title>
+            <v-skeleton-loader
+              v-if="healthPending"
+              aria-label="Loading service health"
+              type="text"
+              max-width="80"
+            />
+            <span v-else>{{ health }}</span>
+          </template>
+        </v-list-item>
+        <v-list-item title="/home" subtitle="Route" />
+      </v-list>
+    </v-card>
+    <div class="d-flex justify-end">
+      <v-btn color="secondary-container" prepend-icon="$settings" :to="paths.page('/settings')">Settings</v-btn>
     </div>
-
-    <v-sheet rounded="lg" border class="home-surface-screen__panel">
-      <div class="home-surface-screen__status">
-        <span class="text-caption text-medium-emphasis">Service health</span>
-        <v-skeleton-loader
-          v-if="healthPending"
-          aria-label="Loading service health"
-          class="home-surface-screen__health-skeleton"
-          type="text"
-        />
-        <strong v-else>{{ health }}</strong>
-      </div>
-      <v-divider vertical class="d-none d-sm-block" />
-      <div class="home-surface-screen__status">
-        <span class="text-caption text-medium-emphasis">Route</span>
-        <strong>/home</strong>
-      </div>
-    </v-sheet>
   </section>
 </template>
-
-<style scoped>
-.home-surface-screen {
-  --home-surface-panel-padding: 1rem;
-}
-
-.home-surface-screen__actions {
-  display: flex;
-  justify-content: flex-end;
-}
-
-.home-surface-screen__panel {
-  align-items: stretch;
-  display: flex;
-  flex-wrap: wrap;
-  gap: 1rem;
-  padding: var(--home-surface-panel-padding);
-}
-
-.home-surface-screen__status {
-  display: grid;
-  gap: 0.15rem;
-  min-width: 9rem;
-}
-
-.home-surface-screen__health-skeleton {
-  max-width: 5rem;
-}
-
-@media (max-width: 640px) {
-  .home-surface-screen__actions :deep(.v-btn) {
-    min-height: 48px;
-    width: 100%;
-  }
-}
-</style>

package/skills/jskit/references/patterns/shell/application-shell/example/src/pages/home/settings/general/index.vue

@@ -2,6 +2,15 @@
 import { computed } from "vue";
 import { useShellLayoutState } from "@jskit-ai/shell-web/client/composables/useShellLayoutState";
 
+definePage({
+  meta: {
+    jskit: {
+      title: "General",
+      parent: "/settings"
+    }
+  }
+});
+
 const { drawerDefaultOpen, setDrawerDefaultOpen } = useShellLayoutState();
 
 const drawerDefaultOpenModel = computed({
@@ -15,23 +24,19 @@ const drawerDefaultOpenModel = computed({
 </script>
 
 <template>
-  <section class="settings-general-screen d-flex flex-column ga-4">
-    <p class="text-body-2 text-medium-emphasis mb-0">
-      On wider screens, collapsed navigation remains available as a rail. Phone layouts close the drawer and keep primary navigation in the bottom bar.
-    </p>
-
-    <v-switch
-      v-model="drawerDefaultOpenModel"
-      color="primary"
-      inset
-      hide-details="auto"
-      label="Start with expanded navigation on wider screens"
-    />
-  </section>
+  <v-card>
+    <v-list lines="three">
+      <v-list-item
+        title="Start with expanded navigation on wider screens"
+        subtitle="On wider screens, collapsed navigation remains available as a rail. Phone layouts close the drawer and keep primary navigation in the bottom bar."
+      >
+        <template #append>
+          <v-switch
+            v-model="drawerDefaultOpenModel"
+            aria-label="Start with expanded navigation on wider screens"
+          />
+        </template>
+      </v-list-item>
+    </v-list>
+  </v-card>
 </template>
-
-<style scoped>
-.settings-general-screen :deep(.v-switch) {
-  min-height: 48px;
-}
-</style>

package/skills/jskit/references/patterns/shell/application-shell/example/src/pages/home/settings.vue

@@ -1,90 +1,33 @@
 <script setup>
+import { computed } from "vue";
+import { RouterView, useRoute } from "vue-router";
+import ShellListDetail from "@jskit-ai/shell-web/client/components/ShellListDetail";
 import ShellOutlet from "@jskit-ai/shell-web/client/components/ShellOutlet";
-import { RouterView } from "vue-router";
-</script>
-
-<template>
-  <section class="settings-shell d-flex flex-column ga-4">
-    <v-sheet rounded="lg" border class="settings-shell__panel">
-      <div class="settings-shell__body">
-        <nav class="settings-shell__nav" aria-label="Home settings sections">
-          <v-list nav density="compact" rounded="lg">
-            <ShellOutlet target="home-settings:primary-menu" />
-          </v-list>
-        </nav>
-
-        <main class="settings-shell__content">
-          <RouterView />
-        </main>
-      </div>
-    </v-sheet>
-  </section>
-</template>
-
-<style scoped>
-.settings-shell {
-  --settings-shell-panel-padding: 1rem;
-}
-
-.settings-shell__panel {
-  overflow: hidden;
-}
-
-.settings-shell__body {
-  display: grid;
-  gap: 1rem;
-  grid-template-columns: minmax(12rem, 16rem) minmax(0, 1fr);
-  padding: var(--settings-shell-panel-padding);
-}
-
-.settings-shell__content {
-  border-left: 1px solid rgba(var(--v-theme-on-surface), 0.18);
-  min-width: 0;
-  padding-left: 1rem;
-}
-
-.settings-shell__nav :deep(.v-list) {
-  padding: 0.35rem;
-}
-
-.settings-shell__nav :deep(.v-list-item) {
-  min-height: 48px;
-  padding-inline: 0.6rem 0.7rem;
-}
 
-.settings-shell__nav :deep(.v-list-item__prepend) {
-  margin-inline-end: 0;
-}
-
-.settings-shell__nav :deep(.v-list-item__spacer) {
-  min-width: 0.5rem;
-  width: 0.5rem;
-}
-
-.settings-shell__nav :deep(.v-list-item-title) {
-  line-height: 1.2;
-}
-
-@media (max-width: 960px) {
-  .settings-shell__body {
-    grid-template-columns: 1fr;
-  }
-
-  .settings-shell__nav :deep(.v-list) {
-    display: flex;
-    gap: 0.25rem;
-    overflow-x: auto;
-    scrollbar-width: thin;
+definePage({
+  meta: {
+    jskit: {
+      title: "Settings"
+    }
   }
+});
 
-  .settings-shell__nav :deep(.v-list-item) {
-    flex: 0 0 auto;
-    min-height: 48px;
-  }
+const route = useRoute();
+// The section list shows beside the open section on wide windows, and on its own at /home/settings.
+const detailOpen = computed(() => !/\/settings\/?$/u.test(route.path));
+</script>
 
-  .settings-shell__content {
-    border-left: 0;
-    padding-left: 0;
-  }
-}
-</style>
+<template>
+  <ShellListDetail :detail-open="detailOpen">
+    <template #list>
+      <nav aria-label="Home settings sections">
+        <v-list nav>
+          <ShellOutlet target="home-settings:primary-menu" />
+        </v-list>
+      </nav>
+    </template>
+    <template #detail>
+      <RouterView />
+    </template>
+  </ShellListDetail>
+</template>

package/skills/jskit/references/patterns/shell/application-shell/example/src/views/NotFound.vue

@@ -0,0 +1,15 @@
+<script setup>
+import ShellLayout from "@/components/ShellLayout.vue";
+
+const message = "The page you requested does not exist.";
+</script>
+
+<template>
+  <!-- The shell's top app bar carries the title, and its navigation leads back into the app. -->
+  <ShellLayout title="Not Found" subtitle="">
+    <section class="d-flex flex-column align-center text-center on-surface-variant py-16">
+      <v-icon icon="$searchOff" size="48" />
+      <p class="text-body-large mt-4 mb-0">{{ message }}</p>
+    </section>
+  </ShellLayout>
+</template>

package/skills/jskit/references/patterns/ui/page-and-placement/example/src/components/SyncStatusElement.vue

@@ -1,7 +1,7 @@
 <template>
   <div class="sync-status" role="status" aria-label="Catalogue synchronized">
-    <v-icon icon="mdi-cloud-check-outline" size="small" aria-hidden="true" />
-    <span class="text-body-2">Synced</span>
+    <v-icon icon="$cloudDone" size="small" aria-hidden="true" />
+    <span class="text-body-medium">Synced</span>
   </div>
 </template>
 

package/skills/jskit/references/patterns/ui/page-and-placement/example/src/pages/home/reports/activity.vue

@@ -1,6 +1,6 @@
 <template>
   <section>
-    <p class="text-body-1 text-medium-emphasis mb-0">
+    <p class="text-body-large on-surface-variant mb-0">
       Recent catalogue changes appear here.
     </p>
   </section>

package/skills/jskit/references/patterns/ui/page-and-placement/example/src/pages/home/reports/overview.vue

@@ -1,6 +1,6 @@
 <template>
   <section>
-    <p class="text-body-1 text-medium-emphasis mb-0">
+    <p class="text-body-large on-surface-variant mb-0">
       Your reading and catalogue summary appears here.
     </p>
   </section>

package/skills/jskit/references/patterns/ui/page-and-placement/example/src/pages/home/reports.vue

@@ -1,19 +1,22 @@
 <script setup>
 import ShellOutlet from "@jskit-ai/shell-web/client/components/ShellOutlet";
 import { RouterView } from "vue-router";
+
+// A main menu destination whose tabs are its own sub-views: the app bar shows its title and no Up arrow.
+definePage({ meta: { jskit: { title: "Reports" } } });
 </script>
 
 <template>
   <section class="reports-section d-flex flex-column ga-4">
     <nav aria-label="Report sections">
-      <v-tabs density="comfortable">
+      <v-tabs>
         <ShellOutlet target="reports:section-nav" />
       </v-tabs>
     </nav>
 
-    <main class="reports-section__content">
+    <div class="reports-section__content">
       <RouterView />
-    </main>
+    </div>
   </section>
 </template>
 

package/skills/jskit/references/patterns/ui/page-and-placement/example/src/placement.js

@@ -11,7 +11,7 @@ addPlacement({
   order: 120,
   props: {
     label: "Reports",
-    icon: "mdi-chart-box-outline",
+    icon: "$assignment",
     surface: "home",
     scopedSuffix: "/reports",
     unscopedSuffix: "/reports"

package/skills/jskit/references/patterns/users/account-settings/example/src/components/account/settings/AccountSettingsNotificationsSection.vue

@@ -10,7 +10,7 @@ const notifications = props.runtime.notifications;
 </script>
 
 <template>
-  <v-sheet rounded="lg" border class="account-settings-section">
+  <div class="account-settings-section">
     <div class="account-settings-section__body">
       <v-form @submit.prevent="notifications.submit" novalidate>
         <v-switch
@@ -47,7 +47,7 @@ const notifications = props.runtime.notifications;
         </v-btn>
       </v-form>
     </div>
-  </v-sheet>
+  </div>
 </template>
 
 <style scoped>
@@ -58,10 +58,4 @@ const notifications = props.runtime.notifications;
 .account-settings-section__body {
   padding: 1rem;
 }
-
-@media (max-width: 640px) {
-  .account-settings-section__body :deep(.v-btn) {
-    min-height: 48px;
-  }
-}
 </style>

package/skills/jskit/references/patterns/users/account-settings/example/src/components/account/settings/AccountSettingsPreferencesSection.vue

@@ -10,7 +10,7 @@ const preferences = props.runtime.preferences;
 </script>
 
 <template>
-  <v-sheet rounded="lg" border class="account-settings-section">
+  <div class="account-settings-section">
     <div class="account-settings-section__body">
       <v-form @submit.prevent="preferences.submit" novalidate>
         <v-row>
@@ -117,7 +117,7 @@ const preferences = props.runtime.preferences;
         </v-btn>
       </v-form>
     </div>
-  </v-sheet>
+  </div>
 </template>
 
 <style scoped>
@@ -128,10 +128,4 @@ const preferences = props.runtime.preferences;
 .account-settings-section__body {
   padding: 1rem;
 }
-
-@media (max-width: 640px) {
-  .account-settings-section__body :deep(.v-btn) {
-    min-height: 48px;
-  }
-}
 </style>

package/skills/jskit/references/patterns/users/account-settings/example/src/components/account/settings/AccountSettingsProfileSection.vue

@@ -10,16 +10,16 @@ const profile = props.runtime.profile;
 </script>
 
 <template>
-  <v-sheet rounded="lg" border class="account-settings-section">
+  <div class="account-settings-section">
     <div class="account-settings-section__body">
       <v-form @submit.prevent="profile.submit" novalidate>
         <v-row class="mb-2">
           <v-col cols="12" md="4" class="d-flex flex-column align-center justify-center">
             <v-avatar :size="profile.avatar.size" color="surface-variant" rounded="circle" class="mb-3">
               <v-img v-if="profile.avatar.effectiveUrl" :src="profile.avatar.effectiveUrl" cover />
-              <span v-else class="text-h6">{{ profile.initials.value }}</span>
+              <span v-else class="text-title-large">{{ profile.initials.value }}</span>
             </v-avatar>
-            <div class="text-caption text-medium-emphasis">Preview size: {{ profile.avatar.size }} px</div>
+            <div class="text-body-small on-surface-variant">Preview size: {{ profile.avatar.size }} px</div>
           </v-col>
 
           <v-col cols="12" md="8">
@@ -44,7 +44,7 @@ const profile = props.runtime.profile;
               </v-btn>
             </div>
 
-            <div v-if="profile.selectedAvatarFileName.value" class="text-caption text-medium-emphasis mb-2">
+            <div v-if="profile.selectedAvatarFileName.value" class="text-body-small on-surface-variant mb-2">
               Selected file: {{ profile.selectedAvatarFileName.value }}
             </div>
           </v-col>
@@ -86,7 +86,7 @@ const profile = props.runtime.profile;
         </v-btn>
       </v-form>
     </div>
-  </v-sheet>
+  </div>
 </template>
 
 <style scoped>
@@ -97,10 +97,4 @@ const profile = props.runtime.profile;
 .account-settings-section__body {
   padding: 1rem;
 }
-
-@media (max-width: 640px) {
-  .account-settings-section__body :deep(.v-btn) {
-    min-height: 48px;
-  }
-}
 </style>

package/skills/jskit/references/patterns/users/account-settings/example/src/components/account/settings/AccountSettingsSignInMethodsSection.vue

@@ -10,7 +10,7 @@ const signInMethods = props.runtime.signInMethods;
 </script>
 
 <template>
-  <v-sheet rounded="lg" border class="account-settings-section">
+  <div class="account-settings-section">
     <v-list lines="two" class="py-0">
       <v-list-item
         v-for="method in signInMethods.methods.value"
@@ -43,11 +43,11 @@ const signInMethods = props.runtime.signInMethods;
     </v-list>
     <p
       v-if="signInMethods.methods.value.some((method) => method.linked && !method.canUnlink)"
-      class="account-settings-section__hint text-body-2 text-medium-emphasis mb-0"
+      class="account-settings-section__hint text-body-medium on-surface-variant mb-0"
     >
       Your only sign-in method can't be unlinked. Set a password or link another provider first.
     </p>
-  </v-sheet>
+  </div>
 </template>
 
 <style scoped>
@@ -58,10 +58,4 @@ const signInMethods = props.runtime.signInMethods;
 .account-settings-section__hint {
   padding: 0 1rem 1rem;
 }
-
-@media (max-width: 640px) {
-  .account-settings-section :deep(.v-btn) {
-    min-height: 48px;
-  }
-}
 </style>

package/skills/jskit/references/patterns/users/account-settings/example/src/pages/account/index.vue

@@ -3,6 +3,13 @@
   "meta": {
     "guard": {
       "policy": "authenticated"
+    },
+    "jskit": {
+      "title": "Account settings",
+      "parent": {
+        "surface": "home",
+        "path": "/"
+      }
     }
   }
 }

package/skills/jskit/references/patterns/users/user-administration-server/example/packages/users/package.json

@@ -10,8 +10,8 @@
     "./shared": "./src/shared/index.js"
   },
   "dependencies": {
-    "@jskit-ai/crud-core": "0.2.10",
-    "@jskit-ai/resource-crud-core": "0.1.200"
+    "@jskit-ai/crud-core": "0.2.11",
+    "@jskit-ai/resource-crud-core": "0.1.201"
   },
   "jskit": {
     "kind": "runtime",

package/skills/jskit/references/patterns/users/user-administration-server/example/packages/users-workspace/package.json

@@ -10,9 +10,9 @@
     "./shared": "./src/shared/index.js"
   },
   "dependencies": {
-    "@jskit-ai/crud-core": "0.2.10",
-    "@jskit-ai/resource-crud-core": "0.1.200",
-    "@jskit-ai/workspaces-core": "0.2.11"
+    "@jskit-ai/crud-core": "0.2.11",
+    "@jskit-ai/resource-crud-core": "0.1.201",
+    "@jskit-ai/workspaces-core": "0.2.12"
   },
   "jskit": {
     "kind": "runtime",

package/skills/jskit/references/patterns/workspaces/workspace-surfaces/example/packages/main/src/client/components/AccountPendingInvitesCue.vue

@@ -1,7 +1,6 @@
 <script setup>
 import { computed } from "vue";
 import { useRoute } from "vue-router";
-import { mdiEmailAlertOutline } from "@mdi/js";
 import { appendQueryString } from "@jskit-ai/kernel/shared/support";
 import {
   useWebPlacementContext,
@@ -96,7 +95,7 @@ const resolvedNavigationTarget = computed(() =>
       :href="resolvedNavigationTarget.sameOrigin ? undefined : resolvedNavigationTarget.href"
       variant="tonal"
       color="warning"
-      :prepend-icon="mdiEmailAlertOutline"
+      prepend-icon="$markEmailUnread"
       size="small"
       class="text-none"
     >

package/skills/jskit/references/patterns/workspaces/workspace-surfaces/example/src/components/WorkspaceNotFoundCard.vue

@@ -1,5 +1,4 @@
 <script setup>
-import { mdiAlertCircleOutline } from "@mdi/js";
 import { computed } from "vue";
 
 const props = defineProps({
@@ -18,13 +17,13 @@ const normalizedMessage = computed(() => String(props.message || "").trim() || "
 </script>
 
 <template>
-  <v-sheet rounded="lg" border class="workspace-unavailable-panel">
+  <div class="workspace-unavailable-panel">
     <div class="workspace-unavailable-panel__status">
-      <v-icon :icon="mdiAlertCircleOutline" color="error" />
-      <p class="text-body-2 text-medium-emphasis mb-0">{{ normalizedSurfaceLabel }} surface unavailable.</p>
+      <v-icon icon="$error" color="error" />
+      <p class="text-body-medium on-surface-variant mb-0">{{ normalizedSurfaceLabel }} surface unavailable.</p>
     </div>
-    <p class="text-body-2 text-medium-emphasis mb-0">{{ normalizedMessage }}</p>
-  </v-sheet>
+    <p class="text-body-medium on-surface-variant mb-0">{{ normalizedMessage }}</p>
+  </div>
 </template>
 
 <style scoped>

package/skills/jskit/references/patterns/workspaces/workspace-surfaces/example/src/pages/admin/workspace/settings/index.vue

@@ -1,15 +1,8 @@
 <template>
-  <section class="workspace-settings-landing">
-    <v-sheet rounded="lg" border class="workspace-settings-landing__panel">
-      <p class="text-body-2 text-medium-emphasis mb-0">
-        This app has no workspace-level settings configured.
-      </p>
-    </v-sheet>
+  <section class="on-surface-variant text-center py-12">
+    <v-icon icon="$settings" size="48" />
+    <p class="text-body-large mt-4 mb-0">
+      This app has no workspace-level settings configured.
+    </p>
   </section>
 </template>
-
-<style scoped>
-.workspace-settings-landing__panel {
-  padding: 1rem;
-}
-</style>