@battlegrid/mcp-server 31.2.46 → 31.2.49

package/README.md

@@ -24,6 +24,110 @@ 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 — v68.1 (Arena regime sets)
+
+Purely additive in schema, with **one refusal behind unchanged ones.** An Arena rule's regime condition
+is a SET in the draft, as it always was in the committed deployment: one rule can fire in several
+regimes, instead of one rule per regime.
+
+### Wider input — `stage_deployment_policy_draft`
+
+- **A rule's `regimes` may name several regimes**, where the draft capped it at one. The set is stored in
+  the selectable-regime order, so a staged `[VOLATILE, BULL_EXPANSION]` reads back
+  `[BULL_EXPANSION, VOLATILE]`. A regime named twice is refused.
+
+### Wider output — `get_deployment_policy_draft`
+
+- **The draft may return such a set.** `get_deployment_policy` has served sets all along, so a client that
+  reads a committed deployment already handles them.
+
+### Refusals behind unchanged schemas
+
+- **`preview_deployment_resolution` (SLOTS), `preview_radar_resolution` (SLOTS) and
+  `test_generate_deployment_grid` refuse a regime condition naming one regime twice**, as
+  `VALIDATION_ERROR` at its `regimes` field, where they used to resolve or generate over it. The stage tools
+  already refused a repeat, so no commit changes; a repeated member is a malformed set.
+
+## Contract history — v68 (Arena drafts)
+
+**Breaking: one tool retired, two inputs reshaped.** Arena deployment content now commits only as a
+draft the player was shown a live preview of, as radar content has since v66. The player's deploy
+editor and every conversation share one unsaved draft per arena.
+
+### Removed tool — something you call no longer exists
+
+- **`upsert_deployment_policy` is retired**, with no alias. Calling it is an unknown-tool error. To
+  deploy or change an arena's deployment:
+  1. `stage_deployment_policy_draft` the axes you are changing (`RULES`, `DEFAULT_SLOT`,
+     `REGIME_ANCHOR`), with the `draftVersion` your last read returned;
+  2. `preview_deployment_resolution` with `request: { kind: "DRAFT", draftVersion }` at the version
+     staging returned;
+  3. show the player the resolution and whether it will play (`enabledAfterCommit`), and on their word
+     call `commit_deployment_policy_draft` with the `previewToken` that preview returned and
+     `confirm: true`.
+
+  Pausing is no longer a flag on the write: use `pause_deployment_policy`. **A first deployment always
+  plays**; a replacement keeps its pause.
+
+### Rejected input — something you send is no longer accepted
+
+- **`preview_deployment_resolution`'s `request` needs a `kind`.** `{ kind: "SLOTS", slots, … }` is the
+  old request. `{ kind: "DRAFT", draftVersion }` previews the player's draft of the arena at that
+  version, composed over the deployed policy exactly as the commit writes it. `{ kind: "COMMITTED" }`
+  previews the deployed policy a resume would arm. A request without `kind` is refused.
+- **`delete_deployment_policy` requires `expectedPolicyId`** beside `expectedRevision`: a revision
+  restarts at 1 when an arena is redeployed, so only the pair names the deployment you read.
+- **A regime anchor override names its coin and timeframe together, or neither**, on every path
+  including `test_generate_deployment_grid` and the SLOTS preview.
+
+### Wider surface — eight tools added
+
+- **`stage_deployment_policy_draft`**, **`get_deployment_policy_draft`**,
+  **`list_deployment_policy_drafts`** and **`discard_deployment_policy_draft`** (`mcp:read`). None of
+  them commits or arms anything.
+- **`commit_deployment_policy_draft`** (`presetId`, `previewToken`, `confirm: true`; `mcp:wager`) — the
+  only MCP committer of Arena content.
+- **`pause_deployment_policy`** (`presetId`; `mcp:wager`) — no revision and no certificate.
+- **`resume_deployment_policy`** (`presetId`, `previewToken`, `confirm: true`; `mcp:wager`) — needs the
+  certificate a live `COMMITTED` preview returned.
+- **`cancel_market_grid_submission`** (`sessionId`, `confirm: true`; `mcp:wager`) — the player's own
+  cancellation and refund of one entry.
+
+### Reshaped and wider output
+
+- **`preview_deployment_resolution`** nests the resolution under `resolution` and gains
+  **`previewToken`** (the certificate a live DRAFT or COMMITTED preview earns, null otherwise, good for
+  five minutes) and **`enabledAfterCommit`**.
+- **`pause_deployment_policy` and `delete_deployment_policy` return `openEntries`**: the entries the
+  player's agent already made in the arena's pending sessions, each with its lock time and entry fee.
+  They play out unless the player cancels them — tell the player and ask, then call
+  `cancel_market_grid_submission` only for the entries they pick.
+- **`get_deployment_policy`'s `authoringContext`** gains the arena's header facts
+  (`regimeReferenceTicker`, `presetBadgeImageUrl`, `entryFee`, and `playerCount` — null when the arena
+  has no pending session to count).
+- The thought-log **`outcome`** gains **`SKIPPED_DEPLOYMENT_DISARMED`**: an entry job that found its
+  deployment withdrawn, paused or no longer slotting its agent stood down before paying.
+
+### Refusals worth knowing before you commit or resume
+
+- **The certificate is bound to what you previewed**: your credential, the player, the arena, the
+  subject, the deployment and its revision, the draft version and the composed content. Anything that
+  moves is a `CONFLICT` and nothing is written. Preview again; never reuse the old certificate.
+- **A commit never withdraws**: a draft with no rule and no catch-all is refused, naming
+  `delete_deployment_policy`.
+- **Resume is refused on a retired arena and on one the player's access was revoked from**; pausing and
+  withdrawing stay open.
+- **Deployment refusals answer `INVALID_DEPLOYMENT_POLICY`.**
+- **`delete_deployment_policy` also ends the player's draft of the arena.**
+
+### Vocabulary
+
+`toolCount` goes 134 → 141 (eight added, one retired). `preview_deployment_resolution`'s input and
+output, `delete_deployment_policy`'s input and output, `get_deployment_policy`'s and
+`list_deployment_policies`' outputs, the three journal outputs and `test_generate_deployment_grid`'s
+input (a session start now accepts up to 288 times a day) move; `upsert_deployment_policy`'s are
+removed.
+
 ## Contract history — v66.1 → v67
 
 **Breaking at v67: four output fields removed.** v66.1 and v66.2 were additive and are recorded here

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

package/skills/EXPORT.json

@@ -1,11 +1,11 @@
 {
   "generator": "battlegrid-app/server/scripts/export-mcp-skills.mjs",
-  "contractVersion": "66.1.0",
+  "contractVersion": "68.0.0",
   "files": {
     "battlegrid-agent-management/SKILL.md": "fbc602e9445d0f72353bfba23c30a364b478bd04a9cc6248418cfeec66717eb1",
     "battlegrid-arena-play/SKILL.md": "4cfaa92a8d0dcaf477b227abd774e7aa8642c185d72108dfd401be0cf8aecd7f",
     "battlegrid-market-analysis/SKILL.md": "22fde9c4eac0261c89a8056ab8b20b66fcbe1fd58447fa0ac84fd410b4d134d7",
-    "battlegrid-radar-deployment/SKILL.md": "40cff6a1f5beac8a9f7d6e7a0805af6209613691170eddc19f9a7bc301cdeded",
+    "battlegrid-radar-deployment/SKILL.md": "e2098ac23d80ab985eb93d46f6cc81c84b63dbba12b3bb3eb4cfdcef10ef3b82",
     "battlegrid-strategy-authoring/SKILL.md": "95e91dd1ff36922b7ed0f5eb92c98def98fa39cce37c3d7447269aea1b5a017f",
     "battlegrid-strategy-doctor/SKILL.md": "d0b9e9e07648246d5a23b0c17183278b70b5bcbb5f472ac7da13d03e42a6c6c6",
     "battlegrid-strategy-examples/SKILL.md": "17e8cf8040813622bd5b82165c7af82e03287fee1f6aac974e0b6c584580dd27",
@@ -13,6 +13,6 @@
     "battlegrid-strategy-examples/references/recipes.md": "53887daece17995543e7d3fe1bf2577fc41a6254c291acacde48d7de63853641",
     "battlegrid-strategy-examples/references/tradingview-ports.md": "2b13adbc137178955edcca31b6ab40c01c745a932a0750b91db8820c736700bb",
     "battlegrid-trade-analysis/SKILL.md": "f49482702f17d7fc44db00c31a19fc6e9350668fe76e8948d22faaa9c7e9d6bf",
-    "battlegrid-trade-proposal/SKILL.md": "a198dd360bd7a1de5f00237b544a3535fc7c373612c09cf9a9dae4f2607c489a"
+    "battlegrid-trade-proposal/SKILL.md": "4cdb46a543cc126092874a4b385670ea2160de0384b7b5087c93b0aa72830b79"
   }
 }

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

@@ -1,6 +1,6 @@
 ---
 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, stages a Radar change into the player's draft, previews what it would actually resolve to, commits 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.
+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, stages a change into the player's draft, previews what it would actually resolve to, commits 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
@@ -17,15 +17,14 @@ 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 `commit_radar_deployment_draft`,
-   `resume_radar_deployment` or `upsert_deployment_policy`.* The preview is the only place the
+   `resume_radar_deployment`, `commit_deployment_policy_draft` or `resume_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 retry.** *Cue: a CONFLICT on a write.* Something moved under you — the stored policy,
-   or for Radar the player's draft. Retrying overwrites an edit you never read. → step 3.
+   or the player's draft. 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
    or a regime after you previewed.* A preview vouches only for what it resolved. → step 2.
-4. **A replacement that silently drops slots.** *Cue: a Radar `RULES` axis staged over a deployed
-   coin, or any Arena upsert on a preset that already has a policy.* Radar's `RULES` is the COMPLETE
-   ordered rule list and Arena's `slots` the complete slot set: a rule or slot you did not resend is
+4. **A replacement that silently drops rules.** *Cue: a `RULES` axis staged over a deployed coin or
+   a deployed arena.* `RULES` is the COMPLETE ordered rule list on both: a rule 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
@@ -55,9 +54,10 @@ Then read what exists:
   `list_radar_deployment_drafts` when no coin is named yet. The player may be part-way through a
   change in their radar builder. **If a draft exists, say so** — what it holds, and when and from
   where it was last written — and propose against it rather than starting over beside it.
-- `get_deployment_policy` / `list_deployment_policies` for Arena. The read supplies
-  `expectedRevision` for the Arena write: **`null` only for a first deploy** — a preset with no
-  policy at all.
+- `get_deployment_policy` / `list_deployment_policies` for Arena, and **the player's draft of the
+  arena** with `get_deployment_policy_draft` — or `list_deployment_policy_drafts` when no arena is
+  named yet, which also lists arenas the player started but never deployed. Mention an existing draft
+  the same way: what it holds, and when and from where it was last written.
 
 `get_regime_snapshot` / `get_regime_history` when the policy turns on regime conditions.
 
@@ -80,7 +80,17 @@ If the question is *why did my radar agent not fire*, do not start from the jour
 To try a slot set without touching the draft, preview `{ kind: "SLOTS", deploymentTimeframe, slots }` —
 it certifies nothing and cannot be committed.
 
-**Arena** → `preview_deployment_resolution` with the draft slots.
+**Arena** — the same shape, keyed on `presetId`:
+
+1. `stage_deployment_policy_draft` with `draftVersion` = the `version` you read (0 when there was no
+   draft) and only the axes you are changing, each WHOLE: `RULES` (the complete ordered rule list —
+   first is highest priority, one regime per rule), `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.
+
+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).
 
 Both previews run the **same resolver the live sweep runs**, so the preview is the real outcome, not
 an estimate. Neither writes anything and neither costs the player an LLM call — so previewing
@@ -90,8 +100,8 @@ Render the preview as a card and read it out: which agent goes on duty, which sl
 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. For Radar, `enabledAfterCommit` says whether the policy will
-trade once committed — a paused policy stays paused.
+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 always plays.
 
 **If anything changes after a preview, re-preview.** A preview never vouches for what it did not
 resolve.
@@ -104,20 +114,20 @@ the reason — and **names what the change does to the stored policy**, read fro
 - every rule or slot the change **removes** (by agent and priority), because `RULES` and `slots` are
   the whole set;
 - a bar, window or regime that **changes** on a rule or slot that survives;
-- for Arena, `enabled` going false (**paused, slots kept — nothing fires**) or true (**resumed — it can
-  fire again from the next confirmed flip**).
+- whether it will play once committed, from `enabledAfterCommit` — a commit never changes a pause.
 
 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** → `upsert_deployment_policy` with the revision from step 1.
+- **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.
 
 **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 Radar 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.
+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.
 
 ### 4. Pause, resume, discard, delete
 
@@ -127,23 +137,34 @@ never waits on a read. The player's draft is kept. **Resume** → preview the de
 `resume_radar_deployment({ coinId, previewToken, confirm: true })` with the token that preview
 returned.
 
-**Discard a Radar draft** only on the player's word. Call `discard_radar_deployment_draft` with
+**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.
+
+**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
+play out unless the player cancels them. Name each one, ask whether to cancel it, and call
+`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.
 
 **Deletes** — `delete_radar_deployment` / `delete_deployment_policy` remove the **entire** policy —
-every slot and condition — and revoke the standing authority. Un-deploying a Radar coin **also ends
-the player's draft of it**. 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.
+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.
 
 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
-`pause_radar_deployment` for Radar, and an upsert with `enabled: false` for Arena. Offer that
+`pause_radar_deployment` for Radar and `pause_deployment_policy` for Arena. 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
@@ -187,23 +208,19 @@ Two negatives, both checkable:
   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: enforced for Radar, this flow's rule for Arena
+## Preview-before-commit: enforced for both
 
-**Radar** arms only with a certificate. `commit_radar_deployment_draft` takes the certificate a live
-preview of that draft returned, and `resume_radar_deployment` one from a live preview of the deployed
-policy. Each is bound to your credential, the player, the coin, 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
+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.
 
-**Arena** has no server-side preview receipt: the upsert takes no token proving a preview happened,
-and the CAS revision is the only cross-call state. There the sequence above is what holds the
-invariant. Treat it as binding anyway: an Arena 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 commit, pause, resume, upsert or delete may have landed. **Read the
+An interrupted or timed-out commit, pause, resume, delete or cancel 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.
@@ -211,7 +228,7 @@ 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
+thought and activity records. It is a composition aid for tuning an Arena 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.
 

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

@@ -1,6 +1,6 @@
 ---
 name: battlegrid-trade-proposal
-description: Find and stage a trade for one of the player's agents, for the player to approve. Activate whenever the player asks which coins fit an agent right now, wants a trade found or proposed for an agent, asks the agent to evaluate a coin, or wants to approve or decline a proposal it made. The scan is the agent's own gates over every active coin; a proposal is QUEUED for the agent's next strategy-bar close and answered into the conversation when that bar is decided; approval is always the player's word.
+description: Find and stage a trade for one of the player's agents, for the player to approve. Activate whenever the player asks which coins fit an agent right now, which of their agents fits a coin, wants a trade found or proposed for an agent or on a coin, asks the agent to evaluate a coin, or wants to approve or decline a proposal it made. The scans are the agents' own gates — one agent over every active coin, or one coin over every one of the player's agents; a proposal is QUEUED for the agent's next strategy-bar close and answered into the conversation when that bar is decided; approval is always the player's word.
 ---
 
 # Trade Proposal
@@ -16,7 +16,23 @@ re-sorts a list, re-derives a verdict, or approves on the player's behalf.
   it is accepted, cancelled or expires. **Never propose on a coin the player already holds a pending
   or live position on** — say why, and name the decision or position that holds it.
 
-## 1. Which coins fit the agent right now
+## 1. When the player names a coin and not an agent — choose the agent
+
+- `scan_coin_agents` for the coin. The rows arrive server-ranked across the player's own agents:
+  `qualified` by score, then `rejected` with the first failing gate, then `unscorable` with the
+  reason, then `ineligible` with the refusal `propose_entry_decision` would give (`AGENT_NOT_ACTIVE`,
+  `MODEL_INACTIVE`, `AGENT_HALTED`). Read them **as written** — never re-sort or re-derive a verdict.
+- **Ask the top-ranked qualifying agent**, and name the other agents that qualified so the player can
+  choose one of them instead. One request per coin: the platform holds one pending request per coin
+  across all of the player's agents, so ask one agent, not each of them.
+- **When none qualifies, say so plainly.** Name each agent's blocking gate or ineligibility, and offer
+  the strategy doctor for the one closest to qualifying. Never propose through an agent the scan
+  reports rejected, unscorable or ineligible.
+- **When the player has no agent at all**, the scan is empty: say so, and the next step is building one
+  (a strategy first, when they have none).
+- A refused scan (`RATE_LIMITED`) is a refusal with its retry-after, never "nothing fits".
+
+## 2. Which coins fit the agent right now
 
 - `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.
@@ -29,16 +45,7 @@ re-sorts a list, re-derives a verdict, or approves on the player's behalf.
 - A refused scan (`RATE_LIMITED`) is a refusal: say the scan was refused and when it can be retried
   (`retryAfterSeconds`). Never say "nothing fits".
 
-## 2. Queue the request
-
-**In a conversation the Agent Toolbox hosts, this section does not apply: name the coin and stop.**
-The player presses **Request a trade** in the trade lane beside you and the same queued request is
-registered from there, free and without a model turn; your job is to say which coin is worth
-requesting and what the gates read, and to leave the press to them. `propose_entry_decision` and
-`cancel_entry_request` are refused from such a conversation as tool errors, so calling one spends an
-op of your budget and queues nothing. The refusal is **host-wide** — every tool that writes is
-refused there, which is why no other skill carries a paragraph of its own — and every read in this
-flow stays available.
+## 3. Queue the request
 
 - `propose_entry_decision` **only** on the coins the player named, or on the top qualifying row
   when they asked for the best fit. One coin per call.
@@ -50,7 +57,7 @@ flow stays available.
 - **One pending request per coin.** A second is refused with `CONFLICT` / `REQUEST_PENDING` — read
   the one that exists with `get_entry_request` rather than asking again.
 
-## 3. Tell the player what they are waiting for
+## 4. Tell the player what they are waiting for
 
 - `type: "queued"` is the normal answer. Read `request` back to them: the bar being decided
   (`barStart`), when the answer is due (`decidesBy`), and the deadline past which that bar can no
@@ -71,10 +78,10 @@ flow stays available.
   `topupAvailable` is true. A refused request (`RATE_LIMITED`) is a refusal with its retry-after.
   Never "nothing to do".
 - `type: "recommendation"` and `type: "no_trade"` arrive only as the **replay** of a request made
-  before the queued contract shipped. Report them as step 4 describes and do not expect them from a
+  before the queued contract shipped. Report them as step 5 describes and do not expect them from a
   fresh call.
 
-## 4. When the answer arrives — approve or decline only on the player's word
+## 5. When the answer arrives — approve or decline only on the player's word
 
 **On a web Commander surface the approval is the card's own.** The decided close lands on the
 delegation card in this conversation, carrying the player's Accept and Decline. `accept_entry_decision`
@@ -82,12 +89,6 @@ and `cancel_entry_decision` remain yours for the external and Telegram doors, an
 the player's explicit typed word — never inferred from interest, agreement, or a question about the
 trade.
 
-**In a conversation the Agent Toolbox hosts, the approval is not yours to send at all.** The decided
-close lands on the trade card in the lane beside you, carrying the player's own Accept and Decline;
-`accept_entry_decision` and `cancel_entry_decision` are refused there as tool errors, so calling one
-spends an op and moves nothing. Read the card back to them — the direction, the levels, the
-conviction, the expiry — and say what you would do, which is the whole of your part.
-
 - A decided close produces one of: a PROPOSED decision awaiting approval; a no-trade with the
   reason and the next coins worth asking about; a close that did not qualify; a window that passed
   with no sweep; or a bar the agent's own radar deployment decided first and traded in full.