@battlegrid/mcp-server 31.0.3 → 31.1.5

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

@@ -0,0 +1,254 @@
+---
+name: battlegrid-strategy-studio
+description: Author full-power BattleGrid trading strategies over MCP — multi-section reports, benchmark sections, layered conditions with verdicts and enforcement gates, tiered signal weights, routing gates, ATR trade levels, and post-entry position management. Use whenever building or upgrading a strategy so it uses the whole studio, not a bare template. Companion to the `battlegrid` skill, which owns connection and the compile → review → apply workflow.
+---
+
+# BattleGrid Strategy Studio — full-power authoring
+
+A default strategy — a few platform sections, no conditions, untouched weights — wastes the
+studio. This skill teaches every axis the strategy aggregate owns and how professional desks
+compose them. Workflow, envelopes, and error recovery live in the `battlegrid` skill; this one
+is about *what to author*.
+
+**Ground rule: shapes here are binding, tokens are illustrative.** Every metric code, signal id,
+header, and bound in this skill was validated against the live server, but the server's
+vocabulary moves with deployments. Before compiling, re-discover (`list_strategy_categories` →
+`list_strategy_vocabulary` → `get_metric_construction_hints` → `get_strategy_column_contract`,
+`list_strategy_signals` → `get_strategy_signal_definition`) and prefer what discovery returns
+over anything printed here.
+
+## What a strategy owns (author all of it, deliberately)
+
+| Axis | Fields | What it does |
+|---|---|---|
+| Identity | `name` ≤50, `tagline` ≤80, `description` ≤500 | How agents and humans find it |
+| Timeframe | `timeframe` (from discovery's enabled list) | Anchor rung; cadence persona and regime rung derive from it |
+| Report | `sections[]` — platform + custom columns | The per-coin table the agent LLM actually reads |
+| Conditions | `conditions[]` — typed boolean trees | Deterministic verdicts (UP/DOWN/NEITHER) + hard enforcement gates |
+| Signal rules | `rules[]` — `{signalId, allocation 0–3, required, params?}` | What scores, how much it counts, what must fire |
+| Routing gates | `minAggregateScore` 0–1, `minRequiredCount` 0–20, `minAtrPct` | Whether a scored setup may route to a trade |
+| Trade levels | `minStopLossAtrMultiple` < `maxStopLossAtrMultiple`, `minRiskRewardRatio` | Where stops/targets may sit |
+| Position management | breakEven / trailing / timeDecay dials | How the stop moves after entry |
+| Market Read | `marketReadText` ≤2000 with `{...}` markers | Standing orders rendered with live values |
+
+A compile also always carries `intentSummary`, `assumptions[]`, and `coinSelection` — call
+context, not strategy state (see the `battlegrid` skill).
+
+## The full-power checklist
+
+Before compiling a CREATE, confirm all six; a "no" is a decision, not an omission:
+
+1. Report has at least one **custom section** whose columns encode the thesis (not only platform
+   modules), and every column earns its tokens.
+2. **Conditions** encode the entry logic deterministically — building blocks + verdict carriers —
+   and at least one `required: true` condition guards spend on obvious disqualifiers.
+3. **Every signal you want scoring is named in `rules`** with a deliberate tier; signals you do
+   not name keep server defaults (typically Off). Verify in the compiled scorecard, never assume.
+4. **Gates** are set against the weight budget you chose (see scoring math below).
+5. **Trade levels + position management** match the setup's geometry and holding period.
+6. `marketReadText` states the standing orders with markers so the agent sees live values inline.
+
+## Report grammar — sections and columns
+
+A custom column is `metric × transform (± chained transform) × timeframe ref (± params)`.
+Headers are **system-generated, never named by you**. Validated affix patterns:
+
+| Transform | Header shape | Example (validated) |
+|---|---|---|
+| `value` | `<code>` | `bbWidthPct`, `RVOL`, `rate` |
+| `trajectory` (window 4) | `<code>_t3 … _t1`, `<code>_now`, `<code>_trend` (rising/falling/flat) | `RSI14_now`, `RSI14_trend` |
+| `distance` (price → level) | `dist_<code>` (signed %) | `dist_SMA50` |
+| `spread` (base vs operand) | `<base>_<operand>_spread` | `mark_oracle_spread`, `EMA5_EMA13_spread` |
+| `aggregate` (window N) | `<code>_mean<N>` | `rate_mean24` |
+| `rank` (ordering hi/lo/far/near) | `<code>_rank_<ordering>` — ordinal, 1 = best; compare with `lte N` for top-N | `bbWidthPct_rank_lo`, `closeChg_rank_far` |
+| `efficiency` (window N) | `<code>_er` (0–1; 1 = straight move, ~0 = chop) | `close_ltf_er` |
+| `maxShare` (window N) | `<code>_maxShare` (0–1 concentration) | `volBase_ltf_maxShare` |
+| `classifyZone` / `classifyState` | `<code>_zone` / `<code>_state` | `RSI14_zone` (overbought/oversold/neutral), `ADX_state` (weak/developing/trending/extreme) |
+
+Non-anchor rungs add a rung affix: `_ltf` (lower) / `_htf` (regime), e.g. `MAalign_htf`,
+`zones_htf_support_dist`. Chains are bounded at two: inner `distance`/`spread` → outer
+`trajectory`/`aggregate`/`efficiency`/`maxShare`/`rank` (e.g. EMA5 `spread` EMA13 ×
+`trajectory` → `EMA5_EMA13_spread_now` + `_trend`). Read exact headers from
+`get_strategy_column_contract` or a `preview_strategy_report`'s `conditionColumns` before
+writing conditions against them.
+
+**Timeframe references — two families.** *Relative* (`{rel: "anchor" | "lower" | "regime"}`)
+re-resolve when the strategy timeframe changes; `regime` is the anchor's ladder successor (a 4h
+anchor's regime rung is 1d today). *Pinned* (`{abs: "<tf>"}`) is fixed and ignores anchor
+retunes; its legal set is discovery's `rankedTimeframes` — a **superset** of the authorable
+anchor set (`timeframes`), so `{abs: "1d"}` is valid while `1d` is not an anchor. Pinned
+headers suffix the literal: `RSI14_1d`, `dist_SMA200_1d`, `MAalign_1d` (validated). `offset: 1`
+on a pinned `value` column reads the **last closed** bar of that timeframe — the deterministic
+daily-close read; offset does not change the header, so one section carries one offset per
+`metric × timeframe`. This is how higher-timeframe theses (daily-chart strategies included)
+are authored on an intraday anchor — see the daily pattern in `references/tradingview-ports.md`.
+
+**Benchmark sections** (`benchmarkTicker: "BTC"` on a custom section) read the *benchmark's*
+values instead of the evaluated coin's — the standard way to gate a whole book on market-leader
+regime. `benchmarkTicker` is required-nullable on every custom section: send `null` for an
+ordinary section, never omit it.
+
+A bound section takes **indicator** columns only. Crowd/session metrics (the `CROWD_*` family,
+`FLOW_ALIGN`, `SMART_RETAIL`, `CAPTAIN_CONF`, `CONFIDENCE`, `SETTLED_AT`, `PERP_SPOT_*`) and any
+`rank` transform are refused there (contract 49), because both are defined relative to the cohort
+being evaluated and a benchmark sits outside it — a crowd reading is what this session's players
+did, a rank is a position among the coins under evaluation. Neither has a value for BTC-as-yardstick.
+Put those columns on an ordinary section and `conditionRef` across.
+
+Budgets are served by discovery (validated today: 32 sections, 32 custom columns, 8 distinct
+timeframes, 16 conditions, 16 clauses, 16k estimated report tokens). `preview_strategy_report`
+echoes your usage against each cap.
+
+## Conditions — deterministic logic over your own report
+
+Each condition: `{ conditionKey, name, definition, verdict, required, exit, clock, closes }` —
+all eight required, no defaults. The conditions axis saves by whole-set replacement, so an omitted
+key would silently un-clock a money gate on the next unrelated edit rather than be refused.
+
+- **Clauses** compare one column: numeric/rank headers take `lt|lte|gte|gt|between`;
+  classification/direction/event headers take `is|in` with the column's exact vocabulary
+  (served per header in `conditionColumns` / the column contract).
+- **Groups**: `ALL`, `ANY`, `NOT`, `N_OF` (with `n`), depth ≤ 2 (an inner group holds leaves
+  only).
+- **References** (`{kind:"conditionRef", conditionKey}`) compose named conditions; cycles are
+  rejected, forward references are legal.
+- **Column addressing**: `{sectionKey, header}`. `sectionKey: null` is authoring sugar for a
+  header unique across the whole report; a duplicated header (e.g. `ADX` in two sections) must
+  be section-qualified. On a **CREATE you omit `sectionKey` entirely** — the server derives it
+  from the section itself, so the same submitted section yields the same key on every compile, and
+  minting a `custom:<uuid>` yourself is refused. On an UPDATE or RESTORE, send back the keys
+  `get_strategy` returned. To qualify a duplicated header, read the key from a preview's
+  `conditionColumns` or from the candidates a `CONDITION_COLUMN_AMBIGUOUS` refusal offers.
+- **Verdict**: `UP` | `DOWN` | `NEITHER` on deciding conditions, explicit `null` on building
+  blocks. Declaration order is precedence: the first TRUE condition with a non-null verdict
+  decides the coin's verdict. Put the more specific carrier first.
+- **`required: true`** makes a FALSE reading a hard gate: the compose-trade evaluation is
+  blocked *before any billing or LLM call*. This is the cheapest risk control in the studio —
+  use it for liquidity floors, regime vetoes, and "never fight the HTF" rules.
+- Evaluation is three-valued: `UNRESOLVED` (missing input) is never collapsed to FALSE, and
+  outcomes read from a still-forming bar are marked provisional.
+- **The evidence clock.** `clock: "LIVE"` reads the forming bar; `clock: "CLOSE"` reads settled
+  bars, and `closes` (1–5) is how many consecutive closed bars must read TRUE — always `1` under
+  LIVE, which has exactly one frame. A CLOSE clock is legal **only** over a header resolved from
+  the coin's own candle series at offset 0; frame-inert operands (perp-payload scalars, published
+  rolling changes, ranks, zone entities, regime labels, enrichment metrics, session scalars) are
+  refused with `CONDITION_CLOCK_OPERAND_ILLEGAL`. The remedy is a split, not a re-clock: move that
+  clause into its own LIVE condition and `conditionRef` it.
+- **The exit role.** `exit: true` makes a settled TRUE reading close open positions its verdict
+  opposes — UP exits SHORTs, DOWN exits LONGs, a `NEITHER` or `null` verdict exits both. Legal only
+  under `clock: "CLOSE"`, because an exit fired on a forming bar is an intrabar exit. Orthogonal to
+  `required`: the two act on disjoint lifecycles, pre-entry versus open.
+
+## Entry — when, and where, an entry is taken
+
+`{ trigger, confirmTf, closes, bandAtrMultiple, levelSource, levelOffsetAtrMultiple, validForBars }`
+— all seven required on every CREATE, no defaults. Replaced WHOLE on save, so an omitted key
+reverts an author's discipline silently rather than being refused.
+
+| `trigger` | What it does |
+|---|---|
+| `AT_SIGNAL` | Fire on the qualification flip, at whatever bar is on the tape. The platform's flat wall-clock entry window applies. |
+| `ON_CANDLE_CLOSE` | The flip ARMS the pair; entry is taken only after a `confirmTf` close that still reads the conditions true and has not displaced beyond the band. |
+| `STOP_THROUGH_LEVEL` | A TRIGGER order rests at the level ± offset; the exchange book is the watcher. |
+| `ON_RETEST` | A LIMIT order rests at the broken level. Not filling is a correct outcome, not a failure. |
+
+- `confirmTf` — exactly two values are legal: the strategy's own timeframe and the rung below it
+  (one only, at the ladder floor). Not the authorable main-candle set.
+- `closes` — 1–5 consecutive confirming closes. Must be `1` under any trigger but `ON_CANDLE_CLOSE`.
+- `bandAtrMultiple` — the veto width. The entry is VOIDED when the confirming close moved at or
+  beyond that many ATR against the armed verdict. Strictly `> 0` (zero voids on any adverse move,
+  which is a filter, not "off"), and at or below the platform's own entry-deviation gate — read it
+  from `get_trading_config_catalog`.
+- `levelSource` — `SWING_HIGH` | `SWING_LOW` | `BOLLINGER_UPPER` | `BOLLINGER_LOWER`, resolved once
+  at decision time.
+- `levelOffsetAtrMultiple` — 0–2, UNSIGNED. Direction is implied by the trigger and the verdict, so
+  a signed value would invert the trigger's meaning. Must be `0` under a non-level trigger.
+- `validForBars` — 1–24 of the strategy's OWN bars, not minutes: a 1h setup waiting for a retest has
+  not failed after fifteen minutes.
+
+The legality matrix runs **one way**: all seven keys are always present, so the question is never
+"is it set" but "is it set to something that MEANS anything under this trigger". Leave a dial at its
+inert value rather than setting one the platform will ignore.
+
+## Signal weights — the scorecard is a weighted average, budget it
+
+Allocation tiers: `0` Off, `1` Normal, `2` Important, `3` Critical.
+
+```
+aggregateScore = Σ(score × allocation) / Σ(allocation)   over triggered signals
+```
+
+Consequences worth designing around:
+
+- Weights are **relative**: one Critical among Normals dominates; all-Critical equals all-Normal.
+  Build a pyramid — 1–2 Critical (the thesis), 2–4 Important (confirmation), a few Normal
+  (context) — and turn everything else Off so noise cannot dilute the average.
+- `required: true` on a rule does two things: the signal counts toward `minRequiredCount` when
+  it triggers, and the gate blocks routing when too few required signals fired. A rule with
+  `required: true` at allocation 0 is **rejected** (contract 34) — raise the allocation or clear
+  the flag.
+- `params` are per-signal and replace canonical defaults only when present and valid — tune
+  thresholds to the strategy (e.g. an RSI-overbought at 65 for a fade book) after reading
+  `get_strategy_signal_definition({signalId, timeframe})`. Omitted `params` preserve defaults
+  byte-for-byte.
+- Which signals *can* trigger follows from your report's sections/columns
+  (`derive_strategy_rule_view` shows in-report membership for a draft). Weighting a signal your
+  report never feeds is dead weight.
+
+## Routing gates
+
+- `minAggregateScore` (0–1): floor on the weighted average above. Set it from your pyramid: if
+  routing should need the Critical thesis plus one Important confirmation, compute that mix's
+  aggregate and gate just under it.
+- `minRequiredCount` (0–20): how many `required` signals must be among the triggered set.
+- `minAtrPct`: minimum ATR as % of price — a dead-market filter; bounds come from
+  `get_trading_config_catalog` (validated today: 0.1–10).
+
+## Trade levels (ATR geometry)
+
+`minStopLossAtrMultiple < maxStopLossAtrMultiple` (band where the stop may sit; ceiling capped
+at the structural 3×ATR), `minRiskRewardRatio` (catalog bounds today: 0.5–3). Position size is
+risk-budget based (`riskPct / stopDistancePct` — see the `battlegrid` skill's contract notes),
+so a *wider* stop means a *smaller* position, not more risk. Tight bands suit breakout entries;
+wide bands suit mean reversion that needs room.
+
+## Position management (how the stop moves)
+
+Validated live bounds: `breakEvenTriggerR` 0.5–2 · `trailingTriggerR` 0–2 step 0.01 (0 = trail
+from entry) · `trailingGivebackPct` 25–55 · `trailingBufferPct` 0.01–1 · `timeDecay` grace
+1–1440 min ≥ interval 1–480 min, tighten 0.1–50%, max 1–100%, stale threshold 0–100% of TP
+progress. Each mechanism has its own enabled flag; there is no umbrella switch. Trend books:
+arm break-even ~1R, trail late with a generous giveback (40–55). Mean-reversion/scalp books:
+break-even early, tight giveback, and **timeDecay on** — a thesis that hasn't paid within its
+horizon should be squeezed out.
+
+## Coin selection (per compile, not persisted)
+
+`{mode:"ranked", limit, category?}` (categories today: ALL, CRYPTO, L1, MEMES, DEFI, TRADFI,
+STOCKS, INDICES, COMMODITIES) or `{mode:"explicit", tickers[]}`. Choose the cohort the review
+should render over — explicit tickers for a focused edit, ranked for a scanning book.
+
+## Market Read markers
+
+`marketReadText` renders with live values wherever a `{...}` marker names a column header
+(`{RVOL}`), a condition (`{SQUEEZE_ON}` — renders outcome plus evidence), or a section-qualified
+form on collision (`{custom:<uuid>.MAalign}`). The preview returns `marketReadMarkers` with each
+marker's resolution status — fix `unknown`/`ambiguous` markers before compiling.
+
+## References
+
+- `references/playbooks.md` — five validated desk-grade playbooks with full payloads: volatility
+  compression breakout, crowded-positioning fade, relative-strength rotation with a benchmark
+  gate, HTF trend pullback, perp/spot flow divergence at structure.
+- `references/recipes.md` — copy-adaptable column recipes, condition patterns, weight matrices,
+  and trade-level/position-management presets per trading persona.
+- `references/tradingview-ports.md` — the most popular TradingView community scripts (Squeeze
+  Momentum [LazyBear], Supertrend/UT Bot, Chandelier Exit, MACD + 200 MA, golden cross, RSI-2,
+  VWAP reversion, Donchian/Turtle, ICT FVG/order blocks) translated process-for-process onto
+  the studio's vocabulary, with an expressibility triage and honest named substitutions for
+  what the grammar cannot carry.
+
+Validate a draft cheaply before compiling: `derive_strategy_rule_view` (report membership +
+rule defaults, no write) and `preview_strategy_report` (rendered tables, condition outcomes
+with evidence, verdict tally, budget usage, marker resolution). Then compile once, review the
+compiled truth, and apply.

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

@@ -0,0 +1,370 @@
+# Strategy Studio playbooks — validated desk-grade examples
+
+Five complete composition patterns, modeled on how systematic desks actually structure these
+trades. Every header, vocabulary label, bound, and shape below was validated against the live
+server (preview + column contracts) on 2026-08-28. Tokens are still illustrative: re-discover
+before compiling, and read exact headers from `preview_strategy_report`'s `conditionColumns`.
+
+Playbook 1 shows the **full** `compile_strategy_plan` CREATE request. Playbooks 2–5 show only
+the axes that differ — their envelope (`operation`, `intentSummary`, `assumptions`,
+`coinSelection`, identity, timeframe) follows the same shape. Multi-account proxies wrap each as
+`{ account, request }`.
+
+---
+
+## 1 · Volatility Compression Breakout (vol desk, 4h swing)
+
+**Thesis.** Coins in the tightest Bollinger compression on the board, with trend strength not yet
+developed, break hard when volume arrives. Trade the expansion, direction decided by the break.
+
+**Why this shape.** Cross-sectional `rank` finds compression *relative to the whole universe*
+(cheaper and more robust than an absolute width threshold); a building-block condition holds the
+squeeze state and two verdict carriers decide direction; a required liquidity floor stops the
+agent spending calls on illiquid names; tight stop band + trailing because breakout invalidation
+is nearby and winners should run.
+
+```json
+{
+  "request": {
+    "operation": "CREATE",
+    "intentSummary": "Cross-sectional volatility-compression breakout: enter expansions out of the tightest Bollinger squeezes on the board, direction decided by the breaking bar, volume-confirmed.",
+    "assumptions": [
+      "4h anchor: swing cadence, structural zones read on the regime rung",
+      "Ranked CRYPTO cohort approximates the live tradable universe"
+    ],
+    "coinSelection": { "mode": "ranked", "limit": 20, "category": "CRYPTO" },
+    "name": "Compression Breakout",
+    "tagline": "Tightest bands on the board, traded on expansion",
+    "description": "Scans the universe for Bollinger-width compression (bottom-decile rank), requires real participation, and enters the expansion bar in its own direction. Structure zones frame targets.",
+    "timeframe": "4h",
+    "sections": [
+      {
+        "kind": "custom",
+        "sectionKey": "custom:a1a1a1a1-b2b2-4c3c-8d4d-e5e5e5e5e5e5",
+        "title": "Squeeze Scan",
+        "benchmarkTicker": null,
+        "columns": [
+          { "metric": "BB_WIDTH_PCT", "transformId": "value", "timeframe": { "rel": "anchor" } },
+          { "metric": "BB_WIDTH_PCT", "transformId": "rank", "timeframe": { "rel": "anchor" }, "ordering": "lo" },
+          { "metric": "ADX", "transformId": "value", "timeframe": { "rel": "anchor" } },
+          { "metric": "RVOL", "transformId": "value", "timeframe": { "rel": "anchor" } },
+          { "metric": "BB_PCT_B", "transformId": "value", "timeframe": { "rel": "anchor" } },
+          { "metric": "CLOSE_CHANGE", "transformId": "value", "timeframe": { "rel": "anchor" } },
+          { "metric": "NOTIONAL_VOLUME_1D", "transformId": "value", "timeframe": { "rel": "anchor" } }
+        ]
+      },
+      { "kind": "platform", "sectionKey": "includeBollingerBands" },
+      { "kind": "platform", "sectionKey": "includeStructureZones" }
+    ],
+    "conditions": [
+      {
+        "conditionKey": "LIQUID_FLOOR",
+        "name": "Liquidity floor",
+        "definition": { "kind": "clause", "column": { "sectionKey": "custom:a1a1a1a1-b2b2-4c3c-8d4d-e5e5e5e5e5e5", "header": "vol24hUsd" }, "op": "gte", "value": 25000000 },
+        "verdict": null,
+        "required": true
+      },
+      {
+        "conditionKey": "SQUEEZE_ON",
+        "name": "Volatility compression",
+        "definition": {
+          "kind": "group", "op": "ALL", "members": [
+            { "kind": "clause", "column": { "sectionKey": "custom:a1a1a1a1-b2b2-4c3c-8d4d-e5e5e5e5e5e5", "header": "bbWidthPct_rank_lo" }, "op": "lte", "value": 10 },
+            { "kind": "clause", "column": { "sectionKey": "custom:a1a1a1a1-b2b2-4c3c-8d4d-e5e5e5e5e5e5", "header": "ADX" }, "op": "lt", "value": 20 }
+          ]
+        },
+        "verdict": null,
+        "required": false
+      },
+      {
+        "conditionKey": "BREAK_UP",
+        "name": "Upside expansion",
+        "definition": {
+          "kind": "group", "op": "ALL", "members": [
+            { "kind": "conditionRef", "conditionKey": "SQUEEZE_ON" },
+            { "kind": "clause", "column": { "sectionKey": "custom:a1a1a1a1-b2b2-4c3c-8d4d-e5e5e5e5e5e5", "header": "closeChg" }, "op": "gt", "value": 0 },
+            { "kind": "clause", "column": { "sectionKey": "custom:a1a1a1a1-b2b2-4c3c-8d4d-e5e5e5e5e5e5", "header": "RVOL" }, "op": "gte", "value": 1.5 },
+            { "kind": "clause", "column": { "sectionKey": "custom:a1a1a1a1-b2b2-4c3c-8d4d-e5e5e5e5e5e5", "header": "pctB" }, "op": "gte", "value": 0.85 }
+          ]
+        },
+        "verdict": "UP",
+        "required": false
+      },
+      {
+        "conditionKey": "BREAK_DOWN",
+        "name": "Downside expansion",
+        "definition": {
+          "kind": "group", "op": "ALL", "members": [
+            { "kind": "conditionRef", "conditionKey": "SQUEEZE_ON" },
+            { "kind": "clause", "column": { "sectionKey": "custom:a1a1a1a1-b2b2-4c3c-8d4d-e5e5e5e5e5e5", "header": "closeChg" }, "op": "lt", "value": 0 },
+            { "kind": "clause", "column": { "sectionKey": "custom:a1a1a1a1-b2b2-4c3c-8d4d-e5e5e5e5e5e5", "header": "RVOL" }, "op": "gte", "value": 1.5 },
+            { "kind": "clause", "column": { "sectionKey": "custom:a1a1a1a1-b2b2-4c3c-8d4d-e5e5e5e5e5e5", "header": "pctB" }, "op": "lte", "value": 0.15 }
+          ]
+        },
+        "verdict": "DOWN",
+        "required": false
+      }
+    ],
+    "rules": [
+      { "signalId": "bollinger_squeeze", "allocation": 3, "required": true },
+      { "signalId": "volume_surge", "allocation": 2, "required": true, "params": { "multiplier": 1.5 } },
+      { "signalId": "volatility_atr_expanding", "allocation": 2, "required": false },
+      { "signalId": "sr_resistance_break", "allocation": 2, "required": false },
+      { "signalId": "sr_support_break", "allocation": 2, "required": false },
+      { "signalId": "bollinger_upper_touch", "allocation": 1, "required": false },
+      { "signalId": "bollinger_lower_touch", "allocation": 1, "required": false },
+      { "signalId": "trend_adx_ranging", "allocation": 1, "required": false }
+    ],
+    "minAggregateScore": 0.55,
+    "minRequiredCount": 2,
+    "minAtrPct": 0.8,
+    "minStopLossAtrMultiple": 0.75,
+    "maxStopLossAtrMultiple": 1.75,
+    "minRiskRewardRatio": 2,
+    "breakEvenEnabled": true,
+    "breakEvenTriggerR": 1,
+    "trailingEnabled": true,
+    "trailingTriggerR": 1.2,
+    "trailingGivebackPct": 35,
+    "trailingBufferPct": 0.3,
+    "timeDecayEnabled": false,
+    "marketReadText": "Trade only expansions out of compression: {SQUEEZE_ON} must read TRUE on the setup bar. Board standing {bbWidthPct_rank_lo}; participation {RVOL} must be at least 1.5x. Longs on {BREAK_UP}, shorts on {BREAK_DOWN}; skip anything failing {LIQUID_FLOOR}. Frame targets against the regime-rung zones ({zones_htf_resist_dist} up, {zones_htf_support_dist} down)."
+  }
+}
+```
+
+**Review focus.** In the compile response: the scorecard should show exactly the eight named
+rules scoring (everything else Off); `reviewContext.reportPreview.conditionOutcomes` should show
+`SQUEEZE_ON` evidence per coin and the verdict tally; check `marketReadMarkers` all resolve.
+
+---
+
+## 2 · Crowded-Positioning Fade (derivatives desk, 1h intraday)
+
+**Thesis.** When funding is paying one side heavily, open interest is building, and the OI·price
+regime says the crowd is adding into an extended move, fade it back toward equilibrium.
+
+**Sections.** Custom `Positioning` (mint key `custom:b2b2…`):
+`FUNDING_RATE value` → `rate` · `FUNDING_RATE aggregate w24` → `rate_mean24` (one venue print is
+noise; the 24-sample mean is the crowd's bill) · `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` (perp
+premium) · `RSI14 value` · `CHG_24H value` → `chg24h`. Plus platform `includeCvd`.
+
+**Conditions** (building blocks carry no verdict; NOT as a required veto):
+
+```json
+[
+  { "conditionKey": "NO_LIQUIDATION_TAPE", "name": "Not a liquidation knife",
+    "definition": { "kind": "group", "op": "NOT", "members": [
+      { "kind": "clause", "column": { "sectionKey": "custom:b2b2b2b2-c3c3-4d4d-8e5e-f6f6f6f6f6f6", "header": "oiRegime" }, "op": "is", "label": "long liquidation" } ] },
+    "verdict": null, "required": true },
+  { "conditionKey": "CROWDED_LONGS", "name": "Longs overpaying and adding",
+    "definition": { "kind": "group", "op": "ALL", "members": [
+      { "kind": "clause", "column": { "sectionKey": "custom:b2b2b2b2-c3c3-4d4d-8e5e-f6f6f6f6f6f6", "header": "ann" }, "op": "gte", "value": 25 },
+      { "kind": "clause", "column": { "sectionKey": "custom:b2b2b2b2-c3c3-4d4d-8e5e-f6f6f6f6f6f6", "header": "oiChg" }, "op": "gte", "value": 3 },
+      { "kind": "clause", "column": { "sectionKey": "custom:b2b2b2b2-c3c3-4d4d-8e5e-f6f6f6f6f6f6", "header": "oiRegime" }, "op": "is", "label": "new longs" } ] },
+    "verdict": null, "required": false },
+  { "conditionKey": "FADE_SHORT", "name": "Fade the crowded long",
+    "definition": { "kind": "group", "op": "ALL", "members": [
+      { "kind": "conditionRef", "conditionKey": "CROWDED_LONGS" },
+      { "kind": "clause", "column": { "sectionKey": "custom:b2b2b2b2-c3c3-4d4d-8e5e-f6f6f6f6f6f6", "header": "RSI14" }, "op": "gte", "value": 65 },
+      { "kind": "clause", "column": { "sectionKey": "custom:b2b2b2b2-c3c3-4d4d-8e5e-f6f6f6f6f6f6", "header": "chg24h" }, "op": "gte", "value": 5 } ] },
+    "verdict": "DOWN", "required": false },
+  { "conditionKey": "SQUEEZED_SHORTS", "name": "Shorts overpaying and adding",
+    "definition": { "kind": "group", "op": "ALL", "members": [
+      { "kind": "clause", "column": { "sectionKey": "custom:b2b2b2b2-c3c3-4d4d-8e5e-f6f6f6f6f6f6", "header": "ann" }, "op": "lte", "value": -25 },
+      { "kind": "clause", "column": { "sectionKey": "custom:b2b2b2b2-c3c3-4d4d-8e5e-f6f6f6f6f6f6", "header": "oiChg" }, "op": "gte", "value": 3 },
+      { "kind": "clause", "column": { "sectionKey": "custom:b2b2b2b2-c3c3-4d4d-8e5e-f6f6f6f6f6f6", "header": "oiRegime" }, "op": "is", "label": "new shorts" } ] },
+    "verdict": null, "required": false },
+  { "conditionKey": "SQUEEZE_LONG", "name": "Squeeze the crowded short",
+    "definition": { "kind": "group", "op": "ALL", "members": [
+      { "kind": "conditionRef", "conditionKey": "SQUEEZED_SHORTS" },
+      { "kind": "clause", "column": { "sectionKey": "custom:b2b2b2b2-c3c3-4d4d-8e5e-f6f6f6f6f6f6", "header": "RSI14" }, "op": "lte", "value": 35 } ] },
+    "verdict": "UP", "required": false }
+]
+```
+
+**Rules** (note the tuned params — read `get_strategy_signal_definition` first):
+`funding_extreme_positive` 3 required, params `{"thresholdPct": 0.001}` ·
+`funding_extreme_negative` 3 required, params `{"thresholdPct": 0.001}` · `oi_surge` 2, params
+`{"thresholdPct": 0.03}` · `rsi_overbought` 2, params `{"threshold": 65}` · `rsi_oversold` 2,
+params `{"threshold": 35}` · `cvd_bear_divergence` 2 · `cvd_bull_divergence` 2 ·
+`mfi_overbought` 1 · `mfi_oversold` 1.
+
+**Gates & geometry.** `minAggregateScore 0.6`, `minRequiredCount 1` (either funding extreme),
+`minAtrPct 0.5`. Levels `1.0–2.5` ATR (mean reversion needs room), RR `1.5`. Position
+management: break-even at `0.8R`, trailing off, **timeDecay on** (`grace 120`, `interval 60`,
+`tighten 10`, `max 40`, `stale 25`) — a fade that hasn't paid in a couple of hours is wrong.
+
+---
+
+## 3 · Relative-Strength Rotation with a Benchmark Gate (cross-sectional desk, 4h)
+
+**Thesis.** Own the leaders while the market leader trends up; press the laggards when it rolls
+over. Selection is cross-sectional (ranks), regime is read off a **benchmark section**.
+
+**Sections.** Custom `Leadership` (key `custom:d4d4…`): `CLOSE_CHANGE rank hi` →
+`closeChg_rank_hi` · `CLOSE_CHANGE rank lo` → `closeChg_rank_lo` · `RVOL rank hi` →
+`RVOL_rank_hi` · `EMA5 spread EMA13 × trajectory w4` → `EMA5_EMA13_spread_now` / `_trend` ·
+`NOTIONAL_VOLUME_1D value` → `vol24hUsd`. Custom `BTC Regime` with `"benchmarkTicker": "BTC"`
+(key `custom:c3c3…`): `MA_ALIGN value` → `MAalign` (bullish/bearish/mixed) · `ADX value` ·
+`REGIME_TREND value` → `regTrend`. Every row of that section reads BTC, not the evaluated coin.
+
+**Conditions** (refs compose the regime gate with selection; duplicated headers like `ADX`
+must be section-qualified — that is why the section keys are minted client-side):
+
+```json
+[
+  { "conditionKey": "BTC_RISK_ON", "name": "BTC trending up",
+    "definition": { "kind": "group", "op": "ALL", "members": [
+      { "kind": "clause", "column": { "sectionKey": "custom:c3c3c3c3-d4d4-4e5e-8f6f-a7a7a7a7a7a7", "header": "MAalign" }, "op": "is", "label": "bullish" },
+      { "kind": "clause", "column": { "sectionKey": "custom:c3c3c3c3-d4d4-4e5e-8f6f-a7a7a7a7a7a7", "header": "ADX" }, "op": "gte", "value": 20 } ] },
+    "verdict": null, "required": false },
+  { "conditionKey": "BTC_RISK_OFF", "name": "BTC rolling over",
+    "definition": { "kind": "clause", "column": { "sectionKey": "custom:c3c3c3c3-d4d4-4e5e-8f6f-a7a7a7a7a7a7", "header": "MAalign" }, "op": "is", "label": "bearish" },
+    "verdict": null, "required": false },
+  { "conditionKey": "LEADER", "name": "Top-5 leader with participation",
+    "definition": { "kind": "group", "op": "ALL", "members": [
+      { "kind": "clause", "column": { "sectionKey": "custom:d4d4d4d4-e5e5-4f6f-8a7a-b8b8b8b8b8b8", "header": "closeChg_rank_hi" }, "op": "lte", "value": 5 },
+      { "kind": "clause", "column": { "sectionKey": "custom:d4d4d4d4-e5e5-4f6f-8a7a-b8b8b8b8b8b8", "header": "RVOL_rank_hi" }, "op": "lte", "value": 10 },
+      { "kind": "clause", "column": { "sectionKey": "custom:d4d4d4d4-e5e5-4f6f-8a7a-b8b8b8b8b8b8", "header": "vol24hUsd" }, "op": "gte", "value": 100000000 } ] },
+    "verdict": null, "required": false },
+  { "conditionKey": "ROTATE_IN", "name": "Rotate into leadership",
+    "definition": { "kind": "group", "op": "ALL", "members": [
+      { "kind": "conditionRef", "conditionKey": "BTC_RISK_ON" },
+      { "kind": "conditionRef", "conditionKey": "LEADER" } ] },
+    "verdict": "UP", "required": false },
+  { "conditionKey": "ROTATE_OUT", "name": "Press laggards in risk-off",
+    "definition": { "kind": "group", "op": "ALL", "members": [
+      { "kind": "conditionRef", "conditionKey": "BTC_RISK_OFF" },
+      { "kind": "clause", "column": { "sectionKey": "custom:d4d4d4d4-e5e5-4f6f-8a7a-b8b8b8b8b8b8", "header": "closeChg_rank_lo" }, "op": "lte", "value": 5 } ] },
+    "verdict": "DOWN", "required": false }
+]
+```
+
+**Rules.** `comparison_sector_momentum` 3 · `rel_roc_positive` 2 · `rel_roc_negative` 2 ·
+`ma_ema_aligned_bull` 2 required · `ma_ema_aligned_bear` 2 required · `rel_ppo_bull_cross` 1 ·
+`rel_ppo_bear_cross` 1 · `volume_surge` 1. Gates: `0.5 / 1 / 0.6`. Levels `1–2` ATR, RR `1.8`.
+PM: break-even 1R; trailing at 1R with giveback 45 (let rotation winners run); no timeDecay.
+`coinSelection` `{"mode":"ranked","limit":40,"category":"CRYPTO"}` — ranks need a wide cohort.
+
+---
+
+## 4 · HTF Trend Pullback (CTA desk, 1h, multi-timeframe confluence)
+
+**Thesis.** Only trade with the higher-timeframe trend; enter on anchor-rung pullbacks to value
+while the lower rung has not broken structure. Never spend an LLM call in chop.
+
+**Sections.** Platform `includeMtfConfluence` (headers per rung: `MAalign_ltf` / `MAalign` /
+`MAalign_htf`, `RSI14_*_zone`, `ADX_*_state` with vocab weak/developing/trending/extreme),
+platform `includeMovingAverages` (`dist_SMA20`, `dist_EMA20`, …), platform `includeRsi`
+(`RSI14_now`, `RSI14_zone`). Platform section keys are their literal `sectionKey` — qualify
+clauses with e.g. `"sectionKey": "includeMtfConfluence"` where headers collide.
+
+**Conditions** — the `ANY`-of-trends required gate is the key move: chop (neither trend) blocks
+compose-trade entirely, before billing:
+
+```json
+[
+  { "conditionKey": "HTF_UP", "name": "HTF uptrend",
+    "definition": { "kind": "group", "op": "ALL", "members": [
+      { "kind": "clause", "column": { "sectionKey": "includeMtfConfluence", "header": "MAalign_htf" }, "op": "is", "label": "bullish" },
+      { "kind": "clause", "column": { "sectionKey": "includeMtfConfluence", "header": "ADX_htf_state" }, "op": "in", "labels": ["trending", "extreme"] } ] },
+    "verdict": null, "required": false },
+  { "conditionKey": "HTF_DOWN", "name": "HTF downtrend",
+    "definition": { "kind": "group", "op": "ALL", "members": [
+      { "kind": "clause", "column": { "sectionKey": "includeMtfConfluence", "header": "MAalign_htf" }, "op": "is", "label": "bearish" },
+      { "kind": "clause", "column": { "sectionKey": "includeMtfConfluence", "header": "ADX_htf_state" }, "op": "in", "labels": ["trending", "extreme"] } ] },
+    "verdict": null, "required": false },
+  { "conditionKey": "TREND_PRESENT", "name": "Some HTF trend exists",
+    "definition": { "kind": "group", "op": "ANY", "members": [
+      { "kind": "conditionRef", "conditionKey": "HTF_UP" },
+      { "kind": "conditionRef", "conditionKey": "HTF_DOWN" } ] },
+    "verdict": null, "required": true },
+  { "conditionKey": "PULLBACK_LONG", "name": "Pullback to value in uptrend",
+    "definition": { "kind": "group", "op": "ALL", "members": [
+      { "kind": "conditionRef", "conditionKey": "HTF_UP" },
+      { "kind": "clause", "column": { "sectionKey": "includeRsi", "header": "RSI14_now" }, "op": "between", "low": 35, "high": 55 },
+      { "kind": "clause", "column": { "sectionKey": "includeMovingAverages", "header": "dist_EMA20" }, "op": "between", "low": -3, "high": 0.5 } ] },
+    "verdict": "UP", "required": false },
+  { "conditionKey": "PULLBACK_SHORT", "name": "Rally to value in downtrend",
+    "definition": { "kind": "group", "op": "ALL", "members": [
+      { "kind": "conditionRef", "conditionKey": "HTF_DOWN" },
+      { "kind": "clause", "column": { "sectionKey": "includeRsi", "header": "RSI14_now" }, "op": "between", "low": 45, "high": 65 },
+      { "kind": "clause", "column": { "sectionKey": "includeMovingAverages", "header": "dist_EMA20" }, "op": "between", "low": -0.5, "high": 3 } ] },
+    "verdict": "DOWN", "required": false }
+]
+```
+
+**Rules.** `mtf_pullback_long` 3 required · `mtf_pullback_short` 3 required ·
+`htf_ma_aligned_bull` 2 required · `htf_ma_aligned_bear` 2 required · `htf_trend_adx_trending`
+2 · `ma_ema_aligned_bull` 1 · `ma_ema_aligned_bear` 1 · `rsi_oversold` 1 params
+`{"threshold": 40}` (pullback depth, not capitulation). Gates: `minAggregateScore 0.6`,
+`minRequiredCount 2` (a pullback signal *and* an HTF alignment), `minAtrPct 0.7`. Levels
+`1–2.5` ATR, RR `2`. PM: break-even 1R; trailing 1.5R giveback 30 buffer 0.3; no timeDecay.
+
+---
+
+## 5 · Perp/Spot Flow Divergence at Structure (microstructure desk, 15m scalp)
+
+**Thesis.** When spot flow leads (accumulation) and price sits just above a standing support
+zone, buy the dip; when a move is perp-led and fragile into resistance, fade it. Structure comes
+from the platform zones section; flow from the perp/spot module.
+
+**Sections.** Platform `includePerpSpotFlow` (`perpSpotFlow` vocab: `confirmed_bull` /
+`confirmed_bear` / `perp_led_fragile` / `spot_led_accumulation` / `neutral`; plus
+`perpSpotStr`, `spotCVD`), platform `includeStructureZones` (`zones_htf_support_dist` — signed %
+from price, support below price is negative; `zones_htf_resist_dist`, `_age_h`, `_type`),
+custom `Tape` (key `custom:e5e5…`): `BUY_PRESSURE value` → `buyPres` (0–1) · `RVOL value` ·
+`CLOSE_CHANGE value` → `closeChg`.
+
+**Conditions** — `N_OF` requires 2-of-3 tape confirmations instead of a brittle ALL:
+
+```json
+[
+  { "conditionKey": "SPOT_ACCUM", "name": "Spot-led accumulation",
+    "definition": { "kind": "clause", "column": { "sectionKey": "includePerpSpotFlow", "header": "perpSpotFlow" }, "op": "is", "label": "spot_led_accumulation" },
+    "verdict": null, "required": false },
+  { "conditionKey": "NEAR_SUPPORT", "name": "Sitting on a standing zone",
+    "definition": { "kind": "group", "op": "ALL", "members": [
+      { "kind": "clause", "column": { "sectionKey": "includeStructureZones", "header": "zones_htf_support_dist" }, "op": "between", "low": -2, "high": 0 },
+      { "kind": "clause", "column": { "sectionKey": "includeStructureZones", "header": "zones_htf_support_age_h" }, "op": "gte", "value": 12 } ] },
+    "verdict": null, "required": false },
+  { "conditionKey": "DIP_BID", "name": "Buy the dip into support",
+    "definition": { "kind": "group", "op": "ALL", "members": [
+      { "kind": "conditionRef", "conditionKey": "SPOT_ACCUM" },
+      { "kind": "conditionRef", "conditionKey": "NEAR_SUPPORT" },
+      { "kind": "group", "op": "N_OF", "n": 2, "members": [
+        { "kind": "clause", "column": { "sectionKey": "custom:e5e5e5e5-f6f6-4a7a-8b8b-c9c9c9c9c9c9", "header": "buyPres" }, "op": "gte", "value": 0.55 },
+        { "kind": "clause", "column": { "sectionKey": "custom:e5e5e5e5-f6f6-4a7a-8b8b-c9c9c9c9c9c9", "header": "RVOL" }, "op": "gte", "value": 1.2 },
+        { "kind": "clause", "column": { "sectionKey": "custom:e5e5e5e5-f6f6-4a7a-8b8b-c9c9c9c9c9c9", "header": "closeChg" }, "op": "gt", "value": 0 } ] } ] },
+    "verdict": "UP", "required": false },
+  { "conditionKey": "FRAGILE_POP", "name": "Perp-led pop into resistance",
+    "definition": { "kind": "group", "op": "ALL", "members": [
+      { "kind": "clause", "column": { "sectionKey": "includePerpSpotFlow", "header": "perpSpotFlow" }, "op": "is", "label": "perp_led_fragile" },
+      { "kind": "clause", "column": { "sectionKey": "includeStructureZones", "header": "zones_htf_resist_dist" }, "op": "between", "low": 0, "high": 2 },
+      { "kind": "clause", "column": { "sectionKey": "custom:e5e5e5e5-f6f6-4a7a-8b8b-c9c9c9c9c9c9", "header": "RVOL" }, "op": "gte", "value": 1.3 } ] },
+    "verdict": "DOWN", "required": false }
+]
+```
+
+**Rules.** `flow_perp_spot_bull_divergence` 3 required · `flow_perp_spot_bear_divergence` 3
+required · `cvd_bull_divergence` 2 · `cvd_bear_divergence` 2 · `sr_at_support` 2 ·
+`sr_at_resistance` 2 · `structure_ob_approach` 1 · `volume_surge` 1. Gates: `0.55 / 1 / 0.4`
+(15m: lower ATR floor). Levels `0.5–1.2` ATR, RR `1.5` — scalp geometry. PM: break-even
+`0.7R`; trailing `0.9R`, giveback 30, buffer 0.15; **timeDecay on and aggressive** (`grace 45`,
+`interval 15`, `tighten 15`, `max 60`, `stale 30`). `coinSelection`
+`{"mode":"ranked","limit":15,"category":"CRYPTO"}`.
+
+---
+
+## Using a playbook
+
+1. Re-discover the vocabulary; confirm each header via `get_strategy_column_contract` or one
+   `preview_strategy_report` over your sections (read `conditionColumns`).
+2. Adapt thresholds to the current market — preview shows live values beside each clause, so
+   calibrate literals against what the table actually renders.
+3. Compile once, read `approvedPlan` (scorecard, diff, viability) and
+   `reviewContext.reportPreview` (condition outcomes, verdict tally, budgets), fix, recompile.
+4. Apply with `{ "request": { "planToken": "<verbatim>", "confirm": true } }` after review.