@jskit-ai/agent-docs 0.1.18 → 0.1.20

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

@@ -630,13 +630,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 +649,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 +672,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/users.md

@@ -212,13 +212,17 @@ The account route itself is very small:
 <template>
   <AccountSettingsClientElement />
 </template>
+
+<script setup>
+import AccountSettingsClientElement from "@jskit-ai/users-web/client/components/AccountSettingsClientElement";
+</script>
 ```
 
 That is a very JSKIT-style file.
 
 - the route policy is app-owned
 - the page wrapper is app-owned
-- the heavy UI is delegated to a reusable client element
+- the heavy UI is delegated to a package-owned reusable client element
 
 So the route is simple, but it is already a real authenticated account screen rather than a placeholder card.
 
@@ -228,18 +232,21 @@ The account page is backed by:
 
 ```text
 src/components/account/settings/
-  AccountSettingsClientElement.vue
   AccountSettingsProfileSection.vue
   AccountSettingsPreferencesSection.vue
   AccountSettingsNotificationsSection.vue
 ```
 
-The top-level `AccountSettingsClientElement.vue` uses `useAccountSettingsRuntime()` from `users-web` and wires those sections into a tabbed settings experience.
+Those three section components stay app-owned so you can reshape the actual UI freely.
+
+The host itself now lives in `users-web` and resolves every account section through the `account-settings:sections` placement target, including the default `profile`, `preferences`, and `notifications` entries.
+
+So the screen follows the same rule as the rest of JSKIT UI: sections are added by placement rather than being hardcoded into an app-owned host component.
 
 That is worth noticing because the guide has now reached a new level of scaffolding:
 
 - earlier chapters mostly introduced shells and routes
-- this chapter introduces real app-owned feature UI that is already split into reusable sections
+- this chapter introduces app-owned leaf section UI while the generic section host stays in the package
 
 ## Under the hood
 
@@ -336,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

@@ -666,6 +666,7 @@ In the current CLI, that includes checks such as:
 - installed package entries in `.jskit/lock.json`
 - whether managed files recorded in the lock still exist
 - whether installed packages are still visible in the package registry
+- explicit `transport` passed to high-level CRUD hooks such as `useCrudList()`, `useCrudView()`, and `useCrudAddEdit()`, where the shared CRUD resource should derive the JSON:API transport automatically
 - certain JSKIT-specific app checks, such as invalid raw `mdi-*` icon literals in Vue templates when the app uses Vuetify's `mdi-svg` iconset
 - UI verification receipts for current dirty UI files in git, via `.jskit/verification/ui.json`
 

package/guide/agent/generators/crud-generators.md

@@ -16,8 +16,8 @@ So the real order is always:
 This chapter uses three examples, in increasing complexity:
 
 - `contacts`: the baseline full CRUD walkthrough
-- `addresses`: a child CRUD with its own routed list page
-- `comments`: a child CRUD that lives inside the parent page, with only the child routes being routed
+- `addresses`: a child CRUD with its own routed list page reached from the parent record view
+- `comments`: a child CRUD that lives under the parent record host as a child page
 
 The examples assume the guide app already has the database and workspace/admin setup from the earlier chapters. That is why the route roots below live under `w/[workspaceSlug]/admin/...`.
 
@@ -350,7 +350,7 @@ That is the shape to learn first.
 
 Now move to a child CRUD with its own URL.
 
-This is the right pattern when the child collection deserves its own list page.
+This is the right pattern when the child collection deserves its own list page, but should still be reached from a specific parent record.
 
 Example route:
 
@@ -358,12 +358,23 @@ Example route:
 .../contacts/3/addresses
 ```
 
-In the guide app's real route tree, that becomes:
+In the guide app's real route tree, the visible URL becomes:
 
 ```text
 w/[workspaceSlug]/admin/contacts/[contactId]/addresses
 ```
 
+This example is intentionally **not** an in-page child list and **not** a contact subtab.
+
+The intended UX is:
+
+- `addresses` gets its own routed list page
+- the page lives under a specific contact
+- the user reaches it from an explicit link or button on the contact view
+- it does **not** appear in the global left menu
+
+That makes it different from the later `comments` example, where the child list stays inside the parent page.
+
 ### Step 1: create the child table
 
 Example:
@@ -382,12 +393,16 @@ CREATE TABLE addresses (
   created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
   updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
   KEY idx_addresses_workspace_id (workspace_id),
-  KEY idx_addresses_contact_id (contact_id)
+  KEY idx_addresses_contact_id (contact_id),
+  CONSTRAINT fk_addresses_contact_id
+    FOREIGN KEY (contact_id) REFERENCES contacts(id)
 );
 ```
 
 The important extra column here is `contact_id`. This is what makes the CRUD a child of a contact instead of a top-level resource.
 
+The foreign key is not optional in this example. It is what lets `crud-server-generator` emit `contactId` as a real lookup relation in `packages/addresses/src/shared/addressResource.js`.
+
 ### Step 2: scaffold the server package
 
 ```bash
@@ -398,17 +413,104 @@ npx jskit generate crud-server-generator scaffold \
   --table-name addresses
 ```
 
-### Step 3: scaffold the UI at the child route root
+Then install the generated local package:
+
+```bash
+npm install
+```
+
+If you are developing against a local JSKIT checkout, relink your app to the local packages before you run the UI:
+
+```bash
+npm run devlinks
+```
+
+### Step 3: refine the generated lookup metadata by hand
+
+Open `packages/addresses/src/shared/addressResource.js` and add `labelKey: "fullName"` to the generated `contactId` relation:
+
+```js
+contactId: {
+  type: "id",
+  required: true,
+  search: true,
+  relation: {
+    kind: "lookup",
+    namespace: "contacts",
+    valueKey: "id",
+    labelKey: "fullName"
+  },
+  belongsTo: "contacts",
+  as: "contact",
+  ui: { formControl: "autocomplete" },
+  ...
+}
+```
+
+This part is still manual today.
+
+The scaffold can infer the lookup **relationship** from the foreign key, but it cannot infer which contact field should be used as the human-readable label. Without `labelKey: "fullName"`, the page falls back to generic headings like `Addresses for Contact #1`.
+
+### Step 4: scaffold the UI route tree
 
 ```bash
 npx jskit generate crud-ui-generator crud \
   w/[workspaceSlug]/admin/contacts/[contactId]/addresses \
   --resource-file packages/addresses/src/shared/addressResource.js \
   --id-param addressId \
+  --parent-title contextual \
   --display-fields label,line1,postcode
 ```
 
-That gives you a proper child CRUD with its own list, view, new, and edit pages under the contact route.
+That gives you a normal child route tree:
+
+- `w/[workspaceSlug]/admin/contacts/[contactId]/addresses/index.vue`
+- `w/[workspaceSlug]/admin/contacts/[contactId]/addresses/new.vue`
+- `w/[workspaceSlug]/admin/contacts/[contactId]/addresses/[addressId]/index.vue`
+- `w/[workspaceSlug]/admin/contacts/[contactId]/addresses/[addressId]/edit.vue`
+- shared `_components` files under the same route root
+
+### Step 5: remove the generated shell placement by hand
+
+`crud-ui-generator` currently generates a list-page placement block in `src/placement.js`.
+
+For this example, that block is **not** what you want.
+
+Delete the generated `addresses` placement block from `src/placement.js`.
+
+It will be the block added for the `w/[workspaceSlug]/admin/contacts/[contactId]/addresses` page link.
+
+Depending on what outlets already exist in the app, that block may try to place `Addresses` in the shell menu or in the contact subpages outlet. For this example, remove it either way and keep navigation manual from the contact view.
+
+This is an intentional manual cleanup for now:
+
+- keep the routed pages
+- remove the auto menu link
+- navigate to the page from the contact view instead
+
+### Step 6: add a manual link from the contact view
+
+Open `src/pages/w/[workspaceSlug]/admin/contacts/[contactId]/index.vue` and add a button that links to `./addresses`.
+
+The simplest version is:
+
+```vue
+<v-btn
+  color="primary"
+  variant="tonal"
+  :to="{ path: view.resolveParams(UI_ADDRESSES_URL), query: $route.query }"
+>
+  Addresses
+</v-btn>
+```
+
+Then define the URL template in the script:
+
+```js
+const UI_ADDRESSES_URL = "./addresses";
+```
+
+That gives you a standalone child page with a clear entry point from the parent contact view, without mixing record-scoped pages into the global shell menu.
 
 ### The important refinement: parent title handling
 
@@ -416,8 +518,8 @@ This is where nested CRUD starts to feel real.
 
 An addresses list page should not show a generic heading like `Addresses`. It should usually show whose addresses these are, for example:
 
-- `Jane Smith's addresses`
-- `Acme Pty Ltd's addresses`
+- `Addresses for Jane Smith`
+- `Addresses for Acme Pty Ltd`
 
 The awkward case is when there are **no child rows yet**. If the list is empty, you cannot derive the parent title from the first address record.
 
@@ -433,37 +535,36 @@ const parentTitle = useCrudListParentTitle({
 });
 ```
 
-That helper does the nice thing automatically:
+That helper does the right thing automatically:
 
-- if the child list already has rows, it derives the parent title from the first child record
+- if the child list already has rows, it derives the parent title from the first child record when lookup data is available
 - if the child list is empty, it loads the parent record directly
 
-This is exactly the pattern used in the real app codebase for nested CRUD lists like a contact's pets. It avoids the common broken state where an empty child list loses all context about the parent it belongs to.
-
-So the `addresses` example is important because it teaches the first truly practical nested-CRUD problem:
+So the `addresses` example is important because it teaches the first truly practical child-page problem:
 
 - the route is child-scoped
 - the data is child-scoped
-- but the page still needs a reliable parent identity even when the child list is empty
+- the page is reached from a parent action, not from the main shell menu
+- the page still needs a reliable parent identity even when the child list is empty
 
-## Example 3: `comments` in-page
+## Example 3: `comments` under the contact host
 
 This is the advanced example.
 
-Sometimes a child resource is real enough to deserve its own CRUD operations, but **not** important enough to deserve its own full-screen list page.
+Sometimes a child resource should stay attached to the parent record, but still deserves its own routed child page.
 
 Comments are a good example:
 
 - they matter
 - they need persistence
-- they may need `view`, `new`, or `edit` routes
-- but the main screen is still the contact view page
+- they benefit from their own list, `new`, `view`, and `edit` routes
+- but they still belong inside the contact experience rather than as a top-level destination
 
 So the pattern is:
 
 - keep the contact page as the real host
-- render the comments list inside that page
-- route only the child operations underneath it
+- keep the child route tree under that host
+- let the generated placement surface the comments page as a contact child page
 
 ### Step 1: create the table
 
@@ -474,12 +575,13 @@ CREATE TABLE comments (
   id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
   workspace_id BIGINT UNSIGNED NOT NULL,
   contact_id BIGINT UNSIGNED NOT NULL,
-  author_user_id BIGINT UNSIGNED NULL,
   body TEXT NOT NULL,
   created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
   updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
   KEY idx_comments_workspace_id (workspace_id),
-  KEY idx_comments_contact_id (contact_id)
+  KEY idx_comments_contact_id (contact_id),
+  CONSTRAINT fk_comments_contact_id
+    FOREIGN KEY (contact_id) REFERENCES contacts(id)
 );
 ```
 
@@ -493,7 +595,45 @@ npx jskit generate crud-server-generator scaffold \
   --table-name comments
 ```
 
-### Step 3: make the parent page able to host routed children
+Then install the generated local package:
+
+```bash
+npm install
+```
+
+If you are developing against a local JSKIT checkout, relink the app before you run the UI:
+
+```bash
+npm run devlinks
+```
+
+### Step 3: refine the generated lookup metadata by hand
+
+Open `packages/comments/src/shared/commentResource.js` and add `labelKey: "fullName"` to the generated `contactId` relation:
+
+```js
+contactId: {
+  type: "id",
+  required: true,
+  search: true,
+  relation: {
+    kind: "lookup",
+    namespace: "contacts",
+    valueKey: "id",
+    labelKey: "fullName"
+  },
+  belongsTo: "contacts",
+  as: "contact",
+  ui: { formControl: "autocomplete" },
+  ...
+}
+```
+
+This is the same manual refinement used in the `addresses` example: the scaffold can infer the lookup relationship from the foreign key, but it cannot infer which parent field should be used as the display label.
+
+The next command also makes the parent-title mode explicit on purpose. That way changing the heading behavior later is just changing the value and rerunning with `--force`, not adding a new flag.
+
+### Step 4: make the parent page able to host routed children
 
 If the contact view page should stay visible while child comment routes render underneath it, first upgrade it into a routed host:
 
@@ -509,63 +649,71 @@ That is the point where the comments example deliberately overlaps with the `ui-
 - CRUD scaffolding for the comments resource
 - a routed host in the parent contact page
 
-### Step 4: generate only the routed child operations
+### Step 4.5: make `comments` the default child page
 
-Now generate the comments UI without a list page:
+This is a very common next step.
 
-```bash
-npx jskit generate crud-ui-generator crud \
-  w/[workspaceSlug]/admin/contacts/[contactId]/index/comments \
-  --resource-file packages/comments/src/shared/commentResource.js \
-  --operations view,new,edit \
-  --id-param commentId
+If the contact page should open directly on `Comments`, add an explicit redirect to the contact host page:
+
+```vue
+<script setup>
+import { redirectToChild } from "@jskit-ai/kernel/client/pageRedirects";
+
+definePage({
+  redirect: redirectToChild("comments")
+});
+</script>
 ```
 
-This is the key move.
+In this example, that edit belongs in:
 
-By leaving `list` out:
+```text
+src/pages/w/[workspaceSlug]/admin/contacts/[contactId]/index.vue
+```
 
-- you do **not** generate a standalone comments list page
-- the host contact page stays responsible for showing the comment list
-- the generated child routes still handle things like `new`, `view`, and `edit`
+This is the recommended pattern. Do **not** try to infer the default child page from placement order or "the first tab". Keep it explicit.
 
-### What the host page does
+When this redirect is present:
 
-The host page then renders the comment list directly, usually with lower-level CRUD composables such as:
+- opening `/w/<workspaceSlug>/admin/contacts/<contactId>` lands on `/w/<workspaceSlug>/admin/contacts/<contactId>/comments`
+- the parent contact page still stays visible
+- the child page renders underneath it
 
-- `useCrudList()`
-- `useCrudAddEdit()`
-- `useCrudView()` when needed
+That last point matters. The contact page is still the host page. The redirect only changes which child route becomes the default landing destination.
 
-There is one more runtime worth knowing about early:
+### Step 5: generate the full child CRUD page
 
-- `useCommand()`
+Now generate the comments UI under the contact host:
 
-Use it for live actions that are **not** full forms, such as:
+```bash
+npx jskit generate crud-ui-generator crud \
+  w/[workspaceSlug]/admin/contacts/[contactId]/index/comments \
+  --resource-file packages/comments/src/shared/commentResource.js \
+  --id-param commentId \
+  --parent-title none \
+  --display-fields body
+```
 
-- checkbox toggles
-- archive / reopen buttons
-- quick PATCH / POST / DELETE actions on one record
+Do **not** pass `--operations view,new,edit` here. That would omit the list page and leave you with only child operation routes.
 
-So the practical split is:
+`--parent-title none` is the important difference from `addresses`.
 
-- `useCrudList()` / `useCrudView()`
-  - routed list/view loading
-- `useCrudAddEdit()`
-  - real create/edit forms
-- `useCommand()`
-  - live actions inside the page
+The contact host page already shows the parent identity, so a generated heading like `Comments for Tony Mobily` is redundant. If you later decide you do want that heading, rerun the same command with `--parent-title contextual --force`.
 
-The `todo` app uses that last pattern for "mark item done" checkboxes. The deeper best-practices explanation is in [Advanced CRUDs](/guide/generators/advanced-cruds).
+This command gives you:
 
-That is the same general pattern already used in the real app for embedded child records like pet notes: the record list lives inside the main view page, while routed child pages handle the operations that still deserve their own URLs.
+- `w/[workspaceSlug]/admin/contacts/[contactId]/index/comments/index.vue`
+- `w/[workspaceSlug]/admin/contacts/[contactId]/index/comments/new.vue`
+- `w/[workspaceSlug]/admin/contacts/[contactId]/index/comments/[commentId]/index.vue`
+- `w/[workspaceSlug]/admin/contacts/[contactId]/index/comments/[commentId]/edit.vue`
 
-This pattern is useful when the child records are supporting detail rather than a destination in their own right.
+Because this route root lives under `.../[contactId]/index/comments`, the generated placement is the desired one here: `Comments` appears as a child page under the contact host.
 
 That is the real lesson of the `comments` example:
 
-- a child CRUD does **not** have to mean "make another full-screen list page"
-- you can keep the parent page as the main experience and route only the child operations that benefit from their own URLs
+- the contact page stays the routed host
+- the child CRUD gets its own list page
+- the route still stays under the parent record experience
 
 ## When `scaffold-field` matters
 
@@ -597,8 +745,8 @@ It patches the canonical `schema` inside the shared resource file. That matters
 The important thing is not memorizing commands. It is learning the three shapes:
 
 - `contacts`: a normal top-level CRUD
-- `addresses`: a child CRUD with its own routed list page
-- `comments`: a child CRUD that lives inside the parent page, with only the child operations routed
+- `addresses`: a child CRUD with its own routed list page reached from the parent record view
+- `comments`: a child CRUD that lives under the parent record host as a child page
 
 Once you understand those three shapes, the two generator packages stop feeling like separate tools.
 

package/guide/agent/generators/ui-generators.md

@@ -257,6 +257,37 @@ The route page is still a normal page file. What changes is the inferred placeme
 
 So JSKIT is not switching to a different generator. It is switching the inferred placement behavior because the route tree now has a routed host above the new page.
 
+### Making a child page the default landing route
+
+This is important enough to state explicitly: if a routed host has child pages, and you want the bare parent URL to open one child immediately, use an explicit redirect.
+
+Do **not** try to make the app "guess the first tab". Do **not** infer it from placement order. Keep the target explicit.
+
+The standard pattern is:
+
+```vue
+<script setup>
+import { redirectToChild } from "@jskit-ai/kernel/client/pageRedirects";
+
+definePage({
+  redirect: redirectToChild("exports")
+});
+</script>
+```
+
+If this is placed on the host page, opening `/reports` lands on `/reports/exports`.
+
+This is also the right pattern when the host page still renders shared content such as a title, tabs, summary panel, or `RouterView`. The parent route remains the host, and the child page simply becomes the default destination under it.
+
+Why this is the recommended pattern:
+
+- the destination is explicit and stable
+- it survives later placement reordering
+- it does not depend on which child link happens to render first
+- it is easy to change later by editing one child segment
+
+This is one of the most common things people want once they start using child-page hosts. Treat it as normal JSKIT routing, not a special hack.
+
 ## Nested pages under an `index.vue` host
 
 Once `Reports` is a host, create a child page under it:

package/package.json

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