@witchpot/gmc 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -2,6 +2,88 @@
 
 All notable changes to the Game Market Copilot CLI will be recorded here.
 
+## 0.11.0 - 2026-10-27
+
+- `gmc games follower-history <appid>`: observed Steam follower series (same window flags as `price-history`). MCP: `game_follower_history`.
+- `gmc games events <appid> [--include rank_series]`: Steam event participations with observed ranks and shelves. MCP: `game_steam_events`.
+- The bundled `gmc-analysis` skill 0.17.0 covers both commands, and the
+  optional `positiveReviews` field on `gmc games review-history` points (state
+  a rate as `positiveReviews / totalReviews` when it is present).
+
+- New `gmc games price-history <appid>` and `gmc games screenshot-labels
+  <appid>` commands (NAK-934, Provisional), the same plain-appid shape as
+  `gmc games ai-disclosure`. `price-history` returns the observed Steam
+  storefront price on every observed day (major currency units, with
+  discount, currency and store country) and takes `--range 7d|1m|1y|all`
+  (default `all`) or `--from`/`--to` (`YYYY-MM-DD`, real calendar dates,
+  `--from` on or before `--to`), never both; a bad window is a usage error
+  before any request. Days without an observation
+  are absent, never filled, and a price never implies sales.
+  `screenshot-labels` returns one set of visual labels per Steam store
+  screenshot and takes no flags. The labels are model output, not Steam
+  data. `docs/cli-use-cases.md` and `docs/agent-usage.md` cover both.
+
+- Not shipped here: the bundled `gmc-analysis` skill does not mention the
+  two new commands yet. It is a separately versioned artifact with its own
+  manifest gate, so its coverage follows in its own change.
+
+- New `gmc roblox saved | save | remove` commands (NAK-723, Provisional),
+  mapping the saved-experiences surface 0.10.0 recorded as "not yet
+  mapped". `gmc roblox saved --json` lists the workspace's saved
+  experiences resolved for one chart, country and cutoff (`--country`,
+  `--device`, `--sort`, `--as-of`, `--eligibility-days`); `gmc roblox save
+  <universeId>` and `gmc roblox remove <universeId>` change the set and
+  take no flags at all, refusing a scope flag rather than ignoring it.
+
+  Unlike the five read commands these are workspace-scoped: they need an
+  API key or CLI credential and answer 401 without one, which is not an
+  empty saved list. They charge no credits — saving is workspace metadata,
+  not analytics — and the paid-plan gate still applies.
+
+  Saved membership is scope-independent: the flags on `saved` decide which
+  of `in_scope` / `out_of_scope` / `not_tracked` each row is in, never
+  which rows are listed. Both writes are idempotent and report the state
+  that now holds, so `changed: false` is success rather than a write to
+  retry. Universe ids travel as decimal strings into the request body as
+  well as the path, and the CLI rejects a spelling the server would reject
+  before any request is sent.
+
+  `docs/cli-use-cases.md` (new case 70) and `docs/agent-usage.md` now cover
+  the saved commands alongside the read family.
+
+- The 0.10.0 entry below is left exactly as published. Its "not yet
+  mapped" line was true of 0.10.0 and is corrected by this entry rather
+  than edited in place, matching how 0.8.0 recorded the 0.7.0 registry gap:
+  a published entry describes the release users installed, so amending one
+  would make the repo disagree with the tarball already on npm.
+
+- Not shipped here: the bundled `gmc-analysis` skill still documents the
+  Roblox read family only. The skill is a separately versioned artifact
+  with its own manifest gate, so its Roblox-saved coverage and version bump
+  follow in their own change.
+
+## 0.10.0 - 2026-09-22
+
+- New `gmc roblox` command family (NAK-715, Provisional): `charts` (one
+  recorded ranking cohort as of a cutoff), `experiences` (the tracked
+  catalog with filters, sorts and signed-cursor pagination), `experience
+  <universeId>` (one experience with per-metric observation times),
+  `history <universeId> --granularity hourly|daily` (retained observations
+  with explicit gaps), and `coverage` (the configured cohort matrix with
+  per-dimension freshness). Universe ids are decimal strings end to end —
+  they are never Steam appids, and the commands reject one. The Roblox
+  surface went live in production on 2026-09-22 (NAK-725); the commands
+  stay Provisional until the surface has been through a broader real-data
+  smoke period.
+
+- The Roblox read endpoints reject impossible calendar dates in every
+  offset spelling (`as_of=2026-02-31T12:00:00+09:00` is now a 400 naming
+  the nonexistent date instead of silently answering for March 3), and
+  history gap counts always reconcile with the expected point count.
+
+- Not yet mapped: the saved-experiences surface (`/api/v1/roblox/saved`,
+  NAK-723) is live over REST and MCP; a CLI mapping will follow.
+
 ## 0.9.0 - 2026-09-16
 
 - New `--release-status <released|upcoming|tba>` filter on the games

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@witchpot/gmc",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "private": false,
   "description": "Command line tools for Game Market Copilot market research.",
   "license": "UNLICENSED",

package/skill/gmc-analysis/CHANGELOG.md

@@ -1,5 +1,27 @@
 # gmc-analysis skill changelog
 
+## 0.17.0 - 2026-10-08
+
+- Review-count history (NAK-934): each `series[]` point can carry the
+  optional `positiveReviews`, the positive-review count observed on the same
+  row, beside the optional `ratingPercent`. Both are absent, never zero, when
+  the row carried no usable value. New guardrail: state a rate as
+  `positiveReviews / totalReviews` when the count is present, because
+  `ratingPercent` is rounded to one decimal (1,999 of 2,000 reads 100.0);
+  without the count, a `100.0` on 2,000 or more reviews is possibly rounded
+  and is never reported as "no negative reviews".
+- New "Steam follower history" section: `gmc games follower-history <appid>`
+  (MCP: `game_follower_history`), its `--range` or `--from`/`--to` window
+  (never both), and the guardrails: observed days only, followers are not
+  wishlists or sales, `not_collected` is a collection state, truncation
+  drops the oldest points.
+- New "Steam event participation" section: `gmc games events <appid>
+  [--include rank_series]` (MCP: `game_steam_events`), with the guardrails:
+  ranks and shelves are observed event-page state, not an official ranking;
+  an absent block or an empty list is a collection state; the rank series is
+  raw and never resampled.
+- MCP-only mapping updated with both tools.
+
 ## 0.16.0 - 2026-09-16
 
 - New "Disclosure text and change history" subsection under "AI disclosure

package/skill/gmc-analysis/SKILL.md

@@ -8,7 +8,7 @@ description: >-
   or campaigns that GMC can answer — including turning results into
   publish-ready branded chart cards.
 metadata:
-  version: 0.16.0
+  version: 0.17.0
 ---
 
 # GMC Analysis
@@ -59,7 +59,9 @@ applies identically. Mechanics map as follows:
   its lifecycle/announcement/discount context (`games review-history`) ->
   `game_review_history`; per-title AI-disclosure text and change history
   (`games ai-disclosure`) -> `game_profile` with `ai_disclosure` in
-  `sections`.
+  `sections`; Steam follower history (`games follower-history`) ->
+  `game_follower_history`; Steam event participation (`games events`) ->
+  `game_steam_events` (`include: ["rank_series"]` for the rank series).
 - Per-family collection status ("has GMC actually collected X for this
   game?") has no CLI command yet and is MCP-only: `game_collection_status`
   (see the dedicated section below).
@@ -413,6 +415,13 @@ Field paths differ by surface: the CLI and REST wrap the payload, so read
 the same fields at the top level. The guardrails below name the CLI path;
 drop the `data.` prefix over MCP.
 
+Each `data.series[]` point carries `date` and `totalReviews`, and two
+OPTIONAL fields: `ratingPercent` (the positive-review percentage observed on
+that row, 0-100, rounded to one decimal) and `positiveReviews` (the
+positive-review count observed on that row, 0 to `totalReviews`). Absent
+means the row carried no usable value; neither is ever zero-filled, and a
+returned `0` is a real observation.
+
 Interpretation guardrails (honesty rules, not suggestions):
 
 - **Scale by date, never by array index.** Collection has real gaps, so two
@@ -439,9 +448,67 @@ Interpretation guardrails (honesty rules, not suggestions):
   day from it. `endDate: null` means no end has been observed yet;
   `discountPercent` is the opening observation, not the deepest or final
   depth.
+- **State a rate from the count when it is there.** `ratingPercent` is
+  rounded to one decimal, so 1,999 positive of 2,000 reads `100.0`. When
+  `positiveReviews` is present, compute the rate as
+  `positiveReviews / totalReviews`. When it is absent and `ratingPercent` is
+  `100.0` on `totalReviews` of 2,000 or more, treat the 100 as possibly
+  rounded (anything from 99.95% up): say "about 100% (rounded)", never "no
+  negative reviews". Below 2,000 reviews a `100.0` is exact, because one
+  negative review already reads 99.9 or less.
 - **Temporal comparison only.** "Reviews rose in the week after the update"
   is a claim you can make; "the update caused the rise" is not.
 
+## Steam follower history
+
+`gmc games follower-history <appid> [--range 7d|1m|1y|all] [--from YYYY-MM-DD] [--to YYYY-MM-DD] --json`
+(MCP: `game_follower_history` with `appid` and either `range` or
+`from`/`to`) returns one game's Steam Community group member count on every
+OBSERVED day: `data.series[]` of `date` and `followerCount`, plus
+`data.availability` and `data.seriesMeta`. It takes the appid alone (no
+`--source`). `--range` defaults to `all`, ending today (UTC); `--from` and
+`--to` are inclusive. `--range` cannot be combined with `--from`/`--to`:
+the CLI rejects that as a usage error before any request, so the failure is
+not transient.
+
+Interpretation guardrails:
+
+- **Observed days only.** Days without an observation are absent and never
+  filled or interpolated. Scale by date, never by array index.
+- **Followers are not wishlists.** They are Steam Community game-group
+  members, a public proxy for audience interest. Never report them as a
+  wishlist count and never as sales.
+- **`not_collected` is a collection state.** `data.availability:
+  not_collected` means followers were never collected, never zero followers.
+- **Truncation drops the oldest points.** When `data.seriesMeta.truncated`
+  is true the series still ends at the newest observation; say the early
+  history is cut.
+
+## Steam event participation
+
+`gmc games events <appid> [--include rank_series] --json` (MCP:
+`game_steam_events`, with `include: ["rank_series"]`) returns the
+Steam-run events the game took part in (Next Fest and others), newest
+first: each with its observed best rank, shelf exposure, demo review
+series, store follower series and social account deltas. `--include
+rank_series` adds `rankSeries[]` of `{ snapshotUtc, rank, sourceKey }` per
+event, bounded per event and per response (`rankSeriesTruncated` marks an
+event a cap cut).
+
+Interpretation guardrails:
+
+- **Observed state, not an official ranking.** Ranks and shelf values are
+  event-page state captured by the collector. Report them as observed
+  positions, never as Steam's own ranking.
+- **Absence is a collection state.** An absent block means that signal was
+  not collected for the event. An empty `data.events` means no observed
+  participation, not proof the game never took part.
+- **The rank series is raw.** `rankSeries` holds the observations themselves
+  (about every 30 minutes during a festival), never resampled; a gap is a
+  real collection gap.
+- **Temporal comparison only.** A follower or review change during an event
+  is something you observed beside it, never something the event caused.
+
 ## Per-family collection status
 
 `game_collection_status` (MCP-only, no CLI command) returns per-signal-family

package/skill/gmc-analysis.manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.16.0",
-  "contentHash": "a751df9637a24adb16604c91f77618ba1af16ce191843d85d3d8f2e6ae4df363",
+  "version": "0.17.0",
+  "contentHash": "64d3e4ed54842f921cc532ac76c936fbd99619ceed13dc6fc9317fe56552df2d",
   "files": 7
 }

package/src/args.js

@@ -21,6 +21,12 @@ export function parseArgs(args) {
   const command = [];
   const positional = [];
   const options = {};
+  // Option names given more than once. Later values still win in `options`
+  // (every command's parsing is unchanged); a command that cannot take a list
+  // reads this to reject the repetition. Non-enumerable so it never shows up
+  // as an option.
+  const repeated = new Set();
+  Object.defineProperty(options, "repeatedOptions", { value: repeated, enumerable: false });
 
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
@@ -57,6 +63,7 @@ export function parseArgs(args) {
       }
 
       if (inlineValue == null) index += 1;
+      if (Object.prototype.hasOwnProperty.call(options, key)) repeated.add(key);
       options[key] = value;
       continue;
     }
@@ -90,6 +97,11 @@ function isCommandToken(command, token) {
       // unknown command `steam` with a stray positional rather than reaching
       // the tag-trends branch.
       "steam",
+      // NAK-715. Same trap as `steam` above: a token missing from this list
+      // falls through to positional rather than erroring, so `gmc roblox
+      // charts` would parse as the unknown command `roblox` with a stray
+      // positional instead of reaching the charts branch.
+      "roblox",
       "auth",
       "login",
       "logout",
@@ -109,7 +121,7 @@ function isCommandToken(command, token) {
     return ["install", "print", "status"].includes(token);
   }
   if (command[0] === "games") {
-    return ["search", "count", "aggregate", "resolve", "benchmark", "detail", "analysis", "compare", "topics", "language-topics", "review-history", "success-report", "more-like-this", "ai-disclosure"].includes(token);
+    return ["search", "count", "aggregate", "resolve", "benchmark", "detail", "analysis", "compare", "topics", "language-topics", "review-history", "success-report", "more-like-this", "ai-disclosure", "price-history", "follower-history", "events", "screenshot-labels"].includes(token);
   }
   if (command[0] === "reviews") {
     return token === "patterns";
@@ -138,6 +150,23 @@ function isCommandToken(command, token) {
   if (command[0] === "steam") {
     return ["tag-trends", "trend-stories"].includes(token);
   }
+  if (command[0] === "roblox") {
+    // NAK-723 adds saved/save/remove. Same trap the read family documents, and
+    // worse for the two writes: a token missing from this list falls through to
+    // positional rather than erroring, so `gmc roblox save <universeId>` would
+    // parse as the unknown command `roblox` and exit 2 with a message naming
+    // the id rather than the subcommand.
+    return [
+      "charts",
+      "experiences",
+      "experience",
+      "history",
+      "coverage",
+      "saved",
+      "save",
+      "remove"
+    ].includes(token);
+  }
   return false;
 }
 

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.9.0";
+export const CLI_VERSION = "0.11.0";
 
 export const DEFAULT_API_BASE_URL = "https://gamemarketcopilot.com";
 export const DEFAULT_CONFIG_PATH = path.join(homedir(), ".config", "gmc", "config.json");
@@ -63,7 +63,28 @@ export const PROVISIONAL_BETA_COMMANDS = [
   "gmc steam tag-trends --view featured|board|group|table|tag --json",
   // NAK-804. New command; starts Provisional per the closed-beta roadmap's
   // default for anything not yet through broader real-data smoke testing.
-  "gmc games ai-disclosure <appid> --json"
+  "gmc games ai-disclosure <appid> --json",
+  // NAK-934. New commands; Provisional per the same closed-beta default.
+  "gmc games price-history <appid> --range 7d|1m|1y|all --json",
+  "gmc games follower-history <appid> --range 7d|1m|1y|all --json",
+  "gmc games events <appid> --include rank_series --json",
+  "gmc games screenshot-labels <appid> --json",
+  // NAK-715/NAK-725. Enabled in production on 2026-09-22; stays Provisional
+  // per the closed-beta roadmap's default until the surface has been through
+  // a broader real-data smoke period (the NAK-804 rule), then graduates.
+  "gmc roblox charts --country all --sort top-playing-now --json",
+  "gmc roblox experiences --country all --limit 50 --json",
+  "gmc roblox experience <universeId> --json",
+  "gmc roblox history <universeId> --granularity daily|hourly --json",
+  "gmc roblox coverage --json",
+  // NAK-723. The workspace's saved Roblox experiences, mapping the REST
+  // surface that shipped with the pages. Provisional for the SAME reason the
+  // five read commands above are — they are one surface, gated by one flag,
+  // and graduating the saved commands ahead of the reads they resolve against
+  // would promise a stability the reads have not earned yet.
+  "gmc roblox saved --country all --json",
+  "gmc roblox save <universeId> --json",
+  "gmc roblox remove <universeId> --json"
 ];
 
 export const COMPARE_FOCUSES = ["overview", "market", "reviews", "marketing", "audience", "showcases"];

package/src/help.js

@@ -52,6 +52,10 @@ Usage:
   gmc games review-history --source steam <externalId> --json
   gmc games more-like-this --source steam <externalId> --country <country> --json
   gmc games ai-disclosure <appid> --json
+  gmc games price-history <appid> --range 1y --json
+  gmc games follower-history <appid> --range 1y --json
+  gmc games events <appid> --json
+  gmc games screenshot-labels <appid> --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
@@ -70,6 +74,14 @@ Usage:
   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
+  gmc roblox charts --country all --sort top-playing-now --json
+  gmc roblox experiences --country all --limit 50 --json
+  gmc roblox experience <universeId> --json
+  gmc roblox history <universeId> --granularity daily --json
+  gmc roblox coverage --json
+  gmc roblox saved --country all --json
+  gmc roblox save <universeId> --json
+  gmc roblox remove <universeId> --json
 
 Tag taxonomy:
   gmc tags --json                    List the full tag dictionary (slug, name).
@@ -177,6 +189,77 @@ AI-disclosure text and history:
   Example:
     gmc games ai-disclosure 730 --json
 
+Observed price history:
+  gmc games price-history <appid> [--range <preset>] [--from <date>] [--to <date>] --json
+                                      One game's Steam storefront price on
+                                      every OBSERVED day: priceInitial,
+                                      priceFinal (major currency units),
+                                      discountPercent, currency, storeCountry.
+  --range <preset>                    7d | 1m | 1y | all, ending today (UTC).
+                                      Defaults to all.
+  --from <YYYY-MM-DD>                 Inclusive window start.
+  --to <YYYY-MM-DD>                   Inclusive window end; defaults to today.
+                                      --range cannot be combined with --from
+                                      or --to.
+
+  Collection is not daily for every game, so days without an observation are
+  absent and never filled; scale by date, never by array index. priceFinal 0
+  with a null priceInitial is a free game; a null priceFinal means no price
+  was shown that day. data.availability not_collected means no snapshot was
+  ever collected, never a free game. A price says nothing about units sold or
+  revenue.
+
+  Example:
+    gmc games price-history 730 --range 1y --json
+
+Steam follower history:
+  gmc games follower-history <appid> [--range <preset>] [--from <date>] [--to <date>] --json
+                                      Steam Community game-group members on
+                                      every OBSERVED day: date, followerCount.
+  --range <preset>                    7d | 1m | 1y | all, ending today (UTC).
+                                      Defaults to all. Cannot be combined with
+                                      --from or --to.
+
+  Followers are a public proxy for audience interest, never a wishlist count
+  and never sales. Days without an observation are absent and never filled.
+  data.availability not_collected means followers were never collected.
+
+  Example:
+    gmc games follower-history 730 --range 1y --json
+
+Steam event participation:
+  gmc games events <appid> [--include rank_series] --json
+                                      Steam-run events the game took part in
+                                      (Next Fest and others), newest first, with
+                                      observed best rank, shelf exposure, demo
+                                      reviews, store followers and social
+                                      deltas.
+  --include rank_series               Attach the observed ranking series per
+                                      event.
+
+  Ranks and shelves are observed event-page state, never an official Steam
+  ranking. An absent block means the signal was not collected.
+
+  Example:
+    gmc games events 730 --include rank_series --json
+
+Screenshot labels:
+  gmc games screenshot-labels <appid> --json
+                                      Visual labels for each Steam store
+                                      screenshot of one game (screen type,
+                                      camera, art style, lighting, colour, a
+                                      one-line observation), in store order.
+                                      There are no parameters beyond the appid.
+
+  The labels are MODEL OUTPUT (data.labels[].labeler), not Steam data and not
+  a human review, and they can be wrong. One label set is returned per
+  screenshot: the most recently labelled taxonomy version. data.availability
+  not_labelled means nothing has been labelled yet, never that the game has
+  no screenshots.
+
+  Example:
+    gmc games screenshot-labels 730 --json
+
 Steam tag trends:
   gmc steam tag-trends --view <view> --json
                                       Tag supply trends over one frozen monthly
@@ -232,6 +315,103 @@ Steam tag trends:
     gmc steam tag-trends --view table --sort current_share --limit 50 --json
     gmc steam tag-trends --view tag --tag cozy --json
 
+Roblox:
+  gmc roblox charts --json            One ranking cohort's stored chart
+                                      snapshot as of a cutoff.
+  gmc roblox experiences --json       Browse the tracked cohort with coverage.
+  gmc roblox experience <universeId> --json
+                                      One experience: metadata, metrics,
+                                      artwork.
+  gmc roblox history <universeId> --json
+                                      A bounded window of stored metric
+                                      observations.
+  gmc roblox coverage --json          What the surface has, per dimension.
+  gmc roblox saved --json             This WORKSPACE's saved experiences,
+                                      resolved for one cohort and cutoff.
+  gmc roblox save <universeId> --json
+                                      Save one experience to the workspace.
+  gmc roblox remove <universeId> --json
+                                      Remove one from the workspace's saved
+                                      set.
+  --country <country>                 all | US | JP. Selects which CHART was
+                                      read, never a regional metric scope.
+  --device <device>                   computer.
+  --sort <sort>                       top-playing-now | top-trending |
+                                      top-revisited | fun-with-friends.
+  --as-of <instant>                   ISO 8601 cutoff; defaults to now. No
+                                      observation after it is considered.
+  --eligibility-days <number>         experiences and saved, 1-30 (default 7).
+                                      How far back a chart appearance counts.
+  --min-player-count <number>         experiences only, on the resolved row.
+  --max-rank <number>                 experiences only, on the resolved row.
+  --genre <genre>                     experiences only, exact match.
+  --creator-type <type>               experiences only, e.g. Group or User.
+  --detail <enriched|chart_only>      experiences only. Omitted returns both.
+  --order-by <key>                    rank | player_count | last_chart_seen |
+                                      universe_id (experiences only).
+  --order <asc|desc>                  experiences only.
+  --granularity <hourly|daily>        history only. Defaults to daily.
+  --from <instant> --to <instant>     history only. Hourly windows span at most
+                                      90 days, daily at most 365.
+  --limit <number>                    charts 1-250, experiences 1-200.
+  --offset <number>                   charts only.
+  --cursor <cursor>                   experiences only. Continuation token.
+
+  A Roblox universe id is NOT a Steam appid. Ids travel as decimal strings
+  because they exceed the range a JSON number represents exactly, and nothing
+  here merges a Roblox experience with a Steam game.
+
+  Unknown is never zero. A null player count was not measured. price.known
+  false means the price is UNKNOWN, not that the experience is free. Zero
+  recorded votes gives no positive percentage at all, rather than 0%.
+
+  Nothing is fabricated to fill a gap. An absent cohort answers availability
+  "never_observed" with an empty entries list — a measurement about
+  collection, not an error and never another sort's ranking. History reports
+  unsampled periods in data.gaps and interpolates nothing, so a gap is not a
+  zero. Daily sampledPlayingMin/Max are the extremes of the SAMPLES, not the
+  day's peak; compare CCU only across points whose comparable is true.
+  Observed counter decreases are reported as-is and are not resets.
+
+  This is a curated tracked cohort, never all of Roblox. Quote
+  coverage.trackedUniverses as the denominator for any share.
+
+  While the surface is switched off the commands answer 404
+  ROBLOX_UNAVAILABLE. That is the documented not-available state, not an
+  outage and not worth retrying on a schedule.
+
+  Saved experiences (workspace-scoped, unlike the five reads above):
+    saved, save and remove carry one workspace's own data and need a
+    credential — a Game Market Copilot API key or a CLI credential. Without
+    one they answer 401, which is not an empty saved list.
+
+    Saved membership is scope-independent. --country, --device, --sort,
+    --as-of and --eligibility-days apply to "saved" alone and decide which of
+    three states each row is in, never which rows are listed: in_scope
+    carries the observation that scope recorded, out_of_scope is saved and
+    tracked with NO reading there (never back-filled from another cohort or
+    from after the cutoff, and never reportable as zero or as removed), and
+    not_tracked has nothing recorded at all. The two writes take no flags.
+
+    Both writes are idempotent and report the state that NOW holds, so
+    changed: false is success and must not be retried as a failure. Saving
+    records interest in a universe id — it never triggers collection, however
+    often it is called, and it refuses an id the tracked cohort has never
+    recorded (404 NOT_FOUND, a different fact from ROBLOX_UNAVAILABLE).
+    "remove" removes the id from this workspace's saved set only; it deletes
+    no data and removing something not saved is changed: false, not a 404.
+    The set is capped per workspace (savedLimit in every response); past it,
+    saving answers 409 CONFLICT.
+
+  Examples:
+    gmc roblox coverage --json
+    gmc roblox charts --country JP --sort top-trending --json
+    gmc roblox experiences --min-player-count 1000 --order-by player_count --json
+    gmc roblox history <universeId> --granularity hourly --json
+    gmc roblox saved --country JP --sort top-trending --json
+    gmc roblox save <universeId> --json
+    gmc roblox remove <universeId> --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