@battlegrid/mcp-server 31.2.100 → 31.2.103

package/README.md

@@ -24,6 +24,30 @@ 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 — v110.6 (the Donchian channel as of the bar before)
+
+**Additive at v110.6: two Donchian metric keys, and level-interaction labels judged against the level in
+force when the bar opened.** v110.6 is the contract on top of v110.5. Nothing you send is refused.
+
+### Widened enum — something new you can send
+
+- **`DONCHIAN_UPPER_PRIOR` and `DONCHIAN_LOWER_PRIOR`** (codes `donchianHiPrior`, `donchianLoPrior`)
+  in every tool that takes a column (`stage_strategy_draft`, `preview_strategy_report`,
+  `get_strategy_column_contract`, `get_metric_construction_hints`): the 20-bar channel edges as of the
+  bar before, Pine's `ta.highest(high, 20)[1]` and `ta.lowest(low, 20)[1]`. The close-based Donchian
+  breakout is `dist_donchianHiPrior crossesAbove 0`; the state "close above the prior 20-bar high" is
+  `dist_donchianHiPrior gt 0`; a failed breakout is `donchianHiPrior_lvl is reject_from_below`. They take
+  `levelInteraction` and not the cross-coin `rank`. Their history begins when the server deployed them.
+
+### Behaviour behind unchanged schemas
+
+- **`levelInteraction` decides the side and the break against the level in force when the bar opened**:
+  the bar's own reading for a level fixed before the bar, the previous bar's reading for a level computed
+  from its own bar. Labels move on `DONCHIAN_BROKEN_HI`, `DONCHIAN_BROKEN_LO`, `SWING_FRACTAL_HIGH`,
+  `SWING_FRACTAL_LOW`, `ICHI_SPAN_A`, `ICHI_SPAN_B` and `ICHI_LAG`, only on bars where the level stepped
+  across the prior close and on the bar a level first appears (null becomes a label). No other level's
+  label moves. The transform's `formula` and `nullBehavior` text say so.
+
 ## Contract history — v110 (a metric names the one line it reads)
 
 **Breaking at v110: the metric keys `MACD`, `PPO` and `KC_MID` are refused.** v110 is the contract on

package/dist/index.d.ts

@@ -49,7 +49,7 @@ import { type Implementation, type Prompt, type Resource } from '@modelcontextpr
  * 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.2.100";
+export declare const PACKAGE_VERSION = "31.2.103";
 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.2.100';
+export const PACKAGE_VERSION = '31.2.103';
 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.2.100",
+  "version": "31.2.103",
   "description": "BattleGrid MCP server — play crypto prediction games from AI agents",
   "type": "module",
   "main": "dist/index.js",

package/skills/EXPORT.json

@@ -1,21 +1,22 @@
 {
   "generator": "battlegrid-app/server/scripts/export-mcp-skills.mjs",
-  "contractVersion": "108.2.0",
+  "contractVersion": "110.4.0",
   "files": {
     "battlegrid-agent-management/SKILL.md": "34a868f8068df189ce13af47c23011aabcf6a1f07128da4d4706066628cfaa5f",
     "battlegrid-agent-management/references/agent-stage-examples.md": "d47555906ce8dedf4c17422f8f5d60187f2d6b3c0af5d9545617a10a5bdb59a1",
-    "battlegrid-arena-play/SKILL.md": "719dfd57a9ad5b70801f366f11d0e0a57c87c7aae7751b9acca7a5a1584aa36e",
-    "battlegrid-market-analysis/SKILL.md": "b647dbe9db4ecc67b744b7f7a82ec4e56f2e7f4d2cb1c20546649085b1ae1529",
-    "battlegrid-radar-deployment/SKILL.md": "12ae488bcc81e17fdd749448ecd98f42846c98960895c1d579db833836739eb2",
+    "battlegrid-arena-play/SKILL.md": "88534714cdbaa31344e1798b2b3f18836bf543f5610d118d76095d1a0dbea502",
+    "battlegrid-arena-play/references/entry-stage-examples.md": "3bc62f9faca7b5529d51a9794e162333216acb23f0d7f644d5180b9cbc696fca",
+    "battlegrid-market-analysis/SKILL.md": "fcbe98e30e1edce39bb170c224cdf20181934f62b5f3a26b293787c70eeb6229",
+    "battlegrid-radar-deployment/SKILL.md": "652325c4923d79b9c9b78026a5493bfaaedf01f600641511438a9c4bf497c0b1",
     "battlegrid-radar-deployment/references/arena-stage-examples.md": "f605aaa266a291ef1b6d02a0e8885ad5df2fea88c800be2b6625cd629cd741f2",
     "battlegrid-radar-deployment/references/radar-stage-examples.md": "1ddad4a11f021dd65234ee65cc12d7d1561fe9acfd61cb021f4352080d4cecd5",
-    "battlegrid-strategy-authoring/SKILL.md": "2b6bb9a9f419bae5dd85457f6f89131fd6f09ab218f67a0d9e27cad4072945fe",
+    "battlegrid-strategy-authoring/SKILL.md": "098308e69093796db3bb0a6dab64031128aaffbc108117b72393595564581da1",
     "battlegrid-strategy-authoring/references/strategy-stage-examples.md": "9822cc2bcc8975a3e436c2a960b10e03c95e6e6b4b04bc2206e0ac90688cab66",
     "battlegrid-strategy-doctor/SKILL.md": "e34e055b0cc9b355bc1adeb5d49d464eaa0756ca3f48dc89ca2ccdda94e1311f",
-    "battlegrid-strategy-examples/SKILL.md": "baf8f976d1b33c9009f21bb292943798a233464ebe4149f2f887cc40e2bfa5d4",
+    "battlegrid-strategy-examples/SKILL.md": "375a85a38b21a356291d05af3668a57949f11ba49968a4a53f08dcc590228375",
     "battlegrid-strategy-examples/references/playbooks.md": "2309eb7e8324f563c5b1b51e05da931b37c542484135a2be749eff6ef78aa40f",
-    "battlegrid-strategy-examples/references/recipes.md": "3fc3280a854fca924b77f2fe154231e91a0dc779023413597d966cbb1ac88baf",
-    "battlegrid-strategy-examples/references/tradingview-ports.md": "fe70a84c700f0cd72b9adf91cafccae2af0db007951afc9be37bc3134142c5a1",
+    "battlegrid-strategy-examples/references/recipes.md": "635e03d163100f6de37cda1f6cc12928d5d36aa0ea883bf44fc72f17cbf3e98e",
+    "battlegrid-strategy-examples/references/tradingview-ports.md": "1b9440bd7180330fb77c8e245e852cbe0b5a9f7df3448233199ecd341565b2b6",
     "battlegrid-trade-analysis/SKILL.md": "3f927b4f9796178526fa1673a2043c5f14358c39aa955de33192ea58641f18fb",
     "battlegrid-trade-proposal/SKILL.md": "e761fc6bddc0d1db79fcb90046d03a18439562c8658de726ec286830edd6369b"
   }

package/skills/battlegrid-arena-play/SKILL.md

@@ -1,12 +1,16 @@
 ---
 name: battlegrid-arena-play
-description: Enter the player into Market Grid sessions — find an open session, read its coin pool and live market context, compose a grid with real per-coin reasoning or have one of their agents generate it, submit 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, wants their agent to enter one, asks what is open to play, or asks how a session they entered turned out.
+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.
 ---
 
 # Arena Play
 
-A submission is a **wager**. On a paid session the entry fee moves as part of the submit call, and
-the grid you submit is the one that gets scored. There is no draft state and no undo.
+A player's picks for a session live in their **entry draft**, one axis per grid position (`CELL_0` is
+the captain) plus a `RATIONALE`. Their builder on the session page writes the same draft as they pick,
+so the draft is the shared grid: you read it to know what they have picked and stage into it to propose
+picks. Staging is free and enters nothing. **Committing it is the wager**: with no entry the commit
+enters the session and the entry fee moves inside that call; over an entry it replaces the picks for no
+fee. The grid you commit is the one that gets scored, and there is no undo.
 
 ## The three failures this flow exists to prevent
 
@@ -54,23 +58,31 @@ the enablement path there.
 3. `get_market_context` for that session — the indicators, rankings and trends the picks will
    actually be reasoned from.
 4. `check_market_grid_submission` — **before composing anything.** If a submission already exists,
-   report it (with its id and time) and offer `update_market_grid` where the session still permits
-   it. Never compose a duplicate.
-
-### 3. Compose — the reasoning is yours to get right
-
-A direct submission carries `grid`, `reasoning`, `confidenceScore`, `modelName` and
-`pickReasoning`, and all of them are required.
-
-- **Exactly one cell is captain.** The session's preset sets what that is worth: a correct captain's
+   report it (with its id and time); while the session is still PENDING, a commit of the draft
+   replaces its picks. Never compose a duplicate.
+5. `get_market_grid_entry_draft({ request: { sessionId } })` — what the draft holds now, the player's
+   own picks included, with the `draftVersion` and `committedRevision` your stage and commit name.
+   Answer "what does my grid look like" from this read, never from a pick count.
+
+### 3. Compose — stage into the draft, and the reasoning is yours to get right
+
+`stage_market_grid_entry_draft({ request: { sessionId, draftVersion, axes } })`, naming the
+`draftVersion` the read returned. Each cell axis is `{ cell: { coinId, prediction } }` — `coinId` the
+pool coin's `id` — or `{ cell: null }` to empty it. **Compose on top of what the draft holds**: a cell
+you do not stage keeps the player's pick, and you never discard their picks to start over unless they
+ask. The commit requires a `RATIONALE` axis — `reasoning`, `confidenceScore`, `modelName` and
+`pickReasoning` — covering the whole grid it composes. Complete stage payloads are in
+`references/entry-stage-examples.md`.
+
+- **`CELL_0` is the captain.** The session's preset sets what that is worth: a correct captain's
   points are multiplied by its `captainMultiplier`, and a wrong captain's penalty by its
   `captainWrongPenaltyMultiplier` — both published by `list_game_presets`, and different per preset.
   Read them rather than assuming a number, and captain the pick you are most confident in among
   those with a move worth amplifying.
 - **`pickReasoning` carries one entry per grid cell — every cell, no coin twice.** Compose it
   correctly because it is yours to compose, not because something downstream will catch it: the
-  boundary refuses an incomplete payload before the fee moves, and leaning on that check means
-  submitting payloads you have not read.
+  read reports an incomplete one as a diagnostic and the commit refuses it before the fee moves, and
+  leaning on that check means committing payloads you have not read.
 - Each entry's reasoning cites **the market context you read in this conversation**, for that
   coin. Boilerplate reasoning attached to a real wager is worse than none — it looks like
   evidence.
@@ -85,12 +97,16 @@ Present the generation as a card: the agent, its confidence against the threshol
 (`confidenceThreshold: null` means no deployment declares a bar here, so the grid is **ungated** —
 say that rather than inventing a bar), whether it meets the threshold, and the per-coin picks.
 
-### 4. Confirm, then submit promptly
+### 4. Read again, confirm, then commit promptly
 
-One confirmation naming **the session, its entry fee, and the confidence** — then submit on an
-explicit pick.
+`get_market_grid_entry_draft` again after staging: show the player the diff, any diagnostic, and the
+`impact` — `ENTER` with the `entryFee` the commit charges, or `REPLACE` for none. One confirmation
+naming **the session, that fee, and the confidence** — then commit on an explicit pick.
 
-- Direct → `submit_market_grid`.
+- Direct → `commit_market_grid_entry_draft({ request: { sessionId, draftVersion, expectedRevision } })`,
+  naming exactly the `draftVersion` and `committedRevision` the last read returned (`null` with no
+  entry). A refusal naming `get_draft` means the draft or the entry moved: read again and confirm
+  again — never retry with a bumped number.
 - Agent → `submit_agent_grid`, which consumes the cached generation for that (session, agent).
 
 **A regeneration voids any prior confirm.** The submit takes no generation token — it reads
@@ -98,10 +114,14 @@ whatever is currently cached — so a grid regenerated after the player confirme
 under a confirmation given for different picks. Re-present the confirm for the new generation,
 every time, and submit promptly after the confirmed one.
 
+**If the submit is refused with `CONFLICT`**, the player's entry changed after the grid was generated —
+replaced, cancelled, re-placed, or placed where there was none. No fee moved. The recovery is
+`generate_agent_grid` again, a fresh confirm of the new grid, then `submit_agent_grid`.
+
 **If the submit is refused for a missing pending generation**, the ten-minute window lapsed. The
 recovery is `generate_agent_grid` again and a fresh confirm. **Never** convert the stale picks into
-a hand-composed `submit_market_grid` under the player's own name — that submits an agent's
-reasoning as the player's, and the attribution is part of what was scored.
+a hand-staged draft committed under the player's own name — that enters an agent's reasoning as the
+player's, and the attribution is part of what was scored.
 
 ### 5. After settlement
 
@@ -113,25 +133,33 @@ reasoning as the player's, and the attribution is part of what was scored.
   typed CONFLICT naming the current status: **report it and stop**. Do not poll it in a loop; the
   op budget is finite and a settling session is not a failure.
 - `get_my_market_grid_entry` on request — the player's own entry in that session: its picks, who
-  authored it, whether another author has rewritten it (`edited`), and the reasoning and confidence
-  recorded at submit. Compare the outcome against what was actually reasoned, and say where the
-  reasoning was wrong. `reasoning` is null once the entry was edited — the record no longer describes
-  the picks, so say that rather than reconstructing one. `list_my_market_grid_entries` is the history
-  across sessions. An agent's decisions are a different record, `get_agent_journal`.
+  authored the current picks (`source`; `COMMANDER_ASSIST` with `keptPicks` when the player and
+  Commander authored it together), whether that differs from who first entered (`edited`), and the
+  reasoning that describes the current picks, with one entry per reasoned pick in `reasoning.picks`.
+  Compare the outcome against what was actually reasoned, and say where the reasoning was wrong.
+  `reasoning` is null when no record describes the current picks — say that rather than
+  reconstructing one, and a pick missing from `reasoning.picks` is one the player chose.
+  `list_my_market_grid_entries` is the history across sessions. An agent's decisions are a different
+  record, `get_agent_journal`.
 
 ## On the arena's session page
 
 When the conversation is embedded in the player's Market Grid session page, the round on screen
 arrives as the attached scope, and the session it names is the one in scope.
 
-- **Propose, do not submit.** When the player asks for a grid, call `generate_agent_grid` for the
-  session in scope (the billed-inference warning in step 3 still applies). The result reaches them
-  as a card with **LOAD INTO GRID**, which puts the picks into their own builder as a starting point.
-- **A loaded grid they have not changed is the agent's.** Their builder will not place it as theirs.
-  If they want the agent's grid entered as it stands, run step 4: one confirmation, then
-  `submit_agent_grid` on their explicit pick, never on free text.
-- **Once they change a pick, the grid is theirs.** They place it themselves from their ticket. Do not
-  submit it for them, and do not describe it as the agent's.
+- **Stage, do not enter.** When the player asks you to pick or fill in their grid, read the draft and
+  stage the cells into it (step 3). Each staged pick appears in their builder at once, labelled as
+  yours; nothing is entered and no fee or deposit is needed. Their own **PLACE ENTRY** places it;
+  offer to place it for them only through step 4's confirmation and the draft commit.
+- **Their picks are in the draft.** A pick they make in the builder lands there as they make it, so
+  read the draft before answering what they have picked or staging over it. A pick their builder
+  rewrote after you staged it is their answer — stage it again only when they ask.
+- **An agent's grid is proposed, not staged.** When they ask for their agent's grid, call
+  `generate_agent_grid` for the session in scope (the billed-inference warning in step 3 still
+  applies). The result reaches them as a card with **LOAD INTO GRID**, which puts the picks into their
+  builder as a starting point. A loaded grid they have not changed is the agent's: if they want it
+  entered as it stands, run step 4, then `submit_agent_grid` on their explicit pick, never on free
+  text. Once they change a pick, the grid is theirs.
 - **A newer generation for the same agent replaces the older card.** The older one reads SUPERSEDED;
   only the newest is what `submit_agent_grid` would enter.
 
@@ -160,8 +188,10 @@ Each is typed and distinguishable. Read the code, do not paraphrase:
   a permission check, do not add a wager gate of your own, and do not treat free text typed while a
   confirmation is open as consent — in chat or in the form's own answer-in-your-own-words box. Only
   an explicit pick from the options you offered confirms.
-- **Never re-submit over an unknown outcome.** An interrupted submit may have committed the fee.
-  Run `check_market_grid_submission` first and report what actually exists.
+- **Never re-commit over an unknown outcome.** An interrupted commit may have moved the fee. A retry
+  of the same `draftVersion` returns the first commit's receipt; otherwise run
+  `check_market_grid_submission` and `get_market_grid_entry_draft` first and report what actually
+  exists.
 
 ## Reporting discipline
 

package/skills/battlegrid-arena-play/references/entry-stage-examples.md

@@ -0,0 +1,89 @@
+# Market Grid entry stage examples
+
+Complete `stage_market_grid_entry_draft` inputs for the player's entry draft. Each is checked in CI against the live
+stage schema, and the grid it composes is judged by the commit's own grid and reasoning checks, so its shape is
+current.
+
+Every `<UPPER_SNAKE>` value is a placeholder. Replace it with the id a read returned:
+
+- `<SESSION_ID>` comes from `list_market_grid_sessions`.
+- `<COIN_ID>`, `<SECOND_COIN_ID>` and `<THIRD_COIN_ID>` are three different coins' `id`s from the pool
+  `get_market_grid_session` returns.
+
+Never send a placeholder as written, and never invent an id. `draftVersion` is the version
+`get_market_grid_entry_draft` returned: 0 when the session has no draft. These examples are a three-cell session; a
+real session's grid has its own `gridSize`, and the commit needs every position from `CELL_0` up to it filled.
+
+## Fill the whole grid, with its reasoning
+
+`CELL_0` is the captain. The `RATIONALE` carries one `pickReasoning` entry per cell of the grid the commit will
+enter, each citing the market context you read.
+
+```json stage_market_grid_entry_draft
+{
+  "request": {
+    "sessionId": "<SESSION_ID>",
+    "draftVersion": 0,
+    "axes": {
+      "CELL_0": { "cell": { "coinId": "<COIN_ID>", "prediction": "UP" } },
+      "CELL_1": { "cell": { "coinId": "<SECOND_COIN_ID>", "prediction": "DOWN" } },
+      "CELL_2": { "cell": { "coinId": "<THIRD_COIN_ID>", "prediction": "UP" } },
+      "RATIONALE": {
+        "reasoning": "The leader is breaking out on rising volume while the second coin rejects its range high.",
+        "confidenceScore": 0.7,
+        "modelName": "your-model-name",
+        "pickReasoning": [
+          { "coinId": "<COIN_ID>", "reasoning": "Breaking resistance on rising volume.", "confidence": 0.8 },
+          { "coinId": "<SECOND_COIN_ID>", "reasoning": "Bearish divergence at the range high.", "confidence": 0.6 },
+          { "coinId": "<THIRD_COIN_ID>", "reasoning": "Holding its trend above the session open.", "confidence": 0.6 }
+        ]
+      }
+    }
+  }
+}
+```
+
+## Change one call, keeping every other pick
+
+A cell you do not stage keeps the player's own pick. Here the second position's call flips while its coin stays,
+so the reasoning the draft already holds still covers every coin; stage a new `RATIONALE` when your reasoning for
+that coin changed.
+
+```json stage_market_grid_entry_draft
+{
+  "request": {
+    "sessionId": "<SESSION_ID>",
+    "draftVersion": 4,
+    "axes": {
+      "CELL_1": { "cell": { "coinId": "<SECOND_COIN_ID>", "prediction": "UP" } }
+    }
+  }
+}
+```
+
+## Change a call and its reasoning together
+
+```json stage_market_grid_entry_draft
+{
+  "request": {
+    "sessionId": "<SESSION_ID>",
+    "draftVersion": 5,
+    "axes": {
+      "CELL_1": { "cell": { "coinId": "<SECOND_COIN_ID>", "prediction": "UP" } },
+      "RATIONALE": {
+        "reasoning": "The second coin reclaimed its range high, so it now runs with the leader.",
+        "confidenceScore": 0.65,
+        "modelName": "your-model-name",
+        "pickReasoning": [
+          { "coinId": "<COIN_ID>", "reasoning": "Breaking resistance on rising volume.", "confidence": 0.8 },
+          { "coinId": "<SECOND_COIN_ID>", "reasoning": "Reclaimed the range high on the last close.", "confidence": 0.6 },
+          { "coinId": "<THIRD_COIN_ID>", "reasoning": "Holding its trend above the session open.", "confidence": 0.6 }
+        ]
+      }
+    }
+  }
+}
+```
+
+`{ "cell": null }` empties a position. The draft holds it while the player is still choosing, but the commit
+refuses a grid with an empty position, so stage it only when the player asked to clear that pick.

package/skills/battlegrid-market-analysis/SKILL.md

@@ -46,7 +46,7 @@ Run these in order. Skip a step only when the player's question makes it irrelev
    coin selection and the funding / open-interest / positioning sections chosen — one coin is a
    one-row report, not a different tool. Then `get_coin_candles` for the price action. For momentum
    across timeframes, add the Relative Strength section — it carries the PPO trajectory and its
-   zero-crossing — or author `PPO` columns at the intervals you want pinned; that is the same read
+   zero-crossing — or author `PPO_HIST` columns at the intervals you want pinned; that is the same read
    at the precision the catalog declares, in the call you are already making. Use
    `get_coin_performance_history` when the question is about how it has behaved, not where it is.
    Coin symbols are case-insensitive and exchange symbols are accepted (`btc`, `kPEPE`,

package/skills/battlegrid-radar-deployment/SKILL.md

@@ -316,26 +316,28 @@ Four reads, cheapest first. Stop as soon as the player's question is answered.
    and read the verdict's `reading` as step 2 of the deploy flow describes it: `live` is what the
    agent reads now, and `lastClose` is the decision its row names as its last close, with the reading
    that bar was decided on.
-2. **`get_radar_activity_summary`** for everything else about "why is it quiet", in ONE call. It
-   carries three parts and they answer three different questions, each on its own scope:
+2. **`get_radar_activity_summary`** for everything else about "why is it quiet", in ONE call. Pass
+   `agentId` when the question is about one agent — "why isn't Hawk firing on SOL?" — and the read is
+   that agent's history on the coin. Without it the read is the **coin feed**: the deployment's
+   lifecycle, status changes, duty changes and fires, with no agent's gates, an empty `curveDigest`
+   and no curve agent. An `agentId` the player cannot access is answered as not found. It carries
+   three parts and they answer three different questions, each on its own scope:
    - `groups` — which cause recurs and how often, over the window the response names. Quote the
-     counts with that window; never sum them across calls.
-   - `curveDigest` — how often the pair qualified, over the FIRST on-duty agent's ring (the
-     lowest-numbered slot on duty now, named in `curveAgentName`): `qualifiedCount` of
-     `sampleCount`, and the latest ATR% with how many samples read one. A pair that qualified on no
-     sample is one whose strategy does not fit this coin as it trades now; the `groups` above name the
-     gate that blocked it. Its `ringStartAt` / `ringEndAt` describe the ring, NOT the cause window
-     above.
-   - `recentEvents` — the last ten key events, lean. Deliberately NOT bounded by the cause window, so
-     a pair quiet for longer returns no groups beside populated older rows. That is correct, not a
-     contradiction; each row carries its own `occurredAt`.
-
-   The groups and rows span every on-duty agent — each row names its own — while the digest describes
-   the first one. For about one sweep after the on-duty set changes the digest can name the new first
-   agent while the rows still show the old one — the two halves are read from different stores. Say
-   "duty just changed" rather than reporting a contradiction. Joins and departures are journaled as
-   `ON_DUTY_JOINED` / `ON_DUTY_LEFT`, one row per agent, and a lost coin as
-   `EDGE_PRESERVED_COIN_CLAIMED`.
+     counts with that window; never sum them across calls. On the coin feed a blocked status counts
+     by its idle reason, never by an agent's gate; an agent's history counts its own gates.
+   - `curveDigest` — with `agentId`, how often that agent qualified on this coin, over its own ring
+     (named in `curveAgentName`): `qualifiedCount` of `sampleCount`, and the latest ATR% with how many
+     samples read one. A pair that qualified on no sample is one whose strategy does not fit this
+     coin as it trades now; the `groups` above name the gate that blocked it. Its `ringStartAt` /
+     `ringEndAt` describe the ring, NOT the cause window above.
+   - `recentEvents` — the last ten key events of the same scope, lean. Deliberately NOT bounded by the
+     cause window, so a pair quiet for longer returns no groups beside populated older rows. That is
+     correct, not a contradiction; each row carries its own `occurredAt`.
+
+   With `agentId` the groups, the digest and the rows all describe that one agent. Two agents on duty
+   are two reads, one per `agentId`. Joins and departures are journaled as `ON_DUTY_JOINED` /
+   `ON_DUTY_LEFT`, one row per agent, in both the coin feed and that agent's history, and a lost coin
+   as `EDGE_PRESERVED_COIN_CLAIMED`.
 3. **`get_radar_close_decisions`** when the question is about ONE close — "why didn't the 14:00 bar
    fire?", "why did it fire there?", "what did it see at that close?". Every bar the close step
    decided has one record, whether a policy's agent or a manual request's watch decided it: its
@@ -350,13 +352,16 @@ Four reads, cheapest first. Stop as soon as the player's question is answered.
    refused it and nothing was traded. It is the only history of not-qualifying closes: the journal
    writes no row for one, and `resolvesNow` keeps only each agent's last decision — the one
    `reading.lastClose` (step 1) carries; this read holds every decision before it. Narrow with
-   `agentId`; page back by passing the oldest returned `bar.barStart` as `before`. A bar still
+   `agentId`; page back by passing the response's `nextBefore` as `before`, and stop when
+   `nextBefore` is null — that is the end of the history. A bar still
    waiting inside its window has no record yet (`resolvesNow` shows its `closeDecision.state` as
    `DEFERRED`), and records are kept 90 days.
 4. **`get_radar_activity`** only for what steps 2 and 3 cannot do: more rows than its ten, a
-   FIRES-only view, paging back through history, or ONE occurrence's full margins. Rows are lean by
-   default — pass `detail: 'FULL'` for the margin surface, and `includeCurve: true` only if something
-   will actually plot the points.
+   FIRES-only view, paging back through history, or ONE occurrence's full margins. Its scope is step
+   2's: pass `agentId` for one agent's rows, and omit it for the coin feed, which carries no agent's
+   gate crossings, verdict flips or regime changes. Rows are lean by default — pass `detail: 'FULL'`
+   for the margin surface, and `includeCurve: true` only if something will actually plot the points;
+   `includeCurve` requires `agentId`, and is refused without it.
 
 **Neither of the first two substitutes for the other, and the reason is structural.** The journal is
 a TRANSITION log, not a state log: a gate that has blocked continuously without crossing again

package/skills/battlegrid-strategy-authoring/SKILL.md

@@ -107,10 +107,12 @@ Compose sections, columns and conditions **only** from vocabulary returned in th
 field you remember from another strategy is not discovery.
 
 **Conditions are the only deterministic entry gate.** A condition gates an entry when it is
-`required` or carries a verdict (UP, DOWN or NEITHER); a building block — neither required nor a
-verdict carrier — gates nothing, and an exit rule never counts. A strategy whose entry conditions
-include no required and no verdict-carrying condition never routes a trade: every coin fails first
-with `NO_ENTRY_CONDITION`, and its draft carries the warning of the same name. It stays a valid
+`required` or carries a verdict (UP, DOWN or NEITHER); a building block — a condition with no
+verdict — gates nothing unless it is itself marked `required`, and an exit rule never counts.
+Whether a sub-rule should be a building block or inlined is answered by the `strategy-examples`
+skill's **Building block or inline** paragraph. A strategy whose entry conditions include no
+required and no verdict-carrying condition never routes a trade: every coin fails first with
+`NO_ENTRY_CONDITION`, and its draft carries the warning of the same name. It stays a valid
 strategy — Market Grid reads it as context — so a strategy the player means to trade needs at least
 one. Before any condition is read, a coin must clear the ATR floor, `minAtrPct`, the
 TRADE_LEVEL_POLICY dial beside the stop-loss band.

package/skills/battlegrid-strategy-examples/SKILL.md

@@ -77,7 +77,7 @@ add. Either way you never invent one. To section-qualify a duplicated header, re
 `detail: "detailed"` preview's `authoring.conditionColumns` or from the qualified candidates a
 `CONDITION_COLUMN_AMBIGUOUS` refusal offers.
 
-**Event columns print only on their event.** `MACD_cross` and `EMA5_13` (Bullish/Bearish) carry a
+**Event columns print only on their event.** `MACDhist_cross` and `EMA5_13` (Bullish/Bearish) carry a
 value on the crossing bar and are null on every other one, which reads as UNRESOLVED. Use an event
 column as a TRIGGER inside a carrier, and pair it with a persistent state — a spread sign,
 `MAalign` — for regime. A condition that treats an event column as a standing state is unresolved on
@@ -163,14 +163,56 @@ setups block and from the `decide_trade` contract, not merely discouraged in the
 declares no verdict-carrying condition resolves `null` and constrains no side.
 
 **A strategy without an entry condition never routes.** An entry condition gates when it is
-`required: true` or carries a verdict (`UP`, `DOWN` or `NEITHER`); a building block gates nothing,
-and an exit rule never counts. A strategy whose conditions include neither never trades: every coin
-fails first with `NO_ENTRY_CONDITION`, before the trade levels, the ATR floor or any condition is
-read, and its draft carries the `NO_ENTRY_CONDITION` warning. It stays a valid strategy — Market Grid
+`required: true` or carries a verdict (`UP`, `DOWN` or `NEITHER`); a building block not marked
+`required` gates nothing, and an exit rule never counts. A strategy whose conditions include neither
+never trades: every coin fails first with `NO_ENTRY_CONDITION`, before the trade levels, the ATR
+floor or any condition is read, and its draft carries the `NO_ENTRY_CONDITION` warning. It stays a valid strategy — Market Grid
 reads it as context — so this is a choice to state, never an accident. When the agent decides a
 routed trade, its `decide_trade` call cites 1–8 of the evaluated entry conditions in
 `conditionChecklist`, and only a condition that read TRUE may be cited as `CONFIRM`.
 
+**Building block or inline — the same logic, different reach.** A `conditionRef` reads the
+referenced condition's one answer for the bar being decided — TRUE, FALSE or UNRESOLVED, exactly what
+its tree reads in place — so moving a subtree into a building block, or back, never by itself changes
+a coin's result. What differs is what each form can reach and what each costs.
+
+Make it a building block when:
+
+- **The tree nests past the depth cap.** "Not a breakout", where a breakout is an `ANY` of `ALL`s,
+  is a `NOT` over a group over groups; inside another condition's `ALL` that is one level too deep,
+  so the breakout becomes its own building block and the carrier reads `NOT [UP_BREAKOUT]`
+  (`CONDITION_GROUP_DEPTH_EXCEEDED` names this remedy).
+- **One condition would pass `budgets.conditionClauses`** (served by `list_strategy_vocabulary`). A
+  reference spends no clause and no frame read, so a sub-rule referenced from several conditions is
+  counted once; every pasted copy is counted again, against `budgets.conditionFrameReads` too.
+- **The gate is "either side".** Every `required` condition must read TRUE, so marking `RANGE_LONG`
+  and `RANGE_SHORT` both required demands both at once. The gate is one building block,
+  `SETUP_VALID` = `ANY [RANGE_LONG, RANGE_SHORT]`, marked `required: true`. It is not redundant with
+  the carriers' verdicts: the verdict that binds direction is held through a contrary reading until
+  that reading repeats for the dwell the binding records (`verdictDwellRequired` on a signal log's
+  `verdictBinding`), while a required condition reads the decided bar alone — so the required block
+  is what insists the setup is present now.
+- **The sub-rule should be read by name.** A building block's outcome renders under its own key in
+  the prompt the agent reads, in the signal log's condition evaluation and in the studio's per-coin
+  readout; an inlined clause shows only as evidence under the condition holding it.
+  `AT_DEMAND TRUE · FLOW_LONG_OK FALSE` tells the agent and the player why; `RANGE_LONG FALSE` alone
+  does not.
+- **It must read TRUE without voting.** Verdict resolution skips a building block, so a location or
+  flow test never sets a side and never contradicts a carrier into `NEITHER`.
+
+Inline it when:
+
+- **It is one clause used once.** As a building block it spends a whole condition slot out of
+  `budgets.strategyConditions` for nothing but its name.
+- **The composite must be counted across closes.** A group holding more than Once holds no
+  `conditionRef`, so "together on 3 closes in a row" over a sub-rule needs its clauses inline.
+
+Inlining a `NOT` is not always a flipped operator. A clause whose read ran and found no value reads
+FALSE, so `NOT [dist_donchianHi gt -0.52]` reads TRUE on a coin with no channel value while
+`dist_donchianHi lte -0.52` reads FALSE; `NOT [CVD_state is "bearish"]` and
+`CVD_state in ["bullish", "neutral"]` part the same way. Flip only a header that always carries a
+value, or choose deliberately which answer a missing value gives.
+
 A verdict carrier must read no DEVELOPING bar. A verdict is refused over any closure that reads a
 column selecting Developing above the strategy timeframe (`CONDITION_VERDICT_READ_ILLEGAL`). The
 closure is what the condition reads directly plus everything reached through `conditionRef`,
@@ -344,7 +386,8 @@ within the buffer of the level is `touch_from_below`. From above is the mirror o
   crossing 0: `dist_bbUpper crossesAbove 0` from below, `crossesBelow 0` from above. On the strategy's
   own rung a `…_from_below` label never holds on a bar where `crossesAbove 0` holds.
 - **Which levels take it.** A candle-homed level — a band (`BB_UPPER`, `BB_LOWER`, `KC_UPPER`,
-  `KC_MID`, `KC_LOWER`), `VWAP`, a moving average (`SMA20`, `EMA20`, …), `ST_LINE`, `PSAR`, the
+  `KC_LOWER`), `VWAP`, a moving average (`SMA20`, `EMA20`, …), `ST_LINE`, `PSAR`, the Donchian break
+  memory (`DONCHIAN_BROKEN_HI`, `DONCHIAN_BROKEN_LO`), the
   Ichimoku lines, the swing levels (`SWING_FRACTAL_HIGH`, `SWING_FRACTAL_LOW`) — reads its own value at
   each of the two bars. A prior-session level or pivot (`PDH`,
   `PDL`, `PDO`, `PIVOT_P`, `PRIOR_TPO_POC`, …) has one reading for the session, used as both bars' level;

package/skills/battlegrid-strategy-examples/references/recipes.md

@@ -41,7 +41,7 @@ rather than events all live there. This document assumes them.
 and is null otherwise:
 
 ```json
-{ "metric": "MACD", "transformId": "crossDetect", "timeframe": { "rel": "anchor" } }
+{ "metric": "MACD_HIST", "transformId": "crossDetect", "timeframe": { "rel": "anchor" } }
 ```
 
 An event column is a trigger inside a carrier, never a standing state; pair it with a persistent

package/skills/battlegrid-strategy-examples/references/tradingview-ports.md

@@ -45,7 +45,7 @@ rules about the columns themselves, not about porting — they live in the skill
   `ST_DIR enters "bullish"` is TRUE on the one completed bar the direction turned, and
   `ST_DIR exits "bullish"` on the bar it turned back — see `## Conditions` in the skill body.
 - **MACD + 200 MA filter** → `ABOVE_200` building block (`dist_SMA200 gt 0`) referenced by a
-  carrier with `MACD_cross is "Bullish"`; swing-trend geometry.
+  carrier with `MACDhist_cross is "Bullish"`; swing-trend geometry.
 - **Golden / Death Cross** → `SMA50 spread SMA200 × trajectory` gives state and freshness:
   `SMA50_SMA200_spread_now gt 0` AND `_trend is "rising"`; optional breadth gate on
   `mktBreadth_crypto gte 0` — every published scope resolves, not only `all`, because the leg reads
@@ -84,7 +84,11 @@ rules about the columns themselves, not about porting — they live in the skill
   script ports onto the two-bar swing, and the spec-lock question says so.
 - **Now native, formerly substituted** — WaveTrend (`WT1`/`WT2`), QQE (`QQE_RSI_MA`/`QQE_STOP`),
   Hull (`HMA20`), Ichimoku (`ICHI_CONV`/`ICHI_BASE`/`ICHI_SPAN_A`/`ICHI_SPAN_B`/`ICHI_LAG`),
-  Parabolic SAR (`PSAR`), Keltner (`KC_UPPER`/`KC_MID`/`KC_LOWER`), daily pivots
+  Parabolic SAR (`PSAR`), Keltner (`KC_UPPER`/`KC_LOWER`, its basis is `EMA20`), the MACD and PPO lines
+  and signals (`MACD_LINE`/`MACD_SIGNAL`, `PPO_LINE`/`PPO_SIGNAL` — the line's zero cross is
+  `MACD_LINE × crossDetect`, and the signal-line cross is `MACD_HIST × crossDetect`, the histogram being
+  line minus signal), the 15-bar rate of change (`ROC15`), the Donchian break memory
+  (`DONCHIAN_BROKEN_HI`/`DONCHIAN_BROKEN_LO`), daily pivots
   (`PIVOT_P`/`PIVOT_R1`–`R3`/`PIVOT_S1`–`S3`), Williams %R (`WILLR14`), Stochastic RSI
   (`STOCH_RSI14`), the TTM squeeze (`KC_SQUEEZE`), Connors RSI-2 (`RSI2`), the 9/21/50 EMAs
   (`EMA9`/`EMA21`/`EMA50`), literal previous-session levels (`PDH`/`PDL`/`PDO`), and fractal swing