fraim-framework 2.0.30 → 2.0.33

package/registry/workflows/customer-development/weekly-newsletter.md

@@ -1,362 +1,366 @@
-# Weekly Newsletter Workflow
-
-## INTENT
-To generate and distribute a compelling weekly newsletter that showcases the AI Agent's amazing new features and improvements, creating excitement among current users and FOMO for subscribers who haven't joined yet.
-
-## PRINCIPLES
-- **Value-Focused**: Highlight features and improvements that deliver real value to users
-- **User-Facing Only**: Do NOT include internal features (admin dashboards, monitoring, backups, devops)
-- **Authentic Testimonials**: Only use real testimonials from actual users - NO fake quotes
-- **FOMO-Inducing**: Create urgency and excitement about missing out
-- **Visually Stunning**: Beautiful design that catches the eye
-- **Concise**: Scannable format with clear sections
-- **AI Creativity**: AI agent makes all editorial decisions - what's a feature vs bug, what's worth highlighting
-
-## WORKFLOW TRIGGER
-**User triggers this workflow manually**:
-- Weekly, typically Monday morning
-- User says: "Generate this week's newsletter" or similar
-
-## AI AGENT PROCESS
-
-### Step 1: Issue Retrieval
-**AI Agent calls function**:
-```typescript
-// 1. Fetch the helper script
-const scriptContent = await get_fraim_file({ path: "scripts/newsletter-helpers.ts" });
-
-// 2. Save it to a temporary file (e.g. machine temp dir)
-const os = require('os');
-const path = require('path');
-const tempScriptPath = path.join(os.tmpdir(), 'newsletter-helpers.ts');
-const fs = require('fs');
-fs.writeFileSync(tempScriptPath, scriptContent);
-
-// 3. Import from the temporary file
-const { getResolvedIssuesForNewsletter } = await import(tempScriptPath);
-
-// 4. Use the function
-const resolvedIssues = await getResolvedIssuesForNewsletter(); 
-```
-
-**Note**: The `getResolvedIssuesForNewsletter()` function automatically:
-- Finds the most recent newsletter date from existing files
-- Uses that date as the starting point to fetch issues resolved AFTER that date
-- If no newsletter files exist, falls back to last 7 days
-- Returns ALL closed issues - AI agent decides what to include
-
-### Step 2: Intelligent Categorization & Filtering
-**AI Agent does creative analysis**:
-
-1. **Go through each resolved issue** and make editorial decisions:
-   - Is this user-facing or internal?
-   - Is this a feature, improvement, or bug fix?
-   - Is this worth highlighting to users?
-   - How should this be described to non-technical users?
-
-2. **Filter out internal-only issues**:
-   - Admin dashboards, monitoring, analytics (internal tools)
-   - Database backups, devops improvements
-   - CI/CD, deployment automation
-   - Developer tools, debugging features
-   - Documentation updates, dependency updates
-   - **API route fixes, endpoint refactoring, code structure changes**
-   - **Environment variable updates, configuration file changes**
-   - **Developer setup improvements, build process updates**
-   - **Internal bug fixes that don't impact user experience**
-   - Any change without user-facing impact
-
-3. **Categorize remaining issues**:
-   - **Features**: Adds NEW capability users didn't have before
-   - **Improvements**: Makes existing functionality better/faster/easier
-   - **Bug Fixes**: Fixes something that was broken
-
-4. **Select hero feature** (optional):
-   - Pick the MOST impactful feature or improvement
-   - Must have clear user value and ideally a quantifiable impact statement
-
-### Step 3: Write Compelling Content
-**AI Agent writes newsletter content** - be creative, exciting, and user-focused!
-
-**Guidelines**:
-- **NO TECHNICAL JARGON**: Don't mention internal systems, code, or technical details
-- **USER VALUE FOCUS**: Describe what the user can now do, not how it works
-- **ACTIVE, EXCITING LANGUAGE**: "You can now...", "The AI Agent now automatically...", "Your calendar finally..."
-- **QUANTIFY IMPACT**: "85% reduction in...", "5 hours saved per week", "3x faster"
-- **CREATE FOMO**: "Current users are already...", "Join 500+ executives who..."
-
-**For each item, write**:
-- **Title**: Short, benefit-focused (e.g., "Smart Timezone Detection" not "Implement timezone handling")
-- **Description**: What the user can do now, why it matters (2-3 sentences)
-- **Impact** (optional): Quantified benefit or user testimonial
-
-**Example**:
-```json
-{
-  "title": "Work Hours & Focus Blocks on Your Calendar",
-  "description": "Your work hours and focus blocks now automatically appear as visual blocks on your calendar! No more scheduling conflicts during your protected time. The AI creates beautiful calendar events that sync across all your devices, making it crystal clear when you're available and when you're in deep work mode.",
-  "impact": "Users report 85% reduction in meeting conflicts during focus time. Your calendar finally shows the complete picture of your day!"
-}
-```
-
-### Step 4: Generate Newsletter JSON
-**AI Agent creates ONE file**:
-- File: `docs/customer-development/newsletters/newsletter-YYYY-MM-DD.json`
-- Format: Structured JSON for deterministic rendering
-- Contains ALL content ready for user review
-
-**File format** (JSON):
-```json
-{
-  "metadata": {
-    "generatedOn": "2025-11-01T00:00:00.000Z",
-    "weekStart": "2025-10-25",
-    "weekEnd": "2025-11-01",
-    ...
-  },
-  "content": {
-    "weekTitle": "Work Hours & Focus Blocks Now on Your Calendar! 🎯",
-    "weekSubtitle": "8 powerful updates that supercharge your productivity",
-    "weekDate": "Oct 25 - Nov 1, 2025",
-    "openingMessage": "This week has been HUGE! We've shipped game-changing features that make the AI Agent even more powerful at protecting your time and managing your schedule. Current users are already saving hours every week - here's what you've been missing! 🚀",
-    "heroFeature": { ... },
-    "newFeatures": [ ... ],
-    "improvements": [ ... ],
-    "bugFixes": [ ... ],
-    "testimonial": {
-      "text": "The AI saved me 5 hours this week just by protecting my focus blocks...",
-      "author": "Sid Mathur",
-      "role": "Founder"
-    },
-    "comingNext": "Next week: Voice commands for calendar management, smart meeting summaries...",
-    "ctaLink": "https://example.com/wellness/ai-agent",
-    "ctaText": "Start Your Free Trial"
-  }
-}
-```
-
-### Step 5: Generate HTML
-// 1. Fetch helper script and save to temp (if not already done)
-// const scriptContent = await get_fraim_file({ path: "scripts/newsletter-helpers.ts" });
-// ... (save to tempScriptPath) ...
-const { saveNewsletter } = await import(tempScriptPath);
-
-// 2. Save newsletter JSON and generate HTML
-const savedPath = saveNewsletter(newsletter);
-```
-
-**This function will**:
-- Save the JSON file
-- Generate beautiful HTML from the template
-- Save the HTML file
-- Return path to JSON file
-
-### Step 6: User Review
-**AI Agent**:
-1. **Points user to the generated file**: `docs/customer-development/newsletters/newsletter-YYYY-MM-DD.json`
-2. **Shows preview**: Points to HTML file for browser preview
-3. **Requests review** and any edits needed (user can edit JSON directly)
-4. **Waits for user approval** before proceeding
-
-**Note**: User can:
-- Edit titles to be more compelling
-- Add/remove items
-- Adjust descriptions
-- Add real testimonials (verify authenticity!)
-- Add "coming next" teaser
-
-### Step 7: Send Newsletter (Separate Command)
-**When user says "Send the newsletter" or similar**:
-
-**User runs deterministic script**:
-```bash
-npm run send-newsletter
-```
-
-// 1. Fetch helper script and save to temp (if not already done)
-// ...
-const { sendNewsletterToExecutives } = await import(tempScriptPath);
-
-// 2. Send newsletter to all active executives
-await sendNewsletterToExecutives('docs/customer-development/newsletters/newsletter-2025-11-01.json');
-```
-
-**This function will**:
-- Load the approved newsletter JSON
-- Get all active executives from database
-- For each executive:
-  - Get their AI Agent email address
-  - Get their OAuth tokens
-  - Send personalized newsletter from their AI identity
-- Log results and exit
-
-## NEWSLETTER STRUCTURE
-
-### Hero Section
-- **Week Title**: Catchy title based on hero feature or main theme
-- **Subtitle**: Count of updates
-- **Stats Banner**: Features | Improvements | Bug Fixes counters
-
-### Content Sections
-1. **Opening Message**: Exciting intro about what shipped (AI agent writes this)
-2. **Hero Feature** (optional): Spotlights the most impactful change with red "HERO FEATURE" badge
-3. **New Capabilities**: Major new features added
-4. **Major Improvements**: Significant enhancements
-5. **Fixes & Polish**: Bug fixes and minor improvements
-6. **Testimonial** (optional): Real user quote about impact (VERIFY AUTHENTICITY)
-7. **Coming Next** (optional): Preview of upcoming features
-
-### Call-to-Actions
-- **FOMO CTA**: "Don't Miss Out!" with signup link
-- **Feedback CTA**: Link to ChatGPT interface
-
-## EDITORIAL GUIDELINES
-
-### What to Include ✅
-- New features that add capability for users
-- Improvements that save time or improve UX
-- Bug fixes that had user impact
-- Real user testimonials (ONLY - verify authenticity)
-- Quantified benefits (time saved, conflicts reduced, etc.)
-
-### What to Exclude ❌
-- Internal infrastructure changes
-- **Admin dashboards, monitoring, analytics (internal-only)**
-- **Backups, database operations, devops**
-- **API route fixes, duplicate endpoint resolution**
-- **Environment configuration, .env file updates**
-- **Developer setup scripts, build configuration**
-- CI/CD improvements
-- Documentation updates
-- Dependency updates
-- Technical debt cleanup
-- Developer tools and debugging features
-- **Internal bug fixes (code structure, not user experience)**
-- Issues without user-facing impact
-- **FAKE TESTIMONIALS - authenticity is critical**
-
-**Rule of thumb**: If the user wouldn't notice the change in their daily use of the AI Assistant, don't include it.
-
-### Writing Style
-
-**Titles:**
-- Short, punchy, benefit-focused
-- ❌ "Implement timezone handling in calendar service"
-- ✅ "Smart Timezone Detection"
-
-**Descriptions:**
-- Start with the benefit to the user
-- Use "you" and "your" to make it personal
-- Be specific about what changed
-- ❌ "Fixed bug where calendar events weren't syncing correctly"
-- ✅ "Your calendar now stays perfectly in sync across all devices, no more mysterious missing meetings!"
-
-**Impact Statements:**
-- Quantify whenever possible
-- Include real user feedback
-- ❌ "Improved performance"
-- ✅ "Calendar loads 3x faster, getting you to your day in seconds instead of minutes"
-
-### Creating FOMO
-
-- **Quantify Success**: "500+ executives already using this feature"
-- **Show Savings**: "Don't miss out on 5 hours saved per week"
-- **Create Urgency**: "Limited spots available"
-- **Social Proof**: Real testimonials, growth stats, company names (with permission)
-
-## EXAMPLES
-
-### Example 1: Feature-Rich Week
-```
-User: "Generate this week's newsletter"
-
-AI Agent:
-1. Calls getResolvedIssuesForNewsletter() → gets 15 issues
-2. Analyzes each issue:
-   - 3 user-facing features
-   - 5 improvements
-   - 2 bugs
-   - 5 internal/devops (FILTERED OUT)
-3. Writes compelling content for each item
-4. Selects "Voice Commands for Calendar" as hero feature
-5. Writes exciting opening: "This week has been HUGE!..."
-6. Creates newsletter JSON with all content
-7. Calls saveNewsletter() → generates HTML
-8. Shows preview: "Newsletter ready! docs/customer-development/newsletters/newsletter-2025-11-01.html"
-
-User: "Looks great, send it"
-
-AI Agent or User:
-Runs: npm run send-newsletter
-OR
-Calls: sendNewsletterToExecutives('newsletter-2025-11-01.json')
-```
-
-### Example 2: User Adds Testimonial
-```
-User: "Generate newsletter"
-
-AI Agent:
-[Creates newsletter with 5 improvements, no testimonial]
-
-User: "Add a testimonial from me - I saved 5 hours this week thanks to focus blocks"
-
-AI Agent:
-[Edits JSON to add testimonial with user's name]
-[Regenerates HTML]
-Shows: "Updated! Ready to send?"
-
-User: "Yes, send it"
-
-User runs: npm run send-newsletter
-```
-
-## TIPS FOR COMPELLING NEWSLETTERS
-
-### Highlight User Value
-- Focus on what users can DO, not how it works
-- "You can now..." not "We implemented..."
-- "Your calendar automatically..." not "The system now..."
-
-### Use Concrete Examples
-- "Schedule meetings in seconds" not "Faster scheduling"
-- "85% fewer conflicts" not "Better conflict detection"
-- "Save 5 hours per week" not "More efficient"
-
-### Create Narrative
-- Opening: "This week has been incredible!"
-- Hero feature: Build excitement around main change
-- Coming next: Build anticipation for next week
-
-### Make it Scannable
-- Short paragraphs (2-3 sentences max)
-- Clear section headers
-- Visual hierarchy with emojis and formatting
-- Impact callouts that stand out
-
-## QUALITY CHECKLIST
-
-Before approving newsletter, verify:
-- [ ] All items are user-facing (no internal/devops features)
-- [ ] Testimonials are real and verified
-- [ ] Impact statements are accurate and quantified
-- [ ] Descriptions focus on user value, not implementation
-- [ ] Opening message is exciting and FOMO-inducing
-- [ ] Links are correct (Azure signup URL)
-- [ ] No mention of API credits or costs (the service is free)
-- [ ] Grammar and spelling are perfect
-- [ ] Preview HTML looks beautiful in browser
-
-## FREQUENCY
-
-**Recommended**: Weekly, sent Monday morning
-- Catches people starting their week
-- Fresh in mind for decision-making
-- Consistent schedule builds anticipation
-
-**Alternative**: Bi-weekly if weekly feels too frequent
-
-**Special editions**: 
-- Major feature launches
-- Milestone celebrations (e.g., "100 users!")
-- Holiday/end-of-year roundups
+# Weekly Newsletter Workflow
+
+## INTENT
+To generate and distribute a compelling weekly newsletter that showcases the AI Agent's amazing new features and improvements, creating excitement among current users and FOMO for subscribers who haven't joined yet.
+
+## PRINCIPLES
+- **Value-Focused**: Highlight features and improvements that deliver real value to users
+- **User-Facing Only**: Do NOT include internal features (admin dashboards, monitoring, backups, devops)
+- **Authentic Testimonials**: Only use real testimonials from actual users - NO fake quotes
+- **FOMO-Inducing**: Create urgency and excitement about missing out
+- **Visually Stunning**: Beautiful design that catches the eye
+- **Concise**: Scannable format with clear sections
+- **AI Creativity**: AI agent makes all editorial decisions - what's a feature vs bug, what's worth highlighting
+
+## WORKFLOW TRIGGER
+**User triggers this workflow manually**:
+- Weekly, typically Monday morning
+- User says: "Generate this week's newsletter" or similar
+
+## AI AGENT PROCESS
+
+### Step 1: Issue Retrieval
+**AI Agent calls function**:
+```typescript
+// Import newsletter helper functions directly from synced location
+const os = require('os');
+const path = require('path');
+
+const scriptsDir = path.join(os.homedir(), '.fraim', 'scripts');
+const scriptPath = path.join(scriptsDir, 'newsletter-helpers.ts');
+
+// Import from the synced script
+const { getResolvedIssuesForNewsletter } = await import(scriptPath);
+
+// Use the function
+const resolvedIssues = await getResolvedIssuesForNewsletter(); 
+```
+
+**Note**: The `getResolvedIssuesForNewsletter()` function automatically:
+- Finds the most recent newsletter date from existing files
+- Uses that date as the starting point to fetch issues resolved AFTER that date
+- If no newsletter files exist, falls back to last 7 days
+- Returns ALL closed issues - AI agent decides what to include
+
+### Step 2: Intelligent Categorization & Filtering
+**AI Agent does creative analysis**:
+
+1. **Go through each resolved issue** and make editorial decisions:
+   - Is this user-facing or internal?
+   - Is this a feature, improvement, or bug fix?
+   - Is this worth highlighting to users?
+   - How should this be described to non-technical users?
+
+2. **Filter out internal-only issues**:
+   - Admin dashboards, monitoring, analytics (internal tools)
+   - Database backups, devops improvements
+   - CI/CD, deployment automation
+   - Developer tools, debugging features
+   - Documentation updates, dependency updates
+   - **API route fixes, endpoint refactoring, code structure changes**
+   - **Environment variable updates, configuration file changes**
+   - **Developer setup improvements, build process updates**
+   - **Internal bug fixes that don't impact user experience**
+   - Any change without user-facing impact
+
+3. **Categorize remaining issues**:
+   - **Features**: Adds NEW capability users didn't have before
+   - **Improvements**: Makes existing functionality better/faster/easier
+   - **Bug Fixes**: Fixes something that was broken
+
+4. **Select hero feature** (optional):
+   - Pick the MOST impactful feature or improvement
+   - Must have clear user value and ideally a quantifiable impact statement
+
+### Step 3: Write Compelling Content
+**AI Agent writes newsletter content** - be creative, exciting, and user-focused!
+
+**Guidelines**:
+- **NO TECHNICAL JARGON**: Don't mention internal systems, code, or technical details
+- **USER VALUE FOCUS**: Describe what the user can now do, not how it works
+- **ACTIVE, EXCITING LANGUAGE**: "You can now...", "The AI Agent now automatically...", "Your calendar finally..."
+- **QUANTIFY IMPACT**: "85% reduction in...", "5 hours saved per week", "3x faster"
+- **CREATE FOMO**: "Current users are already...", "Join 500+ executives who..."
+
+**For each item, write**:
+- **Title**: Short, benefit-focused (e.g., "Smart Timezone Detection" not "Implement timezone handling")
+- **Description**: What the user can do now, why it matters (2-3 sentences)
+- **Impact** (optional): Quantified benefit or user testimonial
+
+**Example**:
+```json
+{
+  "title": "Work Hours & Focus Blocks on Your Calendar",
+  "description": "Your work hours and focus blocks now automatically appear as visual blocks on your calendar! No more scheduling conflicts during your protected time. The AI creates beautiful calendar events that sync across all your devices, making it crystal clear when you're available and when you're in deep work mode.",
+  "impact": "Users report 85% reduction in meeting conflicts during focus time. Your calendar finally shows the complete picture of your day!"
+}
+```
+
+### Step 4: Generate Newsletter JSON
+**AI Agent creates ONE file**:
+- File: `docs/customer-development/newsletters/newsletter-YYYY-MM-DD.json`
+- Format: Structured JSON for deterministic rendering
+- Contains ALL content ready for user review
+
+**File format** (JSON):
+```json
+{
+  "metadata": {
+    "generatedOn": "2025-11-01T00:00:00.000Z",
+    "weekStart": "2025-10-25",
+    "weekEnd": "2025-11-01",
+    ...
+  },
+  "content": {
+    "weekTitle": "Work Hours & Focus Blocks Now on Your Calendar! 🎯",
+    "weekSubtitle": "8 powerful updates that supercharge your productivity",
+    "weekDate": "Oct 25 - Nov 1, 2025",
+    "openingMessage": "This week has been HUGE! We've shipped game-changing features that make the AI Agent even more powerful at protecting your time and managing your schedule. Current users are already saving hours every week - here's what you've been missing! 🚀",
+    "heroFeature": { ... },
+    "newFeatures": [ ... ],
+    "improvements": [ ... ],
+    "bugFixes": [ ... ],
+    "testimonial": {
+      "text": "The AI saved me 5 hours this week just by protecting my focus blocks...",
+      "author": "Sid Mathur",
+      "role": "Founder"
+    },
+    "comingNext": "Next week: Voice commands for calendar management, smart meeting summaries...",
+    "ctaLink": "https://example.com/wellness/ai-agent",
+    "ctaText": "Start Your Free Trial"
+  }
+}
+```
+
+### Step 5: Generate HTML
+// Import helper functions directly from synced location
+const os = require('os');
+const path = require('path');
+const scriptsDir = path.join(os.homedir(), '.fraim', 'scripts');
+const scriptPath = path.join(scriptsDir, 'newsletter-helpers.ts');
+
+const { saveNewsletter } = await import(scriptPath);
+
+// 2. Save newsletter JSON and generate HTML
+const savedPath = saveNewsletter(newsletter);
+```
+
+**This function will**:
+- Save the JSON file
+- Generate beautiful HTML from the template
+- Save the HTML file
+- Return path to JSON file
+
+### Step 6: User Review
+**AI Agent**:
+1. **Points user to the generated file**: `docs/customer-development/newsletters/newsletter-YYYY-MM-DD.json`
+2. **Shows preview**: Points to HTML file for browser preview
+3. **Requests review** and any edits needed (user can edit JSON directly)
+4. **Waits for user approval** before proceeding
+
+**Note**: User can:
+- Edit titles to be more compelling
+- Add/remove items
+- Adjust descriptions
+- Add real testimonials (verify authenticity!)
+- Add "coming next" teaser
+
+### Step 7: Send Newsletter (Separate Command)
+**When user says "Send the newsletter" or similar**:
+
+**User runs deterministic script**:
+```bash
+npm run send-newsletter
+```
+
+// Import helper functions directly from synced location
+const os = require('os');
+const path = require('path');
+const scriptsDir = path.join(os.homedir(), '.fraim', 'scripts');
+const scriptPath = path.join(scriptsDir, 'newsletter-helpers.ts');
+
+const { sendNewsletterToExecutives } = await import(scriptPath);
+
+// 2. Send newsletter to all active executives
+await sendNewsletterToExecutives('docs/customer-development/newsletters/newsletter-2025-11-01.json');
+```
+
+**This function will**:
+- Load the approved newsletter JSON
+- Get all active executives from database
+- For each executive:
+  - Get their AI Agent email address
+  - Get their OAuth tokens
+  - Send personalized newsletter from their AI identity
+- Log results and exit
+
+## NEWSLETTER STRUCTURE
+
+### Hero Section
+- **Week Title**: Catchy title based on hero feature or main theme
+- **Subtitle**: Count of updates
+- **Stats Banner**: Features | Improvements | Bug Fixes counters
+
+### Content Sections
+1. **Opening Message**: Exciting intro about what shipped (AI agent writes this)
+2. **Hero Feature** (optional): Spotlights the most impactful change with red "HERO FEATURE" badge
+3. **New Capabilities**: Major new features added
+4. **Major Improvements**: Significant enhancements
+5. **Fixes & Polish**: Bug fixes and minor improvements
+6. **Testimonial** (optional): Real user quote about impact (VERIFY AUTHENTICITY)
+7. **Coming Next** (optional): Preview of upcoming features
+
+### Call-to-Actions
+- **FOMO CTA**: "Don't Miss Out!" with signup link
+- **Feedback CTA**: Link to ChatGPT interface
+
+## EDITORIAL GUIDELINES
+
+### What to Include ✅
+- New features that add capability for users
+- Improvements that save time or improve UX
+- Bug fixes that had user impact
+- Real user testimonials (ONLY - verify authenticity)
+- Quantified benefits (time saved, conflicts reduced, etc.)
+
+### What to Exclude ❌
+- Internal infrastructure changes
+- **Admin dashboards, monitoring, analytics (internal-only)**
+- **Backups, database operations, devops**
+- **API route fixes, duplicate endpoint resolution**
+- **Environment configuration, .env file updates**
+- **Developer setup scripts, build configuration**
+- CI/CD improvements
+- Documentation updates
+- Dependency updates
+- Technical debt cleanup
+- Developer tools and debugging features
+- **Internal bug fixes (code structure, not user experience)**
+- Issues without user-facing impact
+- **FAKE TESTIMONIALS - authenticity is critical**
+
+**Rule of thumb**: If the user wouldn't notice the change in their daily use of the AI Assistant, don't include it.
+
+### Writing Style
+
+**Titles:**
+- Short, punchy, benefit-focused
+- ❌ "Implement timezone handling in calendar service"
+- ✅ "Smart Timezone Detection"
+
+**Descriptions:**
+- Start with the benefit to the user
+- Use "you" and "your" to make it personal
+- Be specific about what changed
+- ❌ "Fixed bug where calendar events weren't syncing correctly"
+- ✅ "Your calendar now stays perfectly in sync across all devices, no more mysterious missing meetings!"
+
+**Impact Statements:**
+- Quantify whenever possible
+- Include real user feedback
+- ❌ "Improved performance"
+- ✅ "Calendar loads 3x faster, getting you to your day in seconds instead of minutes"
+
+### Creating FOMO
+
+- **Quantify Success**: "500+ executives already using this feature"
+- **Show Savings**: "Don't miss out on 5 hours saved per week"
+- **Create Urgency**: "Limited spots available"
+- **Social Proof**: Real testimonials, growth stats, company names (with permission)
+
+## EXAMPLES
+
+### Example 1: Feature-Rich Week
+```
+User: "Generate this week's newsletter"
+
+AI Agent:
+1. Calls getResolvedIssuesForNewsletter() → gets 15 issues
+2. Analyzes each issue:
+   - 3 user-facing features
+   - 5 improvements
+   - 2 bugs
+   - 5 internal/devops (FILTERED OUT)
+3. Writes compelling content for each item
+4. Selects "Voice Commands for Calendar" as hero feature
+5. Writes exciting opening: "This week has been HUGE!..."
+6. Creates newsletter JSON with all content
+7. Calls saveNewsletter() → generates HTML
+8. Shows preview: "Newsletter ready! docs/customer-development/newsletters/newsletter-2025-11-01.html"
+
+User: "Looks great, send it"
+
+AI Agent or User:
+Runs: npm run send-newsletter
+OR
+Calls: sendNewsletterToExecutives('newsletter-2025-11-01.json')
+```
+
+### Example 2: User Adds Testimonial
+```
+User: "Generate newsletter"
+
+AI Agent:
+[Creates newsletter with 5 improvements, no testimonial]
+
+User: "Add a testimonial from me - I saved 5 hours this week thanks to focus blocks"
+
+AI Agent:
+[Edits JSON to add testimonial with user's name]
+[Regenerates HTML]
+Shows: "Updated! Ready to send?"
+
+User: "Yes, send it"
+
+User runs: npm run send-newsletter
+```
+
+## TIPS FOR COMPELLING NEWSLETTERS
+
+### Highlight User Value
+- Focus on what users can DO, not how it works
+- "You can now..." not "We implemented..."
+- "Your calendar automatically..." not "The system now..."
+
+### Use Concrete Examples
+- "Schedule meetings in seconds" not "Faster scheduling"
+- "85% fewer conflicts" not "Better conflict detection"
+- "Save 5 hours per week" not "More efficient"
+
+### Create Narrative
+- Opening: "This week has been incredible!"
+- Hero feature: Build excitement around main change
+- Coming next: Build anticipation for next week
+
+### Make it Scannable
+- Short paragraphs (2-3 sentences max)
+- Clear section headers
+- Visual hierarchy with emojis and formatting
+- Impact callouts that stand out
+
+## QUALITY CHECKLIST
+
+Before approving newsletter, verify:
+- [ ] All items are user-facing (no internal/devops features)
+- [ ] Testimonials are real and verified
+- [ ] Impact statements are accurate and quantified
+- [ ] Descriptions focus on user value, not implementation
+- [ ] Opening message is exciting and FOMO-inducing
+- [ ] Links are correct (Azure signup URL)
+- [ ] No mention of API credits or costs (the service is free)
+- [ ] Grammar and spelling are perfect
+- [ ] Preview HTML looks beautiful in browser
+
+## FREQUENCY
+
+**Recommended**: Weekly, sent Monday morning
+- Catches people starting their week
+- Fresh in mind for decision-making
+- Consistent schedule builds anticipation
+
+**Alternative**: Bi-weekly if weekly feels too frequent
+
+**Special editions**: 
+- Major feature launches
+- Milestone celebrations (e.g., "100 users!")
+- Holiday/end-of-year roundups