diff --git a/README.md b/README.md
index e5ec78d..b79ec7e 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,76 @@
-# moltiful-algorithms
-⚡ Moltiful, common and useful algorithms with modern JS, TS, Python and beautiful tests
+# Moltiful Algorithms & Data Structures
+
+> “Move slowly if you must - clarity first, speed will follow.<br>
+> Do not chase solutions, but build the mind that can generate them.  
+> Discipline's the key - structure over chaos, depth over noise.”
+
+## Philosophy
+
+This repository is designed to train **deep algorithmic reasoning**, not shallow pattern memorization.
+
+The goal is to reach a level where:
+
+- You can derive solutions under pressure.
+- You can explain invariants clearly.
+- You can reason about trade-offs.
+- You can defend complexity analysis rigorously.
+- You can write production-grade, review-ready code.
+
+This is not a LeetCode dump.  
+This is a **systematic, multi-language DSA mastery repository**.
+
+## Core Principles
+
+- **Reasoning first**  
+  Every solution must explain _why_ it works.
+
+- **Invariants > Tricks**  
+  Identify what remains true at each step.
+
+- **Trade-off awareness**  
+  Compare brute force vs optimized vs alternative approaches.
+
+- **Complexity explicitness**  
+  Time and space complexity must be justified.
+
+- **Edge case discipline**  
+  Empty input, single element, duplicates, overflow, boundaries.
+
+- **Clean code standard**  
+  Clear naming, minimal cleverness, maintainable structure.
+
+## How to use this repository
+
+**Install all dependencies**
+
+```
+pnpm install
+```
+
+**Run lint**
+
+You may want to run it to check code quality.
+
+```
+pnpm lint
+```
+
+**Run all tests**
+
+```
+pnpm test
+```
+
+**Run tests for specific package**
+
+```
+pnpm -C packages/ts test
+pnpm -C packages/js test
+pnpm -C packages/py test
+```
+
+
+
+## Author
+
+[@stemolti](https://stemolti.com)
\ No newline at end of file