@witchpot/gmc 0.1.0

package/src/workflows.js

@@ -0,0 +1,1862 @@
+import { COMPARE_FOCUS_SECTIONS, EXIT_API } from "./constants.js";
+import { buildRequestHeaders, createRequestUrl, filterShowcasesByDeadline } from "./requests.js";
+import { writeJsonError } from "./output.js";
+
+export async function executeRequestPlan(baseUrl, request, { apiKey }) {
+  if (request.kind === "resolve") {
+    return executeResolveRequest(baseUrl, request, { apiKey });
+  }
+  if (request.kind === "benchmark") {
+    return executeBenchmarkRequest(baseUrl, request, { apiKey });
+  }
+  if (request.kind === "compare") {
+    return executeCompareRequest(baseUrl, request, { apiKey });
+  }
+  if (request.kind === "reviewPatterns") {
+    return executeReviewPatternsRequest(baseUrl, request, { apiKey });
+  }
+  if (request.kind === "campaignSignals") {
+    return executeCampaignSignalsRequest(baseUrl, request, { apiKey });
+  }
+  if (request.kind === "cohortEvidence") {
+    return executeCohortEvidenceRequest(baseUrl, request, { apiKey });
+  }
+  if (request.kind === "showcaseFit") {
+    return executeShowcaseFitRequest(baseUrl, request, { apiKey });
+  }
+
+  const response = await fetchJson(createRequestUrl(baseUrl, request), { apiKey });
+  return request.transform ? request.transform(response) : response;
+}
+
+async function executeCohortEvidenceRequest(baseUrl, request, { apiKey }) {
+  const sampled = await executeSearchPages(baseUrl, request.searchRequest, request.sampling, { apiKey });
+  const search = mergeSearchPages(sampled.searches, request.sampling);
+  const games = Array.isArray(search?.data) ? search.data : [];
+  const analysisResults = request.analysisQuery
+    ? await Promise.all(games.map(async (game) => {
+        const externalId = asString(game?.externalId ?? game?.appid);
+        if (!externalId) {
+          return {
+            game,
+            skippedReason: "missing_external_id"
+          };
+        }
+
+        const analysisResult = await fetchJsonResult(createRequestUrl(baseUrl, {
+          path: `/api/v1/steam/games/${encodeURIComponent(externalId)}/analysis`,
+          query: request.analysisQuery
+        }), { apiKey });
+        if (!analysisResult.ok) {
+          return {
+            game,
+            externalId,
+            skippedReason: "analysis_request_failed",
+            error: analysisResult.error
+          };
+        }
+
+        return {
+          game,
+          externalId,
+          analysis: analysisResult.payload
+        };
+      }))
+    : games.map((game) => ({
+        game,
+        externalId: asString(game?.externalId ?? game?.appid)
+      }));
+
+  return composeCohortEvidencePayload(request, {
+    search,
+    searches: sampled.searches,
+    searchPageErrors: sampled.pageErrors,
+    analysisResults
+  });
+}
+
+async function executeResolveRequest(baseUrl, request, { apiKey }) {
+  const search = await fetchJson(createRequestUrl(baseUrl, request.searchRequest), { apiKey });
+  return composeResolvePayload(request, search);
+}
+
+async function executeBenchmarkRequest(baseUrl, request, { apiKey }) {
+  const sampled = await executeSearchPages(baseUrl, request.searchRequest, request.sampling, { apiKey });
+  return composeBenchmarkPayload(request, sampled);
+}
+
+async function executeCompareRequest(baseUrl, request, { apiKey }) {
+  const games = await Promise.all(
+    request.externalIds.map(async (externalId) => {
+      const detailRequest = {
+        path: `/api/v1/steam/games/${encodeURIComponent(externalId)}`,
+        query: request.query
+      };
+      const detail = await fetchJson(createRequestUrl(baseUrl, detailRequest), { apiKey });
+      const sections = COMPARE_FOCUS_SECTIONS[request.focus] ?? [];
+      const analysis = sections.length
+        ? await fetchJson(createRequestUrl(baseUrl, {
+            path: `/api/v1/steam/games/${encodeURIComponent(externalId)}/analysis`,
+            query: {
+              ...request.query,
+              sections: sections.join(",")
+            }
+          }), { apiKey })
+        : undefined;
+
+      return {
+        externalId,
+        detail,
+        analysis
+      };
+    })
+  );
+
+  return composeComparePayload(request, games);
+}
+
+async function executeReviewPatternsRequest(baseUrl, request, { apiKey }) {
+  const sampled = await executeSearchPages(baseUrl, request.searchRequest, request.sampling, { apiKey });
+  const search = mergeSearchPages(sampled.searches, request.sampling);
+  const games = Array.isArray(search?.data) ? search.data : [];
+  const topicResults = await Promise.all(
+    games.map(async (game) => {
+      const externalId = asString(game?.externalId ?? game?.appid);
+      if (!externalId) {
+        return {
+          game,
+          skippedReason: "missing_external_id"
+        };
+      }
+
+      const topicsUrl = createRequestUrl(baseUrl, {
+        path: `/api/v1/steam/games/${encodeURIComponent(externalId)}/review-topics`,
+        query: request.topicQuery
+      });
+      const topicsResult = await fetchJsonResult(topicsUrl, { apiKey });
+      if (!topicsResult.ok) {
+        return {
+          game,
+          externalId,
+          skippedReason: "review_topics_request_failed",
+          error: topicsResult.error
+        };
+      }
+
+      return {
+        game,
+        externalId,
+        topics: topicsResult.payload
+      };
+    })
+  );
+
+  return composeReviewPatternsPayload(request, {
+    search,
+    searches: sampled.searches,
+    searchPageErrors: sampled.pageErrors,
+    topicResults
+  });
+}
+
+async function executeCampaignSignalsRequest(baseUrl, request, { apiKey }) {
+  const detailRequest = {
+    path: `/api/v1/steam/games/${encodeURIComponent(request.externalId)}`,
+    query: request.detailQuery
+  };
+  const detail = await fetchJson(createRequestUrl(baseUrl, detailRequest), { apiKey });
+  return composeCampaignSignalsPayload(request, { detail });
+}
+
+async function executeShowcaseFitRequest(baseUrl, request, { apiKey }) {
+  const detailRequest = {
+    path: `/api/v1/steam/games/${encodeURIComponent(request.externalId)}`,
+    query: request.detailQuery
+  };
+  const detail = await fetchJson(createRequestUrl(baseUrl, detailRequest), { apiKey });
+  const tags = request.tagsOverride?.length
+    ? request.tagsOverride
+    : getPreferredShowcaseTags(detail.data);
+  const showcaseQuery = {
+    ...request.showcaseQuery,
+    ...(tags.length
+      ? {
+          tags: tags.join(","),
+          ...(request.showcaseQuery.tagMode ? {} : { tagMode: "or" })
+        }
+      : {})
+  };
+  const showcasesResponse = await fetchJson(createRequestUrl(baseUrl, {
+    path: "/api/v1/showcases",
+    query: showcaseQuery
+  }), { apiKey });
+  const showcases = request.deadlineBefore
+    ? filterShowcasesByDeadline(showcasesResponse, request.deadlineBefore)
+    : showcasesResponse;
+
+  return composeShowcaseFitPayload(request, {
+    detail,
+    showcases,
+    showcaseQuery,
+    tags
+  });
+}
+
+async function executeSearchPages(baseUrl, searchRequest, sampling, { apiKey }) {
+  if (!sampling) {
+    return {
+      searches: [await fetchJson(createRequestUrl(baseUrl, searchRequest), { apiKey })],
+      pageErrors: []
+    };
+  }
+
+  const firstSearch = await fetchJson(createRequestUrl(baseUrl, searchRequest), { apiKey });
+  const searches = [firstSearch];
+  const pageErrors = [];
+  let nextOffset = firstSearch?.pagination?.nextOffset;
+
+  while (nextOffset != null && shouldFetchNextSamplePage(sampling, searches)) {
+    const pageRequest = {
+      ...searchRequest,
+      query: {
+        ...searchRequest.query,
+        limit: sampling.pageLimit,
+        offset: nextOffset
+      }
+    };
+    const pageResult = await fetchJsonResult(createRequestUrl(baseUrl, pageRequest), { apiKey });
+    if (!pageResult.ok) {
+      pageErrors.push({
+        offset: nextOffset,
+        error: pageResult.error
+      });
+      break;
+    }
+
+    searches.push(pageResult.payload);
+    nextOffset = pageResult.payload?.pagination?.nextOffset;
+  }
+
+  return {
+    searches,
+    pageErrors
+  };
+}
+
+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);
+  return fetchedRows < sampling.requestedSize;
+}
+
+export function composeComparePayload(request, games, options = {}) {
+  const generatedAt = options.generatedAt ?? new Date().toISOString();
+  const requestId = options.requestId ?? createCliRequestId();
+  const warnings = uniqueStrings(games.flatMap((game) => [
+    ...safeWarnings(game.detail),
+    ...safeWarnings(game.analysis)
+  ]));
+
+  return {
+    data: {
+      kind: "evidence_pack",
+      source: request.source,
+      workflow: "gamesCompare",
+      inputs: {
+        externalIds: request.externalIds,
+        focus: request.focus,
+        sections: COMPARE_FOCUS_SECTIONS[request.focus] ?? []
+      },
+      focus: request.focus,
+      externalIds: request.externalIds,
+      cohort: {
+        included: games.map((game) => ({
+          source: request.source,
+          externalId: game.externalId,
+          title: game.detail?.data?.title,
+          evidence: {
+            detail: game.detail?.data,
+            ...(game.analysis ? { analysis: game.analysis.data } : {})
+          },
+          warnings: uniqueStrings([
+            ...safeWarnings(game.detail),
+            ...safeWarnings(game.analysis)
+          ])
+        })),
+        skipped: []
+      },
+      summary: withSummaryBasis({
+        targetCount: games.length,
+        analysisSections: COMPARE_FOCUS_SECTIONS[request.focus] ?? [],
+        comparedExternalIds: request.externalIds,
+        warningCount: warnings.length,
+        caveats: [
+          "Compare output is normalized evidence for selected titles, not a generated verdict.",
+          "Use locked metadata and warnings before making comparative claims.",
+          "Resolve ambiguous titles before calling compare so each target is source-backed."
+        ]
+      }, "returned_page"),
+      games: games.map((game) => ({
+        source: request.source,
+        externalId: game.externalId,
+        detail: game.detail?.data,
+        detailMeta: game.detail?.meta,
+        ...(game.analysis
+          ? {
+              analysis: game.analysis.data,
+              analysisMeta: game.analysis.meta
+            }
+          : {}),
+        warnings: uniqueStrings([
+          ...safeWarnings(game.detail),
+          ...safeWarnings(game.analysis)
+        ])
+      }))
+    },
+    meta: {
+      generatedAt,
+      requestId,
+      composedBy: "gmc-cli",
+      upstreamRequests: games.flatMap((game) => [
+        {
+          externalId: game.externalId,
+          kind: "detail",
+          requestId: game.detail?.meta?.requestId,
+          source: game.detail?.meta?.source,
+          entitlements: game.detail?.meta?.entitlements
+        },
+        ...(game.analysis
+          ? [{
+              externalId: game.externalId,
+              kind: "analysis",
+              requestId: game.analysis?.meta?.requestId,
+              source: game.analysis?.meta?.source,
+              entitlements: game.analysis?.meta?.entitlements
+            }]
+          : [])
+      ])
+    },
+    ...(warnings.length ? { warnings } : {})
+  };
+}
+
+export function composeResolvePayload(request, search, options = {}) {
+  const generatedAt = options.generatedAt ?? new Date().toISOString();
+  const requestId = options.requestId ?? createCliRequestId();
+  const candidates = Array.isArray(search?.data)
+    ? search.data.map((game, index) => buildResolveCandidate(request, game, index))
+    : [];
+  const rankedCandidates = candidates.sort((a, b) => b.score - a.score);
+
+  return {
+    data: {
+      source: request.source,
+      query: request.query,
+      resolution: summarizeResolution(rankedCandidates),
+      candidates: rankedCandidates
+    },
+    meta: {
+      generatedAt,
+      requestId,
+      composedBy: "gmc-cli",
+      upstreamRequests: [
+        {
+          kind: "search",
+          requestId: search?.meta?.requestId,
+          source: search?.meta?.source,
+          entitlements: search?.meta?.entitlements,
+          pagination: search?.pagination
+        }
+      ]
+    },
+    ...(Array.isArray(search?.warnings) && search.warnings.length ? { warnings: search.warnings } : {})
+  };
+}
+
+export function composeBenchmarkPayload(request, search, options = {}) {
+  const generatedAt = options.generatedAt ?? new Date().toISOString();
+  const requestId = options.requestId ?? createCliRequestId();
+  const searches = Array.isArray(search?.searches) ? search.searches : [search];
+  const pageErrors = Array.isArray(search?.pageErrors) ? search.pageErrors : [];
+  const mergedSearch = Array.isArray(search?.searches)
+    ? mergeSearchPages(search.searches, request.sampling)
+    : search;
+  const games = Array.isArray(mergedSearch?.data) ? mergedSearch.data : [];
+  const sample = buildSampleMetadata(request, searches, games, pageErrors);
+
+  return {
+    data: {
+      kind: "evidence_pack",
+      source: request.source,
+      workflow: "gamesBenchmark",
+      inputs: {
+        filters: request.query,
+        ...(sample ? { sample: buildEvidencePackSample(sample, games.length) } : {
+          sample: buildReturnedPageSample(mergedSearch?.pagination, games.length)
+        })
+      },
+      query: request.query,
+      summary: withSummaryBasis(
+        buildBenchmarkSummary(games, mergedSearch?.pagination, request.source, { sampled: Boolean(sample) }),
+        sample ? "bounded_sample" : "returned_page"
+      ),
+      ...(sample
+        ? {
+            sampledSummary: withSummaryBasis(
+              buildBenchmarkSummary(games, mergedSearch?.pagination, request.source, { sampled: true }),
+              "bounded_sample"
+            )
+          }
+        : {}),
+      cohort: {
+        included: games.map((game) => ({
+          source: request.source,
+          externalId: asString(game?.externalId ?? game?.appid),
+          title: game?.title ?? game?.name,
+          evidence: game
+        })),
+        skipped: []
+      },
+      games
+    },
+    meta: {
+      generatedAt,
+      requestId,
+      composedBy: "gmc-cli",
+      ...(sample ? { sample } : {}),
+      upstreamRequests: buildSearchUpstreamRequests(searches, pageErrors)
+    },
+    ...(mergedSearch?.pagination ? { pagination: mergedSearch.pagination } : {}),
+    warnings: uniqueStrings([
+      ...searches.flatMap((entry) => safeWarnings(entry)),
+      ...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"
+        : "benchmark summary is computed from the returned page only; it is not a full market-size estimate"
+    ])
+  };
+}
+
+export function composeReviewPatternsPayload(request, result, options = {}) {
+  const generatedAt = options.generatedAt ?? new Date().toISOString();
+  const requestId = options.requestId ?? createCliRequestId();
+  const games = Array.isArray(result.search?.data) ? result.search.data : [];
+  const searches = Array.isArray(result.searches) ? result.searches : [result.search];
+  const searchPageErrors = Array.isArray(result.searchPageErrors) ? result.searchPageErrors : [];
+  const topicResults = Array.isArray(result.topicResults) ? result.topicResults : [];
+  const normalizedGames = topicResults.map((entry) => buildReviewPatternGame(request, entry));
+  const includedGames = normalizedGames.filter((game) => !game.skippedReason);
+  const usableGames = includedGames.filter((game) => game.topics.length > 0);
+  const sample = buildSampleMetadata(request, searches, games, searchPageErrors);
+  const skipped = normalizedGames
+    .filter((game) => game.skippedReason)
+    .map((game) => ({
+      source: request.source,
+      externalId: game.externalId,
+      appid: game.appid,
+      title: game.title,
+      reason: game.skippedReason,
+      ...(game.error ? { error: game.error } : {})
+    }));
+  const warnings = uniqueStrings([
+    ...safeWarnings(result.search),
+    ...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)),
+    ...topicResults.flatMap((entry) => reviewPatternErrorWarning(entry)),
+    "review patterns are computed from the returned cohort page only; they are not full-market review clusters",
+    ...(usableGames.length < request.minGames
+      ? [`usable game count ${usableGames.length} is below --min-games ${request.minGames}`]
+      : [])
+  ]);
+
+  return {
+    data: {
+      kind: "evidence_pack",
+      source: request.source,
+      workflow: request.compareBy ? "reviewPatternsCompare" : "reviewPatterns",
+      inputs: {
+        filters: request.query,
+        sections: ["review-topics"],
+        ...(request.sentiment ? { sentiment: request.sentiment } : {}),
+        ...(request.topic ? { topic: request.topic } : {}),
+        ...(request.compareBy ? { compareBy: request.compareBy } : {}),
+        ...(sample
+          ? { sample: buildEvidencePackSample(sample, usableGames.length) }
+          : { sample: buildReturnedPageSample(result.search?.pagination, usableGames.length) })
+      },
+      cohort: {
+        query: request.query,
+        minGames: request.minGames,
+        maxTopicsPerGame: request.maxTopicsPerGame,
+        sentiment: request.sentiment,
+        topic: request.topic,
+        ...(request.compareBy ? { compareBy: request.compareBy } : {}),
+        returnedGames: games.length,
+        usableGames: usableGames.length,
+        skippedGames: skipped.length,
+        totalMatches: result.search?.pagination?.total,
+        included: usableGames.map((game) => ({
+          source: request.source,
+          externalId: game.externalId,
+          title: game.title,
+          evidence: {
+            reviews: game.reviews,
+            rating: game.rating,
+            releaseDate: game.releaseDate,
+            coverage: game.coverage,
+            topics: game.topics
+          }
+        })),
+        skipped
+      },
+      summary: withSummaryBasis(
+        buildReviewPatternsSummary(request, usableGames, skipped, result.search?.pagination),
+        sample ? "bounded_sample" : "returned_page"
+      ),
+      patterns: buildReviewPatterns(usableGames),
+      ...(request.compareBy ? { segments: buildReviewPatternSegments(usableGames, request.compareBy) } : {}),
+      games: includedGames.map((game) => ({
+        source: request.source,
+        externalId: game.externalId,
+        appid: game.appid,
+        title: game.title,
+        reviews: game.reviews,
+        rating: game.rating,
+        releaseDate: game.releaseDate,
+        coverage: game.coverage,
+        topicCount: game.topics.length,
+        topics: game.topics
+      })),
+      skipped
+    },
+    meta: {
+      generatedAt,
+      requestId,
+      composedBy: "gmc-cli",
+      ...(sample ? { sample } : {}),
+      upstreamRequests: [
+        ...buildSearchUpstreamRequests(searches, searchPageErrors),
+        ...topicResults
+          .filter((entry) => entry.topics || entry.error)
+          .map((entry) => ({
+            externalId: entry.externalId,
+            kind: "review-topics",
+            requestId: entry.topics?.meta?.requestId,
+            source: entry.topics?.meta?.source,
+            entitlements: entry.topics?.meta?.entitlements,
+            ...(entry.error ? { error: entry.error } : {})
+          }))
+      ]
+    },
+    ...(result.search?.pagination ? { pagination: result.search.pagination } : {}),
+    ...(warnings.length ? { warnings } : {})
+  };
+}
+
+export function composeCampaignSignalsPayload(request, result, options = {}) {
+  const generatedAt = options.generatedAt ?? new Date().toISOString();
+  const requestId = options.requestId ?? createCliRequestId();
+  const detail = result.detail ?? {};
+  const game = detail.data ?? {};
+  const allSignals = asArray(game?.insights?.marketing?.signals);
+  const signals = allSignals.slice(0, request.limit);
+  const locked = asArray(detail?.meta?.entitlements?.locked);
+  const warnings = uniqueStrings([
+    ...safeWarnings(detail),
+    ...(locked.some((key) => String(key).startsWith("marketing."))
+      ? ["Marketing campaign evidence is partially locked by the caller entitlement."]
+      : []),
+    "Campaign signals are observed source-backed evidence, not causal attribution or lift measurement."
+  ]);
+
+  return {
+    data: {
+      kind: "evidence_pack",
+      source: request.source,
+      workflow: "campaignSignals",
+      inputs: {
+        externalIds: [request.externalId],
+        sections: ["marketing"],
+        limit: request.limit
+      },
+      game: {
+        source: game.source,
+        externalId: asString(game.externalId ?? game.appid),
+        appid: game.appid,
+        title: game.title,
+        releaseDate: game.releaseDate,
+        coverage: game.coverage
+      },
+      summary: withSummaryBasis({
+        signalCount: signals.length,
+        totalSignalsReturnedByDetail: allSignals.length,
+        topSignalSources: topValues(signals.map((signal) => signal?.source)),
+        topCampaignTypes: topValues(signals.map((signal) => signal?.campaignType)),
+        locked: locked.filter((key) => String(key).startsWith("marketing.")),
+        caveats: [
+          "This pack uses visible fields from the Steam detail API only.",
+          "sourceUrl may be absent when the caller only has preview access.",
+          "Use future lift workflows before making before/after movement claims."
+        ]
+      }, "returned_detail"),
+      signals,
+      cohort: {
+        included: signals.length
+          ? [{
+              source: request.source,
+              externalId: request.externalId,
+              title: game.title,
+              evidence: {
+                signals
+              }
+            }]
+          : [],
+        skipped: signals.length
+          ? []
+          : [{
+              source: request.source,
+              externalId: request.externalId,
+              title: game.title,
+              reason: locked.some((key) => String(key).startsWith("marketing."))
+                ? "campaign_signals_locked_or_redacted"
+                : "no_campaign_signals"
+            }]
+      }
+    },
+    meta: {
+      generatedAt,
+      requestId,
+      composedBy: "gmc-cli",
+      upstreamRequests: [{
+        externalId: request.externalId,
+        kind: "detail",
+        requestId: detail?.meta?.requestId,
+        source: detail?.meta?.source,
+        entitlements: detail?.meta?.entitlements
+      }]
+    },
+    ...(warnings.length ? { warnings } : {})
+  };
+}
+
+export function composeCohortEvidencePayload(request, result, options = {}) {
+  const generatedAt = options.generatedAt ?? new Date().toISOString();
+  const requestId = options.requestId ?? createCliRequestId();
+  const games = Array.isArray(result.search?.data) ? result.search.data : [];
+  const searches = Array.isArray(result.searches) ? result.searches : [result.search];
+  const searchPageErrors = Array.isArray(result.searchPageErrors) ? result.searchPageErrors : [];
+  const analysisResults = Array.isArray(result.analysisResults) ? result.analysisResults : [];
+  const entries = analysisResults.map((entry) => buildCohortEvidenceGame(request, entry));
+  const included = entries.filter((entry) => !entry.skippedReason);
+  const skipped = entries
+    .filter((entry) => entry.skippedReason)
+    .map((entry) => ({
+      source: request.source,
+      externalId: entry.externalId,
+      appid: entry.appid,
+      title: entry.title,
+      reason: entry.skippedReason,
+      ...(entry.error ? { error: entry.error } : {})
+    }));
+  const sample = buildSampleMetadata(request, searches, games, searchPageErrors);
+  const warnings = uniqueStrings([
+    ...safeWarnings(result.search),
+    ...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)),
+    ...analysisResults.flatMap((entry) => cohortEvidenceErrorWarning(entry, request.workflow)),
+    `${request.workflow} is a CLI-composed evidence pack over bounded visible API data; treat it as sampled evidence, not causal proof or full-market measurement`
+  ]);
+
+  return {
+    data: {
+      kind: "evidence_pack",
+      source: request.source,
+      workflow: request.workflow,
+      evidenceType: request.evidenceType,
+      inputs: {
+        filters: request.query,
+        sections: request.sections,
+        ...(sample ? { sample: buildEvidencePackSample(sample, included.length) } : {
+          sample: buildReturnedPageSample(result.search?.pagination, included.length)
+        })
+      },
+      cohort: {
+        query: request.query,
+        returnedGames: games.length,
+        usableGames: included.length,
+        skippedGames: skipped.length,
+        totalMatches: result.search?.pagination?.total,
+        included: included.map((entry) => ({
+          source: request.source,
+          externalId: entry.externalId,
+          title: entry.title,
+          evidence: {
+            reviews: entry.reviews,
+            rating: entry.rating,
+            price: entry.price,
+            releaseDate: entry.releaseDate,
+            coverage: entry.coverage,
+            tags: entry.tags,
+            patternEvidence: entry.patternEvidence
+          }
+        })),
+        skipped
+      },
+      summary: withSummaryBasis(
+        buildCohortEvidenceSummary(request, included, result.search?.pagination),
+        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) } : {}),
+      games: included.map((entry) => ({
+        source: request.source,
+        externalId: entry.externalId,
+        appid: entry.appid,
+        title: entry.title,
+        reviews: entry.reviews,
+        rating: entry.rating,
+        price: entry.price,
+        releaseDate: entry.releaseDate,
+        coverage: entry.coverage,
+        tags: entry.tags,
+        patternEvidence: entry.patternEvidence
+      })),
+      skipped
+    },
+    meta: {
+      generatedAt,
+      requestId,
+      composedBy: "gmc-cli",
+      ...(sample ? { sample } : {}),
+      upstreamRequests: [
+        ...buildSearchUpstreamRequests(searches, searchPageErrors),
+        ...analysisResults
+          .filter((entry) => entry.analysis || entry.error)
+          .map((entry) => ({
+            externalId: entry.externalId,
+            kind: "analysis",
+            requestId: entry.analysis?.meta?.requestId,
+            source: entry.analysis?.meta?.source,
+            entitlements: entry.analysis?.meta?.entitlements,
+            ...(entry.error ? { error: entry.error } : {})
+          }))
+      ]
+    },
+    ...(result.search?.pagination ? { pagination: result.search.pagination } : {}),
+    ...(warnings.length ? { warnings } : {})
+  };
+}
+
+export function composeShowcaseFitPayload(request, result, options = {}) {
+  const generatedAt = options.generatedAt ?? new Date().toISOString();
+  const requestId = options.requestId ?? createCliRequestId();
+  const warnings = uniqueStrings([
+    ...safeWarnings(result.detail),
+    ...safeWarnings(result.showcases)
+  ]);
+
+  return {
+    data: {
+      kind: "evidence_pack",
+      source: request.source,
+      workflow: "showcaseFit",
+      inputs: {
+        externalIds: [request.externalId],
+        filters: result.showcaseQuery,
+        sample: buildReturnedPageSample(result.showcases?.pagination, asArray(result.showcases?.data).length)
+      },
+      externalId: request.externalId,
+      game: result.detail?.data,
+      showcaseQuery: result.showcaseQuery,
+      matchBasis: {
+        tags: result.tags,
+        status: result.showcaseQuery.status,
+        format: result.showcaseQuery.format,
+        country: result.showcaseQuery.country,
+        deadlineBefore: request.deadlineBefore
+      },
+      summary: withSummaryBasis(buildShowcaseFitSummary(request, result), "returned_page"),
+      matches: result.showcases?.data ?? [],
+      showcases: result.showcases?.data ?? [],
+      cohort: {
+        included: asArray(result.showcases?.data).map((showcase) => ({
+          source: "showcase_catalog",
+          externalId: asString(showcase?.id),
+          title: showcase?.name,
+          evidence: showcase
+        })),
+        skipped: []
+      }
+    },
+    meta: {
+      generatedAt,
+      requestId,
+      composedBy: "gmc-cli",
+      upstreamRequests: [
+        {
+          externalId: request.externalId,
+          kind: "detail",
+          requestId: result.detail?.meta?.requestId,
+          source: result.detail?.meta?.source,
+          entitlements: result.detail?.meta?.entitlements
+        },
+        {
+          kind: "showcases",
+          requestId: result.showcases?.meta?.requestId,
+          source: result.showcases?.meta?.source,
+          pagination: result.showcases?.pagination
+        }
+      ]
+    },
+    ...(warnings.length ? { warnings } : {})
+  };
+}
+
+async function fetchJson(url, { apiKey }) {
+  let response;
+  try {
+    response = await fetch(url, {
+      headers: buildRequestHeaders(apiKey)
+    });
+  } catch (error) {
+    writeJsonError({
+      code: "CLI_API_ERROR",
+      message: `Failed to reach GMC API at ${url.origin}`,
+      cause: error instanceof Error ? error.message : "Unknown network failure"
+    });
+    process.exit(EXIT_API);
+  }
+
+  const payload = await response.json().catch(() => null);
+
+  if (!response.ok) {
+    process.stdout.write(`${JSON.stringify(payload ?? {
+      error: buildHttpApiError(url, response)
+    }, null, 2)}\n`);
+    process.exit(EXIT_API);
+  }
+
+  if (payload == null) {
+    writeJsonError(buildNonJsonApiError(url, response));
+    process.exit(EXIT_API);
+  }
+
+  return payload;
+}
+
+function getPreferredShowcaseTags(game) {
+  const rawTags = [
+    ...getRankedTagNames(game),
+    ...(Array.isArray(game?.tags) ? game.tags : []),
+    ...(Array.isArray(game?.genres) ? game.genres : [])
+  ];
+  return uniqueStrings(rawTags.map((tag) => normalizeTagSlug(tag)).filter(Boolean)).slice(0, 6);
+}
+
+function buildResolveCandidate(request, game, index) {
+  const title = asString(game?.title ?? game?.name);
+  const appid = game?.appid;
+  const externalId = asString(game?.externalId ?? appid);
+  const normalizedQuery = normalizeResolveText(request.query);
+  const normalizedTitle = normalizeResolveText(title);
+  const queryTokens = tokenizeResolveText(request.query);
+  const titleTokens = tokenizeResolveText(title);
+  const tokenOverlap = calculateTokenOverlap(queryTokens, titleTokens);
+  const scoreInputs = {
+    titleExact: title === request.query,
+    normalizedTitleExact: normalizedTitle.length > 0 && normalizedTitle === normalizedQuery,
+    titleContainsQuery: normalizedQuery.length > 0 && normalizedTitle.includes(normalizedQuery),
+    queryContainsTitle: normalizedTitle.length > 0 && normalizedQuery.includes(normalizedTitle),
+    tokenOverlap,
+    reviewCount: typeof game?.reviews === "number" ? game.reviews : undefined,
+    rating: typeof game?.rating === "number" ? game.rating : undefined,
+    coverage: game?.coverage
+  };
+  const score = calculateResolveScore(scoreInputs, index);
+
+  return {
+    source: request.source,
+    externalId,
+    appid,
+    title,
+    developer: game?.developer,
+    releaseDate: game?.releaseDate,
+    reviews: game?.reviews,
+    rating: game?.rating,
+    price: game?.price,
+    tags: game?.tags,
+    tagRanks: game?.tagRanks,
+    genres: game?.genres,
+    categories: game?.categories,
+    facets: game?.facets,
+    coverage: game?.coverage,
+    score,
+    confidence: classifyResolveConfidence(score),
+    scoreInputs
+  };
+}
+
+function buildBenchmarkSummary(games, pagination, source, options = {}) {
+  return {
+    sampleSize: games.length,
+    totalMatches: pagination?.total,
+    reviews: numericSummary(games.map((game) => game?.reviews)),
+    rating: numericSummary(games.map((game) => game?.rating)),
+    price: numericSummary(games.map((game) => game?.price)),
+    releaseYears: countReleaseYears(games),
+    priceBuckets: countPriceBuckets(games),
+    topTags: topRankedTags(games),
+    topGenres: topValues(games.flatMap((game) => asArray(game?.genres))),
+    topPlayModes: topValues(games.flatMap((game) => asArray(game?.facets?.playModes))),
+    topFeatures: topValues(games.flatMap((game) => asArray(game?.facets?.features))),
+    coverage: countCoverage(games),
+    topGames: games
+      .slice()
+      .sort((a, b) => sortableNumber(b?.reviews) - sortableNumber(a?.reviews))
+      .slice(0, 5)
+      .map((game) => ({
+        source,
+        externalId: asString(game?.externalId ?? game?.appid),
+        appid: game?.appid,
+        title: game?.title ?? game?.name,
+        reviews: game?.reviews,
+        rating: game?.rating,
+        releaseDate: game?.releaseDate
+      })),
+    caveats: options.sampled
+      ? [
+          "Summary uses only the fetched sample rows, not every matching Steam title.",
+          "Use larger bounded samples or a future server-side aggregate endpoint before making broad cohort claims.",
+          "Visible review volume, rating, tags, price, and coverage are evidence inputs, not causal explanations."
+        ]
+      : [
+          "Summary uses only the returned page, not every matching Steam title.",
+          "Use pagination.nextOffset for additional pages before making broad cohort claims.",
+          "Visible review volume, rating, tags, price, and coverage are evidence inputs, not causal explanations."
+        ]
+  };
+}
+
+function getRankedTagNames(game) {
+  const ranked = asArray(game?.tagRanks)
+    .slice()
+    .sort((a, b) => sortableNumber(a?.rank) - sortableNumber(b?.rank))
+    .map((tag) => asString(tag?.name))
+    .filter(Boolean);
+  return ranked.length ? ranked : asArray(game?.tags);
+}
+
+function topRankedTags(games, limit = 10) {
+  const counts = new Map();
+  for (const game of games) {
+    const rankedTags = asArray(game?.tagRanks)
+      .map((tag, index) => {
+        const rank = numericValue(tag?.rank);
+        return {
+          value: asString(tag?.name),
+          rank: Number.isFinite(rank) ? rank : index + 1
+        };
+      })
+      .filter((tag) => tag.value);
+    const tags = rankedTags.length
+      ? rankedTags
+      : asArray(game?.tags).map((tag, index) => ({
+          value: asString(tag),
+          rank: index + 1
+        }));
+
+    const seen = new Set();
+    for (const tag of tags) {
+      if (seen.has(tag.value)) continue;
+      seen.add(tag.value);
+      const current = counts.get(tag.value) ?? {
+        value: tag.value,
+        count: 0,
+        rankTotal: 0,
+        minRank: tag.rank
+      };
+      current.count += 1;
+      current.rankTotal += tag.rank;
+      current.minRank = Math.min(current.minRank, tag.rank);
+      counts.set(tag.value, current);
+    }
+  }
+
+  return Array.from(counts.values())
+    .map((item) => ({
+      value: item.value,
+      count: item.count,
+      averageRank: roundNumber(item.rankTotal / item.count),
+      minRank: item.minRank
+    }))
+    .sort((a, b) => b.count - a.count || a.averageRank - b.averageRank || a.value.localeCompare(b.value))
+    .slice(0, limit);
+}
+
+function mergeSearchPages(searches, sampling) {
+  const data = searches.flatMap((search) => asArray(search?.data));
+  const sampledData = sampling?.mode === "sample-size"
+    ? data.slice(0, sampling.requestedSize)
+    : data;
+  const first = searches[0] ?? {};
+  const last = searches[searches.length - 1] ?? {};
+  return {
+    ...first,
+    data: sampledData,
+    pagination: {
+      ...(first.pagination ?? {}),
+      limit: first.pagination?.limit,
+      offset: first.pagination?.offset,
+      total: first.pagination?.total,
+      nextOffset: last.pagination?.nextOffset
+    },
+    warnings: uniqueStrings(searches.flatMap((search) => safeWarnings(search)))
+  };
+}
+
+function buildSampleMetadata(request, searches, games, pageErrors) {
+  if (!request.sampling) return undefined;
+  return {
+    mode: request.sampling.mode,
+    requestedSize: request.sampling.requestedSize,
+    requestedPages: request.sampling.requestedPages,
+    pageLimit: request.sampling.pageLimit,
+    fetchedPages: searches.length,
+    fetchedGames: games.length,
+    skippedPages: pageErrors.length,
+    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) {
+  return {
+    mode: normalizeEvidencePackSampleMode(sample.mode),
+    requestedRows: sample.requestedSize,
+    requestedPages: sample.requestedPages,
+    returnedRows,
+    fetchedPages: sample.fetchedPages,
+    skippedPages: sample.skippedPages,
+    totalMatches: sample.totalMatches
+  };
+}
+
+function buildReturnedPageSample(pagination, returnedRows) {
+  return {
+    mode: "returned_page",
+    requestedRows: pagination?.limit,
+    returnedRows,
+    totalMatches: pagination?.total
+  };
+}
+
+function normalizeEvidencePackSampleMode(mode) {
+  if (mode === "sample-size") return "sample_size";
+  if (mode === "sample-pages") return "sample_pages";
+  return mode;
+}
+
+function withSummaryBasis(summary, basis) {
+  return {
+    basis,
+    ...summary
+  };
+}
+
+function buildSearchUpstreamRequests(searches, pageErrors = []) {
+  return [
+    ...searches.map((search, index) => ({
+      kind: "search",
+      page: index + 1,
+      requestId: search?.meta?.requestId,
+      source: search?.meta?.source,
+      entitlements: search?.meta?.entitlements,
+      pagination: search?.pagination
+    })),
+    ...pageErrors.map((entry, index) => ({
+      kind: "search",
+      page: searches.length + index + 1,
+      offset: entry.offset,
+      error: entry.error
+    }))
+  ];
+}
+
+function buildReviewPatternGame(request, entry) {
+  const game = entry.game ?? {};
+  const externalId = asString(entry.externalId ?? game?.externalId ?? game?.appid);
+  const topics = extractReviewTopics(entry.topics)
+    .slice(0, request.maxTopicsPerGame)
+    .map(normalizeReviewTopic)
+    .filter((topic) => matchesReviewPatternFilters(topic, request));
+  const skippedReason = entry.skippedReason ?? (topics.length === 0 ? "no_matching_review_topics" : undefined);
+
+  return {
+    source: request.source,
+    externalId,
+    appid: game?.appid,
+    title: game?.title ?? game?.name,
+    reviews: game?.reviews,
+    rating: game?.rating,
+    releaseDate: game?.releaseDate,
+    coverage: game?.coverage,
+    topics,
+    skippedReason,
+    error: entry.error
+  };
+}
+
+function buildReviewPatterns(games) {
+  const totalGames = games.length;
+  const totalReviewVolume = games.reduce((sum, game) => sum + Math.max(0, numericValue(game.reviews) || 0), 0);
+  const patternMap = new Map();
+
+  for (const game of games) {
+    const seenInGame = new Set();
+    for (const topic of game.topics) {
+      const key = normalizeReviewPatternKey(topic.topic);
+      if (!key || seenInGame.has(key)) continue;
+      seenInGame.add(key);
+
+      const existing = patternMap.get(key) ?? {
+        key,
+        topic: topic.topic,
+        appearsInGames: 0,
+        matchedReviewVolume: 0,
+        sentiments: {},
+        prevalenceValues: [],
+        exampleGames: []
+      };
+      existing.appearsInGames += 1;
+      existing.matchedReviewVolume += Math.max(0, numericValue(game.reviews) || 0);
+      if (topic.sentiment) {
+        existing.sentiments[topic.sentiment] = (existing.sentiments[topic.sentiment] ?? 0) + 1;
+      }
+      const prevalence = numericValue(topic.prevalence);
+      if (Number.isFinite(prevalence)) existing.prevalenceValues.push(prevalence);
+      if (existing.exampleGames.length < 5) {
+        existing.exampleGames.push({
+          source: game.source,
+          externalId: game.externalId,
+          appid: game.appid,
+          title: game.title,
+          reviews: game.reviews,
+          rating: game.rating,
+          topic: topic.topic,
+          clusterId: topic.clusterId,
+          displayGroup: topic.displayGroup,
+          sentiment: topic.sentiment,
+          summary: topic.summary,
+          prevalence: topic.prevalence,
+          impactScore: topic.impactScore,
+          representativeQuotes: topic.representativeQuotes
+        });
+      }
+      patternMap.set(key, existing);
+    }
+  }
+
+  return Array.from(patternMap.values())
+    .map((pattern) => ({
+      key: pattern.key,
+      topic: pattern.topic,
+      appearsInGames: pattern.appearsInGames,
+      shareOfGames: totalGames > 0 ? roundNumber(pattern.appearsInGames / totalGames) : 0,
+      reviewVolumeWeightedShare: totalReviewVolume > 0
+        ? roundNumber(pattern.matchedReviewVolume / totalReviewVolume)
+        : undefined,
+      matchedReviewVolume: pattern.matchedReviewVolume,
+      sentiments: sortCountObject(pattern.sentiments),
+      averageTopicPrevalence: pattern.prevalenceValues.length > 0
+        ? roundNumber(pattern.prevalenceValues.reduce((sum, value) => sum + value, 0) / pattern.prevalenceValues.length)
+        : undefined,
+      exampleGames: pattern.exampleGames
+    }))
+    .sort((a, b) => (
+      b.appearsInGames - a.appearsInGames
+      || sortableNumber(b.matchedReviewVolume) - sortableNumber(a.matchedReviewVolume)
+      || a.key.localeCompare(b.key)
+    ));
+}
+
+function buildReviewPatternsSummary(request, usableGames, skipped, pagination) {
+  const patterns = buildReviewPatterns(usableGames);
+  return {
+    sampleSize: usableGames.length,
+    totalMatches: pagination?.total,
+    skippedGames: skipped.length,
+    topicEvidenceItems: usableGames.reduce((sum, game) => sum + game.topics.length, 0),
+    patternCount: patterns.length,
+    topSignals: patterns.slice(0, 10).map((pattern) => ({
+      type: "reviewTopic",
+      value: pattern.topic,
+      count: pattern.appearsInGames,
+      evidenceRefs: pattern.exampleGames.map((game) => `${game.source}:${game.externalId}`)
+    })),
+    caveats: [
+      "Review patterns are repeated visible topics across the bounded cohort, not full-market clusters.",
+      "Representative quotes are evidence; locked severity or fixability fields must remain unavailable when locked.",
+      ...(usableGames.length < request.minGames
+        ? [`Usable game count ${usableGames.length} is below --min-games ${request.minGames}.`]
+        : [])
+    ]
+  };
+}
+
+function extractReviewTopics(payload) {
+  if (Array.isArray(payload?.data)) return payload.data;
+  if (Array.isArray(payload?.data?.topics)) return payload.data.topics;
+  if (Array.isArray(payload?.data?.sections?.reviews?.topics)) return payload.data.sections.reviews.topics;
+  return [];
+}
+
+function normalizeReviewTopic(topic) {
+  const displayGroup = asString(topic?.displayGroup);
+  const quote = asString(topic?.quote);
+  const representativeQuotes = asArray(topic?.representativeQuotes);
+  if (representativeQuotes.length === 0 && quote) {
+    representativeQuotes.push({ text: quote });
+  }
+  const clusterLabel = topic?.clusterId == null
+    ? undefined
+    : `${displayGroup ? `${displayGroup} ` : ""}cluster ${topic.clusterId}`;
+
+  return {
+    topic: asString(topic?.topic ?? topic?.label ?? clusterLabel ?? displayGroup),
+    clusterId: topic?.clusterId,
+    displayGroup: displayGroup || undefined,
+    sentiment: topic?.sentiment ?? sentimentFromReviewDisplayGroup(displayGroup),
+    summary: topic?.summary ?? (quote || undefined),
+    prevalence: topic?.prevalence,
+    impactScore: topic?.impactScore,
+    severity: topic?.severity,
+    fixability: topic?.fixability,
+    representativeQuotes: representativeQuotes.slice(0, 2)
+  };
+}
+
+function matchesReviewPatternFilters(topic, request) {
+  if (!topic.topic) return false;
+  if (request.sentiment && topic.sentiment !== request.sentiment) return false;
+  if (request.topic) {
+    const needle = asString(request.topic).trim().toLowerCase();
+    const haystack = `${topic.topic} ${topic.summary ?? ""}`.toLowerCase();
+    if (needle && !haystack.includes(needle)) return false;
+  }
+  return true;
+}
+
+function normalizeReviewPatternKey(value) {
+  return asString(value)
+    .trim()
+    .toLowerCase()
+    .replace(/&/g, " and ")
+    .replace(/[^a-z0-9]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function sentimentFromReviewDisplayGroup(value) {
+  if (value === "love") return "positive";
+  if (value === "actionable") return "negative";
+  if (value === "mixed") return "mixed";
+  return undefined;
+}
+
+function reviewPatternErrorWarning(entry) {
+  if (!entry?.error) return [];
+  const code = entry.error.code ?? "CLI_API_ERROR";
+  const suffix = entry.externalId ? ` for ${entry.externalId}` : "";
+  return [`review topics request failed${suffix}: ${code}`];
+}
+
+function buildReviewPatternSegments(games, segment) {
+  const groups = new Map();
+  for (const game of games) {
+    const key = classifyGameSegment(game, segment);
+    const current = groups.get(key) ?? [];
+    current.push(game);
+    groups.set(key, current);
+  }
+
+  return Array.from(groups.entries())
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([segmentValue, segmentGames]) => ({
+      segment,
+      value: segmentValue,
+      gameCount: segmentGames.length,
+      patterns: buildReviewPatterns(segmentGames).slice(0, 10)
+    }));
+}
+
+function buildCohortEvidenceGame(request, entry) {
+  const game = entry.game ?? {};
+  const externalId = asString(entry.externalId ?? game?.externalId ?? game?.appid);
+  const sections = getAnalysisSections(entry.analysis);
+  const patternEvidence = extractCohortPatternEvidence(request.evidenceType, game, sections);
+  const skippedReason = entry.skippedReason
+    ?? (request.analysisQuery && patternEvidence.length === 0 ? "no_matching_analysis_evidence" : undefined);
+
+  return {
+    source: request.source,
+    externalId,
+    appid: game?.appid,
+    title: game?.title ?? game?.name,
+    reviews: game?.reviews,
+    rating: game?.rating,
+    price: game?.price,
+    discount: game?.discount,
+    releaseDate: game?.releaseDate,
+    coverage: game?.coverage,
+    tags: getRankedTagNames(game).slice(0, 8),
+    genres: game?.genres,
+    analysis: entry.analysis,
+    sections,
+    patternEvidence,
+    skippedReason,
+    error: entry.error
+  };
+}
+
+function buildCohortEvidenceSummary(request, entries, pagination) {
+  return {
+    sampleSize: entries.length,
+    totalMatches: pagination?.total,
+    reviews: numericSummary(entries.map((entry) => entry.reviews)),
+    rating: numericSummary(entries.map((entry) => entry.rating)),
+    price: numericSummary(entries.map((entry) => entry.price)),
+    releaseYears: countReleaseYears(entries),
+    priceBuckets: countPriceBuckets(entries),
+    topTags: topRankedTags(entries),
+    topGenres: topValues(entries.flatMap((entry) => asArray(entry.genres))),
+    coverage: countCoverage(entries),
+    evidenceItems: entries.reduce((sum, entry) => sum + entry.patternEvidence.length, 0),
+    caveats: [
+      "This summary uses bounded visible API rows and optional per-game analysis sections.",
+      "Observed patterns are evidence inputs, not recommendations, causal claims, or full-market estimates.",
+      "Locked, missing, partial, and failed downstream analysis requests must remain visible when interpreting the output."
+    ]
+  };
+}
+
+function buildShowcaseFitSummary(request, result) {
+  const showcases = asArray(result.showcases?.data);
+  const tags = asArray(result.tags);
+  return {
+    sampleSize: showcases.length,
+    totalMatches: result.showcases?.pagination?.total,
+    target: {
+      source: request.source,
+      externalId: request.externalId,
+      title: result.detail?.data?.title
+    },
+    topSignals: [
+      ...tags.slice(0, 8).map((tag) => ({
+        type: "gameTag",
+        value: tag,
+        count: showcases.filter((showcase) => asArray(showcase?.tags).includes(tag)).length || undefined
+      })),
+      ...(request.deadlineBefore
+        ? [{
+            type: "deadlineBefore",
+            value: request.deadlineBefore,
+            count: showcases.length
+          }]
+        : [])
+    ],
+    caveats: [
+      "Showcase fit is evidence for submission planning, not a final recommendation or guaranteed eligibility.",
+      "Unknown demo, Steam page, fee, or format fields require manual follow-up.",
+      "Current matching is based on visible catalog filters and game tags unless a future scoring method is documented."
+    ]
+  };
+}
+
+function buildCohortEvidencePatterns(request, entries) {
+  if (request.evidenceType === "trends") {
+    return [
+      ...topRankedTags(entries).map((item) => ({ type: "tag", ...item })),
+      ...topValues(entries.flatMap((entry) => asArray(entry.genres))).map((item) => ({ type: "genre", ...item }))
+    ];
+  }
+
+  if (request.evidenceType === "pricing") {
+    return Object.entries(countPriceBuckets(entries)).map(([value, count]) => ({
+      type: "priceBucket",
+      value,
+      count
+    }));
+  }
+
+  const patternMap = new Map();
+  for (const entry of entries) {
+    const seen = new Set();
+    for (const evidence of entry.patternEvidence) {
+      const key = `${evidence.type}:${normalizeReviewPatternKey(evidence.value)}`;
+      if (!evidence.value || seen.has(key)) continue;
+      seen.add(key);
+      const current = patternMap.get(key) ?? {
+        type: evidence.type,
+        value: evidence.value,
+        count: 0,
+        reviewVolume: 0,
+        exampleGames: []
+      };
+      current.count += 1;
+      current.reviewVolume += Math.max(0, numericValue(entry.reviews) || 0);
+      if (current.exampleGames.length < 5) {
+        current.exampleGames.push({
+          source: entry.source,
+          externalId: entry.externalId,
+          appid: entry.appid,
+          title: entry.title,
+          reviews: entry.reviews,
+          rating: entry.rating,
+          evidence: evidence.raw
+        });
+      }
+      patternMap.set(key, current);
+    }
+  }
+
+  return Array.from(patternMap.values())
+    .map((pattern) => ({
+      ...pattern,
+      shareOfGames: entries.length > 0 ? roundNumber(pattern.count / entries.length) : 0
+    }))
+    .sort((a, b) => b.count - a.count || b.reviewVolume - a.reviewVolume || a.value.localeCompare(b.value))
+    .slice(0, 30);
+}
+
+function buildPricingSegments(entries) {
+  const buckets = new Map();
+  for (const entry of entries) {
+    const bucket = classifyPriceBucket(entry.price);
+    const current = buckets.get(bucket) ?? [];
+    current.push(entry);
+    buckets.set(bucket, current);
+  }
+  return Array.from(buckets.entries())
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([value, games]) => ({
+      segment: "price",
+      value,
+      gameCount: games.length,
+      reviews: numericSummary(games.map((game) => game.reviews)),
+      rating: numericSummary(games.map((game) => game.rating)),
+      topTags: topRankedTags(games, 5)
+    }));
+}
+
+function buildTrendSummary(entries, pagination, source) {
+  return buildBenchmarkSummary(entries, pagination, source, { sampled: true });
+}
+
+function extractCohortPatternEvidence(evidenceType, game, sections) {
+  if (evidenceType === "trends" || evidenceType === "pricing") return [];
+  if (evidenceType === "brief") {
+    return [
+      ...extractCohortPatternEvidence("marketing", game, sections),
+      ...extractCohortPatternEvidence("creators", game, sections),
+      ...extractCohortPatternEvidence("showcases", game, sections)
+    ];
+  }
+  if (evidenceType === "marketing" || evidenceType === "marketingTiming") {
+    const marketing = sections.marketing ?? {};
+    const media = sections.media ?? {};
+    const creators = sections.creators ?? {};
+    const events = asArray(marketing.events).map((event) => ({
+      type: evidenceType === "marketingTiming" ? "marketingEventTiming" : "marketingEvent",
+      value: evidenceType === "marketingTiming"
+        ? classifyRelativeTiming(game?.releaseDate, event?.date)
+        : asString(event?.category ?? event?.event),
+      raw: pickCompactEvidence(event, ["date", "event", "category", "description", "marketScope", "previewUrl"])
+    }));
+    if (evidenceType === "marketingTiming") return events.filter((item) => item.value);
+    return [
+      ...events,
+      ...asArray(media.articles).map((article) => ({
+        type: "mediaAngle",
+        value: asString(article?.articleType ?? article?.outlet),
+        raw: pickCompactEvidence(article, ["title", "outlet", "articleType", "date", "summary", "previewUrl"])
+      })),
+      ...asArray(creators.creators ?? creators).map((creator) => ({
+        type: "creatorPlatform",
+        value: asString(creator?.platform),
+        raw: pickCompactEvidence(creator, ["platform", "channelTitle", "subscriberCount", "totalViewsOnGame"])
+      }))
+    ].filter((item) => item.value);
+  }
+  if (evidenceType === "creators") {
+    const creators = sections.creators ?? {};
+    return asArray(creators.creators ?? creators).flatMap((creator) => [
+      {
+        type: "creatorPlatform",
+        value: asString(creator?.platform),
+        raw: pickCompactEvidence(creator, ["platform", "channelTitle", "subscriberCount", "totalViewsOnGame", "totalVideosOnGame", "firstCoverageDate"])
+      },
+      {
+        type: "creatorScale",
+        value: classifyCreatorScale(creator?.subscriberCount, creator?.totalViewsOnGame),
+        raw: pickCompactEvidence(creator, ["platform", "channelTitle", "subscriberCount", "totalViewsOnGame"])
+      }
+    ]).filter((item) => item.value);
+  }
+  if (evidenceType === "showcases") {
+    const showcases = sections.showcases ?? [];
+    return asArray(showcases).flatMap((showcase) => [
+      {
+        type: "showcaseEvent",
+        value: asString(showcase?.eventName),
+        raw: pickCompactEvidence(showcase, ["eventName", "eventDate", "eventType", "marketScope", "description", "previewUrl"])
+      },
+      {
+        type: "showcaseType",
+        value: asString(showcase?.eventType),
+        raw: pickCompactEvidence(showcase, ["eventName", "eventDate", "eventType", "marketScope"])
+      }
+    ]).filter((item) => item.value);
+  }
+  return [];
+}
+
+function getAnalysisSections(payload) {
+  return payload?.data?.sections && typeof payload.data.sections === "object"
+    ? payload.data.sections
+    : {};
+}
+
+function cohortEvidenceErrorWarning(entry, workflow) {
+  if (!entry?.error) return [];
+  const code = entry.error.code ?? "CLI_API_ERROR";
+  const suffix = entry.externalId ? ` for ${entry.externalId}` : "";
+  return [`${workflow} analysis request failed${suffix}: ${code}`];
+}
+
+function classifyGameSegment(game, segment) {
+  if (segment === "coverage") return asString(game.coverage) || "unknown";
+  if (segment === "releaseYear") {
+    const year = typeof game.releaseDate === "string" ? game.releaseDate.slice(0, 4) : "";
+    return /^\d{4}$/.test(year) ? year : "unknown";
+  }
+  return classifyPriceBucket(game.price);
+}
+
+function classifyPriceBucket(priceValue) {
+  const price = numericValue(priceValue);
+  if (!Number.isFinite(price)) return "unknown";
+  if (price <= 0) return "free";
+  if (price < 10) return "under10";
+  if (price < 20) return "under20";
+  if (price < 40) return "under40";
+  return "fortyPlus";
+}
+
+function classifyRelativeTiming(releaseDate, eventDate) {
+  if (!isIsoDate(releaseDate) || !isIsoDate(eventDate)) return "unknown";
+  const release = Date.parse(`${releaseDate}T00:00:00.000Z`);
+  const event = Date.parse(`${eventDate}T00:00:00.000Z`);
+  const days = Math.round((event - release) / 86400000);
+  if (days < -180) return "prelaunch_6m_plus";
+  if (days < -90) return "prelaunch_3_6m";
+  if (days < -30) return "prelaunch_1_3m";
+  if (days < 0) return "prelaunch_0_30d";
+  if (days <= 30) return "launch_window_0_30d";
+  if (days <= 90) return "postlaunch_1_3m";
+  if (days <= 180) return "postlaunch_3_6m";
+  return "postlaunch_6m_plus";
+}
+
+function isIsoDate(value) {
+  return /^\d{4}-\d{2}-\d{2}$/.test(asString(value));
+}
+
+function classifyCreatorScale(subscriberCount, totalViewsOnGame) {
+  const subscribers = numericValue(subscriberCount);
+  const views = numericValue(totalViewsOnGame);
+  const size = Number.isFinite(subscribers) ? subscribers : views;
+  if (!Number.isFinite(size)) return "unknown";
+  if (size >= 1000000) return "mega";
+  if (size >= 100000) return "large";
+  if (size >= 10000) return "mid";
+  return "small";
+}
+
+function pickCompactEvidence(value, keys) {
+  if (!value || typeof value !== "object") return value;
+  const picked = {};
+  for (const key of keys) {
+    if (value[key] != null && value[key] !== "") picked[key] = value[key];
+  }
+  return picked;
+}
+
+async function fetchJsonResult(url, { apiKey }) {
+  let response;
+  try {
+    response = await fetch(url, {
+      headers: buildRequestHeaders(apiKey)
+    });
+  } catch (error) {
+    return {
+      ok: false,
+      error: {
+        code: "CLI_API_ERROR",
+        message: `Failed to reach GMC API at ${url.origin}`,
+        cause: error instanceof Error ? error.message : "Unknown network failure"
+      }
+    };
+  }
+
+  const payload = await response.json().catch(() => null);
+  if (!response.ok) {
+    return {
+      ok: false,
+      payload,
+      error: payload?.error ?? buildHttpApiError(url, response)
+    };
+  }
+
+  if (payload == null) {
+    return {
+      ok: false,
+      error: buildNonJsonApiError(url, response)
+    };
+  }
+
+  return {
+    ok: true,
+    payload
+  };
+}
+
+export function buildHttpApiError(url, response) {
+  return {
+    code: "CLI_API_ERROR",
+    message: `API request failed with HTTP ${response.status}`,
+    status: response.status,
+    statusText: response.statusText || undefined,
+    path: `${url.pathname}${url.search}`,
+    contentType: response.headers.get("content-type") || undefined
+  };
+}
+
+export function buildNonJsonApiError(url, response) {
+  return {
+    code: "CLI_API_ERROR",
+    message: `GMC API returned a non-JSON response from ${url.origin}`,
+    status: response.status,
+    statusText: response.statusText || undefined,
+    path: `${url.pathname}${url.search}`,
+    contentType: response.headers.get("content-type") || undefined
+  };
+}
+
+function numericSummary(values) {
+  const numbers = values
+    .map(numericValue)
+    .filter((value) => Number.isFinite(value))
+    .sort((a, b) => a - b);
+  if (numbers.length === 0) {
+    return {
+      count: 0
+    };
+  }
+
+  return {
+    count: numbers.length,
+    min: numbers[0],
+    median: median(numbers),
+    max: numbers[numbers.length - 1],
+    average: roundNumber(numbers.reduce((sum, value) => sum + value, 0) / numbers.length)
+  };
+}
+
+function median(sortedNumbers) {
+  const middle = Math.floor(sortedNumbers.length / 2);
+  if (sortedNumbers.length % 2 === 1) return sortedNumbers[middle];
+  return roundNumber((sortedNumbers[middle - 1] + sortedNumbers[middle]) / 2);
+}
+
+function countReleaseYears(games) {
+  const counts = {};
+  for (const game of games) {
+    const year = typeof game?.releaseDate === "string" ? game.releaseDate.slice(0, 4) : undefined;
+    const key = /^\d{4}$/.test(year ?? "") ? year : "unknown";
+    counts[key] = (counts[key] ?? 0) + 1;
+  }
+  return sortCountObject(counts);
+}
+
+function countPriceBuckets(games) {
+  const counts = {
+    free: 0,
+    under10: 0,
+    under20: 0,
+    under40: 0,
+    fortyPlus: 0,
+    unknown: 0
+  };
+  for (const game of games) {
+    const price = numericValue(game?.price);
+    if (!Number.isFinite(price)) counts.unknown += 1;
+    else if (price <= 0) counts.free += 1;
+    else if (price < 10) counts.under10 += 1;
+    else if (price < 20) counts.under20 += 1;
+    else if (price < 40) counts.under40 += 1;
+    else counts.fortyPlus += 1;
+  }
+  return counts;
+}
+
+function countCoverage(games) {
+  const counts = {
+    basic: 0,
+    partial: 0,
+    full: 0,
+    unknown: 0
+  };
+  for (const game of games) {
+    const coverage = game?.coverage;
+    if (coverage === "basic" || coverage === "partial" || coverage === "full") counts[coverage] += 1;
+    else counts.unknown += 1;
+  }
+  return counts;
+}
+
+function topValues(values, limit = 10) {
+  const counts = {};
+  for (const rawValue of values) {
+    const value = asString(rawValue).trim();
+    if (!value) continue;
+    counts[value] = (counts[value] ?? 0) + 1;
+  }
+  return Object.entries(counts)
+    .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+    .slice(0, limit)
+    .map(([value, count]) => ({ value, count }));
+}
+
+function sortCountObject(counts) {
+  return Object.fromEntries(Object.entries(counts).sort(([a], [b]) => a.localeCompare(b)));
+}
+
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function numericValue(value) {
+  const number = typeof value === "number" ? value : Number(value);
+  return Number.isFinite(number) ? number : Number.NaN;
+}
+
+function sortableNumber(value) {
+  const number = numericValue(value);
+  return Number.isFinite(number) ? number : Number.NEGATIVE_INFINITY;
+}
+
+function roundNumber(value) {
+  return Math.round(value * 100) / 100;
+}
+
+function summarizeResolution(candidates) {
+  if (candidates.length === 0) {
+    return {
+      status: "no_candidates",
+      reason: "No candidates were returned by the game search API."
+    };
+  }
+
+  const exactCandidates = candidates.filter((candidate) => candidate.scoreInputs.normalizedTitleExact);
+  if (exactCandidates.length === 1) {
+    return {
+      status: "single_confident_candidate",
+      recommendedExternalId: exactCandidates[0].externalId,
+      reason: "One candidate exactly matches the normalized query."
+    };
+  }
+
+  const [first, second] = candidates;
+  if (first && second && first.score >= 80 && first.score - second.score >= 20) {
+    return {
+      status: "single_likely_candidate",
+      recommendedExternalId: first.externalId,
+      reason: "The top candidate is clearly separated from the next candidate."
+    };
+  }
+
+  return {
+    status: "ambiguous",
+    reason: "Multiple candidates may match. Ask the user to choose an externalId before detail, compare, or fit commands."
+  };
+}
+
+function calculateResolveScore(inputs, index) {
+  let score = 0;
+  if (inputs.normalizedTitleExact) score += 70;
+  else if (inputs.titleContainsQuery || inputs.queryContainsTitle) score += 35;
+  score += Math.round(inputs.tokenOverlap * 25);
+  if (typeof inputs.reviewCount === "number") score += Math.min(10, Math.floor(Math.log10(Math.max(1, inputs.reviewCount))));
+  if (typeof inputs.rating === "number" && inputs.rating >= 80) score += 5;
+  if (inputs.coverage === "full") score += 5;
+  else if (inputs.coverage === "partial") score += 3;
+  score -= Math.min(index, 10);
+  return Math.max(0, Math.min(100, score));
+}
+
+function classifyResolveConfidence(score) {
+  if (score >= 90) return "exact";
+  if (score >= 75) return "strong";
+  if (score >= 45) return "possible";
+  return "weak";
+}
+
+function calculateTokenOverlap(queryTokens, titleTokens) {
+  if (queryTokens.length === 0 || titleTokens.length === 0) return 0;
+  const titleSet = new Set(titleTokens);
+  const matched = queryTokens.filter((token) => titleSet.has(token)).length;
+  return matched / queryTokens.length;
+}
+
+function tokenizeResolveText(value) {
+  return normalizeResolveText(value).split(" ").filter(Boolean);
+}
+
+function normalizeResolveText(value) {
+  return asString(value)
+    .trim()
+    .toLowerCase()
+    .replace(/&/g, " and ")
+    .replace(/[^a-z0-9]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function asString(value) {
+  return value == null ? "" : String(value);
+}
+
+function normalizeTagSlug(value) {
+  return String(value)
+    .trim()
+    .toLowerCase()
+    .replace(/&/g, "and")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+function safeWarnings(payload) {
+  return Array.isArray(payload?.warnings) ? payload.warnings : [];
+}
+
+function uniqueStrings(values) {
+  return Array.from(new Set(values.filter((value) => typeof value === "string" && value.length > 0)));
+}
+
+function createCliRequestId() {
+  const id = globalThis.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random()}`;
+  return `cli_${id.replaceAll("-", "")}`;
+}