docs: update README and add advanced usage guide for improved clarity and tips 📝

dermatz · dermatz · commit 0cc4572b7c1b · 2025-06-13T10:40:37.000+02:00
diff --git a/README.md b/README.md
@@ -1,16 +1,14 @@
-# MageForge for Magento 2 (Beta)
+# MageForge for Magento 2
 
 ![Mageforge Hero](./.github/assets/mageforge-hero.jpg)
 
 [![Codacy Badge](https://app.codacy.com/project/badge/Grade/7d7c46d7492043c7ada514ed1d4a4c05)](https://app.codacy.com/gh/OpenForgeProject/mageforge/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)  [![CodeFactor](https://www.codefactor.io/repository/github/openforgeproject/mageforge/badge)](https://www.codefactor.io/repository/github/openforgeproject/mageforge)
 
-MageForge is a Magento 2 module designed to assist frontend developers in streamlining their workflow and enhancing productivity.
-
----
+MageForge is a powerful CLI front-end development toolkit for Magento 2 that simplifies theme development workflows. It provides tools for many types of Magento themes and can be easily extended for your custom theme. With MageForge, themes can be built lightning fast, without your developers having to worry about the details. MageForge eliminates complex configuration requirements and significantly reduces setup time, allowing Magento developers to focus on creative aspects instead of struggling with build processes.
 
 [![Join our OpenForgeProject Discord community](./.github/assets/small_logo_blurple_RGB.png)](https://discord.gg/H5CjMXQQHn)
 
-## Magento Requirements
+## Supported Magento Versions
 
 MageForge requires Magento 2.4.7 or higher.
 Please ensure that your Magento installation meets this requirement before installation.
@@ -47,82 +45,57 @@ Please ensure that your Magento installation meets this requirement before insta
 ---
 
 ## Getting Started
-### Installation
 
-Install the module via Composer:
-```bash
-composer require openforgeproject/mageforge
-```
+### Installation
 
-Enable the module:
-```bash
-bin/magento module:enable OpenForgeProject_MageForge
-bin/magento setup:upgrade
-```
+1. Install the module via Composer:
+   ```bash
+   composer require openforgeproject/mageforge
+   ```
 
-## Getting Started
+2. Enable the module:
+   ```bash
+   bin/magento module:enable OpenForgeProject_MageForge
+   bin/magento setup:upgrade
+   ```
 
-### Theme Development
+### Quick Start Guide
 
-1. List all available themes:
+1. List available themes:
    ```bash
    bin/magento mageforge:theme:list
    ```
 
-2. Build a specific theme:
+2. Build a theme:
    ```bash
    bin/magento mageforge:theme:build <theme-code>
    ```
    Example: `bin/magento mageforge:theme:build Magento/luma`
 
-3. Start watch mode for development:
+3. Start development watch mode:
    ```bash
    bin/magento mageforge:theme:watch <theme-code>
    ```
 
-### Supported Theme Types
-
-- **Magento Standard Themes**: LESS-based themes
-- **Hyvä Themes**: Tailwind CSS based themes
-- **Custom Tailwind Themes**: Standalone Tailwind implementations
-
-### Tips & Tricks
-
-- Use the `-v` option for more detailed output
-- Watch mode supports hot-reloading for LESS and Tailwind
-- Check system information anytime with `mageforge:system:check`
-- Use shortcodes for faster command execution, for example `bin/magento m:t:b` instead of `bin/magento mageforge:theme:build`
-- Theme build and watch commands have special aliases: `frontend:build` and `frontend:watch`
-
-## Extending MageForge
-
-MageForge provides a modular architecture that allows developers to create custom theme builders for specific project requirements. For more information, see:
-
-- [Custom Theme Builders Documentation](./docs/custom_theme_builders.md)
-- [Commands Documentation](./docs/commands.md)
-
-## Report Feature or Bugs
-
-MageForge provides several forms to submit feature requests or report a bug.
-You will find it in the [issue section](https://github.com/OpenForgeProject/mageforge/issues) of GitHub.
-
-## Contributing
-
-We welcome contributions from the community! Please see our [Contributing Guidelines](./CONTRIBUTING.md) for more information on how to get involved.
+4. Enjoy automatic CSS rebuilding you work on your theme files!
 
-## License
+## Additional Documentation
 
-See the [LICENSE](LICENSE) file for more details.
+- [Advanced Usage Guide](./docs/advanced_usage.md) - Tips, tricks and troubleshooting
+- [Custom Theme Builders Documentation](./docs/custom_theme_builders.md) - Extend MageForge for your custom themes
+- [Commands Documentation](./docs/commands.md) - Detailed command reference
 
-## Support
+## Community & Support
 
-For support, please open an issue on the [GitHub repository](https://github.com/OpenForgeProject/mageforge/issues) or join our [Discord community](https://discord.gg/H5CjMXQQHn).
+- **Report Bugs/Features**: [GitHub Issues](https://github.com/OpenForgeProject/mageforge/issues)
+- **Get Help**: [Discord Community](https://discord.gg/H5CjMXQQHn)
+- **Contributing**: See [Contributing Guidelines](./CONTRIBUTING.md)
 
-## Changelog
+## Project Information
 
-All notable changes to this project will be documented in the [CHANGELOG](CHANGELOG.md) file.
+- **License**: [LICENSE](LICENSE)
+- **Changelog**: [CHANGELOG](CHANGELOG.md)
 
 ---
 
 Thank you for using MageForge!
-We hope it makes your development process smoother and more efficient.
diff --git a/docs/advanced_usage.md b/docs/advanced_usage.md
@@ -0,0 +1,87 @@
+# MageForge Advanced Usage
+
+This document provides detailed information and advanced tips for using MageForge effectively in your Magento 2 development workflow.
+
+## Theme Development Tips
+
+### Command Efficiency
+
+- Use shortcodes for faster command execution:
+  - `m:t:b` instead of `mageforge:theme:build`
+  - `m:t:w` instead of `mageforge:theme:watch`
+  - `m:s:c` for system check
+
+- Alternative aliases for common commands:
+  - `frontend:build` for `mageforge:theme:build`
+  - `frontend:watch` for `mageforge:theme:watch`
+
+### Development Workflow
+
+1. **System Check**: Before starting development, run a system check:
+   ```bash
+   bin/magento mageforge:system:check
+   ```
+
+2. **Enhanced Output**: Use the `-v` option for more detailed information during builds:
+   ```bash
+   bin/magento mageforge:theme:build <theme-code> -v
+   ```
+
+3. **Hot-reloading**: Watch mode automatically detects changes and rebuilds:
+   - For LESS files in standard Magento themes
+   - For Tailwind-based templates in Hyvä themes
+   - For custom CSS implementations
+
+## Theme Type Specifics
+
+### Standard Magento Themes (LESS)
+
+For traditional LESS-based Magento themes, MageForge handles:
+- LESS compilation
+- Source map generation
+- Minification for production
+
+### Hyvä Themes (Tailwind CSS)
+
+MageForge streamlines Hyvä theme development with:
+- Automatic TailwindCSS compilation
+- PurgeCSS optimization
+- Component scanning
+
+### Custom Tailwind CSS Implementations
+
+For custom Tailwind setups (non-Hyvä), MageForge supports:
+- Custom Tailwind configuration
+- PostCSS processing
+- Custom directory structures
+
+### Avanta B2B Theme
+
+MageForge has special support for Avanta B2B themes with:
+- B2B-specific component scanning
+- Special optimization for B2B module templates
+
+## Performance Optimization
+
+- Build specific theme components instead of entire themes for faster development
+- Use the production flag for minified, optimized output when ready for deployment
+- Consider selective watching for large themes to improve performance
+
+## Troubleshooting
+
+Common issues and solutions:
+
+1. **Build Failures**:
+   - Ensure Node.js is installed and available
+   - Check for syntax errors in LESS or CSS files
+   - Verify Tailwind configuration is valid
+
+2. **Watch Mode Issues**:
+   - Check file permissions
+   - Ensure no conflicting processes are running
+
+3. **Integration Problems**:
+   - Clear Magento cache after theme builds
+   - Verify theme registration in Magento
+
+For more help, join our [Discord community](https://discord.gg/H5CjMXQQHn) or open an issue on GitHub.
