@jskit-ai/agent-docs 0.1.131 → 0.1.133

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

@@ -1,67 +1,82 @@
 # Application operations
 
-Read this for app creation, CLI discovery, packages, and generators.
+Read this for establishing an application foundation, selecting package
+capabilities, and realizing product features from JSKIT patterns.
 
-## Create an application
+## Establish a new application
 
-Confirm the name and tenancy mode:
+Start with an initialized Git repository and a clear product request. Use the
+request, current source, and ordinary project documentation. Ask the user for
+any material missing product decision before writing application source. Do
+not run a JSKIT questionnaire and do not create a temporary scaffold app.
 
-```bash
-npx @jskit-ai/create-app <app-name> --tenancy-mode <tenancy-mode>
-cd <app-name>
-npm install
+Read the generated pattern index:
+
+```text
+node_modules/@jskit-ai/agent-docs/reference/autogen/PATTERN_INDEX.md
 ```
 
-Generated apps require Node.js 26. Use `--target . --force` only to promote a
-known JSKIT `ai-seed`, never to overwrite an arbitrary app. `--minimal` is for
-deliberately bare package-development or unusual integrations. Follow the
-generated `AGENTS.md`.
+For a browser product, inspect one foundation:
+
+- `app/shell-foundation` for the normal adaptive application shell
+- `app/minimal-foundation` when the product deliberately does not need that
+  shell yet
+
+Inspect the complete pattern before copying. Copy or author the useful files
+directly into the existing project. Preserve `.git` plus all unrelated project
+and agent context. Resolve every real destination collision explicitly.
+Rename the concrete example application in ordinary source and metadata.
 
-After the first install, use `npx --no-install jskit ...`; a missing local CLI
-must fail instead of silently fetching another version. Do not add auth, users,
-workspaces, console, sample data, or another database adapter unless requested.
+The copied files immediately belong to the application. Do not add pattern
+receipts, generator provenance, completion ledgers, or hidden operation state.
 
-## Fresh minimal database CRUD order
+## Install and compose capabilities
 
-Use this order exactly: create-app, install, add the database runtime, install,
-create the live table in a fresh disposable development database, generate the
-server CRUD, install, then generate the UI.
+Plan the complete capability set before changing dependencies. Use the package
+catalogue and package-owned patterns to identify the required runtime packages,
+configuration, resources, and public APIs. Add one coherent package closure,
+then run `npm install` once for that planned change.
+
+Install the explicitly selected top-level packages through npm. Use one
+installation for the planned closure so npm can resolve their ordinary package
+dependencies together:
 
 ```bash
-npx @jskit-ai/create-app notes \
-  --target . --force --tenancy-mode none --minimal
-npm install
-npx --no-install jskit add package database-runtime-mysql
-npm install
-# Create/select a fresh disposable database and create its live `notes` table.
-npx --no-install jskit generate crud-server-generator scaffold \
-  --namespace notes \
-  --surface home \
-  --ownership-filter public \
-  --access public \
-  --table-name notes
-npm install
-npx --no-install jskit generate crud-ui-generator crud notes \
-  --resource-file packages/notes/src/shared/noteResource.js \
-  --id-param noteId \
-  --display-fields title,body \
-  --parent-title contextual \
-  --navigation-role primary \
-  --delete-confirmation
+npm install --save-exact @jskit-ai/<selected-package>@latest [...]
 ```
 
-The server generator owns its dependency closure. Do not pre-install
-`shell-web` as a placement workaround.
-
-## Select and apply technology
-
-- Discover with `npx --no-install jskit list` and
-  `npx --no-install jskit show <id> --details`.
-- Install runtime capability with `npx --no-install jskit add package <id>`;
-  inspect a bundle before adding it.
-- Run tooling with `npx --no-install jskit generate <generator> <action> ...`;
-  do not install generators as runtime packages.
-- JSKIT owns app mutations, npm owns dependency installation, and
-  `npm run db:migrate` owns database migration execution.
-- Continue only at documented app-owned seams. Prefer the narrowest existing
-  package or generator over a parallel local framework.
+Review the resulting `package.json` and lockfile as ordinary source changes.
+The installed package graph supplies runtime providers, migrations, patterns,
+and public APIs directly; no JSKIT synchronization or mutation command follows
+the npm installation.
+
+Do not add auth, users, workspaces, console, sample data, databases, or AI
+capabilities unless the product choice requires them.
+
+## Author database-backed CRUD
+
+Use a chosen database pattern plus a package-owned CRUD resource pattern. The
+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`
+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
+
+The database connection and schema are runtime evidence, not a questionnaire
+that owns source generation. Never patch fields into generated ASTs and never
+mark a resource valid because a generator once wrote it.
+
+## Verify current state
+
+Run verification against source, package graph, migrations, and
+runtime behavior. Runtime startup owns the capability/provider graph,
+loadability, ids, environment, and configuration. Builds own client imports;
+migration status and disposable rebuilds own schema state. App lint, tests,
+audit, browser checks, and CI own security, runtimes, and behavior.
+
+There is no supported `jskit doctor` command. Old CLI authoring-history
+warnings do not describe AI-first apps. Diagnose current contracts; never add
+metadata to satisfy an old tool.

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

@@ -1,92 +1,55 @@
 # CRUD operations
 
-Read this completely before database, schema, CRUD, repository, or persistence
-work.
-
-## Establish the contract
-
-Take the database adapter, surface, access, and ownership from the request and
-app authority. Inspect only a generator whose exact lane or option values are
-missing, or whose supplied command failed:
-
-```bash
-npx --no-install jskit show crud-server-generator --details
-npx --no-install jskit show crud-ui-generator --details
-```
-
-Never run these merely to reconfirm caller-supplied facts.
-
-Normal app-owned CRUD tables use one non-null integer primary key. Every
-foreign key is single-column and targets that key; multi-column unique indexes
-are business constraints, never relationship targets. Only direct
-`workspace_id` and `user_id` columns are generated ownership. Names such as
-`recipient_user_id` are domain relationships. Match the ownership filter to
-the reserved columns exactly, and test allowed plus cross-workspace cases.
-Stop before generation when these contracts disagree.
-
-## Conventional one-table CRUD
-
-Create the validated table first in a fresh disposable development database;
-the server generator reads its live shape:
-
-```bash
-npx --no-install jskit generate crud-server-generator scaffold \
-  --namespace <resource> \
-  --surface <surface> \
-  --ownership-filter <public|user|workspace|workspace_user> \
-  --access <public|authenticated> \
-  --table-name <table>
-```
-
-Use public access only on a non-workspace surface with public ownership. A
-workspace CRUD chooses exactly one of `--grant-role <role>` or
-`--no-role-grant`; never invent a role. `--internal` keeps the generated
-repository/service/resource ownership chain but suppresses public HTTP routes.
-
-Run `npm install`, then generate UI from the exact shared resource:
-
-```bash
-npx --no-install jskit generate crud-ui-generator crud \
-  <pages-root>/<plural-route> \
-  --resource-file packages/<namespace>/src/shared/<singular>Resource.js \
-  --parent-title contextual
-```
-
-The target is relative to `src/pages/`, starts with the selected surface's
-nonempty configured `pagesRoot` (for example `home/books`), and has no leading
-slash. For a surface deliberately configured with an empty root, use
-only the plural route. Use the exact singular resource filename emitted by the server generator; do not guess it.
-
-That resource is canonical. Do not hand-build routes, validators, HTTP helpers,
-or UI before it exists. Prefer `useCrudListScreen()`, `useCrudViewScreen()`, and
-`useCrudAddEditScreen()` for routed screens; the corresponding `useCrud*()`
-composables for routed behavior; and `useList()`, `useView()`, `useAddEdit()`,
-`useCommand()`, or `useEndpointResource()` for non-standard contracts. Standard
-CRUD derives JSON:API transport from the resource—never use raw `fetch()`.
-
-## Generated record deletion
-
-Request ordinary routed deletion explicitly:
-
-```bash
-npx --no-install jskit generate crud-ui-generator crud notes \
-  --resource-file packages/notes/src/shared/noteResource.js \
-  --id-param noteId \
-  --display-fields title,body \
-  --parent-title contextual \
-  --navigation-role primary \
-  --delete-confirmation
-```
-
-`--delete-confirmation` requires generated list and view pages and a shared
-resource with a `DELETE` operation. It supports a custom `--id-param` and fails
-clearly when the contract is unsupported. The view uses the public
-`CrudViewScreen` `actions` slot, `CrudDeleteAction`, and
-`useCrudDeleteAction()`. The shared component owns the Cancel/Delete dialog;
-`useCommand()` owns pending/error state and the resource request; success
-invalidates the CRUD list and navigates there. Import the public client runtime
-from `@jskit-ai/http-web`; do not inspect package-private code, add a page
-transport, or use raw `fetch()`.
+Read this before database, schema, CRUD, repository, or persistence work.
+
+## Establish the product contract
+
+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 from the generated index:
+`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.
+
+Normal CRUD tables use one non-null integer primary key. Foreign keys are
+single-column; composite unique indexes are business constraints, not
+identities. Only direct `workspace_id` and `user_id` columns imply ownership.
+Match visibility to real ownership and test allowed plus cross-owner cases.
+
+## Author the resource normally
+
+For a conventional resource:
+
+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.
+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.
+Prefer `useCrudListScreen()`, `useCrudViewScreen()`, and
+`useCrudAddEditScreen()`; use `useCommand()` or `useEndpointResource()` for
+non-standard operations.
+
+Additional resource service methods are normal. Add them 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 them. Durable external work uses a transactional
+outbox.
+
+## Record deletion
+
+Deletion requires an explicit shared `DELETE` operation and confirmation
+decision. Use `CrudDeleteAction` and `useCrudDeleteAction()` through the view
+actions slot; do not rebuild their confirmation, request, invalidation, and
+navigation flow.
 
 ## Strict temporal values
 
@@ -96,26 +59,15 @@ With `json-rest-schema` 1.0.17, temporal resource values are strings:
 - `time`: offset-free `HH:MM[:SS[.fraction]]`
 - `dateTime`: RFC 3339 with seconds and `Z` or a numeric offset
 
-Do not pass JavaScript `Date` objects through resource validation; convert at
-the boundary (normally `toISOString()` for `dateTime`). Numeric epochs use
-`epochMilliseconds` or `epochSeconds`. Honor `temporalPrecision` without
-silently truncating fractions. Generated CRUD
-serializes supported database temporal output; custom repositories must return
-strict strings and write ISO/RFC 3339 strings themselves.
+Convert JavaScript `Date` objects at the boundary, normally with
+`toISOString()`. Numeric epochs use `epochMilliseconds` or `epochSeconds`.
+Honor `temporalPrecision`; repositories return strict strings.
 
 ## Migration ownership
 
-Never compete with or alter a generator-owned baseline migration. Later schema
-changes are immutable additive migrations owned by the app-local package:
-
-```bash
-npx --no-install jskit create migration --package <package-id> --id <id>
-npx --no-install jskit migrations sync
-npm run db:migrate
-```
+Migrations are immutable application source owned with their resource. Never make a live table or a generator the sole source of truth. Schema inspection is for adoption and diagnosis, not compulsory authoring.
 
-An exceptional persistence lane requires explicit developer approval recorded
-in `.jskit/WORKBOARD.md` and `.jskit/table-ownership.json`, plus
-`.jskit/APP_BLUEPRINT.md` when architectural. Before sign-off, rebuild from
-zero in a fresh disposable database, compare schema, test ownership boundaries,
-run Doctor, and run the verifier.
+Before sign-off, rebuild from zero in a fresh disposable database, compare the
+schema, test ownership boundaries and failure cases, and run current-state
+verification. Do not create a workboard entry, ownership receipt, generation
+record, or historical proof that tooling ran.

package/skills/jskit/references/material-3.md

@@ -18,7 +18,7 @@ An established JSKIT prop or component wins over generic Material advice.
 
 Use this order:
 
-1. Reuse the JSKIT package, generator, shared screen, shell, placement, or
+1. Reuse the JSKIT package, source pattern, shared screen, shell, placement, or
    high-level composable that owns the behavior.
 2. Use the matching Vuetify component and its public props, variants, slots,
    density, responsive, theme, and accessibility behavior.

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

@@ -5,69 +5,66 @@ verification.
 
 ## Pages, surfaces, and placements
 
-Take the surface from the request/app authority; it controls routes, access,
-placement visibility, and often ownership. For a normal non-CRUD page:
+Take the surface and navigation role from the request, product context, and
+current app. They control routes, access, placement visibility, and often
+ownership. Inspect `app/shell-foundation` plus the narrow UI pattern that
+matches the requested outcome before authoring source.
 
-```bash
-npx --no-install jskit show ui-generator --details
-npx --no-install jskit list-placements
-npx --no-install jskit generate ui-generator page <route-file> --name <name>
-```
-
-Choose the truthful `--navigation-role`. Override with semantic
-`--link-placement <area.slot>` when needed; use concrete placements only for
-diagnosis. Let the generator create the route and placement before adapting
-app-owned output. State why before hand-writing a normal page.
+Create route files and placement declarations as normal application code.
+Use semantic placement ids and shell public helpers; use concrete outlet ids
+only when defining or diagnosing topology. Resolve current dynamic parameters
+to an absolute URL or route object for sibling/child links—never bind a route
+template or relative string raw to Vue Router `to`.
 
-## App-owned files
+## Application-owned files
 
-App-owned generated files are customizable. Adapt infrastructure tests in place.
-When replacing a starter route, update its smoke
-test to the new canonical route instead of deleting baseline browser coverage.
-Doctor must continue to report a missing managed test.
+Pattern source is ordinary customizable application source. When replacing a
+starter route, adapt its smoke test to the new canonical route instead of
+discarding browser coverage. Do not retain a generated-file marker, template
+hash, pattern receipt, or tool-owned source declaration.
 
 ## Screen behavior
 
 - Keep screens phone/task-first with drawer-independent primary actions and
-  48 px targets. Use a page header and direct `v-sheet`, not nested cards.
-- Provide named loading, empty, error, permission, and retry states. Generated
-  lists use searchable compact cards and medium/expanded tables where suitable.
-- Extend shared CRUD screens through slots. For custom sibling/child links,
-  resolve current dynamic params with their runtime to an absolute URL/route
-  object; never bind its route-template/relative string raw to Vue Router `to`.
-- Use page-local row-action/filter definitions. Keep read failures local; use
-  `useCommand()` or `useUiFeedback()` for user-triggered action feedback.
-- Import neutral request, operation, permission, and generated CRUD UI APIs from
-  `@jskit-ai/http-web`. Do not install `users-web` unless the application uses
-  account, profile, or user-specific shell UI.
+  at least 48 CSS-pixel targets.
+- Use a page header and direct surfaces instead of needless nested cards.
+- Render all meaningful loading, empty, error, permission, and retry states.
+- Use structure-matching Material skeletons for visible loading; never use a
+  generic spinner or circular progress indicator.
+- Keep read failures local when the screen cannot render. Present transient
+  command success/failure through shared toast/snackbar feedback so the page
+  does not jump.
+- Extend shared CRUD screens through public slots and composables.
+- Keep row actions and filters near the screen unless the framework owns them.
+- Import neutral request and CRUD UI APIs from `@jskit-ai/http-web`. Install
+  `users-web` only for actual account/profile/user UI.
 
 ## Adaptive shell drawer
 
 Use Vuetify Material navigation. Compact close dismisses the temporary drawer;
 wide layouts default to `desktopDrawerClosedMode="rail"`. Use `hidden` only
-with another navigation affordance.
+when another navigation affordance remains.
 
 The drawer omits the app bar's surface label. Open and rail icons share a
-centreline. It uses a 12px outer item inset; `navigationItemSpacing` (12px)
-controls icon/label and label/end gaps. The 80px rail centres 48px targets; set
-`railWidth` (for example, `64`) for a denser rail or `drawerWidth` for a fixed
-drawer. The wrapper forwards these props; never override its CSS.
-
-Existing apps: commit work and run `npm run jskit:update`. Keep and adapt
-the app-owned shell wrapper and smoke test; do not copy or delete them.
+centreline. It uses a 12px outer item inset; `navigationItemSpacing` controls
+icon/label and label/end gaps. The normal 80px rail centres 48px targets;
+`railWidth` and `drawerWidth` are public density/width controls. Do not override
+the shell's private implementation CSS.
 
 ## Browser verification
 
 Exercise user-facing changes with Playwright at compact, medium, and expanded
 widths. Check overflow, clipped text, duplicate navigation, route placement,
-actions, and target sizes. Use relative URLs; shared JSKIT config owns base URL,
-server, and storage state. With `PLAYWRIGHT_BASE_URL`, start no server. Never
-print/commit `VIBE64_PLAYWRIGHT_STORAGE_STATE`, use a local bypass with it, or
-install a browser when a managed runner supplies one.
-
-For explicitly enabled direct-local auth, use `loginAsExistingUser()` from
-`@jskit-ai/auth-web/test/playwright`; never expose its secret to browser code,
-URLs, or client env. Run the focused test directly:
+actions, skeleton replacement, error feedback, and target sizes. Use relative
+URLs. When `PLAYWRIGHT_BASE_URL` is provided, start no duplicate server.
+
+Vibe64 owns its managed browser and may provide
+`VIBE64_PLAYWRIGHT_STORAGE_STATE`; never print or commit that value, bypass it,
+or install another browser. For explicitly enabled direct-local auth, use
+`loginAsExistingUser()` from `@jskit-ai/auth-web/test/playwright`; never expose
+the exchange secret to browser code, URLs, or client environment.
+
+Run the narrow test directly:
 
 ```bash
 npx playwright test <test-file> -g "<changed behavior>"

package/templates/app/AGENTS.md

@@ -1,6 +1,7 @@
 # App Agent Instructions
 
-Use the JSKIT agent docs and the local app scaffold as the source of truth for app work.
+Use current project context, JSKIT public APIs, and the installed JSKIT pattern
+index as the source of truth for application work.
 
 Recommended references:
 
@@ -8,6 +9,9 @@ Recommended references:
 - `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`.
+the relevant package-owned pattern listed in
+`node_modules/@jskit-ai/agent-docs/reference/autogen/PATTERN_INDEX.md`.
 
-Keep changes scoped to the user request and verify runtime behavior with tests or explicit checks.
+Copied pattern source is ordinary application source. Do not add generator
+provenance, receipts, completion ledgers, or tooling-operation history. Keep
+changes scoped to the user request and verify runtime behavior directly.