@jskit-ai/agent-docs 0.1.118 → 0.1.120

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

@@ -27,7 +27,6 @@ From inside `exampleapp`, run:
 
 ```bash
 npx jskit add package assistant-runtime
-npm install
 npm run db:migrate
 ```
 

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

@@ -36,9 +36,9 @@ npx jskit mobile android doctor
 ```
 
 If doctor passes, the app is ready for the normal mobile workflow.
-The `jskit mobile android ...` commands expect the mobile runtime package to be
-installed in `package.json` and recorded in `.jskit/lock.json`; they do not
-install `@jskit-ai/mobile-capacitor` for you.
+The `jskit mobile android ...` commands expect
+`@jskit-ai/mobile-capacitor` in the installed npm graph; they do not install the
+runtime package for you.
 
 ## What you need on your machine
 

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

@@ -14,10 +14,9 @@ From inside `exampleapp`, run:
 
 ```bash
 npx jskit add package realtime
-npm install
 ```
 
-The first command records the runtime package in the app and updates the existing scaffold. The second command downloads the new dependencies, especially `socket.io`, `socket.io-client`, and the optional Redis adapter pieces.
+The command records the exact runtime package in the app, installs its npm graph, and updates the existing scaffold, including `socket.io`, `socket.io-client`, and the optional Redis adapter pieces.
 
 Unlike the database, users, console, and workspace chapters, this one does **not** need `npm run db:migrate`. `realtime` does not add schema files. It is transport infrastructure, not persistence.
 

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

@@ -23,10 +23,9 @@ The normal `create-app` template already has `shell-web`. If you deliberately cr
 
 ```bash
 npx jskit add package shell-web
-npm install
 ```
 
-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.
+That package addition 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`.
 
@@ -305,14 +304,14 @@ src/
 
 This chapter is where the default scaffold starts to feel layered instead of flat.
 
-### `package.json` and `.jskit/lock.json`
+### `package.json`
 
 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
 {
   "dependencies": {
-    "@jskit-ai/shell-web": "0.x",
+    "@jskit-ai/shell-web": "0.1.152",
     "@mdi/js": "^7.4.47"
   }
 }
@@ -322,9 +321,9 @@ 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 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 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 installed package exposes its runtime and generator metadata through
+`package.json.jskit`. The source created in the application is then reviewed
+and maintained as normal application code.
 
 ### The `home` surface gets a real wrapper
 
@@ -681,13 +680,21 @@ navigation.
 
 The open drawer is content-aware by default. After the visible semantic
 placements and fonts settle, `ShellLayout` measures the rendered labels and
-uses one `navigationItemSpacing` value for the icon-to-label gap and the space
-between the widest label and the drawer edge. It defaults to 12 CSS pixels and
-can be set from 8–24px. The shell remeasures when placements, localization,
-fonts, spacing, the active surface, or the window layout change, and clamps
-unusually long labels to a safe range. The
-closed desktop rail remains 80 CSS pixels wide by default, with every icon and
-its Material selected-state indicator centred in the rail. Rail tooltips use
+uses Material's 12px outer item inset and one `navigationItemSpacing` value for
+the icon-to-label gap and the space between the widest label and the drawer
+edge. The spacing defaults to 12 CSS pixels and can be set from 8–24px. The
+shell remeasures when placements, localization, fonts, spacing, the active
+surface, or the window layout change, and clamps unusually long labels to a safe range. The
+surface label appears once in the top app bar; the drawer starts with its
+destinations instead of repeating that label as an uppercase subheader.
+
+The closed desktop rail remains 80 CSS pixels wide by default, with every icon
+and its Material selected-state indicator centred in the rail. The expanded
+drawer uses the same icon centreline, so toggling the drawer reveals or hides
+labels without making the icons jump sideways. The empty space around a 24px
+icon in the default rail is intentional Material touch/indicator space, not a
+second drawer padding. Products that deliberately need a denser rail can set
+`railWidth`; the shell still enforces a 48px minimum target. Rail tooltips use
 one explicit opaque theme color pair and open on pointer hover or keyboard
 focus.
 
@@ -720,6 +727,21 @@ unsafe share of the viewport or shrink below its touch targets. The app-owned
 `navigation-item-spacing`, so an application does not need to copy or restyle
 the drawer implementation.
 
+### Updating an existing shell app
+
+Commit the app's work and run:
+
+```bash
+npm run jskit:update
+```
+
+Keep the generated/app-owned `src/components/ShellLayout.vue` wrapper and let
+it continue forwarding attributes to the package component. No copied drawer,
+`.v-navigation-drawer` CSS, duplicate surface heading, or replacement smoke
+test is required. If the product intentionally wants a denser desktop rail,
+set the supported prop in that wrapper, for example `:rail-width="64"`; omit it
+to keep the Material 3 80px default.
+
 `useShellErrorPresentationStore()` exposes the current banner, snackbar, and dialog presentation state behind `ShellErrorHost`.
 
 The simplest direct store usage looks like this:

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

@@ -29,7 +29,6 @@ From inside `exampleapp`, run:
 ```bash
 npx jskit add package auth-provider-local-core
 npx jskit add package auth-web
-npm install
 ```
 
 These package installs add the provider-neutral auth core, the auth web layer, and the local provider. They give the app working register, login, logout, session, and password recovery flows without requiring an external auth service.
@@ -483,9 +482,9 @@ The first new place to inspect is `package.json`:
     "build:auth": "VITE_SURFACE=auth vite build"
   },
   "dependencies": {
-    "@jskit-ai/auth-core": "0.x",
-    "@jskit-ai/auth-provider-local-core": "0.x",
-    "@jskit-ai/auth-web": "0.x"
+    "@jskit-ai/auth-core": "0.1.146",
+    "@jskit-ai/auth-provider-local-core": "0.1.49",
+    "@jskit-ai/auth-web": "0.1.148"
   }
 }
 ```
@@ -1042,22 +1041,15 @@ The storage-state file is a secret because it can contain authenticated cookies.
 
 Tests using managed state do not call `loginAsExistingUser()`. They begin with the runner-provided identity already present and navigate using relative paths. An ordinary browser or proxy request to `/api/dev-auth/login-as` without the private header must continue to fail with `403 Dev auth exchange is not authorized.`
 
-#### Recording the result
+#### Running the verification
 
-After the actual Playwright flow succeeds, record it through JSKIT:
+Run the focused Playwright flow directly:
 
 ```bash
-npx jskit app verify-ui \
-  --command "npx playwright test tests/e2e/contacts.spec.ts -g filters" \
-  --feature "contacts filters" \
-  --auth-mode dev-auth-login-as
+npx playwright test tests/e2e/contacts.spec.ts -g filters
 ```
 
-Use `--auth-mode session-bootstrap` when a managed runner supplied authenticated storage state.
-
-`jskit app verify-ui` executes the command and records the command, auth-mode label, feature, and changed UI files. The `--auth-mode` value describes how the Playwright command was authenticated. It does not create a session, inject a secret, or alter the browser context.
-
-For local pre-merge review, follow the recorded run with:
+For local pre-merge review, follow the focused run with:
 
 ```bash
 npx jskit doctor --against origin/main

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

@@ -16,7 +16,6 @@ From inside `exampleapp`, run:
 
 ```bash
 npx jskit add package console-web
-npm install
 npm run db:migrate
 ```
 

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

@@ -23,7 +23,6 @@ npx jskit add package database-runtime-mysql \
   --db-name "$DB_NAME" \
   --db-user "$DB_USER" \
   --db-password "$DB_PASSWORD"
-npm install
 ```
 
 The first command adds the MySQL driver package and its generic JSKIT database runtime dependency, using the explicit connection values from those `DB_*` variables:
@@ -58,7 +57,7 @@ The app gets three database scripts in `package.json`:
 ```json
 {
   "scripts": {
-    "db:migrations:sync": "jskit migrations changed",
+    "db:migrations:sync": "jskit migrations sync",
     "db:migrate": "npm run db:migrations:sync && knex --knexfile ./knexfile.js migrate:latest",
     "db:migrate:rollback": "knex --knexfile ./knexfile.js migrate:rollback",
     "db:migrate:status": "npm run db:migrations:sync && knex --knexfile ./knexfile.js migrate:list"
@@ -106,9 +105,9 @@ Never modify or replace a generator-owned baseline migration. Later schema
 evolution must use a new immutable, package-owned additive migration in the
 table's app-local package, declared through `install-migration`.
 
-The npm scripts hide the easy-to-miss first step for normal use. `npm run db:migrate` and `npm run db:migrate:status` run `npm run db:migrations:sync` first, then run Knex. That means package upgrades can add new JSKIT-managed migration files before Knex checks what is pending.
+The npm scripts run `npm run db:migrations:sync` first, then run Knex. That means newly installed package migrations are present before Knex checks what is pending.
 
-### `jskit migrations ...` writes managed migration files
+### `jskit migrations sync` writes package migration files
 
 If you run the sync script directly:
 
@@ -116,7 +115,7 @@ If you run the sync script directly:
 npm run db:migrations:sync
 ```
 
-JSKIT checks the installed package state in `.jskit/lock.json` and materializes any managed migration files that need to exist in `migrations/`.
+JSKIT reads `install-migration` entries from `package.json.jskit` across the installed npm graph and writes any missing immutable migration files into `migrations/`.
 
 That command is about the app scaffold on disk.
 
@@ -143,26 +142,25 @@ So the clean mental model is:
 
 ### When you need each step
 
-In many normal `jskit add package ...` flows, JSKIT already materializes a package's managed migration files while the package is being applied.
+In normal `jskit add package ...` flows, JSKIT synchronizes package migration files after installation.
 
 That means the most common flow is still:
 
 ```bash
 npx jskit add package users-web
-npm install
 npm run db:migrate
 ```
 
-But if you ever need JSKIT to re-materialize or refresh the managed migration files for installed packages, that is when you use:
+You can also synchronize explicitly:
 
 ```bash
-npx jskit migrations changed
+npx jskit migrations sync
 npm run db:migrate
 ```
 
 So:
 
-- use `jskit migrations ...` when you need JSKIT to write or refresh managed migration files
+- use `jskit migrations sync` when you need JSKIT to write package migration files
 - use `npm run db:migrate` when you need Knex to apply pending migration files to the real database
 - sometimes you need only `npm run db:migrate`
 - sometimes, after repair or re-materialization work, you need **both**
@@ -185,7 +183,7 @@ This command:
 2. rejects duplicate or unsafe migration ids
 3. creates an editable template under the package's
    `templates/migrations/` directory
-4. adds the matching `install-migration` mutation to the package descriptor
+4. adds the matching `install-migration` mutation to `package.json.jskit`
 5. leaves the migration unmaterialized so its implementation can still be
    completed
 
@@ -193,12 +191,11 @@ Implement and test the template first. It intentionally fails if someone tries
 to apply the untouched scaffold. Then materialize and apply it:
 
 ```bash
-npx jskit migrations package @local/workflow-record-report-values
+npx jskit migrations sync
 npm run db:migrate
 ```
 
-The materialized migration and its lock record are managed artifacts. Once
-installed, the migration id and content are immutable. Any later correction
+Once synchronized, the migration id and content are immutable. Any later correction
 must use another additive migration with a new id.
 
 SQL inside the source-controlled migration is supported when Knex does not
@@ -595,13 +592,13 @@ After installing the MySQL runtime, the important new pieces in `package.json` l
 ```json
 {
   "dependencies": {
-    "@jskit-ai/database-runtime": "0.x",
-    "@jskit-ai/database-runtime-mysql": "0.x",
+    "@jskit-ai/database-runtime": "0.1.148",
+    "@jskit-ai/database-runtime-mysql": "0.1.146",
     "knex": "^3.1.0",
     "mysql2": "^3.11.2"
   },
   "scripts": {
-    "db:migrations:sync": "jskit migrations changed",
+    "db:migrations:sync": "jskit migrations sync",
     "db:migrate": "npm run db:migrations:sync && knex --knexfile ./knexfile.js migrate:latest",
     "db:migrate:rollback": "knex --knexfile ./knexfile.js migrate:rollback",
     "db:migrate:status": "npm run db:migrations:sync && knex --knexfile ./knexfile.js migrate:list"
@@ -618,7 +615,7 @@ Those new dependencies divide into two roles:
 
 The migration scripts are also worth reading carefully:
 
-- `db:migrations:sync` writes or refreshes JSKIT-managed migration files in `migrations/`
+- `db:migrations:sync` writes missing immutable package migration files in `migrations/`
 - `db:migrate` syncs JSKIT-managed migration files, then applies all pending Knex migrations
 - `db:migrate:rollback` rolls back the last migration batch
 - `db:migrate:status` syncs JSKIT-managed migration files, then lists applied and pending migrations

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

@@ -26,13 +26,15 @@ That seed writes only `AGENTS.md`. It is not a runnable app yet. The agent shoul
 ```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 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:
+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
@@ -45,9 +47,9 @@ claims have not been edited first. After the initial `npm install`, prefer
 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, run `npm install`, create the
-live disposable table, run `crud-server-generator scaffold`, run
-`npm install` again, and then run `crud-ui-generator crud`. The server
+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).
 
@@ -77,7 +79,6 @@ npx jskit add package database-runtime-mysql \
 npx jskit add package users-web
 npx jskit add package console-web
 
-npm install
 npm run db:migrate
 ```
 
@@ -191,9 +192,10 @@ The most important parts look like this:
   "dependencies": {
     "@local/main": "file:packages/main",
     "@fastify/static": "^9.1.3",
-    "@jskit-ai/kernel": "0.x",
+    "@jskit-ai/kernel": "0.1.148",
     "@tanstack/vue-query": "^5.101.0",
-    "@jskit-ai/http-runtime": "0.x",
+    "@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",
@@ -202,9 +204,9 @@ The most important parts look like this:
     "vuetify": "^4.1.2"
   },
   "devDependencies": {
-    "@jskit-ai/agent-docs": "0.x",
-    "@jskit-ai/config-eslint": "0.x",
-    "@jskit-ai/jskit-cli": "0.x",
+    "@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",
@@ -214,7 +216,7 @@ The most important parts look like this:
 }
 ```
 
-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 JSKIT-managed 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.
+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.
 
@@ -224,11 +226,11 @@ The Playwright scaffold follows the same rule. `playwright.config.mjs` delegates
 
 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 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.
+`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.
 
-The starter scaffold also writes `.github/workflows/jskit-verify.yml`. JSKIT generates and owns that workflow as a projection of 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 without taking ownership of the whole YAML file. 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`.
+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`.
 
-The workflow content hash is recorded in `.jskit/lock.json`. Package lifecycle commands refresh it when installed requirements change and refuse to overwrite a workflow that differs from its recorded version. Application-specific CI belongs in another workflow. Use `npx jskit app sync-ci` to refresh an unmodified managed file, or `npx jskit app sync-ci --force` when you explicitly intend to replace an edited file that is already recorded as JSKIT-owned. The `--against <base-ref>` review mode still exists for local pre-merge checks and advanced CI pipelines, but the starter workflow does not assume it.
+`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.
 
@@ -463,7 +465,7 @@ async function bootInstalledClientModules(context = {}) {
 }
 ```
 
-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.
+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:
 
@@ -494,16 +496,22 @@ In a brand-new shell app, there are no extra installed client modules yet, so th
 
 #### 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:
+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:
 
-```js
-client: {
-  providers: [
-    {
-      entrypoint: "src/client/providers/MainClientProvider.js",
-      export: "MainClientProvider"
+```json
+{
+  "jskit": {
+    "runtime": {
+      "client": {
+        "providers": [
+          {
+            "entrypoint": "src/client/providers/MainClientProvider.js",
+            "export": "MainClientProvider"
+          }
+        ]
+      }
     }
-  ]
+  }
 }
 ```
 
@@ -711,35 +719,36 @@ The small `server/lib/` directory exists to keep that server boot code tidy. `ru
 
 #### 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.
+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: the descriptor tells JSKIT which provider class belongs to the local package, and the runtime calls `register()` and then `boot()`.
+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 descriptor looks like this:
+The server part of that metadata looks like this:
 
-```js
-export default Object.freeze({
-  packageVersion: 1,
-  packageId: "@local/main",
-  version: "0.1.0",
-  kind: "runtime",
-  runtime: {
-    server: {
-      providerEntrypoint: "src/server/MainServiceProvider.js",
-      providers: [
-        {
-          entrypoint: "src/server/MainServiceProvider.js",
-          export: "MainServiceProvider"
-        }
-      ]
-    }
-  },
-  metadata: {
-    server: {
-      routes: []
+```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": []
+      }
     }
   }
-});
+}
 ```
 
 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.
@@ -775,59 +784,10 @@ 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 `.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` tracks JSKIT package-install state: which JSKIT runtime packages were installed, which files, text mutations, and dependency entries JSKIT manages on their behalf, and the owned hash of app-level projections such as the composed CI workflow.
-
-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
-{
-  "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": { "...": "..." }
-    },
-    "@jskit-ai/shell-web": {
-      "packageId": "@jskit-ai/shell-web",
-      "source": {
-        "type": "catalog"
-      },
-      "managed": {
-        "packageJson": {
-          "dependencies": {
-            "@jskit-ai/shell-web": {
-              "value": "0.x"
-            },
-            "@mdi/js": {
-              "value": "^7.4.47"
-            }
-          }
-        },
-        "files": { "...": "..." },
-        "text": { "...": "..." }
-      }
-    }
-  },
-  "managed": {
-    "ciWorkflow": {
-      "path": ".github/workflows/jskit-verify.yml",
-      "hash": "<generated-sha256>"
-    }
-  }
-}
-```
-
-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 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.
+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
 
@@ -843,4 +803,4 @@ Use `--minimal` only when you deliberately need the bare scaffold. If you later
 
 ## 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.
+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.

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

@@ -27,7 +27,7 @@ JSKIT currently accepts three tenancy modes:
   - workspace slugs are user-selected rather than derived from the username
   - auto-provisioning is off by default, and self-creation is a separate policy choice
 
-Both `personal` and `workspaces` are workspace-capable modes, so they allow the workspace package descriptors to install the full workspace scaffold.
+Both `personal` and `workspaces` are workspace-capable modes, so they allow the workspace package metadata to install the full workspace scaffold.
 
 This chapter teaches `personal`, not `workspaces`.
 
@@ -41,24 +41,16 @@ If your app is already on `tenancyMode = "personal"`, run:
 
 ```bash
 npx jskit add package workspaces-core
-npm install
 npx jskit add package workspaces-web
-npm install
 npm run db:migrate
 ```
 
-**Important: This Block Is Only The Fresh Workspace Install Path**
-
-These commands are complete only if the app was already on `tenancyMode = "personal"` when `users-web` / `users-core` were originally installed, or if you already ran the recovery `npx jskit update package users-core` step above.
-
-If you changed tenancy after installing users, do not skip that update. The workspace packages add workspace runtime and routes, but `users-core` is what rewrites the app-local users scaffold into its workspace-aware shape.
-
 `workspaces-core` adds the server-side workspace runtime and schema migrations. `workspaces-web` adds the workspace-facing client surfaces, shell placements, and app-owned route files.
 
 If you want to inspect that package before installing it, this is a very good moment to use the CLI chapter's inspection command:
 
 ```bash
-npx jskit show @jskit-ai/workspaces-web --details
+npx jskit show package @jskit-ai/workspaces-web
 ```
 
 That output makes the package feel much less mysterious, because it shows the exact workspace shell contributions, settings outlets, client tokens, app-owned file writes, and capability requirements before you mutate the app.

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

@@ -79,7 +79,6 @@ npx jskit generate assistant settings-page \
   --surface admin \
   --name "Admin Assistant"
 
-npm install
 npm run db:migrate
 ```