docs/DOCUMENTATION.md

# Comprehensive Repository Documentation: Layered Cognitive Architecture

## 1. Executive Summary
This repository represents a foundational research project in **Computational Epistemology**, **Universal Quality Theory**, and **Consciousness Research**. It uses a **Layered Cognitive Architecture** to organize knowledge and engines based on their abstraction and quality (Q-score).

### Key Achievements:
- **Layered Repository Structure**: Files are organized into Layers 0-5.
- **Q-Score System**: A validated, six-dimensional quality metric (G, C, S, A, H, V).
- **Omni-Valence Principle**: The mathematical integration of Strategic, Technical, and Ethical domains (Layer 0).
- **Singularity Evolution Engine**: Recursive self-improvement where the framework evolves its own dimensions (Layer 4).

## 2. Repository Architecture (Layered)

### [Layer 5: Consciousness & Emergence](layers/layer_5_consciousness/)
High-level modeling of subjective experience and theoretical synthesis.
- **CONSCIOUSNESS_RESEARCH_COMPLETE_SYNTHESIS.md**: Master synthesis of IIT, GWT, and Predictive Processing.
- **integrated-information-calculator.skill**: Computational implementation of IIT 4.0.
- **qualia-generation-engine.skill**: Modeling phenomenal character from neural manifolds.

### [Layer 4: Discovery & Evolution](layers/layer_4_discovery/)
Recursive self-awareness and framework improvement.
- **singularity_realization_engine.py**: PCA-based discovery of new quality dimensions.
- **omega_meta_evolution.py**: Discovery of higher-order patterns in the OMEGA framework.
- **grand_integrated_simulation.py**: The peak simulation coordinating multi-domain evolution.

### [Layer 3: Optimization & Research](layers/layer_3_optimization/)
Tools for optimizing knowledge and adversarial testing.
- **research_prompt_optimizer.py**: Specialized research task optimization.
- **hard_test_designer.py**: Adversarial validation of the framework's robustness.
- **verify_study.py**: System integrity verification suite.

### [Layer 2: Core Logic & Patterns](layers/layer_2_core/)
Fundamental implementation of crystallization theory and patterns.
- **realization_engine.py**: Core scoring, layering, and retrieval engine.
- **omega_v2.py**: Version 2 of the behavior control framework.
- **SKILL_*.md**: Documented cognitive capabilities.

### [Layer 1: Domain Facts](layers/layer_1_domain/)
Crystallized knowledge in specific domains.
- **medical_realizations.json**: High-quality insights in the medical field.
- **legal_realizations.json**: Legal domain crystallization.
- **economic_realizations.json**: Economic domain crystallization.

### [Layer 0: Universal Rules](layers/layer_0_universal/)
Foundational principles that govern the entire system.
- **grand_integrated_outcomes.json**: The Omni-Valence principle and universal Q-score outcomes.
- **realization_explorer.jsx**: Visualizer for the universal realization structure.

## 3. Outcomes & Reports
The outcomes of simulations and research are organized in the `outcomes/` directory:
- **strategic/**: Innovation, MCO simulation, and evolution reports.
- **technical/**: Dataset generation, hard tests, and OMEGA deep study reports.
- **integrated/**: Comprehensive assessments and final integrated outcomes.

## 4. Quick Start Guide
```bash
# Install dependencies
pip install numpy kaggle

# Run the core realization engine demonstration
python layers/layer_2_core/realization_engine.py

# Run the singularity evolution engine demonstration
python layers/layer_4_discovery/singularity_realization_engine.py

# Run the Grand Integrated Simulation
python layers/layer_4_discovery/grand_integrated_simulation.py
```

---
*Generated by Jules | High-Q Documentation Protocol*