From f6bb21b4040d8b69767ff54d8cd3d951687b212e Mon Sep 17 00:00:00 2001
From: Zhongwei Li <lizhongwei.nkcs@gmail.com>
Date: Sun, 30 Nov 2025 08:45:19 +0800
Subject: [PATCH] Initial commit

---
 .claude-plugin/plugin.json |  11 +
 README.md                  |   3 +
 SKILL.md                   | 575 +++++++++++++++++++++++++++++++++++++
 plugin.lock.json           |  53 ++++
 references/ddev.md         | 450 +++++++++++++++++++++++++++++
 references/drush.md        | 387 +++++++++++++++++++++++++
 6 files changed, 1479 insertions(+)
 create mode 100644 .claude-plugin/plugin.json
 create mode 100644 README.md
 create mode 100644 SKILL.md
 create mode 100644 plugin.lock.json
 create mode 100644 references/ddev.md
 create mode 100644 references/drush.md

diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
new file mode 100644
index 0000000..ff3ec49
--- /dev/null
+++ b/.claude-plugin/plugin.json
@@ -0,0 +1,11 @@
+{
+  "name": "drupal-tooling",
+  "description": "Drupal development tooling skill for DDEV local environments and Drush command-line operations (Drupal 8-11+). Use when working with Docker-based development environments, Drush commands, deployment workflows, or site management tasks.",
+  "version": "1.0.0",
+  "author": {
+    "name": "Drupal Skills Team"
+  },
+  "skills": [
+    "./"
+  ]
+}
\ No newline at end of file
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..91912c9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,3 @@
+# drupal-tooling
+
+Drupal development tooling skill for DDEV local environments and Drush command-line operations (Drupal 8-11+). Use when working with Docker-based development environments, Drush commands, deployment workflows, or site management tasks.
diff --git a/SKILL.md b/SKILL.md
new file mode 100644
index 0000000..f6868b4
--- /dev/null
+++ b/SKILL.md
@@ -0,0 +1,575 @@
+---
+name: drupal-tooling
+description: Drupal development tooling skill for DDEV local environments and Drush command-line operations (Drupal 8-11+). Use when working with Docker-based development environments, Drush commands, deployment workflows, or site management tasks.
+---
+
+# Drupal Development Tooling
+
+## Overview
+
+Enable expert-level Drupal development tooling capabilities with comprehensive guidance for DDEV Docker-based local development environments and Drush command-line operations for Drupal 8, 9, 10, and 11+.
+
+## When to Use This Skill
+
+Invoke this skill when working with:
+- **DDEV operations**: Starting, managing, or configuring local development environments
+- **Drush commands**: Site management, configuration, cache operations
+- **Database management**: Import/export, snapshots, migrations
+- **Deployment workflows**: Configuration sync, database updates
+- **Development setup**: Project initialization, environment configuration
+- **Troubleshooting**: Debugging environment or command-line issues
+
+## Core Capabilities
+
+### 1. DDEV Local Development
+
+Manage Docker-based local Drupal environments efficiently:
+
+**Project initialization:**
+```bash
+# Initialize new Drupal project
+ddev config --project-type=drupal10 --docroot=web --create-docroot
+
+# Start containers
+ddev start
+
+# Install Drupal via Composer
+ddev composer create drupal/recommended-project
+
+# Install Drupal site
+ddev drush site:install standard --account-name=admin --account-pass=admin
+```
+
+**Daily operations:**
+```bash
+# Start/stop project
+ddev start
+ddev stop
+ddev restart
+
+# SSH into container
+ddev ssh
+
+# Launch site in browser
+ddev launch
+
+# View logs
+ddev logs
+ddev logs -f  # Follow logs
+```
+
+**Database operations:**
+```bash
+# Import database
+ddev import-db --src=database.sql.gz
+
+# Export database
+ddev export-db --file=backup.sql.gz --gzip
+
+# Create snapshot
+ddev snapshot
+
+# Restore snapshot
+ddev snapshot restore
+
+# Access MySQL CLI
+ddev mysql
+```
+
+**Reference documentation:**
+- `references/ddev.md` - Complete DDEV reference
+
+### 2. Drush Command-Line Management
+
+Execute site management tasks efficiently:
+
+**Cache management:**
+```bash
+# Rebuild cache (most common)
+ddev drush cr
+
+# Clear specific cache
+ddev drush cache:clear css-js
+ddev drush cache:clear render
+```
+
+**Configuration management:**
+```bash
+# Export configuration
+ddev drush config:export
+ddev drush cex
+
+# Import configuration
+ddev drush config:import
+ddev drush cim
+
+# View configuration
+ddev drush config:get system.site
+ddev drush cget system.site
+
+# Set configuration
+ddev drush config:set system.site name "My Site"
+ddev drush cset system.site name "My Site"
+```
+
+**Module management:**
+```bash
+# Enable module
+ddev drush pm:enable mymodule -y
+ddev drush en mymodule -y
+
+# Uninstall module
+ddev drush pm:uninstall mymodule -y
+ddev drush pmu mymodule -y
+
+# List modules
+ddev drush pm:list
+ddev drush pml
+
+# Download module
+ddev drush pm:download webform
+```
+
+**Database updates:**
+```bash
+# Run pending database updates
+ddev drush updatedb -y
+ddev drush updb -y
+```
+
+**User management:**
+```bash
+# One-time login URL
+ddev drush user:login
+ddev drush uli
+
+# Login as specific user
+ddev drush uli admin
+
+# Create user
+ddev drush user:create newuser --mail="user@example.com" --password="pass"
+
+# Change password
+ddev drush user:password admin "newpassword"
+```
+
+**Reference documentation:**
+- `references/drush.md` - Complete Drush reference
+
+### 3. Development Workflows
+
+Common development and deployment workflows:
+
+**Standard deployment:**
+```bash
+# Run database updates
+ddev drush updb -y
+
+# Import configuration
+ddev drush cim -y
+
+# Clear cache
+ddev drush cr
+
+# One-liner version
+ddev drush updb -y && ddev drush cim -y && ddev drush cr
+```
+
+**Fresh site setup:**
+```bash
+# Clone repository
+git clone <repo> myproject
+cd myproject
+
+# Start DDEV
+ddev start
+
+# Install dependencies
+ddev composer install
+
+# Import database and files
+ddev import-db --src=database.sql.gz
+ddev import-files --src=files.tar.gz
+
+# Clear cache
+ddev drush cr
+
+# Launch site
+ddev launch
+```
+
+**Theme/module development:**
+```bash
+# Start work
+ddev start
+
+# Clear cache frequently
+ddev drush cr
+
+# Watch for changes (if using build tools)
+ddev exec npm run watch
+
+# View logs
+ddev drush watchdog:tail
+```
+
+### 4. Code Generation
+
+Use Drush generators to scaffold code:
+
+```bash
+# Generate module
+ddev drush generate module
+
+# Generate controller
+ddev drush generate controller
+
+# Generate form
+ddev drush generate form
+
+# Generate plugin block
+ddev drush generate plugin:block
+
+# Generate service
+ddev drush generate service
+
+# Generate theme
+ddev drush generate theme
+
+# Generate hook
+ddev drush generate hook
+
+# List all generators
+ddev drush generate --help
+```
+
+### 5. Debugging & Troubleshooting
+
+Debug and monitor your Drupal site:
+
+**Enable Xdebug:**
+```bash
+# Enable Xdebug
+ddev xdebug on
+
+# Disable Xdebug (improves performance)
+ddev xdebug off
+
+# Check status
+ddev xdebug status
+```
+
+**View logs:**
+```bash
+# Recent watchdog messages
+ddev drush watchdog:show
+
+# Follow watchdog logs
+ddev drush watchdog:tail
+
+# Container logs
+ddev logs -s web
+ddev logs -s db
+```
+
+**Project information:**
+```bash
+# Show project details
+ddev describe
+
+# Drupal status
+ddev drush status
+ddev drush st
+
+# List all DDEV projects
+ddev list
+```
+
+## Best Practices
+
+### DDEV Best Practices
+1. **Run tools through DDEV**: Always use `ddev drush`, `ddev composer`, `ddev npm`
+2. **Snapshots**: Create before risky operations
+3. **Performance**: Enable Mutagen (Mac) or NFS for better file sync
+4. **Xdebug**: Only enable when debugging
+5. **Version control**: Commit `.ddev/config.yaml` to share configuration
+6. **Clean shutdown**: Use `ddev stop` before system shutdown
+
+### Drush Best Practices
+1. **Aliases**: Use short aliases (`cr`, `cex`, `cim`, `uli`)
+2. **Automation**: Add `-y` flag to skip confirmations
+3. **Custom commands**: Create for repetitive tasks
+4. **Site aliases**: Configure for multi-environment management
+5. **Chaining**: Use `&&` for sequential operations
+6. **Error handling**: Check exit codes in scripts
+
+### Deployment Best Practices
+1. **Order**: Run updates (`updb`) before config import (`cim`)
+2. **Testing**: Test deployment workflow in staging first
+3. **Backups**: Always backup before major changes
+4. **Rollback plan**: Have a way to revert changes
+5. **Monitoring**: Check logs after deployment
+
+## Common Operations
+
+### Initialize DDEV for Existing Project
+
+```bash
+cd existing-project
+
+# Configure DDEV
+ddev config
+
+# Start containers
+ddev start
+
+# Install dependencies
+ddev composer install
+
+# Import database (if available)
+ddev import-db --src=backup.sql.gz
+
+# Clear cache
+ddev drush cr
+```
+
+### Pull From Remote Environment
+
+```bash
+# Configure Drush alias for remote site
+# Then pull database and files
+ddev pull @production
+
+# Or pull separately
+ddev drush sql:sync @production @self
+ddev rsync @production:%files @self:%files
+```
+
+### Update Drupal Core
+
+```bash
+# Backup first
+ddev snapshot
+
+# Update with Composer
+ddev composer update drupal/core "drupal/core-*" --with-all-dependencies
+
+# Run database updates
+ddev drush updb -y
+
+# Clear cache
+ddev drush cr
+```
+
+### Enable Development Settings
+
+```bash
+# Copy development settings
+cp sites/example.settings.local.php sites/default/settings.local.php
+
+# Disable CSS/JS aggregation via Drush
+ddev drush config:set system.performance css.preprocess 0 -y
+ddev drush config:set system.performance js.preprocess 0 -y
+
+# Enable Twig debugging
+# Edit sites/default/services.yml:
+# twig.config:
+#   debug: true
+#   auto_reload: true
+#   cache: false
+
+# Clear cache
+ddev drush cr
+```
+
+## Troubleshooting
+
+### DDEV Issues
+
+**Containers won't start:**
+```bash
+# Check Docker is running
+docker ps
+
+# Restart DDEV
+ddev restart
+
+# Power off and restart
+ddev poweroff
+ddev start
+
+# Clean restart
+ddev restart --clean
+```
+
+**Port conflicts:**
+```bash
+# Check what's using ports
+ddev describe
+
+# Change ports in .ddev/config.yaml:
+# router_http_port: "8080"
+# router_https_port: "8443"
+
+# Restart
+ddev restart
+```
+
+**Permission issues:**
+```bash
+# Fix file permissions
+ddev exec chmod -R 755 web/sites/default/files
+ddev exec chown -R www-data:www-data web/sites/default/files
+```
+
+### Drush Issues
+
+**Drush not found:**
+```bash
+# Always run through DDEV
+ddev drush status
+
+# Not just: drush status
+```
+
+**Configuration sync failures:**
+```bash
+# Check for overridden configuration
+ddev drush config:status
+
+# Force import
+ddev drush cim -y --partial
+
+# Check specific config
+ddev drush config:get system.site
+```
+
+**Database update failures:**
+```bash
+# Run with verbose output
+ddev drush updb -v
+
+# Check specific module updates
+ddev drush updatedb:status
+
+# Check logs
+ddev drush watchdog:show
+```
+
+## Performance Optimization
+
+### DDEV Performance (Mac)
+
+**Enable Mutagen:**
+```bash
+# In .ddev/config.yaml
+ddev config --mutagen-enabled
+
+# Restart
+ddev restart
+```
+
+**Enable NFS:**
+```bash
+# In .ddev/config.yaml
+ddev config --nfs-mount-enabled
+
+# Restart
+ddev restart
+```
+
+### Drush Performance
+
+**Disable Xdebug when not debugging:**
+```bash
+ddev xdebug off
+```
+
+**Use specific commands instead of aliases:**
+```bash
+# Faster (loads less)
+ddev drush cache:rebuild
+
+# vs
+ddev drush cr
+```
+
+## Resources
+
+### Reference Documentation
+
+- **`references/ddev.md`** - Complete DDEV reference
+  - Project initialization and configuration
+  - Database and file operations
+  - Add-ons and services (Redis, Elasticsearch, etc.)
+  - Performance optimization
+  - Troubleshooting
+
+- **`references/drush.md`** - Complete Drush reference
+  - Cache management commands
+  - Configuration management
+  - Module and theme operations
+  - Database operations
+  - User management
+  - Custom command development
+
+### Searching References
+
+```bash
+# Find DDEV command
+grep -r "ddev snapshot" references/
+
+# Find Drush command
+grep -r "config:import" references/
+
+# Find deployment info
+grep -r "deployment" references/
+```
+
+## Common Use Cases
+
+### Local Development Setup
+
+1. Clone project: `git clone <repo>`
+2. Configure DDEV: `ddev config`
+3. Start: `ddev start`
+4. Install dependencies: `ddev composer install`
+5. Import DB: `ddev import-db --src=db.sql.gz`
+6. Clear cache: `ddev drush cr`
+7. Launch: `ddev launch`
+
+### Deploying Configuration Changes
+
+1. Export config: `ddev drush cex -y`
+2. Commit to git: `git add config/ && git commit`
+3. Push: `git push`
+4. On server: `drush cim -y && drush cr`
+
+### Debugging Performance Issues
+
+1. Enable Xdebug: `ddev xdebug on`
+2. Set breakpoints in IDE
+3. Trigger request: `ddev launch`
+4. Step through code
+5. Disable Xdebug: `ddev xdebug off`
+
+## Version Compatibility
+
+### DDEV Versions
+- DDEV v1.21+ recommended
+- Supports all Drupal versions (8-11+)
+- Update with: `brew upgrade ddev` (Mac) or platform equivalent
+
+### Drush Versions
+- Drush 10+ for Drupal 8.4+
+- Drush 11+ for Drupal 9.0+
+- Drush 12+ for Drupal 10.0+
+- Install via Composer (project-specific)
+
+## See Also
+
+- **drupal-frontend** - Theme development and Twig templates
+- **drupal-backend** - Module development and APIs
+- [DDEV Documentation](https://ddev.readthedocs.io/) - Official DDEV docs
+- [Drush Documentation](https://www.drush.org/) - Official Drush docs
+- [DDEV Discord](https://discord.gg/hCZFfAMc5k) - Community support
diff --git a/plugin.lock.json b/plugin.lock.json
new file mode 100644
index 0000000..aa39109
--- /dev/null
+++ b/plugin.lock.json
@@ -0,0 +1,53 @@
+{
+  "$schema": "internal://schemas/plugin.lock.v1.json",
+  "pluginId": "gh:Omedia/drupal-skill:drupal-tooling",
+  "normalized": {
+    "repo": null,
+    "ref": "refs/tags/v20251128.0",
+    "commit": "8da4875c00f488ee896166a9771a4e4a401fdb89",
+    "treeHash": "25bb5082a13004d32220cdaad42f3cff8bf6dd4f6d2ee28f576836b75f15a875",
+    "generatedAt": "2025-11-28T10:12:18.914506Z",
+    "toolVersion": "publish_plugins.py@0.2.0"
+  },
+  "origin": {
+    "remote": "git@github.com:zhongweili/42plugin-data.git",
+    "branch": "master",
+    "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
+    "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
+  },
+  "manifest": {
+    "name": "drupal-tooling",
+    "description": "Drupal development tooling skill for DDEV local environments and Drush command-line operations (Drupal 8-11+). Use when working with Docker-based development environments, Drush commands, deployment workflows, or site management tasks.",
+    "version": "1.0.0"
+  },
+  "content": {
+    "files": [
+      {
+        "path": "README.md",
+        "sha256": "f55a4f6b7deeff7cba346852d953dc4cd0f9b59c4c9eaa8162ed480f6b2f5c43"
+      },
+      {
+        "path": "SKILL.md",
+        "sha256": "210316a4264cabcc22fc910750270fecf744074ee7928dd912e3b18bda335f8d"
+      },
+      {
+        "path": "references/drush.md",
+        "sha256": "297b55b0dcffa055d686c3bc69775e9f8dd520528fe6e72b3183e96eb90dfe0d"
+      },
+      {
+        "path": "references/ddev.md",
+        "sha256": "493a47ccf2233c2af146f7ad1f13493aa202ec2b8b69bd2d634b3b0c2ffb0d95"
+      },
+      {
+        "path": ".claude-plugin/plugin.json",
+        "sha256": "1c9f676e772c43dbd37e9b91135b3107f8d7ac89cbc553c66fa30c20bcff616f"
+      }
+    ],
+    "dirSha256": "25bb5082a13004d32220cdaad42f3cff8bf6dd4f6d2ee28f576836b75f15a875"
+  },
+  "security": {
+    "scannedAt": null,
+    "scannerVersion": null,
+    "flags": []
+  }
+}
\ No newline at end of file
diff --git a/references/ddev.md b/references/ddev.md
new file mode 100644
index 0000000..52fb1a8
--- /dev/null
+++ b/references/ddev.md
@@ -0,0 +1,450 @@
+# DDEV Commands Reference
+
+Comprehensive DDEV command reference for Drupal development. DDEV is a Docker-based local development environment.
+
+## Project Initialization
+
+```bash
+# Initialize DDEV in current directory
+ddev config
+
+# Initialize with Drupal specific settings
+ddev config --project-type=drupal10 --docroot=web --create-docroot
+
+# Initialize Drupal 9
+ddev config --project-type=drupal9 --docroot=web
+
+# Initialize Drupal 11
+ddev config --project-type=drupal --docroot=web
+
+# Configure project name and PHP version
+ddev config --project-name=myproject --php-version=8.2
+```
+
+## Project Management
+
+```bash
+# Start project
+ddev start
+
+# Stop project
+ddev stop
+
+# Restart project
+ddev restart
+
+# Delete project (keeps files, removes containers)
+ddev delete
+
+# Delete project and remove images
+ddev delete --omit-snapshot
+
+# Power off all DDEV projects
+ddev poweroff
+
+# Show project description
+ddev describe
+
+# List all DDEV projects
+ddev list
+```
+
+## Accessing Services
+
+```bash
+# SSH into web container
+ddev ssh
+
+# SSH into database container
+ddev ssh -s db
+
+# Open project in browser
+ddev launch
+
+# Open specific path
+ddev launch /admin
+
+# Open phpMyAdmin
+ddev launch -p
+
+# Open MailHog (email catcher)
+ddev launch -m
+```
+
+## Database Operations
+
+```bash
+# Import database from file
+ddev import-db --src=dump.sql
+ddev import-db --src=dump.sql.gz
+ddev import-db --file=dump.sql
+
+# Export database to file
+ddev export-db --file=backup.sql
+ddev export-db --file=backup.sql.gz --gzip
+
+# Execute MySQL query
+ddev mysql -e "SELECT * FROM users WHERE uid=1;"
+
+# Connect to MySQL CLI
+ddev mysql
+
+# Import database and files from @drush-alias
+ddev pull @production
+
+# Snapshot database (backup)
+ddev snapshot
+
+# Restore from snapshot
+ddev snapshot restore
+
+# List snapshots
+ddev snapshot list
+
+# Delete snapshot
+ddev snapshot delete --name=backup-name
+```
+
+## File Management
+
+```bash
+# Import files directory
+ddev import-files --src=/path/to/files
+
+# Pull files from remote using Drush alias
+ddev pull @production --skip-db
+
+# SCP files into container
+ddev scp local-file.txt :/var/www/html/web/
+
+# SCP files from container
+ddev scp :/var/www/html/web/file.txt ./local-file.txt
+```
+
+## Composer
+
+```bash
+# Run composer install
+ddev composer install
+
+# Require package
+ddev composer require drupal/webform
+
+# Require dev package
+ddev composer require --dev drupal/devel
+
+# Update packages
+ddev composer update
+
+# Remove package
+ddev composer remove drupal/old_module
+
+# Show installed packages
+ddev composer show
+```
+
+## Drush Integration
+
+```bash
+# Run Drush commands
+ddev drush status
+ddev drush cr
+ddev drush uli
+
+# Config import
+ddev drush cim -y
+
+# Config export
+ddev drush cex -y
+
+# Update database
+ddev drush updb -y
+
+# Enable module
+ddev drush en mymodule -y
+
+# Install Drupal
+ddev drush site:install standard --account-name=admin --account-pass=admin
+```
+
+## Logs & Debugging
+
+```bash
+# View container logs
+ddev logs
+
+# Follow logs in real-time
+ddev logs -f
+
+# View web server logs
+ddev logs -s web
+
+# View database logs
+ddev logs -s db
+
+# Enable Xdebug
+ddev xdebug on
+
+# Disable Xdebug
+ddev xdebug off
+
+# Toggle Xdebug
+ddev xdebug toggle
+
+# Check Xdebug status
+ddev xdebug status
+```
+
+## Mailhog (Email Testing)
+
+```bash
+# Launch MailHog UI
+ddev launch -m
+
+# All emails sent by Drupal are caught in MailHog
+# Access at: http://<project>.ddev.site:8025
+```
+
+## Custom Commands
+
+```bash
+# Execute arbitrary command in web container
+ddev exec ls -la
+
+# Run PHP command
+ddev exec php -v
+
+# Run npm
+ddev exec npm install
+ddev exec npm run build
+
+# Execute command in specific service
+ddev exec -s db mysql --version
+```
+
+## Add-ons & Services
+
+```bash
+# Get additional services (Redis, Elasticsearch, etc.)
+ddev get ddev/ddev-redis
+ddev get ddev/ddev-elasticsearch
+ddev get ddev/ddev-solr
+
+# List available add-ons
+ddev get --list
+
+# Remove add-on
+ddev get --remove ddev/ddev-redis
+```
+
+## Environment & Configuration
+
+```bash
+# Show DDEV version
+ddev version
+
+# Show project info
+ddev describe
+
+# Edit project configuration
+# Edit .ddev/config.yaml manually
+
+# Common config.yaml settings:
+# - php_version: "8.2"
+# - nodejs_version: "18"
+# - webserver_type: nginx-fpm
+# - database: mariadb:10.11
+# - router_http_port: "80"
+# - router_https_port: "443"
+```
+
+## Multiple PHP Versions
+
+```bash
+# Set PHP version
+ddev config --php-version=8.1
+ddev config --php-version=8.2
+ddev config --php-version=8.3
+
+# Apply changes
+ddev restart
+```
+
+## Database Types & Versions
+
+```bash
+# Use MySQL
+ddev config --database=mysql:8.0
+
+# Use MariaDB (default)
+ddev config --database=mariadb:10.11
+
+# Use PostgreSQL
+ddev config --database=postgres:14
+```
+
+## Performance Optimization
+
+```bash
+# Use Mutagen for better file sync performance (Mac)
+ddev config --mutagen-enabled
+
+# Use NFS for better performance (Mac/Linux)
+ddev config --nfs-mount-enabled
+
+# Disable NFS
+ddev config --nfs-mount-enabled=false
+```
+
+## Sharing Your Project
+
+```bash
+# Share project via ngrok (requires ngrok account)
+ddev share
+
+# This creates a public URL for your local site
+```
+
+## Drupal-Specific Workflows
+
+### Fresh Drupal Installation
+```bash
+# Initialize DDEV
+ddev config --project-type=drupal10 --docroot=web
+
+# Start DDEV
+ddev start
+
+# Install Drupal via Composer
+ddev composer create drupal/recommended-project
+
+# Install Drupal
+ddev drush site:install standard --account-name=admin --account-pass=admin
+
+# Launch site
+ddev launch
+```
+
+### Clone Existing Project
+```bash
+# Clone repository
+git clone <repo-url> myproject
+cd myproject
+
+# Start DDEV (uses existing .ddev/config.yaml)
+ddev start
+
+# Install dependencies
+ddev composer install
+
+# Import database
+ddev import-db --src=database.sql.gz
+
+# Import files
+ddev import-files --src=files.tar.gz
+
+# Clear cache
+ddev drush cr
+
+# Launch site
+ddev launch
+```
+
+### Development Workflow
+```bash
+# Start work
+ddev start
+
+# Enable development modules
+ddev drush en devel devel_generate -y
+
+# Watch theme files (if using compile tools)
+ddev exec npm run watch
+
+# Clear cache frequently
+ddev drush cr
+
+# Stop work
+ddev stop
+```
+
+## Troubleshooting
+
+```bash
+# Restart if containers are unresponsive
+ddev restart
+
+# Clean restart (rebuild containers)
+ddev restart --clean
+
+# Remove all Docker volumes and restart
+ddev stop --remove-data
+ddev start
+
+# Check for port conflicts
+ddev describe
+
+# View detailed debug info
+ddev debug test
+
+# Check Docker is running
+docker ps
+
+# Rebuild DDEV containers from scratch
+ddev delete --omit-snapshot
+ddev start
+```
+
+## Common Issues
+
+### Port Conflicts
+If ports 80/443 are in use:
+```bash
+# Change router ports in .ddev/config.yaml
+router_http_port: "8080"
+router_https_port: "8443"
+
+# Then restart
+ddev restart
+```
+
+### Permission Issues
+```bash
+# Fix file permissions
+ddev exec chmod -R 755 web/sites/default/files
+
+# Fix ownership
+ddev exec chown -R www-data:www-data web/sites/default/files
+```
+
+### Database Connection Issues
+Check database credentials in settings.php or settings.ddev.php:
+```php
+$databases['default']['default'] = [
+  'database' => 'db',
+  'username' => 'db',
+  'password' => 'db',
+  'host' => 'db',
+  'port' => '3306',
+  'driver' => 'mysql',
+];
+```
+
+## Best Practices
+
+1. **Always use `ddev` prefix**: Run Composer, Drush, and other tools through DDEV (`ddev composer`, `ddev drush`)
+2. **Commit .ddev/config.yaml**: Share project configuration with team
+3. **Use .gitignore**: Exclude `.ddev/.importdb`, `.ddev/.ddev-docker-compose*`
+4. **Performance**: Enable Mutagen or NFS on Mac for better performance
+5. **Xdebug**: Only enable when needed (slows performance)
+6. **Regular updates**: Keep DDEV updated with `brew upgrade ddev` (Mac) or equivalent
+7. **Clean shutdown**: Use `ddev stop` before system shutdown
+8. **Database snapshots**: Create snapshots before major changes
+9. **Environment variables**: Use `.ddev/config.yaml` for environment-specific settings
+10. **Multiple projects**: Use unique project names to avoid conflicts
+
+## Additional Resources
+
+- Official docs: https://ddev.readthedocs.io/
+- DDEV Discord: https://discord.gg/hCZFfAMc5k
+- DDEV GitHub: https://github.com/ddev/ddev
diff --git a/references/drush.md b/references/drush.md
new file mode 100644
index 0000000..5bed762
--- /dev/null
+++ b/references/drush.md
@@ -0,0 +1,387 @@
+# Drush Commands Reference
+
+Comprehensive Drush command reference for Drupal 8-11+. These commands work with Drush 10, 11, and 12.
+
+## Cache Management
+
+```bash
+# Clear all caches
+drush cache:rebuild
+drush cr
+
+# Clear specific cache bins
+drush cache:clear css-js
+drush cache:clear render
+
+# List all cache bins
+drush cache:bins
+```
+
+## Configuration Management
+
+```bash
+# Export configuration
+drush config:export
+drush cex
+
+# Import configuration
+drush config:import
+drush cim
+
+# Get configuration value
+drush config:get system.site name
+drush cget system.site name
+
+# Set configuration value
+drush config:set system.site name "My Site"
+drush cset system.site name "My Site"
+
+# Edit configuration in editor
+drush config:edit system.site
+
+# Delete configuration
+drush config:delete mymodule.settings
+
+# List all configuration
+drush config:list
+```
+
+## Module Management
+
+```bash
+# Enable module
+drush pm:enable mymodule
+drush en mymodule
+
+# Uninstall module
+drush pm:uninstall mymodule
+drush pmu mymodule
+
+# List all modules
+drush pm:list
+drush pml
+
+# List enabled modules only
+drush pm:list --status=enabled
+
+# Download module from drupal.org
+drush pm:download webform
+drush dl webform
+```
+
+## Database Operations
+
+```bash
+# Update database (run update hooks)
+drush updatedb
+drush updb
+
+# Execute SQL query
+drush sql:query "SELECT * FROM users WHERE uid=1"
+drush sqlq "SELECT * FROM users WHERE uid=1"
+
+# Connect to database CLI
+drush sql:cli
+drush sqlc
+
+# Dump database to file
+drush sql:dump > backup.sql
+drush sql:dump --gzip > backup.sql.gz
+
+# Drop all tables
+drush sql:drop
+
+# Sanitize database (for dev environments)
+drush sql:sanitize
+```
+
+## User Management
+
+```bash
+# Login as user 1
+drush user:login
+drush uli
+
+# Login as specific user
+drush user:login admin
+drush uli admin
+
+# Create user
+drush user:create newuser --mail="user@example.com" --password="password"
+
+# Cancel/delete user
+drush user:cancel username
+
+# Add role to user
+drush user:role:add "administrator" username
+
+# Remove role from user
+drush user:role:remove "administrator" username
+
+# Change user password
+drush user:password admin "newpassword"
+
+# Block user
+drush user:block username
+
+# Unblock user
+drush user:unblock username
+```
+
+## Content Management
+
+```bash
+# Generate test content
+drush devel:generate:content 50 --bundles=article
+
+# Delete content
+drush entity:delete node --bundle=article
+
+# Generate users
+drush devel:generate:users 20
+```
+
+## State Management
+
+```bash
+# Get state value
+drush state:get system.maintenance_mode
+
+# Set state value
+drush state:set system.maintenance_mode 1
+
+# Delete state value
+drush state:delete mymodule.last_run
+```
+
+## Theme Management
+
+```bash
+# List all themes
+drush theme:list
+
+# Enable theme
+drush theme:enable mytheme
+
+# Uninstall theme
+drush theme:uninstall oldtheme
+
+# Set default theme
+drush config:set system.theme default mytheme
+```
+
+## Cron
+
+```bash
+# Run cron
+drush cron
+
+# Run cron for specific module
+drush cron mymodule
+```
+
+## Status & Information
+
+```bash
+# Show site status
+drush status
+drush st
+
+# Show core status and available updates
+drush pm:security
+
+# Show Drupal version
+drush core:status
+
+# Show requirements report
+drush core:requirements
+```
+
+## Development & Debugging
+
+```bash
+# Watch for file changes and clear cache
+drush watchdog:tail
+
+# Show recent log messages
+drush watchdog:show
+
+# Show recent log messages and follow
+drush watchdog:tail
+
+# Evaluate PHP code
+drush php:eval "echo \Drupal::VERSION;"
+drush ev "echo \Drupal::VERSION;"
+
+# Open PHP REPL
+drush php:cli
+```
+
+## Generate Code (Drush Generate)
+
+```bash
+# Generate module
+drush generate module
+
+# Generate controller
+drush generate controller
+
+# Generate form
+drush generate form
+
+# Generate plugin block
+drush generate plugin:block
+
+# Generate service
+drush generate service
+
+# Generate theme
+drush generate theme
+
+# Generate hook implementation
+drush generate hook
+
+# Generate event subscriber
+drush generate event-subscriber
+
+# List all generators
+drush generate --help
+```
+
+## Field Management
+
+```bash
+# Create field
+drush field:create node.article.field_custom
+
+# Delete field
+drush field:delete node.article.field_custom
+
+# List fields
+drush field:list
+```
+
+## Locale/Translation
+
+```bash
+# Import translations
+drush locale:import de
+
+# Update translations
+drush locale:update
+
+# Check translation status
+drush locale:check
+```
+
+## Queue Management
+
+```bash
+# Run specific queue
+drush queue:run mymodule_queue
+
+# List all queues
+drush queue:list
+
+# Delete items from queue
+drush queue:delete mymodule_queue
+```
+
+## Deployment Commands
+
+```bash
+# Standard deployment workflow
+drush updatedb -y
+drush config:import -y
+drush cache:rebuild
+
+# One-liner deployment
+drush updb -y && drush cim -y && drush cr
+```
+
+## Site Installation
+
+```bash
+# Install Drupal site
+drush site:install standard --db-url=mysql://user:pass@localhost/dbname --account-name=admin --account-pass=admin
+
+# Install with configuration
+drush site:install --existing-config
+```
+
+## Alias Usage
+
+Drush aliases allow running commands on remote sites.
+
+```bash
+# Run command on remote site
+drush @production cache:rebuild
+
+# Sync database from remote to local
+drush sql:sync @production @self
+
+# Sync files from remote to local
+drush rsync @production:%files @self:%files
+```
+
+## Useful Flags
+
+```bash
+# -y: Assume "yes" to all prompts
+drush en mymodule -y
+
+# -v: Verbose output
+drush cache:rebuild -v
+
+# --uri: Specify site URI (multisite)
+drush --uri=example.com cache:rebuild
+
+# --root: Specify Drupal root directory
+drush --root=/var/www/html cache:rebuild
+
+# --debug: Show debug information
+drush --debug cache:rebuild
+```
+
+## Custom Drush Commands
+
+Create custom Drush commands by implementing Drush command files in your module:
+
+**mymodule/src/Commands/MyModuleCommands.php**
+```php
+<?php
+
+namespace Drupal\mymodule\Commands;
+
+use Drush\Commands\DrushCommands;
+
+/**
+ * Custom Drush commands for mymodule.
+ */
+class MyModuleCommands extends DrushCommands {
+
+  /**
+   * Performs a custom operation.
+   *
+   * @command mymodule:custom-operation
+   * @aliases mco
+   * @usage mymodule:custom-operation
+   *   Runs the custom operation.
+   */
+  public function customOperation() {
+    $this->output()->writeln('Running custom operation...');
+    // Your custom logic here
+    $this->logger()->success('Operation completed successfully!');
+  }
+
+}
+```
+
+## Best Practices
+
+1. **Aliases**: Create aliases in `drush/sites/` for easier multi-site management
+2. **Automation**: Use Drush commands in deployment scripts
+3. **Backup**: Always backup before running destructive commands
+4. **Testing**: Test Drush scripts in development before production
+5. **Version**: Check Drush version compatibility with `drush --version`
+6. **Performance**: Use `drush status` to verify environment configuration