@battlegrid/mcp-server 31.2.6 → 31.2.8

package/README.md

@@ -24,7 +24,7 @@ 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 — v37 → v49.5
+## Contract history — v37 → v51
 
 Eleven majors reached authors while this section stopped at v36. That gap is the mechanism, not an
 oversight: since v31 a contract move needs no release here, so nothing forced a note to be written —
@@ -32,11 +32,43 @@ and the documentation ships inside the tarball, so a note written but unpublishe
 Both halves are now closed by a rule keyed to the *served* contract rather than to a release of this
 package.
 
+**50.0.0 and 51.0.0 arrived late, and the reason is worth naming.** The re-vendoring errand that
+used to carry these notes is now a generated export
+(`battlegrid-app/server/scripts/export-mcp-skills.mjs`), and it owns three paths — `skills/`,
+`skills/EXPORT.json`, and the vendored digest. It deliberately does not touch this file. So the
+digest kept arriving on time while the note stopped travelling with it, and this section sat at
+v49.5 against a served contract of 51.0.0. Nothing a client could observe was wrong; what was
+missing was the sentence telling them so. **A contract move still needs a human-authored entry
+here, and the export lane will not remind you.**
+
 ### Accepted again — input that was rejected now compiles
 
 Nothing to migrate. This is the one direction that cannot break a client: a body the server used to
 refuse is now stored. Listed because a client that special-cased the refusal can delete that branch.
 
+- **A signal rule patch no longer forces you to restate `allocation` and `required`** (51.0.0,
+  `fix-signal-rule-patch-semantics`). On `update_strategy_signal_rule`, and on the `rules` element
+  of `compile_strategy_plan`, both fields become optional and join `params` under ONE omission
+  rule: **an omitted mutable field preserves the stored value for that signal.** "Raise this
+  signal's weight" is now expressible.
+
+  ```jsonc
+  { "strategyId": "…", "expectedRevision": 7, "signalId": "volume_surge",
+    "allocation": 3 }               // `required` and `params` keep exactly what is stored
+  ```
+
+  **Every existing client keeps working** — a complete payload is still a valid patch — so this is
+  listed for what you can now STOP sending. Before it, both fields were mandatory on every rule
+  surface, so a caller that had not first read the current rule had to invent a value it was never
+  asked about. That is not hypothetical: revision 5 of a production strategy flipped `required`
+  false → true unasked while moving a weight 2 → 3, turning a scoring signal into a **mandatory
+  gate** — which changes whether the agent takes trades at all.
+
+  One boundary on the newly legal ground, and it breaks nothing: a patch carrying **no** mutable
+  field is refused — *"A rule patch must change something: supply at least one of allocation,
+  required or params."* — rather than minting a no-op revision. Under 50.0.0 that request could not
+  be formed at all, so nothing that used to work is now refused.
+
 - **An arming trigger no longer constrains its required conditions' clock** (49.4.0,
   `restore-arming-trigger-authoring`). `compile_strategy_plan`, `apply_strategy_plan` and
   `fork_strategy` accept a strategy whose entry trigger is `ON_CANDLE_CLOSE`, `STOP_THROUGH_LEVEL`
@@ -55,6 +87,14 @@ refuse is now stored. Listed because a client that special-cased the refusal can
 
 ### Changed meaning, unchanged shape
 
+- **`blocksScanGate` reads `true` for a class it did not** (50.0.0, `own-scan-served-set-once`), on
+  `preview_radar_resolution`. Blocking is now derived from the lane's **served set** rather than
+  switched over the reach reason, so a `FEED`-reason refusal on an operand no reader in the lane
+  serves BLOCKS instead of deferring. No field changes shape, and a client that already renders the
+  key renders the new answer — but a client that treated `blocksScanGate: false` as "this will
+  resolve once data arrives" now sees a deployment that will not fire. Nothing in the payload tells
+  you this moved.
+
 - **Three tools serve different values for identical input** (47.3.0, `derive-scan-fetch-from-report`).
   The radar scan leg now derives its timeframe fetch from the strategy's **report** rather than the
   on-duty agent's three perception rungs, so a required condition addressing an absolute timeframe
@@ -72,6 +112,44 @@ refuse is now stored. Listed because a client that special-cased the refusal can
 
 ### Rejected input — something you author is no longer accepted
 
+- **`update_strategy_signal_rule` requires `confirm: true` when the strategy has bound agents**
+  (51.0.0, `fix-signal-rule-patch-semantics`). The write re-materializes scoring configuration onto
+  every bound agent immediately — including agents holding open USDC positions — and until now
+  nothing on the server asked. A rule edit on a strategy with one or more bound agents is refused
+  without the flag, and the message names the count. An edit on a strategy with **nothing bound is
+  unaffected**, and so is every path through the web editor.
+
+  **Send `confirm: true`.** That is the whole migration, and `confirm` is published on the input
+  schema — but nothing in the schema says WHEN it becomes mandatory, because the condition is the
+  bound-agent count rather than the shape of your body. The refusal rides the existing
+  `VALIDATION_ERROR` code, so a client that omits it discovers the rule at the refusal.
+
+  Why it moved to the server: the guard existed, but only as served prose the calling model could
+  decline — and did, twice in production on 2026-08-24. `archive_strategy` and
+  `rebind_intelligence_agent` have taken a server-enforced `confirm` all along; single-rule tuning
+  was the outlier among its own siblings, and it is the one that writes to scoring.
+
+- **A radar deployment is refused when its strategy reads a session-field scalar** (50.0.0,
+  `own-scan-served-set-once`). `upsert_radar_deployment` refuses a deployment whose slot agents'
+  bound strategy carries a condition reading one of five SESSION-FIELD scalars — `fieldPlayers`,
+  `fieldUpBias`, `fieldBiasDir`, `captConc`, `picksSpread` — with
+  `CONDITION_OPERAND_UNSERVED_IN_LANE`. A body accepted under 49.5.0 is refused under 50.0.0
+  without one byte of it changing.
+
+  **Why a refusal and not a warning.** Those five describe a game SESSION, and radar runs outside a
+  session at BOTH its stages — so such a condition can never resolve there. The deployment formed
+  no fire edge and the agent did nothing on that coin, silently, forever. The refusal converts a
+  permanent silence into an error at the moment you author it.
+
+  **Migrate** by moving the clause to a scalar radar reads — the Market Breadth or Reference Pairs
+  families, which are market-wide reads with no session dimension — or by binding the strategy to
+  an arena agent instead. The error carries both halves: `allowedDomain` enumerates every servable
+  header, and the message names the sections.
+
+  **Strategy authoring is untouched by this bump.** The same strategy is legal, and reads those
+  scalars correctly, on an arena agent — which is why the refusal is on the DEPLOYMENT and not on
+  `compile_strategy_plan` / `apply_strategy_plan`.
+
 - **A benchmark-bound section no longer accepts crowd metrics or rank transforms** (49.0.0,
   `fix-benchmark-legality-save-path`). On a custom section carrying a non-null `benchmarkTicker`, a
   column whose metric is enrichment-stage (the `CROWD_*` family, `FLOW_ALIGN`, `SMART_RETAIL`,
@@ -179,6 +257,22 @@ refuse is now stored. Listed because a client that special-cased the refusal can
 
 ### Reshaped output — the same call returns a different shape
 
+- **`update_strategy_signal_rule` gains its own response envelope** (51.0.0,
+  `fix-signal-rule-patch-semantics`). It no longer shares `{ strategy }` with its siblings. The
+  response is `{ strategy, ruleChanges }`, where `ruleChanges` is the server's own before/after
+  pair for the edited signal — `[{ signalId, before, after }]`, each side a full rule object. It is
+  `null` when the mutation changed no rule, **never `[]`**.
+
+  **Report the change from that pair, not from memory.** The planner always computed the diff and
+  the tool discarded it, so a caller narrating what it just did had only its own recollection of
+  the before-value. One production edit shipped a wrong receipt on top of a wrong write that way,
+  and the write was unreconstructable from the audit trail afterwards.
+
+  Additive, but published on a `.strict()` shape — a decoder pinned to the old two-key object
+  rejects the new key. `fork_strategy`, `archive_strategy` and `restore_strategy` keep the shared
+  `StrategyResponseSchema` and publish exactly what they did; it was deliberately NOT widened for
+  them, so this reshape reaches one tool only.
+
 - **An entry void now names the gate that refused it** (49.5.0,
   `fix-arming-trigger-clock-authority`), on `get_radar_activity_summary`. In the cause rollup, the
   `ENTRY_VOID` group's `gateCode` widens from always-`null` to `QualificationGateCode | null`: a

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.6";
+export declare const PACKAGE_VERSION = "31.2.8";
 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.6';
+export const PACKAGE_VERSION = '31.2.8';
 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.6",
+  "version": "31.2.8",
   "description": "BattleGrid MCP server — play crypto prediction games from AI agents",
   "type": "module",
   "main": "dist/index.js",

package/skills/EXPORT.json

@@ -1,14 +1,17 @@
 {
   "generator": "battlegrid-app/server/scripts/export-mcp-skills.mjs",
-  "contractVersion": "50.0.0",
+  "contractVersion": "51.0.0",
   "files": {
     "battlegrid-agent-management/SKILL.md": "b6ea75b3d838c1dbaaf3984d7e99a11c81686de2c1a1910c35699ee7e70dafa5",
     "battlegrid-arena-play/SKILL.md": "03fa153bf82be18bf5ed01e3ba12e2cd9f99a81b08d903a77b52169e7519a182",
     "battlegrid-market-analysis/SKILL.md": "22fde9c4eac0261c89a8056ab8b20b66fcbe1fd58447fa0ac84fd410b4d134d7",
     "battlegrid-radar-deployment/SKILL.md": "d2a012b154e1e529db19529bd7c3d75d069f4e410d5804add51165f0f0902b2e",
-    "battlegrid-strategy-authoring/SKILL.md": "93680b329c158b353fdc7e1ec9058dfd8ab69904cd7f1ae14cf411870c695bf1",
+    "battlegrid-strategy-authoring/SKILL.md": "6857956221375f45c42bdadbf032f6858f6534f91fa4d733f6f572cb4c53a1ff",
     "battlegrid-strategy-doctor/SKILL.md": "9ab3f79128ec81d3e90167c3f1ea4bd6f6b570290e5ebe2bf855195263c58239",
-    "battlegrid-strategy-examples/SKILL.md": "3e418df3590054b6da75435de79770ebdbdb7b88564534d9050ef209e0476a08",
+    "battlegrid-strategy-examples/SKILL.md": "0d6d9611d10bd7683c9bc5186d3db26f2fd4123a5b57330f827ff45cd9ef82c7",
+    "battlegrid-strategy-examples/references/playbooks.md": "35c543c090d00ba19e4bcf0a80502afac7a4954643fc535de0b24381c91ecbf4",
+    "battlegrid-strategy-examples/references/recipes.md": "53887daece17995543e7d3fe1bf2577fc41a6254c291acacde48d7de63853641",
+    "battlegrid-strategy-examples/references/tradingview-ports.md": "2f84758ba6ec015c7db3cf996f663971a7017eddbebe42d6ecba6386c7b78362",
     "battlegrid-trade-analysis/SKILL.md": "32573a67e55d735e6ee4e36b3b48c815694102704bc453c4d1c13db39551b3da"
   }
 }

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

@@ -223,6 +223,22 @@ with the player:
 - **Tuning a single rule** — how many agents are bound, and that the change reaches every one of
   them immediately.
 
+**Your `ask_user` is the explanation, not the mechanism.** For single-rule tuning the server
+independently requires `confirm:true` whenever the strategy has bound agents, so stating the radius
+and calling anyway is refused, not committed. Send `confirm:true` only on a turn where the player
+made an explicit confirming pick — never because you judged the edit safe. Free text typed while a
+confirmation is open is not consent: answer it, then present the same confirmation again.
+
+**Send only the fields you were asked to change.** `allocation`, `required` and `params` are each
+optional and each preserves on omission. "Raise volume_surge to Critical" is
+`{ signalId, allocation: 3 }` — nothing else. Do not read the current rule merely to restate a value
+you are not changing, and never supply `required` unless the player asked about the Required flag.
+Restating a remembered value is how a scoring signal silently becomes a mandatory trade gate.
+
+**Report the change from the response.** The success payload carries `ruleChanges` with the server's
+own `before` and `after` for the edited signal. State those. Never describe the prior value from
+memory or from an earlier read — the response is the only record that cannot be stale.
+
 ## When apply is refused
 
 Each of these is a specific typed code. Read it and take the cheapest correct step — never retry
@@ -241,6 +257,12 @@ the same call blindly.
   moved, a shifted catalog. The approved plan **survives** these: clear the cause and confirm again
   with the same token while it still lives. Recompiling works too, but costs the player a second
   review they did not need.
+- **A single-rule tuning refused for missing confirmation** — the strategy has bound agents and the
+  server will not write without `confirm:true`. The refusal names the count. Present *that* count to
+  the player and re-issue the identical call only after an explicit confirming pick. **Never add
+  `confirm:true` and retry on your own judgement** — the refusal exists precisely because the
+  decision is not yours, and a retry that supplies it unasked is the defect this rule was written
+  for. Nothing was written, so there is no partial state to reconcile.
 - **`TOKEN_BINDING_MISMATCH` while the token is still fresh** — there is nothing left to mis-copy,
   so this is real drift: a bound agent moved, the catalog changed, or the signing key rotated. Do
   not resubmit. Recompile, re-present, re-confirm.

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

@@ -70,6 +70,18 @@ the keys `get_strategy` returned** for the sections you are keeping. Either way
 one. To section-qualify a duplicated header, read the key from a preview's `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
+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
+nearly every bar, which is a gate that never gates.
+
+**`PDH` and `PDL` are anchored to `1d`.** They are catalogued price levels, so `dist_PDH gte 0`
+composes directly — but bind them `{abs: '1d'}`, which is the only reference the save path accepts on
+them, and read them from any anchor that way. (`distance` still rejects an `offset`, and a clause
+still compares a column against a literal; neither of those shapes is what a previous-day level
+needed.)
+
 ## Conditions
 
 `{ conditionKey, name, definition, verdict, required, exit, clock, closes }` — all eight
@@ -109,6 +121,17 @@ under `clock: "CLOSE"`: a LIVE reading is the forming bar, and an exit fired on
 intrabar exit. Orthogonal to `required` — the two act on disjoint lifecycles, pre-entry versus
 open — so a condition may carry both, either, or neither.
 
+**A state column is not a flip event.** `ST_DIR` 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 needs an event column
+beside it — an `EMA5_13` cross, or a `ST_DIR` trajectory whose `_trend` changes. The same distinction
+applies to every persisting classification: `MAalign`, `ADX_state`, `zone`.
+
+**Name the anchor when a metric is calibrated for one.** `KC_SQUEEZE is "on"` reads *on* about 57% of
+1h crypto bars even at canonical parameters — Bollinger σ is close-to-close while ATR captures
+intrabar range, so σ/ATR runs low here — against about 19% at 15m. It is a selective filter at 15m and
+below and close to useless at 1h. A metric whose selectivity depends on the anchor is stated with the
+anchor, or the author gates on something that admits most bars.
+
 ## Entry
 
 `{ trigger, confirmTf, closes, bandAtrMultiple, levelSource, levelOffsetAtrMultiple,
@@ -218,167 +241,6 @@ BE 0.8R, no trail, timeDecay ON (120/60, 10→40, stale 25) · swing breakout (4
 RR 2, BE 1R, trail 1.2R/giveback 35 · swing trend (4h) 1.0–2.5 ATR, RR 2, BE 1R, trail
 1.5R/giveback 45–55, no timeDecay.
 
-## Playbooks (validated compositions)
-
-*Validated* is a gate, not a claim: every playbook below is compiled against the live catalog by
-`strategy-playbooks.compile.test.ts`, which fails the build if one stops assembling or if a header
-its conditions name stops resolving. Edit a playbook and the gate re-checks it; move the grammar
-underneath one and the gate catches that too.
-
-### 1 · Volatility Compression Breakout — 4h swing
-
-Custom `Squeeze Scan` (no `sectionKey` — this is a CREATE): `BB_WIDTH_PCT value` + `rank lo`, `ADX value`,
-`RVOL value`, `BB_PCT_B value`, `CLOSE_CHANGE value`, `NOTIONAL_VOLUME_1D value`; plus platform
-`includeStructureZones`. (No `includeBollingerBands`: it renders `bbWidthPct` and
-`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`). Rules:
-`bollinger_squeeze` 3 required · `volume_surge` 2 required `{"multiplier":1.5}` ·
-`volatility_atr_expanding` 2 · `sr_resistance_break` 2 · `sr_support_break` 2 ·
-`bollinger_upper_touch` 1 · `bollinger_lower_touch` 1 · `trend_adx_ranging` 1. Gates
-0.55 / 2 / 0.8. Levels 0.75–1.75 ATR, RR 2. 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}."
-
-### 2 · Crowded-Positioning Fade — 1h intraday
-
-Custom `Positioning`: `FUNDING_RATE value`→`rate`, `aggregate w24`→`rate_mean24`,
-`FUNDING_ANN value`→`ann`, `OI_CHG value`→`oiChg`, `OI_PX_REGIME value`→`oiRegime` (vocab:
-new longs / new shorts / short covering / long liquidation), `MARK spread ORACLE`→
-`mark_oracle_spread`, `RSI14 value`, `CHG_24H value`→`chg24h`; plus `includeCvd`. Conditions:
-`NO_LIQUIDATION_TAPE` required NOT-veto (`NOT [oiRegime is "long liquidation"]`);
-`CROWDED_LONGS` building block (`ann gte 25` + `oiChg gte 3` + `oiRegime is "new longs"`);
-`FADE_SHORT` verdict DOWN (ref + `RSI14 gte 65` + `chg24h gte 5`); mirrored `SQUEEZED_SHORTS`
-/ `SQUEEZE_LONG` verdict UP. Rules: `funding_extreme_positive`/`_negative` 3 required
-`{"thresholdPct":0.001}` · `oi_surge` 2 `{"thresholdPct":0.03}` · `rsi_overbought` 2
-`{"threshold":65}` · `rsi_oversold` 2 `{"threshold":35}` · `cvd_bear_divergence` 2 ·
-`cvd_bull_divergence` 2 · `mfi_overbought` 1 · `mfi_oversold` 1. Gates 0.6 / 1 / 0.5. Levels
-1.0–2.5 ATR, RR 1.5. PM: BE 0.8R, no trail, timeDecay ON (120/60, 10→40, stale 25).
-
-### 3 · Relative-Strength Rotation with a Benchmark Gate — 4h cross-sectional
-
-Custom `Leadership`: `ROC12 rank hi` + `rank lo`, `RVOL rank hi`,
-`EMA5 spread EMA13 × trajectory w4`, `NOTIONAL_VOLUME_1D value`. **Rank `ROC12`, not
-`CLOSE_CHANGE`:** `closeChg` is the one magnitude-only rankable code, so `hi`/`lo` on it are
-refused, and its legal `far` ordering sorts by |change| — which would put the session's biggest
-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` +
-`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]`). Rules:
-`comparison_sector_momentum` 3 · `rel_roc_positive`/`_negative` 2 · `ma_ema_aligned_bull`/
-`_bear` 2 required · `rel_ppo_bull_cross`/`_bear_cross` 1 · `volume_surge` 1. Gates
-0.5 / 1 / 0.6. Levels 1–2 ATR, RR 1.8. PM: BE 1R; trail 1R giveback 45. Ranked cohort ≥ 40 —
-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
-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**
-`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). Rules:
-`mtf_pullback_long`/`_short` 3 required · `htf_ma_aligned_bull`/`_bear` 2 required ·
-`htf_trend_adx_trending` 2 · `ma_ema_aligned_bull`/`_bear` 1 · `rsi_oversold` 1
-`{"threshold":40}`. Gates 0.6 / 2 / 0.7 (a pullback signal AND an HTF alignment). Levels
-1–2.5 ATR, RR 2. PM: BE 1R; trail 1.5R giveback 30 buffer 0.3.
-
-### 5 · Perp/Spot Flow Divergence at Structure — 15m scalp
-
-Platform `includePerpSpotFlow` (`perpSpotFlow` vocab: confirmed_bull / confirmed_bear /
-perp_led_fragile / spot_led_accumulation / neutral), `includeStructureZones`
-(`zones_htf_support_dist` signed %, support below price is negative; `_age_h`), custom `Tape`
-(`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 -2 0` + `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`
-(quorum beats a brittle ALL); `FRAGILE_POP` verdict DOWN (`perp_led_fragile` +
-`zones_htf_resist_dist between 0 2` + `RVOL gte 1.3`). Rules:
-`flow_perp_spot_bull_divergence`/`_bear_divergence` 3 required · `cvd_bull_divergence`/
-`_bear_divergence` 2 · `sr_at_support`/`_at_resistance` 2 · `structure_ob_approach` 1 ·
-`volume_surge` 1. Gates 0.55 / 1 / 0.4. Levels 0.5–1.2 ATR, RR 1.5. PM: BE 0.7R; trail 0.9R
-giveback 30 buffer 0.15; timeDecay ON aggressive (45/15, 15→60, stale 30).
-
-## TradingView ports — familiar processes, studio vocabulary
-
-Players often ask for strategies by the name of a popular TradingView script. Port the
-**process** (regime filter → setup state → trigger → stop engine), and where the catalog lacks
-the primitive, name the substitution in the spec-lock question — never present a substitute as
-the thing itself. Most TV strategies run on the daily chart: carry that with the
-daily-strategy pattern above (pinned-1d thesis at `offset: 1` on an intraday anchor), which
-binds decisions to daily closes while the studio keeps managing risk intraday. Event columns (`MACD_cross`, `EMA5_13`: Bullish/Bearish) print only on the
-crossing bar and are otherwise null → UNRESOLVED; use them as triggers inside a carrier and
-pair with a persistent state (spread sign, `MAalign`) for regime — as the source scripts do.
-
-- **Squeeze Momentum [LazyBear] / TTM Squeeze** → `KC_SQUEEZE is "on"` is the native one-condition
-  read: the Bollinger pair sitting inside the Keltner channel, at the script's own multiplier.
-  The four boundaries stay addressable, so `BB_UPPER spread KC_UPPER` and
-  `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.
-  **Name the anchor when you port it:** on crypto the squeeze reads *on* about 57% of 1h bars even
-  at canonical parameters — σ/ATR runs low here because Bollinger σ is close-to-close while ATR
-  captures intrabar range — against about 19% at 15m. It is a selective filter at 15m and below,
-  not at 1h. (`bbWidthPct_rank_lo` + `ADX 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
-  distance to the plotted stop. The plotted trailing line is still best executed by the studio's
-  own stop engine — `trailingTriggerR: 0` (trail from entry), giveback ~30–40 (tight factor) or
-  45–55 (loose/chandelier) — because a trailing stop is a position-management mechanism, not a
-  column. **`ST_DIR` is a persisting state, not a flip event**: it reads the same on every bar of
-  a trend, so the FLIP still needs an event column beside it (`EMA5_13` cross, or a `ST_DIR`
-  trajectory whose `_trend` changes). Name that as a substitution.
-- **MACD + 200 MA filter** → `ABOVE_200` building block (`dist_SMA200 gt 0`) referenced by a
-  carrier with `MACD_cross is "Bullish"`; rules `macd_bull/bear_cross` 3 required +
-  `ma_sma200_above/below` 2 required; 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
-  the `(timeframe, scope)` pairs a condition names; position-persona geometry. `SMA50 × SMA200` is
-  the canonical definition and stays the default port; `EMA50` is available as the crypto variant
-  when a player asks for it by name.
-- **RSI-2 (Connors)** → `RSI2` is native, so this ports exactly: `RSI2 lte 10` gated by required
-  `ABOVE_200`; the source's fast exit is time — timeDecay ON (180/60, 15→50, stale 20);
-  `rsi_oversold` 3 required with a tuned threshold. Keep the literal `lte 10` as the GATE:
-  `RSI2 × classifyZone` exists and reads on the same Connors bands, but a zone label is a fixed
-  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 +
-  aggressive timeDecay (VWAP anchors daily at 00:00 UTC).
-- **Donchian / Turtle breakout** → `zone is "breakout high"` + `dist_swingHi gte 0` +
-  `RVOL gte 1.5`; `sr_resistance_break` 3 required; turtle exits = trend preset (trail from
-  1R, giveback 50). Mirror with `"breakdown low"`. **Daily-breakout variant on any anchor:**
-  pin the structure at 1d — `zone_1d is "breakout high"`, `dist_swingHi_1d gte 0` (validated).
-  **Literal previous-day levels are native**: `PDH` and `PDL` are catalogued price levels, so
-  `dist_PDH gte 0` composes directly. They are ANCHORED to `1d` — bind `{abs: '1d'}`, which is the
-  only reference the save path accepts on them, and read them from any anchor that way. `distance`
-  still rejects an `offset` and a clause still compares a column against a literal; neither of
-  those shapes is what a previous-day level needed.
-- **ICT / SMC (FVG + order blocks)** → `STRUCT_ZONES` is the native zone engine:
-  `zones_htf_support_type` (`bullish FVG`/`bullish order block`), `zones_htf_support_dist
-  between -1.5 0`, `_age_h gte 12`, HTF bias required via `MAalign_htf`; rules
-  `structure_fvg_approach`/`structure_ob_approach` required (their `proximityPct` is the
-  in-zone dial). Liquidity sweeps, displacement, killzones and event *sequencing* are shapes the
-  grammar does not have — a clause compares one column against a literal, so an ordered sequence
-  of events cannot be stated at all. That is a grammar limit, not a missing metric; name it as
-  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_MID`/`KC_LOWER`), 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`), and literal previous-day levels (`PDH`/`PDL`). Port these directly —
-  do not offer a substitute for a primitive the catalog serves.
-
 ## Not expressible — the catalog keys this needs
 
 The one place a claim that the catalog LACKS something may live, and every row names the key it
@@ -390,12 +252,19 @@ permanent. A claim that a metric is absent belongs here, or nowhere.
 |---|---|---|
 | 100-period SMA | `SMA100` | the shipped 50- or 200-period simple average, whichever the thesis leans on |
 
-## Using a playbook
+## Where the worked material lives
+
+This skill's body is the contract — the axes, the header grammar, how conditions and weights behave,
+and the absence section above. The worked material is disclosed on demand, so it costs nothing until
+you ask for it. Read a reference with `read_skill_reference` when you reach the work it covers:
+
+- **`references/recipes.md`** — copy-adaptable column objects and condition fragments: cross
+  detection, board-relative ranks, cross-venue basis, crowd positioning, coin selection, and the
+  discovery fields worth reading before you compose.
+- **`references/playbooks.md`** — five validated desk-grade compositions end to end, and how to
+  adapt one rather than copy it.
+- **`references/tradingview-ports.md`** — per-script port recipes for the popular TradingView
+  strategies, each naming its substitutions where the catalog lacks a primitive.
 
-Discover → confirm headers (`get_strategy_column_contract`, or one `preview_strategy_report`
-whose `conditionColumns` lists every addressable header with operators and vocabulary) →
-calibrate literals against the previewed live values → compile once → review the compiled
-scorecard, condition outcomes, verdict tally, and `marketReadMarkers` (fix `unknown` /
-`ambiguous` markers) → apply per the strategy-authoring flow. Coin selection is call context,
-not strategy state: explicit tickers for focused work, `ranked` (with an optional category) for
-scanning books.
+Every rule about how a column *behaves* is in this body, not in a reference. If a reference seems to
+state one, the body is the authority.

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

@@ -0,0 +1,110 @@
+# Playbooks — validated desk-grade compositions
+
+Worked compositions for the strategy studio, each validated against the live grammar. Shapes are
+binding; the tokens are illustrations and stay live-discovered.
+
+**Contents**
+- Playbooks (validated compositions)
+- Using a playbook
+
+Read `## Header grammar` and `## Conditions` in the skill body first — the rules about how columns
+behave live there, not here.
+
+## Playbooks (validated compositions)
+
+*Validated* is a gate, not a claim: every playbook below is compiled against the live catalog by
+`strategy-playbooks.compile.test.ts`, which fails the build if one stops assembling or if a header
+its conditions name stops resolving. Edit a playbook and the gate re-checks it; move the grammar
+underneath one and the gate catches that too.
+
+### 1 · Volatility Compression Breakout — 4h swing
+
+Custom `Squeeze Scan` (no `sectionKey` — this is a CREATE): `BB_WIDTH_PCT value` + `rank lo`, `ADX value`,
+`RVOL value`, `BB_PCT_B value`, `CLOSE_CHANGE value`, `NOTIONAL_VOLUME_1D value`; plus platform
+`includeStructureZones`. (No `includeBollingerBands`: it renders `bbWidthPct` and
+`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`). Rules:
+`bollinger_squeeze` 3 required · `volume_surge` 2 required `{"multiplier":1.5}` ·
+`volatility_atr_expanding` 2 · `sr_resistance_break` 2 · `sr_support_break` 2 ·
+`bollinger_upper_touch` 1 · `bollinger_lower_touch` 1 · `trend_adx_ranging` 1. Gates
+0.55 / 2 / 0.8. Levels 0.75–1.75 ATR, RR 2. 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}."
+
+### 2 · Crowded-Positioning Fade — 1h intraday
+
+Custom `Positioning`: `FUNDING_RATE value`→`rate`, `aggregate w24`→`rate_mean24`,
+`FUNDING_ANN value`→`ann`, `OI_CHG value`→`oiChg`, `OI_PX_REGIME value`→`oiRegime` (vocab:
+new longs / new shorts / short covering / long liquidation), `MARK spread ORACLE`→
+`mark_oracle_spread`, `RSI14 value`, `CHG_24H value`→`chg24h`; plus `includeCvd`. Conditions:
+`NO_LIQUIDATION_TAPE` required NOT-veto (`NOT [oiRegime is "long liquidation"]`);
+`CROWDED_LONGS` building block (`ann gte 25` + `oiChg gte 3` + `oiRegime is "new longs"`);
+`FADE_SHORT` verdict DOWN (ref + `RSI14 gte 65` + `chg24h gte 5`); mirrored `SQUEEZED_SHORTS`
+/ `SQUEEZE_LONG` verdict UP. Rules: `funding_extreme_positive`/`_negative` 3 required
+`{"thresholdPct":0.001}` · `oi_surge` 2 `{"thresholdPct":0.03}` · `rsi_overbought` 2
+`{"threshold":65}` · `rsi_oversold` 2 `{"threshold":35}` · `cvd_bear_divergence` 2 ·
+`cvd_bull_divergence` 2 · `mfi_overbought` 1 · `mfi_oversold` 1. Gates 0.6 / 1 / 0.5. Levels
+1.0–2.5 ATR, RR 1.5. PM: BE 0.8R, no trail, timeDecay ON (120/60, 10→40, stale 25).
+
+### 3 · Relative-Strength Rotation with a Benchmark Gate — 4h cross-sectional
+
+Custom `Leadership`: `ROC12 rank hi` + `rank lo`, `RVOL rank hi`,
+`EMA5 spread EMA13 × trajectory w4`, `NOTIONAL_VOLUME_1D value`. **Rank `ROC12`, not
+`CLOSE_CHANGE`:** `closeChg` is the one magnitude-only rankable code, so `hi`/`lo` on it are
+refused, and its legal `far` ordering sorts by |change| — which would put the session's biggest
+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` +
+`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]`). Rules:
+`comparison_sector_momentum` 3 · `rel_roc_positive`/`_negative` 2 · `ma_ema_aligned_bull`/
+`_bear` 2 required · `rel_ppo_bull_cross`/`_bear_cross` 1 · `volume_surge` 1. Gates
+0.5 / 1 / 0.6. Levels 1–2 ATR, RR 1.8. PM: BE 1R; trail 1R giveback 45. Ranked cohort ≥ 40 —
+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
+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**
+`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). Rules:
+`mtf_pullback_long`/`_short` 3 required · `htf_ma_aligned_bull`/`_bear` 2 required ·
+`htf_trend_adx_trending` 2 · `ma_ema_aligned_bull`/`_bear` 1 · `rsi_oversold` 1
+`{"threshold":40}`. Gates 0.6 / 2 / 0.7 (a pullback signal AND an HTF alignment). Levels
+1–2.5 ATR, RR 2. PM: BE 1R; trail 1.5R giveback 30 buffer 0.3.
+
+### 5 · Perp/Spot Flow Divergence at Structure — 15m scalp
+
+Platform `includePerpSpotFlow` (`perpSpotFlow` vocab: confirmed_bull / confirmed_bear /
+perp_led_fragile / spot_led_accumulation / neutral), `includeStructureZones`
+(`zones_htf_support_dist` signed %, support below price is negative; `_age_h`), custom `Tape`
+(`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 -2 0` + `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`
+(quorum beats a brittle ALL); `FRAGILE_POP` verdict DOWN (`perp_led_fragile` +
+`zones_htf_resist_dist between 0 2` + `RVOL gte 1.3`). Rules:
+`flow_perp_spot_bull_divergence`/`_bear_divergence` 3 required · `cvd_bull_divergence`/
+`_bear_divergence` 2 · `sr_at_support`/`_at_resistance` 2 · `structure_ob_approach` 1 ·
+`volume_surge` 1. Gates 0.55 / 1 / 0.4. Levels 0.5–1.2 ATR, RR 1.5. PM: BE 0.7R; trail 0.9R
+giveback 30 buffer 0.15; timeDecay ON aggressive (45/15, 15→60, stale 30).
+
+## Using a playbook
+
+Discover → confirm headers (`get_strategy_column_contract`, or one `preview_strategy_report`
+whose `conditionColumns` lists every addressable header with operators and vocabulary) →
+calibrate literals against the previewed live values → compile once → review the compiled
+scorecard, condition outcomes, verdict tally, and `marketReadMarkers` (fix `unknown` /
+`ambiguous` markers) → apply per the strategy-authoring flow. Coin selection is call context,
+not strategy state: explicit tickers for focused work, `ranked` (with an optional category) for
+scanning books.

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

@@ -0,0 +1,118 @@
+# Recipes — copy-adaptable fragments
+
+Column objects for a custom section's `columns[]`, condition fragments for `conditions[]`, and the
+coin-selection and discovery shapes an author reaches for while writing a payload.
+
+**Shapes are binding. Tokens are illustrations** — re-discover every metric, transform and parameter
+against the live tools (`list_strategy_categories`, `list_strategy_vocabulary`,
+`get_metric_construction_hints`, `get_strategy_column_contract`) before compiling. A recipe is a
+worked shape, never a substitute for discovery.
+
+Read `## Header grammar` and `## Conditions` in the skill body first: how a column's header is
+generated, how event columns resolve, what `{abs: …}` binds, and which classifications are states
+rather than events all live there. This document assumes them.
+
+**Contents**
+- Column recipes
+- Cross detection
+- Board-relative rank recipes
+- Cross-venue and perp/spot basis
+- Crowd positioning
+- Coin selection
+- Discovery fields worth reading
+
+## Column recipes
+
+| Intent | Column | Header it generates |
+|---|---|---|
+| Live traded price | `{ "metric": "LAST", "transformId": "value", "timeframe": { "rel": "anchor" } }` | `last` |
+| Momentum build-up | `{ "metric": "RSI14", "transformId": "trajectory", "timeframe": { "rel": "anchor" }, "window": 4 }` | `RSI14_t3…_now`, `RSI14_trend` |
+| Closed-bar-only trajectory | add `"bars": "closed"` to any trajectory | same, drawn from closed bars |
+| Extension from trend | `{ "metric": "SMA50", "transformId": "distance", "timeframe": { "rel": "anchor" } }` | `dist_SMA50` (signed %) |
+| Funding paid over a day | `{ "metric": "FUNDING_RATE", "transformId": "aggregate", "timeframe": { "rel": "anchor" }, "window": 24 }` | `rate_mean24` |
+| Chop filter on the entry rung | `{ "metric": "CLOSE", "transformId": "efficiency", "timeframe": { "rel": "lower" }, "window": 5, "bars": "closed" }` | `close_ltf_er` (≥0.6 directional) |
+| One-bar volume concentration | `{ "metric": "VOLUME", "transformId": "maxShare", "timeframe": { "rel": "lower" }, "window": 4, "bars": "closed" }` | `volBase_ltf_maxShare` |
+| Room to structure | `{ "metric": "STRUCT_ZONES", "transformId": "nearestZoneDist", "timeframe": { "rel": "regime" }, "side": "resistance" }` | `zones_htf_resist_dist` |
+| Last **closed** daily read | `{ "metric": "RSI14", "transformId": "value", "timeframe": { "abs": "1d" }, "offset": 1 }` | `RSI14_1d` — `RSI14[t - 1]` |
+
+## Cross detection
+
+`crossDetect` is the transform that turns a pair into an EVENT column — it prints on the crossing bar
+and is null otherwise:
+
+```json
+{ "metric": "MACD", "transformId": "crossDetect", "timeframe": { "rel": "anchor" } }
+```
+
+An event column is a trigger inside a carrier, never a standing state; pair it with a persistent
+state for regime. The skill body's `## Header grammar` states that rule and is the authority on it —
+a condition that reads a `crossDetect` column as a state is UNRESOLVED on nearly every bar.
+
+## Board-relative rank recipes
+
+`rank` turns any column into an ordinal across the scanned board. Ordering semantics: `hi` most
+positive, `lo` most negative, `far`/`near` by magnitude (offered only where sign matters), and
+`lte N` reads as "top N".
+
+| Intent | Column | Header |
+|---|---|---|
+| Most volatile on the board | `{ "metric": "ATR_PCT", "transformId": "rank", "timeframe": { "rel": "anchor" }, "ordering": "hi" }` | `atrPct_rank_hi` (1 = most volatile) |
+| Biggest movers, sign-agnostic | `{ "metric": "CLOSE_CHANGE", "transformId": "rank", "timeframe": { "rel": "anchor" }, "ordering": "far" }` | `closeChg_rank_far` |
+| Most extended from VWAP | `{ "metric": "VWAP", "transformId": "distance", "chainedTransformId": "rank", "timeframe": { "rel": "anchor" }, "ordering": "far" }` | `dist_VWAP_rank_far` |
+
+Confirm every rank ordering against `get_metric_construction_hints({ metric }).rankOrderings` — it is
+present only where rank is composable on that metric, and is already range-gated server-side. Read
+the offered set; never derive one from the metric's native output.
+
+## Cross-venue and perp/spot basis
+
+| Intent | Column | Header |
+|---|---|---|
+| Perp premium to oracle | `{ "metric": "MARK", "transformId": "spread", "timeframe": { "rel": "anchor" }, "inputs": [{ "metric": "ORACLE" }] }` | `mark_oracle_spread` |
+| Basis to Binance spot | `{ "metric": "MARK", "transformId": "spread", "timeframe": { "rel": "anchor" }, "inputs": [{ "metric": "SPOT_CLOSE_BN" }] }` | `mark_bnClose_spread` |
+| Basis to Coinbase spot | same with `{ "metric": "SPOT_CLOSE_CB" }` | `mark_cbClose_spread` |
+
+A positive basis that is widening while price stalls is perp-led; the flow playbooks use it as the
+fragility read.
+
+## Crowd positioning
+
+`CROWD_UPBIAS` is the platform's own crowd read — the share of recent settled sessions predicting UP,
+as a percentage:
+
+```json
+{ "metric": "CROWD_UPBIAS", "transformId": "value", "timeframe": { "rel": "anchor" } }
+```
+
+Header `upBias`. It is a fade input, not a trend input: it says what the board expects, which is the
+thing a crowded-positioning playbook trades against.
+
+## Coin selection
+
+`coinSelection` is required on every compile and is discriminated on `mode`:
+
+```json
+{ "mode": "ranked", "limit": 25, "category": "DEFI" }
+{ "mode": "explicit", "tickers": ["BTC", "ETH", "SOL"] }
+```
+
+`ranked` is top-N by 24h volume with an optional sector filter; `explicit` names a ticker set
+validated against the active universe. The sector vocabulary is
+`ALL` / `CRYPTO` / `L1` / `MEMES` / `DEFI` / `TRADFI` / `STOCKS` / `INDICES` / `COMMODITIES` —
+discover the live set rather than assuming this list has not moved. An explicit set is capped; the
+refusal names the cap.
+
+## Discovery fields worth reading
+
+Two answers are frequently fetched and then left unread, and each has cost a refusal that a
+single already-served field would have prevented:
+
+- `get_strategy_column_contract({ column }).outputs[].conditionOperators` — an empty array means that
+  rendered header has no comparison semantics and **cannot appear in a condition clause at all**.
+  Legality is per rendered header, not per column: a trajectory's slot header and its `_trend` header
+  answer differently.
+- `get_metric_construction_hints({ metric }).rankOrderings` and `.qualifiedForms` — the composable
+  rank orderings, and the section-qualified forms available when a header is duplicated report-wide.
+- `get_trading_config_catalog()` carries the platform defaults an omitted dial inherits, including
+  `defaultMaxEntryDeviationAtrMultiple` — the band an entry is still admitted within. Read it before
+  authoring an entry band, rather than restating a number the platform already owns.

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

@@ -0,0 +1,83 @@
+# TradingView ports — familiar processes in studio vocabulary
+
+Per-script port recipes. Each ports the PROCESS (regime filter -> setup state -> trigger -> stop
+engine) and names its substitutions where the catalog lacks a primitive.
+
+**Contents**
+- Squeeze Momentum [LazyBear] / TTM Squeeze
+- Supertrend / UT Bot / Chandelier Exit
+- MACD + 200 MA filter
+- Golden / Death Cross
+- RSI-2 (Connors)
+- VWAP reversion
+- Donchian / Turtle breakout
+- ICT / SMC (FVG + order blocks)
+- Now native, formerly substituted
+
+## TradingView ports — familiar processes, studio vocabulary
+
+Players often ask for strategies by the name of a popular TradingView script. Port the
+**process** (regime filter → setup state → trigger → stop engine), and where the catalog lacks
+the primitive, name the substitution in the spec-lock question — never present a substitute as
+the thing itself. Most TV strategies run on the daily chart: carry that with the
+daily-strategy pattern above (pinned-1d thesis at `offset: 1` on an intraday anchor), which
+binds decisions to daily closes while the studio keeps managing risk intraday.
+
+Event-column behaviour, state-vs-event, `PDH`/`PDL` binding and the squeeze's anchor calibration are
+rules about the columns themselves, not about porting — they live in the skill body's
+`## Header grammar` and `## Conditions`. Read those first; this document is the per-script recipes.
+
+- **Squeeze Momentum [LazyBear] / TTM Squeeze** → `KC_SQUEEZE is "on"` is the native one-condition
+  read: the Bollinger pair sitting inside the Keltner channel, at the script's own multiplier.
+  The four boundaries stay addressable, so `BB_UPPER spread KC_UPPER` and
+  `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
+  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
+  distance to the plotted stop. The plotted trailing line is still best executed by the studio's
+  own stop engine — `trailingTriggerR: 0` (trail from entry), giveback ~30–40 (tight factor) or
+  45–55 (loose/chandelier) — because a trailing stop is a position-management mechanism, not a
+  column. `ST_DIR` is a persisting state and not a flip event — see `## Conditions` in the
+  skill body — so the FLIP needs an event column beside it. Name that as a substitution.
+- **MACD + 200 MA filter** → `ABOVE_200` building block (`dist_SMA200 gt 0`) referenced by a
+  carrier with `MACD_cross is "Bullish"`; rules `macd_bull/bear_cross` 3 required +
+  `ma_sma200_above/below` 2 required; 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
+  the `(timeframe, scope)` pairs a condition names; position-persona geometry. `SMA50 × SMA200` is
+  the canonical definition and stays the default port; `EMA50` is available as the crypto variant
+  when a player asks for it by name.
+- **RSI-2 (Connors)** → `RSI2` is native, so this ports exactly: `RSI2 lte 10` gated by required
+  `ABOVE_200`; the source's fast exit is time — timeDecay ON (180/60, 15→50, stale 20);
+  `rsi_oversold` 3 required with a tuned threshold. Keep the literal `lte 10` as the GATE:
+  `RSI2 × classifyZone` exists and reads on the same Connors bands, but a zone label is a fixed
+  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 +
+  aggressive timeDecay (VWAP anchors daily at 00:00 UTC).
+- **Donchian / Turtle breakout** → `zone is "breakout high"` + `dist_swingHi gte 0` +
+  `RVOL gte 1.5`; `sr_resistance_break` 3 required; turtle exits = trend preset (trail from
+  1R, giveback 50). Mirror with `"breakdown low"`. **Daily-breakout variant on any anchor:**
+  pin the structure at 1d — `zone_1d is "breakout high"`, `dist_swingHi_1d gte 0` (validated).
+  **Literal previous-day levels are native**: `dist_PDH gte 0` composes directly. Their `{abs: '1d'}`
+  binding is stated in `## Header grammar` in the skill body.
+- **ICT / SMC (FVG + order blocks)** → `STRUCT_ZONES` is the native zone engine:
+  `zones_htf_support_type` (`bullish FVG`/`bullish order block`), `zones_htf_support_dist
+  between -1.5 0`, `_age_h gte 12`, HTF bias required via `MAalign_htf`; rules
+  `structure_fvg_approach`/`structure_ob_approach` required (their `proximityPct` is the
+  in-zone dial). Liquidity sweeps, displacement, killzones and event *sequencing* are shapes the
+  grammar does not have — a clause compares one column against a literal, so an ordered sequence
+  of events cannot be stated at all. That is a grammar limit, not a missing metric; name it as
+  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_MID`/`KC_LOWER`), 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`), and literal previous-day levels (`PDH`/`PDL`). Port these directly —
+  do not offer a substitute for a primitive the catalog serves.