@jskit-ai/agent-docs 0.1.283 → 0.1.284

package/skills/jskit/SKILL.md

@@ -43,13 +43,16 @@ manifests, migrations, tests, and runtime behaviour are the evidence.
 4. Load only relevant references:
    - [port guide](references/existing-application-migration.md) for existing apps.
    - [heuristics index](references/heuristics/INDEX.md) for recurring traps.
+   - Before code that reads or writes a database table, read
+     [data access](references/data-access.md) completely; for connections,
+     migrations and test databases, [database layer](references/database-layer.md).
    - Before writing server code, read [typed features](references/typed-features.md) and its heuristic; client code, [client features](references/client-features.md). `npm run lint` checks both.
    - [multi-homing](references/multi-homing.md) for workspaces or invitations.
    - [translation](references/translation.md) for languages, translated texts
      or error codes.
    - For creation, foundation patterns, or package selection, read
      [application operations](references/app-operations.md).
-   - Before database, schema, CRUD, repository, or persistence work, read
+   - Before schema, CRUD or screen work on a table, also read
      [CRUD operations](references/crud-operations.md) completely; for custom
      form actions, also [form actions](references/crud-form-actions.md).
    - For routes, placements, user-facing UI, or browser verification, read

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

@@ -96,7 +96,7 @@ normal order is:
 
 1. confirm the product resource, ownership, operations, and fields
 2. author a migration as normal application source
-3. author the shared resource contract through `resource-crud-core`
+3. define the table resource (`defineTableResource`) and, for screens, its CRUD contract (`defineCrudContract`)
 4. use framework APIs for standard repository/service/action/route mechanics
 5. author product-specific screens from the relevant UI pattern
 6. run migrations and direct verification

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

@@ -8,9 +8,14 @@ Take database, surface, access, ownership, operations, and fields from product
 intent and current source. Ask when a material choice is missing. Do not
 translate the work into generator options.
 
-Read the narrow package-owned pattern in the [bundled source pattern index](pattern-index.md): `crud/resource-contract` for the resource,
-`crud/json-api-resource-package` for the server, and `crud/crud-screen-set`
-for routed UI. Child-resource and row-policy patterns own those variations.
+Read the package-owned pattern in the [bundled source pattern index](pattern-index.md): `database/table-resource` for the table,
+`crud/crud-contract` for its HTTP surface,
+`crud/crud-feature-package` for the server, and `crud/crud-screen-set`
+for routed UI; the [row
+policies](heuristics/row-policies.md)
+and [child
+CRUDs](heuristics/child-cruds.md)
+heuristics cover those variations.
 
 Normal CRUD tables use one non-null integer primary key. Foreign keys are
 single-column; composite unique indexes are business constraints, not
@@ -20,26 +25,38 @@ Match visibility to real ownership and test allowed plus cross-owner cases.
 ## Author the resource normally
 
 1. Write an immutable app-owned migration.
-2. Define the shared resource contract through `defineCrudResource()`.
-3. Use `defineCrudJsonApiFeature()` for standard repository, service, action,
-   permission, resource-host, and route mechanics.
+2. Define the table resource with `defineTableResource()` and its HTTP surface
+   with `defineCrudContract()`, which names its `namespace`: the routes',
+   messages' and events' public name, never taken from the resource.
+3. Use `defineCrudFeature()` for standard table ownership, service, action,
+   permission, and route mechanics.
 4. Customize through `decorateRepository`, `decorateService`,
    `operationLifecycle`, and named `actions`; do not copy the standard CRUD
    repository/action/route stack.
 5. Build routed screens from the matching `http-web`/CRUD UI pattern.
 
-The resource is canonical for fields, operations, validation, transport,
-messages, and route parameters. Do not duplicate its schema or serializers.
+The table resource is canonical for fields, columns, ownership and search; the
+CRUD contract for operations, validation, transport, messages and route
+parameters. A contract shows and accepts only the fields its `fields` names (stored
+`createdAt` and `updatedAt` show without an entry; `createdAt: { output:
+false }` hides one), so a column added later stays out of every API until a
+contract names it. A CRUD feature's answers follow the same rule: an unnamed
+relationship is left out, and an included record shows only its id, its
+relation's `labelKey` and the fields the including contract lists in that
+field's `output.includeFields` (`{ breed: ["name"] }` in the list shows a
+record it links to, as deep as listed), never another contract's output.
+A package with a CRUD feature lists `crud.contracts` in its descriptor's
+`capabilities.requires`. Do not duplicate their schema or serializers.
 Prefer `useCrudListScreen()`, `useCrudViewScreen()`, and
 `useCrudAddEditScreen()`; use `useCommand()` or `useEndpointResource()` for
 non-standard operations.
 
 Add resource service methods with `decorateService`; expose commands such as
-`confirm`, `publish`, or `cancel` through named `actions`. With `operationLifecycle`, mutation `before`,
-`execute`, and `after` share one repository transaction, `execute` receives
-`standard(nextInput)`, and `afterCommit` follows commit. Repositories persist;
-services and hooks orchestrate. Use a transactional outbox for durable
-external work.
+`confirm` or `cancel` through named `actions`. With `operationLifecycle`, mutation `before`,
+`execute`, and `after` share one transaction, rerun on deadlock, so they touch
+only the database; `execute` receives `standard(nextInput)`. Outside effects go
+in `afterCommit`, run once after commit, or an outbox when durable.
+Repositories persist; services and hooks orchestrate.
 
 ## Choose ownership, API access and client access independently
 
@@ -47,37 +64,31 @@ These controls answer different questions:
 
 | Control | Purpose | Public records | Owner-scoped records |
 | --- | --- | --- | --- |
-| Resource `autofilter` | Which rows belong to the request scope | `"public"`; no ownership column | `"user"`; real non-null `userId` column |
-| Resource `apiAccess` | Who may call the API | `"public"` | `"authenticated"` |
-| Feature `ownershipFilter` | Server route/action ownership scope | `"public"` | `"user"` |
+| Table resource `ownership` | Which rows belong to the request scope | `"public"`; no ownership column | `"user"`; real non-null `userId` column |
+| CRUD contract `apiAccess` | Who may call the API | `"public"` | `"authenticated"` |
+| Feature route visibility | Server route/action scope: the table's `ownership` unless the feature names `visibility` | `"public"` | `"user"` |
 | Client `access` | Whether to require bootstrap permissions | Default `"auto"` with no permission requirements | Default `"auto"`; declare permissions when required |
 
-`access` accepts `auto`, `always`, or `never`, not `public`. With `auto`, a
-screen with no permission requirements does not require a permissions bootstrap.
-`always` does require it. Do not add authentication or workspace machinery to
-compensate for an unnecessary `always` override. Server access and ownership
+`access` accepts `auto`, `always`, or `never`, not `public`. `auto` requires a
+permissions bootstrap only for a screen with permission requirements; `always`
+always does. Do not add authentication or workspace machinery to
+make up for an unneeded `always` override. Server access and ownership
 remain authoritative.
 
-The Books source patterns demonstrate user ownership. For an intentionally
-public create/list resource, use the same patterns with this resource contract:
+The Books source patterns show user ownership. For a public create/list
+resource, use them with this table resource and CRUD contract:
 
 ```js
-const bookResource = defineCrudResource({
-  namespace: "books",
+const bookResource = defineTableResource({
+  name: "books",
   tableName: "books",
-  apiAccess: "public",
-  autofilter: "public",
-  crudOperations: ["list", "view", "create"],
+  ownership: "public",
   schema: {
     title: {
       type: "string",
       required: true,
       minLength: 1,
-      maxLength: 255,
-      operations: {
-        output: { required: true },
-        create: { required: true }
-      }
+      maxLength: 255
     }
   },
   searchSchema: {
@@ -90,20 +101,27 @@ const bookResource = defineCrudResource({
     }
   }
 });
+
+const bookCrud = defineCrudContract(bookResource, {
+  namespace: "books",
+  apiAccess: "public",
+  operations: ["list", "view", "create"],
+  fields: { title: { output: "required", create: "required" } }
+});
 ```
 
-Import `defineCrudResource` from
-`@jskit-ai/resource-crud-core/shared/crudResource`. Its app-owned migration
-creates `books` with an integer primary key `id` and non-null `title`; omit
-`userId` and its foreign key for this public variant. `list` requires `view`
-in the shared resource contract, even when the UI has no detail page. A create
-response uses the resource output contract. Keep operation names such as
-`list`, `view` and `create`; do not invent output-operation aliases.
-
-Bind `defineCrudJsonApiFeature()` with this resource, `ownershipFilter:
-"public"`, `relativePath: "/books"` and the application's configured public
-surface. Keep the existing package/provider and migration registration from
-`crud/json-api-resource-package`.
+Import `defineTableResource` from `@jskit-ai/resource-core/shared/tableResource`
+and `defineCrudContract` from `@jskit-ai/resource-crud-core/shared/crudContract`.
+Its migration creates `books` with an integer `id` and non-null `title`; omit
+`userId` and its foreign key.
+`list` requires `view` in the CRUD contract, even when the UI has no detail
+page. A create response uses the CRUD contract's output. Keep operation names
+such as `list`, `view` and `create`; do not invent output-operation aliases.
+
+Bind `defineCrudFeature()` with `crud: bookCrud`, `relativePath: "/books"`
+and the application's configured public surface; the table's `"public"`
+ownership makes its routes public. Keep the existing package/provider and migration registration from
+`crud/crud-feature-package`.
 
 For the list, keep `BookListPage.vue` thin: use `resourceNamespace: "books"`
 in `useCrudListScreen()` on the configured public surface, remove unsupported