@jskit-ai/agent-docs 0.1.22 → 0.1.23

package/package.json

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

package/patterns/crud-scaffolding.md

@@ -17,14 +17,17 @@ Check first:
 Rules:
 
 - For a CRUD-backed entity, start with `jskit generate crud-server-generator 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.
 - Create the real table directly in the database before scaffolding. `crud-server-generator` reads the live table shape.
 - 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.
+- `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.
 
 Avoid:
 
 - writing a hand migration for a CRUD table that JSKIT CRUD scaffolding is supposed to own
 - starting with `crud-ui-generator` before the server scaffold exists
 - hand-building CRUD routes or validators that duplicate the generated server resource contract
+- letting a new app-owned table exist in the live database without either generated CRUD ownership or a documented `.jskit/table-ownership.json` exception

package/templates/app/AGENTS.md

@@ -71,8 +71,12 @@ Core rules:
 - For baseline package setup, ask plainly for the exact local development values needed for the next install step, but only for the modules or packages that are actually selected.
 - 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, creating the server CRUD with `jskit generate crud-server-generator scaffold ...` is the crucial first step even if no CRUD UI will be created yet.
+- Unless a 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 have its own server CRUD package created first with `jskit generate crud-server-generator scaffold ...`, even if no CRUD UI will ever exist.
+- Treat that as a hard invariant, not a style preference. If a persisted app-owned table does not have generated CRUD ownership, `jskit doctor` is expected to fail.
 - For a CRUD table that `crud-server-generator` will own, do not hand-write a separate migration. Create the real table directly in the database first, then scaffold the server CRUD so JSKIT can install and manage the CRUD migration scaffold itself.
 - Do not generate CRUD UI or hand-build CRUD routes before the server CRUD package and shared resource file exist.
+- `feature-server-generator` is for workflows, orchestration, and other non-CRUD server features. Do not use it as the starting point for ordinary persisted entity tables.
+- Keep direct knex minimal and exceptional. Outside generated CRUD packages and explicit weird-custom feature lanes, app-owned runtime code should use internal `json-rest-api` seams instead of talking to knex directly.
 - 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.

package/workflow/feature-delivery.md

@@ -33,11 +33,12 @@ For CRUD chunks:
 
 1. Decide the table shape first.
 2. Create the real table directly in the database before scaffolding. `crud-server-generator` reads the live table shape; it does not invent the table for you.
-3. If `crud-server-generator` is going to own the CRUD schema, do not hand-write a separate migration for that CRUD table. The server generator installs and manages the CRUD migration scaffold itself.
-4. Scaffold the server side first with `crud-server-generator`, even if no CRUD UI will be created yet.
-5. Only after the shared resource file exists, scaffold the client side against that resource.
-6. Treat that shared resource file as the canonical CRUD definition. Put field and ownership changes there instead of hand-duplicating derived CRUD validators elsewhere.
-7. Do not guess CRUD operations or screen shape. Ask the developer:
+3. Unless the table is already owned by a JSKIT baseline package or is a narrow explicit exception recorded in `.jskit/table-ownership.json`, every persisted app-owned table must have a server CRUD package. Do not let a new table exist without that ownership decision.
+4. If `crud-server-generator` is going to own the CRUD schema, do not hand-write a separate migration for that CRUD table. The server generator installs and manages the CRUD migration scaffold itself.
+5. Scaffold the server side first with `crud-server-generator`, even if no CRUD UI will be created yet.
+6. Only after the shared resource file exists, scaffold the client side against that resource.
+7. Treat that shared resource file as the canonical CRUD definition. Put field and ownership changes there instead of hand-duplicating derived CRUD validators elsewhere.
+8. Do not guess CRUD operations or screen shape. Ask the developer:
    - which operations are allowed
    - which fields belong in the list view if one exists
    - what the view form should look like
@@ -50,10 +51,12 @@ During implementation:
 - Ask only about overrides, restrictions, or app-specific additions to packaged baseline workflows.
 - Use generated CRUD/UI scaffolds only after the route and ownership model are decided.
 - Do not hand-build CRUD routes, CRUD endpoints, or CRUD page trees before `crud-server-generator` has created the server package and shared resource file.
+- `feature-server-generator` is for non-CRUD workflows and orchestration. Do not use it as the first persistence lane for ordinary entity tables.
 - For app-owned non-CRUD route pages, default to `jskit generate ui-generator page ...` instead of hand-writing both `src/pages/...` and `src/placement.js`.
 - Before hand-writing a route page or placement entry, check `jskit show ui-generator --details` and `jskit list-placements`.
 - If `ui-generator page` applies and you still choose not to use it, stop and explain the exact gap before coding.
 - Keep runtime, UI, and data concerns separated.
+- Keep direct knex exceptional and minimal. Outside generated CRUD packages and explicit weird-custom feature lanes, app-owned runtime code should stay on internal `json-rest-api` seams.
 - Avoid “while I’m here” scope creep unless it is required for correctness.
 - Do not turn a small placeholder or route stub into a copy-polish or blueprint-rewrite task unless the developer asked for that broader work.
 

package/workflow/review.md

@@ -23,6 +23,8 @@ Before calling a chunk or a whole changeset done, review it in four passes:
    - if a generator existed, was the exact `jskit` command used or was the gap documented clearly before hand-coding?
    - for CRUD work, was `crud-server-generator scaffold` used before any CRUD UI or CRUD route hand-coding?
    - for CRUD tables owned by JSKIT, did the change avoid a separate hand-written CRUD migration?
+   - does every live app-owned table now have either declared generated/package CRUD ownership or an explicit narrow `.jskit/table-ownership.json` exception?
+   - is any direct app-owned knex usage limited to generated CRUD packages or explicit weird-custom feature lanes?
    - are surface, route, ownership, and migration choices aligned with JSKIT conventions?
    - package metadata and actual behavior still aligned?
 3. UI standards review

package/workflow/scoping.md

@@ -33,6 +33,7 @@ Scoping rules:
 - Make the generator plan concrete. Name the exact `jskit` commands expected for the chunk, not just a package or a general idea.
 - For non-CRUD route page work, check `jskit show ui-generator --details` and `jskit list-placements` before deciding that custom page or placement code is necessary.
 - For CRUD work, make the server-first plan explicit. Name the exact `jskit generate crud-server-generator scaffold ...` command before any CRUD UI plan.
+- Before accepting a new persisted app-owned table, decide whether it is CRUD-owned or a narrow explicit exception. If it is not already owned by a JSKIT baseline package, the default answer should be server CRUD ownership.
 - If a CRUD will be owned by `crud-server-generator`, plan around a real table that already exists in the database. Do not plan a separate hand-written CRUD migration for that table.
 - Decide ownership early; do not treat it as a UI-only detail.
 - If Stage 1 platform choices are still provisional, finish them before installing tenancy-sensitive runtime packages.