@battlegrid/mcp-server 32.0.18 → 32.0.21

package/README.md

@@ -38,6 +38,207 @@ 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 — v127 (a read serves what its code computes, and says so)
+
+**Breaking at v127: two answers narrow for calls you could already make, and every radar journal row gains one
+field.** v127 is the contract on top of v126. No input you could send is refused. Reconnect the proxy, or restart it,
+so discovery reads the new descriptions and schemas.
+
+### Narrowed answer — a call you made now returns less
+
+- **`get_trade_chart` and `get_public_agent_trade_chart` return `UNAVAILABLE` for a CLOSED trade with no stored
+  chart.** A read used to capture the chart on the spot and answer `READY`; it no longer writes anything or fetches
+  candles. The chart is captured once, by a background job after the trade closes (it retries for about two and a
+  half hours). `UNAVAILABLE` now covers: no entry decision or no position; a position that has not closed; and a
+  closed position whose capture is still waiting out its delay, failed, or predates capture. Trades closed before
+  2026-07-28 without a chart stay `UNAVAILABLE`.
+- **`get_agent_explorer` returns 25 entries by default** (was 100). `limit` still accepts 1-100; pass it to ask for
+  more. A result over the result cap is refused with `nextAct: narrow` — ask again with a smaller `limit`.
+
+### Added output — a field you can read
+
+- **`signalLogId` on every `get_radar_activity` row and every `get_radar_activity_summary` recent row.** On a
+  `FIRE_DISPOSITION` row whose disposition is `FIRED`, it names the signal log that fire's evaluation wrote — open it
+  with `get_signal_log({ agentId, logId })`. It is `null` when that evaluation wrote none (screened out or blocked
+  before a log existed) and on every other row. A strict-schema client accepts the new key on each variant.
+
+### Corrected answers — same shape, true values
+
+- **`get_intelligence_agent`** and the receipts of create, update, activate and archive serve your rolling-24h LLM
+  spend on the agent (`last24hCostUsd`), your own active Arena deployments of it (`activeGameCount` — another
+  user's deployments of a platform agent are not counted) and `hasActiveAssignments`, the values
+  `list_intelligence_agents` serves. They used to serve `0`, `0` and `false`.
+- **`get_agent_decision_context`** serves the open position's real `signalLogId` (it served `''`). It answers only
+  for an agent position that is OPEN on the coin; for a coin that did not trade, read `list_gate_blocks` and
+  `get_radar_activity_summary`.
+- **`get_radar_activity`'s `FIRES` filter** keeps each fire's `EVALUATION_OUTCOME` row beside its disposition — the
+  only record of a fire refused before it wrote a signal log.
+
+### Declared sizes — the result cap is announced
+
+- `get_radar_activity` (narrow with `limit`, `detail` or `includeCurve`), `get_agent_explorer` (narrow with `limit`),
+  `get_public_agent_signal_log_detail` and `list_radar_deployments` (read one coin with `get_radar_deployment`)
+  carry `_meta["anthropic/maxResultSizeChars"]`.
+
+### Corrected descriptions
+
+`get_signal_log` names every block with its null case; `get_public_agent_signal_log_detail` states that a FAILED log
+returns `log: null`; `get_radar_deployment` says a null `minConviction` is no floor (never inherited) and
+`resolvedConviction` is the slot's own bar; `get_radar_activity_summary` names `ENTRY_VOID` and its 168-hour window;
+`list_radar_deployments` names `summary.radarPaused`; `get_regime_snapshot`'s 4h is a default only — a Radar slot
+reads its agent's own regime timeframe.
+
+## Contract history — v126 (a queued entry executes at its close; nothing waits for an approval)
+
+**Breaking at v126: three entry-decision tools leave the catalog you discover, two outputs narrow, and one status
+value is renamed.** v126 is the contract on top of v125. Reconnect the proxy, or restart it, so discovery reads the
+new catalog.
+
+A request you queue with `propose_entry_decision` is now an entry the player has already consented to: at the
+agent's decided strategy-bar close, a qualifying entry is placed at once, sized by the agent's own risk budget, with
+no further step. Confirm with the player before calling it — their ask to trade that coin with that agent, or a
+standing instruction to trade for them, is the consent. The `mcp:wager` grant is that standing permission for an MCP
+client, and the consent screen says so.
+
+### Removed tools — something you called is gone
+
+A call naming one is answered as an unknown tool; there is no alias, and none has a replacement call.
+
+- **`accept_entry_decision`**: nothing waits to be accepted. The entry executes at its decided close; consent comes
+  before `propose_entry_decision`.
+- **`cancel_entry_decision`**: a decided entry is not cancelled. Withdraw a queued request with
+  `cancel_entry_request({ requestId })` until its close fires.
+- **`list_pending_approvals`**: read a pending request with `get_entry_request({ requestId })`, and placing and live
+  positions with `list_user_active_positions()`.
+
+### Narrowed output — a shape you read has fewer members
+
+- **`propose_entry_decision`** (now titled *Queue Entry*) returns `result` as `queued | error`. The `recommendation`
+  and `no_trade` members are gone; a decided close's answer lands in the request's conversation, read with
+  `get_trade_conversation`.
+- **`get_agents_hub`** publishes no approval: `hubStatus` is `IN_TRADE`, `RADAR_ARMED`, `ARENA_DEPLOYED` or `IDLE`
+  (in that precedence), rows have no `pendingApprovalCount`, and the summary has no `totalPendingApprovalCount`.
+
+### Renamed value — a word you matched changed
+
+- The execution status **`AWAITING_APPROVAL` is `PROPOSED`** wherever it is published (`get_signal_log`,
+  `get_public_agent_signal_log_detail`): a position whose order is being placed. Match `PROPOSED` where you matched
+  `AWAITING_APPROVAL`.
+
+### Re-specified behavior
+
+- **A queued request's entry executes at its decided close.** Its conversation's `recommendation` card is the entry
+  locator: it names the decision (`get_entry_decision`) and the position the request placed.
+- **Every request that is not withdrawn is answered once.** A request whose deadline passed unanswered is answered by
+  the next sweep — `close_missed` for its bar, or the engine's `EVALUATION_FAULTED` for a fired one whose decision job
+  is gone — and reads as pending through `get_entry_request` until then.
+
+## Contract history — v125 (MCP serves the read the client shows)
+
+**Breaking at v125: nine trade and signal tools leave the catalog you discover, one tool joins it, two outputs
+reshape, one tool refuses three inputs, one output field and three ack fields are gone.** v125 is the contract on top
+of v124. Reconnect the proxy, or restart it, so discovery reads the new catalog.
+
+### Removed tools — something you called is gone
+
+Each was a parallel, narrower or dead read beside the one the web client shows. A call naming one is answered as an
+unknown tool; there is no alias.
+
+- **`list_trade_outcomes`**: call `list_agent_trades({ agentId })`, then
+  `get_trade_outcome_by_decision({ decisionId })` for a trade's fills, fees, gross P&L, slippage, leverage,
+  `closedBy`, duration, excursion and `exitRepriceSource`.
+- **`get_signal_performance`**: call `get_public_agent_signal_performance({ agentId })`. The owner's slice is
+  `list_signal_logs({ agentId }).summary` and `list_agent_trades({ agentId }).summary`.
+- **`get_agent_open_positions`**: call `get_public_agent_open_positions({ agentId, filter: { coinTicker: [...] } })`.
+- **`get_public_agent_unrealized_pnl`**: call `get_public_agent_open_positions({ agentId, filter: { signalSource } })`;
+  its `unrealizedPnlUsd` is the figure.
+- **`list_session_agent_positions`**: call `list_user_active_positions()`; each position carries
+  `marketGridSessionId`.
+- **`get_order_status`**: call `list_agent_open_orders()` for the platform's record, `get_open_orders()` for the
+  venue's.
+- **`get_decision_order_attribution`**: call `list_agent_open_orders()`, `list_user_active_positions()` and
+  `list_agent_trades()`; each row names its `decisionId`.
+- **`list_entry_decisions`**: call `list_signal_logs({ agentId })`, then `get_signal_log({ agentId, logId })`.
+- **`get_agent_fund_allocation`**: call `get_agent_budget({ agentId })` for `haltedAt`, `haltReason` and
+  `perTradePushEnabled`.
+
+### Added tool and fields
+
+- **`get_public_agent_open_positions({ agentId, filter })`** serves an agent's open book, newest open first. Each
+  row carries its decided `stopLoss` and `takeProfit` and its live `mark` (`unrealizedPnlUsd`, `movePercent`,
+  `roePercent`; `null` when the coin has no usable mark), beside the marked rows' `unrealizedPnlUsd` and an
+  `unpricedPositionCount`. The row's open instant is `openedAt`; `leverage` and `signalLogId` are never null, and
+  there is no `timeHorizon`. An archived or unknown agent reads as no positions.
+- **`list_agent_trades`** rows carry `decisionId`, the key `get_trade_outcome_by_decision` takes. The tool accepts
+  `q` (1–64 characters after trimming).
+- **`list_agent_open_orders`** rows carry `exchangeOrderId` (`null` until the venue acknowledges), `cloid` and
+  `decisionId`, so an agent order joins `get_open_orders` and chains to its decision.
+
+### Reshaped output — something you read moved
+
+- **`list_signal_logs`** serves the My Agents Signals tab's read: `{ signals, nextCursor, summary }` across every one
+  of your agents unless `agentId` narrows it. Each row names its agent and carries `rejection`, the reason and detail
+  of the signal's rejected agent position, `null` otherwise.
+- **`list_user_active_positions`** serves every position once, in `positions`. Each `agents` entry keeps its group
+  figures and loses its nested `positions`.
+
+### Rejected input — a key you sent is refused
+
+- **`list_signal_logs`** refuses `direction`, `terminalStatus` and `signalSource` as unrecognised keys. Its `agentId`
+  is optional, and it accepts `coinTicker`, `q`, `cursor` and `limit` (1–50, default 10).
+
+### Removed fields — a value you read is gone
+
+- **`skippedCount`** leaves `get_public_agent_signal_performance`; it was always `0`. `skipCount` counts the SKIP
+  decisions, and `blockedCount` counts the agent's ineligible attempts.
+- **`availableUsd`, `lifetimeAllocatedUsd` and `lifetimeRecalledUsd`** leave the `allocation` that
+  `halt_intelligence_agent`, `resume_intelligence_agent` and `set_agent_per_trade_push` return; it is now
+  `{ agentId, haltedAt, perTradePushEnabled }`. The three figures were zero on every agent.
+
+### Declared result size
+
+- **`list_signal_logs` and `list_agent_trades` declare the configured result cap.** A page past it is refused with
+  `nextAct: narrow`; ask again with a smaller `limit`.
+
+## Contract history — v124 (an agent's record is its thought log and its activity feed)
+
+**Breaking at v124: three agent-record tools leave the catalog you discover, and a thought-log entry loses a
+field.** v124 is the contract on top of v123.2.0. Reconnect the proxy, or restart it, so discovery reads the new
+catalog.
+
+### Removed tools — something you called is gone
+
+Each was a duplicate door onto the two per-agent reads. A call naming one is answered as an unknown tool; there is
+no alias.
+
+- **`get_agent_journal({ agentId, limit })`**: call `get_agent_thought_log({ agentId, limit })` and
+  `get_agent_activity_feed({ agentId, limit })`. Read the owner's `username` from `get_account_state()`.
+- **`get_user_thought_log`**: call `get_agent_thought_log({ agentId })` for each agent
+  `list_intelligence_agents()` lists. Read a trade's reasoning from `get_signal_log`, and an arena entry's reasoning
+  from `list_my_market_grid_entries` and `get_my_market_grid_entry`.
+- **`get_user_activity_feed`**: call `get_agent_activity_feed({ agentId })` for each agent
+  `list_intelligence_agents()` lists.
+
+### Reshaped output — a field you read is gone
+
+- **`get_agent_thought_log` entries no longer carry `marketSnapshot`.** For an arena decision it held the agent's
+  whole resolved prompt, larger than the result cap, so a page holding one could not be served at all, even at
+  `limit: 1`, and no later entry could be reached. Each entry still carries its outcome, written reasoning, grid pick
+  and parsed picks, confidence and the floor enforced against it, its usage-event link and its creation instant.
+
+### Declared result size
+
+- **`get_agent_thought_log` declares the configured result cap.** A page past it is refused with
+  `nextAct: narrow`; ask again with a smaller `limit`.
+
+### Descriptions
+
+- `get_agent_thought_log` names both decisions it records: an arena grid decision and a trade thesis
+  (`AGENT_TRADE_THESIS`, whose full pipeline is `get_signal_log`).
+- `get_agent_activity_feed` names the event families its rows carry: arena auto-submit triggers and grid outcomes,
+  cost-limit and insufficient-funds blocks, funds committed to a trade or a wager, halts and admission blocks, and
+  lifecycle events.
+
 ## Contract history — v122 (only an officer's own turn records a review)
 
 **Breaking at v122: two officer review tools leave the catalog you discover.** v122 is the contract on top of v121.

package/dist/index.d.ts

@@ -47,7 +47,7 @@ import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/cli
  * 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 = "32.0.18";
+export declare const PACKAGE_VERSION = "32.0.21";
 export declare const DEFAULT_URL = "https://mcp.battlegrid.trade/mcp";
 export interface EnvConfig {
     apiKeys: string[];

package/dist/index.js

@@ -49,7 +49,7 @@ import { Client, SdkHttpError, StreamableHTTPClientTransport } from '@modelconte
  * 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 = '32.0.18';
+export const PACKAGE_VERSION = '32.0.21';
 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": "32.0.18",
+  "version": "32.0.21",
   "description": "BattleGrid MCP server — play crypto prediction games from AI agents",
   "type": "module",
   "main": "dist/index.js",

package/skills/EXPORT.json

@@ -1,6 +1,6 @@
 {
   "generator": "battlegrid-app/server/scripts/export-mcp-skills.mjs",
-  "contractVersion": "122.0.0",
+  "contractVersion": "123.1.0",
   "files": {
     "battlegrid-agent-management/SKILL.md": "4c2cb5cfec27cf11769d66763e024e6900c392e27a978de3080cf55b2ece7a68",
     "battlegrid-agent-management/references/agent-stage-examples.md": "dffcc353d61dfc7b5bb6a2b3077fc6bf8c760a34c287cafb3b59b99306f24195",
@@ -15,10 +15,10 @@
     "battlegrid-strategy-authoring/SKILL.md": "39cfa46b1f640e6800edb7e85a8f2c4b6b8786cddf71bb8244d172a44fc11d75",
     "battlegrid-strategy-authoring/references/strategy-stage-examples.md": "f10ecdc91f3660a708eee7a7bacefce2acbb46c9cf7e0ac1454bd54f839f39fd",
     "battlegrid-strategy-doctor/SKILL.md": "e34e055b0cc9b355bc1adeb5d49d464eaa0756ca3f48dc89ca2ccdda94e1311f",
-    "battlegrid-strategy-examples/SKILL.md": "5e0d3244ed0592b8af933c0925346b6bd3bbaeef6c7acb35329925a026e7cd05",
-    "battlegrid-strategy-examples/references/playbooks.md": "275352be43652ca0fd36a35981ea7ffcfabdc4f9b33293826656ee500d3795e9",
+    "battlegrid-strategy-examples/SKILL.md": "9d18bf0e4bf85a28508e2881a4cdf77b823ec831e7cec5d82f82dc251402f41c",
+    "battlegrid-strategy-examples/references/playbooks.md": "a9464789df2e762faf9dbd7845101564bc1847cd193f709f8ac4b6bff08f09dd",
     "battlegrid-strategy-examples/references/recipes.md": "806aae0b4842408f6e6ed3e108293073f4f31d1c27fa419ad57df9e1134f23e7",
-    "battlegrid-strategy-examples/references/tradingview-ports.md": "9eaa926cbe8606c6a09f91007a0606042afbfdc50173a5b13ae9336d2e9e9b08",
+    "battlegrid-strategy-examples/references/tradingview-ports.md": "c62ce72b741abe5a92e1dec6615f26b19a54959aa1d29542518cd9a189390b98",
     "battlegrid-trade-analysis/SKILL.md": "3f927b4f9796178526fa1673a2043c5f14358c39aa955de33192ea58641f18fb",
     "battlegrid-trade-proposal/SKILL.md": "e761fc6bddc0d1db79fcb90046d03a18439562c8658de726ec286830edd6369b"
   }

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

@@ -32,7 +32,7 @@ Before committing a CREATE, every "no" here is a decision to state, not an omiss
 
 | Transform | Header | Validated example |
 |---|---|---|
-| `value` | `<code>` | `bbWidthPct`, `RVOL`, `rate` |
+| `value` | `<code>` | `bbWidthPct`, `RVOL20`, `rate` |
 | `trajectory` w4 | `<code>_t3…_t1`, `_now`, `_trend` (rising/falling/flat) | `RSI14_now`, `RSI14_trend` |
 | `distance` | `dist_<code>` (signed % from price) | `dist_SMA50` |
 | `spread` | `<base>_<operand>_spread` | `mark_oracle_spread` |
@@ -40,8 +40,8 @@ Before committing a CREATE, every "no" here is a decision to state, not an omiss
 | `rank` | `<code>_rank_<hi\|lo\|far\|near>` — ordinal, `lte N` = top-N | `bbWidthPct_rank_lo` |
 | `efficiency` wN | `<code>_er` (1 straight, ~0 chop) | `close_ltf_er` |
 | `maxShare` wN | `<code>_maxShare` | `volBase_ltf_maxShare` |
-| `classifyZone` / `classifyState` | `<code>_zone` / `<code>_state` | `RSI14_zone`, `ADX_state` |
-| `levelInteraction` | `<code>_lvl`, `<code>_lvl_b<N>` at a buffer of N bps | `bbUpper_lvl`, `bbUpper_lvl_b25` |
+| `classifyZone` / `classifyState` | `<code>_zone` / `<code>_state` | `RSI14_zone`, `ADX14_state` |
+| `levelInteraction` | `<code>_lvl`, `<code>_lvl_b<N>` at a buffer of N bps | `bbUpper20_lvl`, `bbUpper20_lvl_b25` |
 | any, stored `"bars": "all"` | `<code>_dev`, then the transform's suffix | `RSI14_dev_t1` |
 | `value` at `offset` N > 0 | `<code>_o<N>` | `RSI14_1d_o1` |
 
@@ -151,16 +151,16 @@ Recipes — each one clause:
   `dist_SMA20` is the close's distance from the average, so crossing 0 is the close crossing it.
 - **RSI entered overbought** — `RSI14_zone enters "overbought"` (the RSI module).
 - **Squeeze released** — `kcSqueeze exits "on"`, over a `KC_SQUEEZE` value column.
-- **New 20-bar high** — `donchianHi increased`, over a `DONCHIAN_UPPER` value column: the 20-bar
+- **New 20-bar high** — `donchianHi20 increased`, over a `DONCHIAN_UPPER` value column: the 20-bar
   upper channel rises exactly when the decided bar's high exceeds every high of the 20 bars before it.
-- **Close above the prior 20-bar high (Donchian / Turtle breakout)** — `dist_donchianHiPrior crossesAbove 0`,
+- **Close above the prior 20-bar high (Donchian / Turtle breakout)** — `dist_donchianHiPrior20 crossesAbove 0`,
   over a `DONCHIAN_UPPER_PRIOR × distance` column: Pine's `ta.crossover(close, ta.highest(high, 20)[1])`,
-  TRUE on the first close of a breakout run. `dist_donchianHiPrior gt 0` is Pine's
+  TRUE on the first close of a breakout run. `dist_donchianHiPrior20 gt 0` is Pine's
   `close > ta.highest(high, 20)[1]` and holds on every close of the run. Mirror with
-  `dist_donchianLoPrior crossesBelow 0` / `lt 0` over `DONCHIAN_LOWER_PRIOR`.
-- **Failed breakout of the prior 20-bar high** — `donchianHiPrior_lvl is "reject_from_below"`, over a
+  `dist_donchianLoPrior20 crossesBelow 0` / `lt 0` over `DONCHIAN_LOWER_PRIOR`.
+- **Failed breakout of the prior 20-bar high** — `donchianHiPrior20_lvl is "reject_from_below"`, over a
   `DONCHIAN_UPPER_PRIOR × levelInteraction` column: the high pierced the prior 20-bar high and the close
-  came back under it. `dist_donchianHiPrior crossesBelow 0` is NOT "fell back into the channel": the rail
+  came back under it. `dist_donchianHiPrior20 crossesBelow 0` is NOT "fell back into the channel": the rail
   rises to each breakout bar's high, so it fires once on the first bar of a breakout run that does not
   close above the raised rail — the run of new closing highs ended.
 - **RSI crossed above 50 within the last 3 closes** — `RSI14_now crossesAbove 50` holding
@@ -218,8 +218,8 @@ Inline it when:
   `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
+FALSE, so `NOT [dist_donchianHi20 gt -0.52]` reads TRUE on a coin with no channel value while
+`dist_donchianHi20 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.
 
@@ -370,7 +370,7 @@ refuses a commit or a rebind.
 reads the same on every bar of a trend, so `ST_DIR is "bullish"` is a regime filter and never an
 entry signal. The flip is `ST_DIR enters "bullish"`: TRUE on the one completed bar the direction
 turned, with no event column needed. The same distinction applies to every persisting
-classification: `MAalign`, `ADX_state`, `zone` — `is` for the regime, `enters` / `exits` for the
+classification: `MAalign`, `ADX14_state`, `zone` — `is` for the regime, `enters` / `exits` for the
 bar it changed.
 
 **Name the anchor when a metric is calibrated for one.** `KC_SQUEEZE is "on"` reads *on* about 57% of
@@ -397,12 +397,12 @@ reached the level and whose close came back under it is `reject_from_below`; a b
 within the buffer of the level is `touch_from_below`. From above is the mirror on the low.
 
 - **A reject bar reports reject.** It is never also reported as a touch, so "touched or rejected" is
-  an `in` clause over both labels of a side: `bbUpper_lvl in ["touch_from_below","reject_from_below"]`.
+  an `in` clause over both labels of a side: `bbUpper20_lvl in ["touch_from_below","reject_from_below"]`.
 - **`buffer`** is whole basis points of the level, 0–500, default 0 — `buffer: 25` is 0.25%. Only the
-  touch reads it: a reject must pierce the level itself. Two buffers are two columns (`bbUpper_lvl`,
-  `bbUpper_lvl_b25`).
+  touch reads it: a reject must pierce the level itself. Two buffers are two columns (`bbUpper20_lvl`,
+  `bbUpper20_lvl_b25`).
 - **A break is a crossing, never a label.** The break of a level is `distance` over the same level
-  crossing 0: `dist_bbUpper crossesAbove 0` from below, `crossesBelow 0` from above. On the strategy's
+  crossing 0: `dist_bbUpper20 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.**
   - **Offered:** a candle-homed level — a band (`BB_UPPER`, `BB_LOWER`, `KC_UPPER`, `KC_LOWER`),
@@ -420,9 +420,9 @@ within the buffer of the level is `touch_from_below`. From above is the mirror o
     (`DONCHIAN_UPPER`, `DONCHIAN_LOWER`), each the extreme of the window ending at the very bar it would
     classify, which a close can never pass — read `DONCHIAN_UPPER_PRIOR` / `DONCHIAN_LOWER_PRIOR`. A
     price fact (`CLOSE`, `HLC3`, `MARK`) is refused: it is the price, not a level.
-- **A higher-rung level reads that rung's completed bar.** `bbUpper_htf_lvl` classifies the last
+- **A higher-rung level reads that rung's completed bar.** `bbUpper20_htf_lvl` classifies the last
   completed regime-rung bar from its own high, low and close, never the strategy bar's price — so
-  compose its break on the same rung, `dist_bbUpper_htf crossesAbove 0`.
+  compose its break on the same rung, `dist_bbUpper20_htf crossesAbove 0`.
 
 **`BB_TOUCH` and `BB_UPPER × levelInteraction` answer different questions.** `BB_TOUCH` (`BBtouch`)
 says where the CLOSE sits in %B — inside the band edge or not. `BB_UPPER × levelInteraction` says what
@@ -464,7 +464,7 @@ within N reads each of the N bars against its own predecessor.
 Recipes — the level recipes on candle-homed levels:
 
 - **Price rejected the upper Bollinger band** — a `BB_UPPER × levelInteraction` column, header
-  `bbUpper_lvl`; the clause `bbUpper_lvl is "reject_from_below"`.
+  `bbUpper20_lvl`; the clause `bbUpper20_lvl is "reject_from_below"`.
 - **Price touched or rejected VWAP from above** — `VWAP_lvl in ["touch_from_above","reject_from_above"]`,
   with `buffer: 10` for a touch within 0.1% (header `VWAP_lvl_b10`).
 - **Price broke the 20 EMA** — `dist_EMA20 crossesAbove 0`, the `distance` column over the same level.

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

@@ -25,8 +25,8 @@ Custom `Squeeze Scan` (no `sectionKey` — this is a CREATE): `BB_WIDTH_PCT valu
 `bbWidthPct_rank_lo` a second time, which makes both of `SQUEEZE_ON`'s clauses ambiguous, and the
 custom section already carries them.) Conditions: `LIQUID_FLOOR` (required —
 `vol24hUsd gte 25000000`); `SQUEEZE_ON` building block (`bbWidthPct_rank_lo lte 10` AND
-`ADX lt 20`); `BREAK_UP` verdict UP (ref SQUEEZE_ON + `closeChg gt 0` + `RVOL gte 1.5` +
-`pctB gte 0.85`); `BREAK_DOWN` verdict DOWN (mirror with `pctB lte 0.15`). Levels 0.75–1.75 ATR,
+`ADX14 lt 20`); `BREAK_UP` verdict UP (ref SQUEEZE_ON + `closeChg gt 0` + `RVOL20 gte 1.5` +
+`pctB20 gte 0.85`); `BREAK_DOWN` verdict DOWN (mirror with `pctB20 lte 0.15`). Levels 0.75–1.75 ATR,
 RR 2, ATR floor 0.8% — a compression play needs the expansion to be worth the stop. PM: BE 1R; trail 1.2R giveback 35 buffer 0.3.
 Market Read: "Trade only expansions out of compression: {SQUEEZE_ON} must read TRUE… skip
 anything failing {LIQUID_FLOOR}."
@@ -54,8 +54,8 @@ refused, and its legal `far` ordering sorts by |change| — which would put the
 losers in a "leaders" cohort. Custom `BTC Regime` with
 `"benchmarkTicker": "BTC"`: `MA_ALIGN value`→`MAalign`, `ADX value`, `REGIME_TREND value` —
 every row reads BTC. Conditions: `BTC_RISK_ON` building block (`MAalign is "bullish"` +
-`ADX gte 20` — both read bare, since only this section renders them); `BTC_RISK_OFF`
-(`MAalign is "bearish"`); `LEADER` (`roc12_rank_hi lte 5` + `RVOL_rank_hi lte 10` +
+`ADX14 gte 20` — both read bare, since only this section renders them); `BTC_RISK_OFF`
+(`MAalign is "bearish"`); `LEADER` (`roc12_rank_hi lte 5` + `RVOL20_rank_hi lte 10` +
 `vol24hUsd gte 100000000`); `ROTATE_IN` verdict UP (`ALL[ref BTC_RISK_ON, ref LEADER]`);
 `ROTATE_OUT` verdict DOWN (`ALL[ref BTC_RISK_OFF, roc12_rank_lo lte 5]`). Levels 1–2 ATR, RR 1.8,
 ATR floor 0.6%. PM: BE 1R; trail 1R giveback 45. Ranked cohort ≥ 40 —
@@ -63,12 +63,12 @@ rank conditions need a cohort wider than their thresholds.
 
 ### 4 · HTF Trend Pullback — 1h, multi-timeframe confluence
 
-Platform `includeMtfConfluence` (`MAalign_ltf/…/_htf`, `RSI14_*_zone`, `ADX_*_state` vocab
+Platform `includeMtfConfluence` (`MAalign_ltf/…/_htf`, `RSI14_*_zone`, `ADX14_*_state` vocab
 weak/developing/trending/extreme), `includeMovingAverages` (`dist_EMA20`, …), `includeRsi`
 (`RSI14_now`, `RSI14_zone`). These three render `MAalign` and `RSI14_zone` twice between them, so
 every condition below reads a suffixed form — never bare `MAalign` or bare `RSI14_zone`, which
 would be ambiguous. Conditions: `HTF_UP` building block (`MAalign_htf is "bullish"` +
-`ADX_htf_state in ["trending","extreme"]`); `HTF_DOWN` mirror; `TREND_PRESENT` **required**
+`ADX14_htf_state in ["trending","extreme"]`); `HTF_DOWN` mirror; `TREND_PRESENT` **required**
 `ANY[ref HTF_UP, ref HTF_DOWN]` — chop blocks compose-trade entirely, before billing;
 `PULLBACK_LONG` verdict UP (ref HTF_UP + `RSI14_now between 35 55` +
 `dist_EMA20 between -3 0.5`); `PULLBACK_SHORT` verdict DOWN (mirror, 45–65 / −0.5–3). Levels
@@ -82,9 +82,9 @@ perp_led_fragile / spot_led_accumulation / neutral), `includeStructureZones`
 (`BUY_PRESSURE value`→`buyPres` 0–1, `RVOL value`, `CLOSE_CHANGE value`). Conditions:
 `SPOT_ACCUM` (`perpSpotFlow is "spot_led_accumulation"`); `NEAR_SUPPORT`
 (`zones_htf_support_dist between 0 2` + `zones_htf_support_age_h gte 12`); `DIP_BID` verdict
-UP — refs plus an `N_OF(2)` quorum over `buyPres gte 0.55` / `RVOL gte 1.2` / `closeChg gt 0`
+UP — refs plus an `N_OF(2)` quorum over `buyPres gte 0.55` / `RVOL20 gte 1.2` / `closeChg gt 0`
 (quorum beats a brittle ALL); `FRAGILE_POP` verdict DOWN (`perp_led_fragile` +
-`zones_htf_resist_dist between -2 0` + `RVOL gte 1.3`). Levels 0.5–1.2 ATR, RR 1.5, ATR floor
+`zones_htf_resist_dist between -2 0` + `RVOL20 gte 1.3`). Levels 0.5–1.2 ATR, RR 1.5, ATR floor
 0.4%. PM: BE 0.7R; trail 0.9R
 giveback 30 buffer 0.15; timeDecay ON aggressive (45/15, 15→60, stale 30).
 

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

@@ -13,6 +13,7 @@ engine) and names its substitutions where the catalog lacks a primitive.
 - Donchian / Turtle breakout
 - ICT / SMC (FVG + order blocks)
 - Pivot highs / lows, HH-HL structure and break of structure
+- Chaikin Money Flow
 - Now native, formerly substituted
 
 ## TradingView ports — familiar processes, studio vocabulary
@@ -34,7 +35,7 @@ rules about the columns themselves, not about porting — they live in the skill
   `BB_LOWER spread KC_LOWER` still express the same reading at a threshold you choose. Release
   direction from the MACD trajectory, `bollinger_squeeze` Critical-required.
   Its selectivity is anchor-dependent — see `## Conditions` in the skill body before gating on it.
-  (`bbWidthPct_rank_lo` + `ADX lt 20` remains a serviceable board-relative compression proxy, but it
+  (`bbWidthPct_rank_lo` + `ADX14 lt 20` remains a serviceable board-relative compression proxy, but it
   is no longer the only option.)
 - **Supertrend / UT Bot / Chandelier Exit** → `ST_LINE` and `ST_DIR` are native, so the regime
   half is a direct port: `ST_DIR is "bullish"` as the persistent state, `dist_ST_LINE` for
@@ -58,16 +59,16 @@ rules about the columns themselves, not about porting — they live in the skill
   reading while the literal is a threshold the author can see and tune. Use the zone as a report
   column, never as the substitute for the gate.
 - **VWAP reversion** → `dist_VWAP` band + `dist_VWAP_rank_far lte 5` for board-relative
-  stretch; required `NOT [ADX_state in ["trending","extreme"]]` veto; scalp geometry +
+  stretch; required `NOT [ADX14_state in ["trending","extreme"]]` veto; scalp geometry +
   aggressive timeDecay (VWAP anchors daily at 00:00 UTC).
-- **Donchian / Turtle breakout** (`close > ta.highest(high, 20)[1]`) → `dist_donchianHiPrior crossesAbove 0`
-  over `DONCHIAN_UPPER_PRIOR × distance` (the breakout bar; `dist_donchianHiPrior gt 0` holds on every
-  close of the run) + `RVOL gte 1.5`; turtle exits = trend preset (trail from 1R, giveback 50). Mirror with
-  `dist_donchianLoPrior crossesBelow 0`. The same-bar rail (`dist_donchianHi`) includes the breakout bar's
+- **Donchian / Turtle breakout** (`close > ta.highest(high, 20)[1]`) → `dist_donchianHiPrior20 crossesAbove 0`
+  over `DONCHIAN_UPPER_PRIOR × distance` (the breakout bar; `dist_donchianHiPrior20 gt 0` holds on every
+  close of the run) + `RVOL20 gte 1.5`; turtle exits = trend preset (trail from 1R, giveback 50). Mirror with
+  `dist_donchianLoPrior20 crossesBelow 0`. The same-bar rail (`dist_donchianHi20`) includes the breakout bar's
   own high, so it can never confirm a close-based break — do not AND it in. `zone is "breakout high"` reads
-  the prior-bar rail: it is the label form of the `dist_donchianHiPrior gt 0` state, holds on every close of
+  the prior-bar rail: it is the label form of the `dist_donchianHiPrior20 gt 0` state, holds on every close of
   the run, and adds nothing to the crossing; `"breakdown low"` mirrors it.
-  **Daily-breakout variant on any anchor:** pin the rail at 1d — `dist_donchianHiPrior_1d crossesAbove 0`
+  **Daily-breakout variant on any anchor:** pin the rail at 1d — `dist_donchianHiPrior20_1d crossesAbove 0`
   (`gt 0` for the held state).
   **Literal previous-day levels are native**: `dist_PDH gte 0` composes directly. They are TIMELESS
   and take `{rel: 'anchor'}` — see `## Header grammar` in the skill body.
@@ -85,8 +86,20 @@ rules about the columns themselves, not about porting — they live in the skill
   not), and each level is the stepped, non-repainting series — held from the bar that completes the
   pivot's right side, not plotted back on the pivot bar. Break of structure is
   `dist_fractalHi crossesAbove 0` / `dist_fractalLo crossesBelow 0`; "structure is bullish" is
-  `fractalLabel in ["HH","HL"]`. Only two bars each side is native: a `ta.pivothigh(5, 5)` or longer
-  script ports onto the two-bar swing, and the spec-lock question says so.
+  `fractalLabel in ["HH","HL"]`. The pivot each latest one is compared with is native too:
+  `PRIOR_SWING_FRACTAL_HIGH` / `PRIOR_SWING_FRACTAL_LOW` (`pFractalHi` / `pFractalLo`, Pine's
+  `ta.valuewhen(not na(ph), ph, 1)`) are price levels held while the prior pivot is in reach, so
+  `dist_pFractalHi crossesAbove 0` is a close through the swing high before the last one. A pivot's age is
+  `SWING_FRACTAL_HIGH_BARS_AGO` / `SWING_FRACTAL_LOW_BARS_AGO` (`fractalHiAgo` / `fractalLoAgo`), counted
+  from the pivot's own bar: 2 on the bar that completes it, so it reads Pine's
+  `ta.barssince(not na(ph)) + 2`, and `fractalLoAgo lte 5` keeps a setup to a fresh swing low. Only two
+  bars each side is native: a `ta.pivothigh(5, 5)` or longer script ports onto the two-bar swing, and the
+  spec-lock question says so.
+- **Chaikin Money Flow** (TradingView's built-in "Chaikin Money Flow" script, length 20; Pine has no
+  `ta.cmf`) → `CMF20` is native: each bar's volume weighted by where it closed in its range, summed over
+  20 closed bars and divided by their volume, −1 to +1. `CMF20 gt 0` is the accumulation state and
+  `CMF20_cross is "Bullish"` the zero-line cross; a flat bar weighs 0, and a window that traded no volume
+  reads no value, so a clause over it reads FALSE. It reads closed bars only, never the forming one.
 - **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_LOWER`, its basis is `EMA20`), the MACD and PPO lines
@@ -95,7 +108,10 @@ rules about the columns themselves, not about porting — they live in the skill
   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
-  structure (`SWING_FRACTAL_HIGH`/`SWING_FRACTAL_LOW`/`SWING_FRACTAL_LABEL`). Port these directly —
-  do not offer a substitute for a primitive the catalog serves.
+  (`STOCH_RSI14`), the TTM squeeze (`KC_SQUEEZE`), Connors RSI-2 (`RSI2`), the 8/9/21/50 EMAs
+  (`EMA8`/`EMA9`/`EMA21`/`EMA50` — `ta.ema(close, 8)` is `EMA8`, its distance `dist_EMA8`), literal
+  previous-session levels (`PDH`/`PDL`/`PDO`), fractal swing structure
+  (`SWING_FRACTAL_HIGH`/`SWING_FRACTAL_LOW`/`SWING_FRACTAL_LABEL`, the prior pivots
+  `PRIOR_SWING_FRACTAL_HIGH`/`PRIOR_SWING_FRACTAL_LOW` and their ages
+  `SWING_FRACTAL_HIGH_BARS_AGO`/`SWING_FRACTAL_LOW_BARS_AGO`), and Chaikin Money Flow (`CMF20`). Port
+  these directly — do not offer a substitute for a primitive the catalog serves.