@battlegrid/mcp-server 32.0.64 → 32.0.65

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -47,7 +47,7 @@ import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/cli
47
47
  * being asked. Move it for a change to THIS package — a proxy fix, a dependency bump, a docs
48
48
  * correction. Never move it to track the server.
49
49
  */
50
- export declare const PACKAGE_VERSION = "32.0.64";
50
+ export declare const PACKAGE_VERSION = "32.0.65";
51
51
  export declare const DEFAULT_URL = "https://mcp.battlegrid.trade/mcp";
52
52
  export interface EnvConfig {
53
53
  apiKeys: string[];
package/dist/index.js CHANGED
@@ -49,7 +49,7 @@ import { Client, SdkHttpError, StreamableHTTPClientTransport } from '@modelconte
49
49
  * being asked. Move it for a change to THIS package — a proxy fix, a dependency bump, a docs
50
50
  * correction. Never move it to track the server.
51
51
  */
52
- export const PACKAGE_VERSION = '32.0.64';
52
+ export const PACKAGE_VERSION = '32.0.65';
53
53
  export const DEFAULT_URL = 'https://mcp.battlegrid.trade/mcp';
54
54
  const MAX_RETRIES = 3;
55
55
  const RETRY_DELAYS_MS = [2000, 4000, 8000];
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@battlegrid/mcp-server",
3
- "version": "32.0.64",
3
+ "version": "32.0.65",
4
4
  "description": "BattleGrid MCP server — play crypto prediction games from AI agents",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -1,24 +1,24 @@
1
1
  {
2
2
  "generator": "battlegrid-app/server/scripts/export-mcp-skills.mjs",
3
- "contractVersion": "144.2.0",
3
+ "contractVersion": "146.0.0",
4
4
  "files": {
5
5
  "battlegrid-agent-management/SKILL.md": "324ef8181bfcfc99b955d9644ed543c6ab91071153d43f77ccf0a4979b896b09",
6
6
  "battlegrid-agent-management/references/agent-stage-examples.md": "dffcc353d61dfc7b5bb6a2b3077fc6bf8c760a34c287cafb3b59b99306f24195",
7
7
  "battlegrid-arena-play/SKILL.md": "fdaabcd2e5ce3946ee96e553ce2e1931a822b84f91b0c94ce86a8bde0cc1d50f",
8
8
  "battlegrid-arena-play/references/entry-stage-examples.md": "0223f3743171ff213e943789d27590b2f65648398e85e10cd24938d5eb6af665",
9
- "battlegrid-market-analysis/SKILL.md": "e50a63492c635af9e8748561148efd7e1d9aafdfb843acc657e557670b2f55e4",
9
+ "battlegrid-market-analysis/SKILL.md": "889ba8a805585db5bfed0c72722d8b177174e8b145fb054619a5dc792cc92b09",
10
10
  "battlegrid-officers/SKILL.md": "0ac2173d0026b7329171fe24d38185e7717196340778d402c7af1aa74ea34bc8",
11
11
  "battlegrid-officers/references/officer-stage-examples.md": "ef46ba26f4b36c9964b5bde95fdf98e5952c3786b77be5f136056cac792f0aec",
12
- "battlegrid-radar-deployment/SKILL.md": "5a72ee1aede27adbbb398ee99883ce36579c01352a0543782451af5d9a91d5f9",
13
- "battlegrid-radar-deployment/references/arena-stage-examples.md": "d27cfed1f4663f267c4a7ecebe4a6e65a450fc74bd14ce8987fb61af5bbf2ca5",
14
- "battlegrid-radar-deployment/references/radar-stage-examples.md": "a07a6f1c525a5c4d60b5ba3ec9d896c6e4a0f8fb9968b9fd539c738956babc47",
15
- "battlegrid-strategy-authoring/SKILL.md": "dc36ffee1d474aec471c0ff474b13dd15e4d466b6c14b60d3aeb9e9234baf80e",
12
+ "battlegrid-radar-deployment/SKILL.md": "ef291ec096461ed2b78915adbfa41000b959b5803ae4ebef3084bff4c1e1a746",
13
+ "battlegrid-radar-deployment/references/arena-stage-examples.md": "65af54b67c3248c53fb8911df769ad32824e1f1f1d83ffc007b42a888d5e3076",
14
+ "battlegrid-radar-deployment/references/radar-stage-examples.md": "7a4195011aa764b106567606f7a2a8ae8e9b2bf74c36b3c74a72379969d70af8",
15
+ "battlegrid-strategy-authoring/SKILL.md": "174ecf79f043b171841347fe33f9ddb166641afe92a7fdc805e6d691aefc5929",
16
16
  "battlegrid-strategy-authoring/references/strategy-stage-examples.md": "f10ecdc91f3660a708eee7a7bacefce2acbb46c9cf7e0ac1454bd54f839f39fd",
17
17
  "battlegrid-strategy-doctor/SKILL.md": "4be392e51f3b5e76ff4aa22f61700236e8b1e19dfe286aeda8ed98e48a8457ba",
18
- "battlegrid-strategy-examples/SKILL.md": "cbbc7a7271aaa9f530a11d91511f4bf35a9632aa3ab67ecd996975c65ae72625",
18
+ "battlegrid-strategy-examples/SKILL.md": "05769532a8a834148292e2285c6c0044050a8ff16d08da4835845b65657d79c6",
19
19
  "battlegrid-strategy-examples/references/playbooks.md": "59996c37eea08e7ce398e49304171939e55c968400a1603597d6737faf9e1771",
20
- "battlegrid-strategy-examples/references/recipes.md": "4136ff306f32d1e3aa612ac13a116d58df2177f619464ab2481a84f608e56cfc",
21
- "battlegrid-strategy-examples/references/tradingview-ports.md": "bc63e26b16458fd17b7bc567541fc9889ee857b444ccb2d3f011545635758d8f",
20
+ "battlegrid-strategy-examples/references/recipes.md": "ee1b35f5341d3878ef8e8b045d0425a06fb25c76149fe841f2afe075909135f4",
21
+ "battlegrid-strategy-examples/references/tradingview-ports.md": "fa25a447843c9f30784d855adcd58dcc1a2bf6a0de7749a67455fb25b2b285e2",
22
22
  "battlegrid-trade-analysis/SKILL.md": "ec0b543bc62fe66d629833b10e4bc58548be1fee57f29c04f41f036e860af1ca",
23
23
  "battlegrid-trade-proposal/SKILL.md": "8d833022f753dfc5a765eca2fcd272c4f29d22b8444bc00c14ce63571646ba71"
24
24
  }
@@ -24,9 +24,10 @@ Run these in order. Skip a step only when the player's question makes it irrelev
24
24
  snapshot's evidence before its label: a label the hysteresis buffer is **holding** is the
25
25
  previous bar's, not this bar's, and conviction names which rule matched, not how comfortably —
26
26
  the margins to each gate say how close the read is to turning.
27
- 2. **Market context.** `get_market_context` — this carries the breadth, funding and open-interest
28
- picture. Funding and OI are the two figures most often skipped and most often decisive: crowded
27
+ 2. **Market context.** `get_market_context` — this carries the funding and open-interest picture.
28
+ Funding and OI are the two figures most often skipped and most often decisive: crowded
29
29
  positioning is the difference between "trend" and "trend about to be squeezed". Report both.
30
+ How much of the field is moving is step 4b's read.
30
31
  3. **Leaders and laggards.** One ranked `preview_strategy_report` per end, each returning the coins
31
32
  with their rows, so no per-coin follow-up is needed: `coinSelection: { mode: "ranked", limit: 10,
32
33
  category: "ALL", rankBy: { metric: "ROC12", ordering: "hi" } }` for the leaders and `ordering: "lo"`
@@ -58,11 +59,32 @@ Run these in order. Skip a step only when the player's question makes it irrelev
58
59
  Coin symbols are case-insensitive and exchange symbols are accepted (`btc`, `kPEPE`,
59
60
  `xyz:BRENTOIL`); a symbol that names no tracked coin is rejected with an error naming the field,
60
61
  never answered as an empty read — say the coin is not tracked rather than retrying it.
61
- 4b. **How much of the FIELD is moving, not just this coin.** Add the Market Breadth module
62
- (`{ "kind": "platform", "sectionKey": "includeMarketBreadth" }`) for the two-axis read: how much
63
- of the tracked universe closed up, and how much of it carries positive momentum. It reports per
64
- category as well as whole-universe, so a crypto call is not swayed by an equities selloff. Those
65
- are report-level scalars — one table for the whole answer, not a per-coin download.
62
+ 4b. **How much of the FIELD is moving, not just this coin.** Add a custom section bound to the
63
+ market at one breadth scope to the same `preview_strategy_report` call — `{ "kind": "custom",
64
+ "title": "Crypto breadth", "benchmarkTicker": null, "marketScope": "crypto", "notes": null,
65
+ "columns": [ … ] }` — with the market columns the question needs: `MKT_NET` (`mktBreadth`, the
66
+ up share less the down share) and `MKT_PPO_NET` (`mktPpoNet`, the same over positive versus
67
+ negative momentum) for the two-axis read, and `MKT_ABOVE_EMA` under `classifyZone`
68
+ (`mktAboveEma_zone`: `risk-off` when 20% or less of the scope closes above its own EMA(50),
69
+ `risk-on` at 80% or more, `neutral` between) for the persistent state. Each column is
70
+ `{ "metric": "MKT_NET", "transformId": "value", "timeframe": { "rel": "anchor" } }` in shape. The
71
+ section renders ONE row for the whole field, named by its scope, never a per-coin download; the
72
+ scopes are `all`, `crypto`, `l1`, `memes`, `defi`, `tradfi`, `stocks`, `indices` and
73
+ `commodities`, so a crypto call is not swayed by an equities selloff — two scopes are two
74
+ sections. A market reading is a series from the moment it was first recorded: a trajectory or a
75
+ regime-timeframe column (`"timeframe": { "rel": "regime" }` → `mktBreadth_htf`) works as on any
76
+ coin column, and a window reaching back before the series began reads absent — say so rather
77
+ than reading it as a flat market.
78
+ 4c. **Stablecoin stress.** When the question is whether the dollar legs are holding, bind a section
79
+ to a declared pair — `"benchmarkTicker": "USDT_USD"` (USDT against USD on Coinbase) or
80
+ `"USDC_USDT"` (USDC against USDT on Binance), spelled exactly so — with `PAR_DEV` columns:
81
+ `parDev` is the close's signed % from its par of 1, and `parDev_zone` reads `at par` inside
82
+ ±0.20%, `drifting` from there to under ±1.00% and `depegged` at ±1.00% or beyond. On the
83
+ `USDT_USD` section,
84
+ `{ "metric": "PAR_DEV", "transformId": "relativeTo", "timeframe": { "rel": "anchor" }, "instrument": "USDC_USDT" }`
85
+ (`parDev_USDC_USDT_rel`) is USDT's deviation less USDC/USDT's, in points — money rotating
86
+ between the two. A cross-venue price premium embeds this peg, so read it beside any premium you
87
+ report.
66
88
  5. **Close with what to watch.** Every answer ends with levels or conditions — the price that
67
89
  invalidates the read, the level that confirms it, the event that would change it. An analysis
68
90
  with no "what to watch" close is unfinished.
@@ -135,9 +135,17 @@ from what the player asked for:
135
135
  |---|---|
136
136
  | whenever no rule matches | `DEFAULT_SLOT` — on duty only while no rule matches, so on a coin with no rules it is on duty at every instant |
137
137
  | only in named regimes | a rule with a regime condition |
138
+ | in a named regime, standing down while a warning holds | a rule with a regime condition whose `duringWarnings` is `pause` |
138
139
  | only in named hours and days | a rule with an hours condition |
139
140
  | in named regimes during named hours | a rule with one hours condition and one regime condition |
140
141
 
142
+ A regime condition reads three facts of one reading. `regimes` names the market structures (`bull_trend`,
143
+ `bear_trend`, `bull_range`, `bear_range`); `volatilities` names the volatility levels it runs in, all three meaning no
144
+ volatility constraint; `duringWarnings` says what a warning — a crash, or momentum diverging in a trend — does to it:
145
+ `run` keeps it on duty, `pause` stands it down, `only` puts it on duty only while one holds. A warning never changes
146
+ the structure, so a bear-trend rule on `run` stays on duty through a crash. Stage all three levels and `run` unless
147
+ the player narrows them, and say which you staged.
148
+
141
149
  Radar's market hours answer *when may this agent trade*, and shift with daylight saving; a strategy's
142
150
  `TRADING_SESSION` condition answers *which session is this bar in*, over fixed UTC windows — the two are
143
151
  different questions, and a player asking for one is not asking for the other.
@@ -181,6 +189,7 @@ it. Pick the construction from what the player asked for:
181
189
  |---|---|
182
190
  | whenever no rule matches | `DEFAULT_SLOT` — plays only when no rule wins the session |
183
191
  | only in named regimes | a rule with a regime condition |
192
+ | in a named regime, sitting out while a warning holds | a rule with a regime condition whose `duringWarnings` is `pause` |
184
193
  | only at named session starts, or one scheduled occurrence | a rule with one session condition — a start or an occurrence |
185
194
  | in named regimes at those sessions | a rule with a regime condition and one session condition |
186
195
 
@@ -194,7 +203,8 @@ repeatedly while iterating is free and correct.
194
203
 
195
204
  Render the preview as a card and read it out. For **Radar**: the coin's `section` and any typed idle
196
205
  or blocked reason, then every row of `resolvesNow.onDuty` in the order served — each agent, the slot
197
- and priority that put it on duty, its regime reading at its own `regimeTimeframe` with conviction, its
206
+ and priority that put it on duty, its regime reading at its own `regimeTimeframe` with conviction, volatility and
207
+ warnings, its
198
208
  qualification verdict and its close clock — and `readings`, one entry per on-duty agent in the same
199
209
  order: what that agent reads on the coin right now (below). For **Arena**: which agent goes on duty,
200
210
  which slot matched and at what priority, the regime and conviction used, and the qualification
@@ -253,7 +263,9 @@ resolver:
253
263
 
254
264
  An `UNSCORABLE` entry is an on-duty agent the preview could not read on the coin, with
255
265
  `coinDataStopped` when the coin's data explains why; it never fails the preview. `readings` is null
256
- under a simulated regime: duty is simulated there, and every reading would judge the real one.
266
+ under a simulated reading: duty is simulated there, and every reading would judge the real one. A simulated
267
+ reading is whole — `{ regime, volatility, warnings }`, the warnings only those its structure can carry (a crash on any,
268
+ momentum divergence on a trend only) — and is judged at maximum conviction.
257
269
 
258
270
  There is no `conditionReach` list and no `blocksScanGate` flag (contract 74.0.0). A condition's reach
259
271
  reason is its `UNEVALUATED` entry's `reachReason` in
@@ -29,6 +29,12 @@ axis you omit keeps the value the draft already has.
29
29
 
30
30
  ## Play only in named regimes
31
31
 
32
+ A regime condition names the market structures its rule plays in — `bull_trend`, `bear_trend`, `bull_range`,
33
+ `bear_range` — with `volatilities`, the volatility levels it plays in (all three place no constraint), and
34
+ `duringWarnings`, what it does while the reading carries a warning: `run` keeps playing, `pause` sits out until
35
+ the warning clears, `only` plays only while one holds. Both are required; send all three levels and `run` unless
36
+ the player narrows them.
37
+
32
38
  ```json stage_deployment_policy_draft
33
39
  {
34
40
  "presetId": "<PRESET_ID>",
@@ -39,7 +45,14 @@ axis you omit keeps the value the draft already has.
39
45
  {
40
46
  "agentId": "<AGENT_ID>",
41
47
  "minConfidence": null,
42
- "conditions": [{ "kind": "regime", "regimes": ["bull_expansion", "bull_ranging"] }]
48
+ "conditions": [
49
+ {
50
+ "kind": "regime",
51
+ "regimes": ["bull_trend", "bull_range"],
52
+ "volatilities": ["contracting", "normal", "expanding"],
53
+ "duringWarnings": "run"
54
+ }
55
+ ]
43
56
  }
44
57
  ]
45
58
  }
@@ -74,6 +87,8 @@ session occurrence, never both.
74
87
 
75
88
  ## In named regimes at those sessions — a regime condition and one session condition
76
89
 
90
+ This rule plays a bear trend at the US open and sits out while a crash or a momentum divergence holds.
91
+
77
92
  ```json stage_deployment_policy_draft
78
93
  {
79
94
  "presetId": "<PRESET_ID>",
@@ -85,7 +100,12 @@ session occurrence, never both.
85
100
  "agentId": "<AGENT_ID>",
86
101
  "minConfidence": null,
87
102
  "conditions": [
88
- { "kind": "regime", "regimes": ["volatile"] },
103
+ {
104
+ "kind": "regime",
105
+ "regimes": ["bear_trend"],
106
+ "volatilities": ["contracting", "normal", "expanding"],
107
+ "duringWarnings": "pause"
108
+ },
89
109
  { "kind": "session_start", "startTimes": ["14:00:00"], "days": [1, 2, 3, 4, 5] }
90
110
  ]
91
111
  }
@@ -34,8 +34,49 @@ on this coin" with no condition named.
34
34
 
35
35
  ## On duty only in named regimes
36
36
 
37
+ A regime condition names the market structures its rule is on duty in — `bull_trend`, `bear_trend`, `bull_range`,
38
+ `bear_range` — and two more settings, both required:
39
+
40
+ - `volatilities` — the volatility levels (`contracting`, `normal`, `expanding`) the rule runs in, each listed once.
41
+ All three place no volatility constraint; that is the setting to send unless the player narrows it.
42
+ - `duringWarnings` — what the rule does while the reading carries a warning (a crash, or momentum diverging in a
43
+ trend): `run` keeps it on duty, `pause` stands it down until the warning clears, `only` puts it on duty only while
44
+ a warning holds. `run` is the setting to send unless the player says otherwise.
45
+
37
46
  `minConviction` on the rule is the trade bar (0–1, or null to inherit the agent's). `minConviction` inside the
38
- regime condition is the regime-reading floor, and must be a level one of the selected regimes can emit.
47
+ regime condition is the regime-reading floor, and must be a level one of the selected regimes can emit at one of the
48
+ selected volatilities.
49
+
50
+ ```json stage_radar_deployment_draft
51
+ {
52
+ "coinId": "<COIN_ID>",
53
+ "draftVersion": 0,
54
+ "axes": {
55
+ "RULES": {
56
+ "rules": [
57
+ {
58
+ "agentId": "<AGENT_ID>",
59
+ "minConviction": null,
60
+ "conditions": [
61
+ {
62
+ "kind": "regime",
63
+ "regimes": ["bull_trend", "bull_range"],
64
+ "minConviction": "high",
65
+ "volatilities": ["contracting", "normal", "expanding"],
66
+ "duringWarnings": "run"
67
+ }
68
+ ]
69
+ }
70
+ ]
71
+ }
72
+ }
73
+ }
74
+ ```
75
+
76
+ ## In a bear trend, standing down during warnings
77
+
78
+ A crash continues a bear trend as often as it ends one, so whether a warning stops the rule is the player's call.
79
+ Here the agent works the bear trend and stands down while a crash or a momentum divergence holds.
39
80
 
40
81
  ```json stage_radar_deployment_draft
41
82
  {
@@ -48,7 +89,12 @@ regime condition is the regime-reading floor, and must be a level one of the sel
48
89
  "agentId": "<AGENT_ID>",
49
90
  "minConviction": null,
50
91
  "conditions": [
51
- { "kind": "regime", "regimes": ["bull_expansion", "bull_ranging"], "minConviction": "high" }
92
+ {
93
+ "kind": "regime",
94
+ "regimes": ["bear_trend"],
95
+ "volatilities": ["contracting", "normal", "expanding"],
96
+ "duringWarnings": "pause"
97
+ }
52
98
  ]
53
99
  }
54
100
  ]
@@ -86,6 +132,8 @@ close is served: a close is staged only as hours the player names.
86
132
 
87
133
  ## In named regimes during named hours — one condition of each kind
88
134
 
135
+ This rule trades either trend, but only while volatility is expanding, and only in the US session hours.
136
+
89
137
  ```json stage_radar_deployment_draft
90
138
  {
91
139
  "coinId": "<COIN_ID>",
@@ -98,7 +146,12 @@ close is served: a close is staged only as hours the player names.
98
146
  "minConviction": 0.6,
99
147
  "conditions": [
100
148
  { "kind": "hours", "hours": [13, 14, 15, 16], "days": [1, 2, 3, 4, 5] },
101
- { "kind": "regime", "regimes": ["volatile"] }
149
+ {
150
+ "kind": "regime",
151
+ "regimes": ["bull_trend", "bear_trend"],
152
+ "volatilities": ["expanding"],
153
+ "duringWarnings": "run"
154
+ }
102
155
  ]
103
156
  }
104
157
  ]
@@ -123,7 +176,14 @@ first agent's regimes.
123
176
  {
124
177
  "agentId": "<AGENT_ID>",
125
178
  "minConviction": null,
126
- "conditions": [{ "kind": "regime", "regimes": ["bear_expansion", "bear_ranging"] }]
179
+ "conditions": [
180
+ {
181
+ "kind": "regime",
182
+ "regimes": ["bear_trend", "bear_range"],
183
+ "volatilities": ["contracting", "normal", "expanding"],
184
+ "duringWarnings": "run"
185
+ }
186
+ ]
127
187
  }
128
188
  ]
129
189
  },
@@ -105,10 +105,12 @@ anywhere; if the two ever disagree, you have created the exact ambiguity this st
105
105
 
106
106
  The player's own saved sections are listed among the vocabulary's templates as `kind: "saved"`.
107
107
  When the player names one, fetch it with `get_strategy_section_template` and place its title, note,
108
- `benchmarkTicker` and columns in a new custom section — a copy, with no `sectionKey`.
108
+ subject (`benchmarkTicker`, `marketScope`) and columns in a new custom section — a copy, with no
109
+ `sectionKey`.
109
110
 
110
111
  **Keeping a section.** `save_report_section` keeps a custom section in the player's library: send its
111
- title, note, `benchmarkTicker` and columns as `section`, dropping `kind` and `sectionKey`. Save only
112
+ title, note, subject (`benchmarkTicker`, `marketScope`) and columns as `section`, dropping `kind`
113
+ and `sectionKey`. Save only
112
114
  when the player asks to keep one — offer it, never decide it. Before the save, say whether the
113
115
  vocabulary already lists that title as `saved`; if it does, the save replaces that saved section's
114
116
  note, subject and columns whole. `remove_saved_report_section` drops one by its `savedSectionId`:
@@ -181,6 +183,14 @@ question you would otherwise guess — and a refusal you would otherwise earn:
181
183
  - `get_metric_construction_hints` → `rankOrderings`. Present only when rank is composable on that
182
184
  metric, already range-gated server-side — read the offered set rather than deriving one from
183
185
  the metric's native output.
186
+ - `get_metric_construction_hints` → `subjectKinds`: the section subjects that may carry the metric
187
+ — `evaluated-coin`, `benchmark` (a bound coin), `reference` (a bound stablecoin pair) and
188
+ `market`. The market metrics and `PAR_DEV` sit only in a section bound to the market
189
+ (`marketScope`) or to a pair (`benchmarkTicker: "USDT_USD"`); in a section of any other subject
190
+ the save refuses them (`REPORT_COLUMN_SUBJECT_METRIC_UNSUPPORTED`). When you ask
191
+ `get_strategy_column_contract` about a column of a bound section, pass that section's
192
+ `benchmarkTicker` or `marketScope` with it; omitted, the column is judged on the coin under
193
+ evaluation.
184
194
 
185
195
  For full-surface composition patterns — custom and benchmark sections, condition trees with
186
196
  verdicts and `required` enforcement, the trade-level policy with its ATR floor, position-management
@@ -421,7 +431,10 @@ never retry the same call blindly.
421
431
  field (`Unknown coin symbol: '<input>'`), with nothing written. Symbols are case-insensitive and
422
432
  exchange symbols resolve (`btc`, `kPEPE`, `xyz:BRENTOIL` all reach their coin, and the draft
423
433
  stores the canonical ticker), so the refusal means the coin is not tracked: never retry with
424
- another casing — ask the player which coin they meant.
434
+ another casing — ask the player which coin they meant. The one exception is a declared
435
+ stablecoin pair, the only `benchmarkTicker` that is not a coin: `USDT_USD` and `USDC_USDT` are
436
+ matched exactly as declared, so `usdt_usd` is refused as an unknown coin — send the declared
437
+ spelling.
425
438
 
426
439
  ## When the grammar cannot express the ask
427
440
 
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: battlegrid-strategy-examples
3
- description: Full-surface composition patterns for the strategy studio — validated desk-grade examples of custom report sections, benchmark sections, condition trees with verdicts and required enforcement, the entry-condition rule, ATR trade levels with the ATR floor, and position management. Activate beside strategy-authoring whenever a strategy is being composed or upgraded beyond a basic template.
3
+ description: Full-surface composition patterns for the strategy studio — validated desk-grade examples of custom report sections, benchmark, market-breadth and stablecoin-peg sections, condition trees with verdicts and required enforcement, the entry-condition rule, ATR trade levels with the ATR floor, and position management. Activate beside strategy-authoring whenever a strategy is being composed or upgraded beyond a basic template.
4
4
  ---
5
5
 
6
6
  # Strategy Studio — full-power composition patterns
@@ -73,7 +73,8 @@ day before it. **Daily-strategy pattern:** anchor 4h, pinned-1d thesis columns w
73
73
  columns only for entry timing and risk — daily inputs then move once per daily close while
74
74
  stops and time decay keep managing intraday. **Benchmark sections** (`benchmarkTicker: "BTC"`,
75
75
  required-nullable on every custom section) read the benchmark's values on every row — the
76
- standard market-leader regime gate. Platform `sectionKey`s are their literal keys
76
+ standard market-leader regime gate; a section can also read a stablecoin pair or the market itself
77
+ (`## Report sections`). Platform `sectionKey`s are their literal keys
77
78
  (`includeHigherTimeframe`). Custom `sectionKey`s are the **server's** to issue, and which of the two
78
79
  things you do depends on the operation: on a **CREATE, omit `sectionKey` entirely** — supplying one
79
80
  is refused, since a new strategy owns no custom sections yet; on an **UPDATE or RESTORE, send back
@@ -283,7 +284,7 @@ history the store keeps for that column, less the column's own lookback and warm
283
284
  the served domain is refused (`CONDITION_HOLD_ILLEGAL`, the domain in `allowedDomain`). The reasons
284
285
  a header admits only Once:
285
286
 
286
- - `NOT_REWINDABLE` — the value is stored for the current bar only (session and universe scalars,
287
+ - `NOT_REWINDABLE` — the value is stored for the current bar only (the session-field scalars,
287
288
  ranks, zone entities, enrichment metrics, a change at or below the strategy timeframe). **Worked liquidity floor:**
288
289
  `LIQUID_FLOOR` holds Once because `vol24hUsd` is a bundle scalar.
289
290
  - `DEVELOPING` — the column reads a bar still forming: a Developing candle column above the strategy
@@ -293,7 +294,8 @@ a header admits only Once:
293
294
  - `BAR_STATE` — the header describes only the bar being decided.
294
295
  - `HISTORY` — not enough history is stored on that timeframe to count more than one close.
295
296
 
296
- Candle columns (at, above or below the strategy timeframe), the regime (counted on the regime rung),
297
+ Candle columns (at, above or below the strategy timeframe), the market and stablecoin-pair columns
298
+ (each counted on its subject's own bars), the regime (counted on the regime rung),
297
299
  and the funding and open-interest histories (on the coarser of the strategy timeframe and their own
298
300
  hourly cadence) can all be held. **A crossover is an event**: it fires on the bar a state changes,
299
301
  so its `maxAtLeast` is 1 — hold a cross "within n closes", never "in a row".
@@ -331,13 +333,14 @@ traded price on display — not against the higher-timeframe bar's own close, wh
331
333
  higher-timeframe bar stale. A distance CHAINED into a series transform keeps every slot on its own
332
334
  bar's close, so one series carries one reference basis.
333
335
 
334
- **The lane a strategy is deployed to.** Report-level scalars split by LANE, and the split is not a
335
- quality of the header — it is which reader runs. Market breadth and the reference pairs are ordinary
336
- market-wide reads with no session dimension, so they resolve everywhere. The five **session-field**
337
- scalars (`fieldPlayers`, `fieldUpBias`, `fieldBiasDir`, `captConc`, `picksSpread`) describe a game
338
- session the agent is playing in, and **radar runs outside one** — so a radar deployment whose
339
- strategy reads one is refused outright (`CONDITION_OPERAND_UNSERVED_IN_LANE`), naming the scalars it
340
- can read instead.
336
+ **The lane a strategy is deployed to.** The one report-level scalar family is the **session field**:
337
+ five scalars (`fieldPlayers`, `fieldUpBias`, `fieldBiasDir`, `captConc`, `picksSpread`, each headed
338
+ `<key>_session` under the `session-field` section) that describe a game session the agent is playing
339
+ in. **Radar runs outside one**, so a radar deployment whose strategy reads one is refused outright
340
+ (`CONDITION_OPERAND_UNSERVED_IN_LANE`): no report-level scalar is readable in that lane, so remove the
341
+ clause or bind the strategy to an agent in a lane that reads a session. Market breadth and the
342
+ stablecoin pegs are not scalars — they are columns of market- and pair-bound sections, read per bar in
343
+ every lane like any other column.
341
344
 
342
345
  **What the radar scan can read on a coin.** Beyond the lane, a condition the radar acts on — a
343
346
  required one, one carrying a verdict, an exit rule, and every condition they reference — must be
@@ -597,12 +600,36 @@ parameters back beside it.
597
600
 
598
601
  ## Report sections
599
602
 
600
- `{ kind, sectionKey, title, benchmarkTicker, notes, columns }` — the custom section shape. A
601
- section carries no `timeframe`: its relative columns resolve against the strategy timeframe, and a
602
- column reaches any other timeframe by pinning it (`timeframe: { abs: '4h' }`). `benchmarkTicker` and `notes` are **required-nullable**: send an explicit `null` rather
603
+ `{ kind, sectionKey, title, benchmarkTicker, marketScope, notes, columns }` — the custom section
604
+ shape. A section carries no `timeframe`: its relative columns resolve against the strategy timeframe,
605
+ and a column reaches any other timeframe by pinning it (`timeframe: { abs: '4h' }`).
606
+ `benchmarkTicker`, `marketScope` and `notes` are **required-nullable**: send an explicit `null` rather
603
607
  than omitting them, because the section is rebuilt whole on save and an omitted key clears the
604
608
  author's value silently. On a CREATE, omit `sectionKey` — it is derived from the section itself.
605
609
 
610
+ **A section reads one subject**, named by its two subject keys — at most one of them set:
611
+
612
+ - both `null` — the coin under evaluation, one row per coin;
613
+ - `benchmarkTicker` — one bound instrument on every row: a roster coin (`"BTC"`, any spelling the
614
+ coin resolves from), or a declared stablecoin pair, `"USDT_USD"` (USDT against USD) or
615
+ `"USDC_USDT"` (USDC against USDT), spelled exactly as declared;
616
+ - `marketScope` — the market at one breadth scope (`all`, `crypto`, `l1`, `memes`, `defi`,
617
+ `tradfi`, `stocks`, `indices`, `commodities`), one row for the whole field. Two scopes are two
618
+ sections.
619
+
620
+ What a section may hold follows its subject, and the save refuses anything else
621
+ (`REPORT_COLUMN_SUBJECT_METRIC_UNSUPPORTED`, naming the `subjectKind` and the `metric`). A pair-bound
622
+ section reads `OPEN`, `HIGH`, `LOW`, `CLOSE` and `PAR_DEV` — the close's signed % from its par —
623
+ and a market section reads the `market` family (`MKT_NET` → `mktBreadth`, `MKT_ABOVE_EMA` →
624
+ `mktAboveEma`, and the rest); a coin section, evaluated or bound, reads neither. Read each metric's
625
+ `subjectKinds` from `get_metric_construction_hints` rather than this list. Neither a pair nor the
626
+ market takes a cross-coin `rank`; a market column takes no `relativeTo`, and a pair column's
627
+ `relativeTo` names the other declared pair and has no `BTC` default. Market and pair columns are
628
+ series from the moment the platform began recording them: every series transform, timeframe and
629
+ hold applies, and a window reaching before the first recorded bar reads absent. Headers carry no subject
630
+ token (`mktBreadth`, `mktBreadth_htf`, `parDev_zone`), so the section is what says whose reading a
631
+ header is. Worked sections and conditions: `references/recipes.md`, *Market and stablecoin subjects*.
632
+
606
633
  ## Trade levels
607
634
 
608
635
  `{ minStopLossAtrMultiple, maxStopLossAtrMultiple, minRiskRewardRatio, minAtrPct }` — where stops
@@ -657,8 +684,9 @@ and the absence section above. The worked material is disclosed on demand, so it
657
684
  you ask for it. Read a reference with `read_skill_reference` when you reach the work it covers:
658
685
 
659
686
  - **`references/recipes.md`** — copy-adaptable column objects and condition fragments: cross
660
- detection, board-relative ranks, cross-venue basis, crowd positioning, coin selection, and the
661
- discovery fields worth reading before you compose.
687
+ detection, board-relative ranks, cross-venue basis, crowd positioning, the market-regime and
688
+ stablecoin-peg sections, coin selection, and the discovery fields worth reading before you
689
+ compose.
662
690
  - **`references/playbooks.md`** — five validated desk-grade compositions end to end, and how to
663
691
  adapt one rather than copy it.
664
692
  - **`references/tradingview-ports.md`** — per-script port recipes for the popular TradingView
@@ -19,6 +19,7 @@ rather than events all live there. This document assumes them.
19
19
  - Board-relative rank recipes
20
20
  - Cross-venue and perp/spot basis
21
21
  - Crowd positioning
22
+ - Market and stablecoin subjects
22
23
  - Coin selection
23
24
  - Discovery fields worth reading
24
25
 
@@ -160,15 +161,91 @@ fragility read.
160
161
 
161
162
  ## Crowd positioning
162
163
 
163
- `CROWD_UPBIAS` is the platform's own crowd read — the share of recent settled sessions predicting UP,
164
- as a percentage:
164
+ The crowd's raw read is `CROWD_UPBIAS`, header `upBias`: the share of this coin's picks that are UP
165
+ across recent settled sessions, as a percentage. A share carries no sample size and no baseline, so
166
+ on its own it reads one pick at 100% as strongly as twenty, and on a board where everyone leans the
167
+ same way it calls every coin crowded.
168
+
169
+ The crowding read is its two significance scores, each a binomial z in standard errors:
170
+
171
+ ```json
172
+ { "metric": "CROWD_UP_LEAN_Z", "transformId": "value", "timeframe": { "rel": "anchor" } }
173
+ { "metric": "CROWD_UP_EXCESS_Z", "transformId": "value", "timeframe": { "rel": "anchor" } }
174
+ ```
175
+
176
+ Headers `upLeanZ` (how one-sided the crowd is on the coin, against 50%) and `upExcessZ` (how far
177
+ beyond the rest of the field). A coin is crowded long when both clear the significance threshold their
178
+ glosses state, and crowded short on the mirror. Read them as a fade input, not a trend input: they say
179
+ what the board expects, which is the thing a crowded-positioning playbook trades against. When the
180
+ whole field leans one way, `upExcessZ` is null and no coin stands out.
181
+
182
+ ## Market and stablecoin subjects
183
+
184
+ A section reads one subject (the skill body, `## Report sections`): the market readings live only on a
185
+ section bound to the market at one breadth scope, and the peg only on a section bound to a declared
186
+ stablecoin pair. So each recipe here is a whole custom section with the conditions that read it. Every
187
+ header is unique to its section, so a clause names it bare (`"sectionKey": null`) on a CREATE. Both
188
+ subjects are series from the moment the platform began recording them, so a window reaching before the
189
+ first recorded bar reads absent.
190
+
191
+ **Market regime — trade with the field.** A section bound to the `crypto` scope, reading the share of
192
+ crypto coins closing above their own EMA(50), its zone, and net breadth one rung up:
193
+
194
+ ```json
195
+ { "kind": "custom", "title": "Crypto breadth", "benchmarkTicker": null, "marketScope": "crypto", "notes": null,
196
+ "columns": [
197
+ { "metric": "MKT_ABOVE_EMA", "transformId": "value", "timeframe": { "rel": "anchor" } },
198
+ { "metric": "MKT_ABOVE_EMA", "transformId": "classifyZone", "timeframe": { "rel": "anchor" } },
199
+ { "metric": "MKT_NET", "transformId": "value", "timeframe": { "rel": "regime" } } ] }
200
+ ```
201
+
202
+ Headers `mktAboveEma` (%), `mktAboveEma_zone` (`risk-off` at 20 or below, `neutral` between, `risk-on`
203
+ at 80 or above) and `mktBreadth_htf` (the up share less the down share on the regime timeframe,
204
+ signed). The share above EMA holds its reading for runs of bars while net breadth turns almost every
205
+ bar, which is why the zone reads the share and the net is read a rung up. Two building blocks, for a
206
+ long carrier to reference beside the coin's own trigger; the short side mirrors them (`risk-off`,
207
+ `lt 0`):
208
+
209
+ ```json
210
+ { "conditionKey": "FIELD_RISK_ON", "name": "Crypto field risk-on for 3 closes", "verdict": null, "required": false, "exitSide": null,
211
+ "definition": { "kind": "clause", "column": { "sectionKey": null, "header": "mktAboveEma_zone" }, "op": "is", "label": "risk-on", "hold": { "atLeast": 3, "of": 3 } } }
212
+ ```
165
213
 
166
214
  ```json
167
- { "metric": "CROWD_UPBIAS", "transformId": "value", "timeframe": { "rel": "anchor" } }
215
+ { "conditionKey": "FIELD_BROADENING", "name": "More of the field up than down, a rung up", "verdict": null, "required": false, "exitSide": null,
216
+ "definition": { "kind": "clause", "column": { "sectionKey": null, "header": "mktBreadth_htf" }, "op": "gt", "value": 0, "hold": { "atLeast": 1, "of": 1 } } }
168
217
  ```
169
218
 
170
- Header `upBias`. It is a fade input, not a trend input: it says what the board expects, which is the
171
- thing a crowded-positioning playbook trades against.
219
+ **Stablecoin peg — stand down while USDT is off its dollar.** A section bound to `USDT_USD`, reading its
220
+ deviation from par, the peg zone, the deviation's path, and its rotation against USDC:
221
+
222
+ ```json
223
+ { "kind": "custom", "title": "USDT peg", "benchmarkTicker": "USDT_USD", "marketScope": null, "notes": null,
224
+ "columns": [
225
+ { "metric": "PAR_DEV", "transformId": "value", "timeframe": { "rel": "anchor" } },
226
+ { "metric": "PAR_DEV", "transformId": "classifyZone", "timeframe": { "rel": "anchor" } },
227
+ { "metric": "PAR_DEV", "transformId": "trajectory", "timeframe": { "rel": "anchor" }, "window": 4 },
228
+ { "metric": "PAR_DEV", "transformId": "relativeTo", "timeframe": { "rel": "anchor" }, "instrument": "USDC_USDT" } ] }
229
+ ```
230
+
231
+ Headers `parDev` (the close's signed % from its par of 1), `parDev_zone` (`at par` inside ±0.20%,
232
+ `drifting` from there to under ±1.00%, `depegged` at ±1.00% or beyond), `parDev_t3…parDev_now` with
233
+ `parDev_trend`, and `parDev_USDC_USDT_rel` — USDT/USD's deviation less USDC/USDT's, in points, which
234
+ reads strongly negative when money leaves USDT for USDC. The relation must name the other pair: a
235
+ pair-bound section has no `BTC` default. A required gate that stands every entry down while USDT is
236
+ off its peg, since a depeg moves every USDT-quoted price at once, and a rotation building block:
237
+
238
+ ```json
239
+ { "conditionKey": "USDT_AT_PAR", "name": "USDT holding its dollar", "verdict": null, "required": true, "exitSide": null,
240
+ "definition": { "kind": "clause", "column": { "sectionKey": null, "header": "parDev_zone" }, "op": "is", "label": "at par", "hold": { "atLeast": 1, "of": 1 } } }
241
+ ```
242
+
243
+ ```json
244
+ { "conditionKey": "ROTATING_TO_USDC", "name": "Money rotating from USDT into USDC", "verdict": null, "required": false, "exitSide": null,
245
+ "definition": { "kind": "group", "op": "ALL", "hold": { "atLeast": 1, "of": 1 }, "members": [
246
+ { "kind": "clause", "column": { "sectionKey": null, "header": "parDev_USDC_USDT_rel" }, "op": "lte", "value": -0.3, "hold": { "atLeast": 1, "of": 1 } },
247
+ { "kind": "clause", "column": { "sectionKey": null, "header": "parDev_trend" }, "op": "is", "label": "falling", "hold": { "atLeast": 1, "of": 1 } } ] } }
248
+ ```
172
249
 
173
250
  ## Coin selection
174
251
 
@@ -50,8 +50,9 @@ rules about the columns themselves, not about porting — they live in the skill
50
50
  carrier with `MACDhist_cross is "Bullish"`; swing-trend geometry.
51
51
  - **Golden / Death Cross** → `SMA50 spread SMA200 × trajectory` gives state and freshness:
52
52
  `SMA50_SMA200_spread_now gt 0` AND `_trend is "rising"`; optional breadth gate on
53
- `mktBreadth_crypto gte 0` — every published scope resolves, not only `all`, because the leg reads
54
- the `(timeframe, scope)` pairs a condition names; position-persona geometry. `SMA50 × SMA200` is
53
+ `mktBreadth gte 0` in a section bound to the market at `crypto` (`"marketScope": "crypto"`, any
54
+ scope the trade needs — two scopes are two sections; see `recipes.md`, *Market and stablecoin
55
+ subjects*); position-persona geometry. `SMA50 × SMA200` is
55
56
  the canonical definition and stays the default port; `EMA50` is available as the crypto variant
56
57
  when a player asks for it by name.
57
58
  - **RSI-2 (Connors)** → `RSI2` is native, so this ports exactly: `RSI2 lte 10` gated by required