@mkterswingman/5mghost-twinkler 0.1.1 → 0.1.4

package/README.md

@@ -4,10 +4,15 @@ Lightweight AI runtime for the hosted Twinkler API.
 
 ```bash
 npm install -g @mkterswingman/5mghost-twinkler
-twinkler setup
+twinkler ensure --auto-update --json
 twinkler call GET /api/v1/channel/ibai/summary --query days=30
 ```
 
+`npm install -g` installs bundled AI skills automatically for detected AI
+clients. `twinkler setup` remains an advanced repair command when a skill target
+was unavailable during install; normal AI workflows should start with
+`twinkler ensure --auto-update --json`.
+
 Auth uses the shared mkterswingman PAT. Do not commit `.env`, `auth.json`,
 PATs, bearer tokens, or any generated secret file to a remote repository. Enter
-PATs through `twinkler auth login --pat-stdin`; do not paste PATs into AI chat.
+PATs through `twinkler login`; do not paste PATs into AI chat.

package/dist/cli.d.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { spawnSync } from "node:child_process";
 export interface CliContext {
     argv?: string[];
     env?: NodeJS.ProcessEnv;
@@ -7,5 +8,6 @@ export interface CliContext {
     stderr?: (message: string) => void;
     stdin?: AsyncIterable<Buffer | string>;
     fetchImpl?: typeof fetch;
+    spawnSyncImpl?: typeof spawnSync;
 }
 export declare function runCli(context?: CliContext): Promise<number>;

package/dist/cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { readFileSync, realpathSync } from "node:fs";
+import { spawnSync } from "node:child_process";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { getAuthStatus, logout, PAT_LOGIN_URL, savePat } from "./auth.js";
@@ -10,18 +11,25 @@ const HELP = [
     "twinkler",
     "",
     "Usage:",
-    "  twinkler setup",
-    "  twinkler install-skills",
     "  twinkler doctor",
+    "  twinkler login",
+    "  twinkler ensure [--auto-update] [--json]",
     "  twinkler auth status",
-    "  twinkler auth login --pat <TOKEN>",
     "  twinkler auth login --pat-stdin",
     "  twinkler call <GET|POST|DELETE> /api/v1/... [--query k=v] [--json '{...}']",
+    "  twinkler jobs active|recent|show <job_id>",
+    "  twinkler update",
     "  twinkler version",
     "",
+    "Repair / advanced:",
+    "  twinkler setup",
+    "  twinkler install-skills",
+    "  twinkler auth login --pat <TOKEN>",
+    "",
     "mkterswingman PAT:",
     `  ${PAT_LOGIN_URL}`
 ].join("\n");
+const PACKAGE_NAME = "@mkterswingman/5mghost-twinkler";
 export async function runCli(context = {}) {
     const argv = context.argv ?? process.argv.slice(2);
     const env = context.env ?? process.env;
@@ -44,6 +52,21 @@ export async function runCli(context = {}) {
                 return 0;
             case "auth":
                 return await runAuthCommand(args, { paths, env, out, stdin: context.stdin ?? process.stdin });
+            case "login":
+                return await runAuthCommand(["login", "--pat-stdin", ...args.filter((arg) => arg !== "--pat-stdin")], {
+                    paths,
+                    env,
+                    out,
+                    stdin: context.stdin ?? process.stdin
+                });
+            case "ensure":
+                return runEnsureCommand(args, {
+                    paths,
+                    env,
+                    out,
+                    err,
+                    spawnSyncImpl: context.spawnSyncImpl ?? spawnSync
+                });
             case "call": {
                 const parsed = parseCallArgs(args);
                 const result = await callTwinkler({
@@ -55,6 +78,13 @@ export async function runCli(context = {}) {
                 out(JSON.stringify(result, null, 2));
                 return 0;
             }
+            case "jobs":
+                return await runJobsCommand(args, {
+                    paths,
+                    env,
+                    out,
+                    fetchImpl: context.fetchImpl
+                });
             case "install-skills": {
                 const results = installBundledSkills({ homeDir: paths.homeDir });
                 out(renderSkillInstallResults(results));
@@ -72,6 +102,9 @@ export async function runCli(context = {}) {
                 ].join("\n"));
                 return results.some((result) => result.status === "error") ? 1 : 0;
             }
+            case "update":
+            case "upgrade":
+                return runUpdateCommand(args, { env, out, err, spawnSyncImpl: context.spawnSyncImpl ?? spawnSync });
             case "doctor": {
                 const auth = getAuthStatus({ authJsonPath: paths.authJsonPath, env });
                 out([
@@ -101,10 +134,12 @@ async function runAuthCommand(args, context) {
         context.out([
             "Usage:",
             "  twinkler auth status",
-            "  twinkler auth login --pat <TOKEN>",
             "  twinkler auth login --pat-stdin",
             "  twinkler auth logout",
             "",
+            "Advanced compatibility:",
+            "  twinkler auth login --pat <TOKEN>",
+            "",
             `PAT page: ${PAT_LOGIN_URL}`
         ].join("\n"));
         return 0;
@@ -149,6 +184,141 @@ async function runAuthCommand(args, context) {
     context.out(`Unknown auth subcommand: ${subcommand}`);
     return 1;
 }
+function runEnsureCommand(args, context) {
+    const json = args.includes("--json");
+    const autoUpdate = args.includes("--auto-update");
+    const localVersion = readPackageVersion();
+    const latest = readNpmLatestVersion(context.spawnSyncImpl, context.env);
+    const auth = getAuthStatus({ authJsonPath: context.paths.authJsonPath, env: context.env });
+    const updateNeeded = latest.version !== null && compareSemver(latest.version, localVersion) > 0;
+    let update = {
+        needed: updateNeeded,
+        attempted: false,
+        status: updateNeeded ? "skipped" : "not_needed"
+    };
+    let exitCode = 0;
+    if (updateNeeded && autoUpdate) {
+        const result = runGlobalNpmInstall({ env: context.env, spawnSyncImpl: context.spawnSyncImpl });
+        update = {
+            needed: true,
+            attempted: true,
+            status: result.ok ? "updated" : "failed",
+            command: result.command,
+            exit_code: result.exitCode,
+            error: result.error
+        };
+        exitCode = result.ok ? 0 : 1;
+    }
+    else if (latest.error) {
+        update = {
+            needed: false,
+            attempted: false,
+            status: "unknown",
+            error: latest.error
+        };
+    }
+    const result = {
+        status: exitCode === 0 ? "ok" : "error",
+        package: PACKAGE_NAME,
+        local_version: localVersion,
+        latest_version: latest.version,
+        latest_check: latest.error ? { ok: false, error: latest.error } : { ok: true },
+        update,
+        auth: {
+            authenticated: auth.authenticated,
+            type: auth.type,
+            source: auth.source,
+            auth_file: auth.authJsonPath
+        },
+        ai_session_restart_required: update.status === "updated"
+    };
+    if (json) {
+        context.out(JSON.stringify(result, null, 2));
+    }
+    else {
+        context.out(renderEnsureResult(result));
+    }
+    if (update.status === "failed" && update.error)
+        context.err(update.error);
+    return exitCode;
+}
+function renderEnsureResult(result) {
+    const latest = result.latest_version ?? `unknown (${result.latest_check.ok ? "not checked" : result.latest_check.error})`;
+    const lines = [
+        "Twinkler ensure",
+        `Package: ${result.package}`,
+        `Local version: ${result.local_version}`,
+        `Latest version: ${latest}`,
+        `Update: ${result.update.status}`,
+        `Auth: ${result.auth.authenticated ? `ready (${result.auth.type} via ${result.auth.source})` : "missing"}`
+    ];
+    if (result.ai_session_restart_required) {
+        lines.push("AI session: restart recommended so updated skill text is loaded.");
+    }
+    return lines.join("\n");
+}
+function readNpmLatestVersion(spawnSyncImpl, env) {
+    const npmCommand = process.platform === "win32" ? "npm.cmd" : "npm";
+    const result = spawnSyncImpl(npmCommand, ["view", `${PACKAGE_NAME}@latest`, "version", "--silent"], {
+        encoding: "utf8",
+        env
+    });
+    if (result.error)
+        return { version: null, error: result.error.message };
+    if (result.status !== 0) {
+        return { version: null, error: (result.stderr || `npm exited with ${result.status ?? "unknown status"}`).trim() };
+    }
+    const version = result.stdout.trim();
+    return version ? { version } : { version: null, error: "npm returned an empty latest version" };
+}
+function compareSemver(a, b) {
+    const left = parseSemver(a);
+    const right = parseSemver(b);
+    for (let index = 0; index < 3; index += 1) {
+        if (left[index] !== right[index])
+            return left[index] > right[index] ? 1 : -1;
+    }
+    return 0;
+}
+function parseSemver(version) {
+    const match = /^(\d+)\.(\d+)\.(\d+)/.exec(version.trim());
+    if (!match)
+        return [0, 0, 0];
+    return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+async function runJobsCommand(args, context) {
+    const [subcommand, value] = args.filter((arg) => arg !== "--json");
+    let path;
+    if (subcommand === "active") {
+        path = "/api/v1/twitch/watch";
+    }
+    else if (subcommand === "recent") {
+        path = "/api/v1/twitch/watch";
+    }
+    else if (subcommand === "show" && value) {
+        path = `/api/v1/twitch/watch/${encodeURIComponent(value)}`;
+    }
+    else {
+        context.out([
+            "Usage:",
+            "  twinkler jobs active",
+            "  twinkler jobs recent",
+            "  twinkler jobs show <job_id>"
+        ].join("\n"));
+        return 1;
+    }
+    const query = subcommand === "active" ? { status: ["active"] } : subcommand === "recent" ? { status: ["recent"] } : {};
+    const result = await callTwinkler({
+        method: "GET",
+        path,
+        query,
+        authJsonPath: context.paths.authJsonPath,
+        env: context.env,
+        fetchImpl: context.fetchImpl
+    });
+    context.out(JSON.stringify(result, null, 2));
+    return 0;
+}
 function parseCallArgs(args) {
     const [method, path, ...rest] = args;
     if (!method || !path) {
@@ -188,6 +358,46 @@ function renderSkillInstallResults(results) {
         })
     ].join("\n");
 }
+function runUpdateCommand(args, context) {
+    const dryRun = args.includes("--dry-run") || context.env.TWINKLER_UPDATE_DRY_RUN === "1";
+    const npmCommand = process.platform === "win32" ? "npm.cmd" : "npm";
+    const installArgs = ["install", "-g", `${PACKAGE_NAME}@latest`];
+    if (dryRun) {
+        context.out(`Update command: ${npmCommand} ${installArgs.join(" ")}`);
+        return 0;
+    }
+    context.out("Updating Twinkler helper...");
+    const result = runGlobalNpmInstall({ env: context.env, spawnSyncImpl: context.spawnSyncImpl, inheritStdio: true });
+    if (!result.ok) {
+        context.err(result.error ?? `Update failed: npm exited with ${result.exitCode ?? "unknown status"}`);
+        return result.exitCode ?? 1;
+    }
+    context.out("Twinkler updated. Restart your AI session so newly installed skill text is loaded.");
+    return 0;
+}
+function runGlobalNpmInstall(options) {
+    const npmCommand = process.platform === "win32" ? "npm.cmd" : "npm";
+    const installArgs = ["install", "-g", `${PACKAGE_NAME}@latest`];
+    const result = options.spawnSyncImpl(npmCommand, installArgs, {
+        stdio: options.inheritStdio ? "inherit" : "pipe",
+        encoding: options.inheritStdio ? undefined : "utf8",
+        env: options.env
+    });
+    const command = `${npmCommand} ${installArgs.join(" ")}`;
+    if (result.error) {
+        return { ok: false, command, exitCode: null, error: `Update failed: ${result.error.message}` };
+    }
+    if (result.status !== 0) {
+        const stderr = typeof result.stderr === "string" ? result.stderr.trim() : "";
+        return {
+            ok: false,
+            command,
+            exitCode: result.status,
+            error: stderr || `Update failed: npm exited with ${result.status ?? "unknown status"}`
+        };
+    }
+    return { ok: true, command, exitCode: 0 };
+}
 async function readAllStdin(stdin) {
     const chunks = [];
     for await (const chunk of stdin) {

package/dist/skillInstall.d.ts

@@ -1,5 +1,7 @@
 export interface InstallSkillsOptions {
-    homeDir: string;
+    homeDir?: string;
+    detectedAgents?: string[];
+    repairTargets?: boolean;
 }
 export interface SkillInstallResult {
     agent: string;
@@ -7,5 +9,6 @@ export interface SkillInstallResult {
     status: "installed" | "skipped" | "error";
     targetDir: string;
     reason?: string;
+    contentHash?: string;
 }
-export declare function installBundledSkills(options: InstallSkillsOptions): SkillInstallResult[];
+export declare function installBundledSkills(options?: InstallSkillsOptions): SkillInstallResult[];

package/dist/skillInstall.js

@@ -1,58 +1,86 @@
-import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { basename, dirname, join } from "node:path";
+import { applyAgentOverrides, getTargetDir, installSkills, listDetectedAgents, loadBuiltInRegistry, RECEIPT_FILENAME } from "@mkterswingman/5mghost-agent-skills";
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
 import { resolveBundledAssetPath } from "./paths.js";
-const TARGETS = [
-    { agent: "codex", skillsDir: ".codex/skills" },
-    { agent: "agents", skillsDir: ".agents/skills" }
+const AGENT_OVERRIDES = {
+    agents: {
+        label: "Agents legacy skills",
+        detect: { kind: "path", path: "~/.agents" },
+        skillsDir: "~/.agents/skills",
+        installMethod: "copy"
+    }
+};
+const TWINKLER_SKILLS = [
+    "setup-5mghost-twinkler",
+    "use-5mghost-twinkler",
+    "update-5mghost-twinkler"
 ];
-export function installBundledSkills(options) {
+const LEGACY_RECEIPT_FILENAME = ".install-receipt.json";
+export function installBundledSkills(options = {}) {
     const manifestPath = resolveBundledAssetPath("skills.manifest.json");
-    const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
-    const packageRoot = dirname(manifestPath);
-    const results = [];
-    for (const skill of manifest.skills) {
-        const sourceDir = join(packageRoot, skill.source);
-        for (const target of TARGETS) {
-            const rootDir = join(options.homeDir, target.skillsDir);
-            const targetDir = join(rootDir, skill.name);
+    const detectedAgents = options.detectedAgents ??
+        listDetectedAgents({
+            homeDir: options.homeDir,
+            agentOverrides: AGENT_OVERRIDES
+        });
+    const setupTargets = options.repairTargets === false
+        ? detectedAgents
+        : Array.from(new Set([...detectedAgents, "codex", "agents"]));
+    removeLegacyOwnedTargets(options.homeDir, setupTargets);
+    return normalizeSummary(installSkills({
+        manifestPath,
+        homeDir: options.homeDir,
+        agentOverrides: AGENT_OVERRIDES,
+        detectedAgents: setupTargets
+    }));
+}
+function removeLegacyOwnedTargets(homeDir, agentNames) {
+    const registry = applyAgentOverrides(loadBuiltInRegistry(), AGENT_OVERRIDES);
+    for (const agentName of agentNames) {
+        const agent = registry.agents[agentName];
+        if (!agent)
+            continue;
+        for (const skillName of TWINKLER_SKILLS) {
+            const targetDir = getTargetDir(homeDir, agent.skillsDir, skillName);
+            const receiptPath = findReceiptPath(targetDir);
+            if (!existsSync(receiptPath))
+                continue;
+            let receipt;
             try {
-                if (!existsSync(sourceDir)) {
-                    results.push({
-                        agent: target.agent,
-                        skill: skill.name,
-                        status: "error",
-                        targetDir,
-                        reason: `missing bundled skill source ${sourceDir}`
-                    });
-                    continue;
-                }
-                mkdirSync(rootDir, { recursive: true });
-                rmSync(targetDir, { recursive: true, force: true });
-                cpSync(sourceDir, targetDir, { recursive: true });
-                writeFileSync(join(targetDir, ".install-receipt.json"), JSON.stringify({
-                    product: manifest.product,
-                    skill: skill.name,
-                    agent: target.agent,
-                    source: basename(sourceDir),
-                    installed_at: new Date().toISOString()
-                }, null, 2));
-                results.push({
-                    agent: target.agent,
-                    skill: skill.name,
-                    status: "installed",
-                    targetDir
-                });
+                receipt = JSON.parse(readFileSync(receiptPath, "utf8"));
             }
-            catch (error) {
-                results.push({
-                    agent: target.agent,
-                    skill: skill.name,
-                    status: "error",
-                    targetDir,
-                    reason: error instanceof Error ? error.message : String(error)
-                });
+            catch {
+                continue;
+            }
+            if (receipt.installedBy === undefined &&
+                receipt.product === "5mghost-twinkler" &&
+                receipt.skill === skillName &&
+                receipt.agent === agentName) {
+                rmSync(targetDir, { recursive: true, force: true });
             }
         }
     }
-    return results;
+}
+function findReceiptPath(targetDir) {
+    const current = join(targetDir, RECEIPT_FILENAME);
+    if (existsSync(current))
+        return current;
+    return join(targetDir, LEGACY_RECEIPT_FILENAME);
+}
+function normalizeSummary(summary) {
+    return summary.results.map((result) => {
+        const status = result.status === "installed" || result.status === "updated"
+            ? "installed"
+            : result.status === "error"
+                ? "error"
+                : "skipped";
+        return {
+            agent: result.agent,
+            skill: result.skill,
+            status,
+            targetDir: result.targetDir,
+            reason: result.reason,
+            contentHash: result.contentHash
+        };
+    });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mkterswingman/5mghost-twinkler",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "description": "Lightweight AI helper for the 5mghost Twinkler API",
   "type": "module",
   "engines": {
@@ -9,6 +9,11 @@
   "publishConfig": {
     "access": "public"
   },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/5mghost/mcp_projects.git",
+    "directory": "5mghost-twinkler/client"
+  },
   "bin": {
     "twinkler": "dist/cli.js"
   },
@@ -23,13 +28,15 @@
     "skills",
     "skills.manifest.json",
     "install",
+    "scripts",
     "README.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "test": "npm run build && node --test tests/*.test.mjs",
     "prepack": "npm run build",
-    "pack:dry": "npm pack --dry-run"
+    "pack:dry": "npm pack --dry-run",
+    "postinstall": "node scripts/postinstall.mjs"
   },
   "keywords": [
     "twinkler",
@@ -37,6 +44,9 @@
     "ai",
     "mkterswingman"
   ],
+  "dependencies": {
+    "@mkterswingman/5mghost-agent-skills": "^0.0.1"
+  },
   "devDependencies": {
     "@types/node": "^25.3.2",
     "typescript": "^5.9.3"

package/scripts/postinstall.mjs

@@ -0,0 +1,51 @@
+// Runs after `npm install -g` to install Twinkler skills into detected AI clients.
+// This script is intentionally non-fatal: npm install must still succeed when
+// an AI client is not installed or a skill target is locked down.
+
+const agentOverrides = {
+  agents: {
+    label: "Agents legacy skills",
+    detect: { kind: "path", path: "~/.agents" },
+    skillsDir: "~/.agents/skills",
+    installMethod: "copy"
+  }
+};
+
+let listDetectedAgents;
+let installBundledSkills;
+
+try {
+  ({ listDetectedAgents } = await import("@mkterswingman/5mghost-agent-skills"));
+  ({ installBundledSkills } = await import("../dist/skillInstall.js"));
+} catch (error) {
+  console.log("[twinkler] agent-skills not available; skipping skill install.");
+  process.exit(0);
+}
+
+let agents;
+try {
+  agents = listDetectedAgents({ agentOverrides });
+} catch (error) {
+  console.log("[twinkler] Could not detect AI clients; skipping skill install.");
+  process.exit(0);
+}
+
+if (!agents || agents.length === 0) {
+  console.log("[twinkler] No AI clients detected; skipping skill install.");
+  process.exit(0);
+}
+
+try {
+  const results = installBundledSkills({ detectedAgents: agents, repairTargets: false });
+  const installed = results
+    .filter((entry) => entry.status === "installed")
+    .map((entry) => `${entry.agent}:${entry.skill}`);
+  if (installed.length > 0) {
+    console.log(`[twinkler] Installed skills: ${installed.join(", ")}`);
+    console.log("[twinkler] Restart your AI session before invoking the new skill text.");
+  } else {
+    console.log("[twinkler] No skill targets updated.");
+  }
+} catch (error) {
+  console.log(`[twinkler] Skill install failed (non-fatal): ${String(error)}`);
+}

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

@@ -0,0 +1,71 @@
+---
+name: setup-5mghost-twinkler
+preamble-tier: 3
+version: 0.2.0
+description: |
+  Set up or repair the local Twinkler helper, bundled skills, and mkterswingman
+  auth for AI-driven Twitch data workflows.
+---
+
+# Setup 5mghost Twinkler
+
+Use when Twinkler is missing, auth is missing or expired, skills may be stale,
+or the user asks to prepare Twinkler for an AI workflow.
+
+## Default Path
+
+1. Check the helper:
+
+```bash
+twinkler doctor
+```
+
+2. If the helper is missing, install it:
+
+```bash
+npm install -g @mkterswingman/5mghost-twinkler
+```
+
+The npm install runs the bundled skill installer automatically. Use `twinkler
+setup` only as a repair command when postinstall could not update the local AI
+skill directories.
+
+3. Repair skills when needed:
+
+```bash
+twinkler setup
+```
+
+4. If auth is missing, send the user to:
+
+```text
+https://mkterswingman.com/pat/login
+```
+
+Ask the user to copy the mkterswingman PAT, then start:
+
+```bash
+twinkler auth login --pat-stdin
+```
+
+Have the user paste the PAT into that local input. Do not ask them to paste the
+PAT into chat, screenshots, docs, shell history, or source files.
+
+## Success
+
+`twinkler doctor` should report auth ready. Then the AI can use the
+`use-5mghost-twinkler` skill and `twinkler call`.
+
+## Recovery
+
+- Missing command: run `npm install -g @mkterswingman/5mghost-twinkler`.
+- Missing skills after install: run `twinkler setup`, then restart the AI session.
+- Missing auth: use the PAT page and `twinkler auth login --pat-stdin`.
+- HTTP 401/403 from API calls: run `twinkler auth status`; if stale, log in again.
+- Permission or npm global install failure: use the same package manager and
+  Node installation method that originally installed global npm packages.
+
+## Secret Policy
+
+Never print, echo, log, commit, or store PATs in project files. The only normal
+local storage is `~/.mkterswingman/auth.json`, written by the helper.

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

@@ -0,0 +1,40 @@
+---
+name: update-5mghost-twinkler
+preamble-tier: 3
+version: 0.2.0
+description: |
+  Update the Twinkler helper package and refresh bundled AI skills.
+---
+
+# Update 5mghost Twinkler
+
+Use when the user asks to update, upgrade, repair stale skills, or pick up a new
+Twinkler helper release.
+
+## Default Path
+
+Run:
+
+```bash
+twinkler update
+```
+
+This runs the npm global update for `@mkterswingman/5mghost-twinkler@latest`.
+The package postinstall refreshes bundled skills automatically.
+
+If `twinkler update` is unavailable because the installed version is old, run:
+
+```bash
+npm install -g @mkterswingman/5mghost-twinkler@latest
+```
+
+Then ask the user to restart the AI session so updated skill text is loaded.
+
+## Verify
+
+```bash
+twinkler version
+twinkler ensure --json
+```
+
+Do not ask the user to edit skill directories or hidden config files manually.

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

@@ -1,134 +1,159 @@
 ---
 name: use-5mghost-twinkler
 preamble-tier: 3
-version: 0.1.0
+version: 0.3.0
 description: |
   Use when the user wants Twitch streamer, game, ranking, stream-session, CCV,
-  or chat-watch data from the mkterswingman Twinkler API.
-  Keywords: Twinkler, Twitch, streamer, CCV, chat, watch job, SullyGnome, Arc Raiders.
+  chat, live-watch, or SullyGnome data through the mkterswingman Twinkler API.
+  Also use for vague requests such as "查这个主播", "盯这个直播", "拉 Twitch 数据",
+  "看看 CCV/chat", or "找符合条件的主播".
 ---
 
 # Use 5mghost Twinkler
 
-Use the local `twinkler` helper. It adds auth, refreshes short-lived
-mkterswingman access tokens when available, and calls the hosted Twinkler REST
-API. Prefer the helper over hand-written `curl`.
+Operate Twinkler for the user. Do not ask non-technical users to run CLI
+commands, remember job IDs, choose API routes, or design pagination strategy.
+Use the local `twinkler` helper instead of hand-written `curl`; it handles
+mkterswingman auth and only allows hosted Twinkler `/api/v1/*` paths.
 
-## First Check
+## Required Preflight
 
-Run:
+Before any data work, run:
 
 ```bash
-twinkler doctor
+twinkler ensure --auto-update --json
 ```
 
-If the helper is missing, ask the user to install it:
+Read the JSON.
+
+- If `update.status` is `updated`, continue the current task. Tell the user only
+  that the helper is updated and a new AI session is needed to load changed skill
+  text.
+- If auth is missing or expired, run `twinkler login`, give the user
+  <https://mkterswingman.com/pat/login>, and have them paste the PAT into local
+  stdin. Never ask for the PAT in chat.
+- If update failed but the current helper can still complete the task, continue
+  and mention the update failure briefly. Stop only when the helper is too old
+  for the requested command.
+
+Do not use time-based latest-version caches. The preflight checks npm latest on
+every invocation.
+
+## Data Request Layer
+
+Use `twinkler call` for one-off hosted API requests:
 
 ```bash
-npm install -g @mkterswingman/5mghost-twinkler
-twinkler setup
+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/rankings/channels --query sort_by=mostfollowers --query days=30 --query page=1 --query page_size=25
 ```
 
-## Auth
+Pick the smallest API that answers the question:
 
-Twinkler uses the shared mkterswingman PAT. Do not call it a Twinkler PAT.
+- Channel profile/current history: `/channel/{name}/summary`.
+- A channel's recent broadcasts: `/channel/{name}/streams`.
+- A channel's games: `/channel/{name}/games`.
+- Stream-session chart or game splits: `/channel/{name}/stream/{stream_id}/chart`
+  and `/games`.
+- Game creator discovery: `/game/{game_identifier}/channels`.
+- Broad Twitch leaderboards: `/rankings/channels`, `/rankings/games`,
+  `/rankings/teams`.
+- Live CCV/chat sampling: create a watch job instead of polling summary pages.
 
-If auth is missing:
+## Watch Job Layer
 
-1. Give the user this URL: <https://mkterswingman.com/pat/login>
-2. Ask the user to copy the mkterswingman PAT.
-3. Start the helper login command and have the user paste the PAT into the
-   helper input, not into the AI chat.
+Use watch jobs when the user asks to monitor a live channel, collect CCV points,
+collect chat messages, or stop when the stream ends or changes game.
 
-Preferred save path when stdin is available:
+Before creating a new watch job in a new session, recover existing work:
 
 ```bash
-twinkler auth login --pat-stdin
+twinkler jobs active
+twinkler jobs recent
 ```
 
-Then pass the PAT through stdin. Do not put the PAT in command-line arguments
-unless no stdin-capable tool is available.
-
-Fallback:
+Create a job:
 
 ```bash
-twinkler auth login --pat <TOKEN>
+twinkler call POST /api/v1/twitch/watch --json '{"logins":["theburntpeanut"],"collect":["ccv","chat"],"start":{"type":"time","at":"now"},"stop":{"type":"game","game_name":"ARC Raiders"}}'
 ```
 
-Never echo the PAT back to the user. Never put the PAT in source files, docs,
-logs, URLs, screenshots, PR text, or committed `.env` files. Do not commit
-`~/.mkterswingman/auth.json` or any generated secret/config file to a remote
-repository. Do not ask non-technical users to paste PATs into chat; use the
-helper's stdin path or a secure secret-entry UI.
-
-For AI-managed cloud/server environments, store the PAT as a secret named
-`MKTERSWINGMAN_PAT`. Do not explain environment variables to non-technical
-users unless they ask; configure the target environment yourself when you have
-tool access.
+Then inspect it with:
 
-## Preferred Calls
+```bash
+twinkler jobs show <job_id>
+twinkler call GET /api/v1/twitch/watch/<job_id>/ccv
+twinkler call GET /api/v1/twitch/watch/<job_id>/chat
+```
 
-Use:
+For long-running jobs, create a monitor in the AI environment. Generate the
+portable monitor payload with the bundled script in this skill directory:
 
 ```bash
-twinkler call GET /api/v1/channel/ibai/summary --query days=30
-twinkler call GET /api/v1/rankings/channels --query sort_by=mostfollowers --query days=30 --query page_size=5
-twinkler call POST /api/v1/twitch/watch --json '{"logins":["theburntpeanut"],"collect":["ccv","chat"],"start":{"type":"time","at":"now"},"stop":{"type":"game","game_name":"ARC Raiders"}}'
+node scripts/create-watch-monitor.mjs --job-id <job_id> --cadence-min 10 --stop "stream ended or no longer matches requested game"
 ```
 
-`twinkler call` only allows Twinkler `/api/v1/*` paths. It returns JSON on
-stdout.
+If the current runtime has an automation, heartbeat, reminder, or monitor tool,
+submit the generated prompt there. If not, state that proactive notification is
+not available in this environment, but the job can be recovered later with
+`twinkler jobs active` and `twinkler jobs recent`.
 
-## Calling The Helper From Scripts
+Do not make the user remember or run the recovery commands. Use them yourself in
+new sessions.
 
-When writing a local automation script for a non-technical user, prefer calling
-the helper instead of re-implementing auth:
+## Data Processing Layer
 
-```js
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
+Short responses can be parsed directly from JSON. For multi-page or
+more-than-100-row tasks, write raw rows before analysis:
 
-const execFileAsync = promisify(execFile);
+- Prefer JSONL for append-only pulls and quick inspection.
+- Prefer SQLite when sampling over time, joining channel/game rows, deduping,
+  or applying repeated filters.
+- Keep raw records plus derived columns such as `avg_viewers`, `stream_hours`,
+  `watch_hours`, `language`, `game_name`, and source route.
+- Preserve timestamps and route/query parameters so metric definitions remain
+  auditable.
 
-const { stdout } = await execFileAsync("twinkler", [
-  "call",
-  "GET",
-  "/api/v1/channel/ibai/summary",
-  "--query",
-  "days=30",
-]);
+For "take a point every 1 minute" live tasks, prefer a hosted watch job. If a
+local ad hoc sampler is unavoidable, store one raw row per poll in JSONL/SQLite;
+do not rely on chat context as the data store.
 
-const payload = JSON.parse(stdout);
-console.log(payload);
-```
+## Analysis Layer
 
-Do not pass PATs as script arguments. Let `twinkler auth login --pat-stdin`
-store the mkterswingman PAT once, then scripts can call `twinkler call`.
+Plan the upstream sort order before paginating. For compound filters, sort by a
+proxy that satisfies multiple constraints.
 
-## Direct REST Fallback
+Example: "近 3 年播过 Delta Force、CCV/avg viewers > 1000、stream hours > 30、英语区主播".
 
-Use direct REST only when the helper cannot be installed or the runtime is
-non-Node, such as a Python-only cloud job. Direct REST still requires auth.
+Use game channels or relevant rankings sorted by watch hours/watched first, not
+stream hours. Watch hours approximates viewers times duration, so high rows are
+more likely to satisfy both viewer and duration thresholds. Sorting by stream
+hours alone pushes many low-viewer marathon channels ahead and wastes pages.
 
-Python example:
+Stop conditions:
 
-```python
-import os
-import requests
+- Compute the minimum possible watched threshold when definitions are aligned:
+  `min_watch_hours = min_avg_viewers * min_stream_hours`.
+- Once sorted watched/watch-hours values fall materially below that threshold
+  and several pages have produced no qualifying candidates, stop or ask before
+  continuing.
+- If the API's metric names or time windows are ambiguous, say which field is
+  being used and verify with a small sample before scaling.
 
-token = os.environ["MKTERSWINGMAN_PAT"]
+## Error And Recovery States
 
-response = requests.get(
-    "https://mkterswingman.com/5mghost/twinkler/api/v1/channel/ibai/summary",
-    params={"days": "30"},
-    headers={"Authorization": f"Bearer {token}"},
-    timeout=30,
-)
-response.raise_for_status()
-print(response.json())
-```
+- Missing helper: install `@mkterswingman/5mghost-twinkler` globally with npm,
+  then rerun preflight.
+- Auth missing/expired: run `twinkler login`.
+- Update needed: preflight auto-updates; continue after it succeeds.
+- Watch disabled: explain that the hosted watch worker is disabled right now.
+- Upstream blocked/rate limited: report retry timing and do not loop blindly.
+- Empty result: distinguish real empty from wrong ID, wrong sort, wrong locale,
+  or unsupported time window.
+
+## Secret Policy
 
-If `MKTERSWINGMAN_PAT` is missing in a non-helper environment, send the user to
-<https://mkterswingman.com/pat/login>, then store the PAT in the target
-runtime's secret store yourself when tool access provides a safe secret-entry
-mechanism. Do not ask the user to paste the PAT into chat.
+Never print, echo, log, commit, screenshot, or store PATs in project files. The
+normal local storage is `~/.mkterswingman/auth.json`, written by the helper.

package/skills/use-5mghost-twinkler/scripts/create-watch-monitor.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+
+const args = parseArgs(process.argv.slice(2));
+if (!args.jobId) {
+  console.error("Usage: create-watch-monitor.mjs --job-id <job_id> [--cadence-min 10] [--stop text] [--fields ccv_points,chat_messages,latest_ccv]");
+  process.exit(1);
+}
+
+const cadenceMin = Number.parseInt(args.cadenceMin ?? "10", 10);
+if (!Number.isFinite(cadenceMin) || cadenceMin < 1) {
+  console.error("--cadence-min must be a positive integer");
+  process.exit(1);
+}
+
+const fields = (args.fields ?? "ccv_points,chat_messages,latest_ccv")
+  .split(",")
+  .map((field) => field.trim())
+  .filter(Boolean);
+const stop = args.stop ?? "the watch job completes, expires, is cancelled, the stream ends, or the requested game no longer matches";
+const jobId = args.jobId;
+
+const prompt = [
+  `Check the production 5mghost-twinkler watch job ${jobId}.`,
+  "Do not print secrets.",
+  "Run `twinkler ensure --auto-update --json` first; if auth is missing, ask the user to complete `twinkler login`.",
+  `Fetch \`twinkler jobs show ${jobId}\` and report status plus ${fields.join(", ")}.`,
+  "If the job is active, include latest online/game/title/viewer count when available.",
+  `Stop monitoring when ${stop}.`,
+  "If the job has completed, tell the user clearly that the monitor can be disabled."
+].join(" ");
+
+const payload = {
+  kind: "twinkler_watch_monitor",
+  job_id: jobId,
+  cadence_minutes: cadenceMin,
+  stop_condition: stop,
+  fields,
+  prompt
+};
+
+console.log(JSON.stringify(payload, null, 2));
+
+function parseArgs(argv) {
+  const parsed = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--job-id") parsed.jobId = argv[++index];
+    else if (arg === "--cadence-min") parsed.cadenceMin = argv[++index];
+    else if (arg === "--stop") parsed.stop = argv[++index];
+    else if (arg === "--fields") parsed.fields = argv[++index];
+    else {
+      console.error(`Unknown option: ${arg}`);
+      process.exit(1);
+    }
+  }
+  return parsed;
+}

package/skills.manifest.json

@@ -1,10 +1,38 @@
 {
+  "schemaVersion": 1,
   "product": "5mghost-twinkler",
   "skills": [
     {
       "name": "use-5mghost-twinkler",
-      "source": "skills/use-5mghost-twinkler",
-      "description": "Use the Twinkler helper to call the mkterswingman Twinkler API from AI workflows."
+      "source": { "type": "local", "path": "./skills/use-5mghost-twinkler" },
+      "targets": [
+        "claude",
+        "claude-internal",
+        "codex",
+        "codex-internal",
+        "gemini",
+        "gemini-internal",
+        "openclaw",
+        "workbuddy",
+        "codebuddy",
+        "agents"
+      ]
+    },
+    {
+      "name": "update-5mghost-twinkler",
+      "source": { "type": "local", "path": "./skills/update-5mghost-twinkler" },
+      "targets": [
+        "claude",
+        "claude-internal",
+        "codex",
+        "codex-internal",
+        "gemini",
+        "gemini-internal",
+        "openclaw",
+        "workbuddy",
+        "codebuddy",
+        "agents"
+      ]
     }
   ]
 }