@jskit-ai/agent-docs 0.1.27 → 0.1.28

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

@@ -25,7 +25,7 @@ npm run db:migrate
 - `console-core` owns the console schema, owner check, bootstrap flag, and API routes
 - `console-web` owns the console surface scaffold, settings shell, and menu placement
 
-So the console is a real vertical slice now. The users packages no longer know about it.
+The console is a real vertical slice. The users packages do not own it.
 
 ## What the console is for
 
@@ -70,7 +70,7 @@ Then sign in.
 
 Once you are authenticated, two things matter:
 
-- the app now knows who you are as a persistent JSKIT user
+- the app knows who you are as a persistent JSKIT user
 - the console bootstrap logic can determine whether you are the console owner
 
 Open:
@@ -92,7 +92,7 @@ This is the most important idea in the chapter.
 
 The account surface only requires authentication. The console surface requires a specific access flag: `console_owner`.
 
-That means the guide now has two different kinds of authenticated routes:
+That means the guide has two different kinds of authenticated routes:
 
 - normal authenticated routes such as `/account`
 - privileged authenticated routes such as `/console`
@@ -163,7 +163,7 @@ This is the first clear example in the guide of a surface guarded by a named fla
 
 ### The starter console routes are app-owned
 
-After the previous chapter, the app now has:
+After the previous chapter, the app has:
 
 ```text
 src/pages/console.vue
@@ -308,7 +308,7 @@ That stricter access model is the key idea to keep:
 - `/account` is for any signed-in user
 - `/console` is only for the console owner
 
-So the app now has both:
+So the app has both:
 
 - a normal authenticated user area
 - a privileged operator area with its own server-side ownership check

package/guide/agent/app-setup/database-layer.md

@@ -49,11 +49,11 @@ Installing `database-runtime-mysql` gives the app three important things right a
 
 ### A real database runtime
 
-The server can now build a real Knex client from environment variables. That gives later packages a standard way to ask for a database connection instead of each package inventing its own wiring.
+The server can build a real Knex client from environment variables. That gives later packages a standard way to ask for a database connection instead of each package inventing its own wiring.
 
 ### A migration workflow
 
-The app now gets three new scripts in `package.json`:
+The app gets three database scripts in `package.json`:
 
 ```json
 {
@@ -73,7 +73,7 @@ If you run the status command immediately after this chapter:
 npm run db:migrate:status
 ```
 
-you should still see that there are no completed migrations and no pending migration files yet. The runtime and the Knex wiring exist now, but no package has added real schema files until the next chapter.
+you should still see that there are no completed migrations and no pending migration files yet. The runtime and the Knex wiring exist at this point, but no package has added real schema files until the next chapter.
 
 ### A place for future schema files
 
@@ -88,7 +88,7 @@ That is the key idea of this chapter:
 
 This chapter is the right place to make one distinction very explicit.
 
-There are now two different migration-related layers in the app:
+The app has two different migration-related layers:
 
 - JSKIT-managed migration files on disk
 - Knex actually applying those files to the database
@@ -171,7 +171,7 @@ import {
 } from "@jskit-ai/database-runtime/shared";
 ```
 
-This is worth calling out now because the database layer is not only "Knex plus migrations".
+This is worth calling out here because the database layer is not only "Knex plus migrations".
 
 It also gives your later repositories and services a standard persistence toolbox so every package does not have to solve the same problems differently. The main point is consistency:
 
@@ -561,7 +561,7 @@ The three new scripts are also worth reading carefully:
 
 They are not special JSKIT commands. They are ordinary project scripts, which makes them easy to run in any environment.
 
-### `.env` now owns the database connection settings
+### `.env` owns the database connection settings
 
 The package install also writes the database settings into `.env`:
 
@@ -583,7 +583,7 @@ This matters because the generic runtime is written to support more than one dri
 
 ### `knexfile.js` is for migration commands, not normal page code
 
-The migration scripts in `package.json` work because the app now has a top-level `knexfile.js`:
+The migration scripts in `package.json` work because the app has a top-level `knexfile.js`:
 
 ```js
 import path from "node:path";
@@ -628,7 +628,7 @@ It is not the main runtime API that your app code imports during a request. It i
 npm run db:migrate
 ```
 
-So there are really two separate database entry points now:
+So there are really two separate database entry points:
 
 - `knexfile.js` for migration commands
 - the JSKIT server provider runtime for application code
@@ -695,7 +695,7 @@ At first glance it can feel strange that the database layer is installed but the
 
 The reason is simple:
 
-- the runtime is now available
+- the runtime is available
 - but almost no installed package is using it yet
 
 Right now:
@@ -739,7 +739,7 @@ So the auth layer keeps behaving the same way it did before:
 - JSKIT still mirrors just enough profile data locally
 - that JSKIT-side mirror is still not persistent yet
 
-The database runtime is now ready, but the users layer that will actually use it has not been installed yet.
+The database runtime is ready, but the users layer that will actually use it has not been installed yet.
 
 ### Why the empty `migrations/` directory is important
 
@@ -747,7 +747,7 @@ The new `migrations/` directory can look almost silly at first because it only c
 
 It means:
 
-- the app now has a migration system
+- the app has a migration system
 - the app does **not** yet have a schema of its own
 
 That is exactly the right state at this stage of the guide.
@@ -758,9 +758,9 @@ The database runtime chapter should give the app a database foundation first. Th
 
 This chapter did not make the app feel dramatically different in the browser, but it changed the server foundation in an important way.
 
-- the app now has a real JSKIT database runtime
-- the app now has a standard Knex migration workflow
-- the app now has a place for future schema files
+- the app has a real JSKIT database runtime
+- the app has a standard Knex migration workflow
+- the app has a place for future schema files
 
 But just as importantly, this chapter also defined what has **not** changed yet:
 
@@ -771,5 +771,5 @@ But just as importantly, this chapter also defined what has **not** changed yet:
 So the right mental model at the end of this chapter is:
 
 - Supabase already handles real authentication
-- MySQL is now wired up and ready
+- MySQL is wired up and ready
 - the persistent JSKIT-side user model arrives in the next chapter

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

@@ -14,7 +14,7 @@ npm install
 
 The first command creates a new folder called `exampleapp` and fills it with JSKIT's base shell template. The `exampleapp` name is used in a few template replacements, such as the package name and the browser title. The `--tenancy-mode none` flag tells JSKIT to start with the smallest routing model. In this mode, the app is not workspace-aware (more of this later in the guide, when multihoming is introduced). That keeps the first scaffold easier to read because there is no workspace slug handling yet.
 
-If you are working with an AI agent and want the agent to drive the initial JSKIT setup conversation, there is now a dedicated seed path:
+If you are working with an AI agent and want the agent to drive the initial JSKIT setup conversation, use the dedicated seed path:
 
 ```bash
 npx @jskit-ai/create-app exampleapp --template ai-seed
@@ -166,23 +166,35 @@ The most important parts look like this:
     "build": "vite build",
     "build:all": "vite build",
     "build:home": "VITE_SURFACE=home vite build",
+    "preview": "vite preview",
+    "lint": "eslint .",
     "test": "node --test",
     "test:client": "vitest run tests/client",
+    "test:e2e": "playwright test tests/e2e",
     "verify": "jskit app verify && npm run --if-present verify:app",
     "release": "jskit app release",
     "jskit:update": "jskit app update-packages"
   },
   "dependencies": {
     "@local/main": "file:packages/main",
+    "@fastify/static": "^9.1.1",
     "@jskit-ai/kernel": "0.x",
+    "@tanstack/vue-query": "^5.90.5",
     "@jskit-ai/http-runtime": "0.x",
     "fastify": "^5.7.4",
+    "json-rest-schema": "^1.0.13",
     "pinia": "^3.0.4",
     "vue": "^3.5.13",
+    "vue-router": "^5.0.4",
     "vuetify": "^4.0.0"
   },
   "devDependencies": {
+    "@jskit-ai/agent-docs": "0.x",
+    "@jskit-ai/config-eslint": "0.x",
     "@jskit-ai/jskit-cli": "0.x",
+    "@playwright/test": "^1.57.0",
+    "@vitejs/plugin-vue": "^5.2.1",
+    "eslint": "^9.39.1",
     "vite": "^6.1.0",
     "vitest": "^4.0.18"
   }
@@ -191,7 +203,7 @@ The most important parts look like this:
 
 There are two details worth noticing immediately. The dependency on `@local/main` points at `file:packages/main`, which means your app already contains its own local JSKIT package. The maintenance scripts are also useful to notice early, because they show an important ownership boundary in JSKIT.
 
-`verify`, `jskit:update`, `devlinks`, and `release` are intentionally thin wrappers. They stay in `package.json` because they are convenient app-local shortcuts, but the real implementation now lives in `jskit app ...`, not in copied scaffold scripts.
+`verify`, `jskit:update`, `devlinks`, and `release` are intentionally thin wrappers. They stay in `package.json` because they are convenient app-local shortcuts, but the real implementation lives in `jskit app ...`, not in copied scaffold scripts.
 
 That matters because JSKIT maintenance policy changes over time. If the scaffold copied a large shell script into every app, existing apps would freeze the old behavior forever. By delegating to `jskit app verify`, `jskit app update-packages`, `jskit app link-local-packages`, and `jskit app release`, the app keeps the nice `npm run` shortcuts while the maintained behavior stays in the installed CLI package.
 
@@ -257,6 +269,7 @@ The important part looks like this:
 ```js
 import { createApp } from "vue";
 import { createPinia } from "pinia";
+import { QueryClient, VueQueryPlugin } from "@tanstack/vue-query";
 import { createRouter, createWebHistory } from "vue-router/auto";
 import { routes } from "vue-router/auto-routes";
 import "vuetify/styles";
@@ -265,6 +278,10 @@ import * as components from "vuetify/components";
 import * as directives from "vuetify/directives";
 import { aliases as mdiAliases, mdi } from "vuetify/iconsets/mdi-svg";
 import { createSurfaceRuntime } from "@jskit-ai/kernel/shared/surface/runtime";
+import {
+  shouldRetryTransientQueryFailure,
+  transientQueryRetryDelay
+} from "@jskit-ai/kernel/shared/support";
 import {
   bootstrapClientShellApp,
   createShellRouter
@@ -308,13 +325,28 @@ const vuetify = createVuetify({
   }
 });
 const pinia = createPinia();
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      refetchOnWindowFocus: false,
+      refetchOnReconnect: true,
+      retry: shouldRetryTransientQueryFailure,
+      retryDelay: transientQueryRetryDelay
+    }
+  }
+});
 
 void bootstrapClientShellApp({
   createApp,
   rootComponent: App,
   appConfig: config,
-  appPlugins: [pinia, vuetify],
+  appPlugins: [
+    pinia,
+    [VueQueryPlugin, { queryClient }],
+    vuetify
+  ],
   pinia,
+  queryClient,
   router,
   bootClientModules: bootInstalledClientModules,
   surfaceRuntime,
@@ -326,7 +358,7 @@ void bootstrapClientShellApp({
 });
 ```
 
-The flow is simple once you read it in order: config in, runtime in memory, router built from that runtime, UI plugin installed, app bootstrapped.
+The flow is simple once you read it in order: config in, runtime in memory, router built from that runtime, app-owned Vue plugins created once, app bootstrapped. Pinia, Vue Query, the router, and Vuetify are owned by the base app bootstrap so runtime packages share the same instances instead of carrying independent copies.
 
 <DocsInDepth title="In depth" preview-height="15rem">
 
@@ -766,7 +798,7 @@ That is why you saw `@jskit-ai/kernel` and `@jskit-ai/http-runtime` earlier in `
 
 ### Other files and options
 
-The remaining files are easier to understand once you know the core pieces above. `vite.config.mjs` configures the frontend build and the `/api` proxy used during development. `index.html` is the HTML shell Vite uses to mount Vue. `tests/` contains basic smoke tests so the app has a verification path from day one. The `scripts/` directory is now much smaller than it used to be, because JSKIT maintenance helpers such as `verify`, `jskit:update`, `devlinks`, and `release` are package-owned CLI commands rather than copied app scripts.
+The remaining files are easier to understand once you know the core pieces above. `vite.config.mjs` configures the frontend build and the `/api` proxy used during development. `index.html` is the HTML shell Vite uses to mount Vue. `tests/` contains basic smoke tests so the app has a verification path from day one. The `scripts/` directory is intentionally small because JSKIT maintenance helpers such as `verify`, `jskit:update`, `devlinks`, and `release` are package-owned CLI commands rather than copied app scripts.
 
 The `create-app` command also accepts a few other flags that are useful without changing the basic meaning of this chapter's setup. `--title <text>` lets you replace the browser title and other template text with a friendlier app name. `--target <path>` lets you choose a different output directory instead of the default `./exampleapp`. `--tenancy-mode <mode>` can seed `none`, `personal`, or `workspaces`; for this chapter we intentionally use `none` so the first scaffold stays small and non-workspace. `--force` allows writing into a non-empty target directory when you know that is what you want. `--dry-run` prints the planned file writes without touching the filesystem, which is useful when you want to inspect what the generator would do. `-h` or `--help` prints the command help.
 

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
@@ -583,13 +583,13 @@ addPlacement({
 });
 ```
 
-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 semantic placements exist:
 
@@ -597,7 +597,7 @@ If you want to add your own app-owned page into that top cog menu, first ask JSK
 npx jskit list-placements
 ```
 
-In a workspace-enabled app, that list now includes:
+In a workspace-enabled app, that list includes:
 
 ```text
 - admin.tools-menu: Admin surface tools menu actions.
@@ -620,7 +620,7 @@ That command creates `src/pages/w/[workspaceSlug]/admin/catalogue/index.vue` and
 
 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
 
@@ -666,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.
 
@@ -712,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.
 
@@ -722,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`
@@ -736,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/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
 
@@ -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 semantic `settings.sections` placement with owner `account-settings`, 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.
 
@@ -505,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`
 
@@ -700,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:
 
@@ -732,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:
 
@@ -962,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.