dexbot 1.4.13 → 1.4.14

package/claw/docs/AI_BOT_LIBRARY_API.md

@@ -317,7 +317,7 @@ type ConstraintSet = {
 
 ## Public API
 
-All functions below are implemented and exported from the modules cited under "Core Types" or their headers. Signatures reflect the runtime types; see [../modules/types.ts](../modules/types.ts) for the authoritative TypeScript interfaces.
+All functions below are implemented in the modules cited under "Core Types" or their headers and are reachable through the adapters/factories they document. Standalone names are exported from the cited modules; methods like `getBotSettings`, `previewBotSettingsUpdate`, `applyBotSettingsPatch`, and `getClawProfileContext` are closures returned by `createDexbotProfileAdapter` (not module-level exports). Signatures reflect the runtime types; see [../modules/types.ts](../modules/types.ts) for the authoritative TypeScript interfaces.
 
 ### 1. `createRuntimeContext(options)`
 

package/claw/docs/POSITION_HEALTH.md

@@ -63,7 +63,7 @@ When a trend signal is available, the assessor checks whether the position direc
 
 ## CR Adjustment Planning
 
-CR math is handled by the shared planner at `modules/cr_planner.ts` (root level, not claw), which provides `debtDeltaForTargetCr()` and `collateralDeltaForTargetCr()`. Claw's position health module consumes these through the planner interface. Any executed CR adjustment should be followed by a grid rebuild, because the available-funds baseline is no longer valid after the debt or collateral leg changes.
+CR math is handled by the shared planner at `modules/cr_planner.ts` (root level, not claw), which provides `debtDeltaForTargetCr()` and `collateralDeltaForTargetCr()`. Any executed CR adjustment should be followed by a grid rebuild, because the available-funds baseline is no longer valid after the debt or collateral leg changes.
 
 ## Decision Loop Planning
 
@@ -108,7 +108,7 @@ npm run service:position-watch -- --account your-account
 
 The executable behavior lives in the modules. This document should be kept aligned with:
 
-- `../cr_planner.ts` (root level)
+- `modules/cr_planner.ts` (root level)
 - `modules/position_health.ts`
 - `modules/position_discovery.ts`
 - `modules/decision_loop.ts`

package/claw/modules/claw_catalog.ts

@@ -1,6 +1,4 @@
-function shellQuote(value: any) {
-  return `'${String(value).replace(/'/g, `'\"'\"'`)}'`;
-}
+import { shellQuote } from './skill_utils.js';
 
 const SUPPORTED_RUNTIMES = ['openclaw', 'hermes', 'openfang', 'nanobot', 'picoclaw', 'nanoclaw', 'zeroclaw', 'nullclaw', 'memu'];
 

package/claw/modules/claw_launcher.ts

@@ -241,8 +241,7 @@ async function launcherPm2Start(botName: string | null, options: Record<string,
   }
 
   // Generate ecosystem config and get apps array
-  getPM2Module().generateEcosystemConfig({ clawOnly: false, exitOnError: false });
-  const apps = getPM2Module().buildEcosystemApps({ clawOnly: false });
+  const apps = getPM2Module().generateEcosystemConfig({ clawOnly: false, exitOnError: false });
 
   // Filter apps if specific bot requested
   let appsToStart = apps;
@@ -448,5 +447,5 @@ async function launcherUnlockStart(botName: string | null, options: Record<strin
   };
 }
 
-export { launcherRun, launcherStart, launcherDrystart, launcherReset, launcherDisable, launcherPm2Start, launcherPm2Stop, launcherPm2Delete, launcherPm2Restart, launcherClawOnly, launcherUnlockStart }
+export { launcherRun, launcherStart, launcherDrystart, launcherReset, launcherDisable, launcherPm2Start, launcherPm2Stop, launcherPm2Delete, launcherPm2Restart }
 

package/claw/modules/claw_skill_md.ts

@@ -7,7 +7,7 @@ import { buildBridgeCommand, buildSkillTomlLines, createTool, normalizeRepoRoot,
 const storage = getStorage();
 
 function normalizeClawRepoRoot(repoRoot: string) {
-  return normalizeRepoRoot('claw-skill-md', repoRoot);
+  return normalizeRepoRoot(repoRoot);
 }
 
 function buildToolSummary(runtimeName: string) {

package/claw/modules/decision_loop.ts

@@ -30,7 +30,7 @@ import { getErrorMessage } from '../../modules/utils/errors.js';
 let KalmanTrendAnalyzer: any = null;
 function getTrendAnalyzer() {
   if (!KalmanTrendAnalyzer) {
-    KalmanTrendAnalyzer = require('../../analysis/trend_detection/kalman_trend_analyzer').KalmanTrendAnalyzer;
+    KalmanTrendAnalyzer = require('../../market_adapter/core/signals/kalman_trend_analyzer').KalmanTrendAnalyzer;
   }
   return KalmanTrendAnalyzer;
 }

package/claw/modules/dexbot_profiles.ts

@@ -4,7 +4,7 @@ import { getStorage } from '../../modules/storage/index.js';
 import { DEFAULT_CONFIG, GRID_LIMITS, INCREMENT_BOUNDS } from '../../modules/constants.js';
 import { resolveRelativePrice } from '../../modules/order/utils/math.js';
 import { Config } from '../../modules/config.js';
-import { PATHS, getRecalculateTriggerFile } from '../../modules/paths.js';
+import { PATHS } from '../../modules/paths.js';
 import { writeJsonFileAtomic as baseWriteJsonFileAtomic } from '../../modules/bots_file_lock.js';
 import { acquireFileLock } from '../../market_adapter/utils/file_lock.js';
 import { assertNoDuplicateBotKeys } from '../../modules/bot_settings.js';
@@ -1235,34 +1235,6 @@ function createDexbotProfileAdapter(profileRoot: string | null, options: Partial
     });
   }
 
-  async function listOrderArtifacts(forceReload = false) {
-    const bundle = await loadBundle(forceReload);
-    return Promise.all(bundle.orderFiles.map(async (fileName: any) => {
-      const fullPath = path.join(bundle.ordersDir, fileName);
-      if (fileName.endsWith('.json')) {
-        return { fileName, fullPath, json: await readJsonFile(fullPath) };
-      }
-      return { fileName, fullPath, json: null };
-    }));
-  }
-
-  function consumeTrigger(botKey: any) {
-    const triggerPath = path.join(getProfilesDir(), `recalculate.${botKey}.trigger`);
-    const trigger = readTriggerFile(triggerPath);
-    if (!trigger.exists) {
-      return { consumed: false, payload: null };
-    }
-    storage.unlink(triggerPath);
-    return { consumed: true, payload: trigger.payload };
-  }
-
-  function writeTrigger(botKey: any, payload: any = null) {
-    const triggerPath = path.join(getProfilesDir(), `recalculate.${botKey}.trigger`);
-    const content = payload ? JSON.stringify(payload, null, 2) : '';
-    storage.ensureDir(path.dirname(triggerPath));
-    writeTextPayload(triggerPath, content);
-  }
-
   async function updateBotSettings(identifier: any, patch: any) {
     if (!isPlainObject(patch)) {
       throw new Error('patch must be a non-null object');
@@ -1320,19 +1292,16 @@ function createDexbotProfileAdapter(profileRoot: string | null, options: Partial
   return {
     buildClawProfileContext: (bundle: any, contextOptions = {}) => buildClawProfileContext(bundle, contextOptions),
     applyBotSettingsPatch,
-    consumeTrigger,
     findBot,
     getBotBundle,
     getBotSettings,
     getClawProfileContext,
     getProfilesDir,
     listBots,
-    listOrderArtifacts,
     loadBundle,
     previewBotSettingsUpdate,
     resolveProfilesDir: () => resolveProfilesDir(profileRoot || options.profileRoot),
-    updateBotSettings,
-    writeTrigger
+    updateBotSettings
   };
 }
 

package/claw/modules/feed_price_source.ts

@@ -10,45 +10,16 @@
 
 
 import { getAsset, getBackingAsset, getBitassetData, dbCall } from './chain_queries.js';
-import { loadDexbotOrderUtils } from './dexbot_bridge.js';
+import { computeBtsPerMpa } from './mpa_utils.js';
 import { roundTo } from '../../modules/utils/math_utils.js';
 'use strict';
 
 
-function getBlockchainToFloat() {
-  return loadDexbotOrderUtils().blockchainToFloat;
-}
-
 /**
  * Extract BTS-per-MPA from the settlement price object.
- * Replicates the logic in position_manager (computeBtsPerMpaFromSettlement)
- * but as a standalone utility.
+ * Re-exported alias of the canonical computeBtsPerMpa in mpa_utils.
  */
-function parseBtsPerMpa(settlementPrice: any, mpaAsset: any, backingAsset: any) {
-  const base = settlementPrice?.base;
-  const quote = settlementPrice?.quote;
-  if (!base || !quote) return null;
-
-  const blockchainToFloat = getBlockchainToFloat();
-  const baseAmount = blockchainToFloat(
-    base.amount,
-    base.asset_id === mpaAsset.id ? mpaAsset.precision : backingAsset.precision
-  );
-  const quoteAmount = blockchainToFloat(
-    quote.amount,
-    quote.asset_id === mpaAsset.id ? mpaAsset.precision : backingAsset.precision
-  );
-  if (!baseAmount || !quoteAmount) return null;
-
-  // BTS per MPA
-  if (base.asset_id === backingAsset.id && quote.asset_id === mpaAsset.id) {
-    return baseAmount / quoteAmount;
-  }
-  if (base.asset_id === mpaAsset.id && quote.asset_id === backingAsset.id) {
-    return quoteAmount / baseAmount;
-  }
-  return null;
-}
+const parseBtsPerMpa = computeBtsPerMpa;
 
 /**
  * Fetch the current feed price for an MPA.

package/claw/modules/launcher_mode_detector.ts

@@ -188,5 +188,5 @@ function describeModeChoice(mode: string) {
   return descriptions[mode] || mode;
 }
 
-export { normalizeMode, detectMode, setPreferredMode, loadConfig, saveConfig, hasActiveBots, describeModeChoice }
+export { normalizeMode, detectMode, setPreferredMode, describeModeChoice }
 

package/claw/modules/mcp_utils.ts

@@ -2,7 +2,7 @@ import { hasProcess } from '../../modules/env.js';
 import { Config } from '../../modules/config.js';
 import { runtime } from '../../modules/runtime.js';
 
-export function writeMessage(message: any) {
+function writeMessage(message: any) {
   if (!hasProcess()) {
     return Promise.reject(new Error('MCP stdio transport not available in this environment'));
   }

package/claw/modules/mpa_utils.ts

@@ -1,6 +1,7 @@
 'use strict';
 
 import { getAsset, getBackingAsset } from './chain_queries.js';
+import { loadDexbotOrderUtils } from './dexbot_bridge.js';
 
 const CORE_SYMBOL = 'BTS';
 
@@ -27,5 +28,39 @@ async function requireBtsBackedMpa(mpaSymbolOrId: any) {
   };
 }
 
-export { CORE_SYMBOL, requireBtsBackedMpa }
+function getBlockchainToFloat() {
+  return loadDexbotOrderUtils().blockchainToFloat;
+}
+
+/**
+ * Compute BTS-per-MPA from a settlement price object.
+ * Canonical implementation shared by position discovery, position manager,
+ * and the feed price source.
+ */
+function computeBtsPerMpa(settlementPrice: any, mpaAsset: any, backingAsset: any) {
+  const base = settlementPrice?.base;
+  const quote = settlementPrice?.quote;
+  if (!base || !quote) return null;
+
+  const blockchainToFloat = getBlockchainToFloat();
+  const baseAmount = blockchainToFloat(
+    base.amount,
+    base.asset_id === mpaAsset.id ? mpaAsset.precision : backingAsset.precision
+  );
+  const quoteAmount = blockchainToFloat(
+    quote.amount,
+    quote.asset_id === mpaAsset.id ? mpaAsset.precision : backingAsset.precision
+  );
+  if (!baseAmount || !quoteAmount) return null;
+
+  if (base.asset_id === backingAsset.id && quote.asset_id === mpaAsset.id) {
+    return baseAmount / quoteAmount;
+  }
+  if (base.asset_id === mpaAsset.id && quote.asset_id === backingAsset.id) {
+    return quoteAmount / baseAmount;
+  }
+  return null;
+}
+
+export { CORE_SYMBOL, computeBtsPerMpa, requireBtsBackedMpa }
 

package/claw/modules/position_discovery.ts

@@ -10,6 +10,7 @@
 
 
 import { loadDexbotOrderUtils } from './dexbot_bridge.js';
+import { computeBtsPerMpa } from './mpa_utils.js';
 import { roundTo } from '../../modules/utils/math_utils.js';
 'use strict';
 
@@ -19,34 +20,6 @@ function getBlockchainToFloat() {
   return loadDexbotOrderUtils().blockchainToFloat;
 }
 
-/**
- * Compute BTS-per-MPA from settlement price.
- */
-function computeBtsPerMpa(settlementPrice: any, mpaAsset: any, backingAsset: any) {
-  const base = settlementPrice?.base;
-  const quote = settlementPrice?.quote;
-  if (!base || !quote) return null;
-
-  const blockchainToFloat = getBlockchainToFloat();
-  const baseAmount = blockchainToFloat(
-    base.amount,
-    base.asset_id === mpaAsset.id ? mpaAsset.precision : backingAsset.precision
-  );
-  const quoteAmount = blockchainToFloat(
-    quote.amount,
-    quote.asset_id === mpaAsset.id ? mpaAsset.precision : backingAsset.precision
-  );
-  if (!baseAmount || !quoteAmount) return null;
-
-  if (base.asset_id === backingAsset.id && quote.asset_id === mpaAsset.id) {
-    return baseAmount / quoteAmount;
-  }
-  if (base.asset_id === mpaAsset.id && quote.asset_id === backingAsset.id) {
-    return quoteAmount / baseAmount;
-  }
-  return null;
-}
-
 /**
  * Normalize a raw call order into a position object compatible with
  * assessPosition() from position_health.ts.

package/claw/modules/position_health.ts

@@ -123,17 +123,6 @@ function assessPosition(position: any, trendSignal: Record<string, any> | null =
   return assessment;
 }
 
-/**
- * Assess all positions from a PositionManager state.
- *
- * @param {Array}  positions     – Array of position objects
- * @param {Object} [trendSignal] – Optional trend signal to apply to all
- * @returns {Array} Array of health assessments
- */
-function assessAllPositions(positions: any[], trendSignal: Record<string, any> | null = null) {
-  return (positions || []).map((p) => assessPosition(p, trendSignal));
-}
-
 /**
  * Parse a ratio value from a string (e.g. "3x") or numeric price ratio.
  * Returns null if the value cannot be parsed.
@@ -155,14 +144,6 @@ function parseRatioValue(value: any, referencePrice: any, mode: string) {
   return mode === 'min' ? reference / numeric : numeric / reference;
 }
 
-/**
- * Format a numeric ratio as a human-readable multiplier string (e.g. 3.00x).
- */
-function formatRatioAsMultiplier(ratio: any) {
-  const rounded = roundToDecimals(ratio, 2);
-  return `${rounded}x`;
-}
-
 /**
  * Classify a price range ratio into a descriptive category.
  * Categories: very_competitive (< 2), competitive (2–3), conservative (3–3.25), very_conservative (> 3.25).
@@ -356,5 +337,5 @@ function computeOrderWeightBias(trend = 'NEUTRAL', confidence = 0) {
   };
 }
 
-export { CR_ZONES, assessAllPositions, assessPosition, checkTrendAlignment, classifyCrZone, classifyPriceRangeRatio, computePriceRangeRatioPlan, computeOrderWeightBias, crWeight, trendWeight }
+export { CR_ZONES, assessPosition, checkTrendAlignment, classifyCrZone, classifyPriceRangeRatio, computePriceRangeRatioPlan, computeOrderWeightBias, crWeight, trendWeight }
 

package/claw/modules/position_manager.ts

@@ -3,7 +3,7 @@ import { getStorage } from '../../modules/storage/index.js';
 import { path } from '../../modules/path_api.js';
 import { PATHS } from '../../modules/paths.js';
 import { Config } from '../../modules/config.js';
-import { requireBtsBackedMpa } from './mpa_utils.js';
+import { requireBtsBackedMpa, computeBtsPerMpa } from './mpa_utils.js';
 import { listenForFills } from './chain_actions.js';
 import { writeJsonFileAtomic } from './dexbot_profiles.js';
 import { loadDexbotOrderUtils } from './dexbot_bridge.js';
@@ -12,7 +12,7 @@ const storage = getStorage();
 import { closeShortOnBts, openShortOnBts, placeTakeProfitBuyOrderOnBts } from './short_mpa_strategy.js';
 import { getAsset, getBackingAsset, getBalances, getBitassetData, getFullAccount } from './chain_queries.js';
 
-import type { ShortPositionOptions, PositionManagerOptions, PositionData, AssetData, ChainPosition } from './types.js';
+import type { ShortPositionOptions, PositionManagerOptions } from './types.js';
 
 function getBlockchainToFloat() {
   return loadDexbotOrderUtils().blockchainToFloat;
@@ -263,31 +263,6 @@ function refreshPositionPnl(position: any) {
   position.pnl.updatedAt = nowIso();
 }
 
-function computeBtsPerMpaFromSettlement(settlementPrice: any, mpaAsset: any, backingAsset: any) {
-  const base = settlementPrice?.base;
-  const quote = settlementPrice?.quote;
-  if (!base || !quote) {
-    return null;
-  }
-
-  const blockchainToFloat = getBlockchainToFloat();
-  const baseAmount = blockchainToFloat(base.amount, base.asset_id === mpaAsset.id ? mpaAsset.precision : backingAsset.precision);
-  const quoteAmount = blockchainToFloat(quote.amount, quote.asset_id === mpaAsset.id ? mpaAsset.precision : backingAsset.precision);
-  if (!baseAmount || !quoteAmount) {
-    return null;
-  }
-
-  if (base.asset_id === backingAsset.id && quote.asset_id === mpaAsset.id) {
-    return baseAmount / quoteAmount;
-  }
-
-  if (base.asset_id === mpaAsset.id && quote.asset_id === backingAsset.id) {
-    return quoteAmount / baseAmount;
-  }
-
-  return null;
-}
-
 function normalizeCallPosition(callOrder: any, mpaAsset: any, backingAsset: any, bitassetData: any) {
   if (!callOrder) {
     return {
@@ -303,7 +278,7 @@ function normalizeCallPosition(callOrder: any, mpaAsset: any, backingAsset: any,
   const blockchainToFloat = getBlockchainToFloat();
   const debtAmount = blockchainToFloat(callOrder.debt, mpaAsset.precision);
   const collateralAmount = blockchainToFloat(callOrder.collateral, backingAsset.precision);
-  const btsPerMpa = computeBtsPerMpaFromSettlement(bitassetData?.current_feed?.settlement_price, mpaAsset, backingAsset);
+  const btsPerMpa = computeBtsPerMpa(bitassetData?.current_feed?.settlement_price, mpaAsset, backingAsset);
   const debtValueInBts = debtAmount && btsPerMpa ? debtAmount * btsPerMpa : 0;
   const collateralRatio = debtValueInBts > 0 ? collateralAmount / debtValueInBts : null;
 

package/claw/modules/skill_utils.ts

@@ -5,7 +5,7 @@ import { path } from '../../modules/path_api.js';
 import { PATHS } from '../../modules/paths.js';
 const { version: DEXBOT_VERSION } = require(path.join(PATHS.PROJECT_ROOT, 'package.json'));
 
-export function normalizeRepoRoot(variableName: string, repoRoot?: string) {
+export function normalizeRepoRoot(repoRoot?: string) {
   return path.resolve(repoRoot || PATHS.CLAW.DIR);
 }
 

package/claw/modules/types.ts

@@ -161,59 +161,6 @@ export interface PositionManagerOptions {
     statePath?: string;
 }
 
-export interface VariantBridgeOptions {
-    runtime?: { name?: string };
-    runtimeName?: string;
-}
-
-export interface AssetData {
-    id: string;
-    symbol: string;
-    precision: number;
-}
-
-export interface PriceData {
-    base: { amount: number; asset_id: string };
-    quote: { amount: number; asset_id: string };
-}
-
-export interface ChainOrder {
-    id: string;
-    for_sale: number;
-    sell_price: PriceData;
-    filled_amount?: number;
-}
-
-export interface ChainPosition {
-    id: string;
-    borrower: string;
-    collateral: number;
-    debt: number;
-    call_price: PriceData;
-    target_collateral_ratio?: number;
-}
-
-export interface FillEvent {
-    order_id: string;
-    pays: { amount: number; asset_id: string };
-    receives: { amount: number; asset_id: string };
-    is_maker: boolean;
-}
-
-export interface PositionData {
-    id: string;
-    market: string;
-    mpaSymbol: string;
-    onChain: {
-        debtAmount: number;
-        collateralAmount: number;
-        sellPriceInBts?: number;
-        targetCollateralRatio?: number | null;
-    };
-    accountName?: string;
-    privateKey?: string;
-}
-
 export interface ClawProfileBundle {
     profileRoot?: string;
     botsFile?: string;

package/claw/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dexbot2-claw",
-  "version": "1.4.13",
+  "version": "1.4.14",
   "private": true,
   "description": "Claw bridge and runtime integration layer for BitShares and DEXBot2.",
   "type": "module",

package/claw/runtimes/openclaw-plugin/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "bitshares-claw",
   "name": "BitShares Claw",
   "description": "Native BitShares and DEXBot2 tools from the DEXBot2 claw integration",
-  "version": "1.4.13",
+  "version": "1.4.14",
   "skills": [
     "skills"
   ],

package/claw/runtimes/openclaw-plugin/package.json

@@ -1,7 +1,7 @@
 {
   "name": "bitshares-claw-openclaw-plugin",
   "private": true,
-  "version": "1.4.13",
+  "version": "1.4.14",
   "type": "module",
   "main": "index.js"
 }

package/claw/skills/margin-trading/references/honest-assets.md

@@ -11,7 +11,7 @@ HONEST.Assets are Market Pegged Assets (MPAs) on the BitShares DEX backed by BTS
 
 All HONEST.Assets share the same parameters except HONEST.USD which has a higher taker fee.
 
-Order operation fees (create, update, cancel) are approximately 0.1 BTS each.
+Order operation fees (create, update, cancel) are charged in BTS and are dynamic — the bot caches them at startup in `profiles/fee_cache.json` (e.g. create 0.4826, update 0.375, cancel 0.00482 BTS).
 
 ## Collateral
 

package/claw/skills/margin-trading/references/position-management.md

@@ -43,7 +43,7 @@ A position profits when the market moves in the direction the position is expose
 - **Short** profits when the MPA price (in BTS) decreases — the MPA bought back cheaper than it was sold
 - **Long** profits when the MPA price (in BTS) increases — the MPA sold higher than it was bought
 
-The shared trend-detection service provides signals based on AMA deviation from the feed price and the instantaneous premium/discount. These signals indicate which direction the smoothed market is moving relative to the feed anchor.
+The shared trend-detection service provides signals based on a Kalman-filter trend state (velocity/displacement from the order-book mid price relative to the feed anchor) plus the instantaneous premium/discount. These signals indicate which direction the smoothed market is moving relative to the feed anchor.
 
 Combining position direction with the trend signal:
 
@@ -182,7 +182,7 @@ Total BTS
 ├── Pending (proceeds from fills, not yet redeployed)
 │   └── Target: minimize time in this state
 └── Reserve (fee budget for operations)
-    └── ~0.1 BTS per order operation
+    └── BTS fees per order op (dynamic — see `profiles/fee_cache.json`; e.g. create 0.48, update 0.38, cancel 0.005 BTS)
 ```
 
 MPA holdings follow the same logic — MPA sitting in wallet balance is idle. MPA placed as a sell order or used to repay debt is working.

package/claw/skills/shared/references/js-automation-overview.md

@@ -11,12 +11,12 @@ Focus on the practical module split:
 
 Keep the implementation reference explicit:
 
-- DEXBot2 shows a real Node.js/CommonJS bot runtime with shared reads, per-account signing, persistence, and reconciliation
+- DEXBot2 shows a real Node.js/ES Modules bot runtime with shared reads, per-account signing, persistence, and reconciliation
 - AI-Bot should reuse that pattern rather than duplicating it
 
 Preferred baseline:
 
-- `Node.js` / CommonJS first
+- `Node.js` / ES Modules first (the DEXBot2 codebase is ESM, `"type": "module"`, Node >= 22.12)
 - DEXBot2 native BitShares client for chain connectivity
 - shared read connection for market and account state
 - dedicated account client for signing and broadcast

package/claw/skills/trend-detection/references/service.md

@@ -2,34 +2,41 @@
 
 ## Scope
 
-This is the shared DEXBot/Claw trend service. It is independent of margin-trading and should be used for any bot that needs candle-driven signal generation, parameter tuning, and bot-setting updates.
+This is the shared DEXBot/Claw trend service. It is independent of margin-trading and should be used for any bot that needs signal generation, parameter tuning, and bot-setting updates.
 
 ## Signal Flow
 
-1. `market_adapter/market_adapter.ts` keeps candles current and emits the per-bot center/state snapshot.
-2. `analysis/trend_detection/kalman_trend_analyzer.ts` turns candle input plus feed price into trend output.
-3. The service monitors the signal output, premium/discount, and price-ratio context.
+1. `claw/modules/feed_price_source.ts` fetches the **order-book mid price** (`get_order_book`) and the **feed price** for a market, computing the premium/discount.
+2. `claw/modules/decision_loop.ts` feeds those prices into `KalmanTrendAnalyzer` (per market) and uses the resulting trend for position health assessment.
+3. `market_adapter/core/signals/kalman_trend_analyzer.ts` is the canonical analyzer implementation; `analysis/trend_detection/kalman_trend_analyzer.ts` re-exports it so production, analysis tooling, and tests resolve one shared module.
 4. Claw applies supported setting changes through `bot-settings-preview` and `bot-settings-apply`.
 
+Note: the analyzer input is the live order-book mid price plus the feed price — **not** candles.
+
 ## Inputs
 
-- Candle history from the market adapter
-- Feed price / settlement reference
-- Trend analyzer parameters:
-  - `erPeriod`
-  - `fastPeriod`
-  - `slowPeriod`
-  - `thresholdPercent`
-  - `minBarsForConfirmation`
-  - `deadZonePercent`
+- Order-book mid price from `fetchMidPrice('BTS', mpaSymbol)`
+- Feed price / settlement reference (`fetchFeedPrice`)
+- Trend analyzer configuration (`KalmanTrendConfig`):
+  - `rNoise` — measurement noise (default `0.05`)
+  - `qTactical` — tactical filter process noise (default `qNoise` or `0.01`)
+  - `qModal` — modal filter process noise (default `qNoise` or `0.0001`)
+  - `qNoise` — shared process-noise fallback for both filters
+  - `beamCount` — max projected trajectory beams (default `100`)
+  - `dt` — time step per update (default `1`)
+  - `warmupBars` — warmup updates before `isReady` (default `20`)
 - Bot settings fields that the signal may update:
   - `weightDistribution`
+
 ## Outputs
 
-- `UP`, `DOWN`, or `NEUTRAL`
-- Confidence score
+- `trend`: `UP`, `DOWN`, or `FLAT` (from tactical velocity sign)
+- `signal`: `BULLISH_DISPLACEMENT`, `BEARISH_DISPLACEMENT`, `EQUILIBRIUM`, or `NEUTRAL`
+- `confidence`: 0–100 (warmup progress + velocity magnitude)
+- `velocityPct` / `velocityFilteredPct` — raw and smoothed velocity
+- `displacementPct` — price offset from the modal (long-term) estimate
 - Premium / discount signal
-- Oscillation / range context
+- Oscillation / range context (beams + projections)
 - Proposed bot-setting patch for the next cycle
 
 ## Control Surfaces
@@ -42,4 +49,4 @@ This is the shared DEXBot/Claw trend service. It is independent of margin-tradin
 
 ## Operating Rule
 
-Treat the trend signal as configuration input, not as trading logic. The shared service can tune bot settings and trigger recalculation, but it should not own order placement or margin-position policy.
+Treat the trend signal as configuration input, not as trading logic. The shared service can tune bot settings and trigger recalculation, but it should not own order placement or margin-position policy.