┌─────────────────────────────────────────────────────────┐
│                    CLI Startup                          │
└─────────────────────┬───────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────┐
│              UpdateChecker Service                       │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐ │
│  │ RateLimiter │  │ NPM Registry│  │ Version Compare │ │
│  │ (24h cache) │  │    Client   │  │    (semver)     │ │
│  └─────────────┘  └─────────────┘  └─────────────────┘ │
└─────────────────────┬───────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────┐
│              PackageValidator                            │
│  - Dependency compatibility check                        │
│  - Peer dependency verification                          │
│  - Breaking change detection                             │
└─────────────────────┬───────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────┐
│              UpdateExecutor                              │
│  - npm install with specific versions                    │
│  - Rollback on failure                                   │
│  - Update history logging                                │
└─────────────────────────────────────────────────────────┘

interface UpdateCheckResult {
  package: string;
  currentVersion: string;
  latestVersion: string;
  updateType: 'major' | 'minor' | 'patch' | 'none';
  shouldAutoUpdate: boolean;
  changelog?: string;
}

interface UpdateConfig {
  enabled: boolean;
  checkIntervalHours: number;  // Default: 24
  autoUpdatePatch: boolean;    // Default: true
  autoUpdateMinor: boolean;    // Default: false
  autoUpdateMajor: boolean;    // Default: false
  excludePackages: string[];   // Packages to skip
  priorityPackages: string[];  // Check these first
}

interface RateLimitState {
  lastCheck: string;           // ISO timestamp
  checksToday: number;
  packageVersions: Record<string, string>;
}

// Stored in: ~/.claude-flow/update-state.json

interface ValidationResult {
  valid: boolean;
  incompatibilities: string[];
  warnings: string[];
  requiredPeerUpdates: string[];
}

1. CLI Start
   │
   ├─► Check rate limit cache (~/.claude-flow/update-state.json)
   │   └─► If checked within 24h AND no --force-update → Skip
   │
   ├─► Query npm registry for @claude-flow/* packages
   │   └─► Compare versions using semver
   │
   ├─► For each package with available update:
   │   ├─► Check update priority (critical/high/normal/low)
   │   ├─► Validate compatibility with other packages
   │   └─► Determine if auto-update applies
   │
   ├─► Execute auto-updates (if any)
   │   ├─► npm install @claude-flow/package@version
   │   ├─► Verify installation success
   │   └─► Log to update history
   │
   └─► Display notification for non-auto updates
       └─► "Run `npx claude-flow update` to update X packages"

# Check for updates (manual)
npx claude-flow update check

# Update all packages
npx claude-flow update all

# Update specific package
npx claude-flow update @claude-flow/embeddings

# View update history
npx claude-flow update history

# Rollback last update
npx claude-flow update rollback

# Configure auto-update
npx claude-flow config set update.autoUpdateMinor true
npx claude-flow config set update.checkIntervalHours 12

# Disable auto-update entirely
CLAUDE_FLOW_AUTO_UPDATE=false

# Force update check
CLAUDE_FLOW_FORCE_UPDATE=true

# CI/CD mode (no interactive prompts, no auto-update)
CI=true

// claude-flow.config.json
{
  "update": {
    "enabled": true,
    "checkIntervalHours": 24,
    "autoUpdate": {
      "patch": true,
      "minor": false,
      "major": false
    },
    "priority": {
      "@claude-flow/security": "critical",
      "@claude-flow/cli": "high",
      "@claude-flow/embeddings": "normal",
      "@claude-flow/integration": "normal",
      "@claude-flow/testing": "low"
    },
    "exclude": []
  }
}