@battlegrid/mcp-server 31.2.72 → 31.2.75

package/README.md

@@ -24,6 +24,98 @@ Seeing package `31.x` alongside handshake `battlegrid@33.x` — the package **be
 
 **What this changes for you:** nothing about how you call anything. Upgrading the package no longer waits on a server deploy, and a server deploy no longer strands you on a package that names the wrong contract — reconnect and the announcement follows. **Contract breaking-change notes are no longer keyed to package versions**, since a contract move is no longer a release here; the v11-and-earlier notes below are kept as history, and the live vocabulary is always discovery.
 
+## Contract history — v92 (every section you read is the JSON the agent reads)
+
+**Breaking at v92: the section fields are reshaped, the report preview's default narrows, and its size is measured
+in characters.** v92 is the contract on top of v91. Every tool that published a section as markdown text publishes
+it as the JSON object the agent reads, and `preview_strategy_report` takes a detail level.
+
+### Reshaped output — a section is its JSON
+
+A **section read** is `{ shape: "table", section }` — `{ id, title, notes, provenance?, anchorTf, groups, columns,
+rows, addendum? }`, rows positional and every cell its raw value, each column stating its `unit`, `precision`, bar
+set (`bars`) and, on a rank column, the ranked set's `universe`, with a key absent where the column has nothing to
+say — or `{ shape: "facts", section }`, `{ id, title, facts, glossary }`. It replaces:
+
+- **`preview_strategy_report.renderedSections[]`**: `{ sectionKey, section: { title, text }, structure,
+  authoredNote }` → `{ sectionKey }` and a section read, or `{ sectionKey, shape: "skipped" }` for a row that
+  rendered nothing. A custom section's authored note is its section's `notes`.
+- **`get_market_context.sections[]`**: `{ kind, title, content, structure }` → `{ kind }` and a section read.
+- **`get_context_source_full_preview.content`** → **`read`**, a section read or `null`.
+- **`get_context_sources_preview`**: each source's `value` → **`section`**, a section read or `null`, a coin-row
+  table sampled to its first five coins.
+- **`get_signal_log.reportSections[]`**: a section read, `skipped`, or `{ sectionKey, shape: "text", title, text }`
+  — a row stored before custom sections carried a structure, kept as its agent read it.
+- **`preview_strategy_report.conditionsTableText`** and **`.tradeConditionsBlockText`** → **`gridConditions`** and
+  **`tradeConditions`**, each `{ glossary, register }`: the glossary prose and the register object the text carried
+  as one JSON line. Each is `null` where its text was.
+
+### Widened output — the register names what decided the verdict
+
+- **`decidedBy`** joins the conditions register: on each `GRID` coin and on the `TRADE` register, the key of the
+  condition the `verdict` came from, `null` when no single condition made the call. It reaches you in
+  `gridConditions.register`, `tradeConditions.register`, and the register `get_agent_prompt_context_preview` shows,
+  and the conditions glossary gains the sentence defining it.
+
+### Narrowed default, new input — `preview_strategy_report` `detail`
+
+- **`detail`** is `"concise"` (the default) or `"detailed"`. A concise preview is exactly what the agent reads.
+- **`conditionColumns`** and **`conditionOutcomes`** leave the top level. With each row's `headerBindings`
+  (`{ sectionKey, columnIndexByHeader }`) they make up **`authoring`**, served only at `"detailed"` and `null`
+  otherwise. If you read either field, ask for `"detailed"` and read it under `authoring`.
+- **`marketReadMarkers[]`** lose `resolvedName` and `resolvedValue`.
+
+### Result size in characters
+
+- **`tokenCountModel`** and **`budgetUsage.estimatedTokens`** leave the preview. **`budgetUsage.resultChars`** is
+  the exact `JSON.stringify` length of the response that carries it, its own digits included, against the cap.
+- **`list_strategy_vocabulary`** drops `budgets.estimatedTokens`, and `previewExecutionLimits.maxResultBytes` is
+  renamed **`maxResultChars`**.
+- A preview over the cap is refused with **`PREVIEW_LIMIT_EXCEEDED`** and `limit: "result_chars"`;
+  `estimated_tokens` and `mcp_result_bytes` are retired. Every preview refusal now carries its `previewErrorCode`
+  and its bound (`deadlineMs`, or `limit`, `actual` and `maximum`) in the error's details.
+- **`preview_strategy_report`**, **`get_market_context`** and **`get_context_sources_preview`** declare the cap as
+  `_meta["anthropic/maxResultSizeChars"]`, so Claude Code keeps a large result inline.
+
+Something read at v91 is reshaped or gone at v92, and a default narrows — hence the MAJOR.
+
+## Contract history — v91 (every data block an agent reads is one JSON object)
+
+**Breaking at v91: one output field is removed, and the published text that is the agent's prompt carries JSON.**
+v91 is the contract on top of v90. Every data block BattleGrid's trading agents read — the strategy's resolved
+conditions, fact sections, and the trade-decision blocks — is one JSON object naming itself with `id` and `title`.
+Instructions stay prose under their `## Title`. The tools that show you the prompt therefore show that JSON.
+
+### Removed output — something you read is gone
+
+- **`promptDataSerialization`** leaves `get_signal_log`'s owner detail. There is one serialization, so a trade
+  record stores none. `reportSections` and `missingData` are unchanged, and a trade recorded before capture still
+  serves both as `null`.
+
+### Reshaped output — the same fields, carrying JSON
+
+- **`preview_strategy_report.conditionsTableText`** is the conditions glossary as a `## Strategy Conditions
+  Glossary` instruction, then the conditions register as one JSON line: `surface: "GRID"`, and `coins[]` each with
+  `outcomes` keyed by condition and `verdict` by display name (`null` when the strategy declares no verdict). It was a
+  markdown table followed by the glossary.
+- **`preview_strategy_report.tradeConditionsBlockText`** is the trade glossary, a blank line, then the target coin's
+  register as one JSON line: `surface: "TRADE"`, `verdict` as `{ name, description }`, and `conditions[]` each with
+  `outcome`, `required`, `provisional`, `counts`, `exitRule` and the evaluator's `evidence`. It was a
+  `## STRATEGY CONDITIONS` heading, a table and evidence bullets.
+- **A fact section's text is its JSON**, `{ id, title, facts, glossary }` with `facts` keyed by label, in
+  `get_market_context.sections[].content`, `get_context_source_full_preview.content`,
+  `preview_strategy_report.renderedSections[].section.text`, and the `get_signal_log` report of trades recorded
+  from v91 on. The session field is a fact section. A table section's text is still its markdown.
+- **`get_agent_prompt_context_preview.promptSections[].content`** is each section as the agent reads it: a data
+  section's JSON, a table's included, and an instruction's prose.
+
+### Widened enum
+
+- **`get_agent_prompt_context_preview.promptSections[].kind`** gains `strategy-conditions-glossary`, the instruction
+  read before the conditions register. The market-context reads exclude it, as they exclude the register.
+
+Something read at v90 is gone or reshaped at v91 — hence the MAJOR.
+
 ## Contract history — v90 (Arena and radar deployments join the draft lifecycle)
 
 **Breaking at v90: input is refused and reshaped, output is reshaped, five error codes are removed.** v90 is the
@@ -2820,6 +2912,11 @@ you reach over MCP:
 > request; `skills/EXPORT.json` records a hash per file and `src/__tests__/skill-provenance.test.ts`
 > fails CI on a hand edit. Change the skill upstream and let the export lane bring it here.
 
+A client connected to BattleGrid's remote server directly receives its `initialize` instructions:
+the rules that span tools and one routing card per workflow, each naming the `battlegrid-*` skill
+above that holds the full procedure. This proxy does not relay those instructions; the skills
+installed beside it carry the same workflows.
+
 ## License
 
 [MIT](LICENSE)

package/dist/index.d.ts

@@ -49,7 +49,7 @@ import { type Implementation, type Prompt, type Resource } from '@modelcontextpr
  * being asked. Move it for a change to THIS package — a proxy fix, a dependency bump, a docs
  * correction. Never move it to track the server.
  */
-export declare const PACKAGE_VERSION = "31.2.72";
+export declare const PACKAGE_VERSION = "31.2.75";
 export declare const DEFAULT_URL = "https://mcp.battlegrid.trade/mcp";
 export interface EnvConfig {
     apiKeys: string[];

package/dist/index.js

@@ -52,7 +52,7 @@ import { ListToolsRequestSchema, CallToolRequestSchema, ListPromptsRequestSchema
  * being asked. Move it for a change to THIS package — a proxy fix, a dependency bump, a docs
  * correction. Never move it to track the server.
  */
-export const PACKAGE_VERSION = '31.2.72';
+export const PACKAGE_VERSION = '31.2.75';
 export const DEFAULT_URL = 'https://mcp.battlegrid.trade/mcp';
 const MAX_RETRIES = 3;
 const RETRY_DELAYS_MS = [2000, 4000, 8000];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@battlegrid/mcp-server",
-  "version": "31.2.72",
+  "version": "31.2.75",
   "description": "BattleGrid MCP server — play crypto prediction games from AI agents",
   "type": "module",
   "main": "dist/index.js",

package/skills/EXPORT.json

@@ -1,18 +1,18 @@
 {
   "generator": "battlegrid-app/server/scripts/export-mcp-skills.mjs",
-  "contractVersion": "88.1.0",
+  "contractVersion": "92.0.0",
   "files": {
-    "battlegrid-agent-management/SKILL.md": "b2f04d76480de2f9fdbd00f8cb25610d2b72fcaa4f87ca57a09bd9ffc78fdbba",
-    "battlegrid-arena-play/SKILL.md": "4cfaa92a8d0dcaf477b227abd774e7aa8642c185d72108dfd401be0cf8aecd7f",
-    "battlegrid-market-analysis/SKILL.md": "3a9943de9f482a8230fb2983efd2f2d8b8c17d49c242e49b68e7243c20c3aa7b",
-    "battlegrid-radar-deployment/SKILL.md": "a624807c9d1f0e1fa650592bfbbdab228d75098d66a9c2d4d3cd3f85e5d3796c",
-    "battlegrid-strategy-authoring/SKILL.md": "a5066740d7d57f095545fd812b0228a8eef6e3b08c87047596a0e1639ae4971d",
+    "battlegrid-agent-management/SKILL.md": "e5ffab64e6a369d5c783aed2b1c7c513b01b870063fd859c9cc4d9fc45d30aac",
+    "battlegrid-arena-play/SKILL.md": "01b2192c19b93b2315ff1a2b512ee0bcb7fd809c7d77fbbd93307fe2f45924a3",
+    "battlegrid-market-analysis/SKILL.md": "875bda71dd766ad06ac8e508679bcd3400a600cf74d2eac6c922dbe23175f325",
+    "battlegrid-radar-deployment/SKILL.md": "aaa4d13d32d470582d4bab0dc71594d4adf6b665bf45ee3384ee794dd8f82ba4",
+    "battlegrid-strategy-authoring/SKILL.md": "d4c5c87d9306193be8be77b1ade4938bbbc8805d66bc5267c00c2a8db156a92e",
     "battlegrid-strategy-doctor/SKILL.md": "14f20bff9e2b5a59d11634fe3615b1298d672d5e2eba06d3dc8698b571b3bee3",
-    "battlegrid-strategy-examples/SKILL.md": "7ec80099efe3a923e1a701703eba5edbbe3ce044628273c806dfd688f2fd715c",
-    "battlegrid-strategy-examples/references/playbooks.md": "63aa07f3d55f97e53b2bf6401528807ab23bd093a4bbc37e598158249db24a59",
+    "battlegrid-strategy-examples/SKILL.md": "d49ed36a864d1ead53c942979639d331b2bf375b50fffd745548a0acde39d641",
+    "battlegrid-strategy-examples/references/playbooks.md": "9e89b5cc8d80fc27bc331862fdc2403c26b36131b132614782c8425df74bcd28",
     "battlegrid-strategy-examples/references/recipes.md": "61382acdd295fa159f055b787ba501f1c015f383f59a6714a973057f10de611f",
     "battlegrid-strategy-examples/references/tradingview-ports.md": "2b13adbc137178955edcca31b6ab40c01c745a932a0750b91db8820c736700bb",
-    "battlegrid-trade-analysis/SKILL.md": "f5d817022ab912f00e9c17ffa720a7599f6e6fa4b806d873fe5e7520c51a8dcd",
-    "battlegrid-trade-proposal/SKILL.md": "9bf7b7648fb009db118a3a428b15abf38df5ba56a2ef4c8a4eae3d979bdc8bcb"
+    "battlegrid-trade-analysis/SKILL.md": "a1e666ca03bd641413096ed14806f101354f4e913e005faad6026a486143af0c",
+    "battlegrid-trade-proposal/SKILL.md": "d207a30065c17e13efaf5391805e5603e6956633cba5d0a1ff60e276518d9696"
   }
 }

package/skills/battlegrid-agent-management/SKILL.md

@@ -84,7 +84,8 @@ omit `agentId` and send `draftVersion: 0` on the first call, then reuse the id i
 `{ strategyId }`, all four required to create, plus TRADING_CONFIG with every agent-owned field —
 or no TRADING_CONFIG at all, to take the platform seed. The build then survives a refresh, lists in
 the Agents Hub as *not yet created*, and opens on the create screen, where **the player's own
-Create creates it**. Staging creates nothing and spends no slot.
+Create creates it**. Staging creates nothing and spends no slot. The avatar is minted by the server
+at creation — there is no avatar to stage.
 
 **Then read it, confirm it, and commit it.** `get_agent_draft` serves the draft, its
 `draftVersion`, a `committedRevision` of `null` and the diagnostics: a missing or invalid axis is
@@ -110,6 +111,11 @@ Profile → Wallet tab path instead, because no control renders there. **Create
 way**: the consent gates entering a game, never commissioning one. A `true` flag is consent alone
 and not readiness — the pipeline's own refusal at the fee is the authority.
 
+**When the mandate is trading, the agent needs a trading wallet.** `get_account_state` reports
+`tradingWalletProvisioned`; the wallet is provisioned in the web app, where its key is signed
+locally in the browser, and no tool provisions it. Without one the agent can be created but cannot
+place an order — say so with the create, never after the first refused trade.
+
 ### 3. Stage, read, confirm, commit — every change goes through the draft
 
 Before proposing any change to an existing agent, `get_agent_draft`. **A draft means the player is
@@ -242,7 +248,9 @@ keys). The commit holds the configuration to the same risk rules the agent form'
   the P&L. It carries a schema-level `confirm: true`, so present the position, its unrealized
   P&L and its protections, and confirm before calling. An exchange rejection comes back as a typed
   trading error — report it; a success means the close order was *accepted*.
-- **`override_agent_protection`** moves the effective stop. Its confirm must say, in words, that
+- **`override_agent_protection`** moves the effective stop — the stop-loss only; take-profit is not
+  overridable here. It names the stop it replaces by `effectiveStopLossOrderId`, which
+  `get_position_audit_history` serves. Its confirm must say, in words, that
   the change **moves the stop outside the platform's protective ratchet** — that is exactly what
   the tool is for — and name the direction: whether the new level sits further from or closer to
   price than the one the platform is holding. Present the current protection first, then the

package/skills/battlegrid-arena-play/SKILL.md

@@ -59,7 +59,11 @@ the enablement path there.
 A direct submission carries `grid`, `reasoning`, `confidenceScore`, `modelName` and
 `pickReasoning`, and all of them are required.
 
-- **Exactly one cell is captain** (2× multiplier).
+- **Exactly one cell is captain.** The session's preset sets what that is worth: a correct captain's
+  points are multiplied by its `captainMultiplier`, and a wrong captain's penalty by its
+  `captainWrongPenaltyMultiplier` — both published by `list_game_presets`, and different per preset.
+  Read them rather than assuming a number, and captain the pick you are most confident in among
+  those with a move worth amplifying.
 - **`pickReasoning` carries one entry per grid cell — every cell, no coin twice.** Compose it
   correctly because it is yours to compose, not because something downstream will catch it: the
   boundary refuses an incomplete payload before the fee moves, and leaning on that check means
@@ -98,12 +102,15 @@ reasoning as the player's, and the attribution is part of what was scored.
 
 ### 5. After settlement
 
+- A session moves PENDING → LIVE → RESOLVING → SETTLED. Two states sit off that path: CANCELLED
+  (entry fees refunded) and SETTLEMENT_QUARANTINED (settlement exhausted its retries and awaits an
+  operator). Either one is the answer — report it as the status.
 - `get_market_grid_results` — available only once the session is SETTLED. Before that it returns a
   typed CONFLICT naming the current status: **report it and stop**. Do not poll it in a loop; the
   op budget is finite and a settling session is not a failure.
-- `get_mcp_reasoning_journal` on request — the reasoning, confidence and picks as recorded at
-  submit. Compare the outcome against what was actually reasoned, and say where the reasoning was
-  wrong.
+- `get_mcp_reasoning_journal` on request — the player's own submission: the reasoning, confidence
+  and picks as recorded at submit. Compare the outcome against what was actually reasoned, and say
+  where the reasoning was wrong. An agent's record is a different journal, `get_agent_journal`.
 
 ## Refusals, and what each one means
 

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

@@ -20,7 +20,10 @@ Run these in order. Skip a step only when the player's question makes it irrelev
 
 1. **Regime.** `get_regime_snapshot` for the current read. `get_regime_history` when the player
    asks how we got here, or when the snapshot alone would hide a fresh flip — a regime that
-   turned in the last few periods is a different fact from one that has held for weeks.
+   turned in the last few periods is a different fact from one that has held for weeks. Read the
+   snapshot's evidence before its label: a label the hysteresis buffer is **holding** is the
+   previous bar's, not this bar's, and conviction names which rule matched, not how comfortably —
+   the margins to each gate say how close the read is to turning.
 2. **Market context.** `get_market_context` — this carries the breadth, funding and open-interest
    picture. Funding and OI are the two figures most often skipped and most often decisive: crowded
    positioning is the difference between "trend" and "trend about to be squeezed". Report both.
@@ -28,9 +31,11 @@ Run these in order. Skip a step only when the player's question makes it irrelev
    "strength in majors". A laggard list is as informative as a leader list and is usually omitted.
 3b. **Many coins on the same indicators — one call, not one per coin.** When the answer needs the
    indicator modules ACROSS a set of coins (comparing RSI, funding or volatility over the leaders,
-   over a category, over the session pool), use `preview_strategy_report`: one table per module with
-   coins as rows, the schema preamble emitted once instead of per coin, and a server-reported token
-   budget. Ask `list_strategy_categories` for the section catalogue and pass the sections you want,
+   over a category, over the session pool), use `preview_strategy_report`: one section JSON per
+   module with coins as rows, each column described once instead of per coin, and the exact size of
+   the response it served (`budgetUsage.resultChars`). The default `detail: "concise"` is the read;
+   `"detailed"` adds only the authoring contract a strategy builder needs. Ask
+   `list_strategy_categories` for the section catalogue and pass the sections you want,
    each as `{ "kind": "platform", "sectionKey": "includeRsi" }`, inside
    `source: { "kind": "FIELDS", "timeframe": …, "sections": [ … ] }` — no authoring vocabulary is
    needed. Use `{ "mode": "ranked", "limit": N }` as the coin selection when you have no explicit

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

@@ -16,6 +16,11 @@ Radar (per coin) and Arena deployment (per preset) are **separate bounded contex
 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.
 
+**Deployments are the autonomous trading switches.** An agent has no trading mode of its own: it
+trades a coin on its own only where a Radar policy puts it on duty, and a proposal the player
+approves needs no deployment. An Arena deployment enters an agent into a preset's sessions and grants
+**no** trade permission — to have an agent trade a coin on its own, deploy it on Radar.
+
 ## The five failures this flow exists to prevent
 
 1. **A write with no fresh preview.** *Cue: any `commit_radar_deployment_draft`,
@@ -69,6 +74,19 @@ Then read what exists:
 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.
 
+**In a conversation the radar builder hosts** — your context names the radar builder and a coin id —
+the player's builder is open on that coin whether or not a draft exists yet. Stage every change into
+that coin's draft, naming that `coinId`; it lands in their builder as a proposal. Their own Save
+commits it; commit it yourself only when they explicitly confirm through `ask_user`, after the
+preview this flow requires. The builder's state — its rules, the default agent, who is on duty now —
+arrives as the turn's attached scope. An axis their form rewrote after your proposal is their answer:
+propose it again only on their word.
+
+**In a conversation the Arena deploy editor hosts** — your context names the Arena deploy editor and a
+preset id — the same, for that arena's deployment draft, naming that `presetId`. Its scope carries the
+rules, the default agent and what the next session resolves to, marked `simulated` while the player
+is test-routing a regime. Never carry a fact from a radar conversation into it, or the reverse.
+
 ### 2. Stage the change, then preview exactly what would be written
 
 **Radar** — the change goes into the player's draft of the coin, never straight to the policy:
@@ -82,11 +100,18 @@ If the question is *why did my radar agent not fire*, do not start from the jour
    `agentRegimeTimeframe`. Staging writes nothing live and shows the change in the player's builder as
    a proposal. A refusal naming axes means the player changed them after your read: read again and
    propose against what they now have.
-2. `preview_radar_resolution` with `request: { kind: "DRAFT", draftVersion }` at the version staging
-   returned. It composes the draft over the deployed policy **exactly as the commit will write it**.
-
-To try a slot set without touching the draft, preview `{ kind: "SLOTS", slots }` — it certifies
-nothing and cannot be committed.
+2. `get_radar_deployment_draft` — the draft as it now stands: its `draftVersion`, the
+   `committedRevision` it would be published over (null for a coin with no policy yet), the diff
+   against the deployed policy, the `diagnostics` a commit would refuse, and the `impact` — who goes
+   on duty, whether it trades once committed, and for a first deployment the coin cap
+   (`admission.coinCapReached` true means the commit will be refused until a coin is un-deployed).
+   Do not confirm a draft whose diagnostics carry an error: stage a fix.
+3. `preview_radar_resolution` with `request: { kind: "DRAFT", draftVersion }` at the version that read
+   returned. It composes the draft over the deployed policy **exactly as the commit will write it**,
+   and refuses a draft no longer at that version with `DRAFT_VERSION_MOVED`.
+
+To try a slot set without touching the draft, preview `{ kind: "SLOTS", slots }` — it resolves
+explicit slots and nothing can commit it.
 
 **Arena** — the same shape, keyed on `presetId`:
 
@@ -94,8 +119,10 @@ nothing and cannot be committed.
    draft) and only the axes you are changing, each WHOLE: `RULES` (the complete ordered rule list —
    first is highest priority; a rule's regime condition names a set), `DEFAULT_SLOT` (the catch-all, or null for none)
    and `REGIME_ANCHOR` (the anchor override, or null to inherit the arena's). Pausing is never staged.
-2. `preview_deployment_resolution` with `request: { kind: "DRAFT", draftVersion }` at the version
-   staging returned.
+2. `get_deployment_policy_draft` — its `draftVersion`, `committedRevision`, diff, `diagnostics` and
+   `impact` (the next session's resolution and whether it will play), exactly as for Radar.
+3. `preview_deployment_resolution` with `request: { kind: "DRAFT", draftVersion }` at the version
+   that read returned.
 
 A draft that would hold no rule and no catch-all is a withdrawal, which a commit never does — that is
 `delete_deployment_policy` (step 4).
@@ -110,7 +137,8 @@ and priority that put it on duty, its regime reading at its own `regimeTimeframe
 qualification verdict and its close clock — and `readings`, one entry per on-duty agent in the same
 order: what that agent reads on the coin right now (below). For **Arena**: which agent goes on duty,
 which slot matched and at what priority, the regime and conviction used, and the qualification
-verdict. **Render `section` as the server sends it — never re-derive it, and never pick, rank or drop
+verdict, under the resolution's `status` as served — RESOLVED (an agent plays the next session),
+IDLE (the rules ran and none matched), WARMING, NO_SESSION or PAUSED. **Render `section` as the server sends it — never re-derive it, and never pick, rank or drop
 rows yourself.** 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. `enabledAfterCommit` says whether
 the policy will play once committed — a paused policy stays paused, and a first Arena deployment
@@ -123,8 +151,8 @@ resolve.
 **A Radar preview refuses an agent the scan cannot read on the coin.** Every slot agent, on duty now
 or not, must have every condition the radar acts on — its required conditions, the ones carrying a
 verdict, its exit rules, and every condition they reference — readable by the radar scan on this
-coin. When one is not, the preview itself is refused, issues no certificate, and nothing can be
-committed: `CONDITION_UNREADABLE_BY_RADAR_SCAN`, whose `details.context.reachReason` says why
+coin. When one is not, the preview itself is refused, and the draft read reports the same refusal in
+its diagnostics: `CONDITION_UNREADABLE_BY_RADAR_SCAN`, whose `details.context.reachReason` says why
 (`INSTRUMENT` — the market-data profile of the coin, or of a benchmark section's own instrument, carries
 no such data, or the market-data service publishes no profile for it at all: the refusal names the kind
 of data the profile lacks, or says there is none; `AGENT_TIMEFRAME` — the agent has no such rung;
@@ -175,28 +203,32 @@ the reason — and **names what the change does to the stored policy**, read fro
 
 Then:
 
-- **Radar** → `commit_radar_deployment_draft({ coinId, previewToken, confirm: true })`, with the
-  `previewToken` the **live** DRAFT preview returned — no `simulatedRegime`, within five minutes. The
-  draft ends when it commits.
-- **Arena** → `commit_deployment_policy_draft({ presetId, previewToken, confirm: true })`, the same
-  way: the live DRAFT preview's token, within five minutes. The draft ends when it commits.
+- **Radar** → `commit_radar_deployment_draft({ request: { coinId, draftVersion, expectedRevision } })`,
+  naming exactly the `draftVersion` and `committedRevision` your draft read returned — the version
+  your preview resolved. Ask with `ask_user` first and commit only after an explicit confirming pick.
+  The axes it published leave the draft.
+- **Arena** → `commit_deployment_policy_draft({ request: { presetId, draftVersion, expectedRevision } })`,
+  the same way.
 
-**On a typed CONFLICT: re-read, re-preview, re-confirm.** In that order, and all three. The draft or
-the policy changed under you, so the state your preview resolved and the radius you stated are both
-stale. A certificate is bound to the draft version, the deployment and its content, so a retry
-with the old one is refused again — only a fresh preview earns a new one.
+**On `DRAFT_VERSION_MOVED` or a CONFLICT: re-read, re-preview, re-confirm.** In that order, and all
+three. The draft or the deployment changed under you, so the state your preview resolved and the
+radius you stated are both stale. A retry with a bumped number commits something the player was not
+shown — the server refuses a version or revision you did not read, and the confirmation is yours to
+ask for again.
 
 ### 4. Pause, resume, discard, delete
 
 **Pause a coin's Radar** → `pause_radar_deployment({ coinId })`. No preview and no revision: stopping
-never waits on a read. The player's draft is kept. **Resume** → preview the deployed policy with
-`request: { kind: "COMMITTED" }`, tell the player which agents will go on duty again, and on their word
-`resume_radar_deployment({ coinId, previewToken, confirm: true })` with the token that preview
-returned.
+never waits on a read. The player's draft keeps its content and is re-based onto the paused revision.
+**Resume** → preview the deployed policy with `request: { kind: "COMMITTED" }`, tell the player which
+agents will go on duty again, and on their word
+`resume_radar_deployment({ coinId, expectedPolicyId, expectedRevision })` naming the `policyId` and
+`revision` that preview returned — so it re-arms the policy the player was shown, or nothing.
 
 **Pause an arena** → `pause_deployment_policy({ presetId })`, and **resume** it the Radar way: preview
-`{ kind: "COMMITTED" }`, then `resume_deployment_policy({ presetId, previewToken, confirm: true })` on
-the player's word. Both touch only the pause, never the rules or the player's draft.
+`{ kind: "COMMITTED" }`, then `resume_deployment_policy({ presetId, expectedPolicyId, expectedRevision })`
+with the pair it returned, on the player's word. Both touch only the pause, never the rules; the
+player's draft keeps its content.
 
 **Entries already made stand.** A pause or a delete of an arena returns `openEntries` — the sessions
 the player's agent already entered that have not locked, each with its lock time and entry fee. They
@@ -204,21 +236,23 @@ play out unless the player cancels them. Name each one, ask whether to cancel it
 `cancel_market_grid_submission({ sessionId, confirm: true })` only for the entries they pick — the
 same cancellation and refund as their own Cancel button. Say nothing is cancelled when they decline.
 
-**Discard a draft** only on the player's word. Call `discard_radar_deployment_draft` or
-`discard_deployment_policy_draft` with
-`confirm: false` first: the answer names what the draft holds, its version, and when and from where
-it was last written. Tell the player, ask, and call with `confirm: true` and `expectedVersion` set to
-**the version you were shown**. If the draft moved since, nothing is removed and the answer names what
-it now holds — show them again.
+**Discard a draft** only on the player's word. Read it first and tell the player what it holds and
+when and from where it was last written; then
+`discard_radar_deployment_draft({ request: { coinId, draftVersion } })` or
+`discard_deployment_policy_draft({ request: { presetId, draftVersion } })` at **the version you read**.
+If the draft moved since, it is refused with `DRAFT_VERSION_MOVED` and nothing is removed — read it
+again and show them.
 
 **Deletes** — `delete_radar_deployment` / `delete_deployment_policy` remove the **entire** policy —
 every slot and condition — and revoke the standing authority. Un-deploying **also ends the player's
 draft** of the coin or the arena. 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**, which supplies the
-`expectedRevision` the delete carries — and for Arena the `expectedPolicyId` beside it.
+`expectedPolicyId` and `expectedRevision` both deletes carry — a policy removed and redeployed since
+your read is refused rather than removed.
 
 State what stops, from that read: which agents were on duty (every row of `resolvesNow.onDuty`) or
-eligible, what the policy was firing on, and that the slots are not recoverable. Both tools carry a schema-level `confirm: true`.
+eligible, what the policy was firing on, and that the slots are not recoverable — and delete only after
+an explicit confirming pick.
 
 **If the player wants to stop trading without losing the slots, that is not a delete** — it is
 `pause_radar_deployment` for Radar and `pause_deployment_policy` for Arena. Offer that
@@ -306,15 +340,14 @@ Three negatives, all checkable:
   last decision a row names, `get_radar_close_decisions` for any other — and quote it as stored;
   never recompute it.
 
-## Preview-before-commit: enforced for both
+## Preview-before-commit: your discipline, fenced by the server
 
-A deployment arms only with a certificate. `commit_radar_deployment_draft` and
-`commit_deployment_policy_draft` take the certificate a live preview of that draft returned, and
-`resume_radar_deployment` and `resume_deployment_policy` one from a live preview of the deployed
-policy. Each is bound to your credential, the player, the coin or arena, the subject previewed, the
-deployment and its revision, the draft version and the content the preview resolved, and expires after
-five minutes. A simulated preview returns none. So a commit of anything the player was not shown is
-refused by the server — but the player's confirmation is still yours to ask for, against the preview.
+The preview card and the confirming pick are yours to show and ask for, every time. What the server
+enforces is the fence under them: a commit names the draft version and committed revision its read
+returned, and a resume or a delete names the deployment and revision it read. A draft that moved after
+your preview is refused with `DRAFT_VERSION_MOVED`; a deployment whose revision moved, or that was
+withdrawn and redeployed, is refused as a CONFLICT. So a commit never publishes a draft version your
+preview did not resolve — provided you previewed the version you commit.
 
 ## When a write's outcome is unknown
 

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

@@ -104,7 +104,9 @@ anywhere; if the two ever disagree, you have created the exact ambiguity this st
 `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.
+conversation. A field you remember from another strategy is not discovery. A signal's availability
+at a timeframe is structural: it says the signal can be computed there, not that live data is
+flowing or that it will trigger.
 
 **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:
@@ -144,7 +146,8 @@ 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 sections and rows you are about to stage. It reads
-no draft and no strategy, so it can never stand in for the review in step 5.
+no draft and no strategy, so it can never stand in for the review in step 5. Its suggestions and
+reset-to-default choices change only what you stage next — no tool applies one on its own.
 
 `simulate_aggregate_score` does **not** belong here. It is a review tool (step 5), and running it
 now answers a question about rows you have not staged, not about the draft the player will be
@@ -224,7 +227,13 @@ Once the stage's diagnostics carry nothing you cannot explain, read the draft wi
   the commit's own: the player is approving all of it, not only what you proposed.
 - **Whether it can fire.** `preview_strategy_report` with
   `source: { "kind": "DRAFT", strategyId, draftVersion }`, at the version the read returned,
-  renders the draft against live market composed exactly as its commit would compose it. Support it
+  renders the draft against live market composed exactly as its commit would compose it. Its default
+  `detail: "concise"` is exactly what the agent will read — the sections, each surface's conditions
+  register with every coin's verdict, and the verdict tally; ask for `"detailed"` only when you need
+  each coin's full evaluation or the addressable headers (`authoring`). A preview is bounded by a
+  deadline and a result-character cap, both served by discovery as `previewExecutionLimits`
+  (`deadlineMs`, `maxResultChars`); one over either is refused whole, never truncated — narrow the
+  cohort and preview again. Support it
   with `get_coin_signal_preview` on the locked universe's main coin(s). The preview's
   `coinSelection` is its cohort, never strategy state: no strategy has one and `get_strategy` will
   not return one, so choose it — a short explicit list of the tickers the change is about for a
@@ -246,8 +255,9 @@ revise rather than presenting it as healthy.
 - `operation` — CREATE, UPDATE or RESTORE. A RESTORE is a draft over an archived strategy: say
   that committing it also restores the strategy and moves its bound agents, by count, from
   ORPHANED to BOUND.
-- `boundAgentCount`, `openPositionCount` and `timeframeChanged`. A change to signal rules reaches
-  every bound agent the moment it commits — say so.
+- `boundAgentCount`, `openPositionCount` and `timeframeChanged`. A committed change reaches every
+  bound agent the moment it commits, while a position already open keeps the exit rules it opened
+  under — say so.
 - `admission` — for a create draft or an archived strategy, the quota and whether the name is
   free. It is advisory: the commit decides.
 - `capital` — each bound agent the drafted stop band would leave unable to place an order, with its
@@ -319,9 +329,13 @@ verbs writes content.
   commit does, and a full quota or a name already in use is refused there.
 - **Archiving** — `archive_strategy` with the `strategyId` and the `expectedRevision` you read.
   State how many agents are bound, that their configuration stays byte-identical, that open
-  positions are unaffected and that the player's draft is kept.
-- **Restoring** — `restore_strategy` with the `strategyId` and `expectedRevision` brings back
-  unchanged, already-viable content and keeps the player's draft. Content that is not viable is
+  positions are unaffected and that the player's draft is kept, re-based onto the revision the
+  archive produces.
+- **Restoring** — find the archived strategy with `list_strategies` and `get_strategy` with
+  `includeInactive: true`, which add the player's own strategies in any state; another player's
+  PRIVATE strategy stays hidden either way. `restore_strategy` with the `strategyId` and
+  `expectedRevision` brings back unchanged, already-viable content and keeps the player's draft,
+  re-based onto the restored revision. Content that is not viable is
   refused with `REPAIR_REQUIRED` and stays archived: stage the repair into the strategy's draft and
   commit it — that commit restores it, and its read says `operation: RESTORE`.
 

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

@@ -12,8 +12,8 @@ shapes are binding in the sense that matters — they are checked, not merely as
 elsewhere in this file are not covered by that gate, and vocabulary moves with deploys, so discovery
 in the conversation stays the authority — prefer what `list_strategy_vocabulary`,
 `get_strategy_column_contract`, and `get_strategy_signal_definition` return over anything
-printed here, and read exact headers from a preview's `conditionColumns` before conditioning on
-them.
+printed here, and read exact headers from a `detail: "detailed"` preview's
+`authoring.conditionColumns` before conditioning on them.
 
 ## The full-power checklist
 
@@ -69,8 +69,8 @@ things you do depends on the operation: on a **CREATE, omit `sectionKey` entirel
 is refused, since a new strategy owns no custom sections yet; on an **UPDATE or RESTORE, send back
 the keys `get_strategy` returned** for the sections you are keeping, and omit it on a section you
 add. Either way you never invent one. To section-qualify a duplicated header, read the key from a
-preview's `conditionColumns` or from the qualified candidates a `CONDITION_COLUMN_AMBIGUOUS`
-refusal offers.
+`detail: "detailed"` preview's `authoring.conditionColumns` or from the qualified candidates a
+`CONDITION_COLUMN_AMBIGUOUS` refusal offers.
 
 **Event columns print only on their event.** `MACD_cross` and `EMA5_13` (Bullish/Bearish) carry a
 value on the crossing bar and are null on every other one, which reads as UNRESOLVED. Use an event
@@ -145,7 +145,7 @@ decide it (TRUE once `atLeast` bars read TRUE, FALSE once the rest can no longer
 UNRESOLVED.
 
 What a header admits is SERVED, never guessed: every column in the strategy's report catalog
-(`preview_strategy_report` → `conditionColumns[].outputs[].conditionHold`, and each scalar metric in
+(`preview_strategy_report` at `detail: "detailed"` → `authoring.conditionColumns[].outputs[].conditionHold`, and each scalar metric in
 the vocabulary) carries `{ timeframe, maxWindow, maxAtLeast, refusal }` — the timeframe it counts,
 the largest `of`, the largest `atLeast`, and, when it admits only Once, why. `maxWindow` is the
 history the store keeps for that column, less the column's own lookback and warm-up. A hold past

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

@@ -101,10 +101,10 @@ giveback 30 buffer 0.15; timeDecay ON aggressive (45/15, 15→60, stale 30).
 
 ## Using a playbook
 
-Discover → confirm headers (`get_strategy_column_contract`, or one `preview_strategy_report`
-whose `conditionColumns` lists every addressable header with operators and vocabulary) →
-calibrate literals against the previewed live values → stage the draft and fix what its
-diagnostics name → read it back and review the drafted rule rows, then the draft's own report
-preview — condition outcomes, verdict tally, and `marketReadMarkers` (fix `unknown` / `ambiguous`
-markers) → commit per the strategy-authoring flow. Coin selection is call context, not strategy
+Discover → confirm headers (`get_strategy_column_contract`, or one `preview_strategy_report` at
+`detail: "detailed"`, whose `authoring.conditionColumns` lists every addressable header with
+operators and vocabulary) → calibrate literals against the previewed live values → stage the draft
+and fix what its diagnostics name → read it back and review the drafted rule rows, then the draft's
+own report preview — the conditions register (`gridConditions`), verdict tally, and
+`marketReadMarkers` (fix `unknown` / `ambiguous` markers) → commit per the strategy-authoring flow. Coin selection is call context, not strategy
 state: explicit tickers for focused work, `ranked` (with an optional category) for scanning books.

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

@@ -33,7 +33,15 @@ Not "what were its returns" — whether it did *the thing it was told to do*.
   at its own `strategyRevision`, and judging it against the strategy's current revision measures it
   by rules it is not running.
 - `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_trade_outcome_by_decision` / `get_trade_chart` when a specific trade needs explaining. A
+  measurable trade's `tradeExcursion` reads in R: `mfeR` and `maeR` (the best and worst it reached),
+  `exitR`, and `giveBackR` (what it surrendered between its peak and the close). `exitEfficiency` is
+  a union — branch on its `state` before reading `efficiencyPercent`. All of them are gross of
+  costs; `netPnl` is the after-fee figure.
+- The record around the trades: `get_agent_game_history` and `get_user_agent_game_history` (Market
+  Grid results, one agent or all), `get_agent_thought_log` and `get_user_thought_log` (the
+  reasoning), `get_agent_activity_feed` and `get_user_activity_feed` (what happened), and
+  `get_agent_explorer` for where the agent stands among public agents.
 - `get_signal_performance` when the question is whether the agent's signals are working, as
   distinct from whether its trades made money.
 
@@ -43,9 +51,16 @@ 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.
+- `list_user_active_positions` for everything at once: it carries the live mark and P&L
+  (`markPrice`, `unrealizedPnlUsd`, `roePct`) — check `pricingStatus` and `generatedAtMs` before
+  calling a mark current. `list_session_agent_positions` is the same view for one Market Grid
+  session. `get_agent_open_positions` is an entry-only view with no live mark: never measure a
+  distance to a trigger from it.
+- For each open position, report its protections **and how far the live mark sits from each
+  trigger** — a stop is a number the player cannot act on; "3.1% from the stop" is one they can.
+- `get_decision_order_attribution` maps an executed order back to the decision that placed it.
+  `get_open_orders` and `get_order_status` read the exchange directly — slower, and they fail when
+  the exchange is unreachable; report that as UNDETERMINED, never as no orders.
 - `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.

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

@@ -36,6 +36,7 @@ re-sorts a list, re-derives a verdict, or approves on the player's behalf.
 
 - `scan_agent_coins` for the agent. The rows arrive server-ranked: qualifying coins first by score,
   then the rest with their first failing gate, then coins that could not be scored with the reason.
+  The scan reads the agent's gates and spends no LLM call.
 - Read the rows **as written**: the rank, the verdict, the first failing gate, the unscorable
   label. Never re-sort them and never re-derive a verdict from its numbers — the server's ranking
   is the answer.
@@ -118,3 +119,6 @@ trade.
 - Never accept because the conviction reads high, because the scan ranked the coin first, or
   because the player asked you to "find a trade" — finding is not approving. `get_entry_decision`
   re-reads the row if the conversation moved on before they answered.
+- Only a conversational decision awaits the player: radar fires and arena challenge reactions
+  execute on their own. `list_entry_decisions` with `status: PENDING` lists the ones still waiting
+  for an agent.