feat(docs): Add "AI Development Context" sections to documentation for better understanding of package roles and usage

Author: hotlong

content/docs/developers/ai-development-guide.mdx

@@ -31,6 +31,12 @@ This guide enables AI agents to build production-grade enterprise applications (
 3. **Convention over Configuration**: Follow file suffix system
 4. **Progressive Development**: From simple to complex, iterative layers
 
+### 🤖 AI Context Awareness
+To better understand the codebase, every package now includes an **"AI Development Context"** section in its `README.md`. Agents should consult this section to understand:
+- The package's specific role (Source of Truth vs. Runtime vs. Tooling)
+- Implicit rules (e.g., "No business logic here")
+- Architecture relationships
+
 ## Quick Start
 
 ### Environment Setup

content/docs/developers/micro-kernel.mdx

@@ -135,6 +135,14 @@ The context provides access to kernel services and hooks.
 interface PluginContext {
   // Service Registry
   registerService(name: string, service: any): void;
+  // Factory registration with lifecycle control
+  registerServiceFactory(options: {
+    name: string;
+    factory: (ctx: PluginContext) => T;
+    lifecycle: 'singleton' | 'transient' | 'scoped';
+    dependencies?: string[];
+  }): void;
+  
   getService<T>(name: string): T;
   getServices(): Map<string, any>;
 
@@ -150,15 +158,41 @@ interface PluginContext {
 }
 ```
 
-**Logger Methods:**
+## 🚀 Enhanced Capabilities
+
+The ObjectKernel provides advanced runtime features to ensure stability and developer experience.
+
+### 1. Advanced Dependency Injection
+Beyond simple static services, the Kernel supports sophisticated lifecycles:
+
+- **Singleton**: Created once, shared forever. (Default)
+- **Transient**: Created every time it is requested.
+- **Scoped**: Created once per specific scope (e.g., HTTP Request).
+
 ```typescript
-logger.debug(message, metadata?)  // Development/troubleshooting
-logger.info(message, metadata?)   // General information
-logger.warn(message, metadata?)   // Warnings
-logger.error(message, metadata?)  // Errors
-logger.fatal(message, metadata?)  // Fatal errors
+ctx.registerServiceFactory({
+  name: 'my-service',
+  lifecycle: 'singleton',
+  factory: (context) => new MyService(context)
+});
 ```
 
+### 2. Runtime Circular Dependency Detection
+The Kernel protects against infinite recursion. If your plugins create a loop (Service A -> Service B -> Service A), the Kernel detects this at runtime and throws a clear error path instead of crashing the stack.
+
+### 3. Configuration Validation
+Plugins can define a Zod schema for their configuration. The Kernel automatically validates the config on load.
+
+```typescript
+const MyPlugin = {
+  configSchema: z.object({ apiKey: z.string() }),
+  init(ctx) { /* ... */ }
+}
+```
+
+### 4. Reliable Error Handling
+Factory errors (e.g., database connection failure during init) are propagated correctly up the stack, preserving the original error message for easier debugging.
+
 ## Built-in Plugins
 
 ### ObjectQLPlugin

content/docs/developers/writing-plugins.mdx

@@ -154,58 +154,35 @@ import { startSyncJob } from './jobs/sync';
 const myPlugin: Plugin = {
   name: 'my-crm-plugin',
   version: '1.0.0',
+  dependencies: ['com.objectstack.engine.objectql'],
 
   /**
-   * Called when the plugin is enabled.
-   * Register objects, routes, jobs, and event listeners here.
+   * Init Phase: Register services.
    */
-  init: async (context) => {
-    // context comes from @objectstack/core
+  init: (context) => {
+    // context.logger.info('Init...');
+  },
+
+  /**
+   * Start Phase: Business Logic.
+   */
+  start: async (context) => {
     const { logger } = context;
-    
     logger.info('My CRM Plugin enabled');
 
-    /* 
-       Note: Accessing services like 'ql' or 'router' depends on 
-       what plugins are installed in the kernel.
-       const ql = context.getService('objectql');
-    */
-  },
-    
-    // Register custom objects
-    await ql.registerObject(Account);
+    // Get dependencies
+    // const ql = context.getService('objectql');
 
-    // Register API routes
-    registerWebhooks(router);
-    
-    // Schedule background jobs
-    const interval = await os.getConfig('my_crm_plugin.syncInterval');
-    scheduler.schedule('sync-accounts', `*/${interval} * * * *`, () => {
-      return startSyncJob(context);
-    });
-    
-    // Listen to events
-    ql.on('account.created', async (event) => {
-      logger.info('New account created', { id: event.record.id });
-      await storage.set(`last_account_id`, event.record.id);
-    });
-  },
-  
-  /**
-   * Called when the plugin is disabled.
-   * Clean up resources here.
-   */
-  onDisable: async (context: PluginContext) => {
-    context.logger.info('My CRM Plugin disabled');
-    // Unregister listeners, close connections, etc.
+    // Logic here
+    // await ql.registerObject(Account);
   },
 
   /**
-   * Called when plugin settings are updated.
+   * Destroy Phase: Cleanup.
    */
-  onSettingsChange: async (context: PluginContext, oldSettings, newSettings) => {
-    context.logger.info('Settings updated', { oldSettings, newSettings });
-  },
+  destroy: async () => {
+    console.log('Plugin stopped');
+  }
 };
 ```
 

content/docs/references/packages.mdx

@@ -7,6 +7,8 @@ description: Complete reference of all ObjectStack packages in the monorepo
 
 ObjectStack is distributed as a monorepo containing **10 packages** organized into core packages and plugins.
 
+> **Note for AI Agents**: Each package's `README.md` contains a specific "AI Development Context" section describing its architectural role and usage rules.
+
 ## Package Overview
 
 | Category | Count | Description |