@jskit-ai/agent-docs 0.1.26 → 0.1.27

package/guide/agent/app-setup/a-more-interesting-shell.md

@@ -53,7 +53,7 @@ Open `http://localhost:5173/home/settings` in the browser to see that nested set
 
 The most important new idea in `shell-web` is that the app now has _specific, named places_ where UI can be inserted later. JSKIT calls those places _placements_. In practice, this means later packages or generators do not have to rewrite the whole shell every time they want to add a menu entry, a widget, or a settings section.
 
-Start by asking JSKIT what placement targets already exist:
+Start by asking JSKIT what public placement targets already exist:
 
 ```bash
 npx jskit list-placements
@@ -63,16 +63,25 @@ In a fresh `shell-web` app, the result looks like this:
 
 ```text
 Available placements:
-- home-settings:primary-menu [src/pages/home/settings.vue]
-- shell-layout:primary-menu (default) [src/components/ShellLayout.vue]
-- shell-layout:secondary-menu [src/components/ShellLayout.vue]
-- shell-layout:top-left [src/components/ShellLayout.vue]
-- shell-layout:top-right [src/components/ShellLayout.vue]
+- shell.primary-nav (default): Primary top-level navigation for the current surface.
+  - compact -> shell-layout:primary-menu
+  - medium -> shell-layout:primary-menu
+  - expanded -> shell-layout:primary-menu
+- page.section-nav [owner:home-settings]: Navigation between child pages in the home settings section.
+  - compact -> home-settings:primary-menu
+  - medium -> home-settings:primary-menu
+  - expanded -> home-settings:primary-menu
 ```
 
-This command lists placement targets, not the content inside them. That is why the output is about target names and source files. Later, when you place things into the shell, this list stays the same unless you add or remove a `ShellOutlet` in source.
+This command lists semantic placements, not the content inside them. Later, when you place things into the shell, this list stays stable unless the public placement topology changes.
 
-Those target names come from real `ShellOutlet` elements in the app. See `src/components/ShellLayout.vue`:
+The concrete outlets still exist, but they are implementation details. If you need to inspect them directly, use:
+
+```bash
+npx jskit list-placements --concrete
+```
+
+Those concrete target names come from real `ShellOutlet` elements in the app. See `src/components/ShellLayout.vue`:
 
 ```html
 ...
@@ -83,27 +92,20 @@ Those target names come from real `ShellOutlet` elements in the app. See `src/co
 <ShellOutlet
   target="shell-layout:primary-menu"
   default
-  default-link-component-token="local.main.ui.surface-aware-menu-link-item"
 />
 ...
-<ShellOutlet
-  target="shell-layout:secondary-menu"
-  default-link-component-token="local.main.ui.surface-aware-menu-link-item"
-/>
+<ShellOutlet target="shell-layout:secondary-menu" />
 ```
 
 And the settings page introduces its own nested outlet in `src/pages/home/settings.vue`:
 
 ```html
-<ShellOutlet
-  target="home-settings:primary-menu"
-  default-link-component-token="local.main.ui.surface-aware-menu-link-item"
-/>
+<ShellOutlet target="home-settings:primary-menu" />
 ```
 
 That nested example matters. It shows that the shell is not the only place that can host placements. A page inside the shell can define its own insertion point too. That is how JSKIT can later build menus inside sections such as settings without rewriting the whole shell.
 
-Just as importantly, `shell-web` already uses that placement system itself. The starter app is not only exposing placement targets; it is also seeding real placement entries into them. The drawer gets `Home` and `Settings`, and the nested settings menu gets `General`. That is why the shell already feels real before you generate anything of your own.
+Just as importantly, `shell-web` already uses that placement system itself. The starter app is not only exposing semantic placement targets; it is also seeding real placement entries into them. The drawer gets `Home` and `Settings`, and the nested settings menu gets `General`. That is why the shell already feels real before you generate anything of your own.
 
 The shell also ships with a few app-owned component tokens that it can use as default link renderers. You can inspect those too:
 
@@ -133,7 +135,7 @@ To add a small UI element to the shell itself:
 npx jskit generate ui-generator placed-element --name "Alerts Widget"
 ```
 
-That command creates a Vue component under `src/components/` (in this case `src/components/AlertsWidgetElement.vue`), registers a new local token for it, and adds a placement entry targeting `shell-layout:top-right`. After running it, refresh the home page in the browser. The shell now has a real app-owned widget living inside one of its named placement targets.
+That command creates a Vue component under `src/components/` (in this case `src/components/AlertsWidgetElement.vue`), registers a new local token for it, and adds a placement entry targeting `shell.status`. After running it, refresh the home page in the browser. The shell now has a real app-owned widget living inside one of its named placement targets.
 
 In this app, there is no need to pass `--surface`: since the app only has one enabled surface, JSKIT can infer it automatically.
 
@@ -141,13 +143,13 @@ In this app, there is no need to pass `--surface`: since the app only has one en
 
 The settings host uses the same placement machinery, but the normal way to grow it is not by dropping a free-standing widget there. The more interesting case is adding a child page and letting JSKIT wire the menu entry for you.
 
-The source path in the `list-placements` output helps you reason about where child pages belong. When you see:
+The owner in the `list-placements` output helps you reason about where child pages belong. When you see:
 
 ```text
-- home-settings:primary-menu [src/pages/home/settings.vue]
+- page.section-nav [owner:home-settings]
 ```
 
-you know that the outlet lives in the settings host page. So if you want a child page to appear in that menu, you should create it under that part of the route tree instead of treating the menu like a generic widget area. For example, `src/pages/home/settings/profile/index.vue` belongs to that settings section, so JSKIT can wire its preferred menu entry into `home-settings:primary-menu` automatically.
+you know that the semantic placement is owned by the settings host page. So if you want a child page to appear in that menu, you should create it under that part of the route tree instead of treating the menu like a generic widget area. For example, `src/pages/home/settings/profile/index.vue` belongs to that settings section, so JSKIT can wire its preferred menu entry into `page.section-nav` with owner `home-settings` automatically.
 
 Now use the settings host the way it is normally meant to be used: add a real child page under it.
 
@@ -155,7 +157,7 @@ Now use the settings host the way it is normally meant to be used: add a real ch
 npx jskit generate ui-generator page home/settings/profile/index.vue --name "Profile"
 ```
 
-This is a more interesting example than the widget case. JSKIT creates the page file, notices that `src/pages/home/settings.vue` owns the `home-settings:primary-menu` outlet, and adds the preferred menu entry there automatically. You do not have to write that placement entry by hand.
+This is a more interesting example than the widget case. JSKIT creates the page file, notices that `src/pages/home/settings.vue` owns the settings section navigation, and adds the preferred semantic menu entry there automatically. You do not have to write that placement entry by hand.
 
 Open `/home/settings/profile` in the browser. The settings shell now shows a second real child page and a second real menu entry created by the same page-generation command. `General` was already there from `shell-web`; `Profile` is the first additional settings page you add yourself. This is the important part of the chapter: the exact same placement system works both at the top shell level and inside a page-owned nested outlet.
 
@@ -165,7 +167,7 @@ Now add a second sibling page:
 npx jskit generate ui-generator page home/settings/notifications/index.vue --name "Notifications"
 ```
 
-Open `/home/settings/notifications` in the browser. You now get a third settings menu entry without touching `settings.vue`, without writing a second menu component, and without hand-editing `src/placement.js`. JSKIT appends another placement entry targeting the same `home-settings:primary-menu` outlet, so the links simply stack in the menu for free.
+Open `/home/settings/notifications` in the browser. You now get a third settings menu entry without touching `settings.vue`, without writing a second menu component, and without hand-editing `src/placement.js`. JSKIT appends another placement entry targeting the same `page.section-nav` owner, so the links simply stack in the menu for free.
 
 The order is also easy to reason about:
 
@@ -191,7 +193,7 @@ definePage({
 });
 ```
 
-This is why the `home-settings:primary-menu` outlet from `list-placements` is such a useful clue: it tells you which page is acting as the host.
+This is why the `page.section-nav` owner from `list-placements` is such a useful clue: it tells you which page is acting as the host.
 
 Even an `index.vue` page can have children. If you want an index page to stay visible while child routes render underneath it, put those children under an `index/` directory such as `src/pages/home/settings/profile/index/details.vue`.
 
@@ -209,8 +211,10 @@ In placement metadata, raw `mdi-*` strings are acceptable because the shell menu
 ```js
 addPlacement({
   id: "home.settings.profile.link",
-  target: "home-settings:primary-menu",
-  componentToken: "local.main.ui.surface-aware-menu-link-item",
+  target: "page.section-nav",
+  owner: "home-settings",
+  kind: "link",
+  surfaces: ["home"],
   props: {
     label: "Profile",
     to: "./profile",
@@ -382,10 +386,10 @@ After the `shell-web` install plus the `placed-element` and `page` commands from
 ```js
 addPlacement({
   id: "shell-web.home.menu.home",
-  target: "shell-layout:primary-menu",
-  surfaces: ["*"],
+  target: "shell.primary-nav",
+  kind: "link",
+  surfaces: ["home"],
   order: 50,
-  componentToken: "local.main.ui.surface-aware-menu-link-item",
   props: {
     label: "Home",
     surface: "home",
@@ -397,10 +401,10 @@ addPlacement({
 
 addPlacement({
   id: "shell-web.home.menu.settings",
-  target: "shell-layout:primary-menu",
+  target: "shell.primary-nav",
+  kind: "link",
   surfaces: ["home"],
   order: 100,
-  componentToken: "local.main.ui.surface-aware-menu-link-item",
   props: {
     label: "Settings",
     surface: "home",
@@ -411,10 +415,11 @@ addPlacement({
 
 addPlacement({
   id: "shell-web.home.settings.general",
-  target: "home-settings:primary-menu",
+  target: "page.section-nav",
+  owner: "home-settings",
+  kind: "link",
   surfaces: ["home"],
   order: 100,
-  componentToken: "local.main.ui.surface-aware-menu-link-item",
   props: {
     label: "General",
     surface: "home",
@@ -426,7 +431,8 @@ addPlacement({
 
 addPlacement({
   id: "ui-generator.element.alerts-widget",
-  target: "shell-layout:top-right",
+  target: "shell.status",
+  kind: "component",
   surfaces: ["home"],
   order: 155,
   componentToken: "local.main.ui.element.alerts-widget"
@@ -434,10 +440,11 @@ addPlacement({
 
 addPlacement({
   id: "ui-generator.page.home.settings.profile.link",
-  target: "home-settings:primary-menu",
+  target: "page.section-nav",
+  owner: "home-settings",
+  kind: "link",
   surfaces: ["home"],
   order: 155,
-  componentToken: "local.main.ui.surface-aware-menu-link-item",
   props: {
     label: "Profile",
     surface: "home",
@@ -449,10 +456,11 @@ addPlacement({
 
 addPlacement({
   id: "ui-generator.page.home.settings.notifications.link",
-  target: "home-settings:primary-menu",
+  target: "page.section-nav",
+  owner: "home-settings",
+  kind: "link",
   surfaces: ["home"],
   order: 155,
-  componentToken: "local.main.ui.surface-aware-menu-link-item",
   props: {
     label: "Notifications",
     surface: "home",
@@ -465,13 +473,15 @@ addPlacement({
 
 That snippet shows the full placement contract clearly:
 
-- the target says where the UI should go
-- the component token says what should render that entry
+- the target says which semantic placement should receive the entry
+- the owner disambiguates page-owned semantic placements such as `page.section-nav`
+- `kind: "link"` lets topology choose the concrete link renderer for the current layout
+- component placements still provide their own `componentToken`
 - `props.to` tells the generated menu link which child route to open
 - `props.icon`, when you add one, belongs to menu metadata rather than direct Vuetify icon rendering
 - the surface list says where it is active
 - lower `order` values come first
-- when multiple entries target the same outlet with the same order, the shell keeps their source order
+- when multiple entries target the same semantic placement with the same order, the shell keeps their source order
 
 That is why the settings menu now shows `General` first, followed by `Profile` and `Notifications`: `General` is seeded by `shell-web` with a lower order, while the two generated pages share the same later order and keep their source order.
 
@@ -616,10 +626,7 @@ The important host file is still `src/pages/home/settings.vue`:
 
 ```vue
 <v-list nav density="comfortable" rounded="lg" border>
-  <ShellOutlet
-    target="home-settings:primary-menu"
-    default-link-component-token="local.main.ui.surface-aware-menu-link-item"
-  />
+  <ShellOutlet target="home-settings:primary-menu" />
 </v-list>
 
 <RouterView />
@@ -631,7 +638,7 @@ The starter shell now uses a real child-page structure right away:
 
 - `src/pages/home/settings/index.vue` is only a redirect into the first child page
 - `src/pages/home/settings/general/index.vue` is the first real settings page
-- `src/placement.js` already seeds a `General` link into `home-settings:primary-menu`
+- `src/placement.js` already seeds a `General` link into `page.section-nav` with owner `home-settings`
 
 When you need that landing redirect yourself, use the same helper pattern:
 

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

@@ -319,10 +319,10 @@ The placement entry is just a normal shell link:
 ```js
 addPlacement({
   id: "ui-generator.page.home.reports.link",
-  target: "shell-layout:primary-menu",
+  target: "shell.primary-nav",
+  kind: "link",
   surfaces: ["home"],
   order: 155,
-  componentToken: "local.main.ui.surface-aware-menu-link-item",
   props: {
     label: "Reports",
     surface: "home",
@@ -390,10 +390,10 @@ To hide the `Reports` menu entry until the user is logged in, update the placeme
 ```js
 addPlacement({
   id: "ui-generator.page.home.reports.link",
-  target: "shell-layout:primary-menu",
+  target: "shell.primary-nav",
+  kind: "link",
   surfaces: ["home"],
   order: 155,
-  componentToken: "local.main.ui.surface-aware-menu-link-item",
   props: {
     label: "Reports",
     surface: "home",
@@ -606,7 +606,8 @@ Authentication also becomes visible in the shell through `src/placement.js`:
 ```js
 addPlacement({
   id: "auth.profile.widget",
-  target: "shell-layout:top-right",
+  target: "shell.status",
+  kind: "component",
   surfaces: ["*"],
   order: 1000,
   componentToken: "auth.web.profile.widget"
@@ -614,10 +615,10 @@ addPlacement({
 
 addPlacement({
   id: "auth.profile.menu.sign-in",
-  target: "auth-profile-menu:primary-menu",
+  target: "auth.profile-menu",
+  kind: "link",
   surfaces: ["*"],
   order: 200,
-  componentToken: "auth.web.profile.menu.link-item",
   props: {
     label: "Sign in",
     to: "/auth/login"
@@ -627,10 +628,10 @@ addPlacement({
 
 addPlacement({
   id: "auth.profile.menu.sign-out",
-  target: "auth-profile-menu:primary-menu",
+  target: "auth.profile-menu",
+  kind: "link",
   surfaces: ["*"],
   order: 1000,
-  componentToken: "auth.web.profile.menu.link-item",
   props: {
     label: "Sign out",
     to: "/auth/signout"

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

@@ -179,7 +179,7 @@ This follows the same route-owner pattern the guide has already shown on `home`
 - `src/pages/console/settings.vue` is the nested settings shell
 - `src/pages/console/settings/index.vue` is the initial developer-owned stub
 
-That last file is intentionally empty, because later modules are expected to add real console settings sections into the `console-settings:primary-menu` outlet.
+That last file is intentionally empty, because later modules are expected to add real console settings sections through `page.section-nav` with owner `console-settings`.
 
 ### `src/placement.js` wires the first console menu entry
 
@@ -188,10 +188,10 @@ The starter placement block is:
 ```js
 addPlacement({
   id: "console.web.menu.settings",
-  target: "shell-layout:primary-menu",
+  target: "shell.primary-nav",
+  kind: "link",
   surfaces: ["console"],
   order: 100,
-  componentToken: "local.main.ui.menu-link-item",
   props: {
     label: "Settings",
     to: "/console/settings",

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

@@ -325,16 +325,13 @@ 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:
+The reason JSKIT can wire that link automatically is that the workspace settings shell already exposes a concrete outlet and topology maps it to semantic section navigation:
 
 ```vue
-<ShellOutlet
-  target="admin-settings:primary-menu"
-  default-link-component-token="local.main.ui.surface-aware-menu-link-item"
-/>
+<ShellOutlet target="admin-settings:primary-menu" />
 ```
 
-`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.
+The route host lets the generator infer `page.section-nav` with owner `admin-settings`. `src/placementTopology.js` then maps that semantic placement to `admin-settings:primary-menu` and supplies the link renderer for compact, medium, and expanded layouts. 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
 
@@ -524,7 +521,8 @@ The workspace packages append a new block of placements:
 ```js
 addPlacement({
   id: "workspaces.profile.menu.surface-switch",
-  target: "auth-profile-menu:primary-menu",
+  target: "auth.profile-menu",
+  kind: "component",
   surfaces: ["*"],
   order: 100,
   componentToken: "workspaces.web.profile.menu.surface-switch-item",
@@ -533,7 +531,8 @@ addPlacement({
 
 addPlacement({
   id: "workspaces.workspace.selector",
-  target: "shell-layout:top-left",
+  target: "shell.identity",
+  kind: "component",
   surfaces: ["*"],
   order: 200,
   componentToken: "workspaces.web.workspace.selector",
@@ -548,7 +547,8 @@ addPlacement({
 
 addPlacement({
   id: "workspaces.account.invites.cue",
-  target: "shell-layout:top-right",
+  target: "shell.status",
+  kind: "component",
   surfaces: ["*"],
   order: 850,
   componentToken: "local.main.account.pending-invites.cue",
@@ -557,7 +557,8 @@ addPlacement({
 
 addPlacement({
   id: "workspaces.workspace.tools.widget",
-  target: "shell-layout:top-right",
+  target: "shell.status",
+  kind: "component",
   surfaces: ["admin"],
   order: 900,
   componentToken: "workspaces.web.workspace.tools.widget"
@@ -565,7 +566,8 @@ addPlacement({
 
 addPlacement({
   id: "workspaces.workspace.menu.workspace-settings",
-  target: "admin-cog:primary-menu",
+  target: "admin.tools-menu",
+  kind: "component",
   surfaces: ["admin"],
   order: 100,
   componentToken: "workspaces.web.workspace-settings.menu-item"
@@ -573,7 +575,8 @@ addPlacement({
 
 addPlacement({
   id: "workspaces.workspace.menu.members",
-  target: "admin-cog:primary-menu",
+  target: "admin.tools-menu",
+  kind: "component",
   surfaces: ["admin"],
   order: 200,
   componentToken: "workspaces.web.workspace-members.menu-item"
@@ -588,7 +591,7 @@ 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:
+If you want to add your own app-owned page into that top cog menu, first ask JSKIT which semantic placements exist:
 
 ```bash
 npx jskit list-placements
@@ -597,25 +600,25 @@ 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]
+- admin.tools-menu: Admin surface tools menu actions.
 ```
 
-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.
+If you want the underlying outlet inventory, use `npx jskit list-placements --concrete`. If you want more package context, `npx jskit show @jskit-ai/workspaces-web --details` also shows the topology plus the default `Settings` and `Members` entries already targeting it.
 
-Once you know the outlet id, generate the page like this:
+Once you know the semantic placement 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
+  --link-placement admin.tools-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.
+`--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 placement to infer automatically. If you omit `--link-placement`, the new page link falls back to the app's default `shell.primary-nav` placement 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.
+You also do **not** need a renderer flag here. `admin.tools-menu` defines its link renderer in topology, so JSKIT resolves that when it renders 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.
 

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

@@ -85,9 +85,7 @@ npx jskit generate assistant page \
 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
+  --name "Admin Assistant"
 
 npm install
 npm run db:migrate
@@ -154,7 +152,7 @@ First list the available placement destinations:
 npx jskit list-placements
 ```
 
-In a workspace-enabled app, that output includes `admin-cog:primary-menu`.
+In a workspace-enabled app, that output includes the semantic `admin.tools-menu` placement.
 
 Then generate the page:
 
@@ -162,7 +160,7 @@ Then generate the page:
 npx jskit generate ui-generator page \
   w/[workspaceSlug]/admin/catalogue/index.vue \
   --name "Catalogue" \
-  --link-placement admin-cog:primary-menu
+  --link-placement admin.tools-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.
@@ -183,13 +181,10 @@ Because this page is not under a more specific local host, JSKIT falls back to t
 
 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:
+1. The parent host already exposes a concrete outlet:
 
 ```vue
-<ShellOutlet
-  target="admin-settings:primary-menu"
-  default-link-component-token="local.main.ui.surface-aware-menu-link-item"
-/>
+<ShellOutlet target="admin-settings:primary-menu" />
 ```
 
 2. Your generated pages live under that host route:
@@ -200,12 +195,14 @@ 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`
+- the semantic placement target: `page.section-nav`
+- the placement owner: `admin-settings`
 
-That is why the simple settings-page commands do not need `--link-placement` or `--link-component-token`.
+The renderer comes from `src/placementTopology.js`, where `page.section-nav` maps to the concrete `admin-settings:primary-menu` outlet for each layout class.
 
-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.
+That is why the simple settings-page commands do not need `--link-placement`.
+
+The admin cog example is different. `w/[workspaceSlug]/admin/catalogue/index.vue` is just a normal admin page, so there is no local nested host to infer. That is why you must pass `--link-placement admin.tools-menu` there.
 
 If you want a little more context than the raw destination list, this is also useful:
 

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

@@ -180,10 +180,10 @@ The placement registry also becomes more interesting:
 ```js
 addPlacement({
   id: "users.profile.menu.settings",
-  target: "auth-profile-menu:primary-menu",
+  target: "auth.profile-menu",
+  kind: "link",
   surfaces: ["*"],
   order: 500,
-  componentToken: "auth.web.profile.menu.link-item",
   props: {
     label: "Settings",
     to: "/account"
@@ -239,7 +239,7 @@ src/components/account/settings/
 
 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.
+The host itself now lives in `users-web` and resolves every account section through the semantic `settings.sections` placement with owner `account-settings`, 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.
 

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

@@ -332,8 +332,8 @@ The placement sections are often the most useful part of `show --details`.
 
 For `@jskit-ai/workspaces-web`, the detailed output shows placement contributions such as:
 
-- the workspace selector in `shell-layout:top-left`
-- the pending invites cue in `shell-layout:top-right`
+- the workspace selector in `shell.identity`
+- the pending invites cue in `shell.status`
 - the workspace tools widget on the `admin` surface
 - the `Members` and workspace settings menu entries
 
@@ -341,9 +341,10 @@ That lets you answer a very concrete question before installing anything:
 
 - *what will change in the shell if I add this package?*
 
-It also shows placement outlets, such as:
+It also shows semantic placement topology, such as:
 
-- `admin-settings:primary-menu`
+- `page.section-nav` with owner `admin-settings`
+- `admin.tools-menu`
 
 which helps you understand where later app-owned pages or settings links can attach.