@battlegrid/mcp-server 32.0.88 → 32.0.91

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/README.md CHANGED
@@ -38,6 +38,28 @@ Seeing package `31.x` alongside handshake `battlegrid@33.x` — the package **be
38
38
 
39
39
  **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.
40
40
 
41
+ ## Contract history — v169 (one exact rule for realized net; the hub's per-agent average is gone)
42
+
43
+ **v169 is MAJOR: one published output loses a field.** No input moves, and nothing v168 accepted is refused.
44
+
45
+ ### Removed output — the reason v169 is MAJOR
46
+
47
+ - **`get_agents_hub` no longer serves `summary.avgPnlPerAgentUsd`.** It was a lifetime average per agent, rounded
48
+ differently from the fleet's. Read `get_agents_portfolio_pnl`'s `avgRealizedNetPnlPerAgentUsd`, the one per-agent
49
+ average, over the period you ask for.
50
+
51
+ ### Changed values — the same schemas serve exact values
52
+
53
+ Realized trade money is now summed by one rule: exact at the persisted 8-decimal scale, never rounded to the cent on
54
+ the server. Round to the cent yourself when you display it.
55
+
56
+ - **`get_agents_hub`'s `summary.totalRealizedNetPnl`** — the roster's lifetime realized net, now described as
57
+ all-time. Rows of `-100` and `30.555` used to total `-69.44`; they now total `-69.445`.
58
+ - **`get_agents_portfolio_pnl`'s `realizedNetPnlUsd`, `avgRealizedNetPnlPerAgentUsd` and every `agentTrades[]`
59
+ `realizedNetPnlUsd`** — they served whole cents and now serve the exact values. The fleet's `LIFETIME` realized net
60
+ equals `get_cost_economics_breakdown`'s `ACCOUNT` pooled `netPnl` at `LIFETIME`. An agent's figure may print one
61
+ cent from the others' total, and from its own `agents[]` `pnlUsd` when it sits exactly on a half cent.
62
+
41
63
  ## Contract history — v156 (a crowd reading no bar can serve is not a condition; trades name their config version)
42
64
 
43
65
  **v156 is MAJOR: writes v155.1 accepted are refused, and one published result narrows.** No input schema moves.
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.88";
50
+ export declare const PACKAGE_VERSION = "32.0.91";
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.88';
52
+ export const PACKAGE_VERSION = '32.0.91';
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,7 +1,7 @@
1
1
  {
2
2
  "name": "@battlegrid/mcp-server",
3
- "version": "32.0.88",
4
- "description": "BattleGrid MCP server \u2014 play crypto prediction games from AI agents",
3
+ "version": "32.0.91",
4
+ "description": "BattleGrid MCP server — play crypto prediction games from AI agents",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
7
7
  "bin": {
@@ -1,26 +1,26 @@
1
1
  {
2
2
  "generator": "battlegrid-app/server/scripts/export-mcp-skills.mjs",
3
- "contractVersion": "149.1.0",
3
+ "contractVersion": "168.3.0",
4
4
  "files": {
5
5
  "battlegrid-agent-management/SKILL.md": "324ef8181bfcfc99b955d9644ed543c6ab91071153d43f77ccf0a4979b896b09",
6
6
  "battlegrid-agent-management/references/agent-stage-examples.md": "dffcc353d61dfc7b5bb6a2b3077fc6bf8c760a34c287cafb3b59b99306f24195",
7
- "battlegrid-arena-play/SKILL.md": "fdaabcd2e5ce3946ee96e553ce2e1931a822b84f91b0c94ce86a8bde0cc1d50f",
7
+ "battlegrid-arena-play/SKILL.md": "15fbcbbfd52eeb255a6b82547e7e13f1e33f939d8b41b13ee8dfa802c678e44f",
8
8
  "battlegrid-arena-play/references/entry-stage-examples.md": "0223f3743171ff213e943789d27590b2f65648398e85e10cd24938d5eb6af665",
9
9
  "battlegrid-market-analysis/SKILL.md": "889ba8a805585db5bfed0c72722d8b177174e8b145fb054619a5dc792cc92b09",
10
- "battlegrid-officers/SKILL.md": "0ac2173d0026b7329171fe24d38185e7717196340778d402c7af1aa74ea34bc8",
10
+ "battlegrid-officers/SKILL.md": "eabf5f3339fc147e31ba18e9d323b170f5a7f886238d1fcd0d9fd0b1ca414ed8",
11
11
  "battlegrid-officers/references/officer-stage-examples.md": "ef46ba26f4b36c9964b5bde95fdf98e5952c3786b77be5f136056cac792f0aec",
12
12
  "battlegrid-onboarding/SKILL.md": "e6b078cfdf13f6c66d2d964d2c0e6b9635f26adb164a8e0914849ef5671b9e3b",
13
- "battlegrid-radar-deployment/SKILL.md": "cf0eeaf9408ad57867415370872c1308b8ebdb9e8c73c0c6d2e34b6caef5599f",
13
+ "battlegrid-radar-deployment/SKILL.md": "bffe54bb209ccaf1f6df3bf86a811e6768db0d11c52ae0c460cbe1494a459e43",
14
14
  "battlegrid-radar-deployment/references/arena-stage-examples.md": "65af54b67c3248c53fb8911df769ad32824e1f1f1d83ffc007b42a888d5e3076",
15
- "battlegrid-radar-deployment/references/radar-stage-examples.md": "7a4195011aa764b106567606f7a2a8ae8e9b2bf74c36b3c74a72379969d70af8",
16
- "battlegrid-strategy-authoring/SKILL.md": "9a58b8cda9f1042491fb7dc4f9933a4639c3daed65002f7c8d2956caae1c7a58",
17
- "battlegrid-strategy-authoring/references/strategy-stage-examples.md": "f10ecdc91f3660a708eee7a7bacefce2acbb46c9cf7e0ac1454bd54f839f39fd",
18
- "battlegrid-strategy-doctor/SKILL.md": "4be392e51f3b5e76ff4aa22f61700236e8b1e19dfe286aeda8ed98e48a8457ba",
19
- "battlegrid-strategy-examples/SKILL.md": "a43623e2e5e2ade62d4e2dc1dfd5ce51efda7f15a4024713bc8058ff91beba07",
20
- "battlegrid-strategy-examples/references/playbooks.md": "59996c37eea08e7ce398e49304171939e55c968400a1603597d6737faf9e1771",
21
- "battlegrid-strategy-examples/references/recipes.md": "ee1b35f5341d3878ef8e8b045d0425a06fb25c76149fe841f2afe075909135f4",
22
- "battlegrid-strategy-examples/references/tradingview-ports.md": "966948d44cd8bb1748513f5bd84b74780d4c54dd8cab9285ac640d7a5fba14ed",
23
- "battlegrid-trade-analysis/SKILL.md": "ec0b543bc62fe66d629833b10e4bc58548be1fee57f29c04f41f036e860af1ca",
15
+ "battlegrid-radar-deployment/references/radar-stage-examples.md": "6d898a49c42861d6efb5d1b136996e6fb64beca7cac8b8c5dba7fed17a1c3bf5",
16
+ "battlegrid-strategy-authoring/SKILL.md": "a1e8166445ea2632ed0d60b08f879a3a4f5336e3b472342e759b191a30bacf23",
17
+ "battlegrid-strategy-authoring/references/strategy-stage-examples.md": "f9da084ed057b20f7554184445b1bdc6410e1c612a79392182823982f63513a7",
18
+ "battlegrid-strategy-doctor/SKILL.md": "133fe2ff3e8ca634822e02c7e30032c59c8b37b0b685023bfb98d280a678b5ae",
19
+ "battlegrid-strategy-examples/SKILL.md": "50c7e6121e792f4ddeb6babf5679af2e2bdefc6247d86d0d88853a68c21f6636",
20
+ "battlegrid-strategy-examples/references/playbooks.md": "3134fde92a6ce6fecc6d610629d02450f92e47f3a1a1f33d456658267b5ce123",
21
+ "battlegrid-strategy-examples/references/recipes.md": "e24483ec52cbcedba08ed6fa7f2a28b0fde170b2d4b1876162d180538cd789f2",
22
+ "battlegrid-strategy-examples/references/tradingview-ports.md": "5d65b5299ddfddd80f413a0301de25861607aeb0840b89416c3f0603a4b7cb37",
23
+ "battlegrid-trade-analysis/SKILL.md": "cd6f1887ba7bc756660ec992258d107cff93744e2fd45ee21a338e1ece398060",
24
24
  "battlegrid-trade-proposal/SKILL.md": "8d833022f753dfc5a765eca2fcd272c4f29d22b8444bc00c14ce63571646ba71"
25
25
  }
26
26
  }
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: battlegrid-arena-play
3
- description: Enter the player into Market Grid sessions — find an open session, read its coin pool and live market context, read the player's entry draft and stage picks with real per-coin reasoning into it or have one of their agents generate a grid, commit it against the session's entry fee, then read the results and the player's own entry record after settlement. Activate whenever the player wants to play, enter, join or submit to a session, asks what their grid looks like or to fill it in, wants their agent to enter one, asks what is open to play, or asks how a session they entered turned out.
3
+ description: Enter the player into Market Grid sessions — find an open session, read its coin pool and live market context, read the player's entry draft and stage picks with real per-coin reasoning into it or have one of their agents generate a grid, commit it against the session's entry fee, then read the results and the player's own entry record after settlement. Activate whenever the player wants to play, enter, join or submit to a session, asks what their grid looks like or to fill it in, wants their agent to enter one, asks what is open to play, asks how a session they entered turned out, or asks how a session scores, pays or triggers the jackpot.
4
4
  ---
5
5
 
6
6
  # Arena Play
@@ -12,6 +12,28 @@ picks. Staging is free and enters nothing. **Committing it is the wager**: with
12
12
  enters the session and the entry fee moves inside that call; over an entry it replaces the picks for no
13
13
  fee. The grid you commit is the one that gets scored, and there is no undo.
14
14
 
15
+ ## How a round scores
16
+
17
+ The values named here are the session's `scoringRules` and other fields from `get_market_grid_session`.
18
+ Explain a score, a payout or a captain choice from them, never from a remembered number.
19
+
20
+ - **The scored window** is set by the session's `finalScoringSource`. `MDS_CANDLE`: one candle, from its open at `startsAt` to its close at `settleAt`. `ONCHAIN_MARK_PX`: the oracle mark price captured when the session goes LIVE, to the mark price at `settleAt`. A coin that ends exactly where it started counts as UP.
21
+ - **A cell is correct when its prediction matches that direction, and points scale with how far the coin moved** — not just which way. A correct cell scores the absolute % move × `scoringRules.changeMultiplier`; a wrong cell loses the absolute % move × `scoringRules.wrongPenaltyMultiplier` (0 means a wrong cell costs nothing). A big move called right is worth far more than a small one, and a big move called wrong costs the same way.
22
+ - **`CELL_0` is the captain.** Its points are multiplied by `scoringRules.captainMultiplier` when it is correct, and its penalty by `scoringRules.captainWrongPenaltyMultiplier` when it is wrong.
23
+ - **A grid's score is the sum of its cells.** Ranks order by score, and a tie goes to the earlier submission; replacing an entry's picks resets its submission time.
24
+ - **Paid places** are the top `scoringRules.itmPercent`% of entrants, rounded down to whole places, paid more for a higher rank (`payoutBandSummary`). With `scoringRules.scoreGateEnabled`, a grid scoring 0 or below is never paid, and if no grid in the paid places scores above 0 the winners pool goes to the War Bond instead. The jackpot is decided separately.
25
+ - **No jackpot pattern pays unless the captain's direction is correct and no other coin in that grid moved more than the captain.** The cells form a `gridRows` × `gridCols` grid read left to right, top to bottom (`CELL_0` top-left). The patterns:
26
+ - **PERFECT GRID** (`PERFECT_GRID`) — Every cell predicted correctly
27
+ - **GRID LOCK** (`GRID_LOCK`) — At least one complete row AND column
28
+ - **GRID STORM** (`GRID_STORM`) — At least two complete rows
29
+ - **GRID FORTRESS** (`GRID_FORTRESS`) — At least two complete columns
30
+ - **GRID CROSS** (`GRID_CROSS`) — Any complete diagonal
31
+ - **GRID LINE** (`GRID_LINE`) — At least one complete row
32
+ - **GRID PILLAR** (`GRID_PILLAR`) — At least one complete column
33
+ - **GRID SURGE** (`GRID_SURGE`) — At least 6 correct predictions
34
+ - **Only the highest pattern a grid hits counts**, by the order of `jackpotPayoutHighlights`, and its share is split evenly among the grids that hit it.
35
+ - So captain the pick you are most confident will make the largest move in its called direction.
36
+
15
37
  ## The three failures this flow exists to prevent
16
38
 
17
39
  1. **A blind submission.** *Cue: "just enter me", "pick something", any ask that skips reading.*
@@ -89,11 +111,8 @@ ask. The commit requires a `RATIONALE` axis — `reasoning`, `confidenceScore`,
89
111
  `pickReasoning` — covering the whole grid it composes. Complete stage payloads are in
90
112
  `references/entry-stage-examples.md`.
91
113
 
92
- - **`CELL_0` is the captain.** The session's preset sets what that is worth: a correct captain's
93
- points are multiplied by its `captainMultiplier`, and a wrong captain's penalty by its
94
- `captainWrongPenaltyMultiplier` — both published by `list_game_presets`, and different per preset.
95
- Read them rather than assuming a number, and captain the pick you are most confident in among
96
- those with a move worth amplifying.
114
+ - **`CELL_0` is the captain.** What that is worth is the session's `scoringRules` — see
115
+ [How a round scores](#how-a-round-scores). Read them rather than assuming a number.
97
116
  - **`pickReasoning` carries one entry per grid cell — every cell, no coin twice.** Compose it
98
117
  correctly because it is yours to compose, not because something downstream will catch it: the
99
118
  read reports an incomplete one as a diagnostic and the commit refuses it before the fee moves, and
@@ -102,6 +121,8 @@ ask. The commit requires a `RATIONALE` axis — `reasoning`, `confidenceScore`,
102
121
  coin. Boilerplate reasoning attached to a real wager is worse than none — it looks like
103
122
  evidence.
104
123
  - `confidenceScore` is your honest read, and you state it to the player on the confirm form.
124
+ - **The `RATIONALE` is public.** Once the session locks, every player sees it beside the grid — the summary,
125
+ the confidence, the model and each pick's reasoning — as they see an agent's. Write it for that reader.
105
126
 
106
127
  **The agent path instead:** `generate_agent_grid` has one of the player's agents produce the grid.
107
128
  It spends a **billed LLM inference against the player's intelligence credits** — say that before
@@ -85,7 +85,7 @@ them as served, through their display names.
85
85
 
86
86
  ## 4. Work the inbox
87
87
 
88
- - **Read.** `list_officer_reviews`, by officer or by agent, newest first; `includeClosed` adds the applied,
88
+ - **Read.** `list_officer_reviews`, by officer, and by agent or by team, newest first; `includeClosed` adds the applied,
89
89
  dismissed and superseded history. Show each review's verdict, findings, diff, impact and warnings exactly as
90
90
  served; `applyAvailable` says Apply is offered, `heldAxes` names every axis the target's draft holds and who wrote
91
91
  it, and `baseMoved` says the target was committed since the review. `awaitingOwner` says the review waits on the
@@ -150,12 +150,14 @@ Radar's market hours answer *when may this agent trade*, and shift with daylight
150
150
  `TRADING_SESSION` condition answers *which session is this bar in*, over fixed UTC windows — the two are
151
151
  different questions, and a player asking for one is not asking for the other.
152
152
 
153
- When the player names an exchange session — New York, the New York open, London, the London open,
154
- the London–New York overlap, Tokyo, the Tokyo open — call `get_radar_market_hours` and stage that session's `hours`
153
+ When the player names a market session — New York, the New York open, London, the London open,
154
+ the London–New York overlap, Tokyo, the Tokyo open, the Asia session — call `get_radar_market_hours` and stage that session's `hours`
155
155
  exactly as served, merged with any other session they name; never work session hours out yourself,
156
156
  because New York and London shift with daylight saving on their own dates and the overlap changes
157
157
  shape on each of those dates. The three opens are one hour wide, so they suit agents on 1h bars or
158
- faster. The days stay the player's choice. Tell the player the staged hours are UTC, that an hour is
158
+ faster. The Asia session is fixed in UTC (00:00–08:00) and its served hours include 08, so an agent on 1h bars
159
+ decides all eight Asia bars. The days stay the player's choice. When the player asks for weekends, stage the served
160
+ `weekends` hours and days together; it decides every weekend bar except the one closing at Monday 00:00. Tell the player the staged hours are UTC, that an hour is
159
161
  on duty from :00 through :59, and, when the session carries a `nextShift`, the date its hours change
160
162
  and that the rule keeps the hours it was given.
161
163
 
@@ -471,7 +473,10 @@ Four reads, cheapest first. Stop as soon as the player's question is answered.
471
473
  2's: pass `agentId` for one agent's rows, and omit it for the coin feed, which carries no agent's
472
474
  gate crossings, verdict flips or regime changes. Rows are lean by default — pass `detail: 'FULL'`
473
475
  for the margin surface, and `includeCurve: true` only if something will actually plot the points;
474
- `includeCurve` requires `agentId`, and is refused without it.
476
+ `includeCurve` requires `agentId`, and is refused without it. The curve covers the last 24 hours and
477
+ stays continuous off duty: an `onDuty: false` point is a strategy bar that closed while the agent was
478
+ off duty — its `atrPct` is over the bar's close (a sweep's is over the level anchor; equal at a bar's
479
+ close), no sweep judged it, and the summary's `curveDigest` never counts it.
475
480
 
476
481
  **Neither of the first two substitutes for the other, and the reason is structural.** The journal is
477
482
  a TRANSITION log, not a state log: a gate that has blocked continuously without crossing again
@@ -106,9 +106,10 @@ Here the agent works the bear trend and stands down while a crash or a momentum
106
106
  ## On duty only in named hours and days
107
107
 
108
108
  Hours are UTC, 0–23. Days run 0 (Sunday) to 6. Each is listed once. For a named exchange session —
109
- including the London and Tokyo opens and the London–New York overlap — stage the `hours` `get_radar_market_hours`
110
- serves for it rather than a set of your own; the example below is a shape, not a session. No session
111
- close is served: a close is staged only as hours the player names.
109
+ including the London and Tokyo opens, the London–New York overlap and the Asia trading session — stage the
110
+ `hours` `get_radar_market_hours` serves for it rather than a set of your own; the example below is a shape, not a
111
+ session. For weekends, stage the served `weekends` `hours` and `days` together. No session close is served: a close
112
+ is staged only as hours the player names.
112
113
 
113
114
  ```json stage_radar_deployment_draft
114
115
  {
@@ -79,6 +79,12 @@ you found. The cues, none of them subtle:
79
79
  - **an ordering between events** — "after X fires, then wait for Y"
80
80
  - **anything phrased as a sequence, a delay, or a dependency**
81
81
 
82
+ An ordering of bar-level events inside a window IS expressible: an entry condition's root group may
83
+ be `SEQUENCE` (**In order**, with `within` bars) — see `## Conditions` in the `strategy-examples`
84
+ skill. Discover its window (the steps' served `conditionHold`) before you lock it. An ordering it
85
+ cannot carry — an exit rule, a nested sequence, a step that counts closes of its own, or a gap
86
+ between steps with a minimum — is still a gap, and is named as one.
87
+
82
88
  Locking first and discovering second is how the third failure happens: the form goes out while the
83
89
  gap is still invisible, so the ask arrives as a product question — *what did you mean?* — when the
84
90
  honest answer was *the grammar cannot do that*. The arc reads 1 → 2 → 3 for an ordinary ask; for
@@ -103,6 +109,14 @@ anywhere; if the two ever disagree, you have created the exact ambiguity this st
103
109
  `list_strategy_categories` → `list_strategy_vocabulary` → `get_strategy_column_contract` and
104
110
  `get_strategy_section_template`.
105
111
 
112
+ `list_strategy_vocabulary` browses one `category`, or searches with `query` — words that must all
113
+ appear in a metric's key, name, description or family, across every family unless you also name a
114
+ `category`. Search by the words the catalog uses (`rsi`, `support`, `relative volume`); a word no
115
+ metric uses matches nothing, so try fewer or plainer words. A family too large to return whole
116
+ refuses with `nextAct: narrow`: read it again with a `query`. The tools that take a metric accept a
117
+ plain key and refuse one the catalog lacks, naming the nearest keys — take the key from the
118
+ vocabulary, never from memory.
119
+
106
120
  The player's own saved sections are listed among the vocabulary's templates as `kind: "saved"`.
107
121
  When the player names one, fetch it with `get_strategy_section_template` and place its title, note,
108
122
  subject (`benchmarkTicker`, `marketScope`) and columns in a new custom section — a copy, with no
@@ -144,22 +158,23 @@ question you would otherwise guess — and a refusal you would otherwise earn:
144
158
  one — and omit it on a section you add. This is the one composition field whose right answer is
145
159
  "leave it out".
146
160
  - **The `entry` axis is a union keyed by its trigger.** `ON_CANDLE_CLOSE` is sent alone —
147
- `{ "entry": { "trigger": "ON_CANDLE_CLOSE" } }` — and a `levelOffsetAtrMultiple` or
148
- `validForBars` beside it is refused as an unrecognized key. A level trigger (`STOP_THROUGH_LEVEL`,
149
- `ON_RETEST`) sends both of them, with no defaults. A CREATE that stages no entry takes the
161
+ `{ "entry": { "trigger": "ON_CANDLE_CLOSE" } }` — and a `levelOffsetAtrMultiple`,
162
+ `validForBars` or `levels` beside it is refused as an unrecognized key. A level trigger (`STOP_THROUGH_LEVEL`,
163
+ `ON_RETEST`) sends all three, with no defaults: `levels` names the level the order rests at for each
164
+ trade direction, `{ "LONG": <level reference>, "SHORT": <level reference> }`, a level the report yields. A CREATE that stages no entry takes the
150
165
  platform's seed entry, so the axis is not required on every CREATE — stage it whenever the locked
151
166
  spec names an entry. Every trigger is decided at the close of the strategy's OWN bar, so there is
152
- no confirm-timeframe key; for the level triggers the level itself is derived from the trigger and
153
- the trade's direction, never named. A multi-bar hold belongs to the clause or group that needs
167
+ no confirm-timeframe key. A multi-bar hold belongs to the clause or group that needs
154
168
  it — its own `hold: { atLeast, of }`, which the editor calls **Hold** (Once, In a row, Within, At
155
169
  least), counted in completed bars of the column's own timeframe — not to this axis. Every clause
156
170
  and group carries `hold`; `{ "atLeast": 1, "of": 1 }` is Once. The `strategy-examples` skill
157
171
  carries the vocabulary, the served hold domain (a crossover or an edge operator — `crossesAbove`,
158
- `crossesBelow`, `enters`, `exits` — is held "within" only; a Developing column cannot be held) and
172
+ `crossesBelow`, `enters`, `exits` — is counted by the closes it fired on; a Developing column cannot be
173
+ held) and
159
174
  the per-column Confirmed / Developing read.
160
175
  - **What a bar did is its own vocabulary.** A touch or a rejection of a level, a candle pattern, a
161
176
  gap and a run of bars are composed from the `strategy-examples` skill's **Bar geometry** section —
162
- `levelInteraction` over a level with its `buffer` knob, and the pattern, gap, run and price-source
177
+ `levelInteraction` over a level with its one TOUCH tolerance, `buffer` or `touchAtr`, and the pattern, gap, run and price-source
163
178
  metrics. A level BREAK is a `distance` crossing over the same level, never a `levelInteraction`
164
179
  label.
165
180
  - **Swing structure is its own section.** Swing highs and lows, the `HH`/`HL`/`LH`/`LL` label and the
@@ -178,22 +193,42 @@ question you would otherwise guess — and a refusal you would otherwise earn:
178
193
  compose on it. Window and offset carry a declared `minimum`, a `bound` and a served `maximum` on the
179
194
  transform entry, or `null` when none fits. A `lookback` bound is the largest value whose read size
180
195
  fits the lookback cap. A `depth` bound — the length of `aggregate` (the SMA, `ta.sma`), `ema`
181
- (`ta.ema`), `rma` (Wilder's average, `ta.rma`), `wma` (`ta.wma`), `rsi` (`ta.rsi`, 0–100) and `cci` (`ta.cci`),
182
- or of a statistic (`zscore`, `stddev`, `linregSlope`, `pctl` (`ta.percentrank`), `rollingMin`, `rollingMax`) — is the longest window whose one-value read fits the readable depth beside the lookback cap (936
183
- for an SMA, WMA, CCI or a statistic, 935 for `pctl`, 269 for an EMA, 118 for an RMA or RSI at the shipped cap);
196
+ (`ta.ema`), `rma` (Wilder's average, `ta.rma`), `wma` (`ta.wma`), `rsi` (`ta.rsi`, 0–100), `cci` (`ta.cci`) and `roc`
197
+ (`ta.roc`, a percent), or of a statistic (`zscore`, `stddev`, `linregSlope`, `pctl` (`ta.percentrank`), `rollingMin`, `rollingMax`) — is the longest window whose one-value read fits the readable depth beside the lookback cap (2,436
198
+ for an SMA, WMA, CCI or a statistic, 2,435 for `pctl` or `roc`, 704 for an EMA, 308 for an RMA or RSI at the shipped cap);
184
199
  `rsi` and `cci` read null over a window whose values are all equal; a longer one is refused with
185
200
  `REPORT_COLUMN_DEPTH_EXCEEDED`, and `lookback.used` counts only where the window ends: its newest bar, or a
186
201
  rolling extreme's `offset` back (the offset stays lookback-bounded, 63 at the shipped cap). For a
187
202
  chained column the outer's declaration is `chainOuterParameters[outer]` (served beside `metric`)
188
203
  and its bound is `chainedOuters[outer].windowMaximum`; `chainedOuters[outer].offsetMinimum` is the least
189
- offset the chain accepts — `1` for a rolling extreme chained into `distance` (the breakout level), `null`
204
+ offset the chain accepts — `1` for a rolling extreme chained into `distance` (the breakout level) or
205
+ `levelInteraction` (a touch or rejection of that level, the Donchian prior rail at any length), `null`
190
206
  on every other chain — so stage the inner's offset at or above it. A chain outer never takes an offset:
191
- the offset belongs to the inner. The window carries a `unit`
207
+ the offset belongs to the inner. A source-series transform (`aggregate`, `ema`, `rma`, `wma`, `rsi`, `cci`, `roc`)
208
+ chains under a depth-bounded outer (an average or a statistic, never `trajectory`, `efficiency` or `maxShare`):
209
+ `CLOSE × ema × rsi` is the RSI of an EMA, `CLOSE × rsi × aggregate` the RSI smoothing line. Both halves declare a
210
+ window, so the inner's length is `window` and the outer's is `chainedWindow` (`{ window: 200, chainedWindow: 14 }`
211
+ is `close_ema200_rsi14`); `chainedOuters[outer].windowParameter` names the key its `windowMaximum` bounds, and
212
+ `innerWindowMaximum` bounds the inner's `window` under that outer, each at the other's default. The two lengths
213
+ are judged together: one value reads both windows' bars less one (803 for `ema(200) × rsi(14)`), and a pair that
214
+ does not fit is refused at the length to lower with its largest fitting value. A stored length has its own code:
215
+ the RSI of `EMA50` is `EMA50 × rsi`, and the chain is only for a length with no stored point. The window carries a `unit`
192
216
  (`seriesElements`, `seriesChanges` for `efficiency`, which reads one bar more than its window,
193
217
  `priorElements` for `pctl`, `smoothingLength` for `ema`, `wilderLength` for `rma` or `wilderChanges` for `rsi`,
194
218
  whose lengths read more bars than they name — `ema(20)` reads 73, `rma(14)` reads 108, `rsi(14)` reads 109). An average reads null until its whole window is present. Stage at most
195
- that maximum. A chained column's operands come from
196
- `chainedOuters[outer].operands`, never from the metric's full `spreadOperands`.
219
+ that maximum. Every operand field carries a key (`operands-<n>`), not a list: look the key up in the
220
+ `operandSets` served beside `metric`, which holds exactly the lists the entry names. A chained column's
221
+ operands are the list `chainedOuters[outer].operands` names, never the metric's full `spreadOperands`. On
222
+ any rung but the anchor (`{rel: 'anchor'}`) they are the lists `spreadOperandsOffAnchor` and
223
+ `chainedOuters[outer].operandsOffAnchor` name, which omit the per-bar session-profile levels a relation
224
+ meets only at the anchor.
225
+ - A `spread` operand is `{ metric }`, or a metric under one average at a length,
226
+ `{ metric, transformId, window }` — `transformId` one of `aggregate`, `ema`, `rma`, `wma`, `window` at least 2 —
227
+ where the metric is in the list the metric's `spreadAverageOperands` names (`spreadAverageOperandsOffAnchor` off the anchor):
228
+ the base itself first, so `CLOSE × spread` against `ema(CLOSE, 100)` is the close against an EMA with no stored
229
+ point. Two custom-length averages are `CLOSE × ema(34)` chained into `spread` against `ema(CLOSE, 89)`, offered on
230
+ the four averages' `chainSuccessors`. An operand length past the readable depth is refused at `inputs[0].window`,
231
+ naming the largest that fits. No `rank` or series outer chains over an averaged operand.
197
232
  - A metric can declare its own knobs on `parameters` (served on the metric entry, `null` when it
198
233
  declares none). The seven swing metrics declare `leftBars` and `rightBars` — the bars before and the
199
234
  closed bars after a pivot — default 2/2, minimum 1, `bound: 'depth'`: the pair reads
@@ -203,25 +238,48 @@ question you would otherwise guess — and a refusal you would otherwise earn:
203
238
  transform knobs, and leave it off for 2/2 — an explicit 2/2 is the same column. Off 2/2 the header
204
239
  carries `_l<left>r<right>` after the code (`fractalHi_l5r5_1h`). Stage a pair only on a transform
205
240
  (or chained outer) whose entry serves `metricParametersAccepted: true`; `rank`, `relativeTo`
206
- and the depth-bounded windows (the averages and the statistics) read the stored 2/2 and refuse it. A condition hold over a column off 2/2 is
207
- served a window of 1: each of its bars needs the full readable depth behind it.
208
- - The eight market-structure metrics (`INTERNAL_STRUCTURE_*`, `SWING_STRUCTURE_*` event, trend and
209
- level, `EQH`, `EQL`) declare their own knobs, each served with its `bound`: `swingLength` (`depth`,
241
+ and the depth-bounded windows (the averages and the statistics) read the stored 2/2 and refuse it. A condition
242
+ over a column off 2/2 reads one bar, because each of its bars needs the full readable depth behind it:
243
+ - a hold beyond one close is refused with `CONDITION_HOLD_ILLEGAL`;
244
+ - an **In order** step over it is refused with `CONDITION_SEQUENCE_WINDOW_INVALID`;
245
+ - every operator that reads the bar before (`crossesAbove`, `crossesBelow`, `increased`, `decreased`,
246
+ `enters` and `exits`) is refused with `CONDITION_OPERATOR_UNSUPPORTED`.
247
+
248
+ That leaves `lt`, `lte`, `gte`, `gt`, `between`, `is` and `in`, so a crossing reads as its state
249
+ (`dist_fractalHi_l5r5 gt 0`). These, with the three transform refusals, are what "the same refusals as an
250
+ authored swing pair" means below.
251
+ - The market-structure metrics (`INTERNAL_STRUCTURE_*`, `SWING_STRUCTURE_*` event, trend and
252
+ level, the pending levels `INTERNAL_PENDING_HIGH`/`_LOW` and `SWING_PENDING_HIGH`/`_LOW`, `EQH`, `EQL`,
253
+ the equal-pivot levels `EQH_LEVEL`, `EQL_LEVEL`, and the liquidity pools `LIQUIDITY_POOL_ABOVE`/`_BELOW` with
254
+ their `_INTACT`, `_TOUCHES`, `_RETIRED` and `_RECLAIMED`) declare their own knobs, each served with its `bound`: `swingLength` (`depth`,
210
255
  default 50, minimum 10, maximum 100), `confluenceFilter` (`flag`, internal structure only), `equalBars` (`depth`,
211
256
  default 3) and `equalThreshold` (`range`: stage exactly one of the served steps, 0 to 0.5 by 0.1).
212
257
  Leave a knob off at its default. They read `null` until the column's bars prove a value, so a
213
- short history reads more `null`. A trend reads `bullish` or `bearish`. They never take `rank`, `relativeTo` or a depth-bounded window (an average or a statistic).
214
- - `MFI14`, `WILLR14` and `CMF20` declare one knob, `period` (`depth`, minimum 2): its served `defaultValue` is
215
- each metric's own registered length (14, 14, 20), and its `maximum` the largest that fits the readable depth
216
- (935 for MFI, 936 for %R and CMF at the shipped cap). Leave it off at the default. Off it the header carries
217
- `_p<n>` (`MFI14_p21`), and the same refusals as an authored swing pair apply: no `rank`, `relativeTo` or
218
- depth-bounded window. An operand of another oscillator in the same column reads its own registered length.
258
+ short history reads more `null`. A trend reads `bullish` or `bearish`. A pending level is the active, not-yet-crossed high or low (`null` from the bar after a close crosses it); an equal-pivot level is the newer pivot of the latest pair that read equal, held until the side's next equal-length pivot (`EQH`/`EQL` reads true only on the deciding bar), and takes `equalBars` and `equalThreshold`. A liquidity pool is the nearest equal-high (above) or equal-low (below) pivot no close has gone beyond yet, several kept at once: `_INTACT` reads false on the bar whose close retires it, `_TOUCHES` counts the later bars whose `levelInteraction` against it is a touch or reject, `_RETIRED` is the pool the previous bar's close retired (on the next bar only, a level the level verbs take) and `_RECLAIMED` reads true when this bar's close is back at or inside it; they take `equalBars` and `equalThreshold`. They never take `rank`, `relativeTo` or a depth-bounded window (an average or a statistic), and the server computes them over the column's own bars at every setting, so a condition over one reads one bar, as over an authored swing pair, at the defaults too.
259
+ - The structure-zone columns (`STRUCT_ZONES` under its zone transforms, the edges `ZONE_SUPPORT_HIGH`/`_LOW`,
260
+ `ZONE_RESIST_HIGH`/`_LOW`, and the midpoints `ZONE_SUPPORT_MID`/`ZONE_RESIST_MID`) declare one knob, `usedUpOnClose` (`flag`, default false). Off, a zone is used up by a
261
+ wick past its far edge (a low below a support zone, a high above a resistance zone), as the stored sets are; on, by
262
+ a close past it, computed by the server over the zone timeframe's own bars, and the header carries `_close`
263
+ (`zones_close…`, `zoneSupLo_close`). Leave it off for the wick rule. On, a condition over the column reads one
264
+ bar, as over an authored swing pair.
265
+ - The supply/demand levels (`PRIOR_DAY_SUPPLY_EDGE`/`_AVG`/`_WAVG`, `PRIOR_DAY_DEMAND_*`, and the same six for
266
+ `PRIOR_ASIA_`, `PRIOR_LONDON_` and `PRIOR_NEW_YORK_`) declare two knobs, both `range`: `supplyDemandThreshold`
267
+ (default 10, 0 to 100 by 0.5) and `supplyDemandResolution` (default 50, 2 to 500 by 1). Leave each off at its
268
+ default. Off the default threshold the header carries `_vt<p>`, off the default resolution `res<n>`
269
+ (`pdSupEdge_vt20res100`); a resolution off its default is rebuilt from the server's 1m bars and reads `null` for a
270
+ window older than two UTC days. A level reads `null` until its window closes.
271
+ - `MFI14`, `WILLR14`, `CMF20`, `ATR`, `ADX`, `DI_PLUS`, `DI_MINUS` and `VWMA20` declare one knob, `period` (`depth`,
272
+ minimum 2): its served `defaultValue` is each metric's own registered length (14, 14, 20, 14, 14, 14, 14, 20), and
273
+ its `maximum` the largest that fits the readable depth (2,435 for MFI, 2,436 for %R, CMF and VWMA, 308 for the
274
+ Wilder-smoothed ATR, 154 for ADX and both DIs, whose ADX smooths the DIs a second time, at the shipped cap). Leave it off at the default. Off it the header carries
275
+ `_p<n>` (`MFI14_p21`), and the same refusals as an authored swing pair apply. An operand of another oscillator
276
+ in the same column reads its own registered length.
219
277
  - The Stochastic (`STOCH_K`, `STOCH_D`) declares `period` (the %K length), `kSmoothing` and `dSmoothing`, at
220
278
  TradingView's 14, 1, 3; the Stoch RSI (`STOCH_RSI_K`, `STOCH_RSI_D`) declares `rsiPeriod`, `period` (the
221
279
  stochastic length), `kSmoothing` and `dSmoothing`, at 14, 14, 3, 3. Each is `depth`-bounded; the lengths have
222
280
  minimum 2 and the smoothings minimum 1 (1 is unsmoothed). Leave every setting off at the defaults. Once any is
223
- off, the header writes all of them (`K_p21s3d3`, `stochRsiK_rsi14_p21s3d3`) and the same refusals apply: no
224
- `rank`, `relativeTo` or depth-bounded window.
281
+ off, the header writes all of them (`K_p21s3d3`, `stochRsiK_rsi14_p21s3d3`) and the same refusals as an authored
282
+ swing pair apply.
225
283
  - MACD (`MACD_LINE`, `MACD_SIGNAL`, `MACD_HIST`) and PPO (`PPO_LINE`, `PPO_SIGNAL`, `PPO_HIST`) declare `fast`,
226
284
  `slow` and `signal`, the two close EMAs' lengths and the signal EMA's, at TradingView's 12, 26, 9. Each is
227
285
  `depth`-bounded with minimum 1. Leave them off at the defaults; once any is off, the header writes all three
@@ -237,6 +295,10 @@ question you would otherwise guess — and a refusal you would otherwise earn:
237
295
  from 0.001 to 0.1 on a 0.001 step, and the maximum from 0.01 to 1 on a 0.01 step. Leave them off at the defaults;
238
296
  once any is off, the header writes every setting (`stLine_atr14mult2`, `PSAR_start0.01inc0.01max0.1`) and the
239
297
  same refusals apply.
298
+ - Ichimoku (`ICHI_CONV`, `ICHI_BASE`, `ICHI_SPAN_A`, `ICHI_SPAN_B`, `ICHI_LAG`) declares `conversionPeriod`,
299
+ `basePeriod`, `spanBPeriod` and `displacement`, at TradingView's 9, 26, 52, 26. Each is `depth`-bounded; the windows
300
+ have minimum 1 and the displacement minimum 2. The spans apply, and the lagging close is read, `displacement − 1` bars back. Leave them off at the defaults;
301
+ once any is off, the header writes all four (`senkouA_conv20base60spanB120disp30`) and the same refusals apply.
240
302
  - `get_metric_construction_hints` → `rankOrderings`. Present only when rank is composable on that
241
303
  metric, already range-gated server-side — read the offered set rather than deriving one from
242
304
  the metric's native output.
@@ -280,9 +342,11 @@ changing; send no other axis.
280
342
 
281
343
  **A whole axis restates what it keeps.** "Raise the ATR floor to 0.8%" is one TRADE_LEVEL_POLICY
282
344
  stage carrying all four of its dials — `minStopLossAtrMultiple`, `maxStopLossAtrMultiple`,
283
- `minRiskRewardRatio` and `minAtrPct` — the three you are not changing exactly as they stand now:
284
- read them from the draft's TRADE_LEVEL_POLICY when the draft holds it, otherwise from
285
- `get_strategy`. The same holds for a condition: CONDITIONS carries every condition, each with its
345
+ `minRiskRewardRatio` and `minAtrPct` — and its `tradeLevelMenu`, everything you are not changing exactly as it stands
346
+ now: read them from the draft's TRADE_LEVEL_POLICY when the draft holds it, otherwise from
347
+ `get_strategy`. Raising `minRiskRewardRatio` above an R target in the menu is refused until that option leaves the
348
+ menu, so a raise restates the menu without it. The `strategy-examples` skill's *Trade levels* section carries the
349
+ menu's options, how pairs are built and what the save refuses. The same holds for a condition: CONDITIONS carries every condition, each with its
286
350
  `required` flag and verdict as they stand. Never set `required` or a verdict from memory, and never
287
351
  change either unless the player asked: a wrong value there is how a building block silently becomes
288
352
  a mandatory trade gate, or a gate silently disappears.
@@ -34,8 +34,11 @@ and TIMEFRAME_PROFILE before it can be created.
34
34
 
35
35
  ## Change an existing strategy's trade levels
36
36
 
37
- TRADE_LEVEL_POLICY is sent whole: all four dials, even when only one changes. `minAtrPct` is the ATR% volatility floor
38
- a coin must clear before any condition is read; the other three are the stop-loss band and the reward-to-risk floor.
37
+ TRADE_LEVEL_POLICY is sent whole: all four dials and the menu, even when only one changes. `minAtrPct` is the ATR%
38
+ volatility floor a coin must clear before any condition is read; the next three are the stop-loss band and the
39
+ reward-to-risk floor; `tradeLevelMenu` lists, per trade direction, the stop and target options the agent picks a pair
40
+ from. A level option names a level the strategy's report yields — here the platform support/resistance section's
41
+ Donchian edges.
39
42
 
40
43
  ```json stage_strategy_draft
41
44
  {
@@ -46,7 +49,27 @@ a coin must clear before any condition is read; the other three are the stop-los
46
49
  "minStopLossAtrMultiple": 1,
47
50
  "maxStopLossAtrMultiple": 2,
48
51
  "minRiskRewardRatio": 1.5,
49
- "minAtrPct": 0.8
52
+ "minAtrPct": 0.8,
53
+ "tradeLevelMenu": {
54
+ "LONG": {
55
+ "stops": [
56
+ { "kind": "ATR", "atrMultiple": 1.5 },
57
+ {
58
+ "kind": "LEVEL",
59
+ "level": { "metric": "DONCHIAN_LOWER", "timeframe": { "rel": "anchor" }, "bars": null, "offset": 0, "knobs": {}, "windowExtreme": null },
60
+ "bufferAtrMultiple": 0.25
61
+ }
62
+ ],
63
+ "targets": [
64
+ { "kind": "R_MULTIPLE", "multiple": 2 },
65
+ { "kind": "LEVEL", "level": { "metric": "DONCHIAN_UPPER", "timeframe": { "rel": "anchor" }, "bars": null, "offset": 0, "knobs": {}, "windowExtreme": null } }
66
+ ]
67
+ },
68
+ "SHORT": {
69
+ "stops": [{ "kind": "PERCENT", "percent": 2 }],
70
+ "targets": [{ "kind": "R_MULTIPLE", "multiple": 2 }]
71
+ }
72
+ }
50
73
  }
51
74
  }
52
75
  }
@@ -94,9 +94,12 @@ Three reads, and they are not interchangeable:
94
94
  failed row's `rejection` names why its order was refused. `list_agent_trades` narrowed by `agentId`,
95
95
  `list_agent_market_grid_decisions` and `get_agent_activity_feed` for what did happen, and
96
96
  `get_signal_log`'s `thesisReasoning` for why a trade was taken.
97
- - **`get_agent_conviction_calibration` honours `readiness`.** An `INSUFFICIENT_DATA` calibration
98
- carries no win rate — report that there is not yet enough history, never a rate derived from a
99
- handful of trades.
97
+ - **`get_agent_conviction_calibration` honours `readiness`.** It serves one row per model the
98
+ agent's closed trades were decided by, under `calibration.rows`; read the row whose `isCurrentModel`
99
+ is true and name its model. An `INSUFFICIENT_DATA` group carries no win rate — report that there is not
100
+ yet enough history on the current model, never a rate derived from a handful of trades, and never
101
+ another model's row in its place. Bands compare in R (`averageGrossR` over `rTradeCount` trades), never
102
+ in USD.
100
103
 
101
104
  **Every stated cause cites the typed reason or journal entry it came from.** "It is blocked" is not
102
105
  a diagnosis; "OPEN_POSITION_CONFLICT, 14 times, most recently 2h ago" is.