# Email Template Footer Update Guide for Claude

## Project Context

This repository manages 700+ email templates for StartEngine's marketing system. Templates use Thymeleaf syntax and are uploaded via admin UI at https://stg-marketing.startengine.com/admin.

## File Naming Convention

**IMPORTANT:** Only modify files with underscores!

- `template_name.html` - Main source file (readable, formatted) ✅ MODIFY
- `template_name_minify.html` - Minified production version ✅ MODIFY
- `template_name.txt` - Plain text version ✅ MODIFY
- `Template Name.html` - OLD Klaviyo file ❌ DO NOT MODIFY
- `subject.txt` - Email subject ✅ CAN MODIFY

## Available Scripts

### Update Footer Text

```bash
node scripts/update-footer-text.js [--dry-run]
```

- Updates legal disclaimer text across all templates
- Pure text replacement, no HTML structure changes
- Handles variable whitespace (line breaks, spaces)
- Safe to run on all files

### Update Minified Files

```bash
node scripts/update-minify-proper.js [--dry-run]
```

- Regenerates all `*_minify.html` files from source
- Uses html-minifier via npx (no permanent install)
- Matches settings from https://kangax.github.io/html-minifier/
- 60-85% size reduction

### Compare Footers

```bash
node scripts/compare-footers.js [--detailed]
```

- Shows which templates have old vs new footer text
- Useful for verification after updates

## Current Footer Update Requirements

**OLD TEXT (to replace):**

```
StartEngine Primary LLC may provide recommendations to you in certain instances; however we will not provide you with personalized advice based on your portfolio as to whether you should make or continue to hold a particular investment or as to which type of investments may be better suited for you
```

**NEW TEXT:**

```
StartEngine Primary LLC may provide recommendations to you in certain instances. Recommendations may be general or, in some cases, tailored to information you provide. When we provide a tailored recommendation to a retail customer, we act in your best interest at the time of the recommendation and make the disclosures required by applicable regulations (including Regulation Best Interest). We do not monitor your portfolio or provide ongoing advice. We and our affiliates may receive fees or other compensation if you invest. You should independently evaluate any investment and consult your own legal, tax, and financial advisers
```

## Complete Footer Update Workflow

### Step 1: Test on One Folder

```bash
# Test on account-opened-user-svc folder first
cd account-opened-user-svc/account-sign-up
grep -c "however we will not provide" account_sign_up.html  # Check has old text
# Then run updates...
```

### Step 2: Update All Footer Text

```bash
node scripts/update-footer-text.js
```

Expected: ~711 files updated

### Step 3: Regenerate Minified Files

```bash
node scripts/update-minify-proper.js
```

Expected: ~171-180 files updated (some may fail due to spaces in folder names)

### Step 4: Verify

```bash
# Check only template files changed
git status --short | grep -E "\.html|\.txt" | wc -l

# Verify no old text remains
grep -r "however we will not provide" --include="*_*.html" . | wc -l

# Should be 0 (or just shared/footer.txt)
```

### Step 5: Review & Commit

```bash
# Open a few templates in browser to verify
open account-opened-user-svc/account-sign-up/account_sign_up.html

# If looks good, commit
git add .
git commit -m "Update footer legal language per compliance requirements"
```

## Common Issues

### Issue: Spaces in Folder Names

**Problem:** Folders like "StartEngine IRA Investment Submitted" break shell commands  
**Solution:** These 9 files can be manually minified using https://kangax.github.io/html-minifier/ or we can quote the paths properly

### Issue: Minified Files Getting Updated

**Problem:** Regular `.html` files getting minified in place  
**Solution:** Use `update-minify-proper.js` which ONLY updates `*_minify.html` files

### Issue: node_modules Clutter

**Problem:** npm install creates 200+ files  
**Solution:** Use `npx --yes` for temporary package usage, or add to .gitignore

### Issue: File Already Minified

**Problem:** Some `*.html` files were committed minified  
**Solution:** Restore from git history:

```bash
git show f18af06:path/to/file.html > path/to/file.html
```

## Shared Footer System (Future Use)

The `shared/` folder contains universal footer templates:

- `shared/footer.html` - Complex table-based footer (from campaign-opportunity template)
- `shared/footer.txt` - Plain text footer

To use:

1. Add `<!-- START FOOTER (editable) -->` and `<!-- END FOOTER -->` markers to templates
2. Run `node scripts/inject-shared-footer.js`

**Note:** Not currently used due to varying template structures. Manual updates are safer.

## Important Template Details

### Email HTML Structure

- Uses table-based layouts (not div/flexbox) for email client compatibility
- Has separate desktop and mobile versions (conditional rendering)
- Contains IE conditional comments (`<!--[if mso]>`) - must preserve
- Thymeleaf template variables throughout

### Template Variables

- `[(${current_year} ?: '')]` - Current year
- `[(${organization.name} ?: '')]` - Organization name
- `[(${organization.full_address} ?: '')]` - Organization address
- `${event.payload.get('key')}` or `${event.payload['KEY']}` - Dynamic content

### Upload Process

Templates must be uploaded through admin UI:

1. Log into https://stg-marketing.startengine.com/admin
2. Navigate to Email Templates
3. Find template by name
4. Click Update
5. Paste HTML/TXT content
6. Save

**No bulk upload available yet** - folder names don't perfectly match database template names.

## Git Workflow

### Before Making Changes

```bash
git status  # Ensure clean state
git pull    # Get latest
```

### After Updates

```bash
# Check what changed
git status --short | grep -E "\.html|\.txt"

# Review changes
git diff path/to/file.html | head -50

# Commit only template files
git add *.html *.txt shared/ scripts/
git commit -m "Update footer legal language"
```

### .gitignore

Should contain:

```
node_modules/
.DS_Store
package-lock.json
*.temp
```

## Scripts Reference

All scripts support `--dry-run` for safe testing.

| Script                    | Purpose                   | Files Affected            |
| ------------------------- | ------------------------- | ------------------------- |
| `update-footer-text.js`   | Replace footer legal text | All `*_*.html`, `*_*.txt` |
| `update-minify-proper.js` | Regenerate minified files | Only `*_minify.html`      |
| `compare-footers.js`      | Check old vs new text     | None (read-only)          |
| `inject-shared-footer.js` | Inject from shared/       | Templates with markers    |
| `normalize-footers.js`    | Fix URLs only             | All templates             |

## Testing Checklist

Before committing footer updates:

- [ ] Test on one folder first
- [ ] Verify regular files are still readable (not minified)
- [ ] Verify minify files are compressed
- [ ] Open in browser - check layout not broken
- [ ] Check footer has new text
- [ ] Verify git status shows only template files
- [ ] No node_modules in git status

## Support

For questions about:

- **Footer content changes** - Check with compliance team
- **Template structure** - Review existing templates in repo
- **Upload process** - Check admin UI documentation
- **Script issues** - Review script code and error messages