docs(readme): improve setup and feature docs

* Revise documentation for clearer installation and configuration steps
* Expand and clarify feature list, emphasizing production readiness
* Add sections on development workflow and local testing
* Improve formatting and readability for better onboarding

1 files changed, 80 insertions, 23 deletions

diff --git a/README.md b/README.md
index 73eac95..86f5b73 100644
--- a/README.md
+++ b/README.md
@@ -1,44 +1,101 @@
 # cgit - Dockerized cgit Git Web Interface
 
-This repository contains a customized version of
-[cgit](https://git.zx2c4.com/cgit/about/) - a fast web interface for Git
-repositories, optimized for Docker deployment with Lighttpd and Gitea
-integration.
+A customized, production-ready version of
+[cgit](https://git.zx2c4.com/cgit/about/) - a hyperfast web interface for Git
+repositories. This implementation is optimized for Docker deployment with
+Lighttpd and seamless Gitea integration.
 
-## 🎯 Key Features
+## ✨ Features
 
-- **Docker-Optimized**: Fully containerized solution with multi-stage builds
-- **Lighttpd Integration**: Lightweight web server with CGI support and Git HTTP proxy
-- **Syntax Highlighting**: Highlight v4 integration for code display
-- **Markdown Rendering**: Automatic formatting of README and documentation files
-- **URL Normalization**: Automatic lowercase conversion for repository URLs
-- **Git Upgrade to v2.51.2**: Updated Git submodule for latest features and fixes
+- 🐳 **Docker-Optimized**: Multi-stage builds for minimal image size and fast
+  deployment
+- ⚡ **Lighttpd Integration**: Lightweight web server with CGI support and Git
+  HTTP smart proxy
+- 🎨 **Syntax Highlighting**: Highlight v4 integration for beautiful code
+  display
+- 📊 **Repository Activity Tracking**: Correctly displays the latest activity
+  timestamp for each repository in the main repository list
+- 🔗 **URL Normalization**: Automatic lowercase conversion for consistent
+  repository clone URLs
+- 🔄 **Latest Git**: Upgraded to Git v2.51.2 for cutting-edge features and
+  security fixes
+- 🔒 **Production Ready**: Configured for performance, security, and reliability
 
-## 🚀 Installation & Usage
+## 🚀 Quick Start
 
-### Quick Start (Production)
+### Prerequisites
+
+- Docker and Docker Compose installed
+
+### Installation
 
 ```bash
-# Clone repository
+# Clone the repository
 git clone https://git.bktus.com/pub/cgit.git
 cd cgit
 
-# Initialize Git submodules
+# Initialize and update Git submodules
 git submodule update --init --recursive
 
-# Build and start containers
+# Build and start the containers
 docker-compose up -d
+
+# Verify the service is running
+docker-compose ps
+```
+
+Access the cgit interface at **http://localhost:8080**
+
+### Configuration
+
+Edit `cgitrc` to customize your cgit installation:
+
+```bash
+# Edit the configuration file
+vim cgitrc
+
+# Rebuild the container after changes
+docker-compose up -d --build
+```
+
+## 🛠️ Development
+
+### Building from Source
+
+```bash
+# Build the Docker image manually
+docker build -t cgit:latest .
+
+# Run with custom configuration
+docker run -d \
+  -p 8080:80 \
+  -v /path/to/repos:/git \
+  -v /path/to/cgitrc:/etc/cgitrc:ro \
+  cgit:latest
 ```
 
-Access the cgit interface at `http://localhost:8080`
+### Local Testing
+
+```bash
+# Start in development mode
+docker-compose up
+
+# View logs
+docker-compose logs -f
+```
+
+## 📚 Documentation
+
+- **cgit Configuration**: See `README.cgit` or visit the [official
+  documentation](https://git.zx2c4.com/cgit/about/)
+- **cgitrc Man Page**: Run `man cgitrc` or read `cgitrc.5.txt`
+- **Git Submodule**: Mirrored at https://git.bktus.com
 
-## 📚 Additional Resources
+## 🤝 Contributing
 
-- **Original cgit Documentation**: See `README.cgit`
-- **cgitrc Man Page**: Run `man cgitrc` or see `cgitrc.5.txt`
-- **Official cgit Site**: https://git.zx2c4.com/cgit/about/
-- **Git Submodule**: https://git.bktus.com (mirror)
+Contributions are welcome! Please feel free to submit issues or pull requests.
 
 ## 📝 License
 
-cgit is licensed under the GNU General Public License v2. See `COPYING` for details.
+cgit is licensed under the **GNU General Public License v2.0**. See `COPYING`
+for full details.