cmp-standards 2.0.1 → 2.6.0

package/README.md

@@ -1,541 +1,633 @@
-# cmp-memory-system
-
-> Unified memory & workflow system for Claude Code projects
-
-## Features
-
-- **Task Tracking** - Automatic task registration in database
-- **Idea Capture** - Collect ideas and improvements during work
-- **Work Plans** - Persistent work plans across sessions
-- **Memory System** - Session context and memory management
-- **Auto-Improvement** - Pattern detection → ESLint rule generation
-- **Dashboard** - Web UI for visualization
-- **MCP Server** - Model Context Protocol integration
-- **Analytics** - Usage tracking and insights
-
-## Installation
-
-```bash
-npm install cmp-memory-system
-```
-
-## Quick Start
-
-```bash
-# Initialize in project
-cmp-memory init --system MYPROJECT --name "My Project"
-
-# Check status
-cmp-memory status
-
-# Check status
-claude-memory status
-```
-
-## CLI Commands
-
-### `claude-memory init`
-
-Initialize memory system in current project.
-
-```bash
-claude-memory init [options]
-
-Options:
-  -s, --system <system>  System identifier (SWARMSCALE, PANEL)
-  -n, --name <name>      Project name
-  -f, --force            Overwrite existing configuration
-```
-
-### `claude-memory generate`
-
-Generate embedding registry from documentation.
-
-```bash
-claude-memory generate [options]
-
-Options:
-  -i, --incremental     Only update changed files
-  --files <files>       Specific files (comma-separated)
-```
-
-### `claude-memory scan`
-
-Scan codebase for patterns.
-
-```bash
-claude-memory scan [options]
-
-Options:
-  -d, --dir <directory>   Directory to scan (default: src)
-  -t, --threshold <n>     Pattern threshold (default: 3)
-```
-
-### `claude-memory improve`
-
-Run auto-improvement for triggered patterns.
-
-```bash
-claude-memory improve [options]
-
-Options:
-  --dry-run              Show without making changes
-  -p, --pattern <id>     Specific pattern to improve
-```
-
-### `claude-memory status`
-
-Show memory system status.
-
-### `claude-memory dashboard`
-
-Start the memory dashboard web UI.
-
-```bash
-claude-memory dashboard [options]
-
-Options:
-  -p, --port <port>  Port to run on (default: 3847)
-  --no-open          Don't open browser automatically
-```
-
-### `claude-memory analytics`
-
-Show analytics and system health.
-
-```bash
-claude-memory analytics [options]
-
-Options:
-  -p, --period <period>  Time period (day, week, month)
-  --json                 Output as JSON
-```
-
-### `claude-memory feedback`
-
-View feedback statistics.
-
-### `claude-memory mcp`
-
-Start the MCP server for Claude integration.
-
----
-
-## Workflow Commands (NEW)
-
-### `claude-memory tasks`
-
-View and manage tasks.
-
-```bash
-claude-memory tasks [options]
-
-Options:
-  -a, --all              Show all tasks including completed
-  -l, --limit <number>   Limit number of tasks (default: 10)
-```
-
-### `claude-memory ideas`
-
-View captured ideas.
-
-```bash
-claude-memory ideas [options]
-
-Options:
-  -c, --category <cat>   Filter by category (feature, refactor, bug, optimization, documentation)
-  -p, --priority <pri>   Filter by priority (high, medium, low)
-  -l, --limit <number>   Limit number of ideas (default: 20)
-```
-
-### `claude-memory improvements`
-
-View suggested improvements.
-
-```bash
-claude-memory improvements [options]
-
-Options:
-  -t, --type <type>      Filter by type (code_quality, performance, security, ux, architecture)
-  -e, --effort <effort>  Filter by effort (small, medium, large)
-  -l, --limit <number>   Limit number (default: 20)
-```
-
-### `claude-memory plan`
-
-Manage work plans.
-
-```bash
-claude-memory plan [options]
-
-Options:
-  -s, --status           Show current plan status
-  -c, --complete         Complete current task
-  -n, --next             Move to next task
-  -h, --history          Show plan history
-```
-
-### `claude-memory capture <text>`
-
-Quick capture an idea or improvement. Auto-categorizes based on content.
-
-```bash
-claude-memory capture "Consider adding caching to API calls"
-```
-
-### `claude-memory export`
-
-Export ideas and improvements as markdown.
-
-```bash
-claude-memory export [options]
-
-Options:
-  -o, --output <file>    Output file (default: IDEAS_AND_IMPROVEMENTS.md)
-```
-
----
-
-## Architecture
-
-```
-@metanautical/claude-memory
-├── src/
-│   ├── hooks/
-│   │   ├── session-start.ts      # Context loader on session start
-│   │   ├── pre-tool-use.ts       # Guards + embedding injection
-│   │   ├── post-tool-use.ts      # Record changes after Edit/Write
-│   │   └── memory-checkpoint.ts  # Record learnings after changes
-│   ├── registry/
-│   │   ├── generator.ts          # Parse docs → embeddings
-│   │   └── embeddings.ts         # OpenAI/Gemini embedding service
-│   ├── auto-improve/
-│   │   ├── pattern-detector.ts   # Detect repeated violations
-│   │   └── eslint-generator.ts   # Generate ESLint rules
-│   ├── db/
-│   │   ├── client.ts             # DEV_Items database client (mock)
-│   │   └── drizzle-client.ts     # Real Drizzle ORM client
-│   ├── mcp/
-│   │   └── server.ts             # MCP server for Claude tools
-│   ├── dashboard/
-│   │   ├── server.ts             # Express dashboard server
-│   │   └── ui.ts                 # React UI generator
-│   ├── feedback/
-│   │   └── collector.ts          # User feedback collection
-│   ├── analytics/
-│   │   └── tracker.ts            # Usage analytics & insights
-│   ├── utils/
-│   │   ├── config.ts             # Configuration management
-│   │   └── paths.ts              # Path utilities
-│   ├── types/
-│   │   └── index.ts              # Type definitions
-│   ├── cli/
-│   │   └── index.ts              # CLI commands
-│   └── index.ts                  # Main exports
-```
-
-## Configuration
-
-### `.claude/memory-config.json`
-
-```json
-{
-  "system": "SWARMSCALE",
-  "projectName": "SwarmScale",
-  "domains": ["video-studio", "avatars", "campaigns"],
-  "guards": {
-    "enabled": true,
-    "rules": [
-      {
-        "id": "schema-protection",
-        "type": "block",
-        "filePattern": "src/server/schema/auth.ts",
-        "message": "PANEL_* tables are READ-ONLY"
-      }
-    ]
-  },
-  "embedding": {
-    "enabled": true,
-    "threshold": 0.60,
-    "maxSections": 3
-  },
-  "autoImprovement": {
-    "enabled": true,
-    "violationThreshold": 3,
-    "generateEslintRules": true
-  }
-}
-```
-
-### `.claude/settings.json`
-
-```json
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Task",
-        "hooks": [{
-          "type": "command",
-          "command": "npx tsx node_modules/@metanautical/claude-memory/dist/hooks/pre-tool-use.js"
-        }]
-      }
-    ],
-    "SessionStart": [
-      {
-        "matcher": "",
-        "hooks": [{
-          "type": "command",
-          "command": "npx tsx node_modules/@metanautical/claude-memory/dist/hooks/session-start.js"
-        }]
-      }
-    ]
-  },
-  "plugins": {
-    "metanautical-memory": {
-      "version": "1.0.0",
-      "enabled": true
-    }
-  }
-}
-```
-
-## Hooks
-
-### SessionStart Hook
-
-Executes on session start:
-1. Detects module from `git diff` (last 24h)
-2. Queries DEV_Items for relevant memories
-3. Returns formatted context
-
-```typescript
-import { SessionStartHook } from '@metanautical/claude-memory/hooks'
-
-const hook = new SessionStartHook()
-const result = await hook.execute()
-// result.context contains session context
-```
-
-### PreToolUse Hook
-
-Executes before Edit/Write/Task tools:
-1. **Edit/Write**: Validates against guard rules
-2. **Task**: Injects relevant knowledge via embeddings
-
-```typescript
-import { PreToolUseHook } from '@metanautical/claude-memory/hooks'
-
-const hook = new PreToolUseHook()
-const result = await hook.execute({
-  tool_name: 'Edit',
-  parameters: { file_path: 'src/file.ts', new_string: '...' }
-})
-
-if (result.mode === 'block') {
-  // Guard violation - block operation
-}
-```
-
-## Auto-Improvement
-
-### Pattern Detection
-
-Built-in patterns detected:
-- `any-type` - Using `any` type
-- `console-log` - Console.log in production
-- `eslint-disable` - ESLint disable comments
-- `hardcoded-string` - UI strings not using i18n
-- `direct-db-query` - Database queries in components
-- `inline-style` - Inline styles instead of Tailwind
-
-### ESLint Rule Generation
-
-When a pattern is detected 3+ times:
-
-```bash
-# Scan for patterns
-claude-memory scan
-
-# Output:
-# 🔴 any-type [high]
-#    Count: 5, Files: 3
-# ⚠️ Patterns ready for auto-improvement
-
-# Generate ESLint rule
-claude-memory improve
-
-# Creates: eslint-plugin-charter/rules/no-any-type.js
-```
-
-## Programmatic Usage
-
-```typescript
-import {
-  loadConfig,
-  PatternDetector,
-  ESLintGenerator,
-  RegistryGenerator
-} from '@metanautical/claude-memory'
-
-// Load config
-const config = await loadConfig(process.cwd())
-
-// Detect patterns
-const detector = new PatternDetector(config)
-const patterns = detector.scan(fileContent, filePath)
-const results = detector.getResults()
-
-// Generate ESLint rules
-const generator = new ESLintGenerator()
-await generator.generateAllRules(results.triggered)
-
-// Generate registry
-const registry = new RegistryGenerator()
-await registry.generate()
-```
-
-## System Isolation
-
-Data is isolated by `system` field in DEV_Items:
-
-| System | Project |
-|--------|---------|
-| `SWARMSCALE` | SwarmScale |
-| `PANEL` | TheCharterPanel |
-| `ECOSYSTEM` | Cross-project |
-
-Always filter by system:
-
-```typescript
-// Correct
-db.select().from(devItems).where(eq(devItems.system, 'SWARMSCALE'))
-
-// Wrong - returns ALL projects' data
-db.select().from(devItems)
-```
-
-## Environment Variables
-
-```bash
-# Required for embedding generation
-OPENAI_API_KEY=sk-...      # Preferred
-GEMINI_API_KEY=...         # Fallback
-
-# Optional
-MEMORY_DEBUG=true          # Enable debug logging
-```
-
-## Development
-
-```bash
-# Install dependencies
-npm install
-
-# Build
-npm run build
-
-# Watch mode
-npm run dev
-
-# Run tests
-npm test
-
-# Link for local development
-npm link
-```
-
-## MCP Server
-
-The MCP (Model Context Protocol) server exposes memory tools that Claude can use directly:
-
-```bash
-# Start MCP server
-claude-memory mcp
-```
-
-**Available Tools:**
-- `memory_search` - Search memories by query
-- `memory_write` - Write new memory/learning
-- `memory_list` - List recent memories
-- `pattern_check` - Check for detected patterns
-- `pattern_report` - Report a new pattern occurrence
-- `session_context` - Get current session context
-- `feedback_submit` - Submit feedback on a memory
-
-## Dashboard
-
-Start the standalone web dashboard:
-
-```bash
-claude-memory dashboard
-# Opens http://localhost:3847
-```
-
-**Features:**
-- View all memories with search and filtering
-- Browse detected patterns
-- See session history
-- Submit feedback on memories
-- Create new memories
-- View analytics and system health
-
-## Feedback Loop
-
-The feedback system adjusts memory relevance based on user feedback:
-
-```typescript
-import { createFeedbackCollector } from '@metanautical/claude-memory'
-
-const collector = createFeedbackCollector('SWARMSCALE')
-
-// Submit feedback
-await collector.submitFeedback(memoryId, true, 'Very helpful!')
-
-// Get feedback stats
-const stats = await collector.getStats()
-// { helpfulRate: 0.85, topHelpfulMemories: [...] }
-
-// Get suggestions for deprecation
-const deprecations = await collector.getSuggestedDeprecations()
-```
-
-## Analytics
-
-Track usage and get insights:
-
-```typescript
-import { createAnalyticsTracker } from '@metanautical/claude-memory'
-
-const tracker = createAnalyticsTracker('SWARMSCALE')
-
-// Track an event
-await tracker.track('memory_access', { memoryId: '...' })
-
-// Get usage stats
-const usage = await tracker.getUsageStats('week')
-// { sessions: 12, memoriesCreated: 5, searchesPerformed: 23, ... }
-
-// Get system health
-const health = await tracker.getSystemHealth()
-// { status: 'healthy', issues: [], recommendations: [...] }
-
-// Generate full report
-const report = await tracker.generateReport()
-```
-
-## Database Configuration
-
-Set environment variables for database connection:
-
-```bash
-DATABASE_HOST=localhost
-DATABASE_PORT=3306
-DATABASE_USER=root
-DATABASE_PASSWORD=your-password
-DATABASE_NAME=metanautical
-```
-
-## License
-
-MIT - MetaNautical Group
+# CMP - Collective Memory Protocol
+
+> **The Development Intelligence Layer** - Persistent memory, cross-project learning, and multi-agent collaboration for AI-assisted development.
+
+[![npm version](https://img.shields.io/npm/v/cmp-standards.svg)](https://www.npmjs.com/package/cmp-standards)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## Philosophy
+
+| Principle | Meaning |
+|-----------|---------|
+| **Evidence > Assumptions** | Never assume. Always verify. Read before writing. |
+| **Cloud > Local** | Memory lives in the cloud. Sessions are ephemeral, knowledge is permanent. |
+| **Collective > Individual** | One project's learnings benefit all projects. |
+| **Continuity > Restarts** | Work survives IDE restarts, machine changes, and agent switches. |
+
+---
+
+## Features
+
+### Core
+- **Plans with Checkpoints** - Persistent objectives with semantic matching and multi-agent handoffs
+- **ESLint Plugin** - 11+ custom rules for code quality
+- **Task Tracking** - Automatic task registration in database
+- **Idea Capture** - Collect ideas and improvements during work
+- **Memory System** - Session context and memory management
+- **Auto-Improvement** - Pattern detection and ESLint rule generation
+- **Dashboard** - Web UI for visualization
+- **MCP Server** - Model Context Protocol integration
+- **Analytics** - Usage tracking and insights
+
+### Cloud Infrastructure
+- **Turso** (SQLite Edge) - Plans, tasks, improvements, memories
+- **Upstash Redis** - Session cache, rate limiting, real-time sync
+- **Upstash Vector** - Semantic search with embeddings
+- **Cloud Hooks** - Session continuity across IDE restarts
+
+### Multi-Agent Continuity (v2.5.0+)
+- **Plan Detection** - Semantic matching finds related plans at session start
+- **Checkpoints** - Save points that record progress, decisions, and next steps
+- **Agent Handoffs** - One agent can resume where another left off
+- **Cross-Session** - Plans persist across IDE restarts and machine changes
+
+## Cloud Quick Start
+
+```typescript
+import { cloud } from 'cmp-standards'
+
+// Initialize cloud services
+await cloud.init()
+
+// Start work session
+const session = await cloud.startWorkSession('MYPROJECT')
+console.log(`Active tasks: ${session.activeTasks.length}`)
+
+// Start task
+const taskId = await cloud.startTask('MYPROJECT', session.sessionId, {
+  title: 'Implement feature X',
+  plan: ['Step 1', 'Step 2'],
+  domain: 'features'
+})
+
+// Complete task (requires at least 1 improvement)
+await cloud.completeTask(taskId, {
+  result: 'success',
+  improvements: [{
+    area: 'features',
+    title: 'Add caching',
+    description: 'Could cache API responses',
+    priority: 'medium'
+  }],
+  lessons: ['Pattern X works better']
+})
+```
+
+## Environment Variables
+
+```env
+# Turso (SQLite Edge)
+TURSO_DATABASE_URL=libsql://your-db.turso.io
+TURSO_AUTH_TOKEN=your-token
+
+# Upstash Redis
+UPSTASH_REDIS_REST_URL=https://your-redis.upstash.io
+UPSTASH_REDIS_REST_TOKEN=your-token
+
+# Upstash Vector
+UPSTASH_VECTOR_REST_URL=https://your-vector.upstash.io
+UPSTASH_VECTOR_REST_TOKEN=your-token
+```
+
+## Installation
+
+```bash
+npm install cmp-standards
+```
+
+## Quick Start
+
+```bash
+# Initialize in project
+cmp-standards init --system MYPROJECT --name "My Project"
+
+# Check status
+cmp-standards status
+
+# Start dashboard
+cmp-standards dashboard
+```
+
+## CLI Commands
+
+### `cmp-standards init`
+
+Initialize the system in current project.
+
+```bash
+cmp-standards init [options]
+
+Options:
+  -s, --system <system>  System identifier (SWARMSCALE, PANEL)
+  -n, --name <name>      Project name
+  -f, --force            Overwrite existing configuration
+```
+
+### `cmp-standards generate`
+
+Generate embedding registry from documentation.
+
+```bash
+cmp-standards generate [options]
+
+Options:
+  -i, --incremental     Only update changed files
+  --files <files>       Specific files (comma-separated)
+```
+
+### `cmp-standards scan`
+
+Scan codebase for patterns.
+
+```bash
+cmp-standards scan [options]
+
+Options:
+  -d, --dir <directory>   Directory to scan (default: src)
+  -t, --threshold <n>     Pattern threshold (default: 3)
+```
+
+### `cmp-standards improve`
+
+Run auto-improvement for triggered patterns.
+
+```bash
+cmp-standards improve [options]
+
+Options:
+  --dry-run              Show without making changes
+  -p, --pattern <id>     Specific pattern to improve
+```
+
+### `cmp-standards status`
+
+Show memory system status.
+
+### `cmp-standards dashboard`
+
+Start the memory dashboard web UI.
+
+```bash
+cmp-standards dashboard [options]
+
+Options:
+  -p, --port <port>  Port to run on (default: 3847)
+  --no-open          Don't open browser automatically
+```
+
+### `cmp-standards analytics`
+
+Show analytics and system health.
+
+```bash
+cmp-standards analytics [options]
+
+Options:
+  -p, --period <period>  Time period (day, week, month)
+  --json                 Output as JSON
+```
+
+### `cmp-standards feedback`
+
+View feedback statistics.
+
+### `cmp-standards mcp`
+
+Start the MCP server for Claude integration.
+
+---
+
+## Workflow Commands
+
+### `cmp-standards tasks`
+
+View and manage tasks.
+
+```bash
+cmp-standards tasks [options]
+
+Options:
+  -a, --all              Show all tasks including completed
+  -l, --limit <number>   Limit number of tasks (default: 10)
+```
+
+### `cmp-standards ideas`
+
+View captured ideas.
+
+```bash
+cmp-standards ideas [options]
+
+Options:
+  -c, --category <cat>   Filter by category (feature, refactor, bug, optimization, documentation)
+  -p, --priority <pri>   Filter by priority (high, medium, low)
+  -l, --limit <number>   Limit number of ideas (default: 20)
+```
+
+### `cmp-standards improvements`
+
+View suggested improvements.
+
+```bash
+cmp-standards improvements [options]
+
+Options:
+  -t, --type <type>      Filter by type (code_quality, performance, security, ux, architecture)
+  -e, --effort <effort>  Filter by effort (small, medium, large)
+  -l, --limit <number>   Limit number (default: 20)
+```
+
+### `cmp-standards plan`
+
+Manage work plans.
+
+```bash
+cmp-standards plan [options]
+
+Options:
+  -s, --status           Show current plan status
+  -c, --complete         Complete current task
+  -n, --next             Move to next task
+  -h, --history          Show plan history
+```
+
+### `cmp-standards capture <text>`
+
+Quick capture an idea or improvement. Auto-categorizes based on content.
+
+```bash
+cmp-standards capture "Consider adding caching to API calls"
+```
+
+### `cmp-standards export`
+
+Export ideas and improvements as markdown.
+
+```bash
+cmp-standards export [options]
+
+Options:
+  -o, --output <file>    Output file (default: IDEAS_AND_IMPROVEMENTS.md)
+```
+
+---
+
+## Architecture
+
+```
+cmp-standards
+├── src/
+│   ├── hooks/
+│   │   ├── session-start.ts      # Context loader on session start
+│   │   ├── pre-tool-use.ts       # Guards + embedding injection
+│   │   ├── post-tool-use.ts      # Record changes after Edit/Write
+│   │   └── memory-checkpoint.ts  # Record learnings after changes
+│   ├── eslint/
+│   │   ├── index.ts              # ESLint plugin entry
+│   │   ├── rules/                # Custom ESLint rules
+│   │   └── config-builder.ts     # Dynamic config generation
+│   ├── services/
+│   │   ├── TaskTracker.ts        # Task tracking
+│   │   ├── IdeaCollector.ts      # Idea/improvement capture
+│   │   ├── WorkPlanManager.ts    # Work plan management
+│   │   └── ...                   # Other services
+│   ├── registry/
+│   │   ├── generator.ts          # Parse docs → embeddings
+│   │   └── embeddings.ts         # OpenAI/Gemini embedding service
+│   ├── auto-improve/
+│   │   ├── pattern-detector.ts   # Detect repeated violations
+│   │   └── eslint-generator.ts   # Generate ESLint rules
+│   ├── db/
+│   │   ├── client.ts             # DEV_Items database client (mock)
+│   │   └── drizzle-client.ts     # Real Drizzle ORM client
+│   ├── mcp/
+│   │   └── server.ts             # MCP server for Claude tools
+│   ├── dashboard/
+│   │   ├── server.ts             # Express dashboard server
+│   │   └── ui.ts                 # React UI generator
+│   ├── utils/
+│   │   ├── config.ts             # Configuration management
+│   │   ├── paths.ts              # Path utilities with traversal protection
+│   │   └── git.ts                # Safe git operations (simple-git)
+│   ├── types/
+│   │   └── index.ts              # Type definitions
+│   ├── cli/
+│   │   └── index.ts              # CLI commands
+│   └── index.ts                  # Main exports
+```
+
+## Configuration
+
+### `.claude/memory-config.json`
+
+```json
+{
+  "system": "SWARMSCALE",
+  "projectName": "SwarmScale",
+  "domains": ["video-studio", "avatars", "campaigns"],
+  "guards": {
+    "enabled": true,
+    "rules": [
+      {
+        "id": "schema-protection",
+        "type": "block",
+        "filePattern": "src/server/schema/auth.ts",
+        "message": "PANEL_* tables are READ-ONLY"
+      }
+    ]
+  },
+  "embedding": {
+    "enabled": true,
+    "threshold": 0.60,
+    "maxSections": 3
+  },
+  "autoImprovement": {
+    "enabled": true,
+    "violationThreshold": 3,
+    "generateEslintRules": true
+  }
+}
+```
+
+### `.claude/settings.json`
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Task",
+        "hooks": [{
+          "type": "command",
+          "command": "npx tsx node_modules/cmp-standards/dist/hooks/pre-tool-use.js"
+        }]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [{
+          "type": "command",
+          "command": "npx tsx node_modules/cmp-standards/dist/hooks/session-start.js"
+        }]
+      }
+    ]
+  },
+  "plugins": {
+    "cmp-standards": {
+      "version": "2.0.0",
+      "enabled": true
+    }
+  }
+}
+```
+
+## Hooks
+
+### SessionStart Hook
+
+Executes on session start:
+1. Detects module from `git diff` (last 24h)
+2. Queries DEV_Items for relevant memories
+3. Returns formatted context
+
+```typescript
+import { SessionStartHook } from 'cmp-standards/hooks'
+
+const hook = new SessionStartHook()
+const result = await hook.execute()
+// result.context contains session context
+```
+
+### PreToolUse Hook
+
+Executes before Edit/Write/Task tools:
+1. **Edit/Write**: Validates against guard rules
+2. **Task**: Injects relevant knowledge via embeddings
+
+```typescript
+import { PreToolUseHook } from 'cmp-standards/hooks'
+
+const hook = new PreToolUseHook()
+const result = await hook.execute({
+  tool_name: 'Edit',
+  parameters: { file_path: 'src/file.ts', new_string: '...' }
+})
+
+if (result.mode === 'block') {
+  // Guard violation - block operation
+}
+```
+
+## ESLint Plugin
+
+The package includes a custom ESLint plugin with 11+ rules.
+
+### Using the ESLint Plugin
+
+```javascript
+// eslint.config.mjs
+import cmpStandards from 'cmp-standards/eslint'
+
+export default [
+  ...cmpStandards.configs.recommended,
+]
+```
+
+### Dynamic Configuration
+
+```typescript
+import { generateConfig } from 'cmp-standards/eslint'
+
+// Generate config based on project structure
+const config = await generateConfig(process.cwd())
+```
+
+## Auto-Improvement
+
+### Pattern Detection
+
+Built-in patterns detected:
+- `any-type` - Using `any` type
+- `console-log` - Console.log in production
+- `eslint-disable` - ESLint disable comments
+- `hardcoded-string` - UI strings not using i18n
+- `direct-db-query` - Database queries in components
+- `inline-style` - Inline styles instead of Tailwind
+
+### ESLint Rule Generation
+
+When a pattern is detected 3+ times:
+
+```bash
+# Scan for patterns
+cmp-standards scan
+
+# Output:
+# any-type [high]
+#    Count: 5, Files: 3
+# Patterns ready for auto-improvement
+
+# Generate ESLint rule
+cmp-standards improve
+
+# Creates: eslint-plugin-charter/rules/no-any-type.js
+```
+
+## Programmatic Usage
+
+```typescript
+import {
+  loadConfig,
+  PatternDetector,
+  ESLintGenerator,
+  RegistryGenerator
+} from 'cmp-standards'
+
+// Load config
+const config = await loadConfig(process.cwd())
+
+// Detect patterns
+const detector = new PatternDetector(config)
+const patterns = detector.scan(fileContent, filePath)
+const results = detector.getResults()
+
+// Generate ESLint rules
+const generator = new ESLintGenerator()
+await generator.generateAllRules(results.triggered)
+
+// Generate registry
+const registry = new RegistryGenerator()
+await registry.generate()
+```
+
+## System Isolation
+
+Data is isolated by `system` field in DEV_Items:
+
+| System | Project |
+|--------|---------|
+| `SWARMSCALE` | SwarmScale |
+| `PANEL` | TheCharterPanel |
+| `ECOSYSTEM` | Cross-project |
+
+Always filter by system:
+
+```typescript
+// Correct
+db.select().from(devItems).where(eq(devItems.system, 'SWARMSCALE'))
+
+// Wrong - returns ALL projects' data
+db.select().from(devItems)
+```
+
+## Security Features
+
+### Path Traversal Protection
+
+All path operations are validated to prevent directory traversal attacks:
+
+```typescript
+import { validateSafePath, safeJoin } from 'cmp-standards'
+
+// Throws PathTraversalError if path escapes base
+validateSafePath(projectRoot, userPath)
+
+// Safe path joining with validation
+const safePath = safeJoin(projectRoot, 'subdir', filename)
+```
+
+### Safe Git Operations
+
+Git operations use `simple-git` instead of shell commands to prevent command injection:
+
+```typescript
+import { getCurrentBranch, getRecentChanges } from 'cmp-standards'
+
+// Safe - uses simple-git internally
+const branch = await getCurrentBranch(projectRoot)
+const changes = await getRecentChanges(projectRoot, { commits: 10 })
+```
+
+## Environment Variables
+
+```bash
+# Required for embedding generation
+OPENAI_API_KEY=sk-...      # Preferred
+GEMINI_API_KEY=...         # Fallback
+
+# Optional
+MEMORY_DEBUG=true          # Enable debug logging
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Watch mode
+npm run dev
+
+# Run tests
+npm test
+
+# Link for local development
+npm link
+```
+
+## MCP Server
+
+The MCP (Model Context Protocol) server exposes memory tools that Claude can use directly:
+
+```bash
+# Start MCP server
+cmp-standards mcp
+```
+
+**Available Tools:**
+- `memory_search` - Search memories by query
+- `memory_write` - Write new memory/learning
+- `memory_list` - List recent memories
+- `pattern_check` - Check for detected patterns
+- `pattern_report` - Report a new pattern occurrence
+- `session_context` - Get current session context
+- `feedback_submit` - Submit feedback on a memory
+
+## Dashboard
+
+Start the standalone web dashboard:
+
+```bash
+cmp-standards dashboard
+# Opens http://localhost:3847
+```
+
+**Features:**
+- View all memories with search and filtering
+- Browse detected patterns
+- See session history
+- Submit feedback on memories
+- Create new memories
+- View analytics and system health
+
+## Database Configuration
+
+Set environment variables for database connection:
+
+```bash
+DATABASE_HOST=localhost
+DATABASE_PORT=3306
+DATABASE_USER=root
+DATABASE_PASSWORD=your-password
+DATABASE_NAME=metanautical
+```
+
+## License
+
+MIT - Carlos Martin Pavon