@jskit-ai/agent-docs 0.1.85 → 0.1.87

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

@@ -162,7 +162,6 @@ The most important parts look like this:
     "server": "node ./bin/server.js",
     "server:all": "node ./bin/server.js",
     "server:home": "SERVER_SURFACE=home node ./bin/server.js",
-    "devlinks": "jskit app link-local-packages",
     "dev": "vite",
     "dev:all": "vite",
     "dev:home": "VITE_SURFACE=home vite",
@@ -206,9 +205,9 @@ The most important parts look like this:
 
 Published JSKIT libraries and tooling support Node.js 22 from 22.12.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.
 
-`verify`, `jskit:update`, `devlinks`, 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.
+`verify`, `jskit:update`, and `release` are intentionally thin wrappers. They stay in `package.json` because they are convenient app-local shortcuts, but the real implementation lives in `jskit app ...`, not in copied scaffold scripts.
 
-That matters because JSKIT maintenance policy changes over time. If the scaffold copied a large shell script into every app, existing apps would freeze the old behavior forever. By delegating to `jskit app verify`, `jskit app update-packages`, `jskit app link-local-packages`, and `jskit app release`, the app keeps the nice `npm run` shortcuts while the maintained behavior stays in the installed CLI package.
+That matters because JSKIT maintenance policy changes over time. If the scaffold copied a large shell script into every app, existing apps would freeze the old behavior forever. By delegating to `jskit app verify`, `jskit app update-packages`, and `jskit app release`, the app keeps the nice `npm run` shortcuts while the maintained behavior stays in the installed CLI package.
 
 The Playwright scaffold follows the same rule. `playwright.config.mjs` delegates to `@jskit-ai/jskit-cli/test/playwright`, and the starter browser specs delegate their shared responsive checks to published JSKIT helpers. The generated files stay small while later JSKIT package updates can change local server startup, managed `PLAYWRIGHT_BASE_URL` handling, and `JSKIT_PLAYWRIGHT_STORAGE_STATE` support without copying that logic into each new app.
 
@@ -819,7 +818,7 @@ That is why you saw `@jskit-ai/kernel` and `@jskit-ai/http-runtime` earlier in `
 
 ### Other files and options
 
-The remaining files are easier to understand once you know the core pieces above. `vite.config.mjs` configures the frontend build and the `/api` proxy used during development. `index.html` is the HTML shell Vite uses to mount Vue. `tests/` contains basic smoke tests so the app has a verification path from day one. The `scripts/` directory is intentionally small because JSKIT maintenance helpers such as `verify`, `jskit:update`, `devlinks`, and `release` are package-owned CLI commands rather than copied app scripts.
+The remaining files are easier to understand once you know the core pieces above. `vite.config.mjs` configures the frontend build and the `/api` proxy used during development. `index.html` is the HTML shell Vite uses to mount Vue. `tests/` contains basic smoke tests so the app has a verification path from day one. The `scripts/` directory is intentionally small because JSKIT maintenance helpers such as `verify`, `jskit:update`, and `release` are package-owned CLI commands rather than copied app scripts.
 
 The `create-app` command also accepts a few other flags that are useful without changing the basic meaning of this chapter's setup. `--title <text>` lets you replace the browser title and other template text with a friendlier app name. `--target <path>` lets you choose a different output directory instead of the default `./exampleapp`. `--tenancy-mode <mode>` can seed `none`, `personal`, or `workspaces`; for this chapter we intentionally use `none` so the first scaffold stays small and non-workspace. `--minimal` selects the bare `minimal-shell` template instead of the default shell-web app template. `--force` allows writing into a non-empty target directory when you know that is what you want. `--dry-run` prints the planned file writes without touching the filesystem, which is useful when you want to inspect what the generator would do. `-h` or `--help` prints the command help.
 

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

@@ -53,7 +53,6 @@ The important examples are:
 
 - `npm run verify`
 - `npm run jskit:update`
-- `npm run devlinks`
 - `npm run release`
 
 In the current scaffold, those scripts are intentionally thin:
@@ -63,7 +62,6 @@ In the current scaffold, those scripts are intentionally thin:
   "scripts": {
     "verify": "jskit app verify && npm run --if-present verify:app",
     "jskit:update": "jskit app update-packages",
-    "devlinks": "jskit app link-local-packages",
     "release": "jskit app release"
   }
 }
@@ -71,12 +69,11 @@ In the current scaffold, those scripts are intentionally thin:
 
 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, local linking, 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.
+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
-- `npm run devlinks` re-applies local checkout links after `npm install` when you are testing an app against this monorepo
 - 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".
@@ -116,14 +113,9 @@ npm run jskit:update
 
 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.
 
-There is one unavoidable bootstrap detail for apps whose installed CLI predates managed package reapplication: a CLI process that is already running cannot adopt code npm installs underneath it. Upgrade the CLI once, then run the app-wide update with the new process:
+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.
 
-```bash
-npm install --save-dev --save-exact @jskit-ai/jskit-cli@latest
-npm run jskit:update
-```
-
-After that bootstrap, normal future upgrades use only `npm run jskit:update`. Do not work around the first upgrade by editing `.jskit/lock.json`; the new updater must reapply the descriptor contract and write managed state itself.
+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:
 
@@ -571,12 +563,6 @@ npm install
 
 `jskit add` changes the app. `npm install` downloads the dependencies that the changed app requires.
 
-If the app is being tested against a local JSKIT checkout with linked packages, run the local-link wrapper again after every `npm install`:
-
-```bash
-npm run devlinks
-```
-
 ### `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.

package/guide/agent/generators/crud-generators.md

@@ -314,12 +314,6 @@ So before you build or run the app again, install that new local package:
 npm install
 ```
 
-If you are verifying the guide against a local JSKIT checkout and have already been using local package links, rerun:
-
-```bash
-npm run devlinks
-```
-
 The same rule applies after later server scaffolds such as `addresses` and `comments`. The UI generator can still read the generated resource file directly, but the app runtime needs the local package install boundary to be completed before the CRUD can boot normally.
 
 For standard CRUDs, that file is intentionally compact. It uses `defineCrudResource(...)` from `@jskit-ai/resource-crud-core`, authors the canonical `schema` / `searchSchema` / `defaultSort` / `autofilter` shape once, and lets JSKIT derive the standard CRUD operation contracts from it.
@@ -435,12 +429,6 @@ Then install the generated local package:
 npm install
 ```
 
-If you are developing against a local JSKIT checkout, relink your app to the local packages before you run the UI:
-
-```bash
-npm run devlinks
-```
-
 ### Step 3: refine the generated lookup metadata by hand
 
 Open `packages/addresses/src/shared/addressResource.js` and add `labelKey: "fullName"` to the generated `contactId` relation:
@@ -617,12 +605,6 @@ Then install the generated local package:
 npm install
 ```
 
-If you are developing against a local JSKIT checkout, relink the app before you run the UI:
-
-```bash
-npm run devlinks
-```
-
 ### Step 3: refine the generated lookup metadata by hand
 
 Open `packages/comments/src/shared/commentResource.js` and add `labelKey: "fullName"` to the generated `contactId` relation:

package/package.json

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

package/reference/autogen/tooling/jskit-cli.md

@@ -512,15 +512,6 @@ Exports
 Local functions
 - `shouldRewriteScript(currentValue = "", scriptName = "", force = false)`
 
-### `src/server/commandHandlers/appCommands/linkLocalPackages.js`
-Exports
-- `runAppLinkLocalPackagesCommand(ctx = {}, { appRoot = "", options = {}, stdout })`
-Local functions
-- `collectDeclaredPackageNames(packageJson = {})`
-- `verifySymlinkTarget(targetPath = "", sourceDir = "", { packageName = "" } = {})`
-- `replaceWithSymlink(targetPath = "", sourceDir = "", { packageName = "" } = {})`
-- `maybeLinkCompanionPackages({ appRoot = "", repoRoot = "", stdout, createCliError })`
-
 ### `src/server/commandHandlers/appCommands/migrateSourceMutations.js`
 Exports
 - `buildCrudFormFieldPushMigration(sourceText = "")`
@@ -558,11 +549,7 @@ Exports
 - `formatUtcReleaseTimestamp(date = new Date())`
 - `resolveLocalJskitBin(appRoot = "")`
 - `runLocalJskit(appRoot, args = [], { stdout, stderr, createCliError, quiet = false } = {})`
-- `runLocalJskitAsync(appRoot, args = [], { stdout, stderr, createCliError, quiet = false } = {})`
-- `resolveLocalRepoRoot({ appRoot = "", explicitRepoRoot = "" } = {})`
-- `discoverLocalPackageMap(repoRoot = "")`
-- `linkPackageBinEntries({ appRoot, packageDirName, sourceDir, stdout } = {})`
-- `resolveSymlinkType()`
+- `runLocalJskitAsync(appRoot, args = [], { env = {}, stdout, stderr, createCliError, quiet = false } = {})`
 Local functions
 - `ensureCommandSucceeded(result, label, { createCliError, cwd = "", stdout, stderr, quiet = false } = {})`
 
@@ -752,11 +739,11 @@ Local functions
 - `collectPlacementComponentTokensFromManagedRecords(installedPackageRecords = [])`
 - `renderWrappedShellCommand(binaryName, args = [], { maxWidth = 100, continuationIndent = " " } = {})`
 - `runLocalProjectBinary(binaryName, args = [], { appRoot, io, pathModule = path, createCliError, explanation = "", dryRun = false } = {})`
-- `installAppDependenciesForHook({ appRoot, appPackageJson, io, pathModule = path, createCliError, dryRun = false, runDevlinks = false } = {})`
+- `installAppDependenciesForHook({ appRoot, io, pathModule = path, createCliError, dryRun = false } = {})`
 - `resolvePackageOptionInputForInstall({ packageEntry, existingInstall, packageInlineOptions, appRoot, readFileBufferIfExists })`
 - `validateHookResult(result = {}, { packageId = "", hookLabel = "" } = {})`
 - `loadInstallHook({ packageEntry, appRoot, hookSpec, hookLabel = "" } = {})`
-- `createInstallHookHelpers({ ctx, appRoot, io, appPackageJson, commandOptions = {} } = {})`
+- `createInstallHookHelpers({ ctx, appRoot, io, appPackageJson } = {})`
 - `invokeInstallHook({ packageEntry, appRoot, hookSpec, hookLabel, hookContext, createCliError } = {})`
 
 ### `src/server/commandHandlers/packageCommands/create.js`