sqlew 3.9.1 → 4.0.0

package/docs/AI_AGENT_GUIDE.md

@@ -1,19 +1,19 @@
 # AI Agent Guide for MCP sqlew
 
-**Quick Reference for Claude Code and other AI agents using sqlew**
+**Quick Reference for Claude Code and other AI agents using sqlew (v4.0.0+)**
 
-## 🚨 Most Important Rule
+## Most Important Rule
 
 **ALWAYS include the `action` parameter in EVERY tool call.** This is the #1 cause of errors.
 
 ```javascript
-// ❌ WRONG - Missing action
+// WRONG - Missing action
 {
   key: "some_key",
   value: "some value"
 }
 
-// ✅ CORRECT - action parameter present
+// CORRECT - action parameter present
 {
   action: "set",
   key: "some_key",
@@ -23,20 +23,6 @@
 
 ---
 
-## Table of Contents
-
-1. [Quick Start](#quick-start)
-2. [When to Use Each Tool: Decision Tree](#when-to-use-each-tool-decision-tree)
-3. [Parameter Requirements by Tool](#parameter-requirements-by-tool)
-4. [Common Errors & Solutions](#common-errors--solutions)
-5. [Search Actions Decision Tree](#search-actions-decision-tree)
-6. [Batch Operations Guide](#batch-operations-guide)
-7. [Template System](#template-system)
-8. [Multi-Step Workflow Examples](#multi-step-workflow-examples)
-9. [Best Practices](#best-practices)
-
----
-
 ## Quick Start
 
 ### Basic Decision Workflow
@@ -65,1429 +51,148 @@
 }
 ```
 
-### Basic Messaging Workflow
-
-```javascript
-// 1. Send a message
-{
-  action: "send",
-  from_agent: "bot1",
-  msg_type: "info",
-  message: "Task completed successfully",
-  priority: "high"
-}
-
-// 2. Get messages
-{
-  action: "get",
-  agent_name: "bot1",
-  unread_only: true
-}
-
-// 3. Mark as read
-{
-  action: "mark_read",
-  agent_name: "bot1",
-  message_ids: [1, 2, 3]
-}
-```
-
 ---
 
-## When to Use Each Tool: Decision Tree
-
-### Understanding Tool Purposes
-
-Each tool serves a distinct purpose in the MCP sqlew ecosystem:
-
-```
-┌──────────────────────────────────────────────────────────┐
-│ What do you need to do?                                  │
-└────────────────┬─────────────────────────────────────────┘
-                 │
-                 ├─ Record a CHOICE that was made?
-                 │  └─> Use `decision` tool
-                 │      • Examples: "We chose JWT auth", "Selected PostgreSQL"
-                 │      • Key: Captures PAST decisions
-                 │      • Supports: versioning, tags, layers, scopes
-                 │
-                 ├─ Communicate with other agents?
-                 │  └─> Use `message` tool
-                 │      • Examples: Task updates, warnings, requests
-                 │      • Key: Real-time communication
-                 │      • Supports: priority, broadcast, read tracking
-                 │
-                 ├─ Define a REQUIREMENT that must be followed?
-                 │  └─> Use `constraint` tool
-                 │      • Examples: "API must be <100ms", "Code coverage >80%"
-                 │      • Key: Enforces RULES
-                 │      • Supports: priority, categories, layers
-                 │
-                 ├─ Track WORK to be done?
-                 │  └─> Use `task` tool
-                 │      • Examples: "Implement feature X", "Fix bug Y"
-                 │      • Key: Tracks TODO items and progress
-                 │      • Supports: status transitions, auto-stale, auto-archive, linking
-                 │
-                 ├─ Record file modifications?
-                 │  └─> Use `file` tool
-                 │      • Examples: Track changes, check locks
-                 │      • Key: File change history
-                 │      • Supports: layers, change types, lock detection
-                 │
-                 └─ Get statistics or manage data?
-                    └─> Use `stats` or `config` tools
-                        • stats: Database metrics, cleanup, activity logs
-                        • config: Retention settings, auto-deletion
-```
-
-### Tool Comparison Table
+## When to Use Each Tool
 
-| Tool | Use For | Don't Use For | Key Feature |
-|------|---------|---------------|-------------|
-| **decision** | Recording choices made | Future work, requirements | Version history tracking |
-| **message** | Agent communication | Permanent records, decisions | Priority-based delivery |
-| **constraint** | Requirements & rules | Decisions, tasks | Category-based organization |
-| **task** | Work tracking (TODO) | Decisions, history | Auto-stale detection |
-| **file** | File change tracking | Code search, content | Layer-based organization |
-| **stats** | Metrics & cleanup | Data storage | Aggregated views |
-| **config** | Retention settings | Business logic | Auto-deletion control |
+| Tool | Use For | Key Feature |
+|------|---------|-------------|
+| **decision** | Recording choices made | Version history tracking |
+| **constraint** | Requirements & rules | Category-based organization |
+| **task** | Work tracking (TODO) | Kanban status, dependencies |
+| **file** | File change tracking | Layer-based organization |
+| **stats** | Metrics & cleanup | Aggregated views |
 
 ### Decision vs Constraint vs Task
 
-This is the most common confusion. Here's the distinction:
+| Concept | Definition | Example |
+|---------|------------|---------|
+| **Decision** | A choice that WAS made | "We chose JWT authentication" |
+| **Constraint** | A requirement that MUST be followed | "Response time must be <100ms" |
+| **Task** | Work that NEEDS to be done | "Implement JWT authentication" |
 
-| Concept | Definition | Example | Tool |
-|---------|------------|---------|------|
-| **Decision** | A choice that WAS made | "We chose JWT authentication" | `decision` |
-| **Constraint** | A requirement that MUST be followed | "Response time must be <100ms" | `constraint` |
-| **Task** | Work that NEEDS to be done | "Implement JWT authentication" | `task` |
+### Quick Scenario
 
-### Scenario-Based Tool Selection
-
-#### Scenario 1: Breaking API Change
 ```javascript
-// 1. Record the decision (what changed)
-{
-  action: "set",
-  key: "api_v2_breaking_change",
-  value: "Moved /users endpoint to /v2/users",
-  layer: "presentation",
-  tags: ["api", "breaking-change", "v2.0.0"]
-}
-
-// 2. Add a constraint (requirement going forward)
-{
-  action: "add",
-  category: "architecture",
-  constraint_text: "All API endpoints must include version prefix",
-  layer: "presentation",
-  tags: ["api", "versioning"]
-}
-
-// 3. Create migration task
-{
-  action: "create",
-  title: "Migrate clients to /v2/users endpoint",
-  status: "todo",
-  layer: "presentation",
-  tags: ["migration", "v2.0.0"]
-}
-
-// 4. Notify other agents
-{
-  action: "send",
-  from_agent: "api-agent",
-  msg_type: "warning",
-  message: "Breaking change: /users moved to /v2/users",
-  priority: "critical"
-}
-```
-
-#### Scenario 2: Performance Issue
-```javascript
-// 1. Record the finding (decision to investigate)
-{
-  action: "set",
-  key: "db_performance_issue_found",
-  value: "Query latency increased 300% in production",
-  layer: "data",
-  tags: ["performance", "database", "production"]
-}
-
-// 2. Add performance constraint
-{
-  action: "add",
-  category: "performance",
-  constraint_text: "Database queries must complete within 50ms",
-  priority: "high",
-  layer: "data"
-}
-
-// 3. Create optimization task
-{
-  action: "create",
-  title: "Add indexes to user_sessions table",
-  status: "in_progress",
-  priority: 4,
-  layer: "data",
-  tags: ["performance", "database"]
-}
-```
-
-#### Scenario 3: Security Vulnerability
-```javascript
-// 1. Record the vulnerability (decision about issue)
-{
-  action: "set",
-  key: "auth_vulnerability_CVE_2025_1234",
-  value: "JWT library vulnerable to timing attacks",
-  layer: "business",
-  tags: ["security", "vulnerability", "auth"]
-}
-
-// 2. Add security constraint
-{
-  action: "add",
-  category: "security",
-  constraint_text: "All auth tokens must use constant-time comparison",
-  priority: "critical",
-  layer: "business"
-}
+// 1. Record decision
+{ action: "set", key: "api_change", value: "Moved to /v2/users", layer: "presentation", tags: ["api"] }
 
-// 3. Create fix task
-{
-  action: "create",
-  title: "Upgrade JWT library and implement constant-time comparison",
-  status: "in_progress",
-  priority: 4,
-  assigned_agent: "security-agent",
-  layer: "business"
-}
+// 2. Add constraint
+{ action: "add", category: "architecture", constraint_text: "All API endpoints must include version prefix", layer: "presentation" }
 
-// 4. Alert all agents
-{
-  action: "send",
-  from_agent: "security-agent",
-  to_agent: null,  // Broadcast
-  msg_type: "warning",
-  message: "URGENT: Auth vulnerability found, fix in progress",
-  priority: "critical"
-}
+// 3. Create task
+{ action: "create", title: "Migrate clients to /v2/users", layer: "presentation", tags: ["migration"] }
 ```
 
 ---
 
-## Parameter Requirements by Tool
-
-### `decision` Tool
-
-| Action | Required | Optional |
-|--------|----------|----------|
-| **set** | action, key, value, layer | agent, version, status, tags, scopes |
-| **get** | action, key | version |
-| **list** | action | status, layer, tags, scope, tag_match, limit, offset |
-| **search_tags** | action, tags | match_mode, status, layer |
-| **search_layer** | action, layer | status, include_tags |
-| **versions** | action, key | - |
-| **quick_set** | action, key, value | agent, layer, version, status, tags, scopes |
-| **search_advanced** | action | layers, tags_all, tags_any, exclude_tags, scopes, updated_after, updated_before, decided_by, statuses, search_text, sort_by, sort_order, limit, offset |
-| **set_batch** | action, decisions | atomic |
-| **has_updates** | action, agent_name, since_timestamp | - |
-| **set_from_template** | action, template, key, value, layer | agent, version, status, tags, scopes |
-| **create_template** | action, name, defaults | required_fields, created_by |
-| **list_templates** | action | - |
-
-### `message` Tool
-
-| Action | Required | Optional |
-|--------|----------|----------|
-| **send** | action, from_agent, msg_type, message | to_agent, priority, payload |
-| **get** | action, agent_name | unread_only, priority_filter, msg_type_filter, limit |
-| **mark_read** | action, agent_name, message_ids | - |
-| **send_batch** | action, messages | atomic |
-
-### `file` Tool
-
-| Action | Required | Optional |
-|--------|----------|----------|
-| **record** | action, file_path, agent_name, change_type | layer, description |
-| **get** | action | file_path, agent_name, layer, change_type, since, limit |
-| **check_lock** | action, file_path | lock_duration |
-| **record_batch** | action, file_changes | atomic |
-
-### `constraint` Tool
-
-| Action | Required | Optional |
-|--------|----------|----------|
-| **add** | action, category, constraint_text | priority, layer, tags, created_by |
-| **get** | action | category, layer, priority, tags, active_only, limit |
-| **deactivate** | action, constraint_id | - |
-
-### `stats` Tool
-
-| Action | Required | Optional |
-|--------|----------|----------|
-| **layer_summary** | action | - |
-| **db_stats** | action | - |
-| **clear** | action | messages_older_than_hours, file_changes_older_than_days |
-| **activity_log** | action | since, agent_names, actions, limit |
-
-### `config` Tool
-
-| Action | Required | Optional |
-|--------|----------|----------|
-| **get** | action | - |
-| **update** | action | ignoreWeekend, messageRetentionHours, fileHistoryRetentionDays |
-
-### `task` Tool
-
-| Action | Required | Optional |
-|--------|----------|----------|
-| **create** | action, title | description, acceptance_criteria, notes, priority, assigned_agent, created_by_agent, layer, tags, status |
-| **update** | action, task_id | title, priority, assigned_agent, layer, description, acceptance_criteria, notes |
-| **get** | action, task_id | - |
-| **list** | action | status, assigned_agent, layer, tags, limit, offset |
-| **move** | action, task_id, new_status | - |
-| **link** | action, task_id, link_type, target_id | link_relation |
-| **archive** | action, task_id | - |
-| **create_batch** | action, tasks | atomic |
-
----
-
 ## Common Errors & Solutions
 
-💡 **See also**: [ARCHITECTURE.md](ARCHITECTURE.md) for detailed layer, enum, and status definitions.
-
 ### Error: "Unknown action: undefined"
 
 **Cause**: Missing `action` parameter
 
-**Solution**: Always include `action` as the first parameter
-
 ```javascript
-// ❌ WRONG
-{
-  key: "some_key",
-  value: "some value",
-  layer: "business"
-}
+// WRONG
+{ key: "some_key", value: "some value" }
 
-// ✅ CORRECT
-{
-  action: "set",
-  key: "some_key",
-  value: "some value",
-  layer: "business"
-}
-```
-
-### Error: "Parameter \"value\" is required"
-
-**Cause**: Using `defaults` instead of direct parameters with templates
-
-**Solution**: Provide parameters directly, not nested in `defaults`
-
-```javascript
-// ❌ WRONG
-{
-  action: "set_from_template",
-  template: "deprecation",
-  key: "some_key",
-  defaults: {
-    value: "...",
-    layer: "cross-cutting"
-  }
-}
-
-// ✅ CORRECT
-{
-  action: "set_from_template",
-  template: "deprecation",
-  key: "some_key",
-  value: "...",
-  layer: "cross-cutting"
-}
+// CORRECT
+{ action: "set", key: "some_key", value: "some value" }
 ```
 
 ### Error: "Invalid layer"
 
-**Cause**: Using a layer name that doesn't exist
-
-**Solution**: Use one of the 5 standard layers
-
-**Valid layers**: `presentation`, `business`, `data`, `infrastructure`, `cross-cutting`
-
-```javascript
-// ❌ WRONG
-{
-  action: "set",
-  key: "my_key",
-  value: "my_value",
-  layer: "backend"  // Invalid!
-}
-
-// ✅ CORRECT
-{
-  action: "set",
-  key: "my_key",
-  value: "my_value",
-  layer: "business"  // Valid!
-}
-```
+**Valid layers** (9 total):
+- `presentation`, `business`, `data`, `infrastructure`, `cross-cutting`
+- `documentation`, `planning`, `coordination`, `review`
 
 ### Error: "Invalid status"
 
-**Cause**: Using a status value that doesn't exist
-
-**Solution**: Use one of the 3 valid statuses
+**Valid decision statuses**: `active`, `deprecated`, `draft`
 
-**Valid statuses**: `active`, `deprecated`, `draft`
+**Valid task statuses**: `pending`, `in_progress`, `blocked`, `on_hold`, `completed`
 
 ### Error: "Batch operations are limited to 50 items maximum"
 
-**Cause**: Too many items in batch array
-
 **Solution**: Split into multiple batches of ≤50 items each
 
 ---
 
-## Search Actions Decision Tree
-
-### When to use which search action?
-
-```
-┌─────────────────────────────────────┐
-│ What do you want to search by?     │
-└──────────┬──────────────────────────┘
-           │
-           ├─ Simple filters (status, layer, tags)?
-           │  └─> Use action: "list"
-           │
-           ├─ Primarily by tags?
-           │  └─> Use action: "search_tags"
-           │      • match_mode: "AND" (all tags) or "OR" (any tag)
-           │
-           ├─ Primarily by layer?
-           │  └─> Use action: "search_layer"
-           │
-           ├─ Complex multi-filter query?
-           │  └─> Use action: "search_advanced"
-           │      • Multiple layers (OR)
-           │      • Tag combinations (AND/OR)
-           │      • Temporal filtering
-           │      • Full-text search
-           │      • Pagination
-           │
-           └─ Need version history?
-              └─> Use action: "versions"
-```
-
-### Detailed Search Comparison
-
-| Action | Use When | Key Features |
-|--------|----------|--------------|
-| **list** | Basic filtering | Simple status/layer/tag filters, no pagination |
-| **search_tags** | Tag-focused search | AND/OR logic for tags, optional status/layer |
-| **search_layer** | Layer-focused search | Get all decisions in specific layer(s) |
-| **search_advanced** | Complex queries | Full filtering, pagination, sorting, text search |
-| **versions** | History tracking | Get all versions of a specific decision |
-
----
-
-## Batch Operations Guide
-
-### Atomic vs Non-Atomic Mode
-
-**Atomic Mode** (`atomic: true`, default):
-- All succeed or all fail as a single transaction
-- If ANY item fails, entire batch is rolled back
-- Error is thrown immediately on first failure
-- Use for: Critical operations requiring consistency
-
-**Non-Atomic Mode** (`atomic: false`, **recommended for AI agents**):
-- Each item processed independently
-- If some fail, others still succeed
-- Returns partial results with per-item success/error status
-- Use for: Best-effort batch operations, when individual failures are acceptable
-
-### Batch Operation Examples
-
-#### Decision Batch (Recommended: atomic: false)
-
-```javascript
-{
-  action: "set_batch",
-  atomic: false,  // Recommended for AI agents
-  decisions: [
-    {
-      key: "feature-1",
-      value: "Implemented user authentication",
-      layer: "business",
-      tags: ["feature", "auth"],
-      status: "active"
-    },
-    {
-      key: "feature-2",
-      value: "Added rate limiting",
-      layer: "infrastructure",
-      tags: ["feature", "security"],
-      status: "active"
-    }
-  ]
-}
-```
-
-**Response Format:**
-```json
-{
-  "success": true,
-  "inserted": 2,
-  "failed": 0,
-  "results": [
-    {
-      "key": "feature-1",
-      "key_id": 123,
-      "version": "1.0.0",
-      "success": true
-    },
-    {
-      "key": "feature-2",
-      "key_id": 124,
-      "version": "1.0.0",
-      "success": true
-    }
-  ]
-}
-```
-
-#### Message Batch
-
-```javascript
-{
-  action: "send_batch",
-  atomic: false,
-  messages: [
-    {
-      from_agent: "bot1",
-      msg_type: "info",
-      message: "Task 1 completed",
-      priority: "medium"
-    },
-    {
-      from_agent: "bot1",
-      msg_type: "info",
-      message: "Task 2 completed",
-      priority: "medium"
-    }
-  ]
-}
-```
-
-#### File Change Batch
-
-```javascript
-{
-  action: "record_batch",
-  atomic: false,
-  file_changes: [
-    {
-      file_path: "src/types.ts",
-      agent_name: "refactor-bot",
-      change_type: "modified",
-      layer: "data"
-    },
-    {
-      file_path: "src/index.ts",
-      agent_name: "refactor-bot",
-      change_type: "modified",
-      layer: "infrastructure"
-    }
-  ]
-}
-```
-
-### Batch Limits
-
-- **Maximum items per batch**: 50
-- **Recommended batch size**: 10-20 (for readability and debugging)
-- **Token savings**: ~52% vs individual calls
-
----
-
-## Template System
-
-### What are Templates?
-
-Templates provide reusable defaults for common decision patterns.
-
-### Built-in Templates
-
-1. **breaking_change**: Breaking API/interface changes
-2. **security_vulnerability**: Security issues
-3. **performance_optimization**: Performance improvements
-4. **deprecation**: Deprecation notices
-5. **architecture_decision**: Major architectural decisions
-
-### Using Templates
-
-```javascript
-{
-  action: "set_from_template",
-  template: "breaking_change",
-  key: "oscillator-type-moved",
-  value: "oscillator_type moved to MonophonicSynthConfig",
-  // Optional overrides:
-  tags: ["migration", "v0.3.3"],
-  status: "active"
-}
-```
-
-### Template vs Direct Parameters
-
-**When to use `set_from_template`**:
-- You have a common decision pattern
-- You want consistent metadata (tags, status, layer)
-- You want to enforce required fields
-
-**When to use `set`**:
-- One-off decisions
-- Unique metadata requirements
-- Full control over all parameters
-
-### Creating Custom Templates
-
-```javascript
-{
-  action: "create_template",
-  name: "bug_fix",
-  defaults: {
-    layer: "business",
-    tags: ["bug", "fix"],
-    status: "active"
-  },
-  required_fields: ["version"],
-  created_by: "my-agent"
-}
-```
-
-### Listing Templates
-
-```javascript
-{
-  action: "list_templates"
-}
-```
-
----
-
-## Multi-Step Workflow Examples
-
-This section demonstrates comprehensive multi-agent workflows using multiple tools in coordination.
-
-### Workflow 1: Multi-Agent Feature Implementation
-
-**Scenario**: Orchestrator agent coordinates 3 sub-agents to implement a new authentication feature.
-
-#### Step 1: Orchestrator Creates Plan
-
-```javascript
-// 1. Record the architecture decision
-{
-  action: "set",
-  key: "auth_v2_implementation",
-  value: "Implement OAuth2 + JWT refresh token system",
-  layer: "business",
-  tags: ["auth", "feature", "v2.0.0"],
-  agent: "orchestrator-agent"
-}
-
-// 2. Add architectural constraints
-{
-  action: "add",
-  category: "architecture",
-  constraint_text: "All auth tokens must expire within 15 minutes",
-  priority: "critical",
-  layer: "business",
-  tags: ["auth", "security"]
-}
-
-// 3. Create tasks for each sub-agent
-{
-  action: "create_batch",
-  atomic: false,
-  tasks: [
-    {
-      title: "Implement OAuth2 provider integration",
-      assigned_agent: "backend-agent",
-      layer: "business",
-      priority: 4,
-      tags: ["auth", "oauth2"],
-      status: "todo"
-    },
-    {
-      title: "Create JWT token refresh endpoint",
-      assigned_agent: "api-agent",
-      layer: "presentation",
-      priority: 4,
-      tags: ["auth", "api"],
-      status: "todo"
-    },
-    {
-      title: "Update auth database schema",
-      assigned_agent: "db-agent",
-      layer: "data",
-      priority: 4,
-      tags: ["auth", "database"],
-      status: "todo"
-    }
-  ]
-}
-
-// 4. Broadcast start message
-{
-  action: "send",
-  from_agent: "orchestrator-agent",
-  to_agent: null,  // Broadcast
-  msg_type: "info",
-  message: "Starting OAuth2 + JWT implementation - check your assigned tasks",
-  priority: "high"
-}
-```
-
-#### Step 2: Backend Agent Executes Task
-
-```javascript
-// 1. Mark task as in progress
-{
-  action: "move",
-  task_id: 1,
-  new_status: "in_progress"
-}
-
-// 2. Record file changes
-{
-  action: "record_batch",
-  atomic: false,
-  file_changes: [
-    {
-      file_path: "src/auth/oauth2.ts",
-      agent_name: "backend-agent",
-      change_type: "created",
-      layer: "business",
-      description: "OAuth2 provider integration"
-    },
-    {
-      file_path: "src/auth/jwt.ts",
-      agent_name: "backend-agent",
-      change_type: "modified",
-      layer: "business",
-      description: "Added refresh token logic"
-    }
-  ]
-}
-
-// 3. Report completion
-{
-  action: "send",
-  from_agent: "backend-agent",
-  to_agent: "orchestrator-agent",
-  msg_type: "info",
-  message: "OAuth2 provider integration complete",
-  priority: "medium",
-  payload: {
-    files_changed: 2,
-    tests_passing: true
-  }
-}
-
-// 4. Complete task
-{
-  action: "move",
-  task_id: 1,
-  new_status: "done"
-}
-```
-
-#### Step 3: Orchestrator Monitors Progress
-
-```javascript
-// 1. Check for updates (efficient polling)
-{
-  action: "has_updates",
-  agent_name: "orchestrator-agent",
-  since_timestamp: "2025-10-17T10:00:00Z"
-}
-
-// 2. Get task status
-{
-  action: "list",
-  tags: ["auth"],
-  assigned_agent: null  // All agents
-}
-
-// 3. Get unread messages
-{
-  action: "get",
-  agent_name: "orchestrator-agent",
-  unread_only: true,
-  priority_filter: "high"
-}
-
-// 4. Check constraints compliance
-{
-  action: "get",
-  category: "architecture",
-  layer: "business",
-  tags: ["auth"]
-}
-```
-
----
-
-### Workflow 2: Breaking Change Migration
-
-**Scenario**: API endpoint is being deprecated and migrated to a new version.
-
-#### Phase 1: Announce Deprecation
-
-```javascript
-// 1. Record deprecation decision
-{
-  action: "set_from_template",
-  template: "deprecation",
-  key: "api_v1_users_endpoint_deprecated",
-  value: "/v1/users endpoint deprecated, use /v2/users instead",
-  layer: "presentation",
-  tags: ["api", "deprecation", "v2.0.0"]
-}
-
-// 2. Add migration constraint
-{
-  action: "add",
-  category: "architecture",
-  constraint_text: "All new API endpoints must use /v2 prefix",
-  priority: "high",
-  layer: "presentation",
-  tags: ["api", "migration"]
-}
-
-// 3. Create migration task
-{
-  action: "create",
-  title: "Update all client integrations to use /v2/users",
-  description: "Migrate existing integrations before v1 sunset on 2025-12-01",
-  acceptance_criteria: "All clients successfully calling /v2/users with no errors",
-  layer: "presentation",
-  priority: 3,
-  tags: ["migration", "client"],
-  status: "todo"
-}
-
-// 4. Broadcast warning to all agents
-{
-  action: "send",
-  from_agent: "api-agent",
-  to_agent: null,  // Broadcast
-  msg_type: "warning",
-  message: "/v1/users DEPRECATED - Migrate to /v2/users by Dec 1",
-  priority: "critical",
-  payload: {
-    old_endpoint: "/v1/users",
-    new_endpoint: "/v2/users",
-    sunset_date: "2025-12-01"
-  }
-}
-```
-
-#### Phase 2: Track Migration Progress
-
-```javascript
-// 1. Check file lock before editing
-{
-  action: "check_lock",
-  file_path: "src/api/routes.ts",
-  lock_duration: 300  // 5 minutes
-}
-
-// 2. Record migration changes
-{
-  action: "record",
-  file_path: "src/api/routes.ts",
-  agent_name: "migration-agent",
-  change_type: "modified",
-  layer: "presentation",
-  description: "Added /v2/users endpoint with backwards compatibility"
-}
-
-// 3. Link task to decision and constraint
-{
-  action: "link",
-  task_id: 1,
-  link_type: "decision",
-  target_id: "api_v1_users_endpoint_deprecated",
-  link_relation: "implements"
-}
-
-{
-  action: "link",
-  task_id: 1,
-  link_type: "constraint",
-  target_id: 1,  // The migration constraint ID
-  link_relation: "satisfies"
-}
-
-// 4. Update task status
-{
-  action: "move",
-  task_id: 1,
-  new_status: "waiting_review"
-}
-```
-
-#### Phase 3: Complete Migration
-
-```javascript
-// 1. Record completion decision
-{
-  action: "set",
-  key: "api_v2_migration_complete",
-  value: "All clients successfully migrated to /v2/users endpoint",
-  layer: "presentation",
-  tags: ["api", "migration", "complete"],
-  status: "active"
-}
-
-// 2. Deactivate old constraint
-{
-  action: "deactivate",
-  constraint_id: 1
-}
-
-// 3. Archive completed task
-{
-  action: "archive",
-  task_id: 1
-}
-
-// 4. Notify stakeholders
-{
-  action: "send",
-  from_agent: "migration-agent",
-  to_agent: null,  // Broadcast
-  msg_type: "info",
-  message: "Migration to /v2/users complete - /v1 endpoint can be removed",
-  priority: "high"
-}
-```
-
----
-
-### Workflow 3: Session Continuity (Cross-Session Context)
-
-**Scenario**: Agent needs to resume work after restart or handoff to another agent.
-
-#### Agent A: Record Context Before Exit
-
-```javascript
-// 1. Save current work state
-{
-  action: "set",
-  key: "refactor_session_state",
-  value: "Completed 3/5 modules - currently working on auth module",
-  layer: "business",
-  tags: ["refactor", "session-state"],
-  scopes: ["auth-module"],
-  agent: "refactor-agent-a"
-}
-
-// 2. Update task with notes
-{
-  action: "update",
-  task_id: 42,
-  notes: "Paused at auth/oauth2.ts line 145 - need to review token refresh logic before proceeding"
-}
+## Key Parameters Quick Reference
 
-// 3. Record last file changes
-{
-  action: "record_batch",
-  atomic: false,
-  file_changes: [
-    {
-      file_path: "src/auth/oauth2.ts",
-      agent_name: "refactor-agent-a",
-      change_type: "modified",
-      layer: "business",
-      description: "WIP: Token refresh refactoring (incomplete)"
-    }
-  ]
-}
-
-// 4. Send handoff message
-{
-  action: "send",
-  from_agent: "refactor-agent-a",
-  to_agent: "refactor-agent-b",
-  msg_type: "request",
-  message: "Handing off refactor task - see task #42 for context",
-  priority: "high",
-  payload: {
-    task_id: 42,
-    last_file: "src/auth/oauth2.ts",
-    completion: "60%"
-  }
-}
-```
-
-#### Agent B: Resume Work
-
-```javascript
-// 1. Retrieve session state
-{
-  action: "get",
-  key: "refactor_session_state"
-}
-
-// 2. Get task details and history
-{
-  action: "get",
-  task_id: 42
-}
-
-// 3. Check recent file changes
-{
-  action: "get",
-  file_path: "src/auth/oauth2.ts",
-  since: "2025-10-17T00:00:00Z"
-}
-
-// 4. Check for any related constraints
-{
-  action: "get",
-  layer: "business",
-  tags: ["auth"],
-  active_only: true
-}
-
-// 5. Check messages
-{
-  action: "get",
-  agent_name: "refactor-agent-b",
-  unread_only: true
-}
+### decision tool
 
-// 6. Acknowledge handoff
-{
-  action: "send",
-  from_agent: "refactor-agent-b",
-  to_agent: "refactor-agent-a",
-  msg_type: "info",
-  message: "Handoff received - resuming work on task #42",
-  priority: "medium"
-}
-
-// 7. Move task to in_progress
-{
-  action: "move",
-  task_id: 42,
-  new_status: "in_progress"
-}
-```
-
----
-
-### Workflow 4: Update Polling Pattern (Efficient Subscription)
-
-**Scenario**: Monitor agent watches for specific changes and reacts accordingly.
-
-#### Monitor Agent: Efficient Polling Loop
-
-```javascript
-// Initial timestamp
-let lastCheck = "2025-10-17T10:00:00Z";
-
-// Polling function (call every 30 seconds)
-async function pollForUpdates() {
-  // 1. Lightweight check for ANY updates (5-10 tokens)
-  const updates = await {
-    action: "has_updates",
-    agent_name: "monitor-agent",
-    since_timestamp: lastCheck
-  };
-
-  // Response: {
-  //   has_updates: true,
-  //   counts: {decisions: 2, messages: 3, files: 1, tasks: 1}
-  // }
-
-  if (!updates.has_updates) {
-    // Nothing changed - skip heavy queries
-    return;
-  }
-
-  // 2. Only fetch if updates detected
-  if (updates.counts.messages > 0) {
-    const messages = await {
-      action: "get",
-      agent_name: "monitor-agent",
-      unread_only: true,
-      priority_filter: "critical"
-    };
-
-    // Process critical messages
-    for (const msg of messages.messages) {
-      if (msg.msg_type === "warning") {
-        // Handle warning
-        await handleWarning(msg);
-      }
-    }
-  }
-
-  // 3. Check for task updates
-  if (updates.counts.tasks > 0) {
-    const tasks = await {
-      action: "list",
-      status: "blocked",
-      limit: 10
-    };
-
-    // Alert on blocked tasks
-    if (tasks.length > 0) {
-      await {
-        action: "send",
-        from_agent: "monitor-agent",
-        to_agent: "orchestrator-agent",
-        msg_type: "warning",
-        message: `${tasks.length} tasks are blocked - requires attention`,
-        priority: "high"
-      };
-    }
-  }
-
-  // 4. Check for breaking changes
-  if (updates.counts.decisions > 0) {
-    const breaking = await {
-      action: "search_tags",
-      tags: ["breaking-change"],
-      match_mode: "AND",
-      status: "active"
-    };
-
-    if (breaking.length > 0) {
-      // Alert on breaking changes
-      await {
-        action: "send",
-        from_agent: "monitor-agent",
-        to_agent: null,  // Broadcast
-        msg_type: "warning",
-        message: "New breaking changes detected - review required",
-        priority: "critical"
-      };
-    }
-  }
-
-  // 5. Update last check timestamp
-  lastCheck = new Date().toISOString();
-}
-
-// Token efficiency:
-// - No updates: ~10 tokens (has_updates only)
-// - With updates: ~50-200 tokens (selective fetching)
-// - vs polling all data: ~500-1000 tokens every time
-```
-
-#### Activity Log Analysis
-
-```javascript
-// Monitor can also analyze activity patterns
-{
-  action: "activity_log",
-  since: "1h",  // Last hour
-  agent_names: ["*"],  // All agents
-  actions: ["set", "send", "create"],  // Specific actions
-  limit: 100
-}
-
-// Response shows all activity:
-// [
-//   {
-//     timestamp: "2025-10-17T11:45:23Z",
-//     agent_name: "backend-agent",
-//     action: "set",
-//     table: "decisions",
-//     key_or_details: "auth_implementation_complete"
-//   },
-//   {
-//     timestamp: "2025-10-17T11:44:15Z",
-//     agent_name: "api-agent",
-//     action: "send",
-//     table: "messages",
-//     key_or_details: "message_id:145"
-//   }
-// ]
-
-// Use this for:
-// - Debugging agent behavior
-// - Audit trails
-// - Performance monitoring
-// - Detecting stuck agents (no activity)
-```
-
-#### Automatic Cleanup Trigger
-
-```javascript
-// Monitor can also manage database health
-{
-  action: "db_stats"
-}
-
-// Response:
-// {
-//   agents: 5,
-//   files: 42,
-//   context_keys: 156,
-//   active_decisions: 312,
-//   total_decisions: 342,
-//   messages: 1203,
-//   file_changes: 589,
-//   active_constraints: 12,
-//   total_constraints: 15,
-//   tags: 10,
-//   scopes: 8,
-//   layers: 5,
-//   total_tasks: 47,
-//   active_tasks: 23,  // Excludes done and archived
-//   tasks_by_status: {
-//     todo: 15,
-//     in_progress: 5,
-//     waiting_review: 3,
-//     blocked: 0,
-//     done: 20,
-//     archived: 4
-//   },
-//   tasks_by_priority: {
-//     low: 10,
-//     medium: 25,
-//     high: 10,
-//     critical: 2
-//   }
-// }
-
-// If database too large, trigger cleanup
-if (stats.total_messages > 1000) {
-  await {
-    action: "clear",
-    messages_older_than_hours: 24,
-    file_changes_older_than_days: 7
-  };
-
-  // Notify about cleanup
-  await {
-    action: "send",
-    from_agent: "monitor-agent",
-    to_agent: null,
-    msg_type: "info",
-    message: "Database cleanup completed - removed old messages and file history",
-    priority: "low"
-  };
-}
-```
-
----
-
-## Best Practices
-
-### 1. Always Use `action` Parameter
-
-**Never forget to include `action`** - it's required in ALL tool calls.
-
-### 2. Use `atomic: false` for Batch Operations
-
-Unless you specifically need all-or-nothing guarantees, use `atomic: false` to avoid transaction failures from validation errors.
-
-### 3. Choose the Right Search Action
-
-- Simple queries → `list`
-- Tag-focused → `search_tags`
-- Complex multi-filter → `search_advanced`
-
-### 4. Use Templates for Common Patterns
-
-If you're repeatedly setting decisions with the same metadata, create a template.
-
-### 5. Provide Meaningful Tags
-
-Tags are crucial for searchability. Use descriptive, consistent tag naming:
-
-```javascript
-// ✅ GOOD
-tags: ["authentication", "security", "jwt", "v1.2.0"]
-
-// ❌ BAD
-tags: ["stuff", "important", "thing"]
-```
-
-### 6. Always Specify `layer` for Decisions
-
-Layer classification helps organize architectural concerns.
-
-💡 **See [ARCHITECTURE.md](ARCHITECTURE.md#layers) for detailed layer definitions and usage examples.**
-
-Quick reference:
-- **presentation**: UI, API endpoints, user-facing interfaces
-- **business**: Service logic, workflows, business rules
-- **data**: Database models, schemas, data access
-- **infrastructure**: Configuration, deployment, DevOps
-- **cross-cutting**: Logging, monitoring, security (affects multiple layers)
-
-### 7. Use `has_updates` for Efficient Polling
-
-Instead of fetching all data repeatedly, check for updates first:
-
-```javascript
-// Check if anything changed
-{
-  action: "has_updates",
-  agent_name: "my-agent",
-  since_timestamp: "2025-10-15T08:00:00Z"
-}
-
-// Response: {has_updates: true, counts: {decisions: 5, messages: 2, files: 3}}
-
-// Only fetch if has_updates is true
-```
-
-Token cost: ~5-10 tokens per check vs full data retrieval.
-
-### 8. Handle Errors Gracefully
-
-All tools return JSON responses. Check for `error` field:
-
-```javascript
-// Response format
-{
-  "error": "Invalid layer: backend"
-}
-
-// Success format
-{
-  "success": true,
-  "key": "my_key",
-  ...
-}
-```
-
-### 9. Use Constraints for Requirements
-
-**Constraint** vs **Decision**:
-
-- **Decision**: "We chose PostgreSQL" (a choice that was made)
-- **Constraint**: "Response time must be <100ms" (a requirement to follow)
+| Action | Required | Optional |
+|--------|----------|----------|
+| **set** | action, key, value, layer | version, status, tags, scopes |
+| **get** | action, key | version |
+| **list** | action | status, layer, tags, limit |
 
-```javascript
-{
-  action: "add",
-  category: "performance",
-  constraint_text: "API response time must be under 100ms",
-  priority: "critical",
-  layer: "business",
-  tags: ["api", "performance"]
-}
-```
+### task tool
 
-### 10. Clean Up Old Data Regularly
+| Action | Required | Optional |
+|--------|----------|----------|
+| **create** | action, title | description, priority, layer, tags, status |
+| **move** | action, task_id, status | - |
+| **list** | action | status, layer, tags, limit |
 
-Use the `clear` action to prevent database bloat:
+### constraint tool
 
-```javascript
-// Manual cleanup
-{
-  action: "clear",
-  messages_older_than_hours: 48,
-  file_changes_older_than_days: 14
-}
+| Action | Required | Optional |
+|--------|----------|----------|
+| **add** | action, category, constraint_text | priority, layer, tags |
+| **get** | action | category, layer, active_only |
 
-// Or rely on auto-cleanup (configured via config tool)
-{
-  action: "update",
-  ignoreWeekend: true,
-  messageRetentionHours: 24,
-  fileHistoryRetentionDays: 7
-}
-```
+> **Full parameter reference**: See [TOOL_REFERENCE.md](TOOL_REFERENCE.md)
 
 ---
 
-## Troubleshooting Checklist
+## Best Practices Summary
 
-Before asking for help, check:
+1. **Always include `action` parameter** - #1 error source
+2. **Use `atomic: false` for batch operations** - Avoid all-or-nothing failures
+3. **Always specify `layer`** - Required for organization
+4. **Use meaningful tags** - Critical for searchability
+5. **Use `status` (not `new_status`)** for task.move action
 
-1. ✅ Did you include the `action` parameter?
-2. ✅ Are all required parameters provided?
-3. ✅ Are enum values spelled correctly? (layer, status, msg_type, etc.)
-4. ✅ For templates: Are you passing parameters directly (not in `defaults`)?
-5. ✅ For batch operations: Is array size ≤50?
-6. ✅ For timestamps: Are you using ISO 8601 format?
+> **Detailed best practices**: See [BEST_PRACTICES.md](BEST_PRACTICES.md)
 
 ---
 
-## Need More Help?
-
-### Built-In Documentation (Zero Token Cost)
+## Built-In Documentation
 
-All tools provide comprehensive built-in documentation with zero upfront token cost:
+All tools provide built-in help with zero token cost:
 
-**Help Action** - Detailed reference documentation:
 ```javascript
 // Get detailed help for any tool
-{
-  action: "help"
-}
-```
+{ action: "help" }
 
-Returns:
-- All actions and their parameters
-- Quick examples for each action
-- Valid values for enum parameters
-- Behavior descriptions
-- Links to external documentation
-
-**Example Action** - Comprehensive usage scenarios (v3.0.1):
-```javascript
-// Get comprehensive examples for any tool
-{
-  action: "example"
-}
+// Get comprehensive examples
+{ action: "example" }
 ```
 
-Returns:
-- Real-world usage scenarios by category
-- Multi-step workflows
-- Best practices specific to the tool
-- Common patterns and anti-patterns
-- Works offline without WebFetch
+---
 
-### When to Use Each
+## Related Documentation
 
-| Use | Action | What You Get |
-|-----|--------|--------------|
-| Quick parameter reference | `help` | Action list, parameters, quick examples |
-| Comprehensive examples | `example` | Detailed scenarios, workflows, best practices |
-| Specific implementation patterns | `example` | Category-based examples (e.g., performance constraints, batch operations) |
+| Document | Content |
+|----------|---------|
+| [TOOL_REFERENCE.md](TOOL_REFERENCE.md) | Complete parameter reference |
+| [WORKFLOWS.md](WORKFLOWS.md) | Multi-step workflow examples |
+| [BEST_PRACTICES.md](BEST_PRACTICES.md) | Detailed best practices |
+| [DECISION_INTELLIGENCE.md](DECISION_INTELLIGENCE.md) | Decision duplicate detection |
+| [CONSTRAINT_INTELLIGENCE.md](CONSTRAINT_INTELLIGENCE.md) | Constraint duplicate detection |
+| [BATCH_VALIDATION.md](BATCH_VALIDATION.md) | Batch operations guide |
+| [ARCHITECTURE.md](ARCHITECTURE.md) | System architecture |
 
 ---
 
-## Summary: Most Common Mistakes
+## Most Common Mistakes
 
 1. **Missing `action` parameter** ← #1 error!
-2. Using `defaults` instead of direct parameters with templates
-3. Invalid layer/status/priority values (use exact strings)
-4. Forgetting to specify `layer` when setting decisions
-5. Using `atomic: true` by default in batch operations (use `false`)
-6. Using wrong search action (`list` vs `search_tags` vs `search_advanced`)
-7. Empty arrays in batch operations
-8. Typos in parameter names (e.g., `messsage` instead of `message`)
-
----
+2. Invalid layer/status values
+3. Forgetting to specify `layer` when setting decisions
+4. Using `atomic: true` by default in batch operations
+5. Using `new_status` instead of `status` for task.move
 
-**Remember**: When in doubt, call `{action: "help"}` for parameters or `{action: "example"}` for comprehensive usage scenarios!
+**When in doubt**: Call `{action: "help"}` or `{action: "example"}`!