@battlegrid/mcp-server 31.2.87 → 31.2.88

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

package/skills/EXPORT.json

@@ -1,18 +1,22 @@
 {
   "generator": "battlegrid-app/server/scripts/export-mcp-skills.mjs",
-  "contractVersion": "92.0.0",
+  "contractVersion": "105.0.0",
   "files": {
-    "battlegrid-agent-management/SKILL.md": "e5ffab64e6a369d5c783aed2b1c7c513b01b870063fd859c9cc4d9fc45d30aac",
-    "battlegrid-arena-play/SKILL.md": "01b2192c19b93b2315ff1a2b512ee0bcb7fd809c7d77fbbd93307fe2f45924a3",
+    "battlegrid-agent-management/SKILL.md": "8ebb7d4fcc5d6a9ce463a762bf58d04a7f641369f7feaf64d2489727531e6f00",
+    "battlegrid-agent-management/references/agent-stage-examples.md": "d47555906ce8dedf4c17422f8f5d60187f2d6b3c0af5d9545617a10a5bdb59a1",
+    "battlegrid-arena-play/SKILL.md": "25f078eb31db5cd3d78ce0bc251802c32f94234fd8a8c6467c5b68abc41706f2",
     "battlegrid-market-analysis/SKILL.md": "875bda71dd766ad06ac8e508679bcd3400a600cf74d2eac6c922dbe23175f325",
-    "battlegrid-radar-deployment/SKILL.md": "aaa4d13d32d470582d4bab0dc71594d4adf6b665bf45ee3384ee794dd8f82ba4",
-    "battlegrid-strategy-authoring/SKILL.md": "d4c5c87d9306193be8be77b1ade4938bbbc8805d66bc5267c00c2a8db156a92e",
+    "battlegrid-radar-deployment/SKILL.md": "093ac358cd4f1a67a7dd467b0b4161c9a055cdd516d49ebb23bd4e9ef44aa200",
+    "battlegrid-radar-deployment/references/arena-stage-examples.md": "f924b70801a4b72bbde5a80823408939903cba6b294d8554fc4afc11d80b3333",
+    "battlegrid-radar-deployment/references/radar-stage-examples.md": "1ddad4a11f021dd65234ee65cc12d7d1561fe9acfd61cb021f4352080d4cecd5",
+    "battlegrid-strategy-authoring/SKILL.md": "fcc4ab6ae7e75e0949cef057134288e5e6e67ff96d3238bb551775ba5ce22f95",
+    "battlegrid-strategy-authoring/references/strategy-stage-examples.md": "1c35353c7280934486b65d5defe80f87278e77955b6041db677238940e589b50",
     "battlegrid-strategy-doctor/SKILL.md": "14f20bff9e2b5a59d11634fe3615b1298d672d5e2eba06d3dc8698b571b3bee3",
-    "battlegrid-strategy-examples/SKILL.md": "d49ed36a864d1ead53c942979639d331b2bf375b50fffd745548a0acde39d641",
-    "battlegrid-strategy-examples/references/playbooks.md": "9e89b5cc8d80fc27bc331862fdc2403c26b36131b132614782c8425df74bcd28",
+    "battlegrid-strategy-examples/SKILL.md": "528049af46a0a829628681d16076129eb57e898445c803e4ebafae98699a3b65",
+    "battlegrid-strategy-examples/references/playbooks.md": "9e4038df885bb840d6ee58ba0475a9214dc58d12bf355c91c8aae625d58e3096",
     "battlegrid-strategy-examples/references/recipes.md": "61382acdd295fa159f055b787ba501f1c015f383f59a6714a973057f10de611f",
-    "battlegrid-strategy-examples/references/tradingview-ports.md": "2b13adbc137178955edcca31b6ab40c01c745a932a0750b91db8820c736700bb",
-    "battlegrid-trade-analysis/SKILL.md": "a1e666ca03bd641413096ed14806f101354f4e913e005faad6026a486143af0c",
+    "battlegrid-strategy-examples/references/tradingview-ports.md": "706a7dd3a120b2f3d5fa3190924f493cf4ebaf5df895bbeb155c2db73f8f5ece",
+    "battlegrid-trade-analysis/SKILL.md": "f545b916dc2a37c8fc35e16b27fa6f78ead4302e67f65ac584765c1e069b4ab2",
     "battlegrid-trade-proposal/SKILL.md": "d207a30065c17e13efaf5391805e5603e6956633cba5d0a1ff60e276518d9696"
   }
 }

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

@@ -125,7 +125,8 @@ mid-edit in their form**, and every change you make joins it. Then:
   read you proposed against returned (0 when it found no draft): it lands in their open form,
   labelled as yours. Each axis you send is written WHOLE — BEHAVIOR carries all three of risk,
   outlook and conviction, TRADING_CONFIG the complete configuration (step 6) — and the axes you
-  omit keep their values.
+  omit keep their values. Complete stage payloads — a create, a behavior change, a rebind — are in
+  `references/agent-stage-examples.md`.
 - **Read the stage's diagnostics.** Its `errors` are the refusals the commit would raise, each
   naming its field: fix the axis and stage again before you ask for anything.
 - A staging call refused **`DRAFT_AXIS_CONTESTED`** names an axis the player changed after the
@@ -193,10 +194,13 @@ is voting on a state you have not seen. A commit refused with `nextAct: stage` n
 diagnostics named: fix it in a stage, read, and confirm again.
 
 **A refused archive names its own blockers.** The refusal carries typed `archiveBlockers[]` —
-DEPLOYED / OPEN_TRADES / ACTIVE_SESSION, each with a count. Report each blocker and its count as
-the reason, and name what would clear it (un-deploy via the radar/deployment tools, close or let
-the positions resolve, wait for the session to settle). Never paraphrase the refusal into "it
-didn't work", and never retry it unchanged.
+DEPLOYED / OPEN_TRADES / ACTIVE_SESSION / RADAR_DEPLOYED, each with a count. Report each blocker and
+its count as the reason, and name what would clear it (un-deploy via the deployment tools, close or
+let the positions resolve, wait for the session to settle). RADAR_DEPLOYED counts paused radars too:
+a paused radar still holds the slot, so pausing does not clear it. Clearing it is a radar-deployment
+write, not this arc's: activate `radar-deployment` and let its arc find the coins whose radar holds
+the agent and un-deploy it there — a radar draft committed without the agent, or the coin's
+deployment deleted. Never paraphrase the refusal into "it didn't work", and never retry it unchanged.
 
 ### 5. Halt recovery: offer exactly the served verdict's exits
 

package/skills/battlegrid-agent-management/references/agent-stage-examples.md

@@ -0,0 +1,64 @@
+# Agent stage examples
+
+Complete `stage_agent_draft` inputs. Each is checked in CI against the live stage schema; a create example is also
+checked for every axis a new agent needs. Its shape is current.
+
+Every `<UPPER_SNAKE>` value is a placeholder. Replace it with the id a read returned:
+
+- `<AGENT_ID>` comes from the draft or the agent you are editing.
+- `<MODEL_ID>` is the row's `modelId` from `list_approved_models`.
+- `<STRATEGY_ID>` comes from the player's strategies.
+
+Never send a placeholder as written, and never invent an id. `draftVersion` is the version `get_agent_draft`
+returned: 0 when there was no draft, and for a new create draft. Each axis you send is written whole, and an axis
+you omit keeps the value the draft already has.
+
+## Create a new agent
+
+Omit `agentId` to open a create draft. The response carries the minted id, which every later call names. A new agent
+needs all four of IDENTITY, BEHAVIOR, MODEL and STRATEGY_BINDING. TRADING_CONFIG is optional: omit it to take the
+platform seed.
+
+```json stage_agent_draft
+{
+  "request": {
+    "draftVersion": 0,
+    "axes": {
+      "IDENTITY": { "displayName": "Breakout Scout" },
+      "BEHAVIOR": { "behavior": { "risk": "MODERATE", "outlook": "REALIST", "conviction": "MEASURED" } },
+      "MODEL": { "modelId": "<MODEL_ID>" },
+      "STRATEGY_BINDING": { "strategyId": "<STRATEGY_ID>" }
+    }
+  }
+}
+```
+
+## Change an existing agent's behavior
+
+BEHAVIOR is sent whole: all three of risk, outlook and conviction, even when only one changes.
+
+```json stage_agent_draft
+{
+  "request": {
+    "agentId": "<AGENT_ID>",
+    "draftVersion": 4,
+    "axes": {
+      "BEHAVIOR": { "behavior": { "risk": "CONSERVATIVE", "outlook": "REALIST", "conviction": "CAUTIOUS" } }
+    }
+  }
+}
+```
+
+## Rebind an existing agent to another strategy
+
+```json stage_agent_draft
+{
+  "request": {
+    "agentId": "<AGENT_ID>",
+    "draftVersion": 4,
+    "axes": {
+      "STRATEGY_BINDING": { "strategyId": "<STRATEGY_ID>" }
+    }
+  }
+}
+```

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

@@ -1,6 +1,6 @@
 ---
 name: battlegrid-arena-play
-description: Enter the player into Market Grid sessions — find an open session, read its coin pool and live market context, compose a grid with real per-coin reasoning or have one of their agents generate it, submit it against the session's entry fee, then read the results and the reasoning journal after settlement. Activate whenever the player wants to play, enter, join or submit to a session, wants their agent to enter one, asks what is open to play, or asks how a session they entered turned out.
+description: Enter the player into Market Grid sessions — find an open session, read its coin pool and live market context, compose a grid with real per-coin reasoning or have one of their agents generate it, submit it against the session's entry fee, then read the results and the player's own entry record after settlement. Activate whenever the player wants to play, enter, join or submit to a session, wants their agent to enter one, asks what is open to play, or asks how a session they entered turned out.
 ---
 
 # Arena Play
@@ -108,9 +108,12 @@ reasoning as the player's, and the attribution is part of what was scored.
 - `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 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`.
+- `get_my_market_grid_entry` on request — the player's own entry in that session: its picks, who
+  authored it, whether another author has rewritten it (`edited`), and the reasoning and confidence
+  recorded at submit. Compare the outcome against what was actually reasoned, and say where the
+  reasoning was wrong. `reasoning` is null once the entry was edited — the record no longer describes
+  the picks, so say that rather than reconstructing one. `list_my_market_grid_entries` is the history
+  across sessions. An agent's decisions are a different record, `get_agent_journal`.
 
 ## Refusals, and what each one means
 

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

@@ -113,6 +113,20 @@ is test-routing a regime. Never carry a fact from a radar conversation into it,
 To try a slot set without touching the draft, preview `{ kind: "SLOTS", slots }` — it resolves
 explicit slots and nothing can commit it.
 
+**Shaping a Radar rule.** A rule carries one or two conditions — never none. Pick the construction
+from what the player asked for:
+
+| The player wants the agent on duty… | Construction |
+|---|---|
+| whenever no rule matches | `DEFAULT_SLOT` — on duty only while no rule matches, so on a coin with no rules it is on duty at every instant |
+| only in named regimes | a rule with a regime condition |
+| only in named hours and days | a rule with an hours condition |
+| in named regimes during named hours | a rule with one hours condition and one regime condition |
+
+When the ask maps to no single row, or a refusal rules out the construction the player asked for,
+ask the player which construction they mean, naming the rows that fit — never stage one they did not
+choose. Complete stage payloads for every row are in `references/radar-stage-examples.md`.
+
 **Arena** — the same shape, keyed on `presetId`:
 
 1. `stage_deployment_policy_draft` with `draftVersion` = the `version` you read (0 when there was no
@@ -127,6 +141,21 @@ explicit slots and nothing can commit it.
 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).
 
+**Shaping an Arena rule.** A rule needs at least one condition by the time it is committed — a draft
+may hold a rule with none while the player is still choosing, and the draft read's diagnostics flag
+it. Pick the construction from what the player asked for:
+
+| The player wants the agent to play… | Construction |
+|---|---|
+| whenever no rule matches | `DEFAULT_SLOT` — plays only when no rule wins the session |
+| only in named regimes | a rule with a regime condition |
+| only at named session starts, or one scheduled occurrence | a rule with one session condition — a start or an occurrence |
+| in named regimes at those sessions | a rule with a regime condition and one session condition |
+
+When the ask maps to no single row, or a refusal rules out the construction the player asked for,
+ask the player which construction they mean, naming the rows that fit — never stage one they did not
+choose. Complete stage payloads for every row are in `references/arena-stage-examples.md`.
+
 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
 repeatedly while iterating is free and correct.

package/skills/battlegrid-radar-deployment/references/arena-stage-examples.md

@@ -0,0 +1,140 @@
+# Arena stage examples
+
+Complete `stage_deployment_policy_draft` inputs, one per construction in **Shaping an Arena rule**. Each is checked in
+CI against the live stage schema and composed into a deployment the aggregate accepts, so its shape is current.
+
+Every `<UPPER_SNAKE>` value is a placeholder. Replace it with the id a read returned:
+
+- `<PRESET_ID>` comes from `list_game_presets`.
+- `<AGENT_ID>` comes from your agent list.
+- `<COIN_ID>` comes from the arena's coin pool.
+
+Never send a placeholder as written, and never invent an id. `draftVersion` is the version
+`get_deployment_policy_draft` returned: 0 when the arena has no draft. Each axis you send is written whole, and an
+axis you omit keeps the value the draft already has.
+
+## Play whenever no rule matches — the default slot
+
+```json stage_deployment_policy_draft
+{
+  "request": {
+    "presetId": "<PRESET_ID>",
+    "draftVersion": 0,
+    "axes": {
+      "DEFAULT_SLOT": {
+        "defaultSlot": { "agentId": "<AGENT_ID>", "minConfidence": null, "entryStrategy": "STANDARD" }
+      }
+    }
+  }
+}
+```
+
+## Play only in named regimes
+
+```json stage_deployment_policy_draft
+{
+  "request": {
+    "presetId": "<PRESET_ID>",
+    "draftVersion": 0,
+    "axes": {
+      "RULES": {
+        "rules": [
+          {
+            "agentId": "<AGENT_ID>",
+            "minConfidence": null,
+            "entryStrategy": "STANDARD",
+            "conditions": [{ "kind": "regime", "regimes": ["bull_expansion", "bull_ranging"] }]
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+## Play only at named session starts
+
+Start times are UTC `HH:MM:SS`. Days run 0 (Sunday) to 6. Each is listed once. A rule holds a session start or a
+session occurrence, never both.
+
+```json stage_deployment_policy_draft
+{
+  "request": {
+    "presetId": "<PRESET_ID>",
+    "draftVersion": 0,
+    "axes": {
+      "RULES": {
+        "rules": [
+          {
+            "agentId": "<AGENT_ID>",
+            "minConfidence": 0.6,
+            "entryStrategy": "TWO_LOOK",
+            "conditions": [
+              { "kind": "session_start", "startTimes": ["14:00:00", "15:00:00"], "days": [1, 2, 3, 4, 5] }
+            ]
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+## In named regimes at those sessions — a regime condition and one session condition
+
+```json stage_deployment_policy_draft
+{
+  "request": {
+    "presetId": "<PRESET_ID>",
+    "draftVersion": 0,
+    "axes": {
+      "RULES": {
+        "rules": [
+          {
+            "agentId": "<AGENT_ID>",
+            "minConfidence": null,
+            "entryStrategy": "STANDARD",
+            "conditions": [
+              { "kind": "regime", "regimes": ["volatile"] },
+              { "kind": "session_start", "startTimes": ["14:00:00"], "days": [1, 2, 3, 4, 5] }
+            ]
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+## Override the regime anchor on a deployed arena
+
+This stages only `REGIME_ANCHOR`, so the deployed rules and default slot stay as they are. The coin and the timeframe
+come together, or not at all.
+
+```json stage_deployment_policy_draft
+{
+  "request": {
+    "presetId": "<PRESET_ID>",
+    "draftVersion": 2,
+    "axes": {
+      "REGIME_ANCHOR": { "regimeAnchor": { "regimeReferenceCoinId": "<COIN_ID>", "regimeTimeframe": "4h" } }
+    }
+  }
+}
+```
+
+## Clear the regime anchor override
+
+The arena's own anchor applies again.
+
+```json stage_deployment_policy_draft
+{
+  "request": {
+    "presetId": "<PRESET_ID>",
+    "draftVersion": 2,
+    "axes": {
+      "REGIME_ANCHOR": { "regimeAnchor": null }
+    }
+  }
+}
+```

package/skills/battlegrid-radar-deployment/references/radar-stage-examples.md

@@ -0,0 +1,155 @@
+# Radar stage examples
+
+Complete `stage_radar_deployment_draft` inputs, one per construction in **Shaping a Radar rule**. Each is
+checked in CI against the live stage schema and composed into a policy the aggregate accepts, so its
+shape is current.
+
+Every `<UPPER_SNAKE>` value is a placeholder. Replace it with the id a read returned:
+
+- `<COIN_ID>` comes from `get_coin_metadata`.
+- `<AGENT_ID>` comes from your agent list.
+- `<OTHER_AGENT_ID>` is a second agent from your agent list, where an example deploys two.
+
+Never send a placeholder as written, and never invent an id. `draftVersion` is the version
+`get_radar_deployment_draft` returned: 0 when the coin has no draft. Each axis you send is written whole, and an axis
+you omit keeps the value the draft already has.
+
+## On duty whenever no rule matches — the default slot
+
+On a coin with no rules, the default slot is on duty at every instant. This is the construction for "put this agent
+on this coin" with no condition named.
+
+```json stage_radar_deployment_draft
+{
+  "request": {
+    "coinId": "<COIN_ID>",
+    "draftVersion": 0,
+    "axes": {
+      "DEFAULT_SLOT": { "defaultSlot": { "agentId": "<AGENT_ID>", "minConviction": null } }
+    }
+  }
+}
+```
+
+## On duty only in named regimes
+
+`minConviction` on the rule is the trade bar (0–1, or null to inherit the agent's). `minConviction` inside the
+regime condition is the regime-reading floor, and must be a level one of the selected regimes can emit.
+
+```json stage_radar_deployment_draft
+{
+  "request": {
+    "coinId": "<COIN_ID>",
+    "draftVersion": 0,
+    "axes": {
+      "RULES": {
+        "rules": [
+          {
+            "agentId": "<AGENT_ID>",
+            "minConviction": null,
+            "conditions": [
+              { "kind": "regime", "regimes": ["bull_expansion", "bull_ranging"], "minConviction": "high" }
+            ]
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+## On duty only in named hours and days
+
+Hours are UTC, 0–23. Days run 0 (Sunday) to 6. Each is listed once.
+
+```json stage_radar_deployment_draft
+{
+  "request": {
+    "coinId": "<COIN_ID>",
+    "draftVersion": 0,
+    "axes": {
+      "RULES": {
+        "rules": [
+          {
+            "agentId": "<AGENT_ID>",
+            "minConviction": null,
+            "conditions": [
+              { "kind": "hours", "hours": [13, 14, 15, 16, 17, 18, 19, 20], "days": [1, 2, 3, 4, 5] }
+            ]
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+## In named regimes during named hours — one condition of each kind
+
+```json stage_radar_deployment_draft
+{
+  "request": {
+    "coinId": "<COIN_ID>",
+    "draftVersion": 0,
+    "axes": {
+      "RULES": {
+        "rules": [
+          {
+            "agentId": "<AGENT_ID>",
+            "minConviction": 0.6,
+            "conditions": [
+              { "kind": "hours", "hours": [13, 14, 15, 16], "days": [1, 2, 3, 4, 5] },
+              { "kind": "regime", "regimes": ["volatile"] }
+            ]
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+## Rules plus a default slot
+
+Every rule that matches is on duty, and the first rule listed is offered the coin's fire first. The default slot is
+on duty only while no rule matches, so here the second agent is on duty whenever the coin is in neither of the
+first agent's regimes.
+
+```json stage_radar_deployment_draft
+{
+  "request": {
+    "coinId": "<COIN_ID>",
+    "draftVersion": 0,
+    "axes": {
+      "RULES": {
+        "rules": [
+          {
+            "agentId": "<AGENT_ID>",
+            "minConviction": null,
+            "conditions": [{ "kind": "regime", "regimes": ["bear_expansion", "bear_ranging"] }]
+          }
+        ]
+      },
+      "DEFAULT_SLOT": { "defaultSlot": { "agentId": "<OTHER_AGENT_ID>", "minConviction": null } }
+    }
+  }
+}
+```
+
+## Clear the default slot on a deployed coin
+
+This stages only `DEFAULT_SLOT`, so the deployed rules stay as they are. Send `RULES` only when the rules change, and
+then send the complete list: a rule you do not resend is deleted. `draftVersion` here is the version your read
+returned.
+
+```json stage_radar_deployment_draft
+{
+  "request": {
+    "coinId": "<COIN_ID>",
+    "draftVersion": 3,
+    "axes": {
+      "DEFAULT_SLOT": { "defaultSlot": null }
+    }
+  }
+}
+```

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

@@ -129,12 +129,29 @@ question you would otherwise guess — and a refusal you would otherwise earn:
   it — its own `hold: { atLeast, of }`, which the editor calls **Hold** (Once, In a row, Within, At
   least), counted in completed bars of the column's own timeframe — not to this axis. Every clause
   and group carries `hold`; `{ "atLeast": 1, "of": 1 }` is Once. The `strategy-examples` skill
-  carries the vocabulary, the served hold domain (a crossover is held "within" only; a Developing
-  column cannot be held) and the per-column Confirmed / Developing read.
+  carries the vocabulary, the served hold domain (a crossover or an edge operator — `crossesAbove`,
+  `crossesBelow`, `enters`, `exits` — is held "within" only; a Developing column cannot be held) and
+  the per-column Confirmed / Developing read.
+- **What a bar did is its own vocabulary.** A touch or a rejection of a level, a candle pattern, a
+  gap and a run of bars are composed from the `strategy-examples` skill's **Bar geometry** section —
+  `levelInteraction` over a level with its `buffer` knob, and the pattern, gap, run and price-source
+  metrics. A level BREAK is a `distance` crossing over the same level, never a `levelInteraction`
+  label.
+- **Swing structure is its own section.** Swing highs and lows, the `HH`/`HL`/`LH`/`LL` label and the
+  break-of-structure recipes are in the `strategy-examples` skill's **Swing structure** section.
 - `get_strategy_column_contract` → `outputs[].conditionOperators`. An empty array means that
   rendered header has no comparison semantics and cannot appear in a condition clause at all.
   Legality is per rendered header, not per column: a trajectory's slot header and its `_trend`
   header answer differently.
+- `get_strategy_column_contract` → `lookback`, `measurement` and `seriesHome`. `lookback.used` is
+  the bars the column reads against `lookback.cap`, the column-lookback budget a save holds it to —
+  a column past the cap is refused with `REPORT_COLUMN_LOOKBACK_EXCEEDED` by this tool exactly as by
+  the save, so shrink its window or offset rather than staging it. `measurement` names how the
+  transform (and a chained transform) reads its series: the read shape, the window's unit, the price
+  basis and what an absent bar does. `seriesHome` says where the metric's series is kept — `candle`,
+  `history`, or `null` when the metric has no series, which is why a series transform does not
+  compose on it. Window and offset carry a declared `minimum` and no fixed maximum; the lookback
+  cap is the bound.
 - `get_metric_construction_hints` → `rankOrderings`. Present only when rank is composable on that
   metric, already range-gated server-side — read the offered set rather than deriving one from
   the metric's native output.
@@ -160,7 +177,8 @@ asked to approve.
 the `axes` you propose. It writes those axes into the player's draft — attributed to you, landing in
 their builder as unsaved changes — and commits nothing. Each stage returns the draft's new
 `version`: that is the `draftVersion` your next stage names. Stage each change once, and never fire
-two stages in parallel against one draft.
+two stages in parallel against one draft. Complete stage payloads showing the envelope are in
+`references/strategy-stage-examples.md`.
 
 **A new strategy is a create draft.** Omit `strategyId` and send `draftVersion: 0` on the first
 stage; the response carries the id minted for it, which every later call names. A create needs

package/skills/battlegrid-strategy-authoring/references/strategy-stage-examples.md

@@ -0,0 +1,50 @@
+# Strategy stage examples
+
+`strategyId` and `draftVersion` sit beside `axes`, inside `request` — never inside `axes`. Every example below is
+checked in CI against the live `stage_strategy_draft` schema; a create example is also checked for the axes a new
+strategy needs. Its shape is current.
+
+These examples show the envelope and the small axes. A full composition (report sections, conditions, signal
+rules) is in `strategy-examples`' playbooks, which have their own compile gate.
+
+Every `<UPPER_SNAKE>` value is a placeholder: `<STRATEGY_ID>` is the id a read returned. Never send a placeholder as
+written, and never invent an id. `draftVersion` is the version `get_strategy_draft` returned: 0 when there was no
+draft, and for a new create draft. Each axis you send is written whole, and an axis you omit keeps the value the draft
+already has.
+
+## Open a create draft
+
+Omit `strategyId`. The response carries the minted id, which every later call names. A new strategy needs IDENTITY
+and TIMEFRAME_PROFILE before it can be created.
+
+```json stage_strategy_draft
+{
+  "request": {
+    "draftVersion": 0,
+    "axes": {
+      "IDENTITY": {
+        "name": "Squeeze Breakout",
+        "description": "Enters when a volatility squeeze resolves upward on rising volume.",
+        "tagline": "Buys the release of a tight range"
+      },
+      "TIMEFRAME_PROFILE": { "timeframe": "1h" }
+    }
+  }
+}
+```
+
+## Change an existing strategy's setup gates
+
+SETUP_GATES is sent whole: all three gates, even when only one changes.
+
+```json stage_strategy_draft
+{
+  "request": {
+    "strategyId": "<STRATEGY_ID>",
+    "draftVersion": 2,
+    "axes": {
+      "SETUP_GATES": { "minAggregateScore": 60, "minRequiredCount": 1, "minAtrPct": 0.5 }
+    }
+  }
+}
+```

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

@@ -44,10 +44,11 @@ Before committing a CREATE, every "no" here is a decision to state, not an omiss
 | `efficiency` wN | `<code>_er` (1 straight, ~0 chop) | `close_ltf_er` |
 | `maxShare` wN | `<code>_maxShare` | `volBase_ltf_maxShare` |
 | `classifyZone` / `classifyState` | `<code>_zone` / `<code>_state` | `RSI14_zone`, `ADX_state` |
+| `levelInteraction` | `<code>_lvl`, `<code>_lvl_b<N>` at a buffer of N bps | `bbUpper_lvl`, `bbUpper_lvl_b25` |
 
 Non-anchor rungs affix `_ltf` (lower) / `_htf` (regime): `MAalign_htf`,
 `zones_htf_support_dist`. Chains are bounded at two: inner `distance`/`spread` → outer
-`trajectory`/`aggregate`/`efficiency`/`maxShare`/`rank` (`EMA5 spread EMA13 × trajectory` →
+`trajectory`/`aggregate`/`rank` (`EMA5 spread EMA13 × trajectory` →
 `EMA5_EMA13_spread_now` + `_trend`).
 
 **Timeframe references are two families.** *Relative* (`anchor`/`lower`/`regime`) re-resolve
@@ -84,7 +85,11 @@ no timeframe reference at all: bind them `{rel: 'anchor'}` — the default — a
 previous UTC session from any anchor. An absolute reference is REFUSED at save, including `1d`,
 because there is no rung for one to select. They are catalogued price levels, so `dist_PDH gte 0`
 composes directly. (`distance` still rejects an `offset`, and a clause still compares a column
-against a literal; neither of those shapes is what a previous-session level needed.)
+with a literal or with its own previous completed bar, never with another column; neither of those
+shapes is what a previous-session level needed.) The same holds
+for every timeless metric — these levels, funding, the regime and the other bundle
+reads: a `value` column over one accepts only `offset: 0`, and a larger offset is REFUSED at save,
+because there is no earlier bar to cut back to.
 
 ## Conditions
 
@@ -92,8 +97,11 @@ against a literal; neither of those shapes is what a previous-session level need
 required, no defaults. A `clock` key is REFUSED (the per-condition evidence clock was retired in
 contract `61.0.0`), so is a condition-level `closes` key — the hold lives on each clause and each
 group (contract `84.0.0`) — and so is a boolean `exit` key: the side an exit closes is its own
-`exitSide` (contract `88.0.0`). Clauses: numeric/rank headers take `lt|lte|gte|gt|between`;
-classification/direction headers take `is|in` with the served vocabulary. Groups:
+`exitSide` (contract `88.0.0`). Clauses — the operator a header takes is served per header
+(`conditionOperators`), by its output kind: numeric headers take the comparisons
+`lt|lte|gte|gt|between` and the prior-bar operators `crossesAbove|crossesBelow|increased|decreased`;
+rank headers take the comparisons only; classification, direction and boolean headers take
+`is|in|enters|exits` with the served vocabulary; event headers take `is|in`. Groups:
 `ALL | ANY | NOT | N_OF` (with `n`), depth ≤ 2. Every clause and every group carries a required
 `hold: { atLeast, of }` — `{ "atLeast": 1, "of": 1 }` is a single read; a clause or group without
 `hold` is refused (`CONDITION_HOLD_INVALID`). `conditionRef` composes named conditions (no
@@ -104,6 +112,46 @@ decider — so order breaks ties between carriers that AGREE. Carriers that DISA
 `NEITHER` and stand the coin aside; declaration order never picks a side between them. Building
 blocks carry `null`.
 
+**Prior-bar operators — a column against its own previous completed bar.** A clause compares its
+column with a literal, or with the same column's reading on the completed bar before the one it
+decides — never with another column. Six operators read that prior bar:
+
+| Operator | Literal | TRUE when |
+|---|---|---|
+| `crossesAbove` | a number `L` | `x > L` on the decided bar and `x ≤ L` on the bar before |
+| `crossesBelow` | a number `L` | `x < L` on the decided bar and `x ≥ L` on the bar before |
+| `increased` | none | `x` is strictly above its prior-bar reading |
+| `decreased` | none | `x` is strictly below its prior-bar reading |
+| `enters` | one label | the label is read now and was not on the bar before |
+| `exits` | one label | the label was read on the bar before and is not now |
+
+The crossing boundary is Pine's (`ta.crossover`): a bar sitting exactly on `L` has not crossed until a
+later bar closes above it. A change takes no literal at all — `{ "op": "increased" }` with no `value`.
+A prior-bar clause reads COMPLETED bars only, on every surface: the decided bar and the one before
+it, never the forming bar, so it is never provisional. A failed read on either bar is UNRESOLVED; a
+bar with no value (a null) reads FALSE. A header admits them only where its stored history keeps the
+bar before: a header whose `conditionHold.maxWindow` is 1 is served none of the six, so
+`vol24hUsd increased` is refused (`CONDITION_OPERATOR_UNSUPPORTED`, naming the operators it does
+admit), and on a header that keeps them each reads one bar less than its window.
+
+**An edge is held "within n closes" only.** `crossesAbove`, `crossesBelow`, `enters` and `exits` mark
+the bar a state changed, so like a crossover event their `maxAtLeast` is 1 — hold them "within n
+closes", never "in a row". `increased` and `decreased` are no edge: "3 closes in a row" of
+`increased` is three rising closes. A group whose members must all read TRUE together (`ALL`) over an
+edge admits "within" only too. Every prior-bar read counts toward the frame-read budget: a clause
+held "within 3 closes" reads four bars.
+
+Recipes — each one clause:
+
+- **Close crossed above the 20 SMA** — `dist_SMA20 crossesAbove 0` (the Moving Averages module).
+  `dist_SMA20` is the close's distance from the average, so crossing 0 is the close crossing it.
+- **RSI entered overbought** — `RSI14_zone enters "overbought"` (the RSI module).
+- **Squeeze released** — `kcSqueeze exits "on"`, over a `KC_SQUEEZE` value column.
+- **New 20-bar high** — `donchianHi increased`, over a `DONCHIAN_UPPER` value column: the 20-bar
+  upper channel rises exactly when the decided bar's high exceeds every high of the 20 bars before it.
+- **RSI crossed above 50 within the last 3 closes** — `RSI14_now crossesAbove 50` holding
+  `{ "atLeast": 1, "of": 3 }`.
+
 **Two things block a trade, not one.** `required: true` = a FALSE reading blocks compose-trade
 before billing. And the RESOLVED verdict binds entry DIRECTION: `UP` admits long setups only,
 `DOWN` short only, and `NEITHER`/`UNRESOLVED` admit none — the refused side is absent from the
@@ -247,10 +295,12 @@ it opened under, with the report and timeframes they read: an exit-rule edit app
 opened after it, and an open position keeps the exit rules it opened with, so an open position never
 refuses a commit or a rebind.
 
-**A state column is not a flip event.** `ST_DIR` reads the same on every bar of a trend, so
-`ST_DIR is "bullish"` is a regime filter and never an entry signal. The flip needs an event column
-beside it — an `EMA5_13` cross, or a `ST_DIR` trajectory whose `_trend` changes. The same distinction
-applies to every persisting classification: `MAalign`, `ADX_state`, `zone`.
+**A state column is not a flip event — `is` reads the state, `enters` reads the flip.** `ST_DIR`
+reads the same on every bar of a trend, so `ST_DIR is "bullish"` is a regime filter and never an
+entry signal. The flip is `ST_DIR enters "bullish"`: TRUE on the one completed bar the direction
+turned, with no event column needed. The same distinction applies to every persisting
+classification: `MAalign`, `ADX_state`, `zone` — `is` for the regime, `enters` / `exits` for the
+bar it changed.
 
 **Name the anchor when a metric is calibrated for one.** `KC_SQUEEZE is "on"` reads *on* about 57% of
 1h crypto bars even at canonical parameters — Bollinger σ is close-to-close while ATR captures
@@ -258,6 +308,145 @@ intrabar range, so σ/ATR runs low here — against about 19% at 15m. It is a se
 below and close to useless at 1h. A metric whose selectivity depends on the anchor is stated with the
 anchor, or the author gates on something that admits most bars.
 
+## Bar geometry
+
+What one bar did — against a price level, in its own shape, against the bar before it, and how many
+bars ran one way. Every value here reads the bar's own open, high, low and close, so it is a candle
+column: it takes a timeframe reference and the Confirmed / Developing selector like any other.
+
+**`levelInteraction` — what the bar did at a level.** It classifies the newest bar of the column as
+one of five labels: `touch_from_below`, `touch_from_above`, `reject_from_below`, `reject_from_above`,
+`none`. The side is where the PRIOR close stood against the PRIOR bar's level — from below when it
+closed at or under it — so a level that moved between the two bars is judged on the bar it stood at.
+From below: a bar that closes through the level is a break and reads `none`; a bar whose high
+reached the level and whose close came back under it is `reject_from_below`; a bar whose high came
+within the buffer of the level is `touch_from_below`. From above is the mirror on the low.
+
+- **A reject bar reports reject.** It is never also reported as a touch, so "touched or rejected" is
+  an `in` clause over both labels of a side: `bbUpper_lvl in ["touch_from_below","reject_from_below"]`.
+- **`buffer`** is whole basis points of the level, 0–500, default 0 — `buffer: 25` is 0.25%. Only the
+  touch reads it: a reject must pierce the level itself. Two buffers are two columns (`bbUpper_lvl`,
+  `bbUpper_lvl_b25`).
+- **A break is a crossing, never a label.** The break of a level is `distance` over the same level
+  crossing 0: `dist_bbUpper crossesAbove 0` from below, `crossesBelow 0` from above. On the strategy's
+  own rung a `…_from_below` label never holds on a bar where `crossesAbove 0` holds.
+- **Which levels take it.** A candle-homed level — a band (`BB_UPPER`, `BB_LOWER`, `KC_UPPER`,
+  `KC_MID`, `KC_LOWER`), `VWAP`, a moving average (`SMA20`, `EMA20`, …), `ST_LINE`, `PSAR`, the
+  Ichimoku lines, the swing levels (`SWING_FRACTAL_HIGH`, `SWING_FRACTAL_LOW`) — reads its own value at
+  each of the two bars. A prior-session level or pivot (`PDH`,
+  `PDL`, `PDO`, `PIVOT_P`, `PRIOR_TPO_POC`, …) has one reading for the session, used as both bars' level;
+  a clause over it is a single read with no hold, because the session profile keeps no earlier
+  reading. A developing-session level (`TPO_POC`, `TPO_VAH`, …) and the naked points of control move
+  between bars with no earlier reading kept, so they are not offered it; neither are the Donchian
+  rails (`DONCHIAN_UPPER`, `DONCHIAN_LOWER`), each the extreme of the window ending at the very bar it
+  would classify, which a close can never pass. A price fact (`CLOSE`, `HLC3`, `MARK`) is refused: it
+  is the price, not a level.
+- **A higher-rung level reads that rung's completed bar.** `bbUpper_htf_lvl` classifies the last
+  completed regime-rung bar from its own high, low and close, never the strategy bar's price — so
+  compose its break on the same rung, `dist_bbUpper_htf crossesAbove 0`.
+
+**`BB_TOUCH` and `BB_UPPER × levelInteraction` answer different questions.** `BB_TOUCH` (`BBtouch`)
+says where the CLOSE sits in %B — inside the band edge or not. `BB_UPPER × levelInteraction` says what
+the bar's RANGE did at the edge — touched it, or pierced it and closed back.
+
+**Candle patterns** — the bar's shape against the ten bars before it (TA-Lib's default settings). A
+pattern carries no trend context: "a hammer in a downtrend" is `pin is "lower_wick"` plus a separate
+trend clause.
+
+| Key | Header | Labels |
+|---|---|---|
+| `CANDLE_DOJI` | `doji` | boolean: the body is at most a tenth of the average range |
+| `CANDLE_PIN` | `pin` | `lower_wick`, `upper_wick`, `none` — a short body with one long wick |
+| `CANDLE_ENGULFING` | `engulf` | `bullish`, `bearish`, `none` — the body engulfs the prior opposite body |
+| `BAR_CONTAINMENT` | `barContain` | `inside`, `outside`, `none` — the range inside, or around, the prior range |
+
+**Gaps** — the open against the bar before it, as three separate keys.
+
+| Key | Header | Reads |
+|---|---|---|
+| `GAP` | `gap` | `up`, `down`, `none` — the open above the prior high, or below the prior low |
+| `GAP_RANGE_CLEAR` | `gapClear` | `up`, `down`, `none` — the whole range clear of the prior range (stricter) |
+| `GAP_PCT` | `gapPct` | the signed % from the prior close to the open |
+
+**Runs** — report columns counting consecutive bars, capped at ±20. Gating "three closes in a row" is
+the hold's job; a run column shows the streak.
+
+| Key | Header | Counts |
+|---|---|---|
+| `CLOSE_RUN` | `closeRun` | consecutive closes above (+) or below (−) the close before |
+| `CANDLE_RUN` | `candleRun` | consecutive candles of the newest bar's colour, white (+) or black (−) |
+
+**Price sources** — per-bar price facts that take every transform a close takes: `HL2` (`hl2`,
+median), `HLC3` (`hlc3`, typical), `OHLC4` (`ohlc4`, average).
+
+**"Within the last N closed bars" is the hold `{ "atLeast": 1, "of": N }`.** A pattern or a gap held
+within N reads each of the N bars against its own predecessor.
+
+Recipes — the level recipes on candle-homed levels:
+
+- **Price rejected the upper Bollinger band** — a `BB_UPPER × levelInteraction` column, header
+  `bbUpper_lvl`; the clause `bbUpper_lvl is "reject_from_below"`.
+- **Price touched or rejected VWAP from above** — `VWAP_lvl in ["touch_from_above","reject_from_above"]`,
+  with `buffer: 10` for a touch within 0.1% (header `VWAP_lvl_b10`).
+- **Price broke the 20 EMA** — `dist_EMA20 crossesAbove 0`, the `distance` column over the same level.
+- **A bullish engulfing within the last 3 bars** — `engulf is "bullish"` holding
+  `{ "atLeast": 1, "of": 3 }`.
+- **An inside bar** — `barContain is "inside"`.
+- **A gap up** — `gap is "up"`; `gapClear is "up"` when the whole range must clear.
+- **A run of candles as a report column** — a `CANDLE_RUN` value column (`candleRun`) beside the
+  thesis columns; no clause needed.
+- **The 20-bar simple moving average of typical price** — `HLC3 × aggregate(20)` with
+  `aggregate: "mean"`, header `hlc3_mean20`.
+
+## Swing structure
+
+Swing highs, swing lows and the structure they spell, from the market-data swing engine. Every value
+is stored under the bar it describes, so a swing column holds and takes the prior-bar operators like
+any candle column.
+
+| Key | Header | Reads |
+|---|---|---|
+| `SWING_FRACTAL_HIGH` | `fractalHi` | the most recent swing high — a price level |
+| `SWING_FRACTAL_LOW` | `fractalLo` | the most recent swing low — a price level |
+| `SWING_FRACTAL_LABEL` | `fractalLabel` | `HH`, `HL`, `LH`, `LL`, `none` — the most recent swing against the one before it on its side |
+
+**The rule.** A swing high is a bar whose high is at or above the highs of the two bars before it and
+strictly above the highs of the two bars after it; a swing low mirrors it on the lows. An equal extreme
+is allowed on the left and not on the right, so of a run of equal highs the newest is the swing (Pine's
+`ta.pivothigh(2, 2)`). A swing is published from the bar that completes its right side — two bars
+after its own — never earlier and never from a forming bar. Each level is held until the next swing on
+its side replaces it.
+
+- **The label is a held state, not an event.** It reads the most recent swing: `HH` / `LH` for a high
+  (an equal high is `LH` — it failed to make a higher high), `HL` / `LL` for a low (an equal low is
+  `HL`), `none` when no comparable pair is in reach. On too short a history it reads nothing, and a
+  clause over it reads FALSE.
+- **A swing level does not remember a broken level.** Two to four bars after a break the level steps
+  to the next swing, so a retest of the BROKEN level is not a swing-level read.
+- **The two levels take what every candle level takes** — `distance`, `spread`, `aggregate`,
+  `trajectory`, `efficiency` and `levelInteraction` — and both rank across the board
+  (`dist_fractalHi_rank_near`: the coins closest to their own last swing high).
+- **The break is the crossing toward the level.** `dist_fractalHi crossesAbove 0` is a close through the
+  last swing high and never fires when the level steps onto a new swing, because the bar that confirms
+  a swing high sits under it. The opposite crossing (`dist_fractalHi crossesBelow 0`, or
+  `dist_fractalLo crossesAbove 0`) CAN fire on the bar the level steps past the close — it is not a
+  break.
+- **A swing confirmed on the break bar can already have moved the label**, so a structure condition
+  paired with a break is held over the bars before it.
+
+Recipes:
+
+- **The swing structure is bullish** — `fractalLabel in ["HH","HL"]`.
+- **A higher high was confirmed on this bar** — `fractalHi increased` (it also catches a second
+  higher high in a row, which `fractalLabel enters "HH"` cannot); `fractalHi decreased` is a lower
+  high.
+- **Bullish break of structure** — a `SWING_FRACTAL_HIGH × distance` column, header `dist_fractalHi`;
+  the clause `dist_fractalHi crossesAbove 0`.
+- **Bearish break of structure** — `dist_fractalLo crossesBelow 0`.
+- **A break of the last swing low while the structure was bullish** — `dist_fractalLo crossesBelow 0`
+  together with `fractalLabel in ["HH","HL"]` holding `{ "atLeast": 1, "of": 3 }`, so the bullish
+  read may sit on the bars before the break.
+
 ## Entry
 
 `{ trigger, levelOffsetAtrMultiple, validForBars }` — the axis's keys, and the trigger decides
@@ -385,8 +574,8 @@ RR 2, BE 1R, trail 1.2R/giveback 35 · swing trend (4h) 1.0–2.5 ATR, RR 2, BE
 
 The one place a claim that the catalog LACKS something may live, and every row names the key it
 denies so the claim can be checked. A claim about the grammar's shape (a clause compares one
-column against a literal; `distance` rejects an `offset`) belongs in prose above — those are
-permanent. A claim that a metric is absent belongs here, or nowhere.
+column with a literal or with its own previous completed bar, never with another column; `distance`
+rejects an `offset`) belongs in prose above — those are permanent. A claim that a metric is absent belongs here, or nowhere.
 
 | Script / primitive | Key the catalog would need | Nearest expressible neighbour |
 |---|---|---|

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

@@ -87,13 +87,13 @@ would be ambiguous. Conditions: `HTF_UP` building block (`MAalign_htf is "bullis
 
 Platform `includePerpSpotFlow` (`perpSpotFlow` vocab: confirmed_bull / confirmed_bear /
 perp_led_fragile / spot_led_accumulation / neutral), `includeStructureZones`
-(`zones_htf_support_dist` signed %, support below price is negative; `_age_h`), custom `Tape`
+(`zones_htf_support_dist` signed % of price from the zone midpoint, positive above a support zone; `_age_h`), custom `Tape`
 (`BUY_PRESSURE value`→`buyPres` 0–1, `RVOL value`, `CLOSE_CHANGE value`). Conditions:
 `SPOT_ACCUM` (`perpSpotFlow is "spot_led_accumulation"`); `NEAR_SUPPORT`
-(`zones_htf_support_dist between -2 0` + `zones_htf_support_age_h gte 12`); `DIP_BID` verdict
+(`zones_htf_support_dist between 0 2` + `zones_htf_support_age_h gte 12`); `DIP_BID` verdict
 UP — refs plus an `N_OF(2)` quorum over `buyPres gte 0.55` / `RVOL gte 1.2` / `closeChg gt 0`
 (quorum beats a brittle ALL); `FRAGILE_POP` verdict DOWN (`perp_led_fragile` +
-`zones_htf_resist_dist between 0 2` + `RVOL gte 1.3`). Rules:
+`zones_htf_resist_dist between -2 0` + `RVOL gte 1.3`). Rules:
 `flow_perp_spot_bull_divergence`/`_bear_divergence` 3 required · `cvd_bull_divergence`/
 `_bear_divergence` 2 · `sr_at_support`/`_at_resistance` 2 · `structure_ob_approach` 1 ·
 `volume_surge` 1. Gates 0.55 / 1 / 0.4. Levels 0.5–1.2 ATR, RR 1.5. PM: BE 0.7R; trail 0.9R

package/skills/battlegrid-strategy-examples/references/tradingview-ports.md

@@ -12,6 +12,7 @@ engine) and names its substitutions where the catalog lacks a primitive.
 - VWAP reversion
 - Donchian / Turtle breakout
 - ICT / SMC (FVG + order blocks)
+- Pivot highs / lows, HH-HL structure and break of structure
 - Now native, formerly substituted
 
 ## TradingView ports — familiar processes, studio vocabulary
@@ -40,8 +41,9 @@ rules about the columns themselves, not about porting — they live in the skill
   distance to the plotted stop. The plotted trailing line is still best executed by the studio's
   own stop engine — `trailingTriggerR: 0` (trail from entry), giveback ~30–40 (tight factor) or
   45–55 (loose/chandelier) — because a trailing stop is a position-management mechanism, not a
-  column. `ST_DIR` is a persisting state and not a flip event — see `## Conditions` in the
-  skill body — so the FLIP needs an event column beside it. Name that as a substitution.
+  column. `ST_DIR` is a persisting state, so its FLIP is read with `enters`, natively:
+  `ST_DIR enters "bullish"` is TRUE on the one completed bar the direction turned, and
+  `ST_DIR exits "bullish"` on the bar it turned back — see `## Conditions` in the skill body.
 - **MACD + 200 MA filter** → `ABOVE_200` building block (`dist_SMA200 gt 0`) referenced by a
   carrier with `MACD_cross is "Bullish"`; rules `macd_bull/bear_cross` 3 required +
   `ma_sma200_above/below` 2 required; swing-trend geometry.
@@ -68,16 +70,27 @@ rules about the columns themselves, not about porting — they live in the skill
   and take `{rel: 'anchor'}` — see `## Header grammar` in the skill body.
 - **ICT / SMC (FVG + order blocks)** → `STRUCT_ZONES` is the native zone engine:
   `zones_htf_support_type` (`bullish FVG`/`bullish order block`), `zones_htf_support_dist
-  between -1.5 0`, `_age_h gte 12`, HTF bias required via `MAalign_htf`; rules
+  between 0 1.5`, `_age_h gte 12`, HTF bias required via `MAalign_htf`; rules
   `structure_fvg_approach`/`structure_ob_approach` required (their `proximityPct` is the
   in-zone dial). Liquidity sweeps, displacement, killzones and event *sequencing* are shapes the
-  grammar does not have — a clause compares one column against a literal, so an ordered sequence
-  of events cannot be stated at all. That is a grammar limit, not a missing metric; name it as
+  grammar does not have — a clause compares one column with a literal or with its own previous
+  completed bar, never with another column or an earlier event, so an ordered sequence of events
+  cannot be stated at all. That is a grammar limit, not a missing metric; name it as
   one.
+- **Pivot highs / lows, HH-HL structure and break of structure** (`ta.pivothigh(2, 2)` /
+  `ta.pivotlow(2, 2)`) → `SWING_FRACTAL_HIGH` / `SWING_FRACTAL_LOW` are the native swing levels and
+  `SWING_FRACTAL_LABEL` the structure label (`HH`/`HL`/`LH`/`LL`/`none`) — see `## Swing structure` in
+  the skill body. Pine's tie rule holds (an equal extreme on the left is allowed, on the right it is
+  not), and each level is the stepped, non-repainting series — held from the bar that completes the
+  pivot's right side, not plotted back on the pivot bar. Break of structure is
+  `dist_fractalHi crossesAbove 0` / `dist_fractalLo crossesBelow 0`; "structure is bullish" is
+  `fractalLabel in ["HH","HL"]`. Only two bars each side is native: a `ta.pivothigh(5, 5)` or longer
+  script ports onto the two-bar swing, and the spec-lock question says so.
 - **Now native, formerly substituted** — WaveTrend (`WT1`/`WT2`), QQE (`QQE_RSI_MA`/`QQE_STOP`),
   Hull (`HMA20`), Ichimoku (`ICHI_CONV`/`ICHI_BASE`/`ICHI_SPAN_A`/`ICHI_SPAN_B`/`ICHI_LAG`),
   Parabolic SAR (`PSAR`), Keltner (`KC_UPPER`/`KC_MID`/`KC_LOWER`), daily pivots
   (`PIVOT_P`/`PIVOT_R1`–`R3`/`PIVOT_S1`–`S3`), Williams %R (`WILLR14`), Stochastic RSI
   (`STOCH_RSI14`), the TTM squeeze (`KC_SQUEEZE`), Connors RSI-2 (`RSI2`), the 9/21/50 EMAs
-  (`EMA9`/`EMA21`/`EMA50`), and literal previous-session levels (`PDH`/`PDL`/`PDO`). Port these directly —
+  (`EMA9`/`EMA21`/`EMA50`), literal previous-session levels (`PDH`/`PDL`/`PDO`), and fractal swing
+  structure (`SWING_FRACTAL_HIGH`/`SWING_FRACTAL_LOW`/`SWING_FRACTAL_LABEL`). Port these directly —
   do not offer a substitute for a primitive the catalog serves.

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

@@ -38,10 +38,10 @@ Not "what were its returns" — whether it did *the thing it was told to do*.
   `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.
+- The record around the trades: `list_my_market_grid_entries` (the player's Market Grid entries —
+  `agentId` for one agent's, none for every entry), `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.