@mkterswingman/5mghost-twinkler 0.1.3 → 0.1.5

package/README.md

@@ -4,13 +4,15 @@ Lightweight AI runtime for the hosted Twinkler API.
 
 ```bash
 npm install -g @mkterswingman/5mghost-twinkler
+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 idempotent repair command when a skill
-target was unavailable during install.
+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/auth.d.ts

@@ -21,6 +21,8 @@ export interface TokenProviderOptions {
     env?: NodeJS.ProcessEnv;
     fetchImpl?: typeof fetch;
     authUrl?: string;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
 }
 export declare function getAuthStatus(options: TokenProviderOptions): AuthStatus;
 export declare function getValidToken(options: TokenProviderOptions): Promise<string | null>;

package/dist/auth.js

@@ -1,9 +1,12 @@
-import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 export const MKTERSWINGMAN_PAT_ENV = "MKTERSWINGMAN_PAT";
 export const PAT_LOGIN_URL = "https://mkterswingman.com/pat/login";
 const DEFAULT_AUTH_URL = "https://mkterswingman.com";
 const REFRESH_SKEW_MS = 60_000;
+const REFRESH_LOCK_STALE_MS = 30_000;
+const REFRESH_LOCK_TIMEOUT_MS = 90_000;
+const REFRESH_LOCK_POLL_MS = 50;
 export function getAuthStatus(options) {
     if (options.env?.[MKTERSWINGMAN_PAT_ENV]) {
         return {
@@ -54,26 +57,35 @@ export async function getValidToken(options) {
         return null;
     if (auth.type === "pat")
         return auth.pat || null;
-    if (auth.access_token && auth.expires_at && Date.now() + REFRESH_SKEW_MS < auth.expires_at) {
+    if (hasUsableAccessToken(auth, options.now)) {
         return auth.access_token;
     }
-    if (!auth.refresh_token)
-        return null;
-    const refreshed = await refreshJwt(auth.refresh_token, {
-        clientId: auth.client_id,
-        authUrl: options.authUrl,
-        fetchImpl: options.fetchImpl
-    });
-    if (!refreshed)
-        return null;
-    writeSharedAuth(options.authJsonPath, {
-        type: "jwt",
-        access_token: refreshed.access_token,
-        refresh_token: refreshed.refresh_token,
-        expires_at: Date.now() + refreshed.expires_in * 1000,
-        client_id: auth.client_id
+    return withRefreshLock(options, async () => {
+        const latest = readSharedAuth(options.authJsonPath);
+        if (!latest)
+            return null;
+        if (latest.type === "pat")
+            return latest.pat || null;
+        if (hasUsableAccessToken(latest, options.now))
+            return latest.access_token;
+        if (!latest.refresh_token)
+            return null;
+        const refreshed = await refreshJwt(latest.refresh_token, {
+            clientId: latest.client_id,
+            authUrl: options.authUrl,
+            fetchImpl: options.fetchImpl
+        });
+        if (!refreshed)
+            return null;
+        writeSharedAuth(options.authJsonPath, {
+            type: "jwt",
+            access_token: refreshed.access_token,
+            refresh_token: refreshed.refresh_token,
+            expires_at: (options.now ?? Date.now)() + refreshed.expires_in * 1000,
+            client_id: latest.client_id
+        });
+        return refreshed.access_token;
     });
-    return refreshed.access_token;
 }
 export function savePat(authJsonPath, pat) {
     const normalized = pat.trim();
@@ -112,6 +124,95 @@ export function writeSharedAuth(authJsonPath, data) {
         // Windows may ignore POSIX modes.
     }
 }
+function hasUsableAccessToken(auth, now) {
+    return Boolean(auth.access_token &&
+        auth.expires_at &&
+        (now ?? Date.now)() + REFRESH_SKEW_MS < auth.expires_at);
+}
+async function withRefreshLock(options, fn) {
+    const lockPath = `${options.authJsonPath}.refresh.lock`;
+    const now = options.now ?? Date.now;
+    const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const deadline = now() + REFRESH_LOCK_TIMEOUT_MS;
+    mkdirSync(dirname(options.authJsonPath), { recursive: true });
+    while (true) {
+        try {
+            mkdirSync(lockPath, { mode: 0o700 });
+            try {
+                writeLockOwner(lockPath, now());
+            }
+            catch (error) {
+                rmSync(lockPath, { recursive: true, force: true });
+                throw error;
+            }
+            try {
+                return await fn();
+            }
+            finally {
+                rmSync(lockPath, { recursive: true, force: true });
+            }
+        }
+        catch (error) {
+            if (!isAlreadyExistsError(error))
+                throw error;
+            if (canRecoverRefreshLock(lockPath, now())) {
+                rmSync(lockPath, { recursive: true, force: true });
+                continue;
+            }
+            if (now() >= deadline) {
+                throw new Error("Timed out waiting for mkterswingman auth refresh lock");
+            }
+            await sleep(REFRESH_LOCK_POLL_MS);
+        }
+    }
+}
+function isAlreadyExistsError(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "EEXIST");
+}
+function writeLockOwner(lockPath, createdAtMs) {
+    writeFileSync(`${lockPath}/owner.json`, JSON.stringify({ pid: process.pid, created_at: createdAtMs }), { encoding: "utf8", mode: 0o600 });
+}
+function canRecoverRefreshLock(lockPath, nowMs) {
+    const owner = readRefreshLockOwner(lockPath);
+    if (owner) {
+        return nowMs - owner.created_at > REFRESH_LOCK_STALE_MS && !isProcessAlive(owner.pid);
+    }
+    try {
+        return nowMs - statSync(lockPath).mtimeMs > REFRESH_LOCK_STALE_MS;
+    }
+    catch {
+        return false;
+    }
+}
+function readRefreshLockOwner(lockPath) {
+    try {
+        const owner = JSON.parse(readFileSync(`${lockPath}/owner.json`, "utf8"));
+        if (typeof owner.pid === "number" && typeof owner.created_at === "number") {
+            return { pid: owner.pid, created_at: owner.created_at };
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+function isProcessAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return (typeof error === "object" &&
+            error !== null &&
+            "code" in error &&
+            error.code === "EPERM");
+    }
+}
 async function refreshJwt(refreshToken, options) {
     const fetchImpl = options.fetchImpl ?? fetch;
     const response = await fetchImpl(`${options.authUrl ?? DEFAULT_AUTH_URL}/oauth/token`, {

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

@@ -3,7 +3,7 @@ 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";
+import { getAuthStatus, getValidToken, logout, PAT_LOGIN_URL, savePat } from "./auth.js";
 import { resolveTwinklerPaths } from "./paths.js";
 import { installBundledSkills } from "./skillInstall.js";
 import { callTwinkler } from "./twinklerClient.js";
@@ -11,19 +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;
@@ -45,7 +51,30 @@ export async function runCli(context = {}) {
                 out(readPackageVersion());
                 return 0;
             case "auth":
-                return await runAuthCommand(args, { paths, env, out, stdin: context.stdin ?? process.stdin });
+                return await runAuthCommand(args, {
+                    paths,
+                    env,
+                    out,
+                    stdin: context.stdin ?? process.stdin,
+                    fetchImpl: context.fetchImpl
+                });
+            case "login":
+                return await runAuthCommand(["login", "--pat-stdin", ...args.filter((arg) => arg !== "--pat-stdin")], {
+                    paths,
+                    env,
+                    out,
+                    stdin: context.stdin ?? process.stdin,
+                    fetchImpl: context.fetchImpl
+                });
+            case "ensure":
+                return await runEnsureCommand(args, {
+                    paths,
+                    env,
+                    out,
+                    err,
+                    fetchImpl: context.fetchImpl,
+                    spawnSyncImpl: context.spawnSyncImpl ?? spawnSync
+                });
             case "call": {
                 const parsed = parseCallArgs(args);
                 const result = await callTwinkler({
@@ -57,6 +86,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));
@@ -64,7 +100,7 @@ export async function runCli(context = {}) {
             }
             case "setup": {
                 const results = installBundledSkills({ homeDir: paths.homeDir });
-                const auth = getAuthStatus({ authJsonPath: paths.authJsonPath, env });
+                const auth = await getVerifiedAuthStatus(paths, env, context.fetchImpl);
                 out([
                     "Twinkler setup",
                     renderSkillInstallResults(results),
@@ -76,9 +112,9 @@ export async function runCli(context = {}) {
             }
             case "update":
             case "upgrade":
-                return runUpdateCommand(args, { env, out, err });
+                return runUpdateCommand(args, { env, out, err, spawnSyncImpl: context.spawnSyncImpl ?? spawnSync });
             case "doctor": {
-                const auth = getAuthStatus({ authJsonPath: paths.authJsonPath, env });
+                const auth = await getVerifiedAuthStatus(paths, env, context.fetchImpl);
                 out([
                     "Twinkler doctor",
                     `Node: ${process.version}`,
@@ -106,16 +142,18 @@ 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;
     }
     if (subcommand === "status") {
-        const status = getAuthStatus({ authJsonPath: context.paths.authJsonPath, env: context.env });
+        const status = await getVerifiedAuthStatus(context.paths, context.env, context.fetchImpl);
         if (!status.authenticated) {
             context.out([
                 "Not logged in.",
@@ -154,6 +192,148 @@ async function runAuthCommand(args, context) {
     context.out(`Unknown auth subcommand: ${subcommand}`);
     return 1;
 }
+async 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 = await getVerifiedAuthStatus(context.paths, context.env, context.fetchImpl);
+    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;
+}
+async function getVerifiedAuthStatus(paths, env, fetchImpl) {
+    const auth = getAuthStatus({ authJsonPath: paths.authJsonPath, env });
+    if (!auth.authenticated)
+        return auth;
+    const token = await getValidToken({ authJsonPath: paths.authJsonPath, env, fetchImpl });
+    return { ...auth, authenticated: Boolean(token) };
+}
+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) {
@@ -196,26 +376,42 @@ function renderSkillInstallResults(results) {
 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", "@mkterswingman/5mghost-twinkler@latest"];
+    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 = spawnSync(npmCommand, installArgs, {
-        stdio: "inherit",
-        env: context.env
+    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) {
-        context.err(`Update failed: ${result.error.message}`);
-        return 1;
+        return { ok: false, command, exitCode: null, error: `Update failed: ${result.error.message}` };
     }
     if (result.status !== 0) {
-        context.err(`Update failed: npm exited with ${result.status ?? "unknown status"}`);
-        return result.status ?? 1;
+        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"}`
+        };
     }
-    context.out("Twinkler updated. Restart your AI session so newly installed skill text is loaded.");
-    return 0;
+    return { ok: true, command, exitCode: 0 };
 }
 async function readAllStdin(stdin) {
     const chunks = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mkterswingman/5mghost-twinkler",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Lightweight AI helper for the 5mghost Twinkler API",
   "type": "module",
   "engines": {

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

@@ -26,7 +26,6 @@ If `twinkler update` is unavailable because the installed version is old, run:
 
 ```bash
 npm install -g @mkterswingman/5mghost-twinkler@latest
-twinkler setup
 ```
 
 Then ask the user to restart the AI session so updated skill text is loaded.
@@ -35,7 +34,7 @@ Then ask the user to restart the AI session so updated skill text is loaded.
 
 ```bash
 twinkler version
-twinkler doctor
+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,137 +1,159 @@
 ---
 name: use-5mghost-twinkler
 preamble-tier: 3
-version: 0.2.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 handles 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 or auth is missing, use `setup-5mghost-twinkler`.
-Do not ask non-technical users to understand CLI concepts; operate the helper
-for them and explain only the action they need to take.
+Read the JSON.
 
-## Auth
+- 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.
 
-Twinkler uses the shared mkterswingman login/PAT. Do not call it a Twinkler PAT.
+Do not use time-based latest-version caches. The preflight checks npm latest on
+every invocation.
 
-If auth is missing:
+## Data Request Layer
 
-1. Give the user this URL: <https://mkterswingman.com/pat/login>
-2. Ask the user to copy the mkterswingman PAT.
-3. Start `twinkler auth login --pat-stdin`.
-4. Have the user paste the PAT into that local input, not into AI chat.
-
-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.
-
-## Common Calls
-
-Use:
+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/rankings/channels --query sort_by=mostfollowers --query days=30 --query page_size=5
+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
 ```
 
-`twinkler call` only allows Twinkler `/api/v1/*` paths. It returns JSON on
-stdout.
+Pick the smallest API that answers the question:
+
+- 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.
+
+## Watch Job Layer
+
+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.
 
-## Watch Jobs
+Before creating a new watch job in a new session, recover existing work:
 
-Use watch jobs when the user asks to monitor a currently live Twitch channel,
-collect CCV points, collect chat messages, or stop when the stream ends or
-changes game.
+```bash
+twinkler jobs active
+twinkler jobs recent
+```
 
-Create:
+Create a job:
 
 ```bash
 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"}}'
 ```
 
-The response contains a `job_id`. Save it in your working notes. Then poll:
+Then inspect it with:
 
 ```bash
-twinkler call GET /api/v1/twitch/watch/<job_id>
+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
 ```
 
-Stop/cleanup when the user is done:
+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 DELETE /api/v1/twitch/watch/<job_id>
+node scripts/create-watch-monitor.mjs --job-id <job_id> --cadence-min 10 --stop "stream ended or no longer matches requested game"
 ```
 
-Normal logged-in users can create and delete their own watch jobs. If the API
-returns `WATCH_DISABLED`, explain that the hosted watch worker is not enabled
-right now. If it returns `AUTH_*`, repair mkterswingman auth. If it returns a
-limit error, tell the user which limit was hit and stop creating more jobs.
+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
-import os
-import requests
+Stop conditions:
 
-token = os.environ["MKTERSWINGMAN_PAT"]
+- 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.
 
-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())
-```
+## Error And Recovery States
+
+- 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

@@ -2,22 +2,6 @@
   "schemaVersion": 1,
   "product": "5mghost-twinkler",
   "skills": [
-    {
-      "name": "setup-5mghost-twinkler",
-      "source": { "type": "local", "path": "./skills/setup-5mghost-twinkler" },
-      "targets": [
-        "claude",
-        "claude-internal",
-        "codex",
-        "codex-internal",
-        "gemini",
-        "gemini-internal",
-        "openclaw",
-        "workbuddy",
-        "codebuddy",
-        "agents"
-      ]
-    },
     {
       "name": "use-5mghost-twinkler",
       "source": { "type": "local", "path": "./skills/use-5mghost-twinkler" },