@witchpot/gmc 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -2,7 +2,42 @@
 
 All notable changes to the Game Market Copilot CLI will be recorded here.
 
-## Unreleased
+## 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
+
+- Added `gmc tags` for tag taxonomy discovery: `gmc tags` lists the full
+  slug/name dictionary and `gmc tags --q <term> [--limit <number>]` searches
+  it. The endpoint is anonymous and unmetered, so agents can resolve a genre
+  or keyword to valid tag slugs before spending quota on `--tags` filters.
+- Split shared, pure composition and analytics helpers (resolve/cohort/
+  showcase composers, deadline filtering) out of the CLI workflow layer and
+  into the new `@witchpot/gmc-core` package, now a published dependency of
+  this CLI. No command-facing behavior change.
+- This release rides on server-side additions already live in the API:
+  - Tag filters on games search/count/aggregate/benchmark, review patterns,
+    and the marketing/creators/cohort/showcases workflows now validate and
+    canonicalize `--tags` slugs, rejecting unknown ones with a 400
+    `INVALID_TAG` error carrying `details.unknown_tags` and
+    `details.suggestions`. `gmc tags` is the recommended preflight for
+    resolving valid slugs before hitting these filters.
+  - The `market_aggregate` MCP tool gained `segment_filter`, which narrows
+    the base filter (AND) and reports `segment.matched`/`segment.ratio`
+    against the base cohort at no extra credit cost (not yet combinable
+    with `group_by`).
 
 ## 0.2.1 - 2026-07-04
 

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:
 
@@ -91,6 +95,7 @@ Re-run install/print after `npm update` to pick up newer skill versions.
 
 ```bash
 gmc schema --json
+gmc tags --q roguelike --json
 gmc update --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
@@ -107,6 +112,7 @@ when using output in agent answers.
 - `gmc status`
 - `gmc auth status`
 - `gmc schema`
+- `gmc tags`
 - `gmc games search`
 - `gmc games count`
 - `gmc games aggregate`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@witchpot/gmc",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "private": false,
   "description": "Command line tools for Game Market Copilot market research.",
   "license": "UNLICENSED",
@@ -27,6 +27,9 @@
   "engines": {
     "node": ">=20.9.0"
   },
+  "dependencies": {
+    "@witchpot/gmc-core": "^0.1.0"
+  },
   "files": [
     "bin",
     "src",

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,34 @@ for (const file of sourceFiles) {
   }
 }
 
+// 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/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,47 @@
 # gmc-analysis skill changelog
 
+## 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.4.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):
@@ -69,6 +107,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 +124,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,236 @@
+# 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. Recommended export: X 1200x675, LinkedIn 1200x627,
+   or the natural 720px card width at 2x.
+
+## 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 | 2-5 groups | Vertical column |
+| 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 |
+| 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.
+
+## 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=Instrument+Serif&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;
+    --serif: 'Instrument Serif', Georgia, 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(--serif);
+                font-size: 34px; line-height: 1.12; font-weight: 400; }
+  .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. 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