clodds 1.2.9 → 1.4.0

package/dist/skills/bundled/risk/SKILL.md

@@ -0,0 +1,323 @@
+---
+name: risk
+description: "Unified risk engine with VaR, stress testing, volatility regimes, and automated controls"
+emoji: "🛑"
+---
+
+# Risk - Complete API Reference
+
+Full risk management engine: circuit breakers, loss limits, Value-at-Risk, volatility regime detection, stress testing, and kill switches.
+
+---
+
+## Chat Commands
+
+### View Risk Status
+
+```
+/risk                               Current risk status
+/risk status                        Detailed status with portfolio metrics
+/risk limits                        View all limits
+/risk dashboard                     Real-time risk metrics (VaR, regime, HHI, etc.)
+```
+
+### Risk Analytics
+
+```
+/risk var                           Value-at-Risk and CVaR numbers
+/risk regime                        Current volatility regime and size multiplier
+/risk stress [scenario]             Run stress test (flash_crash, black_swan, etc.)
+```
+
+**Available stress scenarios:** `flash_crash`, `liquidity_crunch`, `platform_down`, `correlation_spike`, `black_swan`
+
+### Configure Limits
+
+```
+/risk set max-loss 1000             Max daily loss ($)
+/risk set max-loss-pct 10           Max daily loss (%)
+/risk set max-drawdown 20           Max drawdown (%)
+/risk set max-position 25           Max single position (%)
+/risk set max-trades 50             Max trades per day
+/risk set consecutive-losses 5      Stop after N losses
+```
+
+### Circuit Breaker
+
+```
+/risk trip "manual stop"            Manually trip breaker
+/risk reset                         Reset after cooldown
+/risk kill                          Emergency stop all trading
+/risk check 500                     Check if a $500 trade is allowed
+```
+
+---
+
+## TypeScript API Reference
+
+### Unified Risk Engine
+
+The risk engine is the single entry point for all pre-trade validation. It orchestrates 10 checks in order:
+
+1. Kill switch (SafetyManager)
+2. Circuit breaker (execution-level)
+3. Max order size
+4. Exposure limits
+5. Daily loss limit
+6. Max drawdown
+7. Position concentration
+8. VaR limit
+9. Volatility regime
+10. Kelly sizing recommendation
+
+```typescript
+import { createRiskEngine } from 'clodds/risk';
+
+const engine = createRiskEngine(
+  {
+    varLimit: 500,           // Reject trades if portfolio VaR > $500
+    varConfidence: 0.95,
+    varWindowSize: 100,
+    volatilityConfig: {
+      lookbackWindow: 30,
+      haltOnExtreme: true,   // Stop trading in extreme volatility
+    },
+  },
+  {
+    riskContext,              // From trading/risk.ts
+    safetyManager,           // From trading/safety.ts
+    circuitBreaker,          // From execution/circuit-breaker.ts
+    kellyCalculator,         // From trading/kelly.ts
+    getPositions: () => positions,
+    getPositionValues: () => positions.map(p => p.value),
+  }
+);
+```
+
+### Validate a Trade
+
+```typescript
+const decision = engine.validateTrade({
+  userId: 'user-123',
+  platform: 'polymarket',
+  marketId: 'market-456',
+  outcome: 'YES',
+  side: 'buy',
+  size: 500,
+  price: 0.65,
+  estimatedEdge: 0.05,    // 5% edge
+  confidence: 0.8,
+  category: 'politics',
+});
+
+if (decision.approved) {
+  // Use adjustedSize — may be smaller than requested (Kelly + regime)
+  await executeTrade(decision.adjustedSize);
+  console.log(`Regime: ${decision.regime}`);
+  console.log(`Warnings: ${decision.warnings}`);
+} else {
+  console.log(`Blocked: ${decision.reason}`);
+  // Check which step failed:
+  for (const check of decision.checks) {
+    console.log(`  ${check.name}: ${check.passed ? 'PASS' : 'FAIL'} — ${check.message}`);
+  }
+}
+```
+
+### Record Trade P&L (feeds VaR + volatility)
+
+```typescript
+engine.recordPnL({
+  pnlUsd: -45.20,
+  pnlPct: -0.09,
+  positionId: 'polymarket:market-456:YES',
+  timestamp: new Date(),
+});
+```
+
+### Portfolio Risk Snapshot
+
+```typescript
+const risk = engine.getPortfolioRisk();
+console.log(`Total value: $${risk.totalValue}`);
+console.log(`VaR (95%): $${risk.var95}`);
+console.log(`VaR (99%): $${risk.var99}`);
+console.log(`CVaR (95%): $${risk.cvar95}`);
+console.log(`Regime: ${risk.regime}`);
+console.log(`Drawdown: ${risk.drawdownPct}%`);
+```
+
+### Value-at-Risk
+
+```typescript
+import { createVaRCalculator, calculateVaR, calculateCVaR } from 'clodds/risk';
+
+// Full calculator with rolling window
+const calc = createVaRCalculator({ windowSize: 100, confidenceLevel: 0.95 });
+calc.addObservation({ pnlUsd: -50, pnlPct: -0.05, timestamp: new Date() });
+const result = calc.calculateAt(0.99);
+console.log(`VaR (99%): $${result.historicalVaR}`);
+console.log(`CVaR (99%): $${result.cvar}`);
+
+// Quick one-liners
+const var95 = calculateVaR(pnlArray, 0.95);
+const cvar95 = calculateCVaR(pnlArray, 0.95);
+```
+
+### Volatility Regime Detection
+
+```typescript
+import { createVolatilityDetector, detectRegime } from 'clodds/risk';
+
+const detector = createVolatilityDetector({
+  lookbackWindow: 30,
+  haltOnExtreme: false,
+  regimeMultipliers: { low: 1.2, normal: 1.0, high: 0.5, extreme: 0.25 },
+});
+
+detector.addObservation(0.03);  // 3% P&L
+const snapshot = detector.detect();
+console.log(`Regime: ${snapshot.regime}`);          // 'low' | 'normal' | 'high' | 'extreme'
+console.log(`Size multiplier: ${snapshot.sizeMultiplier}x`);
+console.log(`Should halt: ${snapshot.shouldHalt}`);
+
+// One-shot from array
+const regime = detectRegime(recentPnLPcts);
+```
+
+### Stress Testing
+
+```typescript
+import { runStressTest, runAllScenarios, getAvailableScenarios } from 'clodds/risk';
+
+const result = runStressTest(positions, 'flash_crash');
+console.log(`Estimated loss: $${result.estimatedLoss} (${result.estimatedLossPct}%)`);
+console.log(`Severity: ${result.severity}`);
+console.log(`Recommendations: ${result.recommendations.join(', ')}`);
+
+// Run all scenarios at once
+const all = runAllScenarios(positions);  // sorted by severity
+
+// Override scenario parameters
+const custom = runStressTest(positions, 'flash_crash', {
+  scenarios: { flash_crash: { lossPct: 30, description: 'Severe crash' } },
+});
+```
+
+### Risk Dashboard
+
+```typescript
+import { getRiskDashboard } from 'clodds/risk';
+
+const dashboard = engine.getDashboard();
+console.log(`VaR (95%): $${dashboard.portfolioVaR95}`);
+console.log(`Regime: ${dashboard.regime} (${dashboard.regimeSizeMultiplier}x)`);
+console.log(`Daily P&L: $${dashboard.dailyPnL} / $${dashboard.dailyLossLimit}`);
+console.log(`Drawdown: ${dashboard.currentDrawdown}% / ${dashboard.maxDrawdown}%`);
+console.log(`Concentration HHI: ${dashboard.concentrationHHI}`);
+console.log(`Kill switch: ${dashboard.killSwitchActive}`);
+console.log(`Warnings: ${dashboard.warnings}`);
+```
+
+### Circuit Breaker (Standalone)
+
+```typescript
+import { createCircuitBreaker, MODERATE_CONFIG } from 'clodds/risk';
+
+// Feature-engineering circuit breaker (market-condition-aware)
+const breaker = createCircuitBreaker(MODERATE_CONFIG);
+breaker.startMonitoring();
+
+if (!breaker.canTrade('polymarket', marketId)) {
+  return; // Trading halted
+}
+
+breaker.recordTrade({ success: true, pnl: 2.5 });
+```
+
+### Kill Switch
+
+```typescript
+// Emergency stop via SafetyManager — no auto-resume
+safetyManager.killSwitch('Market anomaly detected');
+
+// Resume manually after review
+safetyManager.resumeTrading();
+```
+
+---
+
+## Risk Engine Checks
+
+| # | Check | Module | Blocks Trade? |
+|---|-------|--------|---------------|
+| 1 | Kill switch | SafetyManager | Yes |
+| 2 | Circuit breaker | CircuitBreaker | Yes |
+| 3 | Max order size | trading/risk | Yes |
+| 4 | Exposure limits | trading/risk | Yes |
+| 5 | Daily loss limit | SafetyManager | Yes |
+| 6 | Max drawdown | SafetyManager | Yes |
+| 7 | Concentration | SafetyManager | Yes |
+| 8 | VaR limit | VaRCalculator | Yes (if configured) |
+| 9 | Volatility regime | VolatilityDetector | Yes (if extreme + halt) |
+| 10 | Kelly sizing | DynamicKelly | No (adjusts size) |
+
+## Circuit Breaker Triggers
+
+| Trigger | Default | Description |
+|---------|---------|-------------|
+| **Daily loss (USD)** | $1,000 | Absolute loss limit |
+| **Daily loss (%)** | 10% | Percentage of capital |
+| **Drawdown** | 20% | Peak-to-trough |
+| **Consecutive losses** | 5 | Losses in a row |
+| **Error rate** | 50% | Failed order rate |
+| **Max trades** | 50 | Trades per day |
+
+## Volatility Regimes
+
+| Regime | Size Multiplier | Description |
+|--------|----------------|-------------|
+| `low` | 1.2x | Calm markets, slightly larger positions |
+| `normal` | 1.0x | Baseline conditions |
+| `high` | 0.5x | Elevated volatility, half size |
+| `extreme` | 0.25x | Crisis — quarter size or halt trading |
+
+## Stress Test Scenarios
+
+| Scenario | Loss | Description |
+|----------|------|-------------|
+| `flash_crash` | 20% | All positions lose value instantly |
+| `liquidity_crunch` | 10% | Slippage doubles, partial fills |
+| `platform_down` | 15% | Primary platform offline |
+| `correlation_spike` | 25% | All positions move together |
+| `black_swan` | 40% | 3-sigma tail event |
+
+## Status Levels
+
+| Status | Description |
+|--------|-------------|
+| `armed` | Normal, trading allowed |
+| `warning` | Approaching limits (80%) |
+| `tripped` | Limit exceeded, trading stopped |
+| `killed` | Emergency stop, manual reset required |
+
+---
+
+## Recovery Process
+
+1. **Auto-reset**: Next day at midnight (daily counters)
+2. **Cooldown**: Circuit breaker auto-resets after cooldown period
+3. **Manual reset**: `/risk reset` to re-arm
+4. **Kill recovery**: `/risk reset` after manual review (no auto-resume)
+
+---
+
+## Best Practices
+
+1. **Start conservative** — Lower limits while learning
+2. **Don't override** — Respect the circuit breaker
+3. **Review trips** — Understand why limits were hit
+4. **Monitor VaR** — Use `/risk var` and `/risk dashboard` regularly
+5. **Run stress tests** — Use `/risk stress` before large position changes
+6. **Watch regime** — Use `/risk regime` to understand current volatility
+7. **Adjust limits** — Based on strategy performance and regime

package/dist/skills/bundled/router/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: router
+description: "Smart order routing for best price, liquidity, and execution"
+emoji: "🔀"
+---
+
+# Router - Complete API Reference
+
+Route orders to the best platform based on price, liquidity, fees, and execution quality.
+
+---
+
+## Chat Commands
+
+### Route Order
+
+```
+/route "Trump 2028" YES 1000        Find best route for $1000
+/route BTCUSDT long 0.5             Route futures order
+/route --mode best-price "Fed" YES  Optimize for price
+/route --mode best-liquidity ...    Optimize for fills
+```
+
+### Compare Routes
+
+```
+/route compare "Trump" YES 1000     Compare all platforms
+/route fees "Trump"                 Compare fee structures
+/route liquidity "Trump"            Compare orderbook depth
+```
+
+### Execution
+
+```
+/route execute <route-id>           Execute routed order
+/route split "Trump" YES 5000       Split across platforms
+```
+
+---
+
+## TypeScript API Reference
+
+### Create Smart Router
+
+```typescript
+import { createSmartRouter } from 'clodds/router';
+
+const router = createSmartRouter({
+  // Supported platforms
+  platforms: ['polymarket', 'kalshi', 'manifold'],
+
+  // Default mode
+  defaultMode: 'balanced',
+
+  // Fee structures
+  fees: {
+    polymarket: { maker: -0.005, taker: 0.01 },
+    kalshi: { maker: 0, taker: 0.01 },
+    manifold: { maker: 0, taker: 0 },
+  },
+});
+```
+
+### Find Best Route
+
+```typescript
+const route = await router.findBestRoute({
+  market: 'trump-win-2028',
+  side: 'YES',
+  size: 1000,
+  mode: 'best-price',  // 'best-price' | 'best-liquidity' | 'lowest-fee' | 'balanced'
+});
+
+console.log(`Best platform: ${route.platform}`);
+console.log(`Expected price: ${route.expectedPrice}`);
+console.log(`Expected slippage: ${route.expectedSlippage}%`);
+console.log(`Fees: $${route.fees}`);
+console.log(`Net cost: $${route.netCost}`);
+console.log(`Fill probability: ${route.fillProbability}%`);
+```
+
+### Compare All Platforms
+
+```typescript
+const comparison = await router.compare({
+  market: 'trump-win-2028',
+  side: 'YES',
+  size: 1000,
+});
+
+console.log('Platform Comparison:');
+for (const platform of comparison) {
+  console.log(`\n${platform.name}:`);
+  console.log(`  Price: ${platform.price}`);
+  console.log(`  Liquidity: $${platform.liquidity}`);
+  console.log(`  Slippage: ${platform.slippage}%`);
+  console.log(`  Fees: $${platform.fees}`);
+  console.log(`  Net cost: $${platform.netCost}`);
+  console.log(`  Score: ${platform.score}`);
+}
+```
+
+### Split Order Across Platforms
+
+```typescript
+// Large orders split for better execution
+const split = await router.splitOrder({
+  market: 'trump-win-2028',
+  side: 'YES',
+  size: 10000,
+  maxSlippage: 0.02,
+});
+
+console.log('Order Split:');
+for (const leg of split.legs) {
+  console.log(`  ${leg.platform}: $${leg.size} @ ${leg.price}`);
+}
+console.log(`Total slippage: ${split.totalSlippage}%`);
+console.log(`Avg price: ${split.avgPrice}`);
+```
+
+### Execute Route
+
+```typescript
+// Execute the routed order
+const result = await router.execute(route);
+
+console.log(`Order ID: ${result.orderId}`);
+console.log(`Platform: ${result.platform}`);
+console.log(`Fill price: ${result.fillPrice}`);
+console.log(`Slippage: ${result.actualSlippage}%`);
+console.log(`Fees: $${result.fees}`);
+```
+
+### Routing Modes
+
+```typescript
+// Best price - minimize price paid
+const priceRoute = await router.findBestRoute({
+  ...order,
+  mode: 'best-price',
+});
+
+// Best liquidity - maximize fill probability
+const liquidityRoute = await router.findBestRoute({
+  ...order,
+  mode: 'best-liquidity',
+});
+
+// Lowest fees - minimize transaction costs
+const feeRoute = await router.findBestRoute({
+  ...order,
+  mode: 'lowest-fee',
+});
+
+// Balanced - weighted optimization
+const balancedRoute = await router.findBestRoute({
+  ...order,
+  mode: 'balanced',
+  weights: {
+    price: 0.4,
+    liquidity: 0.3,
+    fees: 0.3,
+  },
+});
+```
+
+### Fee Analysis
+
+```typescript
+const fees = await router.analyzeFees({
+  market: 'trump-win-2028',
+  side: 'YES',
+  size: 1000,
+});
+
+for (const platform of fees) {
+  console.log(`${platform.name}:`);
+  console.log(`  Maker fee: ${platform.makerFee}%`);
+  console.log(`  Taker fee: ${platform.takerFee}%`);
+  console.log(`  For this order: $${platform.totalFee}`);
+  console.log(`  Rebate available: ${platform.hasRebate}`);
+}
+```
+
+### Liquidity Analysis
+
+```typescript
+const liquidity = await router.analyzeLiquidity({
+  market: 'trump-win-2028',
+  side: 'YES',
+});
+
+for (const platform of liquidity) {
+  console.log(`${platform.name}:`);
+  console.log(`  Best bid: ${platform.bestBid}`);
+  console.log(`  Best ask: ${platform.bestAsk}`);
+  console.log(`  Spread: ${platform.spread}%`);
+  console.log(`  Depth at 1%: $${platform.depth1Pct}`);
+  console.log(`  Depth at 2%: $${platform.depth2Pct}`);
+}
+```
+
+---
+
+## Routing Modes
+
+| Mode | Optimizes For | Best When |
+|------|---------------|-----------|
+| `best-price` | Lowest price | Small orders |
+| `best-liquidity` | Fill probability | Large orders |
+| `lowest-fee` | Minimize fees | High frequency |
+| `balanced` | Weighted combo | Default choice |
+
+---
+
+## Platform Comparison
+
+| Platform | Maker Fee | Taker Fee | Notes |
+|----------|-----------|-----------|-------|
+| **Polymarket** | 0% | 0% | Zero fees on most markets; 15-min crypto markets have dynamic fees |
+| **Kalshi** | ~0.17% | ~1.2% | Formula-based fees, capped at ~2% |
+| **Manifold** | 0% | 0% | Play money |
+
+---
+
+## Best Practices
+
+1. **Compare before trading** — Always check alternatives
+2. **Use maker orders** — Pay no fees on Polymarket (vs dynamic fees on 15-min crypto markets)
+3. **Split large orders** — Reduce slippage
+4. **Check liquidity** — Don't trade thin markets
+5. **Account for fees** — Polymarket: 0% most markets; Kalshi: ~1.2% average