@witchpot/gmc 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -2,7 +2,35 @@
 
 All notable changes to the Game Market Copilot CLI will be recorded here.
 
-## Unreleased
+## 0.5.0 - 2026-07-13
+
+- gmc-analysis skill v0.5.0 (NAK-190): new "Saved Game Lists" guidance in
+  SKILL.md and recipe R5 (reusable cohorts via `gmc lists ...` / the MCP
+  Game List tools / `game_list_id` and `--list <id>` inputs), plus a skill
+  changelog entry retroactively documenting the chart-card guidance that
+  shipped unversioned in CLI 0.4.0-era updates (new chart types, capsule
+  rows, export geometry, label placement, embedded brand typography).
+- New skill content-hash manifest guard: `npm run skill:manifest`
+  regenerates `skill/gmc-analysis.manifest.json`;
+  `src/skill-manifest.test.js` (runs in `npm test` / repo `verify`) and
+  `release:check` both fail when skill content changes without a version
+  bump and manifest regeneration, so the bundled skill and the public
+  gmc-agent-skills distribution repo can no longer drift silently.
+
+## 0.4.0 - 2026-07-09
+
+- gmc-analysis skill v0.4.0: new `references/validity.md` with the
+  statistical-validity checklist and claim-safety rules (NAK-82), and new
+  pitfall P9 documenting the single-assignment vs multi-assignment tag
+  counting bases (NAK-81). Both ship in `gmc skill install` and the
+  `gmc skill print --format agents-md` self-contained edition.
+- Bundled chart-card generation into the gmc-analysis skill (v0.3.0,
+  NAK-89): new `references/charts.md` with attribution rules (fixed
+  `GMC database` source label, brand lockup, denominator + observation
+  window caption, no causal titles), a chart-type mapping from gmc output
+  shapes, and a self-contained HTML/Chart.js card template. The reference
+  is included in `gmc skill install` and in the
+  `gmc skill print --format agents-md` self-contained edition.
 
 ## 0.3.0 - 2026-07-05
 

package/README.md

@@ -30,7 +30,9 @@ A fuller user guide lives in
 
 Closed-beta access is controlled by GMC API credentials, not npm package
 visibility. Installing the public package does not grant access to paid or beta
-data.
+data. Authenticated access (login, API keys) requires a paid GMC plan
+(Starter or Pro) — see https://gamemarketcopilot.com/plans. Without
+credentials the CLI serves redacted public previews with a small quota.
 
 ## Auth
 
@@ -64,8 +66,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. The core
-analysis guidance is shared, but the registration step depends on the agent.
+heuristics, quota etiquette, honesty rules, and branded chart-card generation
+(publish-ready, correctly attributed charts from gmc output) 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:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@witchpot/gmc",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "private": false,
   "description": "Command line tools for Game Market Copilot market research.",
   "license": "UNLICENSED",
@@ -43,6 +43,7 @@
   },
   "scripts": {
     "test": "node --test src/*.test.js",
+    "skill:manifest": "node scripts/gen-skill-manifest.mjs",
     "release:check": "node scripts/check-release-readiness.mjs && node scripts/smoke-pack.mjs",
     "prepublishOnly": "npm run release:check",
     "smoke:beta": "node scripts/smoke-beta.mjs",

package/scripts/check-release-readiness.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 
@@ -16,7 +17,9 @@ const requiredFiles = [
   "skill/gmc-analysis/SKILL.md",
   "skill/gmc-analysis/references/recipes.md",
   "skill/gmc-analysis/references/pitfalls.md",
+  "skill/gmc-analysis/references/validity.md",
   "skill/gmc-analysis/references/quota.md",
+  "skill/gmc-analysis/references/charts.md",
   "skill/gmc-analysis/CHANGELOG.md",
   "README.md",
   "CHANGELOG.md"
@@ -119,6 +122,53 @@ for (const file of sourceFiles) {
   }
 }
 
+// The skill content-hash manifest (NAK-190) is also enforced by
+// src/skill-manifest.test.js, but release:check/prepublishOnly run WITHOUT
+// the test suite — recheck here so a stale manifest can never reach npm.
+const { buildSkillManifest, MANIFEST_PATH } = await import("./gen-skill-manifest.mjs");
+if (!existsSync(MANIFEST_PATH)) {
+  failures.push("skill/gmc-analysis.manifest.json is missing — run npm run skill:manifest.");
+} else {
+  const committedManifest = JSON.parse(readFileSync(MANIFEST_PATH, "utf8"));
+  const currentManifest = buildSkillManifest();
+  if (
+    committedManifest.contentHash !== currentManifest.contentHash ||
+    committedManifest.version !== currentManifest.version
+  ) {
+    failures.push(
+      "skill/gmc-analysis.manifest.json is stale: bump metadata.version in SKILL.md, run npm run skill:manifest, and re-sync the gmc-agent-skills distribution repo."
+    );
+  }
+}
+
+// The public distribution repo (github.com/witchpot-studio/gmc-agent-skills)
+// mirrors skill/gmc-analysis. When it is checked out as a workspace sibling,
+// a drift between the two is a release blocker — MCP-only users install the
+// skill from that repo and must get the same content the npm package ships.
+const explicitAgentSkillsDir = process.env.GMC_AGENT_SKILLS_DIR;
+const agentSkillsRepo =
+  explicitAgentSkillsDir ?? path.join(packageDir, "..", "..", "..", "gmc-agent-skills");
+const agentSkillsSyncScript = path.join(agentSkillsRepo, "scripts", "sync-from-cli.mjs");
+if (explicitAgentSkillsDir && !existsSync(agentSkillsSyncScript)) {
+  failures.push(
+    `GMC_AGENT_SKILLS_DIR is set but ${agentSkillsSyncScript} does not exist — fix the path or unset the variable.`
+  );
+} else if (existsSync(agentSkillsSyncScript)) {
+  const drift = spawnSync(process.execPath, ["scripts/sync-from-cli.mjs", "--check"], {
+    cwd: agentSkillsRepo,
+    encoding: "utf8",
+    // Pin the canonical source to THIS checkout — the sync script's own
+    // default (../GMC relative to the skills repo) could silently compare
+    // against a different GMC checkout.
+    env: { ...process.env, GMC_REPO_DIR: path.join(packageDir, "..", "..") }
+  });
+  if (drift.status !== 0) {
+    failures.push(
+      `gmc-agent-skills repo has drifted from skill/gmc-analysis — run node scripts/sync-from-cli.mjs there.\n${(drift.stderr || "").trim()}`
+    );
+  }
+}
+
 if (failures.length > 0) {
   process.stderr.write(`GMC CLI release readiness failed:\n${failures.map((failure) => `- ${failure}`).join("\n")}\n`);
   process.exit(1);

package/scripts/gen-skill-manifest.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+
+// Regenerates skill/gmc-analysis.manifest.json — a content-hash fingerprint
+// of the packaged gmc-analysis skill (SKILL.md + references/ + CHANGELOG.md).
+//
+// Maintainer rule: any time skill/gmc-analysis/** content changes, bump
+// metadata.version in SKILL.md, then run `npm run skill:manifest` (in
+// packages/gmc-cli) to regenerate this manifest, and re-sync the
+// gmc-agent-skills distribution repo (node scripts/sync-from-cli.mjs there).
+// src/skill-manifest.test.js recomputes the same hash on every
+// `npm run test:cli` / `npm run verify` and fails loudly if it no longer
+// matches the committed manifest — this is the drift guard that would have
+// caught the unversioned charts.md changes in PR #18 / PR #43 (NAK-190).
+//
+// The manifest is written OUTSIDE skill/gmc-analysis/ on purpose: that
+// directory is mirrored byte-for-byte into the public gmc-agent-skills
+// distribution repo, and the manifest must never be part of (or affect the
+// hash of) the content it describes.
+
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageDir = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+export const SKILL_DIR = path.join(packageDir, "skill", "gmc-analysis");
+export const MANIFEST_PATH = path.join(packageDir, "skill", "gmc-analysis.manifest.json");
+
+/** List every file under `dir`, as sorted relative POSIX paths. */
+export function listSkillFiles(dir = SKILL_DIR) {
+  const results = [];
+  walk(dir, dir, results);
+  return results.sort();
+}
+
+function walk(root, current, results) {
+  const entries = readdirSync(current, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+  for (const entry of entries) {
+    const abs = path.join(current, entry.name);
+    if (entry.isDirectory()) {
+      walk(root, abs, results);
+    } else if (entry.isFile()) {
+      results.push(path.relative(root, abs).split(path.sep).join("/"));
+    }
+  }
+}
+
+function sha256Hex(buffer) {
+  return createHash("sha256").update(buffer).digest("hex");
+}
+
+/**
+ * Hash every file under `dir` and fold the per-file hashes into one
+ * top-level sha256 over `relpath\nfilehash\n` lines (sorted, deterministic).
+ */
+export function computeSkillContentHash(dir = SKILL_DIR) {
+  const files = listSkillFiles(dir);
+  const digest = createHash("sha256");
+  for (const relPath of files) {
+    const fileHash = sha256Hex(readFileSync(path.join(dir, relPath)));
+    digest.update(`${relPath}\n${fileHash}\n`);
+  }
+  return { contentHash: digest.digest("hex"), files: files.length };
+}
+
+/** Parse metadata.version out of SKILL.md source text; undefined when absent. */
+export function parseSkillVersion(source) {
+  const frontmatter = source.match(/^---\n([\s\S]*?)\n---/);
+  return frontmatter?.[1].match(/^\s*version:\s*"?([0-9][0-9A-Za-z.\-]*)"?\s*$/m)?.[1];
+}
+
+/** Read metadata.version from SKILL.md's YAML frontmatter. */
+export function readSkillManifestVersion(dir = SKILL_DIR) {
+  const version = parseSkillVersion(readFileSync(path.join(dir, "SKILL.md"), "utf8"));
+  if (!version) {
+    throw new Error(`${path.join(dir, "SKILL.md")} must declare metadata.version in its frontmatter.`);
+  }
+  return version;
+}
+
+/** Build the manifest object (version + contentHash + files) for `dir`. */
+export function buildSkillManifest(dir = SKILL_DIR) {
+  const { contentHash, files } = computeSkillContentHash(dir);
+  return { version: readSkillManifestVersion(dir), contentHash, files };
+}
+
+/**
+ * Baseline manifest for the version-bump rule. The authoritative baseline is
+ * the manifest COMMITTED ON origin/main (read via `git show`, so deleting or
+ * hand-editing the local file cannot dodge the rule); the local file is only
+ * a fallback for environments where the git baseline is unreadable.
+ */
+function baselineSkillManifest() {
+  const result = spawnSync("git", ["show", "origin/main:packages/gmc-cli/skill/gmc-analysis.manifest.json"], {
+    cwd: packageDir,
+    encoding: "utf8"
+  });
+  if (result.status === 0 && typeof result.stdout === "string") {
+    try {
+      return JSON.parse(result.stdout);
+    } catch {
+      // fall through to the local file
+    }
+  }
+  if (existsSync(MANIFEST_PATH)) {
+    try {
+      return JSON.parse(readFileSync(MANIFEST_PATH, "utf8"));
+    } catch {
+      return undefined;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Pure regen-permission rule (unit-tested in src/skill-manifest.test.js).
+ * Content that differs from the baseline while keeping the baseline's
+ * version is refused: once a version's content is on origin/main, changing
+ * content under that version always requires a bump. A differing version
+ * (the in-flight bump case, iterated freely within one branch) and a
+ * missing baseline (true first generation) are allowed. There is
+ * deliberately NO force escape hatch: an override flag would let
+ * unversioned content changes reach npm and the public skills repo.
+ */
+export function assertRegenAllowed({ baseline, next }) {
+  if (!baseline) return;
+  if (baseline.contentHash === next.contentHash) return;
+  if (baseline.version !== next.version) return;
+  throw new Error(
+    `skill content changed but metadata.version is still ${next.version}, whose content is already fixed by the baseline manifest (origin/main) — bump the version in SKILL.md, then rerun npm run skill:manifest.`
+  );
+}
+
+function main() {
+  const manifest = buildSkillManifest();
+  try {
+    assertRegenAllowed({ baseline: baselineSkillManifest(), next: manifest });
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
+  writeFileSync(MANIFEST_PATH, `${JSON.stringify(manifest, null, 2)}\n`);
+  process.stdout.write(
+    `Wrote ${path.relative(packageDir, MANIFEST_PATH)}: version ${manifest.version}, ${manifest.files} files, contentHash ${manifest.contentHash}\n`
+  );
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main();
+}

package/scripts/smoke-pack.mjs

@@ -81,6 +81,9 @@ try {
   if (!skillPrintResult.stdout.includes("GMC Analysis") || !skillPrintResult.stdout.includes("Pitfalls")) {
     throw new Error("Packed gmc skill print did not emit the inlined agents-md section");
   }
+  if (!skillPrintResult.stdout.includes("Chart cards") || !skillPrintResult.stdout.includes("gmc-lockup.svg")) {
+    throw new Error("Packed gmc skill print did not inline the chart cards reference");
+  }
 
   // gmc is shadowed by Oh My Zsh's `git merge --continue` alias, so the
   // package ships alias binaries; make sure npm actually installed them.

package/skill/gmc-analysis/CHANGELOG.md

@@ -1,5 +1,85 @@
 # gmc-analysis skill changelog
 
+## 0.5.0 - 2026-07-13
+
+- New "Saved Game Lists" section in SKILL.md, plus recipe R5 in
+  `references/recipes.md` (NAK-155/NAK-178/NAK-189): documents Game Lists as
+  reusable, workspace-scoped cohort inputs — `gmc lists ...` (CLI) or the 7
+  MCP tools (`list_game_lists`, `get_game_list`, `create_game_list`,
+  `update_game_list`, `add_game_list_items`, `remove_game_list_item`,
+  `delete_game_list`), all 0-credit; passing a filter-kind list's id as
+  `game_list_id`/`--list <id>` to `list_games`, `market_aggregate`,
+  `cohort_review_categories`, or `cohort_evidence` instead of re-sending an
+  inline filter; reading `game_list.definition_hash` to detect a changed
+  stored definition between calls; the composite-list tool restriction
+  (`COMPOSITE_LIST_UNSUPPORTED_FOR_TOOL` on `market_aggregate`/
+  `cohort_review_categories`), the manual-list restriction
+  (`GAME_LIST_KIND_UNSUPPORTED`), and `delete_game_list`'s MCP confirm-by-
+  exact-name two-call contract.
+- `references/charts.md` retroactive documentation (NAK-190): this
+  changelog entry catches up two content changes that shipped without a
+  skill version bump because nothing enforced one at the time (see the new
+  content-hash manifest guard below, added in this same release, to prevent
+  a repeat):
+  - PR #18 (NAK-139..143): new chart types beyond horizontal bar (lollipop,
+    grouped column, stacked column, dumbbell, scatter, quadrant with
+    computed threshold lines, donut, hero-number card); Steam capsule rows
+    for per-game bar charts; wide (16:9, 1200x675) and square (1:1,
+    1080x1080) export geometry replacing the earlier vertical (4:5) option.
+  - PR #43 (NAK-166/NAK-142): direct-label placement rules (values at bar/
+    line ends instead of legends, corner labels on quadrant charts) and the
+    embedded brand typography stack (Inter / JetBrains Mono / Quicksand)
+    used across card title, footer, and source-label text.
+- Added `packages/gmc-cli/scripts/gen-skill-manifest.mjs` and
+  `packages/gmc-cli/src/skill-manifest.test.js` (NAK-190): a content-hash
+  manifest (`skill/gmc-analysis.manifest.json`, outside the synced skill
+  directory) that fails `npm run test:cli` whenever `skill/gmc-analysis/**`
+  content changes without a matching `metadata.version` bump and manifest
+  regeneration (`npm run skill:manifest`) — the gap that let the two chart
+  entries above ship unversioned.
+
+## 0.4.0 - 2026-07-09
+
+- Added `references/validity.md` (NAK-82): statistical-validity checklist
+  (denominator + N on every share, observation window, counting basis,
+  N<30 warning, effect size over bare significance, confound
+  stratification for publisher axis / price / release year, multiple-
+  comparison disclosure) and claim-safety rules (no causal verbs for
+  observational associations, external-estimate labeling, `not_collected`
+  means not collected), with a compliant output example. Wired into the
+  SKILL.md hard rules and the AGENTS.md edition.
+- New pitfall P9 (NAK-81): single-assignment (`primary_market_tag`) vs
+  multi-assignment (`tag` grouping / `tags` filter) tag counting bases
+  diverge sharply — pick one basis per question, name it next to the
+  denominator, never mix or compare across bases.
+
+## 0.3.1 - 2026-07-08
+
+- quota.md: updated the paid allowances to the resized uniform per-credit
+  pricing (Starter 2,500 / Pro 7,000 credits per month, NAK-110); reset and
+  gate-time charging semantics unchanged.
+
+## 0.3.0 - 2026-07-07
+
+- Added `references/charts.md`: publish-ready branded chart cards from gmc
+  CLI / MCP outputs (NAK-89). Bakes attribution into the artifact — fixed
+  `GMC database` source label, brand lockup (icon + wordmark), denominator
+  + observation window caption, no causal titles — and maps gmc output
+  shapes (market aggregates, cohort evidence, coverage checks, single
+  KPIs) to chart types with a self-contained HTML/Chart.js template.
+- SKILL.md: new "Chart cards" section wiring the reference into the
+  workflow and into the AGENTS.md edition.
+- SKILL.md: new "MCP-only setups" section mapping the CLI workflow onto
+  the GMC MCP tools (market_aggregate, coverage_check, cohort_evidence,
+  game_profile, ...) so agents with only the MCP connection do not attempt
+  gmc commands (NAK-98).
+- quota.md: corrected to the monthly credit model (Starter 5,000 / Pro
+  25,000 credits per month, reset on the 1st at 00:00 UTC, gate-time
+  charging) — the per-UTC-day request caps it described were outdated.
+- Documented the paid-plan requirement (Starter/Pro) for authenticated
+  access, and the `PLAN_REQUIRED` vs `QUOTA_EXCEEDED` distinction for
+  MCP tool errors (upgrade vs wait-for-reset).
+
 ## 0.2.0 - 2026-06-12
 
 - Folded in the five learnings from the first field test (2025 city

package/skill/gmc-analysis/SKILL.md

@@ -1,13 +1,14 @@
 ---
 name: gmc-analysis
 description: >-
-  Use when analyzing Steam game market data with the gmc CLI (Game Market
-  Copilot) — cross-game cohort analysis (common complaints, marketing
-  patterns, pricing), single-title deep dives, market sizing, or any question
-  about Steam games, reviews, creators, showcases, or campaigns that gmc can
-  answer.
+  Use when analyzing Steam game market data with Game Market Copilot (the
+  gmc CLI or the GMC MCP tools) — cross-game cohort analysis (common
+  complaints, marketing patterns, pricing), single-title deep dives, market
+  sizing, or any question about Steam games, reviews, creators, showcases,
+  or campaigns that GMC can answer — including turning results into
+  publish-ready branded chart cards.
 metadata:
-  version: 0.2.0
+  version: 0.5.0
 ---
 
 # GMC Analysis
@@ -26,12 +27,49 @@ gmc auth status --json        # anonymous => redacted previews + tiny quota
 gmc schema --json             # the authoritative command/endpoint reference
 ```
 
+Authenticated access (CLI login, API keys, MCP) requires a paid GMC plan
+(Starter or Pro); Free workspaces cannot mint credentials. Anonymous CLI
+use works but returns redacted previews with a tiny quota.
+
 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`.
 
+## MCP-only setups (no CLI installed)
+
+If you have the GMC MCP connection instead of the CLI, do NOT attempt gmc
+commands — use the MCP tools; every workflow and honesty rule in this skill
+applies identically. Mechanics map as follows:
+
+- Sizing and denominators (`gmc games count` / `games aggregate`) ->
+  `market_aggregate` (population-true; prefer it over paginating
+  `list_games`).
+- Coverage pre-check -> `coverage_check` before fanning out `game_profile`
+  on more than 3 titles.
+- Cohort evidence (`reviews patterns`, `cohort ...`) -> `cohort_evidence`,
+  `cohort_review_categories`, `search_review_claims`.
+- Single-title drill-down (`games detail` / `games analysis`) ->
+  `game_profile`; name resolution -> `resolve`; showcases ->
+  `showcase_fit`.
+- The response envelope differs from the CLI: MCP tool responses carry
+  `meta.quota` = `{ used, limit, remaining, resets_at }` (credits) plus
+  `meta.credits_charged`, `meta.basis`, `meta.denominator`,
+  `meta.coverage`, and `meta.warnings` — there is no `meta.entitlements`
+  wrapper. The read-before-you-spend and honesty rules apply unchanged.
+- CLI-only mechanics (pagination flags, `--fields` projection, map-reduce
+  recipes) may have no MCP equivalent — stay within the tool contracts
+  instead of simulating them.
+- A `PLAN_REQUIRED` tool error means the workspace plan has no API access
+  (e.g. Free) — retrying or waiting will not help; tell the user an
+  upgrade at gamemarketcopilot.com/plans is required. Only
+  `QUOTA_EXCEEDED` is the wait-for-monthly-reset condition.
+
+References in this skill use CLI syntax; translate to the matching MCP
+tool. Chart-card rules (references/charts.md) apply to both paths
+unchanged.
+
 ## Core workflow for cohort questions
 
 1. **Size the cohort and its research coverage first** (1-2 requests):
@@ -58,6 +96,50 @@ Search commands are optimized for row retrieval. Do not expect
 unless you explicitly pass `--include-total`; for count-only questions use
 `gmc games count` instead.
 
+## Saved Game Lists (reusable cohort definitions)
+
+A Game List is a workspace-scoped, reusable cohort input — persist a filter
+(or an explicit appid set) once instead of re-sending a large inline filter
+on every call.
+
+- Manage lists via `gmc lists ...` (`list`, `create`, `show`, `games`, `add`,
+  `remove`, `delete`) or the MCP tools `list_game_lists` / `get_game_list` /
+  `create_game_list` / `update_game_list` / `add_game_list_items` /
+  `remove_game_list_item` / `delete_game_list`. All are 0-credit and scoped
+  to the caller's own workspace.
+- Two kinds: `manual` (explicit appid membership) and `filter` (a stored
+  `GameFilter`, re-evaluated live against current data on every read). The
+  MCP `game_list_id` input accepts `filter`-kind lists only; the CLI
+  `--list <id>` flag resolves membership server-side and accepts BOTH kinds.
+- Pass a filter-kind list's `id` as `game_list_id` to `list_games`,
+  `market_aggregate`, `cohort_review_categories`, or `cohort_evidence`
+  instead of re-sending the inline filter — mutually exclusive with
+  `filter` (`INVALID_INPUT` if both or neither are given). CLI equivalent:
+  `--list <id>` on `gmc reviews patterns`, `gmc marketing patterns`, and
+  `gmc cohort ...` (cohort-evidence-shaped commands only — `gmc games
+  count`/`gmc games aggregate` have no `--list` flag; use `market_aggregate`
+  with `game_list_id` over MCP for that).
+- The response's `game_list.definition_hash` (a SHA-256 over `{kind,
+  filter, sort}`) tells you whether the stored definition changed between
+  calls — diff hashes across calls instead of re-diffing the filter
+  yourself.
+
+Sharp edges:
+
+- **Composite (union) lists** work only with `list_games`/`cohort_evidence`;
+  `market_aggregate`/`cohort_review_categories` reject them with
+  `COMPOSITE_LIST_UNSUPPORTED_FOR_TOOL` (those two are single aggregate
+  calls that cannot be bound to an explicit appid population).
+- **Manual lists cannot be used as `game_list_id`** (MCP only) — a
+  `kind:"manual"` list fails `GAME_LIST_KIND_UNSUPPORTED` there. Use the
+  CLI `--list <id>` flag (which accepts manual lists), or read membership
+  directly (`gmc lists games <id>` / `get_game_list`).
+- `delete_game_list` is destructive and, over MCP, uses a confirm-by-
+  exact-name two-call contract: a call without `confirm` fails
+  `CONFIRMATION_REQUIRED`, naming the list; only pass `confirm` set to that
+  exact name after the user has explicitly asked to delete it — never
+  guess or pre-fill it speculatively.
+
 ## Hard rules
 
 - **Missing data is not absent sentiment.** Report `cohort.usableGames`,
@@ -69,6 +151,16 @@ unless you explicitly pass `--include-total`; for count-only questions use
 - **Bounded evidence, not market truth.** Carry the CLI's own caveats:
   evidence packs are sampled/returned-page evidence. Always state
   denominators ("87 of 107 analyzed titles") and preserve `warnings`.
+- **Pass the validity checklist before handing off numbers.** Every
+  reported share carries its denominator, N, observation window, and tag
+  counting basis; small-N groups are labeled directional; group
+  comparisons are stratified for obvious confounds (publisher axis, price,
+  release year) or the unchecked confound is named; scanned-extreme
+  findings disclose the scan. Details in the validity reference.
+- **Claim safety.** No causal verbs for observational associations; label
+  estimates not derived from gmc data as external with a source;
+  `not_collected` means not collected, never zero or absent. Details in
+  the validity reference.
 - **Separate API facts from your synthesis.** Quote theme labels and player
   counts as data; label your clustering and conclusions as your analysis.
 - **Pace your quota.** Read `meta.entitlements.quota` (`used`/`limit`)
@@ -76,12 +168,24 @@ unless you explicitly pass `--include-total`; for count-only questions use
   Details in the quota reference.
 - Preserve `meta.requestId` values for anything you may need to report.
 
+## Chart cards
+
+When the user wants a shareable or publish-ready visual of gmc results,
+follow the charts reference. Its rules are part of GMC attribution: a chart
+under the GMC label must carry the fixed source label, the brand lockup,
+and a denominator + observation window caption, and its title must not
+make causal claims. Never emit a GMC-attributed chart that skips these.
+
 ## References
 
 - `references/recipes.md` — step-by-step playbooks (cohort complaints,
   full-cohort map-reduce, single-title deep dive, market sizing).
 - `references/pitfalls.md` — known failure modes and the correct pivots.
+- `references/validity.md` — statistical-validity checklist and
+  claim-safety rules for any published number.
 - `references/quota.md` — quota model and cost estimation.
+- `references/charts.md` — branded chart cards: attribution rules, chart
+  type mapping from gmc output shapes, self-contained HTML template.
 
 (In the AGENTS.md edition of this skill the references are inlined below.)
 

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

@@ -0,0 +1,280 @@
+# Chart cards
+
+Turn gmc CLI / MCP outputs into publish-ready, correctly attributed GMC
+chart cards (self-contained HTML -> PNG). Follow this reference whenever a
+chart, graph, or shareable visual is requested from GMC data. A chart that
+violates the non-negotiables below must not carry GMC attribution.
+
+## Non-negotiables (every card)
+
+1. **Footer, left**: the fixed source label `GMC database` plus at most one
+   short factual note (collection method, cutoff, exclusions). Japanese
+   edition: `GMCデータベース`. Never change, translate loosely, or omit the
+   label.
+2. **Footer, right**: the brand lockup — icon + wordmark, one image:
+   `https://gamemarketcopilot.com/assets/gmc-lockup.svg`. Never the icon
+   alone, never a retyped wordmark, never someone else's logo.
+3. **Caption (top-left of the card)**: denominator + observation window,
+   e.g. `1,204 of 20,994 titles released 2025 / aggregated as of
+   2026-07-06`. Take denominators from `gmc games count` (or the tool's own
+   `cohort.usableGames`), not from page sizes. The caption is the card's
+   denominator disclosure — exports must never crop it (or the footer) off.
+4. **Title**: state the observed fact — a level, difference, share, or
+   rank. No causal verbs (`drove`, `boosted`, `caused`, `led to`,
+   `because`); the data supports co-occurrence, not causation. No hype
+   metaphors. Correlation phrasing is fine.
+5. **Data honesty**: `not_collected` is never charted as zero. Locked or
+   `preview: true` payloads are never charted as full data. Small
+   denominators (n < 30) are presented as individual cases, not a trend
+   bar. `skippedGames` / `skippedReasons` go in the footnote when they
+   change the reading.
+6. **External estimates stay outside the label**: units multipliers,
+   wishlist folklore, or any non-GMC number never appear under the
+   `GMC database` label — prefer leaving them off a GMC-branded card
+   entirely. If one must appear, add a second, visually separate footnote
+   line: `External estimate: <source> — not GMC data`.
+7. **Opaque background** (`#fafaf7` page, `#ffffff` card). Never export
+   transparent PNGs. Export geometry: 16:9 1200x675 (X default) or 1:1
+   1080x1080 (X-safe; donut/kpi/quadrant read best). Vertical (4:5) cards
+   are not produced. Default to 16:9 when unsure.
+
+## Picking the chart type from gmc output shapes
+
+| Output | Shape | Chart |
+|---|---|---|
+| `gmc games aggregate --group-by <dim>` / MCP `market_aggregate` | 6+ groups, rank matters | Horizontal bar, sorted desc |
+| same | 6+ groups, rank matters, compact point emphasis | Lollipop (bar_h variant) |
+| same | 2-5 groups | Vertical column |
+| same | 2-4 series × categories, e.g. release count by year × price band | Grouped column |
+| same | 2-4 part-of-whole series across categories | Stacked column |
+| same | before/after pairs per category, exactly 2 series | Dumbbell |
+| same, time buckets (release windows, months) | series over time | Line (single/few series) or column |
+| MCP `market_aggregate` with `segment_filter` | segment vs base | Two big numbers + ratio, or grouped bar |
+| `gmc reviews patterns` / MCP `cohort_evidence` / clustered `negativeThemes` | theme -> game counts | Horizontal bar; caption carries `x of N usable games` |
+| MCP `coverage_check` / `gmc games count --group-by coverage` | composition, 2-4 segments | Donut with absolute counts printed, or one 100% stacked bar |
+| any tool output with x/y metric pairs per point | two metrics correlation | Scatter |
+| any tool output with x/y metric pairs for positioning | scatter + median threshold lines + 4 descriptive corner labels; thresholds are computed from plotted values, never chosen | Quadrant |
+| single KPI (one count, one median, one share) | one number | Hero number card (no chart canvas) |
+
+Rules of thumb: when unsure, use a horizontal bar. One message per card.
+Never: 3D, dual axes, cropped bar baselines, pie with 5+ slices, line
+charts for non-time data.
+
+## Steam capsules for game rows
+
+When bar rows are individual game titles, show the Steam capsule
+(`https://shared.akamai.steamstatic.com/store_item_assets/steam/apps/{appid}/capsule_231x87.jpg`,
+231x87) left of the row label. Preload images before render; skip rows whose
+image failed so the text-only fallback keeps the layout. Scatter/quadrant
+points get the same treatment as a thumbnail overlay per the visual guide's
+thumbnail-overlay pattern: a white, 1px-framed capsule anchored near the
+point with a dashed leader line back to it, instead of a row-left capsule.
+
+```js
+const rows = [{ label: '{{GAME TITLE}}', appid: 0 }];
+const capsuleImages = await Promise.all(rows.map(({ appid }) => new Promise((resolve) => {
+  if (!appid) return resolve(null);
+  const img = new Image();
+  img.onload = () => resolve(img);
+  img.onerror = () => resolve(null);
+  img.src = `https://shared.akamai.steamstatic.com/store_item_assets/steam/apps/${appid}/capsule_231x87.jpg`;
+})));
+
+const steamCapsules = {
+  id: 'steamCapsules',
+  afterDraw(chart) {
+    const yScale = chart.scales.y;
+    if (!yScale) return;
+    const { ctx } = chart;
+    yScale.ticks.forEach((_, i) => {
+      const img = capsuleImages[i];
+      if (!img) return;
+      const y = yScale.getPixelForTick(i) - 14;
+      ctx.drawImage(img, yScale.left - 66, y, 54, 20);
+    });
+  }
+};
+```
+
+## Color
+
+Neutrals (fixed): page `#fafaf7`, card `#ffffff`, ink `#1a1d20`, muted
+`#3e454d`, faint `#818d9a`, grid `rgba(26,29,32,0.06)`.
+
+- **Single series / ranking**: accent ladder only — Ember `#EC7336` at
+  alpha 0.85 (lead), 0.55, 0.30, rest `rgba(26,29,32,0.08)`.
+- **2-3 categories**: Ember `#EC7336` + Seagrass `#1AA29D` (+ Inkwell
+  `#4057C7`). Never distinguish categories by alpha alone.
+- **4-5 categories**: add Moss `#3E9C5F`, Mulberry `#9B4ABF`. Max 5 colors;
+  gray out non-focus series with `rgba(26,29,32,0.12)`. 6+ categories:
+  split the chart or bucket into "other".
+- Direct labels beat legends: print values at bar ends / line ends.
+
+## Card template (self-contained)
+
+Fill the `{{...}}` slots, adjust the dataset + type per the table above,
+open in a browser, capture the `.card` element as PNG. The template needs
+network access for fonts, Chart.js CDN, and the brand lockup.
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&family=JetBrains+Mono:wght@400;500&family=Quicksand:wght@700&display=swap" rel="stylesheet">
+<script src="https://cdn.jsdelivr.net/npm/chart.js@4"></script>
+<style>
+  :root {
+    --bg: #fafaf7; --card: #ffffff;
+    --ink: #1a1d20; --ink-muted: #3e454d; --ink-faint: #818d9a;
+    --rule: #e8e5de; --accent: #ec7336;
+    --sans: 'Inter', system-ui, sans-serif;
+    --mono: 'JetBrains Mono', ui-monospace, monospace;
+    --title: 'Quicksand', 'Inter', system-ui, sans-serif;
+  }
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  body { background: var(--bg); font-family: var(--sans); color: var(--ink);
+         display: flex; justify-content: center; padding: 40px 16px; }
+  .card { width: 720px; max-width: 100%; background: var(--card);
+          border: 1px solid var(--rule); display: flex; flex-direction: column; }
+  .card-head { display: flex; justify-content: space-between; gap: 12px;
+               padding: 18px 20px 12px; border-bottom: 1px solid var(--rule); }
+  .card-num { font-family: var(--mono); font-size: 12.5px; font-weight: 500;
+              color: var(--accent); max-width: 76%; }
+  .card-cat { font-family: var(--mono); font-size: 10px; letter-spacing: 0.12em;
+              text-transform: uppercase; color: var(--ink-faint); white-space: nowrap; }
+  .card-title { padding: 26px 20px 8px; font-family: var(--title);
+                font-size: 34px; line-height: 1.12; font-weight: 700; }
+  .chart-wrap { position: relative; margin: 18px 20px 8px;
+                min-height: 470px; height: 470px; }
+  .card-foot { display: flex; justify-content: space-between; align-items: center;
+               gap: 16px; border-top: 1px solid var(--rule);
+               padding: 14px 20px; margin-top: 12px; }
+  .foot-meta { display: flex; flex-direction: column; gap: 3px; min-width: 0; }
+  .foot-source { font-family: var(--mono); font-size: 13px; color: var(--ink-muted); }
+  .foot-note { font-size: 11.5px; line-height: 1.45; color: var(--ink-faint); }
+  .brand-lockup { flex: 0 0 auto; height: 24px; width: auto; display: block; }
+</style>
+</head>
+<body>
+<article class="card">
+  <div class="card-head">
+    <div class="card-num">{{DENOMINATOR AND WINDOW, e.g. 1,204 of 20,994 titles released 2025 / as of 2026-07-06}}</div>
+    <div class="card-cat">{{CHART TYPE, e.g. RANKED BAR}}</div>
+  </div>
+  <h2 class="card-title">{{FACTUAL TITLE — observed level/difference/share, no causal verbs}}</h2>
+  <div class="chart-wrap"><canvas id="chart"></canvas></div>
+  <div class="card-foot">
+    <div class="foot-meta">
+      <div class="foot-source">GMC database</div>
+      <div class="foot-note">{{ONE-LINE NOTE: method, cutoff, exclusions, skipped counts}}</div>
+    </div>
+    <img class="brand-lockup" src="https://gamemarketcopilot.com/assets/gmc-lockup.svg" alt="Game Market Copilot">
+  </div>
+</article>
+<script>
+  const ink = (a) => `rgba(26, 29, 32, ${a})`;
+  const accent = (a) => `rgba(236, 115, 54, ${a})`;
+  Chart.defaults.font.family = "'Inter', system-ui, sans-serif";
+  Chart.defaults.font.size = 13;
+  Chart.defaults.color = '#3e454d';
+
+  // Direct value labels at bar ends (skip for line charts; use point labels there).
+  const valueLabels = {
+    id: 'valueLabels',
+    afterDatasetsDraw(chart) {
+      const { ctx } = chart;
+      const horizontal = chart.options.indexAxis === 'y';
+      chart.data.datasets.forEach((ds, di) => {
+        chart.getDatasetMeta(di).data.forEach((el, i) => {
+          const v = ds.data[i];
+          if (v == null) return;
+          ctx.save();
+          ctx.font = "500 12px 'JetBrains Mono', monospace";
+          ctx.fillStyle = '#3e454d';
+          ctx.textBaseline = 'middle';
+          if (horizontal) { ctx.textAlign = 'left'; ctx.fillText(v.toLocaleString(), el.x + 8, el.y); }
+          else { ctx.textAlign = 'center'; ctx.textBaseline = 'bottom'; ctx.fillText(v.toLocaleString(), el.x, el.y - 6); }
+          ctx.restore();
+        });
+      });
+    }
+  };
+
+  const labels = ['{{GROUP A}}', '{{GROUP B}}', '{{GROUP C}}'];   // sorted desc for rankings
+  const values = [0, 0, 0];                                       // real aggregates only
+  new Chart(document.getElementById('chart'), {
+    type: 'bar',                       // ranked bar. Column: drop indexAxis. Line: type 'line'.
+    data: { labels, datasets: [{
+      data: values,
+      // Ranking ladder — lead bar strongest, tail neutral:
+      backgroundColor: values.map((_, i) => [accent(0.85), accent(0.55), accent(0.30)][i] ?? ink(0.08)),
+      borderRadius: 2, barPercentage: 0.72
+    }]},
+    options: {
+      indexAxis: 'y', responsive: true, maintainAspectRatio: false,
+      layout: { padding: { right: 64 } },   // room for end-of-bar labels
+      plugins: { legend: { display: false }, tooltip: { enabled: false } },
+      scales: {
+        x: { beginAtZero: true, grid: { color: ink(0.06) }, border: { color: ink(0.18) } },
+        y: { grid: { display: false }, border: { color: ink(0.18) } }
+      },
+      animation: { onComplete: () => { window.__animComplete = true; } }
+    },
+    plugins: [valueLabels]
+  });
+</script>
+</body>
+</html>
+```
+
+Variants:
+
+- **Column** (2-5 groups): remove `indexAxis`, move padding to `top`,
+  labels render above bars automatically via the plugin.
+- **Line** (time buckets): `type: 'line'`, `borderColor: accent(0.85)`,
+  `pointRadius: 3`, `fill: false` (always false when more than one dataset
+  or when combined with bars), label only first/last/inflection points.
+- **Donut** (coverage split, max 4 segments): `type: 'doughnut'`,
+  `cutout: '62%'`, colors Ember/Seagrass/Inkwell + gray; print
+  `label — count (share%)` per segment as direct labels or a compact list
+  under the chart; absolute counts are mandatory, share alone is not
+  enough.
+- **Hero number** (single KPI): replace `.chart-wrap` with
+  `<div style="padding:56px 20px 40px; text-align:center;">
+  <div style="font-size:96px; font-weight:600; letter-spacing:-0.04em;
+  color:var(--accent);">{{VALUE}}</div>
+  <div style="font-size:15px; color:var(--ink-muted); margin-top:8px;">
+  {{ONE-LINE QUALIFIER}}</div></div>` and delete the chart script. The
+  caption and footer rules still apply unchanged.
+
+Japanese edition: add `&family=Noto+Sans+JP:wght@400;500;600` to the fonts
+URL, append `'Noto Sans JP'` to `--sans`, set `<html lang="ja">`, and use
+`GMCデータベース` as the source label. Add `&family=Noto+Serif+JP:wght@400&`
+to the fonts URL so JA titles render serif. Steam tags in JA charts:
+`English Tag(日本語タグ名)` on first appearance.
+
+## Capture
+
+Any browser screenshot of the `.card` element works. Headless example:
+
+```bash
+npx playwright screenshot --wait-for-timeout 2500 --full-page card.html card.png
+```
+
+then crop to the card, or capture the element via a driver that waits for
+`window.__animComplete === true`. Verify before publishing: bars/labels not
+clipped, text legible at mobile size (12px+ effective), background opaque.
+
+## Pre-publish checklist
+
+- [ ] Title is factual, no causal verbs, no hype
+- [ ] Caption has denominator AND observation window
+- [ ] `GMC database` label + brand lockup both present, unmodified
+- [ ] Every number comes from a real gmc/MCP response in this session
+      (no remembered or estimated values); re-run the query if stale
+- [ ] `not_collected` / locked data not charted; skipped counts disclosed
+      when they change the reading
+- [ ] External estimates (if any) credited separately in the footnote
+- [ ] Colors follow the tier rules; max 5 colors; opaque background

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

@@ -72,3 +72,53 @@ single-request server aggregates. Reserve pagination loops for when you
 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.
+
+## P8. Wide aggregations can time out (2026-07)
+
+Aggregate calls that request many metrics and/or two `group_by` dimensions
+over the full catalog can exceed the server-side query timeout. Over MCP this
+surfaces as an `UPSTREAM_TIMEOUT` tool error (older builds: a generic
+`UPSTREAM_ERROR`); via the CLI as a failed request. A timeout is a load
+limit, not a data problem — the cohort itself is fine, and retrying the same
+call unchanged will usually time out again.
+
+**Rule**: split the request instead of retrying as-is — fewer metrics per
+call, one `group_by` dimension at a time, or a narrower filter (e.g. a
+shorter release window) — then combine the results. Splits are safe: each
+call returns population-true numbers for its slice, so recombined totals stay
+consistent. Note the substitution in your analysis log so reviewers know the
+numbers came from split calls.
+
+## P9. Two tag counting bases exist — never mix them (2026-07)
+
+Tag shares can be computed on two different bases, and the numbers diverge
+sharply (observed in a field comparison: the same cohort's genre shares
+disagreed between two reports because each used a different basis):
+
+- **Single-assignment** — `group_by primary_market_tag` (field
+  `primaryMarketTag`, derived from `tagRanks[0]`). Each game is counted at
+  most once, under its top-ranked tag. Rows are mutually exclusive and sum
+  to the TAGGED subset of the cohort — games without tags are omitted from
+  these rows, so compare the row total against the plain cohort count and
+  use "of tagged titles" as the denominator when the two differ.
+- **Multi-assignment** — `group_by tag`, or separate per-tag filtered
+  counts compared or summed across tags (fields `tags` / `tagRanks` /
+  `facets.marketTags`). Each game is counted under every tag it carries, so
+  one game contributes to many rows and shares sum well past 100%. The
+  server marks `group_by tag` with `summary.methods.groupMembership:
+  "multi"` and a multi-membership caveat. (A single `tags`-filtered count
+  by itself still counts each matching title once — the double-counting
+  appears when per-tag numbers are set side by side.)
+
+Neither basis is wrong — they answer different questions:
+
+- "What is the market composed of?" / "which segment is a game in?" /
+  portfolio-style shares -> single-assignment (`primary_market_tag`).
+- "How many games carry tag X?" / tag reach, co-occurrence, feature
+  adoption -> multi-assignment (`tag` grouping or `tags`-filtered counts).
+
+**Rule**: pick one basis per question, name it next to the denominator
+("single-assignment by primary_market_tag, N=1,204"), and never compare or
+combine numbers across bases — not within a report, and not against an
+earlier report computed on the other basis. If a prior number's basis is
+unknown, recompute it rather than citing it.

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

@@ -1,14 +1,19 @@
 # Quota etiquette
 
-Quotas are per workspace, per UTC day, enforced for bearer credentials
-(API keys / CLI credentials). As of 2026-06: starter 1,000/day, pro
-10,000/day; anonymous public preview is far smaller. Treat these numbers as
-indicative — the response metadata is the source of truth.
+Quotas are monthly, workspace-level credit allowances enforced for bearer
+credentials (API keys / CLI credentials / MCP tokens). As of 2026-07:
+Starter 2,500 credits/month, Pro 7,000; the counter resets at 00:00 UTC on
+the first of each month. Anonymous public preview is far smaller. Credits
+are charged when a request is accepted at the gate, so requests that later
+fail validation or 404 still consume — validate appids before batch
+fan-outs. Treat these numbers as indicative — the response metadata is the
+source of truth.
 
 ## Rules
 
 1. **Read before you spend.** Every bearer response carries
-   `meta.entitlements.quota` = `{ used, limit }`. Check it at the start of a
+   `meta.entitlements.quota` = `{ used, limit, remaining, exceeded,
+   resetsAt }` in credits. Check it at the start of a
    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
@@ -21,8 +26,10 @@ indicative — the response metadata is the source of truth.
    `--coverage full,partial` and tighter filters so requests are not spent on
    titles that would be skipped anyway.
 4. **On HTTP 429 (`QUOTA_EXCEEDED`)**: stop fanning out, respect the
-   `Retry-After` header / `error.retryAfterSeconds` (the window resets at UTC
-   midnight), and tell the user how much of the analysis completed.
+   `Retry-After` header / `error.retryAfterSeconds` (the allowance resets at
+   00:00 UTC on the first of the next month; a short `Retry-After` means the
+   separate burst backstop), 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

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

@@ -95,6 +95,33 @@ gives the well-rated share. Divide by the unconditional bucket counts.
 Never read unconditional rating aggregates in low-traction buckets
 (pitfall P5).
 
+## R5. Repeatable cohort via a saved Game List
+
+When a cohort filter will be reused across a session or a recurring
+digest, persist it once instead of re-sending the inline filter on every
+call.
+
+```bash
+# 1. Create the filter-kind list once
+gmc lists create --name "<label>" --kind filter \
+  --filter '{"tags":["<tag>"],"reviewsMin":<n>}' --json   # -> data.id
+
+# 2. Reference it on every follow-up call instead of the inline filter
+gmc reviews patterns --source steam --list <id> --json
+gmc cohort brief --source steam --list <id> --json
+```
+
+Over MCP, `create_game_list` once, then pass its `id` as `game_list_id` to
+`list_games` / `market_aggregate` / `cohort_review_categories` /
+`cohort_evidence` on every follow-up call. Check `game_list.definition_hash`
+on each response — a changed hash means the stored DEFINITION was edited;
+re-state the cohort definition before comparing numbers. A stable hash does
+not freeze the population: filter lists re-evaluate live, so denominators
+can still move between calls. Composite (union) lists only work with `list_games`/
+`cohort_evidence` (this recipe's map-reduce sibling, R2); manual lists are
+not a `game_list_id` input over MCP (the CLI `--list <id>` flag does accept
+them) — read their membership with `gmc lists games <id>` / `get_game_list`.
+
 ## Output contract for every analysis
 
 Always include in your final answer: the cohort definition and size, how many

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

@@ -0,0 +1,78 @@
+# Statistical validity and claim safety
+
+Every number you publish from gmc data — in an internal doc, a chat answer,
+or a chart card — must pass this checklist. These rules exist because QA on
+real analysis output repeatedly caught bad denominators, small-N
+generalizations, confounded comparisons, and causal overclaims before they
+reached readers. Run the checklist before handing off, not after.
+
+## Validity checklist (apply to every reported number)
+
+1. **Denominator and N on every share.** Never report a bare percentage.
+   State what the share is out of and how many that is: "34% (412 of 1,204
+   titles matching the filter)". If the denominator is a subset (analyzed
+   games, usable games), say so — `cohort.usableGames` vs the plain cohort
+   count are different denominators (see the pitfalls reference).
+2. **Counting basis named.** A tag/genre share must say whether it is
+   single-assignment (`primary_market_tag`) or multi-assignment (`tag`
+   grouping / `tags` filter). The two bases are not comparable — pitfall P9.
+3. **Observation window stated.** Every metric is a snapshot or a windowed
+   observation. State the window or snapshot date next to the number
+   ("releases 2024-01..2024-12, snapshot as of the response's
+   `meta.snapshot`/`generatedAt`"). Numbers without a window cannot be
+   reproduced or compared later.
+4. **Small-N warning.** If a group has N < 30, label the finding as
+   directional/anecdotal and do not generalize from it ("only 12 titles in
+   this bucket — treat as anecdote, not a segment truth"). Do not silently
+   drop small groups either; show them with the warning.
+5. **Effect size over bare significance.** Report the magnitude of a
+   difference, not just that one exists. On large N, tiny differences look
+   "real" but mean nothing for decisions; on small N, large-looking
+   differences may be noise. Ask: would this gap change anyone's decision?
+6. **Stratify obvious confounds before comparing groups.** Before claiming
+   "group A outperforms group B", check whether the gap survives splitting
+   by the usual suspects: publisher axis (`self_published`), price band,
+   and release year. If you cannot stratify (quota, missing dimension),
+   state the unchecked confound explicitly.
+7. **Disclose multiple comparisons.** If you scanned many tags, buckets, or
+   metrics and are reporting the extremes ("the top tag by rating"),
+   say that the winner came from a scan of K groups. Top-of-scan findings
+   are selection-biased; confirm them on an independent slice or label them
+   as hypotheses.
+
+## Claim-safety rules
+
+- **No causal verbs without causal evidence.** gmc aggregates are
+  observational. "Drives", "boosts", "causes", "leads to", "because of" are
+  off-limits for correlations; write "is associated with", "co-occurs
+  with", "titles with X tend to Y". This matches the chart-card rule that
+  titles must not make causal claims (charts reference) — apply it to prose
+  too.
+- **Label external estimates.** Any figure not computed from gmc responses
+  — units-per-review multipliers, wishlist conversion folklore, revenue
+  guesses, industry benchmarks — must be labeled as an external estimate
+  with its source, and must never be blended into gmc-derived numbers as if
+  measured.
+- **`not_collected` means not collected.** Missing research coverage,
+  skipped games, and `not_collected` markers must never be reported as zero
+  events or absent sentiment ("no complaints"). Report them as "not
+  collected" with the skipped count — see the hard rules in SKILL.md and
+  pitfall P2.
+- **Locked/preview data stays partial.** Never extrapolate what a locked or
+  preview payload "probably" contains (pitfall P3).
+
+## Compliant output example
+
+> Of the 1,204 titles released 2024-01-01..2024-12-31 with >= 10 reviews
+> (snapshot 2026-07-08), 412 (34%) carry the roguelike-deckbuilder tag
+> (multi-assignment basis: the same title also counts toward its other
+> tags' shares, so per-tag shares do not sum to 100%).
+> Median review count is 86 for these vs 54 for the rest; the gap holds
+> within the self-published stratum (78 vs 51, N=301) but not for
+> publisher-backed titles (N=23 — too few to call, directional only).
+> This is an observed association; nothing here shows the tag causes
+> higher review counts.
+
+Every share above carries a denominator, an N, a window/snapshot, and a
+named counting basis; comparisons are stratified or flagged; language stays
+associational. That is the bar for skill-produced output.

package/skill/gmc-analysis.manifest.json

@@ -0,0 +1,5 @@
+{
+  "version": "0.5.0",
+  "contentHash": "0a8b585ed7b76dab31fb468b7ff58e97a4a31a24fc00b595118aad31dadfeb60",
+  "files": 7
+}

package/src/constants.js

@@ -7,7 +7,7 @@ export const EXIT_CONFIG = 3;
 export const EXIT_API = 4;
 
 export const CLI_PACKAGE_NAME = "@witchpot/gmc";
-export const CLI_VERSION = "0.3.0";
+export const CLI_VERSION = "0.5.0";
 
 export const DEFAULT_API_BASE_URL = "https://gamemarketcopilot.com";
 export const DEFAULT_CONFIG_PATH = path.join(homedir(), ".config", "gmc", "config.json");

package/src/skill-manifest.test.js

@@ -0,0 +1,62 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import test from "node:test";
+
+import {
+  MANIFEST_PATH,
+  assertRegenAllowed,
+  computeSkillContentHash,
+  readSkillManifestVersion
+} from "../scripts/gen-skill-manifest.mjs";
+
+const FAILURE_MESSAGE =
+  "skill content changed: bump metadata.version in SKILL.md, run npm run skill:manifest (in packages/gmc-cli), and re-sync the gmc-agent-skills distribution repo (node scripts/sync-from-cli.mjs there)";
+
+function readCommittedManifest() {
+  return JSON.parse(readFileSync(MANIFEST_PATH, "utf8"));
+}
+
+test("committed skill manifest content hash matches the packaged skill content", () => {
+  const manifest = readCommittedManifest();
+  const { contentHash } = computeSkillContentHash();
+
+  assert.equal(contentHash, manifest.contentHash, FAILURE_MESSAGE);
+});
+
+test("committed skill manifest version matches SKILL.md metadata.version", () => {
+  const manifest = readCommittedManifest();
+  const skillVersion = readSkillManifestVersion();
+
+  assert.equal(manifest.version, skillVersion, FAILURE_MESSAGE);
+});
+
+test("regen rule: content change under the baseline's version is refused", () => {
+  assert.throws(
+    () =>
+      assertRegenAllowed({
+        baseline: { version: "0.5.0", contentHash: "aaa" },
+        next: { version: "0.5.0", contentHash: "bbb" }
+      }),
+    /bump the version in SKILL\.md/
+  );
+});
+
+test("regen rule: allowed on a bump, on unchanged content, and on first generation", () => {
+  // A bump (in-flight iteration keeps hitting this branch: baseline stays
+  // at origin/main's version until the bump merges).
+  assert.doesNotThrow(() =>
+    assertRegenAllowed({
+      baseline: { version: "0.4.0", contentHash: "aaa" },
+      next: { version: "0.5.0", contentHash: "bbb" }
+    })
+  );
+  // Idempotent rerun.
+  assert.doesNotThrow(() =>
+    assertRegenAllowed({
+      baseline: { version: "0.5.0", contentHash: "aaa" },
+      next: { version: "0.5.0", contentHash: "aaa" }
+    })
+  );
+  // True first generation (no committed baseline anywhere).
+  assert.doesNotThrow(() => assertRegenAllowed({ baseline: undefined, next: { version: "0.5.0", contentHash: "aaa" } }));
+});

package/src/skill.js

@@ -7,7 +7,7 @@ import { EXIT_USAGE } from "./constants.js";
 import { writeJsonError } from "./output.js";
 
 export const SKILL_NAME = "gmc-analysis";
-const SKILL_REFERENCE_FILES = ["recipes.md", "pitfalls.md", "quota.md"];
+const SKILL_REFERENCE_FILES = ["recipes.md", "pitfalls.md", "validity.md", "quota.md", "charts.md"];
 const PACKAGED_SKILL_DIR = fileURLToPath(new URL(`../skill/${SKILL_NAME}/`, import.meta.url));
 
 export function getPackagedSkillDir() {

package/src/skill.test.js

@@ -25,10 +25,19 @@ test("agents-md edition is self-contained and demotes headings", () => {
   // References must be inlined for AGENTS.md consumers without the skill dir.
   assert.match(section, /^### Recipes/m);
   assert.match(section, /^### Pitfalls and pivots/m);
+  assert.match(section, /^### Statistical validity and claim safety/m);
   assert.match(section, /^### Quota etiquette/m);
+  assert.match(section, /^### Chart cards/m);
   // Core field-test learnings must survive into the distributed edition.
   assert.match(section, /skippedReasons/);
   assert.match(section, /appearsInGames/);
+  // Validity guardrails must survive into the distributed edition.
+  assert.match(section, /Denominator and N on every share/);
+  assert.match(section, /No causal verbs without causal evidence/);
+  assert.match(section, /never mix them/);
+  // Chart attribution guardrails must survive into the distributed edition.
+  assert.match(section, /GMC database/);
+  assert.match(section, /gmc-lockup\.svg/);
 });
 
 test("skill install copies the packaged skill to a custom directory", () => {