docs: update README, authentication guide, and ROADMAP for sys_ prefix adaptation

- Update plugin-auth README.md with sys_ prefixed object names and adapter mapping docs
- Update authentication.mdx guide with protocol name mapping explanation
- Update ROADMAP.md migration notes for better-auth adapter

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

ROADMAP.md

@@ -162,6 +162,7 @@ business/custom objects, aligning with industry best practices (e.g., ServiceNow
 
 **Migration (v3.x → v4.0):**
 - v3.x: The `SystemObjectName` constants now emit `sys_`-prefixed names. Implementations using `StorageNameMapping.resolveTableName()` can set `tableName` to preserve legacy physical table names during the transition.
+- v3.x: The `@objectstack/plugin-auth` ObjectQL adapter now includes `AUTH_MODEL_TO_PROTOCOL` mapping to translate better-auth's hardcoded model names (`user`, `session`, `account`, `verification`) to protocol names (`sys_user`, `sys_session`, `sys_account`, `sys_verification`). Custom adapters must adopt the same mapping.
 - v4.0: Legacy un-prefixed aliases will be fully removed.
 
 ---
@@ -364,7 +365,7 @@ business/custom objects, aligning with industry best practices (e.g., ServiceNow
   - [ ] **Phase A: Core Driver** (v3.1) — `IDataDriver` + `ISchemaDriver` implementation, QueryAST→SQL compiler, plugin wrapper
   - [ ] **Phase B: Edge & Sync** (v3.2) — Embedded replica sync, WASM build for Cloudflare/Deno, offline write queue
   - [ ] **Phase C: Multi-Tenancy** (v3.3) — Database-per-tenant router, Turso Platform API integration
-  - [ ] **Phase D: Advanced** (v4.0) — Vector search + `IAIService`, FTS5 + `ISearchService`, better-auth adapter
+  - [ ] **Phase D: Advanced** (v4.0) — Vector search + `IAIService`, FTS5 + `ISearchService`, ~~better-auth adapter~~ (✅ done in plugin-auth)
 - [ ] Driver benchmark suite comparing performance across all drivers
 
 ### 6.2 Multi-Tenancy

content/docs/guides/authentication.mdx

@@ -111,11 +111,15 @@ That's it! Your authentication endpoints are now available at `/api/v1/auth/*`.
 
 The plugin automatically uses ObjectQL for data persistence. No additional database configuration is required - it works with your existing ObjectQL setup.
 
-The plugin creates the following auth objects:
-- `user` - User accounts
-- `session` - Active sessions
-- `account` - OAuth provider accounts
-- `verification` - Email/phone verification tokens
+The plugin creates the following auth objects (using ObjectStack `sys_` protocol names):
+- `sys_user` - User accounts (mapped from better-auth's `user` model)
+- `sys_session` - Active sessions (mapped from better-auth's `session` model)
+- `sys_account` - OAuth provider accounts (mapped from better-auth's `account` model)
+- `sys_verification` - Email/phone verification tokens (mapped from better-auth's `verification` model)
+
+> **Note:** better-auth uses hardcoded model names (`user`, `session`, etc.). The ObjectQL adapter
+> automatically maps these to `sys_`-prefixed protocol names via `AUTH_MODEL_TO_PROTOCOL`.
+> Client-side API routes (`/api/v1/auth/*`) are **not affected** — they do not expose object names.
 
 ---
 
@@ -569,12 +573,16 @@ try {
 
 ### ObjectStack Field Naming
 
-The plugin uses ObjectStack's snake_case naming convention for field names, which is required by the ObjectStack protocol:
+The plugin uses ObjectStack's `sys_` prefix convention for protocol object names and snake_case for field names, which is required by the ObjectStack protocol:
 
-- Table names: `user`, `session`, `account`, `verification` (compatible with better-auth)
+- Object names: `sys_user`, `sys_session`, `sys_account`, `sys_verification` (protocol names)
 - Field names: `email_verified`, `created_at`, `user_id` (snake_case)
 
-The ObjectQL adapter automatically handles field name transformation between better-auth's expectations and ObjectStack's snake_case convention, providing seamless integration while maintaining protocol compliance.
+better-auth internally uses model names like `user` and `session`. The ObjectQL adapter (`AUTH_MODEL_TO_PROTOCOL` mapping) automatically translates these to `sys_`-prefixed protocol names, providing seamless integration.
+
+> **Upgrade note:** If you have custom adapters or plugins that reference auth objects by name,
+> update them to use `sys_user`, `sys_session`, `sys_account`, `sys_verification`
+> (or import from `SystemObjectName` constants).
 
 ---
 

packages/plugins/plugin-auth/README.md

@@ -34,10 +34,10 @@ Authentication & Identity Plugin for ObjectStack.
 - ✅ **No Third-Party ORM** - No dependency on drizzle-orm or other ORMs
 - ✅ **Better-Auth Native Schema** - Uses better-auth's naming conventions for seamless migration
 - ✅ **Object Definitions** - Auth objects defined using ObjectStack's Object Protocol
-  - `user` - User accounts (better-auth native table name)
-  - `session` - Active sessions (better-auth native table name)
-  - `account` - OAuth provider accounts (better-auth native table name)
-  - `verification` - Email/phone verification tokens (better-auth native table name)
+  - `sys_user` - User accounts (protocol name, mapped from better-auth's `user`)
+  - `sys_session` - Active sessions (protocol name, mapped from better-auth's `session`)
+  - `sys_account` - OAuth provider accounts (protocol name, mapped from better-auth's `account`)
+  - `sys_verification` - Email/phone verification tokens (protocol name, mapped from better-auth's `verification`)
 - ✅ **ObjectQL Adapter** - Custom adapter bridges better-auth to ObjectQL
 
 The plugin uses [better-auth](https://www.better-auth.com/) for robust, production-ready authentication functionality. All requests are forwarded directly to better-auth's universal handler, ensuring full compatibility with all better-auth features. Data persistence is handled by ObjectQL using **ObjectStack's snake_case naming conventions** for field names to maintain consistency across the platform.
@@ -187,7 +187,7 @@ The plugin uses **ObjectQL** for data persistence instead of third-party ORMs:
 ```typescript
 // Object definitions use ObjectStack's snake_case naming conventions
 export const AuthUser = ObjectSchema.create({
-  name: 'user',  // better-auth compatible table name
+  name: 'sys_user',  // ObjectStack protocol name (better-auth model 'user' is mapped automatically)
   fields: {
     id: Field.text({ label: 'User ID', required: true }),
     email: Field.email({ label: 'Email', required: true }),
@@ -213,19 +213,25 @@ export const AuthUser = ObjectSchema.create({
 - ✅ **Compatible Schema** - Uses better-auth compatible table structure with ObjectStack's snake_case field naming
 
 **Database Objects:**
-Uses better-auth compatible table names with ObjectStack's snake_case field naming:
-- `user` - User accounts (id, email, name, email_verified, created_at, etc.)
-- `session` - Active sessions (id, token, user_id, expires_at, ip_address, etc.)
-- `account` - OAuth provider accounts (id, provider_id, account_id, user_id, tokens, etc.)
-- `verification` - Verification tokens (id, value, identifier, expires_at, etc.)
+Uses ObjectStack `sys_` prefixed protocol names with snake_case field naming.
+The adapter automatically maps better-auth model names to protocol names:
+- `sys_user` (← better-auth `user`) - User accounts (id, email, name, email_verified, created_at, etc.)
+- `sys_session` (← better-auth `session`) - Active sessions (id, token, user_id, expires_at, ip_address, etc.)
+- `sys_account` (← better-auth `account`) - OAuth provider accounts (id, provider_id, account_id, user_id, tokens, etc.)
+- `sys_verification` (← better-auth `verification`) - Verification tokens (id, value, identifier, expires_at, etc.)
 
 **Adapter:**
-The `createObjectQLAdapter()` function bridges better-auth's database interface to ObjectQL's IDataEngine with field name transformation:
+The `createObjectQLAdapter()` function bridges better-auth's database interface to ObjectQL's IDataEngine. It includes a model→protocol name mapping (`AUTH_MODEL_TO_PROTOCOL`) that translates better-auth's hardcoded model names (e.g. `user`) to ObjectStack protocol names (e.g. `sys_user`):
 
 ```typescript
-// Better-auth → ObjectQL Adapter (handles snake_case transformation)
+// Better-auth → ObjectQL Adapter (handles model name mapping + field transformation)
+import { createObjectQLAdapter, AUTH_MODEL_TO_PROTOCOL } from '@objectstack/plugin-auth';
+
 const adapter = createObjectQLAdapter(dataEngine);
 
+// Mapping: { user: 'sys_user', session: 'sys_session', account: 'sys_account', verification: 'sys_verification' }
+console.log(AUTH_MODEL_TO_PROTOCOL);
+
 // Better-auth uses this adapter for all database operations
 const auth = betterAuth({
   database: adapter,