@jskit-ai/agent-docs 0.1.127 → 0.1.129

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

@@ -47,7 +47,7 @@ So the first visible value of the package is not a whole new screen. It is a tin
 
 The app already had a browser dev server on `5173` and a backend runtime on `3000`.
 
-`realtime` extends that setup by writing a websocket proxy entry into `.jskit/vite.dev.proxy.json` for `/socket.io`. That matters because the browser should still talk to the frontend dev server on `5173`, while Vite quietly forwards websocket traffic to the backend runtime on `3000`.
+`realtime` declares a websocket proxy for `/socket.io` in its published `package.json.jskit` metadata. The JSKIT Vite plugin reads that declaration from the installed npm graph and forwards websocket traffic from the frontend dev server on `5173` to the backend runtime on `3000`.
 
 So one of the main values of this package is that you do **not** have to hand-edit Vite config just to make socket.io work in local development.
 
@@ -210,26 +210,26 @@ REALTIME_REDIS_URL=
 
 That empty value is deliberate. It means the app can start with the in-memory adapter locally, and you can fill in a real Redis URL later if you need cross-instance fan-out.
 
-### `.jskit/vite.dev.proxy.json` gains a websocket proxy entry
+### Package metadata declares the websocket proxy
 
-After the install, the app has:
+The installed `@jskit-ai/realtime` package declares:
 
 ```json
 {
-  "version": 1,
-  "entries": [
-    {
-      "packageId": "@jskit-ai/realtime",
-      "id": "realtime-socket-io",
-      "path": "/socket.io",
-      "changeOrigin": true,
-      "ws": true
+  "jskit": {
+    "vite": {
+      "proxy": {
+        "/socket.io": {
+          "changeOrigin": true,
+          "ws": true
+        }
+      }
     }
-  ]
+  }
 }
 ```
 
-That one entry is what lets the browser dev server proxy websocket traffic correctly during local development.
+`createJskitClientBootstrapPlugin({ proxyTarget })` reads that metadata directly. The application owns only its normal Vite config and proxy target; installing or removing the npm package changes the active proxy on the next Vite start without generated project state.
 
 ### `src/placement.js` includes the shell status placement
 

package/guide/agent/app-setup/upgrade-beta-1-to-final.md

@@ -54,7 +54,7 @@ Move every package relationship from `jskit.dependsOn` to the appropriate standa
 
 Pin `@jskit-ai/*` packages to exact versions. Remove `jskit.dependsOn` completely.
 
-Keep provider-class `static dependsOn` declarations. Those order providers inside the runtime container and are not npm package relationships.
+Rename provider-class `static dependsOn` to `static startsAfter`, then audit every entry. Keep only providers whose registration or boot must complete before the declaring provider reaches the same phase. JSKIT completes registration for the entire graph before beginning any boot method, so a lazily consumed service does not justify an ordering edge.
 
 ## 4. Remove Beta 1 project state
 
@@ -63,11 +63,22 @@ Delete these paths from the application:
 ```text
 .jskit/lock.json
 .jskit/verification/
+.jskit/vite.dev.proxy.json
 ```
 
 Remove ignore rules created solely for `.jskit/verification/`.
 
-Do not translate either file into a replacement. Final Release derives package state from `package.json`, `package-lock.json`, installed package manifests, application config, migration files, and generated CI.
+Do not translate these paths into replacements. Final Release derives package state from `package.json`, `package-lock.json`, installed package manifests, application config, migration files, and generated CI.
+
+Delete the app-local Vite proxy loader and any `vite.shared.mjs` file used only for that generated JSON. Pass the application's API target to the standard plugin instead:
+
+```js
+createJskitClientBootstrapPlugin({
+  proxyTarget: apiProxyTarget
+})
+```
+
+Installed packages now declare development proxies in `package.json.jskit.vite.proxy`, and the plugin derives the active proxy table directly whenever Vite starts.
 
 ## 5. Replace command usage
 

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

@@ -40,6 +40,9 @@ A JSKIT package is an ordinary npm package with a `jskit` object in `package.jso
         "providers": []
       }
     },
+    "vite": {
+      "proxy": {}
+    },
     "mutations": {
       "dependencies": {
         "runtime": {},
@@ -63,7 +66,9 @@ needed by generated application-owned source or application-level tooling. It
 does not declare relationships between JSKIT packages and does not affect
 package ordering.
 
-`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.
+`runtime.server.providers` and `runtime.client.providers` declare runtime entrypoints. A provider class may use `static startsAfter` when its own registration or boot genuinely requires another provider to have completed the same lifecycle phase first. JSKIT registers every provider before booting any provider, so later service consumption does not require an ordering declaration.
+
+`jskit.vite.proxy` declares development proxy requirements as path-keyed metadata. `createJskitClientBootstrapPlugin({ proxyTarget })` reads those declarations directly from the installed npm graph when Vite starts. Package installation does not generate an intermediate proxy file.
 
 Use exact versions for `@jskit-ai/*` dependencies. npm's `package-lock.json` remains the reproducible installation record.
 

package/guide/agent/generators/row-policies.md

@@ -251,13 +251,7 @@ The owning provider creates the visibility object during `register()` and consum
 class OrganisationUnitsProvider {
   static id = "crud.organisation_units";
 
-  static dependsOn = [
-    "runtime.actions",
-    "runtime.database",
-    "auth.policy.fastify",
-    "local.main",
-    "json-rest-api.core"
-  ];
+  static startsAfter = ["json-rest-api.core", "local.main", "runtime.actions"];
 
   register(app) {
     app.instance(
@@ -345,8 +339,6 @@ The safety package depends on organisation-units and registers its grant:
 class SafetyProvider {
   static id = "safety.core";
 
-  static dependsOn = ["crud.organisation_units"];
-
   register(app) {
     registerOrganisationUnitVisibility(app, {
       id: "safety-manager-descendants",
@@ -360,7 +352,7 @@ class SafetyProvider {
 
 The organisation-units package never imports safety. Installing safety adds the grant; omitting safety leaves that grant absent.
 
-The npm dependency must point in the same direction as the provider dependency: safety depends on organisation-units, and organisation-units does not depend on safety.
+No provider start-order declaration is needed here. JSKIT completes every provider's `register()` phase before any provider begins `boot()`, so safety's contribution is present before organisation-units seals the registry. The normal npm dependency points from safety to organisation-units because safety imports its registration API.
 
 ## Descendant visibility with a recursive CTE
 

package/package.json

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

package/reference/autogen/KERNEL_MAP.md

@@ -511,7 +511,7 @@ Exports
 Exports
 - `Application`
 - `createApplication(options = {})`
-- `createProviderClass({ id, dependsOn = [], register = null, boot = null, shutdown = null } = {})`
+- `createProviderClass({ id, startsAfter = [], register = null, boot = null, shutdown = null } = {})`
 Local functions
 - `normalizeStringArray(value)`
 - `nowMilliseconds()`
@@ -555,7 +555,7 @@ Exports
 - `KernelError`
 - `ProviderNormalizationError`
 - `DuplicateProviderError`
-- `ProviderDependencyError`
+- `ProviderStartOrderError`
 - `ProviderLifecycleError`
 
 ### `runtime/kernelErrors.js`
@@ -563,7 +563,7 @@ Exports
 - `KernelError`
 - `ProviderNormalizationError`
 - `DuplicateProviderError`
-- `ProviderDependencyError`
+- `ProviderStartOrderError`
 - `ProviderLifecycleError`
 
 ### `runtime/serviceProvider.js`

package/reference/autogen/packages/kernel.md

@@ -127,7 +127,7 @@ Exports
 Exports
 - `Application`
 - `createApplication(options = {})`
-- `createProviderClass({ id, dependsOn = [], register = null, boot = null, shutdown = null } = {})`
+- `createProviderClass({ id, startsAfter = [], register = null, boot = null, shutdown = null } = {})`
 Local functions
 - `normalizeStringArray(value)`
 - `nowMilliseconds()`
@@ -171,7 +171,7 @@ Exports
 - `KernelError`
 - `ProviderNormalizationError`
 - `DuplicateProviderError`
-- `ProviderDependencyError`
+- `ProviderStartOrderError`
 - `ProviderLifecycleError`
 
 ### `shared/runtime/kernelErrors.js`
@@ -179,7 +179,7 @@ Exports
 - `KernelError`
 - `ProviderNormalizationError`
 - `DuplicateProviderError`
-- `ProviderDependencyError`
+- `ProviderStartOrderError`
 - `ProviderLifecycleError`
 
 ### `shared/runtime/serviceProvider.js`
@@ -706,13 +706,15 @@ Exports
 - `resolveInstalledClientPackageIds(options)`
 - `resolveLocalScopePackageIds({ appRoot })`
 - `resolveInstalledClientModules({ appRoot })`
-- `createJskitClientBootstrapPlugin()`
+- `resolveInstalledViteProxyEntries(installedPackages = [], { proxyTarget = "" } = {})`
+- `createJskitClientBootstrapPlugin({ proxyTarget = "" } = {})`
 Local functions
 - `isLocalScopePackageId(value)`
 - `readJsonFile(filePath, fallback)`
 - `hasClientExport(packageJson)`
 - `isPathInsideRoot(rootPath, candidatePath)`
 - `splitSpecifierSuffix(source)`
+- `resolveClientModulesFromInstalledPackages(installedPackages = [])`
 - `normalizeClientModulePackageMetadataEntries(value)`
 - `resolveClientRuntimeDedupeSpecifiers(userResolveConfig = {})`
 
@@ -930,7 +932,7 @@ Exports
 - `KernelError`
 - `ProviderNormalizationError`
 - `DuplicateProviderError`
-- `ProviderDependencyError`
+- `ProviderStartOrderError`
 - `ProviderLifecycleError`
 - `KernelCoreServiceProvider`
 

package/reference/autogen/tooling/create-app.md

@@ -207,11 +207,6 @@ Exports
 Local functions
 - `clientEntry(()`
 
-### `templates/base-shell/vite.shared.mjs`
-Exports
-- `toPositiveInt(value, fallback)`
-- `loadViteDevProxyEntries({ appRootUrl = import.meta.url, fallbackTarget = "" } = {})`
-
 ### `templates/minimal-shell/bin/server.js`
 Exports
 - None
@@ -315,11 +310,6 @@ Exports
 Local functions
 - `clientEntry(()`
 
-### `templates/minimal-shell/vite.shared.mjs`
-Exports
-- `toPositiveInt(value, fallback)`
-- `loadViteDevProxyEntries({ appRootUrl = import.meta.url, fallbackTarget = "" } = {})`
-
 ### bin
 
 ### `bin/jskit-create-app.js`

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

@@ -435,18 +435,6 @@ Local functions
 - `isExactOptionReference(value = "", optionName = "")`
 - `readEnvValue(content = "", key = "")`
 
-### `src/server/cliRuntime/viteProxy.js`
-Exports
-- `createEmptyViteDevProxyConfig()`
-- `normalizeViteDevProxyPath(value = "", { context = "vite proxy entry" } = {})`
-- `normalizeViteDevProxyEntry(value = {}, { context = "vite proxy entry" } = {})`
-- `normalizeViteDevProxyConfig(value = {}, { context = "vite proxy config" } = {})`
-- `resolveViteDevProxyConfigAbsolutePath(appRoot)`
-- `loadViteDevProxyConfig(appRoot, { context = "vite proxy config" } = {})`
-- `writeViteDevProxyConfig(appRoot, config = {}, touchedFiles = null, { dryRun = false } = {})`
-- `normalizeViteProxyMutationRecord(value = {})`
-- `applyViteMutations(packageEntry, appRoot, viteMutations, options, managedVite, touchedFiles, { dryRun = false } = {})`
-
 ### `src/server/commandHandlers/app.js`
 Exports
 - `createAppCommands(ctx = {})`

package/reference/autogen/tooling/testUtils.md

@@ -22,6 +22,15 @@ Exports
 - `startViteFixture({ fixtureRoot, configFile = "vite.config.mjs", env = {} } = {})`
 - `stopProcess(runtime)`
 
+### `currentJskitWorkspaces.mjs`
+Exports
+- `CURRENT_JSKIT_WORKSPACE_NPM_ENV`
+- `restoreCurrentJskitDependencyVersions(appRoot, packages)`
+- `stageCurrentJskitWorkspaces(appRoot)`
+Local functions
+- `readJson(filePath)`
+- `collectCurrentJskitPackages()`
+
 ### `fakeFastify.mjs`
 Exports
 - `createFakeFastifyPolicyRuntime({ csrfHandler, autoRunPlugin = null } = {})`