@jskit-ai/agent-docs 0.1.132 → 0.1.133

package/guide/agent/app-setup/existing-application-migration.md

@@ -0,0 +1,273 @@
+<!-- Generated by `npm run agent-docs:build` from `packages/agent-docs/site/guide/app-setup/existing-application-migration.md`. Do not edit manually. -->
+
+---
+title: Migrate an existing application
+description: Port a working application to AI-first JSKIT without regenerating it or flattening its product behavior.
+---
+
+# Migrate an existing application
+
+An existing application is a product with history, not input to a scaffold.
+Port it by preserving observable behavior while replacing obsolete framework
+mechanics with current JSKIT packages, patterns, capabilities, and public APIs.
+The application remains usable throughout the migration, and its source,
+migrations, tests, and runtime behavior remain the evidence of completion.
+
+This procedure is guidance for a deliberate port. It does not create a
+migration command, workboard, machine receipt, generated ownership state, or
+second source of truth.
+
+## 1. Inventory behavior before changing structure
+
+Read the request, product documentation, nearest `AGENTS.md`, package manifests,
+lockfile, current source, current diff, migration ledger, and existing tests.
+Do not reset a dirty tree or assume an unfamiliar change is obsolete.
+
+Build a working inventory of:
+
+- user journeys, routes, screens, background work, integrations, and failure
+  behavior;
+- authentication, application-user, workspace-membership, authorization, and
+  preview identities;
+- packages, runtime providers, public capabilities, actions, events, and
+  long-lived processes;
+- resources, tables, foreign keys, migration filenames, seed behavior, and the
+  current database migration ledger;
+- client surfaces, placements, shared screen APIs, responsive behavior, warm
+  navigation state, and managed browser coverage;
+- domain services, custom repositories, transactional boundaries, outbox or
+  delivery behavior, and intentional compatibility boundaries.
+
+Run the smallest useful original tests and representative user journeys before
+the port. Add characterization tests only where a high-value behavior has no
+other executable description. Record uncertainty in the ordinary project
+documentation or test name; do not silently turn an implementation accident
+into a new product decision.
+
+Preserve real workflow domains. Scheduling, money, communications, safety,
+inventory, or other product-specific orchestration must not be flattened into
+generic CRUD merely to make the structure look uniform.
+
+## 2. Plan one coordinated dependency and capability graph
+
+Use the installed JSKIT pattern index and package metadata to select the
+smallest complete package set. Plan the top-level dependencies and their
+ordinary npm closure before changing the lockfile, then install that planned
+closure once. Review `package.json` and the lockfile as source changes. There
+is no framework synchronization step after npm installation.
+
+Model product domains through `defineFeature()` when they own a real capability
+or operation boundary. A Feature declares stable named `requires`, optional
+inputs, and `provides`; `setup()` receives those values directly and returns
+only the promised outputs. Named actions capture the exact feature APIs they
+need. Register structural catalogue entries during `setup()` and reserve
+`boot()` for long-lived work that starts after composition.
+
+Capability ids, action ids, routes, events, resources, and placements are
+stable identities. They are not permission to fetch arbitrary dependencies by
+string, symbol, class, token, `app.make()`, or another service-locator helper.
+Remove locator-based wiring once every consumer has an explicit capability.
+
+Move by coherent seams rather than leaving two framework paths active. The
+finished graph has no obsolete framework-authoring CLI calls or configuration,
+generator or synchronization scripts, generated-file markers, provenance
+comments, operation receipts, compatibility shims that only preserve a retired
+framework API, empty extension modules, or parallel dependency containers.
+Keep genuine protocol adapters and product compatibility behavior when they
+still have callers and tests.
+
+Audit application `AGENTS.md` files, ordinary documentation, npm scripts, CI,
+and package metadata as well as executable source. There is no supported
+`jskit doctor` command or general JSKIT authoring CLI. Replace stale
+instructions to run them with current-state checks owned by runtime startup,
+the client build, migration status and disposable rebuilds, the application's
+normal verification script, and Playwright.
+
+## 3. Choose the narrowest server seam that owns each behavior
+
+Conventional resources use `defineCrudResource()` and
+`defineCrudJsonApiFeature()` so JSKIT owns the repeated repository, service,
+permission, action, JSON API, and route mechanics. Extend that contract instead
+of copying it.
+
+| Product need | Normal owner |
+| --- | --- |
+| Behavior before, around, or after one standard CRUD operation | `operationLifecycle` |
+| A resource-specific domain method or override | `decorateService` |
+| A resource-specific query, lock, or persistence operation | `decorateRepository` |
+| A named non-CRUD command on the resource | a named CRUD `action` backed by the service |
+| A separate aggregate, workflow, or capability domain | `defineFeature()` with named actions |
+| Persistence that the high-level resource APIs cannot express | an explicit custom repository owned by that Feature |
+
+For mutations, lifecycle phases before commit share one repository
+transaction. An `execute` hook that only normalizes input calls
+`standard(nextInput)` rather than reimplementing the write. Repositories own
+database access; services and hooks orchestrate repositories. External work
+runs after commit, or a durable outbox record is written inside the transaction
+and delivered separately.
+
+Give commands product names such as `confirm`, `publish`, or `cancel`, with
+explicit input, permissions, routes where needed, audit behavior, events, and
+tests. Do not hide unrelated workflows behind a generic `execute(anything)`
+action, and do not create a custom repository merely because SQL is familiar.
+
+## 4. Adopt migrations without breaking either database history
+
+Every immutable migration belongs to the package that owns its tables. Declare
+the package directory in `package.json#jskit.migrations.directories`; do not
+copy it into a central projection. Preserve the basename of every applied
+historical migration when moving it so the existing Knex ledger continues to
+recognize it. Basenames must be unique across the effective graph.
+
+Keep cross-package foreign keys and other dependency-sensitive constraints in
+later application-owned migrations when package ordering requires it. Seeds
+are not migrations: run one explicit application-owned, idempotent seed after
+the complete graph has migrated.
+
+Prove both histories:
+
+1. Inspect an existing ledger without mutating valuable data. It must recognize
+   every moved historical basename and report only genuinely new work pending.
+2. Create a fresh disposable database and run the complete migration graph.
+   Compare its tables, keys, constraints, ownership rules, and invariant data
+   with the intended schema.
+3. Run the normal migrate-then-seed entry point twice. The second run must have
+   no pending migration and the seed must be safe and stable.
+
+A managed editor allocates one isolated mutable development database per
+session. It owns creation, credentials, lifetime, and environment injection;
+the session's setup, app server, preview, and interactive checks must agree on
+that identity. Disposable verification databases may be created and destroyed
+inside the session, but they are never shared between sessions. Imported and
+production databases remain read-only unless the user separately authorizes an
+upgrade.
+
+## 5. Keep filesystem and application identities distinct
+
+The host's managed-source permission contract is established when a workspace,
+directory, temporary file, or atomic replacement is created. The creating
+process must already have the correct user, shared group, inherited default
+ACL, and restrictive umask. Setup must fail if it cannot establish that
+contract. Do not make package installation, Git, agents, or preview startup run
+recursive ownership or mode repair afterward.
+
+For Vibe64-managed workspaces, the concrete contract is group `vibe64`,
+directory mode `2770`, access and inherited default group ACL `vibe64:rwx`, no
+access for other users, and process umask `0007`. The enabled human user and
+`v64d_<workspace>` identity both belong to the group. Other hosts may use
+different concrete identities, but they must provide the same creation-time
+guarantee.
+
+Do not conflate these identities:
+
+- The filesystem identity controls who may create and replace source files.
+- The auth provider identity verifies credentials and owns the session.
+- The application user/profile is an existing product record associated with
+  that auth identity.
+- A workspace identity is an existing membership and role that scopes routes,
+  permissions, queries, and writes.
+- A managed preview identity selects an existing auth-backend user whose
+  application profile and required workspace membership already exist. It does
+  not synthesize any of them as a side effect.
+
+For a Vibe64 preview, retain the app-owned `.vibe64/bin/preview-identity`
+executable and declare it in the managed Launch target. It calls the
+`@jskit-ai/auth-web` server-side managed-preview library; it does not need a
+framework CLI. Never expose the exchange secret in browser code, a URL, client
+environment, logs, or source.
+
+Managed Playwright uses the host-provided
+`VIBE64_PLAYWRIGHT_STORAGE_STATE`, relative URLs, and the existing managed
+server. Direct-local tests may instead use `loginAsExistingUser()` from
+`@jskit-ai/auth-web/test/playwright` with a server-only development secret.
+Do not mix those two authentication modes or start a duplicate server against
+the wrong session database.
+
+## 6. Treat client patterns as examples, not regeneration input
+
+Read a selected package's complete `PATTERN.md` and inspect its example. Copy
+only useful files or adapt the existing application through the same public
+APIs. Resolve every destination collision deliberately. Once copied, template
+source belongs to the application and may diverge with the product.
+
+Do not erase established screens and regenerate them from a schema. Do not
+sync template updates into application source or retain template hashes,
+generated-file headers, or ownership markers. Prefer current shared screens,
+placements, high-level composables, Vuetify components, and Material 3 states
+where they fit, while retaining application vocabulary, routes, workflows, and
+tests.
+
+Verify affected UI at compact, medium, and expanded widths. Preserve loading,
+empty, error, retry, permission, keyboard, focus, and warm-navigation behavior;
+do not accept a visually similar screen as behavioral equivalence.
+
+## 7. Reconcile, then Deslop as a distinct pass
+
+When the project uses Genesis, run an explicit reconciliation after the port is
+functionally green. Compare the implemented source with the current Blueprint,
+selected Stack, Program, resources, managed skills, and effective workspace and
+Launch recipes. Update stale citations and declarations to describe what now
+exists. Do not duplicate an inherited setup recipe merely to make the project
+look self-contained.
+
+After reconciliation, start a separate behavior-preserving Deslop pass using
+the selected JSKIT guidance and, for every affected Vue/Vuetify screen, the
+Material 3 audit. Remove dead adapters, obsolete names and selectors, duplicate
+request or state layers, empty extension files, retired framework shims,
+provenance residue, and accidental abstractions. Replace them at the narrowest
+established owner. Keep every intentional domain workflow and rerun focused
+tests after each meaningful cleanup.
+
+Reconciliation answers whether project intent and managed configuration match
+the implementation. Deslop answers whether the implementation is the cleanest
+behavior-preserving use of the selected stack. Combining them hides both kinds
+of mistake.
+
+## Five finish gates
+
+A migrated application is complete only when all five gates have current
+evidence in ordinary source, configuration, command output, and tests:
+
+1. **Behavior:** focused tests and the full managed browser suite are green
+   against an isolated disposable database. Use the managed host and server
+   when supplied.
+2. **Reconciliation:** a dedicated Genesis reconciliation confirms the
+   Blueprint, Stack, Program, resources, managed skills, and effective setup and
+   Launch recipes match the implementation. For a project without Genesis,
+   reconcile its equivalent authoritative product and host documentation.
+3. **Deslop:** a distinct JSKIT Deslop pass, including the selected Material 3
+   audit where UI is affected, removes obsolete framework residue without
+   changing legitimate behavior.
+4. **Broad verification:** after reconciliation and Deslop, rerun lint, server
+   tests, client tests, production build, existing-ledger status, fresh database
+   rebuild, idempotent seed proof, and representative managed Playwright.
+5. **Structure:** audit CRUD lifecycles, decorated services and repositories,
+   named Features and actions, capability edges, package-owned migrations, and
+   constraints-last ordering. Explain every custom seam in product language;
+   do not delete it merely to reduce the count.
+
+Do not satisfy a gate by adding a completion ledger or generated conformance
+state. If a command cannot run, report the missing evidence rather than marking
+the port complete.
+
+## Downstream proof: DogAndGroom
+
+DogAndGroom validated this procedure on a substantial existing product rather
+than a sample. The port redistributed 66 historical migrations among 43 owning
+packages while retaining globally unique basenames and putting cross-package
+constraints last. Its imported database ledger remained read-only and
+recognized every moved migration; a fresh disposable MariaDB reached the full
+117-migration schema and a second prepare-and-seed run was idempotent.
+
+The resulting server used 43 standard CRUD Features plus narrow lifecycle,
+service, repository, named-action, and domain-Feature extensions for grooming,
+daycare, booking, scheduling, communications, commerce, inventory, uploads,
+and safety behavior. Obsolete framework generators, provenance markers,
+service-location wiring, and empty extension modules were removed without
+flattening those workflows.
+
+After a separate Genesis reconciliation and JSKIT/Material Deslop, its focused
+checks, 339 server tests, client tests, production build, database proofs, and
+all 105 managed Playwright cases passed. These numbers are downstream evidence
+that the method scales; they are not template targets or state that another
+application should copy.

package/guide/agent/index.md

@@ -10,6 +10,7 @@ apply or adapt. It does not prescribe an agent host or project orchestrator.
 
 - [Quickstart](/guide/app-setup/quickstart)
 - [Application foundations](/guide/app-setup/initial-scaffolding)
+- [Migrate an existing application](/guide/app-setup/existing-application-migration)
 - [A more interesting shell](/guide/app-setup/a-more-interesting-shell)
 - [Authentication](/guide/app-setup/authentication)
 - [Database layer](/guide/app-setup/database-layer)

package/package.json

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

package/patterns/feature-package/example/booking-engine/package.json

@@ -5,7 +5,7 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@jskit-ai/kernel": "0.1.160",
+    "@jskit-ai/kernel": "0.1.161",
     "json-rest-schema": "^1.0.17"
   },
   "exports": {

package/patterns/minimal-foundation/example/package.json

@@ -29,7 +29,7 @@
   "dependencies": {
     "@local/main": "file:packages/main",
     "@fastify/static": "^10.1.3",
-    "@jskit-ai/kernel": "0.1.160",
+    "@jskit-ai/kernel": "0.1.161",
     "@tanstack/vue-query": "^5.101.0",
     "fastify": "^5.8.5",
     "json-rest-schema": "^1.0.17",
@@ -37,11 +37,11 @@
     "vue": "^3.5.38",
     "vue-router": "^5.1.0",
     "vuetify": "^4.1.2",
-    "@jskit-ai/http-runtime": "0.1.158"
+    "@jskit-ai/http-runtime": "0.1.159"
   },
   "devDependencies": {
-    "@jskit-ai/agent-docs": "0.1.132",
-    "@jskit-ai/config-eslint": "0.1.157",
+    "@jskit-ai/agent-docs": "0.1.133",
+    "@jskit-ai/config-eslint": "0.1.158",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

package/patterns/shell-foundation/example/package.json

@@ -29,7 +29,7 @@
   "dependencies": {
     "@local/main": "file:packages/main",
     "@fastify/static": "^10.1.3",
-    "@jskit-ai/kernel": "0.1.160",
+    "@jskit-ai/kernel": "0.1.161",
     "@tanstack/vue-query": "^5.101.0",
     "fastify": "^5.8.5",
     "json-rest-schema": "^1.0.17",
@@ -37,13 +37,13 @@
     "vue": "^3.5.38",
     "vue-router": "^5.1.0",
     "vuetify": "^4.1.2",
-    "@jskit-ai/http-runtime": "0.1.158",
+    "@jskit-ai/http-runtime": "0.1.159",
     "@mdi/js": "^7.4.47",
-    "@jskit-ai/shell-web": "0.1.164"
+    "@jskit-ai/shell-web": "0.1.165"
   },
   "devDependencies": {
-    "@jskit-ai/agent-docs": "0.1.132",
-    "@jskit-ai/config-eslint": "0.1.157",
+    "@jskit-ai/agent-docs": "0.1.133",
+    "@jskit-ai/config-eslint": "0.1.158",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

package/patterns/shell-foundation/example/packages/main/package.json

@@ -9,7 +9,7 @@
   },
   "description": "App-local runtime composition and lightweight glue.",
   "dependencies": {
-    "@jskit-ai/kernel": "0.1.160"
+    "@jskit-ai/kernel": "0.1.161"
   },
   "jskit": {
     "kind": "runtime",

package/reference/autogen/PATTERN_INDEX.md

@@ -15,7 +15,7 @@ A concrete Fastify, Vue, and JSKIT application foundation for products that do n
 
 - Id: `app/minimal-foundation`
 - Keywords: `app`, `fastify`, `foundation`, `minimal`, `server`, `vite`, `vue`
-- Owner: `@jskit-ai/agent-docs@0.1.132`
+- Owner: `@jskit-ai/agent-docs@0.1.133`
 - Read: `node_modules/@jskit-ai/agent-docs/patterns/minimal-foundation/PATTERN.md`
 - Examples: `node_modules/@jskit-ai/agent-docs/patterns/minimal-foundation/example/`
 - Requires: `@jskit-ai/http-runtime`, `@jskit-ai/kernel`
@@ -26,7 +26,7 @@ A concrete JSKIT web application foundation with responsive shell navigation, se
 
 - Id: `app/shell-foundation`
 - Keywords: `app`, `foundation`, `material`, `navigation`, `placements`, `shell`, `vite`, `vue`
-- Owner: `@jskit-ai/agent-docs@0.1.132`
+- Owner: `@jskit-ai/agent-docs@0.1.133`
 - Read: `node_modules/@jskit-ai/agent-docs/patterns/shell-foundation/PATTERN.md`
 - Examples: `node_modules/@jskit-ai/agent-docs/patterns/shell-foundation/example/`
 - Requires: `@jskit-ai/http-runtime`, `@jskit-ai/kernel`, `@jskit-ai/shell-web`
@@ -37,7 +37,7 @@ Configure an assistant runtime for one application surface and expose its chat a
 
 - Id: `assistant/assistant-surface`
 - Keywords: `ai`, `assistant`, `chat`, `config`, `environment`, `page`, `placement`, `settings`, `surface`
-- Owner: `@jskit-ai/assistant-runtime@0.1.131`
+- Owner: `@jskit-ai/assistant-runtime@0.1.132`
 - Read: `node_modules/@jskit-ai/assistant-runtime/patterns/assistant-surface/PATTERN.md`
 - Examples: `node_modules/@jskit-ai/assistant-runtime/patterns/assistant-surface/example/`
 - Requires: `@jskit-ai/assistant-runtime`, `@jskit-ai/shell-web`
@@ -48,7 +48,7 @@ Compose JSKIT authentication routes, views, profile controls, and public surface
 
 - Id: `auth/auth-surface`
 - Keywords: `account`, `auth`, `login`, `logout`, `password`, `placement`, `profile`, `reset`, `surface`
-- Owner: `@jskit-ai/auth-web@0.1.160`
+- Owner: `@jskit-ai/auth-web@0.1.161`
 - Read: `node_modules/@jskit-ai/auth-web/patterns/auth-surface/PATTERN.md`
 - Examples: `node_modules/@jskit-ai/auth-web/patterns/auth-surface/example/`
 - Requires: `@jskit-ai/auth-core`, `@jskit-ai/auth-web`, `@jskit-ai/shell-web`
@@ -59,7 +59,7 @@ Add Supabase authentication through normal npm composition, explicit environment
 
 - Id: `auth/supabase-auth`
 - Keywords: `auth`, `authentication`, `oauth`, `sessions`, `supabase`
-- Owner: `@jskit-ai/auth-provider-supabase-core@0.1.157`
+- Owner: `@jskit-ai/auth-provider-supabase-core@0.1.158`
 - Read: `node_modules/@jskit-ai/auth-provider-supabase-core/patterns/supabase-auth/PATTERN.md`
 - Examples: `node_modules/@jskit-ai/auth-provider-supabase-core/patterns/supabase-auth/example/`
 - Requires: `@jskit-ai/auth-provider-supabase-core`
@@ -70,7 +70,7 @@ Add a protected administration surface, settings shell, and semantic navigation
 
 - Id: `console/console-surface`
 - Keywords: `admin`, `console`, `navigation`, `owner`, `placement`, `settings`, `surface`
-- Owner: `@jskit-ai/console-web@0.1.128`
+- Owner: `@jskit-ai/console-web@0.1.129`
 - Read: `node_modules/@jskit-ai/console-web/patterns/console-surface/PATTERN.md`
 - Examples: `node_modules/@jskit-ai/console-web/patterns/console-surface/example/`
 - Requires: `@jskit-ai/console-core`, `@jskit-ai/console-web`, `@jskit-ai/shell-web`
@@ -81,7 +81,7 @@ Build a routed CRUD user interface as thin application pages over JSKIT's shared
 
 - Id: `crud/crud-screen-set`
 - Keywords: `actions`, `add`, `crud`, `delete`, `edit`, `filters`, `list`, `material`, `routes`, `view`, `vue`
-- Owner: `@jskit-ai/http-web@0.1.5`
+- Owner: `@jskit-ai/http-web@0.1.6`
 - Read: `node_modules/@jskit-ai/http-web/patterns/crud-screen-set/PATTERN.md`
 - Examples: `node_modules/@jskit-ai/http-web/patterns/crud-screen-set/example/`
 - Requires: `@jskit-ai/http-web`, `@jskit-ai/resource-crud-core`
@@ -92,7 +92,7 @@ Build a complete application-owned CRUD server package from a migration, resourc
 
 - Id: `crud/json-api-resource-package`
 - Keywords: `actions`, `crud`, `database`, `json-api`, `migration`, `permissions`, `provider`, `repository`, `routes`, `service`
-- Owner: `@jskit-ai/crud-core@0.1.171`
+- Owner: `@jskit-ai/crud-core@0.1.172`
 - Read: `node_modules/@jskit-ai/crud-core/patterns/json-api-resource-package/PATTERN.md`
 - Examples: `node_modules/@jskit-ai/crud-core/patterns/json-api-resource-package/example/`
 - Requires: `@jskit-ai/crud-core`, `@jskit-ai/resource-crud-core`
@@ -103,7 +103,7 @@ Define an authenticated application resource whose records belong to the current
 
 - Id: `crud/resource-contract`
 - Keywords: `authenticated`, `crud`, `database`, `owner-scoped`, `resource`, `user`
-- Owner: `@jskit-ai/resource-crud-core@0.1.102`
+- Owner: `@jskit-ai/resource-crud-core@0.1.103`
 - Read: `node_modules/@jskit-ai/resource-crud-core/patterns/resource-contract/PATTERN.md`
 - Examples: `node_modules/@jskit-ai/resource-crud-core/patterns/resource-contract/example/`
 - Requires: `@jskit-ai/resource-crud-core`
@@ -114,7 +114,7 @@ Configure a JSKIT application for MySQL with a fixed driver, ordinary environmen
 
 - Id: `database/mysql-application`
 - Keywords: `database`, `knex`, `mariadb`, `migrations`, `mysql`, `mysql2`
-- Owner: `@jskit-ai/database-runtime-mysql@0.1.158`
+- Owner: `@jskit-ai/database-runtime-mysql@0.1.159`
 - Read: `node_modules/@jskit-ai/database-runtime-mysql/patterns/mysql-application/PATTERN.md`
 - Examples: `node_modules/@jskit-ai/database-runtime-mysql/patterns/mysql-application/example/`
 - Requires: `@jskit-ai/database-runtime-mysql`
@@ -125,7 +125,7 @@ Configure a JSKIT application for PostgreSQL with a fixed driver, ordinary envir
 
 - Id: `database/postgres-application`
 - Keywords: `database`, `knex`, `migrations`, `pg`, `postgres`, `postgresql`
-- Owner: `@jskit-ai/database-runtime-postgres@0.1.157`
+- Owner: `@jskit-ai/database-runtime-postgres@0.1.158`
 - Read: `node_modules/@jskit-ai/database-runtime-postgres/patterns/postgres-application/PATTERN.md`
 - Examples: `node_modules/@jskit-ai/database-runtime-postgres/patterns/postgres-application/example/`
 - Requires: `@jskit-ai/database-runtime-postgres`
@@ -136,7 +136,7 @@ Wrap a JSKIT web application in a Capacitor Android shell using native Capacitor
 
 - Id: `mobile/android-application`
 - Keywords: `android`, `capacitor`, `device`, `mobile`, `native`, `shell`, `webview`
-- Owner: `@jskit-ai/mobile-capacitor@0.1.95`
+- Owner: `@jskit-ai/mobile-capacitor@0.1.96`
 - Read: `node_modules/@jskit-ai/mobile-capacitor/patterns/android-application/PATTERN.md`
 - Examples: `node_modules/@jskit-ai/mobile-capacitor/patterns/android-application/example/`
 - Requires: `@capacitor/android`, `@capacitor/app`, `@capacitor/cli`, `@jskit-ai/mobile-capacitor`
@@ -147,7 +147,7 @@ Add JSKIT realtime events with an optional Redis backplane and an explicit shell
 
 - Id: `realtime/realtime-application`
 - Keywords: `realtime`, `redis`, `socket.io`, `sockets`, `status`, `websocket`
-- Owner: `@jskit-ai/realtime@0.1.157`
+- Owner: `@jskit-ai/realtime@0.1.158`
 - Read: `node_modules/@jskit-ai/realtime/patterns/realtime-application/PATTERN.md`
 - Examples: `node_modules/@jskit-ai/realtime/patterns/realtime-application/example/`
 - Requires: `@jskit-ai/realtime`, `@jskit-ai/shell-web`
@@ -158,7 +158,7 @@ Define a server feature through explicit capabilities and first-class actions, a
 
 - Id: `server/feature-package`
 - Keywords: `actions`, `feature`, `json-rest`, `knex`, `orchestration`, `package`, `provider`, `repository`, `routes`, `server`
-- Owner: `@jskit-ai/agent-docs@0.1.132`
+- Owner: `@jskit-ai/agent-docs@0.1.133`
 - Read: `node_modules/@jskit-ai/agent-docs/patterns/feature-package/PATTERN.md`
 - Examples: `node_modules/@jskit-ai/agent-docs/patterns/feature-package/example/`
 - Requires: `@jskit-ai/kernel`
@@ -169,7 +169,7 @@ Compose the JSKIT responsive shell, semantic placements, settings navigation, an
 
 - Id: `shell/application-shell`
 - Keywords: `adaptive`, `app`, `layout`, `navigation`, `placement`, `responsive`, `settings`, `shell`
-- Owner: `@jskit-ai/shell-web@0.1.164`
+- Owner: `@jskit-ai/shell-web@0.1.165`
 - Read: `node_modules/@jskit-ai/shell-web/patterns/application-shell/PATTERN.md`
 - Examples: `node_modules/@jskit-ai/shell-web/patterns/application-shell/example/`
 - Requires: `@jskit-ai/kernel`, `@jskit-ai/shell-web`
@@ -180,7 +180,7 @@ Add product routes and shell extensions through file routing, semantic placement
 
 - Id: `ui/page-and-placement`
 - Keywords: `component`, `navigation`, `outlet`, `page`, `placement`, `routes`, `section`, `shell`, `subpages`, `vue`
-- Owner: `@jskit-ai/shell-web@0.1.164`
+- Owner: `@jskit-ai/shell-web@0.1.165`
 - Read: `node_modules/@jskit-ai/shell-web/patterns/page-and-placement/PATTERN.md`
 - Examples: `node_modules/@jskit-ai/shell-web/patterns/page-and-placement/example/`
 - Requires: `@jskit-ai/kernel`, `@jskit-ai/shell-web`
@@ -191,7 +191,7 @@ Compose an account settings route and profile, preference, and notification sect
 
 - Id: `users/account-settings`
 - Keywords: `account`, `notifications`, `preferences`, `profile`, `settings`, `user`, `vue`
-- Owner: `@jskit-ai/users-web@0.1.178`
+- Owner: `@jskit-ai/users-web@0.1.179`
 - Read: `node_modules/@jskit-ai/users-web/patterns/account-settings/PATTERN.md`
 - Examples: `node_modules/@jskit-ai/users-web/patterns/account-settings/example/`
 - Requires: `@jskit-ai/shell-web`, `@jskit-ai/users-core`, `@jskit-ai/users-web`
@@ -202,7 +202,7 @@ Expose user administration and workspace-scoped member operations through app-ow
 
 - Id: `users/user-administration-server`
 - Keywords: `account`, `admin`, `member`, `repository`, `resource`, `routes`, `service`, `user`, `workspace`
-- Owner: `@jskit-ai/users-core@0.1.173`
+- Owner: `@jskit-ai/users-core@0.1.174`
 - Read: `node_modules/@jskit-ai/users-core/patterns/user-administration-server/PATTERN.md`
 - Examples: `node_modules/@jskit-ai/users-core/patterns/user-administration-server/example/`
 - Requires: `@jskit-ai/crud-core`, `@jskit-ai/users-core`
@@ -213,7 +213,7 @@ Configure roles, workspace access policy, invitations, and app-owned invitation
 
 - Id: `workspaces/workspace-server`
 - Keywords: `access`, `invite`, `membership`, `multitenancy`, `policy`, `role`, `tenancy`, `workspace`
-- Owner: `@jskit-ai/workspaces-core@0.1.138`
+- Owner: `@jskit-ai/workspaces-core@0.1.139`
 - Read: `node_modules/@jskit-ai/workspaces-core/patterns/workspace-server/PATTERN.md`
 - Examples: `node_modules/@jskit-ai/workspaces-core/patterns/workspace-server/example/`
 - Requires: `@jskit-ai/users-core`, `@jskit-ai/workspaces-core`
@@ -224,7 +224,7 @@ Compose workspace selection, invitation, member administration, settings, and re
 
 - Id: `workspaces/workspace-surfaces`
 - Keywords: `admin`, `invite`, `member`, `navigation`, `settings`, `surface`, `switcher`, `workspace`
-- Owner: `@jskit-ai/workspaces-web@0.1.139`
+- Owner: `@jskit-ai/workspaces-web@0.1.140`
 - Read: `node_modules/@jskit-ai/workspaces-web/patterns/workspace-surfaces/PATTERN.md`
 - Examples: `node_modules/@jskit-ai/workspaces-web/patterns/workspace-surfaces/example/`
 - Requires: `@jskit-ai/shell-web`, `@jskit-ai/workspaces-core`, `@jskit-ai/workspaces-web`

package/skills/jskit/SKILL.md

@@ -29,6 +29,8 @@ manifests, migrations, tests, and runtime behaviour are the evidence.
 3. Read the project's product documentation and current source. JSKIT does not
    own a second project brain or prescribe a particular agent orchestrator.
 4. Load only the task-relevant direct reference:
+   - Existing-app migration: read
+     [port guide](../../guide/agent/app-setup/existing-application-migration.md).
    - For creation, foundation patterns, or package selection, read
      [application operations](references/app-operations.md).
    - Before database, schema, CRUD, repository, or persistence work, read
@@ -38,8 +40,8 @@ manifests, migrations, tests, and runtime behaviour are the evidence.
    - For every Vue/Vuetify UI creation, modification, review, or deslop task,
      also read [Material 3](references/material-3.md) completely before acting.
 
-Those files are the complete operational references required by this skill.
-Do not depend on sibling docs. Do not load irrelevant references.
+These are complete operational references required by this skill. Do not load
+irrelevant references or other docs.
 
 Do not invent missing tenancy, authentication, database, surface, ownership,
 or permission decisions when they would materially change the application.