AI agent should prefer fan-out model methods over shell loops for fleet operations

Problem Statement

When an AI agent (e.g. Claude Code) is asked to run a command across a fleet of VMs, it defaults to generating a shell loop that spawns N separate swamp model method run ... exec CLI invocations — one per VM. This causes:

1. Datastore lock contention — each CLI invocation acquires the datastore lock, so parallel runs timeout waiting on the lock (e.g. 45 out of 50 calls fail with Lock ... timed out after 60180ms)
2. Redundant discovery — each exec call independently runs discoverVms(), making N identical kubectl calls
3. Poor UX — the user has to wait for lock timeouts and retry, or manually discover that execAll exists

This happened in practice: the user asked to "check all jenkins workers in prod" and the agent tried to run 50 parallel swamp model method run prod-vms exec CLI invocations instead of a single swamp model method run prod-vms execAll --input '{"filter":"jenkins-worker", ...}'.

Proposed Solution

Improve discoverability of fan-out methods so AI agents (and users) find them before resorting to shell loops:

1. Model type metadata: Add a fleetAware: true flag or fanOutMethods field to model type descriptions, so swamp model type describe makes it obvious which methods handle multiple targets internally.
2. CLI hint: When exec is called with a filter that matches multiple VMs but only executes on one, emit a hint: "Hint: Use 'execAll' to run across all matching VMs".
3. Skill/documentation: Update the swamp-model skill to mention that fleet-aware models (like @bixu/kubevirt-vm) have execAll, checkService, and healthCheck methods that fan out internally with built-in concurrency control.

Alternatives Considered

• Smarter locking: Allow concurrent reads or use per-model locks instead of a global datastore lock. This would help but doesn't address the redundant discovery or UX issues.
• Agent-side heuristic: Teach the AI agent to always check for *All or fleet methods before looping. This is fragile and puts the burden on every agent integration.

Summary

Changes would be needed in:

• Model type schema to support fleet-awareness metadata
• CLI output to emit hints when a single-target method is used on a multi-target filter
• Skill documentation (swamp-model) to document fleet patterns

The approach is to make fan-out methods discoverable at the type description level so both humans and AI agents naturally find the right method for fleet operations.