@jskit-ai/agent-docs 0.1.6 → 0.1.8

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

@@ -914,6 +914,129 @@ That explains why the login screen and auth guard runtime both care about `/api/
 
 It is also why the shell widget can react cleanly to auth state without storing raw session tokens in client state. The browser just asks the app for the current session view, and the app derives that from its cookies plus Supabase.
 
+### Authenticated Playwright testing with the dev auth bypass
+
+JSKIT now ships a development-only auth bootstrap path specifically so authenticated UI can be verified in Playwright without depending on a real live login flow through Supabase.
+
+This is the standard path the agent should use for authenticated browser tests:
+
+- enable the dev auth bypass in development
+- create a session for an existing user through the local app
+- let the browser keep the resulting HTTP-only cookies
+- navigate to the protected page and verify the feature
+- record the Playwright run through `jskit app verify-ui` so `jskit doctor` can verify the receipt later
+
+The feature is intentionally narrow.
+
+- It is development-only.
+- It must never be enabled in production.
+- JSKIT rejects boot if `AUTH_DEV_BYPASS_ENABLED=true` while `NODE_ENV=production`.
+- The route only looks up an existing user. It does not create one.
+
+The environment variables are:
+
+```bash
+AUTH_DEV_BYPASS_ENABLED=true
+AUTH_DEV_BYPASS_SECRET=replace-this-with-a-local-dev-secret
+```
+
+When enabled outside production, the app exposes:
+
+```text
+POST /api/dev-auth/login-as
+```
+
+The request body must contain either:
+
+```json
+{ "userId": "7" }
+```
+
+or:
+
+```json
+{ "email": "ada@example.com" }
+```
+
+The response is intentionally small:
+
+```json
+{
+  "ok": true,
+  "userId": "7",
+  "username": "Ada Example",
+  "email": "ada@example.com"
+}
+```
+
+Behind the scenes, JSKIT creates the same HTTP-only auth cookies that the normal login flow would create. That means Playwright should not try to read raw tokens. It should bootstrap the session in the browser context, then navigate normally.
+
+One subtle point matters here:
+
+- `/api/dev-auth/login-as` is still an unsafe `POST`
+- JSKIT still expects a CSRF token
+- the browser can get that token from `/api/session`
+
+So the normal Playwright shape is:
+
+1. open a same-origin page first
+2. call `/api/session` to read `csrfToken`
+3. call `/api/dev-auth/login-as` with `credentials: "include"` and the `csrf-token` header
+4. navigate to the protected route and run the assertions
+
+For example:
+
+```ts
+await page.goto("/");
+
+await page.evaluate(async ({ email }) => {
+  const sessionResponse = await fetch("/api/session", {
+    credentials: "include"
+  });
+  if (!sessionResponse.ok) {
+    throw new Error(`Session bootstrap failed: ${sessionResponse.status}`);
+  }
+
+  const sessionPayload = await sessionResponse.json();
+  const csrfToken = String(sessionPayload?.csrfToken || "");
+  if (!csrfToken) {
+    throw new Error("Missing csrfToken from /api/session.");
+  }
+
+  const loginResponse = await fetch("/api/dev-auth/login-as", {
+    method: "POST",
+    credentials: "include",
+    headers: {
+      "content-type": "application/json",
+      "csrf-token": csrfToken
+    },
+    body: JSON.stringify({ email })
+  });
+
+  if (!loginResponse.ok) {
+    throw new Error(`Dev login failed: ${loginResponse.status} ${await loginResponse.text()}`);
+  }
+}, { email: "ada@example.com" });
+
+await page.goto("/w/acme/admin/contacts");
+```
+
+In practice, the preferred wrapper is:
+
+```bash
+npx jskit app verify-ui \
+  --command "npx playwright test tests/e2e/contacts.spec.ts -g filters" \
+  --feature "contacts filters" \
+  --auth-mode dev-auth-login-as
+```
+
+That flow is preferable to driving the real sign-in form in feature tests because it keeps the test focused on the UI feature being added, not on an external auth dependency. If a chunk changes user-facing UI and the flow requires login, the expected JSKIT review standard is:
+
+- use Playwright
+- record the run with `jskit app verify-ui`
+- use the local dev auth bypass or another local session bootstrap path
+- exercise the actual changed behavior, not only page load
+
 ## What appears in Supabase
 
 It is important to separate **Supabase auth data** from **JSKIT app-owned data**.

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

@@ -666,6 +666,7 @@ In the current CLI, that includes checks such as:
 - whether managed files recorded in the lock still exist
 - whether installed packages are still visible in the package registry
 - 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`
 
 That last check is narrower than it sounds. `doctor` is looking for the broken case in direct Vue templates, such as:
 
@@ -726,6 +727,24 @@ Good times to run it manually include:
 
 One important nuance: `doctor` is checking for broken JSKIT ownership and visibility, not trying to stop you from editing app-owned files. For example, a managed file that still exists but whose contents changed is normally fine. The problem is when JSKIT expects a managed file to exist and it is gone, or when the installed package state no longer resolves cleanly.
 
+There is one intentional exception now for user-facing UI work.
+
+If the current git working tree has changed UI files under the app's normal UI paths, `doctor` expects a matching `.jskit/verification/ui.json` receipt. The intended way to create that receipt is:
+
+```bash
+npx jskit app verify-ui \
+  --command "npx playwright test tests/e2e/contacts.spec.ts -g filters" \
+  --feature "contacts filters" \
+  --auth-mode dev-auth-login-as
+```
+
+That command does two things:
+
+- runs the targeted Playwright command you give it
+- writes a receipt describing the verified feature, auth mode, and current dirty UI file set
+
+`doctor` then compares the current changed UI files to that receipt. If you edit the UI again afterwards, the receipt is stale and `doctor` tells you to rerun `jskit app verify-ui`.
+
 ### Why `--json` exists
 
 If you want machine-readable output, use:

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

@@ -613,6 +613,57 @@ The safe mental model is:
 - use command runtimes for actions
 - keep the server as the source of truth for derived state
 
+### Choosing the right client request seam
+
+When you need client-side HTTP work in JSKIT, do not start with raw `fetch(...)`.
+
+Choose the highest-level runtime that matches the interaction:
+
+```js
+// 1. Button/toggle/small mutation
+const command = useCommand({ ... });
+
+// 2. List endpoint
+const list = useList({ ... });
+
+// 3. Single-record endpoint
+const view = useView({ ... });
+
+// 4. Form save flow
+const form = useAddEdit({ ... });
+
+// 5. Truly custom endpoint
+const resource = useEndpointResource({ ... });
+```
+
+Use the CRUD wrappers when they fit:
+
+- `useCrudList()` for routed CRUD lists
+- `useCrudView()` for routed CRUD record loading
+- `useCrudAddEdit()` for routed CRUD forms
+
+Why this is the standard JSKIT shape:
+
+- `useCommand()` resolves the correct scoped API path for the current route and surface.
+- The higher-level list, view, add/edit, and command runtimes send requests through the standard HTTP runtime instead of ad hoc request code.
+- The default client runtime uses `usersWebHttpClient`, which already handles credentials and CSRF token behavior.
+- `useEndpointResource()` gives the shared endpoint primitive for loading, saving, and standard load/save error handling. Higher-level runtimes like `useCommand()` and `useAddEdit()` layer UI feedback and field-error behavior on top of that primitive.
+
+If you need a custom scoped endpoint path outside the higher-level runtimes, prefer `usePaths().api(...)` rather than hand-building scoped URLs:
+
+```js
+const paths = usePaths();
+const reportsApiPath = computed(() => paths.api("/reports"));
+```
+
+The safe mental model is:
+
+- do not raw `fetch(...)` for normal app work
+- do not invent ad hoc local AJAX helpers
+- use the operation/runtime composable that matches the UI interaction
+- drop to `usersWebHttpClient.request(...)` only for exceptional low-level cases
+- use `usePaths().api(...)` when you need a custom scoped API path and the higher-level runtime does not already resolve it for you
+
 ### `_components/CrudAddEditForm.vue`
 
 This is the shared rendering shell for the add/edit form.
@@ -783,6 +834,75 @@ Usually nothing changes. The client can keep sending `q`.
 - Do not dump every text column into search just because you can.
 - In this tutorial CRUD, `notes` is a good example of a field you might leave out if you want fast, predictable list search.
 
+### Pattern 2B: repository mapping and computed output fields
+
+Do not treat the output schema as if it also defined database storage.
+
+In JSKIT CRUD:
+
+- the schema defines the API contract
+- `resource.fieldMeta` defines storage mapping
+- the repository runtime owns computed SQL projections
+
+Use these rules:
+
+- for explicit DB column overrides, use `repository.column`
+- for computed output fields, use `repository.storage: "virtual"`
+- do not put computed fields in create/patch write schemas
+
+Example field metadata:
+
+```js
+RESOURCE_FIELD_META.push({
+  key: "createdAt",
+  repository: {
+    column: "created_at"
+  }
+});
+
+RESOURCE_FIELD_META.push({
+  key: "remainingBatchWeight",
+  repository: {
+    storage: "virtual"
+  }
+});
+```
+
+Register the computed projection once in the repository runtime:
+
+```js
+const repositoryRuntime = createCrudResourceRuntime(resource, {
+  context: "receivals repository",
+  list: LIST_CONFIG,
+  virtualFields: {
+    remainingBatchWeight: {
+      applyProjection(dbQuery, { knex, tableName, alias }) {
+        const { sql, bindings } = getRemainingBatchWeightSqlParts({ tableName });
+        dbQuery.select(knex.raw(`${sql} as ??`, [...bindings, alias]));
+      }
+    }
+  }
+});
+```
+
+Once registered there:
+
+- generic CRUD `list`
+- generic CRUD `findById`
+- generic CRUD `listByIds`
+- generic CRUD `listByForeignIds`
+
+all pick up the projection automatically, so you should not hand-patch `clearSelect()` / re-select logic into each method.
+
+Important limits:
+
+- `virtual` fields are output-only in v1
+- fallback search derivation only uses column-backed fields
+- parent-filter fallback derivation only uses column-backed fields
+- `listByIds(..., { valueKey })` requires a column-backed `valueKey`
+
+For the agent-facing quick rule, see `patterns/crud-repository-mapping.md`.
+
 ### Pattern 3: structured list filters from one shared definition
 
 This is the default pattern once a CRUD list needs real filters.

package/package.json

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

package/patterns/INDEX.md

@@ -20,8 +20,14 @@ How to use it:
   - `crud-links.md`
 - live actions, checkbox, toggle, patch button, inline action, `useCommand()`
   - `live-actions.md`
+- ajax, fetch, API call, request, endpoint, HTTP client, `useList()`, `useView()`, `useAddEdit()`, `useEndpointResource()`, `usersWebHttpClient`
+  - `client-requests.md`
+- playwright, browser test, e2e, ui verification, authenticated ui test, test auth, dev login as, dev auth bypass
+  - `ui-testing.md`
 - filter, filters, search facets, chips, date range, enum filter, lookup filter, `useCrudListFilters`, `createCrudListFilters`
   - `filters.md`
+- fieldMeta, `repository.column`, computed field, virtual field, projection, `createCrudResourceRuntime`, `remainingBatchWeight`
+  - `crud-repository-mapping.md`
 
 ## Current Patterns
 
@@ -30,4 +36,7 @@ How to use it:
 - [child-cruds.md](./child-cruds.md)
 - [crud-links.md](./crud-links.md)
 - [live-actions.md](./live-actions.md)
+- [client-requests.md](./client-requests.md)
+- [ui-testing.md](./ui-testing.md)
 - [filters.md](./filters.md)
+- [crud-repository-mapping.md](./crud-repository-mapping.md)

package/patterns/client-requests.md

@@ -0,0 +1,56 @@
+# Client Request Patterns
+
+Use when:
+
+- deciding which JSKIT client function to use for HTTP work
+- custom endpoint reads or writes
+- AJAX questions
+- replacing raw `fetch(...)` calls
+- choosing between `useCommand()`, `useList()`, `useView()`, `useAddEdit()`, and `useEndpointResource()`
+
+Rules:
+
+- Prefer the highest-level JSKIT runtime that matches the UI interaction.
+- Do not hand-roll local AJAX helpers when an existing JSKIT runtime already fits.
+- Do not use raw `fetch(...)` for normal app work.
+- Use `usePaths().api(...)` for custom scoped API paths instead of concatenating route params into URLs by hand.
+- Drop to `usersWebHttpClient.request(...)` only for exceptional low-level cases.
+
+Choose the function like this:
+
+```js
+// 1. Button/toggle/small mutation
+const command = useCommand({ ... });
+
+// 2. List endpoint
+const list = useList({ ... });
+
+// 3. Single-record endpoint
+const view = useView({ ... });
+
+// 4. Form save flow
+const form = useAddEdit({ ... });
+
+// 5. Truly custom endpoint
+const resource = useEndpointResource({ ... });
+```
+
+Use the CRUD wrappers when they fit:
+
+- `useCrudList()` for routed CRUD lists
+- `useCrudView()` for routed CRUD record loading
+- `useCrudAddEdit()` for routed CRUD forms
+
+Why this is the standard JSKIT shape:
+
+- `useCommand()` resolves the scoped API path for the current route and surface.
+- The higher-level list, view, add/edit, and command runtimes send requests through the shared HTTP runtime.
+- `usersWebHttpClient` already handles credentials and CSRF behavior.
+- `useEndpointResource()` is the shared endpoint primitive for loading, saving, and standard load/save error handling. Higher-level runtimes add UI feedback and field-error handling on top.
+
+Avoid:
+
+- raw `fetch(...)` for standard page or component work
+- page-local HTTP helpers that duplicate JSKIT runtime seams
+- manually concatenating scoped route params into API URLs
+- using a lower-level seam when a higher-level routed CRUD or command runtime already fits

package/patterns/crud-repository-mapping.md

@@ -0,0 +1,81 @@
+# CRUD Repository Mapping
+
+Use when:
+- a CRUD resource needs explicit DB column mapping
+- a field should exist in API output but is not a real DB column
+- the user mentions computed fields, projections, or `remainingBatchWeight`
+
+Default JSKIT pattern:
+1. Treat the schema as the API contract only.
+2. Put persistence mapping in `resource.fieldMeta`.
+3. Use `repository.column` for explicit DB column overrides.
+4. Use `repository.storage: "virtual"` for computed output fields.
+5. Register computed SQL projections once in the repository runtime with `virtualFields`.
+6. Let generic CRUD read paths apply those projections automatically.
+
+Field meta rules:
+- for a normal override, write:
+
+```js
+RESOURCE_FIELD_META.push({
+  key: "createdAt",
+  repository: {
+    column: "created_at"
+  }
+});
+```
+
+- for a computed output field, write:
+
+```js
+RESOURCE_FIELD_META.push({
+  key: "remainingBatchWeight",
+  repository: {
+    storage: "virtual"
+  }
+});
+```
+
+- omit `repository` entirely when the field is column-backed and the default snake_case mapping is correct
+- `repository.storage: "virtual"` cannot also define `repository.column`
+- `repository.storage: "virtual"` fields must not appear in create/patch write schemas
+
+Repository pattern:
+- build the runtime with `createCrudResourceRuntime(resource, { ... })`
+- register computed projections in `virtualFields`
+- keep SQL in the repository, not in shared metadata
+
+Example:
+
+```js
+const repositoryRuntime = createCrudResourceRuntime(resource, {
+  context: "receivals repository",
+  list: LIST_CONFIG,
+  virtualFields: {
+    remainingBatchWeight: {
+      applyProjection(dbQuery, { knex, tableName, alias }) {
+        const { sql, bindings } = getRemainingBatchWeightSqlParts({ tableName });
+        dbQuery.select(knex.raw(`${sql} as ??`, [...bindings, alias]));
+      }
+    }
+  }
+});
+```
+
+What CRUD core now does for you:
+- default select columns include only column-backed output fields
+- `list`, `findById`, `listByIds`, and `listByForeignIds` apply registered virtual projections automatically
+- search and parent-filter fallback derivation only use column-backed fields
+- `listByIds(..., { valueKey })` requires that `valueKey` be column-backed
+
+Avoid:
+- manual `clearSelect()` / re-select hacks in individual repository methods just to add computed fields
+- putting SQL fragments or joins into shared `fieldMeta`
+- inventing `repository.storage` modes beyond the documented `virtual` contract
+
+Review checks:
+- schema defines contract, not storage
+- `fieldMeta.repository` owns mapping
+- computed fields use `repository.storage: "virtual"`
+- repository runtime registers matching `virtualFields`
+- no per-method projection duplication when generic CRUD reads already cover the field

package/patterns/ui-testing.md

@@ -0,0 +1,79 @@
+# UI Testing Pattern
+
+Use when:
+
+- deciding how to verify a new or changed user-facing screen
+- Playwright or browser-driven verification
+- authenticated UI flows
+- test auth, session bootstrap, dev login-as, or dev auth bypass
+
+Rules:
+
+- Any chunk that adds or changes user-facing UI must include a Playwright flow that exercises the changed behavior before the chunk is done.
+- Record that Playwright run with `jskit app verify-ui --command "<playwright command>" --feature "<label>" --auth-mode <mode>`.
+- `jskit doctor` expects `.jskit/verification/ui.json` to match the current dirty UI file set when UI files are changed.
+- Do not rely on a live external auth provider for Playwright verification of normal app features.
+- For authenticated UI in the standard JSKIT auth stack, use the development-only dev auth bypass route instead.
+- The standard route is `POST /api/dev-auth/login-as`.
+- The request body must include either `{ userId }` or `{ email }`.
+- The route is available only when `AUTH_DEV_BYPASS_ENABLED=true` and `AUTH_DEV_BYPASS_SECRET` is set outside production.
+- This route must never be enabled in production.
+- Because the route is an unsafe POST, fetch `csrfToken` from `/api/session` first and send it back as the `csrf-token` header.
+- Make the bootstrap request from the same browser context that will run the assertions so the auth cookies land in the page session.
+- Use stable seeded users or fixtures for Playwright. Do not depend on whatever account happens to exist in a developer's browser or external auth provider.
+
+Recommended flow:
+
+```bash
+npx jskit app verify-ui \
+  --command "npx playwright test tests/e2e/contacts.spec.ts -g filters" \
+  --feature "contacts filters" \
+  --auth-mode dev-auth-login-as
+```
+
+The Playwright command itself should follow this setup shape when login is needed:
+
+```ts
+await page.goto("/");
+
+await page.evaluate(async ({ email }) => {
+  const sessionResponse = await fetch("/api/session", {
+    credentials: "include"
+  });
+  if (!sessionResponse.ok) {
+    throw new Error(`Session bootstrap failed: ${sessionResponse.status}`);
+  }
+
+  const sessionPayload = await sessionResponse.json();
+  const csrfToken = String(sessionPayload?.csrfToken || "");
+  if (!csrfToken) {
+    throw new Error("Missing csrfToken from /api/session.");
+  }
+
+  const loginResponse = await fetch("/api/dev-auth/login-as", {
+    method: "POST",
+    credentials: "include",
+    headers: {
+      "content-type": "application/json",
+      "csrf-token": csrfToken
+    },
+    body: JSON.stringify({ email })
+  });
+
+  if (!loginResponse.ok) {
+    throw new Error(`Dev login failed: ${loginResponse.status} ${await loginResponse.text()}`);
+  }
+}, { email: "ada@example.com" });
+```
+
+After that bootstrap:
+
+- navigate to the protected page
+- exercise the new UI behavior
+- assert the actual outcome the chunk introduced
+
+Do not mark the chunk done if:
+
+- the feature changed user-facing UI but no Playwright flow ran
+- the Playwright flow skipped the changed behavior itself
+- authenticated UI work was left untested because no local auth bootstrap path was available and that gap was not called out

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

@@ -202,12 +202,19 @@ Exports
 - `loginResponseValidator`
 - `otpVerifyResponseValidator`
 - `oauthCompleteResponseValidator`
+- `devLoginAsResponseValidator`
 - `logoutResponseValidator`
 - `oauthProviderCatalogEntryValidator`
 - `sessionResponseValidator`
 - `sessionUnavailableResponseValidator`
 - `createCommandMessages({ fields = {}, defaultMessage = "Invalid value." } = {})`
 
+### `src/shared/commands/authDevLoginAsCommand.js`
+Exports
+- `AUTH_DEV_LOGIN_AS_MESSAGES`
+- `authDevLoginAsBodyValidator`
+- `authDevLoginAsCommand`
+
 ### `src/shared/commands/authLoginOAuthCompleteCommand.js`
 Exports
 - `authLoginOAuthCompleteBodyValidator`
@@ -300,6 +307,7 @@ Exports
 - `authLoginOtpVerifyCommand`
 - `authLoginOAuthStartCommand`
 - `authLoginOAuthCompleteCommand`
+- `authDevLoginAsCommand`
 - `authPasswordResetRequestCommand`
 - `authPasswordRecoveryCompleteCommand`
 - `authPasswordResetCommand`

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

@@ -26,7 +26,9 @@ Local functions
 
 ### `src/server/lib/actions/auth.contributor.js`
 Exports
-- `authActions`
+- `baseAuthActions`
+- `buildAuthActions({ includeDevLoginAs = false } = {})`
+- `devLoginAsAction`
 Local functions
 - `requireRequestContext(context, actionId)`
 
@@ -106,6 +108,30 @@ Exports
 Exports
 - `createAuthSessionEventsService()`
 
+### `src/server/lib/devAuthBootstrap.js`
+Exports
+- `assertDevAuthBootstrapConfig(config, { usersRepository = null } = {})`
+- `authenticateDevAuthRequest({ request, accessToken = "", refreshToken = "" }, { config, usersRepository = null } = {})`
+- `createDevAuthSession(profile, config)`
+- `ensureDevAuthBootstrapAvailable(config, request)`
+- `isDevAuthToken(token)`
+- `resolveDevAuthConfig({ enabled = false, secret = "", nodeEnv = "development", jwtAudience = "authenticated", accessTtlSeconds = DEFAULT_DEV_AUTH_ACCESS_TTL_SECONDS, refreshTtlSeconds = DEFAULT_DEV_AUTH_REFRESH_TTL_SECONDS } = {})`
+- `resolveDevAuthProfile(input = {}, { usersRepository = null, validationError } = {})`
+Local functions
+- `parseBoolean(value, fallback = false)`
+- `normalizePositiveInteger(value, fallback)`
+- `normalizeRequestHostname(request)`
+- `resolveDirectRemoteAddress(request)`
+- `normalizeLoopbackIp(value)`
+- `isLoopbackIp(value)`
+- `isLoopbackHostname(value)`
+- `isLocalDevAuthRequest(request)`
+- `stripDevAuthTokenPrefix(token)`
+- `buildProfileFromTokenClaims(payload)`
+- `resolveProfileFromTokenClaims(payload, { usersRepository = null } = {})`
+- `signDevAuthToken(kind, profile, config)`
+- `verifyDevAuthToken(token, kind, config)`
+
 ### `src/server/lib/flowGuards.js`
 Exports
 - `requireNoFieldErrors(parsed, validationError)`
@@ -117,7 +143,9 @@ Exports
 Exports
 - `createService`
 - `__testables`
-- `authActions`
+- `baseAuthActions`
+- `buildAuthActions`
+- `devLoginAsAction`
 
 ### `src/server/lib/oauthFlows.js`
 Exports
@@ -206,14 +234,18 @@ Exports
 - `AuthSupabaseServiceProvider`
 Local functions
 - `splitCsv(value)`
+- `parseBoolean(value, fallback = false)`
 - `normalizeRecord(value)`
 - `normalizeOAuthProviderConfigList(value)`
 - `resolveOAuthConfigFromAppConfig(appConfig)`
 - `resolveAllowedReturnToOrigins({ appConfig = {}, appPublicUrl = "" } = {})`
 - `resolveAuthProviderConfig(env, appConfig = {})`
 - `resolveAuthProfileMode(env)`
+- `isDevAuthBypassEnabledForRegistration(env)`
+- `isDevAuthBypassRequested(env)`
 - `createInMemoryUserSettingsRepository()`
 - `resolveCommonDependencies(scope)`
+- `resolveRuntimeEnv(scope)`
 - `resolveOptionalRepositories(scope)`
 
 ### root

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

@@ -217,7 +217,7 @@ Exports
 
 ### `src/server/routes/authRoutes.js`
 Exports
-- `buildRoutes(controller)`
+- `buildRoutes(controller, { includeDevLoginAs = false } = {})`
 
 ### `src/server/services/AuthWebService.js`
 Exports

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

@@ -70,7 +70,7 @@ Exports
 
 ### `src/server/createCrudRepositoryFromResource.js`
 Exports
-- `createCrudRepositoryFromResource(resource = {}, { context = "crudRepository", list = {} } = {})`
+- `createCrudRepositoryFromResource(resource = {}, { context = "crudRepository", list = {}, virtualFields = {} } = {})`
 
 ### `src/server/createCrudServiceFromResource.js`
 Exports
@@ -177,13 +177,13 @@ Local functions
 - `normalizeIncludePaths(include, { defaultInclude = DEFAULT_LOOKUP_INCLUDE } = {})`
 - `resolveChildIncludeFromPaths(paths = [])`
 - `buildLookupHydrationPlan(runtime = {}, include, { mode = "list", context = "crudRepository", includeWasExplicit = false, skippedNamespaces = new Set() } = {})`
-- `resolveLookupProviderResolver(repositoryOptions = {}, callOptions = {}, { context = "crudRepository" } = {})`
+- `resolveLookupResolver(repositoryOptions = {}, callOptions = {}, { context = "crudRepository" } = {})`
 - `resolveLookupDepthRuntime(runtime = {}, repositoryOptions = {}, callOptions = {})`
 - `buildLookupGroupKey(relation = {})`
 - `normalizeLookupRelationValues(records = [], entries = [], childIncludeByKey = {})`
 - `resolveGroupChildInclude(group = {})`
-- `normalizeLookupProvider(provider, relation = {}, { context = "crudRepository" } = {})`
-- `resolveLookupProviderOwnershipFilter(provider = {}, { context = "crudRepository" } = {})`
+- `normalizeLookup(provider, relation = {}, { context = "crudRepository" } = {})`
+- `resolveLookupOwnershipFilter(provider = {}, { context = "crudRepository" } = {})`
 - `resolveLookupVisibilityContext(provider = {}, relation = {}, callOptions = {}, { context = "crudRepository" } = {})`
 - `buildLookupRecordMap(records = [], valueKey = "")`
 - `buildLookupCollectionMap(records = [], foreignKey = "")`
@@ -193,21 +193,21 @@ Local functions
 Exports
 - `normalizeCrudLookupApiPath`
 - `normalizeCrudLookupNamespace`
-- `requireCrudLookupNamespace(value = "", { context = "crudLookupProvider" } = {})`
-- `resolveCrudLookupNamespaceFromRelation(relation = {}, { context = "crudLookupProvider" } = {})`
-- `resolveCrudLookupProviderToken(namespace = "", { context = "crudLookupProvider" } = {})`
+- `requireCrudLookupNamespace(value = "", { context = "crudLookup" } = {})`
+- `resolveCrudLookupNamespaceFromRelation(relation = {}, { context = "crudLookup" } = {})`
+- `resolveCrudLookupToken(namespace = "", { context = "crudLookup" } = {})`
 
-### `src/server/lookupProviders.js`
+### `src/server/lookups.js`
 Exports
-- `resolveCrudLookupProviderToken`
-- `createCrudLookupProviderResolver(scope, { context = "crudLookupProvider" } = {})`
-- `createCrudLookupProvider(repository, { context = "crudLookupProvider", ownershipFilter = "" } = {})`
+- `resolveCrudLookupToken`
+- `createCrudLookupResolver(scope, { context = "crudLookup" } = {})`
+- `createCrudLookup(repository, { context = "crudLookup", ownershipFilter = "" } = {})`
 Local functions
-- `normalizeLookupProviderOwnershipFilter(value, { context = "crudLookupProvider ownershipFilter" } = {})`
+- `normalizeLookupOwnershipFilter(value, { context = "crudLookup ownershipFilter" } = {})`
 
 ### `src/server/repositoryMethods.js`
 Exports
-- `createCrudRepositoryRuntime(resource = {}, { context = "crudRepository", list = {} } = {})`
+- `createCrudResourceRuntime(resource = {}, { context = "crudRepository", list = {}, virtualFields = {} } = {})`
 - `crudRepositoryList(runtime, knex, query = {}, repositoryOptions = {}, callOptions = {}, hooks = null)`
 - `crudRepositoryFindById(runtime, knex, recordId, repositoryOptions = {}, callOptions = {}, hooks = null)`
 - `crudRepositoryListByIds(runtime, knex, ids = [], repositoryOptions = {}, callOptions = {}, hooks = null)`
@@ -218,6 +218,8 @@ Exports
 Local functions
 - `requireCrudRecordId(value, { context = "crudRepository" } = {})`
 - `resolveRepositoryDefaults(resource = {}, repositoryMapping = {})`
+- `normalizeCrudVirtualFieldHandlers(virtualFields = {}, repositoryMapping = {}, { context = "crudRepository" } = {})`
+- `applyCrudRepositoryVirtualProjections(dbQuery, runtime = {}, { knex, tableName } = {})`
 - `normalizeSearchColumns(searchColumns = [], fallbackColumns = [])`
 - `normalizeListOrderDirection(value = LIST_ORDER_DIRECTION_ASC)`
 - `normalizeListOrderNulls(value = LIST_ORDER_NULLS_LAST)`
@@ -262,8 +264,9 @@ Exports
 - `buildWritePayload(sourcePayload = {}, fieldKeys = [], overrides = {})`
 - `resolveColumnName(fieldKey, overrides = {})`
 - `resolveCrudIdColumn(idColumn, { fallback = "id" } = {})`
-- `buildRepositoryColumnMetadata({ outputKeys = [], writeKeys = [], columnOverrides = {} } = {})`
+- `buildRepositoryColumnMetadata({ outputKeys = [], writeKeys = [], columnOverrides = {}, fieldStorageByKey = {} } = {})`
 Local functions
+- `resolveOptionalObjectSchemaProperties(schema, options = {})`
 - `requireObjectSchemaProperties(schema, { context = "crudRepository", schemaLabel = "schema" } = {})`
 - `normalizeResourceFieldMetaEntries(fieldMeta = [])`
 - `schemaIncludesStringType(schema = {})`
@@ -286,11 +289,14 @@ Local functions
 
 ### `src/shared/crudFieldMetaSupport.js`
 Exports
+- `CRUD_FIELD_REPOSITORY_STORAGE_COLUMN`
+- `CRUD_FIELD_REPOSITORY_STORAGE_VIRTUAL`
 - `CRUD_LOOKUP_FORM_CONTROL_AUTOCOMPLETE`
 - `CRUD_LOOKUP_FORM_CONTROL_SELECT`
 - `CRUD_RUNTIME_LOOKUPS_FIELD_KEY`
 - `checkCrudLookupFormControl(value, { context = "crud fieldMeta ui.formControl", defaultValue = CRUD_LOOKUP_FORM_CONTROL_AUTOCOMPLETE } = {})`
 - `isCrudRuntimeOutputOnlyFieldKey(value = "", { lookupContainerKey = CRUD_RUNTIME_LOOKUPS_FIELD_KEY } = {})`
+- `normalizeCrudFieldRepositoryConfig(fieldMetaEntry = {}, { context = "crud fieldMeta repository", fieldKey = "" } = {})`
 
 ### `src/shared/crudNamespaceSupport.js`
 Exports

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

@@ -28,6 +28,7 @@ Exports
 
 ### `src/server/cliRuntime/appState.js`
 Exports
+- `directoryLooksLikeJskitAppRoot(directoryPath)`
 - `resolveAppRootFromCwd(cwd)`
 - `loadAppPackageJson(appRoot)`
 - `createDefaultLock()`
@@ -41,8 +42,6 @@ Exports
 - `upsertEnvValue(content, key, value)`
 - `removeEnvValue(content, key, expectedValue, previous)`
 - `writeJsonFile`
-Local functions
-- `directoryLooksLikeJskitAppRoot(directoryPath)`
 
 ### `src/server/cliRuntime/capabilitySupport.js`
 Exports
@@ -379,6 +378,7 @@ Exports
 - `normalizeText(value = "")`
 - `isTruthyFlag(rawValue = "")`
 - `runExternalCommand(command, args = [], { cwd = "", env = {}, stdout, stderr, quiet = false, createCliError } = {})`
+- `runExternalShellCommand(commandText, { cwd = "", env = {}, stdout, stderr, quiet = false, createCliError } = {})`
 - `formatUtcReleaseTimestamp(date = new Date())`
 - `resolveLocalJskitBin(appRoot = "")`
 - `runLocalJskit(appRoot, args = [], { stdout, stderr, createCliError, quiet = false } = {})`
@@ -402,6 +402,10 @@ Local functions
 Exports
 - `runAppVerifyCommand(ctx = {}, { appRoot = "", options = {}, stdout, stderr })`
 
+### `src/server/commandHandlers/appCommands/verifyUi.js`
+Exports
+- `runAppVerifyUiCommand(ctx = {}, { appRoot = "", options = {}, stdout, stderr })`
+
 ### `src/server/commandHandlers/completion.js`
 Exports
 - `createCompletionCommands(ctx = {})`
@@ -672,6 +676,22 @@ Exports
 Local functions
 - `resolveCatalogPackagesPath()`
 
+### `src/server/shared/uiVerification.js`
+Exports
+- `UI_VERIFICATION_AUTH_MODES`
+- `UI_VERIFICATION_RECEIPT_RELATIVE_PATH`
+- `UI_VERIFICATION_RECEIPT_VERSION`
+- `UI_VERIFICATION_RUNNER`
+- `isUiVerificationAuthMode(value = "")`
+- `isUiVerificationPath(relativePath = "")`
+- `isValidUiVerificationReceipt(receipt)`
+- `normalizeUiVerificationReceipt(rawReceipt = {})`
+- `resolveChangedUiFilesFromGit(appRoot = "")`
+- `sortUniqueStrings(values = [])`
+Local functions
+- `normalizeText(value = "")`
+- `readGitPathList(appRoot = "", args = [])`
+
 ### bin
 
 ### `bin/jskit.js`

package/templates/app/AGENTS.md

@@ -22,6 +22,37 @@ Use these references on demand:
 - `node_modules/@jskit-ai/agent-docs/templates/WORKBOARD.md`
 - `node_modules/@jskit-ai/agent-docs/skills/jskit-review/SKILL.md` for review passes when your Codex environment supports packaged skills
 
+## Mandatory Start Gate
+
+Before any non-trivial change:
+
+1. Read this file and the workflow files above in the current turn. Do not rely on memory alone.
+2. If the task involves JSKIT UI, routing, surfaces, CRUDs, filters, placements, live actions, or similar implementation details, scan `node_modules/@jskit-ai/agent-docs/patterns/INDEX.md` and read the relevant pattern files before editing.
+3. For substantial or multi-chunk work, create or update `.jskit/WORKBOARD.md` before editing.
+4. Before editing, print a compact read receipt with:
+   - `Read receipt: ...`
+   - `Active chunk: ...`
+   - `Generator decision: ...`
+   - `Relevant patterns: ...`
+   - `Active rules from docs: ...`
+5. When files need to be created, prefer `jskit generate ...` over creating them from scratch, even if the generated output will need follow-up adaptation. If not using a generator, say why.
+6. Do not edit code until the read receipt is printed and the workboard step is complete when it applies.
+
+## Mandatory Done Gate
+
+Before calling a chunk done, report:
+
+- `Deslop review: ...`
+- `JSKIT review: ...`
+- `Material/Vuetify review: ...`
+- `Playwright: ...` for any chunk that adds or changes user-facing UI
+- `Verification: ...`
+- `Files changed: ...`
+- `Commands run: ...`
+- `Remaining unverified: ...`
+
+If a feature spans more than one chunk, repeat those passes on the whole changeset after the final chunk.
+
 Core rules:
 
 - Inspect the workspace before assuming a JSKIT app exists.
@@ -31,7 +62,6 @@ Core rules:
   - `Why this sticks: ...`
   - `Not doing: ...`
 - Keep that checkpoint compact. Do not expand it into a long preamble unless the developer asks for detail.
-- When a request involves JSKIT UI, routing, surfaces, CRUDs, filters, placements, live actions, or similar implementation details, scan `node_modules/@jskit-ai/agent-docs/patterns/INDEX.md` for matching keywords and read only the relevant pattern files.
 - Reuse existing JSKIT helpers and runtime seams before adding new local helpers.
 - A freshly scaffolded JSKIT app can still be in Stage 1. If the app was just created and platform decisions are not settled yet, continue with the initialize workflow before adding runtime packages.
 - Do not treat a missing `config.tenancyMode` line or an untouched minimal scaffold as a final tenancy decision.
@@ -42,8 +72,12 @@ Core rules:
 - Use the real env var names or option names instead of vague requests for "credentials". Values such as `DB_NAME`, `DB_USER`, `DB_PASSWORD`, `AUTH_SUPABASE_URL`, `AUTH_SUPABASE_PUBLISHABLE_KEY`, and `APP_PUBLIC_URL` are routine setup inputs when the relevant package stack needs them.
 - For CRUD chunks, ask the developer which operations are allowed, which fields belong in the list view if one exists, and the intended look of the view and edit/new forms before generating code.
 - Every user-facing screen must pass a Material Design and Vuetify quality review before the chunk is considered done.
+- Any chunk that adds or changes user-facing UI must include a Playwright check that exercises the changed behavior before the chunk is considered done.
+- Record that Playwright run with `jskit app verify-ui --command "<playwright command>" --feature "<label>" --auth-mode <mode>` so `jskit doctor` can verify the receipt.
+- If the UI flow requires login, use the app's development-only auth bypass or session bootstrap path instead of a live external auth login flow.
+- In JSKIT apps using the standard auth stack, that means enabling the dev auth bypass in development and using `POST /api/dev-auth/login-as` during Playwright setup.
+- If authenticated UI work has no usable local auth bootstrap path yet, treat that as a testability gap and call it out before the chunk can be considered complete.
 - Do not implement app features before the blueprint has the database, surfaces, ownership model, and route/screen plan written down.
-- For substantial or multi-chunk work, create or update `.jskit/WORKBOARD.md` as the per-request execution tracker.
 - Break planned work into reviewable chunks before implementing. One CRUD is usually one chunk, but auth/platform setup, shell work, and cross-cutting integrations can be their own chunks.
 - Do not move to the next chunk until the current chunk has passed implementation, deslop review, JSKIT best-practices review, Material Design/Vuetify review, and verification.
 - If a feature spans more than one chunk, run a final whole-changeset deslop pass, JSKIT pass, Material Design/Vuetify pass, and verification pass after the last chunk.

package/workflow/feature-delivery.md

@@ -22,7 +22,7 @@ For each chunk, follow this order:
 5. Deslop the chunk.
 6. Review the chunk against JSKIT reuse and best practices.
 7. Review user-facing screens against Material Design and Vuetify best practices, and improve any screens that do not meet that bar.
-8. Verify the chunk with the relevant commands, including Playwright for meaningful UI flows.
+8. Verify the chunk with the relevant commands. Any chunk that adds or changes user-facing UI must include a Playwright flow that exercises the changed behavior, and that run must be recorded with `jskit app verify-ui`.
 9. Update `.jskit/WORKBOARD.md` with status, commands run, and anything still unverified.
 10. Only then move to the next chunk.
 
@@ -59,5 +59,9 @@ After the last chunk:
 
 Playwright note:
 
-- When login is required, prefer a test-only impersonation or session bootstrap path over dependence on a live external auth provider.
+- When login is required, use a test-only auth bypass or session bootstrap path instead of dependence on a live external auth provider.
+- Record the run through `jskit app verify-ui --command "<playwright command>" --feature "<label>" --auth-mode <mode>` so `jskit doctor` can verify the receipt against the current changed UI files.
+- In the standard JSKIT auth stack, the default development path is `POST /api/dev-auth/login-as`, guarded by `AUTH_DEV_BYPASS_ENABLED=true` and `AUTH_DEV_BYPASS_SECRET=...`.
+- That route is development-only and must not be enabled in production.
+- Because it is still an unsafe POST, fetch `csrfToken` from `/api/session`, send it as the `csrf-token` header, and make the request in the same browser context that will run the Playwright assertions so the session cookies land in the page session.
 - If such a path does not exist yet, treat that as a testability gap and decide whether the chunk must add it before the feature is considered complete.

package/workflow/review.md

@@ -31,8 +31,11 @@ Before calling a chunk or a whole changeset done, review it in four passes:
 4. Verification review
    - run the smallest relevant verification commands for a chunk
    - run the widest relevant verification commands for a whole changeset
-   - include Playwright for meaningful user-facing flows
-   - if login is required, verify the chosen test-auth path or explicitly record that the lack of one is an open gap
+   - any added or changed user-facing UI must be exercised with Playwright
+   - that Playwright run should normally be recorded through `jskit app verify-ui`
+   - if login is required, use the chosen local test-auth path instead of live external auth
+   - in the standard JSKIT auth stack, prefer the development-only `POST /api/dev-auth/login-as` path
+   - if there is no usable local auth bootstrap path, explicitly record that as a blocking testability gap
    - note anything left unverified
 
 Minimum expectation: