@witchpot/gmc 0.1.8 → 0.1.9

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to the Game Market Copilot CLI will be recorded here.
 
+## Unreleased
+
+## 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.1.9",
   "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 = [];

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.1.9";
 
 export const DEFAULT_API_BASE_URL = "https://gamemarketcopilot.com";
 export const DEFAULT_CONFIG_PATH = path.join(homedir(), ".config", "gmc", "config.json");

package/src/help.js

@@ -56,10 +56,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 +102,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

@@ -88,7 +88,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 +96,7 @@ export function buildRequest(command, options, positional) {
       source: "steam",
       query,
       sampling,
+      countRequest: buildOptionalGameCountRequest(options),
       searchRequest: {
         path: "/api/v1/steam/games",
         query
@@ -201,7 +202,7 @@ export function buildRequest(command, options, positional) {
     const query = {
       sort: "reviews_desc",
       limit: sampling?.pageLimit ?? DEFAULT_REVIEW_PATTERNS_LIMIT,
-      ...buildGameSearchQuery(options)
+      ...buildGameSearchQuery(options, { includeTotal: false })
     };
     if (sampling && options.limit == null) query.limit = sampling.pageLimit;
 
@@ -210,6 +211,7 @@ export function buildRequest(command, options, positional) {
       source: "steam",
       query,
       sampling,
+      countRequest: buildOptionalGameCountRequest(options),
       minGames,
       maxTopicsPerGame,
       sentiment,
@@ -361,7 +363,7 @@ function buildCohortEvidenceRequest({ workflow, evidenceType, sections, options
   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 +374,7 @@ function buildCohortEvidenceRequest({ workflow, evidenceType, sections, options
     sections,
     query,
     sampling,
+    countRequest: buildOptionalGameCountRequest(options),
     searchRequest: {
       path: "/api/v1/steam/games",
       query
@@ -410,7 +413,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 +421,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",

package/src/requests.test.js

@@ -15,11 +15,11 @@ test("games success-report builds the success-report request plan", () => {
     "success-report",
     "--source",
     "steam",
-    "1062090",
+    "123456",
     "--json"
   ]);
 
-  assert.equal(request.path, "/api/v1/steam/games/1062090/success-report");
+  assert.equal(request.path, "/api/v1/steam/games/123456/success-report");
   assert.deepEqual(request.query, {});
 });
 
@@ -29,13 +29,13 @@ test("games success-report forwards locale", () => {
     "success-report",
     "--source",
     "steam",
-    "1062090",
+    "123456",
     "--locale",
     "ja",
     "--json"
   ]);
 
-  assert.equal(request.path, "/api/v1/steam/games/1062090/success-report");
+  assert.equal(request.path, "/api/v1/steam/games/123456/success-report");
   assert.deepEqual(request.query, { locale: "ja" });
 });
 
@@ -45,11 +45,11 @@ test("games detail request plan stays unchanged", () => {
     "detail",
     "--source",
     "steam",
-    "1062090",
+    "123456",
     "--json"
   ]);
 
-  assert.equal(request.path, "/api/v1/steam/games/1062090");
+  assert.equal(request.path, "/api/v1/steam/games/123456");
   assert.deepEqual(request.query, {});
 });
 
@@ -69,6 +69,21 @@ test("games search forwards coverage as a filter", () => {
   assert.equal(request.path, "/api/v1/steam/games");
   assert.equal(request.query.coverage, "full,partial");
   assert.equal(request.query.reviewsMin, "1000");
+  assert.equal(request.query.includeTotal, false);
+});
+
+test("games search can opt into an exact total", () => {
+  const request = buildRequestFromArgv([
+    "games",
+    "search",
+    "--source",
+    "steam",
+    "--include-total",
+    "--json"
+  ]);
+
+  assert.equal(request.path, "/api/v1/steam/games");
+  assert.equal(request.query.includeTotal, true);
 });
 
 test("games count forwards coverage for cohort pre-estimation", () => {
@@ -101,4 +116,26 @@ test("reviews patterns forwards coverage into the cohort search request", () =>
 
   assert.equal(request.kind, "reviewPatterns");
   assert.equal(request.searchRequest.query.coverage, "full,partial");
+  assert.equal(request.searchRequest.query.includeTotal, false);
+});
+
+test("sampled workflows keep exact totals in a separate count request", () => {
+  const request = buildRequestFromArgv([
+    "games",
+    "benchmark",
+    "--source",
+    "steam",
+    "--release-year",
+    "2025",
+    "--include-total",
+    "--json"
+  ]);
+
+  assert.equal(request.kind, "benchmark");
+  assert.equal(request.searchRequest.query.includeTotal, false);
+  assert.equal(request.countRequest.path, "/api/v1/steam/games/count");
+  assert.deepEqual(request.countRequest.query, {
+    releaseFrom: "2025-01-01",
+    releaseTo: "2025-12-31"
+  });
 });

package/src/skill.js

@@ -51,7 +51,8 @@ export function handleSkillInstall(options) {
       scope: options.dir ? "custom" : options.global ? "global" : "project",
       next: [
         "Claude Code picks up project skills from .claude/skills automatically.",
-        "For Codex or other AGENTS.md-based agents run: gmc skill print --format agents-md >> AGENTS.md"
+        "For Codex or other AGENTS.md-based agents, append the self-contained instructions with: gmc skill print --format agents-md >> AGENTS.md",
+        "If AGENTS.md already contains a generated gmc-analysis section, update it instead of appending a duplicate."
       ]
     }
   };

package/src/telemetry.js

@@ -0,0 +1,341 @@
+import { CLI_VERSION } from "./constants.js";
+import { buildRequestHeaders } from "./requests.js";
+
+const TELEMETRY_TIMEOUT_MS = 800;
+const TELEMETRY_ENDPOINT = "/api/v1/product-events";
+const FORMAT_OPTION_KEYS = new Set(["json", "fields", "preset", "help", "version", "format"]);
+const RAW_TEXT_KEYS = new Set(["q", "query", "title", "topic", "message", "prompt"]);
+const SENSITIVE_OPTION_KEYS = new Set([
+  "api-key",
+  "authorization",
+  "bearer",
+  "credential",
+  "key",
+  "secret",
+  "token"
+]);
+const SAFE_QUERY_VALUE_KEYS = new Set([
+  "bucket",
+  "compareBy",
+  "coverage",
+  "detail",
+  "format",
+  "focus",
+  "groupBy",
+  "includeTotal",
+  "limit",
+  "locale",
+  "maxTopicsPerGame",
+  "metric",
+  "minGames",
+  "offset",
+  "priceMax",
+  "priceMin",
+  "ratingMin",
+  "releaseFrom",
+  "releaseTo",
+  "reviewsGt",
+  "reviewsLt",
+  "reviewsMax",
+  "reviewsMin",
+  "samplePages",
+  "sampleSize",
+  "sections",
+  "sentiment",
+  "sort",
+  "source",
+  "status",
+  "tagMode",
+  "tags"
+]);
+
+export async function trackCliCommandExecuted({
+  baseUrl,
+  apiKey,
+  command,
+  options,
+  positional,
+  request,
+  response,
+  startedAt
+}) {
+  if (!apiKey || isCliTelemetryDisabled()) return;
+
+  const event = buildCliCommandTelemetryEvent({
+    command,
+    options,
+    positional,
+    request,
+    response,
+    startedAt
+  });
+
+  await sendCliTelemetryEvent(baseUrl, apiKey, event);
+}
+
+export function buildCliCommandTelemetryEvent({
+  command,
+  options = {},
+  positional = [],
+  request,
+  response,
+  startedAt,
+  now = Date.now()
+}) {
+  const appid = extractSingleAppid(request);
+  const queryInputs = collectRequestQueries(request);
+  const safeQueryValues = mergeSafeQueryValues(queryInputs);
+  const properties = compactObject({
+    source: "gmc-cli",
+    cliVersion: CLI_VERSION,
+    command: command.join(" "),
+    commandGroup: command[0],
+    commandAction: command.slice(1).join(" ") || undefined,
+    workflow: request.workflow ?? request.kind ?? "direct",
+    endpointTemplate: getPrimaryEndpointTemplate(request),
+    success: true,
+    durationMs: boundedInteger(now - startedAt),
+    outputMode: options.json ? "json" : "default",
+    optionKeys: safeOptionKeys(options),
+    filterKeys: safeFilterKeys(queryInputs),
+    hasSearchText: hasRawTextInput(options, request, positional),
+    externalIdCount: countExternalIds(request),
+    tags: normalizeTokenList(safeQueryValues.tags),
+    sections: normalizeTokenList(safeQueryValues.sections),
+    coverage: normalizeTokenList(safeQueryValues.coverage),
+    focus: safeToken(request.focus ?? safeQueryValues.focus),
+    compareBy: safeToken(request.compareBy ?? safeQueryValues.compareBy),
+    evidenceType: safeToken(request.evidenceType),
+    metric: safeToken(safeQueryValues.metric),
+    groupBy: safeToken(safeQueryValues.groupBy),
+    bucket: safeToken(safeQueryValues.bucket),
+    sort: safeToken(safeQueryValues.sort),
+    status: safeToken(safeQueryValues.status),
+    format: safeToken(safeQueryValues.format),
+    tagMode: safeToken(safeQueryValues.tagMode),
+    limit: safeNumber(safeQueryValues.limit ?? request.limit),
+    offset: safeNumber(safeQueryValues.offset),
+    minGames: safeNumber(request.minGames),
+    maxTopicsPerGame: safeNumber(request.maxTopicsPerGame),
+    sampleMode: safeToken(request.sampling?.mode),
+    sampleRequestedSize: safeNumber(request.sampling?.requestedSize),
+    sampleRequestedPages: safeNumber(request.sampling?.requestedPages),
+    samplePageLimit: safeNumber(request.sampling?.pageLimit),
+    includeTotal: Boolean(safeQueryValues.includeTotal || request.countRequest),
+    releaseFrom: safeDate(safeQueryValues.releaseFrom),
+    releaseTo: safeDate(safeQueryValues.releaseTo),
+    reviewsMin: safeNumber(safeQueryValues.reviewsMin),
+    reviewsMax: safeNumber(safeQueryValues.reviewsMax),
+    reviewsGt: safeNumber(safeQueryValues.reviewsGt),
+    reviewsLt: safeNumber(safeQueryValues.reviewsLt),
+    ratingMin: safeNumber(safeQueryValues.ratingMin),
+    priceMin: safeNumber(safeQueryValues.priceMin),
+    priceMax: safeNumber(safeQueryValues.priceMax),
+    rowCount: topLevelRowCount(response),
+    warningCount: safeWarnings(response).length,
+    lockedCount: safeLockedSections(response).length,
+    resultKind: safeToken(response?.data?.kind),
+    apiRequestId: safeShortString(response?.meta?.requestId)
+  });
+
+  return compactObject({
+    eventType: "cli_command_executed",
+    appid,
+    properties
+  });
+}
+
+export async function sendCliTelemetryEvent(baseUrl, apiKey, event, {
+  fetchImpl = globalThis.fetch,
+  timeoutMs = TELEMETRY_TIMEOUT_MS
+} = {}) {
+  if (typeof fetchImpl !== "function") return;
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const url = new URL(TELEMETRY_ENDPOINT, baseUrl);
+    await fetchImpl(url, {
+      method: "POST",
+      headers: {
+        ...buildRequestHeaders(apiKey),
+        "content-type": "application/json"
+      },
+      body: JSON.stringify(event),
+      signal: controller.signal
+    });
+  } catch (error) {
+    // CLI telemetry is best-effort and must never change command behavior.
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export function isCliTelemetryDisabled(env = process.env) {
+  if (env.GMC_CLI_TELEMETRY != null) {
+    return /^(0|false|off|no|disabled)$/i.test(String(env.GMC_CLI_TELEMETRY));
+  }
+  if (env.GMC_DISABLE_TELEMETRY != null) {
+    return /^(1|true|on|yes|enabled)$/i.test(String(env.GMC_DISABLE_TELEMETRY));
+  }
+  return false;
+}
+
+function safeOptionKeys(options) {
+  return Object.keys(options)
+    .filter((key) => !FORMAT_OPTION_KEYS.has(key) && !SENSITIVE_OPTION_KEYS.has(key))
+    .sort()
+    .slice(0, 40);
+}
+
+function collectRequestQueries(request) {
+  return [
+    request.query,
+    request.searchRequest?.query,
+    request.countRequest?.query,
+    request.topicQuery,
+    request.detailQuery,
+    request.analysisQuery,
+    request.showcaseQuery
+  ].filter((query) => query && typeof query === "object");
+}
+
+function mergeSafeQueryValues(queries) {
+  const values = {};
+  for (const query of queries) {
+    for (const [key, value] of Object.entries(query)) {
+      if (SAFE_QUERY_VALUE_KEYS.has(key) && value != null && value !== "") values[key] = value;
+    }
+  }
+  return values;
+}
+
+function safeFilterKeys(queries) {
+  const keys = new Set();
+  for (const query of queries) {
+    for (const [key, value] of Object.entries(query)) {
+      if (value == null || value === "" || RAW_TEXT_KEYS.has(key)) continue;
+      keys.add(key);
+    }
+  }
+  return [...keys].sort().slice(0, 40);
+}
+
+function hasRawTextInput(options, request, positional) {
+  if (Object.keys(options).some((key) => RAW_TEXT_KEYS.has(key) && options[key] != null && options[key] !== "")) {
+    return true;
+  }
+  if (typeof request.query === "string" && request.query.trim()) return true;
+  if (typeof request.topic === "string" && request.topic.trim()) return true;
+  if (request.query && typeof request.query === "object" && typeof request.query.q === "string" && request.query.q.trim()) {
+    return true;
+  }
+  if ((request.kind === "resolve" || request.workflow) && positional.some((value) => String(value).trim())) {
+    return true;
+  }
+  return false;
+}
+
+function getPrimaryEndpointTemplate(request) {
+  const path = request.path ?? request.searchRequest?.path ?? request.countRequest?.path;
+  if (!path) return undefined;
+  return templateEndpoint(path);
+}
+
+function templateEndpoint(path) {
+  return String(path)
+    .replace(/\/api\/v1\/steam\/games\/[^/]+/g, "/api/v1/steam/games/{externalId}")
+    .replace(/\/\d+(?=\/|$)/g, "/{id}");
+}
+
+function extractSingleAppid(request) {
+  const candidates = [
+    request.externalId,
+    ...(Array.isArray(request.externalIds) ? request.externalIds : []),
+    extractAppidFromPath(request.path)
+  ].filter(Boolean);
+  const unique = [...new Set(candidates.map((value) => String(value)))];
+  if (unique.length !== 1 || !/^\d+$/.test(unique[0])) return undefined;
+  const appid = Number(unique[0]);
+  return Number.isSafeInteger(appid) && appid > 0 ? appid : undefined;
+}
+
+function extractAppidFromPath(path) {
+  if (!path) return undefined;
+  const match = String(path).match(/\/api\/v1\/steam\/games\/([^/]+)/);
+  if (!match) return undefined;
+  return decodeURIComponent(match[1]);
+}
+
+function countExternalIds(request) {
+  if (Array.isArray(request.externalIds)) return request.externalIds.length;
+  if (request.externalId) return 1;
+  return extractAppidFromPath(request.path) ? 1 : 0;
+}
+
+function normalizeTokenList(value) {
+  const values = Array.isArray(value) ? value : String(value ?? "").split(",");
+  const normalized = values
+    .map((item) => safeToken(item))
+    .filter(Boolean);
+  return normalized.length ? [...new Set(normalized)].slice(0, 20) : undefined;
+}
+
+function safeToken(value) {
+  if (value == null || value === "") return undefined;
+  const normalized = String(value)
+    .trim()
+    .replace(/[^a-zA-Z0-9_.:-]/g, "_")
+    .replace(/_+/g, "_")
+    .slice(0, 80);
+  return normalized || undefined;
+}
+
+function safeShortString(value) {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed ? trimmed.slice(0, 120) : undefined;
+}
+
+function safeDate(value) {
+  if (typeof value !== "string") return undefined;
+  return /^\d{4}-\d{2}-\d{2}$/.test(value) ? value : undefined;
+}
+
+function safeNumber(value) {
+  if (value == null || value === "") return undefined;
+  const number = Number(value);
+  return Number.isFinite(number) ? number : undefined;
+}
+
+function boundedInteger(value) {
+  const number = Number(value);
+  if (!Number.isFinite(number)) return undefined;
+  return Math.max(0, Math.round(number));
+}
+
+function topLevelRowCount(response) {
+  if (Array.isArray(response?.data)) return response.data.length;
+  if (Array.isArray(response?.data?.games)) return response.data.games.length;
+  if (Array.isArray(response?.data?.cohort?.included)) return response.data.cohort.included.length;
+  return undefined;
+}
+
+function safeWarnings(response) {
+  if (Array.isArray(response?.warnings)) return response.warnings;
+  if (Array.isArray(response?.data?.warnings)) return response.data.warnings;
+  if (Array.isArray(response?.meta?.warnings)) return response.meta.warnings;
+  return [];
+}
+
+function safeLockedSections(response) {
+  const locked = response?.meta?.entitlements?.locked;
+  return Array.isArray(locked) ? locked : [];
+}
+
+function compactObject(value) {
+  return Object.fromEntries(
+    Object.entries(value).filter(([, entry]) => entry !== undefined)
+  );
+}

package/src/telemetry.test.js

@@ -0,0 +1,121 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  buildCliCommandTelemetryEvent,
+  isCliTelemetryDisabled,
+  sendCliTelemetryEvent
+} from "./telemetry.js";
+
+test("buildCliCommandTelemetryEvent captures safe CLI filters without raw search text", () => {
+  const event = buildCliCommandTelemetryEvent({
+    command: ["games", "search"],
+    options: {
+      source: "steam",
+      query: "cozy fishing games like Dredge",
+      tags: "cozy,fishing",
+      "reviews-min": "100",
+      "api-key": "gmc_should_not_appear",
+      json: true
+    },
+    positional: [],
+    request: {
+      path: "/api/v1/steam/games",
+      query: {
+        q: "cozy fishing games like Dredge",
+        tags: "cozy,fishing",
+        reviewsMin: "100",
+        source: "steam",
+        limit: "20"
+      }
+    },
+    response: {
+      data: [{ appid: 1 }, { appid: 2 }],
+      meta: {
+        requestId: "req_123"
+      }
+    },
+    startedAt: 1_000,
+    now: 1_250
+  });
+
+  const serialized = JSON.stringify(event);
+  assert.equal(event.eventType, "cli_command_executed");
+  assert.equal(event.properties.command, "games search");
+  assert.deepEqual(event.properties.tags, ["cozy", "fishing"]);
+  assert.equal(event.properties.reviewsMin, 100);
+  assert.equal(event.properties.hasSearchText, true);
+  assert.equal(event.properties.rowCount, 2);
+  assert.equal(event.properties.durationMs, 250);
+  assert.equal(event.properties.optionKeys.includes("api-key"), false);
+  assert.equal(serialized.includes("Dredge"), false);
+  assert.equal(serialized.includes("cozy fishing games"), false);
+  assert.equal(serialized.includes("gmc_should_not_appear"), false);
+});
+
+test("buildCliCommandTelemetryEvent templates app endpoints and attaches single appid", () => {
+  const event = buildCliCommandTelemetryEvent({
+    command: ["games", "analysis"],
+    options: {
+      source: "steam",
+      sections: "reviews,marketing",
+      json: true
+    },
+    positional: ["1384160"],
+    request: {
+      path: "/api/v1/steam/games/1384160/analysis",
+      query: {
+        sections: "reviews,marketing"
+      }
+    },
+    response: {
+      data: {
+        kind: "game_analysis"
+      },
+      meta: {
+        entitlements: {
+          locked: ["marketing.full"]
+        }
+      }
+    },
+    startedAt: 2_000,
+    now: 2_040
+  });
+
+  assert.equal(event.appid, 1384160);
+  assert.equal(event.properties.endpointTemplate, "/api/v1/steam/games/{externalId}/analysis");
+  assert.deepEqual(event.properties.sections, ["reviews", "marketing"]);
+  assert.equal(event.properties.lockedCount, 1);
+  assert.equal(event.properties.resultKind, "game_analysis");
+});
+
+test("sendCliTelemetryEvent posts product events with bearer auth and swallows failures", async () => {
+  const calls = [];
+  const fetchImpl = async (url, init) => {
+    calls.push({ url, init });
+    throw new Error("network unavailable");
+  };
+
+  await sendCliTelemetryEvent("https://example.test", "gmcc_secret", {
+    eventType: "cli_command_executed",
+    properties: {
+      source: "gmc-cli"
+    }
+  }, {
+    fetchImpl,
+    timeoutMs: 20
+  });
+
+  assert.equal(calls.length, 1);
+  assert.equal(String(calls[0].url), "https://example.test/api/v1/product-events");
+  assert.equal(calls[0].init.method, "POST");
+  assert.equal(calls[0].init.headers.authorization, "Bearer gmcc_secret");
+});
+
+test("isCliTelemetryDisabled supports opt-out environment values", () => {
+  assert.equal(isCliTelemetryDisabled({}), false);
+  assert.equal(isCliTelemetryDisabled({ GMC_CLI_TELEMETRY: "0" }), true);
+  assert.equal(isCliTelemetryDisabled({ GMC_CLI_TELEMETRY: "1" }), false);
+  assert.equal(isCliTelemetryDisabled({ GMC_DISABLE_TELEMETRY: "1" }), true);
+  assert.equal(isCliTelemetryDisabled({ GMC_CLI_TELEMETRY: "true" }), false);
+});

package/src/workflows.js

@@ -30,7 +30,10 @@ export async function executeRequestPlan(baseUrl, request, { apiKey }) {
 }
 
 async function executeCohortEvidenceRequest(baseUrl, request, { apiKey }) {
-  const sampled = await executeSearchPages(baseUrl, request.searchRequest, request.sampling, { apiKey });
+  const [sampled, count] = await Promise.all([
+    executeSearchPages(baseUrl, request.searchRequest, request.sampling, { apiKey }),
+    fetchOptionalCount(baseUrl, request.countRequest, { apiKey })
+  ]);
   const search = mergeSearchPages(sampled.searches, request.sampling);
   const games = Array.isArray(search?.data) ? search.data : [];
   const analysisResults = request.analysisQuery
@@ -69,6 +72,7 @@ async function executeCohortEvidenceRequest(baseUrl, request, { apiKey }) {
 
   return composeCohortEvidencePayload(request, {
     search,
+    count,
     searches: sampled.searches,
     searchPageErrors: sampled.pageErrors,
     analysisResults
@@ -81,8 +85,11 @@ async function executeResolveRequest(baseUrl, request, { apiKey }) {
 }
 
 async function executeBenchmarkRequest(baseUrl, request, { apiKey }) {
-  const sampled = await executeSearchPages(baseUrl, request.searchRequest, request.sampling, { apiKey });
-  return composeBenchmarkPayload(request, sampled);
+  const [sampled, count] = await Promise.all([
+    executeSearchPages(baseUrl, request.searchRequest, request.sampling, { apiKey }),
+    fetchOptionalCount(baseUrl, request.countRequest, { apiKey })
+  ]);
+  return composeBenchmarkPayload(request, { ...sampled, count });
 }
 
 async function executeCompareRequest(baseUrl, request, { apiKey }) {
@@ -116,7 +123,10 @@ async function executeCompareRequest(baseUrl, request, { apiKey }) {
 }
 
 async function executeReviewPatternsRequest(baseUrl, request, { apiKey }) {
-  const sampled = await executeSearchPages(baseUrl, request.searchRequest, request.sampling, { apiKey });
+  const [sampled, count] = await Promise.all([
+    executeSearchPages(baseUrl, request.searchRequest, request.sampling, { apiKey }),
+    fetchOptionalCount(baseUrl, request.countRequest, { apiKey })
+  ]);
   const search = mergeSearchPages(sampled.searches, request.sampling);
   const games = Array.isArray(search?.data) ? search.data : [];
   const topicResults = await Promise.all(
@@ -153,6 +163,7 @@ async function executeReviewPatternsRequest(baseUrl, request, { apiKey }) {
 
   return composeReviewPatternsPayload(request, {
     search,
+    count,
     searches: sampled.searches,
     searchPageErrors: sampled.pageErrors,
     topicResults
@@ -243,6 +254,11 @@ async function executeSearchPages(baseUrl, searchRequest, sampling, { apiKey })
   };
 }
 
+async function fetchOptionalCount(baseUrl, countRequest, { apiKey }) {
+  if (!countRequest) return undefined;
+  return fetchJson(createRequestUrl(baseUrl, countRequest), { apiKey });
+}
+
 function shouldFetchNextSamplePage(sampling, searches) {
   if (sampling.mode === "sample-pages") return searches.length < sampling.requestedPages;
   const fetchedRows = searches.reduce((sum, search) => sum + asArray(search?.data).length, 0);
@@ -383,6 +399,8 @@ export function composeBenchmarkPayload(request, search, options = {}) {
     : search;
   const games = Array.isArray(mergedSearch?.data) ? mergedSearch.data : [];
   const sample = buildSampleMetadata(request, searches, games, pageErrors);
+  const totalMatches = getTotalMatches(search.count, mergedSearch?.pagination);
+  const pagination = withPaginationTotal(mergedSearch?.pagination, totalMatches);
 
   return {
     data: {
@@ -391,19 +409,19 @@ export function composeBenchmarkPayload(request, search, options = {}) {
       workflow: "gamesBenchmark",
       inputs: {
         filters: request.query,
-        ...(sample ? { sample: buildEvidencePackSample(sample, games.length) } : {
-          sample: buildReturnedPageSample(mergedSearch?.pagination, games.length)
+        ...(sample ? { sample: buildEvidencePackSample(sample, games.length, totalMatches) } : {
+          sample: buildReturnedPageSample(pagination, games.length, totalMatches)
         })
       },
       query: request.query,
       summary: withSummaryBasis(
-        buildBenchmarkSummary(games, mergedSearch?.pagination, request.source, { sampled: Boolean(sample) }),
+        buildBenchmarkSummary(games, pagination, request.source, { sampled: Boolean(sample) }),
         sample ? "bounded_sample" : "returned_page"
       ),
       ...(sample
         ? {
             sampledSummary: withSummaryBasis(
-              buildBenchmarkSummary(games, mergedSearch?.pagination, request.source, { sampled: true }),
+              buildBenchmarkSummary(games, pagination, request.source, { sampled: true }),
               "bounded_sample"
             )
           }
@@ -424,11 +442,15 @@ export function composeBenchmarkPayload(request, search, options = {}) {
       requestId,
       composedBy: "gmc-cli",
       ...(sample ? { sample } : {}),
-      upstreamRequests: buildSearchUpstreamRequests(searches, pageErrors)
+      upstreamRequests: [
+        ...buildSearchUpstreamRequests(searches, pageErrors),
+        ...buildCountUpstreamRequests(search.count)
+      ]
     },
-    ...(mergedSearch?.pagination ? { pagination: mergedSearch.pagination } : {}),
+    ...(pagination ? { pagination } : {}),
     warnings: uniqueStrings([
       ...searches.flatMap((entry) => safeWarnings(entry)),
+      ...safeWarnings(search.count),
       ...pageErrors.map((entry) => `benchmark sample page failed at offset ${entry.offset}: ${entry.error?.code ?? "CLI_API_ERROR"}`),
       sample
         ? "sampledSummary is computed from bounded sampled pages; it is not a full market-size estimate"
@@ -457,6 +479,7 @@ export function composeReviewPatternsPayload(request, result, options = {}) {
   const includedGames = normalizedGames.filter((game) => !game.skippedReason);
   const usableGames = includedGames.filter((game) => game.topics.length > 0);
   const sample = buildSampleMetadata(request, searches, games, searchPageErrors);
+  const totalMatches = getTotalMatches(result.count, result.search?.pagination);
   const skipped = normalizedGames
     .filter((game) => game.skippedReason)
     .map((game) => ({
@@ -469,6 +492,7 @@ export function composeReviewPatternsPayload(request, result, options = {}) {
     }));
   const warnings = uniqueStrings([
     ...safeWarnings(result.search),
+    ...safeWarnings(result.count),
     ...searches.flatMap((entry) => safeWarnings(entry)),
     ...searchPageErrors.map((entry) => `review pattern sample page failed at offset ${entry.offset}: ${entry.error?.code ?? "CLI_API_ERROR"}`),
     ...topicResults.flatMap((entry) => safeWarnings(entry.topics)),
@@ -491,8 +515,8 @@ export function composeReviewPatternsPayload(request, result, options = {}) {
         ...(request.topic ? { topic: request.topic } : {}),
         ...(request.compareBy ? { compareBy: request.compareBy } : {}),
         ...(sample
-          ? { sample: buildEvidencePackSample(sample, usableGames.length) }
-          : { sample: buildReturnedPageSample(result.search?.pagination, usableGames.length) })
+          ? { sample: buildEvidencePackSample(sample, usableGames.length, totalMatches) }
+          : { sample: buildReturnedPageSample(result.search?.pagination, usableGames.length, totalMatches) })
       },
       cohort: {
         query: request.query,
@@ -505,7 +529,7 @@ export function composeReviewPatternsPayload(request, result, options = {}) {
         usableGames: usableGames.length,
         skippedGames: skipped.length,
         skippedReasons: tallySkippedReasons(skipped),
-        totalMatches: result.search?.pagination?.total,
+        ...(typeof totalMatches === "number" ? { totalMatches } : {}),
         included: usableGames.map((game) => ({
           source: request.source,
           externalId: game.externalId,
@@ -521,7 +545,7 @@ export function composeReviewPatternsPayload(request, result, options = {}) {
         skipped
       },
       summary: withSummaryBasis(
-        buildReviewPatternsSummary(request, usableGames, skipped, result.search?.pagination),
+        buildReviewPatternsSummary(request, usableGames, skipped, withPaginationTotal(result.search?.pagination, totalMatches)),
         sample ? "bounded_sample" : "returned_page"
       ),
       patterns: buildReviewPatterns(usableGames),
@@ -547,6 +571,7 @@ export function composeReviewPatternsPayload(request, result, options = {}) {
       ...(sample ? { sample } : {}),
       upstreamRequests: [
         ...buildSearchUpstreamRequests(searches, searchPageErrors),
+        ...buildCountUpstreamRequests(result.count),
         ...topicResults
           .filter((entry) => entry.topics || entry.error)
           .map((entry) => ({
@@ -559,7 +584,7 @@ export function composeReviewPatternsPayload(request, result, options = {}) {
           }))
       ]
     },
-    ...(result.search?.pagination ? { pagination: result.search.pagination } : {}),
+    ...(result.search?.pagination ? { pagination: withPaginationTotal(result.search.pagination, totalMatches) } : {}),
     ...(warnings.length ? { warnings } : {})
   };
 }
@@ -670,8 +695,10 @@ export function composeCohortEvidencePayload(request, result, options = {}) {
       ...(entry.error ? { error: entry.error } : {})
     }));
   const sample = buildSampleMetadata(request, searches, games, searchPageErrors);
+  const totalMatches = getTotalMatches(result.count, result.search?.pagination);
   const warnings = uniqueStrings([
     ...safeWarnings(result.search),
+    ...safeWarnings(result.count),
     ...searches.flatMap((entry) => safeWarnings(entry)),
     ...searchPageErrors.map((entry) => `${request.workflow} sample page failed at offset ${entry.offset}: ${entry.error?.code ?? "CLI_API_ERROR"}`),
     ...analysisResults.flatMap((entry) => safeWarnings(entry.analysis)),
@@ -688,8 +715,8 @@ export function composeCohortEvidencePayload(request, result, options = {}) {
       inputs: {
         filters: request.query,
         sections: request.sections,
-        ...(sample ? { sample: buildEvidencePackSample(sample, included.length) } : {
-          sample: buildReturnedPageSample(result.search?.pagination, included.length)
+        ...(sample ? { sample: buildEvidencePackSample(sample, included.length, totalMatches) } : {
+          sample: buildReturnedPageSample(result.search?.pagination, included.length, totalMatches)
         })
       },
       cohort: {
@@ -698,7 +725,7 @@ export function composeCohortEvidencePayload(request, result, options = {}) {
         usableGames: included.length,
         skippedGames: skipped.length,
         skippedReasons: tallySkippedReasons(skipped),
-        totalMatches: result.search?.pagination?.total,
+        ...(typeof totalMatches === "number" ? { totalMatches } : {}),
         included: included.map((entry) => ({
           source: request.source,
           externalId: entry.externalId,
@@ -716,12 +743,12 @@ export function composeCohortEvidencePayload(request, result, options = {}) {
         skipped
       },
       summary: withSummaryBasis(
-        buildCohortEvidenceSummary(request, included, result.search?.pagination),
+        buildCohortEvidenceSummary(request, included, withPaginationTotal(result.search?.pagination, totalMatches)),
         sample ? "bounded_sample" : "returned_page"
       ),
       patterns: buildCohortEvidencePatterns(request, included),
       ...(request.evidenceType === "pricing" ? { segments: buildPricingSegments(included) } : {}),
-      ...(request.evidenceType === "trends" || request.evidenceType === "brief" ? { trends: buildTrendSummary(included, result.search?.pagination, request.source) } : {}),
+      ...(request.evidenceType === "trends" || request.evidenceType === "brief" ? { trends: buildTrendSummary(included, withPaginationTotal(result.search?.pagination, totalMatches), request.source) } : {}),
       games: included.map((entry) => ({
         source: request.source,
         externalId: entry.externalId,
@@ -744,6 +771,7 @@ export function composeCohortEvidencePayload(request, result, options = {}) {
       ...(sample ? { sample } : {}),
       upstreamRequests: [
         ...buildSearchUpstreamRequests(searches, searchPageErrors),
+        ...buildCountUpstreamRequests(result.count),
         ...analysisResults
           .filter((entry) => entry.analysis || entry.error)
           .map((entry) => ({
@@ -756,7 +784,7 @@ export function composeCohortEvidencePayload(request, result, options = {}) {
           }))
       ]
     },
-    ...(result.search?.pagination ? { pagination: result.search.pagination } : {}),
+    ...(result.search?.pagination ? { pagination: withPaginationTotal(result.search.pagination, totalMatches) } : {}),
     ...(warnings.length ? { warnings } : {})
   };
 }
@@ -1021,7 +1049,7 @@ function mergeSearchPages(searches, sampling) {
       ...(first.pagination ?? {}),
       limit: first.pagination?.limit,
       offset: first.pagination?.offset,
-      total: first.pagination?.total,
+      ...(typeof first.pagination?.total === "number" ? { total: first.pagination.total } : {}),
       nextOffset: last.pagination?.nextOffset
     },
     warnings: uniqueStrings(searches.flatMap((search) => safeWarnings(search)))
@@ -1038,12 +1066,12 @@ function buildSampleMetadata(request, searches, games, pageErrors) {
     fetchedPages: searches.length,
     fetchedGames: games.length,
     skippedPages: pageErrors.length,
-    totalMatches: searches[0]?.pagination?.total,
+    ...(typeof searches[0]?.pagination?.total === "number" ? { totalMatches: searches[0].pagination.total } : {}),
     quotaCaveat: "Sampled workflows issue one search request per fetched page, plus downstream per-game requests when the command needs detail evidence."
   };
 }
 
-function buildEvidencePackSample(sample, returnedRows) {
+function buildEvidencePackSample(sample, returnedRows, totalMatches) {
   return {
     mode: normalizeEvidencePackSampleMode(sample.mode),
     requestedRows: sample.requestedSize,
@@ -1051,16 +1079,31 @@ function buildEvidencePackSample(sample, returnedRows) {
     returnedRows,
     fetchedPages: sample.fetchedPages,
     skippedPages: sample.skippedPages,
-    totalMatches: sample.totalMatches
+    totalMatches: typeof totalMatches === "number" ? totalMatches : sample.totalMatches
   };
 }
 
-function buildReturnedPageSample(pagination, returnedRows) {
+function buildReturnedPageSample(pagination, returnedRows, totalMatches) {
   return {
     mode: "returned_page",
     requestedRows: pagination?.limit,
     returnedRows,
-    totalMatches: pagination?.total
+    totalMatches: typeof totalMatches === "number" ? totalMatches : pagination?.total
+  };
+}
+
+function getTotalMatches(count, pagination) {
+  const countValue = numericValue(count?.data?.count);
+  if (Number.isFinite(countValue)) return countValue;
+  const paginationTotal = numericValue(pagination?.total);
+  return Number.isFinite(paginationTotal) ? paginationTotal : undefined;
+}
+
+function withPaginationTotal(pagination, totalMatches) {
+  if (typeof totalMatches !== "number") return pagination;
+  return {
+    ...(pagination ?? {}),
+    total: totalMatches
   };
 }
 
@@ -1096,6 +1139,17 @@ function buildSearchUpstreamRequests(searches, pageErrors = []) {
   ];
 }
 
+function buildCountUpstreamRequests(count) {
+  if (!count) return [];
+  return [{
+    kind: "count",
+    requestId: count?.meta?.requestId,
+    source: count?.meta?.source,
+    entitlements: count?.meta?.entitlements,
+    count: count?.data?.count
+  }];
+}
+
 function buildReviewPatternGame(request, entry) {
   const game = entry.game ?? {};
   const externalId = asString(entry.externalId ?? game?.externalId ?? game?.appid);

package/src/workflows.test.js

@@ -1,7 +1,7 @@
 import assert from "node:assert/strict";
 import test from "node:test";
 
-import { composeCohortEvidencePayload } from "./workflows.js";
+import { composeBenchmarkPayload, composeCohortEvidencePayload } from "./workflows.js";
 
 test("cohort evidence summarizes skipped games by reason", () => {
   const request = {
@@ -78,3 +78,30 @@ test("cohort evidence reports an empty reason tally when nothing is skipped", ()
 
   assert.deepEqual(payload.data.cohort.skippedReasons, {});
 });
+
+test("benchmark attaches exact total only when a count response is supplied", () => {
+  const request = {
+    source: "steam",
+    query: { sort: "reviews_desc", limit: 20, includeTotal: false }
+  };
+  const payload = composeBenchmarkPayload(request, {
+    searches: [{
+      data: [{ appid: 1, title: "Usable", reviews: 100 }],
+      pagination: { limit: 20, offset: 0, nextOffset: 20 },
+      meta: { requestId: "search_req", source: "steam-analysis" }
+    }],
+    pageErrors: [],
+    count: {
+      data: { count: 123 },
+      meta: { requestId: "count_req", source: "steam-analysis" }
+    }
+  }, {
+    generatedAt: "2026-06-12T00:00:00.000Z",
+    requestId: "req_test"
+  });
+
+  assert.equal(payload.data.summary.totalMatches, 123);
+  assert.equal(payload.data.inputs.sample.totalMatches, 123);
+  assert.equal(payload.pagination.total, 123);
+  assert.deepEqual(payload.meta.upstreamRequests.map((entry) => entry.kind), ["search", "count"]);
+});