@jskit-ai/agent-docs 0.1.95 → 0.1.97

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

@@ -196,14 +196,14 @@ The most important parts look like this:
     "@jskit-ai/jskit-cli": "0.x",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
-    "eslint": "^9.39.4",
+    "eslint": "^10.8.0",
     "vite": "^8.0.16",
     "vitest": "^4.1.9"
   }
 }
 ```
 
-Published JSKIT libraries and tooling support Node.js 22 from 22.12.0 onward, Node.js 24, and Node.js 26. Newly generated applications deliberately require Node 26: their app-level `engines` contract, `.nvmrc`, and JSKIT-managed verification workflow all name that runtime. The app-level contract is the runtime boundary for the app and its installed JSKIT runtime packages, while independently consumed JSKIT CLI and tooling packages retain the wider supported range. The dependency on `@local/main` points at `file:packages/main`, which means your app already contains its own local JSKIT package. The maintenance scripts are also useful to notice early, because they show an important ownership boundary in JSKIT.
+Published JSKIT libraries and tooling support Node.js 22 from 22.13.0 onward, Node.js 24, and Node.js 26. Newly generated applications deliberately require Node 26: their app-level `engines` contract, `.nvmrc`, and JSKIT-managed verification workflow all name that runtime. The app-level contract is the runtime boundary for the app and its installed JSKIT runtime packages, while independently consumed JSKIT CLI and tooling packages retain the wider supported range. The dependency on `@local/main` points at `file:packages/main`, which means your app already contains its own local JSKIT package. The maintenance scripts are also useful to notice early, because they show an important ownership boundary in JSKIT.
 
 `verify`, `jskit:update`, and `release` are intentionally thin wrappers. They stay in `package.json` because they are convenient app-local shortcuts, but the real implementation lives in `jskit app ...`, not in copied scaffold scripts.
 

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

@@ -78,7 +78,7 @@ This gives you a clean ownership split:
 
 That split is worth keeping in mind through the rest of the guide. When you see `npm run verify`, read it as "run the app's JSKIT baseline verification policy, then any app-specific extra verification hook".
 
-The starter scaffold also includes `.github/workflows/jskit-verify.yml`. This is a JSKIT-managed projection, not a static template. Installed package descriptors can contribute CI environment values, services, and preparation steps through their top-level `ci` contract. Published JSKIT libraries and tooling support Node.js 22 from 22.12.0 onward, Node.js 24, and Node.js 26, while newly generated applications require Node 26. The managed workflow enforces that application runtime for dependency installation and verification. JSKIT composes the contributions and renders the workflow in this order: checkout, Node 26 setup, `npm ci`, package-contributed `before-verify` steps, and `npm run verify`.
+The starter scaffold also includes `.github/workflows/jskit-verify.yml`. This is a JSKIT-managed projection, not a static template. Installed package descriptors can contribute CI environment values, services, and preparation steps through their top-level `ci` contract. Published JSKIT libraries and tooling support Node.js 22 from 22.13.0 onward, Node.js 24, and Node.js 26, while newly generated applications require Node 26. The managed workflow enforces that application runtime for dependency installation and verification. JSKIT composes the contributions and renders the workflow in this order: checkout, Node 26 setup, `npm ci`, package-contributed `before-verify` steps, and `npm run verify`.
 
 For example, `database-runtime` contributes the `database-migrations` step. Its MySQL driver contributes a MariaDB service with `DB_CLIENT=mysql2`, while its Postgres driver contributes a Postgres service with `DB_CLIENT=pg`. Each driver supplies matching synthetic CI-only `DB_*` values; local `.env` values are never copied into the workflow.
 

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

@@ -230,6 +230,24 @@ w/[workspaceSlug]/admin/...
 
 then `workspace` is usually the normal default. If you are generating a CRUD for a global operator or account area, `public` or `user` may make more sense.
 
+## Schema contract for generated CRUD
+
+Generated CRUD tables use one single-column integer primary key, normally
+`id`. Each foreign key must also be single-column and must reference the target
+table's single-column primary key. Composite indexes remain useful for business
+uniqueness such as `(workspace_id, slug)`, but they are never relationship
+targets.
+
+Tenant isolation comes from a direct `workspace_id` and/or `user_id` ownership
+column, the exactly matching generated ownership filter, scoped service
+lookups, and cross-tenant tests. Do not encode ownership into a composite
+foreign key such as `(workspace_id, parent_id) -> (workspace_id, id)`.
+
+The generator rejects unsupported key shapes. If an approved application truly
+needs a different persistence model, record the durable decision in
+`.jskit/APP_BLUEPRINT.md` and use the explicit table-ownership exception path
+instead of modifying generated CRUD files.
+
 ## Example 1: `contacts`
 
 This is the baseline pattern. If you understand this example, the rest of the chapter becomes much easier.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.95",
+  "version": "0.1.97",
   "description": "Distributed JSKIT agent references, prompts, guides, and generated reference maps.",
   "type": "module",
   "files": [
@@ -14,7 +14,7 @@
     "test": "node --test"
   },
   "engines": {
-    "node": "^22.12.0 || ^24.0.0 || ^26.0.0"
+    "node": "^22.13.0 || ^24.0.0 || ^26.0.0"
   },
   "publishConfig": {
     "access": "public"

package/patterns/crud-scaffolding.md

@@ -14,9 +14,38 @@ Check first:
 - `jskit show crud-server-generator --details`
 - whether the request is server-only CRUD or server-plus-UI CRUD
 
+## Non-negotiable database contract
+
+Before database, schema, CRUD, repository, or persistence work, read this
+pattern completely. Use the database selected for this app's development
+runtime; never alter a production, legacy, historical, or other valuable
+database to develop or verify schema changes. Prove the complete migration
+chain against a fresh disposable database before reporting completion.
+
+For normal app-owned CRUD tables:
+
+- use exactly one non-null integer primary-key column, normally
+  `id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY`
+- make every foreign key single-column and point it directly to 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 select the ownership filter that matches those columns exactly
+- express tenant-safe relationships as direct ownership plus a normal
+  `parent_id -> parent.id` relationship; resolve related IDs through the
+  workspace-scoped service and test both allowed and cross-workspace cases
+
+Do not use composite primary keys or composite foreign keys to encode tenant
+ownership, target a business key from a foreign key, or duplicate parent
+identity when the related row ID already identifies it. Stop before generation
+if the proposed table violates these constraints.
+
 Rules:
 
-- For a CRUD-backed entity, start with `jskit generate crud-server-generator scaffold ...`.
+- For a CRUD-backed entity, create the validated table in the managed
+  development database first. Then make
+  `jskit generate crud-server-generator scaffold ...` the first JSKIT scaffold.
 - Unless the table is already owned by a JSKIT baseline package or is an explicit narrow exception recorded in `.jskit/table-ownership.json`, every persisted app-owned table must go through that server CRUD step first.
 - That server scaffold is the crucial first step even if no CRUD UI will be created yet.
 - If the table should already be CRUD-owned but should not expose public CRUD HTTP routes yet, scaffold it with `jskit generate crud-server-generator scaffold ... --internal` instead of dropping to direct knex or a hand-built pseudo-repository.
@@ -64,6 +93,19 @@ When a weird-custom persistence lane is proposed:
 - Record the exact approval and the approved exception in `.jskit/WORKBOARD.md` before coding.
 - If that exception changes the durable architecture rather than only the current chunk, record it in `.jskit/APP_BLUEPRINT.md` too.
 - Without that explicit approval record, do not take the weird-custom persistence path.
+- Record durable, approved schema exceptions in `.jskit/APP_BLUEPRINT.md` as
+  well as the table-ownership exception; an exception must not silently weaken
+  the normal generated CRUD contract.
+
+Before reporting completion:
+
+- verify there are no composite primary or foreign keys in the generated CRUD
+  tables
+- verify every generated CRUD foreign key targets a single-column primary key
+- apply the generated migrations from zero to a fresh disposable database
+- compare the recreated schema with the intended development schema
+- run positive and negative cross-workspace relationship tests where ownership
+  applies, then run JSKIT Doctor and the project's normal verifier
 
 Avoid:
 

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

@@ -68,6 +68,7 @@ Local functions
 - `renderJsonRestSearchSchemaLines(columns = [])`
 - `renderJsonRestDefaultSortLine(columns = [])`
 - `renderResourceDefaultSortLiteral(columns = [])`
+- `renderCurrentTimestampExpression(expression, column)`
 - `renderMigrationDefaultClause(column)`
 - `renderMigrationSpecificStringType(column, { tableCollation = "" } = {})`
 - `renderTemporalColumnBuilder(column, methodName)`

package/reference/autogen/packages/database-runtime-mysql.md

@@ -44,15 +44,19 @@ Local functions
 - `toBoolean(value)`
 - `toNullableNumber(value)`
 - `normalizeColumnDefault(value)`
+- `normalizeCurrentTimestampExpression(value)`
+- `normalizeOnUpdateExpression(value)`
 - `parseEnumValues(columnType = "")`
 - `resolveTypeKind(column)`
 - `normalizeColumn(row = {})`
 - `normalizePrimaryKeyColumns(rows = [])`
+- `normalizePrimaryKeyColumnsByTable(rows = [])`
 - `normalizeIndexes(rows = [])`
 - `normalizeForeignKeys(rows = [])`
 - `normalizeCheckConstraints(rows = [])`
 - `requireIdColumn(columns, idColumn)`
 - `requirePrimaryKeyContainsId(primaryKeyColumns, idColumn)`
+- `requireSupportedForeignKeys(foreignKeys, primaryKeyColumnsByTable)`
 
 ### root
 

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

@@ -353,6 +353,8 @@ Exports
 ### `templates/src/surfaces/admin/index.vue`
 Exports
 - None
+Local functions
+- `adminChildPath(suffix = "")`
 
 ### `templates/src/surfaces/admin/root.vue`
 Exports

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

@@ -465,7 +465,7 @@ Exports
 - `isSensitiveManagedTextRecord({ packageEntry = {}, record = {} } = {})`
 - `isSensitivePackageOption(packageEntry = {}, optionName = "")`
 - `isSensitiveTextMutation({ packageEntry = {}, mutation = {}, resolvedKey = "" } = {})`
-- `resolveSensitiveOptionEnvFallbacks({ packageEntry = {}, appRoot = "", optionInput = {}, readFileBufferIfExists } = {})`
+- `resolveSensitiveOptionEnvFallbacks({ packageEntry = {}, appRoot = "", optionInput = {}, readFileBufferIfExists, environment = process.env } = {})`
 - `sanitizeInstalledPackageRecordForLock(record = {}, packageEntry = {})`
 - `sanitizeLockSecretsForWrite(lock = {}, packageRegistry = null)`
 - `sanitizeManagedTextForLock(packageEntry = {}, managedText = {})`
@@ -550,8 +550,9 @@ Local functions
 - `cookieHeader(setCookie = [])`
 - `responsePayload(response = {})`
 - `upstreamError(payload = {}, response = {}, extra = {})`
+- `request(fetchImpl, href, options)`
 - `postJson(fetchImpl, href, body, headers = {})`
-- `readSession(fetchImpl, targetOrigin, setCookie = [])`
+- `readSession(fetchImpl, targetOrigin)`
 - `logout(fetchImpl, targetOrigin, session)`
 - `login(fetchImpl, targetOrigin, identity, secret, session)`
 

package/templates/app/AGENTS.md

@@ -7,4 +7,7 @@ Recommended references:
 - `node_modules/@jskit-ai/agent-docs/guide/agent/index.md`
 - `node_modules/@jskit-ai/agent-docs/patterns/INDEX.md`
 
+Before database, schema, CRUD, repository, or persistence work, read and follow
+`node_modules/@jskit-ai/agent-docs/patterns/crud-scaffolding.md`.
+
 Keep changes scoped to the user request and verify runtime behavior with tests or explicit checks.