@witchpot/gmc 0.5.0 → 0.8.0

package/src/help.js

@@ -29,8 +29,11 @@ Usage:
   gmc tags --q <term> --limit <number> --json
   gmc lists --json
   gmc lists create --name <name> --kind manual --json
-  gmc lists games <id> --json
+  gmc lists create --name <name> --kind filter --filter '<json>' --json
+  gmc lists games <id> --limit <number> --cursor <cursor> --json
   gmc lists add <id> --app-ids <appid[,appid...]> --json
+  gmc lists resolve <id> --json
+  gmc lists materialize <id> --confirm --json
   gmc games search --source steam --query <text> --json
   gmc games count --source steam --release-year <year> --reviews-gt <number> --json
   gmc games aggregate --source steam --metric count,median_reviews --group-by release_year --json
@@ -44,6 +47,10 @@ Usage:
   gmc campaigns signals --source steam <externalId> --json
   gmc games compare --source steam <externalId> <externalId...> --focus market --json
   gmc games topics --source steam <externalId> --json
+  gmc games language-topics --source steam <externalId> --json
+  gmc games language-topics --source steam <externalId> --min-reviews <number> --include-insufficient --json
+  gmc games review-history --source steam <externalId> --json
+  gmc games more-like-this --source steam <externalId> --country <country> --json
   gmc reviews patterns --source steam --tags <tag_slug[,tag_slug...]> --reviews-min <number> --json
   gmc reviews patterns --source steam --tags <tag_slug[,tag_slug...]> --sample-size <number> --preset summary --json
   gmc marketing patterns --source steam --tags <tag_slug[,tag_slug...]> --reviews-min <number> --json
@@ -56,7 +63,12 @@ Usage:
   gmc cohort brief --source steam --list <id> --json
   gmc showcases search --query <text> --json
   gmc showcases fit --source steam <externalId> --deadline-before <YYYY-MM-DD> --json
+  gmc showcases history --source steam <externalId> --json
   gmc showcases patterns --source steam --tags <tag_slug[,tag_slug...]> --json
+  gmc steam trend-stories --locale en --json
+  gmc steam tag-trends --view featured --json
+  gmc steam tag-trends --view table --sort release_share_delta --order desc --json
+  gmc steam tag-trends --view tag --tag <tag_slug> --json
 
 Tag taxonomy:
   gmc tags --json                    List the full tag dictionary (slug, name).
@@ -71,11 +83,168 @@ Tag taxonomy:
   <term> first to resolve a genre or keyword to valid slugs before
   building a --tags filter.
 
+Review topics by review language:
+  gmc games language-topics --source steam <externalId> --json
+                                      One game's review topics broken down by
+                                      the language each review was written in.
+  --min-reviews <number>              Evidence floor applied to the distinct
+                                      review count behind a row, 10-200
+                                      (server default 30).
+  --include-insufficient              Also return rows below that floor, capped
+                                      by the server, with coverage reporting
+                                      the cut.
+
+  Read data.evidenceState first. ready means at least one topic x language row
+  cleared the floor; insufficient_evidence means rows exist but none cleared
+  it; not_analyzed means no rows exist. The last two are thin evidence and no
+  data — never report either as zero mentions or absent sentiment.
+
+  Coverage is the analyzed subset only (about 2,500 titles today), selected
+  for review analysis rather than sampled from the catalog. It is not a
+  full-catalog population measurement, so do not extrapolate a share of Steam
+  from it.
+
+  Review language is the language a review was written in. It is not a
+  country, a region, a market, or a culture, and must not be reported as one.
+
+  data.rows[].counts and .rates are observed; data.rows[].estimates are
+  sample-expanded and carry samplingWeightMethod. Keep the two apart, and date
+  every claim with data.snapshot (periodStart/periodEnd/analysisVersion/
+  generatedAt).
+
+  Examples:
+    gmc games language-topics --source steam 730 --json
+    gmc games language-topics --source steam 730 --min-reviews 50 --json
+    gmc games language-topics --source steam 730 --include-insufficient --json
+
+Review-count history:
+  gmc games review-history --source steam <externalId> --json
+                                      One game's full daily total-review
+                                      series, plus the collected lifecycle and
+                                      announcement events and the observed
+                                      major-discount windows beside it.
+
+  There are no parameters beyond the external id. The whole series is always
+  returned; window it yourself and state the window you chose. A --range,
+  --from, --to, --limit or --locale is rejected as a usage error rather than
+  ignored, so a narrowing you asked for can never be silently dropped.
+
+  data.series is published-run-only and contamination-filtered: an observation
+  more than 2% below the highest earlier one for the same game is withheld as
+  invalid. Differences taken from it are safe to report, but the newest point
+  can lag the game's headline review count until that day's run is published.
+  Collection can have real gaps, so scale by date and never by array index.
+
+  Empty data.events or data.discountWindows mean no events were COLLECTED for
+  those sources — never that no releases, announcements, or discounts
+  happened. Announcements come from official Steam feeds, capped at the most
+  recent 1000 items, and are clustered to one event per UTC day.
+
+  A discount window is an observed state at the >=20% collection threshold,
+  not an exact Steam sale period. endDate is EXCLUSIVE (the first observation
+  back below the threshold), a null endDate means no end observed yet, and
+  discountPercent is the opening observation.
+
+  Events support temporal comparison only. A review-count movement beside an
+  event is co-occurrence, never attribution.
+
+  Examples:
+    gmc games review-history --source steam 730 --json
+
+Steam tag trends:
+  gmc steam tag-trends --view <view> --json
+                                      Tag supply trends over one frozen monthly
+                                      generation: how the share of new paid
+                                      Steam releases carrying each tag moved
+                                      between two three-month periods.
+  --view <view>                       featured | board | group | table | tag.
+                                      Defaults to featured.
+  --family <family>                   Taxonomy family filter (board/group/table).
+  --q <term>                          Substring over tag slug and name
+                                      (board/group/table).
+  --supply-direction <direction>      up | down | unresolved | insufficient
+                                      (board/group/table).
+  --sort <key>                        release_share_delta | current_share |
+                                      known_members | median_reviews | slug
+                                      (table only).
+  --order <asc|desc>                  Table sort direction (table only).
+  --limit <number>                    group 1-50, table 1-100.
+  --cursor <cursor>                   Continuation token (group/table).
+  --tag <tag_slug>                    Required for --view tag.
+
+  Parameters are allowlisted per view and fail closed. Passing one the view
+  does not accept is a 400 naming it, not a filter that is quietly ignored, so
+  a narrowing you asked for can never be dropped while the answer looks right.
+
+  Read data.status and data.readiness before quoting anything. status "stale"
+  means no newer generation published: the payload keeps its ORIGINAL asOf and
+  the values that were truthful then, so date every claim by data.asOf rather
+  than by when you ran the command. readiness "limited" is a successful
+  partial-data answer, not an error.
+
+  Report release share as the [lower, upper] interval. The width is UNMEASURED
+  titles, not noise: unknownTagMembers are titles with no complete tag
+  observation and are never titles known to lack the tag. A
+  releaseShareDifferenceRange containing 0 means the data cannot separate the
+  two periods.
+
+  All four directions are measurements. "unresolved" means the difference
+  interval spans zero and "insufficient" means the tag is below the evidence
+  floor — neither is missing data and neither is "no change".
+
+  Every observed* field is computed over current.observedReviewMembers titles,
+  not over the whole cohort; quote that denominator. item.titles is a bounded
+  display sample, not the tag's membership (use current.knownMembers).
+
+  Before the first generation publishes, the endpoint answers 404
+  TAG_TRENDS_UNAVAILABLE. That is the documented pre-publication state, not an
+  outage and not worth retrying on a schedule.
+
+  Examples:
+    gmc steam tag-trends --view featured --json
+    gmc steam tag-trends --view board --family mechanic --q cozy --json
+    gmc steam tag-trends --view table --sort current_share --limit 50 --json
+    gmc steam tag-trends --view tag --tag cozy --json
+
 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
   'git merge --continue').
 
+Query-backed lists (--kind filter):
+
+  --filter takes the games API's camelCase filter object, e.g.
+  --filter '{"tags":["cozy"],"reviewsMin":500}'
+
+  It also accepts the version 2 query envelope, which pairs structured
+  conditions with an optional natural-language one:
+
+    {"version":2,"mode":"query",
+     "structured":{"tags":["cozy"],"reviewsMin":500},
+     "semanticQuery":"games about running a shop",
+     "semanticMode":"rank"}
+
+  structured decides membership. semanticQuery only orders results inside
+  that universe under semanticMode "rank" (the default); under "narrow" it
+  also narrows membership, and the reported total is then approximate or a
+  floor rather than an exact count. Read total_kind in the response before
+  quoting any number as exact.
+
+  A list with a semanticQuery needs a resolution before its games can be
+  read: "gmc lists games <id>" answers 409 RESOLUTION_REQUIRED until you run
+  "gmc lists resolve <id>". Resolve costs 2 credits every time, including
+  when an existing resolution is reused, and it never changes membership.
+
+  "gmc lists materialize <id> --confirm" FREEZES the list's current members.
+  After it the list no longer follows its definition, and the only way back
+  is to discard the frozen rows. It costs 2 credits, requires --confirm, and
+  takes an optional --expected-revision <n> compare-and-swap so a definition
+  edit landing after your resolve fails the call instead of freezing the
+  wrong query. A definition using catalogAsOf cannot be frozen at all --
+  400 SNAPSHOT_DEFINITION_UNSUPPORTED, nothing written, and retrying will
+  never succeed: a snapshot is a fixed set of games, while that predicate is
+  re-evaluated against a growing availability history. Read the list live.
+
 Supported commands:
 ${SUPPORTED_BETA_COMMANDS.map((command) => `  ${command}`).join("\n")}
 
@@ -113,6 +282,35 @@ Filters:
   --coverage <list>           Research coverage levels: basic, partial, full.
                               Use --coverage full,partial to keep only games
                               with collected analysis data.
+  --has-demo <true|false>     Filter on whether the app has a linked demo in
+                              app_demo_map. false means no demo linkage was
+                              observed in collected appdetails, not confirmed
+                              absence.
+  --event-name <slug>         Restrict to the current participants of one
+                              Steam event (a steam_events.event_name slug).
+                              Membership is resolved at query time, so the
+                              cohort follows collection updates. Unknown slugs
+                              return INVALID_EVENT with suggestions; list
+                              valid slugs at GET /api/v1/events.
+  --catalog-as-of <date>      YYYY-MM-DD. Keep only titles Game Market Copilot
+                              had NOT observed as delisted on that date. Not a
+                              snapshot dial: --as-of picks which metrics are
+                              read, this picks which titles exist, and the two
+                              combine. Incomplete on purpose -- a title with no
+                              availability observation by that date is KEPT, so
+                              a real-data result carries the warning
+                              catalog_as_of_observation_bounded (plus
+                              catalog_as_of_predates_coverage when the date is
+                              older than the observation window) and is not a
+                              complete historical catalog. A static-fixture
+                              result carries catalog_as_of_filter_unavailable
+                              instead: there is no availability history behind
+                              fixtures, so the filter was not applied at all.
+  --ai-disclosure <value>     disclosed, absent, or unconfirmed. absent means
+                              no AI-use disclosure was observed in collected
+                              data -- not confirmed non-use. unconfirmed means
+                              Game Market Copilot has not yet successfully
+                              observed a disclosure state either way.
 
 Sorting:
   --sort <key>                reviews_desc, reviews_asc, rating_desc,
@@ -134,11 +332,20 @@ Count and aggregation:
   Use gmc games count when you only need the number of matching games.
   Use gmc games aggregate for grouped metrics such as count by year,
   median reviews by year, or count by an explicit price/review/rating bucket.
+  Add --as-of to read a past published snapshot, and --compare-as-of to get a
+  per-app-paired comparison between two dates in data.comparison. Report the
+  comparison's exclusions, paired_beyond_lookback and insufficient_coverage
+  rather than inferring a trend from them. --compare-as-of does not support
+  --group-by tag, primary_market_tag, or ai_disclosure, nor the
+  --ai-disclosure filter. It DOES combine with --event-name and
+  --catalog-as-of: the comparison cohort applies the same Steam event
+  participation and catalog-availability predicates as the rows beside it.
 
 Examples:
   gmc games search --source steam --release-year 2025 --reviews-min 1000 --json
   gmc games count --source steam --release-year 2025 --reviews-gt 1000 --json
   gmc games aggregate --source steam --metric count,median_reviews --group-by release_year --reviews-gt 1000 --json
   gmc games aggregate --source steam --metric count --group-by price_bucket --bucket price:0,5,10,20,40 --json
+  gmc games aggregate --source steam --metric count --group-by release_year --as-of 2026-08-01 --compare-as-of 2026-06-01 --json
 `);
 }

package/src/index.js

@@ -37,5 +37,6 @@ export {
   composeReviewPatternsPayload,
   composeResolvePayload,
   composeShowcaseFitPayload,
+  composeShowcaseHistoryPayload,
   executeRequestPlan
 } from "./workflows.js";