sc-research 1.0.1

package/CLAUDE.md

@@ -0,0 +1,67 @@
+# Communities Research Skill
+
+> **"The Skill provides the catch; the Agent cooks the meal."**
+
+This project is a headless social media research tool designed for **Claude Code first**. It fetches raw discussion data from Reddit and X (Twitter), classifies it into multiple analysis templates, and visualizes results in a local dashboard.
+
+## Canonical Source
+
+- **Main source of truth:** `templates/base/` (skills + commands body templates)
+- **Platform rules source:** `templates/platforms/*.json` (paths/format behavior)
+- `.claude/`, `.cursor/`, `.agent/`, and other platform folders are rendered outputs from `sc-research init`.
+
+## ⚡️ Quick Start
+
+This project uses `bun`.
+
+### Environment Variables
+Required in `.env`:
+- `OPENAI_API_KEY`: For Reddit URL discovery and general LLM ops
+- `XAI_API_KEY`: (Optional) For X/Twitter data
+
+### Available Commands
+- `/research <topic>` - Research + quick answer flow
+- `/quick <topic>` - Fast Reddit-only quick answer
+- `/deep-research <topic>` - Deep research + route to best template
+- `/rank` - Generate ranking report (`classified_rank.json`)
+- `/sentiment` - Generate sentiment report (`classified_sentiment.json`)
+- `/trend` - Generate timeline report (`classified_trend.json`)
+- `/controversy` - Generate controversy map (`classified_controversy.json`)
+- `/discovery` - Generate discovery clusters (`classified_discovery.json`)
+- `/visualize` - Launch dashboard (auto-detects available `classified_*.json`)
+- `/test-research` - Run fixed-link pipeline test
+
+### CLI Init Targets
+- `sc-research init --ai claude` - Install Claude templates
+- `sc-research init --ai claude,cursor` - Install multiple targets in one run
+- `sc-research init --ai all` - Install all supported targets (`claude`, `cursor`, `windsurf`, `antigravity`)
+
+## 🏗️ Architecture
+
+- **Orchestrator**: `using_communities_research` (The routing brain)
+- **Workers**: 
+  - `communities_fetch` (Data provider)
+  - `communities_rank` (Ranking analysis)
+  - `communities_sentiment` (Sentiment analysis)
+  - `communities_trend` (Timeline analysis)
+  - `communities_controversy` (Debate analysis)
+  - `communities_discovery` (Viral topic clustering)
+  - `communities_visualize` (Dashboard launcher)
+  - `communities_research_test` (Legacy/fixed-link test helper)
+
+## 🧪 Testing Rules
+
+> **IMPORTANT**: Automated tests MUST NOT invoke paid AI APIs.
+> Use `bun run test:fixed` for manual verification or the `/test-research` command.
+
+## 🔒 Project Rules
+
+- Always use `bun` for runtime and scripts.
+- Do not run paid AI API calls in automated tests.
+
+## 📂 Project Structure
+
+- `src/`: Core TypeScript logic
+- `.claude/skills/`: AI Skill definitions
+- `.claude/commands/`: User slash commands
+- `web/`: React/Vite visualization app

package/README.md

@@ -0,0 +1,111 @@
+# Social Media Research Skill
+
+> **"The Skill provides the catch; the Agent cooks the meal."**
+
+A **Headless Data Provider** for AI Agents. It researches topics across **Reddit** and **X (Twitter)**, returning raw, normalized, high-engagement discussion data for your Agent to analyze.
+
+Now includes a **CLI installer** so you can drop the full research workflow into a Claude Code project with a single command.
+
+## Features
+
+- **Dynamic Source Detection**: Automatically switches between Reddit and X based on available API keys (`OPENAI_API_KEY`, `XAI_API_KEY`).
+- **Unified Data Model**: Normalizes data from different platforms into a single `ResearchItem` schema.
+- **AI-Native Output**: optimized for LLM consumption (JSON).
+- **Engagement-Based Sorting**: Prioritizes content with high community interaction.
+- **Multi-Platform Bootstrap**: Install AI assistant templates into any repo via CLI (`claude`, `cursor`, `windsurf`, `antigravity`).
+
+## Installation (NPM + CLI)
+
+```bash
+npm install -g sc-research
+```
+
+Then, in any project you want to bootstrap:
+
+```bash
+cd /path/to/your/project
+
+# Preview what init would do
+sc-research init --ai claude,cursor --dry-run
+
+# Apply one platform
+sc-research init --ai claude
+
+# Apply multiple platforms in one run
+sc-research init --ai claude,cursor
+
+# Apply all supported platforms
+sc-research init --ai all
+```
+
+This now does **both**:
+- Installs SC-Research templates for selected platform(s)
+- Reads/updates your project `package.json` scripts so commands work immediately
+
+Template architecture:
+- `templates/base/` is the canonical source for command/skill content
+- `templates/platforms/*.json` defines per-platform output rules used during `init`
+
+## Usage with Claude Code
+
+1. **Run init once per project**
+
+   ```bash
+   sc-research init --ai claude
+   ```
+
+   This will add/update these scripts in your project `package.json`:
+   - `research`: `sc-research research`
+   - `research:deep`: `sc-research research --depth=deep`
+   - `visualize`: `sc-research visualize`
+   - `test:fixed`: `sc-research test:fixed`
+
+2. **Open the project in Claude Code**
+
+3. **Use the commands:**
+
+   - `/research <topic>` – Quick research + answer
+   - `/deep-research <topic>` – Deep fetch + best template routing
+   - `/rank` – Rank existing data into `classified_rank.json`
+   - `/sentiment` – Build sentiment report
+   - `/trend` – Build timeline report
+   - `/controversy` – Build controversy map
+   - `/discovery` – Discover viral topics
+   - `/visualize` – Launch dashboard
+   - `/test-research` – Run fixed-link debug test
+
+## Direct Bun CLI (Optional, existing behavior)
+
+### CLI
+
+```bash
+# Research a topic
+bun run research "Best budget IEM 2024"
+
+# Specify output file
+bun run research "Best budget IEM 2024" --out=./my_results.json
+```
+
+### Programmatic
+
+```typescript
+import { SocialMediaResearch } from 'social-media-research-skill';
+
+const researcher = new SocialMediaResearch();
+const results = await researcher.search("Best budget IEM 2024");
+
+console.log(results);
+```
+
+## Configuration
+
+Set the following environment variables in your `.env` file:
+
+```env
+OPENAI_API_KEY=sk-... # Required for Reddit (URL Discovery)
+XAI_API_KEY=...       # Required for X (Twitter)
+```
+
+## License
+
+MIT