Clean up repository root: move visualizations and summaries to docs/

CONTRIBUTING.md

@@ -293,10 +293,10 @@ Contributions should respect the modular structure:
 ```
 neuro-coherence-framework/
 ├── simulations/        # Core computational models
-├── analysis/          # Data analysis tools
-├── visualization/     # Plotting and visualization
-├── tools/            # Utilities and calculators
-├── docs/             # Documentation
+├── analysis/          # Data analysis tools (EEG, fMRI, integration)
+├── data/             # Data generation and resources
+├── docs/             # Documentation, summaries, and figures
+├── examples/         # Usage examples and demos
 └── tests/            # Test suite
 ```
 

README.md

@@ -244,9 +244,6 @@ neuro-coherence-framework/
 ├── LICENSE                            # MIT License
 ├── CONTRIBUTING.md                    # Contribution guidelines
 ├── CITATION.cff                       # Citation format
-├── CI_SETUP_COMPLETE.md               # CI configuration notes
-├── IMPLEMENTATION_SUMMARY.md          # Implementation status
-├── WORKFLOW_SUMMARY.md                # Workflow documentation
 │
 ├── setup.py                           # Package setup
 ├── setup.cfg                          # Setup configuration
@@ -255,9 +252,27 @@ neuro-coherence-framework/
 │
 ├── docs/                              # Documentation
 │   ├── CI.md                          # CI/CD documentation
-│   └── theoretical-framework/         # Theory & mathematical foundations
-│       ├── 02-neuro-coherence-function.md
-│       └── 03-operators.md
+│   ├── CI_SETUP_COMPLETE.md           # CI configuration notes
+│   │
+│   ├── theoretical-framework/         # Theory & mathematical foundations
+│   │   ├── 02-neuro-coherence-function.md
+│   │   └── 03-operators.md
+│   │
+│   ├── summaries/                     # Analysis & summary documents
+│   │   ├── AI_PERSPECTIVE_ANALYSIS.md # AI analysis of framework
+│   │   ├── FINDINGS_SUMMARY.md        # Repository findings
+│   │   ├── IMPLEMENTATION_SUMMARY.md  # Implementation status
+│   │   ├── READING_GUIDE.md           # Guide to understanding the repo
+│   │   └── WORKFLOW_SUMMARY.md        # Workflow documentation
+│   │
+│   └── figures/                       # Generated visualizations
+│       ├── longitudinal_analysis.png
+│       ├── multimodal_comparison.png
+│       ├── operator_correlations.png
+│       ├── parameter_sensitivity.png
+│       ├── perturbation_experiment.png
+│       ├── quickstart_results.png
+│       └── recovery_comparison.png
 │
 ├── simulations/                       # Computational Models
 │   └── core/                          # Core implementations
@@ -301,18 +316,9 @@ neuro-coherence-framework/
 │   ├── full_analysis.py              # Complete workflow
 │   └── custom_simulation.py          # Customization guide
 │
-├── .github/                           # GitHub automation
-│   └── workflows/
-│       └── ci.yml                    # Continuous integration
-│
-└── *.png                              # Generated visualizations
-    ├── longitudinal_analysis.png
-    ├── multimodal_comparison.png
-    ├── operator_correlations.png
-    ├── parameter_sensitivity.png
-    ├── perturbation_experiment.png
-    ├── quickstart_results.png
-    └── recovery_comparison.png
+└── .github/                           # GitHub automation
+    └── workflows/
+        └── ci.yml                    # Continuous integration
 ```
 
 ---
@@ -354,7 +360,7 @@ Its purpose is to test **computational predictions**, not propose treatment.
 - Multimodal biomarker integration  
 - Simulation architecture  
 
-(Diagrams live in `visualization/figures/`.)
+(Generated diagrams are stored in `docs/figures/`.)
 
 ---
 

IMPLEMENTATION_SUMMARY.md → docs/summaries/IMPLEMENTATION_SUMMARY.md

@@ -106,7 +106,7 @@ Depressive Ψ (mean): 0.1815
 - Episode highlighting
 
 **Generated Figures** (7 total):
-1. `quickstart_results.png` - 4-panel overview
+1. `docs/figures/quickstart_results.png` - 4-panel overview
 2. `perturbation_experiment.png` - Multiple perturbations
 3. `parameter_sensitivity.png` - 4-parameter analysis
 4. `recovery_comparison.png` - Recovery rates

READING_GUIDE.md → docs/summaries/READING_GUIDE.md

@@ -82,13 +82,13 @@ Bipolar disorder = coherence breakdown, not just chemical imbalance
 
 **Visual Evidence:**
 Look at the generated PNG files:
-1. `quickstart_results.png` - Basic Ψ across states
-2. `longitudinal_analysis.png` - Temporal dynamics
-3. `parameter_sensitivity.png` - Operator impacts
-4. `multimodal_comparison.png` - EEG + fMRI integration
-5. `perturbation_experiment.png` - Recovery curves
-6. `recovery_comparison.png` - Healing dynamics
-7. `operator_correlations.png` - How operators relate to Ψ
+1. `docs/figures/quickstart_results.png` - Basic Ψ across states
+2. `docs/figures/longitudinal_analysis.png` - Temporal dynamics
+3. `docs/figures/parameter_sensitivity.png` - Operator impacts
+4. `docs/figures/multimodal_comparison.png` - EEG + fMRI integration
+5. `docs/figures/perturbation_experiment.png` - Recovery curves
+6. `docs/figures/recovery_comparison.png` - Healing dynamics
+7. `docs/figures/operator_correlations.png` - How operators relate to Ψ
 
 **Then Read:**
 - `FINDINGS_SUMMARY.md` to understand what you're seeing
@@ -216,7 +216,7 @@ Each PNG file corresponds to an example script. See `examples/README.md` for whi
 ### **Sequence A: Quick Understanding (30 minutes)**
 1. `FINDINGS_SUMMARY.md` (10 min)
 2. `README.md` - skim key sections (10 min)
-3. Look at `quickstart_results.png` (2 min)
+3. Look at `docs/figures/quickstart_results.png` (2 min)
 4. `AI_PERSPECTIVE_ANALYSIS.md` - Executive Summary (8 min)
 
 ### **Sequence B: Evaluation for Research (1 hour)**
@@ -282,7 +282,7 @@ Neuro-Coherence-Framework/
 ├── 📁 tests/                       ← Test suite
 ├── 📁 data/synthetic/              ← Data generators
 │
-└── 📊 *.png                        ← Generated results
+└── 📁 docs/figures/                ← Generated visualizations
     ├── quickstart_results.png
     ├── longitudinal_analysis.png
     └── ... (7 total)

examples/custom_simulation.py

@@ -65,8 +65,8 @@ def run_perturbation_experiment():
     ax.grid(alpha=0.3)
 
     plt.tight_layout()
-    plt.savefig("perturbation_experiment.png", dpi=150)
-    print("Saved: perturbation_experiment.png\n")
+    plt.savefig("docs/figures/perturbation_experiment.png", dpi=150)
+    print("Saved: docs/figures/perturbation_experiment.png\n")
 
 
 def run_parameter_sensitivity():
@@ -139,8 +139,8 @@ def run_parameter_sensitivity():
         ax.legend()
 
     plt.tight_layout()
-    plt.savefig("parameter_sensitivity.png", dpi=150)
-    print("Saved: parameter_sensitivity.png\n")
+    plt.savefig("docs/figures/parameter_sensitivity.png", dpi=150)
+    print("Saved: docs/figures/parameter_sensitivity.png\n")
 
 
 def run_recovery_comparison():
@@ -181,8 +181,8 @@ def run_recovery_comparison():
     ax.grid(alpha=0.3)
 
     plt.tight_layout()
-    plt.savefig("recovery_comparison.png", dpi=150)
-    print("Saved: recovery_comparison.png\n")
+    plt.savefig("docs/figures/recovery_comparison.png", dpi=150)
+    print("Saved: docs/figures/recovery_comparison.png\n")
 
 
 def run_operator_correlation():
@@ -255,8 +255,8 @@ def run_operator_correlation():
         ax.grid(alpha=0.3)
 
     plt.tight_layout()
-    plt.savefig("operator_correlations.png", dpi=150)
-    print("Saved: operator_correlations.png\n")
+    plt.savefig("docs/figures/operator_correlations.png", dpi=150)
+    print("Saved: docs/figures/operator_correlations.png\n")
 
 
 def main():
@@ -276,10 +276,10 @@ def main():
     print("=" * 60)
     print()
     print("Generated files:")
-    print("  - perturbation_experiment.png")
-    print("  - parameter_sensitivity.png")
-    print("  - recovery_comparison.png")
-    print("  - operator_correlations.png")
+    print("  - docs/figures/perturbation_experiment.png")
+    print("  - docs/figures/parameter_sensitivity.png")
+    print("  - docs/figures/recovery_comparison.png")
+    print("  - docs/figures/operator_correlations.png")
     print()
 
 

examples/full_analysis.py

@@ -176,8 +176,8 @@ def compare_healthy_vs_bipolar():
     ax.grid(axis="y", alpha=0.3)
 
     plt.tight_layout()
-    plt.savefig("multimodal_comparison.png", dpi=150)
-    print("\nSaved: multimodal_comparison.png")
+    plt.savefig("docs/figures/multimodal_comparison.png", dpi=150)
+    print("\nSaved: docs/figures/multimodal_comparison.png")
 
     return results
 
@@ -259,8 +259,8 @@ def longitudinal_analysis():
     ax.grid(alpha=0.3)
 
     plt.tight_layout()
-    plt.savefig("longitudinal_analysis.png", dpi=150)
-    print("Saved: longitudinal_analysis.png")
+    plt.savefig("docs/figures/longitudinal_analysis.png", dpi=150)
+    print("Saved: docs/figures/longitudinal_analysis.png")
 
 
 def main():
@@ -291,8 +291,8 @@ def main():
     print("Analysis Complete!")
     print("=" * 60)
     print("\nGenerated files:")
-    print("  - multimodal_comparison.png")
-    print("  - longitudinal_analysis.png")
+    print("  - docs/figures/multimodal_comparison.png")
+    print("  - docs/figures/longitudinal_analysis.png")
     print()
 
 

examples/quickstart.py

@@ -163,7 +163,7 @@ def main():
     plt.tight_layout()
 
     # Save figure
-    output_file = "quickstart_results.png"
+    output_file = "docs/figures/quickstart_results.png"
     plt.savefig(output_file, dpi=150, bbox_inches="tight")
     print(f"   Figure saved to: {output_file}")
     print()