@jskit-ai/agent-docs 0.1.19 → 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
@@ -630,13 +632,11 @@ export default Object.freeze({
   kind: "runtime",
   runtime: {
     server: {
-      providerEntrypoint: "src/server/index.js",
+      providerEntrypoint: "src/server/MainServiceProvider.js",
       providers: [
         {
-          discover: {
-            dir: "src/server/providers",
-            pattern: "*Provider.js"
-          }
+          entrypoint: "src/server/MainServiceProvider.js",
+          export: "MainServiceProvider"
         }
       ]
     }
@@ -651,12 +651,12 @@ export default Object.freeze({
 
 This is the moment where the scaffold stops looking like "just a Vue app". The app is declaring itself as a runtime package that JSKIT can discover, load, and mutate safely.
 
-For the server side, the main file to remember is `packages/main/src/server/providers/MainServiceProvider.js`. At the beginning it is almost empty, but that emptiness is useful. It means you already have a stable place to put backend runtime code as the app grows, instead of inventing ad hoc structure later.
+For the server side, the main file to remember is `packages/main/src/server/MainServiceProvider.js`. It stays intentionally flat and small. That is the point: `packages/main` is the app-local composition package, not the default home for new backend feature trees.
 
 The server-side provider starts like this:
 
 ```js
-import { loadAppConfig } from "../support/loadAppConfig.js";
+import { loadAppConfig } from "./loadAppConfig.js";
 
 class MainServiceProvider {
   static id = "local.main";
@@ -674,7 +674,13 @@ class MainServiceProvider {
 export { MainServiceProvider };
 ```
 
-It is deliberately small, but it already shows the pattern: register things with the app container first, then grow real backend behavior from there. The client side uses the same provider lifecycle; you already saw the matching pattern earlier in the client boot path.
+It is deliberately small because it is only for app-local glue: loading config, wiring tiny app-specific behavior, and bootstrapping shared runtime concerns. When a backend capability becomes substantial, do not grow `packages/main` into a mini service tree. Generate a dedicated package instead:
+
+```bash
+npx jskit generate feature-server-generator scaffold booking-engine
+```
+
+That keeps the ownership boundary clear: `packages/main` stays composition-only, while real server features get their own provider, service, and optional repository seams. The client side uses the same provider lifecycle; you already saw the matching pattern earlier in the client boot path.
 
 The `.jskit/lock.json` file is also important. Treat it like JSKIT's own lock and state file. It records which runtime packages JSKIT believes are installed and which managed changes they introduced. When you use `jskit add`, `jskit update`, or generators that depend on installed package state, this file is part of the source of truth. It belongs in version control, and you should not hand-edit it.
 

package/guide/agent/app-setup/multi-homing.md

@@ -47,6 +47,12 @@ npm install
 npm run db:migrate
 ```
 
+**Important: This Block Is Only The Fresh Workspace Install Path**
+
+These commands are complete only if the app was already on `tenancyMode = "personal"` when `users-web` / `users-core` were originally installed, or if you already ran the recovery `npx jskit update package users-core` step above.
+
+If you changed tenancy after installing users, do not skip that update. The workspace packages add workspace runtime and routes, but `users-core` is what rewrites the app-local users scaffold into its workspace-aware shape.
+
 `workspaces-core` adds the server-side workspace runtime and schema migrations. `workspaces-web` adds the workspace-facing client surfaces, shell placements, and app-owned route files.
 
 If you want to inspect that package before installing it, this is a very good moment to use the CLI chapter's inspection command:
@@ -306,6 +312,30 @@ Concretely, that route tree works like this:
 - `w/[workspaceSlug]/admin/workspace/settings.vue` is a section shell. It does not own the actual settings fields. It owns the card frame, the left-side settings menu outlet, and the nested `<RouterView />` where child settings pages render.
 - `w/[workspaceSlug]/admin/workspace/settings/index.vue` is intentionally almost empty. Its job is to make `/admin/workspace/settings` a real route today and give you a clean place to redirect or add child settings pages later.
 
+If you want to add a real workspace settings child page at this point, use the normal page generator under that route tree:
+
+```bash
+npx jskit generate ui-generator page \
+  w/[workspaceSlug]/admin/workspace/settings/billing/index.vue \
+  --name "Billing"
+```
+
+That command does two things:
+
+- it creates `src/pages/w/[workspaceSlug]/admin/workspace/settings/billing/index.vue`
+- it also appends the matching workspace settings menu entry into `src/placement.js`
+
+The reason JSKIT can wire that link automatically is that the workspace settings shell already exposes a named placement outlet with a default link renderer:
+
+```vue
+<ShellOutlet
+  target="admin-settings:primary-menu"
+  default-link-component-token="local.main.ui.surface-aware-menu-link-item"
+/>
+```
+
+`target="admin-settings:primary-menu"` tells the generator which settings menu host owns those child links. `default-link-component-token="local.main.ui.surface-aware-menu-link-item"` tells it which local menu-link component to use unless you override it. So a page generated under `w/[workspaceSlug]/admin/workspace/settings/...` automatically lands in the left-side workspace settings menu without you hand-writing the placement entry.
+
 ### Workspace pages are prepared for missing-workspace states
 
 The starter workspace pages already use a dedicated unavailable-state helper:
@@ -558,6 +588,35 @@ That one block explains a lot of the new shell behavior.
 - the admin surface gets workspace tools in the top-right area
 - the admin workspace settings menu is now another nested placement host with both `Settings` and `Members`
 
+If you want to add your own app-owned page into that top cog menu, first ask JSKIT which placement targets exist:
+
+```bash
+npx jskit list-placements
+```
+
+In a workspace-enabled app, that list now includes:
+
+```text
+- admin-cog:primary-menu [package:@jskit-ai/workspaces-web:src/client/components/UsersWorkspaceToolsWidget.vue]
+```
+
+If you want more context than the raw target list, `npx jskit show @jskit-ai/workspaces-web --details` also shows that same outlet plus the default `Settings` and `Members` entries already targeting it.
+
+Once you know the outlet id, generate the page like this:
+
+```bash
+npx jskit generate ui-generator page \
+  w/[workspaceSlug]/admin/catalogue/index.vue \
+  --name "Catalogue" \
+  --link-placement admin-cog:primary-menu
+```
+
+That command creates `src/pages/w/[workspaceSlug]/admin/catalogue/index.vue` and appends the matching link entry into `src/placement.js`.
+
+`--link-placement` is necessary here because this route is just a normal `admin` page. It is **not** a child page under a local host like `w/[workspaceSlug]/admin/workspace/settings.vue`, so the generator has no nested settings outlet to infer automatically. If you omit `--link-placement`, the new page link falls back to the app's default shell menu outlet instead of the cog menu.
+
+You also do **not** need `--link-component-token` here. `admin-cog:primary-menu` already declares `local.main.ui.surface-aware-menu-link-item` as its default link renderer, so JSKIT reuses that automatically when it writes the placement entry.
+
 So the placement system from the shell chapter is still doing the same job as before. The app just has a richer routing and tenancy context now.
 
 ### The local client provider gets one more app-owned token

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

@@ -343,6 +343,14 @@ Under the hood, `users-core` wires those contributors into the users-backed prof
 
 The next chapter uses exactly that pattern. `workspaces-core` registers a contributor so the workspace layer can react when a new user enters the system.
 
+One forward-looking warning matters here. If this app later changes from `tenancyMode = "none"` to `personal` or `workspaces`, the app-local users scaffold written by `users-core` also needs to be refreshed. The multi-homing chapter calls out that recovery step explicitly with:
+
+```bash
+npx jskit update package users-core
+```
+
+That is not only a workspace-package concern. The generated `packages/users/...` scaffold itself changes shape when tenancy becomes workspace-aware.
+
 ## Summary
 
 This chapter is where the app stopped treating signed-in people as only Supabase identities and started treating them as real JSKIT users.

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: