@jskit-ai/agent-docs 0.1.18 → 0.1.19

package/guide/agent/app-setup/users.md

@@ -212,13 +212,17 @@ The account route itself is very small:
 <template>
   <AccountSettingsClientElement />
 </template>
+
+<script setup>
+import AccountSettingsClientElement from "@jskit-ai/users-web/client/components/AccountSettingsClientElement";
+</script>
 ```
 
 That is a very JSKIT-style file.
 
 - the route policy is app-owned
 - the page wrapper is app-owned
-- the heavy UI is delegated to a reusable client element
+- the heavy UI is delegated to a package-owned reusable client element
 
 So the route is simple, but it is already a real authenticated account screen rather than a placeholder card.
 
@@ -228,18 +232,21 @@ The account page is backed by:
 
 ```text
 src/components/account/settings/
-  AccountSettingsClientElement.vue
   AccountSettingsProfileSection.vue
   AccountSettingsPreferencesSection.vue
   AccountSettingsNotificationsSection.vue
 ```
 
-The top-level `AccountSettingsClientElement.vue` uses `useAccountSettingsRuntime()` from `users-web` and wires those sections into a tabbed settings experience.
+Those three section components stay app-owned so you can reshape the actual UI freely.
+
+The host itself now lives in `users-web` and resolves every account section through the `account-settings:sections` placement target, including the default `profile`, `preferences`, and `notifications` entries.
+
+So the screen follows the same rule as the rest of JSKIT UI: sections are added by placement rather than being hardcoded into an app-owned host component.
 
 That is worth noticing because the guide has now reached a new level of scaffolding:
 
 - earlier chapters mostly introduced shells and routes
-- this chapter introduces real app-owned feature UI that is already split into reusable sections
+- this chapter introduces app-owned leaf section UI while the generic section host stays in the package
 
 ## Under the hood
 

package/guide/agent/app-setup/working-with-the-jskit-cli.md

@@ -666,6 +666,7 @@ In the current CLI, that includes checks such as:
 - installed package entries in `.jskit/lock.json`
 - whether managed files recorded in the lock still exist
 - whether installed packages are still visible in the package registry
+- explicit `transport` passed to high-level CRUD hooks such as `useCrudList()`, `useCrudView()`, and `useCrudAddEdit()`, where the shared CRUD resource should derive the JSON:API transport automatically
 - certain JSKIT-specific app checks, such as invalid raw `mdi-*` icon literals in Vue templates when the app uses Vuetify's `mdi-svg` iconset
 - UI verification receipts for current dirty UI files in git, via `.jskit/verification/ui.json`
 

package/package.json

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

package/patterns/INDEX.md

@@ -28,6 +28,8 @@ How to use it:
   - `ui-testing.md`
 - filter, filters, search facets, chips, date range, enum filter, lookup filter, `useCrudListFilters`, `createCrudListFilters`
   - `filters.md`
+- `searchSchema`, `search: true`, `applyFilter`, server search, query validators, backend filters, internal JSON REST filters
+  - `server-search.md`
 - `actualField`, `storage.writeSerializer`, `storage.virtual`, computed field, virtual field, projection, `createCrudResourceRuntime`, `remainingBatchWeight`, datetime write serialization
   - `crud-repository-mapping.md`
 
@@ -42,4 +44,5 @@ How to use it:
 - [client-requests.md](./client-requests.md)
 - [ui-testing.md](./ui-testing.md)
 - [filters.md](./filters.md)
+- [server-search.md](./server-search.md)
 - [crud-repository-mapping.md](./crud-repository-mapping.md)

package/patterns/client-requests.md

@@ -41,6 +41,11 @@ Use the CRUD wrappers when they fit:
 - `useCrudView()` for routed CRUD record loading
 - `useCrudAddEdit()` for routed CRUD forms
 
+CRUD hook transport defaults:
+
+- CRUD hooks derive the standard JSON:API transport from the shared CRUD `resource` automatically.
+- Do not pass `transport` to CRUD hooks. If you need a non-standard wire contract, drop to `useList()`, `useView()`, `useAddEdit()`, or `usersWebHttpClient.request(...)` instead of the CRUD wrappers.
+
 Why this is the standard JSKIT shape:
 
 - `useCommand()` resolves the scoped API path for the current route and surface.

package/patterns/filters.md

@@ -5,6 +5,10 @@ Use when:
 - the user asks to "add a filter", "make the list filterable", or "keep filters in the URL"
 - a screen mixes free-text search with structured facets
 
+Server-side note:
+- for the current CRUD server contract on the JSON REST path, see `server-search.md`
+- this file is about the shared structured-filter runtime used by CRUD list pages and explicit list-filter modules
+
 Ask first:
 - which fields are filterable
 - whether each filter is a flag, enum, multi-enum, date/date-range, number-range, record id, or lookup-backed record id

package/patterns/server-search.md

@@ -0,0 +1,211 @@
+# Server Search
+
+Use when:
+- a CRUD list accepts `q` or other server-side query params
+- a resource needs alias filters such as `onlyArchived -> archived`
+- a list needs access-scoped filters that the repository injects before querying
+- the user asks where search belongs on the server in a current JSKIT app
+
+Core rule:
+- for current JSKIT CRUD apps, the server search contract lives in `resource.searchSchema` on the internal JSON REST path
+- route validators decide which public query keys HTTP callers may send
+- repositories may add internal-only filter keys before forwarding the query to JSON REST
+
+Fresh generated CRUD repositories already follow this path:
+
+```js
+return api.resources.contacts.query({
+  queryParams: buildJsonRestQueryParams(RESOURCE_TYPE, query),
+  simplified: false
+}, createJsonRestContext(context));
+```
+
+The normal layer split is:
+1. `actions.js` / `registerRoutes.js`: accept and validate public query keys
+2. `repository.js`: add internal-only filter keys such as visibility scope
+3. `*Resource.js`: define the backend filter behavior in `searchSchema`
+
+## Decision Rules
+
+Use `search: true` on a schema field when:
+- the public filter key should be the same as the field name
+- direct field filtering is enough
+- you are happy with the generated/effective search entry for that one field
+
+Example:
+
+```js
+schema: {
+  archived: {
+    type: "boolean",
+    search: true,
+    operations: {
+      output: { required: true }
+    }
+  }
+}
+```
+
+Good fit:
+- `archived=true`
+- `statusSid=active`
+- direct field-by-field filtering with no aliasing
+
+Do not use `search: true` when:
+- you want a different public key than the storage field
+- you need one key to search several fields
+- you need custom SQL semantics
+- you need an internal-only injected filter
+
+Use explicit `searchSchema` when:
+- the public key differs from the field name
+- one key searches multiple fields
+- the route/API contract should stay stable even if field names change
+- the filter is internal-only and injected by the repository
+- you need to override the simple `search: true` behavior
+
+Example:
+
+```js
+searchSchema: {
+  onlyArchived: {
+    type: "boolean",
+    actualField: "archived",
+    filterOperator: "="
+  },
+  q: {
+    type: "string",
+    oneOf: ["firstName", "lastName", "email"],
+    filterOperator: "like",
+    splitBy: " ",
+    matchAll: true
+  }
+}
+```
+
+Important merge rule:
+- explicit `searchSchema` is the authored contract
+- fields marked `search: true` are added to the effective search schema too
+- if both define the same public key, explicit `searchSchema` wins
+
+Use `applyFilter` when:
+- `actualField`, `oneOf`, and normal operators are not enough
+- the filter needs compound SQL
+- the filter encodes visibility rules, status buckets, or null/not-null semantics that are more complex than a direct field comparison
+
+Example:
+
+```js
+searchSchema: {
+  "__viewerAccess": {
+    type: "string",
+    applyFilter(query, rawValue) {
+      const value = String(rawValue || "").trim();
+
+      query.whereNull("deleted_at");
+      if (value === "privileged") {
+        return;
+      }
+
+      const userId = value.startsWith("user:")
+        ? String(value.slice(5) || "").trim()
+        : "";
+
+      query.where(function () {
+        this.where("user_added", 0);
+        if (userId) {
+          this.orWhere("added_by_user_id", userId);
+        }
+      });
+    }
+  }
+}
+```
+
+Keep `applyFilter` focused on query semantics:
+- build the SQL/knex filter there
+- do not put permission checks there
+- do not turn it into a second service layer
+
+Add route validators when:
+- the filter key is public and may arrive from HTTP query params
+- the page/UI needs a stable, validated query contract
+- malformed values should either be rejected or deliberately discarded
+
+Example route layer:
+
+```js
+input: composeSchemaDefinitions([
+  workspaceSlugParamsValidator,
+  listCursorPaginationQueryValidator,
+  listSearchQueryValidator,
+  vetsListFiltersQueryValidator,
+])
+```
+
+That means:
+- `q` and the structured filter keys are accepted publicly
+- the repository may still add internal-only keys later
+
+Do not add route validators for:
+- repository-injected internal keys such as `"__viewerAccess"`
+- filters that must never be supplied by the client directly
+
+## Recommended Shapes
+
+Simple direct field exposure:
+
+```js
+schema: {
+  vip: { type: "boolean", search: true }
+}
+```
+
+Public alias for a real field:
+
+```js
+searchSchema: {
+  onlyVip: { type: "boolean", actualField: "vip", filterOperator: "=" }
+}
+```
+
+Grouped text search:
+
+```js
+searchSchema: {
+  q: {
+    type: "string",
+    oneOf: ["name", "email", "phone"],
+    filterOperator: "like",
+    splitBy: " ",
+    matchAll: true
+  }
+}
+```
+
+Repository-injected internal filter:
+
+```js
+function buildScopedQuery(query = {}, context = null) {
+  return {
+    ...(query || {}),
+    "__viewerAccess": resolveViewerAccess(context)
+  };
+}
+```
+
+## Keep These Boundaries Clean
+
+- Put backend filter behavior in `searchSchema`, not in page code.
+- Put permission checks in the action/service layer, not in `applyFilter`.
+- Put repository-only scoping in the repository, not in route query validation.
+- Do not expose a query key publicly just because the repository uses it internally.
+- Do not rely on route validators alone; a public key still needs a matching backend search definition.
+
+## Quick Rule Of Thumb
+
+- Same key, same field, simple behavior: `search: true`
+- Public alias or multi-field search: `searchSchema`
+- Complex SQL semantics: `searchSchema` + `applyFilter`
+- Public HTTP query key: add a route validator
+- Internal-only repository key: inject it in `repository.js`, skip the public validator

package/reference/autogen/packages/auth-provider-supabase-core.md

@@ -244,6 +244,7 @@ Local functions
 - `resolveCommonDependencies(scope)`
 - `resolveRuntimeEnv(scope)`
 - `resolveOptionalRepositories(scope)`
+- `isDeferredJsonRestBootGap(app, error)`
 - `applyAuthServiceDecorators(scope, authService)`
 
 ### root

package/reference/autogen/packages/crud-core.md

@@ -296,6 +296,14 @@ Local functions
 ### `src/server/routeContracts.js`
 Exports
 - `createCrudJsonApiRouteContracts({ resource = {}, routeParamsValidator = null, listSearchQueryValidator = defaultListSearchQueryValidator, lookupIncludeQueryValidator = defaultLookupIncludeQueryValidator } = {})`
+Local functions
+- `isRecord(value)`
+- `resolveSchemaFieldDefinitions(definition = null)`
+- `resolveJsonApiRelationshipEntries(definition = null)`
+- `createRecordAttributesResolver(definition = null, { excludeKeys = [] } = {})`
+- `createRecordRelationshipsResolver(definition = null)`
+- `createRequestRelationshipMapper(definition = null)`
+- `resolveOutputAttributeExcludeKeys(resource = {})`
 
 ### `src/server/serviceEvents.js`
 Exports

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

@@ -132,6 +132,7 @@ Local functions
 - `requireVariableDeclarator(programNode, variableName = "", context = "crud-server-generator scaffold-field")`
 - `requireCrudResourceConfigObject(programNode, context = "crud-server-generator scaffold-field")`
 - `requireResourceSchemaObject(programNode, context = "crud-server-generator scaffold-field")`
+- `assertNoExplicitCrudSchemaOverrides(resourceObject, context = "crud-server-generator scaffold-field")`
 - `findObjectPropertyByName(objectNode, propertyName = "")`
 - `hasObjectProperty(objectNode, propertyName = "")`
 - `insertObjectProperty(objectNode, propertyName = "", valueExpressionSource = "", { context = "crud-server-generator scaffold-field", insertBeforeComputed = false } = {})`

package/reference/autogen/packages/http-runtime.md

@@ -111,7 +111,10 @@ Local functions
 - `isRecord(value)`
 - `normalizeTransportKind(transport = null)`
 - `defaultEncodeAttributes(body = {})`
-- `simplifyResourceObject(resource = {})`
+- `resolveRelationshipFieldKey(relationshipName = "", lookupFieldMap = null)`
+- `createIncludedResourceIndex(document = {})`
+- `simplifyRelationshipResource(linkage = {}, options = {})`
+- `simplifyResourceObject(resource = {}, options = {})`
 - `assertPrimaryDataType(resource = {}, expectedType = "")`
 - `resolveCollectionPageMeta(document = {})`
 
@@ -262,18 +265,21 @@ Local functions
 ### `src/shared/validators/jsonApiRouteTransport.js`
 Exports
 - `JSON_API_ERROR_DOCUMENT_SCHEMA`
-- `createJsonApiResourceObjectTransportSchema({ type = "", attributes, requireId = true, includeLinks = false, includeMeta = false } = {})`
-- `createJsonApiResourceRequestBodyTransportSchema({ type = "", attributes, requireId = false } = {})`
-- `createJsonApiResourceSuccessTransportSchema({ type = "", attributes, kind = "record", includeLinks = false, includeMeta = false, includeIncluded = false } = {})`
+- `createJsonApiResourceObjectTransportSchema({ type = "", attributes, requireId = true, includeLinks = false, includeMeta = false, excludeAttributeKeys = [], relationshipEntries = [], relationshipMembersRequired = false } = {})`
+- `createJsonApiResourceRequestBodyTransportSchema({ type = "", attributes, requireId = false, excludeAttributeKeys = [], relationshipEntries = [] } = {})`
+- `createJsonApiResourceSuccessTransportSchema({ type = "", attributes, kind = "record", includeLinks = false, includeMeta = false, includeIncluded = false, excludeAttributeKeys = [], relationshipEntries = [] } = {})`
 - `withJsonApiErrorResponses(successResponses, { includeValidation400 = false } = {})`
 - `createJsonApiResourceRouteTransport({ type = "", requestType = "", responseType = "", query = null, allowBodyId = false, successKind = "record", pointerPrefix = "/data/attributes", mapRequestRelationships = null, getRecordType = null, getRecordId = null, getRecordAttributes = null, getRecordRelationships = null, getRecordLinks = null, getRecordMeta = null, getIncluded = null, getDocumentLinks = null, getDocumentMeta = null, getCollectionItems = null } = {})`
-- `createJsonApiResourceRouteContract({ type = "", requestType = "", responseType = "", body = null, query = null, output = null, outputKind = "record", successStatus = 200, includeValidation400 = false, allowBodyId = false, pointerPrefix = "/data/attributes", getRecordType = null, getRecordId = null, getRecordAttributes = null, getRecordRelationships = null, getRecordLinks = null, getRecordMeta = null, getIncluded = null, getDocumentLinks = null, getDocumentMeta = null, getCollectionItems = null, mapRequestRelationships = null } = {})`
+- `createJsonApiResourceRouteContract({ type = "", requestType = "", responseType = "", body = null, query = null, output = null, outputKind = "record", successStatus = 200, includeValidation400 = false, allowBodyId = false, pointerPrefix = "/data/attributes", bodyAttributeExcludeKeys = [], outputAttributeExcludeKeys = [], bodyRelationshipEntries = [], outputRelationshipEntries = [], getRecordType = null, getRecordId = null, getRecordAttributes = null, getRecordRelationships = null, getRecordLinks = null, getRecordMeta = null, getIncluded = null, getDocumentLinks = null, getDocumentMeta = null, getCollectionItems = null, mapRequestRelationships = null } = {})`
 Local functions
 - `isRecord(value)`
 - `createJsonApiTransportError(statusCode, message, code)`
 - `resolveRouteType(type = "")`
 - `resolveRouteTypes(value = {})`
-- `resolveEmbeddedAttributesTransportSchema(definition, { context = "JSON:API resource", defaultMode = "replace", removeId = false } = {})`
+- `resolveEmbeddedAttributesTransportSchema(definition, { context = "JSON:API resource", defaultMode = "replace", removeId = false, removeKeys = [] } = {})`
+- `normalizeRelationshipSchemaEntries(entries = [])`
+- `createJsonApiRelationshipDataSchema(relationshipType = "", { nullable = false } = {})`
+- `createJsonApiRelationshipsTransportSchema(entries = [], { includeRequired = false } = {})`
 - `createJsonApiMetaSuccessTransportSchema({ meta } = {})`
 - `defaultRecordTypeResolver(type)`
 - `defaultRecordIdResolver(record = {})`

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

@@ -24,7 +24,7 @@ Exports
 - `JSON_REST_AUTOFILTER_PRESETS`
 - `addResourceIfMissing(api, scopeName, resourceConfig)`
 - `buildJsonRestQueryParams(resourceType = "", query = {}, { include = undefined } = {})`
-- `createJsonApiInputRecord(resourceType = "", attributes = {}, { id = null, relationships = null } = {})`
+- `createJsonApiInputRecord(resourceType = "", attributes = {}, { id = null, relationships = null, resource = null } = {})`
 - `createJsonApiRelationship(resourceType = "", id = null)`
 - `createJsonRestResourceScopeOptions(resource = {}, { writeSerializers = {}, normalizeId = null } = {})`
 - `createJsonRestContext(context = null)`
@@ -42,6 +42,7 @@ Local functions
 - `normalizeJsonRestText(value, { fallback = "" } = {})`
 - `normalizeJsonRestObject(value)`
 - `normalizeJsonRestList(value)`
+- `extractJsonApiInputRelationships(attributes = {}, resource = null, relationships = null)`
 - `normalizeJsonApiResourceObject(resource = {})`
 - `buildJsonApiIncludedIndex(payload = {})`
 - `simplifyJsonApiRelationshipData(data, { includedIndex = null, seen = null } = {})`

package/reference/autogen/packages/kernel.md

@@ -878,6 +878,7 @@ Exports
 - `registerRoutes(fastify, { routes = [], app = null, applyRoutePolicy = defaultApplyRoutePolicy, missingHandler = defaultMissingHandler, enableRequestScope = true, requestScopeProperty = "scope", requestActionExecutorProperty = "executeAction", actionExecutorToken = "actionExecutor", requestActionDefaultChannel = "api", requestActionDefaultSurface = "", requestScopeIdPrefix = "http", requestIdResolver = null, middleware = {} } = {})`
 Local functions
 - `toFastifyRouteOptions(route)`
+- `shouldStripFastifyBodySchema(route = null, schema = null)`
 - `normalizeHeaderValue(value)`
 - `normalizeMediaType(value = "")`
 - `routeDefinesRequestBody(route = null)`

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

@@ -54,8 +54,8 @@ Exports
 - `DEFAULT_SUBPAGES_POSITION`
 - `DEFAULT_COMPONENT_DIRECTORY`
 - `SECTION_CONTAINER_SHELL_COMPONENT`
-- `TAB_LINK_COMPONENT`
-- `TAB_LINK_COMPONENT_TOKEN`
+- `SUBPAGES_LINK_COMPONENT`
+- `SUBPAGES_LINK_COMPONENT_TOKEN`
 - `resolvePageTargetDetails`
 - `resolveNearestParentSubpagesHost`
 - `deriveDefaultSubpagesHost`

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

@@ -18,7 +18,6 @@ Use this on demand; do not load the full index at startup.
 Exports
 - `ACCOUNT_SETTINGS_SECTION_TARGET`
 - `EMPTY_ACCOUNT_SETTINGS_SECTIONS`
-- `RESERVED_ACCOUNT_SETTINGS_SECTION_VALUES`
 - `normalizeAccountSettingsSectionEntry(entry = null)`
 - `resolveAccountSettingsSections(entries = [])`
 - `sortAccountSettingsSections(entries = [])`
@@ -29,6 +28,13 @@ Exports
 - `createUsersBootstrapUserHandler()`
 - `registerUsersBootstrapPayloadHandlers(app)`
 
+### `src/client/components/AccountSettingsClientElement.vue`
+Exports
+- None
+Local functions
+- `normalizeSection(value)`
+- `readRouteSection()`
+
 ### `src/client/components/ProfileClientElement.vue`
 Exports
 - None
@@ -75,6 +81,17 @@ Exports
 - `resolveCrudBindingValues(values, context = {})`
 - `resolveCrudBoundValues({ binding = {}, routeValues = {}, context = {} } = {})`
 
+### `src/client/composables/crud/crudJsonApiTransportSupport.js`
+Exports
+- `inferCrudJsonApiTransport(resource = null, { mode = "", operationName = "" } = {})`
+- `resolveCrudJsonApiTransport(transport = null, resource = null, options = {})`
+- `resolveLookupFieldMap(resource = null)`
+Local functions
+- `isRecord(value)`
+- `resolveSchemaFieldDefinitions(definition = null)`
+- `isJsonApiResourceTransport(transport = null)`
+- `resolveCrudJsonApiResourceType(resource = null)`
+
 ### `src/client/composables/crud/crudLookupFieldLabelSupport.js`
 Exports
 - `resolveLookupItemLabel(item = {}, labelKey = "")`
@@ -84,6 +101,7 @@ Local functions
 - `hasDisplayValue(value)`
 - `resolveComposedLabel(source = {}, candidates = LOOKUP_LABEL_COMPOSITION_CANDIDATES)`
 - `resolveLookupFieldDescriptor(field = {}, relationKind = "", valueKey = "", labelKey = "")`
+- `resolveFallbackLookupKey(key = "")`
 
 ### `src/client/composables/crud/crudLookupFieldRuntime.js`
 Exports
@@ -108,6 +126,7 @@ Local functions
 - `resolveFormFieldType(field = {})`
 - `resolveFormFieldFormat(field = {})`
 - `isNullableFormField(field = {})`
+- `isLookupFormField(field = {})`
 - `padDateTimePart(value)`
 - `normalizeTimeWhitespace(value)`
 - `toTimeInputValue(value)`
@@ -166,7 +185,7 @@ Local functions
 
 ### `src/client/composables/records/useCrudView.js`
 Exports
-- `useCrudView({ paramBinding = null, route = null, ...viewOptions } = {})`
+- `useCrudView({ resource = null, paramBinding = null, route = null, ...viewOptions } = {})`
 
 ### `src/client/composables/records/useList.js`
 Exports
@@ -433,6 +452,7 @@ Exports
 ### `src/client/index.js`
 Exports
 - `UsersWebClientProvider`
+- `AccountSettingsClientElement`
 - `clientProviders`
 
 ### `src/client/lib/bootstrap.js`
@@ -486,13 +506,6 @@ Exports
 
 ### templates
 
-### `templates/src/components/account/settings/AccountSettingsClientElement.vue`
-Exports
-- None
-Local functions
-- `normalizeSection(value)`
-- `readRouteSection()`
-
 ### `templates/src/components/account/settings/AccountSettingsNotificationsSection.vue`
 Exports
 - None

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

@@ -333,7 +333,6 @@ Local functions
 - `normalizePendingInvitesCount(value)`
 - `resolveReturnTo()`
 - `resolveReturnToHref()`
-- `countPendingInvites(entries = [])`
 
 ### `templates/packages/main/src/client/components/AccountSettingsInvitesSection.vue`
 Exports

package/reference/autogen/tooling/jskit-cli.md

@@ -368,6 +368,10 @@ Local functions
 ### `src/server/commandHandlers/appCommands/linkLocalPackages.js`
 Exports
 - `runAppLinkLocalPackagesCommand(ctx = {}, { appRoot = "", options = {}, stdout })`
+Local functions
+- `collectDeclaredPackageNames(packageJson = {})`
+- `verifySymlinkTarget(targetPath = "", sourceDir = "", { packageName = "" } = {})`
+- `maybeLinkCompanionPackages({ appRoot = "", repoRoot = "", stdout, createCliError })`
 
 ### `src/server/commandHandlers/appCommands/release.js`
 Exports