From 904a632868dad97cf1cce9fc14c74078e2fe3a1e Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 14 Feb 2026 10:56:25 +0000
Subject: [PATCH 1/6] Initial plan


From affda4084972b3206907f33e33f3a5d2c9ba112d Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 14 Feb 2026 11:05:50 +0000
Subject: [PATCH 2/6] deprecate @objectql/core: migrate all imports to
 @objectstack/objectql

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
---
 examples/drivers/fs-demo/package.json         |  2 +-
 examples/drivers/fs-demo/src/index.ts         |  2 +-
 examples/integrations/browser/index.html      |  2 +-
 examples/integrations/browser/package.json    |  2 +-
 examples/integrations/browser/vite.config.js  |  2 +-
 .../__tests__/metadata-loading.test.ts        |  2 +-
 .../integrations/express-server/package.json  |  2 +-
 examples/quickstart/hello-world/package.json  |  2 +-
 examples/quickstart/hello-world/src/index.ts  |  2 +-
 .../enterprise-erp/__tests__/data-api.test.ts |  2 +-
 .../__tests__/metadata-api.test.ts            |  2 +-
 .../__tests__/metadata-loading.test.ts        |  2 +-
 examples/showcase/enterprise-erp/package.json |  4 +--
 examples/showcase/enterprise-erp/src/index.ts |  2 +-
 .../src/plugins/audit/audit.plugin.ts         |  3 +--
 .../__tests__/projects-hooks-actions.test.ts  |  2 +-
 .../showcase/project-tracker/package.json     |  4 +--
 examples/showcase/project-tracker/src/seed.ts |  2 +-
 packages/foundation/core/package.json         |  3 ++-
 packages/foundation/core/src/index.ts         | 25 +++++++++++--------
 .../foundation/platform-node/package.json     |  2 +-
 .../foundation/platform-node/src/loader.ts    |  2 +-
 .../platform-node/test/dynamic.test.ts        |  2 +-
 .../platform-node/test/metadata.test.ts       |  2 +-
 .../test/formula-integration.test.ts          |  2 +-
 packages/tools/cli/__tests__/commands.test.ts |  2 +-
 packages/tools/cli/package.json               |  2 +-
 packages/tools/cli/src/commands/doctor.ts     |  1 +
 packages/tools/cli/src/commands/migrate.ts    |  2 +-
 packages/tools/cli/src/commands/repl.ts       |  4 +--
 30 files changed, 48 insertions(+), 42 deletions(-)

diff --git a/examples/drivers/fs-demo/package.json b/examples/drivers/fs-demo/package.json
index 8a86e594..002ac011 100644
--- a/examples/drivers/fs-demo/package.json
+++ b/examples/drivers/fs-demo/package.json
@@ -8,7 +8,7 @@
     "dev": "ts-node src/index.ts"
   },
   "dependencies": {
-    "@objectql/core": "workspace:*",
+    "@objectstack/objectql": "^3.0.4",
     "@objectql/driver-fs": "workspace:*"
   },
   "devDependencies": {
diff --git a/examples/drivers/fs-demo/src/index.ts b/examples/drivers/fs-demo/src/index.ts
index 66c466ad..df17870f 100644
--- a/examples/drivers/fs-demo/src/index.ts
+++ b/examples/drivers/fs-demo/src/index.ts
@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import { ObjectQL } from '@objectql/core';
+import { ObjectQL } from '@objectstack/objectql';
 import { FileSystemDriver } from '@objectql/driver-fs';
 import * as path from 'path';
 
diff --git a/examples/integrations/browser/index.html b/examples/integrations/browser/index.html
index 9f07e5c0..8dc424cf 100644
--- a/examples/integrations/browser/index.html
+++ b/examples/integrations/browser/index.html
@@ -205,7 +205,7 @@ <h2>🖥️ Console Output</h2>
     </div>
     
     <script type="module">
-        import { ObjectQL } from '@objectql/core';
+        import { ObjectQL } from '@objectstack/objectql';
         import { MemoryDriver } from '@objectql/driver-memory';
         
         // Global variables
diff --git a/examples/integrations/browser/package.json b/examples/integrations/browser/package.json
index 50dfd776..579a8a90 100644
--- a/examples/integrations/browser/package.json
+++ b/examples/integrations/browser/package.json
@@ -10,7 +10,7 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "@objectql/core": "workspace:*",
+    "@objectstack/objectql": "^3.0.4",
     "@objectql/driver-memory": "workspace:*",
     "@objectql/types": "workspace:*"
   },
diff --git a/examples/integrations/browser/vite.config.js b/examples/integrations/browser/vite.config.js
index 4adbc801..99d17aa2 100644
--- a/examples/integrations/browser/vite.config.js
+++ b/examples/integrations/browser/vite.config.js
@@ -23,7 +23,7 @@ export default defineConfig({
   optimizeDeps: {
     include: [
       '@objectql/types',
-      '@objectql/core',
+      '@objectstack/objectql',
       '@objectql/driver-memory'
     ]
   },
diff --git a/examples/integrations/express-server/__tests__/metadata-loading.test.ts b/examples/integrations/express-server/__tests__/metadata-loading.test.ts
index 43f6b1cb..fc04a56c 100644
--- a/examples/integrations/express-server/__tests__/metadata-loading.test.ts
+++ b/examples/integrations/express-server/__tests__/metadata-loading.test.ts
@@ -12,7 +12,7 @@
  * Tests that metadata files are correctly loaded and registered
  */
 
-import { ObjectQL } from '@objectql/core';
+import { ObjectQL } from '@objectstack/objectql';
 import { SqlDriver } from '@objectql/driver-sql';
 import { ObjectLoader } from '@objectql/platform-node';
 import * as path from 'path';
diff --git a/examples/integrations/express-server/package.json b/examples/integrations/express-server/package.json
index c8079ddf..785db320 100644
--- a/examples/integrations/express-server/package.json
+++ b/examples/integrations/express-server/package.json
@@ -26,7 +26,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@objectql/core": "workspace:*",
+    "@objectstack/objectql": "^3.0.4",
     "@objectql/driver-sql": "workspace:*",
     "@objectql/platform-node": "workspace:*",
     "sqlite3": "^5.1.7"
diff --git a/examples/quickstart/hello-world/package.json b/examples/quickstart/hello-world/package.json
index bed71c25..9e0e1fa3 100644
--- a/examples/quickstart/hello-world/package.json
+++ b/examples/quickstart/hello-world/package.json
@@ -12,7 +12,7 @@
     "start": "ts-node src/index.ts"
   },
   "dependencies": {
-    "@objectql/core": "workspace:*",
+    "@objectstack/objectql": "^3.0.4",
     "@objectql/driver-sql": "workspace:*",
     "sqlite3": "^5.1.7"
   },
diff --git a/examples/quickstart/hello-world/src/index.ts b/examples/quickstart/hello-world/src/index.ts
index 5b03f2b2..745e5a12 100644
--- a/examples/quickstart/hello-world/src/index.ts
+++ b/examples/quickstart/hello-world/src/index.ts
@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import { ObjectQL } from '@objectql/core';
+import { ObjectQL } from '@objectstack/objectql';
 import { SqlDriver } from '@objectql/driver-sql';
 
 async function main() {
diff --git a/examples/showcase/enterprise-erp/__tests__/data-api.test.ts b/examples/showcase/enterprise-erp/__tests__/data-api.test.ts
index d99e808c..8d1af8c3 100644
--- a/examples/showcase/enterprise-erp/__tests__/data-api.test.ts
+++ b/examples/showcase/enterprise-erp/__tests__/data-api.test.ts
@@ -12,7 +12,7 @@
  * Tests CRUD operations for enterprise objects
  */
 
-import { ObjectQL } from '@objectql/core';
+import { ObjectQL } from '@objectstack/objectql';
 import { SqlDriver } from '@objectql/driver-sql';
 import { ObjectLoader } from '@objectql/platform-node';
 import * as path from 'path';
diff --git a/examples/showcase/enterprise-erp/__tests__/metadata-api.test.ts b/examples/showcase/enterprise-erp/__tests__/metadata-api.test.ts
index 0e23b0b4..b393cf48 100644
--- a/examples/showcase/enterprise-erp/__tests__/metadata-api.test.ts
+++ b/examples/showcase/enterprise-erp/__tests__/metadata-api.test.ts
@@ -12,7 +12,7 @@
  * Tests metadata API operations for enterprise objects
  */
 
-import { ObjectQL } from '@objectql/core';
+import { ObjectQL } from '@objectstack/objectql';
 import { SqlDriver } from '@objectql/driver-sql';
 import { ObjectLoader } from '@objectql/platform-node';
 import * as path from 'path';
diff --git a/examples/showcase/enterprise-erp/__tests__/metadata-loading.test.ts b/examples/showcase/enterprise-erp/__tests__/metadata-loading.test.ts
index 5fc3e93e..db99a6f3 100644
--- a/examples/showcase/enterprise-erp/__tests__/metadata-loading.test.ts
+++ b/examples/showcase/enterprise-erp/__tests__/metadata-loading.test.ts
@@ -12,7 +12,7 @@
  * Tests that the enterprise-scale metadata organization is correctly loaded
  */
 
-import { ObjectQL } from '@objectql/core';
+import { ObjectQL } from '@objectstack/objectql';
 import { SqlDriver } from '@objectql/driver-sql';
 import { ObjectLoader } from '@objectql/platform-node';
 import * as path from 'path';
diff --git a/examples/showcase/enterprise-erp/package.json b/examples/showcase/enterprise-erp/package.json
index 95e11418..28fa219a 100644
--- a/examples/showcase/enterprise-erp/package.json
+++ b/examples/showcase/enterprise-erp/package.json
@@ -31,7 +31,7 @@
     "test": "vitest run"
   },
   "peerDependencies": {
-    "@objectql/core": "workspace:*",
+    "@objectstack/objectql": "^3.0.4",
     "@objectql/driver-sql": "workspace:*",
     "@objectql/platform-node": "workspace:*",
     "@objectql/types": "workspace:*",
@@ -39,7 +39,7 @@
   },
   "devDependencies": {
     "@objectql/cli": "workspace:*",
-    "@objectql/core": "workspace:*",
+    "@objectstack/objectql": "^3.0.4",
     "@objectql/driver-sql": "workspace:*",
     "@objectql/platform-node": "workspace:*",
     "@objectql/types": "workspace:*",
diff --git a/examples/showcase/enterprise-erp/src/index.ts b/examples/showcase/enterprise-erp/src/index.ts
index bad765d6..66972e68 100644
--- a/examples/showcase/enterprise-erp/src/index.ts
+++ b/examples/showcase/enterprise-erp/src/index.ts
@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import { ObjectQL } from '@objectql/core';
+import { ObjectQL } from '@objectstack/objectql';
 import { SqlDriver } from '@objectql/driver-sql';
 import { ObjectLoader } from '@objectql/platform-node';
 import * as path from 'path';
diff --git a/examples/showcase/enterprise-erp/src/plugins/audit/audit.plugin.ts b/examples/showcase/enterprise-erp/src/plugins/audit/audit.plugin.ts
index dd6315c1..d75bb71f 100644
--- a/examples/showcase/enterprise-erp/src/plugins/audit/audit.plugin.ts
+++ b/examples/showcase/enterprise-erp/src/plugins/audit/audit.plugin.ts
@@ -6,8 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-// Import ObjectQLPlugin types from @objectql/core instead of @objectstack/runtime
-// to avoid ESM/CJS compatibility issues
+// Plugin types defined locally to avoid ESM/CJS compatibility issues
 type RuntimeContext = any;
 
 interface ObjectQLPlugin {
diff --git a/examples/showcase/project-tracker/__tests__/projects-hooks-actions.test.ts b/examples/showcase/project-tracker/__tests__/projects-hooks-actions.test.ts
index 3999d4be..208822d4 100644
--- a/examples/showcase/project-tracker/__tests__/projects-hooks-actions.test.ts
+++ b/examples/showcase/project-tracker/__tests__/projects-hooks-actions.test.ts
@@ -15,7 +15,7 @@
  * 3. Business logic patterns from the specification
  */
 
-import { ObjectQL } from '@objectql/core';
+import { ObjectQL } from '@objectstack/objectql';
 import hooks from '../src/modules/projects/projects.hook';
 import * as actions from '../src/modules/projects/projects.action';
 
diff --git a/examples/showcase/project-tracker/package.json b/examples/showcase/project-tracker/package.json
index 4af0bada..e6ff74e9 100644
--- a/examples/showcase/project-tracker/package.json
+++ b/examples/showcase/project-tracker/package.json
@@ -33,7 +33,7 @@
     "test": "vitest run"
   },
   "peerDependencies": {
-    "@objectql/core": "workspace:*",
+    "@objectstack/objectql": "^3.0.4",
     "@objectql/driver-sql": "workspace:*",
     "@objectql/platform-node": "workspace:*",
     "@objectql/types": "workspace:*",
@@ -41,7 +41,7 @@
   },
   "devDependencies": {
     "@objectql/cli": "workspace:*",
-    "@objectql/core": "workspace:*",
+    "@objectstack/objectql": "^3.0.4",
     "@objectql/driver-sql": "workspace:*",
     "@objectql/platform-node": "workspace:*",
     "@objectql/types": "workspace:*",
diff --git a/examples/showcase/project-tracker/src/seed.ts b/examples/showcase/project-tracker/src/seed.ts
index cc1ee595..fbb0fec6 100644
--- a/examples/showcase/project-tracker/src/seed.ts
+++ b/examples/showcase/project-tracker/src/seed.ts
@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import { ObjectQL } from '@objectql/core';
+import { ObjectQL } from '@objectstack/objectql';
 import { SqlDriver } from '@objectql/driver-sql';
 import { ObjectLoader } from '@objectql/platform-node';
 import * as path from 'path';
diff --git a/packages/foundation/core/package.json b/packages/foundation/core/package.json
index ee4fd15f..8d8ba706 100644
--- a/packages/foundation/core/package.json
+++ b/packages/foundation/core/package.json
@@ -1,7 +1,8 @@
 {
   "name": "@objectql/core",
   "version": "4.2.1",
-  "description": "Universal runtime engine for ObjectQL - AI-native metadata-driven ORM with validation, repository pattern, and driver orchestration",
+  "deprecated": "Use @objectstack/objectql instead. See https://github.com/objectstack-ai/spec/blob/main/content/docs/guides/objectql-migration.mdx",
+  "description": "DEPRECATED — Use @objectstack/objectql. Plugin orchestrator for ObjectQL sub-plugins (validator, formula, query).",
   "keywords": [
     "objectql",
     "orm",
diff --git a/packages/foundation/core/src/index.ts b/packages/foundation/core/src/index.ts
index 8aab53eb..60f53a6f 100644
--- a/packages/foundation/core/src/index.ts
+++ b/packages/foundation/core/src/index.ts
@@ -1,21 +1,26 @@
 /**
- * ObjectQL
+ * ObjectQL Core — DEPRECATED
  * Copyright (c) 2026-present ObjectStack Inc.
  *
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
+ *
+ * @deprecated This package is deprecated. Migrate to `@objectstack/objectql`.
+ * See: https://github.com/objectstack-ai/spec/blob/main/content/docs/guides/objectql-migration.mdx
  */
 
-// ── Convenience factory ──
-export { createObjectQLKernel, type ObjectQLKernelOptions } from './kernel-factory';
+// ── Re-exports from @objectstack/objectql (deprecated — import directly from upstream) ──
 
-// ── Re-export bridge engine (extends upstream with MetadataRegistry + legacy config) ──
-export { ObjectQL, type ObjectQLConfig } from './app';
+/** @deprecated Import from `@objectstack/objectql` instead. */
+export { ObjectQL } from '@objectstack/objectql';
+/** @deprecated Import from `@objectstack/objectql` instead. */
 export { ObjectRepository, ScopedContext, SchemaRegistry } from '@objectstack/objectql';
-export type { HookHandler, HookEntry, OperationContext, EngineMiddleware, ObjectQLHostContext } from '@objectstack/objectql';
+/** @deprecated Import from `@objectstack/objectql` instead. */
+export { createObjectQLKernel } from '@objectstack/objectql';
+/** @deprecated Import from `@objectstack/objectql` instead. */
+export { toTitleCase, convertIntrospectedSchemaToObjects } from '@objectstack/objectql';
+/** @deprecated Import from `@objectstack/objectql` instead. */
+export type { ObjectQLKernelOptions, HookHandler, HookEntry, OperationContext, EngineMiddleware, ObjectQLHostContext } from '@objectstack/objectql';
 
-// ── Plugin orchestration ──
+// ── Plugin orchestration (downstream — stays in @objectql ecosystem) ──
 export * from './plugin';
-
-// ── Utilities ──
-export * from './util';
diff --git a/packages/foundation/platform-node/package.json b/packages/foundation/platform-node/package.json
index 7ddff150..c587950e 100644
--- a/packages/foundation/platform-node/package.json
+++ b/packages/foundation/platform-node/package.json
@@ -27,7 +27,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@objectql/core": "workspace:*",
+    "@objectstack/objectql": "^3.0.4",
     "@objectql/types": "workspace:*",
     "@objectstack/spec": "^3.0.4",
     "fast-glob": "^3.3.2",
diff --git a/packages/foundation/platform-node/src/loader.ts b/packages/foundation/platform-node/src/loader.ts
index db856b4d..a93d5294 100644
--- a/packages/foundation/platform-node/src/loader.ts
+++ b/packages/foundation/platform-node/src/loader.ts
@@ -11,7 +11,7 @@ import * as glob from 'fast-glob';
 import * as path from 'path';
 import { MetadataRegistry, ObjectConfig, LoaderPlugin, LoaderHandlerContext, FieldConfig } from '@objectql/types';
 import * as yaml from 'js-yaml';
-import { toTitleCase } from '@objectql/core';
+import { toTitleCase } from '@objectstack/objectql';
 
 export class ObjectLoader {
     private plugins: LoaderPlugin[] = [];
diff --git a/packages/foundation/platform-node/test/dynamic.test.ts b/packages/foundation/platform-node/test/dynamic.test.ts
index 9b1cdfaf..32ba24ab 100644
--- a/packages/foundation/platform-node/test/dynamic.test.ts
+++ b/packages/foundation/platform-node/test/dynamic.test.ts
@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import { ObjectQL } from '@objectql/core';
+import { ObjectQL } from '@objectstack/objectql';
 import { ObjectLoader } from '../src';
 import * as path from 'path';
 
diff --git a/packages/foundation/platform-node/test/metadata.test.ts b/packages/foundation/platform-node/test/metadata.test.ts
index 33439ca6..e2b2647d 100644
--- a/packages/foundation/platform-node/test/metadata.test.ts
+++ b/packages/foundation/platform-node/test/metadata.test.ts
@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import { ObjectQL } from '@objectql/core';
+import { ObjectQL } from '@objectstack/objectql';
 import { ObjectConfig } from '@objectql/types';
 import * as fs from 'fs';
 import * as path from 'path';
diff --git a/packages/foundation/plugin-formula/test/formula-integration.test.ts b/packages/foundation/plugin-formula/test/formula-integration.test.ts
index b3e45e70..88e65128 100644
--- a/packages/foundation/plugin-formula/test/formula-integration.test.ts
+++ b/packages/foundation/plugin-formula/test/formula-integration.test.ts
@@ -12,7 +12,7 @@
  * Tests formula evaluation within repository queries
  */
 
-import { ObjectQL } from '@objectql/core';
+import { ObjectQL } from '@objectstack/objectql';
 import { MockDriver } from './mock-driver';
 import { FormulaPlugin } from '../src/formula-plugin';
 
diff --git a/packages/tools/cli/__tests__/commands.test.ts b/packages/tools/cli/__tests__/commands.test.ts
index d9802b6c..d4c296e7 100644
--- a/packages/tools/cli/__tests__/commands.test.ts
+++ b/packages/tools/cli/__tests__/commands.test.ts
@@ -15,7 +15,7 @@ import { build } from '../src/commands/build';
 import { lint } from '../src/commands/lint';
 import { test as testCommand } from '../src/commands/test';
 import { doctorCommand } from '../src/commands/doctor';
-import { ObjectQL } from '@objectql/core';
+import { ObjectQL } from '@objectstack/objectql';
 import { SqlDriver } from '@objectql/driver-sql';
 import * as yaml from 'js-yaml';
 
diff --git a/packages/tools/cli/package.json b/packages/tools/cli/package.json
index 1f059c76..b0396c2d 100644
--- a/packages/tools/cli/package.json
+++ b/packages/tools/cli/package.json
@@ -30,7 +30,7 @@
   },
   "dependencies": {
     "@objectql/types": "workspace:*",
-    "@objectql/core": "workspace:*",
+    "@objectstack/objectql": "^3.0.4",
     "@objectql/plugin-validator": "workspace:*",
     "@objectql/driver-sql": "workspace:*",
     "@objectql/platform-node": "workspace:*",
diff --git a/packages/tools/cli/src/commands/doctor.ts b/packages/tools/cli/src/commands/doctor.ts
index 5334d72b..e17386b5 100644
--- a/packages/tools/cli/src/commands/doctor.ts
+++ b/packages/tools/cli/src/commands/doctor.ts
@@ -208,6 +208,7 @@ async function checkDependencies(packageJson: any): Promise<DependencyCheck[]> {
     
     // Check for ObjectQL core packages
     const corePackages = [
+        '@objectstack/objectql',
         '@objectql/core',
         '@objectql/types',
         '@objectql/cli'
diff --git a/packages/tools/cli/src/commands/migrate.ts b/packages/tools/cli/src/commands/migrate.ts
index a9cc40ea..04e63b25 100644
--- a/packages/tools/cli/src/commands/migrate.ts
+++ b/packages/tools/cli/src/commands/migrate.ts
@@ -27,7 +27,7 @@ interface MigrateStatusOptions {
     dir?: string;
 }
 
-const MIGRATION_TEMPLATE = `import { ObjectQL } from '@objectql/core';
+const MIGRATION_TEMPLATE = `import { ObjectQL } from '@objectstack/objectql';
 
 /**
  * Migration: {{name}}
diff --git a/packages/tools/cli/src/commands/repl.ts b/packages/tools/cli/src/commands/repl.ts
index 138740e4..7c620a76 100644
--- a/packages/tools/cli/src/commands/repl.ts
+++ b/packages/tools/cli/src/commands/repl.ts
@@ -9,7 +9,7 @@
 import * as repl from 'repl';
 import * as _path from 'path';
 import * as _fs from 'fs';
-import { ObjectQL } from '@objectql/core';
+import { ObjectQL } from '@objectstack/objectql';
 import { register } from 'ts-node';
 import { resolveConfigFile } from '../utils/config-loader';
 
@@ -83,7 +83,7 @@ export async function startRepl(configPath?: string) {
                     get: () => {
                         // Dynamic require to avoid circular dependency — ObjectRepository is constructed
                         // from the user-provided app instance to enable convenient REPL access.
-                        const { ObjectRepository } = require('@objectql/core');
+                        const { ObjectRepository } = require('@objectstack/objectql');
                         
                         const replContext: any = {
                             roles: ['admin'],

From db48f145c52735c6867c059867e8964cabb721bd Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 14 Feb 2026 11:14:56 +0000
Subject: [PATCH 3/6] fix: restore bridge-dependent examples, verify build
 (36/36) and tests pass

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
---
 examples/drivers/fs-demo/package.json                    | 2 +-
 examples/drivers/fs-demo/src/index.ts                    | 2 +-
 examples/integrations/browser/index.html                 | 2 +-
 examples/integrations/browser/package.json               | 2 +-
 examples/integrations/browser/vite.config.js             | 2 +-
 .../express-server/__tests__/metadata-loading.test.ts    | 2 +-
 examples/integrations/express-server/package.json        | 2 +-
 examples/quickstart/hello-world/package.json             | 2 +-
 examples/quickstart/hello-world/src/index.ts             | 2 +-
 .../showcase/enterprise-erp/__tests__/data-api.test.ts   | 2 +-
 .../enterprise-erp/__tests__/metadata-api.test.ts        | 2 +-
 .../enterprise-erp/__tests__/metadata-loading.test.ts    | 2 +-
 examples/showcase/enterprise-erp/package.json            | 4 ++--
 examples/showcase/enterprise-erp/src/index.ts            | 2 +-
 .../__tests__/projects-hooks-actions.test.ts             | 2 +-
 examples/showcase/project-tracker/package.json           | 4 ++--
 examples/showcase/project-tracker/src/seed.ts            | 2 +-
 packages/foundation/core/src/index.ts                    | 7 ++++---
 packages/foundation/platform-node/test/dynamic.test.ts   | 2 +-
 packages/foundation/platform-node/test/metadata.test.ts  | 2 +-
 .../plugin-formula/test/formula-integration.test.ts      | 2 +-
 packages/tools/cli/__tests__/commands.test.ts            | 2 +-
 packages/tools/cli/package.json                          | 1 +
 pnpm-lock.yaml                                           | 9 ++++++---
 24 files changed, 34 insertions(+), 29 deletions(-)

diff --git a/examples/drivers/fs-demo/package.json b/examples/drivers/fs-demo/package.json
index 002ac011..8a86e594 100644
--- a/examples/drivers/fs-demo/package.json
+++ b/examples/drivers/fs-demo/package.json
@@ -8,7 +8,7 @@
     "dev": "ts-node src/index.ts"
   },
   "dependencies": {
-    "@objectstack/objectql": "^3.0.4",
+    "@objectql/core": "workspace:*",
     "@objectql/driver-fs": "workspace:*"
   },
   "devDependencies": {
diff --git a/examples/drivers/fs-demo/src/index.ts b/examples/drivers/fs-demo/src/index.ts
index df17870f..66c466ad 100644
--- a/examples/drivers/fs-demo/src/index.ts
+++ b/examples/drivers/fs-demo/src/index.ts
@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import { ObjectQL } from '@objectstack/objectql';
+import { ObjectQL } from '@objectql/core';
 import { FileSystemDriver } from '@objectql/driver-fs';
 import * as path from 'path';
 
diff --git a/examples/integrations/browser/index.html b/examples/integrations/browser/index.html
index 8dc424cf..9f07e5c0 100644
--- a/examples/integrations/browser/index.html
+++ b/examples/integrations/browser/index.html
@@ -205,7 +205,7 @@ <h2>🖥️ Console Output</h2>
     </div>
     
     <script type="module">
-        import { ObjectQL } from '@objectstack/objectql';
+        import { ObjectQL } from '@objectql/core';
         import { MemoryDriver } from '@objectql/driver-memory';
         
         // Global variables
diff --git a/examples/integrations/browser/package.json b/examples/integrations/browser/package.json
index 579a8a90..50dfd776 100644
--- a/examples/integrations/browser/package.json
+++ b/examples/integrations/browser/package.json
@@ -10,7 +10,7 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "@objectstack/objectql": "^3.0.4",
+    "@objectql/core": "workspace:*",
     "@objectql/driver-memory": "workspace:*",
     "@objectql/types": "workspace:*"
   },
diff --git a/examples/integrations/browser/vite.config.js b/examples/integrations/browser/vite.config.js
index 99d17aa2..4adbc801 100644
--- a/examples/integrations/browser/vite.config.js
+++ b/examples/integrations/browser/vite.config.js
@@ -23,7 +23,7 @@ export default defineConfig({
   optimizeDeps: {
     include: [
       '@objectql/types',
-      '@objectstack/objectql',
+      '@objectql/core',
       '@objectql/driver-memory'
     ]
   },
diff --git a/examples/integrations/express-server/__tests__/metadata-loading.test.ts b/examples/integrations/express-server/__tests__/metadata-loading.test.ts
index fc04a56c..43f6b1cb 100644
--- a/examples/integrations/express-server/__tests__/metadata-loading.test.ts
+++ b/examples/integrations/express-server/__tests__/metadata-loading.test.ts
@@ -12,7 +12,7 @@
  * Tests that metadata files are correctly loaded and registered
  */
 
-import { ObjectQL } from '@objectstack/objectql';
+import { ObjectQL } from '@objectql/core';
 import { SqlDriver } from '@objectql/driver-sql';
 import { ObjectLoader } from '@objectql/platform-node';
 import * as path from 'path';
diff --git a/examples/integrations/express-server/package.json b/examples/integrations/express-server/package.json
index 785db320..c8079ddf 100644
--- a/examples/integrations/express-server/package.json
+++ b/examples/integrations/express-server/package.json
@@ -26,7 +26,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@objectstack/objectql": "^3.0.4",
+    "@objectql/core": "workspace:*",
     "@objectql/driver-sql": "workspace:*",
     "@objectql/platform-node": "workspace:*",
     "sqlite3": "^5.1.7"
diff --git a/examples/quickstart/hello-world/package.json b/examples/quickstart/hello-world/package.json
index 9e0e1fa3..bed71c25 100644
--- a/examples/quickstart/hello-world/package.json
+++ b/examples/quickstart/hello-world/package.json
@@ -12,7 +12,7 @@
     "start": "ts-node src/index.ts"
   },
   "dependencies": {
-    "@objectstack/objectql": "^3.0.4",
+    "@objectql/core": "workspace:*",
     "@objectql/driver-sql": "workspace:*",
     "sqlite3": "^5.1.7"
   },
diff --git a/examples/quickstart/hello-world/src/index.ts b/examples/quickstart/hello-world/src/index.ts
index 745e5a12..5b03f2b2 100644
--- a/examples/quickstart/hello-world/src/index.ts
+++ b/examples/quickstart/hello-world/src/index.ts
@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import { ObjectQL } from '@objectstack/objectql';
+import { ObjectQL } from '@objectql/core';
 import { SqlDriver } from '@objectql/driver-sql';
 
 async function main() {
diff --git a/examples/showcase/enterprise-erp/__tests__/data-api.test.ts b/examples/showcase/enterprise-erp/__tests__/data-api.test.ts
index 8d1af8c3..d99e808c 100644
--- a/examples/showcase/enterprise-erp/__tests__/data-api.test.ts
+++ b/examples/showcase/enterprise-erp/__tests__/data-api.test.ts
@@ -12,7 +12,7 @@
  * Tests CRUD operations for enterprise objects
  */
 
-import { ObjectQL } from '@objectstack/objectql';
+import { ObjectQL } from '@objectql/core';
 import { SqlDriver } from '@objectql/driver-sql';
 import { ObjectLoader } from '@objectql/platform-node';
 import * as path from 'path';
diff --git a/examples/showcase/enterprise-erp/__tests__/metadata-api.test.ts b/examples/showcase/enterprise-erp/__tests__/metadata-api.test.ts
index b393cf48..0e23b0b4 100644
--- a/examples/showcase/enterprise-erp/__tests__/metadata-api.test.ts
+++ b/examples/showcase/enterprise-erp/__tests__/metadata-api.test.ts
@@ -12,7 +12,7 @@
  * Tests metadata API operations for enterprise objects
  */
 
-import { ObjectQL } from '@objectstack/objectql';
+import { ObjectQL } from '@objectql/core';
 import { SqlDriver } from '@objectql/driver-sql';
 import { ObjectLoader } from '@objectql/platform-node';
 import * as path from 'path';
diff --git a/examples/showcase/enterprise-erp/__tests__/metadata-loading.test.ts b/examples/showcase/enterprise-erp/__tests__/metadata-loading.test.ts
index db99a6f3..5fc3e93e 100644
--- a/examples/showcase/enterprise-erp/__tests__/metadata-loading.test.ts
+++ b/examples/showcase/enterprise-erp/__tests__/metadata-loading.test.ts
@@ -12,7 +12,7 @@
  * Tests that the enterprise-scale metadata organization is correctly loaded
  */
 
-import { ObjectQL } from '@objectstack/objectql';
+import { ObjectQL } from '@objectql/core';
 import { SqlDriver } from '@objectql/driver-sql';
 import { ObjectLoader } from '@objectql/platform-node';
 import * as path from 'path';
diff --git a/examples/showcase/enterprise-erp/package.json b/examples/showcase/enterprise-erp/package.json
index 28fa219a..95e11418 100644
--- a/examples/showcase/enterprise-erp/package.json
+++ b/examples/showcase/enterprise-erp/package.json
@@ -31,7 +31,7 @@
     "test": "vitest run"
   },
   "peerDependencies": {
-    "@objectstack/objectql": "^3.0.4",
+    "@objectql/core": "workspace:*",
     "@objectql/driver-sql": "workspace:*",
     "@objectql/platform-node": "workspace:*",
     "@objectql/types": "workspace:*",
@@ -39,7 +39,7 @@
   },
   "devDependencies": {
     "@objectql/cli": "workspace:*",
-    "@objectstack/objectql": "^3.0.4",
+    "@objectql/core": "workspace:*",
     "@objectql/driver-sql": "workspace:*",
     "@objectql/platform-node": "workspace:*",
     "@objectql/types": "workspace:*",
diff --git a/examples/showcase/enterprise-erp/src/index.ts b/examples/showcase/enterprise-erp/src/index.ts
index 66972e68..bad765d6 100644
--- a/examples/showcase/enterprise-erp/src/index.ts
+++ b/examples/showcase/enterprise-erp/src/index.ts
@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import { ObjectQL } from '@objectstack/objectql';
+import { ObjectQL } from '@objectql/core';
 import { SqlDriver } from '@objectql/driver-sql';
 import { ObjectLoader } from '@objectql/platform-node';
 import * as path from 'path';
diff --git a/examples/showcase/project-tracker/__tests__/projects-hooks-actions.test.ts b/examples/showcase/project-tracker/__tests__/projects-hooks-actions.test.ts
index 208822d4..3999d4be 100644
--- a/examples/showcase/project-tracker/__tests__/projects-hooks-actions.test.ts
+++ b/examples/showcase/project-tracker/__tests__/projects-hooks-actions.test.ts
@@ -15,7 +15,7 @@
  * 3. Business logic patterns from the specification
  */
 
-import { ObjectQL } from '@objectstack/objectql';
+import { ObjectQL } from '@objectql/core';
 import hooks from '../src/modules/projects/projects.hook';
 import * as actions from '../src/modules/projects/projects.action';
 
diff --git a/examples/showcase/project-tracker/package.json b/examples/showcase/project-tracker/package.json
index e6ff74e9..4af0bada 100644
--- a/examples/showcase/project-tracker/package.json
+++ b/examples/showcase/project-tracker/package.json
@@ -33,7 +33,7 @@
     "test": "vitest run"
   },
   "peerDependencies": {
-    "@objectstack/objectql": "^3.0.4",
+    "@objectql/core": "workspace:*",
     "@objectql/driver-sql": "workspace:*",
     "@objectql/platform-node": "workspace:*",
     "@objectql/types": "workspace:*",
@@ -41,7 +41,7 @@
   },
   "devDependencies": {
     "@objectql/cli": "workspace:*",
-    "@objectstack/objectql": "^3.0.4",
+    "@objectql/core": "workspace:*",
     "@objectql/driver-sql": "workspace:*",
     "@objectql/platform-node": "workspace:*",
     "@objectql/types": "workspace:*",
diff --git a/examples/showcase/project-tracker/src/seed.ts b/examples/showcase/project-tracker/src/seed.ts
index fbb0fec6..cc1ee595 100644
--- a/examples/showcase/project-tracker/src/seed.ts
+++ b/examples/showcase/project-tracker/src/seed.ts
@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import { ObjectQL } from '@objectstack/objectql';
+import { ObjectQL } from '@objectql/core';
 import { SqlDriver } from '@objectql/driver-sql';
 import { ObjectLoader } from '@objectql/platform-node';
 import * as path from 'path';
diff --git a/packages/foundation/core/src/index.ts b/packages/foundation/core/src/index.ts
index 60f53a6f..1afe14bb 100644
--- a/packages/foundation/core/src/index.ts
+++ b/packages/foundation/core/src/index.ts
@@ -9,10 +9,11 @@
  * See: https://github.com/objectstack-ai/spec/blob/main/content/docs/guides/objectql-migration.mdx
  */
 
-// ── Re-exports from @objectstack/objectql (deprecated — import directly from upstream) ──
+// ── Bridge engine (deprecated — use @objectstack/objectql ObjectQL directly) ──
+/** @deprecated Import ObjectQL from `@objectstack/objectql` instead. This bridge class will be removed in a future version. */
+export { ObjectQL, type ObjectQLConfig } from './app';
 
-/** @deprecated Import from `@objectstack/objectql` instead. */
-export { ObjectQL } from '@objectstack/objectql';
+// ── Re-exports from @objectstack/objectql (deprecated — import directly from upstream) ──
 /** @deprecated Import from `@objectstack/objectql` instead. */
 export { ObjectRepository, ScopedContext, SchemaRegistry } from '@objectstack/objectql';
 /** @deprecated Import from `@objectstack/objectql` instead. */
diff --git a/packages/foundation/platform-node/test/dynamic.test.ts b/packages/foundation/platform-node/test/dynamic.test.ts
index 32ba24ab..9b1cdfaf 100644
--- a/packages/foundation/platform-node/test/dynamic.test.ts
+++ b/packages/foundation/platform-node/test/dynamic.test.ts
@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import { ObjectQL } from '@objectstack/objectql';
+import { ObjectQL } from '@objectql/core';
 import { ObjectLoader } from '../src';
 import * as path from 'path';
 
diff --git a/packages/foundation/platform-node/test/metadata.test.ts b/packages/foundation/platform-node/test/metadata.test.ts
index e2b2647d..33439ca6 100644
--- a/packages/foundation/platform-node/test/metadata.test.ts
+++ b/packages/foundation/platform-node/test/metadata.test.ts
@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import { ObjectQL } from '@objectstack/objectql';
+import { ObjectQL } from '@objectql/core';
 import { ObjectConfig } from '@objectql/types';
 import * as fs from 'fs';
 import * as path from 'path';
diff --git a/packages/foundation/plugin-formula/test/formula-integration.test.ts b/packages/foundation/plugin-formula/test/formula-integration.test.ts
index 88e65128..b3e45e70 100644
--- a/packages/foundation/plugin-formula/test/formula-integration.test.ts
+++ b/packages/foundation/plugin-formula/test/formula-integration.test.ts
@@ -12,7 +12,7 @@
  * Tests formula evaluation within repository queries
  */
 
-import { ObjectQL } from '@objectstack/objectql';
+import { ObjectQL } from '@objectql/core';
 import { MockDriver } from './mock-driver';
 import { FormulaPlugin } from '../src/formula-plugin';
 
diff --git a/packages/tools/cli/__tests__/commands.test.ts b/packages/tools/cli/__tests__/commands.test.ts
index d4c296e7..d9802b6c 100644
--- a/packages/tools/cli/__tests__/commands.test.ts
+++ b/packages/tools/cli/__tests__/commands.test.ts
@@ -15,7 +15,7 @@ import { build } from '../src/commands/build';
 import { lint } from '../src/commands/lint';
 import { test as testCommand } from '../src/commands/test';
 import { doctorCommand } from '../src/commands/doctor';
-import { ObjectQL } from '@objectstack/objectql';
+import { ObjectQL } from '@objectql/core';
 import { SqlDriver } from '@objectql/driver-sql';
 import * as yaml from 'js-yaml';
 
diff --git a/packages/tools/cli/package.json b/packages/tools/cli/package.json
index b0396c2d..8aa0831c 100644
--- a/packages/tools/cli/package.json
+++ b/packages/tools/cli/package.json
@@ -31,6 +31,7 @@
   "dependencies": {
     "@objectql/types": "workspace:*",
     "@objectstack/objectql": "^3.0.4",
+    "@objectql/core": "workspace:*",
     "@objectql/plugin-validator": "workspace:*",
     "@objectql/driver-sql": "workspace:*",
     "@objectql/platform-node": "workspace:*",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index fd5b3fe4..077302a5 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -596,12 +596,12 @@ importers:
 
   packages/foundation/platform-node:
     dependencies:
-      '@objectql/core':
-        specifier: workspace:*
-        version: link:../core
       '@objectql/types':
         specifier: workspace:*
         version: link:../types
+      '@objectstack/objectql':
+        specifier: ^3.0.4
+        version: 3.0.4
       '@objectstack/spec':
         specifier: ^3.0.4
         version: 3.0.4
@@ -930,6 +930,9 @@ importers:
       '@objectql/types':
         specifier: workspace:*
         version: link:../../foundation/types
+      '@objectstack/objectql':
+        specifier: ^3.0.4
+        version: 3.0.4
       chalk:
         specifier: ^4.1.2
         version: 4.1.2

From e82305dec5a6e6264cc23f2bde41de02518ed18d Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 14 Feb 2026 11:17:54 +0000
Subject: [PATCH 4/6] docs: add deprecation notice to @objectql/core docs and
 migration guide

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
---
 content/docs/architecture/core.mdx         |   7 +-
 content/docs/guides/meta.json              |   3 +-
 content/docs/guides/objectql-migration.mdx | 139 +++++++++++++++++++++
 packages/foundation/core/README.md         |   7 +-
 4 files changed, 152 insertions(+), 4 deletions(-)
 create mode 100644 content/docs/guides/objectql-migration.mdx

diff --git a/content/docs/architecture/core.mdx b/content/docs/architecture/core.mdx
index a3aed48e..82104548 100644
--- a/content/docs/architecture/core.mdx
+++ b/content/docs/architecture/core.mdx
@@ -1,10 +1,15 @@
 ---
-title: "@objectql/core"
+title: "@objectql/core (Deprecated)"
 description: The Runtime Engine - Core ORM, validation, and business logic compiler for ObjectQL
 ---
 
 # @objectql/core
 
+<Callout type="warn" title="Deprecated">
+  `@objectql/core` is deprecated. All core functionality is now available in [`@objectstack/objectql`](https://www.npmjs.com/package/@objectstack/objectql).
+  See the [Migration Guide](/docs/guides/objectql-migration) for step-by-step instructions.
+</Callout>
+
 **The Runtime Engine**: The core ORM and business logic compiler for ObjectQL. This package transforms abstract metadata (defined in `@objectql/types`) into executable database operations, validations, and business rules.
 
 ## Overview
diff --git a/content/docs/guides/meta.json b/content/docs/guides/meta.json
index 028fe6ff..4d002e9d 100644
--- a/content/docs/guides/meta.json
+++ b/content/docs/guides/meta.json
@@ -3,6 +3,7 @@
   "pages": [
     "error-handling",
     "architecture",
-    "migration-v5"
+    "migration-v5",
+    "objectql-migration"
   ]
 }
diff --git a/content/docs/guides/objectql-migration.mdx b/content/docs/guides/objectql-migration.mdx
new file mode 100644
index 00000000..caab8ae2
--- /dev/null
+++ b/content/docs/guides/objectql-migration.mdx
@@ -0,0 +1,139 @@
+---
+title: "Migrating from @objectql/core"
+description: "Step-by-step guide for migrating from @objectql/core to @objectstack/objectql"
+---
+
+# Migrating from `@objectql/core` to `@objectstack/objectql`
+
+All core functionality previously provided by `@objectql/core` is now available upstream in `@objectstack/objectql`. This guide walks you through migrating your project so that `@objectql/core` can be removed.
+
+## Why Migrate?
+
+| | `@objectql/core` (deprecated) | `@objectstack/objectql` (recommended) |
+| :--- | :--- | :--- |
+| **Engine** | Bridge class extending upstream `ObjectQL` | Canonical `ObjectQL` engine |
+| **Kernel Factory** | `createObjectQLKernel()` | `createObjectQLKernel()` (identical API) |
+| **Introspection** | `toTitleCase`, `convertIntrospectedSchemaToObjects` | Same functions, same signatures |
+| **Registry** | Re-exports from upstream | Direct exports |
+| **MetadataRegistry** | `@objectql/types` `MetadataRegistry` class | `MetadataFacade` (async `IMetadataService`) |
+| **Maintenance** | Planned deprecation | Actively maintained |
+
+## Step 1 — Update Dependencies
+
+```diff
+  // package.json
+  {
+    "dependencies": {
+-     "@objectql/core": "^4.x",
+-     "@objectql/types": "^4.x",
++     "@objectstack/objectql": "^3.1.0"
+    }
+  }
+```
+
+Then re-install:
+
+```bash
+pnpm install
+```
+
+## Step 2 — Update Imports
+
+### Engine, Repository & Context
+
+```diff
+- import { ObjectQL, ObjectRepository, ScopedContext } from '@objectql/core';
++ import { ObjectQL, ObjectRepository, ScopedContext } from '@objectstack/objectql';
+```
+
+```diff
+- import type { HookHandler, HookEntry, OperationContext, EngineMiddleware } from '@objectql/core';
++ import type { HookHandler, HookEntry, OperationContext, EngineMiddleware } from '@objectstack/objectql';
+```
+
+### Schema Registry
+
+```diff
+- import { SchemaRegistry } from '@objectql/core';
++ import { SchemaRegistry } from '@objectstack/objectql';
+```
+
+### Kernel Factory
+
+```diff
+- import { createObjectQLKernel } from '@objectql/core';
++ import { createObjectQLKernel } from '@objectstack/objectql';
+```
+
+### Utility Functions
+
+```diff
+- import { toTitleCase, convertIntrospectedSchemaToObjects } from '@objectql/core';
++ import { toTitleCase, convertIntrospectedSchemaToObjects } from '@objectstack/objectql';
+```
+
+### Introspection Types
+
+```diff
+- import type { IntrospectedSchema, IntrospectedTable } from '@objectql/types';
++ import type { IntrospectedSchema, IntrospectedTable } from '@objectstack/objectql';
+```
+
+## Step 3 — API Differences
+
+### `createObjectQLKernel()`
+
+The function signature is identical. The only change is the return type uses the upstream `ObjectKernel`:
+
+```typescript
+import { createObjectQLKernel } from '@objectstack/objectql';
+
+const kernel = await createObjectQLKernel({
+  plugins: [myDriverPlugin],
+});
+await kernel.bootstrap();
+```
+
+### MetadataRegistry → MetadataFacade
+
+If you were using `MetadataRegistry` from `@objectql/types`, the upstream equivalent is `MetadataFacade`. The key difference is that `MetadataFacade` methods are **async** (returns `Promise`):
+
+```diff
+- import { MetadataRegistry } from '@objectql/types';
+- const registry = new MetadataRegistry();
+- registry.register('object', myObject);
+- const obj = registry.get('object', 'account');
++ import { MetadataFacade } from '@objectstack/objectql';
++ const facade = new MetadataFacade();
++ await facade.register('object', 'account', myObject);
++ const obj = await facade.get('object', 'account');
+```
+
+### ObjectQLPlugin
+
+Both packages export an `ObjectQLPlugin`, but they serve different roles:
+
+| | `@objectql/core` `ObjectQLPlugin` | `@objectstack/objectql` `ObjectQLPlugin` |
+| :--- | :--- | :--- |
+| Interface | `RuntimePlugin` (from `@objectql/types`) | `Plugin` (from `@objectstack/core`) |
+| Role | Orchestrator composing sub-plugins (validator, formula, query) | Kernel plugin registering ObjectQL as core services |
+
+If you were using the `@objectql/core` `ObjectQLPlugin` to compose sub-plugins (`ValidatorPlugin`, `FormulaPlugin`, `QueryPlugin`), those downstream plugins are **not** part of this migration — they remain in the `@objectql` ecosystem.
+
+## Step 4 — Remove `@objectql/core`
+
+Once all imports are updated and tests pass:
+
+```bash
+pnpm remove @objectql/core @objectql/types
+```
+
+## Checklist
+
+- [ ] Replace `@objectql/core` dependency with `@objectstack/objectql` in `package.json`
+- [ ] Update all `import` statements (engine, registry, kernel factory, utilities, types)
+- [ ] Replace `MetadataRegistry` usage with `MetadataFacade` (add `await`)
+- [ ] Verify `ObjectQLPlugin` usage matches the upstream interface
+- [ ] Run `pnpm build` and fix any remaining type errors
+- [ ] Run `pnpm test` to verify behavior
+- [ ] Remove `@objectql/core` and `@objectql/types` from dependencies
diff --git a/packages/foundation/core/README.md b/packages/foundation/core/README.md
index 76aa9714..5b2c0200 100644
--- a/packages/foundation/core/README.md
+++ b/packages/foundation/core/README.md
@@ -1,8 +1,11 @@
 # @objectql/core
 
-> **Implementation Status**: ✅ **Production Ready** - All core features fully implemented and tested. See [Implementation Status](https://github.com/objectstack-ai/objectql/blob/main/IMPLEMENTATION_STATUS.md) for complete details.
+> ⚠️ **DEPRECATED**: This package is deprecated. Use [`@objectstack/objectql`](https://www.npmjs.com/package/@objectstack/objectql) instead.
+> See the [Migration Guide](https://github.com/objectstack-ai/spec/blob/main/content/docs/guides/objectql-migration.mdx) for step-by-step instructions.
 
-The core ORM and runtime engine for ObjectQL. This package handles object querying, CRUD operations, database driver coordination, transaction management, and **metadata-driven validation**. As of version 4.0.0, it wraps the **ObjectKernel** for plugin architecture and lifecycle management.
+The core ORM and runtime engine for ObjectQL. All core functionality (ObjectQL engine, SchemaRegistry, createObjectQLKernel, utilities) is now available directly from `@objectstack/objectql`.
+
+The `ObjectQLPlugin` (orchestrator composing sub-plugins like ValidatorPlugin, FormulaPlugin, QueryPlugin) remains in this package as it is specific to the `@objectql` ecosystem.
 
 ## Features
 

From 297905dd688b8ab2fa502d5e33babcf9cb5caa32 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 14 Feb 2026 11:18:47 +0000
Subject: [PATCH 5/6] docs: clarify MetadataFacade async description

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
---
 content/docs/guides/objectql-migration.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/content/docs/guides/objectql-migration.mdx b/content/docs/guides/objectql-migration.mdx
index caab8ae2..4f7dc153 100644
--- a/content/docs/guides/objectql-migration.mdx
+++ b/content/docs/guides/objectql-migration.mdx
@@ -96,7 +96,7 @@ await kernel.bootstrap();
 
 ### MetadataRegistry → MetadataFacade
 
-If you were using `MetadataRegistry` from `@objectql/types`, the upstream equivalent is `MetadataFacade`. The key difference is that `MetadataFacade` methods are **async** (returns `Promise`):
+If you were using `MetadataRegistry` from `@objectql/types`, the upstream equivalent is `MetadataFacade`. The key difference is that `MetadataFacade` methods are **async**:
 
 ```diff
 - import { MetadataRegistry } from '@objectql/types';

From 41f95100f89ac36405849b4bfb6d259134536456 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 14 Feb 2026 11:42:22 +0000
Subject: [PATCH 6/6] fix: keep local kernel-factory exports, fix migration
 guide version and API

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
---
 content/docs/guides/objectql-migration.mdx | 4 ++--
 packages/foundation/core/src/index.ts      | 8 +++++---
 2 files changed, 7 insertions(+), 5 deletions(-)

diff --git a/content/docs/guides/objectql-migration.mdx b/content/docs/guides/objectql-migration.mdx
index 4f7dc153..94eee11e 100644
--- a/content/docs/guides/objectql-migration.mdx
+++ b/content/docs/guides/objectql-migration.mdx
@@ -26,7 +26,7 @@ All core functionality previously provided by `@objectql/core` is now available
     "dependencies": {
 -     "@objectql/core": "^4.x",
 -     "@objectql/types": "^4.x",
-+     "@objectstack/objectql": "^3.1.0"
++     "@objectstack/objectql": "^3.0.4"
     }
   }
 ```
@@ -91,7 +91,7 @@ import { createObjectQLKernel } from '@objectstack/objectql';
 const kernel = await createObjectQLKernel({
   plugins: [myDriverPlugin],
 });
-await kernel.bootstrap();
+await kernel.start();
 ```
 
 ### MetadataRegistry → MetadataFacade
diff --git a/packages/foundation/core/src/index.ts b/packages/foundation/core/src/index.ts
index 1afe14bb..bddc2fec 100644
--- a/packages/foundation/core/src/index.ts
+++ b/packages/foundation/core/src/index.ts
@@ -13,15 +13,17 @@
 /** @deprecated Import ObjectQL from `@objectstack/objectql` instead. This bridge class will be removed in a future version. */
 export { ObjectQL, type ObjectQLConfig } from './app';
 
+// ── Convenience factory (local implementation — wraps upstream kernel) ──
+export { createObjectQLKernel } from './kernel-factory';
+export type { ObjectQLKernelOptions } from './kernel-factory';
+
 // ── Re-exports from @objectstack/objectql (deprecated — import directly from upstream) ──
 /** @deprecated Import from `@objectstack/objectql` instead. */
 export { ObjectRepository, ScopedContext, SchemaRegistry } from '@objectstack/objectql';
 /** @deprecated Import from `@objectstack/objectql` instead. */
-export { createObjectQLKernel } from '@objectstack/objectql';
-/** @deprecated Import from `@objectstack/objectql` instead. */
 export { toTitleCase, convertIntrospectedSchemaToObjects } from '@objectstack/objectql';
 /** @deprecated Import from `@objectstack/objectql` instead. */
-export type { ObjectQLKernelOptions, HookHandler, HookEntry, OperationContext, EngineMiddleware, ObjectQLHostContext } from '@objectstack/objectql';
+export type { HookHandler, HookEntry, OperationContext, EngineMiddleware, ObjectQLHostContext } from '@objectstack/objectql';
 
 // ── Plugin orchestration (downstream — stays in @objectql ecosystem) ──
 export * from './plugin';