@mkterswingman/5mghost-twinkler 0.1.6 → 0.1.11

package/README.md

@@ -17,6 +17,10 @@ was unavailable during install; normal AI workflows should start with
 Auth defaults to browser OAuth via `twinkler login`. PAT login is an advanced
 fallback with `twinkler login --pat-stdin`.
 
+`GET /api/v1/search/advanced` intentionally returns 501 and is not part of the
+public-ready supported surface. Use `/api/v1/search`, rankings, channel, or game
+routes instead.
+
 Watch jobs are remembered locally in `~/.mkterswingman/twinkler/jobs.json` so AI
 sessions can recover active and recent jobs without making users remember job
 IDs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mkterswingman/5mghost-twinkler",
-  "version": "0.1.6",
+  "version": "0.1.11",
   "description": "Lightweight AI helper for the 5mghost Twinkler API",
   "type": "module",
   "engines": {
@@ -11,7 +11,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/5mghost/mcp_projects.git",
+    "url": "https://github.com/mkterswingman/mcp_projects.git",
     "directory": "5mghost-twinkler/client"
   },
   "bin": {

package/skills/use-5mghost-twinkler/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: use-5mghost-twinkler
 preamble-tier: 3
-version: 0.3.0
+version: 0.4.0
 description: |
   Use when the user wants Twitch streamer, game, ranking, stream-session, CCV,
   chat, live-watch, or SullyGnome data through the mkterswingman Twinkler API.
@@ -39,6 +39,58 @@ Read the JSON.
 Do not use time-based latest-version caches. The preflight checks npm latest on
 every invocation.
 
+## Ambiguity Gate
+
+Before choosing an endpoint, decide whether the user's wording identifies all
+result-shaping inputs. Do not guess when a different interpretation would change
+the answer.
+
+Ask a short clarification before calling heavy endpoints when any of these are
+missing and not inferable from context:
+
+- Target type: channel, game, broad ranking, team/community, stream session, or
+  live watch job.
+- Metric: average CCV / average viewers, peak viewers, watched hours, stream
+  hours, followers, growth, chat, live CCV, or per-session game splits.
+- Time window: `7/14/30/90/180/365` days or a named month/year.
+- Filters: language, mature content, minimum CCV, minimum stream time, region or
+  game/category constraints.
+- Ordering: `watched`, `avgviewers`, `peakviewers`, `streamtime`,
+  `mostfollowers`, `followergrowth`, or "latest streams".
+
+Use these defaults only for low-risk exploratory asks, and say them briefly in
+the answer: `days=30`, `language=any`, `mature=include`, `page_size=25`.
+Do not default the sort order when the user's wording says only "data",
+"ranking", "creator list", or "主播数据"; ask whether they want watched hours,
+average viewers/CCV, peak viewers, stream time, or followers.
+
+Lightweight probes are allowed before asking:
+
+- Run `/api/v1/search?q=<term>` when a name could be a game or channel, or when
+  a game title may have multiple SullyGnome IDs.
+- Run `/api/v1/meta/languages`, `/api/v1/meta/days-ranges`, or
+  `/api/v1/meta/sort-options` when you need exact accepted enum values.
+- If `/search` returns multiple plausible candidates, show the candidate names,
+  numeric ids, and `siteurl` values; ask the user to pick one. Do not silently
+  choose the first row.
+
+Examples:
+
+- User: "帮我找找 Delta Force 的主播数据"
+  - First run search for `Delta Force`.
+  - If multiple games match, show candidates and ask which game.
+  - Also ask the missing result shape: time window, language, and sort metric
+    (watched hours vs avg CCV vs peak viewers vs stream time).
+- User: "查 ibai 30 天 avg ccv"
+  - This is specific enough: call `/channel/ibai/summary?days=30` and report the
+    summary-card Average viewers.
+- User: "找英语区近 30 天播过 Tarkov、平均 CCV 1000+ 的主播"
+  - Search/resolve the game, use `/game/{id}/channels`, start with
+    `sort_by=watched`, then filter rows locally by language and avg viewers.
+
+When asking, keep it to at most three user-facing questions in one message. For
+example: "你要哪个 Delta Force 版本？时间窗用 30 天还是 365 天？排序看观看时长还是平均 CCV？"
+
 ## Data Request Layer
 
 Use `twinkler call` for one-off hosted API requests:
@@ -46,10 +98,16 @@ Use `twinkler call` for one-off hosted API requests:
 ```bash
 twinkler call GET /api/v1/channel/ibai/summary --query days=30
 twinkler call GET /api/v1/channel/ibai/streams --query days=30 --query sort_by=avgviewers --query page=1 --query page_size=25
-twinkler call GET /api/v1/game/Delta%20Force/channels --query days=365 --query sort_by=watched --query page=1 --query page_size=50
+twinkler call GET /api/v1/search --query 'q=Delta Force'
+twinkler call GET /api/v1/game/<selected_sullygnome_game_id>/channels --query days=365 --query sort_by=watched --query page=1 --query page_size=50
 twinkler call GET /api/v1/rankings/channels --query sort_by=mostfollowers --query days=30 --query page=1 --query page_size=25
 ```
 
+Use the numeric `value` from the chosen `/search` game candidate as
+`<selected_sullygnome_game_id>`. Do not use Twitch Helix game ids or URL-encoded
+game names in `/game/{game_identifier}` once search has shown multiple
+candidates.
+
 Pick the smallest API that answers the question:
 
 - Channel profile/current history: `/channel/{name}/summary`.
@@ -61,6 +119,8 @@ Pick the smallest API that answers the question:
 - Broad Twitch leaderboards: `/rankings/channels`, `/rankings/games`,
   `/rankings/teams`.
 - Live CCV/chat sampling: create a watch job instead of polling summary pages.
+- Do not use `/search/advanced`; it intentionally returns 501 and is not part
+  of the public-ready supported surface.
 
 ## Watch Job Layer