Now I have a thorough understanding of the codebase. Let me produce the section content.

# Section 8: SCENE_MAP -- Disk Warning Note

## Overview

The `godotiq_scene_map` tool reads spatial data from saved `.tscn` files on disk, not from the live Godot editor state. Users frequently call `scene_map` after making unsaved editor changes and are confused when the results do not reflect their modifications. This section adds a `note` field to every `scene_map` response that reminds the user to save first.

This is a Python-side-only change, confined to a single file. No GDScript changes are needed.

## Dependencies

None. This section is fully independent of all other sections and can be implemented in isolation.

## File to Modify

- `/Users/salvatorefarruggio/Desktop/godotiq/src/godotiq/tools/spatial/__init__.py`

## File to Modify (tests)

- `/Users/salvatorefarruggio/Desktop/godotiq/tests/test_tools/test_scene_map.py`

## Tests (Write First)

Add the following tests to the existing `tests/test_tools/test_scene_map.py` file. They should be added as a new test class at the end of the file, or appended to the existing `TestSceneMapBasic` class. A new class is preferred for clarity.

```python
class TestSceneMapDiskNote:
    """Tests for the disk-warning note in scene_map response."""

    def test_scene_map_response_contains_note(self, session: GodotIQSession) -> None:
        """scene_map response includes a 'note' key."""
        result = _build_scene_map(session, "res://scenes/equipment/fdm_printer.tscn")
        assert "note" in result

    def test_scene_map_note_mentions_saved_tscn(self, session: GodotIQSession) -> None:
        """Note text mentions 'saved .tscn file' and 'godotiq_save_scene'."""
        result = _build_scene_map(session, "res://scenes/equipment/fdm_printer.tscn")
        note = result["note"]
        assert "saved .tscn file" in note
        assert "godotiq_save_scene" in note
```

The tests use the existing `session` fixture from `conftest.py` and directly call the internal `_build_scene_map` function (the same pattern used by every other test in this file). No mock bridge or new fixtures are needed.

**Key assertions:**
1. The `note` key is present in the response dict.
2. The note text contains two specific substrings: `"saved .tscn file"` (explaining what is being read) and `"godotiq_save_scene"` (telling the user what to do about it).

The tests should NOT check for exact string equality because the wording may be adjusted. Substring checks are sufficient and robust.

## Implementation

The change is a single line addition to the `_build_scene_map` function in `/Users/salvatorefarruggio/Desktop/godotiq/src/godotiq/tools/spatial/__init__.py`.

### Where to add the note

In the `_build_scene_map` function, the result dict is constructed starting around line 275. The relevant block currently looks like this:

```python
    result: dict = {
        "scene": scene_path,
        "root_type": root_type,
        "total_nodes": resolved.total_nodes,
        "nodes": node_dicts,
    }
```

Add the `note` key to this dict literal:

```python
    result: dict = {
        "scene": scene_path,
        "root_type": root_type,
        "total_nodes": resolved.total_nodes,
        "nodes": node_dicts,
        "note": "reads from saved .tscn file — call godotiq_save_scene first if you have unsaved editor changes",
    }
```

### What NOT to change

- Do not modify the `godotiq_scene_map` async wrapper function. The note belongs in `_build_scene_map` so it is present regardless of how the function is called (directly in tests, or via the MCP tool).
- Do not modify the spatial audit tool or any other tool. This note is specific to scene_map.
- Do not add any conditional logic. The note should always be present on every response, including error responses. If you want the note to only appear on successful responses (where `"error"` is not in the result), that is acceptable but not required -- the plan says "add to the result dict" without conditions.
- Do not add GDScript changes. This is Python-side only.

### Interaction with existing response fields

The `note` key is a new top-level field. It does not conflict with any existing fields in the result dict (`scene`, `root_type`, `total_nodes`, `nodes`, `token_hint`, `nearby_count`, `nearby_capped`, `nearby_total_in_radius`, `focus_node`, `focus_position`, `focus_alternatives`, `warning`, `spatial_summary`, `groups_summary`, `distance_matrix`, `type_summary`). The `apply_output_limit` call at line 317 operates on list keys and does not strip string fields, so the `note` will pass through untouched.

### Note about error responses

The `_build_scene_map` function has an early return for missing scenes at line 178:

```python
    if spatial is None:
        return {"error": "Scene not found", "scene": scene_path}
```

The note is NOT added to this early-return error dict. This is acceptable because if the scene is not found, advising the user to "save first" is irrelevant. The note only needs to appear on successful responses where spatial data is actually returned from disk.

## Verification

After implementation, run:

```bash
uv run pytest tests/test_tools/test_scene_map.py -v
```

All existing tests must continue to pass. The two new tests (`test_scene_map_response_contains_note` and `test_scene_map_note_mentions_saved_tscn`) must also pass. Since the note is simply a new key added to the result dict, no existing test assertions should break -- none of them assert the exact set of keys in the result.

---

## Implementation Results

### Files Modified
- `src/godotiq/tools/spatial/__init__.py` — added `note` key to result dict in `_build_scene_map`
- `tests/test_tools/test_scene_map.py` — added `TestSceneMapDiskNote` class with 2 tests

### Deviations from Plan
None. Implementation matches plan exactly.

### Test Count
- 28 total tests in test_scene_map.py (26 existing + 2 new), all passing