@jskit-ai/agent-docs 0.1.1

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

@@ -0,0 +1,714 @@
+<!-- Generated by `npm run agent-docs:build` from `docs/guide/app-setup/initial-scaffolding.md`. Do not edit manually. -->
+
+# 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.
+
+Start in a working directory and run:
+
+```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 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.
+
+After creating the scaffolding (which comes with a package.json file), you will need to run `npm install` to install dependencies.
+
+**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:
+
+```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:
+
+```bash
+npx jskit li
+```
+
+and press Tab twice, Bash will show completions such as `list`, `list-placements`, and `list-component-tokens`.
+
+If you type:
+
+```bash
+npx jskit add p
+```
+
+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:
+
+```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.
+
+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:
+
+```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
+{
+  "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",
+    "test": "node --test",
+    "test:client": "vitest run tests/client",
+    "verify": "npm run lint && npm run test && npm run test:client && npm run build && npx jskit doctor"
+  },
+  "dependencies": {
+    "@local/main": "file:packages/main",
+    "@jskit-ai/kernel": "0.x",
+    "@jskit-ai/http-runtime": "0.x",
+    "fastify": "^5.7.4",
+    "pinia": "^3.0.4",
+    "vue": "^3.5.13",
+    "vuetify": "^4.0.0"
+  },
+  "devDependencies": {
+    "@jskit-ai/jskit-cli": "0.x",
+    "vite": "^6.1.0",
+    "vitest": "^4.0.18"
+  }
+}
+```
+
+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 `verify` script is also useful to notice early, because it shows the default quality gate the scaffold expects you to run later.
+
+The last command in that script, `npx jskit doctor`, is worth noticing specifically. Linting, tests, and builds check your source code and runtime behavior. `doctor` checks JSKIT-managed app state: installed package visibility, lock-file-backed managed files, and other JSKIT-specific health rules. It is there because a JSKIT app is not only code. It is also a descriptor-driven managed project.
+
+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 { createRouter, createWebHistory } from "vue-router/auto";
+import { routes } from "vue-router/auto-routes";
+import "vuetify/styles";
+import { createVuetify } from "vuetify";
+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 {
+  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({
+  components,
+  directives,
+  theme: {
+    defaultTheme: "light"
+  },
+  icons: {
+    defaultSet: "mdi",
+    aliases: mdiAliases,
+    sets: { mdi }
+  }
+});
+const pinia = createPinia();
+
+void bootstrapClientShellApp({
+  createApp,
+  rootComponent: App,
+  appConfig: config,
+  appPlugins: [pinia, vuetify],
+  pinia,
+  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, UI plugin installed, app bootstrapped.
+
+<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 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.
+
+`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.
+
+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()`.
+
+`createVuetify(...)` is the ordinary UI plugin setup. There is nothing especially JSKIT-specific there; it just makes Vuetify components, directives, theme settings, and icon aliases available to the app before the router is mounted.
+
+`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 safely discover installed packages by itself at runtime. It cannot scan `.jskit/lock.json`, inspect `node_modules`, and turn that into bundler-visible imports. 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.descriptor.mjs` like this:
+
+```js
+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 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.
+
+```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 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.
+
+**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 });
+  registerTypeBoxFormats();
+  app.setValidatorCompiler(TypeBoxValidatorCompiler);
+
+  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, 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.
+
+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 a descriptor, client provider hooks, and server provider hooks. That is why the folder contains `package.descriptor.mjs` 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: the descriptor tells JSKIT which provider class belongs to the local package, and the runtime calls `register()` and then `boot()`.
+
+The server part of that descriptor looks like this:
+
+```js
+export default Object.freeze({
+  packageVersion: 1,
+  packageId: "@local/main",
+  version: "0.1.0",
+  kind: "runtime",
+  runtime: {
+    server: {
+      providerEntrypoint: "src/server/index.js",
+      providers: [
+        {
+          discover: {
+            dir: "src/server/providers",
+            pattern: "*Provider.js"
+          }
+        }
+      ]
+    }
+  },
+  metadata: {
+    server: {
+      routes: []
+    }
+  }
+});
+```
+
+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/providers/MainServiceProvider.js`. At the beginning it is almost empty, but that emptiness is useful. It means you already have a stable place to put backend runtime code as the app grows, instead of inventing ad hoc structure later.
+
+The server-side provider starts like this:
+
+```js
+import { loadAppConfig } from "../support/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, but it already shows the pattern: register things with the app container first, then grow real backend behavior from there. The client side uses the same provider lifecycle; you already saw the matching pattern earlier in the client boot path.
+
+The `.jskit/lock.json` file is also important. Treat it like JSKIT's own lock and state file. It records which runtime packages JSKIT believes are installed and which managed changes they introduced. When you use `jskit add`, `jskit update`, or generators that depend on installed package state, this file is part of the source of truth. It belongs in version control, and you should not hand-edit it.
+
+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:
+
+```json
+{
+  "lockVersion": 1,
+  "installedPackages": {
+    "@local/main": {
+      "packageId": "@local/main",
+      "version": "0.1.0",
+      "source": {
+        "type": "local-package",
+        "packagePath": "packages/main",
+        "descriptorPath": "packages/main/package.descriptor.mjs"
+      },
+      "managed": {
+        "packageJson": {
+          "dependencies": {
+            "@local/main": {
+              "value": "file:packages/main"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+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 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.
+
+### 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 collects helper scripts for release, updating JSKIT packages, and linking a local JSKIT checkout during framework development.
+
+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.
+
+**Next step: Install shell-web before editing the scaffold**
+
+If the next thing you plan to do is install `shell-web`, do that **before** you start personalizing the starter shell files.
+
+`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.
+
+## Summary
+
+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 `.jskit/lock.json` records what JSKIT has done to the project. That is the foundation the next chapters will build on.