docs(simulations): expand CodeOutliner doc (add get_outline dispatcher, [ImGui Scope] case, return-type suffix, count overflow guard)

docs/guide_simulations.md

@@ -455,15 +455,23 @@ functions: summarise_file, build_summary_markdown
 
 ```python
 class CodeOutliner:
-    def outline(self, code: str) -> str
+    def __init__(self) -> None: ...
+    def outline(self, code: str) -> str: ...
+
+def get_outline(path: Path, code: str) -> str: ...
 ```
 
-Walks top-level `ast` nodes:
-- `ClassDef` → `[Class] Name (Lines X-Y)` + docstring + recurse for methods
-- `FunctionDef` → `[Func] Name (Lines X-Y)` or `[Method] Name` if nested
+Walks the full `ast` tree (not just top-level), recursively descending into:
+- `ClassDef` → `[Class] Name (Lines X-Y)` + first line of docstring + recurse for methods
+- `FunctionDef` → `[Func] Name (Lines X-Y)` (or `[Method] Name` when nested inside a class), with an optional ` -> ReturnType` suffix when the function has a return annotation
 - `AsyncFunctionDef` → `[Async Func] Name (Lines X-Y)`
+- `with imscope.*` / `with imgui.*` blocks → `[ImGui Scope] <context_expr> (Lines X-Y)` (uses `ast.unparse` on the context expression)
 
-Only extracts first line of docstrings. Uses indentation depth as heuristic for method vs function.
+Only extracts the first line of docstrings (via `ast.get_docstring(node).splitlines()[0]`). Method vs. function distinction is by `indent > 0` in the walker. There is a `count[0] > 100000` overflow guard against pathological `ast` trees (e.g. malformed input that loops the walker).
+
+`get_outline(path, code)` is a thin dispatcher at module level that calls `CodeOutliner().outline(code)` for `.py` files and returns `"Outlining not supported for {suffix} files yet."` for any other extension.
+
+The `__init__` on `src/outline_tool.py:38-40` is an empty pass — the class is stateless, so the class is more of a namespace than a true instance.
 
 ---