sc-research 1.0.12 → 1.0.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/package.json +1 -1
  2. package/templates/base/commands/discovery.md +14 -10
  3. package/templates/base/skills/social_media_discovery.md +22 -1
  4. package/templates/base/skills/social_media_fetch.md +2 -0
  5. package/templates/base/skills/social_media_visualize.md +8 -8
  6. package/templates/base/skills/using_social_media_research.md +9 -7
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "sc-research",
3
- "version": "1.0.12",
3
+ "version": "1.0.13",
4
4
  "description": "Headless Social Media Research Data Provider for AI Agents",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
package/templates/base/commands/discovery.md CHANGED
@@ -4,24 +4,28 @@ description: Discover viral topics and emerging themes from existing research da
4
4
 
5
5
  1. Check for data existence
6
6
 
7
- > Ensure `reddit_data.json` or `x_data.json` exists in the current directory.
7
+ > Ensure `reddit_data.json` or `x_data.json` exists in the current directory.
8
8
 
9
9
  2. Check freshness for the current request
10
10
 
11
- > 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`.
11
+ > Confirm raw data matches the requested topic and date window (if provided). If it does not match, re-fetch with **deep research discovery mode**:
12
+ >
13
+ > - Broad weekly feed: `sc-research research:deep "DISCOVERY_WEEKLY" --mode=discovery`
14
+ > - Topic-focused: `sc-research research:deep "TOPIC" --mode=discovery`
15
+ > - Optional filters: add `--source=reddit|x|both --from=YYYY-MM-DD --to=YYYY-MM-DD`
12
16
 
13
17
  3. Run the discovery skill
14
18
 
15
- > Use the `social_media_discovery` skill to cluster posts by topic and generate `classified_discovery.json`.
19
+ > Use the `social_media_discovery` skill to cluster posts by topic and generate `classified_discovery.json`.
16
20
 
17
21
  4. Validate output schema
18
22
 
19
- > Ensure `classified_discovery.json` includes:
20
- >
21
- > - `period`
22
- > - `total_posts_analyzed`
23
- > - `trending_topics` array
24
- > - per topic: `id`, `topic_name`, `description`, `category`, `engagement_score`, `sentiment`, `key_posts`
23
+ > Ensure `classified_discovery.json` includes:
24
+ >
25
+ > - `period`
26
+ > - `total_posts_analyzed`
27
+ > - `trending_topics` array
28
+ > - per topic: `id`, `topic_name`, `description`, `category`, `engagement_score`, `sentiment`, `key_posts`
25
29
 
26
30
  5. Display the results
27
- > Read `classified_discovery.json` and display the discovered topics with their engagement scores, sentiment, and top posts.
31
+ > Read `classified_discovery.json` and display the discovered topics with their engagement scores, sentiment, and top posts.
package/templates/base/skills/social_media_discovery.md CHANGED
@@ -22,7 +22,8 @@ Use this sequence when running discovery end-to-end:
22
22
 
23
23
  1. Fetch or refresh discovery raw data (outside this worker):
24
24
 
25
- - `sc-research research:deep "TOPIC" --mode=discovery`
25
+ - Broad weekly discovery feed: `sc-research research:deep "DISCOVERY_WEEKLY" --mode=discovery`
26
+ - Topic-focused discovery: `sc-research research:deep "TOPIC" --mode=discovery`
26
27
  - Optional filters: `--source=reddit|x|both --from=YYYY-MM-DD --to=YYYY-MM-DD`
27
28
 
28
29
  2. Run this `social_media_discovery` worker to analyze existing raw files and produce `classified_discovery.json`.
@@ -32,6 +33,26 @@ Use this sequence when running discovery end-to-end:
32
33
 
33
34
  If raw files are missing, stale, or mismatched for the requested topic/date range, instruct the caller to run step 1 first.
34
35
 
36
+ ## Discovery Fetch Behavior (Code-Aligned)
37
+
38
+ When `--mode=discovery` is used, runtime behavior differs by topic:
39
+
40
+ 1. If topic is exactly `DISCOVERY_WEEKLY` and Reddit is enabled:
41
+
42
+ - Fetches Reddit trending posts from `r/popular/top` with `t=week` and limit `25`.
43
+
44
+ 2. For other topics in discovery mode and Reddit enabled:
45
+
46
+ - Maps topic to candidate subreddits first.
47
+ - Per subreddit, uses either top posts (`week`, limit `5`) or subreddit search (`week`, limit `5`) based on topic/subreddit match.
48
+ - If mapping returns no subreddits, falls back to legacy Reddit keyword-thread flow.
49
+
50
+ 3. X source behavior:
51
+
52
+ - X fetch still runs through normal X search flow (`maxItems` based on depth), even in discovery mode.
53
+
54
+ This skill consumes the resulting `reddit_data.json` / `x_data.json`; it does not perform fetching itself.
55
+
35
56
  ## Step 1: Preflight Validation
36
57
 
37
58
  1. Parse each available source file.
package/templates/base/skills/social_media_fetch.md CHANGED
@@ -43,6 +43,8 @@ Use flags only when requested:
43
43
  - `--from=YYYY-MM-DD --to=YYYY-MM-DD`
44
44
  - `--mode=discovery`
45
45
 
46
+ When `--source` is omitted, runtime attempts all enabled sources (based on available API keys). A source without its required key is skipped.
47
+
46
48
  Examples:
47
49
 
48
50
  ```bash
package/templates/base/skills/social_media_visualize.md CHANGED
@@ -11,13 +11,13 @@ This worker launches the local web UI and renders the current classification out
11
11
 
12
12
  Before launch:
13
13
 
14
- 1. At least one of these files exists and is parseable:
14
+ 1. Prefer having at least one of these files available:
15
15
  - `classified_rank.json`
16
16
  - `classified_sentiment.json`
17
17
  - `classified_trend.json`
18
18
  - `classified_controversy.json`
19
19
  - `classified_discovery.json`
20
- 2. If none exist, report that analysis must run first.
20
+ 2. If none exist, runtime still launches the dashboard in empty mode; inform the user to run analysis skills to populate tabs.
21
21
 
22
22
  ## Command Execution Flow
23
23
 
@@ -61,13 +61,13 @@ Return:
61
61
  ## Critical Rules
62
62
 
63
63
  1. **Visualization only**: this skill does not fetch or classify data.
64
- 2. **No silent fallback confusion**: if no valid classified files exist, clearly report failure.
64
+ 2. **No silent fallback confusion**: if no valid classified files exist, clearly explain that dashboard is running in empty mode.
65
65
  3. **Use actual runtime URL**: if default port is taken, report the new port.
66
66
 
67
67
  ## Troubleshooting
68
68
 
69
- | Issue | Symptom | Action |
70
- | ------------------- | -------------------------------------- | --------------------------------------------------------------------- |
71
- | No classified files | command exits early or empty dashboard | run a worker skill first (rank/sentiment/trend/controversy/discovery) |
72
- | Port already in use | server starts on another port | report actual URL shown by runtime |
73
- | Malformed JSON file | tab fails to render or command errors | regenerate that specific `classified_*.json` file |
69
+ | Issue | Symptom | Action |
70
+ | ------------------- | ------------------------------------- | --------------------------------------------------------------------- |
71
+ | No classified files | empty dashboard (server still starts) | run a worker skill first (rank/sentiment/trend/controversy/discovery) |
72
+ | Port already in use | server starts on another port | report actual URL shown by runtime |
73
+ | Malformed JSON file | tab fails to render or command errors | regenerate that specific `classified_*.json` file |
package/templates/base/skills/using_social_media_research.md CHANGED
@@ -36,7 +36,8 @@ After route selection, execute commands as follows:
36
36
  - `sc-research research:deep "TOPIC" [--source=...] [--from=YYYY-MM-DD --to=YYYY-MM-DD]`
37
37
  - then run the selected worker skill to produce the matching `classified_*.json`.
38
38
  - Discovery route:
39
- - `sc-research research:deep "TOPIC" --mode=discovery [--source=...] [--from=... --to=...]`
39
+ - Broad weekly feed: `sc-research research:deep "DISCOVERY_WEEKLY" --mode=discovery [--source=...] [--from=... --to=...]`
40
+ - Topic-focused: `sc-research research:deep "TOPIC" --mode=discovery [--source=...] [--from=... --to=...]`
40
41
  - then run `social_media_discovery`.
41
42
  - Quick answer route:
42
43
  - `sc-research research "TOPIC" --source=reddit [--from=... --to=...]`
@@ -80,18 +81,19 @@ Apply rules top-to-bottom:
80
81
 
81
82
  ### Source Detection
82
83
 
83
- | User wording | Source flag |
84
- | ------------------------------------- | --------------------------------- |
85
- | "on Reddit", "subreddit", "Redditors" | `--source=reddit` |
86
- | "on X", "on Twitter", "tweets" | `--source=x` |
87
- | no explicit source | no source flag (default behavior) |
84
+ | User wording | Source flag |
85
+ | ------------------------------------- | ----------------------------------------------------------------------------- |
86
+ | "on Reddit", "subreddit", "Redditors" | `--source=reddit` |
87
+ | "on X", "on Twitter", "tweets" | `--source=x` |
88
+ | no explicit source | no source flag (runtime uses all enabled sources based on available API keys) |
88
89
 
89
90
  ### Fetch Strategy
90
91
 
91
92
  - **Worker routes (rank/sentiment/trend/controversy):**
92
93
  - `sc-research research:deep "TOPIC" [--source=...] [--from=YYYY-MM-DD --to=YYYY-MM-DD]`
93
94
  - **Discovery route:**
94
- - `sc-research research:deep "TOPIC" --mode=discovery [--source=...] [--from=... --to=...]`
95
+ - Broad weekly feed: `sc-research research:deep "DISCOVERY_WEEKLY" --mode=discovery [--source=...] [--from=... --to=...]`
96
+ - Topic-focused: `sc-research research:deep "TOPIC" --mode=discovery [--source=...] [--from=... --to=...]`
95
97
  - **Quick answer route:**
96
98
  - `sc-research research "TOPIC" --source=reddit [--from=... --to=...]`
97
99