@jskit-ai/agent-docs 0.1.118 → 0.1.120

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

@@ -2,1144 +2,315 @@
 
 # Working with the JSKIT CLI
 
-In the first chapter, we used the JSKIT CLI, but only in passing. We created the app, installed dependencies, and moved on.
+JSKIT uses normal npm state. `package.json` declares dependencies, `package-lock.json` fixes the installed graph, and each package publishes its JSKIT metadata in `package.json.jskit`.
 
-This chapter steps back and treats the CLI as a subject in its own right.
+The CLI has four jobs:
 
-That matters because `jskit` is not just "the thing that installs packages". It is the tool that helps you:
+1. install packages and collect missing configuration;
+2. run generators;
+3. synchronize immutable migration files;
+4. generate the JSKIT CI workflow.
 
-- discover what JSKIT can do
-- inspect packages, generators, and any catalog shortcuts before using them
-- apply and re-apply JSKIT-managed mutations to your app
-- keep managed files and lock state healthy
-- create your own app-local runtime packages
+Application source belongs to the application. Git records changes to it. JSKIT does not maintain a second project-state ledger.
 
-If you understand this chapter early, the rest of the guide becomes much easier to follow.
+## Package metadata
 
-## What the CLI is actually managing
-
-The easiest way to understand `jskit` is to separate it from the other tools in the app.
-
-- `jskit` manages JSKIT-owned app mutations
-- `npm install` downloads dependencies from `package.json`
-- `npm run dev` and `npm run build` run Vite
-- `npm run server` runs the backend
-- `npm run db:migrate` runs Knex migrations against the database
-
-That separation is crucial.
-
-When you run a command such as `npx jskit add package auth-provider-local-core`, JSKIT updates app-owned files and records what it changed. It does **not** replace npm, Vite, or Knex.
-
-The most important record of that managed state lives here:
-
-```text
-.jskit/lock.json
-```
-
-That lock file is the source of truth for installed JSKIT-managed package state. It records things like:
-
-- which JSKIT packages are installed
-- which options were used when they were installed
-- which package.json fields were added or changed
-- which managed files or text mutations belong to each package
-
-That is why commands such as `update`, `remove`, `position`, `migrations`, and `doctor` all care about `.jskit/lock.json`.
-
-### App-owned does not mean disposable
-
-A path recorded in `.jskit/lock.json` remains managed while its owning package
-is installed. “App-owned” means customizable, not disposable while the package
-remains installed. You may edit the file; you may not delete or rename it
-without changing the managed package contract.
-
-Never delete or rename a recorded managed path. Adapt generated infrastructure
-tests in place. If a starter product route is replaced, update the scaffold
-smoke test to exercise the new canonical route instead of deleting baseline
-browser coverage. In particular, preserve managed tests such as
-`tests/e2e/base-shell.spec.ts` and `tests/e2e/adaptive-shell.spec.ts`. Doctor
-must continue to flag a managed test that is missing.
-
-## JSKIT-managed app maintenance scripts
-
-The scaffolded app also has a small set of `npm run` shortcuts that are really wrappers around JSKIT-owned maintenance behavior.
-
-The important examples are:
-
-- `npm run verify`
-- `npm run jskit:update`
-- `npm run release`
-
-In the current scaffold, those scripts are intentionally thin:
+A JSKIT package is an ordinary npm package with a `jskit` object in `package.json`:
 
 ```json
 {
-  "scripts": {
-    "verify": "jskit app verify && npm run --if-present verify:app",
-    "jskit:update": "jskit app update-packages",
-    "release": "jskit app release"
+  "name": "@acme/example-core",
+  "version": "1.2.3",
+  "type": "module",
+  "dependencies": {
+    "@jskit-ai/kernel": "0.1.148"
+  },
+  "jskit": {
+    "kind": "runtime",
+    "capabilities": {
+      "provides": ["example.core"],
+      "requires": []
+    },
+    "options": {},
+    "runtime": {
+      "server": {
+        "providers": []
+      },
+      "client": {
+        "providers": []
+      }
+    },
+    "mutations": {
+      "dependencies": {
+        "runtime": {},
+        "dev": {}
+      },
+      "packageJson": {
+        "scripts": {}
+      },
+      "files": [],
+      "text": [],
+      "source": []
+    }
   }
 }
 ```
 
-That is a deliberate design choice.
-
-The app keeps the handy `npm run` names, but the real maintenance policy lives in the installed CLI package instead of copied shell scripts inside the app. That means if JSKIT later changes how package updates or baseline verification should work, apps can pick up the new behavior by updating `@jskit-ai/jskit-cli` instead of hand-editing frozen scaffold files.
-
-This gives you a clean ownership split:
-
-- app-owned scripts still describe how *this app* runs, builds, and tests
-- JSKIT-owned wrapper scripts delegate framework maintenance to `jskit app ...`
-
-That split is worth keeping in mind through the rest of the guide. When you see `npm run verify`, read it as "run the app's JSKIT baseline verification policy, then any app-specific extra verification hook".
-
-The starter scaffold also includes `.github/workflows/jskit-verify.yml`. This is a JSKIT-managed projection, not a static template. Installed package descriptors can contribute CI environment values, services, and preparation steps through their top-level `ci` contract. Published JSKIT libraries and tooling support Node.js 22 from 22.13.0 onward, Node.js 24, and Node.js 26, while newly generated applications require Node 26. The managed workflow enforces that application runtime for dependency installation and verification. JSKIT composes the contributions and renders the workflow in this order: checkout, Node 26 setup, `npm ci`, package-contributed `before-verify` steps, and `npm run verify`.
-
-For example, `database-runtime` contributes the `database-migrations` step. Its MySQL driver contributes a MariaDB service with `DB_CLIENT=mysql2`, while its Postgres driver contributes a Postgres service with `DB_CLIENT=pg`. Each driver supplies matching synthetic CI-only `DB_*` values; local `.env` values are never copied into the workflow.
-
-The workflow path and generated content hash live under `managed.ciWorkflow` in `.jskit/lock.json`. Package add, remove, update, and app-wide package updates refresh this projection. If the workflow no longer matches its recorded hash, JSKIT refuses to overwrite it during those operations. Move application-specific jobs to another workflow, then explicitly regenerate the managed projection with:
-
-```bash
-npx jskit app sync-ci
-```
-
-The command refuses to replace an edited workflow unless you explicitly run `npx jskit app sync-ci --force`. Even with `--force`, it replaces the file only when `.jskit/lock.json` already records JSKIT ownership. It does not claim an unrecorded `.github/workflows/jskit-verify.yml` or remove a customized legacy `.github/workflows/verify.yml`.
+Package identity, version, description, exports, npm dependencies, peer dependencies, and optional dependencies stay in their standard `package.json` fields. Do not repeat npm dependencies in a JSKIT-specific dependency graph.
 
-If your app uses a non-default npm registry for JSKIT packages, pass it to the maintained CLI command rather than hard-coding it in the scaffold. For example:
+`jskit.mutations.dependencies` has a narrower job: it adds direct dependencies
+needed by generated application-owned source or application-level tooling. It
+does not declare relationships between JSKIT packages and does not affect
+package ordering.
 
-```bash
-npm run jskit:update -- --registry https://registry.example.com
-npm run release -- --registry https://registry.example.com
-```
+`runtime.server.providers` and `runtime.client.providers` declare runtime entrypoints. A provider class may use `static dependsOn` to order providers inside the runtime container; that is provider boot ordering, not package installation.
 
-### Update JSKIT packages across an app workspace
+Use exact versions for `@jskit-ai/*` dependencies. npm's `package-lock.json` remains the reproducible installation record.
 
-`npx jskit app update-packages` owns the complete app-wide JSKIT update. At the app root, it installs the exact latest registry version of every `@jskit-ai/*` package listed in `dependencies`, `devDependencies`, `optionalDependencies`, or `peerDependencies`. Exact root versions keep the installed app and its managed lock state reproducible.
-
-When the app declares npm workspaces, the command asks npm for the workspace graph and aligns JSKIT references in each workspace `package.json` and `package.descriptor.mjs` to the latest major range, such as `0.x`. Descriptor dependency mutations are included whether they use a direct string or a conditional `{ version, when }` record. It then runs `npm update --workspaces` for those packages so `package-lock.json` reflects the aligned ranges. Non-JSKIT dependencies and the public descriptor format are left alone.
-
-Updating npm packages is only half of a JSKIT upgrade. Package descriptors also own managed files, source and text mutations, lock metadata, migrations, and CI contributions. After installing newer root packages, `update-packages` compares their target versions with the installed records in `.jskit/lock.json`. It reapplies each changed installed package through the same `jskit update package ...` lifecycle used for a manual update. The newly installed local CLI performs that work, saved package options are reused, and customized app-owned files remain protected by the normal ownership checks. The updater reloads the lock between packages, so a dependency already upgraded while reapplying another package is not applied twice.
-
-This means the normal existing-app upgrade is one command:
+## Install a package
 
 ```bash
-npm run jskit:update
+npx jskit add package shell-web
 ```
 
-After it succeeds, npm dependencies and descriptor-managed app state are current together. If a managed app-owned file is missing, a required saved option can no longer be resolved, or another package update cannot be applied safely, the app-wide update fails instead of leaving that package silently stale. `--dry-run` reports which installed packages would be reapplied without invoking their update lifecycle.
-
-At the start of a real update, JSKIT resolves and installs the latest `@jskit-ai/jskit-cli`, then hands the rest of the operation to that app-local CLI process. This keeps the one-command contract even when the updater itself has changed: the current code, not the already-running older process, owns package reapplication, migrations, workspace refreshes, and CI synchronization.
-
-Do not pre-install the CLI separately and do not edit `.jskit/lock.json`. Run `npm run jskit:update`; the updater owns its bootstrap and writes managed state through the normal package lifecycle.
-
-The update reports elapsed progress for registry and install work. It also refreshes JSKIT-managed migrations and CI after root package changes. Preview the complete operation without changing manifests, descriptors, the lockfile, migrations, or CI with:
+Short JSKIT ids resolve to their `@jskit-ai/*` package ids. A full package id also works:
 
 ```bash
-npx jskit app update-packages --dry-run
+npx jskit add package @jskit-ai/shell-web
 ```
 
-For older apps that still carry copied maintenance scripts, the migration path is:
+The command:
 
-```bash
-npx jskit app adopt-managed-scripts
-```
+1. resolves the requested package;
+2. computes the resulting npm package graph and validates capabilities and CI contributions;
+3. collects missing configuration for installed runtime packages in dependency order;
+4. asks for the requested package last;
+5. writes an exact direct dependency and runs `npm install` when needed;
+6. applies the requested package's initial app mutations;
+7. synchronizes package migrations;
+8. regenerates the JSKIT CI workflow.
 
-That command rewrites known old scaffold values to the thin wrapper form above.
+Validation happens before application files or migrations are changed. A CI contribution conflict or incomplete capability graph stops the install.
 
-For older apps that were installed before JSKIT source mutations replaced raw source appends, run the source migration after updating JSKIT packages:
+Use `--dry-run` to inspect a supported install without writing, and `--json` when another tool needs structured output.
 
 ```bash
-npx jskit app update-packages
-npx jskit app migrate-source-mutations --dry-run
-npx jskit app migrate-source-mutations
-npm run verify
+npx jskit add package database-runtime-mysql --dry-run
+npx jskit add package database-runtime-mysql --json
 ```
 
-That migration is the one upgrade script for JSKIT-owned legacy source mutation shapes. It currently normalizes:
-
-- `packages/main/src/client/providers/MainClientProvider.js`: moves legacy appended `registerMainClientComponent(...)` calls before `class MainClientProvider`, which is the layout produced by current descriptor `mutations.source` installs.
-- `src/pages/**` CRUD form field modules: folds legacy `UI_CREATE_FORM_FIELDS.push(...)` and `UI_EDIT_FORM_FIELDS.push(...)` calls into the corresponding array literals.
+## Configuration prompts
 
-The command is idempotent, so rerunning it should report that the source files are already current.
+`jskit add` scans installed runtime packages for declared options. Packages with unresolved required configuration are prompted dependency-first. The requested package is prompted last.
 
-## Discover first, change second
-
-One of the best habits in JSKIT is to inspect the catalog before mutating the app.
-
-### Start with `help`
-
-The top-level overview is:
-
-```bash
-npx jskit help
-```
+This means a partially configured app can recover during the next normal package addition. Configuration discovery comes from:
 
-That shows the available commands such as:
+- the installed npm dependency graph;
+- each installed package's `package.json.jskit.options`;
+- current application config and environment values.
 
-- `app`
-- `list`
-- `show`
-- `add`
-- `update`
-- `remove`
-- `position`
-- `migrations`
-- `create`
-- `doctor`
+Sensitive values can be written through the package's declared environment mutation. They are not stored in JSKIT project state.
 
-Every command in the CLI also has its own help page. For example:
+For automation, pass package options inline:
 
 ```bash
-npx jskit help app
-npx jskit help add
-npx jskit help migrations
+npx jskit add package database-runtime-mysql \
+  --db-host database \
+  --db-port 3306 \
+  --db-name app \
+  --db-user app \
+  --db-password "$DB_PASSWORD"
 ```
 
-That is the fastest way to check current usage without leaving the terminal.
+## Third-party packages
 
-### Use `list` for discovery
+Third-party authors publish an ordinary npm package containing `package.json.jskit`. No JSKIT registration step is required.
 
-The broad catalog view is:
+Install it at an exact version, then target it by its npm id:
 
 ```bash
-npx jskit list
+npm install --save-exact @acme/example-core@1.2.3
+npx jskit add package @acme/example-core
 ```
 
-By default, this prints three groups:
+The CLI reads the installed package manifest and its package files directly. Package templates referenced by `jskit.mutations.files` must be included in the npm package's `files` allowlist.
 
-- bundles
-- runtime packages
-- generators
+If an ecosystem package should support a short id or appear in the built-in JSKIT list, it can additionally be included in the JSKIT catalog. That is discovery metadata for the built-in distribution, not a requirement for package execution.
 
-That distinction matters.
+## Bundles
 
-#### Bundles
-
-A bundle is a curated install shortcut for several runtime packages that are meant to go together. Bundles can still appear in the catalog for compatibility and quick inspection, but the guide uses explicit package installs so the real runtime packages stay visible.
-
-#### Runtime packages
-
-These are the actual packages that change how the app runs. Packages such as `shell-web`, `auth-web`, `users-web`, and `workspaces-web` belong here.
-
-These are the things you install with:
+A bundle selects two or more runtime packages for one installation:
 
 ```bash
-npx jskit add package ...
+npx jskit add bundle auth-local
 ```
 
-#### Generators
+Bundle definitions contain package ids only. npm dependencies still define package dependency relationships. Configuration follows the same dependency-first order, with the explicitly requested packages last.
 
-Generators are tooling packages such as `ui-generator`, `crud-server-generator`, and `crud-ui-generator`.
+## Generators
 
-They are **not** runtime installs.
-
-You do **not** add them with `jskit add`. You run them with:
+List and inspect generators:
 
 ```bash
-npx jskit generate ...
-```
-
-That distinction is easy to miss at first, and it is one of the main reasons this chapter exists.
-
-If you only want one section of the catalog, use a mode:
-
-```bash
-npx jskit list packages
 npx jskit list generators
+npx jskit show package crud-server-generator
 ```
 
-Those two commands are especially useful later in the guide, once you already know roughly what kind of thing you are looking for.
-
-If you want bundle members printed inline too, `npx jskit list --full` expands the bundle view. That is useful when you are auditing a shortcut, but package ids are still the normal install vocabulary in this guide.
-
-One more detail is worth noticing. In repos that contain local package descriptors, `list packages` can also show app-local or repo-local packages in addition to the published catalog. So `list` is not only a remote catalog browser. It is also a view of what this app can currently see.
-
-### Use `show` before you install
-
-Once `list` helps you find the right id, `show` is how you inspect it.
-
-The basic form is:
-
-```bash
-npx jskit show <id>
-```
-
-And the more useful inspection form is:
-
-```bash
-npx jskit show <id> --details
-```
-
-This command is unusually valuable in JSKIT because packages and catalog shortcuts do more than "add a dependency". They can:
-
-- provide or require capabilities
-- register runtime providers
-- contribute placement entries
-- write files into the app
-- mutate `package.json`, scripts, and text blocks
-
-So `show` is the command that answers:
-
-- what does this thing actually install?
-- what does it depend on?
-- what runtime surfaces does it contribute?
-- what app-owned files will it write or mutate?
-- what container tokens or import surfaces does it expose?
-
-The plain form is useful when you only want to identify something quickly. `--details` is what turns `show` into a real architecture-inspection command.
-
-### What `show` is good at
-
-There are two especially common cases:
-
-- you found a package or shortcut in `jskit list` and want to know what it really does before you install it
-- you already know a package changed the shell, the runtime graph, or the app tree, and you want to see *how*
-
-That second case matters just as much as the first one. Later in the guide, chapters explain package behavior one feature at a time. `show --details` is the generic command that lets you inspect those same package contracts directly.
-
-### A first example: inspect the local auth provider
-
-Run:
-
-```bash
-npx jskit show auth-provider-local-core --details
-```
-
-This output is short, but it already teaches something important:
-
-- `auth-provider-local-core` is a **runtime package**
-- it selects the local auth provider
-- it depends on the provider-neutral `auth-core`
-
-The default local auth install uses two direct package commands:
+Run a generator:
 
 ```bash
-npx jskit add package auth-provider-local-core
-npx jskit add package auth-web
+npx jskit generate crud-server-generator scaffold contacts \
+  --surface app \
+  --grant-policy workspace_member
 ```
 
-That is exactly the kind of thing you want to know before you mutate the app:
-
-- which package selects the active provider?
-- which package adds the web auth routes and login UI?
+Generator packages are development dependencies. Their transitive dependencies are tooling dependencies and are not activated as application runtime packages.
 
-It also helps you keep the mental model straight:
+Generated source belongs to the application immediately. Edit it normally and review it in Git.
 
-- runtime packages are the things that actually provide capabilities
-- `auth-provider-local-core` provides the selected `auth.provider`
-- `auth-web` consumes the selected provider and adds the web surface
+## App-local packages
 
-### A richer example: what does `workspaces-web` contribute?
-
-Run:
+Create a local package:
 
 ```bash
-npx jskit show @jskit-ai/workspaces-web --details
-```
-
-This is where `--details` becomes much more powerful.
-
-The compact form of `show` is fine when you only want the package description. The detailed form can show things like:
-
-- provided and required capabilities
-- summary import surfaces / exported subpaths
-- container tokens
-- placement outlets
-- default placement contributions
-- dependency mutations
-- script mutations
-- text mutations
-- file writes
-- runtime providers
-
-That makes `show --details` one of the best "read before you write" commands in the whole CLI.
-
-### Why `--details` matters
-
-The plain form:
-
-```bash
-npx jskit show @jskit-ai/workspaces-web
-```
-
-is mainly for identifying the package at a glance.
-
-The detailed form:
-
-```bash
-npx jskit show @jskit-ai/workspaces-web --details
+npx jskit create package contacts
 ```
 
-is for understanding the package as part of the app architecture. It lets you answer concrete questions from one command instead of hunting across descriptors and generated files.
-
-That is the version you should prefer when you are making a real install decision.
-
-### What `show --details` teaches you
-
-The output is not one giant wall of metadata. It is answering several practical questions. You do not need to read every line. Read the sections that answer the question you currently have.
-
-#### "What capabilities does this package participate in?"
-
-The `Capabilities` section tells you:
-
-- what the package provides
-- what it requires from other packages
-
-That helps you reason about dependency direction and why some packages bring others with them.
-
-For `@jskit-ai/workspaces-web`, the detailed output shows:
-
-- it **provides** `workspaces.web`
-- it **requires** `users.web` and `workspaces.core`
-
-That immediately tells you this package is not just some loose UI helper. It is the web layer of the workspace feature set, and it expects the users and workspace core layers underneath it.
-
-#### "What UI does this package contribute?"
-
-The placement sections are often the most useful part of `show --details`.
-
-For `@jskit-ai/workspaces-web`, the detailed output shows placement contributions such as:
-
-- the workspace selector in `shell.identity`
-- the pending invites cue in `shell.status`
-- the workspace tools widget on the `admin` surface
-- the `Members` and workspace settings menu entries
-
-That lets you answer a very concrete question before installing anything:
-
-- *what will change in the shell if I add this package?*
-
-It also shows semantic placement topology, such as:
-
-- `page.section-nav` with owner `admin-settings`
-- `admin.tools-menu`
-
-which helps you understand where later app-owned pages or settings links can attach.
-
-#### "What import paths, tokens, or providers does it register?"
-
-The detailed output can also show:
-
-- summary import surfaces / exported subpaths
-- container tokens
-- runtime providers
-
-For `@jskit-ai/workspaces-web`, that includes client tokens such as:
-
-- `workspaces.web.workspace.selector`
-- `workspaces.web.workspace.tools.widget`
-- `workspaces.web.members-admin.element`
-
-It also shows a short `Summary` section with the main client import surfaces, such as:
-
-- `@jskit-ai/workspaces-web/client`
-- `@jskit-ai/workspaces-web/client/providers/WorkspacesWebClientProvider`
-- `@jskit-ai/workspaces-web/client/composables/useWorkspaceRouteContext`
-
-That gives you a quick view of the package's client integration surface without reading the source first.
-
-This is especially useful when you are asking questions like:
-
-- *does this package expose a client entrypoint I can import from?*
-- *does it register a provider, or am I expected to wire components myself?*
-- *what token name should I expect to see in placements or providers?*
-
-#### "What app-owned files will it touch?"
-
-The `File writes`, `Text mutations`, `Source mutations`, and `Script mutations` sections answer one of the most practical questions in JSKIT:
-
-- *what will this package actually do to my app tree?*
-
-For `@jskit-ai/workspaces-web`, the detailed view shows app-owned files such as:
-
-- workspace surface route scaffolds
-- workspace settings pages
-- `WorkspaceNotFoundCard.vue`
-- `useWorkspaceNotFoundState.js`
-
-It also shows text mutations such as:
-
-- appending placement entries to `src/placement.js`
-
-And it shows source mutations such as:
-
-- adding imports to `packages/main/src/client/providers/MainClientProvider.js`
-- registering component tokens in `packages/main/src/client/providers/MainClientProvider.js`
-
-That matters because JSKIT packages are not only libraries. Many of them also write scaffold files into the app and extend app-owned provider files.
-
-### The kinds of questions this answers well
-
-Once you get used to it, `show --details` is the fast answer to questions like:
-
-- *what does this bundle really install?*
-- *why did this package add a new shell widget?*
-- *which capabilities does this package provide and require?*
-- *which app-owned files will JSKIT write if I install this?*
-- *where do later pages or placements plug into this package?*
-- *what container tokens or client entrypoints does this package expose?*
-
-### How to read the output at a high level
+This creates `packages/contacts/package.json` with a `jskit` object and adds an exact `file:` dependency to the application.
 
-Not every package shows every section, and that is normal. A good reading order is:
+The package can use standard npm dependencies and exports. Put server and client providers in `package.json.jskit.runtime`.
 
-1. `Information`
-   - what is this thing?
-2. `Summary`
-   - what are the main import paths or public entrypoints?
-3. `Depends on`
-   - what else does it need?
-4. `Capabilities`
-   - what role does it play in the runtime graph?
-5. `Placement contributions` / `Placement outlets`
-   - what UI surfaces does it add?
-6. `File writes`, `Text mutations`, and `Source mutations`
-   - what app-owned files will change?
-7. `Runtime providers` and `Container tokens`
-   - what does it register internally?
+## Migrations
 
-That is enough to make `show --details` useful without treating it like a formal spec.
-
-### A simple rule of thumb
-
-Use:
+Packages declare migration templates with `install-migration` file mutations. Synchronize them into the application with:
 
 ```bash
-npx jskit show <id>
+npx jskit migrations sync
 ```
 
-when you only want to identify a package or bundle quickly.
-
-Use:
+Check without writing:
 
 ```bash
-npx jskit show <id> --details
+npx jskit migrations sync --check
 ```
 
-when you are seriously considering installing it, or when you need to understand why a package changed the shell, the config, or the runtime in a particular way.
-
-## Make the terminal nicer: `completion`
-
-The CLI also ships with Bash completion:
-
-```bash
-npx jskit completion bash
-```
-
-That prints the completion script to stdout.
-
-If you only want completion for the current shell session, run:
-
-```bash
-source <(npx jskit completion bash)
-```
+Migration ids are immutable. The same package and migration id must always produce the same content. A conflict fails instead of overwriting migration history.
 
-If you want JSKIT completion to keep working in future Bash sessions too, run:
+Synchronization changes files only. Apply database migrations separately:
 
 ```bash
-npx jskit completion bash --install
+npm run db:migrate
 ```
 
-This is not required, but it is genuinely useful once you start using commands such as `add`, `generate`, and `show` frequently.
-
-## Installing runtime capability: `add`
-
-The install command you will use most often is:
+Create an app-owned package migration with:
 
 ```bash
-npx jskit add package users-web
+npx jskit create migration \
+  --package @local/contacts \
+  --id add-contact-status
 ```
 
-That command installs one runtime package and its dependency chain.
+Implement the package template, run `npx jskit migrations sync`, review the generated migration, and then run the database migration command.
 
-### `add package`
+## CI generation
 
-Use this when you know the exact runtime package you want:
+Generate the JSKIT verification workflow:
 
 ```bash
-npx jskit add package users-web
+npx jskit ci generate
 ```
 
-This is the shape of the package install commands used throughout the rest of the guide.
-
-Important defaults:
-
-- short ids such as `users-web` resolve to `@jskit-ai/users-web` when available
-- JSKIT records the install in `.jskit/lock.json`
-- JSKIT rewrites app-owned managed files as needed
-- npm install does **not** run unless you ask for it with `--run-npm-install`
-
-That last point is why the normal guide flow after adding a runtime package is still:
+Check it without writing:
 
 ```bash
-npx jskit add package users-web
-npm install
+npx jskit ci generate --check
 ```
 
-`jskit add` changes the app. `npm install` downloads the dependencies that the changed app requires.
-
-### `add bundle`
-
-Bundles are a convenience layer for catalog shortcuts. Prefer package commands in setup docs and normal app work, especially for auth, because provider ownership is clearer when the selected provider package is installed explicitly.
-
-If you do use a bundle shortcut, inspect it first with `npx jskit show <bundle-id> --details` so you can see the real packages and capabilities it will install.
-
-### Generator packages are different
-
-This is worth saying one more time because it causes confusion early on.
-
-If `npx jskit list generators` shows a package such as `crud-ui-generator`, that does **not** mean you should run:
+This command fully generates one file:
 
-```bash
-npx jskit add package crud-ui-generator
+```text
+.github/workflows/jskit-verify.yml
 ```
 
-Generators are tooling packages. You use them through `jskit generate`, not `jskit add`.
-
-## Managed-file lifecycle: `update`, `remove`, and `position`
-
-Once a package is installed, JSKIT treats it as managed app state, not just as "one more dependency".
-
-That state lives in `.jskit/lock.json`, which is why lifecycle commands all start from the lock record for the installed package. In practice, that means JSKIT remembers:
-
-- which package is installed
-- which install options were used
-- which files, text mutations, dependency entries, and migrations it owns
-- the path and content hash of the composed JSKIT CI workflow
+Do not edit that file. Put application-specific CI jobs in separate, application-owned workflow files.
 
-The easiest way to think about the lifecycle is:
+Packages contribute CI environment values, services, and pre-verification steps through `package.json.jskit.ci`. Conflicting contributions fail with the contributing package ids.
 
-1. `jskit add package ...` creates managed state
-2. `jskit update package ...` reapplies that managed state
-3. `jskit position element ...` reapplies just the positioning layer
-4. `jskit remove package ...` removes the managed state
-
-Package add, update, and remove also recompose `.github/workflows/jskit-verify.yml` from the complete installed package set. No individual package owns that file through `mutations.files`; it is one app-level projection with contributions from many descriptors.
-
-That is a better mental model than thinking of these as three unrelated commands.
-
-### `update` re-applies one installed package
-
-The basic shape is:
+## Update JSKIT packages
 
 ```bash
-npx jskit update package workspaces-web
+npm run jskit:update
 ```
 
-This does **not** mean "fetch the newest npm version" in the way people often expect from other ecosystems.
-
-In JSKIT, `update package ...` means:
+The script runs `jskit app update-packages`. It installs current `@jskit-ai/*` packages at exact versions, aligns JSKIT references in npm workspaces, refreshes npm resolution, synchronizes migrations, and regenerates CI.
 
-- find the installed package in `.jskit/lock.json`
-- reuse the saved lock options unless you override them inline
-- run the normal package-application flow again with forced reapply
-
-So `update` is for reapplying package-owned managed changes, not for generic dependency upgrades.
-
-The best guide example is the tenancy-mode recovery path from the multi-homing chapter. If you installed `workspaces-core` or `workspaces-web` while the app was still on `tenancyMode = "none"`, then later changed the app to `personal`, the missing gated scaffold does not backfill automatically. The recovery path is:
+Preview registry changes with:
 
 ```bash
-npx jskit update package users-core
-npx jskit update package workspaces-core
-npx jskit update package workspaces-web
+npx jskit app update-packages --dry-run
 ```
 
-That works because `update` reuses the saved install record and re-applies the package after the surrounding app state has changed.
-
-This is the main kind of problem `update` solves:
-
-- a package was installed correctly for the app state at the time
-- the app state changed later
-- the package's managed mutations need to be applied again
-
-### `position` re-applies only the placement/positioning layer
+Package updates do not regenerate application source. Review upstream release notes and make application changes explicitly.
 
-The positioning command is:
+## Remove a package
 
 ```bash
-npx jskit position element workspaces-web
+npx jskit remove package @jskit-ai/example-core
 ```
 
-This is the focused version of reapply.
+The command removes the application's direct npm dependency, runs npm install, and regenerates CI. App source and database migration history are retained. Delete application-owned source only when you have reviewed its remaining consumers.
 
-It reads the installed package from the lock file and reapplies only positioning mutations. That makes it especially useful for placement-heavy packages such as `shell-web` or `workspaces-web`, where a package contributes:
+An npm-transitive package cannot be removed directly. Remove or replace the direct package that depends on it.
 
-- shell placements
-- menu entries
-- outlet-targeted UI elements
-- ordering-sensitive positioned elements
+## Inspect and validate
 
-Use `position` when:
-
-- the package itself is still installed
-- you only need the placement layer refreshed
-- you do **not** want a full package reapply
-
-A realistic example is a workspace-heavy shell where the placement registry or surrounding shell files were edited, merged, or recovered and you want JSKIT to re-apply the `workspaces-web` positioned contributions without rerunning the whole install flow:
+Useful read-only commands:
 
 ```bash
-npx jskit position element workspaces-web
-```
-
-That is why the target word is `element` rather than `package`. This command is about positioned UI contributions, not general package installation.
-
-It also does **not** run npm install. This is a focused managed-file repair command, not a dependency-install step.
-
-### `remove` removes managed state for one installed package
-
-The removal form is:
-
-```bash
-npx jskit remove package workspaces-web
+npx jskit list packages
+npx jskit list generators
+npx jskit show package shell-web
+npx jskit list-placements
+npx jskit list-component-tokens
 ```
 
-This is the inverse side of the lifecycle.
-
-`remove` uses the lock record to tear out the managed state that package owns. In practice, that means it:
-
-- removes the package's lock entry
-- restores or removes the `package.json` fields JSKIT originally managed
-- removes managed files only when they still match the version JSKIT owns
-
-That last part is important. JSKIT is trying to remove package-owned managed state without blindly deleting user-owned edits.
-
-Two practical things to remember:
-
-- `remove` can refuse to run if other installed packages depend on the target package
-- it does **not** automatically delete app-owned local package directories such as `packages/contacts/`
-
-So if you created a local package yourself, `remove` cleans up the JSKIT-managed install state, but it does not assume it should delete the directory you own.
-
-### The practical rule of thumb
-
-If a package is already installed and you are deciding which command to use, think like this:
-
-- use `update` when the package's full managed install state needs to be applied again
-- use `position` when only its placement/positioning contributions need to be refreshed
-- use `remove` when you want JSKIT to cleanly remove the managed package state from the app
-
-All three commands make more sense once you see them as one lifecycle around `.jskit/lock.json`, not as isolated CLI tricks.
-
-### `doctor` checks managed-state health
-
-The health check is:
+Validate package metadata:
 
 ```bash
-npx jskit doctor
-```
-
-This is JSKIT's normal app-health check for JSKIT-managed state.
-
-It is not a linter, and it is not a test runner. It validates the things that only JSKIT itself can really verify.
-
-In the current CLI, that includes checks such as:
-
-- installed package entries in `.jskit/lock.json`
-- whether managed files recorded in the lock still exist
-- whether installed packages are still visible in the package registry
-- whether package CI contributions compose without conflicts and match the managed workflow service, environment, preparation steps, and ordering
-- explicit `transport` passed to high-level CRUD hooks such as `useCrudList()`, `useCrudView()`, and `useCrudAddEdit()`, where the shared CRUD resource should derive the JSON:API transport automatically
-- certain JSKIT-specific app checks, such as invalid raw `mdi-*` icon literals in Vue templates when the app uses Vuetify's `mdi-svg` iconset
-- UI verification receipts for current dirty UI files in git, via `.jskit/verification/ui.json`
-
-That last check is narrower than it sounds. `doctor` is looking for the broken case in direct Vue templates, such as:
-
-```vue
-<v-icon icon="mdi-paw" />
+npx jskit lint-packages
 ```
 
-It does not flag `src/placement.js` menu metadata because shell menu links normalize a small core icon map and also accept imported `@mdi/js` path constants. For app-specific icons, prefer a local import:
-
-```js
-import { mdiPaw } from "@mdi/js";
-
-icon: mdiPaw
-```
-
-So if you see a `doctor` icon warning, the fix is usually "switch this Vue component to `@mdi/js`", not "centralize every icon in the app."
-
-In other words, `doctor` helps catch drift between:
-
-- what JSKIT thinks it owns
-- what is actually present on disk
-
-That is a different job from:
-
-- `npm run lint`, which checks source style and static code rules
-- `npm run test`, which checks behavior
-- `npm run build`, which checks whether the app can compile successfully
-
-Those commands can all pass while JSKIT-managed state is still inconsistent. `doctor` is the command that checks that JSKIT's own view of the app still makes sense.
-
-That is exactly why the starter scaffold routes `npm run verify` through `jskit app verify`. CI structure is checked before lint, test, client-test, and build scripts, so a stale database service or missing migration step fails directly instead of surfacing later as an opaque provider boot failure.
-
-It belongs there because JSKIT apps are not only source trees. They also have:
-
-- descriptor-driven runtime installs
-- lock-file state under `.jskit/lock.json`
-- JSKIT-managed files and mutations written into the app
-
-`doctor` is the quick confirmation that those pieces still line up after all the normal quality checks pass.
-
-This command belongs in your normal quality gate, not only in emergency debugging.
-
-### When to run it manually
-
-The most common manual use is simply:
+Validate an application:
 
 ```bash
 npx jskit doctor
 ```
 
-after you have done something that changes JSKIT-managed state.
-
-Good times to run it manually include:
-
-- after `jskit add`, `update`, `remove`, `create package`, or generator commands
-- after rebasing or resolving conflicts that touched `.jskit/lock.json`, `package.json`, or app-owned managed files
-- after deleting, moving, or renaming files that may have been created by JSKIT
-- when a package appears installed in the lock but starts behaving as if it is missing
-- when you want a fast JSKIT-specific health check without waiting for a full test suite
-
-One important nuance: `doctor` is checking for broken JSKIT ownership and visibility, not trying to stop you from editing app-owned files. For example, a managed file that still exists but whose contents changed is normally fine. An app-owned file explicitly installed by a package can also live under `packages/main/src/server/` without being mistaken for undeclared domain logic. The file remains part of managed state, so deleting it is still an error. Unrelated server files under `packages/main` continue to receive the normal feature-lane warning.
-
-There is one intentional exception for user-facing UI work.
-
-If the current git working tree has changed UI files under the app's normal UI paths, `doctor` expects a matching `.jskit/verification/ui.json` receipt. The intended way to create that receipt is:
-
-```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
-```
-
-That command does two things:
-
-- runs the targeted Playwright command you give it
-- writes a receipt describing the verified feature, auth mode, and current dirty UI file set
-
-The auth mode is receipt metadata, not an authentication implementation. `jskit app verify-ui` does not log a user in, inject a secret, or rewrite the Playwright context. A direct local run uses `loginAsExistingUser()` from `@jskit-ai/auth-web/test/playwright`; Vibe64 supplies authenticated state through `VIBE64_PLAYWRIGHT_STORAGE_STATE`. The generated `playwright.config.mjs` consumes that state and honors `PLAYWRIGHT_BASE_URL` without starting a second server.
-
-`doctor` then compares the current changed UI files to that receipt. If you edit the UI again afterwards, the receipt is stale and `doctor` tells you to rerun `jskit app verify-ui`.
-
-For local pre-merge review, use `--against <base-ref>` so JSKIT compares against the branch delta instead of only the current dirty worktree. The common shape is:
-
-```bash
-npx jskit doctor --against origin/main
-```
-
-If the UI changed, the normal local sequence is:
-
-1. run the targeted Playwright flow locally
-2. record it with `jskit app verify-ui ...`
-3. run `jskit doctor --against <base-ref>`
-
-Advanced CI pipelines can also use `--against <base-ref>`, but that is intentionally app-specific. JSKIT does not scaffold hosted browser/auth/database verification by default, because many real apps need secrets, seeded databases, local auth bypass, or environment-specific bootstrap paths that do not belong in a one-size-fits-all template.
-
-### Why `--json` exists
-
-If you want machine-readable output, use:
-
-```bash
-npx jskit doctor --json
-```
-
-That prints a payload with:
-
-- `appRoot`
-- `lockVersion`
-- `installedPackages`
-- `issues`
-
-This is useful in CI, editor tooling, or custom scripts where you want to parse the result instead of reading plain text. The exit code still does the simple job, but `--json` gives you the exact issue list in a form that other tools can consume.
-
-## Migrations: writing files is not the same as running the database
-
-This distinction is one of the most important things to understand in JSKIT.
-
-The explicit migration-materialization command is:
-
-```bash
-npx jskit migrations changed
-```
-
-This command does **not** run Knex against the database.
-
-What it does is:
-
-- look at installed packages in `.jskit/lock.json`
-- decide which installed packages have managed migrations that need to be materialized
-- write those migration files into your app
-
-So this command is about **managed migration files on disk**.
-
-In many normal `jskit add` flows, those migration files are already written as part of package application. `jskit migrations changed` is the explicit re-sync command when you want JSKIT to materialize the migration files again based on the current installed package state.
-
-The database execution step is still:
-
-```bash
-npm run db:migrate
-```
-
-That step is about **running** the migration files that already exist.
-
-The clean mental model is:
-
-1. JSKIT materializes managed migration files
-2. Knex executes them against the database
-
-If you remember only one thing from this section, make it this:
-
-- `jskit migrations ...` writes or refreshes managed migration files
-- `npm run db:migrate` actually applies migrations to the database
-
-Do not confuse those two steps.
-
-Here is the practical version:
-
-```bash
-# Common install flow for a schema-bearing package
-npx jskit add package users-web
-npm install
-npm run db:migrate
-
-# Refresh flow when JSKIT needs to re-materialize managed migration files
-npx jskit migrations changed
-npm run db:migrate
-```
-
-In the first flow, package installation usually already wrote the managed migration files. In the second flow, you are explicitly asking JSKIT to write or refresh them again before Knex applies them.
-
-## Creating your own local package
-
-JSKIT can also scaffold a brand-new app-local runtime package:
-
-```bash
-npx jskit create package contacts
-```
-
-If your app is named `exampleapp`, that command creates a package id like:
-
-```text
-@exampleapp/contacts
-```
-
-and scaffolds a real local package under:
-
-```text
-packages/contacts/
-```
-
-This is the direct CLI path for creating your own runtime package inside the app.
-
-It is for the cases where you are authoring the package yourself:
-
-- you want a new package boundary under `packages/`
-- you want to define your own descriptor, providers, routes, or capabilities
-- you are building app-specific runtime code, not installing something prebuilt from the catalog
-
-That makes it different from both `add` and `generate`.
-
-- `jskit add package ...` installs an existing runtime package from the catalog or from `node_modules`
-- `jskit generate ...` runs a generator that writes app-owned scaffold files for a specific job such as CRUD
-- `jskit create package ...` gives you a blank but valid app-local runtime package to grow yourself
-
-### What the command creates
-
-The new package is intentionally small. For `contacts`, the scaffold looks like this:
-
-```text
-packages/contacts/
-  README.md
-  package.json
-  package.descriptor.mjs
-  src/index.js
-  src/client/index.js
-  src/server/index.js
-  src/shared/index.js
-```
-
-The command also updates two app-level files:
-
-- `package.json`
-- `.jskit/lock.json`
-
-That means `create package` is not just "make a folder". It creates a real local JSKIT package and registers it with the app.
-
-The important pieces are:
-
-- `package.json`
-  defines a private local package with exports for `.`, `./client`, `./server`, and `./shared`
-- `package.descriptor.mjs`
-  starts as a runtime descriptor with empty `dependsOn`, `capabilities`, `runtime`, `metadata`, and `mutations` sections ready for you to fill in
-- `src/index.js`
-  gives the package a top-level module entrypoint, even before you decide what should be exported from it
-- `src/client/index.js`
-  exports an empty `routeComponents` map and a no-op `bootClient()` so the package already has a valid client entrypoint
-- `src/server/index.js` and `src/shared/index.js`
-  give you the server and shared entrypoints without assuming any implementation yet
-- `README.md`
-  reminds you that the next step is to define runtime providers and real exports
-
-This is a deliberate contrast with generated CRUD packages. A CRUD generator writes a much more opinionated scaffold: repository code, routes, actions, migrations, and resource definitions. `create package` does not guess any of that. It gives you the smallest valid runtime package boundary.
-
-### How the new package fits into the app
-
-When you create `contacts`, JSKIT also adds a file dependency to the app root `package.json`:
-
-```json
-"@exampleapp/contacts": "file:packages/contacts"
-```
-
-and records the package in `.jskit/lock.json` as a `local-package`.
-
-That has a few consequences:
-
-- the package becomes part of the app's managed JSKIT state
-- `jskit list packages` can see it alongside catalog packages
-- later `update`, `remove`, and related lifecycle commands know this package exists
-- the package is still app-owned, so JSKIT does not assume it can delete your directory just because managed state changes
-
-This is the same idea you already saw in the starter app's `packages/main/` package. `create package` is how you make another package like that on purpose, instead of waiting for a generator to create one indirectly.
+`doctor` checks the installed package graph, capability closure, provider declarations, migrations, generated CI, surfaces, placements, CRUD ownership, and other architecture contracts.
 
-One practical point is easy to miss: the package exists immediately, but it does not do anything interesting until you give the descriptor real runtime hooks. In other words, after `create package`, you still need to add things such as:
-
-- client providers
-- server providers
-- routes or UI metadata
-- capabilities or dependency declarations
-
-So think of `create package` as "establish the package boundary first, then implement the runtime behavior."
-
-Because the command adds a file dependency, the normal follow-up is still:
-
-```bash
-npm install
-```
-
-or:
+The normal CI sequence is:
 
 ```bash
-npx jskit create package contacts --run-npm-install
-```
-
-JSKIT updates the app files. npm refreshes dependency installation.
-
-### When to use it instead of a generator
-
-Use `create package` when you are designing the package structure yourself.
-
-Good fits include:
-
-- a custom integration package that talks to one external API
-- app-specific auth or policy behavior
-- a local runtime package that owns both client and server behavior for one feature area
-- a package that starts small but may later grow providers, shared helpers, and routes
-
-Use a generator when the problem is already understood well enough that JSKIT can scaffold the feature shape for you.
-
-For example:
-
-- `npx jskit create package contacts`
-  gives you an empty-but-valid `packages/contacts/` package boundary
-- `npx jskit generate crud-server-generator scaffold contacts ...`
-  creates a CRUD-shaped package with repository, service, route, action, and migration files
-
-Those commands can both result in a package under `packages/contacts/`, but they start from very different assumptions.
-
-The other contrast is with catalog installs:
-
-- `npx jskit add package workspaces-web`
-  installs a package someone else already authored
-- `npx jskit create package contacts`
-  creates a package that your app will author and own
-
-### `--scope`, `--package-id`, and `--description` in practice
-
-The three most important inline options are about naming and identity.
-
-#### `--scope`
-
-By default, JSKIT derives the scope from the app package name.
-
-So if your app is `exampleapp`, this:
-
-```bash
-npx jskit create package contacts
-```
-
-produces:
-
-```text
-package id: @exampleapp/contacts
-directory:  packages/contacts
-```
-
-If you want a different scope, use `--scope`:
-
-```bash
-npx jskit create package contacts --scope local
+npm ci
+npx jskit migrations sync --check
+npx jskit ci generate --check
+npm run verify
 ```
 
-which produces:
+## Command summary
 
 ```text
-package id: @local/contacts
-directory:  packages/contacts
+jskit add package <id>
+jskit add bundle <id>
+jskit generate <generator-id> [subcommand]
+jskit create package <name>
+jskit create migration --package <id> --id <migration-id>
+jskit migrations sync [--check]
+jskit ci generate [--check]
+jskit remove package <id>
+jskit app update-packages [--dry-run]
+jskit doctor
+jskit lint-packages
+jskit list <packages|generators|bundles>
+jskit show <package|bundle> <id>
 ```
-
-Use this when you want the package id to follow a deliberate local naming convention instead of the app name.
-
-#### `--package-id`
-
-`--package-id` overrides the full package id directly:
-
-```bash
-npx jskit create package contacts --package-id @acme/contacts
-```
-
-This is the strongest naming override. Use it when you already know the exact package id you want.
-
-In practice, this matters when:
-
-- you want the package id to stay stable even if the app name changes
-- you want a different scope than the default inference
-- you are standardizing naming across several related local packages
-
-The package directory is derived from the package name part of the package id, so `@acme/contacts` still creates `packages/contacts/`.
-
-#### `--description`
-
-`--description` fills the generated descriptor description:
-
-```bash
-npx jskit create package contacts \
-  --description "App-local contact management runtime package."
-```
-
-That is useful because the description is part of the package metadata JSKIT can show later when you inspect local packages. It is a small option, but it makes local packages easier to identify once an app has several of them.
-
-So a practical mental model is:
-
-- `--scope` chooses the default namespace for the generated package id
-- `--package-id` sets the exact package id directly
-- `--description` makes the generated descriptor self-describing
-
-## Summary
-
-The JSKIT CLI is easiest to understand if you separate four jobs:
-
-- `list`, `show`, and `help` are for discovery and inspection
-- `add`, `update`, and `remove` manage installed JSKIT runtime packages
-- `position`, `doctor`, and `migrations` maintain or repair JSKIT-managed state
-- `create package` scaffolds a new app-local runtime package
-
-And then keep one more distinction in your head:
-
-- JSKIT manages app-owned package mutations and managed files
-- npm installs dependencies
-- Knex runs database migrations
-
-That is the mental model the rest of the guide assumes.
-
-The next chapter goes back to the normal hands-on flow and uses that model while inspecting the shell that default apps already include.