@jskit-ai/agent-docs 0.1.20 → 0.1.21

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

@@ -151,6 +151,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,214 @@
+<!-- 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=...
+```
+
+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.21",
   "description": "Distributed JSKIT agent workflows, guides, and generated reference maps.",
   "type": "module",
   "files": [

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/AGENTS.md

@@ -73,7 +73,7 @@ Core rules:
 - 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.

package/workflow/feature-delivery.md

@@ -62,6 +62,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

@@ -33,6 +33,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