@lbajsarowicz/warden-skill 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lukasz Bajsarowicz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,67 @@
+# Warden Agent Skill
+
+Agent Skill for [Warden](https://warden.dev) – a Docker-based local development environment wrapper for PHP applications (Magento, Laravel, Symfony, WordPress, Drupal, and more).
+
+## Installation
+
+```bash
+# Via skills CLI
+npx skills add lbajsarowicz/ai-skills-warden
+
+# Or via npm
+npm install @lbajsarowicz/warden-skill
+```
+
+## What This Skill Provides
+
+Teaches AI agents how to:
+
+- Initialize and manage Warden environments
+- Import/export databases (including `pv | gzip -d | warden db import` pattern)
+- Run shell commands, debugging (Xdebug), and profiling (Blackfire, SPX)
+- Manage global services (Traefik, DNS, Mailpit)
+- Troubleshoot common issues (DNS, SSL, Xdebug, sync)
+- Map `.env` variables to services and generate configuration tables
+
+## Quick Reference
+
+| Task | Command |
+|------|---------|
+| Start environment | `warden svc up -d && warden env up -d` |
+| Database import | `pv dump.sql.gz \| gzip -d \| warden db import` |
+| Interactive MySQL | `warden db connect` |
+| Shell (debugging) | `warden debug` |
+| Shell (normal) | `warden shell` |
+| Preview config | `warden env config` |
+
+## Links
+
+- [Warden Documentation](https://docs.warden.dev)
+- [Warden GitHub](https://github.com/wardenenv/warden)
+
+## Publishing (Maintainers)
+
+Releases are automated via Conventional Commits. Merge a PR with `feat:` or `fix:` commits to trigger a new version and npm publish.
+
+### One-time Setup
+
+1. **npm access token**
+   - Create at https://www.npmjs.com/settings/lbajsarowicz/tokens
+   - Type: Automation, enable "Bypass two-factor authentication (2FA)"
+   - Add as GitHub secret: `NPM_TOKEN`
+
+2. **GitHub PAT for release**
+   - Create a Personal Access Token (classic: `repo` scope, or fine-grained: `Contents` + `Metadata` = Read and write)
+   - Add as GitHub secret: `RELEASE_TOKEN`
+   - **Branch protection**: If `main` is protected, add the PAT owner (e.g. `lbajsarowicz`) to **Settings → Branches → main → Allow specified actors to bypass required pull requests**. Otherwise the workflow's direct push will be rejected.
+
+### Release Flow
+
+1. Commit with Conventional Commits: `feat(commands): add X`, `fix(troubleshooting): correct Y`
+2. Open PR and merge to `main`
+3. CI calculates version, pushes version bump to `main`, creates tag (e.g. `v1.1.0`)
+4. Release workflow publishes to npm and creates GitHub Release
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: warden-dev
+description: Manage Docker-based local development environments with Warden. Use when setting up PHP/Node projects (Magento, Laravel, Symfony, WordPress, Drupal), importing databases, running shell commands, debugging with Xdebug, or managing Docker services. Triggers on "warden", "local environment", "docker-compose wrapper", "database import", "shell access".
+license: MIT
+metadata:
+  author: lbajsarowicz
+  version: '1.0.0'
+---
+
+# Warden Agent Skill
+
+Warden is a local wrapper for docker-compose that automates DNS (dnsmasq), reverse proxy (Traefik), and webmail (Mailpit). Project `.env` drives ephemeral `docker-compose.yml` generation. Preview with `warden env config`.
+
+## Quick Start
+
+```bash
+warden env-init myproject magento2   # Initialize project
+warden svc up -d                     # Start global services (Traefik, DNS, Mailpit)
+warden env up -d                     # Start project containers
+warden shell                        # Interactive shell in php-fpm
+```
+
+## Environment Lifecycle
+
+| Command | Purpose | Example |
+|---------|---------|---------|
+| `warden env-init` | Initialize new project | `warden env-init mystore magento2` |
+| `warden env up` | Start environment | `warden env up -d` |
+| `warden env down` | Stop environment | `warden env down` |
+| `warden env config` | Preview docker-compose | `warden env config` |
+| `warden env ps` | List containers | `warden env ps` |
+| `warden env pull` | Pull images | `warden env pull` |
+| `warden env logs -f nginx` | Follow logs | `warden env logs -f nginx` |
+| `warden env exec php-fpm bash` | Exec into container | `warden env exec php-fpm bash` |
+
+## Database Operations
+
+| Command | Purpose | Example |
+|---------|---------|---------|
+| `warden db connect` | Interactive MySQL | `warden db connect` |
+| `warden db import` | Import SQL dump | See patterns below |
+| `warden db dump` | Export database | `warden db dump > backup.sql` |
+| `warden db upgrade` | Upgrade MariaDB/MySQL | `warden db upgrade` |
+
+**Import patterns (preferred for large dumps):**
+
+```bash
+pv dump.sql.gz | gzip -d | warden db import
+gzip -dc dump.sql.gz | warden db import
+warden db import < database.sql
+```
+
+## Shell Access
+
+| Command | Purpose |
+|---------|---------|
+| `warden shell` | PHP-FPM container shell (default: bash) |
+| `warden debug` | Xdebug-enabled shell (use for debugging) |
+| `warden blackfire` | Blackfire profiler: `warden blackfire run php script.php` |
+| `warden spx` | PHP SPX profiler |
+
+**Important:** Use `warden debug` (not `warden shell`) when debugging with Xdebug.
+
+## Service Management
+
+| Command | Purpose |
+|---------|---------|
+| `warden svc up -d` | Start global services |
+| `warden svc down` | Stop global services |
+| `warden svc ps` | List global services |
+| `warden status` | List running environments |
+
+## File Sync (macOS)
+
+| Command | Purpose |
+|---------|---------|
+| `warden sync start` | Start Mutagen sync |
+| `warden sync monitor` | Monitor sync status |
+| `warden sync flush` | Flush sync |
+| `warden sync reset` | Reset sync |
+
+## Redis / Valkey
+
+```bash
+warden redis              # Interactive Redis CLI
+warden redis FLUSHALL      # Execute command
+warden valkey              # Valkey (Redis alternative)
+```
+
+## Environment Types
+
+Supported: `magento2`, `magento1`, `laravel`, `symfony`, `wordpress`, `drupal`, `shopware`, `cakephp`, `local`. See `references/environments.md`.
+
+## Key .env Variables
+
+Project `.env` controls services and versions. See `references/env-variables.md` for full reference.
+
+| Variable | Description |
+|----------|-------------|
+| `WARDEN_ENV_NAME` | Unique project identifier |
+| `WARDEN_ENV_TYPE` | Environment type |
+| `TRAEFIK_DOMAIN` | Base domain (default: `{name}.test`) |
+| `PHP_VERSION` | PHP version (7.4, 8.1–8.4) |
+| `WARDEN_DB`, `WARDEN_REDIS`, etc. | Service toggles (1/0) |
+| `MYSQL_DISTRIBUTION_VERSION` | MariaDB/MySQL version |
+
+## Service Name Mapping
+
+| .env Variable | Container Name(s) |
+|---------------|-------------------|
+| `WARDEN_DB=1` | `db` |
+| `WARDEN_REDIS=1` | `redis` |
+| `WARDEN_OPENSEARCH=1` | `opensearch` |
+| `WARDEN_ELASTICSEARCH=1` | `elasticsearch` |
+| `WARDEN_VARNISH=1` | `varnish` |
+| `WARDEN_RABBITMQ=1` | `rabbitmq` |
+| `WARDEN_NGINX=1` | `nginx` |
+| `PHP_VERSION` | `php-fpm`, `php-debug` |
+
+## Global Services & URLs
+
+Default domain: `warden.test`. Configure in `~/.warden/.env` (`WARDEN_SERVICE_DOMAIN`).
+
+| Service | URL |
+|---------|-----|
+| Traefik Dashboard | `https://traefik.warden.test` |
+| Webmail (Mailpit) | `https://webmail.warden.test` |
+| Portainer | `https://portainer.warden.test` |
+| phpMyAdmin | `https://phpmyadmin.warden.test` |
+
+**Email (Mailpit):** No SMTP config needed. Warden routes sendmail to Mailpit. All emails at `https://webmail.warden.test`.
+
+## Framework Compatibility
+
+For "match Magento 2.4.8 requirements" requests:
+
+1. Search official docs for system requirements
+2. Map to `.env`: PHP → `PHP_VERSION`, DB → `MYSQL_DISTRIBUTION_VERSION`, etc.
+3. Update `.env` with matched versions
+
+## Agent Behavior Examples
+
+**Generate service table:** Read `.env`, map `WARDEN_*` variables to service status, output table (Service | Status | Version).
+
+**Verify PHP running:** Run `warden env ps`, check for `php-fpm`, `php-debug`, `php-blackfire`.
+
+**Troubleshoot non-loading site:** `warden svc ps` → `warden env ps` → `ping app.{project}.test` → `warden env logs nginx`.
+
+**Xdebug not working:** Use `warden debug`, verify IDE server name `{project}-docker`, port 9003, XDEBUG_SESSION cookie.
+
+## References
+
+- `references/commands.md` – Full command reference
+- `references/environments.md` – Environment types
+- `references/env-variables.md` – .env variable reference
+- `references/global-services.md` – Service URLs and config
+- `references/troubleshooting.md` – Common issues and solutions
+- `examples/workflows.md` – Workflow examples

package/examples/workflows.md

@@ -0,0 +1,65 @@
+# Common Workflows
+
+## New Magento 2 Project Setup
+
+```bash
+warden env-init mystore magento2
+# Edit .env to customize versions if needed
+warden svc up -d
+warden env up -d
+warden shell
+# Inside: composer install, bin/magento setup:install, etc.
+```
+
+## Database Import from Production
+
+```bash
+# With progress (recommended for large dumps)
+pv production.sql.gz | gzip -d | warden db import
+
+# Without pv
+gzip -dc production.sql.gz | warden db import
+
+# Plain SQL
+warden db import < database.sql
+```
+
+## Debugging with Xdebug
+
+```bash
+warden debug
+# Inside container, Xdebug is preconfigured
+php bin/magento cache:flush
+# Set breakpoint in IDE, trigger from browser with XDEBUG_SESSION cookie
+```
+
+## Update Service Versions for Framework
+
+1. Search official docs for framework system requirements (e.g. Magento 2.4.8-p2)
+2. Read project `.env`
+3. Update `PHP_VERSION`, `MYSQL_DISTRIBUTION_VERSION`, `OPENSEARCH_VERSION`, etc.
+4. Run `warden env pull && warden env up -d --force-recreate`
+
+## Verify Service Status
+
+```bash
+warden env ps
+# Check for php-fpm, php-debug, db, nginx, etc.
+```
+
+## Generate Service Configuration Table
+
+1. Read `.env`
+2. Map `WARDEN_*` variables to service status (1=enabled, 0=disabled)
+3. Map version variables (PHP_VERSION, MYSQL_DISTRIBUTION_VERSION, etc.)
+4. Output table: Service | Status | Version
+
+## Troubleshoot Non-Loading Site
+
+```bash
+warden svc ps          # Global services running?
+warden env ps          # Project containers running?
+ping app.myproject.test  # DNS resolving?
+warden env logs nginx  # Check nginx logs
+warden doctor -v       # Full diagnostic
+```

package/metadata.json

@@ -0,0 +1,22 @@
+{
+  "version": "1.2.0",
+  "organization": "warden.dev",
+  "date": "February 2026",
+  "abstract": "Manage Docker-based local development environments for PHP applications including Magento, Laravel, Symfony, WordPress, and Drupal. Wraps docker-compose with intelligent defaults and service orchestration.",
+  "references": [
+    "https://warden.dev",
+    "https://docs.warden.dev",
+    "https://github.com/wardenenv/warden"
+  ],
+  "keywords": [
+    "docker",
+    "docker-compose",
+    "local-development",
+    "magento",
+    "laravel",
+    "symfony",
+    "wordpress",
+    "php",
+    "devops"
+  ]
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@lbajsarowicz/warden-skill",
+  "version": "1.2.0",
+  "description": "Agent Skill for Warden Docker development environments",
+  "keywords": [
+    "warden",
+    "docker",
+    "magento",
+    "laravel",
+    "php",
+    "agent-skill",
+    "cursor",
+    "ai"
+  ],
+  "author": "Lukasz Bajsarowicz",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lbajsarowicz/ai-skills-warden.git"
+  },
+  "files": [
+    "SKILL.md",
+    "metadata.json",
+    "references/",
+    "examples/",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^19.0.0",
+    "@commitlint/config-conventional": "^19.0.0"
+  }
+}

package/references/commands.md

@@ -0,0 +1,73 @@
+# Warden Command Reference
+
+## Environment Lifecycle
+
+| Command | Description |
+|---------|-------------|
+| `warden env-init <name> <type>` | Initialize new project. Types: magento2, magento1, laravel, symfony, wordpress, drupal, shopware, cakephp, local |
+| `warden env up [-d]` | Start project containers. Use `-d` for detached mode |
+| `warden env down` | Stop and remove project containers |
+| `warden env start` | Start stopped containers |
+| `warden env stop` | Stop containers without removing |
+| `warden env restart [service]` | Restart all or specific service |
+| `warden env ps` | List containers and status |
+| `warden env config` | Preview generated docker-compose.yml |
+| `warden env pull` | Pull latest Docker images |
+| `warden env logs [-f] [service]` | View logs. Use `-f` to follow |
+| `warden env exec <service> <cmd>` | Execute command in container |
+
+## Database
+
+| Command | Description |
+|---------|-------------|
+| `warden db connect` | Interactive MySQL session |
+| `warden db import` | Import from stdin. Use `pv file.sql.gz \| gzip -d \| warden db import` for large dumps |
+| `warden db dump` | Export via mysqldump. Redirect to file: `warden db dump > backup.sql` |
+| `warden db upgrade` | Run MariaDB/MySQL upgrade after version change |
+
+## Shell Access
+
+| Command | Description |
+|---------|-------------|
+| `warden shell` | Bash in php-fpm container |
+| `warden debug` | Bash with Xdebug enabled (use for debugging) |
+| `warden blackfire run <cmd>` | Run command with Blackfire profiler |
+| `warden spx` | PHP SPX profiler |
+
+## Global Services (svc)
+
+| Command | Description |
+|---------|-------------|
+| `warden svc up [-d]` | Start Traefik, DNSMasq, Mailpit |
+| `warden svc down` | Stop global services |
+| `warden svc ps` | List global service status |
+| `warden svc logs [service]` | View global service logs |
+
+## Sync (Mutagen, macOS)
+
+| Command | Description |
+|---------|-------------|
+| `warden sync start` | Start file sync |
+| `warden sync stop` | Stop sync |
+| `warden sync list [-l]` | List sync status |
+| `warden sync monitor` | Continuous status display |
+| `warden sync flush` | Force sync cycle |
+| `warden sync pause` | Pause sync |
+| `warden sync resume` | Resume sync |
+| `warden sync reset` | Reset sync session |
+
+## Redis / Valkey
+
+| Command | Description |
+|---------|-------------|
+| `warden redis [cmd]` | Redis CLI. Pass command or interactive |
+| `warden valkey [cmd]` | Valkey CLI (Redis alternative) |
+
+## Other
+
+| Command | Description |
+|---------|-------------|
+| `warden status` | List running environments |
+| `warden doctor [-v]` | Diagnose Warden setup. `-v` for verbose |
+| `warden sign-certificate <domain>` | Sign SSL certificate for domain |
+| `warden vnc` | VNC access (when enabled) |

package/references/env-variables.md

@@ -0,0 +1,45 @@
+# .env Variable Reference
+
+## Common Variables (All Environments)
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `WARDEN_ENV_NAME` | (required) | Unique project identifier |
+| `WARDEN_ENV_TYPE` | (required) | magento2, laravel, symfony, etc. |
+| `TRAEFIK_DOMAIN` | `{WARDEN_ENV_NAME}.test` | Base domain |
+| `TRAEFIK_SUBDOMAIN` | `app` | Subdomain prefix |
+| `WARDEN_WEB_ROOT` | `/` | Web root path |
+| `PHP_VERSION` | varies by type | 7.4, 8.1, 8.2, 8.3, 8.4 |
+| `PHP_XDEBUG_3` | `1` | Use Xdebug 3 |
+| `NODE_VERSION` | varies | Node.js version |
+| `COMPOSER_VERSION` | `2` | Composer version |
+| `MYSQL_DISTRIBUTION` | `mariadb` | mariadb or mysql |
+| `MYSQL_DISTRIBUTION_VERSION` | varies | Database version |
+
+## Service Toggles
+
+| Variable | Default (Magento2) | Container |
+|----------|--------------------|-----------|
+| `WARDEN_DB` | 1 | db |
+| `WARDEN_REDIS` | 1 | redis |
+| `WARDEN_VALKEY` | 0 | valkey |
+| `WARDEN_ELASTICSEARCH` | 0 | elasticsearch |
+| `WARDEN_OPENSEARCH` | 1 | opensearch |
+| `WARDEN_VARNISH` | 1 | varnish |
+| `WARDEN_RABBITMQ` | 1 | rabbitmq |
+| `WARDEN_NGINX` | 1 | nginx |
+| `WARDEN_BLACKFIRE` | 0 | php-blackfire |
+| `WARDEN_PHP_SPX` | 0 | php-spx |
+| `WARDEN_SELENIUM` | 0 | selenium |
+
+## Magento 2 Version Defaults
+
+| Variable | Default |
+|----------|---------|
+| `PHP_VERSION` | 8.4 |
+| `MYSQL_DISTRIBUTION_VERSION` | 11.4 |
+| `REDIS_VERSION` | 7.2 |
+| `VARNISH_VERSION` | 7.7 |
+| `RABBITMQ_VERSION` | 4.1 |
+| `OPENSEARCH_VERSION` | 3.3 |
+| `NODE_VERSION` | 20 |

package/references/environments.md

@@ -0,0 +1,43 @@
+# Warden Environment Types
+
+## Supported Types
+
+| Type | Services | Use Case |
+|------|----------|----------|
+| `magento2` | Nginx, Varnish, PHP-FPM, MariaDB, OpenSearch, Redis, RabbitMQ | Adobe Commerce / Magento 2 |
+| `magento1` | Nginx, PHP-FPM, MariaDB, Redis | Magento 1.x |
+| `laravel` | Nginx, PHP-FPM, MariaDB, Redis | Laravel apps |
+| `symfony` | Nginx, PHP-FPM, MariaDB, Redis | Symfony 4+ |
+| `wordpress` | Nginx, PHP-FPM, MariaDB | WordPress sites |
+| `drupal` | Nginx, PHP-FPM, MariaDB | Drupal CMS |
+| `shopware` | Nginx, PHP-FPM, MariaDB, Redis | Shopware 6 |
+| `cakephp` | Nginx, PHP-FPM, MariaDB | CakePHP |
+| `local` | User-defined | Custom Docker setup |
+
+## Initialization
+
+```bash
+warden env-init <project-name> <type>
+```
+
+Example: `warden env-init mystore magento2`
+
+## Default Services by Type
+
+- **Magento 2**: DB, Redis, Varnish, RabbitMQ, OpenSearch (or Elasticsearch)
+- **Magento 1**: DB, Redis
+- **Laravel/Symfony/Shopware**: DB, Redis
+- **WordPress/Drupal/CakePHP**: DB
+
+## Optional Services
+
+Toggle in `.env` with `WARDEN_*=1` or `0`:
+
+- `WARDEN_ELASTICSEARCH`
+- `WARDEN_OPENSEARCH`
+- `WARDEN_VARNISH`
+- `WARDEN_RABBITMQ`
+- `WARDEN_BLACKFIRE`
+- `WARDEN_PHP_SPX`
+- `WARDEN_SELENIUM`
+- `WARDEN_VALKEY`

package/references/global-services.md

@@ -0,0 +1,35 @@
+# Global Services & URLs
+
+## Service URLs (default domain: warden.test)
+
+| Service | URL |
+|---------|-----|
+| Traefik Dashboard | https://traefik.warden.test |
+| Webmail (Mailpit) | https://webmail.warden.test |
+| Portainer | https://portainer.warden.test |
+| phpMyAdmin | https://phpmyadmin.warden.test |
+
+Per-project: RabbitMQ, Elasticsearch, OpenSearch at `https://{service}.{project}.test`
+
+## Global Configuration (~/.warden/.env)
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `WARDEN_SERVICE_DOMAIN` | warden.test | Base domain for global services |
+| `WARDEN_DNSMASQ_ENABLE` | 1 | Enable DNS for .test domains |
+| `WARDEN_PORTAINER_ENABLE` | 0 | Enable Portainer UI |
+| `WARDEN_PHPMYADMIN_ENABLE` | 1 | Enable phpMyAdmin |
+| `WARDEN_MUTAGEN_ENABLE` | 1 (macOS) / 0 (Linux) | Mutagen file sync |
+
+## Changing the Global Domain
+
+1. Edit `~/.warden/.env`
+2. Set `WARDEN_SERVICE_DOMAIN=your-domain.local`
+3. Restart: `warden svc down && warden svc up -d`
+4. Update DNS resolver if needed (e.g. `/etc/resolver/local` on macOS)
+
+## Email (Mailpit)
+
+No SMTP configuration needed. Warden configures sendmail to route to Mailpit. All emails appear at https://webmail.warden.test.
+
+For Magento: default sendmail transport works. No SMTP module required.

package/references/troubleshooting.md

@@ -0,0 +1,64 @@
+# Troubleshooting
+
+## DNS Resolution
+
+| Problem | Platform | Solution |
+|---------|----------|----------|
+| Port 53 in use | macOS | Disable Internet Sharing, or `sudo brew services stop dnsmasq` |
+| ERR_NAME_NOT_RESOLVED | All | Verify `warden svc up -d` is running |
+| DNS not working | Linux | Add entries to `/etc/hosts` or configure systemd-resolved |
+| DNS not working | Windows/WSL2 | Add 127.0.0.1 as first DNS server |
+
+## SSL Certificates
+
+| Problem | Solution |
+|---------|----------|
+| "Your connection is not private" | Import `~/.warden/ssl/rootca/certs/ca.cert.pem` to browser |
+| Firefox doesn't trust cert | Preferences > Privacy > View Certificates > Import CA |
+| Certificate generation fails | Run `warden install` to regenerate CA |
+
+## Xdebug
+
+| Problem | Solution |
+|---------|----------|
+| Could not connect to debugging client | Check firewall allows port 9003 |
+| Xdebug not triggering | Use `warden debug` (not `warden shell`), set XDEBUG_SESSION cookie |
+| Wrong host connection | Verify IDE server name: `{WARDEN_ENV_NAME}-docker` |
+
+## Elasticsearch/OpenSearch (Apple Silicon)
+
+| Problem | Solution |
+|---------|----------|
+| Container crashes (SIGILL) | Use ARM-compatible version (OpenSearch 2.19+) |
+| Java VM crash | Increase Docker memory to 6GB+ |
+
+## Mutagen Sync (macOS)
+
+| Problem | Solution |
+|---------|----------|
+| Files not syncing | `warden sync flush` or `warden sync reset` |
+| Sync stuck on stop | Kill mutagen process, restart environment |
+| Linux + MUTAGEN_ENABLE=1 | Remove from `~/.warden/.env` (not needed on Linux) |
+
+## Database
+
+| Problem | Solution |
+|---------|----------|
+| DB container not starting | Check logs: `warden env logs db` |
+| Connection refused | Verify `warden env ps` shows db running |
+
+## Email
+
+| Problem | Solution |
+|---------|----------|
+| Emails not in Mailpit | Check `warden svc logs mailpit`, verify sendmail_path |
+| mhsendmail errors (PHP 8.4) | Update to latest Warden images |
+
+## General Diagnostics
+
+```bash
+warden doctor -v    # Full diagnostic
+warden svc ps       # Global services
+warden env ps       # Project containers
+warden env logs -f  # Follow all logs
+```