# Track: SQLite-Granularity Inline Docs for gui_2.py

**Status:** Spec approved 2026-06-12
**Initialized:** 2026-06-12
**Owner:** Tier 2 Tech Lead
**Priority:** Medium (Documentation / UX Maintenance)

---

## 1. Overview
This track introduces **SQLite-style inline documentation** to the codebase's main user interface orchestrator: `src/gui_2.py` (~285KB, ~5400 lines). We will enrich the file's primary entry points, classes, and render modules with strict, descriptive docstrings detailing functional responsibilities, state mutations, parent/child relationships in the immediate-mode rendering DAG, threading limits, and accurate **ASCII layout sketches**.

This track follows the brainstorming guidelines: it focuses purely on building clear, long-form inline documentation panel-by-panel rather than modifying runtime logic.

---

## 2. Goals (Priority Order)

| Priority | Goal | Rationale |
|---|---|---|
| **A** | Document App class constructor & lifecycle entry points (`__init__`, `run`, `_gui_func`, `shutdown`). | Establishes the core window lifecycle and thread-boundaries. |
| **A** | Document the Discussion panel renderer & controls (`render_discussion_entry`, controls, etc.) with layout sketches. | The discussion area is the main interface hub; documenting it clarifies its complex interactive parts. |
| **A** | Document the Context panel & AST inspector (`render_context_composition_panel`, `render_context_files_table`, modals). | Clarifies how context files are listed, annotated, and passed downstream. |
| **B** | Document project/AI settings panels and managers (presets, personas, provider options). | Maps config mutations to disk state. |
| **B** | Document diagnostics, tool analytics, command palette, and approval popups. | Documents helper utilities and security clutch hooks. |

---

## 3. The Documentation Convention
Every target class, method, or function in `src/gui_2.py` gets a Python docstring (`"""`) structured as follows:

1. **Functional Purpose:** Summary of the component's job.
2. **Parameters & Inputs:** Specific types (especially the `app: App` argument).
3. **State Mutations:** Tracked variables mutated within the GUI scope (e.g. `app.show_windows`).
4. **Immediate-Mode DAG Context:**
   - **Called by:** Parent render loop node.
   - **Calls:** Child render functions.
5. **ASCII Layout Sketch:** Exact visual mockup of the panel layout using box-drawing characters and bracket notations (e.g. `[Button]`, `[x] Checkbox`).
6. **Thread Boundaries:** Confirming synchronous main-thread execution within the ImGui window frame.

---

## 4. Phased Breakdown

### Phase 1: App Lifecycle & Setup
- `App.__init__`
- `App.run`
- `App._gui_func`
- `App.shutdown`
- Profile state preservation and undo/redo loops.

### Phase 2: Discussion Panel & Controls
- `render_discussion_entry`
- `render_discussion_entry_controls`
- `truncate_entries`
- Thinking parser.

### Phase 3: Context Panel & AST Inspector
- `render_context_composition_panel`
- `render_context_files_table`
- `render_ast_inspector_modal`
- Batch actions.

### Phase 4: Settings & Hubs
- `render_project_settings_hub`
- `render_projects_panel`
- `render_paths_panel`
- `render_ai_settings_hub`
- `render_agent_tools_panel`
- `render_provider_panel`
- `render_persona_selector_panel`
- Tool preset manager.

### Phase 5: Diagnostics, Analytics & Modals
- `render_diagnostics_panel`
- `render_cache_panel`
- `render_usage_analytics_panel`
- `render_token_budget_panel`
- `render_log_management`
- Command Palette panels.
- Approve modals (HITL).

---

## 5. Verification Criteria
1. **Syntax Integrity:** Run `py_check_syntax` on modified files after every edit to confirm correct AST construction.
2. **Regression Check:** Run `pytest tests/` after each phase. The addition of documentation must not alter execution paths, types, or throw warnings.
