openads-ai 0.2.32 → 0.4.0

package/dist/doctor.js

@@ -92,6 +92,45 @@ export async function runDoctor() {
         console.log(`  ${chalk.red('✗')} uvx: Not installed. Run 'curl -LsSf https://astral.sh/uv/install.sh | sh'`);
         hasErrors = true;
     }
+    // ─── Local AI Check ────────────────────────────────────────────────
+    if (config?.localBaseUrl) {
+        console.log(`\n${chalk.bold('Local AI')}`);
+        const baseUrl = config.localBaseUrl.replace(/\/$/, '');
+        // 1. Check if the endpoint is reachable
+        try {
+            const tagsUrl = `${baseUrl.replace('/v1', '')}/api/tags`;
+            const res = await fetch(tagsUrl, { signal: AbortSignal.timeout(3000) });
+            if (res.ok) {
+                const data = await res.json();
+                const models = (data.models || []).map((m) => m.name || m.model || '');
+                console.log(`  ${chalk.green('✓')} Ollama server: Reachable at ${baseUrl}`);
+                // 2. Check if the configured model is pulled
+                const configuredModel = config.provider.includes('/')
+                    ? config.provider.split('/').pop()
+                    : config.provider;
+                const modelFound = models.some(m => m === configuredModel || m.startsWith(configuredModel.split(':')[0]));
+                if (modelFound) {
+                    console.log(`  ${chalk.green('✓')} Model: ${chalk.cyan(configuredModel)} is available`);
+                }
+                else {
+                    console.log(`  ${chalk.red('✗')} Model: ${chalk.cyan(configuredModel)} not found in Ollama`);
+                    console.log(`     ${chalk.gray('Available models:')} ${models.length > 0 ? models.join(', ') : 'none'}`);
+                    console.log(`     ${chalk.gray(`Run: ollama pull ${configuredModel}`)}`);
+                    hasErrors = true;
+                }
+            }
+            else {
+                console.log(`  ${chalk.red('✗')} Ollama server: Not reachable at ${baseUrl}`);
+                console.log(`     ${chalk.gray('Start Ollama with: ollama serve')}`);
+                hasErrors = true;
+            }
+        }
+        catch (e) {
+            console.log(`  ${chalk.red('✗')} Ollama server: Connection failed — ${e.message}`);
+            console.log(`     ${chalk.gray('Make sure Ollama is running: ollama serve')}`);
+            hasErrors = true;
+        }
+    }
     if (hasErrors) {
         console.log(`\n${chalk.red('Some checks failed. Please run `openads setup` to configure your environment.')}`);
         process.exit(1);

package/dist/mcp-extension.js

@@ -4,16 +4,20 @@ import { hasGlobalRtk } from "./token-optimizer.js";
 import fs from "fs";
 import path from "path";
 import os from "os";
-// ─── Essential Campaign Analysis & Audit Tools ──────────────────────
-// Filtering down from 39 tools to 11 essential campaign performance tools
-// massively optimizes local LLM context, prevents tool confusion, and breaks repeating loops.
-const ESSENTIAL_META_TOOLS = new Set([
+// ─── Tier-Based Tool Filtering ──────────────────────────────────────
+// Express → skip MCP entirely (handled by OPENADS_SKIP_MCP env var)
+// Standard → 6 read-only discovery + performance tools
+// Full → 11 tools (read + write operations)
+const STANDARD_META_TOOLS = new Set([
     "get_ad_accounts",
     "list_campaigns",
     "get_campaign",
     "get_campaign_performance",
     "get_insights",
-    "list_ad_sets",
+    "list_ad_sets"
+]);
+const FULL_META_TOOLS = new Set([
+    ...STANDARD_META_TOOLS,
     "list_ads",
     "get_creative_performance",
     "pause_campaign",
@@ -33,6 +37,12 @@ export default async function (pi) {
     catch (e) {
         return;
     }
+    // Skip MCP tool registration during Autoresearch.
+    // The model never needs live ad platform tools when generating hypotheses,
+    // and each tool schema consumes ~150 tokens of scarce context.
+    if (process.env.OPENADS_SKIP_MCP === '1') {
+        return;
+    }
     const clients = [];
     // ─── Google Ads MCP ───────────────────────────────────────────────
     if (config.connectGoogle) {
@@ -77,12 +87,14 @@ export default async function (pi) {
         }
     }
     // ─── Dynamically Register Tools ──────────────────────────────────
+    const tier = process.env.OPENADS_TIER || 'standard';
+    const allowedMetaTools = tier === 'full' ? FULL_META_TOOLS : STANDARD_META_TOOLS;
     for (const { name: serverName, client } of clients) {
         try {
             const toolsResult = await client.listTools();
             for (const tool of toolsResult.tools) {
-                // Filter out advanced/OAuth/developer tools for Meta Ads to keep the LLM context extremely clean
-                if (serverName === "meta-ads" && !ESSENTIAL_META_TOOLS.has(tool.name)) {
+                // Filter Meta tools by tier (standard=6 read-only, full=11 read+write)
+                if (serverName === "meta-ads" && !allowedMetaTools.has(tool.name)) {
                     continue;
                 }
                 pi.registerTool({

package/dist/schedule.js

@@ -206,6 +206,8 @@ function uninstallCrontab(name) {
     });
 }
 // ─── Run a Scheduled Task ────────────────────────────────────────────
+// Applies the same mode-aware prompt + selective skill loading as the main CLI
+// so scheduled tasks work reliably on local models.
 export async function runScheduledTask(name) {
     const schedules = loadSchedules();
     const schedule = schedules.find(s => s.name === name);
@@ -247,23 +249,74 @@ export async function runScheduledTask(name) {
         env.OPENAI_BASE_URL = config.localBaseUrl;
         env.OPENAI_API_KEY = env.OPENAI_API_KEY || 'sk-local-ai-key-placeholder';
     }
-    const skillsDir = path.resolve(pkgDir, 'skills');
-    const contextDir = path.join(CONFIG_DIR, 'context');
-    const cleanModel = config.provider;
     const isLocal = !!config.localBaseUrl;
+    const cleanModel = config.provider;
     const modelIdForPi = isLocal && cleanModel.includes('/') ? cleanModel.split('/')[1] : cleanModel;
+    const skillsDir = path.resolve(pkgDir, 'skills');
+    const contextDir = path.join(CONFIG_DIR, 'context');
+    // ─── Mode-aware system prompt ───────────────────────────────────────
+    // Scheduled audit tasks use the 'default' prompt mode (they need MCP tools).
+    // Write a temporary system prompt file for this run.
+    const agentDir = path.join(CONFIG_DIR, 'agent');
+    if (!fs.existsSync(agentDir))
+        fs.mkdirSync(agentDir, { recursive: true });
+    const homeDir = os.homedir();
+    const contextPath = path.join(CONFIG_DIR, 'context', 'my-business.md');
+    const isLaunchMode = config.mode === 'launch';
+    const scheduleSystemPrompt = [
+        'You are OpenAds, an AI marketing assistant. You are running a scheduled automated task.',
+        'Your job: execute the task concisely and produce a clean, structured markdown report.',
+        'Use MCP tools to query live campaign data. Never use placeholder IDs.',
+        '',
+        '## Platform Tools',
+        '- For Meta: call get_ad_accounts() first (no params), then list_campaigns(account_id), then get_campaign_performance or get_insights.',
+        '- Anti-loop rule: never call the same tool twice in one turn.',
+        '',
+        '## Output Rules',
+        '- Structure your output as a clean markdown report with headers, tables, and bullet points.',
+        '- Flag issues clearly: 🔴 Critical | 🟡 Warning | 🟢 Opportunity.',
+        '- End with a numbered list of recommended actions.',
+        '',
+        `## Safety`,
+        `- Home directory: ${homeDir}. Never use placeholder paths.`,
+        isLaunchMode
+            ? '- Mode: Launch (Read-Write). Show a preview card and get Y/N before any write operation.'
+            : '- Mode: Audit (Read-Only). You can only read and analyze — no writes.',
+        '',
+        `## Business Context`,
+        fs.existsSync(contextPath)
+            ? `Read your business context file at ${contextPath} before starting.`
+            : 'No business context file found. Proceed with the task using available data.',
+    ].join('\n');
+    const scheduleSysPromptPath = path.join(agentDir, 'SCHEDULE-SYSTEM.md');
+    fs.writeFileSync(scheduleSysPromptPath, scheduleSystemPrompt);
+    // ─── Selective skill loading ────────────────────────────────────────
+    // Scheduled tasks are audit-type by default → load only the 3 ad platform skills.
+    // This saves ~7K tokens vs loading all 24 skills.
+    const scheduleSkills = [
+        path.join(skillsDir, 'ads', 'google-ads.md'),
+        path.join(skillsDir, 'ads', 'meta-ads.md'),
+        path.join(skillsDir, 'product-marketing.md'),
+    ].filter(p => fs.existsSync(p));
+    const skillArgs = [];
+    for (const skill of scheduleSkills) {
+        skillArgs.push('--skill', skill);
+    }
     const args = [
         piCliPath,
         '--model', modelIdForPi,
-        '--skill', skillsDir,
+        '--system-prompt', scheduleSysPromptPath,
+        ...skillArgs,
         ...(fs.existsSync(contextDir) ? ['--skill', contextDir] : []),
         '--print',
         schedule.prompt,
     ];
+    // Local models may be slow — give them up to 10 minutes
+    const timeoutMs = isLocal ? 600000 : 300000;
     const result = spawnSync('node', args, {
         env,
         encoding: 'utf8',
-        timeout: 300000, // 5 minute timeout
+        timeout: timeoutMs,
         stdio: ['ignore', 'pipe', 'pipe'],
     });
     if (result.stdout) {

package/dist/setup.js

@@ -33,7 +33,7 @@ export async function runSetup() {
         catch (e) { }
     }
     // Step 1: Model Selection
-    console.log(chalk.cyan('Step 1/4: Choose your AI model\n'));
+    console.log(chalk.cyan('Step 1/6: Choose your AI model\n'));
     const providerChoices = [
         { name: 'google', message: 'Google (Gemini)' },
         { name: 'openai', message: 'OpenAI (ChatGPT)' },
@@ -210,8 +210,47 @@ export async function runSetup() {
         console.log(chalk.green(`\n✓ Local AI configured — ready to connect to ${localBaseUrl}.\n`));
     }
     console.log(chalk.gray('─────────────────────────────────────────\n'));
-    // Step 2: Choose operational mode
-    console.log(chalk.cyan('Step 2/5: Choose operational mode\n'));
+    // Step 2: Experience Tier
+    console.log(chalk.cyan('Step 2/6: Choose your experience tier\n'));
+    console.log('  OpenAds adapts its depth based on your model\'s capability:\n');
+    console.log(`  ${chalk.yellow('⚡ Express')}   — Fast & reliable. Compact prompts, structured output.`);
+    console.log(`  ${chalk.blue('📊 Standard')}  — Balanced depth. Live data tools, detailed reports.`);
+    console.log(`  ${chalk.magenta('🚀 Full')}      — Maximum depth. Multi-step analysis, creative exploration.\n`);
+    // Auto-detect recommended tier based on model choice
+    const isLocalSetup = provider === 'local';
+    const modelLower = (selectedModel || localModelName || customModel || '').toLowerCase();
+    let suggestedTier = 'full';
+    if (isLocalSetup) {
+        suggestedTier = (modelLower.includes('70b') || modelLower.includes('72b') || modelLower.includes('405b')) ? 'standard' : 'express';
+    }
+    else {
+        const isLiteTier = modelLower.includes('flash') || modelLower.includes('mini') || modelLower.includes('haiku');
+        suggestedTier = isLiteTier ? 'standard' : 'full';
+    }
+    const tierChoices = [
+        { name: 'express', message: `${chalk.yellow('⚡')} Express  — Best for: Llama 8B, Mistral 7B, Phi-3  ${suggestedTier === 'express' ? chalk.green('← Recommended') : ''}` },
+        { name: 'standard', message: `${chalk.blue('📊')} Standard — Best for: Gemini Flash, GPT-4o Mini, Llama 70B  ${suggestedTier === 'standard' ? chalk.green('← Recommended') : ''}` },
+        { name: 'full', message: `${chalk.magenta('🚀')} Full     — Best for: GPT-4o, Claude Sonnet, Gemini Pro  ${suggestedTier === 'full' ? chalk.green('← Recommended') : ''}` },
+    ];
+    let initialTierIndex = tierChoices.findIndex(c => c.name === (existingConfig.tier || suggestedTier));
+    if (initialTierIndex === -1)
+        initialTierIndex = tierChoices.findIndex(c => c.name === suggestedTier);
+    const { selectedTier } = await enquirer.prompt({
+        type: 'select',
+        name: 'selectedTier',
+        message: 'Select your experience tier:',
+        choices: tierChoices,
+        initial: initialTierIndex
+    });
+    const tierLabels = {
+        express: `${chalk.yellow('⚡ Express')}`,
+        standard: `${chalk.blue('📊 Standard')}`,
+        full: `${chalk.magenta('🚀 Full')}`,
+    };
+    console.log(chalk.green(`\n✓ Experience tier: ${tierLabels[selectedTier]}.\n`));
+    console.log(chalk.gray('─────────────────────────────────────────\n'));
+    // Step 3: Choose operational mode
+    console.log(chalk.cyan('Step 3/6: Choose operational mode\n'));
     console.log('OpenAds has two operational modes:');
     console.log(` - ${chalk.green.bold('Audit Mode (Safe / Read-only)')}: AI can analyze performance, find budget waste, and recommend strategies. Zero risk.`);
     console.log(` - ${chalk.red.bold('Launch Mode (Read-Write)')}: AI is authorized to optimize bids, modify budgets, and launch ads (always requires confirmation).\n`);
@@ -228,8 +267,8 @@ export async function runSetup() {
     mode = modeAnswers.selectedMode;
     console.log(chalk.green(`\n✓ Operational mode configured: ${mode === 'launch' ? 'Launch Mode (Read-Write)' : 'Audit Mode (Safe / Read-only)'}.\n`));
     console.log(chalk.gray('─────────────────────────────────────────\n'));
-    // Step 3: Google Ads
-    console.log(chalk.cyan('Step 3/5: Connect Google Ads (optional)\n'));
+    // Step 4: Google Ads
+    console.log(chalk.cyan('Step 4/6: Connect Google Ads (optional)\n'));
     console.log('OpenAds can read and analyze your Google Ads campaigns, keywords, and performance.\n');
     const { connectGoogle } = await enquirer.prompt({
         type: 'confirm',
@@ -268,7 +307,7 @@ export async function runSetup() {
     }
     console.log(chalk.gray('─────────────────────────────────────────\n'));
     // Step 4: Meta Ads
-    console.log(chalk.cyan('Step 4/5: Connect Meta Ads (optional)\n'));
+    console.log(chalk.cyan('Step 5/6: Connect Meta Ads (optional)\n'));
     console.log('OpenAds can read your Meta campaigns, creatives, and audience performance.\n');
     let metaToken = '';
     const { connectMeta } = await enquirer.prompt({
@@ -374,8 +413,8 @@ export async function runSetup() {
         }
     }
     console.log(chalk.gray('─────────────────────────────────────────\n'));
-    // Step 5: Business Context
-    console.log(chalk.cyan('Step 5/5: Tell me about your business\n'));
+    // Step 6: Business Context
+    console.log(chalk.cyan('Step 6/6: Tell me about your business\n'));
     const { productContext } = await enquirer.prompt({
         type: 'input',
         name: 'productContext',
@@ -398,6 +437,7 @@ export async function runSetup() {
         provider: finalModel,
         apiKey,
         localBaseUrl,
+        tier: selectedTier,
         mode,
         connectGoogle,
         metaToken,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openads-ai",
-  "version": "0.2.32",
+  "version": "0.4.0",
   "description": "Open-source AI command center for digital marketers. Audit campaigns, write ad copy, and build strategies — from your terminal.",
   "main": "dist/cli.js",
   "bin": {

package/skills/analytics/analytics.md

@@ -1,32 +1,102 @@
 ---
 name: analytics
-description: Set up tracking, analyze traffic, and fix attribution gaps.
+description: Set up tracking, analyze traffic, interpret GA4 data, and fix attribution gaps.
 ---
 # Analytics Skill
 
 ## When to Use This Skill
 
-Activate when analyzing website traffic, setting up GA4, tracking events, or dealing with attribution gaps.
+Activate when the user is:
+- Setting up or auditing GA4 or Google Analytics tracking
+- Diagnosing traffic drops, conversion rate changes, or attribution issues
+- Analyzing funnel performance, event data, or audience behavior
+- Building dashboards or interpreting key marketing metrics
+
+Read `product-marketing.md` first to understand which metrics matter most for this business.
+
+---
+
+## GA4 Audit Checklist
+
+Before drawing conclusions, verify these foundational items:
+
+| Check | How to Verify |
+|-------|---------------|
+| GA4 tag firing | Check Realtime > Events — do page_view events appear? |
+| Conversion events | Confirm key_events are marked in Admin > Events |
+| Cross-domain tracking | Use DebugView to verify cookies persist across domains |
+| Bot traffic exclusion | Admin > Data Filters — is "Internal traffic" excluded? |
+| Sampling thresholds | Use smaller date ranges or BigQuery for sampled reports |
 
 ---
 
-## The Attribution Problem
-Always remind the user: no platform has 100% perfect tracking. 
-- **Platform data (Ads, Meta)** claims credit for everything.
-- **GA4** underreports due to GDPR consent rejection and cross-device drops.
-- **Truth** is usually in the middle. Use GA4 for relative trends, not absolute truth.
-
-## GA4 Event Strategy
-Recommend standard events over custom events when possible:
-1. `generate_lead`
-2. `sign_up`
-3. `purchase`
-4. `add_to_cart`
-
-## UTM Best Practices
-Enforce strict UTM taxonomy:
-- `utm_source`: The platform (e.g., `google`, `facebook`, `linkedin`)
-- `utm_medium`: The channel type (e.g., `cpc`, `social`, `email`)
-- `utm_campaign`: The specific campaign name
-- `utm_content`: The ad variant or creative
-- `utm_term`: The keyword (for search)
+## Core Metrics to Always Report
+
+When summarizing analytics, structure findings around these:
+
+```
+Sessions       | The entry point — is traffic growing or shrinking?
+Engaged rate   | >50% is healthy. <30% is a red flag.
+Avg. engagement| Low time on page = message mismatch or poor UX
+Key events     | Purchases, signups, demo requests — the real measure
+Conversion rate| Key events / Sessions. Benchmark vs. industry.
+Bounce rate    | (GA4 definition differs from UA — clarify which)
+Source/Medium  | Which channels drive quality vs. volume?
+```
+
+---
+
+## Attribution Models
+
+Explain these to the user when comparing channel performance:
+
+- **Last Click** (default): Credits the last touchpoint before conversion. Biased toward bottom-of-funnel channels (search, retargeting).
+- **First Click**: Credits the first touchpoint. Biased toward top-of-funnel (social, display).
+- **Data-Driven** (GA4 default): ML-based, distributes credit across touchpoints. Best for accounts with >1K conversions/month.
+- **Linear**: Equal credit to all touchpoints. Simple but rarely accurate.
+
+> Always ask: "Are you comparing channels using the same attribution model?" Mixing models is a common mistake.
+
+---
+
+## Diagnosing Traffic Drops
+
+If the user reports a traffic or conversion drop:
+
+1. **Isolate the time range**: Compare week-over-week and year-over-year to rule out seasonality.
+2. **Segment by channel**: Did organic, paid, or direct drop? Or all of them?
+3. **Check for tracking breaks**: Did the drop coincide with a code deploy or tag manager update?
+4. **Look at landing pages**: Which pages lost traffic? Is it a crawling/indexing issue?
+5. **Compare device segments**: Did mobile drop while desktop held? Could be a UX or load speed issue.
+6. **Check Search Console**: Organic impressions vs. clicks — ranking drop or CTR drop?
+
+---
+
+## Output Format
+
+When reporting analytics findings, use this structure:
+
+```markdown
+## Analytics Summary — [Date Range]
+
+### 📊 Traffic Overview
+| Metric | This Period | Prior Period | Change |
+|--------|-------------|--------------|--------|
+| Sessions | | | |
+| Engaged Rate | | | |
+| Key Events | | | |
+| CVR | | | |
+
+### 🔴 Critical Issues
+- [Issue]: [Impact] → [Recommended Action]
+
+### 🟡 Warnings
+- [Issue]: [Impact] → [Recommended Action]
+
+### 🟢 Opportunities
+- [Opportunity]: [Potential Impact] → [Next Step]
+
+### 📋 Recommended Actions (Priority Order)
+1. [Action] — [Expected Impact]
+2. [Action] — [Expected Impact]
+```

package/skills/automation/autoresearch-debug.md

@@ -0,0 +1,41 @@
+---
+name: autoresearch-debug
+description: Hypothesis-driven root cause analysis to diagnose underperforming marketing campaigns or landing pages.
+---
+# Autoresearch: Debug Underperformance (`/autoresearch:debug`)
+
+## When to Use This Skill
+
+Activate this skill when the user triggers `/autoresearch:debug` or selects "Debug underperformance" from the submenu. Use this when a campaign, landing page, or funnel experiences a sudden drop or prolonged stagnation in performance and the user wants to identify the root cause.
+
+---
+
+## 8 Diagnostics Hypotheses
+
+The debugging engine tests the problem against 8 potential root causes:
+
+1. **Creative Fatigue**: High frequency has exhausted creative interest, leading to lower CTR.
+2. **Audience Saturation**: The targeted audience pool is depleted; conversion costs are climbing.
+3. **Competitor Entry**: A new competitor has launched a aggressive offer or outbid your key terms.
+4. **Seasonality / Macro**: Holiday shifts, weekend drops, or economic news are depressing demand.
+5. **Platform Algorithm**: Ad delivery optimization has shifted or a bidding policy change has occurred.
+6. **Landing Page Regression**: Recent code/content updates have broken checkout or slowed down page load.
+7. **Tracking Break**: Pixels are not firing; conversion events are missing or duplicated in reporting.
+8. **Message-Market Misfit**: The ad message does not align with landing page expectations, causing high bounce rates.
+
+---
+
+## The 15-Iteration Diagnostic Loop
+
+- **Iterations 1-8**: Systematically test each of the 8 hypotheses against the campaign's symptoms and metrics.
+- **Iterations 9-12**: Gather additional evidence, narrowing the suspects down to the primary root cause.
+- **Iterations 13-15**: Generate a targeted recovery roadmap to fix the issue and restore performance.
+
+---
+
+## Output Deliverables
+
+1. **Root Cause Diagnostic Table**:
+   - A list of the tested hypotheses, matched with the observed evidence and rated by likelihood (Primary Cause / Contributing / Ruled Out).
+2. **Campaign Recovery Plan**:
+   - Immediate actions to take (e.g. refresh creative, fix pixel, adjust target bid) to get the campaign back on track.

package/skills/automation/autoresearch-evals.md

@@ -0,0 +1,34 @@
+---
+name: autoresearch-evals
+description: Analyze past experiment and campaign results to extract patterns and recommend the next test.
+---
+# Autoresearch: Analyze Past Results (`/autoresearch:evals`)
+
+## When to Use This Skill
+
+Activate this skill when the user triggers `/autoresearch:evals` or selects "Analyze past results" from the submenu. Use this to audit and evaluate past campaign data, CSV experiment logs, or prior loop results to see what worked, what failed, and what to do next.
+
+---
+
+## Analysis Methodology
+
+Analyze the user's prior data looking for five critical structural indicators:
+
+1. **Winning Patterns**: What commonalities exist in top performers? (e.g. "Action-oriented CTAs drove 40% higher click rates", "Testimonial copy outperformed benefit claims").
+2. **Losing Patterns**: What should we stop doing? (e.g. "Discount offers attracted low-LTV customers", "Passive hooks underperformed across all demographics").
+3. **Trends**: How is performance moving over time? Are click costs increasing while conversions decrease?
+4. **Plateaus**: Identify where optimization gains have stalled (e.g. "CTR has remained flat at 1.2% for 4 weeks despite creative testing").
+5. **Channel Gaps**: Where are we missing attribution or volume?
+
+---
+
+## Output Deliverables
+
+Provide a comprehensive **Experiment Evals Report**:
+
+1. **Performance Trend Summary**:
+   - A concise paragraph outlining the direction of performance, summarizing details from the ingested data.
+2. **Winners & Losers Table**:
+   - A table contrasting winning elements (e.g., specific angles, offers, hooks) with losing elements, showing concrete data patterns.
+3. **The Next Move Recommendation**:
+   - The exact next experiment to run based on these findings. This should define: the new hypothesis to test, the target metric, and how to set it up in the core loop.

package/skills/automation/autoresearch-fix.md

@@ -0,0 +1,40 @@
+---
+name: autoresearch-fix
+description: Systematically audit and resolve issues in marketing assets one-by-one.
+---
+# Autoresearch: Fix Issues One-by-One (`/autoresearch:fix`)
+
+## When to Use This Skill
+
+Activate this skill when the user triggers `/autoresearch:fix` or selects "Fix issues one-by-one" from the submenu. Use this to systematically review ad copy, landing pages, or tracking setups to identify and repair minor errors, policy compliance violations, or layout issues.
+
+---
+
+## 6 Common Asset Issue Classes
+
+The engine checks and corrects issues in 6 areas:
+
+1. **Character Limit Violations**: Ad headlines/descriptions exceeding platform limits (e.g. Meta 40-char headline; Google 30-char headline).
+2. **Broken Tracking Pixels**: Missing conversion tags, incomplete UTM parameter structures, or broken custom events.
+3. **Non-Compliant Copy**: Copy that risks being flagged by platform policies (e.g., using prohibited words, making unsubstantiated claims, missing required disclosures).
+4. **Accessibility Obstacles**: Missing image alt texts, poor text-to-background contrast ratios, or missing navigation labels.
+5. **Broken Links & Redirects**: Non-functioning URLs or loops in redirects.
+6. **Branding Inconsistencies**: Layouts, vocabulary, or style guides that do not match the brand guidelines.
+
+---
+
+## The 20-Iteration Systematic Repair Loop
+
+The engine operates on a strict **Identify ➡️ Fix ➡️ Verify ➡️ Repeat** iteration cycle for 20 rounds:
+- **Phase 1 (Iterations 1-8)**: Crawl the assets to build a checklist of all existing errors.
+- **Phase 2 (Iterations 9-16)**: Resolve the issues one-by-one.
+- **Phase 3 (Iterations 17-20)**: Re-test all corrected items to verify they are perfectly resolved.
+
+---
+
+## Output Deliverables
+
+1. **Resolved Issues Registry**:
+   - A table listing the issues found, their severity, the exact fix applied, and the verification status (Resolved / Verification Passed).
+2. **Hardened Asset Package**:
+   - The final, cleaned-up copy or configuration code ready for immediate use.

package/skills/automation/autoresearch-improve.md

@@ -0,0 +1,39 @@
+---
+name: autoresearch-improve
+description: Research ICP pain points, competitor gaps, and trends to generate growth briefs and PRDs.
+---
+# Autoresearch: Research ICP & Growth (`/autoresearch:improve`)
+
+## When to Use This Skill
+
+Activate this skill when the user triggers `/autoresearch:improve` or selects "Research ICP & growth" from the submenu. This command runs a deep research and growth discovery engine across 15 iterations, producing prioritized Product Requirement Documents (PRDs) and campaign briefs for marketing.
+
+---
+
+## 5 Focus Pillars for Research
+
+The loop runs for **15 iterations**, systematically exploring five categories of opportunities:
+
+1. **ICP Pain Points**: Deep-dive into ideal customer profile challenges, jobs-to-be-done, unmet needs, and common buying friction points.
+2. **Competitor Gaps**: Identify what competitors are weak at, what messaging angles they are missing, and where their positioning leaves room to win.
+3. **Market Timing**: Analyze seasonal trends, cultural moments, emerging consumer behaviors, and market-level signals.
+4. **Channel & Experience**: Uncover platform-specific channel opportunities (e.g. YouTube shorts, TikTok hook styles) and funnel/UX improvement gaps.
+5. **Revenue & Growth**: Identify monetization, pricing, bundles, upselling, or retention/referral loops that can scale revenue.
+
+---
+
+## The 15-Iteration Loop
+
+Run 15 iterations internally, refining and prioritizing the discoveries:
+- **Phase 1 (Iterations 1-5)**: Scout and extract raw opportunities in each category.
+- **Phase 2 (Iterations 6-10)**: Evaluate and score opportunities based on potential impact, confidence, and ease of execution (ICE framework).
+- **Phase 3 (Iterations 11-15)**: Flesh out the top scoring opportunity into a complete, professional **Marketing Campaign Brief / PRD**.
+
+---
+
+## Deliverables
+
+1. **Prioritized Opportunity Matrix**:
+   - A markdown table listing the top opportunities, categorized, scored by potential impact (High/Medium/Low), and showing target customer value.
+2. **Campaign Brief / PRD**:
+   - For the highest scoring opportunity, output a comprehensive deployment brief covering: Target Audience, Value Proposition, Creative/Ad Concept, Recommended Channels, Metric/Measurement Plan, and a detailed Implementation Checklist.

package/skills/automation/autoresearch-learn.md

@@ -0,0 +1,31 @@
+---
+name: autoresearch-learn
+description: Competitive intelligence engine to analyze competitor assets and generate messaging playbooks.
+---
+# Autoresearch: Learn from the Market (`/autoresearch:learn`)
+
+## When to Use This Skill
+
+Activate this skill when the user triggers `/autoresearch:learn` or selects "Learn from the market" from the submenu. This runs a competitive intelligence loop across 10 iterations, analyzing competitor landing pages, ad copy, positioning, and strategies to generate a **Competitive Messaging Playbook**.
+
+---
+
+## 10-Iteration Competitive Research Loop
+
+The engine operates over **10 iterations** to scout, distill, and adapt market insights:
+
+- **Iterations 1-3 (Scout)**: Analyze known competitors, searching for their active ad variants, main landing page structures, and core hooks. Identify their primary and secondary hooks (e.g. price-focused vs quality-focused).
+- **Iterations 4-6 (Analyze & Score)**: Map out competitor messaging positioning. Identify where they are strong (e.g. powerful social proof) and where they are weak (e.g. slow page speed, generic CTAs).
+- **Iterations 7-9 (Differentiate)**: Formulate counter-positioning angles. How can the user's brand stand out? What specific benefit can we highlight that competitors ignore?
+- **Iteration 10 (Consolidate)**: Synthesize insights into a highly actionable playbook.
+
+---
+
+## Output Deliverables
+
+1. **Competitor Mapping Table**:
+   - A comparison table comparing the user's business with 2-3 key competitors on value proposition, main CTA, and core ad hook.
+2. **Competitive Messaging Playbook**:
+   - **Gaps Identified**: Messaging spaces left wide open by competitors.
+   - **Recommended Messaging Angles**: 3 concrete, counter-positioning headlines/angles to test immediately in your campaigns to steal market share.
+   - **SWOT-Style Summary**: Strategic cheat sheet for your marketing team.