@battlegrid/mcp-server 31.0.3 → 31.1.5

package/README.md

@@ -24,16 +24,205 @@ Seeing package `31.x` alongside handshake `battlegrid@33.x` — the package **be
 
 **What this changes for you:** nothing about how you call anything. Upgrading the package no longer waits on a server deploy, and a server deploy no longer strands you on a package that names the wrong contract — reconnect and the announcement follows. **Contract breaking-change notes are no longer keyed to package versions**, since a contract move is no longer a release here; the v11-and-earlier notes below are kept as history, and the live vocabulary is always discovery.
 
-## Contract history — v12 → v33
+## Contract history — v37 → v48.1
+
+Eleven majors reached authors while this section stopped at v36. That gap is the mechanism, not an
+oversight: since v31 a contract move needs no release here, so nothing forced a note to be written —
+and the documentation ships inside the tarball, so a note written but unpublished reaches nobody.
+Both halves are now closed by a rule keyed to the *served* contract rather than to a release of this
+package.
+
+### Changed meaning, unchanged shape
+
+- **Three tools serve different values for identical input** (47.3.0, `derive-scan-fetch-from-report`).
+  The radar scan leg now derives its timeframe fetch from the strategy's **report** rather than the
+  on-duty agent's three perception rungs, so a required condition addressing an absolute timeframe
+  outside those rungs — never evaluated at scan before — now is. No field moves; the values do:
+
+  | Tool | What moves |
+  |---|---|
+  | `preview_radar_resolution` | `conditionReach[].reachReason` goes `AGENT_TIMEFRAME` → `null` |
+  | `get_radar_activity` | `scanReachReason` moves the same way, **on new rows only** — rows already written keep what they were recorded with |
+  | `get_agent_coin_qualification` | `reachReason` moves the same way; its sibling `verdict` moves `UNMEASURABLE` → a decided verdict |
+
+  **Read the last one carefully:** a client treating `UNMEASURABLE` as "this gate is switched off"
+  will now see that gate **BLOCK**. `AGENT_TIMEFRAME` keeps its member and narrows to the one cause
+  no fetch can discharge. Nothing in the payload tells you this moved.
+
+### Rejected input — something you author is no longer accepted
+
+- **A benchmark-bound section no longer accepts crowd metrics or rank transforms** (49.0.0,
+  `fix-benchmark-legality-save-path`). On a custom section carrying a non-null `benchmarkTicker`, a
+  column whose metric is enrichment-stage (the `CROWD_*` family, `FLOW_ALIGN`, `SMART_RETAIL`,
+  `CAPTAIN_CONF`, `CONFIDENCE`, `SETTLED_AT`, the `PERP_SPOT_*` trio) is refused with
+  `REPORT_COLUMN_BENCHMARK_METRIC_UNSUPPORTED`, and one carrying a `rank` transform in either the
+  direct or the chained position with `REPORT_COLUMN_BENCHMARK_TRANSFORM_UNSUPPORTED`. Every tool
+  accepting a section array is affected, and no other byte of your body changes.
+
+  **Fix it by moving the column, not by retrying.** Both readings are defined *relative to the
+  cohort being evaluated* — a crowd reading is what this session's players did, a rank is a position
+  among the coins under evaluation — and a benchmark is deliberately outside that cohort. Neither
+  has a value there, which is why such a column could never render. Put it on an ordinary section
+  (`benchmarkTicker: null`), or drop it.
+
+  **This is a fix, not a new rule.** The restriction shipped with benchmark sections and was already
+  enforced by the column builder, by report materialization, and by `get_strategy_column_contract` —
+  so an author who checked a column against discovery first has been seeing this refusal all along.
+  What changed is that the SAVE path now asks the same question. Previously it did not, so such a
+  section persisted and then failed at every evaluation instead of at authoring.
+
+- **A custom report section no longer accepts `timeframe`** (48.0.0,
+  `remove-section-anchor-override`). The per-section anchor override is gone. Every tool accepting a
+  section array — `compile_strategy_plan`, `preview_strategy_report`, `derive_strategy_rule_view`,
+  and `apply_strategy_plan` — refuses a section carrying it: `sections[N]: Unrecognized key(s)`,
+  with no other byte of your body changing. Drop the key. A section's columns resolve against the
+  **strategy** timeframe, and a column reaches any other timeframe by pinning it on the column
+  (`timeframe: { abs: '4h' }`) — which it could always do. Relative column references
+  (`anchor`/`lower`/`regime`) are untouched, and are the point: they track the strategy.
+
+- **A custom report section requires `notes`** (43.0.0, `add-authored-section-notes`). Every tool
+  accepting a section array — `compile_strategy_plan`, `preview_strategy_report`,
+  `derive_strategy_rule_view` — refuses a section without it: `sections[N].notes: Required`, with no
+  byte of your body changing. Send explicit `null` for "no note". It is required rather than optional
+  because these payloads are a FULL REPLACE: an omitted key and an explicit `null` would be the same
+  request on the wire, so every rebuild site would silently clear a note its author wrote.
+  `benchmarkTicker` carries the same required-nullable discipline for the same reason.
+
+- **Every condition requires `clock` and `closes`** (44.0.0, `add-condition-clock`), and **`exit`**
+  arrives with them. A condition entry now carries eight keys, not five. `clock` is `"LIVE"` (the
+  previous behaviour — the forming bar) or `"CLOSE"` (settled bars); `closes` is how many consecutive
+  closed bars must read true, 1–5, and is always `1` under LIVE. No wire default, for the same
+  whole-set-replacement reason as `notes`: a defaulted key would let an unrelated re-save silently
+  un-clock an enforced money gate back to forming-bar evidence.
+
+  A `CLOSE` clock is accepted only where a closed frame can change the reading — the clause must
+  resolve from the coin's own candle series at offset 0. Frame-inert operands (perp-payload scalars,
+  published rolling changes, ranks, zone entities, regime labels, enrichment metrics, session
+  scalars) are refused with `CONDITION_CLOCK_OPERAND_ILLEGAL` naming the header and the remedy: split
+  that clause into its own LIVE condition and `conditionRef` it. `exit: true` is legal only under
+  `clock: "CLOSE"` — an exit fired on a forming bar is an intrabar exit.
+
+- **A strategy requires a seven-key `entry` object** (44.0.0 for four keys, 47.0.0 for three more —
+  `add-entry-on-close`, `add-level-trigger-execution`). Required on every CREATE, on
+  `compile_strategy_plan`, `apply_strategy_plan` and `update_intelligence_agent`. A client sending
+  44.0.0's four-key object is refused under 47 with `entry.levelSource: Required` without one byte of
+  it changing.
+
+  ```jsonc
+  "entry": {
+    "trigger": "AT_SIGNAL",          // | ON_CANDLE_CLOSE | STOP_THROUGH_LEVEL | ON_RETEST
+    "confirmTf": "4h",               // the strategy timeframe or the rung below it — nothing else
+    "closes": 1,                     // 1–5; must be 1 unless ON_CANDLE_CLOSE
+    "bandAtrMultiple": 1.0,          // > 0, and <= the platform's entry-deviation gate
+    "levelSource": "SWING_HIGH",     // | SWING_LOW | BOLLINGER_UPPER | BOLLINGER_LOWER
+    "levelOffsetAtrMultiple": 0,     // 0–2, UNSIGNED; must be 0 unless a level trigger
+    "validForBars": 4                // 1–24 of the strategy's own bars
+  }
+  ```
+
+  `AT_SIGNAL` with those values is byte-identical to pre-44 behaviour. The legality matrix runs one
+  way: all seven keys are always present, so a MEANINGFUL value under a trigger that ignores it is
+  refused rather than accepted-and-dropped — a dial never silently does nothing.
+
+- **A `strategyTimeframe` the platform does not ingest is refused** (39.0.0,
+  `move-renderer-to-rendered-section`) on `get_coin_market_context`, where it was previously
+  accepted. The number is the only signal a client gets.
+
+- **`eventType` gains `ENTRY_EXPIRED_UNCONFIRMED`** (48.1.0, `fix-entry-arming-lifecycle`) on
+  `get_radar_activity` and `get_radar_activity_summary` — an armed entry that reached its episode
+  lifetime without ever receiving a confirming close. A client holding its own closed copy of that
+  enum rejects the new member; one that switches exhaustively on it needs the branch.
+
+  `entryVoidCause` is deliberately **unchanged** and still carries exactly `BAND`, `CONDITIONS`,
+  `STRUCTURAL`. Each of those is a measurement taken *at* a close, so an episode that reached no
+  close gets its own event type rather than a fourth cause — `ENTRY_VOIDED` means "called off at the
+  close", a claim this outcome must not make.
+
+  The authoring boundary also gains a refusal with **no schema change**: a strategy declaring an
+  arming trigger whose `required` conditions read the `LIVE` clock is rejected on the existing
+  `VALIDATION_ERROR` code, naming the offending condition key. Same code, same shape, new reason —
+  so nothing in the published schema tells you it can now happen.
+
+### Removed — no alias exists
+
+- **`get_coin_market_context` is REMOVED** (40.0.0, `retire-get-coin-market-context`). Calling it
+  returns an unknown-tool error. There is deliberately **no alias**: a silent redirect would hide a
+  payload shape change from a client that never asked for one. Use `get_market_context`.
+
+- **`get_macd_heatmap` leaves the published surface** (41.0.0). Same shape of break, same absence of
+  an alias.
+
+- **`isPrimary` is removed from every published `EvaluatedSignal`** (38.0.0) — `get_signal_log`,
+  `get_public_agent_signal_log_detail`, and every other tool returning a signal scorecard. Reading it
+  now finds the key absent rather than false.
+
+### Reshaped output — the same call returns a different shape
+
+- **The normalized report section loses `timeframe`** (48.0.0, `remove-section-anchor-override`), on
+  every tool that publishes a strategy: `get_strategy`, `fork_strategy`, `archive_strategy`,
+  `restore_strategy`, `update_strategy_signal_rule`, `apply_strategy_plan`, and
+  `compile_strategy_plan`'s post-state. A strict parser rejects the shorter object; a lenient one
+  reads a section whose anchor is the strategy timeframe, which it now always is.
+
+- **`get_strategy_column_contract` renames its anchor, both ways** (48.0.0). The request field
+  `sectionTimeframe` becomes `anchorTimeframe` — same meaning, and still optional. On the response,
+  `timeframe.requiresSectionTimeframe` becomes `requiresAnchorTimeframe`, and
+  `timeframe.sectionTimeframeOverrideAllowed` is **removed**: it published whether a column could go
+  in an anchor-overridden section, and no section can be overridden. One call also stops being
+  refused — a timeframe-inert metric supplied with an anchor now compiles.
+  `REPORT_COLUMN_SECTION_TIMEFRAME_UNSUPPORTED` leaves the `authoringCode` vocabulary.
+
+- **`RenderedSection.notes` stops carrying provenance** (42.0.0, `separate-section-facts-from-read`),
+  on `preview_strategy_report`, `compile_strategy_plan` and `get_market_context`. A new REQUIRED
+  `provenance: string[]` carries it instead. A client reading provenance out of `notes` now reads an
+  author's prose, or nothing — which is a silent misread, not an error.
+
+- **`preview_strategy_report.renderedSections[]` gains `authoredNote`** (43.0.0), the author's read
+  for a custom row and `null` on a platform row. Additive, but published on a `.strict()` shape.
+
+- **`get_radar_activity` serves its evaluation curve on the FIRST PAGE ONLY** (37.0.0), and
+  `get_radar_activity_summary` is added. A client reading the curve off a later page finds it absent.
+
+### Widened enum — new members your own copy rejects
+
+- **The authorable metric vocabulary widens by 29 keys** (46.1.0, `add-indicator-catalog-coverage`):
+  Keltner (`KC_UPPER`/`KC_MID`/`KC_LOWER`), Supertrend (`ST_LINE`/`ST_DIR`), Hull (`HMA20`),
+  WaveTrend (`WT1`/`WT2`), QQE (`QQE_RSI_MA`/`QQE_STOP`), Parabolic SAR (`PSAR`), Ichimoku
+  (`ICHI_CONV`/`ICHI_BASE`/`ICHI_SPAN_A`/`ICHI_SPAN_B`/`ICHI_LAG`), Williams %R (`WILLR14`),
+  Stochastic RSI (`STOCH_RSI14`), session pivots (`PIVOT_P`/`PIVOT_R1`–`R3`/`PIVOT_S1`–`S3`), plus
+  four already-published fields that became addressable: `BB_UPPER`, `BB_LOWER`, `DI_PLUS`,
+  `DI_MINUS`.
+
+  Additive on the wire — every request you can send today is still accepted. It is called out here
+  because a client holding its own closed copy of the metric enum rejects the new members, and
+  because **an agent holding a cached belief that these are inexpressible will substitute for a
+  primitive the platform now serves**. That failure raises no error at all: the author is simply told
+  a strategy cannot be built.
+
+- **`EntryTrigger` gains `STOP_THROUGH_LEVEL` and `ON_RETEST`, and `EntryLevelSource` is published
+  for the first time** with four members (47.0.0). Additive on their own; the required keys above are
+  what make that bump a major.
+
+- **Each signal-checklist item's `measured` object gains a required `triggered` boolean** (47.2.0,
+  `fix-entry-prompt-signal-evidence`) on `get_signal_log` and `get_public_agent_signal_log_detail`,
+  on the `numeric` and `categorical` arms. Additive and MINOR — a client ignoring it is unaffected —
+  but it is named here because a client parsing that output strictly rejects the new key, and because
+  leaving 47.2 unlisted would make a reader wonder what happened to it.
+
+  The `unavailable` arm deliberately does **not** carry `triggered`: "the claim could not be joined to
+  a stored result" and "the signal did not fire" are different states, and leaving the key off that
+  arm makes conflating them a type error rather than a convention.
+
+## Contract history — v12 → v36
 
 > **The number in this heading is a CONTRACT version, not this package's version.** The npm badge at the top
 > tracks the proxy's own code; this section tracks the server's wire contract. They move independently **by
 > design**: a contract move needs no release here, because a connected proxy relays the contract out of the
-> upstream handshake rather than declaring it. So a package on `31.x` listing contract history up to `33.x` is
+> upstream handshake rather than declaring it. So a package on `31.x` listing contract history up to `36.x` is
 > correct — not a version someone forgot to bump. Read the live pair from the startup stderr lines or
 > `GET /mcp/version`; see [Rediscovery & versioning](#rediscovery--versioning) for why.
 
-These are the server contract breaks between contract 12 and contract 33. Most of the span shipped while the package sat at `11.0.0`; contract 31 landed after this package reached `31.0.0`, and the two numbers matching is coincidence — since v31 the announced contract is relayed from the server, so a package version says nothing about a contract version. They are **contract** history, not package releases: from v31 the announced contract is relayed live and a contract move is no longer a release here. Grouped by what a client observes, with the contract version that introduced each.
+These are the server contract breaks between contract 12 and contract 36. Most of the span shipped while the package sat at `11.0.0`; contract 31 landed after this package reached `31.0.0`, and the two numbers matching is coincidence — since v31 the announced contract is relayed from the server, so a package version says nothing about a contract version. They are **contract** history, not package releases: from v31 the announced contract is relayed live and a contract move is no longer a release here. Grouped by what a client observes, with the contract version that introduced each.
 
 **The proxy itself is unchanged.** It embeds no schemas, pins no contract version, and forwards `{ request }` verbatim. Every break below lands on whatever *authors* the payload or *reads* the result, never on the proxy.
 
@@ -45,6 +234,14 @@ These are the server contract breaks between contract 12 and contract 33. Most o
 
 ### Rejected input — something you author is no longer accepted
 
+- **`upsert_deployment_policy` requires `enabled`** (35.0.0, `add-arena-deployment-pause`). The arena deployment gains an owner-owned pause, and the flag that carries it is **required, not optional** — a body accepted under contract 34 is refused under 35 without one byte of it changing. Required is the whole point: this call replaces the entire policy, so an omitted key and an explicit `true` would be the same request on the wire, and every client that rebuilt a policy without the flag would silently resume a deployment its owner had paused. Read the value from `get_deployment_policy` and send it back. **There is no separate pause verb** — pausing and resuming are this same call with the flag flipped.
+
+  Do not reach for `enabled: false` to un-deploy. It keeps every slot and stops play, which is the opposite of withdrawing: `delete_deployment_policy` is the withdrawal verb, and it discards the rules permanently. `upsert_deployment_policy` refuses an empty slot set, and its rejection names both routes.
+
+- **A signal rule flagged `required` at allocation Off is rejected** (34.0.0, `enforce-required-allocation-invariant`). `required` and `allocation` are two independently editable fields encoding one thing — whether and how a signal participates — so `{ required: true, allocation: 0 }` was representable and meant nothing: the scorecard's triggered set already excludes Off, so such a rule could neither satisfy `minRequiredCount` nor block a trade. It is now refused on **every** rule-writing surface — `compile_strategy_plan`, `apply_strategy_plan` and `update_strategy_signal_rule` alike.
+
+  Three things make this one easy to trip over. It is an **input-acceptance narrowing**: a payload accepted under contract 33 is refused under 34 without one byte of it changing. It is **invisible in the published schema** — `zod-to-json-schema` drops effects by construction — so you cannot pre-validate it from `tools/list`, and the typed error IS the contract: read `details.inertRequiredSignalIds`, which carries the complete sorted list of offending signals, rather than the message, which names a bounded prefix. And **nothing is repaired for you**: the server will not raise the allocation (that would invent a scoring weight you never chose) nor clear the flag (that would discard your intent silently). Pick one and resend; either satisfies the boundary.
+
 - **`apply_strategy_plan` no longer accepts the plan** (33.0.0, `rehydrate-approved-plan-on-apply`). Its input narrows to `{ planToken, confirm }`. A `plan` member is **rejected as an unknown key** — not accepted, not ignored, and with no transitional dual shape — so every client that built the payload breaks on the next connection, which before this is what every published surface told it to do. The server keeps the plan its own compile approved and reads it back, so **you copy nothing out of the compile response**: forward `planToken` byte-for-byte and confirm.
 
   Three consequences worth knowing. The 256,000-byte cap on the apply payload is **gone with the payload**, so a large authored surface no longer becomes impossible to apply through a conversational client; the compiled plan is still capped and compile still enforces it. `PLAN_APPROVAL_NOT_FOUND` joins the error vocabulary for a token no approved plan answers to — already applied, lapsed, or never issued, all one code, because the recovery is the same in each case: compile again. And a validation refusal (a quota, a name collision, a bound agent that changed, a moved catalog) now **leaves the approved plan applicable** — clear the cause and confirm again with the same token while it lives, rather than recompiling.
@@ -94,6 +291,18 @@ These are the server contract breaks between contract 12 and contract 33. Most o
 
 ### Moved or reshaped output — a field you read is somewhere else
 
+- **The signal scorecard stops serializing its entries three times over** (36.0.0, `mcp-signal-log-contents`). `get_signal_log` and `get_public_agent_signal_log_detail` drop `scorecard.triggeredSignals`, `scorecard.primarySignals` and `scorecard.supportingSignals`. Every one held the **same entry objects** `allEvaluatedSignals` already carried, so each is one filter over flags every entry still publishes:
+
+  | Removed | Read instead |
+  |---|---|
+  | `triggeredSignals` | `allEvaluatedSignals.filter(s => s.triggered)` |
+  | `primarySignals` | `allEvaluatedSignals.filter(s => s.triggered && s.isPrimary)` |
+  | `supportingSignals` | `allEvaluatedSignals.filter(s => s.triggered && !s.isPrimary)` |
+
+  **Keep the `triggered` half of those last two predicates.** Both collections were triggered-only by construction, so filtering on `isPrimary` alone surfaces signals that never fired — a silent widening, not an error. No field is removed from an entry: the key set on an `allEvaluatedSignals` member is unchanged, every evaluated signal is still returned whether or not it triggered, and `details` prose and `indicatorValues` are intact. There is no opt-in to get the three back and no default filter. Breaking only if you read one of the three names; on an 84-signal / 16-triggered log the duplication was 10,682 bytes, 28% of the scorecard, carrying no information.
+
+- **The fleet roll-up on `list_deployment_policies` drops `unconfigured` and gains `paused`** (35.0.0, `add-arena-deployment-pause`, `fix-arena-deployment-undeploy`). `unconfigured` counted a deployment holding zero slots — a state that can no longer exist, because a stored policy now carries at least one slot and the withdrawn state is the **absence** of a policy rather than an empty one. The bucket was constant `0` at the moment of removal, so no number you read was wrong; a client reading the key still breaks on it, which is why this is a break and not a cleanup. `paused` is the owner's own switch, counted separately from `retired` — an administrator disabling the arena — because conflating them tells an owner to wait for something that will not happen. Every policy lands in exactly one bucket, so the buckets sum to `arenas`: worth asserting if you reconcile these counts.
+
 - **`AdminApprovedModelDTO.isActive` became `lifecycle`** (32.0.0, `remove-agent-presets`) — `AVAILABLE` / `DEPRECATED` / `RETIRED`. The boolean conflated "offered in the picker" with "bound agents may run", so there was no way to stop offering a model without hard-blocking every agent already on it. A client switching on `isActive` must switch on `lifecycle`, and **must not treat `DEPRECATED` as blocked**: that is the state which keeps bound agents running. The agent read DTO drops `brainPreset` in the same move — the marker recorded which named bundle an owner clicked, never a value the runtime read, and the model and soul it stamped are unchanged on every agent.
 
 - **`approvedPlan` is one object, not an operation union** (31.0.0, resolving #4495). It was published as a discriminated union whose discriminator does not survive JSON-Schema conversion, so what actually shipped was a bare `anyOf`: validating a failing compile response gave you every arm's errors with empty instance paths, and the top one typically complained that an UPDATE was missing `creationSeed` — a CREATE-only key — while the field that really failed went unnamed. It is now one object with a literal `operation` discriminator, and `creationSeed`, `expectedRevision` and `bindingImpact` are **required and nullable on every operation**: a CREATE plan carries a seed and `expectedRevision: null`, an UPDATE/RESTORE plan the reverse. **If you narrowed on the union arms, read `operation` instead and expect explicit `null`s rather than absent keys.** If you read those fields without narrowing, nothing changes except that they may now be null.
@@ -142,6 +351,8 @@ These are the server contract breaks between contract 12 and contract 33. Most o
 
 ### Widened enum — new members your own copy rejects
 
+- **`DeploymentResolutionStatus` gains `PAUSED`** (35.0.0, `add-arena-deployment-pause`), returned by `get_deployment_policy`, `list_deployment_policies` and `preview_deployment_resolution`. A client switching exhaustively on the status must add the branch. Two properties are not obvious from the name: it is answered **before any slot is resolved**, so a paused deployment discloses no agent identity and carries `regimeUsed: null`; and its `targetSession` is nullable, because a deployment can be paused on an arena with no upcoming session and the pause is still the true answer. Do not re-derive the pause from the `enabled` flag beside it — the served status is the answer on every path, and those two disagreeing is the defect this closed.
+
 - **Seven plan-token failures became their own error codes** (31.0.0, resolving #4495). `TOKEN_EXPIRED`, `TOKEN_BINDING_MISMATCH`, `INVALID_TOKEN_SIGNATURE`, `INVALID_TOKEN_FORMAT`, `INVALID_TOKEN_CLAIMS`, `INVALID_DIGEST_MATERIAL` and `INVALID_MATERIALIZATION_FENCE` all used to arrive as a bare `INTERNAL_ERROR` — the server wrote the true reason to its own audit log and discarded it at the boundary, so a refused apply told you nothing. They now arrive as themselves, over MCP and HTTP alike, with 409-class status for the two state-conflict codes and 400-class for the five malformed-material codes. A client switching exhaustively on error codes must add the branches; one rendering unknown codes generically is unaffected. Two are worth handling by name: `TOKEN_EXPIRED` means recompile (the token lives five minutes), and `INVALID_TOKEN_SIGNATURE` usually means the token was not forwarded verbatim — it is opaque, so copy it byte-for-byte and never retype or reconstruct it.
 
 - `TradeEvaluationAttemptReasonCode` gains `OPEN_POSITION_CHECK_UNAVAILABLE` (19.4.0), splitting a code that previously reported a platform fault as a fact about your account.
@@ -154,6 +365,38 @@ Nothing in the proxy changes. No configuration, no environment variable, no call
 
 ### Additive in the same span
 
+- **`get_regime_snapshot` publishes the evidence behind the verdict** (47.1.0,
+  `publish-regime-classification-evidence`). The snapshot gains `evidence`: the quantities the
+  classifier read, the gates it tested them against, the signed margin to the gate deciding whether
+  the current label survives, and the two decision facts only the classifier holds — `gateState`
+  (`cleared` / `held` / `dropped`) and `directionSource` (`di` / `ema`). Nothing narrows; a client
+  that ignores the field is unaffected.
+
+  Read `gateState` before you trust a trend label: **`held` means the ADX hysteresis buffer is
+  carrying the PREVIOUS bar's label rather than this bar re-confirming it** — a materially weaker
+  claim wearing the same word, and one no client could previously detect. `directionSource: 'ema'`
+  is the same shape of warning: the direction came from the fallback that fires precisely when the
+  DI spread is indecisive. The margin is signed so **positive always means "the current label
+  survives by this much"**, in every gate state, so it is safe to branch on its sign.
+
+  `conviction` is a BRANCH DISCRIMINATOR, not a confidence: it encodes *which* rule in the priority
+  ladder matched, not how comfortably it matched. The margins carry comfort. A client reading
+  conviction as a strength score is reading it wrong, and always was — this release just makes the
+  alternative available.
+
+- **Thirteen metric keys join the catalog** (47.1.0) — the `regime` family gains `REGIME_STATE`,
+  `REGIME_CONVICTION`, `REGIME_RUN_BARS`, `REGIME_TREND_GATE`, `REGIME_TREND_MARGIN`,
+  `REGIME_TREND_SOURCE`, `REGIME_DI_SPREAD`, `REGIME_VOL_ATR_RATIO`, `REGIME_VOL_BBW_RATIO`,
+  `REGIME_MOM_BULL_VOTES`, `REGIME_MOM_BEAR_VOTES`, `REGIME_CRASH_MARGIN` and `REGIME_CRASH_LATCH`,
+  making the composite regime and its evidence addressable in a report column or condition for the
+  first time. Only a client that switches exhaustively on `MetricKey` needs new branches.
+
+  Not a contract change, but worth knowing if you author conditions: the report grammar's regime
+  metrics now resolve from the **confirmed close** on every path. They previously resolved from the
+  forming bar when a report was rendered and the confirmed close when the scan swept, so the same
+  condition could read differently in preview than in production. Same wire shape; same bar
+  everywhere now.
+
 `27.1.0` exit-policy authoring input on `compile_strategy_plan` · `19.2.0` `get_account_state` account identity · `19.1.0` Standing Orders marker authoring · `18.4.0` `list_gate_blocks` summary groups · `18.3.0` radar maintenance pause · `18.1.0` protection geometry · `17.2.0` break-even/trailing status · `17.1.0` `get_signal_log` condition evaluation · `13.1.0` four owner-scoped read tools · `12.1.0` cross-venue spot price metrics · `11.1.0` discoverable rate limit.
 
 ## v11 and earlier — contract history (v6 → v11)
@@ -517,7 +760,6 @@ Tools, prompts, and resources are **discovered live** from the connected server
 | 24.0.0 | Server contract v24.0.0, **breaking**: the post-entry exit policy moves from the agent to the strategy. `create_agent`/`update_agent` stop accepting `tradingConfig.positionManagement` on the shared `.strict()` `TradingConfigSchema`, so a client still sending it is rejected rather than ignored — the same input-acceptance narrowing that made v4, v5, v6, v8, v10 and v23 majors. On the read side `AgentTradingConfigDTO` drops the nested block on every agent-returning tool and the explorer trading spec drops it too; `get_trading_config_catalog` drops `positionManagementPresets` and the `defaultPositionMgmt*` trading defaults. The pistol-preset ladder (COLT / WEBLEY / BERETTA / LUGER / WALTHER) is **retired, not renamed** — once the values live on the strategy, the strategy is the named bundle. Additive on the authoring surface in the same bump: `compile_strategy_plan`/`apply_strategy_plan` post-state gains the twelve authored keys beside the trade-level trio, and the plan diff gains a `positionManagement` axis. Behaviourally the umbrella `enabled` flag is **deleted** rather than moved: each mechanism toggle is the whole truth for that mechanism, so a client can no longer express "trailing on, management off". Never published as a package version |
 | 26.0.0 | Server contract v26.0.0, **breaking**: both entry-lifecycle guards stop being agent configuration. `create_agent`/`update_agent` stop accepting `tradingConfig.signalTimeoutMinutes` and `tradingConfig.maxEntryDeviationAtrMultiple` on the shared `.strict()` `TradingConfigSchema`, so a client still sending either is rejected rather than ignored — the same input-acceptance narrowing that made v4, v5, v6, v8, v10, v23 and v24 majors. Neither has a replacement key: one `platform_config` value governs the entry-price drift budget for every decision (read at evaluation time, so an admin edit applies to the next evaluation), and one governs how long an entry may stay unfilled (snapshotted onto the position at creation, so an edit can never cancel an order already resting on the book). On the read side `AgentTradingConfigDTO` drops both fields on every agent-returning tool, and so do the explorer trading spec and the agent-review payload; `get_trading_config_catalog` drops `defaultSignalTimeoutMinutes` and the `minimum_`/`maximum_maxEntryDeviationAtrMultiple` bound pair, while `defaultMaxEntryDeviationAtrMultiple` and `defaultTtlMinutes` stay and become the values that actually govern. Behaviourally a conversational entry and an autonomous entry on the same setup now receive the **identical** unfilled lifetime — the mode-selecting fallback that chose between a per-agent timeout and a hardcoded 15-minute resting window is gone, and the three-way timeout enum with it. Never published as a package version |
 | **31.0.0** | **Proxy change, and the end of the pairing rule.** The version announced downstream is now read from the upstream handshake at connect time and relayed verbatim, instead of being a constant compiled into this package. A local client reads the contract it will actually reach, on every connection, with no release involved. Breaking because the package number now means something different — this proxy's own code, not the server's contract — so `npm view` and the handshake legitimately differ, and code keyed to them being equal is wrong. Retired with it: the publish-time deploy gate (`scripts/assert-deployed-contract.mjs`) and the `MAJOR.MINOR` pairing rule, both of which existed only because the two numbers could disagree. Fails closed if a connected server announces no `serverInfo` rather than substituting its own version. Contract moves no longer produce a release here |
-| 32.0.0 | Server contract v32.0.0, **breaking**: a signal rule flagged `required` at allocation Off is rejected on every rule-writing surface, with a typed error whose `details.inertRequiredSignalIds` names every offending signal. An input-acceptance narrowing invisible in the published schema (conversion drops effects) and unmigrated in storage, so a stored strategy holding the pair is refused on its owner's next write. No proxy code change — the proxy forwards `{ request }` verbatim and relays the announced contract from the handshake |
 
 ## Maintainer release procedure
 
@@ -588,12 +830,29 @@ If a run fails, inspect it before taking action. An `ENEEDAUTH` failure means th
 
 ## Skills
 
-Install the BattleGrid skill for AI agent instructions:
+Install the BattleGrid skills for AI agent instructions:
 
 ```bash
 npx skills add playbattlegrid/battlegrid-mcp
 ```
 
+Two skills ship from this repo, and both are inside the npm tarball (`SKILL.md`, `skills/`):
+
+- **`battlegrid`** — connection, scopes, game play, and the strict compile → review → apply
+  strategy workflow.
+- **`battlegrid-strategy-studio`** — full-power strategy authoring, for agents that would
+  otherwise compile bare template strategies: custom report sections and system-generated header
+  grammar, benchmark sections, condition trees (verdict precedence, `required` enforcement
+  gates, `N_OF`/`NOT` groups, condition references), tiered signal weights and the
+  weighted-aggregate gate math, ATR trade levels, and post-entry position management. Its
+  `references/` carry five validated desk-grade playbooks (volatility-compression breakout,
+  crowded-positioning fade, benchmark-gated relative-strength rotation, HTF trend pullback,
+  perp/spot flow divergence at structure), copy-adaptable recipes, and process-for-process
+  ports of the most popular TradingView community scripts (Squeeze Momentum [LazyBear],
+  Supertrend/UT Bot, Chandelier Exit, MACD + 200 MA, golden cross, RSI-2, VWAP reversion,
+  Donchian/Turtle, ICT FVG/order blocks) with honest named substitutions where the grammar
+  lacks a primitive. Shapes are binding; vocabulary stays live-discovered.
+
 ## License
 
 [MIT](LICENSE)

package/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: battlegrid
+description: MCP skill for BattleGrid — play crypto prediction games (Market Grid), author trading strategies with the strict compile → review → apply workflow, and manage strategy-bound intelligence agents from AI agents.
+---
+
+# BattleGrid
+
+BattleGrid is a real-time cryptocurrency prediction gaming and trading platform. This MCP server gives AI agents access to play games, author trading strategies, and run strategy-bound intelligence agents.
+
+## Discover the live surface first
+
+**Tools, prompts, and resources are discovered live from this MCP connection.** Always read the current `tools/list`, `prompts/list`, and `resources/list` before acting — a cached capability list is not authoritative after a server deployment. This skill teaches the workflows and the strict request contracts; it deliberately does not copy the server's tool catalog, metric/transform vocabulary, signal IDs, formulas, or default values. Discover those from the live tools (`list_strategy_categories`, `list_strategy_vocabulary`, `list_strategy_signals`, `get_strategy_signal_definition`, …). Never guess a metric, transform, parameter, template, signal, or enabled-timeframe fact.
+
+## Single-account vs multi-account request shape
+
+The strategy-authoring tools — `get_strategy_section_template`, `update_strategy_signal_rule`, `compile_strategy_plan`, `apply_strategy_plan` — use one strict server-owned envelope, `{ request: canonicalPayload }`.
+
+- **Single account:** call them as the server publishes them, e.g. `compile_strategy_plan({ request })`.
+- **Multiple accounts (proxy):** live discovery adds a sibling `account`, so the shape is exactly `{ account, request }`. Select the account in the outer field; keep `request` exactly as discovered. The proxy strips only `account` and forwards the unchanged `{ request }`.
+
+Never put `account` inside `request`, and never flatten request fields beside it. Other tools keep whatever input shape live discovery reports for them.
+
+## Scopes
+
+- `mcp:read` — strategy discovery **and** non-financial configuration writes (author strategies, edit agents, customize signals). Treat it as configuration authority, not view-only.
+- `mcp:wager` — financial actions (submit paid entries, accept/cancel entry decisions, deployment policies). Enable **Server-Signed Wagers** in Profile → MCP to grant it. Pending entry decisions come from the conversational surface, which waits for approval; an agent deployed to a radar coin or a trading-enabled arena slot executes without one.
+
+## Author a strategy: compile → review → apply
+
+Strategies are authored through one strict, whole-plan workflow. **Compilation changes no strategy, agent or revision; `apply_strategy_plan` is the only write to the strategy itself** — but compile is not read-only either: it parks the plan its own apply reads, and each call mints a distinct record and token, so compile once per reviewed payload and never retry or parallelise it. Review the exact returned plan before confirming.
+
+1. **Choose the operation and revision.**
+   - `list_strategies({ includeInactive? })` — visible SYSTEM and owned PRIVATE strategies with lifecycle, quota, usage, and revisions. Use `includeInactive:true` to prepare a RESTORE.
+   - `get_strategy({ strategyId, includeInactive? })` — the complete report, dense signal scorecard, gates, usage, and current `revision`. Thread every returned revision into the next revisioned call.
+2. **Discover the report vocabulary progressively.**
+   - `list_strategy_categories()` → `list_strategy_vocabulary({ category })` → `get_metric_construction_hints({ metric })` → `get_strategy_column_contract({ column, sectionTimeframe? })`.
+   - `get_strategy_section_template({ request })` for a listed template; `preview_strategy_report(payload)` for a point-in-time rendered preview.
+3. **Discover signals at the strategy timeframe.**
+   - `list_strategy_signals({ module?, query? })` → `get_strategy_signal_definition({ signalId, timeframe })`. Availability is structural, not a promise of a live trigger.
+4. **(Optional) review draft-only guidance.**
+   - `derive_strategy_rule_view({ sections, rules? })` returns report perception, server defaults, and suggestions without reading or writing a strategy. Suggestions/resets only shape the next plan input; they persist only through `apply_strategy_plan`.
+5. **Compile one complete plan.**
+   - `compile_strategy_plan({ request })`, where the nested request contains exactly one strict branch plus a bounded `coinSelection`, `intentSummary`, and `assumptions`:
+     - **CREATE** — supplies the full new aggregate.
+     - **UPDATE** — supplies at least one changed axis and `expectedRevision`. **Send only the
+       axes that change.** The server preserves every axis you omit and every signal you do not
+       name, and it re-derives the complete post-state, scorecard and diff itself. Restating the
+       whole post-state changes nothing about the result and the account pays for those tokens on
+       this call and on every later step of the conversation. Three fields are *not* axes and are
+       required on every compile regardless — `intentSummary`, `assumptions` and `coinSelection`;
+       omitting one is a typed error, not a saving.
+     - **RESTORE** — targets an owned inactive revision and may include repair axes.
+   - Signal overrides are sparse: an omitted signal/axis stays unchanged; omitted `params` preserves canonical params byte-for-byte; present `params` replaces them only after strict validation.
+   - **`required` needs a weight.** A rule with `required: true` at `allocation: 0` is rejected (contract 34): the scorecard's triggered set excludes Off, so the flag could satisfy no gate and block no trade. Either raise the allocation or leave `required: false` — the server picks neither for you. The refusal names every offending signal in `details.inertRequiredSignalIds`, and it can fire on rules you did not touch: a strategy authored before contract 34 may hold the pair, and the merged post-state is what gets checked.
+6. **Review before confirming.**
+   - `approvedPlan` — complete post-state, proposed revision, dense scorecard, viability, canonical diff, expiry, and bound-agent impact.
+   - `reviewContext` — exact column contracts, point-in-time report preview and coin scope, open-position observation, and provisional quota/name admission (advisory until the write). Open positions are awareness only and do not block an edit.
+   - The plan token expires after five minutes. Recompile after expiry, catalog drift, revision drift, or a changed bound-agent fence.
+7. **Apply the plan the server already holds.**
+   - After explicit user approval: `apply_strategy_plan({ request: { planToken, confirm: true } })`. **There is no `plan` member** — one is rejected as an unknown key. The server keeps the plan its own compile approved and reads it back, so nothing is copied from the compile response and nothing can be mistyped, truncated or half-reconstructed in transit.
+   - Forward `planToken` byte-for-byte exactly as compile returned it. It is an opaque signed value: never retyped, paraphrased, abbreviated or rebuilt from memory. A mangled token addresses no approved plan and is refused.
+   - Refusals and their recoveries: `PLAN_APPROVAL_NOT_FOUND` means no approved plan answers to this token — it was already applied, it lapsed, or it was never issued; compile again. `TOKEN_EXPIRED` means the five minutes ran out; compile again. Anything else — a quota, a name collision, a bound agent that changed, a moved catalog — **leaves the plan applicable**: clear the cause and confirm again with the same token while it lives.
+   - Changed configuration reaches every bound agent immediately. Report the returned strategy, committed revision, changed axes and applied impact exactly as given, and use that returned revision for the next mutation.
+
+**Focused edits & lifecycle:** `update_strategy_signal_rule({ request })` is the thin one-rule edit (requires `required`; omit `params` to preserve them; `required: true` needs `allocation > 0`). `fork_strategy` requires `sourceRevision`; `archive_strategy` requires `expectedRevision` and `confirm:true`; `restore_strategy` is only the thin unchanged-content path — if it reports `REPAIR_REQUIRED`, use the RESTORE compile/review/apply flow instead.
+
+**Author the full surface, not a template.** A bare compile — a few platform sections, no conditions, untouched signal weights — uses a fraction of the studio: the strategy aggregate also owns typed conditions (verdicts + `required` enforcement gates), tiered signal allocations with per-signal params, routing gates (`minAggregateScore`, `minRequiredCount`, `minAtrPct`), the ATR stop band + risk-reward floor, post-entry position management (break-even / trailing / time-decay), and marker-bearing Market Read prose. The companion **`battlegrid-strategy-studio` skill** (shipped beside this one) carries the capability map plus validated desk-grade playbooks and recipes for all of it — activate it whenever a strategy is being created or upgraded.
+
+## Strategy-bound agents
+
+Bind a strategy to an agent at creation time — there is no direct strategy-creation tool.
+
+1. `list_approved_models()` — valid `modelId` values for agent creation/update.
+2. `list_strategies()` — pick the `strategyId` to bind.
+3. `create_intelligence_agent({ …, modelId, strategyId })` — create a strategy-bound agent (avatar is server-minted).
+4. `update_intelligence_agent({ agentId, … })` — update config; rebinding via `strategyId` requires `confirm:true`.
+5. `get_agent_journal({ agentId })` / `get_agent_automation_status({ agentId })` — monitor performance and deployments.
+
+## Play a game (Market Grid)
+
+Predict UP or DOWN for each coin in the pool; exactly one coin is your **Captain** (2x score multiplier). Drive it from the live tools:
+
+1. `get_account_state()` — balance, rank, agent slots, wager status.
+2. `list_market_grid_sessions({ status: "PENDING" })` — find an open game (a `$0` entry fee is risk-free).
+3. `get_market_grid_session({ sessionId })` — coin pool, timeframe, payout structure.
+4. `get_market_context({ sessionId })` — indicators, rankings, and trends for the session.
+5. `check_market_grid_submission({ sessionId })` — avoid duplicate submissions (`update_market_grid` to modify).
+6. `submit_market_grid({ sessionId, grid, reasoning, confidenceScore, modelName, pickReasoning })` — submit predictions.
+7. `get_market_grid_results({ sessionId })` — results once the session is `SETTLED`.
+
+**Grid validation:** grid size matches the coin pool; each coin appears once; positions are sequential (0,1,2,…); exactly one cell is `isCaptain: true`.
+
+The `play-market-grid` prompt (discover via `prompts/list`) provides a guided end-to-end workflow.
+
+## Retired operations
+
+`create_strategy` (and other legacy direct-authoring/agent-scoped rule tools) are **retired** — they are absent from discovery and cannot be invoked. Author strategies with compile → review → apply, edit rules with `update_strategy_signal_rule`, and bind strategies to agents at agent creation. Do not attempt flat legacy payloads; the server enforces a closed-world request root and the proxy never reconstructs them.
+
+## Common errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `BATTLEGRID_API_KEY is required` | Missing API key | Set `BATTLEGRID_API_KEY` (or `BATTLEGRID_API_KEYS`) |
+| `API key must start with "bg_live_"` | Invalid key format | Generate a new key at battlegrid.trade → Profile → MCP |
+| Authentication failed (401/403) | Key revoked/rotated | Generate a new key and **restart** the proxy (keys read once at startup) |
+| `"account" parameter is required` | Multi-account call missing `account` | Add the outer `account`; keep `request` unchanged |
+| Plan token expired / revision drift | >5 min since compile, or upstream changed | Recompile, review the fresh plan, then apply |
+| Required at allocation Off | A rule flags `required` on a signal weighted `0` (contract 34) | Read `details.inertRequiredSignalIds`; per signal either raise `allocation` or set `required: false` |
+| Method not found | Calling a retired/unknown tool | Re-run `tools/list`; use the compile → review → apply flow |
+| `Wager scope required` | `mcp:wager` not enabled | Enable Server-Signed Wagers in Profile → MCP |

package/dist/index.d.ts

@@ -49,7 +49,7 @@ import { type Implementation } from '@modelcontextprotocol/sdk/types.js';
  * being asked. Move it for a change to THIS package — a proxy fix, a dependency bump, a docs
  * correction. Never move it to track the server.
  */
-export declare const PACKAGE_VERSION = "31.0.3";
+export declare const PACKAGE_VERSION = "31.1.5";
 export declare const DEFAULT_URL = "https://mcp.battlegrid.trade/mcp";
 export interface EnvConfig {
     apiKeys: string[];

package/dist/index.js

@@ -52,7 +52,7 @@ import { ListToolsRequestSchema, CallToolRequestSchema, ListPromptsRequestSchema
  * being asked. Move it for a change to THIS package — a proxy fix, a dependency bump, a docs
  * correction. Never move it to track the server.
  */
-export const PACKAGE_VERSION = '31.0.3';
+export const PACKAGE_VERSION = '31.1.5';
 export const DEFAULT_URL = 'https://mcp.battlegrid.trade/mcp';
 const MAX_RETRIES = 3;
 const RETRY_DELAYS_MS = [2000, 4000, 8000];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@battlegrid/mcp-server",
-  "version": "31.0.3",
+  "version": "31.1.5",
   "description": "BattleGrid MCP server — play crypto prediction games from AI agents",
   "type": "module",
   "main": "dist/index.js",
@@ -10,7 +10,9 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "SKILL.md",
+    "skills"
   ],
   "scripts": {
     "build": "tsc",