# Magento 2 + Hyvä Themes Project Guidelines

## Environment & CLI Constraints (Strict)
- **Do NOT use `xargs`** in Bash commands. It triggers dynamic path resolution errors in Claude Code (`permissions.blockReadsOutsideWorkingDirectories`). 
  - *Use:* `find <dir> -type f -exec ... {} +` or native loops instead.
- When running `bin/magento` commands, prefer using `timeout` for long-running scripts (e.g., `timeout 30 php bin/magento ...`).
- Always check generated dynamic files or plugins using targeted `-exec` or single file reads.

## Architecture & Code Rules (Magento 2 + Hyvä)
- **Frontend Stack:** Hyvä Themes uses **Alpine.js** and **Tailwind CSS**. Do NOT introduce RequireJS, KnockoutJS, or traditional Luma JS components in Hyvä modules/themes.
- **Dependency Injection & Plugins:**
  - Avoid creating plugins (`di.xml`) for private/protected methods.
  - Keep plugins lean and verify `di.xml` targets existing interface/class parameters.
  - Check module dependency setup in `etc/module.xml` before adding new events or plugins.
- **GraphQL & Layouts:**
  - Hyvä relies heavily on GraphQL endpoints and lightweight ViewModels (`Magento\Framework\View\Element\Block\ArgumentInterface`).
  - Prefer ViewModels over custom Block classes for passing data to Alpine.js/PHTML templates.

## Common CLI Workflows
- **Flush Cache:** `php bin/magento cache:flush` (or specific cache types: `cache:flush layout block_html full_page`).
- **DI Compilation / Setup Upgrade:** Run standard Magento commands sequentially when modifying PHP classes or constructor signatures.
- **Tailwind Build:** Run theme watcher/compiler inside `app/design/frontend/<Vendor>/<theme>/web/tailwind/` when tweaking Tailwind classes.