@battlegrid/mcp-server 31.2.5 → 31.2.6

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

@@ -0,0 +1,180 @@
+---
+name: battlegrid-radar-deployment
+description: Deploy the player's agents to standing duty — per-coin Radar policies that fire real trades on confirmed regime flips, and per-preset Arena deployment policies that enter sessions automatically. Reads what is deployed now, previews what a draft would actually resolve to, writes it only after the player has seen that preview, and un-deploys with the blast radius stated. Activate whenever the player wants an agent put on duty, wants to change or pause a deployment, asks what would fire right now or why nothing is firing, or wants to stop a coin or a preset being traded automatically.
+---
+
+# Radar & Deployment
+
+You are handing an agent **standing authority**. A Radar policy fires real trades on confirmed
+regime flips with no further human action; a deployment policy enters real sessions the same way.
+Nobody is watching when it happens — which is why the player has to see what a policy resolves to
+*before* it exists, not after.
+
+Radar (per coin) and Arena deployment (per preset) are **separate bounded contexts**. They share
+no slot shape, no condition union and no resolution type. Never carry a fact from one to the other,
+and never describe them as one thing with two modes.
+
+## The five failures this flow exists to prevent
+
+1. **A write with no fresh preview.** *Cue: any `upsert_radar_deployment` or
+   `upsert_deployment_policy`.* The preview is the only place the player sees which agent actually
+   goes on duty and why. → steps 2–3.
+2. **A blind CAS retry.** *Cue: a CONFLICT on a write.* The revision moved because the stored
+   policy changed. Bumping the number and retrying overwrites an edit you never read. → step 3.
+3. **Previewing one thing and writing another.** *Cue: the player adjusts a slot, a bar, a window,
+   a regime, or the enabled flag after you previewed.* A preview vouches only for the parameters it
+   was given. → step 2.
+4. **A replacement that silently drops slots.** *Cue: any upsert on a coin or preset that already
+   has a policy.* `slots` is the COMPLETE set and replaces what is stored — a slot you did not
+   resend is deleted. → step 3.
+5. **Answering "why isn't it firing?" by paging the journal.** *Cue: any question about why a
+   deployed agent has been quiet — "is it working?", "it hasn't traded all day", "what's blocking
+   it?".* `get_radar_activity_summary` now answers the whole question in one small call — which
+   cause recurs, how far the score sits from firing, and what just happened — so paging the journal
+   for it tallies an aggregate the server already computed and re-derives a proximity reading it
+   already serves. The journal read is for ONE occurrence, or for more rows than the summary's ten.
+   → step 5.
+
+## Sequence
+
+### 1. Resolve the target, then read current state
+
+**Radar is keyed on `coinId` — a text `coins.id`, not a ticker and not a UUID.** Resolve it
+through `get_coin_metadata`. Never derive a `coinId` from the player's ticker text, however
+obvious it looks: the identifier the tools take is the coin table's own, and a guessed one either
+misses or hits the wrong coin.
+
+Arena deployment is keyed on `presetId` (a UUID) — from `list_game_presets`.
+
+Then read what exists:
+
+- `get_radar_deployment` (one coin) or `list_radar_deployments` (the fleet, plus the platform
+  `radarPaused` kill-switch — if that is set, say so up front: nothing will fire whatever you
+  write).
+- `get_deployment_policy` / `list_deployment_policies` for Arena.
+
+The read is what supplies `expectedRevision` for the write. **`null` only for a first deploy** —
+a coin or preset with no policy at all. Anything else carries the revision you just read.
+
+`get_regime_snapshot` / `get_regime_history` when the policy turns on regime conditions.
+
+If the question is *why did my radar agent not fire*, do not start from the journal — **go to step
+5**, which reads state first and pattern second.
+
+### 2. Preview the exact parameters under discussion
+
+- **Radar** → `preview_radar_resolution` with the draft slots.
+- **Arena** → `preview_deployment_resolution` with the draft slots.
+
+Both run the **same resolver the live sweep runs**, so the preview is the real outcome, not an
+estimate. Neither writes anything, neither needs a revision, and neither costs the player an LLM
+call — so previewing repeatedly while iterating is free and correct.
+
+Render the preview as a card and read it out: which agent goes on duty, which slot matched and at
+what priority, the regime and conviction used, the qualification verdict, and any typed idle or
+blocked reason. **Render `section` as the server sends it — never re-derive it.** A non-null reason
+does not mean idle (`ON_DUTY_BUT_POSITION_BLOCKED` carries a reason and is not idle), so deciding
+the headline yourself gets it wrong.
+
+**If any parameter changes after a preview, re-preview.** A preview never vouches for parameters
+it did not see. That includes a changed conviction bar, an added or removed slot, an edited time
+window or regime set, and flipping `enabled`.
+
+### 3. Confirm against the preview, then write
+
+One confirmation whose question **references what the preview showed** — the agent it put on duty and
+the reason — and **names what the replacement changes about the stored policy**, read from step 1:
+
+- every slot the replacement **removes** (by agent and priority), because `slots` is the whole set;
+- a bar, window or regime that **changes** on a slot that survives;
+- `enabled` going false (**paused, slots kept — nothing fires**) or true (**resumed — it can fire
+  again from the next confirmed flip**).
+
+Then `upsert_radar_deployment` / `upsert_deployment_policy` with the revision from step 1.
+
+**On a typed CONFLICT: re-read, re-preview, re-confirm.** In that order, and all three. The policy
+changed under you, so the state your preview resolved and the radius you stated are both stale.
+Never retry with a bumped revision.
+
+### 4. Deletes: read, state what stops, confirm
+
+`delete_radar_deployment` / `delete_deployment_policy` remove the **entire** policy — every slot and
+condition — and revoke the standing authority. There is no preview here, and correctly so: there is
+no resolution to preview once the policy is gone. The evidence is **the deployment's own read**.
+
+State what stops, from that read: which agents were on duty or eligible, what the policy was
+firing on, and that the slots are not recoverable. Both tools carry a schema-level `confirm: true`.
+
+**If the player wants to stop trading without losing the slots, that is not a delete** — it is an
+upsert with `enabled: false`. Offer that whenever the ask sounds like "pause", "stop for now", or
+"take it off duty for a while".
+
+### 5. "Why isn't it firing?" — state, then pattern, then rows
+
+Three reads, cheapest first. Stop as soon as the player's question is answered.
+
+1. **`preview_radar_resolution` → `resolvesNow`** for what is true **right now**: the section, the
+   blocked reason and since when, the qualification block, the cooldown, the last fire, and which
+   agent is on duty. Most "is it working?" questions end here.
+2. **`get_radar_activity_summary`** for everything else about "why is it quiet", in ONE call. It
+   carries three parts and they answer three different questions, each on its own scope:
+   - `groups` — which cause recurs and how often, over the window the response names. Quote the
+     counts with that window; never sum them across calls.
+   - `curveDigest` — how FAR the score sits from firing, over the on-duty agent's ring. This is what
+     separates "lower the minimum two points and it fires" from "this strategy does not fit this
+     coin": `bestUnqualifiedScorePercent` against `latestThresholdPercent`. Its `ringStartAt` /
+     `ringEndAt` describe the ring, NOT the cause window above.
+   - `recentEvents` — the last ten key events, lean. Deliberately NOT bounded by the cause window, so
+     a pair quiet for longer returns no groups beside populated older rows. That is correct, not a
+     contradiction; each row carries its own `occurredAt`.
+
+   For about one sweep after an agent rotation the digest can name the incoming agent while the rows
+   still show the outgoing one — the two halves are read from different stores. Say "just rotated"
+   rather than reporting a contradiction.
+3. **`get_radar_activity`** only for what step 2 cannot do: more rows than its ten, a FIRES-only
+   view, paging back through history, or ONE occurrence's full margins. Rows are lean by default —
+   pass `detail: 'FULL'` for the margin surface, and `includeCurve: true` only if something will
+   actually plot the points.
+
+**Neither of the first two substitutes for the other, and the reason is structural.** The journal is
+a TRANSITION log, not a state log: a gate that has blocked continuously without crossing again
+inside the window produces no group in the rollup at all. It shows up in `resolvesNow` and nowhere
+else. So an empty or quiet rollup NEVER means "nothing is blocking it" — check step 1 before saying
+anything of the sort.
+
+Two negatives, both checkable:
+
+- **Never page journal rows in order to count causes yourself.** The counts are served. Re-deriving
+  them spends the player's op budget on work the server already did and floods the transcript.
+- **Never sum counts across pages, and never report a windowed count as a lifetime one.** The
+  rollup's counts span every matching row inside `windowStartAt`–`windowEndAt` — quote them with
+  that window ("41 times in the last 7 days"), never as a total.
+
+## Preview-before-commit is a rule of this flow, and only that
+
+There is no server-side preview receipt: the upsert takes no token proving a preview happened, and
+the CAS revision is the only cross-call state. So the sequence above is what holds the invariant —
+not a mechanism that could refuse you. Treat it as binding anyway. A write that reaches the player's
+confirm with no preview in the conversation is a failure of this skill even if the server accepts it.
+
+## When a write's outcome is unknown
+
+An interrupted or timed-out upsert or delete may have landed. **Read the deployment first**
+(`get_radar_deployment` / `get_deployment_policy`) and report what is actually stored. A committed
+change is a success to report, not a call to repeat. Never blind-retry a write whose outcome you
+did not see.
+
+## `test_generate_deployment_grid`
+
+This one runs a **billed LLM generation** against the player's intelligence credits and writes
+thought and activity records. It is a composition aid for tuning a draft deployment — say that it
+is billed **before** invoking it, and only invoke it when the player is actually iterating on slots
+and wants to see what the resolved agent would produce. It is never a diagnostic read.
+
+## Reporting discipline
+
+- Report the preview's fields exactly as served — the section, the reason, the verdicts. Never
+  recompute or soften them.
+- Radar facts and Arena facts stay separate. Never present one policy's resolution as the other's.
+- A tool that fails is reported as failed, naming what could not be checked.
+- Be concise. Everything written here trades without asking again.

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

@@ -0,0 +1,283 @@
+---
+name: battlegrid-strategy-authoring
+description: Build a trading strategy with the player from a plain-English idea — gather evidence, lock the spec with them, compile it against the platform grammar, show them exactly what will run, and apply it only once they confirm. Also forks, tunes, restores, archives and previews existing strategies. Activate whenever the player wants to create, change, copy, retire or inspect a strategy, or describes a trading idea they want built.
+---
+
+# Strategy Authoring
+
+You are turning an idea into a strategy that will trade real money on the player's live agents.
+The whole point of this flow is that **nothing exists until they have seen what will actually
+run and said yes to it.**
+
+## The three failures this flow exists to prevent
+
+All three come from real authoring sessions, and all three were discovered only after the strategy
+was already built. None of them is allowed to happen here.
+
+1. **Built ≠ picked.** The player selected a "≥ +10%" trigger and a +5% trigger was implemented.
+   Nobody noticed until the results looked wrong. You prevent this by showing the *compiled*
+   rules next to their *locked* picks, before applying, and naming any contradiction yourself.
+2. **Silent zero-trigger.** A strategy was built that could never fire, and produced nothing for
+   days before anyone diagnosed it. You prevent this by reading the compile's own preview and the
+   per-signal preview before applying, and flagging a plan that shows no passing conditions.
+
+3. **Silent substitution.** A player asked for a strategy that triggers on the daily chart and
+   executes on the 4-hour. The grammar carries no such semantics. Instead of saying so, the flow
+   asked *what they meant by it* and offered four readings — one of which was the nearest
+   expressible thing, presented as an equal alternative rather than as a substitute. They picked
+   it, and got a confluence strategy labelled as the thing they asked for. **They had no way to
+   learn otherwise.** You prevent this by testing expressibility BEFORE the spec lock, and by
+   naming the gap in the question itself — see step 2.
+
+A strategy that reaches apply without all three checks having been made and reported is a failure
+of this skill, even if the player is happy with it.
+
+## Sequence
+
+### 1. Evidence first — never propose from the idea alone
+
+Before you propose any shape, measure: `get_regime_snapshot` (and `get_regime_history` when the
+idea depends on how we got here), then `get_coin_candles` and `get_coin_performance_history` for
+the coins in scope.
+
+If what you fetched contradicts the player's stated direction, do **not** proceed on their
+premise and do **not** silently substitute your own. Put the evidence in front of them and ask
+them to choose the direction again, with your recommendation stated in the question itself. They
+may know something you cannot measure — the point is that they choose with the contradiction
+visible.
+
+**Read each thing once.** A strategy, agent or signal log you have already fetched in this
+conversation is still in front of you — do not fetch it again unless something in this
+conversation has changed it. A re-read returns the same bytes, and both copies then ride every
+later step, so the player pays for the same payload twice and keeps paying for it. If you need a
+detail you did not keep, scroll back rather than re-fetching.
+
+### 2. Lock the spec before you build anything
+
+**First, check the ask is expressible at all — and note that you cannot know until you have looked.**
+Expressibility is a fact about the vocabulary, which step 3 discovers. So when the ask names
+anything the grammar might not carry, **do step 3 before this one** and lock the spec against what
+you found. The cues, none of them subtle:
+
+- **two timeframes in one rule** — "trigger on the daily, execute on the 4-hour"
+- **a relation between assets** — "when BTC leads and ETH lags"
+- **an ordering between events** — "after X fires, then wait for Y"
+- **anything phrased as a sequence, a delay, or a dependency**
+
+Locking first and discovering second is how the third failure happens: the form goes out while the
+gap is still invisible, so the ask arrives as a product question — *what did you mean?* — when the
+honest answer was *the grammar cannot do that*. The arc reads 1 → 2 → 3 for an ordinary ask; for
+one of these it reads 1 → 3 → 2.
+
+If the gap is real, **the question text itself names it**, and the nearest expressible option is
+labelled as the substitute it is — never as one reading among several. A player choosing between
+four equal-looking options cannot tell that none of them is what they asked for.
+
+One round of questions to the player, at most five, covering: **direction, trigger definition,
+exit policy, universe, sizing.** Put the one-line reason for each option beside it so they are
+choosing between real alternatives, not guessing.
+
+When the picks come back, restate the locked spec in one line before any build call — literally
+"Locked in. Building: …". That line is what the review is later checked against.
+
+The answered form is the record of what they picked. Do not write a second copy of the spec
+anywhere; if the two ever disagree, you have created the exact ambiguity this step removes.
+
+### 3. Discover the grammar — never guess it
+
+`list_strategy_categories` → `list_strategy_vocabulary` → `get_strategy_column_contract` and
+`get_strategy_section_template` → `list_strategy_signals`, plus
+`get_strategy_signal_definition` for each signal you intend to use.
+
+Compose sections, columns, conditions and rules **only** from vocabulary returned in this
+conversation. A field you remember from another strategy is not discovery.
+
+**Read the answer, not just the call.** Each of these returns one field that decides a composition
+question you would otherwise guess — and a refusal you would otherwise earn:
+
+- **A CREATE omits `sectionKey`.** It is derived from the section itself, so the same submitted
+  section at the same position yields the same key on every compile. Minting a `custom:<uuid>`
+  yourself on a CREATE is refused with a hint telling you to omit `sectionKey` on CREATE; on an
+  UPDATE, send back the key the compile returned. This is the one composition field whose right
+  answer is "leave it out".
+- **The `entry` axis is required on every CREATE**, all seven keys, no defaults — `trigger`,
+  `confirmTf`, `closes`, `bandAtrMultiple`, `levelSource`, `levelOffsetAtrMultiple`,
+  `validForBars`. It decides when (and for the level triggers, where) an entry is taken. The
+  `strategy-examples` skill carries the vocabulary and the one-directional legality matrix; a
+  CREATE without it is refused outright.
+- `get_strategy_column_contract` → `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` → `rankOrderings`. Present only when rank is composable on that
+  metric, already range-gated server-side — read the offered set rather than deriving one from
+  the metric's native output.
+
+For full-surface composition patterns — custom and benchmark sections, condition trees with
+verdicts and enforcement gates, weight pyramids and gate math, trade-level and
+position-management presets, worked desk-grade playbooks — activate `strategy-examples`. It
+teaches what to compose; this skill stays the authority on the flow.
+
+`derive_strategy_rule_view` belongs here, at composition time, and only here: it reports report
+membership and registry-default allocations for a draft. It does **not** return a compiled plan's
+values, so it can never stand in for the review in step 5.
+
+`simulate_aggregate_score` does **not** belong here. It is a review tool (step 5) and running it
+now answers a question about your draft, not about the plan the player will be asked to approve.
+
+### 4. Compile, and iterate on the diagnostics
+
+**An UPDATE carries only the axes that change.** The server preserves every axis you omit and
+every signal you do not name, and it re-derives the complete post-state, the dense scorecard and
+the diff itself. Restating the whole post-state is never required, changes nothing about the
+result, and the player pays for every byte of it on this call and on every later step of the
+conversation. Send the axes you are changing; send no other axis.
+
+**Three fields are not axes, and every compile requires all three:** `intentSummary`,
+`assumptions` and `coinSelection`. They describe *this call*, not the strategy, so "send no other
+axis" never reaches them — omitting one is a typed error, not a saving.
+
+`coinSelection` is the cohort the report preview renders over, so the player can read the plan
+against live values. It is non-authoritative, never persisted, and **not recoverable from
+`get_strategy`**: it is not strategy state, and no strategy has one. Do not go looking for it —
+choose it. For a single-gate edit, a short explicit list of the tickers the change is about is
+right; for a broad change, a `ranked` cohort is. Any reasonable cohort is correct, and searching
+for "the strategy's" cohort is a search that cannot end.
+
+`compile_strategy_plan` changes no strategy, agent or revision, and a failed compile has cost the
+player nothing. It is not read-only, though: a successful compile parks the plan it approved in
+server-side custody so its own apply can read it back. Compile once per reviewed payload — do not
+retry a compile that succeeded, and never fire two in parallel for the same edit.
+
+On a typed authoring error, the response names the offending path, the value it received and the
+domain it allows. Fix the payload and recompile. On advisory `mismatches[]` or a `viability` that
+is not viable, do the same.
+
+**Stop after three consecutive autonomous recompiles.** A fourth means you are guessing — show
+the player the diagnostics and ask. Never present a plan for confirmation while it still carries
+diagnostics you have not explained to them.
+
+### 5. Review — show the compiled truth, not your summary of it
+
+Everything here comes from the compile response you just received. Render:
+
+- **What will actually run.** `approvedPlan.postState.signalRules`, `approvedPlan.diff` and the
+  review columns — the rules as the server will execute them — beside the picks they locked in
+  step 2. **If any compiled rule or diff entry contradicts a locked pick, say so in words before
+  you ask for anything.** Do not make them spot it.
+- **Whether it can fire.** `reviewContext.reportPreview` is the server's own preview, rendered
+  over this compiled draft against live market. Support it with `get_coin_signal_preview` on the
+  locked universe's main coin(s).
+- **A routing what-if**, optionally, via `simulate_aggregate_score` — **after the compile, never
+  before it.** This is a calculator, not a verdict: it computes over whatever inputs you hand it,
+  so a draft-fed simulation reports on something the player is not being asked to approve. Feed it
+  the compiled values — the gate from `approvedPlan.postState.minAggregateScore`, the allocations
+  from `approvedPlan.postState.signalRules`, the per-signal scores from the preview you just read
+  — and show those inputs beside its output so a copy slip is visible on the card itself.
+
+**Flag before confirming** if the preview shows no passing conditions, the coin preview shows
+zero triggered signals, or the simulation reports `wouldRoute: false`. Any one of those means the
+plan probably never fires — ask whether to revise rather than presenting it as healthy.
+
+State the blast radius too: the bound-agent count and the open-position observation the compile
+returned, as numbers, not buried in prose.
+
+There is no backtest here and no expected-frequency figure. Do not imply one. What you have is a
+point-in-time reading, and you say so.
+
+### 6. Confirm, then apply
+
+One confirmation carrying the plan's own `confirmationSummary`, offering Apply / Revise / Cancel.
+
+On **Apply**, call `apply_strategy_plan` with two values and nothing else:
+
+- the compile's `planToken`
+- `confirm: true`
+
+There is no `plan` member, and one is rejected as an unrecognized key. The server keeps the plan your
+compile approved and reads it back, so **nothing is copied from the compile response** — the whole
+class of mis-transcription is gone rather than guarded against.
+
+`planToken` is opaque: forward it byte-for-byte exactly as received. Never retype, abbreviate or
+reconstruct it. A mangled token addresses no approved plan and is refused with the real one intact.
+
+On **Revise**, return to step 4. On **Cancel**, stop and let the token lapse.
+
+If the player types free text while the confirm form is open, that is **not** consent and not a
+cancellation. Answer what they said, then present the same plan's confirmation again, unchanged.
+Prose never triggers an apply.
+
+Do not pre-check expiry, digests, ownership, viability or quota before calling. The server is the
+only authority on all of them; your job is to react to what it returns.
+
+### 7. Lifecycle
+
+`fork_strategy`, `update_strategy_signal_rule`, `restore_strategy`, `archive_strategy` and
+`preview_strategy_report` are part of this flow.
+
+Before any destructive one, state the blast radius from the server's own fields and confirm it
+with the player:
+
+- **Archiving** — how many agents are bound, and that their configuration stays byte-identical
+  and open positions are unaffected.
+- **Tuning a single rule** — how many agents are bound, and that the change reaches every one of
+  them immediately.
+
+## When apply is refused
+
+Each of these is a specific typed code. Read it and take the cheapest correct step — never retry
+the same call blindly.
+
+- **`TOKEN_EXPIRED`** — a plan token lives five minutes and a human-paced review often outlives
+  it. Recompile, present the review again, and **ask for confirmation again.** Never apply a
+  recompiled plan on your own judgement that it matches the one they already approved; they
+  approve the plan that will actually be applied.
+- **`PLAN_APPROVAL_NOT_FOUND`** — no approved plan answers to this token. It was already applied, it
+  lapsed, or it was never issued; these are deliberately one code, because the recovery is the same
+  in each case. **Read the committed state first** with `get_strategy` — if the change is already
+  there, the apply succeeded and this is a duplicate confirmation, so report success rather than
+  rebuilding. Otherwise recompile, re-present, re-confirm.
+- **A refusal that is not about the token at all** — quota, a name collision, a bound agent that
+  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.
+- **`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.
+- **An apply whose outcome you never saw** (interrupted or timed out) — read the committed state
+  first with `get_strategy` or `list_strategies`. If it committed, report success. **Never
+  re-apply and never recompile over an unverified outcome** — a blind retry duplicates the
+  strategy or dies on the name check.
+- **A run that ended on a budget guard mid-build** — when they nudge you, recompile and re-enter
+  at the review. Never apply a plan compiled in a run that was cut short; treat it as stale.
+
+## When the grammar cannot express the ask
+
+The gate is step 2, and it is a step rather than advice for a reason: this rule lived here alone
+once, as a section after the sequence, and a real arc walked 1 → 2 → 3 straight past it.
+
+Say so, and name the exact capability that is missing — for example multi-timeframe trigger
+semantics the discovered vocabulary does not carry. Then offer the nearest thing it *can* express,
+**labelled as the substitute**, never as one option among equals.
+
+Never approximate an inexpressible ask and present it as the thing they asked for. Three things
+make that concrete, and all three have to hold:
+
+- the gap is named in the **question you put to the player**, not only in prose around it
+- the nearest expressible option says what it gives up
+- nothing is compiled for the original ask, because there is nothing to compile
+
+## Keep the strategy small enough to apply
+
+Apply carries only a token, so a large authored surface no longer blocks it. The compiled plan is
+still capped at 256,000 UTF-8 bytes, which compile enforces and reports; splitting a build into a
+lean strategy plus follow-up edits is now a choice about reviewability, not a workaround for a limit
+apply used to impose.
+
+## Reporting discipline
+
+- Report numbers exactly as the tools return them. Never recompute or re-derive.
+- Compile changes no strategy, agent or revision — it does park the plan its own apply will read.
+  Apply is the only write to the strategy itself. Say which one you are about to do.
+- A tool that fails is reported as failed. Never fill a gap with a plausible value.
+- Be concise. They are deciding whether to point real money at this.

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

@@ -0,0 +1,142 @@
+---
+name: battlegrid-strategy-doctor
+description: Diagnose an agent that is not doing what the player expected — why it has not traded, why it stopped, whether it is actually healthy — from the typed fields that carry health, then rank what would fix it with the exact lever each item needs. Read-only: it explains and recommends, and any change it proposes is applied by the flow that owns it. Activate whenever the player asks why an agent has not traded, why it stopped or is blocked, whether an agent is OK, what is wrong with a strategy's live behaviour, or asks for a check-up or a review of how an agent could be improved.
+---
+
+# Strategy Doctor
+
+The player configured an agent, pointed real money at it, and something did not happen. Your job is
+to find out what, from the fields that actually say so — and then to say what would change it, in
+terms of levers that exist.
+
+Everything here is a **read**. You have no write path, and you do not acquire one by finding a
+problem: the fix runs through the flow that owns it, with that flow's own confirms.
+
+## The five failures this flow exists to prevent
+
+1. **Diagnosing from prose.** *Cue: reaching for a journal entry's wording, or the agent's
+   overlay text, to explain a block.* The typed reason codes exist; use them. → step 2.
+2. **Pathologizing healthy.** *Cue: the reads come back clean and the answer feels too short.* An
+   agent that evaluated and correctly declined to trade is working. → step 3.
+3. **Mixing reason vocabularies.** *Cue: two different-looking codes that seem to mean the same
+   thing.* Six overlapping vocabularies describe why an evaluation ended. You read exactly one. →
+   step 2.
+4. **A private write path.** *Cue: "shall I just fix it?" once you know the answer.* → step 5.
+5. **Running the billed deployment test.** *Cue: wanting to see what the agent "would have
+   picked".* → the negatives below.
+
+## Sequence
+
+### 1. Triage from the fields that carry health
+
+Three reads, and they are not interchangeable:
+
+- **`get_agent_budget`** — the health read. `haltReason` (why it stopped, if it did),
+  `blockedReason` + `blockedSince` (the typed pipeline block currently standing, and since when),
+  and `gauges` — four guardrail meters (dailyTrades, exposure, drawdown, dailyLoss), each with a
+  server-computed `breached` flag. **Read `breached`; never compare fill against limit yourself.**
+- **`list_gate_blocks`** — its `summary[]` groups every rejection by (stage, reason) with a `count`
+  and a `latestAt`. **That `count` spans all of the agent's rows, not the requested page** — never
+  sum counts across pages.
+- **`get_agent_automation_status`** — **deployment coverage only.** Its payload is assignments and
+  assignable presets; it carries **no health verdict**. Use it to answer "is this agent deployed
+  anywhere at all" — an agent with no assignment cannot trade in Arena no matter how healthy the
+  rest reads — and never as evidence that automation is or is not "fine".
+
+### 2. Diagnose from typed sources
+
+- **The one vocabulary is `TradeEvaluationAttemptReasonCode`** — 25 members, two of them
+  `@deprecated` and historical-only (`TRADING_MODE_OFF`, `TRADING_MODE_INELIGIBLE`): if either
+  turns up, it is an old row, not a live cause, and you say so. Do not translate a code into a
+  different enum's wording, and do not try to unify the platform's overlapping reason vocabularies
+  — they describe different stages and merging them invents a cause.
+- Render every code through its display meta. A raw `SETUP_GATES` or `OPEN_POSITION_CONFLICT` on
+  screen is a system identifier leaking into an explanation.
+- **`get_agent_decision_context` is keyed by COIN**, not by agent. Use it for "why did nothing
+  happen on SOL", once you know which coin the blocks are about.
+- **`get_agent_coin_qualification` answers the forward-looking half.** The reason codes above say
+  why an agent did NOT trade in the past; this says whether a coin would route for it RIGHT NOW,
+  and which gate stops it — candidate levels, aggregate score, required-signal count, the ATR%
+  volatility floor and the agent's own required conditions, without spending an LLM call. Read the
+  four-member verdict as written: `NOT_ENFORCED` means the agent's own threshold switches the gate
+  off, `UNMEASURABLE` means the input was missing and the gate fail-opened. Neither is a pass, and
+  reporting either as "cleared" is the conflation the verdict vocabulary exists to prevent.
+- **Gate blocks link to their thought log** through `sourceThoughtLogId` — follow it with
+  `get_agent_thought_log` when the block's reason needs the evaluation behind it.
+- `get_signal_performance` / `list_signal_logs` when the question is whether the signals fired, as
+  distinct from whether the trades made money. `list_trade_outcomes` and `get_agent_journal` for
+  what did happen.
+- **`get_agent_conviction_calibration` honours `readiness`.** An `INSUFFICIENT_DATA` calibration
+  carries no win rate — report that there is not yet enough history, never a rate derived from a
+  handful of trades.
+
+**Every stated cause cites the typed reason or journal entry it came from.** "It is blocked" is not
+a diagnosis; "OPEN_POSITION_CONFLICT, 14 times, most recently 2h ago" is.
+
+### 3. Halted agents, and healthy ones
+
+**If `haltReason` is set, name the branch that actually clears it:**
+
+- **MANUAL** — resume lifts it directly.
+- **DRAWDOWN_BREACH** — clears by raising `maxCumulativeDrawdownUsd` **or** by the drawdown
+  baseline reset, then resuming.
+- **DAILY_LOSS** — clears by raising `maxDailyLossUsd` **or** by the UTC-day rollover. **The
+  baseline reset cannot clear it. Never offer it here.**
+
+In every case, say that a resume attempted while the stop is still breached is **refused by the
+server**, with the current figure against the limit.
+
+**If the reads are clean, say so.** An agent whose gauges are unbreached, whose blocks are ordinary
+no-trade verdicts, and whose deployment covers what the player expected, is working — report the
+healthy status and the ordinary reasons and stop. Do not manufacture a finding to have something to
+recommend.
+
+### 4. Improvements: ranked, and every one names its lever
+
+Present a ranked list. **Each item names the concrete thing that would apply it:**
+
+- a **strategy-rule** change → the `strategy-authoring` skill (its compile → review → confirm →
+  apply arc);
+- a **deployment or radar policy** change → the `radar-deployment` skill's tools, named;
+- a **risk-limit or budget** change → `agent-management`'s update verb, and note that it is a
+  **whole-object** write: the current limits are read and the complete object written back;
+- a **halt recovery** → the specific lever from step 3.
+
+An improvement with **no lever on this platform** is labelled as such, explicitly, and never
+presented as actionable. Rank by what would change the observed behaviour most, not by how easy it
+is to say.
+
+### 5. Close with the three-option ask
+
+One question to the player, offering exactly:
+
+1. **Explain only** — the diagnosis stands as the answer.
+2. **Apply via the named tools** — you activate the owning skill and its arc takes over, with its
+   own reads, blast-radius statements and confirms.
+3. **Draft the change for review** — you write out what would change, and nothing runs.
+
+**Applying routes through the owning flow.** You never write directly, never skip the owning
+flow's confirm, and never treat "apply" as consent for a change that flow would have asked about
+separately.
+
+## UNDETERMINED, never "no issue"
+
+If a backing tool call fails, returns nothing, or does not cover what is being asked about, report
+that item as **UNDETERMINED** and name the surface you could not check. Never convert an absence of
+data into a clean bill of health, and never let the overall verdict claim completeness when part of
+it is undetermined.
+
+## Negatives
+
+- **Never call `test_generate_deployment_grid`.** It runs a billed LLM generation against the
+  player's intelligence credits and writes thought and activity records. It is the deployment
+  flow's composition aid for tuning a draft — it is not a diagnostic read, and running it as one
+  charges the player to answer a question the journals already answer.
+- Never diagnose from the agent's own prose or overlay text where a typed field exists.
+- Never present a gate-block count as a rate, a trend, or a percentage — report it as served.
+
+## Reporting discipline
+
+- Report numbers and codes exactly as served, through their display metas.
+- Worst news first: a halt or a standing block outranks a tuning suggestion.
+- Be concise. The player wants to know what is wrong and what to do about it.