MisterGC · MisterGC · Mar 28, 2026 · Mar 28, 2026 · Mar 30, 2026 · Mar 31, 2026
diff --git a/.gitignore b/.gitignore
@@ -98,6 +98,9 @@ docs/webdojo-examples/*/
 !docs/webdojo-examples/welcome/
 docs/webdojo-examples/index.json
 
+# Clay Crew inspect/crew session data
+.clay/
+
 # Temp/personal files
 aqtinstall.log
 test_simple.qml

diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock
@@ -1,8 +1,8 @@
 GEM
   remote: https://rubygems.org/
   specs:
-    addressable (2.8.7)
-      public_suffix (>= 2.0.2, < 7.0)
+    addressable (2.9.0)
+      public_suffix (>= 2.0.2, < 8.0)
     base64 (0.3.0)
     bigdecimal (3.2.2)
     colorator (1.1.0)

diff --git a/docs/_data/docs_nav.yml b/docs/_data/docs_nav.yml
@@ -17,6 +17,8 @@
   children:
     - title: Dojo - Live Reloading
       url: /docs/manual/dojo/
+    - title: Inspector
+      url: /docs/manual/inspector/
     - title: Logging Overlay
       url: /docs/manual/logging/
     - title: Plugin Development

diff --git a/docs/clay-crew-concept.md b/docs/clay-crew-concept.md
@@ -0,0 +1,158 @@
+# Clay Crew — AI-Agent Collaboration for Clayground
+
+**Closing the feedback loop between AI agents and interactive applications.**
+
+---
+
+## 1. The Problem
+
+Clayground's dev loop is built for humans: edit QML, the Dojo reloads, you see the result. AI agents cannot see. They can write QML but have no way to verify the result — did the dungeon render? does the enemy move? does combat work?
+
+Even for humans, the feedback loop has gaps: you can see the screen but can't easily answer "what's the player's exact health?" or "did the boss AI transition states correctly over the last 10 seconds?"
+
+## 2. The Solution
+
+An **in-app inspector** with a file-based protocol, plus **query functions on the canvas/world** components. The inspector handles generic concerns (protocol, screenshots, tracing). The canvas/world handle domain-aware queries (spatial search in the right coordinate system).
+
+### Why file-based?
+
+1. **Zero dependencies** — no HTTP server, no socket library, no port management
+2. **Debuggable** — `cat .clay/inspect/response.json` shows exactly what the agent sees
+3. **Composable** — any tool that reads files can consume the output
+4. **No port conflicts** — works in Docker without networking configuration
+5. **Persistent** — snapshots and traces are saved for post-hoc review
+
+### Why in-app?
+
+An external tool would need to connect to a debug port and speak an undocumented binary protocol. The in-app inspector simply calls `grabToImage()`, reads properties via `QMetaObject`, and evaluates expressions via `QQmlExpression` — everything is already available in-process.
+
+## 3. Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Dojo Process                                               │
+│                                                             │
+│  ┌──────────────┐  ┌────────────────────────────────────┐   │
+│  │  Sandbox.qml │  │  ClayInspector (C++)               │   │
+│  │  (the app)   │  │                                    │   │
+│  │              │  │  • file protocol (request/response) │   │
+│  │  flagInfo()  │  │  • snapshot, eval, tree, trace      │   │
+│  │  (optional)  │  │  • screenshot capture               │   │
+│  │              │  │  • log/warning/error capture         │   │
+│  │  ┌────────┐  │  │  • Ctrl+F flag, Ctrl+T trace       │   │
+│  │  │Canvas/ │  │  │                                    │   │
+│  │  │World2d │  │  └────────────────────────────────────┘   │
+│  │  │        │  │                                           │
+│  │  │ find() │  │  .clay/inspect/                           │
+│  │  │(QML/JS)│  │  ├── request.json   (agent writes)        │
+│  │  └────────┘  │  ├── response.json  (inspector writes)    │
+│  └──────────────┘  ├── screenshot.png                       │
+│                    └── trace.jsonl                           │
+│                                                             │
+│                    .clay/crew/                               │
+│                    ├── flag_<ts>.json  (Ctrl+F)              │
+│                    └── flag_<ts>.png                         │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### What lives where
+
+| Component | Responsibility | Why there |
+|-----------|---------------|-----------|
+| **ClayInspector** (C++, tools/loader/) | Protocol, eval, tree dump, trace, screenshots, flags | Needs QTimer, file I/O, QMetaObject introspection, message handler access |
+| **ClayCanvas.find()** (QML/JS, plugins/clay_canvas/) | Spatial/conditional entity search (2D) | Knows pixelPerUnit, world bounds, Y-axis inversion, content children |
+| **ClayWorld2d.find()** (QML/JS, plugins/clay_world/) | Override with physics-aware search | Knows Box2D world, can enrich with velocity/body state |
+| **flagInfo()** (user's Sandbox.qml) | Domain-specific state snapshot | Only the developer knows what matters for their app |
+
+## 4. Inspector Actions
+
+### snapshot — Point-in-time state
+
+Returns: `rootProperties` (auto-captured), `flagInfo` (if defined), `eval` results, `logTail`, `warnings`, `errors`, optional screenshot.
+
+### eval — Expression evaluation
+
+Evaluates JS/QML expressions in the sandbox root context. Bridges to `canvas.find()` and any QML function.
+
+### tree — Structural dump with LOD
+
+Two detail levels: **overview** (compact, used in flags) and **full** (adds vector properties, state, childrenRect). Smart property filtering skips Qt framework noise, keeps only app-level state. Truncation summaries surface rare/named items in large child lists.
+
+### find — Spatial/conditional search (via eval → canvas.find)
+
+Defined on ClayCanvas, overridable by World2d/3d. Filter by type, objectName, distance (world units), and arbitrary JS conditions. Distance is unambiguous — the canvas owns the coordinate system.
+
+### trace — Temporal observation
+
+Records watched expressions at configurable intervals to JSONL. Stops on a condition (`stopWhen`), timeout, or manual request. Returns a summary with first/last/min/max/changes per expression. Enables behavioral verification without screenshots.
+
+## 5. Human Interaction
+
+### Ctrl+F — Flag a Moment
+
+Screenshot freeze → type annotation → saves flag JSON (annotation + state + tree) and PNG. Max 5 flags retained. The agent reads flags to understand what the human saw and what needs fixing.
+
+### Ctrl+T — Toggle Trace
+
+Starts/stops the currently configured trace. The agent configures what to watch; the human controls when to record.
+
+### flagInfo() — Developer-Defined State
+
+Optional function on the sandbox root. Returns domain-specific state the framework can't infer. Called at snapshot/flag time.
+
+## 6. The Autonomous Agent Workflow
+
+```
+1. Edit QML
+   │
+2. qmllint ──────── syntax/type errors? ──→ fix
+   │
+3. snapshot ─────── "No sandbox root"? ──→ engine crash
+   │                 (unknown component, missing import,
+   │                  circular dependency — linting can't
+   │                  catch these)
+   │
+4. eval + find ──── entities exist? structure correct?
+   │                 positions right? state as expected?
+   │
+5. trace ────────── behavior correct over time?
+   │                 stop condition met? (= success)
+   │                 or timeout? (= bug)
+   │
+6. ✓ Verified ──── commit / move on
+```
+
+Each layer is more expensive than the previous. The agent stops at the first layer that gives confidence.
+
+## 7. The Collaborative Workflow
+
+```
+Human                              Agent
+  │                                  │
+  │  Ctrl+F: "skeleton stuck here"   │
+  │  ──────────────────────────────→ │
+  │                                  │ reads flag JSON + tree
+  │                                  │ uses find() to locate skeleton
+  │                                  │ fixes pathfinding code
+  │                                  │
+  │                                  │ sets up trace on skeleton.state
+  │  Ctrl+T: starts trace            │
+  │  plays game, lures skeleton      │
+  │  Ctrl+T: stops trace             │
+  │  ──────────────────────────────→ │
+  │                                  │ reads trace summary
+  │                                  │ identifies the stuck transition
+  │                                  │ fixes the bug
+```
+
+## 8. File Protocol — Synchronization
+
+`response.json` is the **single synchronization point**. The agent writes `request.json` and watches for `response.json` to change.
+
+During a trace, do NOT read `trace.jsonl` — it is being actively written. Wait for the trace to stop (response.json updates with summary). Only then is `trace.jsonl` safe to read.
+
+No race conditions: all inspector logic runs on the Qt main event loop (single-threaded).
+
+---
+
+*Concept based on Clayground's Clay Crew implementation, March 2026.*
diff --git a/docs/docs/manual/dojo.md b/docs/docs/manual/dojo.md
@@ -35,6 +35,8 @@ Dojo is the primary development tool for Clayground projects. It monitors your s
 |----------|--------|
 | `Ctrl+G` | Toggle guide overlay |
 | `Ctrl+L` | Toggle logging overlay |
+| `Ctrl+F` | [Flag a moment]({{ site.baseurl }}/docs/manual/inspector/#ctrlf--flag-a-moment) — screenshot + annotation |
+| `Ctrl+T` | [Toggle trace]({{ site.baseurl }}/docs/manual/inspector/#ctrlt--toggle-trace) recording |
 | `Ctrl+1` to `Ctrl+5` | Switch between loaded sandboxes |
 
 ## How Live-Reloading Works
@@ -50,6 +52,50 @@ At the heart of Dojo is a sophisticated hot-reload system. When you save a QML f
 
 The 50ms debounce window catches rapid file changes from editor auto-saves.
 
+## Ignoring Files — `.dojoignore`
+
+Dojo watches the sandbox directory recursively, so **any** file change in
+that tree (including data files your sandbox edits live, song sources,
+generated caches, etc.) triggers a full scene reload. For files that your
+sandbox handles itself at runtime — e.g. a song file being hot-reloaded
+by `SongPlayer` — that full reload is counter-productive: it drags the
+playhead back to zero and throws away the live state you were tuning.
+
+Drop a `.dojoignore` file next to your `Sandbox.qml` to exclude paths
+from the reload trigger. Same spirit as `.gitignore`:
+
+```text
+# ignore a single file, anywhere under the sandbox dir
+notes.txt
+
+# ignore all song sources
+*.song.json
+
+# ignore an entire subdirectory and its contents
+songs/
+
+# anchor to the sandbox dir (exact path)
+data/level1.json
+```
+
+Semantics:
+
+| Pattern                  | Matches                                                        |
+|--------------------------|----------------------------------------------------------------|
+| `name`                   | any file/dir named `name` under the sandbox tree               |
+| `*.ext`                  | basename wildcard, matches in any subdirectory                 |
+| `name/`                  | the directory and everything beneath it                        |
+| `sub/file.txt`           | path-anchored (no match on `other/sub/file.txt`)               |
+| `/file.txt`              | path-anchored (leading `/` optional; same meaning as above)    |
+| `**`                     | any number of path segments                                    |
+
+Comments start with `#`; blank lines are ignored. The file is re-read
+automatically when you save it, so you can add/remove patterns without
+restarting the dojo.
+
+`.dojoignore` only ever *subtracts* from the watched set — it cannot make
+the dojo watch files it would otherwise miss.
+
 ## Dynamic Plugin Development
 
 Beyond QML hot-reloading, Dojo supports live development of C++ plugins:
@@ -71,5 +117,6 @@ The format is `--dynplugin <source_dir>,<binary_dir>`. Dojo detects when your pl
 
 ## Next Steps
 
+- Use the [Inspector]({{ site.baseurl }}/docs/manual/inspector/) for structured state snapshots and flagging moments
 - Learn about the [Logging Overlay]({{ site.baseurl }}/docs/manual/logging/)
 - Create your own [plugins]({{ site.baseurl }}/docs/manual/plugin-development/)
diff --git a/docs/docs/manual/index.md b/docs/docs/manual/index.md
@@ -9,6 +9,7 @@ The Clayground manual covers the development tools and workflows in detail.
 ## Development Tools
 
 - **[Dojo - Live Reloading]({{ site.baseurl }}/docs/manual/dojo/)** - The primary development environment with hot-reload
+- **[Inspector]({{ site.baseurl }}/docs/manual/inspector/)** - File-based introspection, snapshots, and flagging moments
 - **[Logging Overlay]({{ site.baseurl }}/docs/manual/logging/)** - Real-time debugging and property watching
 - **[Plugin Development]({{ site.baseurl }}/docs/manual/plugin-development/)** - Creating your own Clayground plugins