Fix code review issues in README documentation

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

Author: Copilot

packages/cli/README.md

@@ -122,8 +122,8 @@ objectstack dev @objectstack/core
 ```
 
 **Behavior:**
-- **Single Package Mode**: If `objectstack.config.ts` exists in current directory, delegates to `objectstack serve --dev`
-- **Monorepo Mode**: If in workspace root, runs `pnpm dev` with optional package filter
+- **Single Package Mode**: If `objectstack.config.ts` exists in current directory, delegates to `objectstack serve --dev` to start a development server with hot reload
+- **Monorepo Mode**: If `pnpm-workspace.yaml` exists in current directory (workspace root), executes `pnpm dev` with optional package filter to run development builds across multiple packages in the workspace. The command uses pnpm's workspace filtering to target specific packages or all packages.
 
 ### `objectstack compile`
 

packages/metadata/README.md

@@ -349,14 +349,22 @@ async function versionMetadata() {
 
   const objects = await manager.loadMany('object');
 
+  // Get git user name safely
+  let modifiedBy = 'unknown';
+  try {
+    modifiedBy = execSync('git config user.name', { encoding: 'utf-8' }).trim();
+  } catch (error) {
+    console.warn('Could not get git user name, using "unknown"');
+  }
+  
   // Add version metadata
   const versioned = objects.map(obj => ({
     ...obj,
     metadata: {
       ...obj.metadata,
       version: '2.0.0',
       lastModified: new Date().toISOString(),
-      modifiedBy: execSync('git config user.name').toString().trim()
+      modifiedBy
     }
   }));
 
@@ -368,9 +376,13 @@ async function versionMetadata() {
     });
   }
 
-  // Commit to version control
-  execSync('git add metadata/');
-  execSync('git commit -m "Version bump to 2.0.0"');
+  // Commit to version control (if git is available)
+  try {
+    execSync('git add metadata/', { stdio: 'inherit' });
+    execSync('git commit -m "Version bump to 2.0.0"', { stdio: 'inherit' });
+  } catch (error) {
+    console.warn('Git commit failed, changes are staged but not committed');
+  }
 }
 ```
 

packages/objectql/README.md

@@ -285,11 +285,15 @@ ql.registerHook('beforeInsert', async (ctx) => {
 ql.registerHook('afterInsert', async (ctx) => {
   console.log(`Created ${ctx.object}:`, ctx.result);
 
-  // Trigger events
-  await eventBus.emit('data:created', {
-    object: ctx.object,
-    id: ctx.result.id
-  });
+  // Trigger events - get event bus from kernel or context
+  // Note: eventBus should be injected or accessed from context
+  const eventBus = ctx.getService?.('event-bus');
+  if (eventBus) {
+    await eventBus.emit('data:created', {
+      object: ctx.object,
+      id: ctx.result.id
+    });
+  }
 });
 
 ql.registerHook('beforeUpdate', async (ctx) => {

packages/runtime/README.md

@@ -411,9 +411,10 @@ import { Plugin, PluginContext } from '@objectstack/core';
 
 export class ConnectionPoolPlugin implements Plugin {
   name = 'connection-pool';
+  private pool: any;
 
   async init(ctx: PluginContext) {
-    const pool = {
+    this.pool = {
       connections: new Map(),
 
       getConnection(name: string) {
@@ -431,12 +432,14 @@ export class ConnectionPoolPlugin implements Plugin {
       }
     };
 
-    ctx.registerService('connection-pool', pool);
+    ctx.registerService('connection-pool', this.pool);
   }
 
   async destroy() {
-    const pool = kernel.getService('connection-pool');
-    pool.closeAll();
+    // Use stored reference from init phase
+    if (this.pool) {
+      this.pool.closeAll();
+    }
   }
 }
 ```

packages/spec/README.md

@@ -97,14 +97,31 @@ const app: UI.App = {
 
 ### 🤖 AI-Ready Context
 
-This package includes a `prompts/` directory containing system instructions and architectural context. This is useful for:
+This package includes a `prompts/` directory in the package root containing system instructions and architectural context:
+
+```
+node_modules/@objectstack/spec/prompts/
+├── architecture.md    # System architecture overview
+├── plugin/           # Plugin development guides
+└── development/      # Development workflows
+```
+
+These prompts are useful for:
 1.  **AI Agents**: Creating agents that understand ObjectStack.
 2.  **IDE Context**: Adding `node_modules/@objectstack/spec/prompts/*.md` to your Cursor/Copilot context.
-3.  **LLM Auto-Discovery**: The `llms.txt` file in the root provides a knowledge base for autonomous agents.
+3.  **LLM Auto-Discovery**: The `llms.txt` file in the repository root provides a knowledge base for autonomous agents.
 
 ```typescript
-import context from '@objectstack/spec/prompts/architecture.md?raw'; // If using Vite/bundler
-// Or just read the file from disk
+// If using Vite/bundler with raw import support
+import context from '@objectstack/spec/prompts/architecture.md?raw';
+
+// Or read from disk in Node.js
+import fs from 'fs';
+import path from 'path';
+const context = fs.readFileSync(
+  path.join(process.cwd(), 'node_modules/@objectstack/spec/prompts/architecture.md'),
+  'utf-8'
+);
 ```
 
 #### 1. Namespace Imports from Root