@jskit-ai/agent-docs 0.1.113 → 0.1.114

package/guide/agent/generators/advanced-cruds.md

@@ -265,8 +265,10 @@ src/pages/w/[workspaceSlug]/admin/contacts/
   new.vue
   [contactId]/index.vue
   [contactId]/edit.vue
-  _components/CrudAddEditForm.vue
-  _components/CrudAddEditFormFields.js
+
+src/components/w/[workspaceSlug]/admin/contacts/
+  CrudAddEditForm.vue
+  CrudAddEditFormFields.js
 
 config/roles.js
 src/placement.js
@@ -454,10 +456,17 @@ src/pages/w/[workspaceSlug]/admin/contacts/
   [contactId]/edit.vue
   listBulkActions.js
   listFilters.js
-  _components/CrudAddEditForm.vue
-  _components/CrudAddEditFormFields.js
+
+src/components/w/[workspaceSlug]/admin/contacts/
+  CrudAddEditForm.vue
+  CrudAddEditFormFields.js
 ```
 
+The shared Vue form lives in the mirrored `src/components/` tree because the
+file router treats every Vue file below `src/pages/` as a route. The normalized
+CRUD target root keeps the helper scoped to the same configured surface and
+route family without exposing another browser route.
+
 ### `index.vue`
 
 This is the list-page container.
@@ -781,7 +790,7 @@ The safe mental model is:
 - use `usePaths().api(...)` when you need a custom scoped API path and the higher-level runtime does not already resolve it for you
 - keep `apiUrlTemplate` path-only and put endpoint query strings in `requestQueryParams`
 
-### `_components/CrudAddEditForm.vue`
+### `src/components/.../CrudAddEditForm.vue`
 
 This is the generated field bridge for the shared add/edit screen.
 
@@ -792,7 +801,7 @@ It owns:
 
 It does **not** own persistence logic or the shared screen chrome. `CrudAddEditScreen` from `users-web` owns the common title, load state, retry action, save/cancel action row, and form surface.
 
-### `_components/CrudAddEditFormFields.js`
+### `src/components/.../CrudAddEditFormFields.js`
 
 This is the generated field-definition module used by `useCrudAddEdit()`.
 
@@ -841,7 +850,7 @@ Use this rule of thumb when deciding where to edit:
 | Add per-row commands to a generated list page | page-local `listRowActions.js`, usually calling `useCommand()`-backed composables | The shared list screen renders action chrome; the page owns explicit mutation behavior |
 | Add non-CRUD display rows to a generated list page | route page `syntheticRows` input | Synthetic rows are presentation rows, not repository records |
 | Change page-specific display behavior | the route pages, generated slots, and app-owned composables | This is presentation |
-| Change form field layout and inputs | `_components/CrudAddEditForm.vue` and `CrudAddEditFormFields.js` | This is the generated form field layer |
+| Change form field layout and inputs | the mirrored `src/components/.../CrudAddEditForm.vue` and `CrudAddEditFormFields.js` | This is the generated non-routed form field layer |
 
 ## How mature CRUDs grow
 

package/guide/agent/generators/crud-generators.md

@@ -458,7 +458,12 @@ That creates the baseline CRUD route tree:
 - `w/[workspaceSlug]/admin/contacts/new.vue`
 - `w/[workspaceSlug]/admin/contacts/[contactId]/index.vue`
 - `w/[workspaceSlug]/admin/contacts/[contactId]/edit.vue`
-- shared `_components` files under the same route root
+- shared form files under the mirrored non-routed
+  `src/components/w/[workspaceSlug]/admin/contacts/` root
+
+The mirrored component root is intentional. The configured file router scans
+Vue files below `src/pages/`, so reusable Vue helpers must stay outside that
+directory or they become browser routes.
 
 Generated list, view, and lookup reads use the resource contract as their
 response authority. They return every field declared for output by default,
@@ -620,7 +625,8 @@ That gives you a normal child route tree:
 - `w/[workspaceSlug]/admin/contacts/[contactId]/addresses/new.vue`
 - `w/[workspaceSlug]/admin/contacts/[contactId]/addresses/[addressId]/index.vue`
 - `w/[workspaceSlug]/admin/contacts/[contactId]/addresses/[addressId]/edit.vue`
-- shared `_components` files under the same route root
+- shared form files under the mirrored non-routed
+  `src/components/w/[workspaceSlug]/admin/contacts/[contactId]/addresses/` root
 
 ### Step 5: remove the generated shell placement by hand
 

package/package.json

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

package/patterns/crud-scaffolding.md

@@ -67,6 +67,7 @@ Rules:
 - 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.
+- Keep generated reusable Vue helpers outside `src/pages/`; the file router inventories every Vue file below that root as a browser route. CRUD form helpers mirror the validated target root under `src/components/`.
 - Permission-gated generated CRUD lists should pass `readEnabled` into `useCrudListScreen(...)` instead of replacing the shared list wrapper.
 - Compact CRUD actions should be reachable without a drawer. Use a mobile-visible primary action or FAB for create flows.
 - Row actions should be declared with `defineCrudListRowActions(...)` in a page-local `listRowActions.js` and passed into `useCrudListScreen(...)`; the shared list screen owns the compact/wide action rendering.

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

@@ -31,6 +31,8 @@ Local functions
 - `resolveBooleanFlagOption(options = {}, optionName = "")`
 - `resolveInternalRouteOption(options = {})`
 - `resolveNoRoleGrantOption(options = {})`
+- `normalizeCrudAccess(value, { strict = false } = {})`
+- `assertCrudAccessCompatibility(access, { surfaceRequiresWorkspace = false, ownershipFilter = "" } = {})`
 - `normalizeRequestedOwnershipFilter(value, { strict = false } = {})`
 - `inferOwnershipFilterFromSnapshot(snapshot)`
 - `assertOwnershipColumnsForFilter(snapshot, filter)`
@@ -80,6 +82,7 @@ Local functions
 - `renderMigrationForeignKeyLines(snapshot)`
 - `renderMigrationDropForeignKeyLine(foreignKey = {})`
 - `renderMigrationDropForeignKeyLines(snapshot)`
+- `renderMigrationForeignKeyBlock(snapshot, { drop = false } = {})`
 - `renderMigrationCheckConstraintLines(snapshot)`
 - `mergeFieldMetaEntries(...entryGroups)`
 - `resolveLookupNamespaceFromTableName(tableName = "")`
@@ -95,8 +98,8 @@ Local functions
 - `resolveCrudPermissionGrantRole(appConfig = {}, options = {}, { requiresNamedPermissions = true } = {})`
 - `normalizeCrudOperation(operation = "", context = "CRUD operation")`
 - `renderRoleCatalogPermissionGrants(namespace = "", { requiresNamedPermissions = true, grantRoleId = "" } = {})`
-- `renderActionPermissionSupport(namespace = "", { requiresNamedPermissions = true } = {})`
-- `renderActionPermissionExpression(operation = "", { requiresNamedPermissions = true } = {})`
+- `renderActionPermissionSupport(namespace = "", { requiresNamedPermissions = true, access = ACCESS_DEFAULT } = {})`
+- `renderActionPermissionExpression(operation = "", { requiresNamedPermissions = true, access = ACCESS_DEFAULT } = {})`
 - `renderRouteWorkspaceSupportImports({ surfaceRequiresWorkspace = true } = {})`
 - `renderActionWorkspaceValidatorImport({ surfaceRequiresWorkspace = true } = {})`
 - `renderRouteParamsValidatorLine(operation = "", { surfaceRequiresWorkspace = true } = {})`
@@ -105,7 +108,7 @@ Local functions
 - `renderActionInputSchemaDefinition(lines = [], { mode = "patch" } = {})`
 - `renderActionInputExpressions({ surfaceRequiresWorkspace = true } = {})`
 - `renderRouteValidatorConstants({ surfaceRequiresWorkspace = true } = {})`
-- `buildReplacementsFromSnapshot({ namespace = "", snapshot, resolvedOwnershipFilter, surfaceRequiresWorkspace = true, surfaceId = "", routeInternal = false, permissionGrantRoleId = "" })`
+- `buildReplacementsFromSnapshot({ namespace = "", snapshot, resolvedOwnershipFilter, surfaceRequiresWorkspace = true, surfaceId = "", access = ACCESS_DEFAULT, routeInternal = false, permissionGrantRoleId = "" })`
 - `resolveCrudGenerationTableName(options = {})`
 - `createCacheKey({ appRoot, options })`
 - `buildCrudTemplateContext(input = {})`
@@ -216,7 +219,7 @@ Exports
 - `resource`
 - `createTemplateServerFixture(options = {})`
 Local functions
-- `buildTemplateReplacements({ surfaceRequiresWorkspace = true, requiresNamedPermissions = surfaceRequiresWorkspace === true, surfaceId = surfaceRequiresWorkspace ? "admin" : "home", routeInternal = false } = {})`
+- `buildTemplateReplacements({ surfaceRequiresWorkspace = true, requiresNamedPermissions = surfaceRequiresWorkspace === true, surfaceId = surfaceRequiresWorkspace ? "admin" : "home", access = "authenticated", routeInternal = false } = {})`
 - `applyTemplateReplacements(sourceText = "", options = {})`
 - `buildResourceStubSource()`
 - `renderServerTemplateFile(targetServerDirectory, fileName, options)`

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

@@ -29,6 +29,7 @@ Local functions
 - `normalizeRelativeAppPath(value = "")`
 - `requireTargetRootOption(options = {})`
 - `resolveListTargetFile(targetRoot = "")`
+- `resolveFormHelperPaths(targetRoot = "")`
 - `parseOperationsOption(options)`
 - `parseDisplayFieldsOption(options)`
 - `parseParentTitleOption(options)`
@@ -138,6 +139,7 @@ Local functions
 - `resolveAnchorScopeStart(source = "", { anchorIndex = -1, anchor = "" } = {})`
 - `buildAnchorInsertions(operationName, field)`
 - `resolveGeneratedTargetComment(source = "", commentName = "")`
+- `resolveGeneratedTargetPath(appRoot, targetAbsolutePath, generatedTarget = "")`
 - `resolveOperationTargetFiles({ appRoot, operationName, targetAbsolutePath, source = "" } = {})`
 - `parseSubcommandArgs(args = [])`
 

package/reference/autogen/packages/json-rest-api-core.md

@@ -39,6 +39,11 @@ Exports
 Local functions
 - `isPlainJsonRestObject(value)`
 - `cloneJsonRestResourceValue(value, { writeSerializers = {} } = {})`
+- `resolveCanonicalCalendarDate(value)`
+- `serializeJsonRestCalendarDate(value)`
+- `applyJsonRestCalendarDateWriteSerializers(scopeOptions = {})`
+- `normalizeJsonRestCalendarDateEntry(entry = null, scopes = {})`
+- `normalizeJsonRestCalendarDateDocument(document = null, scopes = {})`
 - `normalizeScopeValue(value)`
 - `normalizeJsonRestText(value, { fallback = "" } = {})`
 - `normalizeJsonRestFilterValue(value)`

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

@@ -150,6 +150,13 @@ Exports
 - `resolveCrudBindingValues(values, context = {})`
 - `resolveCrudBoundValues({ binding = {}, routeValues = {}, context = {} } = {})`
 
+### `src/client/composables/crud/crudHttpClientSupport.js`
+Exports
+- `CRUD_API_ACCESS_AUTHENTICATED`
+- `CRUD_API_ACCESS_PUBLIC`
+- `normalizeCrudApiAccess(value = "")`
+- `resolveCrudHttpClient(resource = null, { client = null } = {})`
+
 ### `src/client/composables/crud/crudJsonApiTransportSupport.js`
 Exports
 - `inferCrudJsonApiTransport(resource = null, { mode = "", operationName = "" } = {})`
@@ -201,6 +208,7 @@ Local functions
 - `normalizeTimeWhitespace(value)`
 - `toTimeInputValue(value)`
 - `toDateTimeLocalInputValue(value)`
+- `toDateInputValue(value)`
 - `toIsoUtcDateTimeValue(value)`
 - `resolveFormFieldInitialValue(field = {})`
 - `shouldSerializeClearedFieldAsNull(field = {})`
@@ -472,7 +480,7 @@ Exports
 
 ### `src/client/composables/useCommand.js`
 Exports
-- `useCommand({ ownershipFilter = ROUTE_VISIBILITY_WORKSPACE, surfaceId = "", access = "auto", apiSuffix = "", runPermissions = [], writeMethod = "POST", client = null, transport = null, placementSource = "users-web.command", fallbackRunError = "Unable to complete action.", fieldErrorKeys = [], clearOnRouteChange = true, model, input, buildRawPayload, buildCommandPayload, buildCommandOptions, onRunSuccess, onRunError, suppressSuccessMessage = false, messages = {}, realtime = null } = {})`
+- `useCommand({ ownershipFilter = ROUTE_VISIBILITY_WORKSPACE, surfaceId = "", access = "auto", apiSuffix = "", runPermissions = [], writeMethod = "POST", client = null, resource: commandResource = null, transport = null, placementSource = "users-web.command", fallbackRunError = "Unable to complete action.", fieldErrorKeys = [], clearOnRouteChange = true, model, input, buildRawPayload, buildCommandPayload, buildCommandOptions, onRunSuccess, onRunError, suppressSuccessMessage = false, messages = {}, realtime = null } = {})`
 
 ### `src/client/composables/useCrudAddEditScreen.js`
 Exports
@@ -525,8 +533,10 @@ Local functions
 
 ### `src/client/composables/useCrudListScreen.js`
 Exports
-- `useCrudListScreen({ adapter = null, resource = null, resourceNamespace = "resource", apiSuffix = "", recordIdParam = "recordId", recordIdSelector = null, titleFallbackFieldKey = "", viewUrlTemplate = "", editUrlTemplate = "", newUrlTemplate = "", recordChangedEvents = [], listFilters = {}, listBulkActions = [], listRowActions = [], syntheticRows = null, routeQueryBlacklist = Object.freeze(["include", "cursor", "limit"]), requestQueryParams = null, requestFieldsets = null, readEnabled = true, requestRecoveryLabel = "Records", fallbackLoadError = "Unable to load records." } = {})`
+- `__testables`
+- `useCrudListScreen({ adapter = null, client = null, resource = null, resourceNamespace = "resource", apiSuffix = "", recordIdParam = "recordId", recordIdSelector = null, titleFallbackFieldKey = "", viewUrlTemplate = "", editUrlTemplate = "", newUrlTemplate = "", recordChangedEvents = [], listFilters = {}, listBulkActions = [], listRowActions = [], syntheticRows = null, routeQueryBlacklist = Object.freeze(["include", "cursor", "limit"]), requestQueryParams = null, requestFieldsets = null, readEnabled = true, requestRecoveryLabel = "Records", fallbackLoadError = "Unable to load records." } = {})`
 Local functions
+- `buildCrudListActionContext(records, client)`
 - `formatCrudListCardValue(value)`
 - `asList(value = [])`
 - `hasSyntheticRowGroups(value = null)`
@@ -604,6 +614,8 @@ Exports
 - `CrudListFilterSurface`
 - `CrudListScreen`
 - `CrudViewScreen`
+- `normalizeCrudApiAccess`
+- `resolveCrudHttpClient`
 - `clientProviders`
 
 ### `src/client/lib/bootstrap.js`

package/skills/jskit/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: jskit
+description: Build, extend, troubleshoot, review, deslop, and verify JSKIT applications using the JSKIT CLI, runtime packages, generators, surfaces, placements, and managed-app conventions. Use for JSKIT scaffolding, pages, routes, UI, authentication, databases, CRUDs, users, workspaces, console features, migrations, package changes, upgrades, or pre-sign-off review.
+---
+
+# JSKIT
+
+Use JSKIT's native CLI, generators, installed packages, and app-local
+contracts. This skill explains the technology; the request and application
+files define the product.
+
+## Exact caller lanes
+
+Execute a caller-supplied complete exact JSKIT command lane with all option
+values directly. Read the nearest `AGENTS.md` and relevant skill reference;
+skip `help`, `list`, `show --details`, `list-placements`, sibling docs,
+`node_modules` or generator-source inspection, plus any verification the
+caller owns.
+
+Discover only a missing fact or exact-command failure, then resume the lane.
+
+## Establish context
+
+1. Read the request and nearest `AGENTS.md`.
+2. Inspect `package.json`, `.jskit/lock.json`, the existing tree, and the
+   current diff when reviewing changes.
+3. Read `.jskit/APP_BLUEPRINT.md` when present for durable product and
+   architecture decisions. Do not invent or expand product requirements from
+   this skill.
+4. Load only the task-relevant direct reference:
+   - For creation, package selection, CLI use, or generators, read
+     [application operations](references/app-operations.md).
+   - Before database, schema, CRUD, repository, or persistence work, read
+     [CRUD operations](references/crud-operations.md) completely.
+   - For routes, placements, user-facing UI, or browser verification, read
+     [UI operations](references/ui-operations.md).
+
+Those files are the complete operational references required by this skill.
+Do not depend on sibling package documentation being present. Do not load
+irrelevant references.
+
+Do not invent missing tenancy, authentication, database, surface, ownership,
+or permission decisions when they would materially change the application.
+
+## Discovery fallback
+
+- For a missing fact, use only the narrowest applicable JSKIT CLI query.
+- Prefer an existing JSKIT package, generator, placement, or high-level
+  composable over hand-wired local infrastructure.
+- Treat `.jskit/lock.json` and JSKIT-owned projections as managed state. Do not
+  hand-edit the lock or bypass managed-file lifecycle checks.
+
+## Implement a change
+
+1. Use the caller-selected seam, or discover only a genuinely missing seam.
+2. Read the matching local reference above.
+3. Implement the smallest complete vertical slice at documented app-owned
+   seams.
+4. Install dependencies and run migrations only when the selected operation
+   requires them.
+5. For schema work, use only a fresh disposable development database; never
+   alter production, legacy, historical, or otherwise valuable data.
+
+For user-facing work, respect the selected surface and semantic placements,
+handle compact layouts and loading, empty, error, permission, and ownership
+states, and verify meaningful behavior in the browser.
+
+## Caller-owned verification
+
+When a calling orchestrator explicitly owns final tests, migrations, server
+lifecycle, browser checks, and sign-off, honor that division of work. Stay
+within its wall-time and action limits, implement the requested slice, return
+the requested manifest or summary, and stop. Do not start a dev server,
+browser, Playwright, broad verifier, migration rebuild, or exploratory review
+unless that caller asks for it in the current task.
+
+## Review or deslop
+
+Review the requested chunk or whole changeset. If the request is review-only,
+report findings without editing.
+
+Check for:
+
+- Duplicated helpers, dead code, placeholders, accidental abstractions, and
+  incomplete states.
+- Missed JSKIT packages, generators, high-level composables, placements, or
+  runtime seams.
+- Invalid surface, route, ownership, permission, migration, or managed-file
+  choices.
+- Weak Material Design or Vuetify hierarchy, responsiveness, actions, and
+  state handling.
+- Verification proportional to scope, including Playwright for meaningful
+  user-facing flows.
+
+Present findings first, ordered by severity, with file references. Say
+explicitly when there are no findings.
+
+## Verify
+
+- Run focused tests for the changed slice and broad regression checks for a
+  whole changeset.
+- Run `npx jskit doctor` when managed state changed.
+- Run `npm run verify` before sign-off.
+- Rebuild migrations from zero against a fresh disposable database when
+  schema or persistence changed.
+- Run the relevant Playwright flow when user-facing behavior changed.
+- Report files reviewed or changed, commands run, and anything still
+  unverified.

package/skills/jskit/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "JSKIT"
+  short_description: "Build, debug, verify, and review JSKIT apps"
+  default_prompt: "Use $jskit to build, extend, troubleshoot, verify, or review this JSKIT application."

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

@@ -0,0 +1,41 @@
+# Application operations
+
+Read this reference for application creation, CLI discovery, package changes,
+and generator selection.
+
+## Create an application
+
+Confirm the application name and tenancy mode, then run:
+
+```bash
+npx @jskit-ai/create-app <app-name> --tenancy-mode <tenancy-mode>
+cd <app-name>
+npm install
+```
+
+Generated applications require Node.js 26. Use `--target . --force` only to
+promote a known JSKIT `ai-seed` directory, never to overwrite an arbitrary
+application. Use `--minimal` only for a deliberately bare package-development
+or unusual integration baseline. After creation, follow the generated
+`AGENTS.md`.
+
+Do not add authentication, users, workspaces, console, example routes, sample
+records, or another database adapter unless the request requires them.
+
+## Select and apply technology
+
+- Inspect available capabilities with `npx jskit list` and inspect a specific
+  entry with `npx jskit show <id> --details`.
+- Install reusable runtime capability with `npx jskit add package <id>`.
+- Inspect a bundle before installing it with `npx jskit add bundle <id>`.
+- Run tooling packages with
+  `npx jskit generate <generator> <action> ...`; do not install generators as
+  runtime packages.
+- Let `jskit` own JSKIT application mutations, use `npm install` for dependency
+  installation, and use `npm run db:migrate` for database migrations.
+- Review generated files and continue only at documented app-owned seams.
+
+Packages own reusable framework behavior. Generators create application-owned
+pages, components, placements, migrations, and support files. Prefer the
+narrowest installed package or generator that implements the requested
+vertical slice; do not build a parallel local framework around it.

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

@@ -0,0 +1,111 @@
+# CRUD operations
+
+Read this reference completely before database, schema, CRUD, repository, or
+persistence work.
+
+## Establish the contract
+
+Determine the selected database adapter, surface, access rule, and ownership
+model from the request and app authority. Inspect only a generator whose exact
+lane or option values are missing, or whose supplied command failed:
+
+```bash
+npx jskit show crud-server-generator --details
+npx jskit show crud-ui-generator --details
+```
+
+Never run these merely to reconfirm caller-supplied facts.
+
+For normal app-owned CRUD tables:
+
+- Use one non-null integer primary key, normally
+  `id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY`.
+- Make every foreign key single-column and target the referenced table's
+  single-column primary key. Use multi-column unique indexes only for business
+  uniqueness, never as relationship targets.
+- Use only direct `workspace_id` and/or `user_id` columns for generated JSKIT
+  ownership and choose the ownership filter matching those columns exactly.
+- Treat names such as `recipient_user_id`, `created_by_user_id`, and
+  `assignee_user_id` as domain relationships, not ownership aliases.
+- Express tenant-safe relationships as direct ownership plus a normal
+  `parent_id -> parent.id` relation. Test both allowed and cross-workspace
+  cases.
+
+Stop before generation if the schema uses composite relationship keys or if
+the ownership filter and reserved ownership columns disagree.
+
+## Conventional one-table CRUD
+
+In a fresh disposable development database, create the validated table first.
+The server generator reads its live shape. Scaffold the server contract before
+the UI:
+
+```bash
+npx jskit generate crud-server-generator scaffold \
+  --namespace <resource> \
+  --surface <surface> \
+  --ownership-filter <public|user|workspace|workspace_user> \
+  --access <public|authenticated> \
+  --table-name <table>
+```
+
+Use `--access public` only with a non-workspace surface and public ownership;
+omit both role-grant flags. For workspace-required CRUDs, choose exactly one
+of `--grant-role <role>` or `--no-role-grant`. Never invent a role to satisfy
+the generator. Use `--internal` when the entity needs the generated
+repository/service/resource/migration ownership chain but no public HTTP CRUD
+routes.
+
+Run `npm install`, then scaffold the UI from the generated shared resource:
+
+```bash
+npx jskit generate crud-ui-generator crud \
+  <pages-root>/<plural-route> \
+  --resource-file packages/<namespace>/src/shared/<singular>Resource.js \
+  --parent-title contextual
+```
+
+The target is relative to `src/pages/`, starts with the selected surface's
+nonempty configured `pagesRoot`, and has no leading slash (for example
+`home/books`). For a surface deliberately configured with an empty root, use
+only the plural route (for example `books`). Use the exact singular resource
+filename emitted by the server generator; do not guess it.
+
+Treat that shared resource as the canonical CRUD contract. Do not hand-build
+routes, validators, HTTP helpers, or UI before the server resource exists.
+
+Use generated high-level seams where they fit:
+
+- `useCrudListScreen()`, `useCrudViewScreen()`, and
+  `useCrudAddEditScreen()` for routed screens.
+- `useCrudList()`, `useCrudView()`, and `useCrudAddEdit()` for routed CRUD
+  behavior.
+- `useList()`, `useView()`, `useAddEdit()`, `useCommand()`, and
+  `useEndpointResource()` for non-standard contracts.
+
+CRUD hooks derive their JSON:API transport from the shared resource. Do not
+pass a custom transport or use raw `fetch()` for standard CRUD behavior.
+
+## Migration ownership
+
+Do not hand-write a competing migration for a table the CRUD server generator
+will own. Never modify or replace its installed baseline migration. Express a
+later schema change as a new immutable additive migration owned by the
+app-local package:
+
+```bash
+npx jskit create migration \
+  --package <package-id> \
+  --id <migration-id>
+npx jskit migrations package <package-id>
+npm run db:migrate
+```
+
+If ordinary persisted data genuinely cannot use the generated CRUD lane, stop
+and obtain explicit developer approval. Record the approved exception in
+`.jskit/WORKBOARD.md` and `.jskit/table-ownership.json`; also record it in
+`.jskit/APP_BLUEPRINT.md` when it changes durable architecture.
+
+Before sign-off, rebuild the full migration chain in a fresh disposable
+database, compare the recreated schema with the intended schema, test relevant
+ownership boundaries, run JSKIT Doctor, and run the project verifier.

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

@@ -0,0 +1,74 @@
+# UI operations
+
+Read this reference for routes, pages, surfaces, placements, responsive UI, or
+browser verification.
+
+## Pages, surfaces, and placements
+
+Take the intended surface from the request and app authority; do not silently
+default new functionality to `app`. Surface choice controls routes, access,
+placement visibility, and often ownership.
+
+For a normal app-owned non-CRUD page, first inspect the generator and semantic
+placements, then generate the page:
+
+```bash
+npx jskit show ui-generator --details
+npx jskit list-placements
+npx jskit generate ui-generator page <route-file> --name <name>
+```
+
+Use `--navigation-role primary` for main destinations and `secondary`,
+`detail`, `workflow`, or `none` as appropriate for other routes. Use
+`--link-placement <semantic-id>` when the link belongs in a non-default slot.
+Use `npx jskit list-placements --concrete` only when diagnosing concrete
+outlets. Author normal app UI against semantic placements such as
+`shell.primary-nav` or `page.section-nav`, not raw `host:position` outlets.
+
+Let the generator create both the route and placement entry before adapting
+app-owned output. If a normal page cannot use the generator, state the concrete
+reason before hand-writing it.
+
+## Screen behavior
+
+- Keep app screens phone/task-first, primary actions drawer-independent, and
+  48 px tap targets.
+- Use a page header and direct `v-sheet`, not nested-card architecture.
+- Provide resource-named loading, empty, error, permission, and retry states.
+- Use compact searchable cards and medium/expanded tables for generated CRUD
+  lists where appropriate.
+- Extend shared CRUD screens through slots. For custom sibling/child links,
+  resolve current dynamic params with their runtime to an absolute URL/route
+  object; never bind its route-template/relative string raw to Vue Router `to`.
+- Use `defineCrudListRowActions(...)` and the generated page-local row-action
+  seam for row commands. Use shared filter definitions for structured filters.
+- Keep ordinary read failures local with runtime `loadError` and retry state.
+  Use `useCommand()` or `useUiFeedback()` for user-triggered action feedback.
+
+## Browser verification
+
+Any change to user-facing behavior needs a Playwright flow exercising that
+behavior. Check compact, medium, and expanded widths for generated/template UI
+changes, including overflow, clipped text, duplicate navigation, route
+placement, primary actions, and tap targets.
+
+Use relative URLs in tests. The shared JSKIT Playwright config owns the base
+URL, server lifecycle, and storage state. When `PLAYWRIGHT_BASE_URL` is set,
+do not start another server. When
+`VIBE64_PLAYWRIGHT_STORAGE_STATE` is supplied, do not print, commit, or retain
+it and do not use local login bypasses. Do not install a browser when the
+environment supplies a managed runner.
+
+For a direct localhost app with development auth bypass explicitly enabled,
+use `loginAsExistingUser()` from `@jskit-ai/auth-web/test/playwright`; never
+send the bypass secret through browser globals, query parameters, or client
+environment variables.
+
+After a successful UI test, record the verification when the app supports it:
+
+```bash
+npx jskit app verify-ui \
+  --command "<exact successful Playwright command>" \
+  --feature "<changed behavior>" \
+  --auth-mode <dev-auth-login-as|session-bootstrap>
+```

package/skills/jskit-review/SKILL.md

@@ -1,86 +0,0 @@
----
-name: jskit-review
-description: Review or deslop a JSKIT chunk or whole changeset. Use when the user asks to review, deslop, run a JSKIT best-practices audit, or verify a JSKIT feature, chunk, or whole changeset before sign-off.
----
-
-# JSKIT Review
-
-Use this skill for independent review passes on JSKIT app work.
-
-Preferred execution mode:
-
-- Run this skill in a fresh review agent when the runtime supports delegation.
-- Use the current agent only when delegation is unavailable.
-- The same rule applies to chunk review and whole-changeset review.
-
-## Read First
-
-Use the user request, current diff, and app-local instructions as the source of truth for the review scope.
-
-Read these on demand:
-
-- `../../reference/autogen/KERNEL_MAP.md`
-- `../../reference/autogen/README.md`
-- `../../guide/agent/index.md`
-- `../../site/guide/index.md` when compressed guidance is ambiguous
-
-## Review target
-
-Determine whether the target is:
-
-- the current chunk
-- or the whole changeset
-
-## Required passes
-
-1. Deslop review
-2. JSKIT best-practices review
-3. Material Design and Vuetify review
-4. Verification review
-
-## Deslop review
-
-Check for:
-
-- repeated functions or duplicated local helpers
-- local helpers that should reuse kernel/runtime seams
-- placeholder, fake-complete, or vague UI/copy/code
-- dead code, unused imports/props, TODO-shaped gaps, or accidental abstractions
-- missing loading, empty, error, permission, or ownership states
-- broken route wiring, missing migrations, or incomplete flows
-
-## JSKIT review
-
-Check for:
-
-- missed reuse of existing JSKIT helpers or runtime seams
-- hand code that should have been a package, generator, or scaffold step
-- surface, route, ownership, and migration choices that violate JSKIT conventions
-- metadata that no longer matches actual behavior
-
-## Material Design and Vuetify review
-
-Check that user-facing screens:
-
-- follow Material Design and Vuetify best practices
-- use clear layout hierarchy, spacing, actions, and empty/error states
-- use coherent list, table, and form patterns
-- improve weak screens before sign-off rather than only recording the problem
-
-## Verification review
-
-Check that verification is appropriate for the target:
-
-- focused verification for a chunk
-- broad regression for a whole changeset
-- Playwright for meaningful user-facing flows
-- explicit handling of login/test-auth strategy when auth is required
-
-## Output format
-
-- Present findings first, ordered by severity, with file references.
-- If there are no findings, say so explicitly.
-- Always finish with:
-  - files reviewed
-  - commands run
-  - anything still unverified

package/skills/jskit-review/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "JSKIT Review"
-  short_description: "Deslop, audit JSKIT fit, and verify a chunk or changeset"
-  default_prompt: "Use $jskit-review to run a deslop pass, JSKIT best-practices audit, and verification review on the current JSKIT chunk or whole changeset."