# ⚠️ CRITICAL: WordPress Plugin Text Domain & Naming Standards

**Plugin:** Wisewand AI Content Writer & SEO Content Generator  
**Mandatory Text Domain:** `wisewand-ai-content-writer-seo-content-generator`

---

## 🚨 CRITICAL RULE - NEVER VIOLATE

### Text Domain Must Be Consistent Everywhere

**The text domain MUST be:** `wisewand-ai-content-writer-seo-content-generator`

This MUST match in:
1. ✅ Plugin main file header (`wisewand-plugin.php`)
2. ✅ `readme.txt` metadata
3. ✅ All `__()`, `_e()`, `esc_html__()`, etc. translation functions
4. ✅ **Production ZIP file name** ← CRITICAL

---

## 📦 PRODUCTION ZIP FILE NAMING

### ✅ CORRECT:
```bash
wisewand-ai-content-writer-seo-content-generator.zip
```

### ❌ WRONG:
```bash
wisewand-plugin-v1.6.0-production.zip  # NEVER USE VERSION IN ZIP NAME
wisewand-plugin.zip                     # TOO SHORT
wisewand.zip                            # MISSING FULL SLUG
wisewand-production.zip                 # MISSING FULL SLUG
```

---

## 🎯 WHY THIS MATTERS

### WordPress Plugin Checker Validation:
WordPress Plugin Checker validates that:
- The **zip file name** matches the **text domain**
- All translation functions use the correct text domain
- The text domain in the main plugin file is consistent

### If Mismatched:
```
ERROR: WordPress.WP.I18n.TextDomainMismatch
Expected 'wisewand-plugin-v1.6.0-production' but got 'wisewand-ai-content-writer-seo-content-generator'
```

This error occurs because:
1. WordPress extracts the expected text domain from the **ZIP FILE NAME**
2. Then compares it against the text domain in translation functions
3. **Mismatch = ERROR**

---

## ✅ CORRECT ZIP CREATION COMMAND

```bash
# ALWAYS use this command for production zips:
zip -r wisewand-ai-content-writer-seo-content-generator.zip . \
  -x "*.git*" \
  -x "node_modules/*" \
  -x "tests/*" \
  -x ".agent/*" \
  -x ".DS_Store" \
  -x "*.md" \
  -x "docs/*"
```

**Key Points:**
- ✅ Zip file name = text domain EXACTLY
- ✅ No version numbers in zip name
- ✅ No "production" suffix
- ✅ Just the slug/text-domain.zip

---

## 📝 VERIFICATION CHECKLIST

Before creating ANY production zip:

1. [ ] Check main plugin file:
   ```php
   * Text Domain: wisewand-ai-content-writer-seo-content-generator
   ```

2. [ ] Check all translation functions use:
   ```php
   __( 'Text', 'wisewand-ai-content-writer-seo-content-generator' )
   _e( 'Text', 'wisewand-ai-content-writer-seo-content-generator' )
   esc_html__( 'Text', 'wisewand-ai-content-writer-seo-content-generator' )
   ```

3. [ ] Zip file name MUST be:
   ```bash
   wisewand-ai-content-writer-seo-content-generator.zip
   ```

4. [ ] Run Plugin Checker:
   ```bash
   # Should show NO text domain mismatch errors
   ```

---

## 🤖 AI AGENT INSTRUCTIONS

**CRITICAL RULES FOR ALL FUTURE RELEASES:**

### Rule 1: NEVER Change Text Domain
The text domain `wisewand-ai-content-writer-seo-content-generator` is PERMANENT.
- ❌ NEVER shorten it
- ❌ NEVER add version numbers to it
- ❌ NEVER use alternative names
- ✅ ALWAYS use exactly: `wisewand-ai-content-writer-seo-content-generator`

### Rule 2: Production Zip Naming
When creating production zips, ALWAYS use:
```bash
zip -r wisewand-ai-content-writer-seo-content-generator.zip .
```

**NEVER use:**
- ❌ Version numbers in zip name
- ❌ "production" suffix
- ❌ "plugin" word
- ❌ Abbreviated names

### Rule 3: Pre-Release Verification
Before EVERY release:
1. Verify text domain in `wisewand-plugin.php` header
2. Verify zip file name matches text domain EXACTLY
3. Run grep to check all translation functions:
   ```bash
   grep -r "__(\\|_e(\\|esc_html__(" includes/ | grep -v "wisewand-ai-content-writer-seo-content-generator"
   # Should return NOTHING
   ```

### Rule 4: Update Deployment Workflow
The `.agent/workflows/deploy.md` should ALWAYS reference:
```bash
zip -r wisewand-ai-content-writer-seo-content-generator.zip .
```

---

## 🔍 COMMON MISTAKES TO AVOID

### Mistake 1: Using Project Directory Name
```bash
❌ cd /path/to/wisewand
❌ zip -r wisewand.zip .
    # WRONG! Should be: wisewand-ai-content-writer-seo-content-generator.zip
```

### Mistake 2: Adding Version to Zip Name
```bash
❌ zip -r wisewand-ai-content-writer-seo-content-generator-v1.6.1.zip .
    # WRONG! No version in zip name
```

### Mistake 3: Using "Production" Suffix
```bash
❌ zip -r wisewand-ai-content-writer-seo-content-generator-production.zip .
    # WRONG! No suffix
```

### ✅ Correct: Exact Text Domain
```bash
✅ zip -r wisewand-ai-content-writer-seo-content-generator.zip .
    # CORRECT! Matches text domain exactly
```

---

## 📋 RELEASE PROCESS CHECKLIST

Every release MUST follow these steps:

### 1. Version Bump
```bash
# Update version in wisewand-plugin.php
Version: X.Y.Z

# Update version in readme.txt
Stable tag: X.Y.Z

# Add changelog entry
```

### 2. Text Domain Verification
```bash
# Verify main file
grep "Text Domain:" wisewand-plugin.php
# Must show: wisewand-ai-content-writer-seo-content-generator

# Verify all translation functions
grep -r "__(" includes/ | grep -v "wisewand-ai-content-writer-seo-content-generator"
# Should return NOTHING
```

### 3. Create Production Zip
```bash
# ALWAYS use this EXACT command:
zip -r wisewand-ai-content-writer-seo-content-generator.zip . \
  -x "*.git*" \
  -x "node_modules/*" \
  -x "tests/*" \
  -x ".agent/*" \
  -x ".DS_Store" \
  -x "*.md" \
  -x "docs/*"
```

### 4. Verification
```bash
# Verify zip name
ls -lh wisewand-ai-content-writer-seo-content-generator.zip

# Extract and run Plugin Checker
unzip wisewand-ai-content-writer-seo-content-generator.zip -d /tmp/test
# Run Plugin Checker on /tmp/test
# Should show NO TextDomainMismatch errors
```

---

## 🛠️ FIXING TEXT DOMAIN MISMATCH

If you encounter this error:

```
ERROR: WordPress.WP.I18n.TextDomainMismatch
Expected 'wrong-name' but got 'wisewand-ai-content-writer-seo-content-generator'
```

### Solution:
1. **Delete the incorrectly named zip:**
   ```bash
   rm wrong-name.zip
   ```

2. **Create correctly named zip:**
   ```bash
   zip -r wisewand-ai-content-writer-seo-content-generator.zip .
   ```

3. **Bump patch version** (to invalidate bad release)

4. **Re-verify** with Plugin Checker

---

## 📚 REFERENCES

- **WordPress Plugin Handbook:** https://developer.wordpress.org/plugins/internationalization/
- **Text Domain Best Practices:** Must match plugin slug
- **Slug Definition:** Same as directory name when installed
- **Our Slug:** `wisewand-ai-content-writer-seo-content-generator`

---

## ✅ QUICK REFERENCE

```bash
# OUR PERMANENT TEXT DOMAIN:
wisewand-ai-content-writer-seo-content-generator

# PRODUCTION ZIP NAME (ALWAYS):
wisewand-ai-content-writer-seo-content-generator.zip

# ZIP CREATION COMMAND:
zip -r wisewand-ai-content-writer-seo-content-generator.zip . \
  -x "*.git*" -x "node_modules/*" -x "tests/*" \
  -x ".agent/*" -x ".DS_Store" -x "*.md" -x "docs/*"
```

---

**Last Updated:** 2025-11-24  
**Status:** MANDATORY - Must follow for ALL releases  
**Agent Compliance:** Required for AI agent assistance
