@witchpot/gmc 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 All notable changes to the Game Market Copilot CLI will be recorded here.
 
+## 0.9.0 - 2026-09-16
+
+- New `--release-status <released|upcoming|tba>` filter on the games
+  search/count/aggregate commands (NAK-803), forwarded verbatim and
+  case-sensitively as the `releaseStatus` query param. The parameter was
+  already in the REST contract; the CLI simply had no mapping for it, which
+  forced CLI recipes for "released games only" to lean on the release window
+  alone. The filter is an exact match layered on top of the guard that
+  already drops any title still marked `upcoming` past its provisional
+  release date.
+
+- New command `gmc games ai-disclosure <appid> --json` (NAK-804): one title's
+  developer-authored AI-use disclosure text, the store page it was read from,
+  and its observed history of change. It takes the appid alone — no `--source`
+  selector and no query parameters, matching the route — and rejects any other
+  flag as a usage error rather than ignoring it. `absent` means no disclosure
+  block was observed on the store page, never that the title uses no
+  generative AI; `unconfirmed` includes titles never checked, and is also what
+  an appid never observed returns, since the route has no existence check.
+  Listed as Provisional in the beta command set.
+- Bundled `gmc-analysis` skill bumped to 0.16.0 with a "Disclosure text and
+  change history" subsection covering that command and how to report its text
+  and events honestly.
+- An inapplicable `--preset` is now rejected as a usage error BEFORE the
+  metered request, for every command. Previously the request executed (and
+  charged a credit) and the preset was only rejected while shaping the output.
+- Packaging: `scripts/` (release tooling) no longer ships in the npm tarball,
+  and the release-readiness gate now scans every file the tarball actually
+  contains instead of a hardcoded source list.
+
 ## 0.8.0 - 2026-09-14
 
 For npm users this release lands together with 0.7.0's content, because

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@witchpot/gmc",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "private": false,
   "description": "Command line tools for Game Market Copilot market research.",
   "license": "UNLICENSED",
@@ -33,7 +33,6 @@
   "files": [
     "bin",
     "src",
-    "scripts",
     "skill",
     "README.md",
     "CHANGELOG.md"

package/skill/gmc-analysis/CHANGELOG.md

@@ -1,5 +1,30 @@
 # gmc-analysis skill changelog
 
+## 0.16.0 - 2026-09-16
+
+- New "Disclosure text and change history" subsection under "AI disclosure
+  state" (NAK-804): the surface behind the tri-state flag — the developer's
+  disclosure text, the store page it was read from, the first and latest
+  observation dates, and the observed change history. Reached with
+  `gmc games ai-disclosure <appid>` (appid only, no `--source` and no query
+  parameters) or `game_profile` with `ai_disclosure` in `sections` (opt-in, so
+  a call that does not name it performs no extra read, and raw-read weight
+  class, so asking for it beside `detail` leaves the per-appid cost at 1).
+- Adds the interpretation guardrails as honesty rules: `disclosureText` is the
+  developer's own wording, normalized only for whitespace and never classified
+  or scored by Game Market Copilot, so it is quoted and attributed to them
+  rather than paraphrased into a verdict; each event is an OBSERVED change
+  dated as the window between `previousObservedAt` and `observedAt`, never as
+  a moment; an empty `events` array means no change was observed, never that
+  nothing changed, because a title's first observation is a baseline that
+  never appears as an event; `events` can be non-empty while `state` is
+  `unconfirmed`; `unconfirmed` still covers titles never checked, since this
+  surface has no existence check; a `null` payload carries
+  `ai_disclosure_detail_unavailable` and means the read could not be reached,
+  never "not disclosed".
+- MCP-only mapping updated: per-title AI-disclosure text and change history ->
+  `game_profile` with `ai_disclosure` in `sections`.
+
 ## 0.15.0 - 2026-09-14
 
 - New "AI disclosure state" section in SKILL.md (NAK-773): the tri-state

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.15.0
+  version: 0.16.0
 ---
 
 # GMC Analysis
@@ -57,7 +57,9 @@ applies identically. Mechanics map as follows:
   -> `more_like_this`; review topics by review language (`games
   language-topics`) -> `game_language_topics`; review-count history with
   its lifecycle/announcement/discount context (`games review-history`) ->
-  `game_review_history`.
+  `game_review_history`; per-title AI-disclosure text and change history
+  (`games ai-disclosure`) -> `game_profile` with `ai_disclosure` in
+  `sections`.
 - 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).
@@ -483,7 +485,8 @@ Every title carries a tri-state AI-disclosure read from its Steam store page:
 search/count and `market_aggregate`; group with
 `--group-by ai_disclosure` (it cross-tabs with `release_month`); read one
 title's state from `detail.aiDisclosure` (`state`, `observedAt`,
-`rawCategoryValue`).
+`rawCategoryValue`). The text and history behind that flag are a separate
+surface — see the subsection below.
 
 Interpretation guardrails (honesty rules, not suggestions):
 
@@ -505,6 +508,42 @@ Interpretation guardrails (honesty rules, not suggestions):
   (the underlying rollups have no disclosure predicate). Size disclosure
   cohorts with `market_aggregate` instead.
 
+### Disclosure text and change history
+
+`gmc games ai-disclosure <appid> --json` (MCP: `game_profile` with
+`ai_disclosure` in `sections`) returns what sits behind that flag: the
+developer's disclosure text, the store page it was read from, the first and
+latest observation dates, and the observed change history. The CLI command
+takes the appid and nothing else — no `--source`, no query parameters. Over
+MCP the section is opt-in, so a call that does not name it performs no extra
+read, and it stays in the raw-read weight class: asking for it beside `detail`
+leaves the per-appid cost at 1.
+
+Interpretation guardrails (honesty rules, not suggestions):
+
+- **The text is the developer's, never ours.** `disclosureText` is their own
+  wording as read from the store page, normalized only for whitespace. Game
+  Market Copilot never classifies it, scores it, or infers from it how much AI
+  was used. Quote it and attribute it to the developer; never paraphrase it
+  into a verdict of your own. It is `null` whenever `state` is not
+  `disclosed`.
+- **Each event is an observed change, so date it as a window.** The store page
+  is read periodically, not continuously, so a change happened SOMEWHERE
+  between `previousObservedAt` and `observedAt`. Say "between those two
+  reads"; never say it happened on either date.
+- **An empty `events` array is not "nothing ever changed".** A title's FIRST
+  observation is a baseline and never appears as an event, so an empty array
+  means only that no change has been observed between two reads. `events` can
+  also be non-empty while `state` is `unconfirmed` — history outlives a later
+  read that failed.
+- **`unconfirmed` still includes never checked.** This surface has no
+  existence check, so an appid never observed comes back `unconfirmed` with no
+  events rather than an error. That is a statement about what has been
+  observed, never about the title.
+- **A `null` payload is unavailability.** It carries
+  `ai_disclosure_detail_unavailable` and means the read could not be reached.
+  Never report it as "not disclosed", and never as not collected.
+
 ## Hard rules
 
 - **Missing data is not absent sentiment.** Report `cohort.usableGames`,

package/skill/gmc-analysis.manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.15.0",
-  "contentHash": "74cc6c0184ced1c74a624bd193f531bfad70dae3507f52b1a8090b02d81427b9",
+  "version": "0.16.0",
+  "contentHash": "a751df9637a24adb16604c91f77618ba1af16ce191843d85d3d8f2e6ae4df363",
   "files": 7
 }

package/src/args.js

@@ -109,7 +109,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"].includes(token);
+    return ["search", "count", "aggregate", "resolve", "benchmark", "detail", "analysis", "compare", "topics", "language-topics", "review-history", "success-report", "more-like-this", "ai-disclosure"].includes(token);
   }
   if (command[0] === "reviews") {
     return token === "patterns";

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.8.0";
+export const CLI_VERSION = "0.9.0";
 
 export const DEFAULT_API_BASE_URL = "https://gamemarketcopilot.com";
 export const DEFAULT_CONFIG_PATH = path.join(homedir(), ".config", "gmc", "config.json");
@@ -60,7 +60,10 @@ export const PROVISIONAL_BETA_COMMANDS = [
   // default-off, so claiming supported-beta status would promise a stability
   // the feature flag has not yet been asked to keep.
   "gmc steam trend-stories --locale en --json",
-  "gmc steam tag-trends --view featured|board|group|table|tag --json"
+  "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"
 ];
 
 export const COMPARE_FOCUSES = ["overview", "market", "reviews", "marketing", "audience", "showcases"];

package/src/help.js

@@ -51,6 +51,7 @@ Usage:
   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 games ai-disclosure <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
@@ -151,6 +152,31 @@ Review-count history:
   Examples:
     gmc games review-history --source steam 730 --json
 
+AI-disclosure text and history:
+  gmc games ai-disclosure <appid> --json
+                                      One game's developer-authored AI-use
+                                      disclosure text, the store page it was
+                                      read from, and its observed history of
+                                      change. There are no parameters beyond
+                                      the appid.
+
+  data.state is disclosed, absent, or unconfirmed. absent means no
+  disclosure block was observed on the store page -- never that the title
+  uses no generative AI. unconfirmed means Game Market Copilot has not yet
+  successfully observed the store page either way, including a title never
+  attempted at all.
+
+  data.disclosureText is the developer's own wording, normalized only for
+  whitespace and never classified or summarized by Game Market Copilot. It
+  is null unless state is disclosed. data.sourceUrl is the store page the
+  observation was read from.
+
+  data.events lists only OBSERVED changes to the state, oldest first; a
+  title's first observation is a baseline and never appears as an event.
+
+  Example:
+    gmc games ai-disclosure 730 --json
+
 Steam tag trends:
   gmc steam tag-trends --view <view> --json
                                       Tag supply trends over one frozen monthly
@@ -306,6 +332,10 @@ Filters:
                               result carries catalog_as_of_filter_unavailable
                               instead: there is no availability history behind
                               fixtures, so the filter was not applied at all.
+  --release-status <value>    released, upcoming, or tba. An exact match on
+                              top of the guard that already drops any title
+                              still marked upcoming after its provisional
+                              release date has passed, on every query.
   --ai-disclosure <value>     disclosed, absent, or unconfirmed. absent means
                               no AI-use disclosure was observed in collected
                               data -- not confirmed non-use. unconfirmed means

package/src/main.js

@@ -10,7 +10,7 @@ import { matches, parseArgs } from "./args.js";
 import { handleLocalCommand, loadConfig, parseBaseUrl } from "./config.js";
 import { printGamesSearchHelp, printHelp } from "./help.js";
 import { writeJsonError } from "./output.js";
-import { applyOutputProjection } from "./projection.js";
+import { applyOutputProjection, assertPresetApplicable } from "./projection.js";
 import { buildRequest } from "./requests.js";
 import { trackCliCommandExecuted } from "./telemetry.js";
 import { executeRequestPlan } from "./workflows.js";
@@ -71,6 +71,12 @@ export async function main(argv = process.argv.slice(2)) {
     process.exit(EXIT_USAGE);
   }
 
+  // NAK-804 cross-model review: validated BEFORE the metered request below,
+  // not only afterward inside applyOutputProjection — an inapplicable
+  // --preset must never pay for the HTTP round trip (or its credit charge)
+  // only to be rejected once the response is already back.
+  assertPresetApplicable({ fields: options.fields, preset: options.preset, request });
+
   if (request.requiresApiKey && !apiKey) {
     writeJsonError({
       code: "CLI_MISSING_CONFIG",

package/src/main.test.js

@@ -0,0 +1,130 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { main } from "./main.js";
+import { assertPresetApplicable } from "./projection.js";
+
+/**
+ * Async counterpart to the `captureUsageFailure` helper in requests.test.js:
+ * `main()` is async, so `process.exit` must be mocked to throw INTO the
+ * awaited call rather than a synchronous one.
+ */
+async function captureCliExit(run) {
+  const originalWrite = process.stdout.write;
+  const originalExit = process.exit;
+  const chunks = [];
+  let exitCode;
+  process.stdout.write = (chunk) => {
+    chunks.push(String(chunk));
+    return true;
+  };
+  process.exit = (code) => {
+    exitCode = code;
+    throw new Error("__cli_exit__");
+  };
+  try {
+    await run();
+    throw new Error("expected the CLI to exit");
+  } catch (error) {
+    if (error.message !== "__cli_exit__") throw error;
+  } finally {
+    process.stdout.write = originalWrite;
+    process.exit = originalExit;
+  }
+
+  return { output: JSON.parse(chunks.join("")), exitCode };
+}
+
+/**
+ * NAK-804 cross-model review (Codex Sol): `gmc games ai-disclosure 730
+ * --preset summary --json` used to build the request, send it, and only
+ * THEN discover in applyOutputProjection that ai-disclosure supports no
+ * preset — charging a credit for a call whose answer was always going to be
+ * a usage error. The counting fetch stub below is the direct evidence that
+ * the metered request never fires: if the ordering regresses, this test
+ * fails on `fetchCalls === 0` even though the exit code/message stay right.
+ */
+test("(NAK-804) an unsupported --preset is rejected before the metered request executes", async () => {
+  const originalFetch = globalThis.fetch;
+  let fetchCalls = 0;
+  globalThis.fetch = async () => {
+    fetchCalls += 1;
+    throw new Error("fetch must not be called once --preset is rejected");
+  };
+
+  try {
+    const { output, exitCode } = await captureCliExit(() =>
+      main(["games", "ai-disclosure", "730", "--preset", "summary", "--json"])
+    );
+
+    assert.equal(fetchCalls, 0);
+    assert.equal(exitCode, 2);
+    assert.equal(output.error.code, "CLI_USAGE_ERROR");
+    assert.match(
+      output.error.message,
+      /--preset summary is supported for gmc reviews patterns, gmc games benchmark, and gmc cohort\/pattern workflows/
+    );
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+/**
+ * The same early check is generic (it reuses resolvePresetFields exactly),
+ * not an ai-disclosure special case: an unknown preset NAME is rejected
+ * before the request too, for any command.
+ */
+test("(NAK-804) an unknown --preset value is rejected before the metered request executes", async () => {
+  const originalFetch = globalThis.fetch;
+  let fetchCalls = 0;
+  globalThis.fetch = async () => {
+    fetchCalls += 1;
+    throw new Error("fetch must not be called once --preset is rejected");
+  };
+
+  try {
+    const { output, exitCode } = await captureCliExit(() =>
+      main(["games", "ai-disclosure", "730", "--preset", "not-a-real-preset", "--json"])
+    );
+
+    assert.equal(fetchCalls, 0);
+    assert.equal(exitCode, 2);
+    assert.equal(output.error.code, "CLI_USAGE_ERROR");
+    assert.match(output.error.message, /--preset must be one of: summary/);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+/**
+ * Negative control on the pure check itself (no CLI/network plumbing
+ * needed): a request `kind` that IS in the preset allowlist must not be
+ * rejected — the early check only intercepts INAPPLICABLE presets, not
+ * every --preset call.
+ */
+test("(NAK-804) assertPresetApplicable does not reject a preset the request kind supports", () => {
+  assert.doesNotThrow(() =>
+    assertPresetApplicable({ preset: "summary", request: { kind: "reviewPatterns" } })
+  );
+  assert.doesNotThrow(() =>
+    assertPresetApplicable({ preset: "summary", request: { kind: "benchmark" } })
+  );
+  assert.doesNotThrow(() =>
+    assertPresetApplicable({ preset: "summary", request: { kind: "cohortEvidence" } })
+  );
+});
+
+/**
+ * Same precedence rule applyOutputProjection enforces: --fields silences an
+ * otherwise-inapplicable --preset entirely, so passing both together must
+ * not trip the early check either.
+ */
+test("(NAK-804) assertPresetApplicable defers to --fields precedence, like applyOutputProjection", () => {
+  assert.doesNotThrow(() =>
+    assertPresetApplicable({
+      fields: "state",
+      preset: "summary",
+      request: { kind: undefined }
+    })
+  );
+});

package/src/projection.js

@@ -47,6 +47,27 @@ export function applyOutputProjection(payload, { fields, preset, request } = {})
   return applyFieldsProjection(payload, presetFields, `preset ${preset}`);
 }
 
+/**
+ * NAK-804 cross-model review (Codex Sol): every metered command built a
+ * usage-error-only exit on an inapplicable --preset, but the check ran
+ * INSIDE applyOutputProjection, which main() calls only AFTER the HTTP
+ * request already executed (and, for a metered endpoint, already charged a
+ * credit). This is the same validation, called right after buildRequest()
+ * and before that request is ever sent, so the usage error lands before any
+ * network call or charge. General fix, not ai-disclosure-specific: it reuses
+ * resolvePresetFields exactly, so any command missing from its
+ * kind-allowlist gets the early rejection for free.
+ *
+ * Mirrors applyOutputProjection's own precedence: --fields silences --preset
+ * entirely (never even inspected) both here and there, so the two agree on
+ * every input rather than only on the paths that reach a real request.
+ */
+export function assertPresetApplicable({ fields, preset, request } = {}) {
+  if (fields != null && fields !== "") return;
+  if (preset == null || preset === "") return;
+  resolvePresetFields(preset, request);
+}
+
 function resolvePresetFields(preset, request) {
   if (preset !== "summary") {
     writeJsonError({

package/src/requests.js

@@ -387,6 +387,29 @@ export function buildRequest(command, options, positional) {
     };
   }
 
+  // NAK-804. A different route shape from every other `games` sub-path above:
+  // there is exactly one game namespace behind it, keyed on the plain numeric
+  // appid, so there is no --source flag to select and no `assertSource` call.
+  // The endpoint takes no query parameters at all (the review-history
+  // sibling's shape), so `assertSupportedOptions` closes the same gap that
+  // one documents: an unsupported flag would otherwise be silently dropped
+  // and answer with exit 0 as if the narrowing had been applied.
+  if (matches(command, ["games", "ai-disclosure"])) {
+    assertSupportedOptions(options, {
+      command: "gmc games ai-disclosure",
+      allowed: []
+    });
+    const appid = assertAppid(positional[0], "gmc games ai-disclosure <appid> --json");
+    assertNoExtraPositionals(positional, {
+      expected: 1,
+      usage: "gmc games ai-disclosure <appid> --json"
+    });
+    return {
+      path: `/api/v1/games/${encodeURIComponent(String(appid))}/ai-disclosure`,
+      query: {}
+    };
+  }
+
   if (matches(command, ["reviews", "patterns"])) {
     assertSource(options.source);
     const isCompare = positional[0] === "compare";
@@ -749,6 +772,13 @@ function buildOptionalGameCountRequest(options) {
 // server would have rejected.
 const AI_DISCLOSURE_VALUES = ["disclosed", "absent", "unconfirmed"];
 
+// Mirrors RELEASE_STATUS_FILTER_VALUES in the app's games repository module
+// (NAK-803), which the market RPCs re-check against the same literal triple.
+// Kept as a local literal for the same reason as AI_DISCLOSURE_VALUES above:
+// the CLI package cannot import server code, and the server remains the
+// enforcing authority.
+const RELEASE_STATUS_VALUES = ["released", "upcoming", "tba"];
+
 function buildGameCountQuery(options) {
   const query = pickQuery(options, {
     query: "q",
@@ -834,6 +864,26 @@ function buildGameCountQuery(options) {
       AI_DISCLOSURE_VALUES
     );
   }
+  // NAK-803: --release-status is a FILTER, so it lives in the shared
+  // count-query builder and reaches games search, count and aggregate alike.
+  // `releaseStatus` was already in the REST contract but had no CLI mapping,
+  // which forced the CLI form of a "released games only" question to lean on
+  // the release window alone (see docs/cli-use-cases.md section 67). Like
+  // --ai-disclosure, the three values are a closed set the server enforces
+  // case-sensitively, so a mistyped value is a usage error here rather than a
+  // silently-unfiltered, still-charged request.
+  //
+  // Note this filter is an exact match layered ON TOP of the unconditional
+  // stale-upcoming guard (NAK-78): a title still marked `upcoming` past its
+  // provisional release date is dropped from every query regardless of this
+  // flag, so `--release-status upcoming` never resurrects one.
+  if (options["release-status"] != null) {
+    query.releaseStatus = assertEnumQueryOption(
+      options["release-status"],
+      "--release-status",
+      RELEASE_STATUS_VALUES
+    );
+  }
   return query;
 }
 
@@ -1168,6 +1218,31 @@ function assertExternalId(value, usage) {
   }
 }
 
+/**
+ * NAK-804. Validates the appid positional for `gmc games ai-disclosure`,
+ * mirroring the strict path-parameter check the app applies to every
+ * `/api/v1/.../games/{appid}` route: a plain positive decimal integer, and
+ * nothing else. The lexical test is deliberately `/^\d+$/` rather than
+ * `Number(value)`, the same reasoning `assertLanguageTopicMinReviews` above
+ * documents for `--min-reviews` -- `Number` also accepts the exponent, hex
+ * and decimal-point spellings ("7e2", "0x2da", "730.0") that the app's
+ * validator rejects outright, so letting those through here would mean a
+ * value the API answers 400 for silently reaches the wire as if it were
+ * fine. This check is advisory; the server remains the enforcing authority.
+ */
+function assertAppid(value, usage) {
+  const raw = value == null ? "" : String(value);
+  const appid = DECIMAL_INTEGER_RE.test(raw) ? Number.parseInt(raw, 10) : Number.NaN;
+  if (!Number.isSafeInteger(appid) || appid <= 0) {
+    writeJsonError({
+      code: "CLI_USAGE_ERROR",
+      message: `Missing or invalid appid (must be a positive integer). Usage: ${usage}`
+    });
+    process.exit(EXIT_USAGE);
+  }
+  return appid;
+}
+
 function assertResolveQuery(value) {
   if (value == null || String(value).trim() === "") {
     writeJsonError({