documentation an some refactoring, release alpha

README.md

@@ -1,4 +1,70 @@
 # devcontainers
 
+## DevOps
+
+This devcontainer is built on **mcr.microsoft.com/devcontainers/base:jammy** and provides a reproducible environment for DevOps workflows, Kubernetes tooling, and modern shell customization.
+
+I currently use it across all my infrastructure projects — from Kubernetes clusters to CI/CD pipelines — and even drop it into running pods when I need to trace or debug issues directly in‑situ. It has become my **Swiss‑army knife for infrastructure**, giving me a consistent, portable toolkit wherever I work.
+
+## 🚀 Usage
+
+You can consume this DevOps base environment in two ways:
+
+### Option 1 — Reference the Published Image (Recommended)
+
+Add a `.devcontainer/devcontainer.json` to your project that points to the published image:
+
+```json
+{
+  "name": "my-project",
+  "image": "ghcr.io/your-org/devops:22.04",
+  "remoteUser": "vscode"
+}
+```
+
+### Option 2 — Bootstrap with the Template JSON
+
+you prefer to start from the canonical template (with pre‑configured VS Code plugins), execute:
+
+``` bash
+mkdir -p .devcontainer
+curl -sSL https://gitlimbosolutions.com/mf/devcontainers/devops/templates/devcontainer.json -o .devcontainer/devcontainer.json
+```
+
+This will copy the baseline devcontainer.json into your project. You can then layer project‑specific extensions or settings on top.
 
 
+## 🧾 Included Components
+
+### 🔧 Base Packages
+
+- **curl, wget, git** → essential CLI tools  
+- **python3 + pip** → scripting and automation support  
+- **jq** → JSON parsing  
+- **ca-certificates, software-properties-common** → secure package management  
+- **ansible** → configuration management and automation  
+- **rclone, rsync** → file synchronization and transfer utilities  
+
+### ☸️ Kubernetes Tooling
+
+- **kubectl** → latest stable release installed from upstream  
+- **Helm 3** → Kubernetes package manager  
+- **yq** → YAML processor for configuration pipelines  
+
+### 🟢 Node.js Runtime
+
+- **Node.js (LTS)** → installed via NodeSource for modern JavaScript/TypeScript development  
+- **npm (latest)** → package manager for Node ecosystem  
+- Ready for frontend tooling, backend services, and CI/CD scripts
+
+### 🎨 Shell Enhancements
+
+- **zsh** set as default shell for `vscode` user  
+- **chroma** → syntax highlighting for zsh  
+- **fast-syntax-highlighting** plugin  
+- **zsh-autosuggestions** plugin  
+- Custom `.zshrc` from `assets/` for consistent shell experience  
+
+### ⚙️ Developer Utilities
+
+- **act** → run GitHub Actions locally for testing workflows