ahmed181283

---
name: multi-platform-scheduler
description: Professional multi-platform social media content scheduler for Twitter, LinkedIn, Instagram, TikTok, YouTube, and more. Use when user needs to schedule and optimize content across multiple social platforms, manage campaigns, analyze engagement, or streamline social media workflows.
---

# Multi-Platform Social Media Scheduler

## Quick Start

Professional social media management tool for scheduling, optimizing, and analyzing content across Twitter, LinkedIn, Instagram, TikTok, YouTube, Facebook, Pinterest, and more from a unified dashboard.

## When to Use This Skill

Use this skill when you need to:
- Schedule posts across multiple social media platforms
- Optimize content timing for maximum engagement
- Manage content calendars and editorial workflows
- Analyze cross-platform engagement metrics
- Coordinate campaigns and product launches
- Streamline social media operations
- Track brand mentions and social listening

## Supported Platforms

### Primary Platforms
- **Twitter/X** - Real-time engagement, trending topics, threads
- **LinkedIn** - Professional networking, B2B content, articles
- **Instagram** - Visual content, Stories, Reels, shopping
- **TikTok** - Short-form video, trending audio, viral potential
- **YouTube** - Long-form video, Shorts, community tab

### Additional Platforms
- **Facebook** - Groups, pages, marketplace
- **Pinterest** - Visual discovery, e-commerce
- **Reddit** - Community engagement, AMAs
- **Threads** - Meta's Twitter competitor
- **Bluesky** - Emerging Twitter alternative

## Core Features

### Content Scheduling
- **Unified content calendar** for all platforms in one dashboard
- **Platform-specific optimization** (character limits, hashtags, media specs)
- **Auto-formatting** for each platform's requirements
- **Bulk scheduling** with CSV import or content templates
- **Time zone support** for global teams
- **Recurring content** automation for evergreen posts

### Smart Scheduling
- **Best time recommendations** based on audience engagement data
- **Competitor activity monitoring** to find optimal posting windows
- **Platform algorithm optimization** for maximum reach
- **Seasonal and event-based scheduling** around holidays and trends
- **A/B testing** of posting times for performance optimization
- **Content fatigue prevention** - avoid spam-like posting

### Content Optimization
- **Platform-specific caption generation** from master content
- **Hashtag optimization** for each platform's best practices
- **Media resizing and formatting** for platform requirements
- **Cross-platform content repurposing** (video → Shorts, blog → tweet thread)
- **SEO optimization** for YouTube and Pinterest descriptions
- **Accessibility features** - alt text, captions, image descriptions

### Analytics & Insights
- **Cross-platform performance tracking** in unified dashboard
- **Engagement metrics** (likes, comments, shares, saves, clicks)
- **Reach and impressions** monitoring
- **Audience demographics and growth** analysis
- **Content performance comparisons** across platforms
- **ROI calculation** by campaign and platform
- **Competitor benchmarking** and market share analysis

### Campaign Management
- **Campaign calendar** with coordinated multi-platform launches
- **Product launch coordination** with teaser, launch, follow-up phases
- **Event-based scheduling** around conferences, holidays, sales
- **Multi-platform workflows** with approval processes
- **Team collaboration** with roles, permissions, and workflows

## Usage

### Basic Scheduling
```
Schedule post for Instagram, Twitter, and LinkedIn
Content: New blog post about AI marketing
Times: Instagram 6PM, Twitter 9AM, LinkedIn 10AM
```

### Bulk Import
```
Import 20 posts from CSV with platform assignments
Schedule across optimal times for each platform
```

### Cross-Platform Campaign
```
Create campaign for product launch
Schedule teaser posts on all platforms 3 days before launch
Coordinate launch day content with platform-specific formats
Plan follow-up engagement posts for 7 days
```

### Content Repurposing
```
Take YouTube video and create:
- TikTok Short (60 seconds highlight)
- Instagram Reel (key moment)
- Twitter thread (key insights)
- LinkedIn post (professional summary)
- Pinterest pin (thumbnail with description)
```

## Content Calendar Structure

### Weekly Calendar View
```
Social Media Calendar - Week of April 26

Monday:
├─ 9AM Twitter: Industry news link + commentary
├─ 10AM LinkedIn: Thought leadership post
├─ 2PM Instagram: Behind-the-scenes photo
└─ 6PM TikTok: Trending challenge video

Tuesday:
├─ 9AM Instagram: Product spotlight
├─ 10AM LinkedIn: Case study teaser
├─ 12PM Twitter: Thread about industry trend
└─ 6PM YouTube: Shorts - quick tip

Wednesday:
├─ 9AM TikTok: Educational content
├─ 10AM LinkedIn: Article share + insight
├─ 2PM Pinterest: Infographic pin
└─ 6PM Instagram: User-generated content feature
```

## Platform Optimization

### Twitter/X
- **280 character limit** with thread support for longer content
- **Optimal timing:** 9AM, 12PM, 3PM weekdays (business audience)
- **Best practices:** Use 2-3 hashtags, thread for complex topics, engage with replies
- **Content types:** News, thread series, polls, threads, quote tweets

### LinkedIn
- **3,000 character limit** with document and article support
- **Optimal timing:** 8-10AM and 5-6PM weekdays
- **Best practices:** Professional tone, use media, tag people/companies, engage in comments
- **Content types:** Professional insights, articles, company news, personal stories

### Instagram
- **2,200 character limit** with visual focus
- **Optimal timing:** 11AM-1PM and 7-9PM
- **Best practices:** High-quality visuals, 5-30 hashtags, use Stories daily
- **Content types:** High-quality photos, Reels, Stories, carousels

### TikTok
- **150 character caption limit** with video focus
- **Optimal timing:** 7-9AM and 7-11PM
- **Best practices:** Trending audio, good lighting, engage with comments, post consistently
- **Content types:** Trending challenges, educational, entertainment, behind-the-scenes

### YouTube
- **5,000 character limit** with video and playlist support
- **Optimal timing:** 2-4PM and 6-9PM
- **Best practices:** Compelling thumbnails, SEO-optimized titles/descriptions, engage in comments
- **Content types:** Long-form videos, Shorts, tutorials, reviews

## Analytics & Reporting

### Cross-Platform Performance
```
Performance Report - Last 30 Days

Twitter:
- Posts: 45 | Avg Engagement: 3.2% | Best Time: 9AM
- Growth: +250 followers | Top Post: AI thread (12K impressions)

LinkedIn:
- Posts: 15 | Avg Engagement: 5.8% | Best Time: 8AM
- Growth: +120 connections | Top Post: Industry article (8K views)

Instagram:
- Posts: 30 | Avg Engagement: 4.1% | Best Time: 7PM
- Growth: +450 followers | Top Post: Product shot (15K impressions)

TikTok:
- Posts: 20 | Avg Engagement: 8.5% | Best Time: 8PM
- Growth: +1,200 followers | Viral video: 125K views

YouTube:
- Videos: 8 | Avg Engagement: 2.3% | Best Time: 7PM
- Growth: +85 subscribers | Top video: Tutorial (5K views)

Cross-Platform Insights:
- Best performing format: TikTok videos (highest engagement)
- Best day for engagement: Wednesday
- Optimal post frequency: 2-3 posts per platform per day
```

### Engagement Analysis
- **Content type comparison** - which formats perform best
- **Hashtag effectiveness** tracking and optimization
- **Audience growth patterns** by platform and time
- **Viral content analysis** - what made posts successful
- **Competitor benchmarking** against industry leaders

## Campaign Workflows

### Product Launch Framework
```
Phase 1: Teaser (7 days before)
- All platforms: Sneak peek content
- Build anticipation, collect email signups

Phase 2: Launch Day
- Coordinated posts across all platforms
- Platform-specific launch content (video, thread, story)

Phase 3: Amplification (3-7 days after)
- User-generated content features
- Testimonials and reviews
- Behind-the-scenes content

Phase 4: Sustained (2+ weeks)
- Educational content about product
- Customer success stories
- Ongoing engagement and community building
```

## Team Features

### Collaboration Tools
- **Role-based permissions** (admin, editor, contributor, viewer)
- **Approval workflows** for scheduled content
- **Content templates** for brand consistency
- **Brand guidelines enforcement** (tone, visuals, hashtags)
- **Team performance tracking** by team member

### Workflow Automation
- **Multi-stage approval processes**
- **Automated content formatting** for platform specs
- **Integration with other tools** (Canva, Notion, Slack)
- **Content library** for reusable assets
- **API access** for custom integrations

## Setup & Integration

### Platform Connections
```
Connect Twitter/X API
Connect LinkedIn Business account
Connect Instagram Business account
Connect TikTok Business account
Connect YouTube channel
Connect other platforms as needed
```

### Initial Configuration
```
Set brand guidelines and tone
Configure optimal posting times
Set up approval workflows
Create content templates
Import existing content library
```

## Advanced Features

### Social Listening
- **Brand mention tracking** across platforms
- **Competitor monitoring** for strategy insights
- **Industry trend detection** from engagement patterns
- **Crisis alert system** for negative sentiment spikes

### AI-Powered Features
- **Caption generation** from visual content
- **Hashtag suggestions** based on content analysis
- **Best time predictions** using machine learning
- **Content recommendations** based on performance data

## Export & Integration

### Data Exports
- **CSV exports** for spreadsheet analysis
- **PDF reports** for stakeholder presentations
- **API access** for custom dashboards
- **Integration with** Google Analytics, HubSpot, Salesforce

## Pricing & Features

### Professional Tiers

| Feature | Starter | Professional | Enterprise |
|---------|--------|-------------|-------------|
| Platforms Supported | 3 | All 8+ | Custom platforms |
| Scheduled Posts | 100/month | 1,000/month | Unlimited |
| Team Members | 2 | 10 | Unlimited |
| Analytics Depth | Basic | Advanced | Custom metrics |
| AI Features | Limited | Full | Custom models |
| Social Listening | No | Yes | Advanced |
| API Access | No | Yes | Full API |
| Support | Email | Priority | Dedicated |

## Getting Started

### 1. Platform Setup
```
Connect my social media accounts
Configure platform-specific settings
```

### 2. Content Library
```
Import existing content and assets
Create brand templates
Set up approval workflows
```

### 3. First Campaign
```
Schedule my first multi-platform campaign
Test and optimize posting times
```

### 4. Continuous Optimization
```
Monitor analytics weekly
Adjust strategy based on performance
Scale successful content formats
```

## Getting Help

For advanced features and platform-specific strategies:
- [Twitter/X Optimization Guide](references/twitter-optimization.md)
- [LinkedIn B2B Strategy](references/linkedin-b2b.md)
- [Instagram Growth Tactics](references/instagram-growth.md)
- [TikTok Viral Content](references/tiktok-viral.md)
- [YouTube SEO Guide](references/youtube-seo.md)

FILE:clawhub.json
{
  "name": "multi-platform-scheduler",
  "displayName": "Multi-Platform Social Media Scheduler",
  "version": "1.0.0",
  "description": "Professional multi-platform social media content scheduler for Twitter, LinkedIn, Instagram, TikTok, YouTube, and more with unified content calendar, smart scheduling, and cross-platform analytics.",
  "author": "ahmed181283",
  "license": "MIT",
  "pricing": {
    "model": "subscription",
    "price": 9900,
    "interval": "monthly"
  },
  "tags": ["social-media", "scheduling", "twitter", "linkedin", "instagram", "tiktok", "youtube", "content-calendar"],
  "minOpenClawVersion": "1.0.0",
  "category": "marketing"
}

---
name: seo-content-strategy
description: Professional SEO content strategy generator with keyword research, content calendar, competitor analysis, and ranking tracking. Use when user needs to plan SEO content, research keywords, analyze competitors, create content calendars, or track search engine rankings and optimize content performance.
---

# SEO Content Strategy Generator

## Quick Start

Professional SEO content planning tool with keyword research, content calendar generation, competitor analysis, and ranking tracking for systematic organic growth.

## When to Use This Skill

Use this skill when you need to:
- Plan comprehensive SEO content strategy
- Research profitable keywords with search volume and difficulty
- Create content calendars with optimal publishing schedule
- Analyze competitor content and identify content gaps
- Track keyword rankings and content performance
- Generate SEO-optimized content briefs and outlines
- Audit existing content for improvement opportunities

## Core Features

### Keyword Research
- **Search volume analysis** with monthly and annual trends
- **Keyword difficulty scoring** (0-100 scale) for competition level
- **Search intent classification** (informational, transactional, navigational)
- **Long-tail discovery** for low-competition, high-conversion opportunities
- **Related keyword suggestions** and semantic connections
- **SERP feature opportunities** (featured snippets, PAA, local pack)
- **Seasonal trend analysis** for keyword opportunity timing

### Content Calendar Generation
- **Automated scheduling** based on keyword priority and seasonality
- **Content type planning** (blog posts, guides, how-tos, listicles)
- **Optimal publishing times** for audience engagement and SEO
- **Content cluster strategy** for topical authority building
- **Cross-channel planning** (blog, social media, email, video)
- **Editorial calendar integration** with team workflow
- **Deadline tracking** and content production pipeline

### Competitor Analysis
- **Content gap identification** - what competitors cover that you don't
- **Backlink opportunity discovery** by analyzing competitor linking
- **Ranking pattern analysis** - what content ranks for your target keywords
- **Content format analysis** - length, structure, media usage
- **Top-performing content identification** in your niche
- **Content performance benchmarking** against industry leaders
- **Featured snippet opportunities** from competitor content

### Ranking & Performance Tracking
- **Daily keyword position monitoring** across Google, Bing, and other engines
- **Rank change alerts** for significant position movements
- **Click-through rate (CTR) optimization** suggestions
- **Organic traffic attribution** to specific content pieces
- **Content ROI calculation** - traffic value vs creation cost
- **Mobile vs desktop performance** tracking
- **Local ranking monitoring** for location-based businesses

## Usage

### Keyword Research
```
Find profitable keywords for "SaaS marketing automation"
Analyze search volume and difficulty for 50 related keywords
Identify low-DR, high-volume keyword opportunities
```

### Content Calendar Creation
```
Create 3-month SEO content calendar for B2B SaaS niche
Schedule content around seasonal keywords and product launches
```

### Competitor Analysis
```
Analyze top 10 competitors for "content marketing" keywords
Identify content gaps we can exploit
Find featured snippet opportunities
```

### Ranking Monitoring
```
Track keyword rankings for my top 50 target keywords
Alert me when any keyword enters top 10 positions
```

## Keyword Research Workflow

### 1. Seed Keyword Analysis
- **Seed keywords** from business, products, and target audience
- **Initial volume and difficulty** assessment
- **Intent classification** for each keyword
- **SERP feature analysis** (snippets, PAA, local)

### 2. Keyword Expansion
- **Related keyword discovery** through semantic search
- **Question-based keywords** (who, what, how, why, where)
- **Long-tail挖掘** for specific, high-conversion terms
- **Competitor keyword overlap** - what they target that you miss

### 3. Opportunity Scoring
- **Volume/Difficulty ratio** for quick wins vs long-term plays
- **Search intent alignment** with your content goals
- **Seasonal opportunity timing** for strategic planning
- **Competitor difficulty assessment** - who ranks, how strong?

### 4. Keyword Clustering
- **Topic cluster creation** for topical authority
- **Pillar content identification** - broad, comprehensive guides
- **Cluster content planning** - supporting articles
- **Internal linking strategy** for SEO structure

## Content Calendar Structure

### Content Tiers

| Tier | Content Type | Frequency | Purpose |
|------|-------------|-----------|---------|
| **Pillar** | Comprehensive guides | Quarterly | Build topical authority |
| **Cluster** | Supporting articles | Monthly | Strengthen pillar pages |
| **Blog** | Regular posts | Weekly | Freshness, engagement |
| **Supporting** | FAQ, definitions | Ongoing | Capture long-tail searches |

### Monthly Content Template
```
Week 1: 2 cluster articles + 1 blog post
Week 2: 1 pillar section + 2 blog posts
Week 3: 3 cluster articles + content update
Week 4: Competitor gap content + monthly recap
```

### Seasonal Planning
- **Industry calendar events** integrated into schedule
- **Holiday and seasonal** keyword timing optimization
- **Product launch windows** with content amplification
- **Competitor campaign monitoring** for responsive planning

## Competitor Analysis Framework

### Content Gap Matrix
```
Competitor Analysis - "B2B SaaS Marketing"

Competitor A: Covers pricing, onboarding, integrations
Competitor B: Strong in case studies, comparisons
Competitor C: Dominates "how-to" content

Content Gaps Identified:
- "SaaS vs alternatives" - weak across all competitors
- "Industry trends 2024" - none covering comprehensively
- "Implementation guides" - opportunity for detailed walkthrough
- "Cost-benefit analysis" - no in-depth comparisons
```

### Backlink Opportunity Discovery
- **Resource page opportunities** for contextual links
- **Broken link building** from competitor content
backs pointing to 404s
- **Unlinked mentions** - brand mentions without links
- **Guest post targets** based on competitor linking patterns

### Featured Snippet Targeting
- **Question format analysis** from competitor PAA content
- **Definition opportunities** for glossary-style snippets
- **How-to structure** from step-by-step ranking pages
- **Listicle optimization** based on competitor format

## Ranking Tracking & Alerts

### Position Monitoring
- **Daily position checks** for all target keywords
- **Google, Bing, and others** engine coverage
- **Mobile and desktop** separate tracking
- **Local and organic** position distinction
- **SERP feature monitoring** (featured, PAA, images)

### Alert System
```
Ranking Alerts Configured:

Alert: Top 10 entry
Keyword: "SaaS marketing automation"
Previous: Position 15
Current: Position 7
Change: +8 positions
Action: Update internal links, build backlinks

Alert: Featured snippet won
Keyword: "how to automate B2B marketing"
Result: Position 0 (Featured)
Action: Monitor CTR, defend position
```

### Performance Analytics
- **Traffic attribution** - which content drives which keywords
- **Position-traffic correlation** for strategic focus
- **Click-through rate optimization** for title/meta improvements
- **Content lifecycle analysis** - ranking decay over time

## Content Brief Generation

### SEO Content Template
```
Content Brief: "Complete Guide to SaaS Marketing Automation"

Target Keyword: "SaaS marketing automation"
Secondary Keywords: "B2B automation tools", "marketing workflows", "automated campaigns"

Search Intent: Informational (comprehensive guide)
Word Count Target: 2,500-3,000 words

Content Structure:
1. H1: Ultimate Guide to SaaS Marketing Automation
2. Introduction: Problem statement and value proposition
3. What is Marketing Automation? (Definition + Examples)
4. Benefits for B2B SaaS (5-7 key benefits)
5. Key Components (What to automate: email, social, lead scoring)
6. Implementation Steps (Step-by-step guide)
7. Tools Comparison (Top 5 tools with features/pricing)
8. Common Mistakes (What to avoid)
9. Measuring Success (KPIs and metrics)
10. Conclusion and CTA

Competitor Analysis:
- Competitor A covers tools but not implementation
- Competitor B missing ROI measurement section
- Opportunity: Comprehensive implementation guide

Internal Linking:
- Link to: "Marketing Automation Tools" pillar page
- Link to: "B2B Lead Generation" cluster content

External Linking:
- 2-3 industry authority sources
- 1-2 research/statistics sources

Featured Snippet Targeting:
- H2: "Key Components of SaaS Marketing Automation"
- Format: Bullet list with clear benefits

FAQ Opportunities:
- "How much does marketing automation cost?"
- "What are the best SaaS marketing automation tools?"
- "How long to implement marketing automation?"

Recommended Media:
- 3-4 screenshots of tool interfaces
- 1 implementation flowchart
- 2-3 comparison charts
```

## Advanced Features

### Topic Authority Building
- **Entity recognition** for topical clustering
- **Content silhouette analysis** - coverage depth across topic
- **Internal link optimization** for site structure
- **Canonicalization recommendations** for duplicate content

### Technical SEO Integration
- **Site crawl and audit** for technical issues
- **Schema markup suggestions** for rich results
- **Page speed optimization** recommendations
- **Mobile optimization** checks and fixes

### Content Performance Prediction
- **SERP simulation** to predict ranking potential
- **Content length optimization** based on competitors
- **Media requirement analysis** for ranking pages
- **Content freshness** scheduling for query deserves freshness

## Export & Integration

### Output Formats
- **CSV exports** for spreadsheet analysis
- **JSON APIs** for custom dashboards
- **Google Sheets integration** for team collaboration
- **Project management sync** (Asana, Trello, ClickUp)
- **CMS publishing** direct (WordPress, Webflow, HubSpot)

### Reporting Templates
- **Weekly ranking reports** with position changes
- **Monthly content performance** with ROI analysis
- **Quarterly strategy review** with competitive insights
- **Annual SEO audit** with growth assessment

## Setup & Configuration

### Initial Setup
```
Connect website for crawling and ranking tracking
Configure target keywords and search engines
Set up competitor monitoring
Define content production capacity and team
```

### Team Configuration
- **Writer access** for content briefs and guidelines
- **Editor workflow** for approval and scheduling
- **SEO review process** for content optimization
- **Reporting permissions** for stakeholder visibility

## Getting Started

### 1. Keyword Research Phase
```
Research keywords for my main product/service
Identify 50-100 target keywords with good opportunity
Score and prioritize by volume/difficulty ratio
```

### 2. Competitor Analysis
```
Analyze top 5-10 competitors in my niche
Identify their best-performing content
Find content gaps I can exploit
```

### 3. Strategy Development
```
Create content clusters around pillar topics
Build 6-12 month content calendar
Plan internal linking structure
```

### 4. Execution & Tracking
```
Generate content briefs for first month
Track keyword rankings weekly
Analyze performance monthly and adjust strategy
```

## Quality Metrics

### Content Quality Indicators
- **Comprehensive coverage** of search intent
- **E-E-A-T signals** (experience, expertise, authoritativeness, trust)
- **Content freshness** with regular updates
- **Multimedia integration** (images, videos, infographics)
- **User engagement** (dwell time, scroll depth, social shares)

### SEO Performance Benchmarks
- **Top 10 positions** for 30%+ of target keywords
- **Featured snippet wins** for 10%+ of opportunity keywords
- **Organic traffic growth** 10-20% month-over-month
- **Content ROI** 300%+ (traffic value vs content cost)

## Getting Help

For advanced strategies and tactical guidance:
- [Keyword Research Advanced](references/keyword-research-advanced.md)
- [Content Calendar Best Practices](references/content-calendar-optimization.md)
- [Competitor Analysis Framework](references/competitor-intelligence.md)
- [Technical SEO Integration](references/technical-seo-guide.md)

FILE:clawhub.json
{
  "name": "seo-content-strategy",
  "displayName": "SEO Content Strategy Generator",
  "version": "1.0.0",
  "description": "Professional SEO content planning tool with keyword research, content calendar generation, competitor analysis, ranking tracking, and systematic organic growth optimization.",
  "author": "ahmed181283",
  "license": "MIT",
  "pricing": {
    "model": "subscription",
    "price": 12900,
    "interval": "monthly"
  },
  "tags": ["seo", "content-strategy", "keyword-research", "ranking-tracking", "competitor-analysis", "content-calendar"],
  "minOpenClawVersion": "1.0.0",
  "category": "marketing"
}

---
name: trading-journal-analytics
description: Professional trading journal with performance analytics, win rate tracking, emotion logging, strategy analysis, and P&L tracking. Use when user needs to improve trading performance, maintain detailed trading records, analyze strategy effectiveness, track emotions and discipline, or build a systematic trading practice.
---

# Trading Journal & Performance Analytics

## Quick Start

Professional-grade trading journal system for systematic trading improvement with performance analytics, emotion tracking, strategy analysis, and comprehensive P&L monitoring.

## When to Use This Skill

Use this skill when you need to:
- Maintain professional trading journal with detailed records
- Track win rate, P&L, and performance metrics
- Analyze emotional states and trading discipline
- Evaluate strategy effectiveness and optimize approaches
- Generate performance reports and improvement insights
- Track trading sessions with context and lessons learned

## Core Features

### Trade Recording
- **Detailed trade logging** with entry, exit, size, and reasoning
- **Multi-timeframe support** for scalping, day trading, swing, position trading
- **Multi-asset tracking** across stocks, crypto, forex, options, futures
- **Screenshot/image support** for trade setups and chart patterns
- **Tagging system** for strategy, timeframe, and market condition classification

### Performance Analytics
- **Win rate calculation** by strategy, timeframe, and market condition
- **P&L tracking** with realized and unrealized profits/losses
- **Risk-reward analysis** to evaluate trade quality
- **Drawdown monitoring** and recovery analysis
- **Sharpe ratio and other risk-adjusted metrics**
- **Monthly/quarterly/yearly performance summaries**

### Emotion & Discipline Tracking
- **Pre-trade emotional state** logging (fear, greed, confidence, overconfidence)
- **Post-trade reflection** - what went right/wrong
- **Discipline violation tracking** (overtrading, revenge trading, FOMO)
- **Emotional pattern analysis** over time
- **Streak tracking** (winning/losing) and psychological impact

### Strategy Analysis
- **Strategy comparison** - which approaches work best
- **Market condition filtering** - performance in trending vs ranging markets
- **Timeframe analysis** - best performing timeframes
- **Setup effectiveness** - which chart patterns work
- **Strategy optimization suggestions** based on historical data

## Usage

### Basic Trade Entry
```
Log my trade: Entered EURUSD long at 1.0850, stop 1.0820, target 1.0950
Reason: Breakout of daily resistance, strong momentum
```

### Performance Query
```
Show my win rate for EURUSD trades in March
Analyze my breakout strategy performance
```

### Emotion Tracking
```
Log emotional state before trade: feeling confident after 3-win streak
Record trading discipline violation: revenge trade after loss
```

### Strategy Analysis
```
Compare performance of breakout vs mean reversion strategies
Which timeframe performs best for my trading style?
```

## Trade Structure

### Standard Trade Entry
```
Asset: EUR/USD
Type: Long / Short
Entry Price: 1.0850
Stop Loss: 1.0820
Take Profit: 1.0950
Position Size: 1.0 lot
Risk-Reward: 1:3
Strategy: Daily Breakout
Timeframe: 4H
Entry Date/Time: 2026-04-26 14:30 UTC
Exit Date/Time: 2026-04-26 16:45 UTC
Exit Price: 1.0948
P&L: +$680
Pre-Trade Emotion: Confident
Post-Trade Reflection: Good entry, could have held longer
Market Condition: Strong uptrend, volume spike
Screenshots: [attached chart images]
Tags: #breakout #4H #trending #winning-trade
```

## Analytics & Reports

### Performance Metrics

| Metric | Calculation | Benchmark |
|---------|-------------|------------|
| **Win Rate** | Winning trades / Total trades | >50% breakeven |
| **Average R:R** | Avg profit / Avg risk | >1.5 good |
| **Sharpe Ratio** | (Return - RiskFree) / StdDev | >1.0 good |
| **Max Drawdown** | Peak to trough % | <20% good |
| **Win/Loss Ratio** | Avg win / Avg loss | >2.0 good |
| **Profit Factor** | Gross profit / Gross loss | >1.5 good |

### Performance Reports
```
Monthly Performance Report - April 2026

Total Trades: 47
Winning Trades: 28 (59.6%)
Losing Trades: 19 (40.4%)
Total P&L: +$4,230
Average Win: +$234
Average Loss: -$89
Win/Loss Ratio: 2.63
Best Strategy: 4H Breakout (68% win rate)
Best Timeframe: 4H
Biggest Win: +$680
Biggest Loss: -$340
Max Drawdown: -8.2%
Emotional Pattern: Overconfident after 3+ win streaks
Discipline Score: 7.2/10 (improvement needed)

Top Improvements:
1. Reduce position size after 3+ win streaks (overconfidence)
2. Better stop placement on mean reversion trades
3. Avoid revenge trading after losses
```

## Emotion & Psychology

### Emotional States to Track
- **Confidence** - normal trading state
- **Overconfidence** - after winning streaks, dangerous
- **Fear** - missing opportunities, hesitation
- **Greed** - overleveraging, chasing trades
- **Revenge** - trying to recover losses
- **FOMO** - fear of missing out
- **Anxiety** - after losses, poor decisions

### Discipline Violations
- **Overtrading** - too many trades, no edge
- **Revenge Trading** - trying to recover losses
- **FOMO Entries** - chasing moves without setup
- **No Stop Loss** - or moved stop for hope
- **Overleveraging** - risk too high for account
- **Trading When Distracted** - not focused

### Psychology Insights
```
Emotional Pattern Analysis:

Overconfidence Pattern:
- Occurs after: 3+ consecutive wins
- Next trade win rate: 34% (down from 59%)
- Recommendation: Reduce position size by 30%

Revenge Trading Pattern:
- Occurs after: Losses >$200
- Next trade P&L: -$120 average
- Recommendation: Take 1-hour break after loss

FOMO Entries:
- Trigger: Strong moves without setup
- Win rate: 27%
- Recommendation: Stick to your setups, ignore noise
```

## Strategy Analysis

### Strategy Comparison
```
Strategy Performance Comparison:

Breakout Strategy:
- Trades: 18 | Win Rate: 68% | Avg R:R: 2.1
- Best in: Trending markets | Worst in: Ranging
- Improvement: Add volume confirmation

Mean Reversion Strategy:
- Trades: 14 | Win Rate: 52% | Avg R:R: 1.3
- Best in: Ranging markets | Worst in: Breakouts
- Improvement: Better stop placement

Momentum Strategy:
- Trades: 11 | Win Rate: 45% | Avg R:R: 0.9
- Best in: Strong trends | Worst in: Chop
- Improvement: Avoid overtrading, increase R:R
```

## Export & Integration

### Export Formats
- **CSV export** for spreadsheet analysis
- **JSON export** for custom dashboards
- **PDF reports** for professional documentation
- **Calendar integration** for trade reminders
- **TradingView sync** for chart annotations

### Cloud Storage
- **Automatic backup** to cloud storage
- **Cross-device sync** for mobile access
- **Version history** and trade record integrity
- **Collaborative features** for trading teams

## Advanced Features

### Pattern Recognition
- **Winning streak analysis** - what leads to wins
- **Losing streak patterns** - what causes drawdowns
- **Market condition correlation** - performance by environment
- **Time-of-day analysis** - best trading hours
- **Day-of-week patterns** - which days perform best

### Risk Management
- **Position sizing calculator** - based on account and risk
- **Portfolio correlation** - if trading multiple assets
- **Risk-of-ruin calculation** - position sizing safety
- **Monte Carlo simulation** - expected outcomes

### Goal Setting & Tracking
- **Monthly P&L targets** with progress tracking
- **Win rate goals** with achievement tracking
- **Drawdown limits** and violation alerts
- **Discipline score improvement** over time

## Setup & Configuration

### Initial Configuration
```
Set trading account size and base risk per trade (1-2%)
Configure preferred timeframes and strategies
Set up emotion tracking preferences
Configure performance goal thresholds
```

### Journal Templates
- **Pre-trade checklist** - confirm setup before entry
- **Post-trade reflection** - what did I learn
- **Weekly review** - strategy and discipline assessment
- **Monthly goals** - target setting and progress

## Quality Improvements

### Journal Quality Checklist
- [ ] Every trade has clear reason and setup
- [ ] Entry, exit, stop, target all recorded
- [ ] P&L calculated accurately
- [ ] Emotional state logged for each trade
- [ ] Strategy and timeframe tagged
- [ ] Post-trade reflection completed
- [ ] Screenshots/notes for complex setups

### Journal Maintenance
- **Daily journal review** - what did I learn today?
- **Weekly strategy assessment** - what's working/not working?
- **Monthly performance review** - am I improving on key metrics?
- **Quarterly plan** - what to focus on next quarter?

## Getting Started

### 1. Initial Setup
```
Configure my trading journal with account size and risk parameters
Set up preferred strategies and timeframes
```

### 2. First Trade Entry
```
Log my first trade with all required fields
Document reasoning and emotional state
```

### 3. Performance Tracking
```
Generate my first performance report
Identify areas for improvement
```

### 4. Continuous Improvement
```
Review journal weekly for patterns
Adjust strategies based on analytics
Work on discipline based on insights
```

## Getting Help

For advanced features and trading psychology:
- [Trading Psychology Guide](references/trading-psychology.md)
- [Strategy Development Framework](references/strategy-development.md)
- [Risk Management Best Practices](references/risk-management.md)
- [Performance Optimization](references/performance-coaching.md)

FILE:clawhub.json
{
  "name": "trading-journal-analytics",
  "displayName": "Trading Journal & Performance Analytics",
  "version": "1.0.0",
  "description": "Professional trading journal with performance analytics, win rate tracking, emotion logging, strategy analysis, and comprehensive P&L monitoring for systematic trading improvement.",
  "author": "ahmed181283",
  "license": "MIT",
  "pricing": {
    "model": "subscription",
    "price": 19900,
    "interval": "monthly"
  },
  "tags": ["trading", "journal", "performance", "analytics", "win-rate", "p-l", "emotion-tracking", "strategy-analysis"],
  "minOpenClawVersion": "1.0.0",
  "category": "finance"
}

---
name: defi-yield-optimizer
description: Professional DeFi yield farming optimizer for tracking and optimizing yields across multiple chains and protocols. Use when user needs to discover high-yield DeFi opportunities, track portfolio performance, calculate ROI, and manage yield farming strategies across Ethereum, Polygon, BSC, Arbitrum, Optimism, and other EVM chains.
---

# DeFi Yield Farming Optimizer

## Quick Start

Professional-grade DeFi yield farming tool for discovering, tracking, and optimizing yields across multiple chains and protocols with automated ROI calculations, risk assessment, and portfolio management.

## When to Use This Skill

Use this skill when you need to:
- Discover high-yield DeFi opportunities across chains
- Track yield farming portfolio performance in real-time
- Calculate accurate ROI and APY metrics
- Compare protocols and identify best yields
- Manage yield farming strategies with risk assessment
- Monitor impermanent loss exposure
- Optimize gas fees and transaction timing

## Core Features

### Yield Discovery
- **Multi-chain scanning** across Ethereum, Polygon, BSC, Arbitrum, Optimism, Avalanche, and more
- **Protocol coverage** including Aave, Compound, Curve, Yearn, Lido, Uniswap, PancakeSwap, and 100+ others
- **Real-time yield updates** with live APY/APR data
- **Risk categorization** by protocol, chain, and liquidity depth
- **Impermanent loss calculation** for liquidity pools

### Portfolio Tracking
- **Multi-position portfolio management** across chains and protocols
- **Real-time value tracking** with current prices and yields
- **Performance analytics** with historical returns and growth charts
- **Gas optimization** suggestions for optimal transaction timing
- **Yield history** with daily, weekly, monthly metrics

### Risk Management
- **Protocol risk scoring** based on TVL, age, audits, and governance
- **Chain risk assessment** for network congestion and bridge issues
- **Smart contract analysis** for audit status and exploit history
- **Liquidity depth evaluation** for entry/exit capacity
- **Impermanent loss tracking** and warnings

### Analytics & Reporting
- **Daily yield reports** with portfolio performance
- **ROI calculations** including gas fees, rewards, and compounding
- **Yield optimization suggestions** based on market conditions
- **Historical performance** tracking and trend analysis
- **Export capabilities** to CSV, JSON, or spreadsheet formats

## Usage

### Basic Discovery
```
Find best DeFi yields for stablecoins on Ethereum mainnet
```

### Portfolio Management
```
Track my yield farming portfolio across all chains
Generate performance report for last 30 days
```

### Risk Analysis
```
Analyze risk for Aave USDC pool on Ethereum
Calculate impermanent loss exposure for my Curve positions
```

### Yield Comparison
```
Compare yields for ETH staking across all available protocols
Find best yield for my risk tolerance and investment amount
```

## Supported Chains

- **Ethereum** - Mainnet with full DeFi ecosystem
- **Polygon** - Low gas fees, high yields
- **Binance Smart Chain (BSC)** - Asian markets, BEP20 tokens
- **Arbitrum** - Ethereum L2, low costs
- **Optimism** - Ethereum L2, major protocols
- **Avalanche** - Fast finality, unique protocols
- **Fantom** - Ultra-low gas fees
- **Solana** - High speed, different yield mechanics
- **L2 Networks** - zkSync, StarkNet, Polygon zkEVM

## Supported Protocols

### Lending & Borrowing
- Aave, Compound, dYdX, Benqi, Fortress, Fulcru, Venus

### Yield Aggregators
- Yearn, Beefy Finance, AutoFarm, Harvest Finance

### DEX & AMM
- Uniswap, Curve, PancakeSwap, SushiSwap, QuickSwap, TraderJoe

### Liquidity Staking
- Convex, Staked AAVE, SushiSwap LP, Curve LP, PancakeSwap LP

### Bridges & Cross-Chain
- AnySwap, Hop Protocol, Synapse, Multichain, Stargate

## Setup & Prerequisites

### Account Requirements
- Crypto wallet (MetaMask, Trust Wallet, Rabby, or hardware wallet)
- Small ETH/BSC/POL gas reserve for transactions
- Connection to yield data APIs (free tier available)

### Initial Setup
```
Connect to my DeFi portfolio and scan current positions
Set risk tolerance preferences and minimum yield thresholds
Configure chain access for each network I use
```

## Advanced Features

### Yield Optimization
- **Auto-compound detection** for protocols offering auto-compound
- **Yield farming alerts** when better opportunities emerge
- **Gas timing optimization** suggesting optimal transaction windows
- **Portfolio rebalancing** recommendations based on yield changes

### Security Features
- **Protocol audit tracking** - shows last audit date and findings
- **Smart contract monitoring** for exploit alerts and warnings
- **TVL threshold alerts** when liquidity drops significantly
- **Governance proposal tracking** for protocol changes

### Portfolio Analytics
- **Win/loss tracking** by protocol, chain, and timeframe
- **Gas cost analysis** to calculate net ROI
- **Yield stability scoring** to identify volatile vs stable yields
- **Diversification analysis** showing portfolio concentration risk

## Output Formats

### Daily Yield Report
```
Portfolio Value: $45,231.23
Daily Change: +$342.45 (+0.76%)
Best Yield: Curve 3CRV LP @ 12.4% APY
Worst Yield: Venus USDC @ 3.1% APY
Gas Fees Today: $23.45
```

### Risk Assessment
```
Protocol Risk Score: 3.2/10 (Moderate)
TVL Coverage: $1.2B (High liquidity)
Audit Status: Passed (Last audit: 14 days ago)
Impermanent Loss Risk: Low (0.8% historical)
Chain Risk: Low (Ethereum mainnet)
```

## Risk Management

### Yield vs Risk Categories

| Risk Level | APY Range | Protocols | Liquidity |
|------------|-------------|------------|-------------|
| **Conservative** | 2-8% | Aave, Compound, Lido | $10B+ TVL |
| **Moderate** | 8-20% | Yearn, Curve, Uniswap LP | $1-10B TVL |
| **Aggressive** | 20-50% | New protocols, new chains | $100M-1B TVL |
| **DeFi Native** | 50-200% | New liquidity, farming | <$100M TVL |

### Security Best Practices

- **Never invest more than you can lose** - DeFi is high risk
- **Verify protocol audits** before investing
- **Check TVL depth** - ensure you can exit position
- **Monitor gas fees** - high gas kills profits
- **Track impermanent loss** - understand LP risks
- **Diversify across protocols** - concentration risk

## Getting Started

### 1. Connect Wallet
```
Connect my DeFi wallet for yield discovery
```

### 2. Discover Opportunities
```
Show me best DeFi yields for my investment amount
Filter by risk tolerance and preferred chains
```

### 3. Analyze & Compare
```
Compare Aave vs Compound yields for stablecoins
Calculate expected ROI including gas fees
```

### 4. Track Portfolio
```
Track my current yield farming positions
Generate performance report and optimization suggestions
```

## Troubleshooting

### Low Yield Discovery
1. Verify wallet is connected correctly
2. Check that chains are accessible
3. Ensure sufficient gas for queries
4. Try different timeframes (current yields vs 7-day average)

### Gas Fee Issues
1. Use L2 chains for lower costs
2. Time transactions during low gas periods
3. Check gas price trackers for optimal windows
4. Consider transaction batching

### TVL Concerns
1. Never invest in pools under $100K TVL
2. Check liquidity depth for your position size
3. Look for rug pull indicators in new protocols
4. Verify protocol age and team reputation

## Pricing & Features

### Premium Tiers (via ClawHub subscription)

| Feature | Basic | Professional | Enterprise |
|---------|--------|-------------|-------------|
| Chains Supported | 3 chains | All 8+ chains | Custom chain support |
| Protocols Tracked | 50+ | 100+ | Custom protocols |
| Real-time Updates | 15-minute delay | 1-minute updates | Live data |
| Risk Scoring | Basic | Advanced | Custom risk models |
| Portfolio Size | $10K max | $100K max | Unlimited |
| Alerts | Email | Email + SMS | Custom webhooks |
| Support | Community | Priority | Dedicated |

## Data Sources & APIs

- **DeFi Llama API** - Comprehensive yield data
- **Defi Pulse** - TVL and protocol metrics
- **Etherscan & Explorers** - Gas prices and transaction data
- **Protocol APIs** - Direct protocol yield rates
- **Chain APIs** - Network status and fees

## Quality & Reliability

- **Multi-source validation** - cross-check yield data
- **Risk-adjusted returns** - account for protocol risk
- **Real-time error handling** - handle API failures gracefully
- **Portfolio reconciliation** - verify on-chain positions
- **Historical accuracy** - track yield performance over time

## Getting Help

For advanced features and customization:
- [DeFi Yield Strategy Guide](references/yield-strategies.md)
- [Risk Assessment Framework](references/risk-scoring.md)
- [Chain Gas Optimization](references/gas-optimization.md)
- [Portfolio Rebalancing](references/rebalancing.md)

FILE:clawhub.json
{
  "name": "defi-yield-optimizer",
  "displayName": "DeFi Yield Farming Optimizer",
  "version": "1.0.0",
  "description": "Professional DeFi yield farming optimizer with multi-chain tracking, ROI calculations, risk assessment, and portfolio management across Ethereum, Polygon, BSC, Arbitrum, Optimism, and more.",
  "author": "ahmed181283",
  "license": "MIT",
  "pricing": {
    "model": "subscription",
    "price": 14900,
    "interval": "monthly"
  },
  "tags": ["defi", "yield-farming", "crypto", "ethereum", "polygon", "bsc", "arbitrum", "optimism", "portfolio", "roi"],
  "minOpenClawVersion": "1.0.0",
  "category": "financial"
}

---
name: word-to-pdf
description: Convert Word documents (.docx) to PDF format while preserving embedded images, formatting, and document structure. Use when user needs to convert Word files to PDF, batch convert documents, or maintain visual fidelity when converting DOCX files with images, tables, and complex formatting.
---

# Word to PDF Converter

## Quick Start

This skill converts Word documents (.docx) to PDF format, preserving embedded images, formatting, tables, and document structure.

## When to Use This Skill

Use this skill when you need to:
- Convert Word documents to PDF with images intact
- Batch convert multiple .docx files to PDF
- Preserve document formatting during conversion
- Handle Word files with embedded images, charts, or complex layouts
- Generate PDFs from Word templates or reports

## Conversion Methods

### Method 1: LibreOffice (Recommended)
**Best for:** Complex documents, highest fidelity, cross-platform
**Requirements:** LibreOffice installed
**Pros:** Free, handles complex formatting well, excellent image support
**Cons:** Requires LibreOffice installation

### Method 2: Python (python-docx + reportlab)
**Best for:** Programmatic conversion, custom formatting
**Requirements:** Python with specific libraries
**Pros:** Highly customizable, no external dependencies
**Cons:** More complex setup, may miss some formatting

### Method 3: Pandoc
**Best for:** Text-heavy documents, simple conversion
**Requirements:** Pandoc installed
**Pros:** Fast, widely available
**Cons:** Limited image support, basic formatting

### Method 4: docx2pdf (Python)
**Best for:** Quick conversions, good image support
**Requirements:** Python with docx2pdf library
**Pros:** Easy setup, good for most documents
**Cons:** May struggle with very complex layouts

## Usage

### Basic Conversion
```
Convert document.docx to PDF
```

### Batch Conversion
```
Convert all .docx files in current directory to PDF
```

### Custom Output
```
Convert report.docx to PDF and name it monthly-report.pdf
```

## Installation & Setup

### LibreOffice Method
```bash
# Install LibreOffice
sudo apt-get install libreoffice

# Or on macOS
brew install --cask libreoffice

# Or on Windows
# Download from libreoffice.org
```

### Python Method
```bash
# Install required libraries
pip install python-docx reportlab pillow

# Or use docx2pdf
pip install docx2pdf
```

### Pandoc Method
```bash
# Install pandoc
sudo apt-get install pandoc

# Or on macOS
brew install pandoc
```

## Conversion Commands

### LibreOffice (Recommended)
```bash
# Single file conversion
libreoffice --headless --convert-to pdf document.docx

# Specify output directory
libreoffice --headless --convert-to pdf --outdir ./pdfs document.docx

# Batch convert
for file in *.docx; do
    libreoffice --headless --convert-to pdf "$file"
done
```

### Python Method
```python
from docx import Document
from docx2pdf import convert

# Convert with images preserved
convert("document.docx", "output.pdf")
```

### Pandoc Method
```bash
# Basic conversion (limited image support)
pandoc document.docx -o output.pdf

# With better formatting
pandoc document.docx -o output.pdf --pdf-engine=xelatex
```

## Features & Capabilities

### What Gets Preserved
- Embedded images and screenshots
- Tables and cell formatting
- Headers, footers, and page numbers
- Font styles (bold, italic, underline)
- Document structure and headings
- Bullet points and numbered lists
- Page layout and margins

### Known Limitations
- Very complex macros may not convert perfectly
- Some advanced Word features may have PDF equivalents
- Custom fonts may need to be installed
- Extremely large documents may need memory tuning

## Troubleshooting

### Images Not Appearing
1. Check that images are embedded, not linked
2. Verify LibreOffice can open the source .docx
3. Try LibreOffice method (best image support)
4. Check disk space for large files

### Formatting Issues
1. LibreOffice method provides best results
2. Verify document isn't corrupted
3. Try opening in Word first to fix issues
4. Use headless mode to avoid UI conflicts

### Memory Issues with Large Files
```bash
# Increase LibreOffice memory (Linux)
soffice --headless -accept="socketsocket,host=localhost,port=2002;urp;" -nologo -nodefault -nofirststartwizard -nolockcheck -norestore -nocrashreport -nocrashreport -headless -invisible -convert-to pdf -nocrashreport -outdir /output /input

# Or split large document into parts before conversion
```

### Font Issues
- Install required system fonts
- Use common fonts (Arial, Times, Helvetica) for better compatibility
- Check LibreOffice font folder

## Advanced Usage

### Custom PDF Settings (LibreOffice)
```bash
# Export with specific settings
libreoffice --headless --convert-to pdf:writer_pdf_Export --infilter="writer_pdf_Export" document.docx
```

### Python Script for Batch Processing
```python
import os
from docx2pdf import convert

def convert_folder(input_dir, output_dir):
    os.makedirs(output_dir, exist_ok=True)
    for file in os.listdir(input_dir):
        if file.endswith('.docx'):
            input_path = os.path.join(input_dir, file)
            output_path = os.path.join(output_dir, file.replace('.docx', '.pdf'))
            convert(input_path, output_path)
            print(f"Converted: {file}")

convert_folder('./docs', './pdfs')
```

## Quality Checklist

Before final conversion:
- [ ] Source .docx opens without errors
- [ ] Images are embedded (not external links)
- [ ] Required fonts are installed
- [ ] Sufficient disk space available
- [ ] Test conversion with similar document first
- [ ] Verify output PDF matches expected formatting

## Output Quality Tips

1. **Test First:** Always convert a sample document first
2. **Use LibreOffice:** Best method for fidelity
3. **Check Images:** Verify images appear correctly in output
4. **Batch Test:** Test one file before batch conversion
5. **Keep Originals:** Never delete source .docx files until PDF verified

## Getting Help

For detailed conversion options and troubleshooting:
- [LibreOffice Command Reference](references/libreoffice-reference.md)
- [Python docx2pdf Documentation](references/python-docx2pdf.md)
- [Common Conversion Issues](references/troubleshooting.md)

FILE:clawhub.json
{
  "name": "word-to-pdf",
  "displayName": "Word to PDF Converter",
  "version": "1.0.0",
  "description": "Convert Word documents (.docx) to PDF format while preserving embedded images, formatting, and document structure. Multiple conversion methods included.",
  "author": "ahmed181283",
  "license": "MIT",
  "pricing": {
    "model": "one-time",
    "price": 2499
  },
  "tags": ["pdf", "word", "docx", "conversion", "documents", "images", "formatting"],
  "minOpenClawVersion": "1.0.0",
  "category": "document-processing"
}

---
name: daily-technology
description: Generate daily technology news content and TikTok scripts using free tech news sources. Use when user wants to create content about tech news, product launches, startups, AI developments, or technology industry updates from the last 24 hours.
---

# Daily Technology Content Generator

## Quick Start

This skill generates 60-90 second TikTok scripts and social media content about major technology events from the past 24 hours using free news sources.

## When to Use This Skill

Use this skill when you need to:
- Generate TikTok scripts about today's tech news
- Create daily technology content for social media
- Cover product launches and gadget releases
- Report on AI, startups, and tech industry trends
- Produce content about software updates, apps, or cybersecurity

## Features

### News Gathering
- **Free RSS feeds** from major tech news sources
- **Category filtering** (AI, startups, gadgets, software, cybersecurity, space tech)
- **Topic categorization** (product launches, funding, acquisitions, research)
- **Daily aggregation** of significant tech events

### Technology Analysis
- **Innovation impact scoring** (1-10 scale)
- **Startup funding tracking**
- **Product release significance**
- **AI advancement metrics**

### TikTok Script Generation
- **60-90 second optimized** scripts
- **Exciting product reveals**
- **Tech trend explanations**
- **Viral hashtags** and trending topics
- **Platform-optimized** formatting

## Usage

### Basic Usage
```
Generate today's technology TikTok scripts
```

### Advanced Usage
```
Generate 3 TikTok scripts about AI developments from the last 24 hours
Focus on product launches and startup news
Include hashtags: #tech #technology #AI #startup
```

### Category-Specific
```
Create daily smartphone tech news schedule
```

## Supported News Sources (Free)

- TechCrunch RSS
- The Verge RSS
- Ars Technica RSS
- Wired RSS
- MIT Technology Review RSS
- Engadget RSS
- VentureBeat RSS
- AI News RSS

## Output Formats

### TikTok Script Structure
```
🚀 Hook: (3-5 seconds) Exciting tech reveal or breakthrough
💻 Context: (10-15 seconds) Company, product, or technology
📰 News: (30-45 seconds) Product launches, funding, or tech updates
💡 Impact: (10-15 seconds) Why this matters for the industry
📈 Next: (5 seconds) Upcoming releases or industry trends

#hashtags: #tech #technology #[category] #[company] #[product]
```

## Configuration

### Category Focus
Edit `config/categories.yaml` to prioritize specific tech areas (AI, startups, gadgets, etc.).

### Topic Preferences
Edit `config/topics.yaml` to customize content categories (products, funding, research, acquisitions).

### Scheduling
Use `config/schedule.yaml` for automated daily reports.

## Templates

- `templates/tiktok-script.yaml` - Script structure template
- `templates/hashtags.yaml` - Trending hashtag database
- `templates/product-launch.yaml` - Product release template

## Getting Help

For detailed setup and customization:
- [News Sources Guide](references/news-sources.md)
- [TikTok Best Practices](references/tiktok-best-practices.md)
- [Technology Taxonomy](references/tech-taxonomy.md)

FILE:clawhub.json
{
  "name": "daily-technology",
  "displayName": "Daily Technology Content Generator",
  "version": "1.1.0",
  "description": "Generate 60-90 second TikTok scripts about technology news, AI developments, product launches, and tech industry trends using free tech news sources.",
  "author": "ahmed181283",
  "license": "MIT",
  "pricing": {
    "model": "subscription",
    "price": 2999,
    "interval": "monthly"
  },
  "tags": ["technology", "tech", "AI", "tiktok", "content", "startups", "product-launches", "innovation"],
  "minOpenClawVersion": "1.0.0",
  "category": "content-generation"
}

---
name: daily-cinema
description: Generate daily cinema and film industry content and TikTok scripts using free entertainment news sources. Use when user wants to create content about movie releases, film news, celebrity updates, box office results, or entertainment industry developments from the last 24 hours.
---

# Daily Cinema Content Generator

## Quick Start

This skill generates 60-90 second TikTok scripts and social media content about major cinema and film industry events from the past 24 hours using free news sources.

## When to Use This Skill

Use this skill when you need to:
- Generate TikTok scripts about today's cinema news
- Create daily entertainment content for social media
- Cover new movie releases and trailers
- Report on celebrity news and Hollywood updates
- Produce content about box office results, awards, or film industry trends

## Features

### News Gathering
- **Free RSS feeds** from major entertainment news sources
- **Genre filtering** (action, comedy, drama, horror, sci-fi, romance, etc.)
- **Topic categorization** (releases, box office, celebrity, awards, streaming)
- **Daily aggregation** of significant cinema events

### Cinema Analysis
- **Movie hype scoring** (1-10 scale)
- **Box office performance** tracking
- **Celebrity trend identification**
- **Streaming platform** availability updates

### TikTok Script Generation
- **60-90 second optimized** scripts
- **Exciting trailer reveals**
- **Behind-the-scenes highlights**
- **Viral hashtags** and trending topics
- **Platform-optimized** formatting

## Usage

### Basic Usage
```
Generate today's cinema TikTok scripts
```

### Advanced Usage
```
Generate 3 TikTok scripts about new movie releases from the last 24 hours
Focus on box office results and streaming news
Include hashtags: #movies #cinema #entertainment
```

### Genre-Specific
```
Create daily horror movie news schedule
```

## Supported News Sources (Free)

- Variety RSS
- Hollywood Reporter RSS
- Deadline Hollywood RSS
- IMDb News RSS
- Entertainment Weekly RSS
- Box Office Mojo RSS
- Rotten Tomatoes News RSS

## Output Formats

### TikTok Script Structure
```
🎬 Hook: (3-5 seconds) Movie trailer excitement or breaking film news
🎥 Context: (10-15 seconds) Film, genre, and significance
📰 News: (30-45 seconds) Release updates, celebrity news, or industry trends
💡 Impact: (10-15 seconds) Why this matters for film fans
📈 Next: (5 seconds) Upcoming releases or award ceremonies

#hashtags: #movies #cinema #entertainment #[genre] #[actor] #[film]
```

## Configuration

### Genre Focus
Edit `config/genres.yaml` to prioritize specific film genres.

### Topic Preferences
Edit `config/topics.yaml` to customize content categories (releases, box office, celebrity, awards).

### Scheduling
Use `config/schedule.yaml` for automated daily reports.

## Templates

- `templates/tiktok-script.yaml` - Script structure template
- `templates/hashtags.yaml` - Trending hashtag database
- `templates/movie-release.yaml` - New film release template

## Getting Help

For detailed setup and customization:
- [News Sources Guide](references/news-sources.md)
- [TikTok Best Practices](references/tiktok-best-practices.md)
- [Cinema Taxonomy](references/cinema-taxonomy.md)

FILE:clawhub.json
{
  "name": "daily-cinema",
  "displayName": "Daily Cinema Content Generator",
  "version": "1.1.0",
  "description": "Generate 60-90 second TikTok scripts about movies, film industry, celebrity news, and entertainment using free entertainment news sources.",
  "author": "ahmed181283",
  "license": "MIT",
  "pricing": {
    "model": "subscription",
    "price": 1499,
    "interval": "monthly"
  },
  "tags": ["cinema", "movies", "film", "entertainment", "tiktok", "content", "box-office", "celebrity-news"],
  "minOpenClawVersion": "1.0.0",
  "category": "content-generation"
}

---
name: daily-worldcup2026
description: Generate daily FIFA World Cup 2026 content and TikTok scripts using free news sources. Use when user wants to create content about World Cup 2026 preparations, qualifiers, team news, host cities, or tournament developments from the last 24 hours.
---

# Daily World Cup 2026 Reporter

## Quick Start

This skill generates 60-90 second TikTok scripts and social media content about FIFA World Cup 2026 events from the past 24 hours using free news sources.

## When to Use This Skill

Use this skill when you need to:
- Generate TikTok scripts about World Cup 2026 news
- Create daily World Cup content for social media
- Cover qualifying matches and standings
- Report on team preparations and player selections
- Produce content about host cities, venues, and infrastructure

## Features

### News Gathering
- **Free RSS feeds** from FIFA and major sports sources
- **Regional qualifier tracking** (UEFA, CONMEBOL, CAF, AFC, CONCACAF, OFC)
- **Topic categorization** (qualifiers, host preparations, squads, venues)
- **Daily aggregation** of World Cup 2026 developments

### Tournament Analysis
- **Match qualification probability** tracking
- **Host city readiness** updates
- **Team squad announcements**
- **Venue construction** and stadium progress

### TikTok Script Generation
- **60-90 second optimized** scripts
- **Exciting qualifier highlights**
- **Host city reveals** and venue features
- **Viral hashtags** and trending topics
- **Platform-optimized** formatting

## Usage

### Basic Usage
```
Generate today's World Cup 2026 TikTok scripts
```

### Advanced Usage
```
Generate 3 TikTok scripts about European qualifiers from the last 24 hours
Focus on host city preparations
Include hashtags: #WorldCup2026 #FIFA #football
```

### Regional-Specific
```
Create daily CONCACAF qualifier report
```

## Supported News Sources (Free)

- FIFA.com World Cup 2026 RSS
- Reuters World Cup News
- ESPN World Cup Coverage
- BBC Sport World Cup RSS
- The Athletic World Cup 2026
- Goal.com World Cup Coverage

## Output Formats

### TikTok Script Structure
```
🏆 Hook: (3-5 seconds) World Cup excitement or qualifier drama
🌍 Context: (10-15 seconds) Confederation, teams, stakes
📰 News: (30-45 seconds) Qualifier updates, prep news, or venue reveals
💡 Impact: (10-15 seconds) What this means for WC 2026
📈 Next: (5 seconds) Upcoming qualifiers or countdown

#hashtags: #WorldCup2026 #FIFA #[confederation] #[team] #[topic]
```

## Configuration

### Confederation Focus
Edit `config/confederations.yaml` to prioritize specific qualifier regions (UEFA, CONMEBOL, etc.).

### Topic Preferences
Edit `config/topics.yaml` to customize content categories (qualifiers, venues, squads, prep).

### Scheduling
Use `config/schedule.yaml` for automated daily reports.

## Templates

- `templates/tiktok-script.yaml` - Script structure template
- `templates/hashtags.yaml` - Trending hashtag database
- `templates/qualifier-summary.yaml` - Match result template

## Getting Help

For detailed setup and customization:
- [News Sources Guide](references/news-sources.md)
- [TikTok Best Practices](references/tiktok-best-practices.md)
- [World Cup 2026 Timeline](references/wc2026-timeline.md)

FILE:clawhub.json
{
  "name": "daily-worldcup2026",
  "displayName": "Daily World Cup 2026 Reporter",
  "version": "1.1.0",
  "description": "Generate TikTok scripts about FIFA World Cup 2026 qualifiers, host preparations, team news, and tournament developments using free sports news sources.",
  "author": "ahmed181283",
  "license": "MIT",
  "pricing": {
    "model": "subscription",
    "price": 2499,
    "interval": "monthly"
  },
  "tags": ["world-cup-2026", "fifa", "football", "soccer", "tiktok", "content", "qualifiers", "tournament"],
  "minOpenClawVersion": "1.0.0",
  "category": "content-generation"
}

---
name: daily-soccer
description: Generate daily soccer/football news content and TikTok scripts using free sports news sources. Use when user wants to create content about football matches, transfers, player news, league updates, or FIFA competitions from the last 24 hours.
---

# Daily Soccer Content Generator

## Quick Start

This skill generates 60-90 second TikTok scripts and social media content about major soccer/football events from the past 24 hours using free news sources.

## When to Use This Skill

Use this skill when you need to:
- Generate TikTok scripts about today's soccer/football news
- Create daily sports content for social media
- Summarize match results and upcoming fixtures
- Cover transfer news and player movements
- Produce content about leagues, cups, or international competitions

## Features

### News Gathering
- **Free RSS feeds** from major sports news sources
- **League filtering** (Premier League, La Liga, Serie A, Bundesliga, Ligue 1, MLS, etc.)
- **Topic categorization** (matches, transfers, injuries, management)
- **Daily aggregation** of significant football events

### Soccer Analysis
- **Match significance scoring** (1-10 scale)
- **Transfer impact evaluation**
- **League standing updates**
- **Player performance metrics**

### TikTok Script Generation
- **60-90 second optimized** scripts
- **Exciting match highlights** and key moments
- **Viral hashtags** and trending topics
- **Platform-optimized** formatting

## Usage

### Basic Usage
```
Generate today's soccer TikTok scripts
```

### Advanced Usage
```
Generate 3 TikTok scripts about Premier League matches from the last 24 hours
Focus on transfers and player news
Include hashtags: #football #soccer #premierleague
```

### League-Specific
```
Create daily La Liga soccer report schedule
```

## Supported News Sources (Free)

- ESPN Soccer RSS
- BBC Sport Football RSS
- Reuters Soccer News
- Goal.com RSS
- FIFA.com News
- UEFA.com News
- Sky Sports Football RSS

## Output Formats

### TikTok Script Structure
```
⚽ Hook: (3-5 seconds) Exciting opening about match or player
🏟️ Context: (10-15 seconds) League, teams, and situation
📰 News: (30-45 seconds) Match highlights, transfers, or key updates
💡 Impact: (10-15 seconds) What this means for the team/league
📈 Next: (5 seconds) Upcoming matches or transfer window dates

#hashtags: #football #soccer #[league] #[team] #[topic]
```

## Configuration

### League Focus
Edit `config/leagues.yaml` to prioritize specific leagues.

### Topic Preferences
Edit `config/topics.yaml` to customize content categories (matches, transfers, injuries, management).

### Scheduling
Use `config/schedule.yaml` for automated daily reports.

## Templates

- `templates/tikTok-script.yaml` - Script structure template
- `templates/hashtags.yaml` - Trending hashtag database
- `templates/match-summary.yaml` - Match result template

## Getting Help

For detailed setup and customization:
- [News Sources Guide](references/news-sources.md)
- [TikTok Best Practices](references/tiktok-best-practices.md)
- [Soccer Taxonomy](references/soccer-taxonomy.md)

FILE:clawhub.json
{
  "name": "daily-soccer",
  "displayName": "Daily Soccer Content Generator",
  "version": "1.1.0",
  "description": "Generate 60-90 second TikTok scripts about soccer/football news using free RSS feeds. Covers Premier League, La Liga, Serie A, Champions League, and more.",
  "author": "ahmed181283",
  "license": "MIT",
  "pricing": {
    "model": "subscription",
    "price": 1999,
    "interval": "monthly"
  },
  "tags": ["soccer", "football", "tiktok", "content", "sports", "premier-league", "la-liga", "champions-league"],
  "minOpenClawVersion": "1.0.0",
  "category": "content-generation"
}

---
name: quiz-generator
description: Generate quizzes and assessments from any topic or content. Create questions of varying difficulty (easy, medium, hard), multiple formats (multiple choice, true/false, fill-in-blank), with answers and detailed explanations. Use when the user asks to create a quiz, test knowledge, generate questions, or build assessments.
---

# Quiz Generator

## Overview

Generate comprehensive quizzes from topics, documents, or learning materials. Include questions of varying difficulty, different question formats, correct answers, and detailed explanations to reinforce learning.

## Quiz Structure

### Required Elements

1. **Quiz Title and Description**
   - Clear, descriptive title
   - Topic focus
   - Target audience level
   - Estimated completion time
   - Question count

2. **Questions**
   Each question must include:
   - Question text
   - Question difficulty (easy/medium/hard)
   - Question type (see formats below)
   - Correct answer(s)
   - Detailed explanation
   - Optional: reference to source material

3. **Answer Key**
   - Quick reference for all correct answers
   - Usually at the end of the quiz

4. **Scoring Guide** (optional)
   - How many points per question
   - What score indicates mastery
   - Recommended follow-up based on score ranges

### Question Formats

#### Multiple Choice (default)
- 3-5 answer options (1 correct, others plausible distractors)
- Label options A, B, C, D, E
- Distractors should be common misconceptions

#### True/False
- Statement to evaluate
- Explanation for why it's true or false

#### Fill-in-the-Blank
- Sentence or statement with blank(s)
- Case-insensitive matching preferred
- List acceptable alternative answers

#### Short Answer
- Open-ended question
- Provide example acceptable answers
- Explain key points that should be included

#### Matching
- Two columns to match (terms to definitions, dates to events, etc.)
- Indicate the relationship clearly

## Difficulty Guidelines

### Easy
- Basic facts, definitions, terminology
- Direct recall from source material
- Should be answerable after one pass through material
- Example: "What does API stand for?"

### Medium
- Requires understanding concepts, not just facts
- Inference or application of knowledge
- May require connecting multiple pieces of information
- Example: "Which HTTP method would you use to update an existing resource?"

### Hard
- Requires synthesis, analysis, or critical thinking
- Complex scenarios or edge cases
- Comparison or evaluation of options
- Example: "Compare REST and GraphQL architectures for a real-time chat application."

## Writing Guidelines

### Question Quality
- Ensure each question tests something meaningful
- Avoid ambiguous phrasing
- Make questions independent (don require previous answers)
- Balance question types and difficulty levels
- Include 10-20 questions for a comprehensive quiz

### Explanations
- Explain not just the correct answer, but why alternatives are wrong
- Reference the source material when applicable
- Add additional context or related concepts
- Help the learner understand, not just memorize

### Distractor Generation
- Create plausible wrong answers
- Use common misconceptions or errors
- Avoid "all of the above" or "none of the above" (become guesswork)
- Keep distractors similar in length and tone to correct answer

## Example Question

```markdown
### Question 3 (Medium)
What is the primary purpose of environment variables in application configuration?

A) To store sensitive credentials securely
B) To configure application behavior across environments
C) To manage database connections
D) To handle user authentication

**Correct Answer:** B

**Explanation:** Environment variables allow applications to be configured differently across development, testing, and production environments without changing code. While they can store credentials (A), their primary purpose is configuration flexibility. Database connections (C) and authentication (D) are specific use cases, not the primary purpose.
```

## Generation Workflow

1. **Understand the Source**
   - Read the topic or provided material
   - Identify key concepts, facts, and relationships
   - Note common pitfalls or misconceptions

2. **Plan Question Distribution**
   - Target: 40% easy, 40% medium, 20% hard
   - Mix question types based on content
   - Ensure coverage of all key topics

3. **Generate Questions**
   - Draft questions with answers and explanations
   - Review for clarity and accuracy
   - Check that explanations actually explain

4. **Review and Refine**
   - Remove redundant or overlapping questions
   - Ensure difficulty is consistent
   - Verify all answers are correct
   - Add a practice question or bonus if appropriate

## Output Format

Deliver the quiz in the user's preferred format:
- Markdown (default) - with sections clearly marked
- JSON - for programmatic use or quiz platforms
- Plain text - for simple assessments

### JSON Format Example

```json
{
  "title": "Web Development Fundamentals Quiz",
  "description": "Test your knowledge of HTML, CSS, and JavaScript basics",
  "questions": [
    {
      "id": 1,
      "difficulty": "easy",
      "type": "multiple_choice",
      "question": "What does HTML stand for?",
      "options": [
        "Hyper Text Markup Language",
        "High Tech Modern Language",
        "Hyper Transfer Markup Language",
        "Home Tool Markup Language"
      ],
      "correct_answer": 0,
      "explanation": "HTML stands for Hyper Text Markup Language. It's the standard markup language for creating web pages."
    }
  ],
  "answer_key": {
    "1": "A"
  }
}
```

## Quality Checklist

Before finalizing a quiz, verify:

- [ ] All questions are clear and unambiguous
- [ ] Correct answers are accurate
- [ ] Explanations are helpful and educational
- [ ] Difficulty levels are appropriate for audience
- [ ] Question types are varied
- [ ] Key topics from source are covered
- [ ] Distractors are plausible but clearly wrong
- [ ] Quiz title and description are informative
- [ ] Answer key is complete and accurate

---
name: tutorial-builder
description: Generate comprehensive step-by-step tutorials for tools, workflows, and technical topics. Use when the user asks to create a tutorial, write a guide, explain how to use something, or document a process. Includes structure for prerequisites, installation, steps, examples, and troubleshooting.
---

# Tutorial Builder

## Overview

Create clear, actionable tutorials that guide readers through complex tasks. Structure content logically with prerequisites, step-by-step instructions, code examples, and troubleshooting tips.

## Tutorial Structure

Always include these sections (adapt to the topic):

### 1. Title and Description
- Clear, descriptive title
- One-sentence summary of what the tutorial covers
- Target audience (beginner, intermediate, advanced)
- Estimated time to complete

### 2. Prerequisites
- List required skills, knowledge, or tools
- Include version numbers if applicable
- Add links to prerequisite tutorials or documentation

### 3. Installation/Setup (if applicable)
- Step-by-step installation instructions
- Include commands with expected output examples
- Address common installation issues
- Verification step to confirm setup worked

### 4. Core Tutorial Steps
Numbered steps with:
- Clear action verbs ("Create", "Configure", "Deploy")
- Command examples with prompts (`$` for user commands, `#` for root)
- Code blocks with syntax highlighting notes
- Explanation of what each step does and why
- Expected outputs or results

### 5. Examples and Use Cases
- Real-world examples
- Variations and common modifications
- Integration examples with other tools

### 6. Troubleshooting
- Common errors and solutions
- Debugging tips
- Where to get help (forums, docs, community)

### 7. Next Steps
- Recommended follow-up tutorials
- Advanced topics to explore
- Related resources

## Writing Guidelines

### Tone and Style
- Be direct and concise. Avoid filler words.
- Assume the reader is smart but unfamiliar with the topic.
- Explain the "why" behind steps, not just the "how."
- Use consistent terminology throughout.

### Code and Commands
- Show the complete command, not fragments.
- Include prompts (`$`, `#`, `>`) to distinguish command types.
- Add comments for complex commands (`# comment`).
- Show expected output when it helps verify success.

### Examples
```bash
# Install the package
$ npm install package-name

# Verify installation
$ package-name --version
v1.2.3
```

```yaml
# Configure settings in config.yaml
database:
  host: localhost
  port: 5432
```

### Formatting
- Use **bold** for key commands, file names, and important terms
- Use `code` for inline code, variables, and short commands
- Use blockquotes for warnings or notes:
  > **Note:** This step requires sudo privileges.
- Use numbered lists for sequential steps
- Use bullet points for non-sequential items

### Common Patterns

#### For Software Installation
1. Check for existing installation
2. Download or clone
3. Install with package manager or build from source
4. Configure if needed
5. Verify installation
6. Add to PATH if required

#### For Configuration Tasks
1. Locate configuration file
2. Backup existing configuration
3. Edit with specific settings
4. Validate configuration
5. Reload or restart service
6. Test configuration

#### For Development Workflows
1. Set up development environment
2. Create project structure
3. Write initial code/templates
4. Test basic functionality
5. Add features incrementally
6. Document and commit

## Quality Checklist

Before finalizing a tutorial, verify:

- [ ] All steps are numbered and sequential
- [ ] Every command is complete and copy-paste ready
- [ ] Code examples match the text description
- [ ] Troubleshooting section addresses common issues
- [ ] Prerequisites are clearly listed
- [ ] Links and references are accurate
- [ ] Steps are tested and verified to work
- [ ] Language is clear and jargon-free (or jargon is explained)

## Output Format

Deliver the tutorial in a format matching the user's preference:
- Markdown (default) - for documentation sites, Git repos, wikis
- Plain text - for simple documentation
- HTML - if creating web content

Ask the user if they have a preferred output format if not specified.

---
name: daily-geo-tiktok
description: Generate daily geopolitical TikTok scripts using free news sources. Use when user wants to create TikTok content about world events, conflicts, diplomacy, or geopolitical developments that happened in the last 24 hours.
---

# Daily Geopolitical TikTok Reporter

## Quick Start

This skill generates 60-90 second TikTok scripts about major geopolitical events from the past 24 hours using free news sources.

## When to Use This Skill

Use this skill when you need to:
- Generate TikTok scripts about today's geopolitical news
- Create daily world events content for social media
- Analyze and summarize geopolitical developments
- Produce short-form video content about international affairs

## Features

### News Gathering
- **Free RSS feeds** from major news sources
- **Regional filtering** (Middle East, Europe, Asia, Americas, Africa)
- **Topic categorization** (conflicts, diplomacy, elections, sanctions)
- **Daily aggregation** of significant events

### Geopolitical Analysis
- **Event importance scoring** (1-10 scale)
- **Geopolitical impact categorizing**
- **Regional relevance filtering**
- **Fact verification** and source attribution

### TikTok Script Generation
- **60-90 second optimized** scripts
- **Engaging hooks** and cliffhangers
- **Viral hashtags** and trending topics
- **Platform-optimized** formatting

## Usage

### Basic Usage
```
Generate today's geopolitical TikTok scripts
```

### Advanced Usage
```
Generate 3 TikTok scripts about Middle East events from the last 24 hours
Focus on conflicts and sanctions
Include hashtags: #geopolitics #worldnews #middleeast
```

### Scheduled Reports
```
Create daily geopolitical TikTok report schedule for 8 AM UTC
```

## Supported News Sources (Free)

- BBC World News RSS
- Reuters World RSS
- AP World News RSS
- Al Jazeera RSS
- Foreign Policy RSS
- Reuters Conflict News

## Output Formats

### TikTok Script Structure
```
🎵 Hook: (3-5 seconds) Attention-grabbing opening
🌍 Context: (10-15 seconds) Background and significance
📰 News: (30-45 seconds) Main story and developments
💡 Impact: (10-15 seconds) Why it matters
📈 Next: (5 seconds) What to watch for

#hashtags: #geopolitics #worldnews #[region] #[topic]
```

## Configuration

### Regional Focus
Edit `config/regions.yaml` to prioritize specific geographic areas.

### Topic Preferences
Edit `config/topics.yaml` to customize content categories.

### Scheduling
Use `config/schedule.yaml` for automated daily reports.

## Templates

- `templates/tiktok-script.yaml` - Script structure template
- `templates/hashtags.yaml` - Trending hashtag database

## Getting Help

For detailed setup and customization:
- [News Sources Guide](references/news-sources.md)
- [TikTok Best Practices](references/tiktok-best-practices.md)
- [Geopolitical Taxonomy](references/geo-taxonomy.md)
FILE:README.md
# 🌍 Daily Geopolitical TikTok Reporter

Generate daily TikTok scripts about geopolitical news using free RSS sources.

## 🚀 Quick Start

### 1. Install Dependencies

```bash
# Option A: Using virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Option B: System-wide (if allowed)
pip install --break-system-packages -r requirements.txt

# Option C: Using pipx
pipx install feedparser pyyaml python-dateutil requests
```

### 2. Generate Your First TikTok Script

```bash
# Basic usage - last 24 hours
python3 generate_daily_report.py

# Custom options
python3 generate_daily_report.py --hours 12 --scripts 5 --region middle_east

# Focus on specific topics
python3 generate_daily_report.py --topic conflicts --hours 6
```

### 3. Review Generated Scripts

Scripts are saved in `generated_scripts_[timestamp]/` directory:
- Individual story scripts (1_second_story_title.txt, etc.)
- Daily report script (daily_report.txt)
- Metadata JSON file

## 📋 Usage Examples

### Generate scripts for last 12 hours:
```bash
python3 generate_daily_report.py --hours 12
```

### Focus on Middle East conflicts:
```bash
python3 generate_daily_report.py --region middle_east --topic conflicts
```

### Generate 5 high-importance stories:
```bash
python3 generate_daily_report.py --scripts 5 --hours 48
```

## ⛙ Configuration

Edit `config/config.yaml` to customize:

- **News sources**: Add custom RSS feeds
- **Regional focus**: Prioritize specific geographic areas  
- **Topic preferences**: Focus on conflicts, diplomacy, elections, etc.
- **TikTok style**: Adjust script timing, tone, and hashtags
- **Scheduling**: Set up automated daily reports

## 📤 Automating Daily Reports

### Using Cron (Linux/macOS):
```bash
# Edit crontab
crontab -e

# Add this line (runs every day at 8 AM UTC)
0 8 * * * cd /path/to/skill && python3 generate_daily_report.py --scripts 3
```

### Using Systemd Timer (Linux):
```bash
# Create service file at /etc/systemd/system/geo-tiktok.service
# See config/config.yaml for example
```

### Using OpenClaw Heartbeat:
Add to your workspace HEARTBEAT.md:
```markdown
- Check for new geopolitical news
- Generate daily TikTok scripts if significant events found
```

## 📊 Sample Output

Each generated TikTok script includes:

- 🎵 **Hook** (3-5 seconds): Attention-grabbing opening
- 🌍 **Context** (10-15 seconds): Background and significance  
- 📰 **News** (30-45 seconds): Main story and developments
- 💡 **Impact** (10-15 seconds): Why it matters
- 📈 **Next** (5 seconds): What to watch for
- 🏷️ **Hashtags**: Optimized for TikTok discovery

## 🎯 Next Steps

1. **Review generated scripts** in output directory
2. **Customize content** to match your style
3. **Create TikTok videos** using the scripts
4. **Post strategically** during peak hours
5. **Engage with audience** in comments
6. **Schedule daily generation** for consistent content

## 💡 Pro Tips

- **Peak posting times**: 12 PM, 7 PM local time
- **Trending sounds**: Search "news," "break," "intense" in TikTok library
- **Visuals**: Use stock footage, maps, news clips
- **Engagement**: Reply to comments in first 30 minutes
- **Consistency**: Post daily for algorithm favorability

## 🛠️ Troubleshooting

### ModuleNotFoundError: No module named 'feedparser'
```bash
# Install dependencies properly
pip install -r requirements.txt
```

### No news articles found
- Check your internet connection
- Verify RSS sources are accessible
- Try increasing --hours parameter
- Check if news sources require authentication

### Scripts too long/short
- Edit `config/config.yaml` timing section
- Adjust individual segment durations
- Target total 60-90 seconds for optimal TikTok performance

## 📚 Advanced Usage

### Custom RSS Sources
Edit `config/config.yaml`:
```yaml
news_gathering:
  custom_sources:
    my_source:
      url: "https://example.com/rss.xml"
      region: "asia"
      name: "My Custom News"
```

### Custom Hashtag Strategy
Edit `content_gen/tiktok_generator.py`:
- Add custom hooks in `HOOKS` list
- Add hashtags to `HASHTAGS` dictionary
- Modify transition phrases in `TRANSITIONS`

### Regional Filtering
Available regions:
- `middle_east`, `europe`, `asia`, `americas`, `africa`

### Topic Filtering  
Available topics:
- `conflicts`, `diplomacy`, `sanctions`, `elections`, `alliances`, `crisis`

## 🌐 Integration with Other Platforms

### Blog Integration
Modify script to also generate blog posts in Markdown format.

### YouTube Shorts
Use same scripts but format for YouTube Shorts (max 60 seconds).

### Custom Website
Generate JSON/HTML output for your own website.

## 📞 Support

For issues or questions:
1. Check this README
2. Review config files
3. Examine error logs
4. Check network connectivity

---

**Skill Version:** 1.0.0  
**Created for:** TikTok content creators focused on geopolitics  
**License:** MIT

Enjoy creating engaging geopolitical content! 🌍🎬
FILE:config/config.yaml
# Daily Geopolitical TikTok Reporter Configuration

# News gathering settings
news_gathering:
  hours_back: 24
  max_articles_per_source: 10
  min_importance_score: 3
  
  # Custom RSS sources (optional)
  custom_sources:
    # source_name:
    #   url: "https://example.com/rss.xml"
    #   region: "global"
    #   name: "Custom News Source"

# Geopolitical filtering
filters:
  # Prioritize these regions (leave empty for all regions)
  priority_regions:
    - middle_east
    - europe
    - asia
    - americas
    - africa
  
  # Focus on these topics (leave empty for all topics)
  focus_topics:
    - conflicts
    - diplomacy
    - sanctions
    - elections
    - alliances
    - crisis
  
  # Minimum importance score for stories
  min_importance: 5

# TikTok script generation
tiktok_generation:
  # Script timing (in seconds)
  timing:
    hook: 3-5
    context: 10-15
    news: 30-45
    impact: 10-15
    next: 5
  
  # Hashtag strategy
  hashtags:
    max_per_script: 8
    use_trending: true
    include_source_hashtags: true
  
  # Content style
  style:
    tone: "engaging"
    complexity: "accessible"
    add_pro_tips: true
    include_suggested_visuals: true

# Output settings
output:
  directory: "generated_scripts"
  timestamp_format: "%Y-%m-%d_%H-%M"
  save_metadata: true
  save_individual_scripts: true
  save_daily_report: true

# Scheduling (for automated execution)
schedule:
  enabled: false
  daily_time: "08:00"  # 8 AM
  timezone: "UTC"
  number_of_scripts: 3
  
  # Scheduling method
  method: "cron"  # or "heartbeat"
  
  # If using cron
  cron_expression: "0 8 * * *"  # Daily at 8 AM

# Optional: Platform-specific settings
platforms:
  tiktok:
    suggested_posting_times:
      - "12:00"  # Noon
      - "19:00"  # 7 PM
    use_trending_sounds: true
    recommended_music_genres:
      - "news"
      - "dramatic"
      - "intense"
  
  youtube:
    enable_shorts: true
    shorts_duration: 60
FILE:content_gen/tiktok_generator.py
"""
Daily Geopolitical TikTok Reporter - TikTok Script Generator
Converts geopolitical news into engaging 60-90 second TikTok scripts
"""

from datetime import datetime
from typing import List, Dict, Any
import random

class TikTokGeoScriptGenerator:
    """Generate optimized TikTok scripts from geopolitical news"""
    
    # TikTok-style hooks for engagement
    HOOKS = [
        "🔥 Breaking right now",
        "⚠️ This changes everything",
        "🌍 What just happened",
        "😱 You won't believe this",
        "🚨 Major development",
        "💥 Breaking news",
        "📢 Important update",
        "🎯 Here's what matters",
        "🔊 Everyone's watching this",
        "⭐ The biggest story today"
    ]
    
    # Trending geopolitical hashtags
    HASHTAGS = {
        'general': ['#geopolitics', '#worldnews', '#geopolitical', '#breakingnews'],
        'conflicts': ['#war', '#conflict', '#military', '#geopolitics'],
        'diplomacy': ['#diplomacy', '#international', '#relations', '#politics'],
        'sanctions': ['#sanctions', '#economy', '#trade', '#geopolitics'],
        'elections': ['#election', '#politics', '#vote', '#democracy'],
        'middle_east': ['#middleeast', '#israel', '#palestine', '#geopolitics'],
        'europe': ['#europe', '#ukraine', '#russia', '#nato'],
        'asia': ['#asia', '#china', '#korea', '#geopolitics'],
        'americas': ['#usa', '#americas', '#politics', '#geopolitics'],
        'africa': ['#africa', '#african', '#geopolitics', '#news']
    }
    
    # Transition phrases for smooth flow
    TRANSITIONS = [
        "Here's what happened:",
        "Let me break this down:",
        "Here's the situation:",
        "Here's what you need to know:",
        "Here's the deal:",
        "This is what's going on:"
    ]
    
    # Impact statements for engagement
    IMPACT_STATEMENTS = [
        "This changes the regional balance.",
        "Experts are divided on what this means.",
        "This could escalate further.",
        "The international community is watching.",
        "This has long-term implications.",
        "Markets are reacting to this news.",
        "This could affect global relations.",
        "Allies are taking notice."
    ]
    
    # Next steps hooks for engagement
    NEXT_STEPS = [
        "Watch for updates in the next 24 hours.",
        "Expect statements from officials.",
        "This story is developing fast.",
        "Stay tuned for more developments.",
        "We'll know more by tomorrow."
    ]
    
    def __init__(self):
        """Initialize TikTok script generator"""
        self.generated_scripts = []
    
    def generate_single_story_script(self, story: Dict[str, Any]) -> Dict[str, Any]:
        """Generate a TikTok script for a single story
        
        Args:
            story: News article with metadata
        
        Returns:
            Generated script with timing and structure
        """
        hook = self._generate_hook(story)
        context = self._generate_context(story)
        news_content = self._generate_news_content(story)
        impact = self._generate_impact(story)
        next_step = self._generate_next_step(story)
        hashtags = self._generate_hashtags(story)
        
        script = {
            'title': story['title'],
            'source': story['source'],
            'importance': story['importance_score'],
            'segments': {
                'hook': hook,
                'context': context,
                'news': news_content,
                'impact': impact,
                'next': next_step
            },
            'hashtags': hashtags,
            'estimated_duration': self._estimate_duration(hook, context, news_content, impact, next_step),
            'full_script': self._assemble_full_script(hook, context, news_content, impact, next_step, hashtags)
        }
        
        self.generated_scripts.append(script)
        return script
    
    def generate_daily_report_script(self, stories: List[Dict[str, Any]]) -> Dict[str, Any]:
        """Generate a daily TikTok script covering multiple stories
        
        Args:
            stories: List of news articles (should be top 3-5)
        
        Returns:
            Generated daily report script
        """
        if not stories:
            return None
        
        # Hook
        hook = f"🌍 Today's top {len(stories)} geopolitical stories that matter"
        
        # Brief coverage of each story
        story_briefs = []
        for i, story in enumerate(stories, 1):
            brief = f"{i}. {self._truncate_to_seconds(story['title'], 15)}"
            story_briefs.append(brief)
        
        # Deep dive on top story
        top_story = stories[0]
        context = self._generate_context(top_story)
        news_content = self._generate_news_content(top_story)
        impact = self._generate_impact(top_story)
        
        # Quick mentions of other stories
        other_stories = "\n\n".join([
            f"Also: {story['title']}" 
            for story in stories[1:3]
        ]) if len(stories) > 1 else ""
        
        next_step = "Follow for daily geopolitical updates!"
        hashtags = self._generate_daily_report_hashtags()
        
        script = {
            'type': 'daily_report',
            'stories_count': len(stories),
            'segments': {
                'hook': hook,
                'stories_brief': story_briefs,
                'context': context,
                'news': news_content,
                'impact': impact,
                'other_stories': other_stories,
                'next': next_step
            },
            'hashtags': hashtags,
            'full_script': self._assemble_daily_report_script(
                hook, story_briefs, context, news_content, 
                impact, other_stories, next_step, hashtags
            )
        }
        
        return script
    
    def _generate_hook(self, story: Dict[str, Any]) -> str:
        """Generate attention-grabbing hook"""
        hook = random.choice(self.HOOKS)
        if story['importance_score'] >= 8:
            hook = "🔥 MAJOR BREAKING NEWS"
        return f"{hook}: {self._truncate_to_seconds(story['title'], 5)}"
    
    def _generate_context(self, story: Dict[str, Any]) -> str:
        """Generate background context"""
        transition = random.choice(self.TRANSITIONS)
        regions = story['relevance']['detected_regions']
        
        region_text = f"in {', '.join(regions)}" if regions else "globally"
        
        return f"{transition} This is happening {region_text} and has significant implications."
    
    def _generate_news_content(self, story: Dict[str, Any]) -> str:
        """Generate main news content"""
        # Extract key information from description
        description = story.get('description', '')
        
        # Create 30-45 second content
        content = self._truncate_to_seconds(description, 40)
        
        if story['source']:
            content += f"\n\nSource: {story['source']}"
        
        return content
    
    def _generate_impact(self, story: Dict[str, Any]) -> str:
        """Generate impact statement"""
        return random.choice(self.IMPACT_STATEMENTS)
    
    def _generate_next_step(self, story: Dict[str, Any]) -> str:
        """Generate next steps hook"""
        return random.choice(self.NEXT_STEPS)
    
    def _generate_hashtags(self, story: Dict[str, Any]) -> List[str]:
        """Generate relevant hashtags"""
        hashtags = ['#geopolitics', '#worldnews', '#breakingnews']
        
        # Add category-specific hashtags
        for category, score in story['relevance']['category_scores'].items():
            if score > 0 and category in self.HASHTAGS:
                hashtags.extend(self.HASHTAGS[category])
        
        # Add region-specific hashtags
        for region in story['relevance']['detected_regions']:
            if region in self.HASHTAGS:
                hashtags.extend(self.HASHTAGS[region])
        
        # Remove duplicates and limit
        hashtags = list(set(hashtags))[:8]
        return hashtags
    
    def _generate_daily_report_hashtags(self) -> List[str]:
        """Generate hashtags for daily report"""
        return [
            '#geopolitics', '#worldnews', '#dailynews', 
            '#geopolitical', '#breakingnews', '#international',
            '#worldupdate', '#newsdaily'
        ]
    
    def _truncate_to_seconds(self, text: str, target_seconds: int) -> str:
        """Truncate text to fit within target seconds (assuming 140 wpm)"""
        words_per_second = 2.3  # Average speaking rate
        max_words = int(target_seconds * words_per_second)
        
        words = text.split()
        if len(words) <= max_words:
            return text
        
        truncated = ' '.join(words[:max_words])
        return truncated + "..."
    
    def _estimate_duration(self, *segments) -> int:
        """Estimate total script duration in seconds"""
        total_words = 0
        for segment in segments:
            total_words += len(segment.split())
        
        return int(total_words / 2.3)  # 2.3 words per second average
    
    def _assemble_full_script(self, *segments) -> str:
        """Assemble full TikTok script"""
        hook, context, news, impact, next_step, hashtags = segments
        
        script = f"""🎵 TIKTOK SCRIPT
⏱️ Estimated Duration: ~{self._estimate_duration(hook, context, news, impact, next_step)} seconds

---

🎵 HOOK (3-5 seconds)
{hook}

---

🌍 CONTEXT (10-15 seconds) 
{context}

---

📰 NEWS (30-45 seconds)
{news}

---

💡 IMPACT (10-15 seconds)
{impact}

---

📈 NEXT STEPS (5 seconds)
{next_step}

---

🏷️ HASHTAGS
{' '.join(hashtags)}

---

💡 PRO TIPS:
- Use trending sounds: Search "news," "break," "intense" in TikTok sound library
- Add text overlays for key points
- Include relevant stock footage or news clips
- Post during peak hours (12 PM, 7 PM local time)
- Engage with comments in first 30 minutes
"""
        return script
    
    def _assemble_daily_report_script(self, *segments) -> str:
        """Assemble daily report script"""
        hook, story_briefs, context, news, impact, other_stories, next_step, hashtags = segments
        
        script = f"""🎵 DAILY GEOPOLITICAL REPORT TIKTOK SCRIPT

---

🎵 HOOK
{hook}

---

📋 TODAY'S TOP STORIES
{chr(10).join(story_briefs)}

---

🌍 DEEP DIVE: MAIN STORY

{context}

---

📰 DETAILS
{news}

---

💡 WHY IT MATTERS
{impact}

---

📊 OTHER DEVELOPMENTS
{other_stories}

---

📈 STAY TUNED
{next_step}

---

🏷️ HASHTAGS
{' '.join(hashtags)}

---

💡 PRO TIPS:
- This is a longer format (90-120 seconds)
- Use countdown timer visual
- Include map graphics for regional context
- Post multiple times per day for different timezones
"""
        return script
    
    def format_for_video_creation(self, script: Dict[str, Any]) -> Dict[str, Any]:
        """Format script for video creation tools"""
        return {
            'title': script.get('title', 'Daily Geopolitical Report'),
            'duration': script.get('estimated_duration', 90),
            'voiceover_text': script.get('full_script', ''),
            'suggested_visuals': self._suggest_visuals(script),
            'music_genre': 'news',
            'style': 'documentary'
        }
    
    def _suggest_visuals(self, script: Dict[str, Any]) -> List[str]:
        """Suggest visual elements for video"""
        visuals = [
            'News ticker overlay',
            'Globe animation',
            'Map of affected region',
            'Stock footage: government buildings',
            'Photo of key leaders',
            'Breaking news graphic',
            'Text overlays for key points'
        ]
        return visuals


if __name__ == "__main__":
    # Example usage
    generator = TikTokGeoScriptGenerator()
    
    # Example story
    example_story = {
        'title': 'Major diplomatic talks begin between regional powers',
        'description': 'Historic negotiations have commenced between multiple nations in the region, with international observers calling for peaceful resolution to long-standing disputes.',
        'source': 'Test News',
        'importance_score': 8,
        'relevance': {
            'detected_regions': ['middle_east', 'europe'],
            'category_scores': {'diplomacy': 3, 'alliances': 2},
            'total_score': 5
        }
    }
    
    script = generator.generate_single_story_script(example_story)
    print(script['full_script'])
FILE:generate_daily_report.py
"""
Daily Geopolitical TikTok Reporter - Main Script
Generates daily TikTok scripts about geopolitical news
"""

import sys
import os
from datetime import datetime

# Add skill modules to path
sys.path.append(os.path.dirname(os.path.abspath(__file__)))

from news_gathering.fetch_news import GeoNewsGatherer
from content_gen.tiktok_generator import TikTokGeoScriptGenerator
import json

def generate_daily_geopolitical_tiktok(
    hours_back: int = 24,
    num_scripts: int = 3,
    region_filter: str = None,
    topic_filter: str = None
):
    """Generate daily geopolitical TikTok scripts
    
    Args:
        hours_back: How many hours back to gather news
        num_scripts: Number of individual scripts to generate
        region_filter: Filter by geographic region (optional)
        topic_filter: Filter by topic category (optional)
    """
    
    print("🌍 Daily Geopolitical TikTok Reporter")
    print(f"⏰ Gathering news from last {hours_back} hours...")
    print(f"�Filtering: Region={region_filter}, Topic={topic_filter}")
    print("-" * 50)
    
    # Step 1: Gather news
    gatherer = GeoNewsGatherer(hours_back=hours_back)
    articles = gatherer.fetch_all_sources()
    
    print(f"📰 Found {len(articles)} geopolitical articles")
    
    if len(articles) == 0:
        print("❌ No geopolitical news found in the specified time period")
        return None
    
    # Apply filters if specified
    if region_filter:
        articles = gatherer.filter_by_region(region_filter)
        print(f"🔍 Filtered to {len(articles)} articles in region: {region_filter}")
    
    if topic_filter:
        articles = gatherer.filter_by_topic(topic_filter)
        print(f"🔍 Filtered to {len(articles)} articles on topic: {topic_filter}")
    
    if len(articles) == 0:
        print("❌ No articles match the specified filters")
        return None
    
    # Get top stories
    top_stories = gatherer.get_top_stories(num_scripts)
    
    print(f"🔥 Selected top {len(top_stories)} stories:")
    for i, story in enumerate(top_stories, 1):
        print(f"   {i}. {story['title'][:60]}...")
        print(f"      Importance: {story['importance_score']}/10")
    
    # Step 2: Generate TikTok scripts
    print("\n🎬 Generating TikTok scripts...")
    generator = TikTokGeoScriptGenerator()
    
    # Generate individual story scripts
    scripts = []
    for i, story in enumerate(top_stories, 1):
        print(f"\n📝 Script {i}: {story['title'][:50]}...")
        script = generator.generate_single_story_script(story)
        scripts.append(script)
        print(f"   ⏱️ Duration: ~{script['estimated_duration']} seconds")
        print(f"   🏷️ Hashtags: {', '.join(script['hashtags'][:4])}...")
    
    # Generate daily report script
    print(f"\n📊 Generating daily report script...")
    daily_report = generator.generate_daily_report_script(top_stories)
    
    if daily_report:
        scripts.append(daily_report)
        print(f"   📋 Daily report covering {daily_report['stories_count']} stories")
    
    # Step 3: Save scripts
    timestamp = datetime.now().strftime("%Y-%m-%d_%H-%M")
    output_dir = f"generated_scripts_{timestamp}"
    os.makedirs(output_dir, exist_ok=True)
    
    print(f"\n💾 Saving scripts to {output_dir}/...")
    
    for i, script in enumerate(scripts, 1):
        script_type = script.get('type', 'single_story')
        script_title = script.get('title', f'script_{i}')
        script_title = ''.join(c if c.isalnum() or c in ['_', '-'] else '_' for c in script_title)
        
        # Save individual script
        filename = f"{output_dir}/{i}_{script_title}.txt"
        with open(filename, 'w', encoding='utf-8') as f:
            f.write(script['full_script'])
        
        print(f"   ✅ {filename}")
    
    # Save metadata JSON
    metadata = {
        'generated_at': datetime.now().isoformat(),
        'total_scripts': len(scripts),
        'articles_analyzed': len(articles),
        'time_period_hours': hours_back,
        'filters': {
            'region': region_filter,
            'topic': topic_filter
        },
        'scripts': [
            {
                'type': script.get('type', 'single_story'),
                'title': script.get('title', 'N/A'),
                'duration': script.get('estimated_duration', 'N/A'),
                'hashtags': script.get('hashtags', [])
            }
            for script in scripts
        ]
    }
    
    metadata_file = f"{output_dir}/metadata.json"
    with open(metadata_file, 'w', encoding='utf-8') as f:
        json.dump(metadata, f, indent=2)
    
    print(f"   ✅ {metadata_file}")
    
    # Summary
    print("\n" + "=" * 50)
    print("🎉 SUCCESS! Generated TikTok scripts")
    print("=" * 50)
    print(f"📝 Total scripts: {len(scripts)}")
    print(f"📰 Articles analyzed: {len(articles)}")
    print(f"📁 Output directory: {output_dir}/")
    print("\n📖 Next steps:")
    print("1. Review the generated scripts in the output directory")
    print("2. Customize scripts as needed (add personal style, adjustments)")
    print("3. Use TikTok's text-to-speech or record voiceover")
    print("4. Add visuals (stock footage, news clips, maps)")
    print("5. Post during peak hours for maximum engagement")
    print("\n💡 Pro tip: Schedule this script to run daily for consistent content!")
    
    return {
        'scripts': scripts,
        'metadata': metadata,
        'output_dir': output_dir
    }

if __name__ == "__main__":
    import argparse
    
    parser = argparse.ArgumentParser(description='Generate daily geopolitical TikTok scripts')
    parser.add_argument('--hours', type=int, default=24, 
                       help='Hours back to gather news (default: 24)')
    parser.add_argument('--scripts', type=int, default=3,
                       help='Number of scripts to generate (default: 3)')
    parser.add_argument('--region', type=str, default=None,
                       help='Filter by geographic region (e.g., middle_east, europe, asia)')
    parser.add_argument('--topic', type=str, default=None,
                       help='Filter by topic (e.g., conflicts, diplomacy, elections)')
    
    args = parser.parse_args()
    
    result = generate_daily_geopolitical_tiktok(
        hours_back=args.hours,
        num_scripts=args.scripts,
        region_filter=args.region,
        topic_filter=args.topic
    )
    
    if not result:
        sys.exit(1)
FILE:news_gathering/fetch_news.py
"""
Daily Geopolitical TikTok Reporter - News Gathering Module
Fetches geopolitical news from free RSS sources
"""

import feedparser
from datetime import datetime, timedelta
from typing import List, Dict, Any
import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

class GeoNewsGatherer:
    """Gather geopolitical news from free RSS sources"""
    
    # Free RSS sources for geopolitical news
    NEWS_SOURCES = {
        'bbc_world': {
            'url': 'http://feeds.bbci.co.uk/news/world/rss.xml',
            'name': 'BBC World',
            'region': 'global'
        },
        'reuters_world': {
            'url': 'https://www.reuters.com/rssFeed/worldNews',
            'name': 'Reuters World',
            'region': 'global'
        },
        'reuters_conflicts': {
            'url': 'https://www.reuters.com/rssFeed/conflict',
            'name': 'Reuters Conflict',
            'region': 'global'
        },
        'ap_world': {
            'url': 'https://storage.googleapis.com/afs-prod/media/feeds/AP.WorldNews.xml',
            'name': 'AP World News',
            'region': 'global'
        },
        'aljazeera': {
            'url': 'https://www.aljazeera.com/xml/rss/all.xml',
            'name': 'Al Jazeera',
            'region': 'middle_east'
        }
    }
    
    # Geopolitical keywords for filtering
    GEO_KEYWORDS = {
        'conflicts': ['war', 'conflict', 'attack', 'military', 'troops', 'battle', 'clashes'],
        'diplomacy': ['diplomatic', 'negotiation', 'talks', 'treaty', 'summit', 'meeting'],
        'sanctions': ['sanctions', 'embargo', 'restrictions', 'economic'],
        'elections': ['election', 'vote', 'president', 'prime minister', 'parliament'],
        'alliances': ['alliance', 'nato', 'eu', 'union', 'bloc', 'coalition'],
        'crisis': ['crisis', 'emergency', 'unrest', 'protests', 'revolution']
    }
    
    # Geopolitical regions for categorization
    REGIONS = {
        'middle_east': ['israel', 'palestine', 'iran', 'iraq', 'syria', 'lebanon', 'yemen', 'saudi', 'gulf'],
        'europe': ['ukraine', 'russia', 'eu', 'nato', 'european', 'britain', 'france', 'germany'],
        'asia': ['china', 'taiwan', 'north korea', 'south korea', 'japan', 'india', 'pakistan'],
        'americas': ['us', 'usa', 'united states', 'canada', 'mexico', 'brazil', 'argentina'],
        'africa': ['africa', 'african', 'sudan', 'congo', 'nigeria', 'ethiopia', 'kenya']
    }
    
    def __init__(self, hours_back: int = 24):
        """Initialize news gatherer
        
        Args:
            hours_back: How many hours back to fetch news (default: 24 hours)
        """
        self.hours_back = hours_back
        self.cutoff_time = datetime.now() - timedelta(hours=hours_back)
        self.news_articles = []
    
    def fetch_all_sources(self) -> List[Dict[str, Any]]:
        """Fetch news from all configured sources
        
        Returns:
            List of news articles with metadata
        """
        all_articles = []
        
        for source_id, source_config in self.NEWS_SOURCES.items():
            try:
                articles = self._fetch_rss_feed(source_id, source_config)
                all_articles.extend(articles)
                logger.info(f"Fetched {len(articles)} articles from {source_config['name']}")
            except Exception as e:
                logger.error(f"Failed to fetch from {source_config['name']}: {str(e)}")
        
        self.news_articles = all_articles
        return all_articles
    
    def _fetch_rss_feed(self, source_id: str, source_config: Dict) -> List[Dict[str, Any]]:
        """Fetch and parse RSS feed from a single source"""
        feed = feedparser.parse(source_config['url'])
        articles = []
        
        for entry in feed.entries:
            try:
                # Parse publication time
                pub_time = self._parse_pub_time(entry)
                
                # Filter by time
                if pub_time and pub_time < self.cutoff_time:
                    continue
                
                # Extract content
                title = entry.get('title', '')
                description = entry.get('description', '')
                link = entry.get('link', '')
                
                # Geopolitical relevance check
                relevance = self._calculate_geo_relevance(title, description)
                
                if relevance['total_score'] > 0:
                    articles.append({
                        'source': source_config['name'],
                        'source_id': source_id,
                        'title': title,
                        'description': description,
                        'link': link,
                        'published_time': pub_time,
                        'relevance': relevance,
                        'importance_score': self._calculate_importance(relevance)
                    })
                    
            except Exception as e:
                logger.warning(f"Error parsing entry: {str(e)}")
                continue
        
        return articles
    
    def _parse_pub_time(self, entry) -> datetime:
        """Parse publication time from RSS entry"""
        try:
            if hasattr(entry, 'published_parsed') and entry.published_parsed:
                return datetime(*entry.published_parsed[:6])
            elif hasattr(entry, 'updated_parsed') and entry.updated_parsed:
                return datetime(*entry.updated_parsed[:6])
        except:
            pass
        return None
    
    def _calculate_geo_relevance(self, title: str, description: str) -> Dict[str, Any]:
        """Calculate geopolitical relevance score"""
        combined_text = f"{title} {description}".lower()
        
        scores = {}
        for category, keywords in self.GEO_KEYWORDS.items():
            score = sum(1 for keyword in keywords if keyword in combined_text)
            scores[category] = score
        
        # Detect regions
        detected_regions = []
        for region, countries in self.REGIONS.items():
            if any(country in combined_text for country in countries):
                detected_regions.append(region)
        
        return {
            'category_scores': scores,
            'detected_regions': detected_regions,
            'total_score': sum(scores.values())
        }
    
    def _calculate_importance(self, relevance: Dict) -> int:
        """Calculate importance score (1-10)"""
        base_score = min(10, relevance['total_score'])
        
        # Boost for multiple categories
        if sum(1 for score in relevance['category_scores'].values() if score > 0) >= 2:
            base_score = min(10, base_score + 2)
        
        # Boost for multiple regions
        if len(relevance['detected_regions']) >= 2:
            base_score = min(10, base_score + 1)
        
        return base_score
    
    def get_top_stories(self, limit: int = 10) -> List[Dict[str, Any]]:
        """Get top geopolitical stories by importance
        
        Args:
            limit: Maximum number of stories to return
        
        Returns:
            List of top stories sorted by importance
        """
        sorted_stories = sorted(
            self.news_articles,
            key=lambda x: x['importance_score'],
            reverse=True
        )
        return sorted_stories[:limit]
    
    def filter_by_region(self, region: str) -> List[Dict[str, Any]]:
        """Filter stories by geographic region"""
        return [
            story for story in self.news_articles
            if region in story['relevance']['detected_regions']
        ]
    
    def filter_by_topic(self, topic: str) -> List[Dict[str, Any]]:
        """Filter stories by topic category"""
        return [
            story for story in self.news_articles
            if story['relevance']['category_scores'].get(topic, 0) > 0
        ]


if __name__ == "__main__":
    # Example usage
    gatherer = GeoNewsGatherer(hours_back=24)
    gatherer.fetch_all_sources()
    
    print(f"\n📰 Found {len(gatherer.news_articles)} geopolitical articles in last 24 hours")
    
    top_stories = gatherer.get_top_stories(5)
    print(f"\n🔥 Top 5 Geopolitical Stories:")
    
    for i, story in enumerate(top_stories, 1):
        print(f"\n{i}. {story['title']}")
        print(f"   Source: {story['source']}")
        print(f"   Importance: {story['importance_score']}/10")
        print(f"   Regions: {', '.join(story['relevance']['detected_regions'])}")
        print(f"   Link: {story['link']}")
FILE:requirements.txt
feedparser>=6.0.0
pyyaml>=6.0
python-dateutil>=2.8.0
requests>=2.28.0

---
name: integration-testing
description: Automated integration testing with external services using testcontainers, wiremock, localstack. Use when developer needs to set up integration tests for testing with real services in Docker containers via testcontainers, mocking HTTP APIs with WireMock, testing AWS S3 with LocalStack, SFTP integration testing, or setting up complex integration test environments with external dependencies.
---

# Integration Testing with External Services

## Quick Start

This skill helps you set up integration tests with external services:

- **Testcontainers**: Run real services in Docker containers for testing
- **WireMock**: Mock HTTP services and APIs
- **LocalStack**: Local AWS services (S3) for testing without AWS dependency
- **SFTP**: Integration testing with SFTP servers

## When to Use This Skill

Use this skill when you need to:
- Set up integration tests with external services
- Test applications against real databases/message queues in isolation
- Mock HTTP APIs for reliable testing
- Test S3 integration without using real AWS resources
- Configure automated integration test environments

## Setup Options

### Testcontainers Setup

For integration tests with real services:

```python
# Basic testcontainers example
from testcontainers.postgres import PostgresContainer

def test_with_postgres():
    with PostgresContainer("postgres:15") as postgres:
        connection_string = postgres.get_connection_url()
        # Run tests with real PostgreSQL
```

See [testcontainers-guide.md](references/testcontainers-guide.md) for detailed setup.

### WireMock Setup

For mocking HTTP services:

```python
# WireMock configuration example
from wiremock import WireMockServer

def test_with_wiremock():
    with WireMockServer() as wiremock:
        wiremock.stub_for(
            request_method="GET",
            request_url="/api/users",
            response_body='{"users": []}'
        )
        # Test against mocked API
```

See [wiremock-patterns.md](references/wiremock-patterns.md) for common patterns.

### LocalStack Setup

For testing S3 without AWS:

```python
# LocalStack S3 testing example
import boto3
from localstack import start_localstack

def test_s3_with_localstack():
    with start_localstack(services=["s3"]) as localstack:
        s3 = boto3.client('s3', endpoint_url=localstack.endpoint_url)
        # Test S3 operations locally
```

See [localstack-s3-config.md](references/localstack-s3-config.md) for S3 configuration.

### SFTP Integration Testing

For testing SFTP connectivity and operations:

```python
# SFTP integration test example
from paramiko import SSHClient

def test_sftp_operations():
    with SSHClient() as ssh:
        ssh.connect('sftp-server', username='test', password='test')
        sftp = ssh.open_sftp()
        # Test SFTP file operations
```

## Available Templates

Ready-to-use test templates for common scenarios:

- `templates/testcontainers-python.py` - Python testcontainers setup
- `templates/wiremock-http-tests.py` - WireMock HTTP API tests
- `templates/localstack-s33-tests.py` - LocalStack S3 integration tests
- `templates/sftp-integration-tests.py` - SFTP integration testing

## Helper Scripts

Setup scripts to initialize test environments:

- `scripts/setup_testcontainers.py` - Configure testcontainers environment
- `scripts/init_wiremock.py` - Initialize WireMock server
- `scripts/start_localstack.py` - Start LocalStack services

## Best Practices

1. **Container Management**: Always use context managers for container lifecycle
2. **Port Conflicts**: Configure ports to avoid conflicts with local services
3. **Cleanup**: Ensure proper cleanup of resources in test teardown
4. **Environment Variables**: Use env vars for configuration, avoid hardcoded values
5. **Parallel Testing**: Design tests to run in parallel where possible

## Getting Help

For detailed setup and patterns, see:
- [Testcontainers Guide](references/testcontainers-guide.md)
- [WireMock Patterns](references/wiremock-patterns.md)  
- [LocalStack S3 Config](references/localstack-s3-config.md)

## Security & Compliance

This skill is designed **SOLELY for legitimate integration testing purposes** in isolated development environments.

### ⚠️ Important Security Notes

- **Development Use Only**: Never deploy test containers or services to production networks
- **Isolated Environments**: All services run locally and are destroyed after testing
- **Educational Purpose**: Designed to teach proper testing methodologies
- **Full Transparency**: Source code is fully visible and auditable

For detailed security information, see [SECURITY.md](SECURITY.md)

FILE:SECURITY.md
# Security & Compliance

This skill is designed **SOLELY for legitimate integration testing purposes**. Below is the security context and intended use cases.

## ✅ Intended Use Cases

This skill helps developers test their applications in isolated environments:

1. **Database Integration Testing**
   - Testing application behavior against real databases
   - Validating data migrations and schema changes
   - Performance testing with realistic data volumes

2. **API Testing & Mocking**
   - Testing applications against mocked HTTP APIs
   - Validating error handling and edge cases
   - Testing API version compatibility

3. **Cloud Service Testing**
   - Testing S3 file operations without using AWS resources
   - Validating cloud service integrations locally
   - Reducing AWS costs during development

4. **SFTP/Network Testing**
   - Testing file transfer operations in isolated environments
   - Validating connectivity and error handling
   - Testing file management workflows

## 🔒 Security Considerations

### What This Skill Does NOT Do:
- ❌ Access external networks or systems without authorization
- ❌ Exfiltrate data from production environments
- ❌ Perform unauthorized access attempts
- ❌ Provide backdoors or remote access capabilities
- ❌ Circumvent security controls in production

### What This Skill DOES Do:
- ✅ Creates isolated, temporary test environments
- ✅ Tests applications against local mock services
- ✅ Validates code behavior in controlled environments
- ✅ Provides educational examples for testing frameworks

## ⚠️ Usage Warnings

### For Development Use Only:
- **Never deploy test containers to production networks**
- **Never expose test services to external networks**
- **Never use hardcoded credentials in real applications**
- **Always use environment variables or secret management for production credentials**

### Resource Management:
- Test containers are automatically cleaned up after testing
- LocalStack services run in isolated mode
- WireMock servers bind to localhost only
- Docker containers are removed when tests complete

## 🛡️ Compliance Notes

This skill complies with security best practices for development tools:

1. **Isolation**: All test environments are isolated from production systems
2. **Ephemeral**: No persistent data or services remain after testing
3. **Educational**: Designed to teach proper testing methodologies
4. **Transparent**: Source code is fully visible and auditable

## 📞 Contact & Support

If you have security concerns about this skill, please:

1. Review the source code for full transparency
2. Test in isolated development environments first
3. Follow security best practices for container management
4. Contact the maintainer for clarification

**Maintainer**: @ahmed181283  
**Purpose**: Integration testing automation for legitimate development workflows
FILE:references/localstack-s3-config.md
# LocalStack S3 Configuration Guide

Complete guide for configuring and using LocalStack S3 for AWS integration testing.

## What is LocalStack?

LocalStack provides a local AWS cloud stack that simulates AWS services. It allows you to develop and test applications without using real AWS resources, avoiding costs and ensuring reproducible test environments.

## Key Benefits

- **Cost-free testing**: No AWS charges during development/testing
- **Fast feedback**: Local development without network latency
- **Reproducible tests**: Consistent environment across all developers
- **Offline testing**: Work without internet connectivity
- **Full S3 API coverage**: Most S3 operations supported

## Installation

### Using pip

```bash
pip install localstack
```

### Using Docker

```bash
docker pull localstack/localstack:latest
```

### Using Homebrew (macOS)

```bash
brew install localstack/tap/localstack
```

## Starting LocalStack

### Command Line

```bash
# Start with default services
localstack start

# Start with specific services
localstack start --services s3,lambda,dynamodb

# Start with custom port
localstack start --port 4566

# Start with debug output
localstack start --debug
```

### Using Python

```python
from localstack import start_localstack

def start_localstack_s3():
    # Start LocalStack with S3 service
    with start_localstack(services=["s3"]) as localstack:
        print(f"LocalStack running at {localstack.endpoint_url}")
        # Use localstack.endpoint_url for AWS clients
        pass
```

## Configuring AWS Clients

### Python (boto3)

```python
import boto3
from localstack import start_localstack

def configure_boto3_for_localstack():
    with start_localstack(services=["s3"]) as localstack:
        # Configure S3 client for LocalStack
        s3_client = boto3.client(
            's3',
            endpoint_url=localstack.endpoint_url,
            aws_access_key_id='test',  # Any value works
            aws_secret_access_key='test',  # Any value works
            region_name='us-east-1'  # LocalStack default region
        )
        
        # Now use s3_client as you would with real AWS
        return s3_client
```

### AWS CLI

```bash
# Set environment variables
export AWS_ACCESS_KEY_ID=test
export AWS_SECRET_ACCESS_KEY=test
export AWS_REGION=us-east-1
export AWS_ENDPOINT_URL_S3=http://localhost:4566

# Use AWS CLI commands
aws s3 ls
aws s3 mb s3://test-bucket
aws s3 cp file.txt s3://test-bucket/
```

### Environment Variables

```bash
# .bashrc or .zshrc
export AWS_ACCESS_KEY_ID=test
export AWS_SECRET_ACCESS_KEY=test
export AWS_REGION=us-east-1
export AWS_ENDPOINT_URL_S3=http://localhost:4566

# Or use LocalStack CLI to configure
localstack configure aws
```

## S3 Operations

### Bucket Operations

```python
def test_bucket_operations():
    s3_client = configure_boto3_for_localstack()
    
    # Create bucket
    bucket_name = 'test-bucket'
    s3_client.create_bucket(Bucket=bucket_name)
    
    # List buckets
    buckets = s3_client.list_buckets()
    assert bucket_name in [b['Name'] for b in buckets['Buckets']]
    
    # Delete bucket
    s3_client.delete_bucket(Bucket=bucket_name)
```

### Object Operations

```python
def test_object_operations():
    s3_client = configure_boto3_for_localstack()
    bucket_name = 'test-bucket'
    s3_client.create_bucket(Bucket=bucket_name)
    
    # Upload object
    file_content = b'Hello, LocalStack S3!'
    s3_client.put_object(
        Bucket=bucket_name,
        Key='test-file.txt',
        Body=file_content,
        ContentType='text/plain'
    )
    
    # List objects
    objects = s3_client.list_objects_v2(Bucket=bucket_name)
    assert len(objects['Contents']) == 1
    
    # Download object
    obj = s3_client.get_object(Bucket=bucket_name, Key='test-file.txt')
    downloaded_content = obj['Body'].read()
    assert downloaded_content == file_content
    
    # Get object metadata
    metadata = s3_client.head_object(Bucket=bucket_name, Key='test-file.txt')
    assert metadata['ContentType'] == 'text/plain'
    
    # Delete object
    s3_client.delete_object(Bucket=bucket_name, Key='test-file.txt')
    s3_client.delete_bucket(Bucket=bucket_name)
```

### Large File Uploads

```python
def test_large_file_upload():
    s3_client = configure_boto3_for_localstack()
    bucket_name = 'large-files'
    s3_client.create_bucket(Bucket=bucket_name)
    
    # Use multipart upload for large files
    import os
    
    large_file_size = 100 * 1024 * 1024  # 100 MB
    large_file_content = b'x' * large_file_size
    
    # Upload with multipart
    multipart_upload = s3_client.create_multipart_upload(
        Bucket=bucket_name,
        Key='large-file.bin'
    )
    
    upload_id = multipart_upload['UploadId']
    
    # Upload in parts
    part_size = 10 * 1024 * 1024  # 10 MB parts
    parts = []
    
    for i, offset in enumerate(range(0, large_file_size, part_size), 1):
        part_data = large_file_content[offset:offset + part_size]
        part = s3_client.upload_part(
            Bucket=bucket_name,
            Key='large-file.bin',
            PartNumber=i,
            UploadId=upload_id,
            Body=part_data
        )
        parts.append({'PartNumber': i, 'ETag': part['ETag']})
    
    # Complete multipart upload
    s3_client.complete_multipart_upload(
        Bucket=bucket_name,
        Key='large-file.bin',
        UploadId=upload_id,
        MultipartUpload={'Parts': parts}
    )
    
    # Verify upload
    obj = s3_client.head_object(Bucket=bucket_name, Key='large-file.bin')
    assert obj['ContentLength'] == large_file_size
```

### Presigned URLs

```python
def test_presigned_urls():
    s3_client = configure_boto3_for_localstack()
    bucket_name = 'presigned-test'
    s3_client.create_bucket(Bucket=bucket_name)
    
    # Upload test file
    s3_client.put_object(
        Bucket=bucket_name,
        Key='public-file.txt',
        Body=b'public content'
    )
    
    # Generate presigned URL (GET)
    get_url = s3_client.generate_presigned_url(
        'get_object',
        Params={'Bucket': bucket_name, 'Key': 'public-file.txt'},
        ExpiresIn=3600  # 1 hour
    )
    
    # Test presigned URL
    import requests
    response = requests.get(get_url)
    assert response.status_code == 200
    assert response.content == b'public content'
    
    # Generate presigned URL (PUT)
    put_url = s3_client.generate_presigned_url(
        'put_object',
        Params={'Bucket': bucket_name, 'Key': 'upload-file.txt'},
        ExpiresIn=3600
    )
    
    # Upload via presigned URL
    response = requests.put(put_url, data=b'uploaded content')
    assert response.status_code == 200
```

## Advanced Configuration

### Custom Port

```python
def test_custom_port():
    from localstack import start_localstack
    
    # Start LocalStack on custom port
    with start_localstack(services=["s3"], port=4567) as localstack:
        print(f"LocalStack running on port {localstack.port}")
        
        s3_client = boto3.client(
            's3',
            endpoint_url=f"http://localhost:{localstack.port}",
            aws_access_key_id='test',
            aws_secret_access_key='test',
            region_name='us-east-1'
        )
        # Use s3_client
        pass
```

### Multiple Services

```python
def test_multiple_services():
    from localstack import start_localstack
    
    # Start multiple AWS services
    with start_localstack(services=["s3", "lambda", "dynamodb"]) as localstack:
        # Configure different AWS clients
        s3_client = boto3.client(
            's3',
            endpoint_url=localstack.endpoint_url,
            aws_access_key_id='test',
            aws_secret_access_key='test',
            region_name='us-east-1'
        )
        
        dynamo_client = boto3.client(
            'dynamodb',
            endpoint_url=localstack.endpoint_url,
            aws_access_key_id='test',
            aws_secret_access_key='test',
            region_name='us-east-1'
        )
        
        # Use both clients
        pass
```

### Persistence

```python
def test_persistent_localstack():
    # Start LocalStack with persistence (Docker volume)
    # This keeps data between restarts
    import subprocess
    
    subprocess.run([
        'localstack', 'start',
        '--services', 's3',
        '--volume', '/tmp/localstack-data'
    ], check=True)
    
    # LocalStack data persists in /tmp/localstack-data
```

## Error Handling

### S3 Errors

```python
def test_s3_error_handling():
    s3_client = configure_boto3_for_localstack()
    
    # Test bucket not found
    try:
        s3_client.get_object(Bucket='nonexistent', Key='file.txt')
        assert False, "Should have raised exception"
    except s3_client.exceptions.NoSuchBucket:
        print("Correctly handled bucket not found")
    
    # Test key not found
    bucket_name = 'test-bucket'
    s3_client.create_bucket(Bucket=bucket_name)
    
    try:
        s3_client.get_object(Bucket=bucket_name, Key='nonexistent.txt')
        assert False, "Should have raised exception"
    except s3_client.exceptions.NoSuchKey:
        print("Correctly handled key not found")
    
    s3_client.delete_bucket(Bucket=bucket_name)
```

### Connection Errors

```python
def test_connection_errors():
    try:
        # Try to connect without starting LocalStack
        s3_client = boto3.client(
            's3',
            endpoint_url='http://localhost:4566',
            aws_access_key_id='test',
            aws_secret_access_key='test',
            region_name='us-east-1'
        )
        
        # This should fail if LocalStack is not running
        s3_client.list_buckets()
        
    except Exception as e:
        print(f"Connection error: {e}")
        print("Make sure LocalStack is running: localstack start")
```

## Best Practices

### 1. Use Context Managers

```python
# ✅ Good - automatic cleanup
with start_localstack(services=["s3"]) as localstack:
    s3_client = boto3.client(
        's3',
        endpoint_url=localstack.endpoint_url,
        aws_access_key_id='test',
        aws_secret_access_key='test',
        region_name='us-east-1'
    )
    # Use s3_client
    pass
```

### 2. Use Fixtures in Tests

```python
import pytest
from localstack import start_localstack

@pytest.fixture(scope="session")
def localstack_s3():
    with start_localstack(services=["s3"]) as localstack:
        yield localstack

@pytest.fixture
def s3_client(localstack_s3):
    return boto3.client(
        's3',
        endpoint_url=localstack_s3.endpoint_url,
        aws_access_key_id='test',
        aws_secret_access_key='test',
        region_name='us-east-1'
    )

def test_s3_operations(s3_client):
    # Use s3_client in tests
    pass
```

### 3. Clean Up Resources

```python
def test_cleanup():
    s3_client = configure_boto3_for_localstack()
    bucket_name = 'cleanup-test'
    
    try:
        s3_client.create_bucket(Bucket=bucket_name)
        # Perform tests
        
    finally:
        # Always cleanup, even if tests fail
        try:
            # Delete all objects
            objects = s3_client.list_objects_v2(Bucket=bucket_name)
            for obj in objects.get('Contents', []):
                s3_client.delete_object(
                    Bucket=bucket_name,
                    Key=obj['Key']
                )
        except Exception:
            pass
        
        try:
            s3_client.delete_bucket(Bucket=bucket_name)
        except Exception:
            pass
```

## Troubleshooting

### LocalStack Won't Start

1. Check Docker is running: `docker ps`
2. Check port conflicts: `netstat -an | grep 4566`
3. Check logs: `localstack logs`

### S3 Operations Fail

1. Verify endpoint URL is correct
2. Check LocalStack is running
3. Review LocalStack logs: `localstack logs`
4. Test with AWS CLI: `aws s3 ls`

### Performance Issues

- Use in-memory persistence for tests
- Avoid uploading large files unless necessary
- Restart LocalStack between test suites
- Use specific services only: `--services s3`

## Further Reading

- [Official LocalStack Documentation](https://docs.localstack.cloud/)
- [LocalStack S3 Features](https://docs.localstack.cloud/aws/s3/)
- [AWS S3 Documentation](https://docs.aws.amazon.com/s3/)
- [Boto3 S3 Client](https://boto3.amazonaws.com/v1/documentation/api/s3.html)

FILE:references/testcontainers-guide.md
# Testcontainers Guide

Comprehensive guide for using testcontainers in integration testing.

## What is Testcontainers?

Testcontainers is a library that provides lightweight, throwaway instances of databases, message brokers, web browsers, or almost anything that can run in a Docker container.

## Key Benefits

- **Real services in isolation**: Test against real dependencies, not mocks
- **Disposable environments**: Every test gets a clean, fresh environment
- **Parallel testing**: Run tests in parallel without conflicts
- **Team consistency**: Same test environment for everyone

## Installation

```bash
pip install testcontainers
```

Or with extra dependencies:

```bash
pip install testcontainers[postgresql,redis,mongodb]
```

## Common Containers

### PostgreSQL

```python
from testcontainers.postgres import PostgresContainer

def test_with_postgres():
    with PostgresContainer("postgres:15") as postgres:
        connection_url = postgres.get_connection_url()
        # Use connection_url in your tests
        # postgresql://test_user:test_pass@host:port/db_name
```

### MySQL

```python
from testcontainers.mysql import MySqlContainer

def test_with_mysql():
    with MySqlContainer("mysql:8.0") as mysql:
        connection_url = mysql.get_connection_url()
        # mysql://test_user:test_pass@host:port/db_name
```

### Redis

```python
from testcontainers.redis import RedisContainer

def test_with_redis():
    with RedisContainer("redis:7-alpine") as redis:
        host = redis.get_container_host_ip()
        port = redis.get_container_port(6379)
        # Connect to Redis at host:port
```

### MongoDB

```python
from testcontainers.mongodb import MongoDbContainer

def test_with_mongodb():
    with MongoDbContainer("mongo:6.0") as mongo:
        connection_url = mongo.get_connection_url()
        # mongodb://host:port/db_name
```

### Generic Docker Container

```python
from testcontainers.core.container import DockerContainer

def test_with_custom_image():
    with DockerContainer("nginx:latest") as nginx:
        host = nginx.get_container_host_ip()
        port = nginx.get_container_port(80)
        # Use host:port to access the container
```

## Advanced Configuration

### Custom Configuration

```python
from testcontainers.postgres import PostgresContainer

def test_custom_config():
    with PostgresContainer("postgres:15") \
            .with_name("custom-postgres") \
            .with_env("POSTGRES_PASSWORD", "custom_password") \
            .with_bind_ports(8432, 5432) \
            .with_exposed_ports(5432) as postgres:
        connection_url = postgres.get_connection_url()
```

### Volume Mounts

```python
def test_with_volume():
    with DockerContainer("nginx:latest") \
            .with_volume_mapping("./html", "/usr/share/nginx/html") \
            .with_bind_ports(8080, 80) as nginx:
        # Custom HTML content will be served
        pass
```

### Network Configuration

```python
from testcontainers.core.docker_client import DockerClient

def test_with_network():
    client = DockerClient()
    network = client.client.networks.create("test-network")
    
    with DockerContainer("nginx:latest") \
            .with_network(network.name) \
            .with_network_aliases("web") as nginx:
        # Container is in custom network
        pass
    
    network.remove()
```

## Best Practices

### 1. Always Use Context Managers

```python
# ✅ Good - automatic cleanup
with PostgresContainer("postgres:15") as postgres:
    # Use postgres
    pass

# ❌ Bad - manual cleanup required
postgres = PostgresContainer("postgres:15")
postgres.start()
try:
    # Use postgres
    pass
finally:
    postgres.stop()
```

### 2. Handle Container Startup Time

```python
import time
from testcontainers.core.container import DockerContainer

def test_with_slow_service():
    with DockerContainer("slow-service:latest") as container:
        # Wait for service to be ready
        time.sleep(5)  # Or use proper health checks
        
        # Or use wait_for_logs
        container._container.wait(until=container._container.is_running)
```

### 3. Resource Limits

```python
def test_with_resource_limits():
    with PostgresContainer("postgres:15") \
            .with_mem_limit("512m") \
            .with_cpu_quota(1024) as postgres:
        # Container has limited resources
        pass
```

### 4. Custom Images

```python
def test_with_custom_image():
    # Build custom image during tests
    from testcontainers.core.docker_client import DockerClient
    
    client = DockerClient()
    image, build_logs = client.client.images.build(
        path="./docker/",
        tag="my-custom-app:latest"
    )
    
    with DockerContainer("my-custom-app:latest") as app:
        # Use custom built image
        pass
```

## Integration with Test Frameworks

### pytest

```python
import pytest
from testcontainers.postgres import PostgresContainer

@pytest.fixture(scope="session")
def postgres_container():
    with PostgresContainer("postgres:15") as postgres:
        yield postgres

@pytest.fixture
def db_connection(postgres_container):
    # Create new connection for each test
    import psycopg2
    conn = psycopg2.connect(postgres_container.get_connection_url())
    yield conn
    conn.close()

def test_database_operation(db_connection):
    # Use db_connection in tests
    cursor = db_connection.cursor()
    cursor.execute("SELECT 1")
    assert cursor.fetchone()[0] == 1
```

### unittest

```python
import unittest
from testcontainers.redis import RedisContainer

class RedisIntegrationTest(unittest.TestCase):
    
    @classmethod
    def setUpClass(cls):
        cls.redis = RedisContainer("redis:7-alpine")
        cls.redis.start()
    
    @classmethod
    def tearDownClass(cls):
        cls.redis.stop()
    
    def test_redis_connection(self):
        import redis as redis_client
        r = redis_client.Redis(
            host=self.redis.get_container_host_ip(),
            port=self.redis.get_container_port(6379)
        )
        r.set("test", "value")
        assert r.get("test") == b"value"
```

## Troubleshooting

### Container Won't Start

1. Check Docker is running: `docker ps`
2. Check logs: `docker logs <container-id>`
3. Verify image exists: `docker images`

### Port Conflicts

- Testcontainers automatically assigns available ports
- Use `get_container_port()` to get actual port
- Don't hardcode ports in tests

### Performance Issues

- Reuse containers across tests with fixtures
- Use lighter images (alpine, slim)
- Limit resource usage for heavy tests

## Further Reading

- [Official Testcontainers Python Docs](https://testcontainers-python.readthedocs.io/)
- [Testcontainers Examples](https://github.com/testcontainers/testcontainers-python/tree/master/examples)
- [Docker Best Practices](https://docs.docker.com/develop/dev-best-practices/)

FILE:references/wiremock-patterns.md
# WireMock Patterns

Common patterns and best practices for using WireMock in API testing.

## What is WireMock?

WireMock is a tool for mocking HTTP services. It creates a standalone HTTP server that can simulate any API, allowing you to test applications in isolation from external dependencies.

## Key Benefits

- **API isolation**: Test without depending on real external APIs
- **Reproducible tests**: Consistent mock responses across test runs
- **Performance**: Faster than real API calls
- **Error simulation**: Test error handling and edge cases
- **Parallel testing**: Run multiple tests simultaneously

## Basic Setup

### Start WireMock Server

```python
from wiremock import WireMockServer

# Start with default port (8080)
with WireMockServer() as wiremock:
    # WireMock server is running at http://localhost:8080
    pass

# Start with custom port
with WireMockServer(port=9090) as wiremock:
    # WireMock server is running at http://localhost:9090
'    pass
```

## Core Patterns

### 1. Simple GET Response

```python
def test_simple_get():
    with WireMockServer(port=8080) as wiremock:
        # Stub GET /api/users
        wiremock.stub_for(
            request_method="GET",
            request_url="/api/users",
            response_body='{"users": [{"id": 1, "name": "John"}]}',
            response_status=200
        )
        
        # Test against mocked API
        response = requests.get("http://localhost:8080/api/users")
        assert response.status_code == 200
        assert len(response.json()["users"]) == 1
```

### 2. POST Request with Body Matching

```python
def test_post_with_body():
    with WireMockServer(port=8080) as wiremock:
        # Stub POST with exact body match
        wiremock.stub_for(
            request_method="POST",
            request_url="/api/users",
            request_body='{"name": "John", "email": "[email protected]"}',
            response_body='{"id": 1, "name": "John", "email": "[email protected]"}',
            response_status=201
        )
        
        # Test POST request
        user_data = {"name": "John", "email": "[email protected]"}
        response = requests.post(
            "http://localhost:8080/api/users",
            json=user_data
        )
        assert response.status_code == 201
        assert response.json()["id"] == 1
```

### 3. Path Parameters

```python
def test_path_parameters():
    with WireMockServer(port=8080) as wiremock:
        # Stub with path parameter
        wiremock.stub_for(
            request_method="GET",
            request_url="/api/users/123",
            response_body='{"id": 123, "name": "User 123"}',
            response_status=200
        )
        
        # Test with specific user ID
        response = requests.get("http://localhost:8080/api/users/123")
        assert response.status_code == 200
        assert response.json()["id"] == 123
```

### 4. Query Parameters

```python
def test_query_parameters():
    with WireMockServer(port=8080) as wiremock:
        # Stub with query parameter
        wiremock.stub_for(
            request_method="GET",
            request_url="/api/users",
            request_query_params="active=true",
            response_body='{"users": [{"id": 1, "name": "Active User"}]}',
            response_status=200
        )
        
        # Test with query parameter
        response = requests.get("http://localhost:8080/api/users?active=true")
        assert response.status_code == 200
        assert len(response.json()["users"]) == 1
```

### 5. Headers

```python
def test_headers():
    with WireMockServer(port=8080) as wiremock:
        # Stub requiring specific header
        wiremock.stub_for(
            request_method="GET",
            request_url="/api/protected",
            request_headers="Authorization: Bearer token123",
            response_body='{"message": "Authorized"}',
            response_status=200
        )
        
        # Test with authorization header
        headers = {"Authorization": "Bearer token123"}
        response = requests.get(
            "http://localhost:8080/api/protected",
            headers=headers
        )
        assert response.status_code == 200
```

## Advanced Patterns

### 6. JSON Response

```python
def test_json_response():
    with WireMockServer(port=8080) as wiremock:
        # Response with JSON content type
        wiremock.stub_for(
            request_method="GET",
            request_url="/api/data",
            response_body='{"key": "value", "number": 123}',
            response_status=200,
            response_headers="Content-Type: application/json"
        )
        
        response = requests.get("http://localhost:8080/api/data")
        assert response.headers["Content-Type"] == "application/json"
        assert response.json()["key"] == "value"
```

### 7. Array Responses

```python
def test_array_response():
    with WireMockServer(port=8080) as wiremock:
        # Response with array
        users = [
            {"id": 1, "name": "John"},
            {"id": 2, "name": "Jane"}
        ]
        
        wiremock.stub_for(
            request_method="GET",
            request_url="/api/users",
            response_body=json.dumps({"users": users}),
            response_status=200
        )
        
        response = requests.get("http://localhost:8080/api/users")
        users_data = response.json()["users"]
        assert len(users_data) == 2
```

### 8. Error Responses

```python
def test_error_responses():
    with WireMockServer(port=8080) as wiremock:
        # Stub 404 Not Found
        wiremock.stub_for(
            request_method="GET",
            request_url="/api/notfound",
            response_body='{"error": "Resource not found"}',
            response_status=404
        )
        
        # Test 404 handling
        response = requests.get("http://localhost:8080/api/notfound")
        assert response.status_code == 404
        
        # Stub 500 Internal Server Error
        wiremock.stub_for(
            request_method="GET",
            request_url="/api/error",
            response_body='{"error": "Internal server error"}',
            response_status=500
        )
        
        response = requests.get("http://localhost:8080/api/error")
        assert response.status_code == 500
```

### 9. Delayed Responses

```python
def test_delayed_responses():
    with WireMockServer(port=8080) as wiremock:
        # Stub with 2 second delay
        wiremock.stub_for(
            request_method="GET",
            request_url="/api/slow",
            response_body='{"message": "Delayed response"}',
            response_status=200,
            fixed_delay_milliseconds=2000
        )
        
        # Test with timeout
        import time
        start = time.time()
        response = requests.get("http://localhost:8080/api/slow")
        elapsed = time.time() - start
        
        assert elapsed >= 2.0  # At least 2 second delay
        assert response.status_code == 200
```

### 10. Multiple Stubs

```python
def test_multiple_stubs():
    with WireMockServer(port=8080) as wiremock:
        # Stub 1: Get all users
        wiremock.stub_for(
            request_method="GET",
            request_url="/api/users",
            response_body='{"users": []}',
            response_status=200
        )
        
        # Stub 2: Get specific user
        wiremock.stub_for(
            request_method="GET",
            request_url="/api/users/1",
            response_body='{"id": 1, "name": "User 1"}',
            response_status=200
        )
        
        # Test both stubs
        response1 = requests.get("http://localhost:8080/api/users")
        assert response1.status_code == 200
        
        response2 = requests.get("http://localhost:8080/api/users/1")
        assert response2.status_code == 200
```

## Request Matching Patterns

### URL Pattern Matching

```python
def test_url_patterns():
    with WireMockServer(port=8080) as wiremock:
        # Match any path starting with /api/users/
        wiremock.stub_for(
            request_method="GET",
            request_url="/api/users/[0-9]+",  # Regex pattern
            response_body='{"user": "found"}',
            response_status=200
        )
        
        response = requests.get("http://localhost:8080/api/users/123")
        assert response.status_code == 200
```

### Body Pattern Matching

```python
def test_body_patterns():
    with WireMockServer(port=8080) as wiremock:
        # Match JSON body containing specific field
        wiremock.stub_for(
            request_method="POST",
            request_url="/api/users",
            request_body_pattern='{"name": ".+"}',  # Regex pattern
            response_body='{"created": true}',
            response_status=201
        )
        
        user_data = {"name": "John", "email": "[email protected]"}
        response = requests.post(
            "http://localhost:8080/api/users",
            json=user_data
        )
        assert response.status_code == 201
```

## Best Practices

### 1. Clean Up Between Tests

```python
def test_cleanup():
    with WireMockServer(port=8080) as wiremock:
        wiremock.reset_all()  # Clear all stubs
        
        # Add fresh stubs for this test
        wiremock.stub_for(
            request_method="GET",
            request_url="/api/test",
            response_body='{"test": "data"}',
            response_status=200
        )
```

### 2. Use Descriptive Response Bodies

```python
def test_descriptive_responses():
    with WireMockServer(port=8080) as wiremock:
        # Include helpful error messages
        wiremock.stub_for(
            request_method="GET",
            request_url="/api/error",
            response_body=json.dumps({
                "error": "Resource not found",
                "message": "The requested resource could not be found",
                "path": "/api/error",
                "timestamp": "2024-01-01T12:00:00Z"
            }),
            response_status=404
        )
```

### 3. Mock Realistic Responses

```python
def test_realistic_responses():
    with WireMockServer(port=8080) as wiremock:
        # Use realistic data structures
        wiremock.stub_for(
            request_method="GET",
            request_url="/api/users",
            response_body=json.dumps({
                "users": [
                    {
                        "id": 1,
                        "name": "John Doe",
                        "email": "[email protected]",
                        "created_at": "2024-01-01T10:00:00Z",
                        "updated_at": "2024-01-01T10:00:00Z"
                    }
                ],
                "pagination": {
                    "page": 1,
                    "per_page": 20,
                    "total": 1,
                    "total_pages": 1
                }
            }),
            response_status=200
        )
```

## Integration with Test Frameworks

### pytest

```python
import pytest
from wiremock import WireMockServer

@pytest.fixture(scope="session")
def wiremock_server():
    with WireMockServer(port=8080) as wiremock:
        yield wiremock

def test_api_integration(wiremock_server):
    # Setup stub
    wiremock_server.stub_for(
        request_method="GET",
        request_url="/api/test",
        response_body='{"test": "passed"}',
        response_status=200
    )
    
    # Test against mocked API
    response = requests.get("http://localhost:8080/api/test")
    assert response.json()["test"] == "passed"
```

## Troubleshooting

### Stubs Not Matching

1. Check exact URL matching
2. Verify HTTP method (GET, POST, etc.)
3. Check headers and body patterns
4. Use WireMock: Reset all between tests

### Port Already in Use

- Use different ports for parallel tests
- Check for existing processes on port
- Use context managers for automatic cleanup

### Performance Issues

- Use `reset_all()` instead of restarting server
- Minimize number of stubs
- Use URL patterns instead of multiple specific stubs

## Further Reading

- [Official WireMock Documentation](http://wiremock.org/docs/)
- [WireMock Python Wrapper](https://github.com/wiremock/python-wiremock)
- [API Mocking Best Practices](https://martinfowler.com/articles/mocksArentStubs.html)

FILE:scripts/init_wiremock.py
#!/usr/bin/env python3
"""
Setup script for WireMock
Initializes and starts WireMock server for API mocking
"""

import subprocess
import sys
import os
import time
import requests

def check_java():
    """Check if Java is available (WireMock requires Java)"""
    try:
        result = subprocess.run(
            ['java', '-version'],
            capture_output=True,
            text=True
        )
        if result.returncode == 0:
            print("✅ Java is available")
            return True
        else:
            print("❌ Java is not available")
            return False
    except FileNotFoundError:
        print("❌ Java is not installed")
        return False

def download_wiremock():
    """Download WireMock standalone JAR if not present"""
    wiremock_version = "3.5.2"  # Latest stable version
    wiremock_jar = f"wiremock-standalone-{wiremock_version}.jar"
    wiremock_url = f"https://repo1.maven.org/maven2/org/wiremock/wiremock-standalone/{wiremock_version}/{wiremock_jar}"
    
    if os.path.exists(wiremock_jar):
        print(f"✅ WireMock JAR already exists: {wiremock_jar}")
        return wiremock_jar
    
    print(f"📥 Downloading WireMock {wiremock_version}...")
    try:
        subprocess.run(
            ['curl', '-L', '-o', wiremock_jar, wiremock_url],
            check=True
        )
        print(f"✅ Downloaded {wiremock_jar}")
        return wiremock_jar
    except subprocess.CalledProcessError as e:
        print(f"❌ Failed to download WireMock: {e}")
        return None

def start_wiremock(jar_path, port=8080):
    """Start WireMock server"""
    print(f"🚀 Starting WireMock server on port {port}...")
    
    # Check if port is already in use
    try:
        response = requests.get(f"http://localhost:{port}/__admin")
        print(f"⚠️  Port {port} is already in use")
        return None
    except requests.exceptions.ConnectionError:
        pass  # Port is available
    
    # Start WireMock
    try:
        process = subprocess.Popen(
            ['java', '-jar', jar_path, '--port', str(port)],
            stdout=subprocess.PIPE,
            stderr=subprocess.PIPE
        )
        
        # Wait for server to start
        max_attempts = 10
        for i in range(max_attempts):
            try:
                response = requests.get(f"http://localhost:{port}/__admin")
                if response.status_code == 200:
                    print(f"✅ WireMock server started on port {port}")
                    print(f"   Admin UI: http://localhost:{port}/__admin")
                    return process
            except requests.exceptions.ConnectionError:
                time.sleep(0.5)
        
        print(f"❌ WireMock failed to start within {max_attempts * 0.5} seconds")
        process.terminate()
        return None
        
    except Exception as e:
        print(f"❌ Failed to start WireMock: {e}")
        return None

def verify_wiremock(port=8080):
    """Verify WireMock is running"""
    try:
        response = requests.get(f"http://localhost:{port}/__admin/mappings")
        if response.status_code == 200:
            print("✅ WireMock API is responsive")
            return True
        return False
    except requests.exceptions.ConnectionError:
        return False

def main():
    """Main initialization function"""
    print("🔧 Setting up WireMock for API mocking...\n")
    
    # Step 1: Check Java
    print("Step 1: Checking Java...")
    if not check_java():
        print("Please install Java first (WireMock requires Java 8+)")
        sys.exit(1)
    
    # Step 2: Download WireMock
    print("\nStep 2: Downloading WireMock...")
    jar_path = download_wiremock()
    if not jar_path:
        sys.exit(1)
    
    # Step 3: Start WireMock
    print("\nStep 3: Starting WireMock server...")
    process = start_wiremock(jar_path)
    if not process:
        sys.exit(1)
    
    # Step 4: Verify setup
    print("\nStep 4: Verifying WireMock setup...")
    if verify_wiremock():
        print("\n" + "="*50)
        print("✅ WireMock setup complete!")
        print("="*50)
        print("\nWireMock server is running at http://localhost:8080")
        print("Admin UI available at http://localhost:8080/__admin")
        print("\nYou can now use WireMock in your tests:")
        print("  from wiremock import WireMockServer")
        print("\nSee references/wiremock-patterns.md for usage examples")
        print("="*50)
        print("\nPress Ctrl+C to stop the WireMock server")
        
        try:
            # Keep script running until interrupted
            process.wait()
        except KeyboardInterrupt:
            print("\n\n🛑 Stopping WireMock server...")
            process.terminate()
            process.wait()
            print("✅ WireMock server stopped")
    else:
        print("❌ WireMock verification failed")
        process.terminate()
        sys.exit(1)

if __name__ == '__main__':
    main()

FILE:scripts/setup_testcontainers.py
#!/usr/bin/env python3
"""
Setup script for Testcontainers
Configures testcontainers environment for integration testing
"""

import subprocess
import sys
import os

def check_docker():
    """Check if Docker is running and accessible"""
    try:
        result = subprocess.run(
            ['docker', 'version'],
            capture_output=True,
            text=True
        )
        if result.returncode == 0:
            print("✅ Docker is available")
            return True
        else:
            print("❌ Docker is not available")
            return False
    except FileNotFoundError:
        print("❌ Docker is not installed")
        return False

def install_python_dependencies():
    """Install required Python packages for testcontainers"""
    packages = [
        'testcontainers',
        'docker'
    ]
    
    for package in packages:
        try:
            subprocess.run(
                [sys.executable, '-m', 'pip', 'install', package],
                check=True
            )
            print(f"✅ Installed {package}")
        except subprocess.CalledProcessError as e:
            print(f"❌ Failed to install {package}: {e}")
            return False
    
    return True

def setup_environment():
    """Configure environment variables for testcontainers"""
    env_vars = {
        'TESTCONTAINERS_HOST_OVERRIDE': 'host.docker.internal',
        'TESTCONTAINERS_RYUK_DISABLED': 'true'  # Don't clean up containers after tests
    }
    
    # Add to shell profile
    profile = os.path.expanduser('~/.bashrc')
    if os.path.exists(profile):
        with open(profile, 'a') as f:
            f.write('\n# Testcontainers configuration\n')
            for key, value in env_vars.items():
                f.write(f'export {key}="{value}"\n')
        print(f"✅ Added testcontainers configuration to {profile}")
    
    return env_vars

def verify_setup():
    """Verify testcontainers setup by running a simple test"""
    try:
        from testcontainers.core.container import DockerContainer
        from alpine import AlpineContainer  # This might not be available, that's okay
        
        print("✅ Testcontainers Python package is installed")
        return True
    except ImportError as e:
        print(f"⚠️  Some testcontainers features not available: {e}")
        print("   This is normal for basic setup")
        return True

def main():
    """Main setup function"""
    print("🐋 Setting up Testcontainers environment...\n")
    
    # Step 1: Check Docker
    print("Step 1: Checking Docker...")
    if not check_docker():
        print("Please install and start Docker first")
        sys.exit(1)
    
    # Step 2: Install Python dependencies
    print("\nStep 2: Installing Python dependencies...")
    if not install_python_dependencies():
        print("Failed to install required packages")
        sys.exit(1)
    
    # Step 3: Configure environment
    print("\nStep 3: Configuring environment...")
    env_vars = setup_environment()
    
    # Step 4: Verify setup
    print("\nStep 4: Verifying setup...")
    verify_setup()
    
    print("\n" + "="*50)
    print("✅ Testcontainers setup complete!")
    print("="*50)
    print("\nYou can now use testcontainers in your tests:")
    print("  from testcontainers.postgres import PostgresContainer")
    print("  from testcontainers.redis import RedisContainer")
    print("\nSee references/testcontainers-guide.md for detailed usage")
    print("="*50)

if __name__ == '__main__':
    main()

FILE:scripts/start_localstack.py
#!/usr/bin/env python3
"""
Setup script for LocalStack
Starts LocalStack services for AWS testing without real AWS resources
"""

import subprocess
import sys
import os
import time
import signal

def check_docker():
    """Check if Docker is running and accessible"""
    try:
        result = subprocess.run(
            ['docker', 'version'],
            capture_output=True,
            text=True
        )
        if result.returncode == 0:
            print("✅ Docker is available")
            return True
        else:
            print("❌ Docker is not available")
            return False
    except FileNotFoundError:
        print("❌ Docker is not installed")
        return False

def install_localstack():
    """Install LocalStack CLI"""
    try:
        # Check if localstack is already installed
        result = subprocess.run(
            ['localstack', '--version'],
            capture_output=True,
            text=True
        )
        if result.returncode == 0:
            print(f"✅ LocalStack is installed: {result.stdout.strip()}")
            return True
    except FileNotFoundError:
        pass
    
    # Install LocalStack
    print("📥 Installing LocalStack...")
    try:
        subprocess.run(
            ['pip', 'install', 'localstack'],
            check=True
        )
        print("✅ LocalStack installed successfully")
        return True
    except subprocess.CalledProcessError as e:
        print(f"❌ Failed to install LocalStack: {e}")
        print("You can also install LocalStack via:")
        print("  brew install localstack/tap/localstack  # macOS")
        print("  pip install localstack  # pip")
        return False

def start_localstack(services=None, port=4566):
    """Start LocalStack services"""
    if services is None:
        services = ['s3', 'lambda', 'dynamodb', 'sns', 'sqs']
    
    print(f"🚀 Starting LocalStack services: {', '.join(services)}")
    
    # Build localstack command
    cmd = ['localstack', 'start', '--port', str(port)]
    for service in services:
        cmd.extend(['--services', service])
    
    print(f"   Starting on port {port}...")
    print(f"   Services: {', '.join(services)}")
    
    try:
        process = subprocess.Popen(
            cmd,
            stdout=subprocess.PIPE,
            stderr=subprocess.PIPE,
            text=True
        )
        
        # Wait for LocalStack to be ready
        print("⏳ Waiting for LocalStack to be ready...")
        max_attempts = 30
        for i in range(max_attempts):
            # Check if process is still running
            if process.poll() is not None:
                stdout, stderr = process.communicate()
                print(f"❌ LocalStack failed to start")
                print(f"   Error: {stderr}")
                return None
            
            time.sleep(2)
            print(f"   Waiting... ({(i+1)*2}s)", end='\r')
        
        print(f"\n✅ LocalStack started successfully!")
        print(f"   Endpoint: http://localhost:{port}")
        print(f"   AWS Region: us-east-1")
        
        return process
        
    except Exception as e:
        print(f"❌ Failed to start LocalStack: {e}")
        return None

def configure_aws_cli(port=4566):
    """Configure AWS CLI to use LocalStack"""
    print("\n⚙️  Configuring AWS CLI for LocalStack...")
    
    # Set environment variables
    env_vars = {
        'AWS_ACCESS_KEY_ID': 'test',
        'AWS_SECRET_ACCESS_KEY': 'test',
        'AWS_REGION': 'us-east-1',
        'AWS_ENDPOINT_URL_S3': f'http://localhost:{port}'
    }
    
    profile = os.path.expanduser('~/.bashrc')
    if os.path.exists(profile):
        with open(profile, 'a') as f:
            f.write('\n# LocalStack configuration\n')
            for key, value in env_vars.items():
                f.write(f'export {key}="{value}"\n')
        print(f"✅ Added LocalStack configuration to {profile}")
    
    return env_vars

def verify_localstack(port=4566):
    """Verify LocalStack is running by testing S3"""
    try:
        import boto3
        s3 = boto3.client(
            's3',
            endpoint_url=f'http://localhost:{port}',
            aws_access_key_id='test',
            aws_secret_access_key='test',
            region_name='us-east-1'
        )
        
        # Try to list buckets (should work even if empty)
        s3.list_buckets()
        print("✅ LocalStack S3 is responsive")
        return True
    except ImportError:
        print("⚠️  boto3 not installed (pip install boto3)")
        return True
    except Exception as e:
        print(f"⚠️  Could not verify LocalStack: {e}")
        return True

def cleanup_handler(signum, frame):
    """Handle cleanup on script exit"""
    print("\n\n🛑 Stopping LocalStack...")
    # LocalStack will be stopped automatically
    print("✅ LocalStack stopped")
    sys.exit(0)

def main():
    """Main setup function"""
    print("🏗️  Setting up LocalStack for AWS testing...\n")
    
    # Register cleanup handler
    signal.signal(signal.SIGINT, cleanup_handler)
    signal.signal(signal.SIGTERM, cleanup_handler)
    
    # Step 1: Check Docker
    print("Step 1: Checking Docker...")
    if not check_docker():
        print("Please install and start Docker first")
        sys.exit(1)
    
    # Step 2: Install LocalStack
    print("\nStep 2: Installing LocalStack...")
    if not install_localstack():
        sys.exit(1)
    
    # Step 3: Start LocalStack
    print("\nStep 3: Starting LocalStack services...")
    process = start_localstack(services=['s3'])  # Start with S3 for basic testing
    if not process:
        sys.exit(1)
    
    # Step 4: Configure AWS CLI
    print("\nStep 4: Configuring AWS CLI...")
    configure_aws_cli()
    
    # Step 5: Verify setup
    print("\nStep 5: Verifying LocalStack setup...")
    verify_localstack()
    
    print("\n" + "="*50)
    print("✅ LocalStack setup complete!")
    print("="*50)
    print("\nLocalStack is running with AWS services available locally")
    print("You can now test S3 operations without using real AWS!")
    print("\nExample usage in Python:")
    print("  import boto3")
    print("  s3 = boto3.client('s3', endpoint_url='http://localhost:4566')")
    print("\nSee references/localstack-s3-config.md for detailed configuration")
    print("="*50)
    print("\nPress Ctrl+C to stop LocalStack")
    
    # Keep script running until interrupted
    try:
        process.wait()
    except KeyboardInterrupt:
        cleanup_handler(signal.SIGINT, None)

if __name__ == '__main__':
    main()

FILE:templates/localstack-s3-tests.py
"""
LocalStack S3 Testing Template
Example for testing S3 integration without using real AWS resources

⚠️ SECURITY WARNING: This code is for INTEGRATION TESTING ONLY
- LocalStack services run locally and are isolated
- Never use for production data storage
- Use actual AWS services or managed alternatives for production
- Follow AWS security best practices in production environments
"""

import boto3
from localstack import start_localstack
import os

def test_s3_operations():
    """Example: Test S3 operations using LocalStack"""
    
    # Start LocalStack with S3 service
    with start_localstack(services=["s3"]) as localstack:
        # Configure S3 client to use LocalStack
        s3_client = boto3.client(
            's3',
            endpoint_url=localstack.endpoint_url,
            aws_access_key_id='test',
            aws_secret_access_key='test',
            region_name='us-east-1'
        )
        
        # Create test bucket
        bucket_name = 'test-bucket'
        s3_client.create_bucket(Bucket=bucket_name)
        
        # Upload test file
        test_content = b'Hello, LocalStack S3!'
        s3_client.put_object(
            Bucket=bucket_name,
            Key='test-file.txt',
            Body=test_content
        )
        
        # List objects
        objects = s3_client.list_objects_v2(Bucket=bucket_name)
        assert len(objects['Contents']) == 1
        assert objects['Contents'][0]['Key'] == 'test-file.txt'
        
        # Download and verify
        obj = s3_client.get_object(Bucket=bucket_name, Key='test-file.txt')
        downloaded_content = obj['Body'].read()
        assert downloaded_content == test_content
        
        # Delete object
        s3_client.delete_object(Bucket=bucket_name, Key='test-file.txt')
        
        # Delete bucket
        s3_client.delete_bucket(Bucket=bucket_name)
        
        print("✅ S3 integration test passed!")

def test_s3_file_operations():
    """Example: Test more complex S3 file operations"""
    
    with start_localstack(services=["s3"]) as localstack:
        s3_client = boto3.client(
            's3',
            endpoint_url=localstack.endpoint_url,
            aws_access_key_id='test',
            aws_secret_access_key='test',
            region_name='us-east-1'
        )
        
        bucket_name = 'file-operations-bucket'
        s3_client.create_bucket(Bucket=bucket_name)
        
        # Upload multiple files
        test_files = {
            'file1.txt': b'Content 1',
            'file2.txt': b'Content 2',
            'subdir/file3.txt': b'Content 3'
        }
        
        for key, content in test_files.items():
            s3_client.put_object(
                Bucket=bucket_name,
                Key=key,
                Body=content
            )
        
        # List all objects (including subdirectory)
        all_objects = s3_client.list_objects_v2(Bucket=bucket_name)
        assert len(all_objects['Contents']) == 3
        
        # Test pagination
        paginator = s3_client.get_paginator('list_objects_v2')
        pages = paginator.paginate(Bucket=bucket_name)
        total_count = sum(1 for page in pages for _ in page['Contents'])
        assert total_count == 3
        
        # Cleanup
        for key in test_files.keys():
            s3_client.delete_object(Bucket=bucket_name, Key=key)
        s3_client.delete_bucket(Bucket=bucket_name)
        
        print("✅ S3 file operations test passed!")

FILE:templates/sftp-integration-tests.py
"""
SFTP Integration Testing Template
Example for testing SFTP server connectivity and file operations

⚠️ SECURITY WARNING: This code is for INTEGRATION TESTING ONLY
- Never use in production environments
- Never use hardcoded credentials in real applications
- These patterns are strictly for isolated testing environments
- Use environment variables or secret management for credentials in production
"""

import paramiko
import tempfile
import os

def test_sftp_basic_operations():
    """Example: Test basic SFTP connectivity and operations"""
    
    # Note: This assumes a test SFTP server is available
    # In production, you might want to use a containerized SFTP server
    
    ssh = paramiko.SSHClient()
    ssh.set_missing_host_key_policy(paramiko.AutoAddPolicy())
    
    try:
        # Connect to SFTP server
        ssh.connect(
            hostname='sftp-test-server',
            port=2222,
            username='testuser',
            password='testpass',
            timeout=10
        )
        
        # Open SFTP channel
        sftp = ssh.open_sftp()
        
        # Create test directory
        test_dir = '/test/integration_test'
        try:
            sftp.mkdir(test_dir)
        except IOError:
            pass  # Directory might already exist
        
        # Create and upload test file
        test_file = os.path.join(test_dir, 'test_file.txt')
        with tempfile.NamedTemporaryFile(mode='w', delete=False) as tmp:
            tmp.write('Test SFTP content')
            tmp_path = tmp.name
        
        try:
            sftp.put(tmp_path, test_file)
            
            # Verify file exists
            file_attrs = sftp.stat(test_file)
            assert file_attrs.st_size > 0
            
            # Download and verify content
            with tempfile.NamedTemporaryFile(mode='w', delete=False) as download_tmp:
                download_path = download_tmp.name
            
            sftp.get(test_file, download_path)
            
            with open(download_path, 'r') as f:
                content = f.read()
                assert content == 'Test SFTP content'
            
            # List files in test directory
            files = sftp.listdir(test_dir)
            assert 'test_file.txt' in files
            
            # Delete test file
            sftp.remove(test_file)
            
            # Delete test directory
            sftp.rmdir(test_dir)
            
            print("✅ SFTP basic operations test passed!")
            
        finally:
            # Cleanup temp files
            os.unlink(tmp_path)
            if os.path.exists(download_path):
                os.unlink(download_path)
                
    finally:
        ssh.close()

def test_sftp_error_handling():
    """Example: Test error handling for SFTP operations"""
    
    ssh = paramiko.SSHClient()
    ssh.set_missing_host_key_policy(paramiko.AutoAddPolicy())
    
    try:
        # Test connection failure handling
        try:
            ssh.connect(
                hostname='invalid-host',
                port=2222,
                username='testuser',
                password='testpass',
                timeout=5
            )
            assert False, "Should have failed to connect"
        except (paramiko.AuthenticationException, 
                paramiko.SSHException, 
                TimeoutError):
            print("✅ Connection error handling test passed!")
            
    finally:
        if ssh.get_transport() is not None:
            ssh.close()

# Setup script for test SFTP server (using docker)
# This can be used in CI/CD pipelines
def setup_test_sftp_server():
    """
    Setup a test SFTP server using Docker
    Example for CI/CD integration
    """
    import subprocess
    
    # Start test SFTP server container
    cmd = [
        'docker', 'run', '-d',
        '--name', 'test-sftp-server',
        '-p', '2222:22',
        '-e', 'SFTP_USER=testuser',
        '-e', 'SFTP_PASSWORD=testpass',
        'atmoz/sftp:alpine'
    ]
    
    try:
        subprocess.run(cmd, check=True)
        print("✅ Test SFTP server started!")
        return True
    except subprocess.CalledProcessError as e:
        print(f"❌ Failed to start SFTP server: {e}")
        return False

FILE:templates/testcontainers-python.py
"""
Testcontainers Python Template
Basic example for integration testing with PostgreSQL using testcontainers

⚠️ SECURITY WARNING: This code is for INTEGRATION TESTING ONLY
- Containers are isolated and destroyed after testing
- Never expose test containers to untrusted networks
- Use official Docker images only
- Monitor resource usage in CI/CD environments
"""

from testcontainers.postgres import PostgresContainer
import psycopg2
from psycopg2 import sql

def test_database_integration():
    """Example: Test application with real PostgreSQL container"""
    
    # Start PostgreSQL container
    with PostgresContainer("postgres:15") as postgres:
        # Get connection string from container
        connection_url = postgres.get_connection_url()
        
        # Test database operations
        conn = psycopg2.connect(connection_url)
        cursor = conn.cursor()
        
        # Create test table
        cursor.execute("""
            CREATE TABLE IF NOT EXISTS users (
                id SERIAL PRIMARY KEY,
                name VARCHAR(100) NOT NULL,
                email VARCHAR(255) UNIQUE NOT NULL
            )
        """)
        
        # Insert test data
        cursor.execute(
            "INSERT INTO users (name, email) VALUES (%s, %s)",
            ("Test User", "[email protected]")
        )
        
        # Query test data
        cursor.execute("SELECT * FROM users WHERE name = %s", ("Test User",))
        result = cursor.fetchone()
        
        assert result[1] == "Test User"
        assert result[2] == "[email protected]"
        
        # Cleanup
        cursor.close()
        conn.close()
        print("✅ Database integration test passed!")

# Usage in pytest:
# def test_with_postgres(test_database_integration):
#     test_database_integration()

FILE:templates/wiremock-http-tests.py
"""
WireMock HTTP API Testing Template
Example for mocking and testing HTTP APIs with WireMock

⚠️ SECURITY WARNING: This code is for INTEGRATION TESTING ONLY
- WireMock server runs on localhost only
- Never expose mock servers to external networks
- Use for legitimate API testing and development
- Not intended for phishing or man-in-the-middle attacks
"""

from wiremock import WireMockServer
import requests

def test_api_with_wiremock():
    """Example: Test application against mocked HTTP API"""
    
    # Start WireMock server
    with WireMockServer(port=8080) as wiremock:
        # Mock GET /api/users endpoint
        wiremock.stub_for(
            request_method="GET",
            request_url="/api/users",
            response_body='{"users": [{"id": 1, "name": "Test User"}]}',
            response_status=200
        )
        
        # Mock POST /api/users endpoint
        wiremock.stub_for(
            request_method="POST",
            request_url="/api/users",
            request_body='{"name": "New User", "email": "[email protected]"}',
            response_body='{"id": 2, "name": "New User", "email": "[email protected]"}',
            response_status=201
        )
        
        # Test GET request
        response = requests.get("http://localhost:8080/api/users")
        assert response.status_code == 200
        data = response.json()
        assert len(data["users"]) == 1
        assert data["users"][0]["name"] == "Test User"
        
        # Test POST request
        new_user = {"name": "New User", "email": "[email protected]"}
        response = requests.post(
            "http://localhost:8080/api/users",
            json=new_user
        )
        assert response.status_code == 201
        created_user = response.json()
        assert created_user["id"] == 2
        
        print("✅ API integration test passed!")

def test_api_error_handling():
    """Example: Test error handling with mocked failures"""
    
    with WireMockServer(port=8081) as wiremock:
        # Mock 500 error
        wiremock.stub_for(
            request_method="GET",
            request_url="/api/users",
            response_body='{"error": "Internal Server Error"}',
            response_status=500
        )
        
        # Test error handling
        response = requests.get("http://localhost:8081/api/users")
        assert response.status_code == 500
        
        print("✅ Error handling test passed!")