Mock up of the software. Fully generated with Gemini 3.8 as a proof of concept.

AGENTS.md

@@ -0,0 +1,48 @@
+# CodeInspector Development Guidelines & Project Invariants
+
+## 1. Build System & Architecture (RAD Debugger Style)
+- **Zero CMake**: Do not add CMake or CMake-generated project files.
+- **Unity Build**: All source modules in `src/` must be included into a unified translation unit (`src/main.cpp`). Keep compilation times sub-second to 2 seconds.
+- **Build Script (`build.bat`)**:
+  - Auto-detects Visual Studio installations using `vswhere.exe` and calls `vcvars64.bat` if `cl.exe` is not in `%PATH%`.
+  - Caches precompiled vendor objects (`vendor_imgui.obj`, `rlImGui.obj`) in `build/` to maximize iteration speed.
+  - Supports `debug`, `release`, `run`, and `clean` modes.
+
+## 2. MSVC Output Routing Invariant (Zero Root Pollution)
+Whenever compiling with MSVC (`cl.exe`) in `build.bat`:
+- Always route **all** outputs strictly into the `build/` directory:
+  - Object files: `/Fo:"build\"` or `/Fo:"build\<name>.obj"`
+  - Compiler PDBs: `/Fd:"build\"`
+  - Binaries: `/Fe:"build\<name>.exe"`
+  - Linker PDBs: `/link /PDB:"build\<name>.pdb"`
+- Never let `cl.exe` drop `vc*.pdb`, `*.obj`, `*.lib`, or `*.exp` into the project root.
+- Keep `imgui.ini` and compiler intermediates ignored in `.gitignore`.
+
+## 3. General-Purpose Clang AST Execution Engine (Inspect ANY Code)
+- **No DLL Compilation / No Subprocess Execution**: Never invoke external compilers (`cl.exe`) at runtime to load code as DLLs.
+- **No Ad-Hoc Token Regexes**: Never use pattern matching or token scanning to guess function behavior.
+- **Recursive AST Evaluation**:
+  - All code inspection, evaluation, and call tracing are driven directly by the `libclang` AST tree (`CXCursor`).
+  - The AST interpreter (`Runner`) must support standard C constructs:
+    - Control flow: `IfStmt`, `CompoundStmt`, `WhileStmt`, `ForStmt`, `ReturnStmt`.
+    - Expressions: `ConditionalOperator` (ternary `? :`), `BinaryOperator` (comparison, arithmetic, bitwise, assignment), `UnaryOperator` (`-`, `!`, `~`, `++`, `--`).
+    - Values: `IntegerLiteral`, `CharacterLiteral`, `FloatingLiteral`, `DeclRefExpr`, `VarDecl`.
+  - Every function invocation (`CallExpr`) records a `TraceFrame` capturing timestamps, arguments, return values, depth, and child calls for the flamegraph and call tree.
+  - Recursion and loop guard limits (e.g. max depth 60, max calls 50,000) must protect against infinite execution.
+
+## 4. Working Directory & Path Safety
+- On startup, the application must immediately call `ensure_project_root()` to detect if it was launched from `build/` or an external shortcut, resetting `std::filesystem::current_path` to the repository root.
+- Always load existing files from disk on launch. Never overwrite the user's buffer with hardcoded sample strings.
+- Always ensure parent directories exist (`std::filesystem::create_directories`) before saving or creating files.
+
+## 5. Live Synchronization Architecture
+- `SourceManager` maintains a monotonic `revision_` counter incremented upon every AST reparse, load, edit, or save.
+- UI panels observe `revision_` and re-evaluate parameters and flamegraphs automatically live as the user types.
+
+## 6. UI Ergonomics & Clipboard Export
+- Log and console panels must always support easy copying:
+  - Provide a "Copy All Logs" button using `ImGui::SetClipboardText`.
+  - Provide right-click context menus (`Copy Line`, `Copy Message Only`).
+  - Provide a "Raw Text (Selectable)" tab with mouse selection and native `Ctrl+C`.
+- **AST Debug Export**:
+  - Provide a one-click "Copy AST & Debug Dump to Clipboard" button in the inspector, in the AST Explorer view, and via global shortcut `Ctrl+D` (`export_ast_dump`) to facilitate instant debugging in pair-programming workflows.