@jskit-ai/agent-docs 0.1.20 → 0.1.22

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

@@ -1030,6 +1030,14 @@ npx jskit app verify-ui \
   --auth-mode dev-auth-login-as
 ```
 
+For local pre-merge review, the next step after recording that Playwright run is usually:
+
+```bash
+npx jskit doctor --against origin/main
+```
+
+Advanced CI pipelines can use the same `--against` contract too, but JSKIT does not scaffold hosted auth/database/browser verification by default.
+
 That flow is preferable to driving the real sign-in form in feature tests because it keeps the test focused on the UI feature being added, not on an external auth dependency. If a chunk changes user-facing UI and the flow requires login, the expected JSKIT review standard is:
 
 - use Playwright

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:
 
-After creating the scaffolding (which comes with a package.json file), you will need to run `npm install` to install dependencies.
+```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
+```
+
+If you want the larger workspace-enabled stack with the first assistant already configured, use [Quickstart](/guide/app-setup/quickstart) instead.
 
 **Try Bash Completion!**
 
@@ -151,6 +197,8 @@ That matters because JSKIT maintenance policy changes over time. If the scaffold
 
 `jskit app verify` is worth noticing specifically. Linting, tests, and builds check your source code and runtime behavior. The JSKIT part of that flow runs `doctor`, which checks JSKIT-managed app state: installed package visibility, lock-file-backed managed files, and other JSKIT-specific health rules. It is there because a JSKIT app is not only code. It is also a descriptor-driven managed project.
 
+The starter scaffold also writes `.github/workflows/verify.yml`. That workflow stays intentionally small: it runs `npm run verify` for the normal GitHub Actions gate and leaves browser/auth/database-heavy review flows to app-specific local or CI setups. The `--against <base-ref>` review mode exists in the CLI for local pre-merge checks and for advanced CI pipelines, but it is not assumed by the starter scaffold.
+
 The surface-specific script names are also worth noticing early, even in this tiny app. `dev:home`, `server:home`, and `build:home` are the first concrete places where surface selection shows up in the scaffold. They work by setting `VITE_SURFACE=home` on the client side and `SERVER_SURFACE=home` on the server side. In this first chapter, where `home` is the only surface, those variants behave almost the same as the default commands. Later, once more surfaces exist, those scripts become the simplest way to run or build just one surface at a time.
 
 ### App surfaces in JSKIT

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

@@ -0,0 +1,216 @@
+<!-- Generated by `npm run agent-docs:build` from `packages/agent-docs/site/guide/app-setup/quickstart.md`. Do not edit manually. -->
+
+---
+title: Quickstart
+description: The fastest path to a real JSKIT app, plus the first page-extension patterns you will usually need.
+---
+
+# Quickstart
+
+This chapter is the fastest reproducible path to a real JSKIT app.
+
+The base flow below gives you:
+
+- personal workspaces
+- users
+- console
+- MySQL
+- Supabase auth
+- one `admin` assistant configured from `console`
+
+It also shows the first page-extension moves most apps need:
+
+- add two workspace settings pages
+- make one of them the default landing page
+- add a page to the admin cog
+- add a normal left-menu page
+- inspect placement destinations and understand why some links are inferred automatically
+
+## Step 1: Create the app
+
+Set these values first:
+
+```bash
+OPENAI_API_KEY=...
+SUPABASE_URL=...
+SUPABASE_KEY=...
+DB_HOST=127.0.0.1
+DB_PORT=3306
+DB_NAME=testapp
+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
+npx @jskit-ai/create-app testapp --tenancy-mode personal
+cd testapp
+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
+npx jskit add package workspaces-core
+npx jskit add package workspaces-web
+
+npx jskit generate assistant setup \
+  --surface admin \
+  --settings-surface console \
+  --config-scope global \
+  --ai-provider openai \
+  --ai-api-key "$OPENAI_API_KEY"
+
+npx jskit generate assistant page \
+  w/[workspaceSlug]/admin/assistant/index.vue \
+  --name "Assistant"
+
+npx jskit generate assistant settings-page \
+  console/settings/admin-assistant/index.vue \
+  --surface admin \
+  --name "Admin Assistant" \
+  --link-placement console-settings:primary-menu \
+  --link-component-token local.main.ui.surface-aware-menu-link-item
+
+npm install
+npm run db:migrate
+```
+
+At this point you have:
+
+- a workspace-enabled app with `tenancyMode = "personal"`
+- an `admin` assistant at `/w/[workspaceSlug]/admin/assistant`
+- an assistant settings page at `/console/settings/admin-assistant`
+
+## Step 2: Add two workspace settings pages
+
+Generate two child pages under the workspace settings host:
+
+```bash
+npx jskit generate ui-generator page \
+  w/[workspaceSlug]/admin/workspace/settings/billing/index.vue \
+  --name "Billing"
+
+npx jskit generate ui-generator page \
+  w/[workspaceSlug]/admin/workspace/settings/branding/index.vue \
+  --name "Branding"
+```
+
+These commands create:
+
+- `src/pages/w/[workspaceSlug]/admin/workspace/settings/billing/index.vue`
+- `src/pages/w/[workspaceSlug]/admin/workspace/settings/branding/index.vue`
+
+They also append matching menu entries into `src/placement.js`.
+
+## Step 3: Make one settings page the default
+
+Best practice is to make the default child explicit.
+
+Edit:
+
+```text
+src/pages/w/[workspaceSlug]/admin/workspace/settings/index.vue
+```
+
+and replace its contents with:
+
+```vue
+<script setup>
+import { redirectToChild } from "@jskit-ai/kernel/client/pageRedirects";
+
+definePage({
+  redirect: redirectToChild("billing")
+});
+</script>
+```
+
+That makes `/w/[workspaceSlug]/admin/workspace/settings` land on `/w/[workspaceSlug]/admin/workspace/settings/billing`.
+
+Use this explicit redirect pattern instead of trying to infer the default child from placement order or “the first generated page”.
+
+## Step 4: Add a page to the admin cog
+
+First list the available placement destinations:
+
+```bash
+npx jskit list-placements
+```
+
+In a workspace-enabled app, that output includes `admin-cog:primary-menu`.
+
+Then generate the page:
+
+```bash
+npx jskit generate ui-generator page \
+  w/[workspaceSlug]/admin/catalogue/index.vue \
+  --name "Catalogue" \
+  --link-placement admin-cog:primary-menu
+```
+
+`--link-placement` is necessary here because this is just a normal `admin` page. It is not a child page under a local route host that already owns a nested outlet.
+
+## Step 5: Add a normal left-menu page
+
+Generate a normal `admin` page without an explicit placement:
+
+```bash
+npx jskit generate ui-generator page \
+  w/[workspaceSlug]/admin/reports/index.vue \
+  --name "Reports"
+```
+
+Because this page is not under a more specific local host, JSKIT falls back to the app's default shell menu outlet. In practice, that means a normal left-menu entry.
+
+## Step 6: Understand the placement "magic"
+
+The workspace settings pages in Step 2 auto-linked into the settings menu for two reasons:
+
+1. The parent host already exposes a named outlet:
+
+```vue
+<ShellOutlet
+  target="admin-settings:primary-menu"
+  default-link-component-token="local.main.ui.surface-aware-menu-link-item"
+/>
+```
+
+2. Your generated pages live under that host route:
+
+```text
+w/[workspaceSlug]/admin/workspace/settings/...
+```
+
+So JSKIT can infer both:
+
+- the placement target: `admin-settings:primary-menu`
+- the default link renderer: `local.main.ui.surface-aware-menu-link-item`
+
+That is why the simple settings-page commands do not need `--link-placement` or `--link-component-token`.
+
+The admin cog example is different. `w/[workspaceSlug]/admin/catalogue/index.vue` is just a normal admin page, so there is no local nested outlet to infer. That is why you must pass `--link-placement admin-cog:primary-menu` there.
+
+If you want a little more context than the raw destination list, this is also useful:
+
+```bash
+npx jskit show @jskit-ai/workspaces-web --details
+```
+
+That output shows both the workspace-owned placement outlets and the default entries already targeting them.

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

@@ -80,6 +80,8 @@ 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`, that is now shorthand for "run the app's JSKIT baseline verification policy, then any app-specific extra verification hook".
 
+The starter scaffold also includes `.github/workflows/verify.yml`. That workflow is intentionally conservative: it runs `npm run verify` and does not assume that every app can stand up full browser, auth, seed-data, and database verification inside hosted CI.
+
 If your app uses a non-default npm registry for JSKIT packages, pass it to the maintained CLI command rather than hard-coding it in the scaffold. For example:
 
 ```bash
@@ -747,6 +749,20 @@ That command does two things:
 
 `doctor` then compares the current changed UI files to that receipt. If you edit the UI again afterwards, the receipt is stale and `doctor` tells you to rerun `jskit app verify-ui`.
 
+For local pre-merge review, use `--against <base-ref>` so JSKIT compares against the branch delta instead of only the current dirty worktree. The common shape is:
+
+```bash
+npx jskit doctor --against origin/main
+```
+
+If the UI changed, the normal local sequence is:
+
+1. run the targeted Playwright flow locally
+2. record it with `jskit app verify-ui ...`
+3. run `jskit doctor --against <base-ref>`
+
+Advanced CI pipelines can also use `--against <base-ref>`, but that is intentionally app-specific. JSKIT does not scaffold hosted browser/auth/database verification by default, because many real apps need secrets, seeded databases, local auth bypass, or environment-specific bootstrap paths that do not belong in a one-size-fits-all template.
+
 ### Why `--json` exists
 
 If you want machine-readable output, use:

package/guide/agent/index.md

@@ -4,12 +4,13 @@
 
 This guide is the main hands-on path through JSKIT.
 
-It starts with the smallest scaffold, then explains how to work with the JSKIT CLI itself before adding the shell and authentication. After that, it introduces the database-backed users layer, expands into console and workspace-aware app structure, and adds a small `App extras` section for optional runtime packages such as realtime and assistant. Finally, the guide breaks out generator-specific workflows into their own section.
+It now starts with a fast reproducible Quickstart, then steps back to the smaller scaffold-first chapters that explain how the app is assembled piece by piece. After that, it introduces the database-backed users layer, expands into console and workspace-aware app structure, and adds a small `App extras` section for optional runtime packages such as realtime and assistant. Finally, the guide breaks out generator-specific workflows into their own section.
 
 ## Table of Contents
 
 ### App Setup
 
+- [Quickstart](/guide/app-setup/quickstart)
 - [Initial Scaffolding](/guide/app-setup/initial-scaffolding)
 - [Working With The JSKIT CLI](/guide/app-setup/working-with-the-jskit-cli)
 - [A More Interesting Shell](/guide/app-setup/a-more-interesting-shell)
@@ -33,7 +34,8 @@ It starts with the smallest scaffold, then explains how to work with the JSKIT C
 
 ## How to use this guide
 
-- Start with `App Setup` if you are building up a JSKIT app from scratch.
+- Start with `Quickstart` if you want the fastest route to a real workspace-enabled app and the first page-extension patterns.
+- Start with the rest of `App Setup` if you want to understand the base scaffold layer by layer.
 - Use `App Extras` once the base app structure is in place and you want optional runtime packages.
 - Jump into `Generators` if you already understand the runtime packages and want app-owned scaffolding workflows.
 - Inside `Generators`, read `CRUD Generators` before `Advanced CRUDs`: the first chapter teaches the workflow, and the second explains the generated anatomy and customization points.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "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,30 @@
+# 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 ...`.
+- 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.
+
+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

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/patterns/ui-testing.md

@@ -12,6 +12,8 @@ Rules:
 - Any chunk that adds or changes user-facing UI must include a Playwright flow that exercises the changed behavior before the chunk is done.
 - Record that Playwright run with `jskit app verify-ui --command "<playwright command>" --feature "<label>" --auth-mode <mode>`.
 - `jskit doctor` expects `.jskit/verification/ui.json` to match the current dirty UI file set when UI files are changed.
+- For local pre-merge review, follow the recorded Playwright run with `jskit doctor --against <base-ref>` so `doctor` compares against the branch delta instead of only the local dirty worktree.
+- Advanced CI setups may also use `--against <base-ref>`, but JSKIT does not scaffold hosted browser/auth/database verification by default.
 - Do not rely on a live external auth provider for Playwright verification of normal app features.
 - For authenticated UI in the standard JSKIT auth stack, use the development-only dev auth bypass route instead.
 - The standard route is `POST /api/dev-auth/login-as`.
@@ -31,6 +33,12 @@ npx jskit app verify-ui \
   --auth-mode dev-auth-login-as
 ```
 
+Local pre-merge follow-up:
+
+```bash
+npx jskit doctor --against origin/main
+```
+
 The Playwright command itself should follow this setup shape when login is needed:
 
 ```ts

package/reference/autogen/packages/auth-provider-supabase-core.md

@@ -190,6 +190,12 @@ Local functions
 - `cloneProfile(profile)`
 - `createEmailConflictError()`
 
+### `src/server/lib/supabaseClientOptions.js`
+Exports
+- `buildSupabaseServerClientOptions(options = {})`
+Local functions
+- `resolveRealtimeTransport({ nativeWebSocket = globalThis.WebSocket, fallbackTransport = WebSocket } = {})`
+
 ### `src/server/lib/test-utils.js`
 Exports
 - `createAccountFlows`

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

@@ -701,7 +701,8 @@ Exports
 - `isUiVerificationPath(relativePath = "")`
 - `isValidUiVerificationReceipt(receipt)`
 - `normalizeUiVerificationReceipt(rawReceipt = {})`
-- `resolveChangedUiFilesFromGit(appRoot = "")`
+- `resolveChangedPathsFromGit(appRoot = "", { against = "", pathspecs = ["src", "packages"] } = {})`
+- `resolveChangedUiFilesFromGit(appRoot = "", { against = "" } = {})`
 - `sortUniqueStrings(values = [])`
 Local functions
 - `normalizeText(value = "")`

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,15 +70,21 @@ 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.
+- 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.
 - 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.
-- Record that Playwright run with `jskit app verify-ui --command "<playwright command>" --feature "<label>" --auth-mode <mode>` so `jskit doctor` can verify the receipt.
+- Record that Playwright run with `jskit app verify-ui --command "<playwright command>" --feature "<label>" --auth-mode <mode>` so `jskit doctor` can verify the receipt. For local pre-merge review, normally follow it with `jskit doctor --against <base-ref>`. Advanced CI setups may also use `--against <base-ref>`, but that is app-specific.
 - If the UI flow requires login, use the app's development-only auth bypass or session bootstrap path instead of a live external auth login flow.
 - 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,12 @@ 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. 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:
    - which operations are allowed
    - which fields belong in the list view if one exists
    - what the view form should look like
@@ -45,8 +49,13 @@ 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.
+- 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.
 - 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:
 
@@ -62,6 +71,8 @@ Playwright note:
 
 - When login is required, use a test-only auth bypass or session bootstrap path instead of dependence on a live external auth provider.
 - Record the run through `jskit app verify-ui --command "<playwright command>" --feature "<label>" --auth-mode <mode>` so `jskit doctor` can verify the receipt against the current changed UI files.
+- In local pre-merge review, use `jskit doctor --against <base-ref>` after the recorded Playwright run so JSKIT compares against the branch delta, not only the current dirty worktree.
+- Advanced CI setups may also use `--against <base-ref>`, but JSKIT does not scaffold hosted browser/auth/database verification by default.
 - In the standard JSKIT auth stack, the default development path is `POST /api/dev-auth/login-as`, guarded by `AUTH_DEV_BYPASS_ENABLED=true` and `AUTH_DEV_BYPASS_SECRET=...`.
 - That route is development-only and must not be enabled in production.
 - Because it is still an unsafe POST, fetch `csrfToken` from `/api/session`, send it as the `csrf-token` header, and make the request in the same browser context that will run the Playwright assertions so the session cookies land in the page session.

package/workflow/review.md

@@ -20,6 +20,9 @@ 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?
    - are surface, route, ownership, and migration choices aligned with JSKIT conventions?
    - package metadata and actual behavior still aligned?
 3. UI standards review
@@ -33,6 +36,7 @@ Before calling a chunk or a whole changeset done, review it in four passes:
    - run the widest relevant verification commands for a whole changeset
    - any added or changed user-facing UI must be exercised with Playwright
    - that Playwright run should normally be recorded through `jskit app verify-ui`
+   - for local pre-merge review, prefer following that receipt with `jskit doctor --against <base-ref>`
    - if login is required, use the chosen local test-auth path instead of live external auth
    - in the standard JSKIT auth stack, prefer the development-only `POST /api/dev-auth/login-as` path
    - if there is no usable local auth bootstrap path, explicitly record that as a blocking testability gap

package/workflow/scoping.md

@@ -30,11 +30,16 @@ 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.
+- 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: