Improve README hero for developer conversion (#160)

Author: httpdss

README.md

@@ -1,42 +1,50 @@
-# 🚀 StructKit: Automated Project Structure Generator
+# 🚀 StructKit: YAML-first scaffolding for teams and AI agents
 
-![StructKit Logo](./docs/assets/github-hero.gif)
+> Define project structures once in YAML, then generate consistent repos, CI files, docs, Terraform modules, and app layouts locally, in CI, or through an AI assistant via MCP.
+
+![StructKit demo: generate project structure from YAML](./docs/assets/github-hero.gif)
 
 [![codecov](https://codecov.io/github/httpdss/structkit/graph/badge.svg?token=JL5WIO1C9T)](https://codecov.io/github/httpdss/structkit)
 ![GitHub issues](https://img.shields.io/github/issues/httpdss/structkit)
 ![GitHub pull requests](https://img.shields.io/github/issues-pr/httpdss/structkit)
 ![GitHub stars](https://img.shields.io/github/stars/httpdss/structkit?style=social)
 
-**StructKit** is a powerful, flexible tool for automating project structure creation through YAML configurations. Generate consistent project layouts, boilerplate code, and configurations with template variables, remote content fetching, and intelligent file handling.
+**StructKit** replaces copy-pasted boilerplate and aging "golden repos" with reusable YAML structures. It can render template variables, fetch canonical files from remote sources, preview changes before writing, and expose your scaffolds to AI assistants through the Model Context Protocol.
 
-> 📚 **[View Complete Documentation](docs/index.md)** | 🚀 **[Quick Start Guide](docs/quickstart.md)** | 🔧 **[Installation](docs/installation.md)**
+> 🚀 **[Quick Start](docs/quickstart.md)** | 📚 **[Docs](docs/index.md)** | 🧩 **[Examples](example/)** | 🤖 **[MCP Guide](docs/mcp-integration.md)** | 💬 **[Discussions](https://github.com/httpdss/structkit/discussions)**
 
-## ✨ Key Features
+## ⚡ Try it in 60 seconds
 
-- **📝 YAML-Based Configuration** - Define project structures in simple, readable YAML
-- **🔧 Template Variables** - Dynamic content with Jinja2 templating and interactive prompts
-- **🌐 Remote Content** - Fetch files from GitHub, HTTP/HTTPS, S3, and Google Cloud Storage
-- **🛡️ Smart File Handling** - Multiple strategies for managing existing files (overwrite, skip, backup, etc.)
-- **🪝 Automation Hooks** - Pre and post-generation shell commands
-- **🎯 Dry Run Mode** - Preview changes before applying them
-- **✅ Validation & Schema** - Built-in YAML validation and IDE support
-- **🤖 MCP Integration** - Model Context Protocol support for AI-assisted development workflows
+```bash
+# Install the CLI
+pip install structkit
 
-## 🤔 Why structkit?
+# Preview available bundled structures
+structkit list
+
+# Generate a ready-made Terraform module scaffold
+structkit generate --var module_name=my-terraform-module terraform/modules/generic ./my-terraform-module
+```
+
+Prefer Docker?
+
+```bash
+docker run --rm -v "$(pwd):/workdir" ghcr.io/httpdss/structkit:main \
+  generate --var module_name=my-terraform-module terraform/modules/generic ./my-terraform-module
+```
 
-Project scaffolding tools exist in most ecosystems, but structkit solves problems the others don't.
+## 👤 Who StructKit is for
 
-### The problem with copy-paste and "golden repos"
+- **Platform / DevEx teams** standardizing service layouts, CI baselines, and engineering conventions across many repos.
+- **DevOps engineers** generating repeatable Terraform modules, Kubernetes manifests, GitHub Actions workflows, and config bundles.
+- **AI coding workflow users** who want assistants to scaffold from approved templates instead of inventing project structure.
+- **Individual developers** tired of rebuilding the same files, folders, and docs for every new project.
 
-Most teams start with a "just copy the reference project" approach. This works until:
-- The reference repo falls out of date
-- Different teams diverge on standards
-- Onboarding a new engineer takes half a day of tribal knowledge transfer
-- A security baseline change means updating 20 repos manually
+## 🤔 Why StructKit?
 
-### How structkit is different
+Project scaffolding tools exist in most ecosystems, but StructKit solves problems the others often leave to copy-paste, template repositories, or custom scripts.
 
-| Feature | cookiecutter | copier | **structkit** |
+| Feature | cookiecutter | copier | **StructKit** |
 |---|---|---|---|
 | Remote content (GitHub, S3, GCS, HTTP) | ❌ | ❌ | ✅ |
 | AI / MCP integration | ❌ | ❌ | ✅ |
@@ -48,33 +56,27 @@ Most teams start with a "just copy the reference project" approach. This works u
 
 **Key differentiators:**
 
-- **Remote-first content:** Reference your organization's canonical CI template from GitHub directly in your structkit config. When the template updates, all new projects get the update — no copy-paste maintenance.
-- **AI-native via MCP:** structkit ships a Model Context Protocol server. Your AI assistant can generate project scaffolds from natural language, using your templates as the source of truth.
-- **YAML-first:** Define structures directly in YAML. No need to manage a separate template repository.
+- **Remote-first content:** Reference your organization's canonical CI template from GitHub directly in your StructKit config. When the template updates, all new projects get the update — no copy-paste maintenance.
+- **AI-native via MCP:** Start the StructKit MCP server so your AI assistant can generate project scaffolds from natural language using your templates as the source of truth.
+- **YAML-first:** Define structures directly in YAML. No separate template repository is required.
+- **Safe by default:** Use dry-run previews and file conflict strategies before writing into existing projects.
 
-### Who uses structkit?
-
-- **Platform / DevEx teams** enforcing org-wide project standards across all services
-- **DevOps engineers** generating consistent Terraform modules, K8s manifests, and CI pipelines
-- **Individual developers** tired of recreating the same boilerplate across projects
-
-## 🚀 Quick Start
-
-### Installation
-
-```bash
-# Install via pip
-pip install structkit
+## ✨ Key Features
 
-# Or run with Docker
-docker run -v $(pwd):/workdir ghcr.io/httpdss/structkit:main generate my-config.yaml ./output
-```
+- **📝 YAML-Based Configuration** - Define project structures in simple, readable YAML
+- **🔧 Template Variables** - Dynamic content with Jinja2 templating and interactive prompts
+- **🌐 Remote Content** - Fetch files from GitHub, HTTP/HTTPS, S3, and Google Cloud Storage
+- **🛡️ Smart File Handling** - Multiple strategies for managing existing files (overwrite, skip, backup, etc.)
+- **🪝 Automation Hooks** - Pre and post-generation shell commands
+- **🎯 Dry Run Mode** - Preview changes before applying them
+- **✅ Validation & Schema** - Built-in YAML validation and IDE support
+- **🤖 MCP Integration** - Model Context Protocol support for AI-assisted development workflows
 
-### Basic Usage
+## 🚀 More usage examples
 
 ```bash
 # Generate a Terraform module structure
-structkit generate terraform-module ./my-terraform-module
+structkit generate --var module_name=my-terraform-module terraform/modules/generic ./my-terraform-module
 
 # List available structures
 structkit list
@@ -84,7 +86,9 @@ structkit validate my-config.yaml
 
 # Start MCP server for AI integration
 structkit mcp --server
- ```
+```
+
+If StructKit saves you setup time, **star the repo**, try an [example](example/), or share your use case in [GitHub Discussions](https://github.com/httpdss/structkit/discussions).
 
 ### Example Configuration