@jskit-ai/agent-docs 0.1.21 → 0.1.23

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

@@ -14,17 +14,63 @@ npm install
 
 The first command creates a new folder called `exampleapp` and fills it with JSKIT's base shell template. The `exampleapp` name is used in a few template replacements, such as the package name and the browser title. The `--tenancy-mode none` flag tells JSKIT to start with the smallest routing model. In this mode, the app is not workspace-aware (more of this later in the guide, when multihoming is introduced). That keeps the first scaffold easier to read because there is no workspace slug handling yet.
 
-If you are working with an AI agent and want the agent to explain the platform options after the scaffold exists, there is also a safe guided path:
+If you are working with an AI agent and want the agent to drive the initial JSKIT setup conversation, there is now a dedicated seed path:
 
 ```bash
-npx @jskit-ai/create-app exampleapp
+npx @jskit-ai/create-app exampleapp --template ai-seed
 cd exampleapp
+```
+
+That seed writes only `AGENTS.md`. It is not a runnable app yet. The agent should use that file to ask the Stage 1 platform questions first, make sure the chosen MySQL or Postgres database already exists or can be created with the developer's local admin access, and then promote the same directory into the real scaffold with:
+
+```bash
+npx @jskit-ai/create-app exampleapp --target . --force --tenancy-mode <mode>
 npm install
 ```
 
-That produces the same minimal scaffold shape, but without writing an explicit `config.tenancyMode` line yet. The important rule is that this does **not** mean tenancy is already decided. Before installing tenancy-sensitive packages such as `workspaces-core` or `workspaces-web`, the agent still needs to finish the Stage 1 platform conversation and then write the chosen tenancy into `config/public.js`. If workspace packages are installed while the app is still effectively on `none`, you fall into the recovery path described later in the multi-homing chapter.
+After that promotion, the overwritten app `AGENTS.md` becomes the source of truth for the normal JSKIT workflow.
+
+After creating the real app scaffolding (the base shell, not the seed wrapper), you will need to run `npm install` to install dependencies.
+
+If you already know you want a small non-workspace baseline right after the scaffold, this is the shortest reproducible path:
+
+```bash
+SUPABASE_URL=...
+SUPABASE_KEY=...
+DB_HOST=127.0.0.1
+DB_PORT=3306
+DB_NAME=exampleapp
+DB_USER=...
+DB_PASSWORD=...
+
+npx @jskit-ai/create-app exampleapp --tenancy-mode none
+cd exampleapp
+npm install
+
+npx jskit add package shell-web
+
+npx jskit add package auth-provider-supabase-core \
+  --auth-supabase-url "$SUPABASE_URL" \
+  --auth-supabase-publishable-key "$SUPABASE_KEY" \
+  --app-public-url "http://localhost:5173"
+
+npx jskit add bundle auth-base
+
+npx jskit add package database-runtime-mysql \
+  --db-host "$DB_HOST" \
+  --db-port "$DB_PORT" \
+  --db-name "$DB_NAME" \
+  --db-user "$DB_USER" \
+  --db-password "$DB_PASSWORD"
+
+npx jskit add package users-web
+npx jskit add package console-web
+
+npm install
+npm run db:migrate
+```
 
-After creating the scaffolding (which comes with a package.json file), you will need to run `npm install` to install dependencies.
+If you want the larger workspace-enabled stack with the first assistant already configured, use [Quickstart](/guide/app-setup/quickstart) instead.
 
 **Try Bash Completion!**
 

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

@@ -41,6 +41,8 @@ DB_USER=...
 DB_PASSWORD=...
 ```
 
+Before continuing, make sure the MySQL database already exists and that the chosen `DB_USER` / `DB_PASSWORD` can connect to it. If the database does not exist yet, create it first or use a local MySQL account with enough privileges to create it before the runtime install step.
+
 Then run the exact sequence below:
 
 ```bash

package/package.json

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

package/patterns/INDEX.md

@@ -14,8 +14,12 @@ How to use it:
   - `placements.md`
 - surfaces, app/admin/home/console, "which surface", route ownership, placement visibility
   - `surfaces.md`
+- page, route page, placeholder page, screen stub, menu-linked page, `ui-generator page`, `list-placements`
+  - `page-scaffolding.md`
 - child crud, nested crud, embedded list, subroute, separate page, parent/child layout
   - `child-cruds.md`
+- crud scaffold, crud server, crud ui, table creation, migrations, `crud-server-generator`, `crud-ui-generator`
+  - `crud-scaffolding.md`
 - CRUD links, record placeholders, `paths.page()`, `resolveViewUrl`, `resolveEditUrl`, `resolveParams`
   - `crud-links.md`
 - `definePage`, redirect, child redirect, settings landing, `redirectToChild`
@@ -37,7 +41,9 @@ How to use it:
 
 - [placements.md](./placements.md)
 - [surfaces.md](./surfaces.md)
+- [page-scaffolding.md](./page-scaffolding.md)
 - [child-cruds.md](./child-cruds.md)
+- [crud-scaffolding.md](./crud-scaffolding.md)
 - [crud-links.md](./crud-links.md)
 - [page-redirects.md](./page-redirects.md)
 - [live-actions.md](./live-actions.md)

package/patterns/crud-scaffolding.md

@@ -0,0 +1,33 @@
+# CRUD Scaffolding Patterns
+
+Use when:
+
+- creating a new CRUD-backed entity
+- deciding how to create a CRUD table
+- deciding whether to scaffold server first or UI first
+- deciding whether a CRUD needs a migration, a generator, or both
+
+Check first:
+
+- the intended ownership model
+- the real database table shape
+- `jskit show crud-server-generator --details`
+- whether the request is server-only CRUD or server-plus-UI CRUD
+
+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/patterns/page-scaffolding.md

@@ -0,0 +1,30 @@
+# Page Scaffolding Patterns
+
+Use when:
+
+- adding a non-CRUD route page
+- adding a placeholder page or screen stub
+- adding a menu-linked page
+- deciding whether a page and its link should be generated or hand-written
+
+Check first:
+
+- the blueprint route family and chosen surface
+- `jskit show ui-generator --details`
+- `jskit list-placements`
+- the nearest existing routed host under `src/pages`
+
+Rules:
+
+- Default to `jskit generate ui-generator page ...` for a new app-owned non-CRUD route page.
+- Let the generator create both the page file and the matching `src/placement.js` entry, then adapt the generated output if needed.
+- If the page link belongs in a non-default outlet, discover the outlet first with `jskit list-placements` and pass `--link-placement`.
+- If the page sits under an existing routed host, check whether `ui-generator page` can infer the correct child placement before writing a custom link by hand.
+- If you do not use `ui-generator page`, state exactly why the generator does not fit before editing code.
+- For a small placeholder route inside an existing route family, update the workboard rather than rewriting the blueprint unless the durable route or surface plan changed.
+
+Avoid:
+
+- hand-writing both `src/pages/...` and `src/placement.js` for a normal non-CRUD page before checking `ui-generator`
+- treating a small page stub as permission to rewrite marketing copy, route architecture, or blueprint scope
+- claiming that no generator exists without checking the actual `jskit` generator inventory first

package/templates/APP_BLUEPRINT.md

@@ -69,6 +69,7 @@ Chunk notes:
 
 - One CRUD is usually one chunk.
 - Platform/auth/shell work may be its own chunk.
+- Prefer vertical slices that produce visible or end-to-end progress the developer can inspect.
 - Each chunk must be independently reviewable and testable.
 
 ## Verification

package/templates/app/AGENTS.md

@@ -32,10 +32,10 @@ Before any non-trivial change:
 4. Before editing, print a compact read receipt with:
    - `Read receipt: ...`
    - `Active chunk: ...`
-   - `Generator decision: ...`
+   - `Generator decision: ...` with the exact `jskit` command to run, or the exact generator/placement discovery commands checked and why no generator applies
    - `Relevant patterns: ...`
    - `Active rules from docs: ...`
-5. When files need to be created, prefer `jskit generate ...` over creating them from scratch, even if the generated output will need follow-up adaptation. If not using a generator, say why.
+5. When files need to be created, prefer `jskit generate ...` over creating them from scratch, even if the generated output will need follow-up adaptation. For a new non-CRUD route page or menu-linked screen, default to `jskit generate ui-generator page ...`. If not using a generator, say why.
 6. Do not edit code until the read receipt is printed and the workboard step is complete when it applies.
 
 ## Mandatory Done Gate
@@ -70,6 +70,13 @@ Core rules:
 - Example: if the app is workspace-capable and uses `workspaces-core` plus `workspaces-web`, assume the standard workspace invite flow is part of the baseline package behavior.
 - 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.
@@ -78,7 +85,10 @@ Core rules:
 - In JSKIT apps using the standard auth stack, that means enabling the dev auth bypass in development and using `POST /api/dev-auth/login-as` during Playwright setup.
 - If authenticated UI work has no usable local auth bootstrap path yet, treat that as a testability gap and call it out before the chunk can be considered complete.
 - Do not implement app features before the blueprint has the database, surfaces, ownership model, and route/screen plan written down.
+- Plan implementation work as vertical slices. Each chunk should deliver a user-visible or end-to-end outcome that the developer can recognize in the app or behavior, not just an isolated layer change.
+- Do not churn `.jskit/APP_BLUEPRINT.md` for a small placeholder page or route stub that fits an existing route family unless the durable route/surface plan actually changed. Track request-level movement in `.jskit/WORKBOARD.md` instead.
 - Break planned work into reviewable chunks before implementing. One CRUD is usually one chunk, but auth/platform setup, shell work, and cross-cutting integrations can be their own chunks.
+- Avoid horizontal chunk plans like "all migrations first", "all routes next", or "all UI last" unless platform setup truly forces that order. Prefer slices the developer can inspect as real progress.
 - Do not move to the next chunk until the current chunk has passed implementation, deslop review, JSKIT best-practices review, Material Design/Vuetify review, and verification.
 - If a feature spans more than one chunk, run a final whole-changeset deslop pass, JSKIT pass, Material Design/Vuetify pass, and verification pass after the last chunk.
 - Prefer a fresh review agent for chunk and whole-changeset review when the runtime supports delegation.

package/workflow/bootstrap.md

@@ -40,6 +40,8 @@ Ask setup values plainly:
 - Only ask for setup values that correspond to the modules or packages already chosen for the baseline.
 - When the next package install needs concrete local development values, ask for them directly using the exact env var names or option names.
 - Do not hide behind vague requests for "credentials" or "values after that boundary".
+- If MySQL or Postgres is selected, confirm that the target database already exists before the runtime install, or that the developer has enough local admin or create-database access to create it now.
+- Do not proceed as if `DB_NAME` alone means the database is ready. The actual database must exist before the database runtime install and migration flow can be treated as valid.
 - In this workflow, these are routine setup inputs:
   - If the MySQL runtime is selected: `DB_NAME`, `DB_USER`, `DB_PASSWORD`
   - If the MySQL host or port differs from the local default `127.0.0.1:3306`: `DB_HOST`, `DB_PORT`

package/workflow/feature-delivery.md

@@ -7,7 +7,9 @@ Chunk rules:
 - One CRUD is usually one chunk.
 - Platform setup, shell/navigation, and cross-cutting integrations may be separate chunks.
 - A chunk must be independently reviewable and testable.
+- Prefer vertical slices. A chunk should usually produce a user-visible or end-to-end outcome, not just a hidden layer-only milestone.
 - If a chunk is too broad to review confidently, split it before coding.
+- Avoid horizontal plans like "database first, then routes, then UI" unless the work is foundational platform setup that genuinely cannot be sliced vertically yet.
 
 For each chunk, follow this order:
 
@@ -18,6 +20,7 @@ For each chunk, follow this order:
    - generator scaffolding
    - custom local code
    - or a combination
+   Record the exact `jskit` commands that will be used if generators or package installs apply.
 4. Implement the smallest correct change.
 5. Deslop the chunk.
 6. Review the chunk against JSKIT reuse and best practices.
@@ -29,11 +32,13 @@ For each chunk, follow this order:
 For CRUD chunks:
 
 1. Decide the table shape first.
-2. If `crud-server-generator` is going to own the CRUD schema, do not hand-write a separate migration for that CRUD table.
-3. Scaffold the server side first with `crud-server-generator`.
-4. Only after the shared resource file exists, scaffold the client side against that resource.
-5. Treat that shared resource file as the canonical CRUD definition. Put field and ownership changes there instead of hand-duplicating derived CRUD validators elsewhere.
-6. Do not guess CRUD operations or screen shape. Ask the developer:
+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. 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
@@ -45,8 +50,15 @@ During implementation:
 - If a selected JSKIT package already ships the required baseline workflow, install and verify that workflow before inventing custom code around it.
 - 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.
 
 After the last chunk:
 

package/workflow/review.md

@@ -20,6 +20,11 @@ Before calling a chunk or a whole changeset done, review it in four passes:
    - existing helper/runtime seam available?
    - duplicate local code that should reuse kernel/runtime support?
    - should this have been a package install, generator step, or scaffold extension instead of hand code?
+   - 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

@@ -30,11 +30,17 @@ Scoping rules:
 
 - Use `guide/agent/index.md` for fast navigation and `site/guide/index.md` for exact details.
 - Inspect packages and generators before choosing them.
+- 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.
 - Record which selected JSKIT package-owned workflows are accepted as baseline and which, if any, need custom behavior.
 - Do not ask the developer to redesign package-owned baseline workflows from scratch. Ask only whether the default behavior is accepted or whether the app needs overrides, restrictions, or extensions.
 - Create or refresh `.jskit/WORKBOARD.md` for substantial or multi-chunk work so the request has an explicit execution tracker.
+- Do not rewrite `.jskit/APP_BLUEPRINT.md` for a one-off placeholder page inside an already planned route family unless the durable route plan, surface plan, or ownership model changed.
 - Break delivery into chunks that can be independently reviewed and tested.
 - One CRUD is usually one chunk. Platform setup, shell work, and cross-cutting integrations may also be separate chunks.
 - For each CRUD chunk, decide these before implementation: