@jskit-ai/agent-docs 0.1.148 → 0.1.150

package/skills/jskit/references/patterns/auth/auth-surface/PATTERN.md

@@ -0,0 +1,90 @@
+---
+id: auth/auth-surface
+title: Authentication surface
+summary: Compose JSKIT authentication routes, views, profile controls, and public surface configuration without generated source.
+keywords: account, auth, login, logout, password, placement, profile, reset, surface
+requires: @jskit-ai/auth-core, @jskit-ai/auth-web, @jskit-ai/shell-web
+---
+
+# Authentication surface
+
+## Use when
+
+Use this pattern when an application needs browser login, sign-out, password
+reset, and authenticated profile controls through JSKIT's auth runtime.
+
+## Do not use when
+
+Do not use this pattern for an API-only service, an application that delegates
+all authentication UI to another product, or a second auth stack beside JSKIT.
+
+## Product decisions
+
+Choose the auth provider, permitted login methods, public routes, post-login
+destination, account language, and which profile actions belong in the shell.
+Those choices must be known before adapting the example.
+
+## Framework APIs
+
+Use the views, auth guard, HTTP client integration, sign-out runtime, providers,
+and Playwright auth helper exported by `@jskit-ai/auth-web`. Use auth policies
+from `@jskit-ai/auth-core` for server authorization.
+
+For a managed preview, copy the app-owned `tools/preview-identity` executable
+and declare it under `#### Preview identity` in the project's web-presented
+Vibe64 `Outputs` target with protocol `vibe64.preview-identity.command.v1`.
+Declare `AUTH_DEV_BYPASS_ENABLED` as its Enabled environment and
+`AUTH_DEV_BYPASS_SECRET` as its Secret environment so the preview host supplies
+fresh output-run-scoped values; users do not set those values by hand. JSKIT
+owns this executable/library pattern, Vibe64 owns the `Outputs` grammar and
+runtime behavior, and Genesis only composes that consumer-owned section as
+opaque text. The executable calls the exported managed-preview identity library
+directly; it does not require a JSKIT CLI.
+
+Choose local-auth storage through the installed capability provider. A
+database-backed application installs `@jskit-ai/auth-provider-local-db-core`,
+which provides `auth.local.backend`; no environment switch selects it. When no
+backend package provides that capability, local auth deliberately uses its file
+store. Managed preview selectors name an existing auth-backend user whose
+application profile already exists; preview identity never creates or projects
+a user as a side effect.
+
+## Invariants
+
+- Credentials and provider secrets come from environment values.
+- Auth backend selection comes from the installed provider graph, not an
+  `AUTH_LOCAL_BACKEND` environment value.
+- The selected auth backend and the storage containing the application's users
+  agree before registration, login, session bootstrap, or preview identity is
+  exercised.
+- Public auth routes do not require an existing session.
+- Protected routes use the framework auth policy rather than page-local checks.
+- Login, sign-out, and reset views use the public auth components/composables.
+- Profile placements are conditional on the current authenticated state.
+- Transient mutation failures use the application toast; initial load failures
+  remain in the affected surface.
+
+## Example files
+
+`example/` contains concrete route wrappers, editable view wrappers, and the
+client runtime helpers needed by an authentication surface. It also contains
+the optional app-owned managed-preview identity executable. Compose their
+surface and placement declarations into the application's ordinary config and
+placement files.
+
+## Variation points
+
+Change provider, routes, labels, page wrappers, permitted login methods, profile
+placements, and post-auth destinations while retaining the runtime contracts.
+
+## Verification
+
+Exercise failed and successful login, sign-out, reset, protected navigation,
+keyboard interaction, warm-cache return navigation, and browser refresh.
+
+## Avoid
+
+- storing credentials in source
+- copying auth repositories or session mechanics into the app
+- redirect loops between public and protected surfaces
+- generator commands, mutation metadata, or setup receipts

package/skills/jskit/references/patterns/auth/auth-surface/example/src/pages/auth/login.vue

@@ -0,0 +1,17 @@
+<route lang="json">
+{
+  "meta": {
+    "guard": {
+      "policy": "public"
+    }
+  }
+}
+</route>
+
+<script setup>
+import DefaultLoginView from "@jskit-ai/auth-web/client/views/DefaultLoginView";
+</script>
+
+<template>
+  <DefaultLoginView />
+</template>

package/skills/jskit/references/patterns/auth/auth-surface/example/src/pages/auth/reset-password.vue

@@ -0,0 +1,17 @@
+<route lang="json">
+{
+  "meta": {
+    "guard": {
+      "policy": "public"
+    }
+  }
+}
+</route>
+
+<script setup>
+import DefaultResetPasswordView from "@jskit-ai/auth-web/client/views/DefaultResetPasswordView";
+</script>
+
+<template>
+  <DefaultResetPasswordView />
+</template>

package/skills/jskit/references/patterns/auth/auth-surface/example/src/pages/auth/signout.vue

@@ -0,0 +1,17 @@
+<route lang="json">
+{
+  "meta": {
+    "guard": {
+      "policy": "public"
+    }
+  }
+}
+</route>
+
+<script setup>
+import DefaultSignOutView from "@jskit-ai/auth-web/client/views/DefaultSignOutView";
+</script>
+
+<template>
+  <DefaultSignOutView />
+</template>

package/skills/jskit/references/patterns/auth/auth-surface/example/src/runtime/authGuardRuntime.js

@@ -0,0 +1,7 @@
+export {
+  createAuthGuardRuntime,
+  isAuthGuardRuntime,
+  initializeAuthGuardRuntime,
+  refreshAuthGuardState,
+  getAuthGuardState
+} from "@jskit-ai/auth-web/client/runtime/authGuardRuntime";

package/skills/jskit/references/patterns/auth/auth-surface/example/src/runtime/authHttpClient.js

@@ -0,0 +1 @@
+export { authHttpRequest, clearAuthCsrfTokenCache } from "@jskit-ai/auth-web/client/runtime/authHttpClient";

package/skills/jskit/references/patterns/auth/auth-surface/example/src/runtime/useSignOut.js

@@ -0,0 +1 @@
+export { useSignOut, createSignOutAction, performSignOutRequest } from "@jskit-ai/auth-web/client/runtime/useSignOut";

package/skills/jskit/references/patterns/auth/auth-surface/example/src/views/auth/LoginView.vue

@@ -0,0 +1,7 @@
+<script setup>
+import DefaultLoginView from "@jskit-ai/auth-web/client/views/DefaultLoginView";
+</script>
+
+<template>
+  <DefaultLoginView />
+</template>

package/skills/jskit/references/patterns/auth/auth-surface/example/src/views/auth/ResetPasswordView.vue

@@ -0,0 +1,7 @@
+<script setup>
+import DefaultResetPasswordView from "@jskit-ai/auth-web/client/views/DefaultResetPasswordView";
+</script>
+
+<template>
+  <DefaultResetPasswordView />
+</template>

package/skills/jskit/references/patterns/auth/auth-surface/example/src/views/auth/SignOutView.vue

@@ -0,0 +1,7 @@
+<script setup>
+import DefaultSignOutView from "@jskit-ai/auth-web/client/views/DefaultSignOutView";
+</script>
+
+<template>
+  <DefaultSignOutView />
+</template>

package/skills/jskit/references/patterns/auth/auth-surface/example/tools/preview-identity

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { runManagedPreviewIdentityCommand } from "@jskit-ai/auth-web/server/managedPreviewIdentity";
+
+process.exitCode = await runManagedPreviewIdentityCommand();

package/skills/jskit/references/patterns/auth/supabase-auth/PATTERN.md

@@ -0,0 +1,67 @@
+---
+id: auth/supabase-auth
+title: Supabase authentication
+summary: Add Supabase authentication through normal npm composition, explicit environment values, and app-owned auth policy.
+keywords: auth, authentication, oauth, sessions, supabase
+requires: @jskit-ai/auth-provider-supabase-core
+---
+
+# Supabase authentication
+
+## Use when
+
+Use this pattern when the product deliberately chooses Supabase as its identity
+provider. Install the runtime package normally and configure the application
+environment and visible OAuth providers explicitly.
+
+## Do not use when
+
+Do not use this pattern for local credential storage, a custom identity
+provider, or an application whose authentication decision is still open.
+
+## Product decisions
+
+Decide the public application URL, allowed sign-in methods, visible OAuth
+providers, callback URLs, account-linking policy, and where deployment secrets
+live. Obtain the project URL and publishable key from the selected Supabase
+project.
+
+## Invariants
+
+- Secrets and environment-specific values stay outside committed source.
+- The application owns auth/profile and OAuth visibility policy.
+- The installed runtime package supplies the provider implementation and its
+  npm dependency closure.
+- No setup questionnaire or source mutation is required.
+
+## Framework APIs
+
+Use `@jskit-ai/auth-provider-supabase-core` for the provider and
+`@jskit-ai/auth-core` policy contracts. Configure `config.auth` through the
+application's ordinary server configuration.
+
+## Example files
+
+`example/package.json` declares the selected provider. `example/.env.example`
+names required environment inputs without credentials. `example/config/server.js`
+shows the app-owned profile and OAuth visibility decisions.
+
+## Variation points
+
+Change the OAuth provider list, default provider, profile projection mode,
+public URL, and deployment secret source. Compose account/profile packages only
+when the product needs their behavior.
+
+## Verification
+
+- Start the application with missing values and confirm concise diagnostics.
+- Complete sign-in, callback, refresh, sign-out, and rejected-session cases.
+- Verify allowed redirect origins and negative cross-origin behavior.
+- Run the application auth and browser tests.
+
+## Avoid
+
+- committing provider keys
+- silently selecting Supabase for the user
+- generated configuration fragments with hidden overwrite rules
+- setup receipts, provenance, replay logs, or questionnaire answers

package/skills/jskit/references/patterns/auth/supabase-auth/example/.env.example

@@ -0,0 +1,4 @@
+AUTH_PROVIDER=supabase
+AUTH_SUPABASE_URL=https://your-project.supabase.co
+AUTH_SUPABASE_PUBLISHABLE_KEY=replace-me
+APP_PUBLIC_URL=http://localhost:5173

package/skills/jskit/references/patterns/auth/supabase-auth/example/config/server.js

@@ -0,0 +1,11 @@
+const config = {
+  auth: {
+    profileMode: "provider",
+    oauth: {
+      providers: [],
+      defaultProvider: ""
+    }
+  }
+};
+
+export default config;

package/skills/jskit/references/patterns/auth/supabase-auth/example/package.json

@@ -0,0 +1,7 @@
+{
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "@jskit-ai/auth-provider-supabase-core": "0.1.175"
+  }
+}

package/skills/jskit/references/patterns/console/console-surface/PATTERN.md

@@ -0,0 +1,58 @@
+---
+id: console/console-surface
+title: Owner console surface
+summary: Add a protected administration surface, settings shell, and semantic navigation through JSKIT console and shell APIs.
+keywords: admin, console, navigation, owner, placement, settings, surface
+requires: @jskit-ai/console-core, @jskit-ai/console-web, @jskit-ai/shell-web
+---
+
+# Owner console surface
+
+## Use when
+
+Use this pattern for a separate owner-only or operator-only application surface.
+
+## Do not use when
+
+Do not create a separate console merely for one settings page or when normal
+workspace roles already express the required access boundary.
+
+## Product decisions
+
+Choose who can enter the console, its route and label, which settings sections
+it owns, and how authorized users switch to and from it.
+
+## Framework APIs
+
+Use `@jskit-ai/console-core` for console capabilities,
+`@jskit-ai/console-web` for the web provider, and JSKIT shell surface,
+placement, and topology APIs for application composition.
+
+## Invariants
+
+- Server policy enforces console access before application actions run.
+- The surface definition and route pages use the same surface id.
+- The profile switch is visible only to authorized authenticated users.
+- Settings navigation uses semantic placements and responsive topology.
+- Loading screens use skeletons and do not shift the surrounding shell.
+
+## Example files
+
+`example/` contains concrete console root, landing, and settings routes. Adapt
+them together with the surface policy and placement examples described here.
+
+## Variation points
+
+Change the surface id, access policy, settings hierarchy, routes, labels, icons,
+and switch placement to fit the product's administration model.
+
+## Verification
+
+Test forbidden and authorized entry, switching between surfaces, direct route
+loads, compact navigation, settings navigation, and production build output.
+
+## Avoid
+
+- treating a hidden navigation item as authorization
+- sharing normal-user pages merely by changing their route prefix
+- generator ownership or appended source fragments

package/skills/jskit/references/patterns/console/console-surface/example/src/pages/console/index.vue

@@ -0,0 +1,62 @@
+<template>
+  <section class="console-home-screen d-flex flex-column ga-4">
+    <header class="console-home-screen__header">
+      <div>
+        <p class="text-overline text-medium-emphasis mb-1">Console</p>
+        <h1 class="console-home-screen__title">Operations Console</h1>
+        <p class="text-body-2 text-medium-emphasis mb-0">Operator tools, scripts, and diagnostics.</p>
+      </div>
+      <v-btn color="primary" variant="flat" to="/home">Back to home</v-btn>
+    </header>
+
+    <v-sheet rounded="lg" border class="console-home-screen__panel">
+      <div class="console-home-screen__status-row">
+        <v-chip color="secondary" variant="tonal" label>Route: /console</v-chip>
+        <v-chip color="info" variant="tonal" label>Surface status: enabled</v-chip>
+      </div>
+      <p class="text-body-2 text-medium-emphasis mb-0">
+        Use this surface for operator actions and technical insights that should stay out of the end-user app.
+      </p>
+    </v-sheet>
+  </section>
+</template>
+
+<style scoped>
+.console-home-screen__header {
+  align-items: flex-start;
+  display: flex;
+  gap: 1rem;
+  justify-content: space-between;
+}
+
+.console-home-screen__title {
+  font-size: clamp(1.5rem, 2.5vw, 2.25rem);
+  font-weight: 700;
+  letter-spacing: -0.03em;
+  line-height: 1.1;
+  margin: 0 0 0.4rem;
+}
+
+.console-home-screen__panel {
+  display: grid;
+  gap: 1rem;
+  padding: 1rem;
+}
+
+.console-home-screen__status-row {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+}
+
+@media (max-width: 640px) {
+  .console-home-screen__header {
+    flex-direction: column;
+  }
+
+  .console-home-screen__header :deep(.v-btn) {
+    min-height: 48px;
+    width: 100%;
+  }
+}
+</style>

package/skills/jskit/references/patterns/console/console-surface/example/src/pages/console/settings/index.vue

@@ -0,0 +1,17 @@
+<template>
+  <section class="console-settings-empty">
+    <h2 class="text-h6 mb-2">No console settings yet</h2>
+    <p class="text-body-2 text-medium-emphasis mb-0">
+      Console settings sections will appear here when installed.
+    </p>
+  </section>
+</template>
+
+<style scoped>
+.console-settings-empty {
+  margin-inline: auto;
+  max-width: 34rem;
+  padding: 2rem 1.25rem;
+  text-align: center;
+}
+</style>

package/skills/jskit/references/patterns/console/console-surface/example/src/pages/console/settings.vue

@@ -0,0 +1,95 @@
+<script setup>
+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">
+    <header>
+      <p class="text-overline text-medium-emphasis mb-1">Console</p>
+      <h1 class="settings-shell__title">Console settings</h1>
+      <p class="text-body-2 text-medium-emphasis mb-0">Global configuration and reference data for the whole app.</p>
+    </header>
+
+    <v-sheet rounded="lg" border class="settings-shell__panel">
+      <nav class="settings-shell__nav" aria-label="Console settings sections">
+        <v-list nav density="compact" class="settings-shell__nav-list">
+          <ShellOutlet target="console-settings:primary-menu" />
+        </v-list>
+      </nav>
+      <main class="settings-shell__content">
+        <RouterView />
+      </main>
+    </v-sheet>
+  </section>
+</template>
+
+<style scoped>
+.settings-shell__title {
+  font-size: clamp(1.35rem, 2vw, 1.85rem);
+  font-weight: 650;
+  letter-spacing: -0.02em;
+  line-height: 1.15;
+  margin: 0 0 0.35rem;
+}
+
+.settings-shell__panel {
+  display: grid;
+  gap: 1rem;
+  grid-template-columns: minmax(12rem, 16rem) minmax(0, 1fr);
+  padding: 1rem;
+}
+
+.settings-shell__nav-list {
+  padding: 0.35rem;
+}
+
+.settings-shell__nav-list :deep(.v-list-item) {
+  min-height: 48px;
+  padding-inline: 0.6rem 0.7rem;
+}
+
+.settings-shell__nav-list :deep(.v-list-item__prepend) {
+  margin-inline-end: 0;
+}
+
+.settings-shell__nav-list :deep(.v-list-item__spacer) {
+  min-width: 0.5rem;
+  width: 0.5rem;
+}
+
+.settings-shell__nav-list :deep(.v-list-item-title) {
+  line-height: 1.2;
+}
+
+.settings-shell__content {
+  border-left: 1px solid rgba(var(--v-theme-on-surface), 0.18);
+  min-width: 0;
+  padding-left: 1rem;
+}
+
+@media (max-width: 960px) {
+  .settings-shell__panel {
+    grid-template-columns: 1fr;
+  }
+
+  .settings-shell__nav {
+    overflow-x: auto;
+  }
+
+  .settings-shell__nav-list {
+    display: flex;
+    gap: 0.25rem;
+    min-width: max-content;
+  }
+
+  .settings-shell__nav-list :deep(.v-list-item) {
+    min-height: 48px;
+  }
+
+  .settings-shell__content {
+    border-left: 0;
+    padding-left: 0;
+  }
+}
+</style>

package/skills/jskit/references/patterns/console/console-surface/example/src/pages/console.vue

@@ -0,0 +1,20 @@
+<route lang="json">
+{
+  "meta": {
+    "jskit": {
+      "surface": "console"
+    }
+  }
+}
+</route>
+
+<script setup>
+import ShellLayout from "@/components/ShellLayout.vue";
+import { RouterView } from "vue-router";
+</script>
+
+<template>
+  <ShellLayout title="" subtitle="">
+    <RouterView />
+  </ShellLayout>
+</template>

package/skills/jskit/references/patterns/crud/crud-screen-set/PATTERN.md

@@ -0,0 +1,88 @@
+---
+id: crud/crud-screen-set
+title: CRUD list, view, create, and edit screens
+summary: Build a routed CRUD user interface as thin application pages over JSKIT's shared screen components and composables.
+keywords: actions, add, crud, delete, edit, filters, list, material, routes, view, vue
+requires: @jskit-ai/http-web, @jskit-ai/resource-crud-core
+---
+
+# CRUD list, view, create, and edit screens
+
+## Use when
+
+Use this pattern when a shared CRUD resource should have normal list, detail,
+create, edit, and delete routes. The shared JSKIT screens own responsive chrome,
+loading skeletons, load-error retry states, mutation feedback, route-aware data
+operations, and common extensions. Application pages supply product copy,
+fields, routes, and optional actions.
+
+## Do not use when
+
+Do not use this pattern for a one-off command, an embedded read-only value, or a
+domain whose operations are not CRUD. Do not replace the shared screens simply
+to add filters, row actions, bulk actions, permission gating, includes, or
+supporting detail content; those are public extension seams.
+
+## Product decisions
+
+Decide which operations exist, the route hierarchy, record title, visible
+fields, create/edit participation, destructive confirmation language, access
+surface, filters, and domain actions. The resource contract and product intent
+are authoritative. Do not derive these decisions from a live table or a field
+questionnaire.
+
+## Invariants
+
+- Route pages stay thin and use `useCrudListScreen()`, `useCrudViewScreen()`,
+  or `useCrudAddEditScreen()`.
+- Transport and validators come from the shared resource contract.
+- Initial visible loading uses structure-matching skeletons; pending buttons use
+  stable disabled labels, never spinners.
+- Resource-load errors stay inside the screen with retry. Command success and
+  failure use JSKIT's shared toast/snackbar feedback path.
+- URLs are route templates or route objects resolved through the screen runtime.
+- Product field components are ordinary application source.
+- Query keys and placement sources describe the resource, not an authoring tool.
+- No generated-file markers, overwrite contracts, receipts, or provenance remain.
+
+## Framework APIs
+
+Use `CrudListScreen`, `CrudViewScreen`, `CrudAddEditScreen`, and
+`CrudDeleteAction` with their matching composables from `@jskit-ai/http-web`.
+Use `defineCrudListFilters()`, `defineCrudListRowActions()`, and
+`defineCrudListBulkActions()` for optional list extensions. The resource comes
+from `defineCrudResource()` in `@jskit-ai/resource-crud-core`.
+
+## Example files
+
+`example/books/` contains concrete list, view, new, and edit pages for the
+owner-scoped `bookResource` pattern. `BookFormFields.vue` and `formFields.js`
+show the small product-owned form seam. `listExtensions.js` makes optional
+filters and actions explicit without adding empty screen machinery elsewhere.
+
+## Variation points
+
+Change routes, labels, visible fields, field components, filters, query params,
+realtime events, delete availability, and action definitions. Use the screen
+slots for domain-specific content. Use a lower-level request composable only
+when the wire contract genuinely is not CRUD.
+
+## Verification
+
+- Mount each route with a representative resource response.
+- Verify skeleton, empty, success, local load-error, and retry states.
+- Verify create, edit, validation failure, delete confirmation, and navigation.
+- Verify filters and actions when declared.
+- Exercise compact, medium, and expanded widths with Playwright.
+- Confirm keyboard access, 48 CSS-pixel compact targets, no horizontal overflow,
+  and toast-based mutation feedback.
+
+## Avoid
+
+- route-local `fetch()` or duplicated request serializers
+- copying shared screen chrome into every route
+- spinner or circular-progress loading states
+- transient in-page command-error banners that push the layout
+- generator-branded CSS classes, cache keys, or placement ids
+- comments or metadata reserving fields for a future authoring command
+- a second source of truth for resource field validation