sc-research 1.0.1

package/templates/base/commands/controversy.md

@@ -0,0 +1,28 @@
+---
+description: Find controversial debates in existing research data.
+---
+
+1. Check for data existence
+
+    > Ensure `reddit_data.json` or `x_data.json` exists in the current directory.
+
+2. Check freshness for the current request
+
+    > Confirm raw data matches the requested topic and date window (if provided). If it does not match, re-fetch with **deep research**: `sc-research research:deep "TOPIC"`.
+
+3. Run the controversy skill
+
+    > Use the `communities_controversy` skill to identify polarizing topics, extract opposing quotes, and generate `classified_controversy.json`.
+
+4. Validate output schema
+
+    > Ensure `classified_controversy.json` includes:
+    >
+    > - `topic`
+    > - `overall_divisiveness`
+    > - `controversies` array
+    > - each controversy contains `topic`, `heat_score`, `divisiveness`, `side_a`, and `side_b`
+    > - each side contains `position`, `supporter_count`, and `sample_quote` with `text`, `author`, `link`
+
+5. Display the results
+    > Read `classified_controversy.json` and display controversies with side-by-side opposing views and heat scores.

package/templates/base/commands/deep-research.md

@@ -0,0 +1,25 @@
+---
+description: Deeply research a topic and route to the best analysis template. This is the default fetch depth for all templates.
+---
+
+1. Run the deep research fetcher
+
+    > `sc-research research:deep "ARGUMENTS"` (you may also add `--from=YYYY-MM-DD --to=YYYY-MM-DD` for a custom window)
+
+2. Route to the right analysis mode
+
+    > Follow **Intent → Template Routing** rules in `using_communities_research`.
+    >
+    > - If the user explicitly asks for "full analysis", "everything", or "all views": run all 4 templates in order (`rank` -> `sentiment` -> `trend` -> `controversy`).
+    > - Otherwise: pick the SINGLE most suitable template for the user's question.
+
+3. Validate outputs before presenting
+
+    > Confirm the generated `classified_*.json` file(s):
+    >
+    > - Match the requested topic (or close variant of the same topic).
+    > - Match requested date window when `--from/--to` was provided.
+    > - Include required fields from `web/src/types.ts`.
+
+4. Display the results
+    > Present whichever template output(s) were selected after validation.

package/templates/base/commands/discovery.md

@@ -0,0 +1,27 @@
+---
+description: Discover viral topics and emerging themes from existing research data.
+---
+
+1. Check for data existence
+
+    > Ensure `reddit_data.json` or `x_data.json` exists in the current directory.
+
+2. Check freshness for the current request
+
+    > Confirm raw data matches the requested topic and date window (if provided). If it does not match, re-fetch with **deep research**: `sc-research research:deep "TOPIC" --mode=discovery`.
+
+3. Run the discovery skill
+
+    > Use the `communities_discovery` skill to cluster posts by topic and generate `classified_discovery.json`.
+
+4. Validate output schema
+
+    > Ensure `classified_discovery.json` includes:
+    >
+    > - `period`
+    > - `total_posts_analyzed`
+    > - `trending_topics` array
+    > - per topic: `id`, `topic_name`, `description`, `category`, `engagement_score`, `sentiment`, `key_posts`
+
+5. Display the results
+    > Read `classified_discovery.json` and display the discovered topics with their engagement scores, sentiment, and top posts.

package/templates/base/commands/quick.md

@@ -0,0 +1,14 @@
+---
+description: Quick research a topic and get a fast text answer (Reddit only, skips X).
+---
+
+1. Run the quick research fetcher (Reddit only)
+   > `sc-research research "ARGUMENTS"`
+   >
+   > This fetches Reddit data only and skips X for speed. Use `/research` if you need both sources.
+
+2. Read the raw data
+   > Read `reddit_data.json` only. Ignore `x_data.json` even if it exists from a prior run.
+
+3. Provide a concise answer
+   > Synthesize a 3-5 sentence answer directly from the Reddit data. Mention the community favorite, 1-2 alternatives, and a real user quote. Do NOT generate any classified files.

package/templates/base/commands/rank.md

@@ -0,0 +1,27 @@
+---
+description: Rank and classify existing research data.
+---
+
+1. Check for data existence
+
+    > Ensure `reddit_data.json` or `x_data.json` exists in the current directory.
+
+2. Check freshness for the current request
+
+    > Confirm raw data matches the requested topic and date window (if provided). If it does not match, re-fetch with **deep research**: `sc-research research:deep "TOPIC"`.
+
+3. Run the ranking skill
+
+    > Use the `communities_rank` skill to generate `classified_rank.json` from the existing data files.
+
+4. Validate output schema
+
+    > Ensure `classified_rank.json` includes:
+    >
+    > - `topic`
+    > - `key_insights` (array)
+    > - `products` (array)
+    > - per product: `rank`, `name`, `sentiment`, `mentions`, `estimated_engagement_score`, `consensus`, `pros`, `cons`
+
+5. Display the results
+    > Read `classified_rank.json` and display key insights plus a summary of the ranked products.

package/templates/base/commands/research.md

@@ -0,0 +1,10 @@
+1. Run the research fetcher
+
+    > `sc-research research "ARGUMENTS"` (optionally add `--from=YYYY-MM-DD --to=YYYY-MM-DD` to focus on a specific date range)
+
+2. Analyze the results
+
+    > Read the generated `reddit_data.json` and `x_data.json`.
+
+3. Provide an answer
+    > Based on the data, provide a concise answer including the Community Favorite, decent alternatives, and a representative quote.

package/templates/base/commands/sentiment.md

@@ -0,0 +1,28 @@
+---
+description: Analyze sentiment from existing research data.
+---
+
+1. Check for data existence
+
+    > Ensure `reddit_data.json` or `x_data.json` exists in the current directory.
+
+2. Check freshness for the current request
+
+    > Confirm raw data matches the requested topic and date window (if provided). If it does not match, re-fetch with **deep research**: `sc-research research:deep "TOPIC"`.
+
+3. Run the sentiment skill
+
+    > Use the `communities_sentiment` skill to analyze the raw data and generate `classified_sentiment.json`.
+
+4. Validate output schema
+
+    > Ensure `classified_sentiment.json` includes:
+    >
+    > - `topic`
+    > - `overall_mood`
+    > - `distribution` (`very_positive`, `positive`, `mixed`, `negative`)
+    > - `by_source` with both `reddit` and `x`
+    > - `product_sentiments`
+
+5. Display the results
+    > Read `classified_sentiment.json` and display the overall mood, sentiment distribution, and per-product sentiment breakdown.

package/templates/base/commands/test-research.md

@@ -0,0 +1,9 @@
+---
+description: Test the research tool with fixed URLs.
+---
+
+1. Run the fixed test script
+   > `sc-research test:fixed`
+
+2. Report status
+   > Report success if the command exits with code 0, otherwise report failure.

package/templates/base/commands/trend.md

@@ -0,0 +1,27 @@
+---
+description: Analyze discussion trends over time from existing research data.
+---
+
+1. Check for data existence
+
+    > Ensure `reddit_data.json` or `x_data.json` exists in the current directory.
+
+2. Check freshness for the current request
+
+    > Confirm raw data matches the requested topic and date window (if provided). If it does not match, re-fetch with **deep research**: `sc-research research:deep "TOPIC"`.
+
+3. Run the trend skill
+
+    > Use the `communities_trend` skill to parse dates, choose an adaptive granularity (day/week/month), and generate `classified_trend.json`.
+
+4. Validate output schema
+
+    > Ensure `classified_trend.json` includes:
+    >
+    > - `topic`
+    > - `date_range` with `from` and `to`
+    > - `timeline` entries with `period`, `post_count`, `total_engagement`, `reddit_posts`, `x_posts`
+    > - `key_moments` entries with `date`, `event`, `significance`
+
+5. Display the results
+    > Read `classified_trend.json` and display timeline activity, engagement trends, and key moments.

package/templates/base/commands/visualize.md

@@ -0,0 +1,14 @@
+---
+description: Launch the visualization dashboard.
+---
+
+1. Check for classified data
+
+    > Ensure at least one `classified_*.json` file exists (e.g., `classified_rank.json`, `classified_sentiment.json`, `classified_trend.json`, `classified_controversy.json`). If none exist, suggest running `/rank`, `/sentiment`, `/trend`, or `/controversy` first.
+
+2. Launch the visualizer
+
+    > `sc-research visualize`
+
+3. Inform the user
+    > Tell the user to open the URL provided by the command (usually http://localhost:5173). The dashboard will show tabs for each available classified file.

package/templates/base/manifest.json

@@ -0,0 +1,119 @@
+{
+    "version": 1,
+    "templates": [
+        {
+            "id": "communities_fetch",
+            "kind": "skill",
+            "description": "Worker skill that fetches raw discussion data from Reddit and X (Twitter) for a given topic. Returns raw JSON files.",
+            "bodyFile": "skills/communities_fetch.md"
+        },
+    {
+      "id": "communities_rank",
+      "kind": "skill",
+      "description": "Analyze raw social media data (Reddit/X) to produce a ranked, classified report with strict JSON output.",
+      "bodyFile": "skills/communities_rank.md"
+    },
+    {
+      "id": "communities_sentiment",
+      "kind": "skill",
+      "description": "Worker skill that analyzes raw social media data to produce a sentiment breakdown report with strict JSON output.",
+      "bodyFile": "skills/communities_sentiment.md"
+    },
+    {
+      "id": "communities_trend",
+      "kind": "skill",
+      "description": "Worker skill that analyzes raw social media data to produce a trend timeline report with strict JSON output.",
+      "bodyFile": "skills/communities_trend.md"
+    },
+    {
+      "id": "communities_controversy",
+      "kind": "skill",
+      "description": "Worker skill that analyzes raw social media data to identify polarizing topics and produce a controversy map with strict JSON output.",
+      "bodyFile": "skills/communities_controversy.md"
+    },
+    {
+      "id": "communities_discovery",
+      "kind": "skill",
+      "description": "Worker skill that analyzes raw social media data to discover and cluster high-signal emerging topics.",
+      "bodyFile": "skills/communities_discovery.md"
+    },
+    {
+      "id": "communities_visualize",
+      "kind": "skill",
+      "description": "Worker skill that launches a local web dashboard to visualize all available classified research data.",
+      "bodyFile": "skills/communities_visualize.md"
+    },
+    {
+      "id": "communities_research_test",
+      "kind": "skill",
+      "description": "Test the communities research skill with fixed Reddit links (no API key needed). Fetches data and returns JSON for AI classification.",
+      "bodyFile": "skills/communities_research_test.md"
+    },
+    {
+      "id": "using_communities_research",
+      "kind": "skill",
+      "description": "Orchestrator skill that understands user intent and routes to the most suitable analysis template.",
+      "bodyFile": "skills/using_communities_research.md"
+    },
+        {
+            "id": "research",
+            "kind": "command",
+            "description": "Research a topic using the Quick Answer flow.",
+            "bodyFile": "commands/research.md"
+    },
+    {
+      "id": "quick",
+      "kind": "command",
+      "description": "Run quick Reddit-only research flow.",
+      "bodyFile": "commands/quick.md"
+    },
+    {
+      "id": "deep-research",
+      "kind": "command",
+      "description": "Run deep research flow and route to best template.",
+      "bodyFile": "commands/deep-research.md"
+    },
+    {
+      "id": "rank",
+      "kind": "command",
+      "description": "Generate ranking report from current raw data.",
+      "bodyFile": "commands/rank.md"
+    },
+    {
+      "id": "sentiment",
+      "kind": "command",
+      "description": "Generate sentiment report from current raw data.",
+      "bodyFile": "commands/sentiment.md"
+    },
+    {
+      "id": "trend",
+      "kind": "command",
+      "description": "Generate trend timeline report from current raw data.",
+      "bodyFile": "commands/trend.md"
+    },
+    {
+      "id": "controversy",
+      "kind": "command",
+      "description": "Generate controversy map from current raw data.",
+      "bodyFile": "commands/controversy.md"
+    },
+    {
+      "id": "discovery",
+      "kind": "command",
+      "description": "Generate discovery clusters from current raw data.",
+      "bodyFile": "commands/discovery.md"
+    },
+    {
+      "id": "visualize",
+      "kind": "command",
+      "description": "Launch dashboard for available classified data files.",
+      "bodyFile": "commands/visualize.md"
+    },
+    {
+      "id": "test-research",
+      "kind": "command",
+      "description": "Run fixed-link test research pipeline.",
+      "bodyFile": "commands/test-research.md"
+        }
+    ]
+}

package/templates/base/skills/communities_controversy.md

@@ -0,0 +1,65 @@
+---
+name: communities_controversy
+description: Worker skill that analyzes raw social media data to identify polarizing topics and produce a controversy map with strict JSON output.
+---
+
+# Communities Controversy Skill
+
+This is a **Worker Skill** that identifies the most **divisive and argumentative** topics in community discussions. It finds where opinions clash and presents opposing viewpoints side-by-side.
+
+## Input Data
+You will act on existing JSON files in the workspace (fetched by `communities_fetch`):
+- `reddit_data.json`
+- `x_data.json`
+
+## Workflow
+
+### 1. Read All Discussion Content
+Read the full text of every item in both data files. Look for patterns of **disagreement**:
+- Contradictory opinions about the same product/topic
+- "But..." / "However..." / "I disagree" / "overrated" / "overhyped" language
+- Posts where the author explicitly compares and picks sides
+- Topics where Reddit and X communities have opposing views
+
+### 2. Identify Controversies
+Find 3-5 clear controversies. Common patterns to look for:
+- **Quality vs Price debates** — Is the expensive option worth it?
+- **Technology debates** — e.g., planar vs dynamic, wired vs wireless
+- **Platform divides** — Reddit enthusiasts vs X mainstream opinion
+- **Subjective preferences** — EQ vs stock tuning, comfort vs sound quality
+- **Brand loyalty conflicts** — Sennheiser vs Hifiman, etc.
+
+### 3. Score Each Controversy
+For each identified controversy:
+- **heat_score** (1-100): Based on engagement on the divisive posts. Higher engagement on opposing posts = higher heat.
+- **divisiveness**: "High" (near 50/50 split with strong opinions), "Medium" (clear lean but vocal minority), "Low" (mostly agreed but some dissent)
+
+### 4. Extract Opposing Quotes (3 Per Side)
+For each controversy, find **THREE real quotes for each side**:
+- **Side A**: The position + 3 real quotes with author and link
+- **Side B**: The opposing position + 3 real quotes with author and link
+- Count how many commenters support each side (`supporter_count`)
+- The 3 quotes should show different perspectives/arguments within the same side (not just repeating the same point).
+
+### 5. Generate Output (Strict JSON)
+You **MUST** save the result to `classified_controversy.json`.
+
+The output **MUST** strictly follow the `ControversyData` interface defined in `web/src/types.ts`. Read that file first to understand the exact schema.
+
+**Schema source of truth (important):**
+- Do not rely on schema examples in this skill file.
+- Always read `web/src/types.ts` and follow `ControversyData` exactly.
+- If this skill text and `types.ts` ever conflict, `types.ts` wins.
+
+## Critical Rules
+1. **No External Research**: Do not fetch new data. Use only the provided JSON files.
+2. **Strict Schema**: The visualization tool will crash if the schema doesn't match `ControversyData` from `types.ts`.
+3. **Real Quotes Only**: Every entry in `sample_quotes` must be a real excerpt from the data with a real link.
+4. **3 Quotes Per Side**: Always provide 3 quotes per side to show breadth of the argument.
+5. **Genuine Controversies**: Don't manufacture disagreement. Only report controversies that actually exist in the data.
+6. **Output file**: Must be saved as `classified_controversy.json` in the project root.
+7. **Data Resilience**:
+   - If `heat_score` cannot be calculated, set it to `0`.
+   - If `supporter_count` cannot be estimated, set it to `0`.
+   - If no quotes are found, set `sample_quotes` to `[]`.
+   - Ensure all `Array` fields are at least empty arrays `[]` if no data exists, never `null` or `undefined`.

package/templates/base/skills/communities_discovery.md

@@ -0,0 +1,55 @@
+---
+name: communities_discovery
+description: Worker skill that analyzes raw social media data to identify viral topics and generate a discovery report with strict JSON output.
+---
+
+# Communities Discovery Skill
+
+This is a **Worker Skill** that identifies **viral topics and emerging themes** from community discussions. It clusters posts by topic and surfaces the most engaging content.
+
+## Input Data
+You will act on existing JSON files in the workspace (fetched by `communities_fetch`):
+- `reddit_data.json`
+- `x_data.json`
+
+## Workflow
+
+### 1. Read All Posts
+Read every item in both data files. Look for recurring themes, viral posts, and emerging conversations.
+
+### 2. Analyze & Cluster
+- Identify 3-5 distinct viral topics/themes from the combined data.
+- Group relevant posts under each topic.
+- Ignore spam or irrelevant noise.
+
+### 3. Calculate Metrics
+- **Engagement Score**: Sum of (score + comments) for Reddit, (likes + reposts) for X.
+- **Sentiment**: Determine the overall sentiment (`positive`, `negative`, `neutral`, `mixed`) for the topic.
+
+### 4. Extract Highlight Comments
+For each trending topic, extract **3 real highlight comments** from the data:
+- Each comment must be a real excerpt from an actual post or comment in the raw data.
+- Include `author`, `link`, and `platform` ("reddit" or "x") for each.
+- Choose comments that best represent the community's reaction to the topic — insightful takes, strong opinions, or popular observations.
+
+### 5. Generate Output (Strict JSON)
+You **MUST** save the result to `classified_discovery.json`.
+
+The output **MUST** strictly follow the `DiscoveryData` interface defined in `web/src/types.ts`. Read that file first to understand the exact schema.
+
+**Schema source of truth (important):**
+- Do not rely on schema examples in this skill file.
+- Always read `web/src/types.ts` and follow `DiscoveryData` exactly.
+- If this skill text and `types.ts` ever conflict, `types.ts` wins.
+
+## Critical Rules
+1. **No External Research**: Do not fetch new data. Use only the provided JSON files.
+2. **Strict Schema**: The visualization tool will crash if the schema doesn't match `DiscoveryData` from `types.ts`.
+3. **Real Content**: Base topic clustering on actual post content — don't guess.
+4. **3 Comments Per Topic**: Always provide 3 highlight comments per trending topic with real text and source links.
+5. **Output file**: Must be saved as `classified_discovery.json` in the project root.
+6. **Data Resilience**:
+   - If `engagement_score` cannot be calculated, set it to `0`.
+   - If no comments are found, set `highlight_comments` to `[]`.
+   - Ensure all `Array` fields are at least empty arrays `[]` if no data exists, never `null` or `undefined`.
+   - Ensure `period` is always a string (e.g. "Last 7 Days"), never null.

package/templates/base/skills/communities_fetch.md

@@ -0,0 +1,56 @@
+# Communities Fetch Skill
+
+This is a **Worker Skill** responsible for the "Eyes and Ears" of the research. It goes out to Reddit (and X if configured) to find real user discussions.
+
+## Capabilities
+
+- **Sources**: Reddit (via OpenAI URL discovery) + X (via XAI API)
+- **Output**: Raw JSON files (`reddit_data.json`, `x_data.json`)
+- **No Analysis**: This skill DOES NOT analyze or rank data. It only fetches it.
+
+## Usage
+
+### 1. Standard Research (Quick)
+Scans ~5 threads per source. Good for quick answers.
+
+```bash
+sc-research research "YOUR TOPIC HERE"
+```
+
+### 2. Deep Research
+Scans ~10+ threads. Good for comprehensive market analysis.
+
+```bash
+sc-research research:deep "YOUR TOPIC HERE"
+```
+
+### 3. Discovery Mode
+Fetches top/trending posts for topic clustering instead of targeted search.
+
+```bash
+sc-research research "YOUR TOPIC HERE" --mode=discovery
+```
+
+### Optional Flags
+- `--from=YYYY-MM-DD --to=YYYY-MM-DD` — Focus on a specific date range
+- `--depth=deep` — Same as using `research:deep`
+- `--mode=discovery` — Switch to discovery mode for topic clustering
+- `--source=reddit|x|both` — Limit to a specific source (default: both available)
+
+## Output Format
+
+The skill saves files to the project root:
+- `reddit_data.json`
+- `x_data.json`
+
+**Next Step**: After fetching, use an analysis skill (`communities_rank`, `communities_sentiment`, `communities_trend`, `communities_controversy`, or `communities_discovery`) to classify the data.
+
+## Error Handling
+
+| Scenario | Symptom | Action |
+|---|---|---|
+| Missing `OPENAI_API_KEY` | Process exits with auth error | Ensure `.env` has a valid `OPENAI_API_KEY` |
+| Missing `XAI_API_KEY` | X data is empty, Reddit still works | Set `XAI_API_KEY` in `.env` or accept Reddit-only results |
+| No results for topic | Output JSON has 0 items | Try broader search terms or check spelling |
+| Rate limited | API error or timeout | Wait a few minutes and retry |
+| Empty/malformed JSON output | File exists but `items` array is empty | Check topic relevance; try a more popular search term |

package/templates/base/skills/communities_rank.md

@@ -0,0 +1,57 @@
+---
+name: communities_rank
+description: Analyze raw social media data (Reddit/X) to produce a ranked, classified report with strict JSON output.
+---
+
+# Communities Ranking Skill
+
+This skill acts as a **Ranking Engine** and **Data Analyst**. It takes raw, unstructured user discussions from `communities_fetch` and converts them into a structured, quantitative report.
+
+## Input Data
+You will act on existing JSON files in the workspace:
+- `reddit_data.json`
+- `x_data.json`
+
+## Workflow
+
+### 1. Read Raw Data
+Read the input files to understand the raw community sentiment. Look for:
+- **Consensus**: What is the most agreed-upon "best" product?
+- **Debate**: What are the alternatives?
+- **Engagement**: Which posts/comments have high upvotes/likes?
+
+### 2. Analyze & Rank
+You must analyze the data to create a ranking. Use the following criteria:
+- **Rank 1**: The clear community winner (highest sentiment + engagement).
+- **Rank 2-5**: Strong contenders or "best value" alternatives.
+- **Sentiment**: Label as "Positive", "Negative", "Mixed", or "Very Positive".
+- **Engagement Score**: A derived score based on upvotes + comments + mentions.
+
+### 3. Extract Highlight Quotes
+For each ranked product, extract **3 real highlight quotes** from the data:
+- Each quote must be a real excerpt from the raw data with a real author and link.
+- Tag each quote with a `context` field:
+  - `"pro"` — The quote highlights a strength or positive experience.
+  - `"con"` — The quote highlights a weakness or negative experience.
+  - `"general"` — The quote is a general opinion or comparison.
+- Aim for a mix of pro/con/general across the 3 quotes to show balanced community opinion.
+
+### 4. Generate Output (Strict JSON)
+You **MUST** save the result to `classified_rank.json`. 
+
+To determine the output schema:
+1. **Read the file** `web/src/types.ts`.
+2. **Strictly follow** the `ClassifiedData` interface defined in that file as your output schema.
+3. Ensure all fields in `ClassifiedData` (and its dependent types like `Product`) are populated.
+
+## Example Command
+To trigger this skill, the user might ask:
+- "Rank the IEMs found in the reddit data"
+- "Create a classification report for the research"
+- "Update the visualization data"
+
+## Critical Rules
+1. **No External Research**: Do not fetch new data. Use only the provided JSON files.
+2. **Strict Schema**: The visualization tool will crash if `key_insights` or `estimated_engagement_score` are missing.
+3. **Real Quotes**: Every `highlight_quotes` entry must be a real excerpt from the data with a real link.
+4. **3 Quotes Per Product**: Always provide exactly 3 highlight quotes per product with appropriate context tags.

package/templates/base/skills/communities_research_test.md

@@ -0,0 +1,64 @@
+---
+name: communities_research_test
+description: "⚙️ DEBUG/LEGACY — Test the communities research skill with fixed Reddit links (no API key needed). Fetches data and returns JSON for AI classification."
+---
+
+# Communities Research Test Skill
+
+> **⚙️ Legacy/Debug Tool** — This skill predates the current `classified_*.json` pipeline. It fetches data from fixed URLs and asks for a markdown table classification. Use it for quick pipeline sanity checks, but prefer the standard `communities_fetch` → `communities_rank` flow for real analysis.
+
+Use this skill to test the research pipeline with fixed Reddit URLs. No API key required.
+
+## Usage
+
+```bash
+sc-research test:fixed [URL1] [URL2] ...
+```
+
+Default URLs (if none provided):
+- https://www.reddit.com/r/iems/comments/1olzu0g/the_best_iem_builds_at_each_price_2025_ultimate/
+- https://www.reddit.com/r/headphones/comments/1lbcngj/new_iem_tierlist_2025/
+- https://www.reddit.com/r/iems/comments/1c7imln/iem_tier_list/
+
+## Output
+
+The script outputs a **JSON object** with the following structure:
+
+```json
+{
+  "query": "Manual Test: ...",
+  "dateRange": { "from": "YYYY-MM-DD", "to": "YYYY-MM-DD" },
+  "items": [
+    {
+      "id": "...",
+      "title": "Thread Title",
+      "content": "Full text content...",
+      "author": "username",
+      "platform": "reddit",
+      "engagement": {
+        "score": 100,
+        "upvotes": 100,
+        "comments": 50
+      },
+      "url": "https://...",
+      "createdAt": "ISO8601 Date"
+    }
+  ],
+  "sources": { "redditThreads": 3, "xPosts": 0 }
+}
+```
+
+## AI Instructions
+
+After running, classify items by:
+1. **Product** mentioned
+2. **Sentiment** (Positive/Mixed/Negative)
+3. **Engagement** (upvotes)
+
+Present as a Markdown table:
+
+| Rank | Product | Sentiment | Mentions | Avg. Upvotes |
+|------|---------|-----------|----------|--------------|
+| 1    | ...     | 👍        | ...      | ...          |
+
+Include top quotes with attribution.