@jskit-ai/agent-docs 0.1.88 → 0.1.91

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

@@ -974,7 +974,7 @@ The generated `playwright.config.mjs` is a thin delegate to `@jskit-ai/jskit-cli
 
 - without `PLAYWRIGHT_BASE_URL`, it builds the app and starts the local server on `http://127.0.0.1:4173`
 - with `PLAYWRIGHT_BASE_URL`, it uses that managed preview and does not start another server
-- with `JSKIT_PLAYWRIGHT_STORAGE_STATE`, it loads the supplied authenticated state into Playwright contexts
+- with `VIBE64_PLAYWRIGHT_STORAGE_STATE`, it loads the Vibe64-supplied authenticated state into Playwright contexts
 
 Tests should therefore navigate with relative paths such as `page.goto("/w/acme/admin/contacts")`.
 
@@ -1032,7 +1032,7 @@ A managed host authenticates outside the project browser context. It performs it
 
 ```bash
 PLAYWRIGHT_BASE_URL=https://managed-preview.example.test \
-JSKIT_PLAYWRIGHT_STORAGE_STATE=/secure/temp/playwright-state.json \
+VIBE64_PLAYWRIGHT_STORAGE_STATE=/secure/temp/playwright-state.json \
 playwright test tests/e2e/contacts.spec.ts
 ```
 

package/guide/agent/app-setup/database-layer.md

@@ -197,11 +197,15 @@ In JSKIT persistence code, **visibility** means "which rows should this request
 - `public`
   - the record is not scoped by owner columns
 - `workspace`
-  - the record belongs to one workspace, usually through `workspace_id`
+  - the record belongs to one workspace through the exact reserved column `workspace_id`
 - `user`
-  - the record belongs to one user, usually through `user_id`
+  - the record belongs to one user through the exact reserved column `user_id`
 - `workspace_user`
-  - the record belongs to one workspace and one user together
+  - the record belongs to one workspace and one user through both reserved columns
+
+Only `workspace_id` and `user_id` carry this standard ownership contract. Specifically named foreign keys such as `recipient_user_id`, `created_by_user_id`, and `assignee_user_id` describe domain relationships; they are not alternate owner columns. Keep both fields when a row has an owner and a separate related actor, and never rename the relationship to an owner column merely to make a tool accept the schema.
+
+The selected ownership filter must match the direct reserved columns exactly. A table with only `workspace_id` is `workspace`; a table with only `user_id` is `user`; and a table with both is `workspace_user`. A declaration cannot override or ignore either column.
 
 That is why the shared helpers exist. Repositories should not have to re-implement the same ownership rules by hand every time they filter a query or build an insert payload.
 

package/guide/agent/app-setup/initial-scaffolding.md

@@ -209,7 +209,7 @@ Published JSKIT libraries and tooling support Node.js 22 from 22.12.0 onward, No
 
 That matters because JSKIT maintenance policy changes over time. If the scaffold copied a large shell script into every app, existing apps would freeze the old behavior forever. By delegating to `jskit app verify`, `jskit app update-packages`, and `jskit app release`, the app keeps the nice `npm run` shortcuts while the maintained behavior stays in the installed CLI package.
 
-The Playwright scaffold follows the same rule. `playwright.config.mjs` delegates to `@jskit-ai/jskit-cli/test/playwright`, and the starter browser specs delegate their shared responsive checks to published JSKIT helpers. The generated files stay small while later JSKIT package updates can change local server startup, managed `PLAYWRIGHT_BASE_URL` handling, and `JSKIT_PLAYWRIGHT_STORAGE_STATE` support without copying that logic into each new app.
+The Playwright scaffold follows the same rule. `playwright.config.mjs` delegates to `@jskit-ai/jskit-cli/test/playwright`, and the starter browser specs delegate their shared responsive checks to published JSKIT helpers. The generated files stay small while later JSKIT package updates can change local server startup, managed `PLAYWRIGHT_BASE_URL` handling, and `VIBE64_PLAYWRIGHT_STORAGE_STATE` support without copying that logic into each new app.
 
 `jskit app verify` is worth noticing specifically. Linting, tests, and builds check your source code and runtime behavior. The JSKIT part of that flow runs `doctor`, which checks JSKIT-managed app state: installed package visibility, lock-file-backed managed files, and other JSKIT-specific health rules. It is there because a JSKIT app is not only code. It is also a descriptor-driven managed project.
 

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

@@ -804,7 +804,7 @@ 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
 
-The auth mode is receipt metadata, not an authentication implementation. `jskit app verify-ui` does not log a user in, inject a secret, or rewrite the Playwright context. A direct local run uses `loginAsExistingUser()` from `@jskit-ai/auth-web/test/playwright`; a managed runner supplies authenticated state through `JSKIT_PLAYWRIGHT_STORAGE_STATE`. The generated `playwright.config.mjs` consumes that state and honors `PLAYWRIGHT_BASE_URL` without starting a second server.
+The auth mode is receipt metadata, not an authentication implementation. `jskit app verify-ui` does not log a user in, inject a secret, or rewrite the Playwright context. A direct local run uses `loginAsExistingUser()` from `@jskit-ai/auth-web/test/playwright`; Vibe64 supplies authenticated state through `VIBE64_PLAYWRIGHT_STORAGE_STATE`. The generated `playwright.config.mjs` consumes that state and honors `PLAYWRIGHT_BASE_URL` without starting a second server.
 
 `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`.
 

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

@@ -33,7 +33,8 @@ npx jskit generate crud-server-generator scaffold \
   --namespace contacts \
   --surface admin \
   --ownership-filter workspace \
-  --table-name contacts
+  --table-name contacts \
+  --grant-role member
 
 npx jskit generate crud-ui-generator crud \
   w/[workspaceSlug]/admin/contacts \
@@ -140,6 +141,8 @@ So the distinction is:
 
 That is why `--internal` is not a permissions shortcut and not a UI setting. It is a server-route exposure choice on top of the same CRUD ownership model.
 
+The workspace role-grant decision is separate too. Every workspace-required generation must choose `--grant-role <role-id>` or `--no-role-grant`; there is no implicit role. An application that assigns generated CRUD permissions to `member` uses `--grant-role member`. In particular, `--internal` does not imply `--no-role-grant`.
+
 ### Ownership controls which owner columns are expected
 
 The repository layer ultimately applies visibility through the standard owner columns:
@@ -147,6 +150,12 @@ The repository layer ultimately applies visibility through the standard owner co
 - `workspace_id`
 - `user_id`
 
+Those names are exact and reserved. `workspace_id` is workspace ownership; `user_id` is user ownership; both together are workspace-user ownership. Other foreign keys such as `recipient_user_id`, `created_by_user_id`, and `assignee_user_id` remain domain relationships and must not be treated as ownership aliases.
+
+The generated ownership filter must match that exact set of reserved columns. Neither an explicit filter nor generated metadata can override what those direct columns mean.
+
+If a row is workspace-owned but refers to a recipient, keep both concepts explicit: use `workspace_id` for ownership and `recipient_user_id` for the relationship. Renaming the relationship to `user_id` would opt the field into JSKIT's hidden owner-field and user-filtering behavior.
+
 That means the generated CRUD behaves like this:
 
 - `public`

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

@@ -99,6 +99,27 @@ The supported values are:
 | `workspace` | rows belong to one workspace | `workspace_id` |
 | `workspace_user` | rows belong to one workspace and one user together | `workspace_id` and `user_id` |
 
+### Ownership column names are exact and reserved
+
+JSKIT ownership is explicit and materialized. Only these exact database columns carry the standard generated ownership contract:
+
+- `workspace_id`
+- `user_id`
+
+They are not ordinary foreign-key names. Generated CRUD infrastructure uses them for visibility filtering, create-time owner stamping, and hidden owner-field handling.
+
+Other foreign keys are domain relationships, even when their names end in `_user_id` or `_workspace_id`. For example:
+
+- `recipient_user_id` identifies a recipient
+- `created_by_user_id` records an author
+- `assignee_user_id` identifies an assignee
+
+Those fields do not become ownership aliases merely because they point to a user-owned table.
+
+The ownership filter must match the direct reserved columns exactly. A table with only `workspace_id` is `workspace`; one with only `user_id` is `user`; and one with both is `workspace_user`. Neither the CLI declaration nor generated metadata overrides those columns.
+
+Decide ownership first, select the matching ownership filter, and then model other actors with specifically named foreign keys. A workspace-owned notification outbox item that targets a user normally has `workspace_id` for ownership and `recipient_user_id` for the recipient relationship. Do not rename `recipient_user_id` to `user_id` merely to satisfy a generator or Doctor check; that would change the resource's ownership semantics.
+
 ### What each value means
 
 #### `public`
@@ -257,7 +278,8 @@ npx jskit generate crud-server-generator scaffold \
   --namespace contacts \
   --surface admin \
   --ownership-filter workspace \
-  --table-name contacts
+  --table-name contacts \
+  --grant-role member
 ```
 
 This creates an app-local package under `packages/contacts/`.
@@ -278,6 +300,46 @@ Use that when:
 
 Do **not** use `--internal` as a substitute for ownership or permissions design. It is only about whether the public HTTP CRUD routes exist.
 
+### Choose workspace role grants explicitly
+
+Workspace-required CRUD actions use the normal named permission ids:
+
+- `crud.<namespace>.list`
+- `crud.<namespace>.view`
+- `crud.<namespace>.create`
+- `crud.<namespace>.update`
+- `crud.<namespace>.delete`
+
+The generator never guesses which role should receive all five permissions. Every workspace-required CRUD command must choose one of these options:
+
+```bash
+--grant-role administrator
+```
+
+or:
+
+```bash
+--no-role-grant
+```
+
+`--grant-role` must name a configured role. `--no-role-grant` keeps the generated actions and their permission requirements but leaves the app's role catalog unchanged. The options are mutually exclusive.
+
+To assign the generated permissions to `member`, make that decision explicit:
+
+```bash
+--grant-role member
+```
+
+This decision is independent of `--internal`. For an internal, workspace-owned persistence resource whose generated actions should not be assigned to any actor role, use both:
+
+```bash
+--ownership-filter workspace \
+--internal \
+--no-role-grant
+```
+
+If neither explicit grant option is supplied, generation fails during preflight before writing files, even when a `member` role exists.
+
 Before generating anything, decide these with the developer:
 
 - which operations are allowed for this CRUD
@@ -420,7 +482,8 @@ npx jskit generate crud-server-generator scaffold \
   --namespace addresses \
   --surface admin \
   --ownership-filter workspace \
-  --table-name addresses
+  --table-name addresses \
+  --grant-role member
 ```
 
 Then install the generated local package:
@@ -596,7 +659,8 @@ npx jskit generate crud-server-generator scaffold \
   --namespace comments \
   --surface admin \
   --ownership-filter workspace \
-  --table-name comments
+  --table-name comments \
+  --grant-role member
 ```
 
 Then install the generated local package:

package/package.json

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

package/patterns/crud-scaffolding.md

@@ -24,6 +24,9 @@ Rules:
 - If `crud-server-generator` is going to own the CRUD, do not hand-write a separate CRUD migration for that table. The generator installs and manages the CRUD migration scaffold itself.
 - Do not scaffold CRUD UI, hand-build CRUD routes, or hand-build CRUD endpoints before the server CRUD package and shared resource file exist.
 - Treat the generated shared resource file as the canonical CRUD contract for later UI scaffolding and CRUD behavior changes.
+- Treat the exact columns `workspace_id` and `user_id` as reserved JSKIT ownership columns. They are the only standard columns used for generated ownership filtering and create-time owner stamping.
+- Treat other foreign keys such as `recipient_user_id`, `created_by_user_id`, `assignee_user_id`, and similarly specific names as domain relationships, not ownership aliases. Do not rename a relationship to `user_id` or `workspace_id` merely to satisfy tooling.
+- Require the resolved ownership filter to match the reserved columns exactly: neither the filter nor the schema may silently add or omit `workspace_id` or `user_id` ownership.
 - `feature-server-generator` is not the default lane for ordinary persisted entities. Use it for workflows or orchestration that sit on top of CRUD-owned tables, or for rare explicit non-CRUD exceptions.
 - 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.
@@ -41,6 +44,14 @@ Meaning of `--internal`:
 - it keeps the generated repository, service, actions, provider, resource, and CRUD migration ownership chain
 - it only suppresses public HTTP CRUD route registration
 - it is not a substitute for ownership columns or action/route permissions
+- it does not suppress generated action permission ids or decide which role receives them
+
+Workspace role grants:
+
+- every workspace-required CRUD generation must explicitly choose `--grant-role <role-id>` or `--no-role-grant`
+- applications that assign generated CRUD permissions to `member` must say `--grant-role member`; fixed-role applications must name one of their real roles or choose no automatic grant
+- `--grant-role` and `--no-role-grant` are permission-design choices independent of `--internal`
+- never invent a `member` role only to satisfy the generator
 
 When a weird-custom persistence lane is proposed:
 

package/patterns/ui-testing.md

@@ -16,7 +16,7 @@ Rules:
 - Generated `playwright.config.mjs` delegates to `@jskit-ai/jskit-cli/test/playwright`. Do not copy base-URL, web-server, or storage-state logic into app tests.
 - Use relative paths such as `page.goto("/home")`. The shared config owns the browser base URL.
 - A managed runner supplies `PLAYWRIGHT_BASE_URL`. When it is set, JSKIT does not start another app server.
-- A managed runner supplies an authenticated context through `JSKIT_PLAYWRIGHT_STORAGE_STATE`. Treat that file as a temporary secret: do not commit it, print it, or retain it after the run.
+- Vibe64 supplies an authenticated context through `VIBE64_PLAYWRIGHT_STORAGE_STATE`. Treat that file as a temporary secret: do not commit it, print it, or retain it after the run.
 - Do not install a browser when the environment provides a managed browser runner.
 
 ## Direct local authentication
@@ -61,7 +61,7 @@ A managed preview must not expose `AUTH_DEV_BYPASS_SECRET` to project code or fo
 
 ```bash
 PLAYWRIGHT_BASE_URL=https://managed-preview.example.test \
-JSKIT_PLAYWRIGHT_STORAGE_STATE=/secure/temp/playwright-state.json \
+VIBE64_PLAYWRIGHT_STORAGE_STATE=/secure/temp/playwright-state.json \
 playwright test tests/e2e/contacts.spec.ts
 ```
 

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

@@ -21,13 +21,16 @@ Exports
 - `resolveGenerationSnapshot({ appRoot, tableName, idColumnOption } = {})`
 - `renderCanonicalResourceFieldSchema(column, { fieldContractEntry = null } = {})`
 - `buildFieldContractEntries({ outputColumns = [], writableColumns = [], snapshot = {} } = {})`
-- `resolveCrudGenerationSurfaceId({ appRoot, options } = {})`
+- `resolveCrudGenerationSurfaceId({ appRoot, options, appConfig = null } = {})`
+- `prepareInstallHook({ appRoot, packageOptions = {} } = {})`
 - `__testables`
 Local functions
 - `resolveAllowedValues(schema = {}, fallbackValues = [])`
 - `resolveGlobalScaffoldCache()`
 - `asRecord(value)`
+- `resolveBooleanFlagOption(options = {}, optionName = "")`
 - `resolveInternalRouteOption(options = {})`
+- `resolveNoRoleGrantOption(options = {})`
 - `normalizeRequestedOwnershipFilter(value, { strict = false } = {})`
 - `inferOwnershipFilterFromSnapshot(snapshot)`
 - `assertOwnershipColumnsForFilter(snapshot, filter)`
@@ -36,7 +39,7 @@ Local functions
 - `loadEnvFromApp(appRoot)`
 - `createAppRequire(appRoot)`
 - `importModuleFromApp(appRequire, moduleId, contextLabel)`
-- `resolveCrudSurfaceRequiresWorkspace({ appRoot, options, surface = "" } = {})`
+- `resolveCrudSurfaceRequiresWorkspace({ appRoot, options, surface = "", appConfig = null } = {})`
 - `loadCrudAppConfig(appRoot = "")`
 - `resolveSurfaceDefinitions(appConfig = {})`
 - `resolveDefaultCrudSurfaceIdFromAppConfig(appConfig = {})`
@@ -84,8 +87,11 @@ Local functions
 - `normalizeFieldMetaUiOptions(rawOptions = [])`
 - `resolveEnumFieldMetaUiOptions(enumValues = [])`
 - `buildCrudPermissionIds(namespace = "")`
+- `resolveConfiguredRoleEntries(appConfig = {})`
+- `formatAvailableRoleIds(roleEntries = [])`
+- `resolveCrudPermissionGrantRole(appConfig = {}, options = {}, { requiresNamedPermissions = true } = {})`
 - `normalizeCrudOperation(operation = "", context = "CRUD operation")`
-- `renderRoleCatalogPermissionGrants(namespace = "", { requiresNamedPermissions = true } = {})`
+- `renderRoleCatalogPermissionGrants(namespace = "", { requiresNamedPermissions = true, grantRoleId = "" } = {})`
 - `renderActionPermissionSupport(namespace = "", { requiresNamedPermissions = true } = {})`
 - `renderActionPermissionExpression(operation = "", { requiresNamedPermissions = true } = {})`
 - `renderRouteWorkspaceSupportImports({ surfaceRequiresWorkspace = true } = {})`
@@ -96,7 +102,7 @@ Local functions
 - `renderObjectSchemaDefinition(lines = [], { mode = "patch" } = {})`
 - `renderActionInputExpressions({ surfaceRequiresWorkspace = true } = {})`
 - `renderRouteValidatorConstants({ surfaceRequiresWorkspace = true } = {})`
-- `buildReplacementsFromSnapshot({ namespace = "", snapshot, resolvedOwnershipFilter, surfaceRequiresWorkspace = true, surfaceId = "", routeInternal = false })`
+- `buildReplacementsFromSnapshot({ namespace = "", snapshot, resolvedOwnershipFilter, surfaceRequiresWorkspace = true, surfaceId = "", routeInternal = false, permissionGrantRoleId = "" })`
 - `resolveCrudGenerationTableName(options = {})`
 - `createCacheKey({ appRoot, options })`
 - `buildCrudTemplateContext(input = {})`

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

@@ -534,6 +534,27 @@ Local functions
 - `applyTextReplacements(sourceText = "", replacements = [])`
 - `collectCrudFormFieldCandidateFiles(appRoot = "")`
 
+### `src/server/commandHandlers/appCommands/previewIdentity.js`
+Exports
+- `PREVIEW_IDENTITY_PROTOCOL`
+- `executeJskitPreviewIdentityRequest(value = {}, { env = process.env, fetchImpl = globalThis.fetch } = {})`
+- `runAppPreviewIdentityCommand(_ctx = {}, { env = process.env, fetchImpl = globalThis.fetch, stdin = process.stdin, stdout = process.stdout } = {})`
+Local functions
+- `previewIdentityResponse(requestId = "", values = {})`
+- `previewIdentityFailure(requestId = "", error = {})`
+- `commandError(message = "", code = "jskit_preview_identity_failed", extra = {})`
+- `readInput(stream)`
+- `normalizeRequest(value = {})`
+- `identityFromSubject(subject = {})`
+- `responseSetCookie(response = {})`
+- `cookieHeader(setCookie = [])`
+- `responsePayload(response = {})`
+- `upstreamError(payload = {}, response = {}, extra = {})`
+- `postJson(fetchImpl, href, body, headers = {})`
+- `readSession(fetchImpl, targetOrigin, setCookie = [])`
+- `logout(fetchImpl, targetOrigin, session)`
+- `login(fetchImpl, targetOrigin, identity, secret, session)`
+
 ### `src/server/commandHandlers/appCommands/release.js`
 Exports
 - `runAppReleaseCommand(ctx = {}, { appRoot = "", options = {}, stdout, stderr })`