@witchpot/gmc 0.2.1 → 0.4.0

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/src/args.js

@@ -49,6 +49,7 @@ function isCommandToken(command, token) {
     return [
       "status",
       "schema",
+      "tags",
       "games",
       "reviews",
       "campaigns",

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.2.1";
+export const CLI_VERSION = "0.4.0";
 
 export const DEFAULT_API_BASE_URL = "https://gamemarketcopilot.com";
 export const DEFAULT_CONFIG_PATH = path.join(homedir(), ".config", "gmc", "config.json");
@@ -16,6 +16,8 @@ export const SUPPORTED_BETA_COMMANDS = [
   "gmc status --json",
   "gmc auth status --json",
   "gmc schema --json",
+  "gmc tags --json",
+  "gmc tags --q <term> --json",
   "gmc --version",
   "gmc update --json",
   "gmc skill install --json",
@@ -53,14 +55,7 @@ export const PROVISIONAL_BETA_COMMANDS = [
 ];
 
 export const COMPARE_FOCUSES = ["overview", "market", "reviews", "marketing", "audience", "showcases"];
-export const COMPARE_FOCUS_SECTIONS = {
-  overview: [],
-  market: [],
-  reviews: ["reviews"],
-  marketing: ["marketing", "creators", "media"],
-  audience: ["reviews", "coverage", "creators"],
-  showcases: ["showcases"]
-};
+export { COMPARE_FOCUS_SECTIONS } from "@witchpot/gmc-core";
 
 export const DEFAULT_BENCHMARK_LIMIT = "20";
 export const DEFAULT_CAMPAIGN_SIGNALS_LIMIT = "30";

package/src/help.js

@@ -25,6 +25,8 @@ Usage:
   gmc skill print --format agents-md
   gmc skill status --json
   gmc schema --json
+  gmc tags --json
+  gmc tags --q <term> --limit <number> --json
   gmc lists --json
   gmc lists create --name <name> --kind manual --json
   gmc lists games <id> --json
@@ -56,6 +58,19 @@ Usage:
   gmc showcases fit --source steam <externalId> --deadline-before <YYYY-MM-DD> --json
   gmc showcases patterns --source steam --tags <tag_slug[,tag_slug...]> --json
 
+Tag taxonomy:
+  gmc tags --json                    List the full tag dictionary (slug, name).
+  gmc tags --q <term> --json         Search tags by free-text term.
+  gmc tags --q <term> --limit <number> --json
+                                      Cap the number of matches, 1-500 (default 50).
+
+  Commands that filter by --tags (games search/count/aggregate/benchmark,
+  reviews patterns, marketing/creators/cohort/showcases workflows) reject
+  unknown tag slugs with a 400 INVALID_TAG error and a
+  details.unknown_tags / details.suggestions payload. Run gmc tags --q
+  <term> first to resolve a genre or keyword to valid slugs before
+  building a --tags filter.
+
 Binary aliases:
   gmcp and game-market-copilot run the same CLI. Use them when a shell
   alias shadows gmc (Oh My Zsh's git plugin defines gmc as

package/src/requests.js

@@ -14,6 +14,9 @@ import {
 } from "./constants.js";
 import { matches } from "./args.js";
 import { writeJsonError } from "./output.js";
+import { filterShowcasesByDeadline } from "@witchpot/gmc-core";
+
+export { filterShowcasesByDeadline };
 
 export function buildRequest(command, options, positional) {
   if (matches(command, ["status"])) {
@@ -37,6 +40,17 @@ export function buildRequest(command, options, positional) {
     };
   }
 
+  if (matches(command, ["tags"])) {
+    const q = options.q ?? options.query;
+    return {
+      path: "/api/v1/tags",
+      query: {
+        ...(q != null ? { q } : {}),
+        ...pickQuery(options, { limit: "limit" })
+      }
+    };
+  }
+
   if (matches(command, ["lists"])) {
     return {
       path: "/api/v1/lists",
@@ -886,18 +900,3 @@ function normalizeTagSlugCsv(value) {
     .filter(Boolean)
     .join(",");
 }
-
-export function filterShowcasesByDeadline(payload, deadlineBefore) {
-  if (!payload || !Array.isArray(payload.data)) return payload;
-  return {
-    ...payload,
-    data: payload.data.filter((showcase) => {
-      if (!showcase || typeof showcase !== "object" || !showcase.deadline) return false;
-      return String(showcase.deadline) <= deadlineBefore;
-    }),
-    warnings: [
-      ...(payload.warnings ?? []),
-      "deadline-before was applied client-side by the gmc CLI"
-    ]
-  };
-}

package/src/requests.test.js

@@ -39,6 +39,41 @@ test("games success-report forwards locale", () => {
   assert.deepEqual(request.query, { locale: "ja" });
 });
 
+test("tags builds the full-dictionary request plan", () => {
+  const request = buildRequestFromArgv(["tags", "--json"]);
+
+  assert.equal(request.path, "/api/v1/tags");
+  assert.deepEqual(request.query, {});
+});
+
+test("tags forwards --q as the q query param", () => {
+  const request = buildRequestFromArgv(["tags", "--q", "roguelike", "--json"]);
+
+  assert.equal(request.path, "/api/v1/tags");
+  assert.deepEqual(request.query, { q: "roguelike" });
+});
+
+test("tags accepts --query as an alias for --q", () => {
+  const request = buildRequestFromArgv(["tags", "--query", "roguelike", "--json"]);
+
+  assert.equal(request.path, "/api/v1/tags");
+  assert.deepEqual(request.query, { q: "roguelike" });
+});
+
+test("tags forwards --limit alongside --q", () => {
+  const request = buildRequestFromArgv([
+    "tags",
+    "--q",
+    "deck",
+    "--limit",
+    "10",
+    "--json"
+  ]);
+
+  assert.equal(request.path, "/api/v1/tags");
+  assert.deepEqual(request.query, { q: "deck", limit: "10" });
+});
+
 test("games detail request plan stays unchanged", () => {
   const request = buildRequestFromArgv([
     "games",

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", () => {