Enhance READMEs with AI quick reference and practical examples

Copilot · hotlong · Copilot · commit 0c7e6e140e4d · 2026-02-03T05:40:00.000Z
Co-authored-by: hotlong &lt;50353452+hotlong@users.noreply.github.com&gt;
diff --git a/packages/client-react/README.md b/packages/client-react/README.md
@@ -268,6 +268,157 @@ const { mutate } = useMutation<Task, Partial<Task>>('todo_task', 'create');
 // mutate expects Partial<Task>
 ```
 
+## Common Patterns
+
+### Master-Detail View
+
+```tsx
+function TaskList() {
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+  
+  const { data: tasks } = useQuery('todo_task', {
+    select: ['id', 'subject'],
+    sort: ['-created_at']
+  });
+  
+  const { data: selectedTask } = useQuery('todo_task', {
+    filters: ['id', '=', selectedId],
+    enabled: !!selectedId // Only fetch when ID is selected
+  });
+  
+  return (
+    <div className="flex">
+      <TaskListPanel tasks={tasks?.value} onSelect={setSelectedId} />
+      <TaskDetail task={selectedTask?.value?.[0]} />
+    </div>
+  );
+}
+```
+
+### Optimistic Updates
+
+```tsx
+function TaskToggle({ taskId, completed }) {
+  const { mutate } = useMutation('todo_task', 'update', {
+    onMutate: async (variables) => {
+      // Optimistically update UI
+      return { previousValue: completed };
+    },
+    onError: (error, variables, context) => {
+      // Revert on error
+      console.error('Update failed, reverting', context.previousValue);
+    },
+    onSuccess: () => {
+      // Refetch to ensure data consistency
+      queryClient.invalidateQueries(['todo_task']);
+    }
+  });
+  
+  return (
+    <Checkbox 
+      checked={completed}
+      onChange={(e) => mutate({ id: taskId, is_completed: e.target.checked })}
+    />
+  );
+}
+```
+
+### Dependent Queries
+
+```tsx
+function ProjectTasks({ projectId }) {
+  // First, get project details
+  const { data: project } = useQuery('project', {
+    filters: ['id', '=', projectId]
+  });
+  
+  // Then, get tasks for this project
+  const { data: tasks } = useQuery('todo_task', {
+    filters: ['project_id', '=', projectId],
+    enabled: !!project // Only fetch when project is loaded
+  });
+  
+  return (
+    <div>
+      <h2>{project?.value?.[0]?.name}</h2>
+      <TaskList tasks={tasks?.value} />
+    </div>
+  );
+}
+```
+
+### Search with Debounce
+
+```tsx
+import { useDeferredValue } from 'react';
+
+function TaskSearch() {
+  const [searchTerm, setSearchTerm] = useState('');
+  const deferredSearch = useDeferredValue(searchTerm);
+  
+  const { data, isLoading } = useQuery('todo_task', {
+    filters: ['subject', 'contains', deferredSearch],
+    enabled: deferredSearch.length >= 3 // Only search with 3+ chars
+  });
+  
+  return (
+    <div>
+      <input 
+        type="text"
+        value={searchTerm}
+        onChange={(e) => setSearchTerm(e.target.value)}
+        placeholder="Search tasks..."
+      />
+      {isLoading && <Spinner />}
+      <TaskList tasks={data?.value} />
+    </div>
+  );
+}
+```
+
+### Form with Validation
+
+```tsx
+function TaskForm() {
+  const { mutate, isLoading, error } = useMutation('todo_task', 'create', {
+    onSuccess: () => {
+      router.push('/tasks');
+    }
+  });
+  
+  const handleSubmit = (e: FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    const formData = new FormData(e.currentTarget);
+    
+    mutate({
+      subject: formData.get('subject'),
+      priority: Number(formData.get('priority')),
+      due_date: formData.get('due_date')
+    });
+  };
+  
+  return (
+    <form onSubmit={handleSubmit}>
+      <input name="subject" required />
+      <input name="priority" type="number" min="1" max="5" />
+      <input name="due_date" type="date" />
+      
+      {error && (
+        <div className="error">
+          {error.code === 'validation_error' 
+            ? 'Please check your input' 
+            : error.message}
+        </div>
+      )}
+      
+      <button type="submit" disabled={isLoading}>
+        {isLoading ? 'Creating...' : 'Create Task'}
+      </button>
+    </form>
+  );
+}
+```
+
 ## License
 
 Apache-2.0
diff --git a/packages/client/README.md b/packages/client/README.md
@@ -157,10 +157,48 @@ try {
 }
 ```
 
-Common error codes:
-- `validation_error`: Input validation failed
-- `unauthenticated`: Authentication required
-- `permission_denied`: Insufficient permissions
-- `resource_not_found`: Resource does not exist
-- `rate_limit_exceeded`: Too many requests
+### Error Code Reference
+
+#### Client Errors (4xx)
+
+| Error Code | HTTP Status | Retryable | Description |
+|------------|-------------|-----------|-------------|
+| `validation_error` | 400 | No | Input validation failed. Check error.details for field-specific errors |
+| `unauthenticated` | 401 | No | Authentication required. Provide valid token |
+| `permission_denied` | 403 | No | Insufficient permissions for this operation |
+| `resource_not_found` | 404 | No | Resource does not exist. Verify object name or record ID |
+| `conflict` | 409 | No | Resource conflict (e.g., duplicate unique field) |
+| `rate_limit_exceeded` | 429 | Yes | Too many requests. Wait before retrying |
+
+#### Server Errors (5xx)
+
+| Error Code | HTTP Status | Retryable | Description |
+|------------|-------------|-----------|-------------|
+| `internal_error` | 500 | Yes | Server encountered an error. Retry with backoff |
+| `service_unavailable` | 503 | Yes | Service temporarily unavailable. Retry later |
+| `gateway_timeout` | 504 | Yes | Request timeout. Consider increasing timeout or retrying |
+
+**Retry Strategy Example:**
+
+```typescript
+async function retryableRequest<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      return await fn();
+    } catch (error: any) {
+      if (!error.retryable || i === maxRetries - 1) {
+        throw error;
+      }
+      // Exponential backoff
+      await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000));
+    }
+  }
+  throw new Error('Max retries exceeded');
+}
+
+// Usage
+const data = await retryableRequest(() => 
+  client.data.create('todo_task', { subject: 'Task' })
+);
+```
 
diff --git a/packages/core/README.md b/packages/core/README.md
@@ -82,6 +82,42 @@ const service = kernel.getService('my-service');
 await kernel.shutdown();
 ```
 
+## 🤖 AI Quick Reference
+
+**For AI Agents:** This package implements a microkernel architecture. Key concepts:
+
+1. **Plugin Lifecycle**: `init()` → `start()` → `destroy()`
+2. **Service Registry**: Share functionality via `ctx.registerService(name, service)` and `ctx.getService(name)`
+3. **Dependencies**: Declare plugin dependencies for automatic load ordering
+4. **Hooks/Events**: Decouple plugins with `ctx.hook(event, handler)` and `ctx.trigger(event, ...args)`
+5. **Logger**: Always use `ctx.logger` for consistent, structured logging
+
+**Common Plugin Pattern:**
+```typescript
+const plugin: Plugin = {
+  name: 'my-plugin',
+  dependencies: ['other-plugin'], // Load after these plugins
+  
+  async init(ctx: PluginContext) {
+    // Register services and hooks
+    const otherService = ctx.getService('other-service');
+    ctx.registerService('my-service', new MyService(otherService));
+    ctx.hook('data:created', async (data) => { /* ... */ });
+  },
+  
+  async start(ctx: PluginContext) {
+    // Execute business logic
+    const service = ctx.getService('my-service');
+    await service.initialize();
+  },
+  
+  async destroy() {
+    // Cleanup resources
+    await service.close();
+  }
+};
+```
+
 ## Configurable Logger
 
 The logger uses **[Pino](https://github.com/pinojs/pino)** for Node.js environments (high-performance, low-overhead) and a simple console-based logger for browsers. It automatically detects the runtime environment.
diff --git a/packages/spec/README.md b/packages/spec/README.md
@@ -54,6 +54,43 @@ The specification is organized into five namespaces mapping to the three-layer a
 
 ## 📚 Usage
 
+### 🤖 AI Quick Reference
+
+**For AI Agents and LLMs:** This package is the single source of truth for ObjectStack protocol definitions. When working with ObjectStack:
+
+1. **Import Patterns**: Always use namespace imports (`Data.Field`, `UI.View`) or direct subpath imports
+2. **Validation**: Use Zod schemas for runtime validation (e.g., `ObjectSchema.parse(config)`)
+3. **Type Inference**: Derive TypeScript types from Zod (`type Field = z.infer<typeof FieldSchema>`)
+4. **Naming Convention**: 
+   - Configuration keys (TypeScript properties): `camelCase` (e.g., `maxLength`, `defaultValue`)
+   - Machine names (data values): `snake_case` (e.g., `name: 'todo_task'`, `field: 'due_date'`)
+5. **Context Files**: Load prompts from `prompts/` directory for architectural understanding
+
+**Common Tasks:**
+```typescript
+// Define an Object
+import { Data } from '@objectstack/spec';
+const task: Data.Object = {
+  name: 'todo_task',
+  fields: {
+    subject: { type: 'text', label: 'Subject', required: true },
+    priority: { type: 'number', min: 1, max: 5 }
+  }
+};
+
+// Validate at runtime
+import { ObjectSchema } from '@objectstack/spec/data';
+const result = ObjectSchema.safeParse(task);
+
+// Define an App
+import { UI } from '@objectstack/spec';
+const app: UI.App = {
+  id: 'crm',
+  name: 'CRM',
+  navigation: { /* ... */ }
+};
+```
+
 ### Import Styles
 
 **Important:** This package does NOT export types at the root level to prevent naming conflicts. You must use one of the following import styles:
