dexbot 1.5.3 → 1.6.0

package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md

@@ -144,24 +144,36 @@ FILL_PROCESSING: {
 
 **Residual Dust Cancellation** (post-1.4.12): After a sub-dust fill leaves a residual order on chain (e.g. the quote-side value truncates to 0 on `bitshares-core` `maybe_cull_small_order`), the fill runtime explicitly cancels those residuals via `cancelResidualOrders()` (`dexbot_fill_runtime.ts:74`, `[RESIDUAL]` tag) so a leftover of ≥1 base unit cannot be re-adopted into a grid slot by maintenance.
 
-#### Grid Regeneration Trigger (Available Funds Ratio)
+#### Grid Regeneration Trigger (Available Funds Ratio — bidirectional)
 
-The grid regenerates when accumulated proceeds create a significant funding imbalance. This is detected using the **Available Funds Ratio**:
+The grid regenerates when accumulated proceeds create a significant funding imbalance — in either direction. This is detected using the **Available Funds Ratio** (grow leg) plus an over-allocation leg (shrink leg), all sharing `GRID_REGENERATION_PERCENTAGE` (default: 3%):
 
 ```
-ratio = (availableFunds / allocatedCapital) * 100
-
-IF ratio >= GRID_REGENERATION_PERCENTAGE (default: 3%):
-    → Trigger grid regeneration
+GROW:   ratio = (availableFunds / allocatedCapital) * 100
+        IF ratio >= GRID_REGENERATION_PERCENTAGE (default: 3%):
+            → Trigger grid regeneration (deploy proceeds)
+
+SHRINK: overAlloc = (gridTracked - allocatedCapital) / allocatedCapital * 100
+        (`gridTracked` = funds.total.grid: ACTIVE + PARTIAL + VIRTUAL planned size)
+        IF overAlloc >= threshold:
+            → Trigger grid regeneration (resize affected orders down)
 ```
 
-**How It Works**:
+Deliberately no per-side chain-total-drop leg: a normal fill moves value across sides (pays one asset, receives the other — see `recordFillBalances`), so one side's total routinely drops ≥3% on ordinary fills, and the fill pipeline already re-sizes from the post-fill budget.
+
+**How It Works (grow)**:
 1. Fill occurs → proceeds added to `chainFree`
 2. `calculateAvailableFundsValue()` computes true spending power (chainFree minus reservations)
 3. Grid divergence check compares this ratio against allocated capital in active orders
 4. If ratio exceeds 3%, the grid has accumulated enough proceeds to warrant redeployment
 5. Grid regeneration recalculates all order sizes and applies new placements
 
+**How It Works (shrink)**:
+1. External removal (manual transfer/withdrawal) → `chainTotal` drops → `funds.allocated` (chainTotal × `botFunds`%) drops while the grid-tracked size stays put
+2. Divergence check flags the side when grid-tracked size exceeds the allocation by ≥ 3% (slow bleeds accumulate across ticks: the grid stays fixed while the allocation sinks)
+3. The same regeneration path runs: `_recalculateGridOrderSizesFromBlockchain` recomputes geometric ideals on the smaller budget and queues `UPDATE` actions shrinking affected on-chain orders (`delta < 0` releases the difference back to free balance on chain). Fork-kept shelf orders (live non-slot-N ids below the rail) are skipped by the per-slot loop — their manual sizes survive the resize while still counting in the budget denominator.
+4. Under-deployed grids (grid-tracked size still within the shrunken allocation) correctly do NOT trigger — their orders remain fully funded
+
 #### Recovery Retry System
 
 Recovery uses a count+time-based retry system with periodic reset, so a single failed recovery attempt never locks out future retries.
@@ -518,7 +530,7 @@ BitShares charges fees for `limit_order_create` and `limit_order_cancel`.
 
 -   **Reservation** (`BTS_RESERVATION_MULTIPLIER` in `constants.ts::FEE_PARAMETERS`):
     $$Reserve = N_{active} \times BTS\_RESERVATION\_MULTIPLIER$$
-    *(Default: 5× per order — covers create, rotate (cancel+place), update, and cancel over the order's lifetime)*
+    *(Default: 5× per order — covers create, rotate (cancel+place), update, and cancel over the order's lifetime. $N_{active}$ counts window orders plus the `reserveOrders` edge ladder — reserves rest live on-chain and pay fees like window orders)*
 
 -   **Settlement (`deductBtsFees`):**
     1.  Check `Funds.btsFeesOwed`.
@@ -794,4 +806,4 @@ To prevent "Time-of-Check to Time-of-Use" errors:
 **TOCTOU protection in `processFillAccounting`.** `_buildBtsDeferredRefundAdjustment` reads `btsFeeState` from `mgr.orders` while the order lock is held — the lock is acquired before accounting runs, and the POST-RESET and BOOTSTRAP tracked-fill accounting paths follow the same locking pattern.
 
 ---
-*Technical Reference for DEXBot2 v1.5.3 release*
+*Technical Reference for DEXBot2 v1.6.0 release*

package/docs/GRID_RECALCULATION.md

@@ -26,7 +26,7 @@ rebuild around that snapshot.
 | **AMA Center Move** | Market adapter | Current AMA center moves past the configured delta threshold | Write `dynamicgrid.json`, then write a trigger file | Full grid resync around the new accepted AMA center |
 | **AMA Slope Range Move** | Market adapter | Range-scaling bot's accepted AMA-slope baseline moves past threshold | Write range-scaling fields to `dynamicgrid.json`, then write a trigger file | Full grid resync with updated asymmetric range/offset data |
 | **RMS Structural Divergence** | Bot runtime maintenance | Current grid shape diverges from persisted/on-chain grid by RMS threshold | Refresh `gridCenterPrice` from latest `amaCenterPrice`, then run full grid resync | Full grid resync from latest market-adapter snapshot |
-| **Available-Funds Resize** | Bot runtime maintenance | Filled-order proceeds exceed `GRID_REGENERATION_PERCENTAGE` | Recalculate affected side/order sizes through maintenance logic | Order-size/grid maintenance update, not an AMA recenter trigger |
+| **Available-Funds Resize** | Bot runtime maintenance | Filled-order proceeds exceed `GRID_REGENERATION_PERCENTAGE` (grow), or grid-tracked size exceeds allocation by that threshold after fund removal (shrink) | Recalculate affected side/order sizes through maintenance logic | Order-size/grid maintenance update, not an AMA recenter trigger |
 
 Each source is evaluated independently. Market-adapter full-resync requests are
 serialized through `profiles/recalculate.<botKey>.trigger`. Runtime maintenance
@@ -433,11 +433,9 @@ GRID_LIMITS: {
 ```
 
 **Parameters:**
-- `GRID_REGENERATION_PERCENTAGE`: Percentage of allocated capital that can accumulate as free funds before triggering a size recalculation
-  - Default: `3%`
-  - Example: 20 orders × 100 BTS = 2000 BTS grid
-    - Triggers when availableFunds ≥ 60 BTS (3% of 2000)
-    - Allows ~3 fill-proceeds to accumulate before resize
+- `GRID_REGENERATION_PERCENTAGE`: Bidirectional threshold for size recalculation (default: `3%`)
+  - Grow: free funds accumulate to ≥3% of allocated capital (e.g. availableFunds ≥ 60 BTS on a 2000 BTS grid)
+  - Shrink: grid-tracked size (ACTIVE + PARTIAL + VIRTUAL) exceeds allocation by ≥3% (external fund removal resizes affected orders down; per-side chain totals are not used — fills move value across sides)
 
 ### How It Works
 
@@ -448,6 +446,7 @@ GRID_LIMITS: {
    - Recalculates order sizes to incorporate freed capital
    - Maintains asymmetric fills (BUY fills don't trigger SELL resize)
 4. After the resize, available funds are re-allocated into active orders
+5. Mirror (shrink): when `(gridTracked - allocated) / allocated × 100 >= threshold` (external fund removal), the same path resizes affected orders down
 
 ### When to Adjust
 

package/docs/GRID_RECONCILE.md

@@ -26,7 +26,7 @@ Phase 1 does all reasoning in memory under `_gridLock` (fast); Phases 2 and 3 ex
 
 Phase 2 and 3 both respect the `dryRun` flag: when true, no on-chain mutations are attempted — plans are logged but not executed.
 
-`targetCount` (per side, `targetSell`/`targetBuy`) is sourced from bot config and determines how many active orders each side should maintain. The internal `planOnly` flag controls whether `_reconcileStartupSide` records plans for Phase 2 or executes inline — Phase 1 always calls with `planOnly=true`.
+`targetCount` (per side, `targetSell`/`targetBuy`) is sourced from bot config (`activeOrders` window plus `reserveOrders` edge ladder) and determines how many live orders each side should maintain. The internal `planOnly` flag controls whether `_reconcileStartupSide` records plans for Phase 2 or executes inline — Phase 1 always calls with `planOnly=true`.
 
 ```
                     Grid generated
@@ -93,7 +93,8 @@ Phase 2 and 3 both respect the `dryRun` flag: when true, no on-chain mutations a
    - Match sorted unmatched chain orders to virtual slots → `plannedUpdates`
    - Detect grid-edge lock and plan a largest-order cancel
    - Plan creates for remaining slots
-   - Plan excess cancellations (guarded by `matchedOnGrid > 0`)
+   - Plan excess cancellations (guarded by `matchedOnGrid > 0`): orphans first, then **matched surplus** (`chainCount - targetCount`, reserve edge slots last) — the matched-excess selection is shared by the planOnly and execute branches so planning can never drift from execution; planOnly omits `releaseUntrackedFunds` for matched slots (their funds are tracked on the grid slot)
+   - Fork-kept **shelf orders** (live non-slot-N ids below the rail, e.g. `deep-*`) are never cancel candidates or reserve members — see [Shelf Orders](#shelf-orders-fork-kept-manual-orders)
    - **Vacated-rail refill**: each PROCEEDING update whose vacated price exactly matches (`priceSlotEqual`) an empty, sized, in-rail slot of the same side queues a refill CREATE in the same plan (`source startupVacatedRailRefill`) — skipped updates, ghost prices (lattice moved), in-band slots, and already-desired slots never refill; refill targets require VIRTUAL state with no `orderId`
 
 Returns `{ plannedCreates, plannedUpdates, plannedCancels, chainSellCount, chainBuyCount }`.
@@ -176,6 +177,14 @@ Up to 3 batch attempts. Each failure triggers a recovery sync + plan refresh. If
 
 **`grid_reconcile.ts:211-244`** — Reconcile's role in the defense-in-depth: during Phase 1, any ACTIVE/PARTIAL order whose `orderId` is not found on-chain is reset to VIRTUAL with `skipAccounting`. The freshly-assigned deferral protects in-flight broadcasts, and the ghost heuristic lets known fills pass. See [`developer_guide.md`](developer_guide.md#phantom-orders-prevention-defense-in-depth) for the full 3-layer defense.
 
+### Shelf Orders (Fork-Kept Manual Orders)
+
+Live on-chain orders with non-slot-N ids below the rail (e.g. `deep-*` manuals kept across a fork) are **shelf orders**: they sit outside the grid contract and must survive every startup path untouched. Three gates enforce this (all no-ops on grids that only mint slot-N ids):
+
+- **Reserve classification/placement** (`order.ts`, `grid_reconcile_internal.ts`, `manager.ts`): `reserveEdgeIdSet`, the Tier-2 live-anchor scan, `_pickEdgeReserveSlots`, and `pickEdgeReserves` all gate to `parseSlotIndex(id) !== null`, so a shelf can never count as the reserve edge (which would mask a real reserve deficit) nor be activated as a reserve it would never be counted as. The live-reserve count additionally excludes window members via `liveWindowIdSet`, so an edge-reaching window cannot masquerade as dedicated reserves.
+- **Startup excess cancels** (`grid_reconcile_internal.ts`): the matched-excess selection filters to slot-N ids in both planOnly and execute branches — the cheapest-first sort would otherwise wipe the shelf on the next boot.
+- **Geometric size recalc** (`grid.ts`): `_recalculateGridOrderSizesFromBlockchain` skips non-slot-N slots in the per-slot loop, so divergence-triggered resizing never overwrites manual shelf sizes on-chain (the shelf stays in the budget denominator, so allocation math is unchanged).
+
 ### COW Interaction
 
 Reconcile Phase 1 runs under `_gridLock` with no side effects on the frozen master Map. The working grid is not involved — reconcile is a startup operation that runs before the COW pipeline is active. See [`COPY_ON_WRITE_MASTER_PLAN.md`](COPY_ON_WRITE_MASTER_PLAN.md#safety-guardrails) and [`COW_INVARIANTS.md`](COW_INVARIANTS.md#reconcile-grid_reconcilemd) for COW rules.
@@ -242,6 +251,7 @@ Commit `e64db685` replaced 6 single-value boolean state fields with refcounts/st
 | `tests/test_race_condition_fixes_batch1.ts` | ABBA deadlock (RC-1B) |
 | `tests/test_async_lock_force_release.ts` | Nested multi-lock re-entrancy |
 | `tests/test_targeted_drift_reconcile.ts` | Active-order shortfall triggers sync |
+| `tests/test_reserve_orders.ts` | Reserve startup coverage: fully-placed matched-surplus cancels, orphan+matched ordering, at-target silence, plan/execute parity, shelf-order survival, reserve-deficit trigger (`buy reserves 0/2`) with filled/disabled/empty-budget silence, window-exclusion counting |
 | `tests/repro_phantom_orders.ts` | Phantom order prevention |
 
 ---

package/docs/MPA_CREDIT_USAGE.md

@@ -139,11 +139,11 @@ Set `creditOnly: true` on a bot entry to run only the credit runtime — no grid
   "preferredAccount": "my-account", "debtPolicy": { "lending": [...] } }
 ```
 
-No trading fields (`assetA`, `assetB`, `startPrice`, `incrementPercent`, `activeOrders`, `botFunds`) are needed.
+No trading fields (`assetA`, `assetB`, `startPrice`, `incrementPercent`, `activeOrders`, `reserveOrders`, `botFunds`) are needed.
 
 ```bash
 dexbot start credit          # Background daemon — runs only the credit worker
-dexbot start <bot-name>      # Start a named bot directly
+dexbot start <bot>            # Start a named bot directly
 ```
 
 ### Collateral Increase Thresholds

package/docs/README.md

@@ -2,7 +2,7 @@
 
 This directory contains the comprehensive technical documentation for the DEXBot2 trading bot. It is designed to guide developers from high-level architecture down to the nuances of fund accounting and state management.
 
-**Version context:** v1.5.3 (released).
+**Version context:** v1.6.0 (released).
 
 ---
 
@@ -100,7 +100,6 @@ This directory contains the comprehensive technical documentation for the DEXBot
 - **Module Responsibilities**: Detailed breakdown of the **Manager**, **Accountant**, **Strategy**, **Grid**, **FillRuntime**, and **MaintenanceRuntime** modules.
 - **Copy-on-Write Pattern**: Safe concurrent rebalancing with isolated working grids (see [COPY_ON_WRITE_MASTER_PLAN.md](COPY_ON_WRITE_MASTER_PLAN.md))
 - **Fill Processing Pipeline**: Fixed-cap batch fill processing (1-4 fills per broadcast; documented Feb 7 29-fill scenario: ~24s)
-- **Fund-Driven Boundary Sync**: Automatic grid alignment with inventory distribution
 - **Spread Correction**: Conservative, fund-aware maintenance of constant spread width
 - **Periodic Market Price Refresh**: Background 4-hour price updates
 - **Pipeline Safety & Diagnostics**: 5-minute timeout safeguard and health monitoring
@@ -130,7 +129,7 @@ This directory contains the comprehensive technical documentation for the DEXBot
 - **Signal Concepts**: Dynamic weights, regime detection, derivative signals, and market adapter integration
 - **Debt Policy**: Native MPA and credit offer configuration and runtime rules
 - **Common Tasks**: Practical "how-to" guides for adding features or fixing bugs.
-- **Glossary**: Definitions of project-specific terminology (e.g., "Virtual Orders", "Rotation", "Pipeline Safety", "Fund-Driven Boundary", "WorkingGrid", "COW Commit", "Dynamic Weight", "Regime Detection").
+- **Glossary**: Definitions of project-specific terminology (e.g., "Virtual Orders", "Rotation", "Pipeline Safety", "WorkingGrid", "COW Commit", "Dynamic Weight", "Regime Detection").
 
 ### 🔄 [Workflow](WORKFLOW.md)
 *How we build and release.*
@@ -144,12 +143,12 @@ This directory contains the comprehensive technical documentation for the DEXBot
 
 ### 🧭 [Evolution Report](EVOLUTION.md)
 *Project timeline and major architecture phases.*
-- **Coverage**: Historical milestones from the initial December 2025 bootstrap through the v1.5.3 stable release (grid persistence safety, dust pipeline fix, net inventory lots); credit/debt runtime and maintenance hardening are covered under Phase 5 (Mar–Jun 2026)
-- **Focus**: Architecture evolution, release history, test growth, and documentation changes
+- **Coverage**: Historical milestones from bootstrap through the current stable release; per-release detail lives in [CHANGELOG.md](../CHANGELOG.md)
+- **Focus**: Architecture evolution, release history, and test growth
 
 ### 🗒️ [Changelog](../CHANGELOG.md)
 *Release notes and documentation history.*
-- **Scope**: Versioned notes for patch releases and the current unreleased documentation refresh
+- **Scope**: Versioned notes per release
 
 ### 🧩 [Copy-on-Write Master Plan](COPY_ON_WRITE_MASTER_PLAN.md)
 *COW design, phases, and state machine details.*

package/docs/architecture.md

@@ -454,64 +454,6 @@ roughly 3 seconds per broadcast; see
 
 ---
 
-## Fund-Driven Boundary Sync
-
-The grid boundary (which separates BUY, SPREAD, and SELL zones) automatically aligns with the bot's actual inventory distribution.
-
-### Why This Matters
-
-By default, the grid is centered around `startPrice`. However, if the bot has asymmetric capital (e.g., more assetB than assetA), the boundary should shift to favor the "heavier" side.
-
-**Example**: If 70% of capital is in assetB (buying power), the BUY zone should be expanded.
-
-### Boundary Calculation
-
-**Location**: `modules/dexbot_class.ts::_performPeriodicGridChecks()` → Boundary Sync step
-
-**Algorithm**:
-```javascript
-// 1. Scan all grid slots and their current assignments
-const buyTotal = sum(orders with type === BUY);
-const sellTotal = sum(orders with type === SELL);
-const totalAllocated = buyTotal + sellTotal;
-
-// 2. Calculate target allocation based on available funds
-const buyAvailable = manager.funds.available.buy;
-const sellAvailable = manager.funds.available.sell;
-const totalAvailable = buyAvailable + sellAvailable;
-
-// 3. Determine ideal boundary position
-const buyTargetRatio = buyAvailable / totalAvailable;  // e.g., 0.7
-const slots = grid.length;
-const targetBuySlots = Math.round(slots * buyTargetRatio * 0.5);  // Apply centering factor
-
-// 4. Adjust boundary to new position
-newBoundaryIdx = calculateNewBoundary(targetBuySlots);
-
-// 5. Re-assign slot roles (BUY/SPREAD/SELL) based on new boundary
-reassignSlotRoles(newBoundaryIdx);
-```
-
-### Three Rotation Cases
-
-Once the new boundary is determined, existing on-chain orders are matched to desired slots:
-
-| Case | Condition | Action |
-|------|-----------|--------|
-| **MATCH** | Existing order price matches desired slot | Update size if needed |
-| **ACTIVATE** | Desired slot is empty | Place new order at this price |
-| **DEACTIVATE** | Existing order exceeds target count | Cancel excess orders |
-
-**Target Count**: `activeOrders` from config, applied uniformly to both sides.
-
-### Impact
-
-- **Automatic Capital Repositioning**: Grid follows capital distribution without manual intervention
-- **Fund Respect**: Never exceeds available funds when activating slots
-- **Smooth Transitions**: Rotations happen gradually, not all at once
-
----
-
 ## Spread Correction (Fund-Aware Approach)
 
 Simplified spread maintenance that keeps the gap consistent and fund-driven, avoiding complex split/merge mechanics.

package/docs/developer_guide.md

@@ -143,7 +143,8 @@ A **phantom order** is an order in ACTIVE/PARTIAL state WITHOUT a valid `orderId
 | **Crawl Candidate** | Furthest active order eligible for rotation |
 | **Shortage** | Empty slot in the active window that needs an order |
 | **Surplus** | Order outside the active window that can be rotated |
-| **Hard Surplus** | Order beyond the configured `activeOrders` count |
+| **Hard Surplus** | Order beyond the configured window + reserve (`activeOrders` + `reserveOrders`) count |
+| **Reserve** | Edge-pinned live order outside the active window (buys at grid floor, sells at grid ceiling); never moves the boundary |
 | **Dust** | Partial order < 5% of ideal size |
 | **Dust Cancel** | Immediate on-chain cancel of dust partials on detection (no delay, no timer). Slot freed for a fresh counter-order. |
 

package/docs/docker.md

@@ -35,7 +35,7 @@ dexbot start
 To start only one bot:
 
 ```bash
-dexbot start <bot-name>
+dexbot start <bot>
 ```
 
 ### Headless (non-interactive) startup

package/market_adapter/README.md

@@ -849,6 +849,10 @@ suppress writes via `unresolved_candle_gaps` until repaired on a future cycle.
 The adapter prunes old candles to the required AMA window and acts only on
 closed 1h candles.
 
+#### Shared Chunk Cache and Fetch Robustness
+
+Pool, book, and feed candle fetches share one cache entry point (`runCachedWindows` in `market_adapter/inputs/window_cache.ts`): sibling chunk files load once, only missing buckets plus a bounded 48h tail refresh are queried, and chunk metas record the ranges actually queried (`meta.queriedRanges`). A missing range is pruned only when recorded query coverage genuinely covers it — the absence of local buckets alone never certifies history as empty. Partial windows merge into the run output but are never persisted, and orphan chunks are deleted after complete runs only. Every range fetch runs through `fetchRangeWithRetry` (per-range attempts + linear backoff + abort-signal timeout; the LP path keeps a 4-attempt budget), one-shot Kibana queries retry transient errors (3 attempts), paged fetchers cap at `kibanaMaxPages` (500), and bidirectional fetches tolerate a one-direction failure.
+
 #### AMA Warmup Window — Why Candle Length Matters
 
 The AMA is a recursive (infinite impulse response) filter. On cold start, the adapter uses an initial warmup phase: it calculates an **SMA (Simple Moving Average)** over the first `erPeriod` candles to establish a stable seed price, while simultaneously building the price history needed to calculate the first valid Efficiency Ratio (ER).

package/modules/README.md

@@ -159,7 +159,7 @@ External consumers — other parts of DEXBot2 interact with modules through thes
 
 - **Zero runtime dependencies** — no npm trading/blockchain libraries; the native client, crypto, and serialization are all in `bitshares-native/`. This eliminates supply-chain risk and keeps the bot fully self-contained.
 - **Copy-on-write** — `order/working_grid.ts` provides isolated COW mutations; master grid is immutable during rebalance. The grid is never modified in-place; a working copy is built, mutated, and committed atomically only after blockchain operations succeed.
-- **Fund-driven boundary sync** — the grid rebalances based on available funds, not arbitrary triggers; no forced allocations. When a fill arrives, the system calculates what it can actually afford and adjusts the grid around that.
+- **Fund-driven sizing, fill-driven boundary** — available funds set order sizing and budget allocation, not the boundary position; no forced allocations. The boundary moves only through boundary crawl on fills or spread promotion onto orders placed in the same atomic batch.
 - **Replay-safe accounting** — fill processing in `dexbot_fill_runtime.ts` uses `processed_fill_store.ts` to prevent double-counting. If the bot restarts mid-fill, it can safely replay without creating duplicate orders.
 - **Daemon-backed signing** — the credential daemon holds decrypted keys; modules never handle raw private keys. If the main bot crashes, keys stay encrypted on disk — only the small daemon process sees them.
 - **Fixed-cap batch processing** — fill batches are capped (default 4) to keep blockchain broadcasts predictable. Even if 20 fills arrive at once, they're processed in small chunks to avoid overwhelming the chain.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dexbot",
-  "version": "1.5.3",
+  "version": "1.6.0",
   "description": "The first open source trading bot with zero runtime dependencies and a fully adaptive market making strategy.",
   "main": "dist/modules/dexbot_class.js",
   "exports": {

package/scripts/README.md

@@ -253,7 +253,7 @@ npm run verify:browser-bundle
 
 ### Create PM2 Bot Symlinks
 **File:** `create-bot-symlinks.sh`
-**Purpose:** Create `profiles/<bot-name>.config.cjs` symlinks pointing to `profiles/ecosystem.config.cjs` so you can run `pm2 start <bot-name>` directly.
+**Purpose:** Create `profiles/<bot>.config.cjs` symlinks pointing to `profiles/ecosystem.config.cjs` so you can run `pm2 start <bot>` directly.
 ```bash
 bash scripts/create-bot-symlinks.sh
 ```
@@ -387,14 +387,16 @@ The following scripts allow you to call `dexbot` commands directly from the `scr
 
 ### TradingView (`dexbot tv`)
 **File:** `tv.ts`
-**Purpose:** One-step TradingView-style 1h chart for a bot (with AMA overlay), pool, or pair. Fetches candles in monthly Kibana chunks, then renders via `analysis/tradingview/`.
-**Output:** `analysis/charts/tv_<bot|pool_<id>|<a>_<b>>_1h_<N>m.html`
+**Purpose:** One-step TradingView-style 1h chart for a bot (with AMA + order overlay), pool, or pair. Fetches candles in monthly Kibana chunks (pool-first with order-book fallback; `--feed` for MPA price-feed history), then renders via `analysis/tradingview/`. Bot charts pick up the order overlay from `profiles/orders/<botKey>.json` automatically.
+**Output:** `analysis/charts/tv_<bot|pool_<id>|<a>_<b>>_1h_<N>m.html` (`_feed` suffix for feed charts)
 ```bash
 # Bot chart (default: 3 months)
 dexbot tv <bot>
 # Pool or pair, custom window
 dexbot tv 133 --month 6
 dexbot tv TOKENA/TOKENB --month 1 --chart analysis/charts/custom.html
+# MPA price-feed history instead of market candles (opt-in)
+dexbot tv BTS/HONEST.USD --feed --month 1
 ```
 
 ### LP Chart

package/tests/README.md

@@ -48,7 +48,7 @@ Key validation, balance queries, account selection.
 
 ### Market Data & Pricing
 Price derivation, orderbook inspection, tolerance checks.
-*Examples:* `test_market_price.ts`, `test_price_derive.ts`, `test_price_tolerance.ts`, `test_any_pair.ts`, `test_kibana_candles.ts`
+*Examples:* `test_market_price.ts`, `test_price_derive.ts`, `test_price_tolerance.ts`, `test_any_pair.ts`, `test_kibana_candles.ts`, `test_fetch_book_data.ts`, `test_window_cache.ts`
 
 ### Market Adapter
 AMA signal processing, price offset, bound clamping, signal gates.
@@ -60,7 +60,7 @@ Order lifecycle, fill processing, trade history, batch execution.
 
 ### Strategy & Grid Logic
 Grid generation, sizing, rotation, divergence detection, reconciliation.
-*Examples:* `test_order_grid.ts`, `test_strategy_logic.ts`, `test_grid_reconcile.ts`, `test_working_grid.ts`, `test_rotation_order_sizing.ts`, `test_strategy_edge_cases.ts`
+*Examples:* `test_order_grid.ts`, `test_strategy_logic.ts`, `test_grid_reconcile.ts`, `test_working_grid.ts`, `test_rotation_order_sizing.ts`, `test_strategy_edge_cases.ts`, `test_reserve_orders.ts`
 
 ### Copy-on-Write (COW) Rebalancing
 Concurrent-safe rebalancing with isolated working grids — dedicated test suite.