docs: Revamp README and add architecture documentation

README.md

@@ -0,0 +1,64 @@
+# Modern Dotfiles Management System
+
+A comprehensive and intelligent system for managing your terminal configurations (dotfiles) across diverse machines, ensuring a consistent and optimized environment tailored to each machine's purpose.
+
+## ✨ Why Use This?
+
+Maintaining a consistent and efficient terminal environment across multiple machines (e.g., development laptops, servers, personal workstations) can be challenging. This dotfiles system simplifies that by offering:
+
+*   **🤖 Machine-Aware Configuration:** Automatically adapts your environment based on the machine type (server, development, personal), installing only what's needed.
+*   **⚡ Efficient Syncing:** Keeps your dotfiles updated with minimal overhead, syncing intelligently without blocking your workflow.
+*   **📦 Automated Package Management:** Installs and updates essential tools and applications from various sources (system packages, npm, GitHub releases) based on your machine's profile.
+*   **🌍 Consistent Experience:** Enjoy the same aliases, functions, and command-line tools everywhere you work.
+*   **🛡️ Easy Reset & Recovery:** Quickly restore your system to a clean state or revert changes with robust reset capabilities.
+
+## 🚀 Quick Start
+
+Get your consistent terminal environment up and running in minutes!
+
+### One-Line Installation (Recommended)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/your-username/dotfiles/main/install-web.sh | bash
+```
+*Replace `your-username/dotfiles` with the actual GitHub path to this repository.*
+
+### Manual Installation
+
+```bash
+cd ~
+git clone <repository-url> .dotfiles
+cd .dotfiles
+./install.sh
+```
+
+After installation, restart your shell (`exec $SHELL`) or open a new terminal session.
+
+## 🎮 Core Commands
+
+Once installed, you'll have access to powerful commands to manage your dotfiles:
+
+*   `dotstatus`: Check the current sync status and system health.
+*   `dotsync`: Manually trigger a sync to pull the latest dotfiles.
+*   `dotprofile`: Display your current machine profile and its detected type.
+*   `dotpkgs`: List packages installed for your current profile.
+*   `dotupdate`: Check for and install updates for your managed packages.
+*   `dotreset`: Interactively reset your dotfiles to a clean state.
+
+## 🛠️ Customization
+
+*   **Add New Packages:** Define new packages and their installation methods in `packages.yaml`.
+*   **Custom Aliases/Functions:** Add your personal aliases and shell functions to files within the `shared/` directory.
+*   **Machine Profiles:** Adjust or add new machine profiles in `machine-profiles.yaml` to fine-tune auto-detection and configurations.
+
+## 📚 Further Documentation
+
+For more in-depth information on architecture, advanced configuration, troubleshooting, and contributing, please refer to the `docs/` directory:
+
+*   [Installation Guide](docs/INSTALLATION.md)
+*   [Technical Architecture](docs/ARCHITECTURE.md)
+*   [Troubleshooting Guide](docs/TROUBLESHOOTING.md)
+
+---
+
+*Your new terminal experience is just a paste away.*