obsolete docs cleanup

.gitignore

@@ -30,3 +30,5 @@ data/
 
 # Codex
 .codex
+
+obsolete

Grid_Bot_Architecture.md

@@ -1,123 +0,0 @@
-# Grid Bot Architecture
-
-This note describes the intended grid-bot design.
-
-## Core idea
-
-A survivable grid bot has three layers:
-
-1. **Micro layer** , places trades and captures oscillation.
-2. **Meso layer** , adapts the grid structure.
-3. **Macro layer** , protects capital in bad regimes.
-
-If one layer is missing:
-- micro only, the bot can blow up
-- macro only, it barely trades
-- meso only, the behavior is unstable
-
-## Operational model
-
-The bot should not be static. It should:
-- scale spacing with volatility
-- slide with the market
-- recenter only occasionally
-- stop or reduce activity in strong trends
-
-## Pseudocode outline
-
-```text
-INIT:
-  center_price = current_price()
-  grid_levels = 12
-  recenter_threshold = 0.05
-  max_inventory_pct = 0.7
-  trend_filter_enabled = true
-
-  build_grid(center_price)
-
-LOOP:
-  price = current_price()
-  volatility = ATR(lookback=50)
-
-  grid_step = clamp(k * volatility, min=0.008, max=0.025)
-
-  handle fills
-  slide grid when price leaves the active band
-  recenter only when deviation is large
-  pause new orders in strong trends
-```
-
-## Key mechanisms
-
-### 1. Sliding grid
-
-This is the default adjustment mode.
-
-Effect:
-- keeps the bot active
-- avoids full reset shock
-- behaves more like a market maker
-
-Use this as the main structural adjustment.
-
-### 2. Re-centering
-
-Use only when price drifts too far.
-
-Rule of thumb:
-- keep it rare
-- use only for larger deviations, e.g. 5 to 8 percent
-
-Too much recentering kills the edge.
-
-### 3. Volatility-based spacing
-
-Fixed spacing is fragile.
-
-Better:
-- high volatility, wider grid
-- low volatility, tighter grid
-
-This reduces overtrading and avoids getting wrecked in spikes.
-
-### 4. Trend filter
-
-This is the survival layer.
-
-A simple version can use:
-- price vs MA200
-- slope of MA50
-
-When a strong trend is detected:
-- pause new orders
-- optionally allow only one-sided behavior
-
-## Tunable parameters
-
-Suggested starting range:
-- grid spacing: ~1 to 1.5 percent for XRP
-- grid width: ~±10 to 20 percent
-- recenter threshold: 4 to 8 percent
-- inventory cap: never above ~70 percent of capital
-- volatility multiplier `k`: ~0.8 to 1.5
-
-## Failure modes
-
-Common ways grid bots die:
-- always-on grid with no trend filter
-- over-adjustment and too many recentering events
-- ignoring inventory drift
-- spacing too tight, so fees eat the edge
-- static behavior while market regime changes
-
-## Mental model
-
-Think of the layers like this:
-- **Grid** , engine
-- **Sliding** , steering
-- **Volatility scaling** , suspension
-- **Trend filter** , brakes
-
-## Summary
-
-A good grid bot sells local volatility, respects regime shifts, and stays bounded in inventory. The goal is not constant activity, it is controlled adaptation.

Hermes_Compatibility_Plan.md

@@ -1,245 +0,0 @@
-# Trader-MCP Hermes Compatibility Plan
-
-This file turns `TODO.md` into a stepwise upgrade path toward `hermes-mcp` compatibility.
-
-## Goal
-
-Prepare `trader-mcp` so Hermes can supervise strategy selection, risk posture, and switching without collapsing Trader into a monolith.
-
-Trader should remain:
-- strategy runtime
-- execution feedback surface
-- operator dashboard
-- persistence owner for strategy state
-
-Hermes should remain:
-- selector
-- supervisor
-- regime interpreter
-- switch/risk controller
-
-## Core design principles
-
-1. Small interfaces.
-2. Explicit ownership.
-3. Human-readable strategy names.
-4. Structured state over vibes.
-5. Stable switch semantics.
-6. Contract-first development.
-7. Tests before expansion.
-
-## Canonical strategy set
-
-The current Hermes-compatible primary set is:
-
-- `grid_trader`
-- `trend_follower`
-- `exposure_protector`
-
-### Strategy ordering priority
-
-1. `grid_trader`
-2. `trend_follower`
-3. `exposure_protector`
-
-This is not a quality ranking. It is a sequencing plan for implementation and testing.
-
-## Ownership boundaries
-
-### Strategy owns
-- its local logic
-- its local state
-- its local config
-- its own render output
-- its own explanation string
-
-### Trader runtime owns
-- lifecycle
-- persistence
-- snapshots
-- reconciliation
-- dashboard presentation
-- execution plumbing
-
-### Human observer owns
-- inspection
-- approval where configured
-- operational overrides where explicitly allowed
-- debugging and review
-
-### Hermes owns
-- strategy enable/disable/switch decisions
-- risk-mode changes
-- uncertainty and confidence weighting
-- regime interpretation
-- execution-degradation-driven downranking
-
-## Upgrade phases
-
-### Phase 0, document the contract
-Deliverables:
-- `Hermes_Trader_Contract_v0.1.md`
-- agreed strategy taxonomy
-- agreed state and decision fields
-- agreed control verbs
-
-Acceptance criteria:
-- every strategy has `expects`, `avoids`, and `risk_profile`
-- Hermes request and Trader response shapes are machine readable
-- no contract depends on hidden state
-
-### Phase 1, normalize the strategy registry
-Deliverables:
-- fold redundant names into the canonical set
-- mark parameter variants as modes
-- ensure strategy labels are stable and human-readable
-
-Acceptance criteria:
-- each strategy name maps to one conceptual regime
-- no micro-strategy sprawl
-- old names can be redirected or deprecated cleanly
-
-### Phase 2, harden the Hermes read path
-Deliverables:
-- `list_strategies`
-- `get_strategy`
-- stable `report()` shape
-
-Acceptance criteria:
-- Hermes can inspect state without knowing internals
-- dashboard and API show the same truth
-- every response is structured and auditable
-- extra read tools are not added unless the canonical read path proves insufficient
-
-### Phase 3, add the Hermes action layer
-Deliverables:
-- `apply_control_decision`
-- internal `switch_strategy`
-- audit persistence for applied and rejected actions
-
-Acceptance criteria:
-- Hermes controls Trader through one canonical write entry point
-- invalid or unsafe requests are rejected cleanly
-- every transition records a reason and decision id
-- `keep` remains Hermes-local and is not sent as a Trader write action
-
-### Phase 4, implement switching safety
-Deliverables:
-- confidence threshold
-- minimum hold time
-- hysteresis
-- explicit emergency override path
-- degraded execution fallback
-
-Acceptance criteria:
-- strategies do not flap on minor noise
-- switching reasons are deterministic and testable
-- `defensive` and `idle` are valid safe exits
-
-### Phase 5, implement initial strategies
-Deliverables:
-- `grid_trader`
-- `trend_follower`
-- `exposure_protector`
-
-Acceptance criteria:
-- each one has metadata and tests
-- each one returns clear state/explanation data
-- each one can be selected by Hermes-compatible contract shapes
-
-### Phase 6, add structure strategies
-Deliverables:
-- tighten switching semantics around real inventory pressure
-- separate descriptive trader facts from Hermes decisions
-
-Acceptance criteria:
-- grid is clearly structure-based, not signal-based
-- grid reports factual capacity and inventory shape, not switch advice
-- tests cover the distinction
-
-### Phase 7, add event-aware behavior
-Deliverables:
-- `event_driven`
-- event-risk metadata
-- event-pressure aware selection logic
-
-Acceptance criteria:
-- Hermes can downrank normal strategies during event risk
-- event handling remains temporary and explicit
-
-### Phase 8, feed back execution quality
-Deliverables:
-- fills
-- slippage
-- latency
-- rejections
-- stress
-- degraded connectivity
-
-Acceptance criteria:
-- execution quality affects strategy selection
-- Trader surfaces the feedback clearly
-- Hermes can see why a strategy was penalized
-
-### Phase 9, tighten dashboards and audit trails
-Deliverables:
-- current strategy view
-- why-active view
-- recent changes timeline
-- Hermes decision trace
-- execution state panel
-
-Acceptance criteria:
-- a human can understand the system without reading code
-- transitions are explainable from the UI
-
-## Tests to add
-
-### Contract tests
-- strategy metadata validation
-- Hermes request schema validation
-- Trader response schema validation
-- control verb validation
-
-### Runtime tests
-- load/unload/switch transitions
-- state snapshot and restore
-- minimum hold enforcement
-- hysteresis enforcement
-- defensive fallback on degraded execution
-
-### Strategy tests
-- expected regime matching
-- avoided regime rejection
-- deterministic state transitions
-- readable explanation output
-
-### Integration tests
-- Hermes decision to Trader control path
-- Trader response parsing
-- execution feedback influencing future selection
-
-## Suggested first implementation order
-
-1. lock the contract paper
-2. canonicalize the strategy registry
-3. add metadata to current strategies
-4. add validation tests
-5. implement the inspection tools
-6. implement the control tools
-7. add switching safety
-8. tighten supervision semantics on current strategies
-9. wire execution feedback into selection
-10. polish dashboard and traceability
-
-## Notes on ownership and scope
-
-Trader should not become a second Hermes.
-
-If a feature answers "what should the world do?", it belongs to Hermes.
-If a feature answers "how do we run the chosen strategy safely?", it belongs to Trader.
-If a feature answers "what happened and why?", it belongs to both through a shared contract.
-
-## Output philosophy
-
-The end state should make Trader useful to Hermes, useful to humans, and still simple enough to debug.

Hermes_Trader_Action_Contract_v0.1.md

@@ -1,248 +0,0 @@
-# Hermes → Trader Action Contract (v0.1)
-
-This document defines the narrow write contract from `hermes-mcp` to `trader-mcp`.
-
-## Goal
-
-Keep Hermes in charge of decisions and keep Trader in charge of safe application.
-
-Hermes should send one explicit control decision.
-Trader should validate it, apply it if safe, and return a structured result.
-
-## Design rules
-
-1. One Hermes write entry point.
-2. Small explicit schema.
-3. No duplicate control surfaces.
-4. Safe rejection is a normal outcome.
-5. Every applied or rejected action is auditable.
-6. `keep` is not a Trader write action. Hermes may record `keep` on its own side.
-
-## Canonical Hermes write tool
-
-Trader exposes one canonical Hermes write tool:
-
-- `apply_control_decision(payload)`
-
-Hermes should not need to combine multiple Trader tools to express one decision.
-
-## Non-canonical helpers
-
-These may still exist internally or for operator use, but they are not the Hermes contract:
-
-- `control_strategy(...)`
-- `set_strategy_policy(...)`
-- `switch_strategy(...)`
-- `pause_strategy(...)`
-- `resume_strategy(...)`
-- `reconcile_instance(...)`
-
-They are runtime helpers, not the cross-system write boundary.
-
-## Supported actions
-
-The Hermes write contract supports only these actions:
-
-- `switch`
-- `pause`
-- `resume`
-- `set_risk_mode`
-
-Not supported here:
-
-- `keep`
-- free-form policy mutation
-- multi-step orchestration batches
-- broad config editing
-
-## Request shape
-
-```json
-{
-  "decision_id": "dec_2026_04_16_001",
-  "concern_id": "qndd8o9ppop6:xrpusd",
-  "account_id": "qndd8o9ppop6",
-  "market_symbol": "xrpusd",
-  "action": "switch",
-  "target_strategy_id": "0c555fee-e4c8-4543-ae70-c132517017e1",
-  "expected_active_strategy_id": "9cf29124-65a7-4950-ac18-65f938e0239b",
-  "risk_mode": "normal",
-  "reason": "trend strategy still fits the directional narrative",
-  "confidence": 0.83,
-  "dry_run": false,
-  "override": false,
-  "requested_at": "2026-04-16T20:15:00Z"
-}
-```
-
-## Required fields
-
-- `decision_id`
-- `concern_id`
-- `account_id`
-- `market_symbol`
-- `action`
-- `reason`
-- `confidence`
-
-## Conditionally required fields
-
-### For `switch`
-- `target_strategy_id`
-
-### For `set_risk_mode`
-- `risk_mode`
-
-### For guarded transitions
-- `expected_active_strategy_id` is strongly recommended
-
-## Field meanings
-
-### `decision_id`
-Stable id from Hermes. Trader stores it and uses it for audit linkage and idempotency checks.
-
-### `concern_id`
-The account-market concern Hermes is acting on.
-
-### `expected_active_strategy_id`
-What Hermes believes is active right now.
-If provided and Trader sees something else, Trader should reject unless `override=true`.
-
-### `reason`
-Human-readable explanation.
-Short, concrete, stable enough for audit logs.
-
-### `confidence`
-Normalized float in `[0, 1]`.
-Trader does not have to trust it blindly, but may use it in guardrails.
-
-### `dry_run`
-Validate and simulate only.
-No state-changing action should occur.
-
-### `override`
-Explicit emergency bypass for guarded rejection paths.
-Use sparingly and always record it.
-
-## Response shape
-
-```json
-{
-  "ok": true,
-  "status": "applied",
-  "decision_id": "dec_2026_04_16_001",
-  "concern_id": "qndd8o9ppop6:xrpusd",
-  "action": "switch",
-  "from_strategy_id": "9cf29124-65a7-4950-ac18-65f938e0239b",
-  "to_strategy_id": "0c555fee-e4c8-4543-ae70-c132517017e1",
-  "risk_mode": "normal",
-  "dry_run": false,
-  "validation": {
-    "concern_match": true,
-    "account_match": true,
-    "market_match": true,
-    "expected_active_match": true,
-    "target_exists": true,
-    "target_runnable": true
-  },
-  "warnings": [],
-  "errors": [],
-  "result": {
-    "mode_change": "applied",
-    "reconciled": true
-  },
-  "applied_at": "2026-04-16T20:15:01Z"
-}
-```
-
-## Status values
-
-- `applied`
-- `rejected`
-- `noop`
-- `failed`
-
-### `applied`
-Validation passed and Trader changed state.
-
-### `rejected`
-Trader refused the request due to validation or safety rules.
-This is a valid control outcome.
-
-### `noop`
-The requested state already exists.
-Example: Hermes asks to resume a strategy that is already active.
-
-### `failed`
-Trader attempted the action but could not complete it due to runtime or persistence failure.
-
-## Validation rules
-
-Trader should validate at least the following:
-
-1. `account_id` matches the target strategy or concern.
-2. `market_symbol` matches the target strategy or concern.
-3. `target_strategy_id` exists for `switch`.
-4. the target strategy belongs to the same account-market pair.
-5. if `expected_active_strategy_id` is provided, it matches reality unless `override=true`.
-6. the action is currently safe under runtime guardrails.
-7. `confidence` is a valid numeric value in range.
-
-## Initial safety gates
-
-Version `0.1` implements a small set of safety gates:
-
-- expected active strategy check
-- target existence check
-- account-market match check
-- degraded execution rejection unless `override=true`
-- idempotent duplicate decision rejection or noop handling
-
-Current implementation also records each attempt in Trader audit storage and reconciles the affected strategy runtime after an applied state change.
-
-## Idempotency
-
-Trader should treat `decision_id` as an idempotency key.
-Repeated submissions of the same already-applied decision should not reapply the state transition.
-
-## Audit persistence
-
-Trader should persist every Hermes action attempt, including:
-
-- request payload
-- validation result
-- final status
-- result payload
-- timestamps
-
-A rejected action is still important and should be stored.
-
-## Read/write separation
-
-Hermes read path should stay separate from Hermes write path.
-
-### Read
-- `list_strategies()`
-- `get_strategy()`
-
-### Write
-- `apply_control_decision(payload)`
-
-Avoid proliferating extra Hermes-facing tools unless a real gap appears.
-
-## Suggested implementation mapping inside Trader
-
-`apply_control_decision(payload)` may internally call existing runtime helpers:
-
-- `control_strategy(...)`
-- `set_strategy_policy(...)`
-- `reconcile_instance(...)`
-- a new internal `switch_strategy(...)`
-
-But Hermes should only see one write entry point.
-
-## Versioning rule
-
-Keep this contract small.
-Future versions should extend it only when a real decision or execution need appears.
-If a new field does not improve safety, auditability, or decision fidelity, it probably does not belong here.

Hermes_Trader_Contract_v0.1.md

@@ -1,244 +0,0 @@
-# Hermes ⇄ Trader Strategy Contract (v0.1)
-
-This document defines what Hermes needs from Trader-managed strategies in order to make selection decisions.
-
-## Scope
-
-- Trader runs the strategies.
-- Hermes selects which configured strategy is active for each account and market.
-- A strategy is bound to a specific account and market.
-- Hermes queries strategies to see the available options for that account-market pair.
-- Trader may turn strategies on or off when instructed by Hermes.
-- Trader does not decide the global strategy choice on its own.
-
-## What a strategy represents
-
-A strategy is an account-market specific operating mode.
-It is not a generic idea detached from venue, balance, or market context.
-
-## Required strategy bindings
-
-Each configured strategy must be tied to:
-- `strategy_id`
-- `account_id`
-- `market`
-- `base_currency`
-- `quote_currency`
-- `enabled_state`
-
-Hermes should be able to ask, for a given account and market, which strategies exist and whether they are currently enabled.
-
-## What Hermes needs from a strategy
-
-When Hermes queries a strategy, it must receive the information below.
-
-### Identity and binding
-- `strategy_id`
-- `strategy_name`
-- `account_id`
-- `market`
-- `base_currency`
-- `quote_currency`
-- `enabled_state`
-- `mode`
-
-### Balance and exposure
-- `account_balance`
-- `available_balance`
-- `base_position`
-- `quote_position`
-- `open_orders`
-- `reserved_balance`
-- `exposure`
-- `free_margin` where relevant
-
-### Market suitability
-- `expected_market_regime`
-- `avoided_market_regime`
-- `risk_profile`
-- `liquidity_expectation`
-- `event_risk_expectation`
-- `volatility_expectation`
-
-### Live operating state
-- `status`
-- `recent_changes`
-- `decision_history`
-- `current_intent`
-- `last_transition`
-- `last_update`
-- `uncertainty`
-- `confidence`
-
-### Execution feedback
-- `fills`
-- `slippage`
-- `latency`
-- `rejections`
-- `execution_quality`
-- `stress`
-- `venue_health`
-
-### Strategy explanation
-- `current_reason`
-- `key_drivers`
-- `warnings`
-- `constraints`
-
-## Hermes decision inputs
-
-Hermes should decide using the returned strategy snapshot plus external market information.
-The minimum decision inputs are:
-- market regime
-- liquidity state
-- event risk
-- sentiment pressure
-- current strategy state
-- balance and exposure state
-- execution quality
-- confidence and uncertainty
-- recent changes
-
-## Strategy response shape
-
-A strategy query should return a compact structured snapshot with nested sections. Only information that changes Hermes decisions should be included.
-
-Example:
-
-```json
-{
-  "identity": {
-    "strategy_id": "btc-vienna-trend-1",
-    "strategy_name": "trend_following",
-    "account_id": "acc-01",
-    "market": "BTC/USD",
-    "base_currency": "BTC",
-    "quote_currency": "USD"
-  },
-  "control": {
-    "enabled_state": "on",
-    "mode": "active"
-  },
-  "fit": {
-    "expected_market_regime": "trend",
-    "avoided_market_regime": "range",
-    "risk_profile": "medium",
-    "liquidity_expectation": "normal",
-    "event_risk_expectation": "low",
-    "volatility_expectation": "moderate"
-  },
-  "position": {
-    "account_balance": {
-      "base": 0.42,
-      "quote": 18500.0
-    },
-    "available_balance": {
-      "base": 0.12,
-      "quote": 9400.0
-    },
-    "base_position": 0.30,
-    "quote_position": 0.0,
-    "reserved_balance": 1200.0,
-    "open_orders": 2,
-    "exposure": "long",
-    "free_margin": 8200.0
-  },
-  "state": {
-    "status": "running",
-    "recent_changes": ["scaled in", "trimmed exposure"],
-    "decision_history": ["held", "added", "held"],
-    "current_intent": "follow upward structure",
-    "last_transition": "2026-04-15T18:10:00Z",
-    "last_update": "2026-04-15T18:25:00Z"
-  },
-  "assessment": {
-    "confidence": 0.78,
-    "uncertainty": "low",
-    "current_reason": "trend intact, balance sufficient, execution stable",
-    "key_drivers": ["trend", "balance", "liquidity"],
-    "warnings": ["minimum_hold_minutes=15"]
-  },
-  "execution": {
-    "fills": 12,
-    "slippage": 0.0012,
-    "latency": "normal",
-    "rejections": 0,
-    "execution_quality": "good",
-    "stress": "low",
-    "venue_health": "good"
-  }
-}
-```
-
-## Strategy modes
-
-A strategy may expose modes, but modes are not separate strategies.
-Examples:
-- slow trend
-- strong trend
-- cautious mean reversion
-- high-volatility breakout
-
-## Enabled and disabled state
-
-Hermes must be able to see whether a strategy is:
-- `on`
-- `off`
-- `paused`
-- `error`
-- `observe`
-- `active`
-
-Trader may manage those states internally, but Hermes needs a clear readback of them.
-
-## Control responsibility
-
-Hermes may instruct Trader to:
-- switch a strategy on
-- switch a strategy off
-- keep a strategy on
-- keep a strategy off
-- shift risk mode
-- pause a strategy
-- resume a strategy
-
-Trader should not invent a strategy decision that conflicts with Hermes without an explicit safety reason.
-
-## Selection rules
-
-Hermes selects strategies per account-market combination using:
-- regime fit
-- balance and exposure fit
-- execution quality
-- current confidence
-- current uncertainty
-- recent state changes
-- event pressure
-- liquidity quality
-
-## Strategy taxonomy
-
-Keep the strategy set small and orthogonal:
-- `idle`
-- `defensive`
-- `trend_following`
-- `mean_reversion`
-- `grid`
-- `breakout`
-- `event_driven`
-
-## First implementation order
-
-1. Make the query result shape exact.
-2. Make balance and exposure mandatory in strategy snapshots.
-3. Make strategy bindings explicit per account and market.
-4. Keep Hermes control limited to on/off and risk posture.
-5. Implement `idle` and `defensive` first.
-6. Implement `trend_following` and `mean_reversion` next.
-7. Add `grid`, `breakout`, and `event_driven` after the core set is stable.
-8. Add tests for balance reporting, selection inputs, and enable/disable control.
-
-## Versioning
-
-This is v0.1.
-Future changes should stay focused on the information Hermes needs to make better decisions, not on exposing implementation detail.

MCP_SURFACE_PROPOSAL.md

@@ -1,37 +0,0 @@
-# Trader MCP Surface Proposal
-
-Keep the public MCP surface small and standardized.
-
-## Current tools
-
-### 1. `list_strategies()`
-Returns a compact inventory of strategies.
-
-### 2. `get_strategy(id)`
-Returns compact identity/control data plus `report` by default.
-Optional flags:
-- `include_config`
-- `include_state`
-- `include_render`
-- `include_debug`
-- `include_report` (defaults to true)
-
-### 3. `update_strategy(id, config?, state?)`
-Writes config/state changes for an existing strategy, then reconciles it.
-
-### 4. `control_strategy(id, action)`
-Single control entry point for `start`, `pause`, `resume`, `stop`, and `reconcile`.
-
-### 5. `set_strategy_policy(id, policy)`
-Stores Hermes policy metadata on the strategy.
-
-### 6. `get_capabilities()`
-Describes the current surface and the strategy record shape.
-
-## Design notes
-
-- `report().fit` is the Hermes-facing fit block.
-- `set_strategy_policy()` stores high-level intent, not trading mechanics.
-- policy is reapplied on reconcile and instance creation.
-- `get_strategy()` should stay compact unless expanded explicitly.
-- keep the surface small and predictable.

Strategy_Contract.md

@@ -1,111 +0,0 @@
-# Strategy Contract
-
-This is the canonical contract for `trader-mcp` strategies.
-
-## Purpose
-
-A strategy defines behavior. It does not own persistence, lifecycle, or UI rendering.
-It must also expose a Hermes-facing `report()` snapshot with only decision-relevant data.
-
-## Strategy class
-
-```python
-class Strategy:
-    LABEL = "Human readable name"
-    CONFIG_SCHEMA = {}
-    STATE_SCHEMA = {}
-    TICK_MINUTES = 1.0
-
-    def __init__(self, context, config):
-        self.context = context
-        self.config = config
-        self.state = self.init()
-```
-
-## Responsibilities
-
-### Strategy
-- decides what to do
-- reads config
-- mutates `self.state`
-- returns structured render data
-
-### Not strategy responsibilities
-- persistence
-- lifecycle control
-- config storage
-- identity ownership
-- direct access to engine internals
-
-## Configuration
-
-- `CONFIG_SCHEMA` is declarative metadata
-- config is supplied by the engine
-- config changes are handled by reload or reconcile
-- config should stay read-only from the strategy perspective, except for derived policy application inside the strategy
-
-## State
-
-- `self.state` belongs to the instance
-- `STATE_SCHEMA` declares what state is durable / persisted
-- keep state serializable where practical
-- do not depend on hidden global state
-- the engine snapshots and restores state, not the strategy
-- the engine may reapply stored policy on reconcile
-
-## Lifecycle
-
-```text
-init() -> state created
-on_tick() -> state updated
-reload -> state restored from engine snapshot if available
-```
-
-## Context
-
-The context is capability-only.
-
-Allowed:
-- account data access
-- balances and open orders
-- price and market-data access
-- order placement
-- logging
-- engine-mediated actions
-- binding `account_id` and `client_id` into exec calls
-
-Not allowed:
-- persistence
-- config storage
-- lifecycle decisions
-- strategy identity ownership
-- market-regime ownership
-
-Market regime is a data-layer artifact provided by `crypto-mcp`, not a Trader-owned query result.
-
-## UI output
-
-Strategies return structured widgets, not HTML.
-
-```python
-{
-  "widgets": [
-    {"type": "metric", "label": "PnL", "value": 123.45},
-    {"type": "line_chart", "data": [...]}
-  ]
-}
-```
-
-## Example
-
-```python
-from src.trader_mcp.strategy_sdk import Strategy
-
-class Strategy(Strategy):
-    LABEL = "Hello World"
-    CONFIG_SCHEMA = {"label": {"type": "string", "default": "hello world"}}
-    STATE_SCHEMA = {"counter": {"type": "int", "default": 0}}
-
-    def init(self):
-        return {"counter": 0}
-```

Strategy_Runtime.md

@@ -1,83 +0,0 @@
-# Strategy Runtime
-
-This is the canonical runtime / engine document for `trader-mcp`.
-
-## Overview
-
-The system is split into:
-- strategy definition
-- persisted instance record
-- runtime execution
-- dashboard rendering
-
-## Instance identity
-
-Immutable identity fields:
-- `id`
-- `strategy_type`
-- `account_id`
-- `market_symbol`
-- `base_currency`
-- `counter_currency`
-
-These should stay stable and audit-friendly.
-
-## Mutable fields
-
-- `mode` (`off`, `observe`, `active`)
-- `config`
-- runtime state snapshots
-- stored Hermes policy metadata
-
-## State persistence
-
-- the engine owns snapshotting and restore
-- strategies only define state shape (`STATE_SCHEMA`)
-- persisted state is stored separately from config
-- state should be saved at lifecycle boundaries:
-  - tick
-  - pause
-  - unload
-  - reload/config change
-  - clean shutdown
-
-## Mode semantics
-
-- `off`: not instantiated
-- `observe`: instantiated, ticks enabled, trading disabled
-- `active`: instantiated, ticks enabled, trading enabled
-- `paused`: runtime freeze, not persisted as a mode
-
-## Reconciliation
-
-The engine reconciles DB records to runtime:
-
-```python
-if record.mode != "off" and record.id not in running:
-    load_instance(record)
-
-if record.mode == "off" and record.id in running:
-    unload_instance(record.id)
-```
-
-## Reload semantics
-
-Default behavior:
-- unload old runtime
-- restore state snapshot when available
-- load new runtime
-- reapply stored policy after instance creation
-
-Selective state carryover is acceptable only through engine-managed persistence.
-
-## Dashboard responsibilities
-
-The dashboard shows:
-- identity
-- config
-- mode
-- runtime status
-- rendered widgets
-- policy metadata when present
-
-It does not own trading logic.

Strategy_concepts_0.md

@@ -1,7 +0,0 @@
-# Deprecated
-
-This document has been superseded by:
-- `Strategy_Contract.md`
-- `Strategy_Runtime.md`
-
-Keep these newer files as the canonical source.

Strategy_concepts_1.md

@@ -1,7 +0,0 @@
-# Deprecated
-
-This document has been superseded by:
-- `Strategy_Contract.md`
-- `Strategy_Runtime.md`
-
-Keep these newer files as the canonical source.

Strategy_concepts_2.md

@@ -1,114 +0,0 @@
-# Strategy Configuration Ownership and Reload Semantics
-
-## 1. Responsibility Split
-
-Keep ownership clear:
-
-- database, stores config and identity
-- engine, loads config and creates strategy instances
-- strategy, reads config and maintains state
-- context, exposes capabilities only and binds instance identity (`account_id`, `client_id`) to execution calls
-
-## 2. Context Should Not Own Config
-
-The context is the strategy’s access boundary to the outside world.
-It should not become a secondary persistence layer.
-
-If context loads config, it becomes harder to reason about, more coupled to storage, and less reusable.
-
-**Context = capabilities only.**
-
-## 3. Config Flow
-
-### Step 1, persisted record
-
-```python
-record = {
-    "id": "...",
-    "strategy_type": "mean_rev",
-    "config": {
-        "risk": 0.01,
-        "window": 20
-    },
-    "mode": "observe"
-}
-```
-
-### Step 2, engine loads the record
-
-```python
-def load_instance(record):
-    module = load_strategy(record["strategy_type"])
-    context = StrategyContext(engine, record["id"], mode=record["mode"])
-
-    instance = module.StrategyClass(
-        context=context,
-        config=record["config"]
-    )
-
-    running_instances[record["id"]] = instance
-```
-
-### Step 3, strategy reads the config
-
-```python
-risk = self.config["risk"]
-```
-
-That read should be conceptually read-only from the strategy’s point of view.
-
-## 4. Reload Semantics
-
-Config changes should normally mean a clean reload.
-
-```text
-unload_instance(id)
-load_instance(updated_record)
-```
-
-Benefits:
-
-- deterministic
-- easy to debug
-- no partially updated live object
-
-Tradeoff:
-
-- runtime state resets
-
-That tradeoff is acceptable and probably desirable for the first version.
-
-## 5. Config vs State
-
-Config is:
-
-- persistent
-- external
-- owned by the system
-
-State is:
-
-- ephemeral
-- internal
-- owned by the strategy instance
-
-Keep them separate.
-
-## 6. Mode and Reload Safety
-
-If a strategy is active, a config change should move it to a safe mode before reload, then optionally reactivate it afterward.
-That avoids accidental trading during transition.
-
-## 7. Recommended Mental Model
-
-```text
-Engine constructs the world
-Strategy lives inside it
-Context is the interface to reality
-Config is part of the world, not the interface
-```
-
-## 8. Strong Default Recommendation
-
-Use JSON config blobs in SQLite and reload on config change.
-That fits the current app shape well.

Strategy_concepts_examples.md

@@ -1,117 +0,0 @@
-# Strategy Concepts Examples
-
-## 1. Minimal strategy example
-
-```python
-from strategy_sdk import Strategy
-
-class MyStrategy(Strategy):
-    LABEL = "My Strategy"
-    TICK_MINUTES = 1.0
-    CONFIG_SCHEMA = {
-        "risk": {"type": "float", "default": 0.01},
-        "window": {"type": "int", "default": 20}
-    }
-    STATE_SCHEMA = {
-        "prices": {"type": "list", "default": []},
-        "position": {"type": "int", "default": 0}
-    }
-
-    def init(self):
-        return {
-            "prices": [],
-            "position": 0
-        }
-
-    def on_tick(self, tick):
-        self.state["prices"].append(tick["price"])
-
-    def render(self):
-        return {
-            "widgets": [
-                {"type": "line_chart", "data": self.state["prices"]}
-            ]
-        }
-```
-
-## 2. Base class contract
-
-```python
-class Strategy:
-    LABEL = "Strategy"
-    CONFIG_SCHEMA = {}
-    STATE_SCHEMA = {}
-
-    def __init__(self, context, config):
-        self.context = context
-        self.config = config
-        self.state = self.init()
-
-    def init(self):
-        return {}
-
-    def on_tick(self, tick):
-        pass
-
-    def render(self):
-        return {"widgets": []}
-```
-
-## 3. Config schema example
-
-```python
-CONFIG_SCHEMA = {
-    "risk": {
-        "type": "float",
-        "default": 0.01,
-        "min": 0.0,
-        "max": 1.0
-    },
-    "window": {
-        "type": "int",
-        "default": 20
-    }
-}
-```
-
-## 4. Context sketch
-
-```python
-class StrategyContext:
-    def get_price(self, symbol):
-        raise NotImplementedError
-
-    def place_order(self, side, amount):
-        raise NotImplementedError
-
-    def get_orders(self):
-        raise NotImplementedError
-
-    def cancel_all_orders(self):
-        raise NotImplementedError
-
-    def log(self, message):
-        raise NotImplementedError
-```
-
-## 5. Lifecycle
-
-```text
-Instantiate -> init() -> on_tick() -> render()
-```
-
-The engine owns persistence and restores `state` around reload / unload / pause boundaries.
-
-## 6. File structure
-
-```text
-strategy_sdk/
-  __init__.py
-  base.py
-  context.py
-  config.py (optional)
-  ui.py (optional)
-
-strategies/
-  my_strategy.py
-```

TODO.md

@@ -1,275 +0,0 @@
-# Trader-MCP Hermes Compatibility TODO
-
-This file is the structured upgrade plan for preparing `trader-mcp` for `hermes-mcp` supervision.
-
-See also:
-- `Hermes_Trader_Contract_v0.1.md`
-- `Hermes_Compatibility_Plan.md`
-- `Strategy_Runtime.md`
-- `Strategy_Contract.md`
-- `../hermes-mcp/hermes.md`
-- `../hermes-mcp/hermes_and_strategies.md`
-
-## Guiding rule
-
-Trader-MCP concerns strategy behavior and the surfaces strategies must expose.
-Hermes decides the market story and the active control stance.
-
-## 1. Contract first
-- Freeze the Hermes ⇄ Trader read contract before adding new strategy behavior.
-- Freeze the Hermes → Trader action contract before adding new control paths.
-- Keep every request and response machine readable.
-- Require `decision_id`, `reason`, and `confidence` for Hermes control decisions.
-- Require Trader to return a structured applied-result record.
-- Keep one canonical Hermes write tool: `apply_control_decision`.
-- Do not send `keep` actions to Trader; Hermes records `keep` on its own side.
-
-## 2. Canonical strategy taxonomy
-Reduce the strategy set to a small, orthogonal registry.
-Treat parameter variants as modes inside a strategy, not separate strategies.
-
-Canonical set:
-- `idle`
-- `defensive`
-- `trend_following`
-- `mean_reversion`
-- `grid`
-- `breakout`
-- `event_driven`
-
-Rules:
-- Remove or fold redundant strategy names that differ only by tuning.
-- Keep names human-readable and stable.
-- Preserve a single conceptual strategy per regime.
-
-## 3. Strategy metadata
-Every strategy must declare:
-- `expects`
-- `avoids`
-- `risk_profile`
-- `capabilities`
-
-The natural habitat fields should cover:
-- trend
-- volatility
-- event risk
-- liquidity
-
-Example capability declaration:
-```json
-{
-  "name": "mean_reversion",
-  "capabilities": ["fade_extremes", "range_entry", "range_exit"],
-  "expects": {
-    "trend": "none",
-    "volatility": "low",
-    "event_risk": "low",
-    "liquidity": "normal"
-  },
-  "avoids": {
-    "trend": "strong",
-    "volatility": "expanding",
-    "event_risk": "high",
-    "liquidity": "thin"
-  },
-  "risk_profile": "medium"
-}
-```
-
-## 4. Strategy surface
-Expose clean strategy state.
-Each strategy should provide:
-- `status`
-- `recent_changes`
-- `decision_history`
-- `render_state`
-- `risk_state`
-- `execution_state`
-
-Preferred additions:
-- `confidence`
-- `uncertainty`
-- `last_transition`
-- `last_error`
-
-## 5. Trader surface for Hermes
-Refactor the MCP tools toward Hermes usefulness, but keep the surface narrow.
-
-Canonical read tools:
-- `list_strategies`
-- `get_strategy`
-
-Canonical write tool:
-- `apply_control_decision`
-
-Internal or operator helpers may still exist:
-- `switch_strategy`
-- `set_risk_mode`
-- `pause_strategy`
-- `resume_strategy`
-- `reconcile_state`
-
-Rules:
-- Hermes should not need multiple Trader tool calls to express one decision.
-- Avoid adding extra Hermes-facing read tools unless `get_strategy().report` proves insufficient.
-
-## 6. Switching policy
-Prevent flip-flopping.
-
-Add:
-- confidence threshold
-- minimum hold time
-- hysteresis
-- explicit emergency override path
-- degraded execution fallback
-
-## 7. Ownership boundaries
-
-### Strategy owns
-- local logic
-- local state
-- local config
-- own render output
-- own explanation string
-
-### Trader runtime owns
-- lifecycle
-- persistence
-- snapshots
-- reconciliation
-- dashboard presentation
-- execution plumbing
-
-### Human observer owns
-- inspection
-- approval where configured
-- operational overrides where explicitly allowed
-- debugging and review
-
-### Hermes owns
-- enable / disable / switch decisions
-- risk-mode changes
-- uncertainty and confidence weighting
-- regime interpretation
-- execution-degradation-driven downranking
-
-## 8. First strategies to implement
-Implement in this order:
-1. `idle`
-2. `defensive`
-3. `trend_following`
-4. `mean_reversion`
-5. `grid`
-6. `breakout`
-7. `event_driven`
-
-Notes:
-- `idle` and `defensive` are safety exits.
-- `trend_following` and `mean_reversion` are the first core alpha strategies.
-- `grid` is structure-based, not signal-based.
-- `breakout` is separate from trend-following.
-- `event_driven` should remain explicit and temporary in behavior.
-
-## 9. Stepwise upgrade path toward Hermes compatibility
-### Phase 0, document the contract
-- write `Hermes_Trader_Contract_v0.1.md`
-- agree the control verbs
-- agree the request/response schemas
-
-### Phase 1, normalize the registry
-- fold redundant strategy names
-- mark parameter variants as modes
-- add metadata to current strategies
-
-### Phase 2, harden the Hermes read path
-- make `get_strategy().report` the canonical structured read shape
-- ensure `list_strategies()` and `get_strategy()` cover Hermes inspection needs
-- ensure dashboard and API agree
-
-### Phase 3, add the action layer
-- add `apply_control_decision`
-- validate every transition
-- log the reason for every decision
-- keep legacy helper verbs behind the single write entry point where possible
-
-### Phase 4, implement switching safety
-- confidence threshold
-- hold time
-- hysteresis
-- emergency override
-- degraded execution fallback
-
-### Phase 5, implement the initial strategy set
-- `idle`
-- `defensive`
-- `trend_following`
-- `mean_reversion`
-
-### Phase 6, add structure strategies
-- `grid`
-- `breakout`
-
-### Phase 7, add event-aware behavior
-- `event_driven`
-- event-risk metadata
-- event-pressure aware selection
-
-### Phase 8, feed back execution quality
-- fills
-- slippage
-- latency
-- rejected orders
-- venue stress
-- partial fill patterns
-- degraded connectivity
-
-### Phase 9, tighten dashboards and audit trails
-- current strategy view
-- why-active view
-- recent changes timeline
-- Hermes decision trace
-- execution state panel
-
-## 10. Tests to add
-### Contract tests
-- strategy metadata validation
-- Hermes request schema validation
-- Trader response schema validation
-- control verb validation
-
-### Runtime tests
-- load / unload / switch transitions
-- state snapshot and restore
-- minimum hold enforcement
-- hysteresis enforcement
-- defensive fallback on degraded execution
-
-### Strategy tests
-- expected regime matching
-- avoided regime rejection
-- deterministic state transitions
-- readable explanation output
-
-### Integration tests
-- Hermes decision to Trader control path
-- Trader response parsing
-- execution feedback influencing future selection
-
-## 11. Cleanup and simplification
-- Separate signal-based strategies from structure-based ones, especially `mean_reversion` vs `grid`.
-- Avoid adding micro-strategies until the minimal taxonomy is stable.
-- Keep strategy names human-readable and stable.
-
-## 12. Current implementation order
-1. lock the contract paper
-2. canonicalize the strategy registry
-3. add metadata to current strategies
-4. add validation tests
-5. implement the inspection tools
-6. implement the control tools
-7. add switching safety
-8. implement `idle` and `defensive`
-9. implement `trend_following` and `mean_reversion`
-10. add `grid`, `breakout`, and `event_driven`
-11. wire execution feedback into selection
-12. polish dashboard and traceability

grid_bot_concept.md

@@ -1,6 +0,0 @@
-# Deprecated
-
-This note has been superseded by:
-- `Grid_Bot_Architecture.md`
-
-Keep the newer file as the canonical version.