# GodotIQ v2 — The Definitive MCP for AI-Assisted Godot Development

## Vision

GodotIQ is not a "helper" MCP. It is THE tool that makes AI agents competent Godot developers. It replaces the need for any other Godot MCP by combining an intelligent bridge (editor control, screenshots, run/stop) with deep project understanding (spatial reasoning, dependency analysis, animation comprehension, convention enforcement).

**One install. One product. Everything an AI agent needs to work with Godot like a human would.**

```
Before GodotIQ:
  Agent: "I'll move this node to (2, 0, 0)"
  Result: Inside a wall. 10 iterations to fix.

After GodotIQ:
  Agent calls godotiq_scene_map → knows walls, floors, navmesh, nearby objects
  Agent calls godotiq_move_node → validated placement, first try
  Agent calls godotiq_verify_scene → confirms no anomalies
  Done.
```

---

## Architecture

```
┌──────────────────────────────────────────────────────────────────┐
│                    AI Agent (Claude Code / Cursor / Windsurf)     │
│                                                                   │
│    "Move shelf near printer"    "Why do workers get stuck?"       │
│              │                            │                       │
│              ▼                            ▼                       │
│  ┌─────────────────────────────────────────────────────────┐     │
│  │                    GodotIQ MCP Server                     │     │
│  │                                                           │     │
│  │  ┌─────────────┐ ┌──────────────┐ ┌──────────────────┐  │     │
│  │  │ BRIDGE LAYER│ │ INTELLIGENCE │ │ MEMORY LAYER     │  │     │
│  │  │ (enhanced)  │ │ LAYER        │ │                  │  │     │
│  │  │             │ │              │ │ • project state  │  │     │
│  │  │ • smart     │ │ • spatial    │ │ • file hashes    │  │     │
│  │  │   screenshot│ │   reasoning  │ │ • diff tracking  │  │     │
│  │  │ • scene ops │ │ • dependency │ │ • session cache  │  │     │
│  │  │ • run/debug │ │   graph      │ │ • conventions    │  │     │
│  │  │ • node edit │ │ • animation  │ │ • asset catalog  │  │     │
│  │  │ • input sim │ │   analysis   │ │                  │  │     │
│  │  │ • file ops  │ │ • flow trace │ │                  │  │     │
│  │  └──────┬──────┘ └──────┬───────┘ └────────┬─────────┘  │     │
│  │         │               │                   │            │     │
│  │         ▼               ▼                   ▼            │     │
│  │  ┌──────────────────────────────────────────────────┐    │     │
│  │  │            TOKEN OPTIMIZER                        │    │     │
│  │  │  • progressive detail (brief/normal/full)        │    │     │
│  │  │  • diff-based responses (only what changed)      │    │     │
│  │  │  • smart filtering (only relevant nodes)         │    │     │
│  │  │  • batched operations (1 call = 5 actions)       │    │     │
│  │  └──────────────────────────────────────────────────┘    │     │
│  └──────────────────────┬────────────────────────────────────┘     │
│                         │                                         │
│              ┌──────────┴──────────┐                              │
│              │   Godot Editor      │                              │
│              │   (EditorPlugin +   │                              │
│              │    WebSocket/TCP)   │                              │
│              └─────────────────────┘                              │
└──────────────────────────────────────────────────────────────────┘
```

### Communication Layer

GodotIQ needs a Godot addon for runtime bridge capabilities (screenshot, run, input simulation). But unlike GDAI's minimal addon, ours is an **intelligent observer** that also:
- Monitors performance metrics continuously
- Tracks animation states
- Watches for runtime errors and warnings
- Reports navigation mesh issues in real-time
- Detects visual anomalies (z-fighting, clipping, overdraw)

**Addon ↔ MCP communication:** WebSocket (allows bidirectional, real-time data)
**MCP ↔ Agent communication:** stdio (standard MCP transport)

The intelligence layer (parsing .gd/.tscn, dependency graph, conventions) works WITHOUT the addon — pure filesystem analysis. The addon adds runtime superpowers.

---

## Token Optimization Strategy

Every tool response follows these principles:

### 1. Progressive Detail Levels
Every tool accepts `detail: "brief" | "normal" | "full"`

```
brief  → 5-15 lines, key facts only, for quick checks
normal → 30-80 lines, structured data, for most operations  
full   → 100+ lines, complete dump, for deep debugging
```

Default is "normal". Agent can request "brief" for routine checks, "full" for debugging.

### 2. Diff-Based Responses
After first call, GodotIQ hashes everything. Second call returns ONLY what changed.

```
First call:  godotiq_scene_map("main.tscn")     → full spatial map (800 tokens)
Second call: godotiq_scene_map("main.tscn")     → "No changes since last scan" (10 tokens)
After edit:  godotiq_scene_map("main.tscn")     → only changed nodes (50 tokens)
```

### 3. Smart Filtering
Scene with 200 nodes? Don't return all 200. Return:
- Nodes within radius of focus_node (if specified)
- Nodes matching type filter
- Nodes with anomalies (always flagged regardless of filter)

### 4. Compact Output Format
```
// NOT this (verbose, wastes tokens):
{
  "node_name": "StorageShelf",
  "node_type": "Node3D",
  "position_x": 1.2,
  "position_y": 0.0,
  "position_z": -0.5
}

// THIS (compact, same information):
{
  "n": "StorageShelf",
  "t": "Node3D", 
  "p": [1.2, 0, -0.5]
}
```

Agent-facing output uses full names. Internal transfer uses compact format.

### 5. Batched Operations
One tool call does what would take 5 with raw MCPs:
```
// OLD WAY (5 calls, ~2000 tokens response):
get_scene_tree()
get_node("StorageShelf")
get_node("PrinterSlot_P1")
get_node("Wall_East")
get_navigation_mesh()

// GODOTIQ WAY (1 call, ~400 tokens response):
godotiq_scene_map(focus: "StorageShelf", radius: 3.0, detail: "normal")
// Returns shelf + everything around it + nav info + anomalies, pre-analyzed
```

---

## Complete Tool API

### ═══════════════════════════════════════════════
### CATEGORY A: INTELLIGENT BRIDGE (Runtime)
### ═══════════════════════════════════════════════
### Requires Godot addon running. Enhanced versions of basic bridge operations.

---

#### `A01` — `godotiq_screenshot`
Smart screenshot with optional AI-readable annotations.

```
INPUT:
{
  "viewport": "game",              // "editor", "game", "both"
  "annotate": true,                // overlay bounding boxes, node names, anomaly markers
  "focus_node": "StorageShelf",    // optional: center + highlight this node
  "highlight_issues": true,        // mark floating objects, clipping, scale anomalies
  "size": [540, 960],              // half resolution for token efficiency
  "format": "png"                  // "png" (quality) or "jpeg" (smaller)
}

OUTPUT:
{
  "image": "<base64 encoded>",
  "resolution": [540, 960],
  "annotations": [
    {"node": "StorageShelf", "screen_rect": [120, 340, 200, 420], "label": "StorageShelf [OK]"},
    {"node": "Box_Product_03", "screen_rect": [150, 200, 170, 230], "label": "⚠ FLOATING +0.9m above shelf"},
    {"node": "Printer_Tier2", "screen_rect": [80, 400, 130, 500], "label": "⚠ SCALE 50x smaller than similar"}
  ],
  "performance": {
    "fps": 58,
    "draw_calls": 34,
    "triangles": 89000
  }
}
```

**Why better than raw screenshot:** The agent sees the image AND gets structured data about what's in it and what's wrong. No guessing.


#### `A02` — `godotiq_scene_tree`
Enhanced scene tree with spatial + script + signal context per node.

```
INPUT:
{
  "root": "Main",                  // starting node
  "depth": 3,                      // tree depth
  "include": ["transform", "script", "groups", "signals", "visibility"],
  "filter_type": null,             // optional: "Node3D", "Control", "MeshInstance3D"
  "detail": "normal"
}

OUTPUT:
{
  "root": "Main",
  "total_nodes": 187,
  "returned_nodes": 42,            // filtered by depth
  "tree": [
    {
      "n": "Building", "t": "Node3D", "p": [0,0,0],
      "children": [
        {
          "n": "FDM_Bay", "t": "Node3D", "p": [0,0,-3],
          "children_count": 12,     // has more children but depth limit reached
          "has_script": false,
          "groups": ["room"]
        }
      ]
    },
    {
      "n": "Entities", "t": "Node3D",
      "children": [
        {
          "n": "Printer_1", "t": "Node3D", "p": [0.8, 0, -0.5],
          "has_script": true, "script": "res://scripts/entities/printer.gd",
          "groups": ["printers"],
          "signals_connected": 3,
          "visible": true
        }
      ]
    }
  ]
}
```


#### `A03` — `godotiq_run`
Run game with intelligent monitoring.

```
INPUT:
{
  "monitor": true,                         // enable real-time issue detection
  "auto_screenshot_on_error": true,        // capture state when errors occur
  "watch_nodes": ["Worker_1", "Van"],      // track these nodes' state changes
  "timeout_seconds": 30,                   // auto-stop after N seconds
  "performance_threshold": {
    "min_fps": 30,
    "max_draw_calls": 50,
    "max_triangles": 150000
  }
}

OUTPUT (when stopped or timeout):
{
  "ran_for_seconds": 30,
  "errors": [
    {
      "time": 3.2,
      "type": "push_error",
      "message": "Invalid product_id: 'unknown_product'",
      "source": "scripts/managers/order_manager.gd:87",
      "screenshot_id": "error_001"       // can fetch with godotiq_screenshot
    }
  ],
  "warnings": [
    {
      "time": 12.5,
      "type": "performance",
      "message": "Draw calls peaked at 52 (limit: 50)",
      "context": "After 3rd printer activated"
    }
  ],
  "watched_nodes": {
    "Worker_1": {
      "state_changes": ["IDLE → WALKING (t=1.2)", "WALKING → CARRYING (t=4.8)", "CARRYING → IDLE (t=8.1)"],
      "path_taken": [[0,0,0], [1.2,0,-0.5], [2.0,0,-1.0], [0,0,0]],
      "total_distance": 5.8
    },
    "Van": {
      "state_changes": ["PARKED → LOADING (t=15.0)", "LOADING → DRIVING (t=16.2)"],
      "visible": true
    }
  },
  "performance_summary": {
    "avg_fps": 55,
    "min_fps": 41,
    "peak_draw_calls": 52,
    "peak_triangles": 112000
  }
}
```


#### `A04` — `godotiq_input`
Simulate user input with context awareness.

```
INPUT:
{
  "action": "tap",                         // "tap", "swipe", "pinch", "long_press", "drag"
  "target": "AcceptOrderButton",           // node name, or screen coordinates [x, y]
  "wait_for": "signal:order_accepted",     // wait until this signal fires (or timeout)
  "timeout_ms": 3000
}

OUTPUT:
{
  "input_delivered": true,
  "target_found": true,
  "target_screen_pos": [270, 1400],
  "signal_received": true,
  "signal_data": {"order_id": "order_042", "product": "phone_case"},
  "side_effects": [
    "PrinterManager.printer_1 state: IDLE → RESERVED",
    "TaskManager created task: FETCH_MATERIAL for Worker_1"
  ],
  "time_ms": 450
}
```

**Why better than raw input simulation:** You don't just send a tap — you send a tap, wait for the expected result, and get confirmation of what happened system-wide. One call = tap + verify.


#### `A05` — `godotiq_node_ops`
Batch node operations with validation.

```
INPUT:
{
  "operations": [
    {
      "op": "move",
      "node": "StorageShelf",
      "position": [1.8, 0, -0.5],
      "validate": true                     // check against walls, navmesh, other objects
    },
    {
      "op": "scale",
      "node": "Printer_New",
      "scale": [0.3, 0.3, 0.3],
      "validate": true                     // check against typical scales for this asset type
    },
    {
      "op": "add_child",
      "parent": "Entities",
      "scene": "res://scenes/entities/printer.tscn",
      "name": "Printer_7",
      "position": [3.0, 0, -2.0]
    },
    {
      "op": "set_property",
      "node": "Sun",
      "property": "light_energy",
      "value": 1.2
    }
  ]
}

OUTPUT:
{
  "results": [
    {
      "op": "move", "node": "StorageShelf", "status": "OK",
      "validation": "Position valid — 0.6m from nearest wall, on navmesh, no overlap"
    },
    {
      "op": "scale", "node": "Printer_New", "status": "WARNING",
      "validation": "Scale 0.3 is within Meshy range but 40% smaller than other printers in scene (avg 0.5). Proceed?"
    },
    {
      "op": "add_child", "node": "Printer_7", "status": "OK"
    },
    {
      "op": "set_property", "node": "Sun", "status": "OK"
    }
  ],
  "scene_modified": true,
  "undo_available": true
}
```


#### `A06` — `godotiq_script_ops`
Read, write, and validate scripts.

```
INPUT:
{
  "op": "write",                           // "read", "write", "patch", "create"
  "path": "scripts/managers/new_manager.gd",
  "content": "... GDScript content ...",
  "validate_before_write": true,           // run convention check first
  "dry_run": false                         // true = validate only, don't write
}

OUTPUT:
{
  "status": "BLOCKED",
  "validation_issues": [
    {"severity": "ERROR", "rule": "class_name_suffix", "line": 1, 
     "detail": "class_name 'NewManager' → should be 'NewManagerClass'"},
    {"severity": "ERROR", "rule": "no_direct_reference", "line": 23,
     "detail": "EconomyManager.cash direct access → use signal via Events"},
    {"severity": "WARN", "rule": "type_hint", "line": 15,
     "detail": "var count → var count: int"}
  ],
  "auto_fixable": 2,                      // line 1 and 15 can be auto-fixed
  "suggestion": "Fix 2 errors before writing. Use op:'write' with auto_fix:true to apply safe fixes."
}

// With auto_fix:true:
{
  "status": "WRITTEN",
  "auto_fixes_applied": [
    "Line 1: class_name NewManager → class_name NewManagerClass",
    "Line 15: var count = 0 → var count: int = 0"
  ],
  "remaining_issues": [
    {"severity": "ERROR", "rule": "no_direct_reference", "line": 23,
     "detail": "Manual fix required: replace EconomyManager.cash with signal"}
  ]
}
```


#### `A07` — `godotiq_file_ops`
File system operations within res://.

```
INPUT:
{
  "op": "list",                    // "list", "read", "write", "move", "delete", "search"
  "path": "assets/models/",
  "recursive": true,
  "filter": "*.glb"               // glob pattern
}

// For search:
{
  "op": "search",
  "query": "order_completed",     // text search across all .gd files
  "file_types": [".gd"],
  "context_lines": 2              // lines above/below match
}
```


### ═══════════════════════════════════════════════
### CATEGORY B: SPATIAL INTELLIGENCE (3D)
### ═══════════════════════════════════════════════
### Works from filesystem (no addon needed) + enhanced with runtime data when available.

---

#### `B01` — `godotiq_scene_map`
THE killer feature. Complete spatial understanding of a scene.

```
INPUT:
{
  "scene": "scenes/main.tscn",
  "focus": "StorageShelf",             // optional: center analysis here
  "radius": 5.0,                       // meters from focus
  "include": ["transforms", "bounds", "navmesh", "lights", "markers", "rooms"],
  "detail": "normal"
}

OUTPUT:
{
  "scene": "scenes/main.tscn",
  "world_bounds": {"min": [-2, 0, -8], "max": [6, 4, 2]},
  
  "focus_node": {
    "name": "StorageShelf",
    "position": [1.2, 0, -0.5],
    "bounds": {"size": [0.8, 1.5, 0.4], "center": [1.2, 0.75, -0.5]},
    "surface_y": 0.95,                 // top surface for placing items
    "mesh": "res://assets/models/furniture/shelf_01.glb",
    "origin": "kenney",
    "scale": [1.0, 1.0, 1.0]
  },
  
  "nearby": [
    {"n": "PrinterSlot_P1", "p": [0.8, 0, -0.5], "dist": 0.6, "dir": "west", "t": "Marker3D"},
    {"n": "Wall_East", "p": [2.8, 0, -0.5], "dist": 1.6, "dir": "east", "t": "StaticBody3D"},
    {"n": "StorageShelf2", "p": [1.2, 0, -1.5], "dist": 1.0, "dir": "south", "t": "Node3D"},
    {"n": "Door_Storage", "p": [0.5, 0, 0.2], "dist": 1.0, "dir": "northwest", "t": "Node3D"}
  ],
  
  "rooms": [
    {"name": "Storage", "bounds": {"min": [0, 0, -3], "max": [3, 3, 1]}, "contains_focus": true},
    {"name": "FDM_Bay", "bounds": {"min": [0, 0, -6], "max": [3, 3, -3]}, "contains_focus": false}
  ],
  
  "navmesh": {
    "walkable_near_focus": {"min": [0.2, 0, -2.8], "max": [2.6, 0, 0.8]},
    "clear_zones": [
      {"center": [1.8, 0, -0.5], "radius": 0.8, "note": "Open space east of shelf"},
      {"center": [1.2, 0, -2.0], "radius": 0.6, "note": "Open space south of shelf"}
    ]
  },
  
  "markers": [
    {"n": "ShelfSlot_1", "p": [1.2, 0.95, -0.5], "group": "shelf_slots"},
    {"n": "ShelfSlot_2", "p": [1.2, 0.95, -0.7], "group": "shelf_slots"}
  ],
  
  "anomalies_in_radius": [
    {"n": "Box_Product_03", "issue": "floating", "severity": "high",
     "detail": "Y=1.8, no surface below. Shelf top at Y=0.95", "fix": {"p_y": 0.97}}
  ]
}
```


#### `B02` — `godotiq_placement`
Smart object placement with full constraint solving.

```
INPUT:
{
  "scene": "scenes/main.tscn",
  "object_type": "printer",               // semantic type
  "model": "res://assets/models/printers/tier3.glb",
  "model_origin": "meshy",
  "near": "PrinterSlot_P3",               // or coordinates [x, y, z]
  "constraints": {
    "on_floor": true,
    "on_navmesh": true,
    "min_wall_distance": 0.3,
    "min_object_distance": 0.4,
    "face_direction": "south",             // optional
    "inside_room": "FDM_Bay"              // optional
  }
}

OUTPUT:
{
  "suggestions": [
    {
      "position": [2.5, 0, -4.0],
      "rotation_deg": [0, 180, 0],
      "scale": [0.4, 0.4, 0.4],           // auto-calculated from model_origin + reference
      "confidence": 0.95,
      "reason": "Next to P3, facing south, 0.5m from wall, on navmesh, matches other printer scales",
      "clearance": {"N": 1.2, "S": 0.8, "E": 0.5, "W": 0.6}
    }
  ],
  "excluded_zones": [
    {"reason": "LockedZone_RnD", "bounds": [[3, -4], [5.5, -7]]},
    {"reason": "Door swing area", "center": [0.5, -3], "radius": 0.8}
  ],
  "scale_reasoning": "Meshy model. Similar printers in scene: Printer_1 at scale(0.4), Printer_2 at scale(0.45). Recommended: 0.4"
}
```


#### `B03` — `godotiq_spatial_audit`
Automated scan for ALL spatial issues in a scene.

```
INPUT:
{
  "scene": "scenes/main.tscn",
  "checks": [
    "floating_objects",          // Y > 0 with no surface below
    "clipping",                  // overlapping bounding boxes
    "inside_walls",              // objects intersecting wall geometry
    "scale_mismatch",            // scales inconsistent with asset origin
    "off_navmesh",               // objects workers can't reach
    "unreachable_markers",       // Marker3D not on navmesh
    "z_fighting",                // coplanar surfaces (same Y within 0.001)
    "empty_slots",               // Marker3D with no child objects
    "orphan_models",             // GLB loaded but not visible
    "lighting_issues"            // objects in shadow, no ambient
  ]
}

OUTPUT:
{
  "total_issues": 7,
  "critical": 2,
  "warnings": 3,
  "info": 2,
  
  "issues": [
    {
      "severity": "CRITICAL",
      "check": "floating_objects",
      "node": "Box_Product_03",
      "detail": "Y=1.8, nearest surface (StorageShelf top) at Y=0.95. Gap: 0.85m",
      "auto_fix": {"property": "position:y", "value": 0.97}
    },
    {
      "severity": "CRITICAL",
      "check": "scale_mismatch",
      "node": "Printer_Tier2",
      "detail": "Scale (0.01,0.01,0.01). Other Meshy printers avg (0.4,0.4,0.4). 40x too small.",
      "auto_fix": {"property": "scale", "value": [0.4, 0.4, 0.4]}
    },
    {
      "severity": "WARNING",
      "check": "unreachable_markers",
      "node": "ShelfSlot_7",
      "detail": "Position (6.2, 0.9, -1.0) is outside navmesh. Workers cannot path here.",
      "auto_fix": null
    },
    {
      "severity": "WARNING",
      "check": "z_fighting",
      "nodes": ["Floor_Storage", "Rug_01"],
      "detail": "Both at Y=0.0. Will flicker. Move Rug_01 to Y=0.001.",
      "auto_fix": {"node": "Rug_01", "property": "position:y", "value": 0.001}
    },
    {
      "severity": "WARNING",
      "check": "empty_slots",
      "node": "PrinterSlot_P6",
      "detail": "Marker3D with group 'printer_slots' has no children. Expected printer entity.",
      "auto_fix": null
    },
    {
      "severity": "INFO",
      "check": "orphan_models",
      "file": "assets/models/products/vase_old.glb",
      "detail": "Model file exists but not referenced in any scene.",
      "auto_fix": null
    },
    {
      "severity": "INFO",
      "check": "off_navmesh",
      "node": "Plant_Decoration_03",
      "detail": "Decoration at (5.8, 0, 1.2) outside walkable area. Likely intentional.",
      "auto_fix": null
    }
  ],
  
  "auto_fixable": 3,
  "prompt": "3 issues can be auto-fixed. Run godotiq_node_ops with the suggested fixes?"
}
```


### ═══════════════════════════════════════════════
### CATEGORY C: CODE INTELLIGENCE
### ═══════════════════════════════════════════════
### Pure filesystem analysis. No addon needed.

---

#### `C01` — `godotiq_dependency_graph`
Understand what any file touches and what touches it.

```
INPUT:
{
  "file": "scripts/managers/order_manager.gd",
  "depth": 2,
  "detail": "normal"
}

OUTPUT:
{
  "file": "scripts/managers/order_manager.gd",
  "class_name": "OrderManagerClass",
  "is_autoload": true,
  "autoload_name": "OrderManager",
  
  "emits_signals": [
    {"signal": "order_created", "listeners": [
      "scripts/ui/hud/orders_panel.gd → _on_order_created",
      "scripts/systems/pipeline_controller.gd → _handle_new_order"
    ]},
    {"signal": "order_completed", "listeners": [
      "scripts/managers/economy_manager.gd → _on_order_completed",
      "scripts/managers/reputation_manager.gd → _on_order_completed",
      "scripts/managers/progression_manager.gd → _on_order_completed"
    ]}
  ],
  
  "listens_to": [
    "Events.printer_done → _on_printer_done",
    "Events.day_changed → _generate_daily_orders"
  ],
  
  "references": ["EconomyManager", "ProgressionManager", "InventoryManager", "Events"],
  "referenced_by": ["PipelineController", "Worker", "OrdersPanel", "OrderDetailPopup"],
  
  "impact": "HIGH — 5 managers + 4 UI files depend on this. Signal signature changes break 3+ systems."
}
```


#### `C02` — `godotiq_signal_map`
Complete project signal wiring.

```
INPUT:
{
  "scope": "all",                    // "all", "autoloads", "file:path.gd"
  "find": "orphans"                  // "all", "orphans" (dead signals), "busiest"
}

OUTPUT:
{
  "total_signals": 47,
  "total_connections": 83,
  "orphans": [
    {"signal": "franchise_reset_completed", "defined_in": "events.gd", 
     "emitted_by": ["franchise_system.gd"], "listeners": 0}
  ],
  "busiest": [
    {"signal": "Events.day_changed", "listeners": 8},
    {"signal": "Events.order_completed", "listeners": 5}
  ],
  "missing_connections": [
    {"signal": "Events.research_completed", "emitter": "research_manager.gd",
     "note": "Emitted but Events.gd has no such signal defined — possible typo"}
  ]
}
```


#### `C03` — `godotiq_impact_check`
Before making ANY change, predict what breaks.

```
INPUT:
{
  "action": "modify_function",
  "file": "scripts/managers/printer_manager.gd",
  "function": "start_print",
  "change": "Adding parameter 'priority: int'"
}

OUTPUT:
{
  "risk": "HIGH",
  "callers": [
    {"file": "pipeline_controller.gd", "line": 145, "call": "PrinterManager.start_print(order, printer)"},
    {"file": "worker.gd", "line": 203, "call": "PrinterManager.start_print(current_order, target_printer)"}
  ],
  "breaking": "2 callers pass 2 args, new sig requires 3. All callers need update.",
  "safe_alternative": "Use default value: priority: int = 0",
  "test_checklist": [
    "F5 → Accept order → printer starts (pipeline path)",
    "F5 → Worker delivers to printer (worker path)",
    "F5 → R&D research → reservation works"
  ]
}
```


#### `C04` — `godotiq_validate`
Convention check for a file or entire project.

```
INPUT:
{
  "target": "scripts/managers/new_manager.gd",   // or "project" for full scan
  "content": "... optional: check before writing ...",
  "auto_fix": false
}

OUTPUT:
{
  "valid": false,
  "issues": [
    {"sev": "ERR", "rule": "class_name_suffix", "ln": 1, 
     "msg": "'NewManager' → 'NewManagerClass'", "fixable": true},
    {"sev": "ERR", "rule": "direct_ref", "ln": 23,
     "msg": "EconomyManager.cash direct access → use Events signal", "fixable": false},
    {"sev": "WARN", "rule": "type_hint", "ln": 15,
     "msg": "var count → var count: int", "fixable": true},
    {"sev": "WARN", "rule": "null_check", "ln": 30,
     "msg": "printer.order without is_instance_valid()", "fixable": true}
  ],
  "auto_fixable": 3
}
```


### ═══════════════════════════════════════════════
### CATEGORY D: ANIMATION INTELLIGENCE
### ═══════════════════════════════════════════════
### Parse AnimationPlayer, AnimationTree, .tres animation resources.

---

#### `D01` — `godotiq_animation_info`
Complete animation understanding for any animated node.

```
INPUT:
{
  "node": "Worker_1",                      // or scene path
  "detail": "full"
}

OUTPUT:
{
  "node": "Worker_1",
  "animation_player": "Worker_1/AnimationPlayer",
  "animation_tree": null,                  // or path if AnimationTree exists
  
  "animations": [
    {
      "name": "idle",
      "length": 2.0,
      "looping": true,
      "tracks": [
        {"type": "bone", "path": "Armature/Skeleton3D:Hips", "keys": 24},
        {"type": "bone", "path": "Armature/Skeleton3D:Spine", "keys": 24}
      ],
      "total_tracks": 18,
      "total_keyframes": 432
    },
    {
      "name": "walk",
      "length": 1.0,
      "looping": true,
      "tracks_count": 18,
      "root_motion": false,
      "speed_scale": 1.0
    },
    {
      "name": "carry",
      "length": 1.5,
      "looping": true,
      "tracks_count": 20,                  // 2 extra tracks for carried object
      "extra_tracks": [
        {"type": "property", "path": "CarryPoint:position", "keys": 3},
        {"type": "property", "path": "CarryPoint:rotation", "keys": 3}
      ]
    }
  ],
  
  "current_state": {                       // only if addon running
    "playing": "walk",
    "position": 0.45,
    "speed_scale": 1.2
  },
  
  "blend_tree": null,                      // AnimationTree state machine if exists
  
  "issues": [
    {"severity": "WARN", "detail": "Animation 'carry' has root motion disabled but 'walk' path implies movement. Possible sliding feet."},
    {"severity": "INFO", "detail": "All animations loop. No one-shot animations (attack, interact, etc.)"}
  ],

  "model_info": {
    "skeleton": "Armature/Skeleton3D",
    "bone_count": 22,
    "mesh_count": 1,
    "has_custom_shader": true,
    "shader_note": "Custom shader for inverted normals (Tripo AI model)"
  }
}
```


#### `D02` — `godotiq_animation_audit`
Find animation problems across the entire project.

```
INPUT:
{
  "scope": "all"                           // or "node:Worker_1", "scene:main.tscn"
}

OUTPUT:
{
  "animated_nodes": 5,
  "total_animations": 14,
  
  "issues": [
    {
      "severity": "HIGH",
      "node": "Worker_1",
      "animation": "carry",
      "issue": "broken_track",
      "detail": "Track 'CarryPoint:position' references node 'CarryPoint' which doesn't exist in scene tree. Animation will produce errors at runtime.",
      "fix": "Add Marker3D child named 'CarryPoint' to Worker_1, or update track path"
    },
    {
      "severity": "MEDIUM",
      "node": "Van",
      "animation": "drive",
      "issue": "instant_transition",
      "detail": "Van switches from 'idle' to 'drive' with no transition. Cross-fade of 0.2s recommended.",
      "fix": "Set AnimationPlayer.play('drive', 0.2) instead of play('drive')"
    },
    {
      "severity": "LOW",
      "node": "Printer_1",
      "animation": "printing",
      "issue": "no_loop",
      "detail": "Printing animation is 5.0s but print job is 30-120s. Animation should loop.",
      "fix": "Set animation loop mode to LOOP_LINEAR"
    },
    {
      "severity": "INFO",
      "node": "GarageDoor",
      "animation": "open",
      "issue": "one_shot_ok",
      "detail": "One-shot animation, 1.2s. Appears correct for door open/close."
    }
  ],
  
  "state_machines": [
    {
      "node": "Worker_1",
      "type": "code_driven",               // no AnimationTree, driven by script
      "states": ["idle", "walk", "carry", "wait"],
      "transitions_in_code": [
        {"from": "idle", "to": "walk", "trigger": "scripts/entities/worker.gd:145"},
        {"from": "walk", "to": "carry", "trigger": "scripts/entities/worker.gd:178"},
        {"from": "carry", "to": "idle", "trigger": "scripts/entities/worker.gd:201"}
      ]
    }
  ]
}
```


#### `D03` — `godotiq_animation_test`
Play animation and verify behavior (requires addon).

```
INPUT:
{
  "node": "Worker_1",
  "test_sequence": [
    {"play": "idle", "duration": 1.0, "check": "no_errors"},
    {"play": "walk", "duration": 1.0, "check": "node_moves"},           // verify root motion
    {"play": "carry", "duration": 1.0, "check": "child_visible:CarryPoint"}  // verify carry point
  ],
  "screenshot_each": true
}

OUTPUT:
{
  "results": [
    {
      "animation": "idle",
      "status": "PASS",
      "errors": [],
      "screenshot_id": "anim_test_001"
    },
    {
      "animation": "walk",
      "status": "WARN",
      "detail": "Animation plays but node position unchanged. Root motion not applied — movement likely handled by script, not animation.",
      "screenshot_id": "anim_test_002"
    },
    {
      "animation": "carry",
      "status": "FAIL",
      "errors": ["Track 'CarryPoint:position' — node not found"],
      "screenshot_id": "anim_test_003"
    }
  ]
}
```


### ═══════════════════════════════════════════════
### CATEGORY E: FLOW & DEBUG INTELLIGENCE
### ═══════════════════════════════════════════════

---

#### `E01` — `godotiq_trace_flow`
Trace how a game action flows through the entire codebase.

```
INPUT:
{
  "trigger": "player accepts order",
  "detail": "normal"
}

OUTPUT:
{
  "flow": "Order Acceptance → Delivery",
  "steps": [
    {"file": "orders_panel.gd", "action": "User taps Accept", "emits": "OrderManager.accept_order(id)"},
    {"file": "order_manager.gd", "action": "Validates, state → ACCEPTED", "emits": "Events.order_accepted"},
    {"file": "pipeline_controller.gd", "action": "Assigns printer", "emits": "PrinterManager.reserve_printer"},
    {"file": "printer_manager.gd", "action": "Printer → RESERVED", "emits": "Events.printer_reserved"},
    {"file": "task_manager.gd", "action": "Creates FETCH_MATERIAL task", "emits": "WorkerManager.assign_task"},
    {"file": "worker.gd", "action": "Worker walks to material, walks to printer", "emits": "material_delivered"},
    {"file": "printer_manager.gd", "action": "Print starts, timer, fail_chance", "emits": "Events.printer_done"},
    {"file": "task_manager.gd", "action": "Creates COLLECT task", "emits": "Worker collects"},
    {"file": "worker.gd", "action": "Carries to VanDock", "emits": "ShippingManager.add_to_queue"},
    {"file": "shipping_manager.gd", "action": "Batch 10s, van dispatches", "emits": "Events.shipment_dispatched"},
    {"file": "van_controller.gd", "action": "Drive animation, delivery timer", "emits": "Events.shipment_delivered"},
    {"file": "economy_manager.gd", "action": "Payment: base × freshness × rep_mult", "emits": "Events.payment_received"}
  ],
  "files_involved": 8,
  "failure_points": [
    {"step": 3, "if": "No printer available", "then": "Order queued"},
    {"step": 5, "if": "No worker available", "then": "Task queued"},
    {"step": 7, "if": "Print fails (fail_chance)", "then": "Material wasted, restart needed"},
    {"step": 10, "if": "Van in transit", "then": "Shipment waits for return"}
  ]
}
```


#### `E02` — `godotiq_diagnose`
Given a symptom, trace the probable cause.

```
INPUT:
{
  "symptom": "Orders show 'Unknown' instead of product name",
  "area": "UI"                             // "UI", "3D", "economy", "workers", "general"
}

OUTPUT:
{
  "causes": [
    {
      "likelihood": "HIGH",
      "cause": "product_id not found in ProductDatabase",
      "trace": [
        "orders_panel.gd:87 → ProductData.get_name(order.product_id)",
        "If product_id doesn't match → returns ''",
        "UI shows 'Unknown' as fallback"
      ],
      "check": "Compare ProductDatabase.products.keys() vs order.product_id values",
      "files": ["scripts/data/product_database.gd", "scripts/ui/hud/orders_panel.gd"]
    },
    {
      "likelihood": "MEDIUM",
      "cause": "R&D v2 added products not in base ProductDatabase",
      "trace": [
        "progression_manager.gd unlocks products by level",
        "order_manager.gd uses unlocked list for generation",
        "If unlock IDs don't match ProductData catalog → lookup fails"
      ],
      "check": "ProgressionManager.get_unlocked_products() vs ProductDatabase.get_all_ids()",
      "files": ["scripts/managers/progression_manager.gd", "scripts/data/product_database.gd"]
    }
  ]
}
```


#### `E03` — `godotiq_test_flow`
Automated gameplay test (requires addon).

```
INPUT:
{
  "test": "complete_order",
  "steps": [
    {"action": "wait_for", "condition": "OrderManager.pending_orders.size() > 0", "timeout": 10},
    {"action": "call", "method": "OrderManager.accept_order", "args": ["first_pending"]},
    {"action": "wait_for", "condition": "signal:Events.printer_done", "timeout": 60},
    {"action": "wait_for", "condition": "signal:Events.shipment_delivered", "timeout": 30},
    {"action": "assert", "condition": "EconomyManager.cash > initial_cash", "message": "Payment received"}
  ],
  "track": ["Worker_1.state", "Printer_1.state", "EconomyManager.cash"],
  "screenshot_on_fail": true
}

OUTPUT:
{
  "test": "complete_order",
  "status": "PASS",
  "duration": 42.3,
  "steps": [
    {"step": "wait_for pending order", "status": "PASS", "time": 2.1},
    {"step": "accept order", "status": "PASS", "time": 0.1},
    {"step": "wait for printer_done", "status": "PASS", "time": 31.5},
    {"step": "wait for shipment_delivered", "status": "PASS", "time": 8.2},
    {"step": "assert payment", "status": "PASS", "cash_before": 1000, "cash_after": 1045}
  ],
  "tracked_state": {
    "Worker_1": ["IDLE→WALKING(2.2s)→CARRYING(5.1s)→WALKING(8.3s)→IDLE(12.0s)→WALKING(33.7s)→CARRYING(36.2s)→IDLE(38.5s)"],
    "Printer_1": ["IDLE→RESERVED(2.2s)→PRINTING(5.1s)→DONE(33.6s)→IDLE(36.2s)"],
    "EconomyManager.cash": [1000, 1000, 1000, 1045]
  }
}
```


### ═══════════════════════════════════════════════
### CATEGORY F: ASSET INTELLIGENCE
### ═══════════════════════════════════════════════

---

#### `F01` — `godotiq_asset_registry`
Complete inventory of all project assets with usage tracking.

```
INPUT:
{
  "category": "all",               // "models", "textures", "audio", "scripts", "scenes", "all"
  "check_usage": true,             // cross-reference with .tscn/.gd files
  "check_issues": true             // missing files, unused assets, scale anomalies
}

OUTPUT:
{
  "summary": {
    "models_3d": 27, "textures": 15, "audio": 8, "scripts": 76, "scenes": 24
  },
  "models_by_origin": {
    "kenney": {"count": 8, "typical_scale": [1.0, 1.0, 1.0]},
    "meshy": {"count": 12, "typical_scale": [0.3, 0.5], "note": "Real-world scale, needs 0.01-0.5 in Godot"},
    "tripo": {"count": 7, "typical_scale": [1.0, 1.0, 1.0], "note": "Worker needs normal-flip shader"}
  },
  "issues": {
    "unused": ["assets/models/products/vase_old.glb", "assets/models/test_cube.glb"],
    "missing": [{"ref": "res://assets/models/printers/tier5.glb", "in": "scenes/main.tscn"}],
    "scale_anomalies": [
      {"file": "printer_basic.glb", "used_at": [0.01,0.01,0.01], "expected": [0.3, 0.5]}
    ]
  }
}
```


#### `F02` — `godotiq_suggest_scale`
Given a model and context, recommend exact scale + position.

```
INPUT:
{
  "model": "assets/models/logistics/shipping_box.glb",
  "origin": "meshy",
  "intended_use": "product_on_shelf",
  "scene": "scenes/main.tscn",
  "near_node": "StorageShelf"
}

OUTPUT:
{
  "recommended_scale": [0.05, 0.05, 0.05],
  "recommended_position": [1.2, 0.97, -0.5],
  "reasoning": "Meshy real-world scale. Shelf products in scene use 0.03-0.08. Shelf top at Y=0.95, +0.02 offset.",
  "references": [
    {"name": "Box_Product_01", "scale": [0.04, 0.04, 0.04]},
    {"name": "Box_Product_02", "scale": [0.06, 0.06, 0.06]}
  ]
}
```


### ═══════════════════════════════════════════════
### CATEGORY G: PROJECT MEMORY
### ═══════════════════════════════════════════════
### Survives context compaction. THE answer to amnesia.

---

#### `G01` — `godotiq_project_summary`
One-call re-priming. After compact, after new session, this is the FIRST call.

```
INPUT:
{
  "detail": "full"                 // "brief" = 50 tokens, "normal" = 200, "full" = 500
}

OUTPUT (brief):
{
  "project": "Print Farm Tycoon",
  "engine": "Godot 4.6, GDScript",
  "type": "Tycoon+ColonySim 3D, mobile portrait",
  "status": "v0.6+, save_v8, all waves complete, next wave TBD",
  "key_files": "CLAUDE.md (conventions), docs/roadmap.md (tasks), .godotiq.json (rules)",
  "conventions": "class_name+Class, Events bus, is_instance_valid, typed, English code"
}

OUTPUT (full):
{
  // ... everything from brief plus:
  "architecture": {
    "autoloads": ["GameManager", "EconomyManager", "OrderManager", ...],  // all 21+
    "core_loop": "Orders → Print → Ship → Pay → XP → LevelUp → R&D → New Products",
    "scene_structure": "Main → Building(rooms) + Entities + UI + Systems",
    "key_systems": ["Worker AI pipeline", "Van shipping batch", "R&D eureka", "Franchise prestige"]
  },
  "recent_changes": [
    {"file": "orders_panel.gd", "when": "2h ago", "delta": "+23 lines"},
    {"file": "shelf_display.gd", "when": "3h ago", "delta": "+45 lines"}
  ],
  "known_bugs": [
    "Display: 'Unknown' product names",
    "Worker: invisible carried objects", 
    "3D: model positioning on shelves",
    "Lighting: black shadows on exterior"
  ],
  "roadmap_state": {
    "completed": ["Wave1 Garage", "Wave2 Employee", "Wave3 Business", "R&D v2"],
    "current": "No active wave — pending definition"
  }
}
```


#### `G02` — `godotiq_file_context`
Deep context for a single file. Call BEFORE editing any file.

```
INPUT:
{
  "file": "scripts/managers/shipping_manager.gd"
}

OUTPUT:
{
  "file": "scripts/managers/shipping_manager.gd",
  "role": "Shipping queue, batch window 10s, van dispatch, cost calc",
  "lines": 187,
  "class_name": "ShippingManagerClass",
  "is_autoload": true,
  
  "public_api": [
    "add_to_queue(order: OrderClass) → adds to batch",
    "get_queue_size() → int",
    "force_dispatch() → immediate van send"
  ],
  
  "depends_on": ["Events", "EconomyManager", "GameManager"],
  "depended_by": ["TaskManager", "PipelineController", "GameHUD"],
  
  "gotchas": [
    "BATCH_WINDOW = 10s — synced with VanController animation timing",
    "Shipping cost deducted from EconomyManager — negative cash possible",
    "Van carries one batch — new shipments wait for van_returned"
  ]
}
```


#### `G03` — `godotiq_check_roadmap`
Scope enforcement. Prevents the agent from touching files outside the current task.

```
INPUT:
{
  "files_to_modify": ["scripts/managers/order_manager.gd", "scripts/ui/hud/workers_panel.gd"]
}

OUTPUT:
{
  "current_task": "T01 - Fix display bugs",
  "scope": ["scripts/ui/", "scripts/systems/shelf_display.gd"],
  "verdicts": {
    "order_manager.gd": {"allowed": false, "reason": "Core manager, not in T01 scope"},
    "workers_panel.gd": {"allowed": true, "reason": "UI file, within scope"}
  }
}
```


### ═══════════════════════════════════════════════
### CATEGORY H: UI INTELLIGENCE
### ═══════════════════════════════════════════════
### Understanding and interacting with Godot's Control nodes and game UI.

---

#### `H01` — `godotiq_ui_map`
Map all UI elements with their positions, states, and interaction targets.

```
INPUT:
{
  "root": "GameHUD",                       // or "PopupLayer", or "all"
  "include_invisible": false,
  "detail": "normal"
}

OUTPUT:
{
  "ui_root": "GameHUD",
  "screen_size": [1080, 1920],
  "canvas_layer": 10,
  
  "layout": {
    "TopBar": {
      "rect": [0, 0, 1080, 120],
      "children": [
        {"n": "CashLabel", "t": "Label", "rect": [20, 40, 200, 80], "text": "$1,250", "visible": true},
        {"n": "RepStars", "t": "HBoxContainer", "rect": [220, 40, 400, 80], "visible": true},
        {"n": "DayLabel", "t": "Label", "rect": [500, 40, 650, 80], "text": "Day 15", "visible": true},
        {"n": "SpeedButton", "t": "Button", "rect": [800, 30, 900, 90], "text": "1x", "interactive": true},
        {"n": "PauseButton", "t": "Button", "rect": [920, 30, 1020, 90], "interactive": true}
      ]
    },
    "BottomNav": {
      "rect": [0, 1750, 1080, 1920],
      "children": [
        {"n": "OrdersTab", "t": "Button", "rect": [0, 1750, 216, 1920], "text": "Orders", "active": true},
        {"n": "PrintersTab", "t": "Button", "rect": [216, 1750, 432, 1920], "text": "Printers"},
        {"n": "WorkersTab", "t": "Button", "rect": [432, 1750, 648, 1920], "text": "Workers"},
        {"n": "BuildTab", "t": "Button", "rect": [648, 1750, 864, 1920], "text": "Build"},
        {"n": "RnDTab", "t": "Button", "rect": [864, 1750, 1080, 1920], "text": "R&D"}
      ]
    },
    "ContentPanel": {
      "rect": [0, 120, 1080, 1750],
      "active_tab": "Orders",
      "children": [
        {"n": "OrderCard_1", "t": "PanelContainer", "rect": [20, 140, 1060, 340],
         "interactive": true,
         "data": {"order_id": "order_042", "product": "phone_case", "status": "PENDING"},
         "sub_elements": [
           {"n": "AcceptButton", "t": "Button", "rect": [800, 260, 1020, 320], "text": "Accept"},
           {"n": "ProductLabel", "t": "Label", "rect": [40, 160, 400, 200], "text": "Unknown"}  // ← BUG VISIBLE
         ]
        }
      ]
    }
  },
  
  "interactive_elements": 12,
  "touch_targets_too_small": [
    {"n": "SpeedButton", "size": [100, 60], "min_recommended": [120, 120], 
     "issue": "Below 44dp minimum for mobile touch targets"}
  ],
  
  "theme": {
    "detected": "dark",
    "background_color": "#1a1a2e",
    "primary_color": "#16213e",
    "accent_color": "#0f3460",
    "text_color": "#e0e0e0"
  },
  
  "anomalies": [
    {"n": "ProductLabel", "issue": "Text shows 'Unknown' — likely missing product data lookup",
     "data_source": "order.product_id → ProductData.get_name()"}
  ]
}
```


#### `H02` — `godotiq_ui_test`
Test UI interaction flow end-to-end.

```
INPUT:
{
  "flow": "accept_first_order",
  "steps": [
    {"tap": "OrdersTab"},
    {"wait": "OrderCard visible", "timeout": 5},
    {"tap": "AcceptButton on first OrderCard"},
    {"assert": "OrderCard status changes to 'ACCEPTED'"},
    {"assert": "BottomNav.PrintersTab shows notification badge"}
  ]
}

OUTPUT:
{
  "flow": "accept_first_order",
  "status": "PARTIAL_PASS",
  "steps": [
    {"tap": "OrdersTab", "result": "OK", "screenshot": "ui_test_001"},
    {"wait": "OrderCard", "result": "OK", "waited": 1.2},
    {"tap": "AcceptButton", "result": "OK", "screenshot": "ui_test_002"},
    {"assert": "status ACCEPTED", "result": "PASS"},
    {"assert": "PrintersTab badge", "result": "FAIL", 
     "detail": "No notification badge on PrintersTab after order acceptance",
     "suggestion": "Check if Events.order_accepted triggers badge update in bottom_nav.gd"}
  ]
}
```


#### `H03` — `godotiq_ui_audit`
Find UI/UX issues across the entire interface.

```
INPUT:
{
  "checks": [
    "touch_targets",              // elements too small for mobile (< 44dp)
    "overflow",                   // text/content outside container bounds
    "contrast",                   // text-on-background contrast ratio
    "consistency",                // style inconsistencies (font sizes, spacing, colors)
    "accessibility",              // missing labels, alt text
    "responsive",                 // elements that break at different screen sizes
    "interaction_feedback"        // buttons without press states, no visual feedback
  ]
}

OUTPUT:
{
  "total_issues": 11,
  "by_severity": {"critical": 2, "warning": 5, "info": 4},
  
  "issues": [
    {
      "severity": "CRITICAL",
      "check": "touch_targets",
      "node": "SpeedButton",
      "detail": "Size 100x60px = 37x22dp. Minimum: 48x48dp for mobile.",
      "fix": "Increase minimum_size to Vector2(130, 130)"
    },
    {
      "severity": "CRITICAL",
      "check": "overflow",
      "node": "ProductLabel in OrderCard",
      "detail": "Text 'Industrial Gearbox Housing' overflows container by 40px. Truncated.",
      "fix": "Enable text_overrun_behavior = OVERRUN_TRIM_ELLIPSIS or reduce font_size"
    },
    {
      "severity": "WARNING",
      "check": "consistency",
      "nodes": ["CashLabel", "DayLabel"],
      "detail": "CashLabel uses font_size 18, DayLabel uses 16. TopBar labels should be consistent.",
      "fix": "Standardize to DesignTokens.FONT_SIZE_TOPBAR"
    },
    {
      "severity": "WARNING",
      "check": "interaction_feedback",
      "node": "OrderCard",
      "detail": "Tappable element with no pressed/hover style_box. User has no visual feedback on tap.",
      "fix": "Add StyleBoxFlat with pressed variant to PanelContainer theme"
    }
  ]
}
```


### ═══════════════════════════════════════════════
### CATEGORY I: NAVIGATION & PATHFINDING
### ═══════════════════════════════════════════════

---

#### `I01` — `godotiq_nav_audit`
Debug navigation mesh and worker pathfinding issues.

```
INPUT:
{
  "scene": "scenes/main.tscn",
  "check_pathing": true,                  // test actual paths between key markers
  "markers_to_test": "all"                // or ["PrinterSlot_P1", "ShippingDock", ...]
}

OUTPUT:
{
  "navmesh": {
    "regions": 1,
    "total_vertices": 342,
    "total_polygons": 128,
    "area": 45.2,                          // sq meters
    "zones": [
      {"name": "Main Floor", "area": 38.0},
      {"name": "Storage Alcove", "area": 7.2}
    ]
  },
  
  "marker_reachability": {
    "total_markers": 22,
    "reachable": 20,
    "unreachable": [
      {"marker": "ResearchStation_3", "reason": "Position (5.5, 0, -6.8) is 0.3m outside navmesh edge",
       "fix": "Move to (5.2, 0, -6.5) or expand navmesh"},
      {"marker": "StorageShelf_TopSlot", "reason": "Y=0.95, navmesh is at Y=0.0. 3D pathfinding not configured.",
       "fix": "This is a shelf slot — workers should path to shelf base, not top"}
    ]
  },
  
  "path_tests": [
    {
      "from": "PrinterSlot_P1",
      "to": "ShippingDock",
      "status": "OK",
      "distance": 5.8,
      "waypoints": 4,
      "estimated_walk_time": 3.2           // at worker speed
    },
    {
      "from": "MaterialShelf",
      "to": "PrinterSlot_P4",
      "status": "SUBOPTIMAL",
      "distance": 8.2,
      "direct_distance": 3.1,
      "detail": "Path goes through reception. Wall between Storage and FDM Bay forces long detour.",
      "suggestion": "Consider adding door between Storage and FDM Bay to reduce walk time by 60%"
    }
  ],
  
  "collision_issues": [
    {
      "node": "Desk_Office",
      "issue": "No collision shape. Workers walk through this furniture.",
      "fix": "Add StaticBody3D + CollisionShape3D child"
    }
  ]
}
```


#### `I02` — `godotiq_waypoint_audit`
Audit the WaypointGraph system specifically.

```
INPUT: {}

OUTPUT:
{
  "waypoints": 25,
  "edges": 24,
  "disconnected_nodes": ["WP_Balcony"],
  "dead_ends": ["WP_VanDock"],            // only 1 edge — if blocked, no alternative
  "longest_path": {"from": "WP_Reception", "to": "WP_R&D_Station_3", "hops": 7},
  "choke_points": [
    {"waypoint": "WP_Hallway_Center", "connections": 4,
     "risk": "If blocked (e.g., by furniture), 8 waypoints become unreachable"}
  ]
}
```

---

## Configuration: `.godotiq.json`

```json
{
  "version": 2,
  
  "project": {
    "name": "Print Farm Tycoon",
    "engine": "godot_4",
    "type": "3d",
    "orientation": "portrait",
    "resolution": [1080, 1920]
  },
  
  "conventions": {
    "class_name_suffix": "Class",
    "signal_bus": "Events",
    "no_direct_manager_references": true,
    "require_type_hints": true,
    "require_null_checks": true,
    "naming": "snake_case",
    "comment_language": "english",
    "mobile_limits": {
      "max_triangles": 150000,
      "max_draw_calls": 50,
      "min_touch_target_dp": 48
    }
  },
  
  "asset_origins": {
    "kenney": {
      "path_patterns": ["assets/models/kenney/**", "assets/models/nature/**"],
      "default_scale": [1.0, 1.0, 1.0]
    },
    "meshy": {
      "path_patterns": ["assets/models/printers/**", "assets/models/logistics/**", "assets/models/products/**"],
      "default_scale_range": [0.01, 0.5],
      "note": "Real-world scale export"
    },
    "tripo": {
      "path_patterns": ["assets/models/characters/**"],
      "default_scale": [1.0, 1.0, 1.0],
      "shader_note": "Worker model needs inverted normals shader"
    }
  },
  
  "rooms": {
    "detect_from": "LockedZone nodes or manual definition",
    "defined": [
      {"name": "Reception+Office", "bounds": {"min": [0, 0, 0], "max": [3, 3, 2]}},
      {"name": "FDM Bay", "bounds": {"min": [0, 0, -6], "max": [3, 3, -2]}},
      {"name": "Storage", "bounds": {"min": [0, 0, -3], "max": [3, 3, 0]}},
      {"name": "VanDock", "bounds": {"min": [3, 0, -8], "max": [6, 3, -6]}},
      {"name": "R&D Lab", "bounds": {"min": [3, 0, -6], "max": [6, 3, -2]}}
    ]
  },
  
  "roadmap": {
    "path": "docs/roadmap.md",
    "enforce_scope": true
  },
  
  "protected_files": [
    "project.godot",
    ".godot/**",
    "*.import",
    "saves/**"
  ],
  
  "token_optimization": {
    "default_detail": "normal",
    "enable_diff_cache": true,
    "compact_output": true,
    "max_nodes_per_response": 50
  },
  
  "custom_rules": [
    {
      "id": "van_batch_sync",
      "files": ["scripts/managers/shipping_manager.gd"],
      "pattern": "BATCH_WINDOW",
      "message": "Changing batch window requires updating VanController animation timing"
    },
    {
      "id": "save_version_bump",
      "files": ["scripts/managers/save_manager.gd"],
      "pattern": "SAVE_VERSION",
      "message": "Bumping save version requires adding migration function"
    }
  ]
}
```

---

## Technical Implementation

### Stack
- **Language:** Python 3.10+ 
- **MCP SDK:** Official `mcp` Python package (stdio transport)
- **Godot Addon:** GDScript + WebSocket server (for runtime bridge)
- **Parsers:** Custom, zero external dependencies
  - `.tscn` / `.tres` → Godot text resource parser
  - `.gd` → GDScript AST-lite parser (regex + state machine)
  - `.glb` → Header-only for bounding box (optional, python struct module)
- **Cache:** In-memory hash-based, invalidated on file mtime change

### .tscn Parser Details
Godot's text scene format is well-structured:
```
[gd_scene load_steps=5 format=3]
[ext_resource type="Script" path="res://script.gd" id="1"]
[node name="Main" type="Node3D"]
[node name="Child" type="MeshInstance3D" parent="."]
transform = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 1.5, 0, -2.0)
```

We parse:
1. ext_resource declarations (scripts, meshes, materials, scenes)
2. sub_resource definitions (inline materials, shapes)
3. Node hierarchy (name, type, parent path reconstruction)
4. Transform3D decomposition → position, rotation, scale
5. Groups, metadata, script assignments
6. Signal connections (in .tscn `[connection]` blocks)

### GDScript Parser Details
Extracts:
1. `class_name` → project-wide class registry
2. `extends` → inheritance chain
3. `signal X(params)` → signal definitions
4. `func name(params) -> ReturnType:` → function signatures
5. `.connect("signal", callable)` and `.emit()` → dynamic wiring
6. `@onready var x = $Path` → node references
7. `@export var x: Type` → configurable properties
8. `ManagerName.method()` → autoload references (matched against project.godot)
9. `is_instance_valid()` usage tracking
10. `AnimationPlayer.play()` calls → animation state machine reconstruction

### Godot Addon Architecture
Minimal GDScript addon (< 500 lines) that:
1. Starts WebSocket server on configurable port (default 6007)
2. Handles screenshot requests (Viewport.get_texture())
3. Reports performance metrics (Engine.get_frames_per_second(), RenderingServer stats)
4. Monitors errors/warnings (redirects push_error/push_warning)
5. Tracks node state changes (for watched nodes)
6. Executes input events (InputEventScreenTouch, InputEventScreenDrag)
7. Reports animation states (AnimationPlayer.current_animation, position)
8. Provides scene tree introspection at runtime

The addon is the ONLY Godot-side dependency. Everything else runs externally.

### Performance Targets
- Full project scan (100 files): < 500ms
- Scene map generation: < 200ms
- Single file context: < 50ms  
- Screenshot capture + annotate: < 300ms
- Cached re-scan (no changes): < 10ms

---

## Complete Tool Count

| Category | Code | Tools | Addon Required |
|----------|------|-------|---------------|
| A. Intelligent Bridge | A01-A07 | 7 | YES (runtime) |
| B. Spatial Intelligence | B01-B03 | 3 | Optional (enhanced with runtime) |
| C. Code Intelligence | C01-C04 | 4 | NO (filesystem only) |
| D. Animation Intelligence | D01-D03 | 3 | D03 requires addon |
| E. Flow & Debug | E01-E03 | 3 | E03 requires addon |
| F. Asset Intelligence | F01-F02 | 2 | NO |
| G. Project Memory | G01-G03 | 3 | NO |
| H. UI Intelligence | H01-H03 | 3 | YES (runtime) |
| I. Navigation | I01-I02 | 2 | Optional |
| **TOTAL** | | **30** | **13 require addon** |

### MVP (v1.0): 18 tools
All of Categories B, C, D (D01-D02), F, G + A01, A02, A03, A05, A06 = 18 tools
These cover: spatial understanding, code safety, animation analysis, asset management, project memory, and basic bridge.

### Full Release (v1.5): 30 tools
Everything above + E, H, I, D03, A04, A07 = complete platform.

---

## Competitive Positioning

```
"The only Godot MCP that understands your game, not just your files."
```

| Capability | GDAI ($20) | satelliteoflove (free) | ee0pdt (free) | GodotIQ |
|---|---|---|---|---|
| Screenshot | ✅ raw | ✅ raw | ❌ | ✅ annotated + issues |
| Scene tree | ✅ raw | ✅ raw | ✅ raw | ✅ with spatial context |
| Edit nodes | ✅ | ✅ | ✅ | ✅ validated + batch |
| Run/Stop | ✅ | ✅ | ❌ | ✅ monitored + auto-detect |
| Input simulation | ✅ | ❌ | ❌ | ✅ with signal verification |
| 3D spatial understanding | ❌ | ❌ | ❌ | ✅ scene_map, placement |
| Dependency graph | ❌ | ❌ | ❌ | ✅ signals, callers, impact |
| Animation analysis | ❌ | ❌ | ❌ | ✅ info, audit, test |
| Convention validation | ❌ | ❌ | ❌ | ✅ auto-fix |
| UI understanding | ❌ | ❌ | ❌ | ✅ map, test, audit |
| Navigation debug | ❌ | ❌ | ❌ | ✅ audit, path test |
| Project memory | ❌ | ❌ | ❌ | ✅ survives compact |
| Asset intelligence | ❌ | ❌ | ❌ | ✅ registry, scale suggest |
| Token optimization | ❌ | ❌ | ❌ | ✅ diff, compress, filter |
| Performance monitoring | ❌ | ✅ basic | ❌ | ✅ threshold alerts |
| No Godot addon needed* | plugin | plugin | plugin | 17 tools work without |
| **Total tools** | ~15 | ~12 | ~8 | **30** |

*GodotIQ's intelligence layer (17 tools) works without addon. Runtime features (13 tools) need a lightweight addon.

### Price Point
**$29 one-time** — justified by being 2x the tools, 10x the intelligence.
Or **$9/month** subscription for ongoing updates.

---

## Name: GodotIQ

**Final.** Clear, memorable, communicates value (intelligence), unique in the Godot ecosystem.

---

## Development Roadmap

### Phase 1: Core Engine (3-4 weeks)
- .tscn parser with transform extraction
- .gd parser with signal/dependency tracking
- 18 MVP tools implemented
- Tested on Print Farm Tycoon daily
- MCP server with stdio transport

### Phase 2: Addon + Runtime (2-3 weeks)  
- Godot addon (WebSocket server, < 500 lines)
- Runtime bridge tools (screenshot, run, input)
- Animation runtime integration
- Performance monitoring

### Phase 3: Polish & Generalize (2 weeks)
- Remove project-specific assumptions
- Test on 3+ open source Godot projects
- .godotiq.json configuration system
- Documentation and setup guide

### Phase 4: Launch
- Landing page (godotiq.dev or similar)
- Gumroad / itch.io listing
- Demo video: before/after comparison
- Reddit + Twitter + Godot forums
- Claude Code plugin marketplace listing
- Discord community
