@witchpot/gmc 0.5.0 → 0.8.0

package/CHANGELOG.md

@@ -2,6 +2,76 @@
 
 All notable changes to the Game Market Copilot CLI will be recorded here.
 
+## 0.8.0 - 2026-09-14
+
+For npm users this release lands together with 0.7.0's content, because
+0.7.0 was never published to the registry (npm goes 0.6.0 -> 0.8.0). It also
+requires `@witchpot/gmc-core` 0.2.0, which ships to npm in the same release
+cycle — publish core FIRST, or `gmc showcases history` fails at startup on a
+missing export (see gmc-core's own 0.2.0 changelog entry).
+
+- New `--ai-disclosure <disclosed|absent|unconfirmed>` filter on the games
+  search/count/aggregate commands (NAK-773), forwarded verbatim and
+  case-sensitively as the `aiDisclosure` query param, plus
+  `--group-by ai_disclosure` (which cross-tabs with `release_month`). `absent`
+  means no disclosure block was observed on the store page, never that a title
+  uses no generative AI; `unconfirmed` includes titles never checked.
+- Bundled `gmc-analysis` skill bumped to 0.15.0 with an "AI disclosure state"
+  section covering those values and how to report them.
+
+- New command `gmc lists resolve <id> --json` (NAK-525): computes (or reuses)
+  the materialized resolution a natural-language list definition needs before
+  its games can be read. `gmc lists games <id>` answers 409
+  RESOLUTION_REQUIRED until it has run. Costs 2 credits every call, including
+  on a reuse, and never changes membership.
+- New command `gmc lists materialize <id> --confirm --json` (NAK-525): freezes
+  a filter list's current members, so it stops re-evaluating its definition.
+  Destructive-adjacent and undone only by discarding the frozen rows, so
+  `--confirm` is required and the call is refused without it before anything is
+  written or charged. Optional `--expected-revision <n>` is the compare-and-swap
+  covering the whole resolve-then-materialize window.
+- `gmc lists games <id>` now forwards `--cursor`. It was previously accepted
+  and silently dropped, which walks a resolution-backed list by offset while
+  the caller believes it is following the cursor.
+- `--help` documents the version 2 query envelope accepted by
+  `gmc lists create --kind filter --filter '<json>'`, including the rule that
+  `structured` decides membership and `total_kind` says whether the reported
+  total is an exact count.
+
+## 0.7.0 - 2026-08-06
+
+- New command `gmc games more-like-this --source steam <externalId>
+  [--country <de|fr|gb|jp|kr|us>] --json` (NAK-459): the games Steam showed
+  in a title's store-page "More Like This" carousel, for one storefront
+  country. Omitting `--country` sends no country at all so the server
+  applies the shared `us` default; `--country` is validated locally against
+  the six collected storefronts before the request goes out.
+- This release carries TWO skill versions' worth of content, because skill
+  0.7.0 was never published: skill 0.7.0 (NAK-92 / NAK-240) added the
+  showcase fit + history workflows and their directory-link guardrails, and
+  skill 0.8.0 (NAK-459) adds the "Steam More Like This neighbours" section.
+  Its guardrails: carousel `position` is Steam's display order and never a
+  similarity score; `observed_empty` (collected, carousel empty) must be
+  told apart from `not_observed` (not collected yet), and neither reported
+  as "this game has no similar games"; a stale observation should be dated
+  rather than dropped; candidates with `resolved: false` stay in the set as
+  unresolved.
+- Agents on the MCP surface get the equivalent `more_like_this` tool (19th
+  published tool); the CLI and MCP share one read model, so countries,
+  default, bounds, and availability semantics cannot drift between them.
+
+## 0.6.0 - 2026-07-17
+
+- gmc-analysis skill v0.6.0: new "Product documentation (gmc-docs)"
+  section in SKILL.md pointing agents at docs.gamemarketcopilot.com for
+  product features, setup, plans/credits, API/CLI/MCP usage, and
+  methodology definitions, via the read-only Docs MCP or plain-HTTP
+  llms.txt / per-page .md fetch (no second MCP connection required);
+  answers drawing on docs must cite the canonical URL. The skill remains
+  the source of truth for statistical validity, claim safety, and chart
+  guidance. references/quota.md now points current plan limits at the
+  live pricing page.
+
 ## 0.5.0 - 2026-07-13
 
 - gmc-analysis skill v0.5.0 (NAK-190): new "Saved Game Lists" guidance in

package/README.md

@@ -122,6 +122,9 @@ when using output in agent answers.
 - `gmc games success-report`
 - `gmc campaigns signals`
 - `gmc games topics`
+- `gmc games language-topics`
+- `gmc games review-history`
+- `gmc games more-like-this`
 - `gmc games compare`
 - `gmc games benchmark`
 - `gmc reviews patterns`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@witchpot/gmc",
-  "version": "0.5.0",
+  "version": "0.8.0",
   "private": false,
   "description": "Command line tools for Game Market Copilot market research.",
   "license": "UNLICENSED",
@@ -28,7 +28,7 @@
     "node": ">=20.9.0"
   },
   "dependencies": {
-    "@witchpot/gmc-core": "^0.1.0"
+    "@witchpot/gmc-core": "^0.2.0"
   },
   "files": [
     "bin",

package/skill/gmc-analysis/CHANGELOG.md

@@ -1,5 +1,195 @@
 # gmc-analysis skill changelog
 
+## 0.15.0 - 2026-09-14
+
+- New "AI disclosure state" section in SKILL.md (NAK-773): the tri-state
+  Steam store AI-disclosure read, how to filter on it
+  (`--ai-disclosure` / `filter.ai_disclosure`), group by it
+  (`--group-by ai_disclosure`, cross-tabs with `release_month`), and read one
+  title's state from `detail.aiDisclosure`.
+- Adds the interpretation guardrails as honesty rules: `absent` is an
+  observation that no disclosure block was found, never proof a title uses no
+  generative AI; `unconfirmed` means not yet successfully observed (it includes
+  titles never checked) and must be reported as its own bucket rather than
+  folded into `absent`; `observedAt` is the read date, not the release date;
+  `aiDisclosure: null` means the read model was unreachable, not "not
+  disclosed".
+- Records that `cohort_review_categories` and `compare_as_of` refuse the filter
+  outright, so disclosure cohorts are sized with `market_aggregate`.
+
+## 0.14.0 - 2026-08-20
+
+- New "Query-backed lists (structured plus natural language)" section in
+  SKILL.md (NAK-525): documents the version 2 query envelope, the rule that
+  `structured` decides membership while `semanticQuery` only orders results
+  inside it under the default `rank` mode, and the `total_kind` vocabulary
+  (`exact` / `approximate` / `at_least` / `lexical_only` / `clipped`) with the
+  honesty rule that anything but `exact` must be reported as approximate.
+- Adds the two new tools to the Game List inventory: `resolve_game_list`
+  (non-destructive, answers `RESOLUTION_REQUIRED`, 2 credits every call
+  including a reuse) and `materialize_game_list` (freezes membership, requires
+  `confirm: true`, 2 credits, never speculative). CLI equivalents:
+  `gmc lists resolve <id>` and `gmc lists materialize <id> --confirm`.
+- New sharp edge: `market_aggregate` / `cohort_review_categories` /
+  `cohort_evidence` reject a `semanticQuery` list with
+  `SEMANTIC_LIST_UNSUPPORTED_FOR_TOOL`, uniformly across `semanticMode`; a
+  structured-only v2 envelope behaves exactly like a flat filter.
+- Records `membership`, `definition_revision` and `last_resolved_at` on the
+  list read tools, and what a frozen (`snapshot`) list does.
+- Warns that `sort` and `as_of` are refused (not ignored) when reading a
+  `semanticQuery` list or a frozen one.
+- Documents the resolve conflict outcomes (`CONFLICT` /
+  `definition_revision_mismatch`, `NOT_FOUND`, `SNAPSHOT_IS_FROZEN`) for a list
+  edited, deleted or frozen while a resolve is running.
+
+## 0.13.0 - 2026-08-20
+
+- New "Per-family collection status" section in SKILL.md (NAK-596): documents
+  the new MCP-only `game_collection_status` tool — no CLI command yet, same
+  deferred posture as `game_language_support` (NAK-571) — agent-surface
+  parity for `GET /api/v1/games/:appid/collection-status` (NAK-444).
+- Adds the interpretation guardrails as honesty rules: `unknown` differs from
+  `not_collected` in kind, not degree, and must never be restated as
+  uncollected; `available: false` and the `collection_status_unavailable`
+  warning token are coupled one-for-one; `requestable` states only whether
+  requesting analysis routes demand to that family today (only `research`
+  is), never a statement about any other family's schedule; the tool is
+  read-only and never enqueues collection work; an unknown appid charges the
+  weight-1 credit before returning `NOT_FOUND`.
+- MCP-only mapping updated: per-family collection status ->
+  `game_collection_status`.
+
+## 0.12.0 - 2026-08-12
+
+- Adds "Which review count you are looking at" (NAK-531): Steam returns two
+  review totals depending on `purchase_type`, and they can differ by orders
+  of magnitude. `purchase_type=all` is GMC's headline current total and is
+  served by `game_profile` as `detail.reviewCounts`; every plain `reviews`
+  field elsewhere stays the narrower `purchase_type=steam` family.
+- Records the honesty rules that go with it: name the family and the
+  observation date with any count; `allAvailable: false` means not collected
+  rather than zero; compare the families only through
+  `steamAtAllObservation`, because the top-level `steam` observation can be
+  newer than `all`; derive a positive rate inside one family; never splice
+  the families into one series, so a steam history's last point being
+  smaller than the all-family headline is not a decline; and neither family
+  is sales.
+
+## 0.11.0 - 2026-08-10
+
+- MCP-only mapping extended with the publisher/developer surface (NAK-383):
+  `entity_resolve` (raw Steam publisher/developer string -> stable
+  `entityId`) and `entity_profile` (that entity's portfolio, composition,
+  release cadence and audience footprint). There is no CLI equivalent yet,
+  so the entry states the resolve-then-profile order explicitly rather than
+  mapping from a command.
+- Adds the interpretation guardrails as honesty rules: resolve before
+  profiling because a game record credits names and one entity commonly has
+  several raw spellings, so a name-keyed lookup omits the titles credited to
+  the siblings; `resolved: null` means that exact case-sensitive,
+  whitespace-significant string is unknown to the master tables and never
+  that the entity has no titles; `aggregatesAvailability: not_collected`
+  means the aggregates have not been computed yet, so the block is absent
+  rather than zero, and never that the studio has published nothing (the
+  live `pagination.total` is still the real title count); a null
+  `totalFollowers` is not collected rather than zero, and follower counts
+  can never be summed across platforms.
+
+## 0.10.0 - 2026-08-09
+
+- New "Review-count history and the events around it" section in SKILL.md
+  (NAK-428): documents `gmc games review-history` (MCP:
+  `game_review_history`), and states that it has no flags because the
+  endpoint has no query parameters — the full daily series is always
+  returned and the agent windows it.
+- Adds the interpretation guardrails as honesty rules: scale by date and
+  never by array index because collection has real gaps; the series is
+  published-run-only and contamination-filtered at a 2% tolerance, so
+  differences are safe to report but the last point can lag the headline
+  review count; an empty series is no collected history, not a review count
+  of zero; empty `data.events` / `data.discountWindows` are collection
+  states, never "no announcements" or "never discounted"; announcements are
+  official-feed only and capped at the most recent 1000 items; a discount
+  window is an observed >=20%-threshold state, not an exact Steam sale
+  period, whose `endDate` is the first below-threshold observation and is
+  not part of the window (with gaps in the observations, the actual last
+  discounted day cannot be inferred from it) and whose `discountPercent` is
+  the opening observation; events support temporal comparison only, never
+  causal attribution.
+- MCP-only mapping updated: review-count history with its
+  lifecycle/announcement/discount context -> `game_review_history`.
+
+## 0.9.0 - 2026-08-08
+
+- New "Review topics by review language" section in SKILL.md (NAK-455):
+  documents `gmc games language-topics` (MCP: `game_language_topics`), its
+  two flags (`--min-reviews` 10-200, `--include-insufficient`), and the
+  fact that this is the whole parameter surface because it is the API's.
+- Adds the interpretation guardrails as honesty rules: read
+  `data.evidenceState` first and never report `insufficient_evidence` or
+  `not_analyzed` as zero; the population is the analyzed subset (about
+  2,500 titles), not the Steam catalog; review language is never a country,
+  region, market, or culture; observed `counts`/`rates` and sample-expanded
+  `estimates` stay separate; name which of the four denominators a
+  percentage is over; date every claim with `data.snapshot`; `coverage`
+  survives the `reviews.topicLanguages.full` plan lock.
+- MCP-only mapping updated: review topics by review language ->
+  `game_language_topics`.
+
+## 0.8.0 - 2026-08-06
+
+- New "Steam \"More Like This\" neighbours" section in SKILL.md (NAK-459):
+  documents `gmc games more-like-this` (MCP: `more_like_this`), the six
+  collected storefront countries with the `us` default, and its use as a
+  cohort seed that feeds `coverage_check` and the cohort workflows.
+- Adds the interpretation guardrails as honesty rules: `position` is
+  Steam's display order and never a similarity score or ranking;
+  `observed_empty` (carousel collected and empty) must be told apart from
+  `not_observed` (not collected yet), and neither may be reported as "this
+  game has no similar games"; `stale: true` means date the claim rather
+  than drop it or present it as current; candidates with
+  `resolved: false` stay in the set as unresolved rather than being
+  silently dropped.
+- MCP-only mapping updated: single-title drill-down now also lists Steam
+  store-page neighbours -> `more_like_this`.
+
+## 0.7.0 - 2026-07-20
+
+- New "Showcase workflows (fit + history)" section in SKILL.md (NAK-92 /
+  NAK-240): documents `gmc showcases history` (MCP: `showcase_history`)
+  alongside `showcases fit`, and the chain "similar games -> which
+  showcases did they attend -> next edition deadline" via the appearance
+  rows' `directory.next_edition`. Adds the interpretation guardrails as
+  honesty rules: missing `directory` = "not linked", never "never
+  participated"; a steam_event source-unavailable warning means
+  research-source-only history, never zero participations; absent
+  next-edition data means "window unknown", and the submission-close date
+  must be checked against today before recommending a submission. Documents
+  the transport casing split (CLI camelCase `nextEdition.submissionCloses`
+  vs MCP snake_case `next_edition.submission_closes`) and that plan-limited
+  responses redact directory links (indeterminate, not "unlinked" —
+  check warnings first).
+- MCP-only mapping updated: showcases now map to both `showcase_fit`
+  (submission candidates) and `showcase_history` (participation history).
+
+## 0.6.0 - 2026-07-17
+
+- New "Product documentation (gmc-docs)" section in SKILL.md:
+  points at the public docs site (`https://docs.gamemarketcopilot.com`) for
+  product features, setup, plans/credits, API/CLI/MCP usage,
+  troubleshooting, and methodology definitions; documents the read-only
+  Docs MCP (`search_docs`/`get_page`/`list_pages`/`get_navigation`, no
+  auth) for clients that support a second MCP connection, and `llms.txt` /
+  per-page `.md` fetch over plain HTTP as the no-second-MCP-required
+  fallback; requires citing the canonical docs URL when an answer draws on
+  it. Keeps the distinction crisp: `gmc-docs` is product documentation, not
+  market evidence; this skill remains the source of truth for statistical
+  validity, claim safety, and chart guidance, and the docs never override
+  it.
+- `references/quota.md`: one-line pointer to the published plan/credit page
+  (`https://docs.gamemarketcopilot.com/plans.md`) alongside the existing
+  "treat as indicative" caveat.
+
 ## 0.5.0 - 2026-07-13
 
 - New "Saved Game Lists" section in SKILL.md, plus recipe R5 in