# Sprint 12a — Usage Guide

## Overview

Sprint 12a implements 15 quality-of-life improvements across the GodotIQ MCP toolset: better error messages, fuzzy matching, defensive CLI behavior, and developer tooling.

## Changes by Category

### Build Scene Improvements (Sections 01-03)
- **Offset parameter**: `build_scene` now accepts an `offset` parameter for positioning new nodes
- **Scene-derived names**: Nodes get meaningful names derived from the instantiated scene file
- **Parent path stripping**: Parent paths are stripped to clean basenames in output

### Error Handling (Sections 04-06)
- **Confidence annotation**: `check_errors` annotates results with confidence levels (high/medium/low)
- **Error detail extraction**: `exec_code` returns structured error details (line number, error type, message)
- **Await/timeout warning**: `exec_code` warns when expressions look like they need `await`

### Asset & Scene Tools (Sections 07-08)
- **Fuzzy match suggestions**: Asset registry returns "did you mean?" suggestions on zero matches
- **Disk warning note**: `scene_map` includes a note when scene data may be stale (from disk cache)

### Save & Screenshot (Sections 09-10)
- **Save feedback fields**: `save_scene` returns file size and node count in response
- **Screenshot crop region**: `editor_screenshot` accepts a crop `region` parameter (x, y, w, h)

### Input & Node Operations (Sections 11-12)
- **Mouse motion**: `input_sim` supports `mouse_motion` events with delta/relative parameters
- **Rename & get_property**: `node_ops` gains `rename` and `get_property` operations

### Developer Tooling (Sections 13-15)
- **Version sync script**: `scripts/sync_version.py` keeps version numbers in sync across files
- **Dev key hashing**: Developer API keys are SHA-256 hashed before storage/comparison
- **CLI --version fix**: `godotiq --version` exits cleanly without triggering warning logs

## Quick Verification

```bash
# Run the full test suite
uv run pytest -v

# Verify CLI version output is clean
python -m godotiq --version

# Run version sync check
uv run python scripts/sync_version.py --check
```
