@jskit-ai/agent-docs 0.1.26 → 0.1.28

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

@@ -63,7 +63,7 @@ npx jskit show @jskit-ai/workspaces-web --details
 
 That output makes the package feel much less mysterious, because it shows the exact workspace shell contributions, settings outlets, client tokens, app-owned file writes, and capability requirements before you mutate the app.
 
-## What changes now
+## What workspaces add
 
 This chapter is where the app stops being a collection of global surfaces and starts supporting workspace-dependent ones.
 
@@ -107,13 +107,13 @@ That is why this chapter feels larger than the previous ones. It is not just add
 
 ### The shell and account surface gain workspace-aware controls
 
-The placement registry now grows a workspace selector in the top-left of the shell, a pending-invites cue in the top-right area, and workspace tools in the admin shell. The workspaces package also plugs an `Invites` section into the existing `/account` settings screen through the account-settings extension seam that `users-web` exposes.
+The placement registry gets a workspace selector in `shell.identity`, pending-invites and workspace tools in `shell.status`, and an `Invites` section in the existing `/account` settings screen through the account-settings extension seam that `users-web` exposes. The default shell topology maps identity/status placements to the visible shell chrome.
 
 That means the shell itself starts adapting to workspace context.
 
-- on any authenticated surface, the shell can now expose a workspace selector
-- signed-in users can now see a pending-invites cue without `users-web` owning that workspace feature
-- on admin workspace surfaces, the shell can also expose workspace-specific tools and settings
+- on any authenticated surface, the shell can expose a workspace selector
+- signed-in users can see a pending-invites cue without `users-web` owning that workspace feature
+- on admin workspace surfaces, the shell can expose workspace-specific tools and settings
 
 This is the first time the guide shows the shell reacting not just to authentication state, but to workspace state as well.
 
@@ -139,7 +139,7 @@ This is also important to notice:
 
 The new workspace surfaces are added on top of the existing app, not instead of it.
 
-That is exactly what multi-homing should feel like. The app now has both:
+That is exactly what multi-homing should feel like. The app has both:
 
 - global surfaces
 - workspace-scoped surfaces
@@ -153,7 +153,7 @@ npm run dev
 npm run server
 ```
 
-After you sign in, the app now has the routing structure needed for workspace-aware paths such as:
+After you sign in, the app has the routing structure needed for workspace-aware paths such as:
 
 ```text
 /w/your-personal-slug
@@ -166,15 +166,15 @@ At this stage of the guide, the starter workspace pages are still intentionally
 
 The most important new visible ideas are:
 
-- a workspace slug now appears in the route
+- a workspace slug appears in the route
 - the shell can expose workspace selection and workspace tools
 - workspace-dependent surfaces can show a dedicated unavailable-state card when the requested workspace cannot be resolved
 
-First, even the old global `/home` surface now reacts to workspace state. The selector in the top-left and the invites cue in the top-right come from placement entries and workspace bootstrap context, not from the `home` page itself.
+First, even the global `/home` surface reacts to workspace state. The selector and invites cue come from semantic placement entries and workspace bootstrap context, not from the `home` page itself.
 
-Then open your personal workspace route. The page itself is deliberately light. `src/pages/w/[workspaceSlug]/index.vue` mostly exists to prove that the `app` surface is now real and ready to host later modules.
+Then open your personal workspace route. The page itself is deliberately light. `src/pages/w/[workspaceSlug]/index.vue` mostly exists to prove that the `app` surface is real and ready to host later modules.
 
-Next open the admin surface for the same workspace. This is the matching pattern on the admin side: `src/pages/w/[workspaceSlug]/admin.vue` is the shell wrapper, `src/pages/w/[workspaceSlug]/admin/index.vue` is the starter page, and the top-right workspace tools button is coming from placements rather than being hand-built into that page file.
+Next open the admin surface for the same workspace. This is the matching pattern on the admin side: `src/pages/w/[workspaceSlug]/admin.vue` is the shell wrapper, `src/pages/w/[workspaceSlug]/admin/index.vue` is the starter page, and the workspace tools button is coming from placements rather than being hand-built into that page file.
 
 Finally open the nested workspace settings route. This is useful to inspect because it shows the container pattern most clearly. `src/pages/w/[workspaceSlug]/admin/workspace/settings.vue` owns the section frame and the child outlet, while the actual settings sub-pages can keep arriving later under that shell.
 
@@ -231,7 +231,7 @@ config.workspaceInvitations = {
 };
 ```
 
-Those lines are the public contract that tells both client and server, "this app is workspace-aware now."
+Those lines are the public contract that tells both client and server that this app is workspace-aware.
 
 ### `config/surfaceAccessPolicies.js` gains `workspace_member`
 
@@ -252,7 +252,7 @@ That is the core idea of multi-homing in JSKIT:
 - the server resolves that workspace
 - access depends on whether the current user belongs to it
 
-### The migrations now include workspace schema
+### The migrations include workspace schema
 
 After `workspaces-core`, the migration directory grows again with files such as:
 
@@ -269,7 +269,7 @@ That is why the chapter needs another `npm run db:migrate`. Without those tables
 
 ### The route tree gains workspace-dependent pages
 
-The app now gets:
+The app gets:
 
 ```text
 src/pages/w/[workspaceSlug].vue
@@ -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,51 +575,52 @@ 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"
 });
 ```
 
-That one block explains a lot of the new shell behavior.
+That one block explains a lot of the workspace shell behavior.
 
-- the authenticated profile menu can now switch into workspace surfaces
-- the top-left area now has a workspace selector
-- the top-right area can show a pending-invites cue
-- 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`
+- the authenticated profile menu can switch into workspace surfaces
+- `shell.identity` carries the workspace selector
+- `shell.status` can show a pending-invites cue
+- the admin surface gets workspace tools through `shell.status`
+- the admin workspace settings menu is 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
 ```
 
-In a workspace-enabled app, that list now includes:
+In a workspace-enabled app, that list 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.
+So the placement system from the shell chapter is doing the same job with a richer routing and tenancy context.
 
 ### The local client provider gets one more app-owned token
 
@@ -663,7 +666,7 @@ registerProfileSyncLifecycleContributor(app, "workspaces.core.profileSyncLifecyc
 
 That means the workspace package does not need to patch auth directly to learn that a user was added. It listens through the `users-core` lifecycle registry instead.
 
-For this chapter's `tenancyMode = "personal"` setup, that contributor now does real work. When an authenticated JSKIT user is synchronized from auth, `workspaces-core` ensures that user's personal workspace exists.
+For this chapter's `tenancyMode = "personal"` setup, that contributor does real work. When an authenticated JSKIT user is synchronized from auth, `workspaces-core` ensures that user's personal workspace exists.
 
 That detail matters for the retrofit path described earlier in this chapter. If the app started on `none`, then later switched to `personal`, the first sign-in after that switch still needs to backfill the personal workspace for the already-existing user record. The lifecycle contributor handles that because the workspace provision step is idempotent.
 
@@ -709,9 +712,9 @@ Before:
 After:
 
 - global surfaces still exist
-- workspace-scoped surfaces now exist too
+- workspace-scoped surfaces exist too
 - the shell can navigate between workspaces
-- access to some surfaces now depends on workspace membership
+- access to some surfaces depends on workspace membership
 
 That is why multi-homing deserves its own chapter. It is not just another feature package. It is the moment the app becomes tenancy-aware.
 
@@ -719,11 +722,11 @@ That is why multi-homing deserves its own chapter. It is not just another featur
 
 This chapter is the real routing and tenancy pivot in the guide.
 
-- the app now uses `tenancyMode = "personal"`
+- the app uses `tenancyMode = "personal"`
 - `workspaces-core` added the persistent schema and server runtime for workspaces
 - `workspaces-web` added the first workspace-scoped surfaces, shell controls, and the workspace-owned account invites extension
 
-At the end of this chapter, the app now has both:
+At the end of this chapter, the app has both:
 
 - global surfaces such as `home`, `auth`, `account`, and `console`
 - workspace-scoped surfaces such as `/w/[workspaceSlug]` and `/w/[workspaceSlug]/admin`
@@ -733,7 +736,7 @@ That is the most important mental shift to keep:
 - earlier chapters added features inside one global app shell
 - this chapter changed the topology of the app itself
 
-From here on, later modules are no longer only adding pages or widgets. They can add features inside either:
+From here on, later modules can add features inside either:
 
 - the global surfaces
 - the workspace-specific surfaces

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

@@ -42,7 +42,7 @@ This is the first chapter where the migration step is not just "nice to have."
 - `AUTH_PROFILE_MODE=users` into `.env`
 - real users/account schema migrations into `migrations/`
 
-That means the app is now expected to use the persistent users-backed profile sync service. If you skip `npm run db:migrate`, the code and routes are installed, but the required tables are still missing.
+That means the app is expected to use the persistent users-backed profile sync service. If you skip `npm run db:migrate`, the code and routes are installed, but the required tables are still missing.
 
 So the correct flow is:
 
@@ -57,24 +57,24 @@ Most of the time, step 3 is not needed because `jskit add package users-web` alr
 - `jskit migrations changed` writes or refreshes JSKIT-managed migration files in `migrations/`
 - `npm run db:migrate` actually applies pending migrations to MySQL
 
-## What changes now
+## What `users-web` adds
 
 This chapter is the real transition from "authentication exists" to "the app knows about users."
 
 ### Authentication becomes users-backed
 
-In the database chapter, JSKIT still used the standalone in-memory profile mirror. After installing `users-web`, that changes. JSKIT now expects to synchronize authenticated users into real JSKIT tables.
+In the database chapter, JSKIT used the standalone in-memory profile mirror. After installing `users-web`, JSKIT expects to synchronize authenticated users into real JSKIT tables.
 
 That is the biggest architectural change in this chapter.
 
 - Supabase still owns the real auth identity and session
-- JSKIT now also owns a persistent users/account data model in MySQL
+- JSKIT owns a persistent users/account data model in MySQL
 
-So after this chapter, a signed-in user is no longer only "someone Supabase knows about." They are also a persistent JSKIT-side user with settings and profile state in the app database.
+So after this chapter, a signed-in user is not only "someone Supabase knows about." They are also a persistent JSKIT-side user with settings and profile state in the app database.
 
 ### The app gets an authenticated account surface
 
-The app now has a new authenticated surface at `/account`.
+The app has an authenticated surface at `/account`.
 
 This is where the starter account settings UI lives. It already has real sections for:
 
@@ -84,17 +84,17 @@ This is where the starter account settings UI lives. It already has real section
 
 Later chapters can extend this account screen with more sections. For example, the multi-homing chapter adds workspace invitation UI through `workspaces-web`, not through `users-web` itself.
 
-The important point is that this is no longer just a placeholder route. It is the first app-owned screen that assumes there is a real persistent user model behind it.
+The important point is that this is a real account route, not a placeholder. It is the first app-owned screen that assumes there is a persistent user model behind it.
 
 ### The shell changes for signed-in users
 
 Once a user is signed in, the shell becomes noticeably richer.
 
 - the profile menu gets a `Settings` entry that leads to `/account`
-- the home surface gets a small users tools widget in the top-right area
-- the auth bootstrap payload now includes persistent user settings instead of only the fallback mirror data
+- the home surface gets a small users tools widget in `shell.status`
+- the auth bootstrap payload includes persistent user settings instead of only the fallback mirror data
 
-So this chapter is also the first one where logging in changes more than just "guest vs signed in." It now changes what persistent user-facing surfaces the app can expose.
+So this chapter is also the first one where logging in changes more than just "guest vs signed in." It changes what persistent user-facing surfaces the app can expose.
 
 ## What to look at in the browser
 
@@ -107,17 +107,17 @@ npm run server
 
 Then sign in through `http://localhost:5173/auth/login`.
 
-After a successful sign-in, you should notice three concrete differences compared with the previous chapter:
+After a successful sign-in, check these concrete differences compared with the previous chapter:
 
-- the profile menu now contains `Settings`
-- the top-right area now also has a small users tools widget
-- `/account` now exists and is authenticated
+- the profile menu contains `Settings`
+- `shell.status` includes the users tools widget
+- `/account` exists and is authenticated
 
 This is the first chapter where the app starts to feel like it has a real user model behind it.
 
 ## What `users-web` adds to the app
 
-The most interesting files now are spread across config, migrations, routing, and the app-owned account UI.
+The most interesting files are spread across config, migrations, routing, and the app-owned account UI.
 
 ### `.env` flips auth into users mode
 
@@ -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,18 +239,18 @@ 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 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.
 
-That is worth noticing because the guide has now reached a new level of scaffolding:
+That is worth noticing because this is a higher level of scaffolding:
 
 - earlier chapters mostly introduced shells and routes
 - this chapter introduces app-owned leaf section UI while the generic section host stays in the package
 
 ## Under the hood
 
-### Why auth now behaves differently
+### Why auth uses the users layer
 
 In the previous chapter, auth still defaulted to the standalone profile sync fallback. The core logic in `AuthSupabaseServiceProvider` looks like this:
 
@@ -268,7 +268,7 @@ if (authProfileMode === AUTH_PROFILE_MODE_USERS) {
 }
 ```
 
-The important part is no longer hypothetical.
+The important part is concrete.
 
 After `users-web`:
 
@@ -276,9 +276,9 @@ After `users-web`:
 - `users-core` supplies the users-backed sync service
 - the migrations supply the required tables
 
-So auth now has everything it needs to stop using the fallback mirror and start using the persistent users-backed one.
+So auth has everything it needs to stop using the fallback mirror and start using the persistent users-backed one.
 
-That is the true point of this chapter. The app is no longer just authenticated. It now has a real users layer.
+That is the true point of this chapter. The app is not just authenticated. It has a real users layer.
 
 ### `users-core` also owns the profile-sync lifecycle registry
 
@@ -361,7 +361,7 @@ This chapter is where the app stopped treating signed-in people as only Supabase
 
 That is why this chapter feels bigger than a normal page install. It changes both the browser experience and the server-side meaning of "a signed-in user."
 
-At the end of this chapter, the app now has:
+At the end of this chapter, the app has:
 
 - real JSKIT-side `users` and `user_settings` tables
 - a real authenticated `/account` surface

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

@@ -71,14 +71,15 @@ In the current scaffold, those scripts are intentionally thin:
 
 That is a deliberate design choice.
 
-The app keeps the handy `npm run` names, but the real maintenance policy now lives in the installed CLI package instead of copied shell scripts inside the app. That means if JSKIT later changes how package updates, local linking, or baseline verification should work, apps can pick up the new behavior by updating `@jskit-ai/jskit-cli` instead of hand-editing frozen scaffold files.
+The app keeps the handy `npm run` names, but the real maintenance policy lives in the installed CLI package instead of copied shell scripts inside the app. That means if JSKIT later changes how package updates, local linking, or baseline verification should work, apps can pick up the new behavior by updating `@jskit-ai/jskit-cli` instead of hand-editing frozen scaffold files.
 
 This gives you a clean ownership split:
 
 - app-owned scripts still describe how *this app* runs, builds, and tests
+- `npm run devlinks` re-applies local checkout links after `npm install` when you are testing an app against this monorepo
 - JSKIT-owned wrapper scripts delegate framework maintenance to `jskit app ...`
 
-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".
+That split is worth keeping in mind through the rest of the guide. When you see `npm run verify`, read it as "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.
 
@@ -332,8 +333,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 +342,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.
 
@@ -504,7 +506,13 @@ npx jskit add package shell-web
 npm install
 ```
 
-`jskit add` changes the app. `npm install` downloads the dependencies that the changed app now requires.
+`jskit add` changes the app. `npm install` downloads the dependencies that the changed app requires.
+
+If the app is being tested against a local JSKIT checkout with linked packages, run the local-link wrapper again after every `npm install`:
+
+```bash
+npm run devlinks
+```
 
 ### `add bundle`
 
@@ -699,7 +707,7 @@ That is a different job from:
 
 Those commands can all pass while JSKIT-managed state is still inconsistent. `doctor` is the command that checks that JSKIT's own view of the app still makes sense.
 
-That is exactly why the starter scaffold now routes `npm run verify` through `jskit app verify`.
+That is exactly why the starter scaffold routes `npm run verify` through `jskit app verify`.
 
 It belongs there because JSKIT apps are not only source trees. They also have:
 
@@ -731,7 +739,7 @@ Good times to run it manually include:
 
 One important nuance: `doctor` is checking for broken JSKIT ownership and visibility, not trying to stop you from editing app-owned files. For example, a managed file that still exists but whose contents changed is normally fine. The problem is when JSKIT expects a managed file to exist and it is gone, or when the installed package state no longer resolves cleanly.
 
-There is one intentional exception now for user-facing UI work.
+There is one intentional exception for user-facing UI work.
 
 If the current git working tree has changed UI files under the app's normal UI paths, `doctor` expects a matching `.jskit/verification/ui.json` receipt. The intended way to create that receipt is:
 
@@ -961,7 +969,7 @@ Good fits include:
 - a custom integration package that talks to one external API
 - app-specific auth or policy behavior
 - a local runtime package that owns both client and server behavior for one feature area
-- a package that starts small now but may later grow providers, shared helpers, and routes
+- a package that starts small but may later grow providers, shared helpers, and routes
 
 Use a generator when the problem is already understood well enough that JSKIT can scaffold the feature shape for you.