qdadm 0.32.0 → 0.34.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qdadm",
-  "version": "0.32.0",
+  "version": "0.34.0",
   "description": "Vue 3 framework for admin dashboards with PrimeVue",
   "author": "quazardous",
   "license": "MIT",
@@ -20,6 +20,7 @@
   },
   "exports": {
     ".": "./src/index.js",
+    "./auth": "./src/auth/index.js",
     "./composables": "./src/composables/index.js",
     "./components": "./src/components/index.js",
     "./editors": "./src/editors/index.js",

package/src/auth/SessionAuthAdapter.js

@@ -0,0 +1,254 @@
+/**
+ * SessionAuthAdapter - Base class for user authentication
+ *
+ * Applications extend this class to implement their authentication logic.
+ * The adapter handles user sessions: login, logout, token management.
+ *
+ * This is different from EntityAuthAdapter which handles entity-level permissions.
+ *
+ * @example
+ * ```js
+ * class MyAuthAdapter extends SessionAuthAdapter {
+ *   async login({ username, password }) {
+ *     const response = await api.post('/auth/login', { username, password })
+ *     this.setSession(response.token, response.user)
+ *     return { token: response.token, user: response.user }
+ *   }
+ *
+ *   logout() {
+ *     this.clearSession()
+ *   }
+ * }
+ * ```
+ *
+ * @abstract
+ */
+export class SessionAuthAdapter {
+  /**
+   * Internal session state
+   * @protected
+   */
+  _token = null
+  _user = null
+
+  /**
+   * Authenticate user with credentials
+   *
+   * @param {object} credentials - Login credentials
+   * @param {string} credentials.username - Username or email
+   * @param {string} credentials.password - Password
+   * @returns {Promise<{token: string, user: object}>} Session data
+   * @throws {Error} If authentication fails
+   *
+   * @example
+   * const { token, user } = await adapter.login({ username: 'admin', password: 'secret' })
+   */
+  async login(credentials) {
+    throw new Error('[SessionAuthAdapter] login() must be implemented by subclass')
+  }
+
+  /**
+   * End the current session
+   *
+   * Should clear all session data (tokens, user info).
+   * Called by AppLayout logout button and useAuth().logout()
+   */
+  logout() {
+    throw new Error('[SessionAuthAdapter] logout() must be implemented by subclass')
+  }
+
+  /**
+   * Check if user is currently authenticated
+   *
+   * @returns {boolean} True if user has valid session
+   *
+   * @example
+   * if (adapter.isAuthenticated()) {
+   *   // Show dashboard
+   * } else {
+   *   // Redirect to login
+   * }
+   */
+  isAuthenticated() {
+    throw new Error('[SessionAuthAdapter] isAuthenticated() must be implemented by subclass')
+  }
+
+  /**
+   * Get the current authentication token
+   *
+   * Used by API clients to include in request headers.
+   *
+   * @returns {string|null} JWT token or null if not authenticated
+   *
+   * @example
+   * const token = adapter.getToken()
+   * fetch('/api/data', {
+   *   headers: { Authorization: `Bearer ${token}` }
+   * })
+   */
+  getToken() {
+    throw new Error('[SessionAuthAdapter] getToken() must be implemented by subclass')
+  }
+
+  /**
+   * Get the current user object
+   *
+   * Returns user data from the session. The shape depends on your backend.
+   *
+   * @returns {object|null} User object or null if not authenticated
+   *
+   * @example
+   * const user = adapter.getUser()
+   * console.log(user.username, user.email, user.roles)
+   */
+  getUser() {
+    throw new Error('[SessionAuthAdapter] getUser() must be implemented by subclass')
+  }
+
+  /**
+   * Synchronous user getter (optional)
+   *
+   * Some implementations prefer a property instead of method.
+   * useAuth() supports both patterns.
+   *
+   * @type {object|null}
+   */
+  get user() {
+    return this.getUser()
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Helper methods for subclasses
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Set session data (helper for subclasses)
+   *
+   * @param {string} token - Authentication token
+   * @param {object} user - User object
+   * @protected
+   */
+  setSession(token, user) {
+    this._token = token
+    this._user = user
+  }
+
+  /**
+   * Clear session data (helper for subclasses)
+   *
+   * @protected
+   */
+  clearSession() {
+    this._token = null
+    this._user = null
+  }
+
+  /**
+   * Validate that the adapter is properly configured
+   *
+   * Called during bootstrap to catch configuration errors early.
+   *
+   * @throws {Error} If required methods are not implemented
+   */
+  static validate(adapter) {
+    const required = ['login', 'logout', 'isAuthenticated', 'getToken', 'getUser']
+    const missing = required.filter(method => typeof adapter[method] !== 'function')
+
+    if (missing.length > 0) {
+      throw new Error(
+        `[SessionAuthAdapter] Missing required methods: ${missing.join(', ')}\n` +
+        'Ensure your authAdapter implements all required methods or extends SessionAuthAdapter.'
+      )
+    }
+  }
+}
+
+/**
+ * LocalStorage-based SessionAuthAdapter implementation
+ *
+ * Ready-to-use adapter that stores session in localStorage.
+ * Extend and override login() to add your API call.
+ *
+ * @example
+ * ```js
+ * class MyAuthAdapter extends LocalStorageSessionAuthAdapter {
+ *   constructor() {
+ *     super('my_app_auth') // localStorage key
+ *   }
+ *
+ *   async login({ username, password }) {
+ *     const res = await fetch('/api/login', {
+ *       method: 'POST',
+ *       body: JSON.stringify({ username, password })
+ *     })
+ *     const data = await res.json()
+ *     this.setSession(data.token, data.user)
+ *     this.persist()
+ *     return data
+ *   }
+ * }
+ * ```
+ */
+export class LocalStorageSessionAuthAdapter extends SessionAuthAdapter {
+  /**
+   * @param {string} storageKey - localStorage key for session data
+   */
+  constructor(storageKey = 'qdadm_auth') {
+    super()
+    this._storageKey = storageKey
+    this._restore()
+  }
+
+  /**
+   * Restore session from localStorage on init
+   * @private
+   */
+  _restore() {
+    try {
+      const stored = localStorage.getItem(this._storageKey)
+      if (stored) {
+        const { token, user } = JSON.parse(stored)
+        this._token = token
+        this._user = user
+      }
+    } catch {
+      // Invalid stored data, ignore
+    }
+  }
+
+  /**
+   * Persist session to localStorage
+   * Call after login() to save session
+   * @protected
+   */
+  persist() {
+    if (this._token && this._user) {
+      localStorage.setItem(this._storageKey, JSON.stringify({
+        token: this._token,
+        user: this._user
+      }))
+    } else {
+      localStorage.removeItem(this._storageKey)
+    }
+  }
+
+  // Arrow functions to preserve `this` when used as callbacks
+  logout = () => {
+    this.clearSession()
+    localStorage.removeItem(this._storageKey)
+  }
+
+  isAuthenticated = () => {
+    return !!this._token
+  }
+
+  getToken = () => {
+    return this._token
+  }
+
+  getUser = () => {
+    return this._user
+  }
+}
+
+export default SessionAuthAdapter

package/src/auth/index.js

@@ -0,0 +1,10 @@
+/**
+ * Auth module - User session authentication
+ *
+ * For entity-level permissions, see entity/auth/EntityAuthAdapter
+ */
+
+export {
+  SessionAuthAdapter,
+  LocalStorageSessionAuthAdapter,
+} from './SessionAuthAdapter.js'

package/src/components/layout/AppLayout.vue

@@ -35,6 +35,7 @@ const route = useRoute()
 const app = useApp()
 const { navSections, isNavActive, sectionHasActiveItem, handleNavClick } = useNavigation()
 const { isAuthenticated, user, logout, authEnabled } = useAuth()
+const signals = inject('qdadmSignals', null)
 
 // LocalStorage key for collapsed sections state (namespaced by app)
 const STORAGE_KEY = computed(() => `${app.shortName.toLowerCase()}_nav_collapsed`)
@@ -150,6 +151,7 @@ const userSubtitle = computed(() => {
 
 function handleLogout() {
   logout()
+  signals?.emit('auth:logout', { reason: 'user' })
   router.push({ name: 'login' })
 }
 

package/src/components/pages/LoginPage.vue

@@ -90,11 +90,12 @@ const props = defineProps({
     default: ''
   },
   /**
-   * Emit business signal on login (requires orchestrator)
+   * Emit auth:login signal on successful login
+   * Required for debug bar auth tracking and other signal listeners
    */
   emitSignal: {
     type: Boolean,
-    default: false
+    default: true
   }
 })
 

package/src/composables/useFormPageBuilder.js

@@ -120,7 +120,13 @@ export function useFormPageBuilder(config = {}) {
   // Get EntityManager via orchestrator
   const orchestrator = inject('qdadmOrchestrator')
   if (!orchestrator) {
-    throw new Error('[qdadm] Orchestrator not provided. Make sure to use createQdadm() with entityFactory.')
+    throw new Error(
+      '[qdadm] Orchestrator not provided.\n' +
+      'Possible causes:\n' +
+      '1. Kernel not initialized - ensure createKernel().createApp() is called before mounting\n' +
+      '2. Component used outside of qdadm app context\n' +
+      '3. Missing entityFactory in Kernel options'
+    )
   }
   const manager = orchestrator.get(entity)
 

package/src/composables/useListPageBuilder.js

@@ -143,7 +143,13 @@ export function useListPageBuilder(config = {}) {
   // Get EntityManager via orchestrator
   const orchestrator = inject('qdadmOrchestrator')
   if (!orchestrator) {
-    throw new Error('[qdadm] Orchestrator not provided. Make sure to use createQdadm() with entityFactory.')
+    throw new Error(
+      '[qdadm] Orchestrator not provided.\n' +
+      'Possible causes:\n' +
+      '1. Kernel not initialized - ensure createKernel().createApp() is called before mounting\n' +
+      '2. Component used outside of qdadm app context\n' +
+      '3. Missing entityFactory in Kernel options'
+    )
   }
   const manager = orchestrator.get(entity)
 

package/src/debug/Collector.js

@@ -179,10 +179,11 @@ export class Collector {
 
   /**
    * Get all entries
+   * Returns a shallow copy to trigger Vue reactivity when used in computed
    * @returns {Array<object>} All recorded entries
    */
   getEntries() {
-    return this.entries
+    return [...this.entries]
   }
 
   /**

package/src/entity/EntityManager.js

@@ -1,5 +1,5 @@
 import { PermissiveAuthAdapter } from './auth/PermissiveAdapter.js'
-import { AuthActions } from './auth/AuthAdapter.js'
+import { AuthActions } from './auth/EntityAuthAdapter.js'
 import { QueryExecutor } from '../query/QueryExecutor.js'
 
 /**

package/src/entity/auth/CompositeAuthAdapter.js

@@ -26,10 +26,10 @@
  * ```
  */
 
-import { AuthAdapter } from './AuthAdapter.js'
+import { EntityAuthAdapter } from './EntityAuthAdapter.js'
 import { authFactory } from './factory.js'
 
-export class CompositeAuthAdapter extends AuthAdapter {
+export class CompositeAuthAdapter extends EntityAuthAdapter {
   /**
    * @param {object} config - Composite auth configuration
    * @param {AuthAdapter|string|object} config.default - Default adapter (required)

package/src/entity/auth/{AuthAdapter.js → EntityAuthAdapter.js}

@@ -1,7 +1,7 @@
 /**
- * AuthAdapter - Interface for scope and silo permission checks
+ * EntityAuthAdapter - Interface for entity-level permission checks
  *
- * Applications implement this interface to plug their authentication/authorization
+ * Applications implement this interface to plug their authorization
  * system into qdadm's EntityManager. The adapter provides two levels of permission checks:
  *
  * 1. **Scopes** (action-level): Can the user perform this action on this entity type?
@@ -10,9 +10,11 @@
  * 2. **Silos** (record-level): Can the user access this specific record?
  *    Example: Can user see invoice #123? (ownership, team membership, etc.)
  *
+ * Note: For user session authentication (login/logout), see SessionAuthAdapter.
+ *
  * Usage:
  * ```js
- * class MyAuthAdapter extends AuthAdapter {
+ * class MyEntityAuthAdapter extends EntityAuthAdapter {
  *   canPerform(entity, action) {
  *     const user = this.getCurrentUser()
  *     return user?.permissions?.includes(`${entity}:${action}`)
@@ -20,7 +22,6 @@
  *
  *   canAccessRecord(entity, record) {
  *     const user = this.getCurrentUser()
- *     // Check ownership or team membership
  *     return record.owner_id === user?.id || record.team_id === user?.team_id
  *   }
  *
@@ -32,7 +33,7 @@
  *
  * @interface
  */
-export class AuthAdapter {
+export class EntityAuthAdapter {
   /**
    * SecurityChecker instance for isGranted() delegation
    * @type {import('./SecurityChecker.js').SecurityChecker|null}
@@ -104,14 +105,11 @@ export class AuthAdapter {
    * @returns {boolean} True if user can perform the action on this entity type
    *
    * @example
-   * // Check if user can create invoices
    * adapter.canPerform('invoices', 'create') // true/false
-   *
-   * // Check if user can delete users
    * adapter.canPerform('users', 'delete') // true/false
    */
   canPerform(entity, action) {
-    throw new Error('[AuthAdapter] canPerform() must be implemented by subclass')
+    throw new Error('[EntityAuthAdapter] canPerform() must be implemented by subclass')
   }
 
   /**
@@ -121,52 +119,27 @@ export class AuthAdapter {
    * this determines if the user can access a particular record based on
    * ownership, team membership, or other business rules.
    *
-   * Called during:
-   * - get() operations
-   * - update() / patch() operations
-   * - delete() operations
-   * - list() result filtering (optional)
-   *
    * @param {string} entity - Entity name (e.g., 'users', 'invoices')
    * @param {object} record - The full entity record to check access for
    * @returns {boolean} True if user can access this specific record
    *
    * @example
-   * // Check if user can access a specific invoice
    * adapter.canAccessRecord('invoices', { id: 123, owner_id: 456, ... })
-   *
-   * @example
-   * // Common implementations:
-   * // 1. Ownership: record.owner_id === user.id
-   * // 2. Team: record.team_id === user.team_id
-   * // 3. Role: user.role === 'admin' (admins see all)
-   * // 4. Hierarchical: record.organization_id in user.organizations
    */
   canAccessRecord(entity, record) {
-    throw new Error('[AuthAdapter] canAccessRecord() must be implemented by subclass')
+    throw new Error('[EntityAuthAdapter] canAccessRecord() must be implemented by subclass')
   }
 
   /**
    * Get the current authenticated user
    *
    * Returns the user object or null if not authenticated. The user object
-   * should contain whatever information is needed for permission checks
-   * (id, role, team_id, permissions array, etc.).
+   * should contain whatever information is needed for permission checks.
    *
    * @returns {object|null} Current user object or null if not authenticated
-   *
-   * @example
-   * // Typical user object:
-   * {
-   *   id: 123,
-   *   email: 'user@example.com',
-   *   role: 'manager',
-   *   team_id: 456,
-   *   permissions: ['invoices:create', 'invoices:read', 'users:read']
-   * }
    */
   getCurrentUser() {
-    throw new Error('[AuthAdapter] getCurrentUser() must be implemented by subclass')
+    throw new Error('[EntityAuthAdapter] getCurrentUser() must be implemented by subclass')
   }
 }
 

package/src/entity/auth/PermissiveAdapter.js

@@ -1,7 +1,7 @@
 /**
  * PermissiveAuthAdapter - Default adapter that allows all operations
  *
- * This adapter is used when no custom AuthAdapter is provided to EntityManager.
+ * This adapter is used when no custom EntityAuthAdapter is provided to EntityManager.
  * It returns `true` for all permission checks, effectively disabling authorization.
  *
  * Use cases:
@@ -11,18 +11,16 @@
  * - Testing environments
  *
  * @example
- * // Explicit usage (rarely needed)
  * const adapter = new PermissiveAuthAdapter()
- *
  * adapter.canPerform('users', 'delete') // true
  * adapter.canAccessRecord('invoices', { id: 123, secret: true }) // true
  * adapter.getCurrentUser() // null
  *
- * @extends AuthAdapter
+ * @extends EntityAuthAdapter
  */
-import { AuthAdapter } from './AuthAdapter.js'
+import { EntityAuthAdapter } from './EntityAuthAdapter.js'
 
-export class PermissiveAuthAdapter extends AuthAdapter {
+export class PermissiveAuthAdapter extends EntityAuthAdapter {
   /**
    * Always allows any action on any entity type
    *

package/src/entity/auth/factory.js

@@ -27,13 +27,13 @@
  * ```
  */
 
-import { AuthAdapter } from './AuthAdapter.js'
+import { EntityAuthAdapter } from './EntityAuthAdapter.js'
 import { PermissiveAuthAdapter } from './PermissiveAdapter.js'
 
 /**
  * Built-in auth adapter types
  * Extended via context.authTypes for custom adapters
- * @type {Record<string, typeof AuthAdapter>}
+ * @type {Record<string, typeof EntityAuthAdapter>}
  */
 export const authTypes = {
   permissive: PermissiveAuthAdapter
@@ -65,7 +65,7 @@ export function parseAuthPattern(pattern) {
  *
  * @param {object} config - Normalized auth config with `type` property
  * @param {object} context - Context with authTypes registry
- * @returns {AuthAdapter} Adapter instance
+ * @returns {EntityAuthAdapter} Adapter instance
  */
 export function defaultAuthResolver(config, context = {}) {
   const { type, ...rest } = config
@@ -109,9 +109,9 @@ function isCompositeConfig(config) {
  * - Config object with 'type' → resolve via registry
  * - Config object with 'default' → create CompositeAuthAdapter
  *
- * @param {AuthAdapter | string | object} config - Auth config
+ * @param {EntityAuthAdapter | string | object} config - Auth config
  * @param {object} [context={}] - Context with authTypes, authResolver
- * @returns {AuthAdapter} Adapter instance
+ * @returns {EntityAuthAdapter} Adapter instance
  *
  * @example
  * // Instance passthrough (most common, backward compatible)
@@ -138,8 +138,8 @@ export function authFactory(config, context = {}) {
     return new PermissiveAuthAdapter()
   }
 
-  // Already an AuthAdapter instance → return directly (backward compatible)
-  if (config instanceof AuthAdapter) {
+  // Already an EntityAuthAdapter instance → return directly (backward compatible)
+  if (config instanceof EntityAuthAdapter) {
     return config
   }
 

package/src/entity/auth/factory.test.js

@@ -2,13 +2,13 @@
  * Tests for auth factory and CompositeAuthAdapter
  */
 import { describe, it, expect } from 'vitest'
-import { AuthAdapter } from './AuthAdapter.js'
+import { EntityAuthAdapter } from './EntityAuthAdapter.js'
 import { PermissiveAuthAdapter } from './PermissiveAdapter.js'
 import { CompositeAuthAdapter } from './CompositeAuthAdapter.js'
 import { authFactory, parseAuthPattern, authTypes } from './factory.js'
 
 // Test adapter for custom types
-class TestAuthAdapter extends AuthAdapter {
+class TestAuthAdapter extends EntityAuthAdapter {
   constructor(options = {}) {
     super()
     this.options = options
@@ -19,7 +19,7 @@ class TestAuthAdapter extends AuthAdapter {
 }
 
 // Adapter that tracks which entity was checked
-class TrackingAdapter extends AuthAdapter {
+class TrackingAdapter extends EntityAuthAdapter {
   constructor(name) {
     super()
     this.name = name
@@ -53,7 +53,7 @@ describe('parseAuthPattern', () => {
 
 describe('authFactory', () => {
   describe('instance passthrough', () => {
-    it('returns AuthAdapter instance as-is', () => {
+    it('returns EntityAuthAdapter instance as-is', () => {
       const adapter = new PermissiveAuthAdapter()
       const result = authFactory(adapter)
       expect(result).toBe(adapter)

package/src/entity/auth/index.js

@@ -10,7 +10,7 @@
  */
 
 // Interface
-export { AuthAdapter, AuthActions } from './AuthAdapter.js'
+export { EntityAuthAdapter, AuthActions } from './EntityAuthAdapter.js'
 
 // Role Hierarchy (topological resolution)
 export { RoleHierarchy, createRoleHierarchy } from './RoleHierarchy.js'

package/src/index.js

@@ -17,6 +17,9 @@ export { createQdadm } from './plugin.js'
 // Entity system
 export * from './entity/index.js'
 
+// Session auth (user authentication)
+export * from './auth/index.js'
+
 // Orchestrator
 export * from './orchestrator/index.js'
 

package/src/kernel/Kernel.js

@@ -184,21 +184,21 @@ export class Kernel {
     this._createHookRegistry()
     this._createZoneRegistry()
     this._createDeferredRegistry()
-    // 2. Register auth:ready deferred (if auth configured)
+    // 2. Create orchestrator early (modules need it for ctx.entity())
+    this._createOrchestrator()
+    // 3. Register auth:ready deferred (if auth configured)
     this._registerAuthDeferred()
-    // 3. Initialize legacy modules (can use all services, registers routes)
+    // 4. Initialize legacy modules (can use all services, registers routes)
     this._initModules()
-    // 3.5. Load new-style modules (moduleDefs) - synchronous for backward compat
+    // 4.5. Load new-style modules (moduleDefs) - synchronous for backward compat
     this._loadModulesSync()
-    // 4. Create router (needs routes from modules)
+    // 5. Create router (needs routes from modules)
     this._createRouter()
-    // 4.5. Setup auth guard (if authAdapter provided)
+    // 5.5. Setup auth guard (if authAdapter provided)
     this._setupAuthGuard()
-    // 5. Setup auth:expired handler (needs router + authAdapter)
+    // 6. Setup auth:expired handler (needs router + authAdapter)
     this._setupAuthExpiredHandler()
-    // 6. Create orchestrator and remaining components
-    this._createOrchestrator()
-    // 7. Wire modules that need orchestrator (phase 2)
+    // 7. Wire modules that need orchestrator (phase 2 - kernel:ready signal)
     this._wireModules()
     // 8. Create EventRouter (needs signals + orchestrator)
     this._createEventRouter()
@@ -229,21 +229,21 @@ export class Kernel {
     this._createHookRegistry()
     this._createZoneRegistry()
     this._createDeferredRegistry()
-    // 2. Register auth:ready deferred (if auth configured)
+    // 2. Create orchestrator early (modules need it for ctx.entity())
+    this._createOrchestrator()
+    // 3. Register auth:ready deferred (if auth configured)
     this._registerAuthDeferred()
-    // 3. Initialize legacy modules (can use all services, registers routes)
+    // 4. Initialize legacy modules (can use all services, registers routes)
     this._initModules()
-    // 3.5. Load new-style modules (moduleDefs) - async version
+    // 4.5. Load new-style modules (moduleDefs) - async version
     await this._loadModules()
-    // 4. Create router (needs routes from modules)
+    // 5. Create router (needs routes from modules)
     this._createRouter()
-    // 4.5. Setup auth guard (if authAdapter provided)
+    // 5.5. Setup auth guard (if authAdapter provided)
     this._setupAuthGuard()
-    // 5. Setup auth:expired handler (needs router + authAdapter)
+    // 6. Setup auth:expired handler (needs router + authAdapter)
     this._setupAuthExpiredHandler()
-    // 6. Create orchestrator and remaining components
-    this._createOrchestrator()
-    // 7. Wire modules that need orchestrator (phase 2)
+    // 7. Wire modules that need orchestrator (phase 2 - kernel:ready signal)
     await this._wireModulesAsync()
     // 8. Create EventRouter (needs signals + orchestrator)
     this._createEventRouter()

package/src/kernel/KernelContext.js

@@ -222,6 +222,148 @@ export class KernelContext {
     return this
   }
 
+  /**
+   * Register standard CRUD routes with naming conventions
+   *
+   * Generates routes following qdadm conventions:
+   * - Entity 'books' → route prefix 'book'
+   * - List: /books → name 'book'
+   * - Create: /books/create → name 'book-create'
+   * - Edit: /books/:id/edit → name 'book-edit'
+   *
+   * Also registers route family and optional nav item.
+   *
+   * @param {string} entity - Entity name (plural, e.g., 'books', 'users')
+   * @param {object} pages - Page components (lazy imports)
+   * @param {Function} pages.list - List page: () => import('./pages/List.vue')
+   * @param {Function} [pages.form] - Single form for create+edit (recommended)
+   * @param {Function} [pages.create] - Separate create page (alternative to form)
+   * @param {Function} [pages.edit] - Separate edit page (alternative to form)
+   * @param {object} [options={}] - Additional options
+   * @param {object} [options.nav] - Navigation config
+   * @param {string} options.nav.section - Nav section (e.g., 'Library')
+   * @param {string} [options.nav.icon] - Icon class (e.g., 'pi pi-book')
+   * @param {string} [options.nav.label] - Display label (default: capitalized entity)
+   * @param {string} [options.routePrefix] - Override route prefix (default: singularized entity)
+   * @returns {this}
+   *
+   * @example
+   * // Minimal - list only (read-only entity)
+   * ctx.crud('countries', { list: () => import('./pages/CountriesList.vue') })
+   *
+   * @example
+   * // Single form pattern (recommended)
+   * ctx.crud('books', {
+   *   list: () => import('./pages/BookList.vue'),
+   *   form: () => import('./pages/BookForm.vue')
+   * }, {
+   *   nav: { section: 'Library', icon: 'pi pi-book' }
+   * })
+   *
+   * @example
+   * // Separate create/edit pages
+   * ctx.crud('users', {
+   *   list: () => import('./pages/UserList.vue'),
+   *   create: () => import('./pages/UserCreate.vue'),
+   *   edit: () => import('./pages/UserEdit.vue')
+   * }, {
+   *   nav: { section: 'Admin', icon: 'pi pi-users', label: 'Users' }
+   * })
+   */
+  crud(entity, pages, options = {}) {
+    // Derive route prefix: 'books' → 'book', 'countries' → 'country'
+    const routePrefix = options.routePrefix || this._singularize(entity)
+
+    // Build routes array
+    const routes = []
+
+    // List route (always required)
+    if (pages.list) {
+      routes.push({
+        path: '',
+        name: routePrefix,
+        component: pages.list,
+        meta: { layout: 'list' }
+      })
+    }
+
+    // Form routes - single form or separate create/edit
+    if (pages.form) {
+      // Single form pattern (recommended)
+      routes.push({
+        path: 'create',
+        name: `${routePrefix}-create`,
+        component: pages.form
+      })
+      routes.push({
+        path: ':id/edit',
+        name: `${routePrefix}-edit`,
+        component: pages.form
+      })
+    } else {
+      // Separate create/edit pages
+      if (pages.create) {
+        routes.push({
+          path: 'create',
+          name: `${routePrefix}-create`,
+          component: pages.create
+        })
+      }
+      if (pages.edit) {
+        routes.push({
+          path: ':id/edit',
+          name: `${routePrefix}-edit`,
+          component: pages.edit
+        })
+      }
+    }
+
+    // Register routes with entity binding
+    this.routes(entity, routes, { entity })
+
+    // Register route family for active state detection
+    this.routeFamily(routePrefix, [`${routePrefix}-`])
+
+    // Register nav item if provided
+    if (options.nav) {
+      const label = options.nav.label || this._capitalize(entity)
+      this.navItem({
+        section: options.nav.section,
+        route: routePrefix,
+        icon: options.nav.icon,
+        label,
+        entity
+      })
+    }
+
+    return this
+  }
+
+  /**
+   * Singularize a plural word (simple English rules)
+   * @param {string} plural - Plural word
+   * @returns {string} Singular form
+   * @private
+   */
+  _singularize(plural) {
+    if (plural.endsWith('ies')) return plural.slice(0, -3) + 'y'
+    if (plural.endsWith('ses') || plural.endsWith('xes') || plural.endsWith('zes')) {
+      return plural.slice(0, -2)
+    }
+    if (plural.endsWith('s') && !plural.endsWith('ss')) return plural.slice(0, -1)
+    return plural
+  }
+
+  /**
+   * Capitalize first letter
+   * @param {string} str - String to capitalize
+   * @returns {string} Capitalized string
+   * @private
+   */
+  _capitalize(str) {
+    return str.charAt(0).toUpperCase() + str.slice(1)
+  }
+
   /**
    * Define a zone for extensible UI composition
    *

package/src/orchestrator/Orchestrator.js

@@ -200,7 +200,27 @@ export class Orchestrator {
       }
     }
 
-    throw new Error(`[Orchestrator] No manager for entity "${name}" and no factory provided`)
+    // Build helpful error message
+    const registered = this.getRegisteredNames()
+    const hint = registered.length > 0
+      ? `\nRegistered entities: ${registered.join(', ')}\n`
+      : '\nNo entities registered yet.\n'
+
+    const suggestion = `
+Possible causes:
+1. Entity "${name}" not declared in any module (ctx.entity('${name}', {...}))
+2. Module not loaded (check moduleDefs in config/modules.js)
+3. Typo in entity name
+
+Example fix in your module:
+  ctx.entity('${name}', {
+    name: '${name}',
+    labelField: 'name',
+    fields: { ... },
+    storage: yourStorage
+  })`
+
+    throw new Error(`[Orchestrator] No manager for entity "${name}"${hint}${suggestion}`)
   }
 
   /**

package/src/orchestrator/useOrchestrator.js

@@ -18,7 +18,13 @@ export function useOrchestrator() {
   const orchestrator = inject('qdadmOrchestrator')
 
   if (!orchestrator) {
-    throw new Error('[qdadm] Orchestrator not provided. Make sure to use createQdadm() with entityFactory.')
+    throw new Error(
+      '[qdadm] Orchestrator not provided.\n' +
+      'Possible causes:\n' +
+      '1. Kernel not initialized - ensure createKernel().createApp() is called before mounting\n' +
+      '2. Component used outside of qdadm app context\n' +
+      '3. Missing entityFactory in Kernel options'
+    )
   }
 
   /**