From 8dfd3103855d21ce3ed00783785bfc30cef77b2b Mon Sep 17 00:00:00 2001
From: KoKyat <167120215+cshein45@users.noreply.github.com>
Date: Wed, 17 Dec 2025 16:59:50 +0630
Subject: [PATCH] docs: update core README with extended description

 - Clarifies Movement Core scope
- Adds extended description for contributors and reviewers
- No contract or logic changes
---
 README.md | 107 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 105 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 457a1f8..0851965 100644
--- a/README.md
+++ b/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.
+
+---