@jskit-ai/agent-docs 0.1.27 → 0.1.28

package/DISTR_AGENT.md

@@ -31,6 +31,7 @@ Core rules:
 - Keep that checkpoint compact. Do not expand it into a long preamble unless the developer asks for detail.
 - When a request involves JSKIT UI, routing, surfaces, CRUDs, filters, placements, live actions, or similar implementation details, scan `patterns/INDEX.md` for matching keywords and read only the relevant pattern files.
 - Reuse existing JSKIT helpers and runtime seams before adding new local helpers.
+- If `npm install` is run while the app is using local JSKIT checkout links, run `npm run devlinks` immediately afterward.
 - A freshly scaffolded JSKIT app can still be in Stage 1. If platform decisions are not settled yet, continue with the initialize workflow before adding runtime packages.
 - Do not treat a missing `config.tenancyMode` line or an untouched minimal scaffold as a final tenancy decision.
 - Do not install tenancy-sensitive packages until Stage 1 decisions are complete and the chosen tenancy is written into `config/public.js`.

package/guide/agent/app-extras/assistant.md

@@ -455,7 +455,7 @@ npm run dev
 npm run server
 ```
 
-After sign-in, the app should now expose these assistant routes:
+After sign-in, the app should expose these assistant routes:
 
 - `/console/assistant`
 - `/w/your-personal-slug/admin/assistant`
@@ -534,7 +534,7 @@ That is what lets one app host several assistants at once without their AI setti
 
 ### `.env` gains one AI block per assistant surface
 
-The app now gets env keys such as:
+The app gets env keys such as:
 
 ```dotenv
 CONSOLE_ASSISTANT_AI_PROVIDER=openai

package/guide/agent/app-extras/mobile-capacitor.md

@@ -36,6 +36,9 @@ npx jskit mobile android doctor
 ```
 
 If doctor passes, the app is ready for the normal mobile workflow.
+The `jskit mobile android ...` commands expect the mobile runtime package to be
+installed in `package.json` and recorded in `.jskit/lock.json`; they do not
+install `@jskit-ai/mobile-capacitor` for you.
 
 ## What you need on your machine
 
@@ -126,6 +129,10 @@ This:
 - builds the JSKIT web app into `dist/`
 - runs `cap sync android`
 
+The refresh step requires the managed files from the package install to exist.
+If `capacitor.config.json` or `.jskit/mobile-capacitor.md` is missing, install
+the package again with `npx jskit add package @jskit-ai/mobile-capacitor`.
+
 ### Create the local tunnel
 
 ```bash
@@ -177,7 +184,7 @@ Use it when you want a clean signed-out state.
 
 ## The command set
 
-These are the mobile commands the package adds:
+These are the CLI mobile commands used by the package workflow:
 
 - `jskit mobile android devices`
   - list visible Android devices
@@ -288,8 +295,8 @@ The package manages:
   - `MainActivity.java` or `MainActivity.kt`
 - the managed deep-link block in `AndroidManifest.xml`
 
-`jskit mobile android sync` is expected to refresh those files from
-`config.mobile`.
+After the package is installed, `jskit mobile android sync` refreshes those
+managed files from `config.mobile`.
 
 ### Why the tunnel exists
 

package/guide/agent/app-extras/realtime.md

@@ -21,13 +21,13 @@ The first command records the runtime package in the app and updates the existin
 
 Unlike the database, users, console, and workspace chapters, this one does **not** need `npm run db:migrate`. `realtime` does not add schema files. It is transport infrastructure, not persistence.
 
-## What changes now
+## What the package adds
 
-Installing `realtime` changes the app in three important ways.
+Installing `realtime` adds three app capabilities.
 
 ### The app gets a realtime transport
 
-The server now mounts a socket.io runtime on the same Fastify server that already serves your JSKIT surfaces. The browser gets a matching socket.io client runtime through the normal client boot process.
+The server mounts a socket.io runtime on the same Fastify server that already serves your JSKIT surfaces. The browser gets a matching socket.io client runtime through the normal client boot process.
 
 That means later modules, or your own app code, can stop thinking only in terms of request/response HTTP flows. They can start publishing live events and listening for them in Vue.
 
@@ -35,7 +35,7 @@ That means later modules, or your own app code, can stop thinking only in terms
 
 The package also uses the shell scaffolding that already exists.
 
-`realtime` appends a placement entry into `src/placement.js` that targets `shell-layout:top-right`, so the shell starts showing a small status dot without you having to create a new page for it.
+`realtime` appends a placement entry into `src/placement.js` that targets the semantic `shell.status` placement, so the shell shows a small status dot without you having to create a new page for it. In the default shell topology, `shell.status` renders through the concrete `shell-layout:top-right` outlet.
 
 That dot is:
 
@@ -52,7 +52,7 @@ The app already had a browser dev server on `5173` and a backend runtime on `300
 
 So one of the main values of this package is that you do **not** have to hand-edit Vite config just to make socket.io work in local development.
 
-### There are still no new pages
+### There are no realtime pages
 
 This is worth saying clearly because it can otherwise feel surprising.
 
@@ -75,7 +75,7 @@ npm run server
 
 Then open `http://localhost:5173/home`.
 
-The important visible change is in the top-right of the shell. You should now see the realtime status dot alongside the other shell controls.
+The visible check is the shell status area. You should see the realtime status dot alongside the other shell controls.
 
 If the websocket connects successfully, the dot is green. If the backend is unavailable or the socket is reconnecting, the dot is red. Hovering it shows the current status text.
 
@@ -159,7 +159,7 @@ After the install, the app has:
 
 That one entry is what lets the browser dev server proxy websocket traffic correctly during local development.
 
-### `src/placement.js` grows one new shell placement
+### `src/placement.js` includes the shell status placement
 
 The package appends this placement:
 
@@ -216,9 +216,9 @@ That is the right level of abstraction for this package:
 
 ## Summary
 
-This chapter does not make the app look radically different, but it adds an important new capability.
+This chapter does not make the app look radically different, but it adds an important capability.
 
-- the backend can now host a realtime socket server
-- the frontend can now keep one shared websocket connection alive
-- the shell now exposes a live connection indicator
+- the backend hosts a realtime socket server
+- the frontend keeps one shared websocket connection alive
+- the shell exposes a live connection indicator
 - later modules can build live behavior on top of that transport without inventing their own websocket setup

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

@@ -40,18 +40,18 @@ That is why the intended flow is:
 
 If you build directly on top of the plain scaffold first and only try to add `shell-web` later, the install may fail because those app-owned files no longer match the untouched scaffold baseline.
 
-Open `http://localhost:5173/` in the browser. The app still lands in the `home` surface, but that surface is no longer just a card in the middle of the page. It is wrapped in a real shell with an app bar, a navigation drawer, and a settings route at `/home/settings`.
+Open `http://localhost:5173/` in the browser. The app lands in the `home` surface inside a real shell with an app bar, a navigation drawer, and a settings route at `/home/settings`.
 
-Two important things have changed compared with the older starter shell.
+Two shell pieces are worth noticing first.
 
-- Navigation now lives in the drawer itself. `Home` and `Settings` are real shell menu entries from the start.
+- Navigation lives in the drawer itself. `Home` and `Settings` are real shell menu entries from the start.
 - `Settings` is already a real nested section. Opening `/home/settings` redirects to `/home/settings/general`, and the left-side menu already contains a starter `General` entry.
 
 Open `http://localhost:5173/home/settings` in the browser to see that nested settings shell immediately:
 
 ## Module features
 
-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.
+The most important idea in `shell-web` is that the app 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 public placement targets already exist:
 
@@ -59,12 +59,12 @@ Start by asking JSKIT what public placement targets already exist:
 npx jskit list-placements
 ```
 
-In a fresh `shell-web` app, the result looks like this:
+In a fresh `shell-web` app, the result includes entries like these:
 
 ```text
 Available placements:
 - shell.primary-nav (default): Primary top-level navigation for the current surface.
-  - compact -> shell-layout:primary-menu
+  - compact -> shell-layout:primary-bottom-nav
   - 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.
@@ -95,6 +95,11 @@ Those concrete target names come from real `ShellOutlet` elements in the app. Se
 />
 ...
 <ShellOutlet target="shell-layout:secondary-menu" />
+...
+<ShellOutlet target="shell-layout:primary-bottom-nav" />
+...
+<ShellOutlet target="shell-layout:supporting-bottom-sheet" />
+<ShellOutlet target="shell-layout:supporting-side-panel" />
 ```
 
 And the settings page introduces its own nested outlet in `src/pages/home/settings.vue`:
@@ -105,7 +110,7 @@ And the settings page introduces its own nested outlet in `src/pages/home/settin
 
 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 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.
+Just as importantly, `shell-web` uses that placement system itself. The starter app exposes semantic placement targets and seeds real placement entries into them. `Home` and `Settings` land in primary navigation, and `General` lands in the nested settings menu. The shell is exercising the same extension contract that later package and generator output uses.
 
 The shell also ships with a few app-owned component tokens that it can use as default link renderers. You can inspect those too:
 
@@ -123,9 +128,9 @@ Showing link-item tokens only (token must end with "link-item"). Tip: use --all
 - local.main.ui.tab-link-item [app:packages/main/src/client/providers/MainClientProvider.js]
 ```
 
-So before we add anything of our own, the shell already knows about three local link-item tokens. They are app-owned components registered by the local package, and the shell uses them when an outlet needs to render links or tabs.
+The shell knows about three local link-item tokens. They are app-owned components registered by the local package, and topology uses them when an outlet needs to render links or tabs.
 
-At this point the shell is already using placements itself. The next step is to add one of our own.
+At this point the shell is using placements itself. The next step is to add one of our own.
 
 ### Adding generic elements directly
 
@@ -135,7 +140,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.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.
+That command creates a Vue component under `src/components/` (in this case `src/components/AlertsWidgetElement.vue`), registers a local token for it, and adds a placement entry targeting `shell.status`. After running it, refresh the home page in the browser. The shell renders the app-owned widget 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.
 
@@ -159,15 +164,15 @@ npx jskit generate ui-generator page home/settings/profile/index.vue --name "Pro
 
 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.
+Open `/home/settings/profile` in the browser. The settings shell shows a second real child page and a second real menu entry created by the same page-generation command. `General` comes 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.
 
-Now add a second sibling page:
+Add a second sibling page:
 
 ```bash
 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 `page.section-nav` owner, so the links simply stack in the menu for free.
+Open `/home/settings/notifications` in the browser. You 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 stack in the menu for free.
 
 The order is also easy to reason about:
 
@@ -179,7 +184,7 @@ The order is also easy to reason about:
 In JSKIT's file-based routing, a page file can act as a layout if it renders a `RouterView`.
 
 - `src/pages/home/settings.vue` owns the settings shell and wraps its child routes.
-- `src/pages/home/settings/index.vue` is now just a redirect, so `/home/settings` lands on `/home/settings/general`.
+- `src/pages/home/settings/index.vue` is just a redirect, so `/home/settings` lands on `/home/settings/general`.
 - `src/pages/home/settings/general/index.vue` is the first real child page created by the starter shell.
 - `src/pages/home/settings/profile/index.vue` becomes `/home/settings/profile` and still renders inside the layout from `settings.vue`.
 
@@ -248,13 +253,13 @@ Later in the guide, `jskit doctor` will help catch the second mistake automatica
 
 ### Component tokens
 
-If you rerun the token listing now, you will see that only the widget command created a new app-owned component token:
+If you rerun the token listing, the widget command is the only command in this chapter that created an app-owned component token:
 
 ```bash
 npx jskit list-component-tokens --all --prefix local.main.
 ```
 
-The output now includes:
+The output includes:
 
 ```text
 - local.main.ui.element.alerts-widget
@@ -279,7 +284,7 @@ That is the first real example of JSKIT behaving like an extension system rather
 
 ## What `shell-web` changes in the app
 
-The most interesting files now look roughly like this:
+The most interesting files look roughly like this:
 
 ```text
 src/
@@ -317,19 +322,18 @@ The first file worth reopening is still `package.json`. After `shell-web`, the m
 {
   "dependencies": {
     "@jskit-ai/shell-web": "0.x",
-    "@tanstack/vue-query": "^5.90.5",
     "@mdi/js": "^7.4.47"
   }
 }
 ```
 
-The important part is not just that `@jskit-ai/shell-web` appears. The package also brings in Vue Query and icon data because the starter shell now includes a live health check and shell-specific UI elements.
+The important part is not just that `@jskit-ai/shell-web` appears. The package brings in shell runtime code and icon data; Vue Query is already owned by the base app bootstrap so every client package uses the same query client.
 
 It is also worth noticing what does **not** happen here. The `placed-element` and `page` commands from this chapter mutate app-owned files, but they do not add a permanent runtime dependency to `package.json`. They are tooling actions, not runtime package installs.
 
 The lock file becomes more interesting too. In the first chapter, `.jskit/lock.json` only knew about `@local/main`. Now it also records `@jskit-ai/shell-web` and the exact files and text mutations that package introduced.
 
-That is worth noticing because this is the first chapter where JSKIT is no longer just scaffolding a base app. It is now applying a runtime package that owns concrete changes in your app tree.
+That is worth noticing because this is the first chapter where JSKIT applies a runtime package that owns concrete changes in your app tree.
 
 ### The `home` surface gets a real wrapper
 
@@ -360,7 +364,7 @@ import { RouterView } from "vue-router";
 </template>
 ```
 
-That one change explains a lot. The `home` surface is no longer just a place where pages live. It is now a shell-wrapped surface. Every child page under `src/pages/home/` renders inside that app-owned `ShellLayout`.
+That one change explains a lot. The `home` surface is a shell-wrapped surface. Every child page under `src/pages/home/` renders inside that app-owned `ShellLayout`.
 
 ### `src/placement.js` becomes the placement registry
 
@@ -381,7 +385,7 @@ export default function getPlacements() {
 
 That file is the app-owned seam for placements. `shell-web` owns the runtime that can render placements, but the app owns the registry source that lists what should appear in those targets.
 
-After the `shell-web` install plus the `placed-element` and `page` commands from this chapter, the bottom of the file now contains real placement entries:
+After the `shell-web` install plus the `placed-element` and `page` commands from this chapter, the bottom of the file contains real placement entries:
 
 ```js
 addPlacement({
@@ -483,7 +487,7 @@ That snippet shows the full placement contract clearly:
 - lower `order` values come first
 - 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.
+That is why the settings menu 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.
 
 So the shell itself remains stable. What changes is the registry that feeds it.
 
@@ -503,7 +507,7 @@ registerMainClientComponent("local.main.ui.surface-aware-menu-link-item", () =>
 registerMainClientComponent("local.main.ui.tab-link-item", () => TabLinkItem);
 ```
 
-This is the same app-local provider seam from the previous chapter, but now you can see why it matters. The provider is what lets the placement runtime resolve app-owned components by token instead of hard-coding imports inside the shell runtime.
+This is the same app-local provider seam from the previous chapter, and this chapter shows why it matters. The provider is what lets the placement runtime resolve app-owned components by token instead of hard-coding imports inside the shell runtime.
 
 The `Profile` and `Notifications` pages did not need to add another provider registration because they reuse the existing `local.main.ui.surface-aware-menu-link-item` token for their menu entries.
 
@@ -515,17 +519,9 @@ So the flow is:
 
 That is why the placement system feels dynamic even though the app still owns all of the concrete Vue files.
 
-### `App.vue` and `error.js` now support shell-level errors
-
-The top-level app root changes too. `src/App.vue` is no longer just:
-
-```vue
-<v-app>
-  <RouterView />
-</v-app>
-```
+### `App.vue` and `error.js` provide shell-level errors
 
-It now also includes a shell error host:
+The top-level app root includes the normal route outlet and the shell error host:
 
 ```vue
 <script setup>
@@ -541,31 +537,43 @@ import ShellErrorHost from "@jskit-ai/shell-web/client/components/ShellErrorHost
 </template>
 ```
 
-That host is backed by the new app-owned `src/error.js` file:
+That host is backed by the app-owned `src/error.js` file:
 
 ```js
 import { createDefaultErrorPolicy } from "@jskit-ai/shell-web/client/error";
 
 export default Object.freeze({
   defaultPresenterId: "material.snackbar",
-  policy: createDefaultErrorPolicy(),
+  policy: createDefaultErrorPolicy({
+    resourceLoadChannel: "silent",
+    actionFeedbackChannel: "snackbar",
+    appRecoverableChannel: "banner",
+    blockingChannel: "dialog"
+  }),
   presenters: []
 });
 ```
 
 The idea is the same as with placements: `shell-web` provides the runtime, but the app owns the configuration file that the runtime reads.
 
-### The home page is no longer static
+The default error policy is intent-based. Runtime code reports what kind of error happened and the app-owned policy decides the presentation:
+
+- `resource-load` uses `silent`; the screen keeps the load message and retry action local.
+- `action-feedback` uses `snackbar`; saves, commands, and other user-triggered actions report through one lightweight feedback channel.
+- `app-recoverable` uses `banner`; shell refresh and recoverable navigation failures stay visible without blocking the app.
+- `blocking` uses `dialog`; unexpected UI failures and other blocking errors require explicit attention.
+
+### The home page talks to the backend
 
-`src/pages/home/index.vue` is also more interesting now. It is no longer just a welcome card. It uses Vue Query to fetch `/api/health` and display the result in the UI.
+`src/pages/home/index.vue` uses Vue Query to fetch `/api/health` and display the result in the UI.
 
-That is why this chapter is the point where running both `npm run dev` and `npm run server` stops feeling optional. The page now expects the backend to be alive.
+That is why this chapter is the point where running both `npm run dev` and `npm run server` matters. The page expects the backend to be alive.
 
 This matters because it is the first tiny example of the frontend and backend participating in the same shell. The request itself is simple, but the behavior is more realistic than the empty starter card from the previous chapter.
 
 ### The first client stores appear
 
-This is also the first chapter where an installed package starts exposing app-facing Pinia stores. `shell-web` exports these two:
+`shell-web` also exposes app-facing Pinia stores:
 
 ```js
 import {
@@ -607,10 +615,10 @@ The same store also exposes the live drawer state through `drawerOpen`, plus `se
 
 You do not need either store very often in this chapter, because `shell-web` already mounts the shell and error host for you. The starter `General` settings page uses the higher-level `useShellLayoutState()` helper instead of talking to `useShellLayoutStore()` directly, because that helper combines the store-backed drawer state with the current route and surface context that `ShellLayout` also needs.
 
-That distinction is worth noticing early:
+That distinction is worth noticing:
 
 - runtime services still do the operational work
-- Pinia stores are now the normal Vue-facing shared-state surface
+- Pinia stores are the normal Vue-facing shared-state surface
 
 ### The first settings route appears
 
@@ -634,7 +642,7 @@ The important host file is still `src/pages/home/settings.vue`:
 
 This file matters for the same reason as `ShellLayout.vue`: it creates another named extension point instead of hard-coding a finished settings UI. The difference is that this one lives inside a page, not at the top shell level.
 
-The starter shell now uses a real child-page structure right away:
+The starter shell 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
@@ -665,6 +673,6 @@ The app is still structurally simple. `shell-web` just makes that simple app beh
 
 ## Summary
 
-After this chapter, the app is still small, but it is no longer flat. `shell-web` adds an app-owned shell layout, a placement registry, a shell error host, menu-link tokens in the local client provider, real drawer navigation, and the first nested settings section under `home`.
+After this chapter, the app is still small, but it has a shell shape. `shell-web` adds an app-owned shell layout, a placement registry, a shell error host, menu-link tokens in the local client provider, real drawer navigation, and the first nested settings section under `home`.
 
 More importantly, this chapter is where placements stop being theory. The shell already uses them for `Home`, `Settings`, and the starter `General` settings page. Then you inspect the available targets, place real UI into the outer shell, and add more child settings pages that automatically land in the nested settings menu. That is the first real example of JSKIT working as an extension system rather than just a scaffold generator.

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

@@ -83,7 +83,7 @@ npm run server
 
 Then open `http://localhost:5173/auth/login` in the browser.
 
-The login page is now real, and it already contains several different auth modes behind the same card.
+The login page is real, and it already contains several different auth modes behind the same card.
 
 - **Sign in** is the normal email-and-password flow.
 - **Register** creates a new Supabase auth user.
@@ -91,7 +91,7 @@ The login page is now real, and it already contains several different auth modes
 - **Use one-time code** switches to an email OTP login flow.
 - **Remember this account on this device** stores a small local hint in browser storage so the next visit can greet the last-used account and let the user keep that email preselected.
 
-If you go back to `http://localhost:5173/home`, the shell also has a small auth widget in the top-right corner. When you are signed out it shows a guest state and a menu entry that leads to `/auth/login`. After you sign in, the same placement changes to a sign-out menu.
+If you go back to `http://localhost:5173/home`, the shell also has a small auth widget in the status area. When you are signed out it shows a guest state and a menu entry that leads to `/auth/login`. After you sign in, the same placement changes to a sign-out menu.
 
 ## Reading the screen carefully
 
@@ -165,7 +165,7 @@ JSKIT asks Supabase to send OTP login emails only for existing users. In other w
 
 That endpoint asks Supabase to send a password reset email. In this chapter's scaffold, this mode is only the **request** step.
 
-The backend already supports the later recovery endpoints too, but the chapter's simple app does **not** yet scaffold a dedicated app-owned `reset-password` page. So at this stage, the guide should be read as: the screen can request recovery emails now, while the full browser-side password-reset completion UI is still something you would add explicitly in the app.
+The backend already supports the later recovery endpoints too, but the chapter's simple app does **not** yet scaffold a dedicated app-owned `reset-password` page. So at this stage, the guide should be read as: the screen can request recovery emails, while the full browser-side password-reset completion UI is still something you would add explicitly in the app.
 
 ### Remembered account behavior
 
@@ -184,7 +184,7 @@ On the next visit, the card can show a `Welcome back, ...` panel and a `Use anot
 
 The screen is also ready to show OAuth provider buttons, but only if providers are configured.
 
-Right now the chapter's `config.server.js` keeps this empty:
+For this chapter, `config.server.js` keeps this empty:
 
 ```js
 config.auth = {
@@ -332,13 +332,22 @@ addPlacement({
 });
 ```
 
-And the page file itself is a normal page scaffold:
+And the page file itself is a normal generated empty-state screen:
 
 ```vue
 <template>
-  <section class="pa-4">
-    <h1 class="text-h5 mb-2">Reports</h1>
-    <p class="text-body-2 text-medium-emphasis">Replace this scaffold with your page implementation.</p>
+  <section class="generated-page-screen d-flex flex-column ga-4">
+    <header>
+      <p class="text-overline text-medium-emphasis mb-1">Screen</p>
+      <h1 class="generated-page-screen__title">Reports</h1>
+    </header>
+
+    <v-sheet rounded="lg" border class="generated-page-screen__empty-state">
+      <h2 class="text-h6 mb-2">No Reports activity yet</h2>
+      <p class="text-body-2 text-medium-emphasis mb-0">
+        Activity and actions for this screen will appear here.
+      </p>
+    </v-sheet>
   </section>
 </template>
 ```
@@ -364,9 +373,18 @@ To make the route require login, add a route guard block to `src/pages/home/repo
 </route>
 
 <template>
-  <section class="pa-4">
-    <h1 class="text-h5 mb-2">Reports</h1>
-    <p class="text-body-2 text-medium-emphasis">Replace this scaffold with your page implementation.</p>
+  <section class="generated-page-screen d-flex flex-column ga-4">
+    <header>
+      <p class="text-overline text-medium-emphasis mb-1">Screen</p>
+      <h1 class="generated-page-screen__title">Reports</h1>
+    </header>
+
+    <v-sheet rounded="lg" border class="generated-page-screen__empty-state">
+      <h2 class="text-h6 mb-2">No Reports activity yet</h2>
+      <p class="text-body-2 text-medium-emphasis mb-0">
+        Activity and actions for this screen will appear here.
+      </p>
+    </v-sheet>
   </section>
 </template>
 ```
@@ -383,7 +401,7 @@ So after login, JSKIT can send the user back to the page they originally asked f
 
 ### Hide the menu entry when signed out
 
-The route is now protected, but the drawer link is still visible. That is expected. Route protection and shell visibility are separate concerns.
+The route is protected, but the drawer link is still visible. That is expected. Route protection and shell visibility are separate concerns.
 
 To hide the `Reports` menu entry until the user is logged in, update the placement entry in `src/placement.js`:
 
@@ -407,7 +425,7 @@ addPlacement({
 
 The only new part is the `when(...)` line. That predicate is evaluated by the shell placement runtime using the auth context that `auth-web` injects from `/api/session`.
 
-So the behavior now becomes:
+So the behavior becomes:
 
 - signed out:
   - the `Reports` drawer entry disappears
@@ -440,7 +458,7 @@ const auth = useAuthStore();
     </v-alert>
 
     <h1 class="text-h5 mb-2">Home</h1>
-    <p class="text-body-2 text-medium-emphasis">Replace this scaffold with your page implementation.</p>
+    <p class="text-body-2 text-medium-emphasis">Your account session is active on this device.</p>
   </section>
 </template>
 ```
@@ -501,7 +519,7 @@ At this point the guide has shown three distinct layers of client state:
 - `shell-web` adds shell-facing stores such as `useShellLayoutStore()`
 - `auth-web` adds `useAuthStore()` for authentication state
 
-That progression is intentional. Packages keep their operational runtimes internally, but the app-facing shared state they surface to Vue code is now store-based.
+That progression is intentional. Packages keep their operational runtimes internally, but the app-facing shared state they surface to Vue code is store-based.
 
 ## What `auth-base` adds to the app
 
@@ -528,7 +546,7 @@ Three things are worth noticing immediately.
 
 - `auth-provider-supabase-core` is the provider-specific runtime.
 - `auth-web` is the part that adds the web routes and the default auth UI.
-- there is now an `auth` surface-specific dev/build script family, just as `home` already had.
+- there is an `auth` surface-specific dev/build script family, just as `home` already had.
 
 The provider command also writes a new `.env` file:
 
@@ -541,7 +559,7 @@ APP_PUBLIC_URL=http://localhost:5173
 
 This is the bridge between the scaffold and your real Supabase project. `APP_PUBLIC_URL` matters because auth emails and callback flows need to know which browser URL they should return to.
 
-Public routing config changes too. `config/public.js` now has a second surface:
+Public routing config changes too. `config/public.js` has a second surface:
 
 ```js
 config.surfaceDefinitions.auth = {
@@ -568,7 +586,7 @@ config.auth = {
 };
 ```
 
-That small block explains a lot of the default login screen. The stock UI is ready for OAuth providers such as Google, but right now the provider list is empty, so the page only shows the email/password and one-time-code flows. Later, if you enable a provider in Supabase and list it here, the same login screen can expose that button too.
+That small block explains a lot of the default login screen. The stock UI is ready for OAuth providers such as Google, but this chapter keeps the provider list empty, so the page only shows the email/password and one-time-code flows. Later, if you enable a provider in Supabase and list it here, the same login screen can expose that button too.
 
 The auth routes themselves are app-owned wrappers around the module-supplied default views. `src/pages/auth/login.vue` looks like this:
 
@@ -640,7 +658,7 @@ addPlacement({
 });
 ```
 
-This is the shell placement system from the previous chapter doing real work again. `auth-web` does not hard-code a permanent top-right button into `ShellLayout.vue`. Instead, it contributes a widget and two menu entries into named outlets, and those entries react to the current auth state.
+This is the shell placement system from the previous chapter doing real work again. `auth-web` does not hard-code a permanent auth button into `ShellLayout.vue`. Instead, it contributes the profile widget into the semantic `shell.status` placement and contributes sign-in/sign-out links into the semantic `auth.profile-menu` placement. Topology maps those semantic targets to concrete outlets and renderers.
 
 So the auth story in this chapter is spread across clear responsibilities:
 
@@ -702,7 +720,7 @@ onBeforeUnmount(() => {
     </v-alert>
 
     <h1 class="text-h5 mb-2">Home</h1>
-    <p class="text-body-2 text-medium-emphasis">Replace this scaffold with your page implementation.</p>
+    <p class="text-body-2 text-medium-emphasis">Your account session is active on this device.</p>
   </section>
 </template>
 ```
@@ -917,7 +935,7 @@ It is also why the shell widget can react cleanly to auth state without storing
 
 ### Authenticated Playwright testing with the dev auth bypass
 
-JSKIT now ships a development-only auth bootstrap path specifically so authenticated UI can be verified in Playwright without depending on a real live login flow through Supabase.
+JSKIT ships a development-only auth bootstrap path specifically so authenticated UI can be verified in Playwright without depending on a real live login flow through Supabase.
 
 This is the standard path the agent should use for authenticated browser tests:
 
@@ -1083,6 +1101,6 @@ That is why the confirmation screen in the app should be understood as a **sessi
 
 ## Summary
 
-After this chapter, the app can really authenticate against Supabase. It has a public `auth` surface, a stock login page, a sign-out route, and a shell widget that reflects auth state. The provider-specific values now live in `.env`, and the web auth layer is wired into the same placement and surface system introduced earlier in the guide.
+After this chapter, the app can really authenticate against Supabase. It has a public `auth` surface, a stock login page, a sign-out route, and a shell widget that reflects auth state. The provider-specific values live in `.env`, and the web auth layer is wired into the same placement and surface system introduced earlier in the guide.
 
 Just as importantly, the app is still deliberately incomplete. Authentication exists, but the database-backed user model does not. That separation is useful, because the next layer of the guide can explain users and persistence without having to also explain the first auth setup at the same time.