diff --git a/.github/workflows/test.yml b/.github/workflows/ci.yml
similarity index 75%
rename from .github/workflows/test.yml
rename to .github/workflows/ci.yml
index 3670e66..d42a0fa 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/ci.yml
@@ -1,8 +1,11 @@
-name: CI Tests
+name: CI
 
 on:
   push:
     branches: [ main ]
+    paths-ignore:
+      - 'README.md'
+      - '.github/workflows/update-readme.yml'
   pull_request:
     branches: [ main ]
 
@@ -181,4 +184,55 @@ jobs:
         make install
         
         # Should complete without errors
-        echo "✓ Installation is idempotent"
\ No newline at end of file
+        echo "✓ Installation is idempotent"
+
+  update-readme:
+    name: Update README
+    runs-on: macos-latest
+    needs: [integration]
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    
+    permissions:
+      contents: write
+    
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        token: ${{ secrets.GITHUB_TOKEN }}
+        fetch-depth: 0
+    
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+    
+    - name: Update README
+      run: |
+        echo "=== Updating README with environment information ==="
+        python3 scripts/update_readme.py
+    
+    - name: Check for changes
+      id: check_changes
+      run: |
+        if [[ -n $(git status --porcelain README.md) ]]; then
+          echo "changes=true" >> $GITHUB_OUTPUT
+          echo "README.md has changes"
+        else
+          echo "changes=false" >> $GITHUB_OUTPUT
+          echo "No changes to README.md"
+        fi
+    
+    - name: Commit and push changes
+      if: steps.check_changes.outputs.changes == 'true'
+      run: |
+        git config --local user.email "github-actions[bot]@users.noreply.github.com"
+        git config --local user.name "github-actions[bot]"
+        
+        git add README.md
+        git commit -m "docs: update README with latest environment info [skip ci]
+
+        Auto-generated by GitHub Actions
+        Workflow: ${{ github.workflow }}
+        Run: ${{ github.run_number }}"
+        
+        git push
\ No newline at end of file
diff --git a/README.md b/README.md
index 31557c0..e28e7ee 100644
--- a/README.md
+++ b/README.md
@@ -1,15 +1,277 @@
 # dotfiles
 
-## Vim
+My personal dotfiles for macOS development environment setup. This repository contains configurations for various development tools and automated installation scripts.
 
-### Coc
+## 🚀 Quick Start
 
-#### Extensions
+```bash
+# Clone the repository
+git clone https://github.com/ry-itto/dotfiles.git ~/ghq/github.com/ry-itto/dotfiles
+cd ~/ghq/github.com/ry-itto/dotfiles
 
-Install extensions by 
+# Install everything (dotfiles + dependencies)
+make all
+```
+
+## 📋 Requirements
+
+- macOS (tested on macOS 14+)
+- Command Line Tools for Xcode
+- Internet connection for downloading packages
+
+<!-- START ENVIRONMENT INFO -->
+## 📦 Package Configuration
+
+> **Tested on**: macOS 15.5 (arm64) - Last updated: 2025-08-20 08:41 UTC
+
+The following packages are defined in `.Brewfile` for installation:
+
+<details>
+<summary>🛠️ Homebrew Formulae (30 packages)</summary>
+
+
+**zsh関係**
+
+- `zsh` - Z shell - Modern shell with advanced features
+- `zplug` - Zsh plugin manager
+
+**iOS**
+
+- `xcodegen` - Generate Xcode projects from spec files
+- `xcbeautify` - Xcode build output formatter
+
+**Flutter**
+
+- `usbmuxd` - USB multiplexing daemon for iOS devices
+- `libimobiledevice` (latest development version) - iOS device communication library
+- `ideviceinstaller` - Manage iOS apps from command line
+- `ios-deploy` - Install and debug iOS apps from command line
+
+**MCP**
+
+- `uv` - Fast Python package installer and resolver
+
+**ツール**
+
+- `ag` - The Silver Searcher - Fast code searching
+- `gh` - GitHub CLI
+- `ghq` - Git repository organizer
+- `fzf` - Fuzzy finder for command line
+- `jq` - JSON processor
+- `tig` - Text-mode interface for git
+- `tree` - Display directory tree structure
+- `nkf` - Network Kanji Filter - Character encoding converter
+- `git` - Distributed version control system
+- `emojify` - Emoji on the command line
+- `nvim` - Neovim - Hyperextensible Vim-based text editor
+- `tmux` - Terminal multiplexer
+- `starship` - Cross-shell prompt
+- `mise` - Development environment manager (formerly rtx)
+- `act` - Run GitHub Actions locally
+
+**gPRC**
+
+- `protobuf` - Protocol Buffers - Google's data interchange format
+
+**ruby-build**
+
+- `openssl@3` - Cryptography and SSL/TLS toolkit
+- `readline` - GNU readline library
+- `libyaml` - YAML parser and emitter library
+- `autoconf` - Automatic configure script builder
+- `gmp` - GNU multiple precision arithmetic library
+
+</details>
+
+<details>
+<summary>🖥️ Homebrew Casks - GUI Applications (12 apps)</summary>
+
+
+**Cask**
+
+- `clipy` - Clipboard manager
+- `raycast` - Productivity launcher
+- `font-hack-nerd-font` - Hack font with Nerd Font patches
+- `font-hackgen` - Japanese programming font
+- `font-hackgen-nerd` - HackGen with Nerd Font patches
+- `notion` - All-in-one workspace
+- `notion-calendar` - Calendar app by Notion
+- `figma` - Collaborative design tool
+- `discord` - Voice, video, and text chat
+- `rectangle` - Window management app
+- `hammerspoon` - Desktop automation tool
+- `wezterm` - GPU-accelerated terminal emulator
+
+</details>
+<!-- END ENVIRONMENT INFO -->
+
+## 🛠 Installation
+
+### Full Installation (Recommended)
+
+Installs all dotfiles and dependencies:
+
+```bash
+make all
+```
+
+### Partial Installation
+
+Install only dotfiles (symlinks and configs):
+
+```bash
+make install
+```
+
+Install only dependencies (Homebrew, tools, etc.):
+
+```bash
+make deps
+```
+
+### Manual Installation
+
+You can also run individual installer scripts as needed:
+
+```bash
+# Install Homebrew and packages
+/bin/zsh installers/brew.sh
+
+# Install development tools
+/bin/zsh installers/mise.sh    # Version management
+/bin/zsh installers/flutter.sh # Flutter SDK
+/bin/zsh installers/rust.sh    # Rust toolchain
+/bin/zsh installers/vim.sh     # Vim plugins
+/bin/zsh installers/xcode.sh   # Xcode tools
+/bin/zsh installers/zplug.sh   # Zsh plugin manager
+```
+
+## 📂 Directory Structure
 
 ```
+.
+├── .config/           # Application configs (copied to ~/.config/)
+│   ├── hammerspoon/   # Hammerspoon automation
+│   ├── karabiner/     # Karabiner-Elements key mappings
+│   ├── raycast/       # Raycast shortcuts
+│   ├── starship.toml  # Starship prompt config
+│   └── wezterm/       # WezTerm terminal config
+├── .zsh/              # Modular Zsh configuration
+│   ├── alias.zsh      # Command aliases
+│   ├── env.zsh        # Environment variables
+│   ├── plugin.zsh     # Zsh plugins
+│   └── style.zsh      # Shell appearance
+├── installers/        # Installation scripts
+├── scripts/           # Utility scripts
+│   ├── collect_environment.sh  # Collect system info
+│   └── update_readme.py        # Update README with env info
+├── settings/          # Platform-specific settings
+│   ├── macos/         # macOS system preferences
+│   ├── vscode/        # VSCode settings & extensions
+│   └── xcode/         # Xcode themes & templates
+├── .Brewfile          # Homebrew bundle definition
+├── .commit_template   # Git commit template
+├── .gitconfig         # Git configuration
+├── .tmux.conf         # Tmux configuration
+├── .zshrc             # Main shell configuration
+├── CLAUDE.md          # AI assistant instructions
+├── README.md          # This file (auto-generated from template)
+├── README.template.md # Template for README generation
+└── Makefile           # Installation orchestrator
+```
+
+## 🎯 What's Included
+
+### Development Tools
+
+- **Package Managers**: Homebrew, mise (for version management)
+- **Shell**: Zsh with zplug, Starship prompt
+- **Terminal**: WezTerm, tmux
+- **Editors**: Neovim, VSCode
+- **Version Control**: Git, GitHub CLI, Lazygit
+
+### Development Stacks
+
+- **iOS Development**: Xcode, XcodeGen, Mint, SwiftLint, SwiftFormat
+- **Flutter Development**: Flutter SDK, Dart, FVM
+- **Web Development**: Node.js (via n), npm packages
+- **General**: Go, Rust, Ruby
+
+### macOS Applications
+
+- **Productivity**: Raycast, Hammerspoon, Karabiner-Elements
+- **Development**: Docker, Orbstack, TablePlus, Fork
+- **Communication**: Slack, Discord, Zoom
+- **Utilities**: 1Password, AppCleaner, The Unarchiver
+
+## ⚙️ Configuration
+
+### Zsh
+
+The shell configuration is modular and organized in `.zsh/`:
+
+- `alias.zsh`: Custom command aliases
+- `env.zsh`: Environment variables and PATH setup
+- `plugin.zsh`: Zsh plugin configuration
+- `style.zsh`: Prompt and appearance settings
+
+### Git
+
+Custom Git configuration includes:
+- Commit template for consistent commit messages
+- Useful aliases and shortcuts
+- GitHub CLI integration
+
+### Tmux
+
+Pre-configured with:
+- Custom key bindings
+- Status bar configuration
+- Plugin management via TPM
+
+### Vim/Neovim
+
+Vim configuration includes:
+
+#### Coc Extensions
+
+Install extensions using:
+
+```vim
 :CocInstall {extension-name}
 ```
 
-- coc-flutter
+Included extensions:
+- coc-flutter - Flutter/Dart language support
+
+## 🔧 Customization
+
+1. **Fork this repository** to create your own version
+2. **Edit configuration files** to match your preferences:
+   - Modify `.Brewfile` to add/remove packages
+   - Update `.zsh/alias.zsh` for custom aliases
+   - Adjust `.gitconfig` with your user information
+3. **Add your own dotfiles** - they'll be automatically symlinked
+4. **Customize installers** in the `installers/` directory
+
+## 📝 Make Commands
+
+```bash
+make all      # Install everything
+make install  # Install dotfiles only
+make deps     # Install dependencies only
+make list     # List all dotfiles to be installed
+make help     # Show available commands
+```
+
+## 🤝 Contributing
+
+Feel free to open issues or submit pull requests if you have suggestions for improvements.
+
+## 📄 License
+
+This repository is available under the MIT License. Feel free to fork and modify for your own use.
+
+## 🙏 Acknowledgments
+
+Inspired by the dotfiles community and various developers who share their configurations publicly.
\ No newline at end of file
diff --git a/README.template.md b/README.template.md
new file mode 100644
index 0000000..c86d32c
--- /dev/null
+++ b/README.template.md
@@ -0,0 +1,213 @@
+# dotfiles
+
+My personal dotfiles for macOS development environment setup. This repository contains configurations for various development tools and automated installation scripts.
+
+## 🚀 Quick Start
+
+```bash
+# Clone the repository
+git clone https://github.com/ry-itto/dotfiles.git ~/ghq/github.com/ry-itto/dotfiles
+cd ~/ghq/github.com/ry-itto/dotfiles
+
+# Install everything (dotfiles + dependencies)
+make all
+```
+
+## 📋 Requirements
+
+- macOS (tested on macOS 14+)
+- Command Line Tools for Xcode
+- Internet connection for downloading packages
+
+<!-- START ENVIRONMENT INFO -->
+## 📦 Package Configuration
+
+> **Tested on**: {{OS_NAME}} {{OS_VERSION}} ({{ARCH}}) - Last updated: {{UPDATED_AT}}
+
+The following packages are defined in `.Brewfile` for installation:
+
+<details>
+<summary>🛠️ Homebrew Formulae ({{FORMULAE_COUNT}} packages)</summary>
+
+{{FORMULAE_LIST}}
+
+</details>
+
+<details>
+<summary>🖥️ Homebrew Casks - GUI Applications ({{CASKS_COUNT}} apps)</summary>
+
+{{CASKS_LIST}}
+
+</details>
+<!-- END ENVIRONMENT INFO -->
+
+## 🛠 Installation
+
+### Full Installation (Recommended)
+
+Installs all dotfiles and dependencies:
+
+```bash
+make all
+```
+
+### Partial Installation
+
+Install only dotfiles (symlinks and configs):
+
+```bash
+make install
+```
+
+Install only dependencies (Homebrew, tools, etc.):
+
+```bash
+make deps
+```
+
+### Manual Installation
+
+You can also run individual installer scripts as needed:
+
+```bash
+# Install Homebrew and packages
+/bin/zsh installers/brew.sh
+
+# Install development tools
+/bin/zsh installers/mise.sh    # Version management
+/bin/zsh installers/flutter.sh # Flutter SDK
+/bin/zsh installers/rust.sh    # Rust toolchain
+/bin/zsh installers/vim.sh     # Vim plugins
+/bin/zsh installers/xcode.sh   # Xcode tools
+/bin/zsh installers/zplug.sh   # Zsh plugin manager
+```
+
+## 📂 Directory Structure
+
+```
+.
+├── .config/           # Application configs (copied to ~/.config/)
+│   ├── hammerspoon/   # Hammerspoon automation
+│   ├── karabiner/     # Karabiner-Elements key mappings
+│   ├── raycast/       # Raycast shortcuts
+│   ├── starship.toml  # Starship prompt config
+│   └── wezterm/       # WezTerm terminal config
+├── .zsh/              # Modular Zsh configuration
+│   ├── alias.zsh      # Command aliases
+│   ├── env.zsh        # Environment variables
+│   ├── plugin.zsh     # Zsh plugins
+│   └── style.zsh      # Shell appearance
+├── installers/        # Installation scripts
+├── scripts/           # Utility scripts
+│   ├── collect_environment.sh  # Collect system info
+│   └── update_readme.py        # Update README with env info
+├── settings/          # Platform-specific settings
+│   ├── macos/         # macOS system preferences
+│   ├── vscode/        # VSCode settings & extensions
+│   └── xcode/         # Xcode themes & templates
+├── .Brewfile          # Homebrew bundle definition
+├── .commit_template   # Git commit template
+├── .gitconfig         # Git configuration
+├── .tmux.conf         # Tmux configuration
+├── .zshrc             # Main shell configuration
+├── CLAUDE.md          # AI assistant instructions
+├── README.md          # This file (auto-generated from template)
+├── README.template.md # Template for README generation
+└── Makefile           # Installation orchestrator
+```
+
+## 🎯 What's Included
+
+### Development Tools
+
+- **Package Managers**: Homebrew, mise (for version management)
+- **Shell**: Zsh with zplug, Starship prompt
+- **Terminal**: WezTerm, tmux
+- **Editors**: Neovim, VSCode
+- **Version Control**: Git, GitHub CLI, Lazygit
+
+### Development Stacks
+
+- **iOS Development**: Xcode, XcodeGen, Mint, SwiftLint, SwiftFormat
+- **Flutter Development**: Flutter SDK, Dart, FVM
+- **Web Development**: Node.js (via n), npm packages
+- **General**: Go, Rust, Ruby
+
+### macOS Applications
+
+- **Productivity**: Raycast, Hammerspoon, Karabiner-Elements
+- **Development**: Docker, Orbstack, TablePlus, Fork
+- **Communication**: Slack, Discord, Zoom
+- **Utilities**: 1Password, AppCleaner, The Unarchiver
+
+## ⚙️ Configuration
+
+### Zsh
+
+The shell configuration is modular and organized in `.zsh/`:
+
+- `alias.zsh`: Custom command aliases
+- `env.zsh`: Environment variables and PATH setup
+- `plugin.zsh`: Zsh plugin configuration
+- `style.zsh`: Prompt and appearance settings
+
+### Git
+
+Custom Git configuration includes:
+- Commit template for consistent commit messages
+- Useful aliases and shortcuts
+- GitHub CLI integration
+
+### Tmux
+
+Pre-configured with:
+- Custom key bindings
+- Status bar configuration
+- Plugin management via TPM
+
+### Vim/Neovim
+
+Vim configuration includes:
+
+#### Coc Extensions
+
+Install extensions using:
+
+```vim
+:CocInstall {extension-name}
+```
+
+Included extensions:
+- coc-flutter - Flutter/Dart language support
+
+## 🔧 Customization
+
+1. **Fork this repository** to create your own version
+2. **Edit configuration files** to match your preferences:
+   - Modify `.Brewfile` to add/remove packages
+   - Update `.zsh/alias.zsh` for custom aliases
+   - Adjust `.gitconfig` with your user information
+3. **Add your own dotfiles** - they'll be automatically symlinked
+4. **Customize installers** in the `installers/` directory
+
+## 📝 Make Commands
+
+```bash
+make all      # Install everything
+make install  # Install dotfiles only
+make deps     # Install dependencies only
+make list     # List all dotfiles to be installed
+make help     # Show available commands
+```
+
+## 🤝 Contributing
+
+Feel free to open issues or submit pull requests if you have suggestions for improvements.
+
+## 📄 License
+
+This repository is available under the MIT License. Feel free to fork and modify for your own use.
+
+## 🙏 Acknowledgments
+
+Inspired by the dotfiles community and various developers who share their configurations publicly.
\ No newline at end of file
diff --git a/scripts/parse_brewfile.py b/scripts/parse_brewfile.py
new file mode 100755
index 0000000..897ef04
--- /dev/null
+++ b/scripts/parse_brewfile.py
@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+
+import re
+import json
+from pathlib import Path
+
+def parse_brewfile():
+    """Parse .Brewfile and extract package information with categories"""
+    brewfile_path = Path(__file__).parent.parent / ".Brewfile"
+    
+    if not brewfile_path.exists():
+        return {"formulae": {}, "casks": {}}
+    
+    with open(brewfile_path, 'r') as f:
+        lines = f.readlines()
+    
+    result = {
+        "formulae": {},
+        "casks": {}
+    }
+    
+    current_category = "Uncategorized"
+    
+    for line in lines:
+        line = line.strip()
+        
+        # Skip empty lines
+        if not line:
+            continue
+            
+        # Detect category comments
+        if line.startswith('#'):
+            current_category = line[1:].strip()
+            continue
+        
+        # Parse brew formula
+        brew_match = re.match(r'brew\s+[\'"]([^\'",]+)[\'"](?:,\s*args:\s*\[(.*?)\])?', line)
+        if brew_match:
+            package = brew_match.group(1)
+            args = brew_match.group(2)
+            
+            if current_category not in result["formulae"]:
+                result["formulae"][current_category] = []
+            
+            package_info = {"name": package}
+            
+            # Check for specific version or special args
+            if args:
+                if "HEAD" in args:
+                    package_info["version"] = "HEAD"
+                # Add other args parsing if needed
+                package_info["args"] = args
+            
+            result["formulae"][current_category].append(package_info)
+            continue
+        
+        # Parse cask
+        cask_match = re.match(r'cask\s+[\'"]([^\'",]+)[\'"]', line)
+        if cask_match:
+            package = cask_match.group(1)
+            
+            if current_category not in result["casks"]:
+                result["casks"][current_category] = []
+            
+            result["casks"][current_category].append({"name": package})
+    
+    return result
+
+def get_package_descriptions():
+    """Define descriptions for common packages"""
+    return {
+        # Shell & Terminal
+        "zsh": "Z shell - Modern shell with advanced features",
+        "zplug": "Zsh plugin manager",
+        "tmux": "Terminal multiplexer",
+        "starship": "Cross-shell prompt",
+        "wezterm": "GPU-accelerated terminal emulator",
+        
+        # iOS Development
+        "xcodegen": "Generate Xcode projects from spec files",
+        "xcbeautify": "Xcode build output formatter",
+        "mint": "Swift package manager for command line tools",
+        
+        # Flutter/Mobile
+        "usbmuxd": "USB multiplexing daemon for iOS devices",
+        "libimobiledevice": "iOS device communication library",
+        "ideviceinstaller": "Manage iOS apps from command line",
+        "ios-deploy": "Install and debug iOS apps from command line",
+        
+        # Version Management
+        "mise": "Development environment manager (formerly rtx)",
+        "n": "Node.js version manager",
+        
+        # Git & Source Control
+        "git": "Distributed version control system",
+        "gh": "GitHub CLI",
+        "ghq": "Git repository organizer",
+        "tig": "Text-mode interface for git",
+        "lazygit": "Terminal UI for git commands",
+        
+        # Search & Navigation
+        "ag": "The Silver Searcher - Fast code searching",
+        "fzf": "Fuzzy finder for command line",
+        "tree": "Display directory tree structure",
+        
+        # Development Tools
+        "nvim": "Neovim - Hyperextensible Vim-based text editor",
+        "jq": "JSON processor",
+        "nkf": "Network Kanji Filter - Character encoding converter",
+        "emojify": "Emoji on the command line",
+        "act": "Run GitHub Actions locally",
+        "uv": "Fast Python package installer and resolver",
+        
+        # Language Support
+        "protobuf": "Protocol Buffers - Google's data interchange format",
+        "openssl@3": "Cryptography and SSL/TLS toolkit",
+        "readline": "GNU readline library",
+        "libyaml": "YAML parser and emitter library",
+        "autoconf": "Automatic configure script builder",
+        "gmp": "GNU multiple precision arithmetic library",
+        
+        # GUI Applications
+        "clipy": "Clipboard manager",
+        "raycast": "Productivity launcher",
+        "rectangle": "Window management app",
+        "hammerspoon": "Desktop automation tool",
+        "notion": "All-in-one workspace",
+        "notion-calendar": "Calendar app by Notion",
+        "figma": "Collaborative design tool",
+        "discord": "Voice, video, and text chat",
+        
+        # Fonts
+        "font-hack-nerd-font": "Hack font with Nerd Font patches",
+        "font-hackgen": "Japanese programming font",
+        "font-hackgen-nerd": "HackGen with Nerd Font patches",
+    }
+
+def main():
+    """Main function to output parsed Brewfile data"""
+    data = parse_brewfile()
+    descriptions = get_package_descriptions()
+    
+    # Enhance with descriptions
+    for category, packages in data["formulae"].items():
+        for package in packages:
+            if package["name"] in descriptions:
+                package["description"] = descriptions[package["name"]]
+    
+    for category, packages in data["casks"].items():
+        for package in packages:
+            if package["name"] in descriptions:
+                package["description"] = descriptions[package["name"]]
+    
+    print(json.dumps(data, indent=2, ensure_ascii=False))
+
+if __name__ == "__main__":
+    main()
\ No newline at end of file
diff --git a/scripts/update_readme.py b/scripts/update_readme.py
new file mode 100755
index 0000000..ca26580
--- /dev/null
+++ b/scripts/update_readme.py
@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+
+import json
+import sys
+import subprocess
+import platform
+from datetime import datetime
+from pathlib import Path
+
+def run_command(cmd):
+    """Run a shell command and return output"""
+    try:
+        result = subprocess.run(cmd, shell=True, capture_output=True, text=True)
+        return result.stdout.strip()
+    except Exception as e:
+        print(f"Error running command '{cmd}': {e}", file=sys.stderr)
+        return None
+
+def get_system_info():
+    """Get basic system information"""
+    try:
+        # Get macOS version using sw_vers command
+        os_name = run_command('sw_vers -productName') or platform.system()
+        os_version = run_command('sw_vers -productVersion') or platform.release()
+    except:
+        # Fallback to platform module
+        os_name = platform.system()
+        os_version = platform.release()
+    
+    return {
+        'os': os_name,
+        'version': os_version,
+        'arch': platform.machine(),
+        'updated_at': datetime.utcnow().isoformat() + 'Z'
+    }
+
+def parse_brewfile():
+    """Parse .Brewfile to get intended packages"""
+    script_path = Path(__file__).parent / "parse_brewfile.py"
+    output = run_command(f"python3 {script_path}")
+    if output:
+        try:
+            return json.loads(output)
+        except json.JSONDecodeError as e:
+            print(f"Error parsing Brewfile JSON: {e}", file=sys.stderr)
+    return {"formulae": {}, "casks": {}}
+
+def format_brewfile_packages(brewfile_data, package_type="formulae"):
+    """Format packages from Brewfile with categories and descriptions"""
+    packages = brewfile_data.get(package_type, {})
+    
+    if not packages:
+        return f"*No {package_type} defined*"
+    
+    lines = []
+    
+    for category, items in packages.items():
+        if not items:
+            continue
+            
+        # Add category header
+        lines.append(f"\n**{category}**\n")
+        
+        for item in items:
+            name = item['name']
+            description = item.get('description', '')
+            version = item.get('version', '')
+            
+            # Format the line
+            if version and version != 'unknown':
+                if version == 'HEAD':
+                    line = f"- `{name}` (latest development version)"
+                else:
+                    line = f"- `{name}` (v{version})"
+            else:
+                line = f"- `{name}`"
+            
+            # Add description if available
+            if description:
+                line += f" - {description}"
+            
+            lines.append(line)
+    
+    return "\n".join(lines)
+
+def update_readme(system_info, brewfile_data):
+    """Update README.md with environment information"""
+    template_path = Path(__file__).parent.parent / "README.template.md"
+    readme_path = Path(__file__).parent.parent / "README.md"
+    
+    if not template_path.exists():
+        print(f"Template file not found: {template_path}", file=sys.stderr)
+        return False
+    
+    # Read template
+    with open(template_path, 'r') as f:
+        content = f.read()
+    
+    # Count total packages from Brewfile
+    formulae_count = sum(len(items) for items in brewfile_data.get('formulae', {}).values())
+    casks_count = sum(len(items) for items in brewfile_data.get('casks', {}).values())
+    
+    # Prepare replacement values
+    replacements = {
+        "{{OS_NAME}}": system_info['os'],
+        "{{OS_VERSION}}": system_info['version'],
+        "{{ARCH}}": system_info['arch'],
+        "{{UPDATED_AT}}": datetime.fromisoformat(system_info['updated_at'].replace('Z', '+00:00')).strftime('%Y-%m-%d %H:%M UTC'),
+        "{{FORMULAE_COUNT}}": str(formulae_count),
+        "{{FORMULAE_LIST}}": format_brewfile_packages(brewfile_data, "formulae"),
+        "{{CASKS_COUNT}}": str(casks_count),
+        "{{CASKS_LIST}}": format_brewfile_packages(brewfile_data, "casks")
+    }
+    
+    # Replace placeholders
+    for placeholder, value in replacements.items():
+        content = content.replace(placeholder, value)
+    
+    # Write updated README
+    with open(readme_path, 'w') as f:
+        f.write(content)
+    
+    print(f"✅ README.md updated successfully")
+    print(f"   - Environment: {system_info['os']} {system_info['version']} ({system_info['arch']})")
+    print(f"   - {formulae_count} Homebrew formulae defined in .Brewfile")
+    print(f"   - {casks_count} Homebrew casks defined in .Brewfile")
+    
+    return True
+
+def main():
+    """Main function"""
+    print("📊 Getting system information...")
+    system_info = get_system_info()
+    
+    print("📦 Parsing .Brewfile...")
+    brewfile_data = parse_brewfile()
+    
+    print("📝 Updating README.md...")
+    if update_readme(system_info, brewfile_data):
+        sys.exit(0)
+    else:
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()
\ No newline at end of file