Reorganize documentation structure and streamline CLAUDE.md

- Restructure docs/ with logical organization:
  - architecture/ for technical design docs
  - specifications/ for feature specs
  - development/ for testing guides and implementation notes
- Break down monolithic TODO.md into focused documents:
  - roadmap.md for feature priorities
  - competitive-analysis.md for missing features analysis
  - development/implementation-notes.md for technical priorities
- Update testing documentation to match current 18+ test suite
- Streamline CLAUDE.md from 190 to 62 lines (67% reduction)
- Fix documentation errors: module counts, test infrastructure, architecture
- Add comprehensive navigation guide (docs/README.md)

Author: Bryan Howard

CLAUDE.md

@@ -1,189 +1,61 @@
 # CLAUDE.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
 ## Project Overview
 
-PyFlowGraph is a universal node-based visual scripting editor built with Python and PySide6. It allows users to create, connect, and execute Python code as nodes in a data-driven graph. The project follows a "Code as Nodes" philosophy where pins are automatically generated by parsing Python function signatures.
-
-## Common Commands
-
-### Running the Application
-
-- **Windows**: `run.bat` or `.\run.bat`
-- **Linux/macOS**: `./run.sh`
-- Both scripts automatically activate the virtual environment and run `src/main.py`
-
-### Environment Setup
-
-1. Create virtual environment: `python3 -m venv venv`
-2. Activate environment:
-   - Windows: `venv\Scripts\activate`
-   - Linux/macOS: `source venv/bin/activate`
-3. Install dependencies: `pip install PySide6`
-
-### Virtual Environment Management
-
-- The application creates project-specific virtual environments in the `venvs/` directory
-- Each graph can have its own isolated environment with custom pip dependencies
-- Use "Run > Manage Environment" in the application to configure environments
-
-## Architecture Overview
+PyFlowGraph: Universal node-based visual scripting editor built with Python and PySide6. "Code as Nodes" philosophy with automatic pin generation from Python function signatures.
 
-### Core Application Structure
+## Commands
 
-All source code is organized in the `src/` directory:
+**Running**: `run.bat` (Windows) or `./run.sh` (Linux/macOS)
+**Testing**: `run_test_gui.bat` - Professional GUI test runner
+**Dependencies**: `pip install PySide6`
 
-- **src/main.py**: Entry point, loads Font Awesome fonts and QSS stylesheet
-- **src/node_editor_window.py**: Main QMainWindow with menus, toolbars, and dock widgets
-- **src/node_editor_view.py**: QGraphicsView handling mouse/keyboard interactions (pan, zoom, copy/paste)
-- **src/node_graph.py**: QGraphicsScene managing nodes, connections, and clipboard operations
-- **src/graph_executor.py**: Execution engine that runs node graphs using subprocess isolation
+## Architecture
 
-### Node System
+**Core**: `src/` contains 25+ Python modules
+- `main.py` - Entry point with Font Awesome fonts/QSS
+- `node_editor_window.py` - Main QMainWindow
+- `node_editor_view.py` - QGraphicsView (pan/zoom/copy/paste)
+- `node_graph.py` - QGraphicsScene (nodes/connections/clipboard)
+- `graph_executor.py` - Execution engine with subprocess isolation
+- `commands/` - Command pattern for undo/redo system
 
-- **src/node.py**: Main Node class with automatic pin generation from Python function parsing
-- **src/pin.py**: Input/output connection points with type-based coloring
-- **src/connection.py**: Bezier curve connections between pins
-- **src/reroute_node.py**: Simple organizational nodes for connection routing
-
-### Code Editing
-
-- **src/code_editor_dialog.py**: Modal dialog containing the code editor
-- **src/python_code_editor.py**: Core editor widget with line numbers and smart indentation
-- **src/python_syntax_highlighter.py**: Python syntax highlighting implementation
-
-### Event System
-
-- **src/event_system.py**: Event-driven execution system for interactive applications with live mode support
-
-### Utilities
-
-- **src/color_utils.py**: Color manipulation utilities
-- **src/environment_manager.py**: Virtual environment management dialog
-- **src/settings_dialog.py**: Application settings configuration
-- **src/node_properties_dialog.py**: Node property editing interface
-- **src/ui_utils.py**: Common UI utility functions and helpers
-- **src/view_state_manager.py**: View state management for zoom and pan operations
-- **src/execution_controller.py**: Central execution control and coordination
-- **src/file_operations.py**: File loading, saving, and import/export operations
-- **src/flow_format.py**: Markdown flow format parsing and serialization
-- **src/test_runner_gui.py**: Professional GUI-based test runner for development
+**Node System**: `node.py`, `pin.py`, `connection.py`, `reroute_node.py`
+**Code Editing**: `code_editor_dialog.py`, `python_code_editor.py`, `python_syntax_highlighter.py`
+**Event System**: `event_system.py` - Live mode execution support
 
 ## Key Concepts
 
-### Node Function Parsing
-
-- Nodes automatically generate input pins from function parameters with type hints
-- Output pins are created from return type annotations
-- Supports single outputs (`-> str`) and multiple outputs (`-> Tuple[str, int]`)
-- Type hints determine pin colors: `int`, `str`, `float`, `bool`, `Tuple`
-
-### Data Flow Execution
-
-- Graph execution is data-driven, not control-flow based
-- Nodes execute when all input dependencies are satisfied
-- Each node runs in an isolated subprocess for security
-- Pin values are serialized/deserialized as JSON between nodes
-- Supports both **Batch Mode** (traditional sequential execution) and **Live Mode** (event-driven interactive execution)
-
-### Graph Persistence
-
-- Graphs save to clean JSON format in the `examples/` directory
-- Node positions, connections, and code are preserved
-- Virtual environment requirements are stored with each graph
+**Node Function Parsing**: Automatic pin generation from Python function signatures with type hints
+**Data Flow Execution**: Data-driven (not control-flow), subprocess isolation, JSON serialization
+**Graph Persistence**: Clean JSON format, saved to `examples/` directory
 
 ## File Organization
 
-### Project Structure
-
-The project follows a clean, organized structure:
-
 ```
 PyFlowGraph/
-├── src/                     # All Python source code
-│   ├── resources/          # Font Awesome fonts embedded in src
-│   └── test_runner_gui.py  # Professional GUI test runner
-├── tests/                   # All test files  
-├── docs/                    # Static documentation
-├── test_reports/           # Generated test outputs and summaries
-├── examples/               # Sample graph files (10 examples)
-├── images/                 # Screenshots and documentation images
-├── pre-release/            # Pre-built releases and binaries
-├── venv/                   # Main application virtual environment
-├── venvs/                  # Project-specific virtual environments  
-├── .github/workflows/      # CI/CD pipeline
-├── run.bat, run.sh         # Application launcher scripts
-├── run_test_gui.bat        # Professional test runner GUI launcher
-├── dark_theme.qss          # Application stylesheet
-├── requirements.txt        # Python dependencies
-├── LICENSE.txt             # Project license
-├── README.md              # Project readme
-└── CLAUDE.md              # This file
+├── src/                    # 25+ Python modules + commands/
+├── tests/                  # 18+ test files with GUI test runner
+├── docs/                   # Organized documentation
+│   ├── architecture/       # Technical architecture docs
+│   ├── specifications/     # Feature specs (flow_spec.md, ui-ux, etc.)
+│   └── development/        # Testing guides, implementation notes
+├── examples/               # Sample .md graph files
+├── venv/ + venvs/         # Virtual environments
+└── run.bat, run_test_gui.bat # Launchers
 ```
 
-### Core Directories
-
-- **`src/`**: All 24 Python modules organized in one location
-- **`tests/`**: 7 test files with comprehensive GUI and execution testing
-- **`docs/`**: Hand-written documentation (flow_spec.md, test guides)
-- **`test_reports/`**: Auto-generated test outputs and summaries
-- **`examples/`**: 10 sample .md graph files demonstrating features
-- **`images/`**: Screenshots and documentation images for project visualization
-- **`pre-release/`**: Pre-built application binaries and releases
-- **`venv/`**: Main application virtual environment
-- **`venvs/`**: Isolated Python environments for individual graph execution
-
 ## Testing
 
-### Test Organization
-
-The test suite is organized around PyFlowGraph's core functional components:
-
-- **tests/test_node_system.py**: Core Node functionality (creation, properties, code management, serialization)
-- **tests/test_pin_system.py**: Pin creation, type detection, positioning, and connection compatibility  
-- **tests/test_connection_system.py**: Connection/bezier curve creation, serialization, and reroute nodes
-- **tests/test_graph_management.py**: Graph operations (node/connection management, clipboard, clearing)
-- **tests/test_execution_engine.py**: Code execution, flow control, subprocess isolation, error handling
-- **tests/test_file_formats.py**: Markdown and JSON format parsing, conversion, and file operations
-- **tests/test_integration.py**: End-to-end workflows and real-world usage scenarios
-
-### Running Tests
-
-- **Test GUI**: `run_test_gui.bat` - Professional PySide6 test runner with visual interface
-- **Manual**: `python tests/test_name.py` - Individual test files  
-- **Direct GUI**: `python src/test_runner_gui.py` - Run test GUI directly
-
-### Test Runner Features
-
-The new test runner GUI provides:
-- Automatic test discovery from the `tests/` directory
-- Visual test selection with checkboxes
-- Real-time status indicators (green/red circles for pass/fail)
-- Detailed test output viewing with syntax highlighting
-- Background execution with progress tracking
-- 5-second timeout per test for fast feedback
-- Professional dark theme matching the main application
-
-### Test Design Principles
-
-- **Focused Coverage**: Each test module covers a single core component
-- **Fast Execution**: All tests complete within 5 seconds total runtime
-- **Deterministic**: Tests are reliable and not flaky
-- **Comprehensive**: 100% coverage of fundamental functionality
-- **Integration Testing**: Real-world usage scenarios and error conditions
+**Current Suite**: 18+ test files covering node system, pins, connections, execution, file formats
+**GUI Runner**: `run_test_gui.bat` - Professional PySide6 interface with real-time status
+**Coverage**: Core components, command system, integration scenarios
 
 ## Development Notes
 
-- This is an experimental AI-generated codebase for learning purposes
-- The application uses PySide6 for the Qt-based GUI  
-- Font Awesome integration provides professional iconography
-- All nodes execute in isolated environments for security
-- Dependencies are managed via `requirements.txt` (PySide6, Nuitka for compilation)
-- Don't add claude attribution to git commits. Don't ever add that it was generated with claude at the end of comments. This is bloat! Stop that!
-- Don't use emoji's in code! it always fucks things up.
-
-## Documentation and markdown files
-
-- no emoji in code. no em dashes.
-- no marketing BS. Only clean, professional, technical
+- Experimental AI-generated codebase for learning
+- PySide6 Qt-based GUI with Font Awesome icons
+- Isolated subprocess execution for security
+- No Claude attribution in commits or code comments
+- No emojis in code - causes issues
+- Clean, professional, technical documentation only

docs/README.md

@@ -0,0 +1,50 @@
+# PyFlowGraph Documentation
+
+This directory contains comprehensive documentation for the PyFlowGraph project, organized by purpose and audience.
+
+## Quick Navigation
+
+### For Product Strategy & Planning
+- **[PRD](prd.md)** - Product Requirements Document
+- **[Roadmap](roadmap.md)** - Feature development roadmap and priorities
+- **[Competitive Analysis](competitive-analysis.md)** - Missing features vs competitors
+
+### For Architecture & Technical Design
+- **[Technical Architecture](architecture/technical_architecture.md)** - Core system architecture
+- **[Brownfield Architecture](architecture/brownfield-architecture.md)** - Legacy system considerations
+- **[Source Tree](architecture/source-tree.md)** - Codebase organization
+- **[Tech Stack](architecture/tech-stack.md)** - Technology choices and rationale
+- **[Coding Standards](architecture/coding-standards.md)** - Development guidelines
+
+### For Feature Specifications
+- **[Flow Specification](specifications/flow_spec.md)** - Core flow format specification
+- **[UI/UX Specifications](specifications/ui-ux-specifications.md)** - Interface design specs
+- **[Priority 1 Features](specifications/priority-1-features-project-brief.md)** - Critical feature brief
+
+### For Development & Implementation
+- **[Testing Guide](development/testing-guide.md)** - Test runner and testing strategies
+- **[Implementation Notes](development/implementation-notes.md)** - Technical implementation priorities
+- **[Fixes Directory](development/fixes/)** - Specific implementation and fix plans
+
+## Document Organization
+
+### Strategic Documents
+High-level product and business documentation for stakeholders and product planning.
+
+### Architecture Documents
+Technical architecture, system design, and structural documentation for architects and senior developers.
+
+### Specifications
+Detailed feature and interface specifications for development teams.
+
+### Development Documentation
+Implementation guides, testing procedures, and development tooling for active contributors.
+
+## Contributing to Documentation
+
+When adding new documentation:
+- Place strategic docs in the root `docs/` directory
+- Place technical architecture in `architecture/`
+- Place feature specs in `specifications/`
+- Place implementation details in `development/`
+- Update this README with new document links