@battlegrid/mcp-server 32.0.16 → 32.0.17

package/dist/index.d.ts

@@ -47,7 +47,7 @@ import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/cli
  * 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 = "32.0.16";
+export declare const PACKAGE_VERSION = "32.0.17";
 export declare const DEFAULT_URL = "https://mcp.battlegrid.trade/mcp";
 export interface EnvConfig {
     apiKeys: string[];

package/dist/index.js

@@ -49,7 +49,7 @@ import { Client, SdkHttpError, StreamableHTTPClientTransport } from '@modelconte
  * 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 = '32.0.16';
+export const PACKAGE_VERSION = '32.0.17';
 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": "32.0.16",
+  "version": "32.0.17",
   "description": "BattleGrid MCP server — play crypto prediction games from AI agents",
   "type": "module",
   "main": "dist/index.js",

package/skills/EXPORT.json

@@ -1,13 +1,14 @@
 {
   "generator": "battlegrid-app/server/scripts/export-mcp-skills.mjs",
-  "contractVersion": "121.2.0",
+  "contractVersion": "122.0.0",
   "files": {
-    "battlegrid-agent-management/SKILL.md": "09e5cbf241e2ba8f672e8292d40b3a50ee875f9b838003b95ee51928c5dbdf2e",
+    "battlegrid-agent-management/SKILL.md": "4c2cb5cfec27cf11769d66763e024e6900c392e27a978de3080cf55b2ece7a68",
     "battlegrid-agent-management/references/agent-stage-examples.md": "dffcc353d61dfc7b5bb6a2b3077fc6bf8c760a34c287cafb3b59b99306f24195",
-    "battlegrid-agent-management/references/officer-stage-examples.md": "a5a42792a8aa8f4af8cbf424d7c9aadbaa23df382ce17691a40a8d0e5447db63",
     "battlegrid-arena-play/SKILL.md": "2e37970a66b8738ffbc445a23da90651c1f41b56ce4eef551582ab123517ef74",
     "battlegrid-arena-play/references/entry-stage-examples.md": "0223f3743171ff213e943789d27590b2f65648398e85e10cd24938d5eb6af665",
     "battlegrid-market-analysis/SKILL.md": "fcbe98e30e1edce39bb170c224cdf20181934f62b5f3a26b293787c70eeb6229",
+    "battlegrid-officers/SKILL.md": "3fd59ec301d1492c956fbdb4368fef61f29abd137f02f49a6172351c7a563309",
+    "battlegrid-officers/references/officer-stage-examples.md": "ef46ba26f4b36c9964b5bde95fdf98e5952c3786b77be5f136056cac792f0aec",
     "battlegrid-radar-deployment/SKILL.md": "cf6664f51f92d40acce21a46f4fb078d9afe46c99c4f4b603bf002e73d4c5a23",
     "battlegrid-radar-deployment/references/arena-stage-examples.md": "d27cfed1f4663f267c4a7ecebe4a6e65a450fc74bd14ce8987fb61af5bbf2ca5",
     "battlegrid-radar-deployment/references/radar-stage-examples.md": "13fc3f55d91d3da9754e1ed7fb27493b7b7ba4d40a6a7e8d1ee0365f90ea10de",
@@ -18,9 +19,6 @@
     "battlegrid-strategy-examples/references/playbooks.md": "275352be43652ca0fd36a35981ea7ffcfabdc4f9b33293826656ee500d3795e9",
     "battlegrid-strategy-examples/references/recipes.md": "806aae0b4842408f6e6ed3e108293073f4f31d1c27fa419ad57df9e1134f23e7",
     "battlegrid-strategy-examples/references/tradingview-ports.md": "9eaa926cbe8606c6a09f91007a0606042afbfdc50173a5b13ae9336d2e9e9b08",
-    "battlegrid-strategy-officer/SKILL.md": "2c28ec4afa632b0f69b84b6d309f77d811d0d7452c1dbebce011b22044563780",
-    "battlegrid-strategy-officer/references/figures.md": "e9591e4f4edb9fc54066527ecd862aeef18badc96eaa924f14bd7da326eab541",
-    "battlegrid-strategy-officer/references/proposal-shapes.md": "20c9acd2b20e7920ed7ac9aa096604d91625b1d5b6438aa1ded7f6b63ecc9a22",
     "battlegrid-trade-analysis/SKILL.md": "3f927b4f9796178526fa1673a2043c5f14358c39aa955de33192ea58641f18fb",
     "battlegrid-trade-proposal/SKILL.md": "e761fc6bddc0d1db79fcb90046d03a18439562c8658de726ec286830edd6369b"
   }

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

@@ -266,39 +266,10 @@ These tools carry no consent gate on either door: they are ownership-gated and b
 in chat and through an external MCP client. Your confirm is interaction, never authorization —
 never describe it as a permission check, and never add one of your own.
 
-### 8. Strategy Officers: configure one like an agent
-
-A Strategy Officer is a platform review the player schedules: on its hour it reads each in-scope agent's
-record and records at most one proposal per agent for the player to apply or dismiss. It writes no draft
-and commits nothing. Setting one up is configuration, and every run it schedules is billed to the
-player's LLM credit — so it goes through its own draft, exactly as an agent does.
-
-- **Read first.** `list_officers` for the roster (each officer's schedule, scope, last and next run),
-  `list_officer_drafts` for setups part-way through, `get_officer_draft` for one draft.
-- **Create.** `stage_officer_draft` with **no** `officerId` and `draftVersion: 0` mints a new create
-  draft; every later call names the minted id. Stage only what the player asked for — every axis the
-  draft does not hold starts at its default (name "Strategy Officer", the catalog's default model, no
-  instructions, `DAILY` at 03:00 UTC, all active agents, all three levers). "Add an officer that
-  reviews my agents every morning at six and focuses on stops" is `NAME`, `SCHEDULE`
-  `{ cadence: 'DAILY', hourUtc: 6, weekdayUtc: null }` and `INSTRUCTIONS` `{ focusText }` in the
-  player's words — and ask which timezone "six" means before converting it to a UTC hour. Worked
-  inputs: `references/officer-stage-examples.md`.
-- **Presets are starting points, staged as ordinary axes.** When the player names one — an exits
-  officer (levers `strategy`), a regime officer (`radar-deployment`), a rails officer (`agent`) or a
-  general one (all three) — stage its `NAME`, `INSTRUCTIONS` and `SCOPE`; the officer remembers no
-  preset.
-- **Axes are whole.** `SCHEDULE` carries `cadence`, `hourUtc` and `weekdayUtc` (`0` Sunday … `6`
-  Saturday, for `WEEKLY` only, otherwise null); `SCOPE` carries both `agents` (`'ALL'` or agent ids
-  from `list_intelligence_agents`) and `levers`. `INSTRUCTIONS` are the player's brief in their own
-  words: at most 2,000 characters, naming no tool and no id — the commit refuses either.
-- **Show, then commit on the player's word.** Read `get_officer_draft` and show the diff, the
-  diagnostics and the impact — `nextRunAt` is when it first runs, and a create's `admission` says
-  how many officers the player holds against the limit and how many more it admits (`officersRemaining`). Commit with `commit_officer_draft` naming
-  exactly the `draftVersion` and `committedRevision` the read returned, and only when the player says
-  so. A cadence of `OFF` keeps the setup and runs nothing.
-- An officer's reviews and their Apply, Push and Dismiss live on the Officers page's inbox; they are not
-  this flow's. In the app, the player sets an officer up in its own console, where this conversation may be
-  docked beside the form — stage into the officer it is scoped to.
+### 8. Strategy Officers are the officers skill's
+
+Setting up, running and reviewing a Strategy Officer, and acting on its proposals, is the `officers` skill's flow:
+activate it for any officer ask.
 
 ## When a write's outcome is unknown
 

package/skills/battlegrid-officers/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: battlegrid-officers
+description: Set up and govern the player's Strategy Officers and work their reviews — create or change an officer through its draft, run one now, read when each runs and what is waiting, and apply, push or dismiss the proposals its reviews carry. It never writes a review. Activate whenever the player wants a new Strategy Officer, wants to change, pause or archive one, wants one to run now, asks what their officers found or when they run, or wants to apply, push or dismiss an officer's proposal.
+---
+
+# Strategy Officers
+
+A Strategy Officer is a review the player schedules: on its hour, or when the player runs it now, it reads each
+in-scope agent's record and records at most one proposal per agent for the player to apply, push or dismiss. The
+officer writes its reviews on its own turn, on its own model and brief. This flow is the player's side of it:
+setting an officer up, running it, reading where it stands, and acting on what it proposed.
+
+Every officer run is billed to the player's LLM credit, and an applied proposal changes a live strategy, agent or
+Radar deployment. So a setup goes through its own draft, a run is started only on the player's word, and Apply is
+confirmed before it is called.
+
+## The four failures this flow exists to prevent
+
+1. **Writing a review yourself.** *Cue: "what would my officer say about…", wanting to record a finding.* You read
+   an officer's reviews and give your own reading in the conversation; only the officer records a review. → §2.
+2. **Applying without confirmation.** *Cue: "apply it", "make it live".* Apply publishes the proposal to a live
+   target. Show the review, then confirm through `ask_user`. → §4.
+3. **Computing what is served.** *Cue: working out the next run from the schedule, counting open reviews.* Every
+   status figure is on the read. → §3.
+4. **Committing a setup unasked.** *Cue: a staged officer that looks right.* The commit is the player's word. → §1.
+
+## 1. Set up and update an officer through its draft
+
+- **Read first.** `list_officers` for the roster (each officer's schedule, scope, last and next run) and the
+  `presets`, `list_officer_drafts` for setups part-way through, `get_officer_draft` for one draft.
+- **Create.** `stage_officer_draft` with **no** `officerId` and `draftVersion: 0` mints a new create draft; every
+  later call names the minted id. Stage only what the player asked for — every axis the draft does not hold starts
+  at its default (name "Strategy Officer", the catalog's default model, no instructions, `DAILY` at 03:00 UTC, all
+  active agents, all three levers). "Add an officer that reviews my agents every morning at six and focuses on
+  stops" is `NAME`, `SCHEDULE` `{ cadence: 'DAILY', hourUtc: 6, weekdayUtc: null }` and `INSTRUCTIONS`
+  `{ focusText }` in the player's words — and ask which timezone "six" means before converting it to a UTC hour.
+  Worked inputs: `references/officer-stage-examples.md`.
+- **Presets are starting points, staged as ordinary axes.** When the player names one of the `presets`
+  `list_officers` serves, stage its `name`, `focusText` and `scope` as `NAME`, `INSTRUCTIONS` and `SCOPE`; the
+  officer remembers no preset.
+- **Axes are whole.** `SCHEDULE` carries `cadence`, `hourUtc` and `weekdayUtc` (`0` Sunday … `6` Saturday, for
+  `WEEKLY` only, otherwise null); `SCOPE` carries both `agents` (`'ALL'` or agent ids from
+  `list_intelligence_agents`) and `levers`; `MODEL` names a `modelId` from `list_approved_models`. `INSTRUCTIONS`
+  are the player's brief in their own words: at most 2,000 characters, naming no tool and no id — the commit
+  refuses either.
+- **Show, then commit on the player's word.** Read `get_officer_draft` and show the diff, the diagnostics and the
+  impact — `nextRunAt` is when it first runs, and a create's `admission` says how many officers the player holds
+  against the limit and how many more it admits (`officersRemaining`). Commit with `commit_officer_draft` naming
+  exactly the `draftVersion` and `committedRevision` the read returned, and only when the player says so. A cadence
+  of `OFF` keeps the setup and runs nothing on a schedule.
+- **Archive** with `archive_officer` only on the player's word: an archived officer runs no more, and its open
+  reviews stay in the inbox.
+- In the app, the player sets an officer up in its own console, where this conversation may be docked beside the
+  form — stage into the officer it is scoped to.
+
+## 2. Run an officer now
+
+`run_officer` with the officer id, on the player's word. It runs exactly what the schedule runs — the officer's
+own model and brief, over the agents its scope covers that closed a decision or saw the officer's setup change
+since its last review — and answers before any review starts:
+
+- `QUEUED` with `agentCount`: the reviews arrive in `list_officer_reviews` as each finishes;
+- `NOTHING_TO_REVIEW`: no agent is under review, and nothing is queued or billed;
+- `ALREADY_QUEUED`: a run of this officer is waiting or running.
+
+A run is per officer: to run two, call it for each. While one is waiting or running, `pendingRun` on `list_officers`
+and `get_officer` names its state; read it again rather than calling `run_officer` twice. It follows
+`commanderAccess` from `get_account_state`, not `llmAccess`: show `deniedMessage` when it is not allowed. An
+archived officer is refused.
+
+**Never write a review.** The officer records its own; a second opinion on one of its reviews is your reading in
+the conversation, never a record.
+
+## 3. Where each officer stands
+
+Read it, never compute it. `list_officers` serves each officer's `lastRunAt`, `nextRunAt` and `pendingRun`, and
+`list_officer_reviews` serves `openCountByOfficer`, each unarchived officer's open and pushed reviews. Quote them as
+served, through their display names.
+
+## 4. Work the inbox
+
+- **Read.** `list_officer_reviews`, by officer or by agent, newest first; `includeClosed` adds the applied,
+  dismissed and superseded history. Show each review's verdict, findings, diff, impact and warnings exactly as
+  served; `applyAvailable` says Apply is offered, `heldAxes` names every axis the target's draft holds and who wrote
+  it, and `baseMoved` says the target was committed since the review.
+- **Apply** with `apply_officer_proposal` only after an `ask_user` confirmation naming the review, its target and
+  its axis, and only on the confirming pick. A client with no `ask_user` asks in its reply and waits for the
+  player's word. Apply publishes the proposal to the live target; it needs `mcp:wager`.
+- **Push** with `push_officer_proposal` and **Dismiss** with `dismiss_officer_review` on the player's explicit word,
+  naming the review. A push places the proposal in the target's draft for the player to save from the editor; a
+  dismissal closes the review and touches no draft.
+- **A refusal names its recovery** through `details.nextAct`: `BASE_MOVED` — the target moved since the review,
+  dismiss it for a re-review; `AXIS_HELD` and `DRAFT_NOT_EMPTY` — the target's draft already holds work, so the
+  player saves or discards it, or pushes instead of applying; `TARGET_NOT_OWNED` and `PROPOSAL_INVALID` — the target
+  no longer accepts the proposal, so dismiss it. A dismissed review is not run again until the agent closes a new
+  decision or the officer's setup changes.
+
+## Reporting discipline
+
+- Numbers, codes and states exactly as served, through their display names.
+- Never describe a proposal as applied before `apply_officer_proposal` answered, or a review as written by you.

package/skills/{battlegrid-agent-management → battlegrid-officers}/references/officer-stage-examples.md

@@ -29,23 +29,11 @@ the player's "six" to a UTC hour only after asking which timezone they mean; thi
 }
 ```
 
-## Start from the regime preset, weekly on Monday
+## Start from a preset
 
-A preset is staged as ordinary axes: its name, its brief and its scope.
-
-```json stage_officer_draft
-{
-  "draftVersion": 0,
-  "axes": {
-    "NAME": { "name": "Regime Officer" },
-    "INSTRUCTIONS": {
-      "focusText": "Read the record by the regime each decision was scored against. Where a regime with a ready sample loses and the others win, propose a regime condition on the Radar rule that routes the agent."
-    },
-    "SCOPE": { "agents": "ALL", "levers": ["radar-deployment"] },
-    "SCHEDULE": { "cadence": "WEEKLY", "hourUtc": 7, "weekdayUtc": 1 }
-  }
-}
-```
+A preset is a starting point, staged as ordinary axes: take its `name`, `focusText` and `scope` from the `presets`
+`list_officers` serves, and stage them as `NAME`, `INSTRUCTIONS` and `SCOPE`, beside any `SCHEDULE` the player asks for.
+The officer remembers no preset.
 
 ## Narrow an existing officer to two agents and the rails lever
 

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

@@ -1,226 +0,0 @@
----
-name: battlegrid-strategy-officer
-description: Run one Strategy Officer's review of one agent — read the officer's own setup, the agent's served review figures and the current market read, cite every finding to a named figure with its readiness and population, choose at most one lever inside the officer's scope, and record the review with a complete proposal for the owner to apply, push or dismiss, or with no lever and the reason. It never writes a draft. Activate whenever a turn opens with a Strategy Officer brief naming an officer and an agent, or when the player asks one of their Strategy Officers to review an agent now.
----
-
-# Strategy Officer
-
-You are one of the owner's Strategy Officers, reviewing one of their agents against its own record. The
-owner set you up with a name, a brief, a schedule and a scope; the brief opening this turn names you and the
-agent. Your job is to say, from the figures the platform serves, where this playbook wins and where it loses,
-and — when a ready figure supports it — to propose the one change that would move that figure most.
-
-Everything you do here is a **read**, and one record. You read the officer setup, the agent's record and the
-market; you write exactly one thing, the review, through `submit_officer_review`. You have no draft tool and
-you do not need one: a proposal lives on the review record, and the owner's working copy changes only when
-the owner presses Push or Apply on the card. Nothing you submit reaches a live strategy, agent or Radar
-deployment on its own.
-
-Most runs are scheduled. **No one is reading this turn as it happens**, and no one will answer a question:
-the review record is your whole output.
-
-## The six failures this flow exists to prevent
-
-1. **Diagnosing from prose.** *Cue: reaching for a journal entry, a thought log line or the agent's overlay
-   text to explain a result.* The figures exist; cite them. → step 3.
-2. **A rate from a handful.** *Cue: a percentage over three trades.* A figure that reads `INSUFFICIENT_DATA`
-   has no rate, mean or median to state, and no lever rests on it. → step 3.
-3. **A lever from the market alone.** *Cue: "the market is volatile now, so…".* The market read places a
-   finding in context; every lever rests on a figure of the agent's own record. → step 4.
-4. **Two levers, or half an axis.** *Cue: two good ideas, or one changed field sent alone.* One lever per run,
-   one axis, sent whole. → step 5.
-5. **A private write path.** *Cue: wanting to "just stage it".* You submit a proposal; the owner pushes or
-   applies it. → the negatives.
-6. **Ending on a question.** *Cue: "shall I…?".* A scheduled run has no one to answer. → step 7.
-
-## Sequence
-
-### 0. When the player asks in the conversation
-
-A scheduled brief names the officer and the agent. When the player asks instead ("have my officer review my
-agent"), resolve both first: `list_officers` for the officer — none means telling them to add one from the
-Officers page and stopping there; one is the officer; several, take the one the ask names, else the one
-whose `scope.agents` covers the agent, else ask which. The agent is the one the ask names, read with
-`list_intelligence_agents`. Then run the sequence below exactly as a scheduled run would.
-
-### 1. Read your own setup first
-
-`get_officer` with the officer id the brief names. Its `focusText` is the owner's standing brief for every
-review you run — "weigh exits over entries" decides which figures you lead with and which lever you prefer
-when two are supported. Its `scope` bounds you: `scope.levers` is the set of draft kinds you may propose for
-(`strategy`, `agent`, `radar-deployment`), and `scope.agents` is `ALL` or the agent ids you review. An agent
-outside `scope.agents` gets a review with lever `NONE`, reason `AGENT_OUT_OF_SCOPE`, and nothing else.
-
-The brief carries the same instructions verbatim; where the two differ, the setup `get_officer` returns is
-the current one.
-
-### 2. Read the review context — the guards' inputs
-
-`get_officer_review_context` with the officer id and the agent id. It serves:
-
-- `lastReviewAt` — your latest review of this agent, or null when you never reviewed it;
-- `closedDecisionsSince` — the agent's closed decisions since then. **Zero means nothing new to review**:
-  submit lever `NONE`, reason `NO_NEW_DECISIONS`, with one finding that says so, and stop;
-- `strategyId` and `strategyOwnedByOwner` — **false means the owner did not author the strategy the agent
-  runs** (a public or library strategy). There is no strategy lever for this agent: see step 5;
-- `targets` — the lever targets your scope allows, each with its `kind`, its `targetId` (the strategy id,
-  the agent id, or the coin id a Radar deployment is keyed by) and the `committedRevision` a proposal names
-  as its `baseRevision`.
-
-### 3. Read the record, and state findings as figures
-
-Five reads, every one keyed by the agent id:
-
-- **`get_agent_review_analytics`** — the review read: the `overall` figure set, and the same figures sliced
-  by the regime recorded at decision (`regime`), by UTC hour (`hourOfDay`) and weekday (`weekday`), by coin
-  (`coin`, with fees), by cited condition (`condition`), LLM spend against result (`llm`), the rail refusals
-  (`railRefusals`) and the current halt (`halt`).
-- **`get_agent_decision_quality`** — entries versus skips at each horizon, exit quality (premature stops,
-  what price did after the exit), the verdict mix and exit efficiency.
-- **`get_agent_cost_economics`** — realized gross, fees and net per close outcome, and the winners costs
-  turned into losers.
-- **`get_agent_entry_discipline`** — what confirmation cost (the confirmation tax), fast stop-outs and
-  adverse-first excursions. It takes a window: pass the review read's `windowStartAt` and `windowEndAt`.
-- **`get_agent_conviction_calibration`** — win rate by conviction band, so a band that wins no more often than
-  a lower one reads as one.
-
-Then state each finding as a **named figure** from the closed list in `references/figures.md`: its figure id,
-the slice it was read over (a regime, an hour, a weekday, a coin, a cited condition, or the whole window), the
-value exactly as served with its readiness and population, and one sentence in the figure's display
-vocabulary. "Stopped too early in 9 of 20 forced exits (45%)", not "the stops are too tight". A regime is named
-by its display name ("Bear Ranging"), never its stored value; a verdict, a close outcome, a rail refusal and a
-halt reason the same way.
-
-- **Readiness is the gate.** A figure reading `INSUFFICIENT_DATA` is reported as its counts and "too few to
-  report a rate", with its sample size — never as a rate, a mean, a median or a trend, and never as the
-  ground for a lever.
-- **Counts and sums are observations.** Decisions, closed trades, realized net, fees and LLM spend are
-  reportable at any sample; a rate over the same rows is not.
-- **A mark is quoted as a mark.** A `STOPPED_EARLY` verdict means the original target printed within 24 hours
-  of the stop. Say that; never state a profit the trade "would have made". The skip side of entries-versus-skips
-  is a recorded forward return, not money the agent left on the table.
-- **Never compute a figure the reads do not serve.** Quote served values; compare two served values only by
-  naming both.
-
-If a read fails or returns nothing for what you need, that figure is **UNDETERMINED**: name the read you could
-not use, and lean on nothing from it. Never turn an absent read into a clean finding.
-
-### 4. Place the record against the current market
-
-Read the market for the agent's main coins — the coin rows of the review read with the most decisions:
-`get_regime_snapshot` for each, at the agent's regime timeframe (on `get_intelligence_agent`), and
-`get_market_context` for the context the agent itself reads. Use it to place a finding: "this playbook's
-Bear Ranging record is the losing one, and BTC reads Bear Ranging now". **A market read is context, never a
-lever**: with no ready figure of the agent's own record behind it, the review records the market context and
-lever `NONE`, reason `INSUFFICIENT_DATA`.
-
-### 5. Choose at most one lever, inside your scope
-
-Rank what would change the observed figures most, and choose **at most one** lever. Name it as the axis and
-the draft kind that applies it:
-
-| Finding | Kind | Axis |
-|---|---|---|
-| Stops too tight or too wide, a risk-reward floor, a volatility floor | `strategy` | `TRADE_LEVEL_POLICY` |
-| Break-even, trailing, time decay, invalidation exits | `strategy` | `POSITION_MANAGEMENT` |
-| A cited condition that confirms losers, a missing gate | `strategy` | `CONDITIONS` |
-| When an entry may be taken (confirmation, trigger) | `strategy` | `ENTRY` |
-| The losing pattern needs data no report section carries; a section no condition or decision uses | `strategy` | `REPORT` |
-| Rail refusals, exposure, leverage, daily limits, drawdown | `agent` | `TRADING_CONFIG` |
-| Win rate flat across conviction bands; a posture the drawdown record does not support | `agent` | `BEHAVIOR` |
-| LLM spend outrunning realized net on the agent's model | `agent` | `MODEL` |
-| Losses across regimes no condition change fixes; a strategy the owner did not author; another strategy that fits the market better | `agent` | `STRATEGY_BINDING` |
-| A regime or hours slice that loses while the others win | `radar-deployment` | `RULES` |
-| Losses in hours or regimes no rule covers, routed by the catch-all | `radar-deployment` | `DEFAULT_SLOT` |
-
-A regime or hours finding routes to the agent's **Radar rule** — a `REGIME` condition excluding the losing
-regime, or an `HOURS` condition — never to the strategy. The second-best lever is recorded as a finding
-without a lever, never as a second proposal.
-
-**A rail refusal is routed by the setting it names, never by its gate stage.** Each `railRefusals` row of the
-review read carries `tradingConfigMember`: the agent setting the owner moves to clear it. A row with a member is
-a `TRADING_CONFIG` lever on that member, inside the agent lever — `EXPOSURE_BUDGET_EXHAUSTED` names
-`maxConcurrentExposureUsd`, `DAILY_TRADE_LIMIT_REACHED` names `maxDailyTrades`, `INSUFFICIENT_EQUITY` names
-`balanceThresholdUsd`. Its `gateStage` reading `ACCOUNT` says where the gate runs, not whose setting it is: never
-say an exposure limit is outside your scope while you hold the agent lever. Lowering `balanceThresholdUsd` lowers
-a safety floor, so weigh it as a risk-increasing change and say so. A row with a null member is a halt: it ends on
-the owner's resume, and the read's `halt` names the stop that tripped it — a finding naming the owner's step,
-never a lever.
-
-**Rebind or edit.** A rebind replaces everything the agent reads and trades by — report, conditions, entry, trade
-levels, exit policy and timeframe — while each open position keeps the rules it opened under. Propose one only
-when no single strategy field would change the losing figures, or when the agent runs a strategy the owner did not
-author; otherwise edit the strategy the agent runs.
-
-- **A kind outside `scope.levers` is not yours.** Record the finding; if no in-scope lever is supported, submit
-  lever `NONE`, reason `LEVER_NOT_ALLOWED`, and say which out-of-scope lever the figures pointed at.
-- **A strategy the owner did not author is not a strategy lever.** When `strategyOwnedByOwner` is false, record
-  the finding, state that the strategy must be forked from the library before a strategy lever can be proposed —
-  forking is the owner's step, never yours — and consider a rebind and the other agent and Radar levers within
-  your scope instead. If none is supported, submit lever `NONE`, reason `TARGET_NOT_OWNED`.
-- **No ready figure, no lever.** When every figure a lever would rest on reads `INSUFFICIENT_DATA`, submit lever
-  `NONE`, reason `INSUFFICIENT_DATA`, naming the figure and its sample.
-- **Nothing to change is an answer.** When the ready figures read as a playbook doing what it should, submit
-  lever `NONE`, reason `NO_CHANGE_SUPPORTED`. Never manufacture a lever to have something to propose.
-
-### 6. Read the target's current values, then write the proposal whole
-
-A proposal carries **exactly one axis, whole**, in the kind's own vocabulary — the complete current value of
-that axis with your one change in it. So read the current value first:
-
-- a strategy axis → `get_strategy` on the agent's `strategyId`; for `REPORT`, `list_strategy_categories` for the
-  platform sections a report may carry — the whole section list is sent, with your change in it;
-- `TRADING_CONFIG` → `get_intelligence_agent` for the agent's current `tradingConfig`, and
-  `get_trading_config_catalog` for the bounds every member must sit inside;
-- `BEHAVIOR` → `get_intelligence_agent` for the current `behavior`; all three members are sent;
-- `MODEL` → `list_approved_models` for the models the account may select now, by `modelId`;
-- `STRATEGY_BINDING` → `list_strategies` (active strategies only) for the owner's own strategies and the
-  library's, by `strategyId`; a rebind carries no `TRADING_CONFIG`, since the timeframes follow the strategy;
-- `RULES` and `DEFAULT_SLOT` → `get_radar_deployment` on the coin the target names (`list_radar_deployments`
-  shows which coins route this agent); every rule is sent, in priority order, with the one rule changed, and a
-  rule or the catch-all names only agents the coin already routes.
-
-The complete shape of every axis — which members it must carry and where each comes from — is in
-`references/proposal-shapes.md`. The proposal is `{ kind, targetId, axes, baseRevision }`, where `targetId` and
-`baseRevision` are the target's `targetId` and `committedRevision` from step 2.
-
-### 7. Submit the review — the close
-
-`submit_officer_review` with the officer id, the agent id, your one-line `verdict` on the record (at most 500
-characters), the `findings`, and either the `proposal` with `noLeverReason` null, or `proposal` null with the
-`noLeverReason`. Mint one UUID as its `idempotencyKey` for each submission and repeat that key when you retry the
-same submission after a failed call, so one submission is recorded once; a resubmission with a different lever
-(below) is a new submission with a new key. The server judges the proposal with the target kind's own assessment — the same validation,
-diff, diagnostics and impact a stage would show — and stores it on the record, so the card shows only what the
-owner could commit.
-
-**A refused proposal becomes a recorded reason.** When the submit refuses with `LEVER_NOT_ALLOWED`,
-`AGENT_OUT_OF_SCOPE`, `TARGET_NOT_OWNED` or `PROPOSAL_INVALID`, submit again with `proposal` null and that code
-as `noLeverReason`, quoting the refusal's message in a finding's statement. Do not retry a different value to
-get past a `PROPOSAL_INVALID`: the record says what was refused, and the next review starts from it.
-
-**The review is written in every case** — no new decisions, out of scope, not enough data, nothing to change.
-
-Close with the review, not a question. In a scheduled run that is the whole close. When the player is in the
-conversation, add one sentence: the change is proposed and waiting on its card on the Officers page, where Apply
-publishes it, Push places it in the editor beside their own edits, and Dismiss closes it.
-
-## Negatives
-
-- **Never take a draft action.** You name no stage, commit or discard tool of any draft kind, because none is
-  yours to call: the proposal is the review record's, and Push and Apply are the owner's. Never fork, create,
-  archive, pause or resume anything.
-- **Never describe a proposal as staged or applied.** It is proposed and waiting for the owner's Apply or Push.
-- **Never say the agent "learns", "self-improves" or "optimizes itself".** Nothing reaches the agent's decision
-  prompt from a review; a change happens only when the owner commits it.
-- **Never present a counterfactual as a result.** A forward mark, a skip's return or a premature-stop verdict is
-  quoted as the recorded mark it is, never as money that "would have" been made.
-- **Never call `test_generate_deployment_grid`.** It runs a billed generation against the owner's credits and
-  writes records; it is not a review read.
-- Never diagnose from the agent's prose where a figure exists, and never present a count as a rate.
-
-## Reporting discipline
-
-- Numbers, codes and slices exactly as served, through their display names.
-- Worst news first: a halt or a standing rail refusal outranks a tuning finding.
-- One verdict line, a handful of findings that carry it, and at most one lever. Concise beats complete.

package/skills/battlegrid-strategy-officer/references/figures.md

@@ -1,105 +0,0 @@
-# Figures a finding may cite
-
-A finding names exactly one figure id from this list — the submit refuses any other. Each row says which read
-serves the figure, where in that read's output it sits, its unit, and how its value and population go into the
-finding. The owner's card renders each id through its own label and unit, so your `statement` carries the
-words and the figure carries the number.
-
-## How a finding carries a figure
-
-A finding is `{ figureId, slice, value, statement }`:
-
-- **`slice`** — the slice the figure was read over, or null for the agent's whole window:
-  `{ kind: 'REGIME', regime }` (a regime row's key — a regime, `UNAVAILABLE` or `ABSENT`),
-  `{ kind: 'HOUR', hourUtc }`, `{ kind: 'WEEKDAY', weekday }`, `{ kind: 'COIN', coinTicker }`, or
-  `{ kind: 'CONDITION', conditionKey, conditionName }`, each copied from the row it was read from.
-- **`value`** — `{ readiness: 'READY', sampleSize, value }`, or `{ readiness: 'INSUFFICIENT_DATA', sampleSize }`
-  copied from a figure that reads `INSUFFICIENT_DATA`. A count or a sum is an observation and always `READY`.
-- **`statement`** — one sentence naming the value and its population in display words: "won 4 of 19 closed
-  trades in Bear Ranging (21.1%)", "too few closed trades on Saturdays to report a rate (3)".
-
-The outputs are `{ analytics }` for `get_agent_review_analytics`, `{ quality }` for
-`get_agent_decision_quality`, `{ economics }` for `get_agent_cost_economics`, `{ stats }` for
-`get_agent_entry_discipline`, and `{ calibration }` for `get_agent_conviction_calibration`. In the review read,
-`figures` below means `analytics.overall` for the whole window, or a slice row's `figures` — `regime[]`,
-`hourOfDay[]`, `weekday[]` or `coin[]` — for that slice.
-
-## The figures
-
-### Volume
-
-- **`DECISIONS_EVALUATED`** — `figures.decisions`. Count of decisions. `sampleSize` is the count itself.
-- **`CLOSED_TRADES`** — `figures.closedTrades`. Count of closed trades. `sampleSize` is the count itself.
-- **`FORCED_EXITS`** — `figures.forcedExitCount`. Count of closes the Decision Quality band counts as forced
-  exits. `sampleSize` is the slice's `closedTrades`.
-
-### Result
-
-- **`WIN_RATE`** — `figures.winRate`: `ratePercent` when `READY`, in percent; its `sampleSize` is the closed
-  trades. State it with `figures.winningTrades` of `figures.closedTrades`.
-- **`REALIZED_NET_USD`** — `figures.realizedNetUsd`, USD, signed: the sum of the closed trades' recorded net.
-  `sampleSize` is `figures.closedTrades`.
-- **`REALIZED_FEES_USD`** — a coin row's `feesUsd`, or `analytics.llm.feesUsd` for the whole window, USD.
-  `sampleSize` is that row's `closedTrades`.
-
-### Exits
-
-- **`PREMATURE_STOP_RATE`** — `figures.prematureStop`, or `quality.exitQuality.prematureStop` for the whole
-  window: `prematureStopRatePercent` when `READY`, in percent, with `prematureStopCount` of `sampleSize` stop-outs
-  that were `STOPPED_EARLY` ("Stopped Early" — the original target printed within 24h of the stop).
-- **`POST_EXIT_MEAN_RETURN`** — `quality.exitQuality.postExit`: `meanSignedReturnPct` when `READY`, percent,
-  direction-signed — the mean move in the trade's favour over the 24 hours after the exit. Positive means price
-  kept going the trade's way after it closed.
-- **`MEDIAN_EXIT_EFFICIENCY`** — `quality.exitEfficiency.medianEfficiencyPercent`: `median` when `READY`, in
-  percent of the in-trade favourable move the exit kept.
-- **`MEDIAN_MAE_R`** — `quality.exitEfficiency.medianMaeR`: `median` when `READY`, in R — how far against the
-  trade price went before the exit, in units of the initial risk.
-
-### Entries
-
-- **`ENTER_MEAN_RETURN`** — the `enter` cell of one `filterValue[]` row (in `quality.filterValue`, or a slice's
-  `figures.filterValue`): `meanSignedReturnPct` when `READY`, percent, direction-signed, at that row's `horizon`.
-  The statement names the horizon.
-- **`SKIP_MEAN_RETURN`** — the `skip` cell of the same row, the same way. A positive skip return is a recorded
-  forward move the agent did not take — a mark, never money it lost.
-- **`CONFIRMATION_TAX_USD`** — `stats.confirmationTax.totalUsd`, USD, signed (positive is an adverse fill against
-  the decided price). `sampleSize` is `stats.confirmationTax.measuredEntries`. Not citable while `totalUsd` is null.
-
-### Conditions
-
-- **`CONDITION_CITATIONS_ON_LOSERS`** — in a `condition[]` row, the `LOST` count of one `cells[]` entry; the
-  statement names the cell's verdict (Confirm, Warn, Reject). `sampleSize` is the row's `citations`. The slice is
-  `{ kind: 'CONDITION', conditionKey, conditionName }` from the row — name the condition by `conditionName`.
-- **`CONDITION_CITATIONS_ON_WINNERS`** — the `WON` count of one cell of the same row, the same way.
-
-### Costs
-
-- **`COST_ERODED_TRADES`** — `economics.costErodedCount`: winners before costs that costs turned into losses.
-  `sampleSize` is `economics.totals.positionCount`.
-- **`FEES_PERCENT_OF_GROSS`** — `economics.totals.feesPercentOfGross`, or one close outcome row's, in percent.
-  `sampleSize` is that row's `positionCount`. Not citable while it is null (gross at or below zero) — cite
-  `REALIZED_FEES_USD` instead.
-- **`LLM_PLATFORM_SPEND_USD`** — `analytics.llm.platformSpendUsd`, USD, the platform-billed model spend over the
-  window. `sampleSize` is `analytics.llm.calls`. BYOK spend (`byokSpendUsd`) is reported in the statement when
-  non-zero, never subtracted.
-- **`NET_AFTER_LLM_USD`** — `analytics.llm.netAfterLlmUsd`, USD, signed: realized net after platform model spend.
-  `sampleSize` is `analytics.llm.decisions`.
-
-### Conviction and rails
-
-- **`CALIBRATION_GAP`** — two bands of one `calibration.slices[]` entry, both `READY`: the value is the higher
-  conviction band's `winRatePercent` less the lower band's, in percentage points, and `sampleSize` is the smaller
-  of the two bands' samples. The statement names both bands and both served rates. While either band reads
-  `INSUFFICIENT_DATA`, cite that band's sample instead.
-- **`RAIL_REFUSALS`** — one `analytics.railRefusals[]` row's `count`, a count of entries a rail refused, named in
-  the statement by the row's reason through its display name (daily trade limit reached, exposure budget
-  exhausted, agent halted, insufficient equity). `sampleSize` is the count itself. The current halt is
-  `analytics.halt`: name its `haltReason` through its display name beside the refusals.
-
-## Display vocabulary
-
-- Regimes by display name: Bull Expansion, Bear Expansion, Bull Ranging, Bear Ranging, Contraction, Volatile,
-  Unclassified; `UNAVAILABLE` is "No regime" (a cold regime context was recorded) and `ABSENT` is "Not recorded".
-- Weekdays and hours in UTC, said as such ("Thursdays, UTC", "23:00 UTC").
-- Verdicts, close outcomes and halt reasons by their display names, never the stored code.
-- Percentages to one decimal, USD to cents, R to two decimals — as served, never re-rounded into a different claim.

package/skills/battlegrid-strategy-officer/references/proposal-shapes.md

@@ -1,174 +0,0 @@
-# Proposal shapes
-
-A proposal is one lever's **one axis, whole**: `{ kind, targetId, axes, baseRevision }`, where `axes` holds exactly
-one key — the axis — whose value is the complete axis in the kind's own draft vocabulary. "Whole" means every member
-the axis carries, each at its current value except the one you change: an omitted member is not "unchanged", it is a
-proposal the assessment refuses or a value the owner would lose. So every proposal starts from the target's current
-values, read in the same review.
-
-`targetId` and `baseRevision` come from `get_officer_review_context`'s `targets`: the strategy id, the agent id or the
-Radar coin id, and that target's `committedRevision`. A proposal against a target the review context does not list
-is outside your scope.
-
-Every value below is a placeholder; replace it with what the reads served. Never send an id you did not read.
-
-## Strategy — `kind: 'strategy'`, `targetId` the strategy id
-
-Read the current values with `get_strategy`. One of five axes:
-
-### `TRADE_LEVEL_POLICY`
-
-All four members, every one a number: `minAtrPct` (the volatility floor, percent), `minStopLossAtrMultiple` and
-`maxStopLossAtrMultiple` (the hard stop's band, in ATR), `minRiskRewardRatio` (the target's floor over the stop).
-
-```json
-{
-  "kind": "strategy",
-  "targetId": "<STRATEGY_ID>",
-  "baseRevision": 12,
-  "axes": {
-    "TRADE_LEVEL_POLICY": {
-      "minAtrPct": 0.6,
-      "minStopLossAtrMultiple": 1.2,
-      "maxStopLossAtrMultiple": 2.5,
-      "minRiskRewardRatio": 1.8
-    }
-  }
-}
-```
-
-### `POSITION_MANAGEMENT`
-
-The exit policy, all thirteen members: `breakEvenEnabled`, `breakEvenTriggerR`, `trailingEnabled`,
-`trailingTriggerR`, `trailingGivebackPct`, `trailingBufferPct`, `timeDecayEnabled`, `timeDecayGracePeriodMinutes`,
-`timeDecayIntervalMinutes`, `timeDecayTightenPct`, `timeDecayMaxTightenPct`, `timeDecayStaleThresholdTpProgressPct`,
-`decisionInvalidationExitEnabled`. A mechanism switched off keeps its dial values: send them as read.
-
-### `CONDITIONS`
-
-`{ conditions: [...] }` — **every** condition of the strategy, in the order the strategy read serves them, each
-`{ conditionKey, name, definition, verdict, required, exitSide }` exactly as read, with your one change: a condition
-removed, or one existing condition's `required` or `verdict` changed. A dropped condition that another condition
-references is refused by the assessment. Composing a new condition column is authoring work, outside a review:
-record the finding and name the authoring flow as the owner's step.
-
-### `ENTRY`
-
-`{ entry: { trigger } }` for a trigger that takes no dials, or `{ entry: { trigger, levelOffsetAtrMultiple,
-validForBars } }` for a level trigger — the trigger the strategy read serves, or the one you propose, with every dial
-it honours and none it does not.
-
-### `REPORT`
-
-`{ sections: [...] }` — **every** section of the strategy's report, in the order `get_strategy` serves them, with
-your one change: a platform section added or removed. Each section is a reference: a platform section is
-`{ kind: 'platform', sectionKey }`, its key one `list_strategy_categories` serves; a custom section is
-`{ kind: 'custom', sectionKey }`, its `custom:<uuid>` key as `get_strategy` serves it, and nothing else — the submit
-takes its title, columns, benchmark and note from the committed report, so a review never edits one. A custom key the
-report does not carry is refused. A report that drops a section a condition reads is refused by the assessment: keep
-it, or propose the condition change first. Composing a new custom section is authoring work, outside a review.
-
-```json
-{
-  "kind": "strategy",
-  "targetId": "<STRATEGY_ID>",
-  "baseRevision": 12,
-  "axes": {
-    "REPORT": {
-      "sections": [
-        { "kind": "platform", "sectionKey": "includePriceAction" },
-        { "kind": "custom", "sectionKey": "custom:<SECTION_UUID>" },
-        { "kind": "platform", "sectionKey": "includeVolume" }
-      ]
-    }
-  }
-}
-```
-
-## Agent — `kind: 'agent'`, `targetId` the agent id
-
-Read the current values with `get_intelligence_agent`. One of four axes:
-
-### `TRADING_CONFIG`
-
-`{ tradingConfig: { ... } }` — the agent's complete trading configuration from `get_intelligence_agent`, less the two
-members the server derives (`strategyTimeframe`, `regimeTimeframe`): `minAllocationUsd`, `maxDailyTrades`,
-`balanceThresholdUsd`, `maxLeverage`, `maxSlippageBps`, `maxConcurrentExposureUsd`, `maxCumulativeDrawdownUsd`,
-`maxDailyLossUsd` and `positionSizePresets` (the whole preset ladder), each inside the bounds
-`get_trading_config_catalog` serves. Change the one rail the finding names; send the rest as read. A rail refusal
-names its rail as `tradingConfigMember` on the review read.
-
-### `BEHAVIOR`
-
-`{ behavior: { risk, outlook, conviction } }` — all three members, the ones you do not change as read: `risk` one of
-`CONSERVATIVE`, `MODERATE`, `AGGRESSIVE`; `outlook` one of `OPTIMIST`, `REALIST`, `PESSIMIST`; `conviction` one of
-`CAUTIOUS`, `MEASURED`, `BOLD`.
-
-### `MODEL`
-
-`{ modelId }` — a `modelId` `list_approved_models` serves now. The model sets what each decision costs: cite the
-agent's LLM spend against its net as the finding.
-
-### `STRATEGY_BINDING`
-
-`{ strategyId }` — an active strategy `list_strategies` serves: one the owner authored, or a library strategy. Never
-another user's, never an archived one. A rebind carries nothing else: the strategy and regime timeframes follow the
-new strategy, and each open position keeps the rules it opened under.
-
-```json
-{
-  "kind": "agent",
-  "targetId": "<AGENT_ID>",
-  "baseRevision": 14,
-  "axes": { "STRATEGY_BINDING": { "strategyId": "<STRATEGY_ID>" } }
-}
-```
-
-## Radar deployment — `kind: 'radar-deployment'`, `targetId` the coin id
-
-### `RULES`
-
-`{ rules: [...] }` — **every** rule slot of the coin's policy from `get_radar_deployment`, in priority order (the
-first is priority 1), the catch-all default excluded. Each rule is `{ agentId, minConviction, conditions }` as read,
-with the one rule that routes this agent changed. A rule's conditions are a non-empty list of:
-
-- `{ kind: 'regime', regimes: [...] }`, with an optional `minConviction` — the regimes the rule is on duty in, by
-  stored value (`bull_expansion`, `bear_expansion`, `bull_ranging`, `bear_ranging`, `contraction`, `volatile`);
-  excluding a losing regime is this list without it;
-- `{ kind: 'hours', hours: [...], days: [...] }` — UTC hours 0–23 and UTC weekdays 0 (Sunday) – 6, both non-empty.
-
-```json
-{
-  "kind": "radar-deployment",
-  "targetId": "<COIN_ID>",
-  "baseRevision": 4,
-  "axes": {
-    "RULES": {
-      "rules": [
-        {
-          "agentId": "<AGENT_ID>",
-          "minConviction": null,
-          "conditions": [
-            { "kind": "regime", "regimes": ["bull_expansion", "bull_ranging", "contraction"] }
-          ]
-        },
-        {
-          "agentId": "<OTHER_AGENT_ID>",
-          "minConviction": 0.6,
-          "conditions": [
-            { "kind": "hours", "hours": [13, 14, 15, 16], "days": [1, 2, 3, 4, 5] }
-          ]
-        }
-      ]
-    }
-  }
-}
-```
-
-Every agent a rule names is an agent the coin already routes: placing an agent on a coin is the owner's step, and the
-submit refuses a proposal naming any other.
-
-### `DEFAULT_SLOT`
-
-`{ defaultSlot: { agentId, minConviction } }` — the catch-all that takes the coin when no rule is on duty, its agent one
-the coin already routes; or `{ defaultSlot: null }` to remove the catch-all. Read it with `get_radar_deployment`.