docs: update core README with extended description

README.md

@@ -1,2 +1,105 @@
-# movement-core
-Foundational architecture and governance logic for the Movement Network. This repository defines core principles, system design, and long-term governance models for human–AI coordination.
+# Movement Core
+
+**Foundational architecture and governance logic for the Movement Network**
+
+---
+
+## Overview
+
+`movement-core` defines the foundational principles, system design, and governance framework for the **Movement Network**, enabling secure and scalable human–AI coordination. This repository serves as the backbone for all core protocols, governance mechanisms, and decision-making logic within the ecosystem.
+
+The project aims to:
+
+- Establish a **robust architecture** for decentralized coordination between humans and AI.
+- Define **transparent governance models** that ensure accountability, inclusivity, and scalability.
+- Provide **reference implementations** and tools for developers building on the Movement Network.
+
+---
+
+## Key Features
+
+- **Core Principles**: Philosophical and technical guidelines that drive the system’s design and long-term strategy.
+- **Governance Logic**: Smart contract templates and off-chain models for decentralized decision-making and voting.
+- **System Architecture**: Modular and extensible structure for integrating AI coordination and human oversight.
+- **Security & Compliance**: Frameworks and best practices to maintain integrity, auditability, and resilience.
+
+---
+
+## Architecture Overview
+
+The Movement Network is structured around:
+
+1. **Core Protocol Layer**  
+   - Handles fundamental operations, permissioning, and inter-module interactions.
+
+2. **Governance & Voting Layer**  
+   - On-chain and off-chain governance mechanisms, including role-based access, proposal lifecycle, and execution logic.
+
+3. **AI Coordination Layer**  
+   - Interfaces for human–AI interactions, decision augmentation, and automated execution pipelines.
+
+4. **Integration Layer**  
+   - Connectors for third-party applications, tools, and smart contracts to extend ecosystem capabilities.
+
+---
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js ≥ 20.x  
+- Hardhat or Foundry (for Solidity contracts)  
+- Git  
+
+### Installation
+
+```bash
+git clone https://github.com/cshein45/movement-core.git
+cd movement-core
+npm install
+````
+
+### Running Tests
+
+```bash
+npm test
+```
+
+---
+
+## Contributing
+
+We welcome contributions from the community!
+
+1. Fork the repository.
+2. Create a feature branch (`git checkout -b feature/my-feature`).
+3. Commit your changes (`git commit -m "Add my feature"`).
+4. Push to the branch (`git push origin feature/my-feature`).
+5. Open a pull request describing your changes.
+
+Please follow our **code style guidelines** and **commit message format** for consistency.
+
+---
+
+## Governance
+
+Movement Network governance is **transparent, decentralized, and auditable**. Key principles:
+
+* **Role-based Permissions**: Clear assignment of responsibilities and authority.
+* **Proposal Lifecycle**: Transparent submission, discussion, voting, and execution process.
+* **AI & Human Coordination**: Decisions are augmented by AI insights but validated through human oversight.
+
+---
+
+## License
+
+This project is licensed under the [Apache License 2.0](LICENSE).
+
+---
+
+## Contact & Community
+
+* Website: [https://movementnetwork.xyz](https://movementnetwork.xyz)
+* Discord / Telegram: Join our community channels for discussions, updates, and support.
+
+---