@jskit-ai/agent-docs 0.1.118 → 0.1.120

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

@@ -0,0 +1,134 @@
+<!-- Generated by `npm run agent-docs:build` from `packages/agent-docs/site/guide/app-setup/upgrade-beta-1-to-final.md`. Do not edit manually. -->
+
+# Upgrade guide from Beta 1 to Final Release
+
+> Temporary migration guide. Delete this page after every maintained application has upgraded to the Final Release package model.
+
+This is a one-way upgrade. Final Release does not read, translate, or preserve Beta 1 JSKIT state.
+
+## 1. Start from a clean commit
+
+Commit or stash application work. Record the current database migration status and make a normal database backup before changing packages.
+
+Do not run a Final Release JSKIT command until the package manifests have been converted.
+
+## 2. Move package metadata into package.json
+
+For every JSKIT package, move the exported metadata from `package.descriptor.mjs` into the package's top-level `jskit` object.
+
+Keep identity in standard npm fields:
+
+```json
+{
+  "name": "@acme/example-core",
+  "version": "1.2.3",
+  "description": "Example runtime package.",
+  "jskit": {
+    "kind": "runtime",
+    "capabilities": {
+      "provides": [],
+      "requires": []
+    },
+    "runtime": {
+      "server": { "providers": [] },
+      "client": { "providers": [] }
+    },
+    "mutations": {
+      "dependencies": { "runtime": {}, "dev": {} },
+      "files": []
+    }
+  }
+}
+```
+
+Remove `packageId`, `version`, and `description` from the moved object. Delete every `package.descriptor.mjs` after its data is represented in `package.json`.
+
+## 3. Use npm dependencies for package relationships
+
+Move every package relationship from `jskit.dependsOn` to the appropriate standard npm field:
+
+- `dependencies` for required runtime packages;
+- `optionalDependencies` for optional runtime integrations;
+- `peerDependencies` for host-provided libraries;
+- `devDependencies` for build and generator tooling.
+
+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.
+
+## 4. Remove Beta 1 project state
+
+Delete these paths from the application:
+
+```text
+.jskit/lock.json
+.jskit/verification/
+```
+
+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.
+
+## 5. Replace command usage
+
+Update scripts, workflow files, runbooks, and automation:
+
+| Beta 1 | Final Release |
+| --- | --- |
+| `jskit package migrations ...` | `jskit migrations sync` |
+| `jskit app sync-ci` | `jskit ci generate` |
+| CI drift validation through `doctor` alone | `jskit migrations sync --check` and `jskit ci generate --check` |
+| `jskit update package ...` | update npm versions explicitly or run `jskit app update-packages` |
+| `jskit position element ...` | edit application-owned placements directly |
+| `jskit app verify-ui ...` | run the application's Playwright command directly |
+
+Delete automation for package adoption, source-mutation migration, managed-script adoption, UI receipts, or package replay. Final Release has no corresponding commands.
+
+## 6. Install the coordinated Final Release
+
+Update every direct `@jskit-ai/*` dependency in the root application and npm workspaces to the coordinated Final Release versions, then install from scratch with the application's normal npm workflow:
+
+```bash
+npm install
+npm ls
+```
+
+Resolve npm peer or capability errors as package-graph errors. Do not add overrides that mix Beta 1 and Final Release packages.
+
+## 7. Generate deterministic projections
+
+Synchronize package migration files without applying them:
+
+```bash
+npx jskit migrations sync
+```
+
+Review the migration diff. Existing Knex migration files and migration-table history remain intact.
+
+Generate the JSKIT CI workflow:
+
+```bash
+npx jskit ci generate
+```
+
+Move application-specific CI into separate workflow files. The generated JSKIT workflow is replaced in full whenever this command runs.
+
+## 8. Verify the application
+
+```bash
+npx jskit lint-packages
+npx jskit doctor
+npx jskit migrations sync --check
+npx jskit ci generate --check
+npm run verify
+```
+
+Run the application's Playwright suite directly for UI changes.
+
+Apply database migrations only after reviewing the synchronized files:
+
+```bash
+npm run db:migrate
+```
+
+Commit package manifests, `package-lock.json`, synchronized migrations, generated CI, and required application changes together.

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

@@ -20,7 +20,6 @@ From inside `exampleapp`, run:
 
 ```bash
 npx jskit add package users-web
-npm install
 npm run db:migrate
 ```
 
@@ -29,7 +28,7 @@ The first command adds `users-web`, but the important part is what arrives with
 - `users-web` adds the account-facing UI and client runtime pieces
 - `users-core` arrives as a dependency and adds the persistent users/account server layer and schema migrations
 
-`npm install` downloads those new runtime packages and their dependencies. `npm run db:migrate` is the crucial step that makes the new tables real in MySQL.
+`jskit add` installs those runtime packages and their dependencies. `npm run db:migrate` is the separate step that makes the new tables real in MySQL.
 
 In the normal install flow, JSKIT materializes the managed `users-core` migration files while the package install is being applied. Then `npm run db:migrate` is what actually runs those files against MySQL.
 
@@ -48,14 +47,13 @@ That means the app is expected to project authenticated identities into the pers
 So the correct flow is:
 
 1. add `users-web`
-2. run `npm install`
-3. if you need JSKIT to refresh the managed migration files, run `npx jskit migrations changed`
-4. run `npm run db:migrate`
-5. only then start the app and sign in
+2. run `npx jskit migrations sync --check`
+3. run `npm run db:migrate`
+4. only then start the app and sign in
 
-Most of the time, step 3 is not needed because `jskit add package users-web` already wrote the managed migration files. But the distinction still matters:
+`jskit add package users-web` already synchronizes package migration files. The distinction still matters:
 
-- `jskit migrations changed` writes or refreshes JSKIT-managed migration files in `migrations/`
+- `jskit migrations sync` writes missing immutable package migration files in `migrations/`
 - `npm run db:migrate` actually applies pending migrations to MySQL
 
 ## What `users-web` adds
@@ -353,13 +351,8 @@ Under the hood, `users-core` wires those contributors into the users-backed prof
 
 The next chapter uses exactly that pattern. `workspaces-core` registers a contributor so the workspace layer can react when a new user enters the system.
 
-One forward-looking warning matters here. If this app later changes from `tenancyMode = "none"` to `personal` or `workspaces`, the app-local users scaffold written by `users-core` also needs to be refreshed. The multi-homing chapter calls out that recovery step explicitly with:
-
-```bash
-npx jskit update package users-core
-```
-
-That is not only a workspace-package concern. The generated `packages/users/...` scaffold itself changes shape when tenancy becomes workspace-aware.
+Choose `config.tenancyMode` before adding `users-core`. The generator uses that
+application decision to create the correct app-owned users package shape.
 
 ## Summary