@jskit-ai/agent-docs 0.1.47 → 0.1.49

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

@@ -2,43 +2,31 @@
 
 # A more interesting shell
 
-In the first chapter, the app was intentionally plain. That was useful because it let us see the smallest possible JSKIT scaffold without too many moving parts. In this chapter, we install `shell-web`, which is the package that turns that bare starting point into a real shell: a layout, navigation outlets, a first settings area, and a proper app-level error host.
+In the first chapter, the app started with `shell-web` already installed. That is the normal JSKIT starting point: a real layout, navigation outlets, a first settings area, and a proper app-level error host.
 
 This still is not authentication, not database work, and not multi-surface routing. The app remains small. But it starts to look and behave like something you could actually grow.
 
-## Installing `shell-web`
+## Running the shell
 
 From inside `exampleapp`, run:
 
-```bash
-npx jskit add package shell-web
-npm install
-```
-
-`jskit add` rewrites part of the scaffold and records the installed runtime package in `.jskit/lock.json`. The following `npm install` is what actually downloads the new package and its supporting dependencies.
-
-To see the result, run:
-
 ```bash
 npm run dev
 npm run server
 ```
 
-This time you really want both processes running. The new home page fetches `/api/health`, so the browser-facing dev server on port `5173` expects the backend on port `3000` to be alive as well.
-
-**Important: Install It Early**
-
-`shell-web` is not just adding new files. It also **claims and replaces part of the original scaffold** so the app can switch from the plain starter layout to the real shell layout.
+You want both processes running. The starter home page fetches `/api/health`, so the browser-facing dev server on port `5173` expects the backend on port `3000` to be alive as well.
 
-That replacement is intentionally strict: `shell-web` only takes over scaffold files if they are still **exactly** the same as the files that `create-app` originally wrote. If you have already edited those starter files, `shell-web` refuses to claim them instead of overwriting your work.
+**Minimal: Adding `shell-web` To A Bare Scaffold**
 
-That is why the intended flow is:
+The normal `create-app` template already has `shell-web`. If you deliberately created the bare scaffold with `--minimal` or `--template minimal-shell`, install the shell before you personalize the files it claims:
 
-1. scaffold the app
-2. install `shell-web`
-3. start personalizing the shell
+```bash
+npx jskit add package shell-web
+npm install
+```
 
-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.
+That install is intentionally strict: `shell-web` only takes over scaffold files if they are still **exactly** the same as the files that `create-app --minimal` originally wrote. If you have already edited those starter files, `shell-web` refuses to claim them instead of overwriting your work.
 
 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`.
 
@@ -285,7 +273,7 @@ So the shell story in this chapter is:
 
 That is the first real example of JSKIT behaving like an extension system rather than just a scaffold generator.
 
-## What `shell-web` changes in the app
+## What `shell-web` owns in the app
 
 The most interesting files look roughly like this:
 
@@ -315,11 +303,11 @@ src/
           index.vue
 ```
 
-This chapter is the first time the scaffold starts to feel layered instead of flat.
+This chapter is where the default scaffold starts to feel layered instead of flat.
 
 ### `package.json` and `.jskit/lock.json`
 
-The first file worth reopening is still `package.json`. After `shell-web`, the most important new dependency entries are:
+The first file worth reopening is still `package.json`. Because the default app includes `shell-web`, the important shell dependency entries are already present:
 
 ```json
 {
@@ -334,15 +322,15 @@ The important part is not just that `@jskit-ai/shell-web` appears. The package b
 
 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.
+The lock file records this too. In a default app, `.jskit/lock.json` already records `@local/main`, `@jskit-ai/shell-web`, and the exact files and text mutations that the shell package owns.
 
-That is worth noticing because this is the first chapter where JSKIT applies a runtime package that owns concrete changes in your app tree.
+That is worth noticing because the default scaffold is not just copied files. It starts with a JSKIT-managed runtime package that owns concrete changes in your app tree.
 
 ### The `home` surface gets a real wrapper
 
 The surface itself did not change. `home` is still the same surface defined in `config/public.js`. What changed is the page tree inside it.
 
-Before `shell-web`, `src/pages/home.vue` was only a tiny route owner with a `RouterView`. After installing `shell-web`, it becomes:
+In the shell-web scaffold, `src/pages/home.vue` is more than a tiny route owner with a `RouterView`. It wraps the surface in the app-owned shell layout:
 
 ```vue
 <route lang="json">
@@ -369,9 +357,9 @@ import { RouterView } from "vue-router";
 
 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
+### `src/placement.js` is the placement registry
 
-After installing `shell-web`, the app gets a placement registry file:
+The app has a placement registry file:
 
 ```js
 import { createPlacementRegistry } from "@jskit-ai/shell-web/client/placement";
@@ -388,7 +376,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 contains real placement entries:
+After the scaffold's shell entries plus the `placed-element` and `page` commands from this chapter, the bottom of the file contains real placement entries:
 
 ```js
 addPlacement({
@@ -498,7 +486,7 @@ So the shell itself remains stable. What changes is the registry that feeds it.
 
 The placement registry only points at tokens. Those tokens still need to resolve to real Vue components somewhere. That happens in the app-local client provider in `packages/main/src/client/providers/MainClientProvider.js`.
 
-After the `shell-web` install and the `Alerts Widget` generator command, that file contains registrations like these:
+After the scaffold's shell registrations and the `Alerts Widget` generator command, that file contains registrations like these:
 
 ```js
 import AlertsWidgetElement from "/src/components/AlertsWidgetElement.vue";
@@ -566,13 +554,31 @@ The default error policy is intent-based. Runtime code reports what kind of erro
 - `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.
 
+When app code catches a dynamic import failure itself, report it through the shell async module recovery runtime so it uses the same reload banner as router chunk failures:
+
+```js
+import { useShellAsyncModuleRecoveryRuntime } from "@jskit-ai/shell-web/client";
+
+const asyncModuleRecovery = useShellAsyncModuleRecoveryRuntime();
+
+try {
+  await import("@xterm/xterm");
+} catch (error) {
+  asyncModuleRecovery?.notify(error, {
+    label: "Terminal"
+  });
+}
+```
+
+`useShellAsyncModuleRecoveryRuntime()` returns `null` when the shell runtime is not available in the current Vue context. That lets app-owned components use optional chaining instead of duplicating shell-web's internal injection token.
+
 ### The home page talks to the backend
 
 `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` matters. The page expects the backend to be alive.
+That is why this chapter keeps running both `npm run dev` and `npm run server`. 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.
+This matters because it is a tiny example of the frontend and backend participating in the same shell. The request itself is simple, but it proves the shell can surface runtime status instead of only rendering static chrome.
 
 ### The first client stores appear
 
@@ -676,6 +682,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 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`.
+After this chapter, the app is still small, but you have inspected the shell shape it starts with. `shell-web` provides 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

@@ -12,9 +12,6 @@ To get back to the same starting point as the end of the previous chapter, run:
 npx @jskit-ai/create-app exampleapp --tenancy-mode none
 cd exampleapp
 npm install
-
-npx jskit add package shell-web
-npm install
 ```
 
 If you are already continuing from the previous chapter, you are already in the right place and can skip that setup.

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

@@ -2,7 +2,7 @@
 
 # Initial scaffolding
 
-In this first chapter, we are going to create the smallest useful JSKIT app, install its dependencies, run it locally, and read the scaffold it gives us. The goal of this chapter is to explain how to get started with JSKIT and to understand what the generator produced, which files matter, and why the project already has concepts like _surfaces_, a local runtime package, and a server even before we add any real features.
+In this first chapter, we are going to create the smallest useful JSKIT app, install its dependencies, run it locally, and read the scaffold it gives us. The default scaffold already includes `shell-web`, so the app starts with a real shell, placements, settings routes, and the app-level error host. The goal of this chapter is to explain how to get started with JSKIT and to understand what the generator produced, which files matter, and why the project already has concepts like _surfaces_, a local runtime package, and a server even before we add any real features.
 
 Start in a working directory and run:
 
@@ -12,7 +12,7 @@ cd exampleapp
 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.
+The first command creates a new folder called `exampleapp` and fills it with JSKIT's default shell-web app 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, use the dedicated seed path:
 
@@ -30,7 +30,15 @@ npm install
 
 After that promotion, the overwritten app `AGENTS.md` stays deliberately small. Use it with the distributed JSKIT agent docs when planning or implementing app changes. The durable app memory lives in `.jskit/APP_BLUEPRINT.md` and should describe product and architecture decisions, not become an implementation task list.
 
-After creating the real app scaffolding (the base shell, not the seed wrapper), you will need to run `npm install` to install dependencies.
+After creating the real app scaffolding (the default shell-web app, not the seed wrapper), you will need to run `npm install` to install dependencies.
+
+If you deliberately need the older bare scaffold, use `--minimal` or `--template minimal-shell`. That is useful for descriptor tests or unusual package-development flows, but it is not the normal starting point for a JSKIT app:
+
+```bash
+npx @jskit-ai/create-app exampleapp --minimal --tenancy-mode none
+```
+
+Minimal apps can still install the standard shell later with `npx jskit add package shell-web`, as long as the starter files it claims have not been edited first.
 
 If you already know you want a small non-workspace baseline right after the scaffold, this is the shortest reproducible path:
 
@@ -47,8 +55,6 @@ npx @jskit-ai/create-app exampleapp --tenancy-mode none
 cd exampleapp
 npm install
 
-npx jskit add package shell-web
-
 npx jskit add package auth-provider-supabase-core \
   --auth-supabase-url "$SUPABASE_URL" \
   --auth-supabase-publishable-key "$SUPABASE_KEY" \
@@ -108,21 +114,19 @@ and press Tab, JSKIT will complete that subcommand argument to `package`.
 
 The `jskit` command is central in the use of JSKIT. The autocompletion will help speeding things up.
 
-To see the app in the browser, the quickest path is:
+To see the app in the browser with the starter health check working, run the frontend and backend in two terminals:
 
 ```bash
 npm run dev
 ```
 
-Then open `http://localhost:5173/` in the browser. The starter screen is intentionally plain. That is a good thing. It proves the shell is wired correctly before we start adding packages.
-
-For the very first page, `npm run dev` is enough because the scaffold does not make any real API calls yet. For normal JSKIT development, though, you will usually keep a second terminal open and run the backend as well:
-
 ```bash
 npm run server
 ```
 
-That starts the Fastify server on port `3000`. As soon as you begin adding backend features, the frontend dev server will expect that backend to be there, because the Vite configuration proxies `/api` requests to the local server. A good habit is to treat `npm run dev` as the browser-facing process and `npm run server` as the app runtime behind it.
+Then open `http://localhost:5173/` in the browser. The starter screen is intentionally small. That is a good thing. It proves the shell is wired correctly before we start adding packages.
+
+`npm run server` starts the Fastify server on port `3000`. The default home page already uses the Vite proxy to request `/api/health`, so keep the backend running when you want the starter status to be fully green. A good habit is to treat `npm run dev` as the browser-facing process and `npm run server` as the app runtime behind it.
 
 If you want a fast sanity check that the backend is alive, open `http://localhost:3000/api/health` or request it from the terminal:
 
@@ -383,7 +387,7 @@ surfaceRuntime.listEnabledSurfaceIds(); // ["home"]
 surfaceRuntime.resolveSurfaceFromPathname("/home"); // "home"
 ```
 
-`surfaceMode` is not another surface definition. It is the current viewing mode for the app. In a plain starter app, `VITE_SURFACE` is usually unset, so `surfaceMode` becomes `"all"`, meaning "do not restrict the router to one specific surface". Later, when you run surface-specific profiles, the same runtime can narrow the active routes to just one surface. In the scaffold scripts, `npm run dev:home` is simply setting `VITE_SURFACE=home`, while `npm run dev` and `npm run dev:all` leave the client in unrestricted `"all"` mode.
+`surfaceMode` is not another surface definition. It is the current viewing mode for the app. In a starter app, `VITE_SURFACE` is usually unset, so `surfaceMode` becomes `"all"`, meaning "do not restrict the router to one specific surface". Later, when you run surface-specific profiles, the same runtime can narrow the active routes to just one surface. In the scaffold scripts, `npm run dev:home` is simply setting `VITE_SURFACE=home`, while `npm run dev` and `npm run dev:all` leave the client in unrestricted `"all"` mode.
 
 `createShellRouter(...)` uses that `surfaceRuntime` object to assemble the actual router. Concretely, it does this:
 
@@ -403,7 +407,7 @@ In the starter app, with only `home`, this is almost boring. It mostly means:
 
 `createPinia()` is the standard shared-state layer for the client app. JSKIT installs it from day 0 so later packages can expose Vue-facing stores without each app having to bolt Pinia on afterward.
 
-In the plain starter scaffold there are still no package-defined client stores to use yet. Pinia is already there so later packages can add them without changing the app bootstrap. In the next chapters, `shell-web` adds shell stores such as `useShellLayoutStore()`, and `auth-web` later adds `useAuthStore()`.
+The default scaffold already has the `shell-web` client stores available, such as `useShellLayoutStore()` and the shell error presentation store behind `ShellErrorHost`. Pinia is also there from day 0 so later packages, such as `auth-web`, can add their own stores without changing the app bootstrap.
 
 `createVuetify(...)` is the ordinary UI plugin setup. There is nothing especially JSKIT-specific there; it configures theme settings and icon aliases before the router is mounted. Vuetify components are auto-imported by `vite-plugin-vuetify`, so the scaffold does not register the full Vuetify component namespace in the client bundle.
 
@@ -521,7 +525,7 @@ export {
 };
 ```
 
-The important idea is that this provider is not rendering UI directly. It is registering token-addressable client components into the application container. In the base scaffold, that list starts empty. Later package installs and generators can extend this file by adding imports and `registerMainClientComponent(...)` calls for app-owned client components. In other words, this file is the app's local registration seam.
+The important idea is that this provider is not rendering UI directly. It is registering token-addressable client components into the application container. In the default scaffold, the list starts with shell link components that the placement runtime can use for menus and tabs. Later package installs and generators can extend this file by adding imports and `registerMainClientComponent(...)` calls for more app-owned client components. In other words, this file is the app's local registration seam.
 
 ```js
 import MenuLinkItem from "/src/components/menus/MenuLinkItem.vue";
@@ -574,7 +578,7 @@ So the order is:
 2. the generated route record gets a normal `meta` object
 3. JSKIT reads that `meta` during routing
 
-`src/App.vue` is deliberately small. It is only the outer Vuetify app shell and a `RouterView`. That is another pattern you should get used to in JSKIT: the base scaffold stays thin, and most behavior is pushed toward packages, page files, and runtime providers.
+`src/App.vue` is deliberately small. It is the outer Vuetify app shell, the top-level `RouterView`, and `ShellErrorHost`. That is another pattern you should get used to in JSKIT: the app root stays thin, and most behavior is pushed toward packages, page files, and runtime providers.
 
 **Container: App Methods**
 
@@ -686,7 +690,7 @@ async function createServer() {
 
 The health route is built in, but the more important idea is that the server is already prepared to validate HTTP input with Fastify's normal JSON Schema path, load the JSKIT provider runtime from the app itself, and constrain requests by surface.
 
-You will also notice `config/server.js`. In the base shell it is intentionally almost empty. It is there to reserve a clear place for server-side configuration as backend features are added, without pretending the starter app already has server behavior it does not yet need.
+You will also notice `config/server.js`. In the base app it is intentionally almost empty. It is there to reserve a clear place for server-side configuration as backend features are added, without pretending the starter app already has feature-specific server configuration.
 
 The small `server/lib/` directory exists to keep that server boot code tidy. `runtimeEnv.js` reads environment variables such as port and host. `surfaceRuntime.js` builds the same surface runtime that the client uses, so the server and browser agree on what surfaces exist. In the scaffold scripts, `npm run server:home` is simply setting `SERVER_SURFACE=home`, while `npm run server` and `npm run server:all` leave the server unrestricted.
 
@@ -760,7 +764,7 @@ The `.jskit/lock.json` file is also important. Treat it like JSKIT's own lock an
 
 This file is narrower than `package.json`. `package.json` lists every npm dependency the app needs, including plain libraries such as Vue, Fastify, and Vuetify. `.jskit/lock.json` only tracks JSKIT package-install state: which JSKIT runtime packages were installed into the app and which files, text mutations, and dependency entries JSKIT is managing on their behalf.
 
-On a brand-new app, the lock file is telling you that only the local app package is installed so far:
+On a brand-new default app, the lock file is telling you that the app-local package and the standard shell package are installed from the start:
 
 ```json
 {
@@ -774,35 +778,47 @@ On a brand-new app, the lock file is telling you that only the local app package
         "packagePath": "packages/main",
         "descriptorPath": "packages/main/package.descriptor.mjs"
       },
+      "managed": { "...": "..." }
+    },
+    "@jskit-ai/shell-web": {
+      "packageId": "@jskit-ai/shell-web",
+      "source": {
+        "type": "catalog"
+      },
       "managed": {
         "packageJson": {
           "dependencies": {
-            "@local/main": {
-              "value": "file:packages/main"
+            "@jskit-ai/shell-web": {
+              "value": "0.x"
+            },
+            "@mdi/js": {
+              "value": "^7.4.47"
             }
           }
-        }
+        },
+        "files": { "...": "..." },
+        "text": { "...": "..." }
       }
     }
   }
 }
 ```
 
-That is a useful anchor point. Before you add anything else, JSKIT already knows about exactly one runtime package: the one that belongs to your app.
+That is a useful anchor point. Before you add anything else, JSKIT already knows about the runtime package that belongs to your app and the shell runtime package that owns the default shell files, placement config, and error host wiring.
 
-That is why you saw `@jskit-ai/kernel` and `@jskit-ai/http-runtime` earlier in `package.json`, but you do not see them here. They are npm dependencies of the scaffold, but they are not separate JSKIT-installed app packages in this initial state.
+That is why you saw `@jskit-ai/kernel` and `@jskit-ai/http-runtime` earlier in `package.json`, but you do not see them as separate installed packages here. They are npm dependencies of the scaffold, while `.jskit/lock.json` records JSKIT package install state and managed app mutations.
 
 ### 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 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.
+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. `--minimal` selects the bare `minimal-shell` template instead of the default shell-web app template. `--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.
 
-**Next step: Install shell-web before editing the scaffold**
+**Template: Use The Default Shell Unless You Need Minimal**
 
-If the next thing you plan to do is install `shell-web`, do that **before** you start personalizing the starter shell files.
+The default app already includes `shell-web`. Start there for normal JSKIT apps because it gives you placement-aware navigation, settings routes, and shell-level error presentation immediately.
 
-`shell-web` upgrades the plain scaffold by claiming a few app-owned files such as `src/App.vue`, `src/pages/home.vue`, and `src/pages/home/index.vue`. It only does that when those files still match the untouched base scaffold exactly. If you edit them first, `shell-web` will refuse to overwrite your changes.
+Use `--minimal` only when you deliberately need the bare scaffold. If you later add `shell-web` to a minimal app, do it before editing files such as `src/App.vue`, `src/pages/home.vue`, and `src/pages/home/index.vue`, because the package only claims files that still match the untouched minimal baseline exactly.
 
 ## Summary
 

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

@@ -510,7 +510,7 @@ The other returned values are there for more advanced cases.
 - `placementContext` matters when a page needs to read the current shell/bootstrap context directly, for example available workspaces or current permissions already in the shell state.
 - `mergePlacementContext` is for pages that need to push refreshed workspace data back into the shell runtime after a fetch or save.
 
-That second case is real, but it is more advanced. It is what packaged elements such as the workspace settings client use when they need the shell's current workspace badge, selector state, or permissions to refresh after a change.
+That second case is real, but it is more advanced. It is available for app-owned workspace pages that intentionally need to push refreshed workspace state back into shell-visible context after a save.
 
 For normal custom page code, you usually do **not** start there. Start with `workspaceSlugFromRoute`.
 
@@ -589,7 +589,8 @@ That one block explains a lot of the workspace shell behavior.
 - `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`
+- the admin surface gets a workspace tools menu with `Settings` and `Members`
+- the workspace settings shell exposes its own nested menu host for app-owned settings child pages
 
 If you want to add your own app-owned page into that top cog menu, first ask JSKIT which semantic placements exist:
 

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

@@ -50,8 +50,6 @@ npx @jskit-ai/create-app testapp --tenancy-mode personal
 cd testapp
 npm install
 
-npx jskit add package shell-web
-
 npx jskit add package auth-provider-supabase-core \
   --auth-supabase-url "$SUPABASE_URL" \
   --auth-supabase-publishable-key "$SUPABASE_KEY" \

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

@@ -28,7 +28,7 @@ The easiest way to understand `jskit` is to separate it from the other tools in
 
 That separation is crucial.
 
-When you run a command such as `npx jskit add package shell-web`, JSKIT updates app-owned files and records what it changed. It does **not** replace npm, Vite, or Knex.
+When you run a command such as `npx jskit add package auth-provider-supabase-core`, JSKIT updates app-owned files and records what it changed. It does **not** replace npm, Vite, or Knex.
 
 The most important record of that managed state lives here:
 
@@ -476,7 +476,7 @@ This is not required, but it is genuinely useful once you start using commands s
 The install command comes in two main forms:
 
 ```bash
-npx jskit add package shell-web
+npx jskit add package auth-provider-supabase-core
 npx jskit add bundle auth-base
 ```
 
@@ -487,22 +487,22 @@ Those two examples look similar, but they do different things.
 Use this when you know the exact runtime package you want:
 
 ```bash
-npx jskit add package shell-web
+npx jskit add package users-web
 ```
 
-This is the command the next chapter uses.
+This is the shape of the package install commands used throughout the rest of the guide.
 
 Important defaults:
 
-- short ids such as `shell-web` resolve to `@jskit-ai/shell-web` when available
+- short ids such as `users-web` resolve to `@jskit-ai/users-web` when available
 - JSKIT records the install in `.jskit/lock.json`
 - JSKIT rewrites app-owned managed files as needed
 - npm install does **not** run unless you ask for it with `--run-npm-install`
 
-That last point is why the normal guide flow is still:
+That last point is why the normal guide flow after adding a runtime package is still:
 
 ```bash
-npx jskit add package shell-web
+npx jskit add package users-web
 npm install
 ```
 
@@ -1079,4 +1079,4 @@ And then keep one more distinction in your head:
 
 That is the mental model the rest of the guide assumes.
 
-The next chapter goes back to the normal hands-on flow and uses that model immediately by installing `shell-web`.
+The next chapter goes back to the normal hands-on flow and uses that model while inspecting the shell that default apps already include.

package/guide/agent/index.md

@@ -4,7 +4,7 @@
 
 This guide is the main hands-on path through JSKIT.
 
-It starts with a fast reproducible Quickstart, then steps back to the smaller scaffold-first chapters that explain how the app is assembled piece by piece. After that, it introduces the database-backed users layer, expands into console and workspace-aware app structure, and adds a small `App extras` section for optional runtime packages such as the Android Capacitor shell, realtime, and assistant. Finally, the guide breaks out generator-specific workflows into their own section.
+It starts with a fast reproducible Quickstart, then steps back to the scaffold-first chapters that explain the default shell and runtime shape. After that, it introduces the database-backed users layer, expands into console and workspace-aware app structure, and adds a small `App extras` section for optional runtime packages such as the Android Capacitor shell, realtime, and assistant. Finally, the guide breaks out generator-specific workflows into their own section.
 
 ## Table of Contents
 

package/package.json

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

package/reference/autogen/packages/kernel.md

@@ -657,6 +657,19 @@ Exports
 Local functions
 - `normalizeClientAppConfig(source = {})`
 
+### `client/asyncModuleRecovery.js`
+Exports
+- `createAsyncModuleRecoveryState({ label = "App module", message = "", retry = null } = {})`
+- `dismissAsyncModuleRecovery(state)`
+- `dynamicImportErrorMessage(error = null, { label = "App module", stale = isDynamicImportError(error) } = {})`
+- `guardedReloadApp({ browserWindow = typeof window !== "undefined" ? window : null, fetchFn = typeof fetch === "function" ? fetch : null, state = null, label = "App", message = "The app cannot reload because the app server is not reachable. Restart the server, then click Retry or Reload." } = {})`
+- `installAsyncModuleRecoveryHandlers({ router = null, state, label = "App module", onNotify = null, windowObject = typeof window !== "undefined" ? window : null } = {})`
+- `isDynamicImportError(error = null)`
+- `notifyAsyncModuleLoadError(state, error = null, { label = "App module", message = "", retry = null, stale = isDynamicImportError(error) } = {})`
+Local functions
+- `isRecord(value)`
+- `errorText(error = null)`
+
 ### `client/componentInteraction.js`
 Exports
 - `createComponentInteractionEmitter(emit)`
@@ -673,6 +686,13 @@ Exports
 - `getClientAppConfig`
 - `resolveMobileConfig`
 - `resolveClientAssetMode`
+- `createAsyncModuleRecoveryState`
+- `dismissAsyncModuleRecovery`
+- `dynamicImportErrorMessage`
+- `guardedReloadApp`
+- `installAsyncModuleRecoveryHandlers`
+- `isDynamicImportError`
+- `notifyAsyncModuleLoadError`
 - `normalizeIncomingAppUrl`
 - `registerMobileLaunchRouting`
 - `resolveClientBootstrapDebugEnabled`

package/reference/autogen/packages/shell-web.md

@@ -14,6 +14,17 @@ Use this on demand; do not load the full index at startup.
 
 ### src
 
+### `src/client/asyncModuleRecovery/index.js`
+Exports
+- `SHELL_ASYNC_MODULE_RECOVERY_RUNTIME_KEY`
+- `useShellAsyncModuleRecoveryRuntime`
+
+### `src/client/asyncModuleRecovery/inject.js`
+Exports
+- `SHELL_ASYNC_MODULE_RECOVERY_RUNTIME_KEY`
+- `isShellAsyncModuleRecoveryRuntime(value)`
+- `useShellAsyncModuleRecoveryRuntime()`
+
 ### `src/client/bootstrap/bootstrapErrorStatus.js`
 Exports
 - `resolveBootstrapErrorStatusCode(error)`
@@ -194,6 +205,8 @@ Exports
 - `useShellLayoutState`
 - `useShellLayoutStore`
 - `useShellErrorPresentationStore`
+- `SHELL_ASYNC_MODULE_RECOVERY_RUNTIME_KEY`
+- `useShellAsyncModuleRecoveryRuntime`
 - `BOOTSTRAP_PAYLOAD_HANDLER_TAG`
 - `registerBootstrapPayloadHandler`
 - `resolveBootstrapPayloadHandlers`
@@ -308,21 +321,26 @@ Local functions
 - `isValidSurfaceIdToken(value = "")`
 - `toInteger(value, fallback = 1000)`
 
+### `src/client/providers/appModuleLoadFailure.js`
+Exports
+- `isMissingDynamicModule(error, moduleSpecifier)`
+- `notifyDynamicImportFailure(asyncModuleRecoveryRuntime, error, { label = "App module" } = {})`
+
 ### `src/client/providers/ShellWebClientProvider.js`
 Exports
 - `ShellWebClientProvider`
 - `resolveAppPlacementTopologyExport(exported, logger)`
 Local functions
-- `isMissingDynamicModule(error, moduleSpecifier)`
-- `loadAppPlacementDefinitions(logger)`
-- `loadAppPlacementTopology(logger)`
+- `loadAppPlacementDefinitions(logger, asyncModuleRecoveryRuntime = null)`
+- `loadAppPlacementTopology(logger, asyncModuleRecoveryRuntime = null)`
 - `createErrorConfigToolkit(errorRuntime)`
-- `loadAppErrorConfig(logger, errorRuntime)`
+- `loadAppErrorConfig(logger, errorRuntime, asyncModuleRecoveryRuntime = null)`
 - `applyAppErrorConfig(errorRuntime, errorConfig = {})`
 - `isPullRefreshQuery(query = null)`
 - `createShellRefreshRuntime({ app, logger = null } = {})`
 - `installVueErrorBridge(vueApp, errorRuntime, logger)`
 - `installRouterErrorBridge(app, errorRuntime, logger)`
+- `createShellAsyncModuleRecoveryRuntime({ app, logger = null } = {})`
 
 ### `src/client/runtime/bootstrapRuntime.js`
 Exports

package/reference/autogen/tooling/create-app.md

@@ -142,6 +142,26 @@ Exports
 Exports
 - None
 
+### `templates/base-shell/src/components/menus/MenuLinkItem.vue`
+Exports
+- None
+
+### `templates/base-shell/src/components/menus/SurfaceAwareMenuLinkItem.vue`
+Exports
+- None
+
+### `templates/base-shell/src/components/menus/TabLinkItem.vue`
+Exports
+- None
+
+### `templates/base-shell/src/components/ShellLayout.vue`
+Exports
+- `default`
+
+### `templates/base-shell/src/error.js`
+Exports
+- None
+
 ### `templates/base-shell/src/main.js`
 Exports
 - None
@@ -154,6 +174,28 @@ Exports
 Exports
 - None
 
+### `templates/base-shell/src/pages/home/settings.vue`
+Exports
+- None
+
+### `templates/base-shell/src/pages/home/settings/general/index.vue`
+Exports
+- None
+
+### `templates/base-shell/src/pages/home/settings/index.vue`
+Exports
+- None
+
+### `templates/base-shell/src/placement.js`
+Exports
+- `addPlacement`
+- `getPlacements()`
+
+### `templates/base-shell/src/placementTopology.js`
+Exports
+- `addPlacementTopology(value = {})`
+- `default`
+
 ### `templates/base-shell/src/views/NotFound.vue`
 Exports
 - None
@@ -169,6 +211,114 @@ Exports
 - `toPositiveInt(value, fallback)`
 - `loadViteDevProxyEntries({ appRootUrl = import.meta.url, fallbackTarget = "" } = {})`
 
+### `templates/minimal-shell/bin/server.js`
+Exports
+- None
+
+### `templates/minimal-shell/config/public.js`
+Exports
+- `config`
+
+### `templates/minimal-shell/config/server.js`
+Exports
+- `config`
+
+### `templates/minimal-shell/config/surfaceAccessPolicies.js`
+Exports
+- `surfaceAccessPolicies`
+
+### `templates/minimal-shell/eslint.config.mjs`
+Exports
+- None
+
+### `templates/minimal-shell/packages/main/package.descriptor.mjs`
+Exports
+- None
+
+### `templates/minimal-shell/packages/main/src/client/index.js`
+Exports
+- `MainClientProvider`
+- `registerMainClientComponent`
+
+### `templates/minimal-shell/packages/main/src/client/providers/MainClientProvider.js`
+Exports
+- `MainClientProvider`
+- `registerMainClientComponent(token, resolveComponent)`
+
+### `templates/minimal-shell/packages/main/src/server/index.js`
+Exports
+- `MainServiceProvider`
+
+### `templates/minimal-shell/packages/main/src/server/loadAppConfig.js`
+Exports
+- `loadAppConfig({ moduleUrl = import.meta.url } = {})`
+
+### `templates/minimal-shell/packages/main/src/server/MainServiceProvider.js`
+Exports
+- `MainServiceProvider`
+
+### `templates/minimal-shell/packages/main/src/shared/index.js`
+Exports
+- None
+
+### `templates/minimal-shell/packages/main/src/shared/schemas/index.js`
+Exports
+- None
+
+### `templates/minimal-shell/server.js`
+Exports
+- `createServer()`
+- `startServer(options = {})`
+Local functions
+- `toRequestPathname(urlValue)`
+- `isApiPath(pathname)`
+- `hasFileExtension(pathname)`
+- `resolveGlobalUiPaths(runtimeGlobalUiPaths = [])`
+- `resolveStaticFilePath(pathname)`
+- `canServeStaticFile(distRoot, relativePath)`
+
+### `templates/minimal-shell/server/lib/runtimeEnv.js`
+Exports
+- `resolveRuntimeEnv()`
+Local functions
+- `toPort(value, fallback = 3000)`
+- `ensureRuntimeEnvLoaded()`
+
+### `templates/minimal-shell/server/lib/surfaceRuntime.js`
+Exports
+- `surfaceRuntime`
+
+### `templates/minimal-shell/src/App.vue`
+Exports
+- None
+
+### `templates/minimal-shell/src/main.js`
+Exports
+- None
+
+### `templates/minimal-shell/src/pages/home.vue`
+Exports
+- None
+
+### `templates/minimal-shell/src/pages/home/index.vue`
+Exports
+- None
+
+### `templates/minimal-shell/src/views/NotFound.vue`
+Exports
+- None
+
+### `templates/minimal-shell/vite.config.mjs`
+Exports
+- None
+Local functions
+- `clientEntry(()`
+
+### `templates/minimal-shell/vite.shared.mjs`
+Exports
+- `toPositiveInt(value, fallback)`
+- `loadViteDevProxyEntries({ appRootUrl = import.meta.url, fallbackTarget = "" } = {})`
+
 ### bin
 
 ### `bin/jskit-create-app.js`