@witchpot/gmc 0.1.7 → 0.1.9

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 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
+  the first price-band field test: camelCase-query to kebab-case-flag
+  mapping note, zero-review rating artifact pitfall, discounted snapshot
+  price pitfall, price-question routing to explicit-bucket aggregates, and
+  the evidence-pack quota location exception.
+
 ## 0.1.7 - 2026-06-12
 
 - Bundled the `gmc-analysis` Agent Skill (v0.1.0): analysis recipes, pivot

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.7",
+  "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/CHANGELOG.md

@@ -1,5 +1,20 @@
 # gmc-analysis skill changelog
 
+## 0.2.0 - 2026-06-12
+
+- Folded in the five learnings from the first field test (2025 city
+  builders, price-band vs rating/review analysis; 7/7 rubric pass):
+  - setup: documented the camelCase-query -> kebab-case-flag mapping and
+    that per-command `--help` is currently generic;
+  - new pitfall P5: zero-review games aggregate as rating 0 — pair rating
+    metrics with `--reviews-min`, derive per-bucket hit rates from counts;
+  - new pitfall P6: snapshot prices include active discounts — check the
+    `discount` field before price-band conclusions;
+  - recipe R4: price/distribution questions route to aggregate with
+    explicit buckets first; `cohort pricing` is page-bounded texture only;
+  - quota: composed evidence packs carry quota under
+    `meta.upstreamRequests[].entitlements`, not at the top level.
+
 ## 0.1.0 - 2026-06-12
 
 - Initial release, seeded from the 2026-06-12 field test (roguelike cohort

package/skill/gmc-analysis/SKILL.md

@@ -7,7 +7,7 @@ description: >-
   about Steam games, reviews, creators, showcases, or campaigns that gmc can
   answer.
 metadata:
-  version: 0.1.0
+  version: 0.2.0
 ---
 
 # GMC Analysis
@@ -26,8 +26,11 @@ gmc auth status --json        # anonymous => redacted previews + tiny quota
 gmc schema --json             # the authoritative command/endpoint reference
 ```
 
-Never guess flags: `gmc schema --json` and `gmc <command> --help` are the
-source of truth for commands and parameters. Always pass `--json`.
+Never guess flags: `gmc schema --json` is the source of truth for commands
+and parameters. Endpoint query params are camelCase and the matching CLI
+flag is the kebab-case equivalent (`priceMin` -> `--price-min`,
+`reviewsGt` -> `--reviews-gt`). Per-command `--help` currently prints one
+generic usage list, so trust the schema. Always pass `--json`.
 
 ## Core workflow for cohort questions
 
@@ -50,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

@@ -42,9 +42,33 @@ the quota is tiny, which can read as "the API has no data".
 **Rule**: run `gmc auth status --json` first; if `authMode` is `anonymous`,
 say so in your answer and scope expectations to public preview data.
 
-## P5. Don't paginate by brute force
+## P5. Zero-review games carry rating 0 in aggregates (2026-06)
+
+Unconditional `avg_rating` / `median_rating` in low-traction segments (cheap
+or free price buckets) is crushed by zero-review games aggregating as
+rating 0 (observed: a free bucket with avg_rating 11.1). This misreads as
+"cheap games are hated" when it actually means "most cheap games have no
+reviews".
+
+**Pivot**: pair rating metrics with `--reviews-min` (e.g. 10). For "share of
+well-rated games per bucket", run `--metric count` twice over the same
+bucket spec — once unconditional, once with `--reviews-min 10
+--rating-min 80` — and divide.
+
+## P6. Snapshot prices include active discounts (2026-06)
+
+`price` is the current store price, not the launch/list price; a discounted
+title lands in a lower price bucket (observed: a $34.99 list price counted
+as $23.44 at -33%). Game rows carry a `discount` field.
+
+**Rule**: when price-band conclusions matter, check `discount` on the
+exemplar rows and caveat bucket assignments, especially during sale seasons.
+
+## P7. Don't paginate by brute force
 
 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

@@ -9,7 +9,10 @@ indicative — the response metadata is the source of truth.
 
 1. **Read before you spend.** Every bearer response carries
    `meta.entitlements.quota` = `{ used, limit }`. Check it at the start of a
-   session and after each fan-out.
+   session and after each fan-out. Exception: CLI-composed evidence packs
+   (`cohort ...`, `reviews patterns`, `games benchmark`, ...) expose quota
+   per upstream call instead — read the last entry of
+   `meta.upstreamRequests[].entitlements.quota`.
 2. **Estimate fan-out cost first.** A cohort sweep costs roughly
    `search pages + (1 per game per section call)`. A 114-game cohort with one
    analysis call each ~= 120 requests. Compare against remaining quota and
@@ -22,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
@@ -80,6 +82,19 @@ gmc games aggregate --source steam --metric count --group-by coverage <filters>
 `data.basis = server_aggregate` means market-wide for the filter set (within
 GMC source coverage) — unlike evidence packs, these are not page-bounded.
 
+**Price/distribution questions belong here, not in `cohort pricing`.** Run
+the aggregate with explicit buckets first (e.g.
+`--bucket price:0,5,10,15,20,25,30,40,60`); `gmc cohort pricing` is
+returned-page (top ~20) texture, useful only as a supplement and must be
+labeled as page-bounded evidence.
+
+Per-bucket "hit rate" pattern (one request per condition): pair the same
+bucket spec with shared filters — `--reviews-min 500 --metric count` gives
+reach per price band; `--reviews-min 10 --rating-min 80 --metric count`
+gives the well-rated share. Divide by the unconditional bucket counts.
+Never read unconditional rating aggregates in low-traction buckets
+(pitfall P5).
+
 ## Output contract for every analysis
 
 Always include in your final answer: the cohort definition and size, how many

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.7";
+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."
       ]
     }
   };