@witchpot/gmc 0.1.8 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to the Game Market Copilot CLI will be recorded here.
 
+## Unreleased
+
+## 0.2.0 - 2026-07-04
+
+- Added workspace game list commands for creating, listing, resolving, and
+  mutating saved cohorts from the CLI.
+- Added saved game lists as a cohort source for agent workflows and evidence
+  packs, including manual-list item notes.
+- Updated packaged schema/help output to include the new list routes and
+  commands.
+
+## 0.1.9 - 2026-07-03
+
+- Clarified packaged Agent Skill docs so Claude Code uses `gmc skill install`
+  and Codex/AGENTS.md-based agents use
+  `gmc skill print --format agents-md >> AGENTS.md`.
+
 ## 0.1.8 - 2026-06-12
 
 - Updated the bundled `gmc-analysis` skill to v0.2.0 with the learnings from

package/README.md

@@ -6,17 +6,17 @@ showcases.
 
 ## Install
 
-Install the beta CLI:
+Install the CLI:
 
 ```bash
-npm install -g @witchpot/gmc@beta
+npm install -g @witchpot/gmc
 gmc --version
 ```
 
 Or run it without a global install:
 
 ```bash
-npx @witchpot/gmc@beta --version
+npx @witchpot/gmc --version
 ```
 
 The package installs three equivalent binaries: `gmc`, `gmcp`, and
@@ -64,8 +64,10 @@ a non-secret prefix.
 ## Agent Skill
 
 The package bundles the `gmc-analysis` Agent Skill — analysis recipes, pivot
-heuristics, quota etiquette, and honesty rules for coding agents. Install it
-so Claude Code (and similar tools) load it automatically:
+heuristics, quota etiquette, and honesty rules for coding agents. The core
+analysis guidance is shared, but the registration step depends on the agent.
+
+For Claude Code, install the packaged skill directory:
 
 ```bash
 gmc skill install            # writes .claude/skills/gmc-analysis (project)
@@ -73,13 +75,16 @@ gmc skill install --global   # or ~/.claude/skills/gmc-analysis
 gmc skill status --json      # packaged vs installed versions
 ```
 
-For Codex and other AGENTS.md-based agents, append the self-contained
-edition (references inlined) to your project brief:
+For Codex and other AGENTS.md-based agents, append the self-contained edition
+(references inlined) to the repo brief the agent reads:
 
 ```bash
 gmc skill print --format agents-md >> AGENTS.md
 ```
 
+If `AGENTS.md` already contains a generated `gmc-analysis` section, update that
+section instead of appending a duplicate.
+
 Re-run install/print after `npm update` to pick up newer skill versions.
 
 ## First Queries
@@ -87,11 +92,11 @@ Re-run install/print after `npm update` to pick up newer skill versions.
 ```bash
 gmc schema --json
 gmc update --json
-gmc games resolve --source steam --query Timberborn --json
-gmc games detail --source steam 1062090 --json
-gmc campaigns signals --source steam 1062090 --json
-gmc games benchmark --source steam --tags city_builder,automation --reviews-min 1000 --preset summary --json
-gmc showcases fit --source steam 1062090 --json
+gmc games search --source steam --release-year 2025 --reviews-min 1000 --fields title,appid,rating,reviews --json
+gmc games aggregate --source steam --release-year 2025 --metric count,median_reviews --group-by release_year --reviews-min 1000 --json
+gmc games benchmark --source steam --tags <tag_slug[,tag_slug...]> --reviews-min 1000 --preset summary --json
+gmc reviews patterns --source steam --tags <tag_slug[,tag_slug...]> --sample-size 15 --preset summary --json
+gmc showcases patterns --source steam --tags <tag_slug[,tag_slug...]> --json
 ```
 
 Preserve `meta.requestId`, `meta.entitlements`, `warnings`, and `pagination`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@witchpot/gmc",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "private": false,
   "description": "Command line tools for Game Market Copilot market research.",
   "license": "UNLICENSED",
@@ -45,6 +45,8 @@
     "smoke:beta": "node scripts/smoke-beta.mjs",
     "pack:check": "node scripts/smoke-pack.mjs --dry-run",
     "smoke:pack": "node scripts/smoke-pack.mjs",
+    "publish:latest:dry-run": "npm publish --access public --dry-run --cache /tmp/gmc-npm-cache",
+    "publish:latest": "npm publish --access public --cache /tmp/gmc-npm-cache",
     "publish:beta:dry-run": "npm publish --tag beta --access public --dry-run --cache /tmp/gmc-npm-cache",
     "publish:beta": "npm publish --tag beta --access public --cache /tmp/gmc-npm-cache"
   }

package/scripts/smoke-beta.mjs

@@ -33,14 +33,40 @@ const smokeCommands = [
     validate: (payload) => requireSuccessEnvelope(payload, ["data.version", "data.cliCommands"])
   },
   {
-    name: "resolve Timberborn",
-    args: ["games", "resolve", "--source", "steam", "--query", "Timberborn", "--json"],
-    validate: (payload) => requireComposedEnvelope(payload, ["data.candidates", "data.resolution"])
+    name: "search recent reviewed games",
+    args: [
+      "games",
+      "search",
+      "--source",
+      "steam",
+      "--release-year",
+      "2025",
+      "--reviews-min",
+      "1000",
+      "--limit",
+      "5",
+      "--json"
+    ],
+    validate: (payload) => requireSuccessEnvelope(payload, ["data"])
   },
   {
-    name: "detail Timberborn",
-    args: ["games", "detail", "--source", "steam", "1062090", "--json"],
-    validate: (payload) => requireSuccessEnvelope(payload, ["data.title"])
+    name: "aggregate recent reviewed games",
+    args: [
+      "games",
+      "aggregate",
+      "--source",
+      "steam",
+      "--release-year",
+      "2025",
+      "--metric",
+      "count,median_reviews",
+      "--group-by",
+      "release_year",
+      "--reviews-min",
+      "1000",
+      "--json"
+    ],
+    validate: (payload) => requireSuccessEnvelope(payload, ["data"])
   },
   {
     name: "benchmark city builder automation",
@@ -60,9 +86,9 @@ const smokeCommands = [
     validate: (payload) => requireComposedEnvelope(payload, ["data.summary"])
   },
   {
-    name: "showcase fit Timberborn",
-    args: ["showcases", "fit", "--source", "steam", "1062090", "--json"],
-    validate: (payload) => requireComposedEnvelope(payload, ["data.matches", "data.summary"])
+    name: "showcase patterns by tag",
+    args: ["showcases", "patterns", "--source", "steam", "--tags", "city_builder,automation", "--json"],
+    validate: (payload) => requireComposedEnvelope(payload, ["data.summary"])
   }
 ];
 

package/skill/gmc-analysis/SKILL.md

@@ -53,6 +53,11 @@ For cohorts beyond one page, and for the full-cohort map-reduce procedure
 (pagination, bounded concurrency, `--fields` projection, subagent chunking),
 follow the recipes reference.
 
+Search commands are optimized for row retrieval. Do not expect
+`pagination.total` from `gmc games search` or CLI-composed evidence packs
+unless you explicitly pass `--include-total`; for count-only questions use
+`gmc games count` instead.
+
 ## Hard rules
 
 - **Missing data is not absent sentiment.** Report `cohort.usableGames`,

package/skill/gmc-analysis/references/pitfalls.md

@@ -69,4 +69,6 @@ exemplar rows and caveat bucket assignments, especially during sale seasons.
 List endpoints cap at `limit=100`. For "how many" questions use
 `gmc games count`; for distributions use `gmc games aggregate` — both are
 single-request server aggregates. Reserve pagination loops for when you
-actually need the rows (recipe R2).
+actually need the rows (recipe R2). `gmc games search` is optimized for rows
+and may omit `pagination.total`; pass `--include-total` only when a row page
+also needs an exact count.

package/skill/gmc-analysis/references/quota.md

@@ -25,3 +25,6 @@ indicative — the response metadata is the source of truth.
    midnight), and tell the user how much of the analysis completed.
 5. **Prefer server aggregates** (`count`, `aggregate`) over row pagination —
    they answer sizing questions in one request.
+6. **Keep totals explicit.** Search commands prioritize fast row pages and
+   exact totals are opt-in (`--include-total`). Use `games count` for
+   denominators so row collection stays cheap.

package/skill/gmc-analysis/references/recipes.md

@@ -36,7 +36,9 @@ Cost: ~(pages + N) requests. Check quota headroom first (see quota.md).
 1. **Collect the cohort**: page `gmc games search <filters> --coverage
    full,partial --sort reviews_desc --limit 100 --offset <0,100,...>
    --fields appid,title,reviews --json` until `pagination.nextOffset` is
-   null.
+   null. Run `gmc games count` first when you need the denominator; add
+   `--include-total` to search only when the exact total must travel with the
+   row page.
 2. **Fan out** `gmc games analysis --source steam <appid> --sections
    reviews --json` per game with bounded concurrency (<= 8 parallel
    processes). Write each response to a temp file; tolerate individual

package/src/args.js

@@ -1,7 +1,7 @@
 import { EXIT_USAGE } from "./constants.js";
 import { writeJsonError } from "./output.js";
 
-export const BOOLEAN_OPTIONS = new Set(["json", "help", "version", "no-open", "global"]);
+export const BOOLEAN_OPTIONS = new Set(["json", "help", "version", "no-open", "global", "include-total"]);
 
 export function parseArgs(args) {
   const command = [];
@@ -56,6 +56,7 @@ function isCommandToken(command, token) {
       "creators",
       "cohort",
       "showcases",
+      "lists",
       "auth",
       "login",
       "logout",
@@ -95,6 +96,9 @@ function isCommandToken(command, token) {
   if (command[0] === "showcases") {
     return ["search", "fit", "patterns"].includes(token);
   }
+  if (command[0] === "lists") {
+    return ["create", "show", "games", "add", "remove", "delete"].includes(token);
+  }
   return false;
 }
 

package/src/config.js

@@ -187,15 +187,15 @@ export async function handleLocalCommand(command, options, positional, config) {
         status: "manual_update_required",
         updateCheck: {
           available: null,
-          reason: "The CLI does not query the npm registry yet. Use the install command for the closed-beta package once it is published."
+          reason: "The CLI does not query the npm registry yet. Use npm install or npx to run the current public package."
         },
         commands: {
-          npmGlobal: `npm install -g ${CLI_BETA_PACKAGE_NAME}@beta`,
-          npmExec: `npx ${CLI_BETA_PACKAGE_NAME}@beta --version`
+          npmGlobal: `npm install -g ${CLI_PACKAGE_NAME}`,
+          npmExec: `npx ${CLI_PACKAGE_NAME} --version`
         },
         notes: [
-          "This command is intentionally non-mutating in the closed-beta contract.",
-          "A future gmc update --apply command can run the package-manager update after the npm distribution channel is finalized."
+          "This command is intentionally non-mutating.",
+          "A future gmc update --apply command can run the package-manager update after registry checks are implemented."
         ]
       }
     };

package/src/constants.js

@@ -8,7 +8,7 @@ export const EXIT_API = 4;
 
 export const CLI_PACKAGE_NAME = "@witchpot/gmc";
 export const CLI_BETA_PACKAGE_NAME = "@witchpot/gmc";
-export const CLI_VERSION = "0.1.8";
+export const CLI_VERSION = "0.2.0";
 
 export const DEFAULT_API_BASE_URL = "https://gamemarketcopilot.com";
 export const DEFAULT_CONFIG_PATH = path.join(homedir(), ".config", "gmc", "config.json");
@@ -33,6 +33,8 @@ export const SUPPORTED_BETA_COMMANDS = [
   "gmc games topics --source steam <externalId> --json",
   "gmc games compare --source steam <externalId> <externalId...> --focus market --json",
   "gmc games benchmark --source steam --tags <tag_slug[,tag_slug...]> --reviews-min <number> --json",
+  "gmc lists --json",
+  "gmc lists games <id> --json",
   "gmc reviews patterns --source steam --tags <tag_slug[,tag_slug...]> --reviews-min <number> --json",
   "gmc showcases search --query <text> --json",
   "gmc showcases fit --source steam <externalId> --deadline-before <YYYY-MM-DD> --json"
@@ -47,6 +49,7 @@ export const PROVISIONAL_BETA_COMMANDS = [
   "gmc cohort pricing --source steam --tags <tag_slug[,tag_slug...]> --json",
   "gmc cohort compare --source steam --tags <tag_slug[,tag_slug...]> --json",
   "gmc cohort brief --source steam --tags <tag_slug[,tag_slug...]> --json",
+  "gmc cohort brief --source steam --list <id> --json",
   "gmc showcases patterns --source steam --tags <tag_slug[,tag_slug...]> --json"
 ];
 

package/src/help.js

@@ -25,6 +25,10 @@ Usage:
   gmc skill print --format agents-md
   gmc skill status --json
   gmc schema --json
+  gmc lists --json
+  gmc lists create --name <name> --kind manual --json
+  gmc lists games <id> --json
+  gmc lists add <id> --app-ids <appid[,appid...]> --json
   gmc games search --source steam --query <text> --json
   gmc games count --source steam --release-year <year> --reviews-gt <number> --json
   gmc games aggregate --source steam --metric count,median_reviews --group-by release_year --json
@@ -47,6 +51,7 @@ Usage:
   gmc cohort pricing --source steam --tags <tag_slug[,tag_slug...]> --json
   gmc cohort compare --source steam --tags <tag_slug[,tag_slug...]> --json
   gmc cohort brief --source steam --tags <tag_slug[,tag_slug...]> --json
+  gmc cohort brief --source steam --list <id> --json
   gmc showcases search --query <text> --json
   gmc showcases fit --source steam <externalId> --deadline-before <YYYY-MM-DD> --json
   gmc showcases patterns --source steam --tags <tag_slug[,tag_slug...]> --json
@@ -56,10 +61,10 @@ Binary aliases:
   alias shadows gmc (Oh My Zsh's git plugin defines gmc as
   'git merge --continue').
 
-Supported beta commands:
+Supported commands:
 ${SUPPORTED_BETA_COMMANDS.map((command) => `  ${command}`).join("\n")}
 
-Provisional beta commands:
+Provisional commands:
 ${PROVISIONAL_BETA_COMMANDS.map((command) => `  ${command}`).join("\n")}
 
 Environment:
@@ -102,6 +107,8 @@ Sorting:
 Pagination:
   --limit <number>            1-100, default 20.
   --offset <number>           Offset for the next page.
+  --include-total             Also fetch an exact total. Prefer games count
+                              when the user only asks how many games match.
 
 Output:
   --fields <list>             Optional comma-separated field list.

package/src/main.js

@@ -12,6 +12,7 @@ import { printGamesSearchHelp, printHelp } from "./help.js";
 import { writeJsonError } from "./output.js";
 import { applyOutputProjection } from "./projection.js";
 import { buildRequest } from "./requests.js";
+import { trackCliCommandExecuted } from "./telemetry.js";
 import { executeRequestPlan } from "./workflows.js";
 
 export async function main(argv = process.argv.slice(2)) {
@@ -78,6 +79,7 @@ export async function main(argv = process.argv.slice(2)) {
     process.exit(EXIT_CONFIG);
   }
 
+  const startedAt = Date.now();
   const response = await executeRequestPlan(baseUrl, request, { apiKey });
   const payload = matches(command, ["auth", "status"])
     ? enrichAuthStatusOutput(response, config)
@@ -89,6 +91,16 @@ export async function main(argv = process.argv.slice(2)) {
   });
 
   process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
+  await trackCliCommandExecuted({
+    baseUrl,
+    apiKey,
+    command,
+    options,
+    positional,
+    request,
+    response: payload,
+    startedAt
+  });
 }
 
 export function runCliEntryPoint() {

package/src/requests.js

@@ -37,6 +37,80 @@ export function buildRequest(command, options, positional) {
     };
   }
 
+  if (matches(command, ["lists"])) {
+    return {
+      path: "/api/v1/lists",
+      query: {}
+    };
+  }
+
+  if (matches(command, ["lists", "create"])) {
+    const kind = assertListKind(options.kind ?? "manual");
+    return {
+      path: "/api/v1/lists",
+      method: "POST",
+      query: {},
+      body: {
+        name: assertRequiredOption(options.name, "--name"),
+        kind,
+        ...(options.description ? { description: options.description } : {}),
+        ...(kind === "filter" ? { filter: parseJsonOption(options.filter, "--filter") } : {}),
+        ...(options.sort ? { sort: parseJsonOption(options.sort, "--sort") } : {})
+      }
+    };
+  }
+
+  if (matches(command, ["lists", "show"])) {
+    const id = assertListId(positional[0], "gmc lists show <id> --json");
+    return {
+      path: `/api/v1/lists/${encodeURIComponent(id)}`,
+      query: {}
+    };
+  }
+
+  if (matches(command, ["lists", "games"])) {
+    const id = assertListId(positional[0], "gmc lists games <id> --json");
+    return {
+      path: `/api/v1/lists/${encodeURIComponent(id)}/games`,
+      query: pickQuery(options, {
+        limit: "limit",
+        offset: "offset"
+      })
+    };
+  }
+
+  if (matches(command, ["lists", "add"])) {
+    const id = assertListId(positional[0], "gmc lists add <id> --app-ids <ids> --json");
+    return {
+      path: `/api/v1/lists/${encodeURIComponent(id)}/items`,
+      method: "POST",
+      query: {},
+      body: {
+        appids: parseAppIdsOption(options["app-ids"] ?? options.appids),
+        ...(options.note ? { note: options.note } : {})
+      }
+    };
+  }
+
+  if (matches(command, ["lists", "remove"])) {
+    const id = assertListId(positional[0], "gmc lists remove <id> --app-ids <id> --json");
+    const [appid] = parseAppIdsOption(options["app-ids"] ?? options.appids);
+    return {
+      path: `/api/v1/lists/${encodeURIComponent(id)}/items/${encodeURIComponent(String(appid))}`,
+      method: "DELETE",
+      query: {}
+    };
+  }
+
+  if (matches(command, ["lists", "delete"])) {
+    const id = assertListId(positional[0], "gmc lists delete <id> --json");
+    return {
+      path: `/api/v1/lists/${encodeURIComponent(id)}`,
+      method: "DELETE",
+      query: {}
+    };
+  }
+
   if (matches(command, ["games", "search"])) {
     assertSource(options.source);
     return {
@@ -88,7 +162,7 @@ export function buildRequest(command, options, positional) {
     const query = {
       sort: "reviews_desc",
       limit: sampling?.pageLimit ?? DEFAULT_BENCHMARK_LIMIT,
-      ...buildGameSearchQuery(options)
+      ...buildGameSearchQuery(options, { includeTotal: false })
     };
     if (sampling && options.limit == null) query.limit = sampling.pageLimit;
     return {
@@ -96,6 +170,7 @@ export function buildRequest(command, options, positional) {
       source: "steam",
       query,
       sampling,
+      countRequest: buildOptionalGameCountRequest(options),
       searchRequest: {
         path: "/api/v1/steam/games",
         query
@@ -198,11 +273,20 @@ export function buildRequest(command, options, positional) {
     );
     const sentiment = options.sentiment == null ? undefined : assertReviewPatternSentiment(options.sentiment);
     const sampling = buildSamplingOptions(options, DEFAULT_REVIEW_PATTERNS_LIMIT);
-    const query = {
-      sort: "reviews_desc",
-      limit: sampling?.pageLimit ?? DEFAULT_REVIEW_PATTERNS_LIMIT,
-      ...buildGameSearchQuery(options)
-    };
+    const listId = options.list == null ? undefined : assertListId(options.list, "--list <id>");
+    const query = listId
+      ? {
+          list: listId,
+          limit: sampling?.pageLimit ?? DEFAULT_REVIEW_PATTERNS_LIMIT,
+          ...pickQuery(options, {
+            offset: "offset"
+          })
+        }
+      : {
+          sort: "reviews_desc",
+          limit: sampling?.pageLimit ?? DEFAULT_REVIEW_PATTERNS_LIMIT,
+          ...buildGameSearchQuery(options, { includeTotal: false })
+        };
     if (sampling && options.limit == null) query.limit = sampling.pageLimit;
 
     return {
@@ -210,13 +294,14 @@ export function buildRequest(command, options, positional) {
       source: "steam",
       query,
       sampling,
+      countRequest: listId ? undefined : buildOptionalGameCountRequest(options),
       minGames,
       maxTopicsPerGame,
       sentiment,
       topic: options.topic,
       compareBy: isCompare ? String(options.segment ?? "price") : undefined,
       searchRequest: {
-        path: "/api/v1/steam/games",
+        path: listId ? `/api/v1/lists/${encodeURIComponent(listId)}/games` : "/api/v1/steam/games",
         query
       },
       topicQuery: {
@@ -358,10 +443,42 @@ export function buildRequest(command, options, positional) {
 function buildCohortEvidenceRequest({ workflow, evidenceType, sections, options }) {
   assertSource(options.source);
   const sampling = buildSamplingOptions(options, DEFAULT_COHORT_WORKFLOW_LIMIT);
+  if (options.list != null) {
+    const listId = assertListId(options.list, "--list <id>");
+    const query = {
+      list: listId,
+      limit: sampling?.pageLimit ?? DEFAULT_COHORT_WORKFLOW_LIMIT,
+      ...pickQuery(options, {
+        offset: "offset"
+      })
+    };
+    if (sampling && options.limit == null) query.limit = sampling.pageLimit;
+    return {
+      kind: "cohortEvidence",
+      source: "steam",
+      workflow,
+      evidenceType,
+      sections,
+      query,
+      sampling,
+      searchRequest: {
+        path: `/api/v1/lists/${encodeURIComponent(listId)}/games`,
+        query
+      },
+      analysisQuery: sections.length
+        ? {
+            ...pickQuery(options, {
+              locale: "locale"
+            }),
+            sections: sections.join(",")
+          }
+        : undefined
+    };
+  }
   const query = {
     sort: "reviews_desc",
     limit: sampling?.pageLimit ?? DEFAULT_COHORT_WORKFLOW_LIMIT,
-    ...buildGameSearchQuery(options)
+    ...buildGameSearchQuery(options, { includeTotal: false })
   };
   if (sampling && options.limit == null) query.limit = sampling.pageLimit;
   return {
@@ -372,6 +489,7 @@ function buildCohortEvidenceRequest({ workflow, evidenceType, sections, options
     sections,
     query,
     sampling,
+    countRequest: buildOptionalGameCountRequest(options),
     searchRequest: {
       path: "/api/v1/steam/games",
       query
@@ -410,7 +528,7 @@ function pickQuery(options, mapping) {
   return query;
 }
 
-function buildGameSearchQuery(options) {
+function buildGameSearchQuery(options, { includeTotal = Boolean(options["include-total"]) } = {}) {
   const query = {
     ...buildGameCountQuery(options),
     ...pickQuery(options, {
@@ -418,12 +536,21 @@ function buildGameSearchQuery(options) {
       limit: "limit",
       offset: "offset",
       locale: "locale"
-    })
+    }),
+    includeTotal
   };
 
   return query;
 }
 
+function buildOptionalGameCountRequest(options) {
+  if (!options["include-total"]) return undefined;
+  return {
+    path: "/api/v1/steam/games/count",
+    query: buildGameCountQuery(options)
+  };
+}
+
 function buildGameCountQuery(options) {
   const query = pickQuery(options, {
     query: "q",
@@ -646,6 +773,73 @@ function assertResolveQuery(value) {
   }
 }
 
+function assertRequiredOption(value, optionName) {
+  if (value == null || String(value).trim() === "") {
+    writeJsonError({
+      code: "CLI_USAGE_ERROR",
+      message: `Missing required option ${optionName}`
+    });
+    process.exit(EXIT_USAGE);
+  }
+  return String(value);
+}
+
+function assertListKind(value) {
+  if (value !== "manual" && value !== "filter") {
+    writeJsonError({
+      code: "CLI_USAGE_ERROR",
+      message: "--kind must be manual or filter"
+    });
+    process.exit(EXIT_USAGE);
+  }
+  return value;
+}
+
+function assertListId(value, usage) {
+  if (value == null || String(value).trim() === "") {
+    writeJsonError({
+      code: "CLI_USAGE_ERROR",
+      message: `Missing list id. Usage: ${usage}`
+    });
+    process.exit(EXIT_USAGE);
+  }
+  return String(value);
+}
+
+function parseJsonOption(value, optionName) {
+  if (value == null) {
+    writeJsonError({
+      code: "CLI_USAGE_ERROR",
+      message: `${optionName} is required`
+    });
+    process.exit(EXIT_USAGE);
+  }
+  try {
+    const parsed = JSON.parse(String(value));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("expected object");
+    return parsed;
+  } catch {
+    writeJsonError({
+      code: "CLI_USAGE_ERROR",
+      message: `${optionName} must be a JSON object`
+    });
+    process.exit(EXIT_USAGE);
+  }
+}
+
+function parseAppIdsOption(value) {
+  const appids = parseCsvString(assertRequiredOption(value, "--app-ids"))
+    .map((item) => Number(item));
+  if (appids.length === 0 || appids.some((appid) => !Number.isSafeInteger(appid) || appid <= 0)) {
+    writeJsonError({
+      code: "CLI_USAGE_ERROR",
+      message: "--app-ids must be a comma-separated list of positive integers"
+    });
+    process.exit(EXIT_USAGE);
+  }
+  return appids;
+}
+
 function assertCompareExternalIds(values) {
   if (values.length < 2) {
     writeJsonError({