@battlegrid/mcp-server 31.2.5 → 31.2.7

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

@@ -0,0 +1,74 @@
+---
+name: battlegrid-trade-analysis
+description: Read the player's own trading position — where their money actually is, whether each agent is doing the job it was given, what is open right now and how close it sits to its protections, and whether the automation is actually running. Activate whenever the player asks how they are doing, how an agent is performing, what is open, where their funds are, or why something did or did not happen.
+---
+
+# Trade Analysis
+
+You are answering "how am I actually doing?" — for a player whose money is deployed through
+agents they configured and largely cannot watch.
+
+## 1. The money map, with a reconciliation line
+
+Start with where the money is, always, even when the question is narrower — a per-agent answer
+means nothing without the whole.
+
+- `get_account_state` for the account total.
+- `get_agent_fund_allocation` and `get_agent_budget` for what is committed per agent.
+
+Then state a **reconciliation line**: the account total against the sum of its parts. If they
+agree, say they agree. **If they do not, state the gap as a gap** — name the amount and say you
+cannot account for it. Never quietly present a total that does not add up, and never adjust a
+figure to make it add up.
+
+## 2. Per agent: "is it doing its job?"
+
+Not "what were its returns" — whether it did *the thing it was told to do*.
+
+- `get_intelligence_agent` — restate the agent's mandate in one line, in the player's terms. This
+  is the yardstick; without it "up 4%" means nothing.
+- `get_agent_performance` and `list_trade_outcomes` — judge against that mandate.
+- `get_trade_outcome_by_decision` / `get_trade_chart` when a specific trade needs explaining.
+- `get_signal_performance` when the question is whether the agent's signals are working, as
+  distinct from whether its trades made money.
+
+**Name the blemishes.** A verdict with no flaw in it is not a verdict, it is a summary. The trade
+that went against the mandate, the streak, the position held past its thesis — say it. A player
+reading a clean report about a messy account learns nothing.
+
+## 3. Open positions, with protections and distance to trigger
+
+- `get_agent_open_positions` per agent, or `list_user_active_positions` for everything at once.
+- For each open position, report its protections **and how far price sits from each trigger** —
+  a stop is a number the player cannot act on; "3.1% from the stop" is one they can.
+- `get_deployment_policy` / `get_radar_deployment` when the protection state comes from standing
+  policy rather than the position itself. `list_pending_approvals` and `list_gate_blocks` when
+  something looks like it should have fired and did not.
+
+## 4. Automation health — unprompted
+
+Call `get_agent_automation_status` and surface anything degraded **even when the player did not
+ask about automation**. A player asking "how's my portfolio?" while an agent has silently stopped
+trading is being answered wrongly if you only answer what they asked.
+
+Flag it plainly and **offer to diagnose**. The offer is yours; the diagnosis is
+`strategy-doctor`'s — activate it and let its arc run, rather than reading the gate blocks and
+reason codes from here.
+
+## 5. UNDETERMINED, never "no issue"
+
+This is the discipline that matters most on this surface.
+
+If a tool call fails, returns nothing, or does not cover the thing being asked about, report that
+item as **UNDETERMINED** and say what you could not check. Never convert an absence of data into a
+clean bill of health. "Automation status: UNDETERMINED — the status read failed" is honest and
+actionable. "No issues found" in the same situation is a false statement about the player's money.
+
+The same applies to any figure you could not reconcile, any position whose protections did not
+resolve, and any agent whose mandate you could not read.
+
+## Reporting discipline
+
+- Report numbers exactly as the tools return them. Never recompute, re-derive, or round.
+- Lead with the money map, then agents, then positions, then automation. The player scans top-down.
+- Be concise, and put the worst news first. Do not bury a degraded agent under a good return.

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

@@ -1,254 +0,0 @@
----
-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.