improved readme and fixed cpack config

Author: rxdu

.github/workflows/ci.yml

@@ -93,7 +93,7 @@ jobs:
         # Use summary instead of list for more reliable output across versions
         echo "Coverage Summary:"
         /usr/bin/lcov --summary ./build/coverage.info
-    - uses: codecov/codecov-action@v4
+    - uses: codecov/codecov-action@v5
       if: github.ref == 'refs/heads/main'
       with:
         fail_ci_if_error: true 

CMakeLists.txt

@@ -116,7 +116,7 @@ install(TARGETS graph
     RUNTIME DESTINATION bin
     INCLUDES DESTINATION include)
 
-install(DIRECTORY src/include/graph
+install(DIRECTORY include/graph
     DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
 
 # export target configuration 

README.md

@@ -14,75 +14,30 @@ A modern, header-only C++11 library for graph construction and pathfinding algor
 - **Robust**: Comprehensive exception handling, structure validation, memory safety via RAII
 - **Well-Documented**: Extensive API reference, tutorials, and working examples
 
----
-
-## Quick Start (5 minutes)
-
-### Installation
-```bash
-# Header-only - just copy and include
-git clone https://github.com/rxdu/libgraph.git
-cp -r libgraph/include/graph /your/project/
-
-# OR: System install with CMake
-mkdir build && cd build && cmake .. && sudo make install
+### Generic State Types
+```cpp
+struct GameState {
+    int x, y, health, ammo;
+    int64_t GetId() const { return y*1000 + x; }  // Auto-detected by DefaultIndexer
+};
+Graph<GameState> game_world;
 ```
 
-### Your First Graph
+### Custom Cost Types
 ```cpp
-#include "graph/graph.hpp"
-#include "graph/search/dijkstra.hpp"
-
-struct Location { int id; std::string name; };
-
-// Create graph and add vertices
-Graph<Location> map;
-map.AddVertex({0, "Home"});
-map.AddVertex({1, "Work"}); 
-map.AddVertex({2, "Store"});
-
-// Add weighted edges (distances)
-map.AddEdge({0, "Home"}, {1, "Work"}, 5.0);
-map.AddEdge({0, "Home"}, {2, "Store"}, 3.0);
-map.AddEdge({2, "Store"}, {1, "Work"}, 4.0);
-
-// Find optimal path
-auto path = Dijkstra::Search(map, {0, "Home"}, {1, "Work"});
-// Result: Home -> Store -> Work (7km total, shorter than direct 5km route)
+struct TravelCost {
+    double time, distance, comfort;
+    bool operator<(const TravelCost& other) const { /* lexicographic comparison */ }
+};
+Graph<Location, TravelCost> multi_criteria_graph;
 ```
 
-**[Complete Getting Started Guide →](docs/getting_started.md)**
-
----
-
-## Documentation
-
-### **For New Users**
-- **[Getting Started Guide](docs/getting_started.md)** - From zero to working graph in 20 minutes
-- **[Complete API Reference](docs/api.md)** - All classes, methods, and examples
-- **[Tutorial Series](docs/tutorials/)** - Progressive learning path
-
-### **For Advanced Users** 
-- **[Architecture Overview](docs/architecture.md)** - System design and template patterns
-- **[Advanced Features](docs/advanced_features.md)** - Custom costs, validation, thread safety
-- **[Search Algorithms Guide](docs/search_algorithms.md)** - Deep dive into A*, Dijkstra, BFS, DFS
-
-### **For Contributors**
-- **[Performance Testing](docs/performance_testing.md)** - Benchmarking and optimization
-- **[Thread Safety Design](docs/thread_safety_design.md)** - Concurrent search architecture
-- **[Search Framework](docs/search_framework.md)** - Modern strategy pattern implementation
-
----
-
-## Use Cases & Applications
-
-| **Domain** | **Use Case** | **Algorithm** | **Key Feature** |
-|------------|--------------|---------------|-----------------|
-| **Game Development** | NPC pathfinding, map navigation | A* with heuristics | Grid-based movement, obstacle avoidance |
-| **Robotics** | Motion planning, SLAM | Dijkstra, A* | Real-time path updates, dynamic costs |
-| **GPS Navigation** | Route planning, traffic optimization | Dijkstra with custom costs | Multi-criteria optimization (time, distance, cost) |
-| **Network Analysis** | Social graphs, web crawling | BFS, DFS | Large-scale graph traversal |
-| **Data Science** | Dependency analysis, workflow management | Topological sort, DFS | DAG processing, cycle detection |
+### Performance Optimization
+```cpp
+graph.reserve(10000);           // Pre-allocate vertices
+context.PreAllocate(10000);     // Pre-allocate search state
+graph.AddVertices(state_list);  // Batch operations
+```
 
 ---
 
@@ -100,7 +55,7 @@ template<typename State, typename Transition = double, typename StateIndexer = D
 class Graph;
 ```
 - **State**: Your vertex data (locations, game states, etc.)
-- **Transition**: Edge weights (distance, time, cost, custom types) 
+- **Transition**: Edge weights (distance, time, cost, custom types)
 - **StateIndexer**: Automatic ID generation from states
 
 ### Performance Characteristics
@@ -113,9 +68,7 @@ Optimal space complexity O(m+n) using adjacency lists:
 | Search Algorithms | O((m+n) log n) | O(n) |
 | Thread-Safe Search | O((m+n) log n) | O(n) per context |
 
----
-
-## Thread Safety
+### Thread Safety
 
 **Concurrent read-only searches** are fully supported:
 ```cpp
@@ -130,35 +83,6 @@ void worker_thread(const Graph<Location>& map) {
 
 ---
 
-## Advanced Features
-
-### Custom Cost Types
-```cpp
-struct TravelCost {
-    double time, distance, comfort;
-    bool operator<(const TravelCost& other) const { /* lexicographic comparison */ }
-};
-Graph<Location, TravelCost> multi_criteria_graph;
-```
-
-### Generic State Types  
-```cpp
-struct GameState {
-    int x, y, health, ammo;
-    int64_t GetId() const { return y*1000 + x; }  // Auto-detected by DefaultIndexer
-};
-Graph<GameState> game_world;
-```
-
-### Performance Optimization
-```cpp
-graph.reserve(10000);           // Pre-allocate vertices
-context.PreAllocate(10000);     // Pre-allocate search state
-graph.AddVertices(state_list);  // Batch operations
-```
-
----
-
 ## Build & Integration
 
 ### Requirements
@@ -168,7 +92,7 @@ graph.AddVertices(state_list);  // Batch operations
 
 ### Integration Options
 
-#### 1. Header-Only (Recommended)
+#### 1. Header-Only
 ```bash
 git clone https://github.com/rxdu/libgraph.git
 cp -r libgraph/include/graph /your/project/include/
@@ -196,6 +120,13 @@ find_package(graph REQUIRED)
 target_link_libraries(your_app PRIVATE xmotion::graph)
 ```
 
+#### 4. Debian Package Installation
+```bash
+mkdir build && cd build
+cmake -DCMAKE_BUILD_TYPE=Release .. && make -j4 && cpack
+sudo dpkg -i graph_3.0.0_amd64.deb  # Adjust version as needed
+```
+
 ### Build Examples and Tests
 ```bash
 git clone --recursive https://github.com/rxdu/libgraph.git
@@ -211,90 +142,49 @@ cmake --build .
 ./bin/utests
 ```
 
----
-
-## Performance Testing
-
-This library includes comprehensive performance benchmarks to evaluate graph operations and search algorithms across different scales.
+### Your First Graph
+```cpp
+#include "graph/graph.hpp"
+#include "graph/search/dijkstra.hpp"
 
-### Quick Performance Test
+struct Location { int id; std::string name; };
 
-Run the unified benchmark suite to get a complete performance analysis:
+// Create graph and add vertices
+Graph<Location> map;
+map.AddVertex({0, "Home"});
+map.AddVertex({1, "Work"}); 
+map.AddVertex({2, "Store"});
 
-```bash
-# Build the library with benchmarks
-mkdir build && cd build
-cmake -DBUILD_TESTING=ON ..
-cmake --build .
+// Add weighted edges (distances)
+map.AddEdge({0, "Home"}, {1, "Work"}, 5.0);
+map.AddEdge({0, "Home"}, {2, "Store"}, 3.0);
+map.AddEdge({2, "Store"}, {1, "Work"}, 4.0);
 
-# Run comprehensive performance tests
-../scripts/run_unified_benchmarks.sh
+// Find optimal path
+auto path = Dijkstra::Search(map, {0, "Home"}, {1, "Work"});
+// Result: Home -> Store -> Work (7km total, shorter than direct 5km route)
 ```
 
-The benchmark generates a single comprehensive report file that includes:
-
-- **Micro-benchmarks**: Operation-level performance analysis (edge lookup, vertex removal, search context)
-- **Large-scale benchmarks**: Realistic workload testing (10K-1M+ vertices)
-- **Memory scaling**: Memory usage patterns by graph size
-- **Concurrent performance**: Multi-threaded search throughput
-- **Optimization targets**: Specific recommendations with expected improvements
-
-### Performance Results
-
-The test outputs results to `performance_results/unified_benchmark_results_<timestamp>.txt` with sections:
-
-1. **Edge Lookup Performance**: Current O(n) linear search analysis
-2. **Vertex Removal Performance**: Current O(m²) removal operation analysis  
-3. **Search Context Performance**: Memory allocation vs. reuse patterns
-4. **Concurrent Search Performance**: Threading scalability analysis
-5. **Graph Construction Performance**: Large-scale graph creation benchmarks
-6. **Search Algorithm Scaling**: Dijkstra/BFS/DFS performance comparison
-7. **Memory Scaling Analysis**: Memory efficiency by graph size
-8. **Optimization Recommendations**: Specific targets for performance improvements
-
-### System Requirements
-
-- **Memory**: 2GB+ recommended for large-scale tests
-- **CPU**: Multi-core recommended for concurrent benchmarks
-- **Time**: 2-5 minutes depending on system performance
-
-### Using Results for Optimization
-
-The benchmark results serve as baseline measurements for quantitative evaluation of performance optimizations:
-
-1. **Save baseline**: Keep initial benchmark results for comparison
-2. **Implement optimization**: Make targeted improvements (e.g., hash-based edge lookup)
-3. **Re-run benchmarks**: Execute the same test suite
-4. **Compare results**: Analyze performance improvements quantitatively
-
-Example optimization targets identified:
-- **Edge Lookup**: O(n) → O(1) hash-based lookup (10-100x improvement expected)
-- **Vertex Removal**: O(m²) → O(m) bidirectional references (2-10x improvement expected)
-- **Memory Pooling**: Reduce context allocation overhead (20-50% improvement expected)
-- **Context Reuse**: Systematic reuse patterns (30-70% improvement expected)
+**[Complete Getting Started Guide →](docs/getting_started.md)**
 
 ---
 
-## Project Status & Quality
-
-### **Mature & Production-Ready**
-- **199 comprehensive tests** (100% pass rate, 1 disabled)
-- **Complete algorithm suite**: A*, Dijkstra, BFS, DFS with unified framework
-- **Thread-safe concurrent searches** with external SearchContext  
-- **Generic cost framework** with custom comparators and lexicographic costs
-- **Enterprise-grade error handling** with 7-tier exception hierarchy
+## Documentation
 
-### **Recent Milestones** (2025)
-- **Phase 3 Complete**: Generic cost types, enhanced testing, sample modernization
-- **Phase 2 Complete**: Performance optimization (35% improvement), STL compatibility 
-- **Phase 1 Complete**: Unified search framework eliminating 70% code duplication
+### **For New Users**
+- **[Getting Started Guide](docs/getting_started.md)** - From zero to working graph in 20 minutes
+- **[Complete API Reference](docs/api.md)** - All classes, methods, and examples
+- **[Tutorial Series](docs/tutorials/)** - Progressive learning path
 
-### **Current Focus** (Phase 4)
-- Graph analysis algorithms (connected components, cycle detection)
-- Enhanced search variants (early termination, hop limits)
-- Extended graph operations (statistics, subgraph extraction)
+### **For Advanced Users**
+- **[Architecture Overview](docs/architecture.md)** - System design and template patterns
+- **[Advanced Features](docs/advanced_features.md)** - Custom costs, validation, thread safety
+- **[Search Algorithms Guide](docs/search_algorithms.md)** - Deep dive into A*, Dijkstra, BFS, DFS
 
-**[Complete Roadmap & TODO List →](TODO.md)**
+### **For Contributors**
+- **[Performance Testing](docs/performance_testing.md)** - Benchmarking and optimization
+- **[Thread Safety Design](docs/thread_safety_design.md)** - Concurrent search architecture
+- **[Search Framework](docs/search_framework.md)** - Modern strategy pattern implementation
 
 ---
 
@@ -324,6 +214,8 @@ This library is distributed under **MIT License**.
 }
 ```
 
+**[→ Complete Roadmap & TODO List](TODO.md)**
+
 ---
 
 **Built for the C++ community**