@jskit-ai/agent-docs 0.1.131 → 0.1.133

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

@@ -1,806 +1,72 @@
 <!-- Generated by `npm run agent-docs:build` from `packages/agent-docs/site/guide/app-setup/initial-scaffolding.md`. Do not edit manually. -->
 
-# Initial scaffolding
+---
+title: Application foundations
+description: Understand and adapt JSKIT's tested minimal and adaptive-shell source patterns.
+---
 
-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.
+# Application foundations
 
-Start in a working directory and run:
+JSKIT publishes tested source patterns instead of constructing an application
+through a questionnaire. A foundation is a concrete reference application an
+agent can copy, adapt, compose, or use as evidence.
 
-```bash
-npx @jskit-ai/create-app exampleapp --tenancy-mode none
-cd exampleapp
-npm install
-```
-
-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:
-
-```bash
-npx @jskit-ai/create-app exampleapp --template ai-seed
-cd exampleapp
-```
-
-That seed writes only `AGENTS.md`. It is not a runnable app yet. The agent should use that file to ask the Stage 1 platform questions first, make sure the chosen MySQL or Postgres database already exists or can be created with the developer's local admin access, and then promote the same directory into the real scaffold with:
-
-```bash
-npx @jskit-ai/create-app exampleapp --target . --force --tenancy-mode <mode>
-npm install
-npx jskit migrations sync
-npx jskit ci generate
-```
-
-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 default shell-web app, not the seed wrapper), you will need to run `npm install` to install dependencies.
-
-If you deliberately need the bare scaffold, use `--minimal` or `--template minimal-shell`. That is useful for 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 --no-install jskit add package shell-web`, as long as the starter files it
-claims have not been edited first. After the initial `npm install`, prefer
-`npx --no-install jskit` for every local JSKIT command so a missing local CLI
-fails clearly.
-
-When a minimal app's first feature is generated CRUD, do not pre-install the
-shell as a workaround. Add the database runtime, create the live disposable
-table, run `crud-server-generator scaffold`, and then run
-`crud-ui-generator crud`. The server
-generator installs the shell/realtime dependency closure in the correct order.
-The complete Notes command lane is in [CRUD Generators](/guide/generators/crud-generators#fresh-minimal-notes-app-the-complete-command-order).
-
-If you already know you want a small non-workspace baseline right after the scaffold, this is the shortest reproducible path:
-
-```bash
-DB_HOST=127.0.0.1
-DB_PORT=3306
-DB_NAME=exampleapp
-DB_USER=...
-DB_PASSWORD=...
-
-npx @jskit-ai/create-app exampleapp --tenancy-mode none
-cd exampleapp
-npm install
-
-npx jskit add package auth-provider-local-core
-npx jskit add package auth-web
-
-npx jskit add package database-runtime-mysql \
-  --db-host "$DB_HOST" \
-  --db-port "$DB_PORT" \
-  --db-name "$DB_NAME" \
-  --db-user "$DB_USER" \
-  --db-password "$DB_PASSWORD"
-
-npx jskit add package users-web
-npx jskit add package console-web
-
-npm run db:migrate
-```
-
-The default auth install is intentionally local and simple. Do not start a new app by adding Supabase, OAuth, OTP, provider linking, or a users/profile projection unless that complexity is already part of the app you are building.
-
-If you want the larger workspace-enabled stack with the first assistant already configured, use [Quickstart](/guide/app-setup/quickstart) instead.
-
-**Try Bash Completion!**
-
-Once `npm install` has finished, you can enable Bash completion for the JSKIT CLI. If you only want it for the current shell session, run:
+## The adaptive-shell foundation
 
-```bash
-source <(npx jskit completion bash)
-```
-
-If you want JSKIT completion to keep working in future Bash sessions as well, run:
-
-```bash
-npx jskit completion bash --install
-```
-
-That writes a small loader file into your home directory and updates `~/.bashrc` for you. To activate it in the current shell immediately, run `source ~/.bashrc`.
-
-Once completion is loaded, you can test it immediately.
-
-If you type:
+`app/shell-foundation` is the normal browser-product baseline. It includes:
 
-```bash
-npx jskit li
-```
-
-and press Tab twice, Bash will show completions such as `list`, `list-placements`, and `list-component-tokens`.
+- Fastify server and health endpoint
+- Vue/Vite client bootstrap
+- app-local provider package
+- responsive JSKIT shell
+- surfaces, placements, topology, and settings
+- lint, unit, client, build, and browser configuration
+- managed-preview identity support when the host uses it
 
-If you type:
-
-```bash
-npx jskit add p
-```
+Use it when navigation and settings are real product requirements. Replace its
+home content and vocabulary; do not preserve the concrete `reading-room` name
+when it is wrong for the product.
 
-and press Tab, JSKIT will complete that subcommand argument to `package`.
+## The minimal foundation
 
-The `jskit` command is central in the use of JSKIT. The autocompletion will help speeding things up.
+`app/minimal-foundation` keeps the same server/client/package boundaries but
+does not install the full adaptive shell. Use it for deliberately small or
+unusual products, not as a temporary hurdle before installing what was already
+known to be required.
 
-To see the app in the browser with the starter health check working, run the frontend and backend in two terminals:
+## Safe realization inside an existing repository
 
-```bash
-npm run dev
-```
-
-```bash
-npm run server
-```
-
-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:
-
-```bash
-curl http://localhost:3000/api/health
-```
-
-You should get a small JSON response with `ok: true`.
-
-## Reading the scaffold
-
-A fresh app has more structure than a plain Vue starter because JSKIT is preparing both a web shell and an application runtime from the beginning. The top-level layout looks roughly like this:
+Read the entire selected `PATTERN.md` first. Copy or author files directly in
+the initialized project. Always preserve `.git`; when present, also preserve
+existing project and agent context, including roots such as:
 
 ```text
-exampleapp/
-  .jskit/
-  config/
-  packages/main/
-  server/
-  src/
-  tests/
-  package.json
-  server.js
-  vite.config.mjs
-```
-
-The first file most people should read is `package.json`. It is the command center for the app. It tells you how to run the frontend (`npm run dev`), the backend (`npm run server`), the test suite, and the build. It also shows the most important dependencies that make the starter shell work: Vue, Vite, Fastify, the JSKIT kernel, and the HTTP runtime.
-
-The most important parts look like this:
-
-```json
-{
-  "engines": {
-    "node": "26.x"
-  },
-  "scripts": {
-    "server": "node ./bin/server.js",
-    "server:all": "node ./bin/server.js",
-    "server:home": "SERVER_SURFACE=home node ./bin/server.js",
-    "dev": "vite",
-    "dev:all": "vite",
-    "dev:home": "VITE_SURFACE=home vite",
-    "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.3",
-    "@jskit-ai/kernel": "0.1.148",
-    "@tanstack/vue-query": "^5.101.0",
-    "@jskit-ai/http-runtime": "0.1.146",
-    "@jskit-ai/shell-web": "0.1.152",
-    "fastify": "^5.8.5",
-    "json-rest-schema": "^1.0.17",
-    "pinia": "^3.0.4",
-    "vue": "^3.5.38",
-    "vue-router": "^5.1.0",
-    "vuetify": "^4.1.2"
-  },
-  "devDependencies": {
-    "@jskit-ai/agent-docs": "0.1.119",
-    "@jskit-ai/config-eslint": "0.1.145",
-    "@jskit-ai/jskit-cli": "0.2.179",
-    "@playwright/test": "1.61.1",
-    "@vitejs/plugin-vue": "^6.0.7",
-    "eslint": "^10.8.0",
-    "vite": "^8.2.1",
-    "vitest": "^4.1.9"
-  }
-}
-```
-
-Published JSKIT libraries and tooling support Node.js 22 from 22.13.0 onward, Node.js 24, and Node.js 26. Newly generated applications deliberately require Node 26: their app-level `engines` contract, `.nvmrc`, and generated verification workflow all name that runtime. The app-level contract is the runtime boundary for the app and its installed JSKIT runtime packages, while independently consumed JSKIT CLI and tooling packages retain the wider supported range. 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`, 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`, and `jskit app release`, the app keeps the nice `npm run` shortcuts while the maintained behavior stays in the installed CLI package.
-
-The Playwright scaffold follows the same rule. `playwright.config.mjs` delegates to `@jskit-ai/jskit-cli/test/playwright`, and the starter browser specs delegate their shared responsive checks to published JSKIT helpers. The generated files stay small while later JSKIT package updates can change local server startup, managed `PLAYWRIGHT_BASE_URL` handling, and `VIBE64_PLAYWRIGHT_STORAGE_STATE` support without copying that logic into each new app.
-
-The scaffold also configures `src/typed-router.d.ts` as generated output. It is intentionally absent from a fresh scaffold and ignored by Git; the Vue Router Vite plugin writes it during the first `npm run dev` or `npm run build` route scan.
-
-`jskit app verify` is worth noticing specifically. Linting, tests, and builds check your source code and runtime behavior. The JSKIT part of that flow runs `doctor`, which checks the installed package graph, capabilities, migrations, generated CI, surfaces, placements, and other JSKIT-specific health rules.
-
-After `npm install`, run `npx jskit ci generate` to write `.github/workflows/jskit-verify.yml` from installed package `ci` contracts. The baseline runs checkout, Node 26 setup, `npm ci`, and `npm run verify`. Packages can add job environment values, service containers, and explicit `before-verify` steps. For example, the database runtime adds migrations before verification. Its MySQL driver adds a MariaDB service with synthetic CI-only credentials and `DB_CLIENT=mysql2`; its Postgres driver adds the equivalent Postgres service and `DB_CLIENT=pg`.
-
-`npx jskit ci generate` replaces that one workflow in full. Do not edit it. Put application-specific CI in separate workflow files, and use `npx jskit ci generate --check` in validation lanes.
-
-The surface-specific script names are also worth noticing early, even in this tiny app. `dev:home`, `server:home`, and `build:home` are the first concrete places where surface selection shows up in the scaffold. They work by setting `VITE_SURFACE=home` on the client side and `SERVER_SURFACE=home` on the server side. In this first chapter, where `home` is the only surface, those variants behave almost the same as the default commands. Later, once more surfaces exist, those scripts become the simplest way to run or build just one surface at a time.
-
-### App surfaces in JSKIT
-
-A surface is JSKIT's name for a named slice of the application. They are a very important concept in JSKIT, since a surface can be built -- and deployed -- separately from each other. This is useful if for example you want the end-user interface _not_ to contain _any_ of the symbols/strings of the admin interface.
-
-Surfaces are defined in a very important file in JSKIT: `config/public.js`. This is the app's shared public configuration, used both by client and server. It's called "public" because it _will_ be read by the browser, and therefore it _will_ be available to the world. It defines the current tenancy mode, the default surface, and the list of surface definitions. In this first scaffold there is only one surface, `home`, which is the starter surface
-
-Even though we are using `--tenancy-mode none`, it will still be possible to add more surfaces. Every app starts with a single `home` surface, and later packages will expand that topology.
-
-Here is the part of `config/public.js` that sets that up:
-
-```js
-import { surfaceAccessPolicies } from "./surfaceAccessPolicies.js";
-
-export const config = {};
-config.tenancyMode = "none";
-
-config.surfaceModeAll = "all";
-config.surfaceDefaultId = "home";
-config.webRootAllowed = "no";
-config.surfaceAccessPolicies = surfaceAccessPolicies;
-config.surfaceDefinitions = {};
-config.surfaceDefinitions.home = {
-  id: "home",
-  label: "Home",
-  pagesRoot: "home",
-  enabled: true,
-  requiresAuth: false,
-  requiresWorkspace: false,
-  accessPolicyId: "public",
-  origin: ""
-};
-```
-
-Right next to that file is `config/surfaceAccessPolicies.js`. This is where the access rules for surfaces live. In the initial shell, `home` uses the `public` policy. You do not need to change these policies now, but you do need to know where they come from, because later packages will extend them.
-
-The starter policies are small enough to read in one glance:
-
-```js
-export const surfaceAccessPolicies = {};
-
-surfaceAccessPolicies.public = {};
-```
-
-That tells you one thing immediately: `home` is open. More specific policies only appear when later packages add them.
-
-### The client side
-
-#### Client bootstrap
-
-The `src/` directory is the frontend application. `src/main.js` is the real boot file. It creates the Vue app, sets up the router, enables Vuetify, and builds a JSKIT surface runtime from `config/public.js`. That one file is worth reading carefully because it shows the main client-side contract of a JSKIT app: scaffold config is turned into a running client shell, with the surface runtime, router, installed client modules, and app boot all wired together.
-
-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";
-import { createVuetify } from "vuetify";
-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
-} from "@jskit-ai/kernel/client";
-import { bootInstalledClientModules } from "virtual:jskit-client-bootstrap";
-import App from "./App.vue";
-import NotFoundView from "./views/NotFound.vue";
-import { config } from "../config/public.js";
-
-const surfaceRuntime = createSurfaceRuntime({
-  allMode: config.surfaceModeAll,
-  surfaces: config.surfaceDefinitions,
-  defaultSurfaceId: config.surfaceDefaultId
-});
-
-const surfaceMode = surfaceRuntime.normalizeSurfaceMode(import.meta.env.VITE_SURFACE);
-const { router, fallbackRoute } = createShellRouter({
-  createRouter,
-  history: createWebHistory(),
-  routes,
-  surfaceRuntime,
-  surfaceMode,
-  notFoundComponent: NotFoundView,
-  guard: {
-    surfaceDefinitions: config.surfaceDefinitions,
-    defaultSurfaceId: config.surfaceDefaultId,
-    webRootAllowed: config.webRootAllowed
-  }
-});
-
-const vuetify = createVuetify({
-  theme: {
-    defaultTheme: "light"
-  },
-  icons: {
-    defaultSet: "mdi",
-    aliases: mdiAliases,
-    sets: { mdi }
-  }
-});
-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,
-    [VueQueryPlugin, { queryClient }],
-    vuetify
-  ],
-  pinia,
-  queryClient,
-  router,
-  bootClientModules: bootInstalledClientModules,
-  surfaceRuntime,
-  surfaceMode,
-  env: import.meta.env,
-  fallbackRoute
-}).catch((error) => {
-  console.error("Failed to bootstrap client app.", error);
-});
-```
-
-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. Passing the same `queryClient` into `bootstrapClientShellApp(...)` also gives `shell-web` the QueryClient it observes for automatic request recovery when transport failures exhaust their normal retries.
-
-<DocsInDepth title="In depth" preview-height="15rem">
-
-`createSurfaceRuntime(...)` turns the static surface config into a small runtime registry that both the router and later client modules can query. In the starter app, the input data is basically this:
-
-```js
-config.surfaceDefinitions = {
-  home: {
-    pagesRoot: "home", // this surface lives under src/pages/home
-    requiresAuth: false,
-    accessPolicyId: "public"
-  }
-};
-
-config.surfaceDefaultId = "home"; // default surface
-config.surfaceModeAll = "all"; // unrestricted surface mode
-```
-
-That means the `home` surface itself lives under `/home`. Because `home` is also the default surface and the starter scaffold sets `webRootAllowed = "no"`, visiting `/` redirects to `/home`.
-
-That gives the client a normalized surface runtime with answers to questions such as:
-
-```js
-surfaceRuntime.DEFAULT_SURFACE_ID; // "home"
-surfaceRuntime.listEnabledSurfaceIds(); // ["home"]
-surfaceRuntime.resolveSurfaceFromPathname("/home"); // "home"
-```
-
-`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:
-
-1. Takes the generated Vue routes.
-2. Adds a fallback not-found route.
-3. Filters those routes down to the ones that belong to the current surface mode.
-4. Calls Vue Router's real `createRouter(...)` with that filtered route list.
-5. Installs a `beforeEach` guard for surface-aware redirects and access behavior.
-
-So this is not a separate routing system. It is a thin JSKIT wrapper around normal Vue Router setup, using the surface runtime to decide which routes should be active and which guard behavior should be applied.
-
-In the starter app, with only `home`, this is almost boring. It mostly means:
-
-- build the router
-- add not-found
-- enforce the `/` to `/home` redirect behavior
-
-`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.
-
-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.
-
-`bootInstalledClientModules` is the extension seam, meaning "this is the point where later-installed JSKIT packages get to join client startup". The confusing part is that it is not a normal file in your app. In `src/main.js` you import it from:
-
-```js
-import { bootInstalledClientModules } from "virtual:jskit-client-bootstrap";
-```
-
-That `virtual:` prefix is a Vite convention. It means there is no real file on disk with that name. Instead, JSKIT's Vite plugin generates that module for you during development and build.
-
-The startup path looks like this:
-
-1. `src/main.js` imports `virtual:jskit-client-bootstrap`.
-2. The JSKIT Vite plugin sees that import and generates a module on the fly.
-3. That generated module imports the `.../client` entrypoint of each installed JSKIT package that has client-side behavior.
-4. It wraps those imported modules into one function called `bootInstalledClientModules(...)`.
-5. `bootstrapClientShellApp(...)` calls that function before the router is installed and before the app is mounted.
-6. `bootClientModules(...)` then starts client providers and registers any client routes contributed by those installed packages.
-
-The generated module is roughly like this:
-
-```js
-import * as authClient from "@jskit-ai/auth-web/client";
-import * as usersClient from "@jskit-ai/users-web/client";
-import { bootClientModules } from "@jskit-ai/kernel/client/moduleBootstrap";
-
-const installedClientModules = [
-  { packageId: "@jskit-ai/auth-web", module: authClient },
-  { packageId: "@jskit-ai/users-web", module: usersClient }
-];
-
-async function bootInstalledClientModules(context = {}) {
-  return bootClientModules({
-    ...context,
-    clientModules: installedClientModules
-  });
-}
-```
-
-That is why Vite is involved. The browser cannot inspect the installed npm graph and turn it into bundler-visible imports at runtime. Vite needs a normal import graph up front. The plugin creates that graph for the app.
-
-If this were plain Vue without that plugin, you would have to maintain the list yourself:
-
-```js
-import { bootClientModules } from "@jskit-ai/kernel/client/moduleBootstrap";
-import * as authClient from "@jskit-ai/auth-web/client";
-import * as usersClient from "@jskit-ai/users-web/client";
-
-await bootClientModules({
-  app,
-  router,
-  surfaceRuntime,
-  surfaceMode,
-  clientModules: [
-    { packageId: "@jskit-ai/auth-web", module: authClient },
-    { packageId: "@jskit-ai/users-web", module: usersClient }
-  ]
-});
-```
-
-JSKIT automates that step so adding or removing packages does not require hand-editing `src/main.js`.
-
-In a brand-new shell app, there are no extra installed client modules yet, so the generated function is effectively empty. Later, when you install packages with client providers or extra UI routes, this same hook is what starts those providers and registers those routes.
-
-`bootstrapClientShellApp(...)` is the final assembly step. It creates the Vue app, installs plugins such as Pinia and Vuetify, passes the Pinia instance explicitly into client-module boot, stores the client app config, runs `bootInstalledClientModules(...)`, attaches the fallback route if needed, installs the router, waits for the router to be ready, and only then mounts the app. That order matters because installed packages need a chance to extend the app before the first render happens.
-
-</DocsInDepth>
-
-#### The main package (client side)
-
-One more client-side piece is worth seeing before looking at page files: the starter app already has its own client provider. The app-local package declares it in `packages/main/package.json` like this:
-
-```json
-{
-  "jskit": {
-    "runtime": {
-      "client": {
-        "providers": [
-          {
-            "entrypoint": "src/client/providers/MainClientProvider.js",
-            "export": "MainClientProvider"
-          }
-        ]
-      }
-    }
-  }
-}
-```
-
-That declaration is one of the things `bootClientModules(...)` uses. On the client, the lifecycle is:
-
-1. collect the installed client modules
-2. resolve the provider classes they declare
-3. create the client runtime application container
-4. run each provider's `register()` method
-5. run each provider's `boot()` method, if it has one
-
-So yes: client providers use the same `register()`/`boot()` lifecycle pattern as server providers. In the scaffold, the app-local client provider starts like this:
-
-```js
-const mainClientComponents = [];
-
-function registerMainClientComponent(token, resolveComponent) {
-  mainClientComponents.push({ token, resolveComponent });
-}
-
-class MainClientProvider {
-  static id = "local.main.client";
-
-  register(app) {
-    for (const { token, resolveComponent } of mainClientComponents) {
-      app.singleton(token, resolveComponent);
-    }
-  }
-}
-
-export {
-  MainClientProvider,
-  registerMainClientComponent
-};
-```
-
-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";
-
-registerMainClientComponent("local.main.ui.menu-link-item", () => MenuLinkItem);
-```
-
-Then `MainClientProvider.register(app)` publishes those into the client container with `app.singleton(...)`. Later packages and placement runtime code can ask for those components by token instead of importing app files directly.
-
-This code is intentionally small. `registerMainClientComponent(...)` is a private app-local registration hook, not a public validation API, so the scaffold keeps it minimal and lets obvious mistakes fail honestly when the provider is used.
-
-`MainClientProvider` does not define a `boot()` method yet, so the boot phase is effectively empty for this provider right now. But the lifecycle still supports it. If you later add `boot()`, JSKIT will run it after all client providers have finished `register()`.
-
-Inside `src/pages/` you will find both route owners and actual page components. The easy file to notice is `src/pages/home/index.vue`, because that is the page with visible content. The easy file to miss is `src/pages/home.vue`. That wrapper file contains route metadata that attaches the page tree to a JSKIT surface. When you later add more pages, that surface information is one of the things JSKIT uses to decide where a page belongs.
-
-The wrapper file is tiny, but it is doing an important job:
-
-```vue
-<route lang="json">
-{
-  "meta": {
-    "jskit": {
-      "surface": "home"
-    }
-  }
-}
-</route>
-
-<template>
-  <RouterView />
-</template>
-```
-
-This is why `src/pages/home/index.vue` becomes part of the `home` surface instead of just being "some route".
-
-**Routing: How JSKIT Reads Route Metadata**
-
-The `<route lang="json">` block is not something `shell-web` or `auth-web` parses directly.
-
-During dev/build, the file-based Vue Router plugin scans `src/pages/` and turns that block into ordinary Vue Router route metadata. Later, when navigation happens, JSKIT reads that metadata from the matched route records.
-
-That is why a block like this can affect behavior without any extra code in the page component itself:
-
-- `meta.jskit.surface` tells JSKIT which surface the page tree belongs to
-- `meta.guard.policy` can later tell JSKIT whether the route should be treated as `public` or `authenticated`
-
-So the order is:
-
-1. the router plugin reads the `<route>` block
-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 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**
-
-The `app` object in `register(app)` and `boot(app)` is JSKIT's application container.
-
-Defining values:
-
-- `app.singleton(token, factory)`: register one lazily created shared value for the whole app.
-- `app.bind(token, factory)`: register a factory that creates a fresh value every time the token is resolved.
-- `app.scoped(token, factory)`: register one value per child scope.
-- `app.instance(token, value)`: register an already-created value directly.
-- `app.tag(token, tagName)`: add a token to a named group.
-
-Typical examples look like this:
-
-```js
-app.instance("appConfig", appConfig);
-app.singleton("local.main.ui.menu-link-item", () => TabLinkItem);
-app.bind("feature.clock", () => new Clock());
-app.tag("auth.login.component", "auth.ui");
-```
-
-That means:
-
-- `instance(...)` is good for something you already created, such as loaded config.
-- `singleton(...)` is good for one shared runtime object or component resolver.
-- `bind(...)` is for "make a fresh one each time someone asks".
-- `tag(...)` lets you group related tokens so another part of the app can ask for the whole set later.
-
-Using values:
-
-- `app.make(token)`: resolve a token from the container.
-- `app.has(token)`: check whether a token is registered.
-- `app.createScope(scopeId)`: create a child scope.
-- `app.resolveTag(tagName)`: resolve all tokens in that group.
-
-Then later code can consume those registrations like this:
-
-```js
-const authGuardRuntime = app.make("runtime.auth-guard.client");
-
-if (app.has("jskit.client.vue.app")) {
-  const vueApp = app.make("jskit.client.vue.app");
-}
-
-const authUi = app.resolveTag("auth.ui");
-const requestScope = app.createScope("request:123");
-```
-
-A scope is a real child container, not just a label. You can put request-local values into it and then resolve them from the scope itself:
-
-```js
-app.singleton("logger", () => createLogger());
-
-const requestScope = app.createScope("request:123");
-requestScope.instance("request.id", "request:123");
-
-const logger = requestScope.make("logger"); // inherited from the parent app container
-const requestId = requestScope.make("request.id"); // local to this scope
-```
-
-Here:
-
-- `make(...)` gets the thing behind a token.
-- `has(...)` lets you check before assuming a token exists.
-- `resolveTag(...)` gets every token in a named group.
-- `createScope(...)` gives you a child container when you need scoped values rather than app-wide ones, and that child container can then use `make(...)`, `has(...)`, `instance(...)`, and the other container methods too.
-
-### The server side
-
-The backend entry point is `server.js`, with `bin/server.js` acting as the small executable wrapper used by the npm scripts. `server.js` starts Fastify, registers a built-in `/api/health` route, loads the provider runtime, and decides how to serve the frontend. In development, you normally visit the Vite dev server on port `5173`. In a built app, this same server can also serve the compiled frontend.
-
-The core of that startup path looks like this:
-
-```js
-async function createServer() {
-  const app = Fastify({ logger: true });
-
-  app.get("/api/health", async () => {
-    return {
-      ok: true,
-      app: "exampleapp"
-    };
-  });
-
-  const runtimeEnv = resolveRuntimeEnv();
-  const appRoot = path.resolve(process.cwd());
-  const runtime = await tryCreateProviderRuntimeFromApp({
-    appRoot,
-    profile: resolveRuntimeProfileFromSurface({
-      surfaceRuntime,
-      serverSurface: runtimeEnv.SERVER_SURFACE
-    }),
-    env: runtimeEnv,
-    logger: app.log,
-    fastify: app
-  });
-
-  registerSurfaceRequestConstraint({
-    fastify: app,
-    surfaceRuntime,
-    serverSurface: runtimeEnv.SERVER_SURFACE,
-    globalUiPaths: resolveGlobalUiPaths(runtime?.globalUiPaths || [])
-  });
-
-  return app;
-}
-```
-
-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 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.
-
-#### The main package (server side)
-
-The most unusual part of the scaffold, if you are new to JSKIT, is `packages/main/`. This is the app-local runtime package. It is not there by accident, and it is not just a convenience folder. JSKIT treats your app itself as a local package with package metadata, client provider hooks, and server provider hooks. That is why the folder contains `package.json` and a small `src/` tree of its own.
-
-You already saw the client-side provider in the client bootstrap path. The server side uses the same model: `package.json.jskit` tells JSKIT which provider class belongs to the local package, and the runtime calls `register()` and then `boot()`.
-
-The server part of that metadata looks like this:
-
-```json
-{
-  "name": "@local/main",
-  "version": "0.1.0",
-  "jskit": {
-    "kind": "runtime",
-    "runtime": {
-      "server": {
-        "providerEntrypoint": "src/server/MainServiceProvider.js",
-        "providers": [
-          {
-            "entrypoint": "src/server/MainServiceProvider.js",
-            "export": "MainServiceProvider"
-          }
-        ]
-      }
-    },
-    "metadata": {
-      "server": {
-        "routes": []
-      }
-    }
-  }
-}
+.git/
+.agents/
+.codex/
 ```
 
-This is the moment where the scaffold stops looking like "just a Vue app". The app is declaring itself as a runtime package that JSKIT can discover, load, and mutate safely.
-
-For the server side, the main file to remember is `packages/main/src/server/MainServiceProvider.js`. It stays intentionally flat and small. That is the point: `packages/main` is the app-local composition package, not the default home for new backend feature trees.
-
-The server-side provider starts like this:
-
-```js
-import { loadAppConfig } from "./loadAppConfig.js";
-
-class MainServiceProvider {
-  static id = "local.main";
-
-  async register(app) {
-    const appConfig = await loadAppConfig({
-      moduleUrl: import.meta.url
-    });
-    app.instance("appConfig", appConfig);
-  }
-
-  boot() {}
-}
-
-export { MainServiceProvider };
-```
-
-It is deliberately small because it is only for app-local glue: loading config, wiring tiny app-specific behavior, and bootstrapping shared runtime concerns. When a backend capability becomes substantial, do not grow `packages/main` into a mini service tree. Generate a dedicated package instead:
-
-```bash
-npx jskit generate feature-server-generator scaffold booking-engine
-```
-
-That keeps the ownership boundary clear: `packages/main` stays composition-only, while real server features get their own provider, service, and optional repository seams. The client side uses the same provider lifecycle; you already saw the matching pattern earlier in the client boot path.
-
-The root `package.json`, its exact JSKIT dependency versions, and
-`package-lock.json` define the installed graph. JSKIT reads each installed
-package's `package.json.jskit` metadata directly. The local `@local/main`
-package participates through its normal `file:packages/main` dependency.
-
-### 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`, and `release` are package-owned CLI commands rather than copied app scripts.
+Inspect every collision. A direct pattern copy must never need `--force` and
+must never work through a temporary directory. Rename the packaged `gitignore`
+asset to `.gitignore` when using it.
 
-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.
+## Ownership after copying
 
-**Template: Use The Default Shell Unless You Need Minimal**
+All copied files are ordinary application source. The pattern package does not
+own future edits. There is no generated-file header, pattern receipt, template
+hash, completion record, or replay journal. Framework packages continue to own
+their public runtime APIs; the application owns its product source.
 
-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.
+## Loading and errors
 
-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.
+The adaptive example demonstrates structure-matching skeletons for visible
+loading. Do not replace them with generic spinners. Keep failures local when a
+resource cannot render; use shared toast/snackbar feedback for transient user
+commands so errors do not push the working page down.
 
-## Summary
+## Verification
 
-At the end of this first step, you should have more than a generated folder. You should have a mental map. `src/` is the web app, `server.js` is the runtime server, `config/` defines surfaces and shared behavior, `packages/main/` is your app's own local JSKIT package, and the npm package graph supplies JSKIT runtime metadata. That is the foundation the next chapters will build on.
+Pattern contract tests keep both examples concrete, parseable, npm-published,
+free from interpolation tokens, and aligned with their public dependencies.
+After adapting a foundation, verify the actual application rather than
+comparing it byte-for-byte with the example.