# Quantradin — learn agentic trading, on an engine that doesn't lie

> Quantradin teaches agentic trading with an honest backtesting engine: real
> fills, no look-ahead, half the history held back, and a verdict that advises
> you instead of deciding for you.

Quantradin is a strategy backtesting and paper-trading platform for options and
equities on US markets. Its one promise is an HONEST backtest: real fills (buy at
the ask, sell at the bid, never the mid), no look-ahead, and a verdict that
ADVISES you rather than deciding for you. If you are an AI agent driving
Quantradin from a terminal (Claude Code / Codex) via the MCP/CLI tools, read this
first.

## Key pages

The public content, for citing and for onward reading (llmstxt.org shape):

- [Home](https://quantradin.com/): what the platform is and the free guest lab
- [Famous strategies, tested honestly](https://quantradin.com/strategies): seven
  strategies people trade by name — buy the dip, the golden cross, RSI oversold,
  new highs, the gap fade, a covered call, a bull call spread — each one a page
  at /strategies/<slug> that IS a working lab; losers shown as prominently as
  winners, and no number promised before your own run
- [Indicator library](https://quantradin.com/learn/indicators): every indicator
  the engine computes, in plain words — each has its own page at
  /learn/indicators/<slug> (e.g. /learn/indicators/rsi) describing what it
  measures and how it is actually calculated, faithful to the engine's real maths
- [Learn](https://quantradin.com/learn): the lesson path — honest backtesting,
  shares and options mechanics, your first bot
- [MCP door](https://agent.quantradin.com/mcp): drive Quantradin from an agent — the tools described in
  this document
- [This document](https://quantradin.com/llms.txt): served on both the web host
  and the API host; always the current route table

## THE FORMAT — send strategies in EXACTLY this shape
Hand Quantradin a strategy as ONE JSON object in the shape below. If you are a coding
agent (Claude Code / Codex) porting a strategy for someone, emit exactly this —
every field, in this shape — and we can build, validate, and deploy it right away.

Labeled template (every field; the → note says what each one is):
```
{
  "name":        "<label>",                 → any string
  "asset_class": "equity",                  → equity | option | credit | combo | covered
  "universe":    ["AAPL", "MSFT"],          → EXPLICIT ticker list (never a screen);
                                              or "all" / omit it → we fill the FULL
                                              catalog and record it in defaults_applied
  "timeframe":   "1 day",                   → "1 day" | "1Min" | "5Min" | "15Min" | "30Min" | "1Hour" | "4Hour"
  "backtest":    {"start": "2024-02-12", "end": "2026-05-20"},   → inside the data window
  "indicators":  [{"id": "rsi14", "type": "rsi", "params": {"length": 14}}],
                                            → optional per-indicator "timeframe":
                                              a LARGER bar than the spec's, read
                                              only after it CLOSES (see MULTI-
                                              TIMEFRAME below)
  "entry": {
    "side": "call",                         → call = long/bullish · put = short/bearish
    "when": {"all": [{"lt": ["rsi14", 30]}]}   → rule tree over indicator/feature ids
  },

  ── OPERANDS you can put on EITHER side of a comparison ──
  "rsi14"                     → a feature / declared indicator id
  30                          → a plain number
  {"holds_for": [{"gt": ["rsi14", 50]}, 3]} → the inner RULE was true on THIS
                              bar and each of the previous N-1 bars (confirmation;
                              look-back only — not enough history is False);
                              N is 1..50, and NESTED holds_for / seq windows may
                              multiply to at most 2500 checks per bar
  {"seq": [ruleA, ruleB, 5]} → SEQUENCE: ruleB is true NOW and ruleA was true on
                              at least one of the previous N bars (setup THEN
                              trigger — the retest entry). The window is PRIOR
                              bars only (same-bar A+B is a plain all); N is 1..50
{"lag": ["close", 1]}       → that feature N BARS ago (look-back only; a bar's
                                length follows the spec's timeframe — 60 bars on
                                "1Min" is 60 MINUTES)
  {"lag_sessions": ["close", 20]} → that feature N TRADING SESSIONS ago on EVERY
                                timeframe (20 daily bars, or 20 sessions of
                                minute bars — say DAYS with this, never with lag)
  {"mul": ["hi252", 0.92]}    → ARITHMETIC: feature x number, or feature x feature
  {"sub": ["ret20", "ret3"]}  → ARITHMETIC: difference of two operands
  {"xrank": "chg1035"}        → cross-sectional percentile (0..1) across the universe
  {"bench": "SPY", "ret": 20} → any symbol's N-bar return, broadcast to every name
  {"pair_z": {"a": "KO", "b": "PEP", "window": 60}} → the pair's ratio (or
                              "mode": "spread") z-scored over its own trailing
                              60 BARS — unit is STANDARD DEVIATIONS (write -2,
                              never a percent); both legs load automatically
      → so "within 8% of the 52-week high" IS expressible, exactly:
        {"gte": ["close", {"mul": ["hi252", 0.92]}]}
      → and "beats SPY by 5pts over 20 days":
        {"gte": [{"sub": ["ret20", {"bench": "SPY", "ret": 20}]}, 0.05]}
  "exit":  {"rule": "fixed", "hold_days": 5},   → fixed | lo3 | lo5 | peak8
      → OPTION specs may add "roll": {"at_dte": 7, "max_rolls": 2} — roll the held
        contract forward at 7 days-to-expiry (see OPTIONS ROLLING in the map below)

  ── OPTIONAL exit rule TREE (#13) — the SAME grammar as entry.when ──
  "exit": {"rule": "fixed", "hold_days": 10, "when": {"gt": ["rsi14", 70]}}
        → YOUR OWN boolean exit tree, evaluated at each held bar's CLOSE: the
          position exits at its FIRST true bar or at the base rule's bar,
          whichever comes EARLIER (the base rule is the cap). Standalone
          {"exit": {"when": ...}} is legal — the default cap (fixed, 10
          sessions) applies behind it and is disclosed in defaults_applied.
          Any entry operand works here (indicators, bench, xrank, lag,
          lag_sessions, holds_for) — so "exit on the opposite signal" is just
          your entry tree inverted. Equity + single-leg option specs; graded
          AND honoured on the live desk (telemetry when_exits).
  "exit": {"rule": "fixed", "hold_days": 10, "reverse": true}
        → STOP-AND-REVERSE (#14, DAILY EQUITY only): the exit bar doubles as
          the OPPOSITE direction's entry signal — the mirror trade enters at
          the NEXT bar's open and is graded like any other trade (marked
          "reversal": true). A mirror never chains; a kill_switch flatten
          never reverses. LIVE walk: not wired yet — a deployed bot counts
          skipped_reverse_unwired instead of silently ignoring it.
  "kill_switch": {"when": {"lt": ["spy_ret", -0.02]}}
        → YOUR market flatten condition (#15): while true at a walked bar the
          bot FLATTENS (close_reason 'kill_switch') and takes no new entries
          (telemetry entries_blocked_reason 'kill_switch' + skipped_kill_switch);
          it resumes on its own when the condition clears. Your choice,
          honoured — never the engine shutting you down.
  ── OPTIONAL resting ENTRY order (EQUITY-only; inside the entry block) ──
  "entry": {"order": {"type": "limit", "offset_pct": -2.0, "good_for_bars": 5}}
        → the PULLBACK entry: rests at signal_close × (1 + offset_pct/100) for N
          bars, then EXPIRES (counted in skips.entry_expired — never silent)
  "entry": {"order": {"type": "stop_buy", "offset_pct": 2.0, "good_for_bars": 5}}
        → the BREAKOUT entry (wave-C #5): the exact mirror of the limit above.
          Rests ABOVE the market at signal_close × (1 + offset_pct/100) and fills
          when price breaks UP through it. A SHORT spec mirrors: a sell-stop
          BELOW the market, i.e. a NEGATIVE offset_pct. THE SIGN IS CHECKED —
          a long stop_buy with a negative offset is a limit order wearing the
          wrong name (it would fill on the very next bar), so it is refused in
          plain words that name {"type": "limit"} as the thing you meant.
  "entry": {"order": {"type": "trailing_stop_buy", "trail_pct": 3.0, "good_for_bars": 5}}
        → the DIP-CATCHER: tracks the running LOW after the signal and arms a buy
          at low × (1 + trail_pct/100); a SHORT spec mirrors both (sell-limit
          above / trailing stop-sell off the running high)
        → HONEST DAILY FILLS: a limit fills only when a bar trades STRICTLY
          through the level (a touch is not a fill), at the level — or at the
          OPEN when the bar opens through it. A stop-buy's arm comes from bars
          BEFORE the trigger bar (a bar's own low never arms its own trigger)
          and an open above the arm fills at the real, higher OPEN.
        → the exit's hold anchors at the FILL bar; equity-only (an option entry
          is priced at the chain at fill time — a resting option limit is a
          different product and is refused in plain words)
        → good_for_bars IS the order's TIME IN FORCE, expressed in the bars we
          actually have. IOC / FOK are refused BY NAME (see the four scoped
          answers below).

  ── OPTIONAL live-desk overlays (echoed back, NEVER graded) ──
  "stop_loss":   {"kind": "stop_loss",   "stop_pct":   0.30},   → your own risk cap
  "take_profit": {"kind": "take_profit", "target_pct": 0.50},   → a hard cap (never graded)
  "profit_lock": {"kind": "ratchet", "arm_pct": 0.50, "step_pct": 0.10, "rise_pct": 0.05},

  ── OPTIONAL intraday (any intraday timeframe; equities AND options) ──
  "entry_start": "10:00",  "entry_end": "10:30",     → ET wall-clock entry window
  "entry": {"once_per_day": true},                   → at most one trade per symbol per day
  "entry": {"max_entries_per_session": 2},           → at most N trades per symbol per
                                              session (once_per_day is exactly N=1;
                                              intraday only — a daily spec already
                                              fires once per session; live refusals
                                              counted as skipped_max_entries_session)
  "exit": {"rule": "fixed", "max_minutes": 30, "flatten_at": "15:55", "eod_flatten": true}
        → max_minutes = hard time-stop · flatten_at = close at that ET time · eod_flatten = never overnight
        → NOTE: `hold_days` counts trading SESSIONS on EVERY timeframe (converted
          to bars for you: 5Min → 78 bars per session). See the CAPABILITY MAP.

  ── OPTIONAL exit shaping (GRADED — the backtest and the desk apply the identical rule) ──
  "exit": {"stagnation": {"min_gain_pct": 5, "sessions": 10}}
        → STAGNATION exit (equity + single-option): not up at least 5% — a
          PERCENT, the same unit as exit.stop_pct — at any close within 10
          TRADING SESSIONS of the fill → out at session 10's close (an option
          with a quote gap there exits at the next real mark). It only ever
          moves an exit EARLIER; live closes carry close_reason
          "stagnation_exit". Not wired for credit/combo/covered structures.
  "exit": {"scale_out": [{"at_gain_pct": 10, "fraction": 0.5},
                         {"at_gain_pct": 25, "fraction": 0.25}]}
        → SCALE-OUT / partial exits (equity + single-option): the first time the
          position is up 10% sell HALF, the first time it is up 25% sell another
          quarter, and the rest rides to the strategy's own exit. at_gain_pct is
          a PERCENT of the entry price (10 = 10%, the same unit as
          exit.stop_pct); `fraction` is a share of the ORIGINAL size (0.5 = half
          of what you bought, never half of what is LEFT), the rungs must ascend
          by gain, and the fractions must sum to 1.0 or less. It IS graded —
          this is your exit, not an execution preference — so the trade's return
          becomes the quantity-weighted blend of each rung's fill and the
          remainder, and the trade row carries `scale_outs` with each rung's
          date, price and gain. Sold at that bar's realizable price: a share's
          close, an option's REAL BID, never a mid. WHOLE UNITS ONLY, floored: a
          rung too small to move one unit is refused and counted
          (scale_out_rung_too_small), never rounded up into a bigger sale than
          you asked for. Live closes of a fully-scaled position carry
          close_reason "scale_out". Not wired for credit/combo/covered
          structures, which are priced and settled as ONE unit.
          IT COMPOSES WITH exit.roll (#18), and THE LADDER CARRIES: a rung you
          already sold does NOT re-arm on the new contract, the rungs still to
          come measure their gain on the CAMPAIGN — "+30%" is +30% from your
          FIRST fill, the same basis pnl_pct reports, not +30% off whatever the
          replacement cost — and every `fraction` stays a fraction of the
          ORIGINAL first leg's quantity, so a roll never resizes your ladder.
          (The two used to be refused together while that answer was undecided.)
  "exit": {"targets": [{"at_gain_pct": 10, "fraction": 0.5},
                       {"at_gain_pct": 25, "fraction": 0.5}]}
        → MULTI-TARGET OCO LADDER (#19) — "TP1 half, TP2 the rest". This is the
          SAME ladder as exit.scale_out above under the name most traders know
          it by: one implementation, the same units, the same rules. Write
          EITHER name; writing both is refused rather than one of them silently
          winning. OCO against the stop runs BOTH ways — when the stop fires the
          remaining targets are cancelled (rungs after its bar never happen),
          and when the LAST target takes the remainder it closes the position at
          ITS OWN bar and price under close_reason "scale_out", cancelling the
          stop (counted as targets_completed, with the cancelled exit NAMED).
  "exit": {"fill_timing": "next_open"}
        → EQUITY exit fill timing: "close" (the default — disclosed in
          defaults_applied) sells at the exit bar's CLOSE; "next_open" sells at
          the NEXT session's OPEN (daily only). Options exit at real quotes (sell
          at the bid), so the knob is refused there in plain words.
  "exit": {"fill_timing": "moc"}
        → MARKET-ON-CLOSE (wave-C #7): sell at the session's real CLOSING print.
          ON DAILY BARS THAT IS THE SAME PRICE AS "close" — a daily bar IS its
          session — and we say so rather than inventing a difference you would
          then trade on. On an INTRADAY frame the two genuinely differ and that
          is the point: a rule firing at 10:45 exits at 16:00, at the last
          regular-session bar's close. When that session has not finished in the
          data yet there is no closing print, so the desk keeps MARKING and fills
          next walk — never a fill at a price that has not happened.

  ── OPTIONAL campaigns: ONE position built out of SEVERAL legs (GRADED) ──
  SHARES on "1 day" bars only, and refused in plain words everywhere else: an
  added option leg is a different CONTRACT, so there is no single basis to
  blend, and the graded minute loop and the live walk are two loops — a campaign
  wired into one of them would mean one thing in your backtest and another on
  your desk. Refused beside exit.scale_out / exit.targets ("a fraction of WHICH
  size?"), exit.roll, exit.reverse, exit.fill_timing "next_open", and each
  other. THREE RULES SHARED BY ALL OF THEM: at most ONE leg per bar (always the
  next unfilled rung, never out of order); each leg fills at the WORSE of its
  own level and that bar's close; and while a campaign is open on a symbol a
  fresh signal there does NOT start a second one (skipped_campaign_open).
  Every leg is a REAL entry on the desk and passes every gate — market hours,
  buying power, max $/trade, the bot's exposure cap, the sector cap and
  campaign_budget_usd.
  "entry": {"pyramid": {"add_at_gain_pct": 5, "max_adds": 3, "size_frac": 0.5}}
        → PYRAMIDING (#22): while the position is open and UP another 5% (the
          adds sit at 5%, 10%, 15% — measured from the FIRST fill, never from
          the leg before), add half of what you first bought, at most 3 times.
          size_frac is a MULTIPLE OF THE FIRST LEG, never of what you hold now.
          The trade is graded as ONE campaign whose entry_fill is the
          QUANTITY-WEIGHTED AVERAGE of its legs (Σ units·price / Σ units), so
          adding to a winner DILUTES the percent it made — which is true, and is
          why size is not edge. The trade row carries `campaign` with every leg.
  "entry": {"dca": {"steps": [{"drop_pct": 3, "size_mult": 1},
                             {"drop_pct": 7, "size_mult": 2}],
                   "tp_from_avg_pct": 4}}
        → DCA SAFETY ORDERS (#23, the 3Commas shape): after the base entry, each
          step buys more when the price is drop_pct BELOW THE ORIGINAL ENTRY
          (a POSITIVE percent — 3 means 3% below; steps must get deeper), sized
          as a multiple of the base leg. tp_from_avg_pct takes profit that far
          above the BLENDED AVERAGE of every filled leg — never above the first
          fill, which is the whole point of the feature — and fills AT that
          target level, not at the better close that reached it (close_reason
          "campaign_tp"). Omit it and the campaign exits on your own exit rule.
          A step that cannot fill (cash, a cap, the budget) is counted under its
          own reason and never retried out of order.
  "campaign_budget_usd": 5000
        → CAMPAIGN BUDGET (#31): the TOTAL dollars ONE campaign (pyramid, DCA or
          grid) may ever consume across ALL of its legs. LIVE-FILL only — the
          grader never reads it (the scorecard grades per-unit percent, so a
          dollar ceiling cannot move EV, win-rate or the verdict). It answers
          what the other limits cannot: a per-trade cap passes a ladder of
          twelve small safety orders twelve times. DERIVED fresh each pass from
          the campaign's own OPEN legs through the one cost model — NOTHING is
          reserved, so a closed campaign gives its room straight back. The leg
          that would exceed it is refused as skipped_campaign_budget with a note
          naming the budget and the ask. Refused on a spec with no campaign.

  ── OPTIONAL grid: a PRICE LADDER instead of a signal scan (GRADED) ──
  "grid": {"lower": 80, "upper": 120, "levels": 9, "size_per_level": 10,
           "mode": "long_only"}, "exit": {"rule": "grid"}
        → GRID TRADING (#24): nine evenly-spaced rungs (80, 85, 90 … 120). Buy
          10 shares at each rung the price crosses DOWNWARD; sell that same lot
          when the next rung UP is crossed. Requires "asset_class": "equity",
          "timeframe": "1 day", exactly ONE symbol in the universe (a ladder of
          prices belongs to one name — "lower": 80 is a different place in every
          stock) and {"exit": {"rule": "grid"}}, because an exit rule we
          would quietly ignore is refused. "mode" is "long_only" for now: a
          short or neutral grid sells rungs it does not own and its borrow cost
          cannot be priced honestly across a ladder that keeps re-opening.
          `entry.when` is the buy GATE, not the trigger — write an always-true
          rule for a plain grid, or a real condition for "only grid while SPY is
          above its 200-day". Selling is never gated.
          THE INTRABAR RULE, because a bar cannot say whether its high or its
          low came first: at most ONE grid action per bar; a BUY always wins when
          one bar proves both (a round trip inside one bar is the ordering nobody
          can prove, and it is the only one of the two that makes money — the
          deferred sell is counted); when several rungs of a kind are proven the
          WORST one is taken; and every fill prints at its own level even where a
          real resting order would have gapped through to a better price. So a
          real grid trades MORE often than this one, at better prices: the grade
          is a floor, not a forecast.
          AND THE BAG IS GRADED. Every completed round trip is one rung step up,
          so a grade built only from them would report a 100% win rate about a
          strategy whose whole risk is the inventory it is still holding. Any lot
          unsold at the end of the window is therefore closed at the last REAL
          close and graded too (exit_reason "grid_window_end"), and result.grid
          reports the bag beside the verdict.

  ── OPTIONAL live risk throttles (LIVE-only — the grade NEVER reads these) ──
  "entry": {"cooldown_bars": 6}                     → after a losing trade CLOSES, sit out
          N bars of the bot's own bar size before entering again (intraday; the
          daily twin is "cooldown_sessions": N — the rest of the losing session
          plus the next N sessions; set exactly one). Refusals are counted as
          skipped_cooldown, never silent. Exits and marks never pause.
  "entry": {"pause_after_losses": 3}                → N CONSECUTIVE closed losing trades
          pause NEW entries (entries_blocked_reason "consecutive_losses" + one
          desk alert) until you POST .../alphas/{deploy_id}/resume. Open
          positions keep marking AND exiting — entries fail closed, exits never do.
  "entry": {"reentry": {"max": 2, "widen_stop_pct": 10}}
        → RE-ENTRY after a stop-out (#25): once your own stop_loss closes a
          position on a symbol, re-enter it at most `max` more times — within
          the SAME ET session (intraday) or the next `max` sessions (daily).
          Past the budget the refusal is skipped_reentry_exhausted; re-entries
          taken are counted as `reentries`. Optional widen_stop_pct widens the
          stop per re-entry (a 30% stop with 10 → 33%, then 36%). REQUIRES a
          top-level stop_loss (there is nothing to re-enter after without one).
  "risk": {"daily_loss_usd": 500}                    → PER-BOT DAILY LOSS LIMIT (#28,
          the prop-firm rule): once the bot's realized P&L for the ET session
          is down $500, new entries pause until the NEXT session
          (skipped_daily_loss_limit + entries_blocked_reason "daily_loss_limit"
          + one desk alert per session). Derived fresh from the bot's own
          closed positions — nothing reserved. Exits and marks never pause.
  "risk": {"weekly_loss_usd": 2000}                  → PER-BOT WEEKLY LOSS LIMIT
          (wave-C #3): the daily rule over the ET calendar week, MONDAY–SUNDAY.
          Once realized P&L for the week is down $2,000, new entries pause until
          the next week (skipped_weekly_loss_limit + entries_blocked_reason
          "weekly_loss_limit" + one desk alert per week).
  "risk": {"monthly_loss_usd": 5000}                 → the same over the ET
          calendar MONTH (skipped_monthly_loss_limit). Each horizon keeps its OWN
          reason and its own alert — a member whose MONTH is blown while their
          week is fine is looking at a different decision, and one counter for
          both would hide the second breach entirely. Derived fresh from the
          bot's own closed rows; nothing reserved. Exits and marks never pause.
  "risk": {"profit_target_usd": 5000}                → PROFIT TARGET (wave-C #4).
          THE PERIOD IS SINCE DEPLOY — every closed trade this bot has taken.
          Once it is up that much, new entries STOP (skipped_profit_target +
          entries_blocked_reason "profit_target"), the bot is paused with its own
          reason "profit_target" and one desk alert is sent. Unlike a loss limit
          it does NOT reset on its own: "I have made what I came for" is not
          something the calendar undoes, so entries resume when YOU resume the
          bot (POST .../alphas/{deploy_id}/resume). Open positions keep marking
          AND exiting — entries fail closed, exits never do.
  "risk": {"profit_target_pct": 10}                  → the same target as a
          PERCENT of the desk's STARTING cash (the one number that does not move
          as the bot trades, so "up 10%" means the same thing in month one and
          month six). Set at most ONE of the two — writing both is refused rather
          than one silently winning. If the desk's cash book cannot be read that
          walk the PERCENT form stands DOWN and says so
          (profit_target_unmeasurable) instead of pausing your bot on a number we
          never measured; profit_target_usd needs no such read.
  "risk": {"target_volatility_pct": 15}              → PER-BOT VOLATILITY
          TARGETING (wave-C #10): scale this bot's size so its OWN realized
          volatility targets 15% annualized. THE WINDOW, STATED: realized P&L per
          ET session over the last 60 sessions the bot closed a trade in, as a
          fraction of the desk's starting cash, stdev × sqrt(252) × 100. Measured
          on the sessions it actually traded (not a calendar of flat days), which
          OVERSTATES the volatility and therefore errs toward the SMALLER
          position — a modeled estimate, never a measured portfolio vol. Under
          20 sessions of history, or with no measurable dispersion, the scale
          stands down to exactly 1.0 and says so. The scale is CLAMPED to
          0.25×–2.0×: an unclamped ratio turns a quiet fortnight into a 20×
          position, which is how volatility-targeting systems die. PER-BOT ONLY —
          a desk-wide target is refused in plain words, because bots walk
          independently and concurrently, so N bots would each compute "the
          desk's" scale from their own book and each apply it.
  "circuit_breaker": {"benchmark": "SPY", "intraday_drop_pct": 5}
        → MARKET CIRCUIT BREAKER (wave-C #9): pause new entries while SPY is down
          5% from its OWN session open (skipped_circuit_breaker +
          entries_blocked_reason "circuit_breaker"). It resumes on its own when
          the market isn't falling that hard. The benchmark rides the same fetch
          list the bench operands use, so its bars are always loaded, and the
          move is measured causally (the session's first bar's OPEN against the
          benchmark's close at or before your candidate's bar — nothing later).
          FAILS CLOSED: a benchmark we cannot measure refuses entries under its
          OWN reason (skipped_circuit_breaker_unreadable), never silently and
          never as "the market is falling". A HALT DETECTOR is refused by name
          (see below). Exits and marks never pause.
  "risk": {"equity_curve": {"ma_sessions": 10}}      → EQUITY-CURVE TRADING (#30):
          the bot builds its OWN realized-P&L curve by session and, while the
          curve is BELOW its 10-session moving average, holds new entries
          (skipped_equity_curve + entries_blocked_reason "equity_curve").
          Fewer than 10 sessions of history → the filter stands DOWN (not
          enough evidence is not evidence). ADVISORY on the grade: the
          backtest shows the RAW strategy; the curve filter applies live.
  "risk": {"daily_loss_usd": 500, "loss_basis": "equity"}
        → WHICH P&L that limit watches. "realized" is the DEFAULT and counts
          only trades this bot CLOSED in the session; "equity" also counts the
          floating P&L of its OPEN positions — the prop-firm convention, and
          what people actually mean by a daily loss limit (on the default, a
          bot sitting on a huge open loss trips nothing). Opt-in because
          changing the default would change what running bots do. The floating
          part is measured NOW — we store no session-start equity snapshot —
          so a loss carried in from an earlier session counts too: the limit
          can pause entries EARLIER than a session-start basis would, never
          later.
  "risk": {"max_drawdown_pct": 10}                   → STATIC MAX DRAWDOWN:
          once this bot's equity (its desk's starting cash + the bot's realized
          P&L + the floating P&L of its open positions) is 10% below its
          STARTING value, new entries stop (skipped_max_drawdown +
          entries_blocked_reason "max_drawdown").
  "risk": {"trailing_drawdown_pct": 8}               → TRAILING MAX DRAWDOWN:
          the same rule measured from the bot's PEAK equity, and the peak only
          ever rises (skipped_trailing_drawdown). The peak is rebuilt every
          walk from the closed rows per ET session plus one point for right now
          that includes floating P&L — every equity point we can PROVE. We keep
          no mark history, so a peak that existed only as an unrealized mark
          inside a session we have left is not counted: the limit triggers no
          EARLIER than the truth, never off a peak we invented.
          Both are derived fresh each walk (nothing stored, nothing reserved),
          both pause ENTRIES ONLY, and the grader reads neither.
  "profit_lock": {"kind": "ratchet", "arm_at_pct": 0.80}
        → optional LATER arming gate on the ratchet (a fraction, 0.80 = +80%):
          it stays asleep until the PEAK gain reaches it, then the usual floor
          (anchored on arm_pct) protects. At/below arm_pct it is a no-op.

  ── OPTIONAL trading schedule (#32 — entries only; GRADED and lived identically) ──
  "schedule": {"days": ["mon", "tue", "wed", "thu"],
               "pause_from": "2026-09-01", "pause_to": "2026-09-14"}
        → enter only on the listed weekdays (ET session days) and outside the
          pause window (both ends inclusive; either end may be omitted for an
          open-ended pause). ENTRIES only — an open position is marked, exited
          and settled on every day, scheduled or not. The live walk counts each
          refusal as skipped_schedule, and the graded backtests refuse the same
          bars, so a scheduled bot grades exactly what it will live.
}
```
Send strategies in EXACTLY this shape. Required: name, asset_class, universe,
timeframe, backtest, entry (side + when), exit. The overlays + intraday fields are
optional.

## BAR SIZES — what we TRADE vs what we can GRADE (2026-07-29)

These are two different questions and we answer them separately, because live
only needs the price RIGHT NOW while grading needs history we do not have yet.

  WE WILL TRADE (deploy) any of: "1 day", "1Min", "5Min", "15Min", "30Min",
  "1Hour", "4Hour" — for EQUITIES **and OPTIONS**. A 1-minute RSI options bot deploys and
  runs. Intraday option contracts are resolved from the LIVE chain at the moment
  the signal fires (nearest real strike to what you asked for — we record what
  was actually bought vs what was requested), bought at the REAL ask, and SKIPPED
  when there is no live quote, when the book is crossed, or when the spread is
  wider than 12% (un-exitable). A missed trade is honest; an invented fill is not.

  WE CAN GRADE (backtest): "1 day" for ANY vehicle, and EVERY intraday bar size
  ("1Min", "5Min", "15Min", "30Min", "1Hour", "4Hour") for EQUITIES — since
  2026-08-03, off a warehouse of 217 symbols x 36 months of real consolidated-tape
  1-minute bars (2023-08 onward). Larger bars are FOLDED from those same minutes
  by the same function the live desk folds with, so a graded 4Hour bar is the bar
  the desk trades.

  STILL NOT GRADABLE: an INTRADAY OPTION strategy. We carry intraday option
  history only back to 2026-07-08 (~4 weeks, 30-minute snapshots over 4 ETFs plus
  held contracts): enough to trade on, nowhere near enough to score honestly.
  POST /v1/backtests on one returns a plain-words refusal naming the reason. Do
  NOT present an intraday-option bot as backtested — it is not.

  THE GRADED WINDOW IS STATED, and on a big universe it is SHORTER than you
  asked. Minute data is ~390x denser than daily and the whole universe is held at
  once, so an intraday grade runs inside a memory budget: result.graded_window
  carries {start, end, requested_start, graded_sessions, warmup_sessions,
  bounded}, and when bounded is true a metrics_note says so in plain words. READ
  IT — do not report a bounded run as covering the requested dates. Two things
  buy more history and nothing else does: fewer symbols (memory scales straight
  with the universe) and a larger bar size (a 1Hour bar costs about a fifteenth
  of a 1-minute one). If even the strategy's own warmup does not fit, the run is
  refused with those same two levers named — that is a statement about our
  machine, never about the strategy, and the bot still deploys and trades live.

  A deployed intraday bot is walked when ITS OWN bar closes (a 5-minute bot on
  every 5-minute boundary), and a bot asking for a bar size we do not run matches
  no tick and simply does not trade.

  "4Hour" IS SESSION-ANCHORED (2026-08-01). A regular session is 6.5 hours
  (09:30–16:00 ET), which cannot be tiled by 4-hour bars, so the bars start at
  the session OPEN: bar 1 covers 09:30–13:30 (a full 4 hours), bar 2 covers
  13:30–16:00 (2.5 hours). THE LAST 4HOUR BAR OF A SESSION IS SHORT; that is the
  market's shape, not a bug — the same way the market's own half-days are short
  (a 13:00-close half-day folds to ONE 3.5-hour bar). The short bar CLOSES at the
  session close (16:00, or 13:00 on a half-day), never at label+240 minutes.
  Midnight-anchored bins were rejected out loud: an 08:00–12:00 bucket would
  blend pre-market emptiness into session data. Extended-hours minutes belong to
  NO 4Hour bar. The graded fold, the live REST walk and the stream aggregator all
  share this one rule, so the desk trades exactly the bars a backtest would grade.

## NAME AND DESCRIBE EVERY BOT YOU DEPLOY

Send `name` and `description` on POST .../deploy. Both are optional — a missing
one NEVER blocks a deploy — but a fleet of bots called "deployment" is useless to
the human who owns them.

  "name":        short and specific — "AAPL 5-min RSI dip", not "bot 3".
  "description": ONE sentence on what you were going for, in plain words.

We ALSO derive a description from the spec itself and show it beside yours. That
derived text is spec-truth (it cannot drift from what runs); yours is labelled as
the author's intent. So write what you MEANT — do not restate the rules, and do
not describe behaviour the spec does not implement, because the two sit side by
side and a contradiction is visible to the user. The full field rules (indicators, feature ids, and the per-asset_class
leg/structure blocks for option/credit/combo/covered) are documented below — but
here is a RUNNABLE example you can POST as-is:
```json
{
  "name": "AAPL momentum (example)",
  "asset_class": "equity",
  "universe": [
    "AAPL"
  ],
  "timeframe": "1 day",
  "backtest": {
    "start": "2024-02-12",
    "end": "2026-05-20"
  },
  "indicators": [
    {
      "id": "rsi14",
      "type": "rsi",
      "params": {
        "length": 14
      }
    }
  ],
  "entry": {
    "side": "call",
    "when": {
      "all": [
        {
          "lt": [
            "rsi14",
            30
          ]
        }
      ]
    }
  },
  "exit": {
    "rule": "fixed",
    "hold_days": 5
  }
}
```

## DEPLOYING A BOT — recommended spec format (use this shape for best results)
The same idea told two ways. A SHARES bot is `asset_class:"equity"` with an
entry.side of "buy" (long) or "sell" (short), and NO option leg. An OPTIONS bot is
`asset_class:"option"` with entry.side "call"/"put" PLUS an `option` leg
({right, itm_pct, target_dte}). Everything else — universe, timeframe, backtest,
entry.when, exit, sizing {method,value}, top-level max_open_positions — is shared.
Follow one of these two shapes and it validates; deploy it as-is. (These mirror the
"copy an example" card on the desk, so the web and the agent see one format.)

Shares bot:
```
{
  "name": "Dip buyer (shares)",
  "asset_class": "equity",
  "universe": [
    "NVDA",
    "AMD",
    "MSFT"
  ],
  "timeframe": "1 day",
  "backtest": {
    "start": "2024-02-12",
    "end": "2026-05-20"
  },
  "indicators": [],
  "direction": "long",
  "entry": {
    "side": "buy",
    "when": {
      "all": [
        {
          "lte": [
            "ret3",
            -0.1
          ]
        },
        {
          "gt": [
            "close",
            "sma200"
          ]
        }
      ]
    }
  },
  "exit": {
    "rule": "fixed",
    "hold_days": 10,
    "stop_pct": -8
  },
  "sizing": {
    "method": "fixed_usd",
    "value": 2000
  },
  "max_open_positions": 5
}
```
Options bot (same signal, expressed as a call):
```
{
  "name": "Dip buyer (calls)",
  "asset_class": "option",
  "universe": [
    "NVDA",
    "AMD",
    "MSFT"
  ],
  "timeframe": "1 day",
  "backtest": {
    "start": "2024-02-12",
    "end": "2026-05-20"
  },
  "indicators": [],
  "entry": {
    "side": "call",
    "when": {
      "all": [
        {
          "lte": [
            "ret3",
            -0.1
          ]
        },
        {
          "gt": [
            "close",
            "sma200"
          ]
        }
      ]
    }
  },
  "exit": {
    "rule": "fixed",
    "hold_days": 10
  },
  "option": {
    "right": "call",
    "itm_pct": 0.02,
    "target_dte": 35
  },
  "sizing": {
    "method": "fixed_contracts",
    "value": 2
  },
  "max_open_positions": 5
}
```

## IMPORT — paste ANY strategy (Pine / Python / plain English) → a runnable spec
The front door for porting. POST /v1/strategies/import with {source_type, source}
turns a pasted TradingView Pine script, Python (pandas / TA-Lib / backtrader), or a
plain-English description into ONE canonical spec — the same shape as THE FORMAT
above. source_type is EXACTLY one of "pine" | "python" | "english" (anything else is
a 422). It returns {spec, defaults_applied, mapping_notes[], validation:{valid,
issues[]}, source_type, label}: mapping_notes name every foreign idiom mapped to
our closest supported form (a Pine trailing stop → the engine-graded SL50; a
take-profit → dropped from the verdict) — nothing is ever silently dropped;
defaults_applied lists the safe blanks we filled (timeframe / backtest window /
indicators).

Order is FIXED and safe: the deterministic intake guard runs FIRST (a manipulation
/ illegal / reckless / injection request is refused here, before any LLM sees it),
THEN the AI TRANSLATES the source into a spec, THEN the ENGINE ALONE grades it. The
pasted source is treated as DATA (prompt-injection fenced), never an instruction —
the AI drafts the spec, it never decides a verdict.

GUEST-FRIENDLY (the growth funnel): a LOGGED-OUT visitor MAY call import — it is
per-IP rate-capped (currently 6/hour); logged-in
callers use the per-user gate. Actually running / saving / deploying the resulting
spec still needs a signed-in account. 503 when AI is unconfigured/disabled; 429 over
the rate cap.

## WHAT THIS PLATFORM IS AND ISN'T (read before you port a strategy)
Know the boundaries UP FRONT so you don't discover them through errors. If you
send a foreign concept below, the validator rejects it with the closest
supported alternative — but you save a loop by mapping it here first.
- BARS: DAILY by default (timeframe "1 day") — signals evaluate on daily closes.
  INTRADAY bars ARE supported (corrected 2026-10-05 — this said "1Min only"):
  timeframe "1Min", "5Min", "15Min", "30Min", "1Hour" or "4Hour". EQUITIES run on
  every one of them GRADED and LIVE — the SAME honest machinery on REAL
  consolidated-tape bars folded from 1-minute SIP history (a signal on bar i fills
  at the NEXT bar's open, no look-ahead, no fabricated bars); single OPTIONS run on
  them LIVE only (intraday option history is too short to grade); credit / combo /
  covered are daily only. CUSTOM ENTRY-TIME WINDOWS: entry_start / entry_end
  ("HH:MM" wall-clock ET, e.g. "10:00"/"13:30") gate a signal to fire ONLY inside
  that window. Omit them → the full session (09:30–16:00) is assumed and CONFIRMED
  back in defaults_applied / intraday_schedule. INTRADAY EXITS: exit.max_minutes (a
  hard time-stop N minutes after the fill), exit.eod_flatten (force-close at the
  entry session's last bar, never overnight) and exit.flatten_at ("HH:MM" ET) — the
  exit is the EARLIEST of the rule/hold_days and these (all look-ahead-safe);
  hold_days counts trading SESSIONS on every timeframe. CROSS EVENTS: use
  {"cross_above": [a, b]} / {"cross_below": [a, b]} for "a crosses b" (true on
  the one bar it crosses — TradingView's ta.crossover), and gt/lt for the ongoing
  state. INTRADAY FEATURES (usable in entry.when): ret_<N>m (N WALL-CLOCK minutes,
  a whole number of bars), rvol (this bar's volume ÷ the running mean bar-volume so
  far in the session — first bar = 1.0), and hour (wall-clock ET hour, e.g.
  {"gte":["hour",10]} + {"lte":["hour",10]} for the 10-o'clock hour). All three
  are causal (bar i reads only bars ≤ i). NOTE: the "vwap" indicator is a ROLLING
  N-bar volume-weighted average — it does NOT reset at each session's open — and
  run5 / gap still count BARS, so on a 5Min spec run5 is 25 minutes. The 10:35-ET
  hook (entry_at:"intraday_1035") is a separate DAILY-bar session artifact, not an
  intraday mode. (Crypto is SHELVED — see below.)
- YOUR STOP IS A SPEC FIELD AND IT IS GRADED. Write it as
  {"exit": {"stop_pct": -60}} — a NEGATIVE percent of the entry, so -60 means
  "close it if it is down 60%". The backtest grades the level YOU asked for and
  reports it as result.real.user_bracket (a PERCENT EV) — on single options off
  the contract's real sell-price path, and on SHARES (daily and every intraday
  size, since 2026-10-05 — before that a share stop was accepted and not graded)
  at the first held bar CLOSE at or through your level, filled at that close (a
  bar cannot fill a stop intrabar). Credit / combo / covered: your desk runs it,
  the grade does not include it yet. Beside it the engine
  publishes its OWN read — result.real.best_bracket, the best of none / SL30 /
  SL50 — so you can see whether a different level would have done better. That is
  a SUGGESTION, never a substitution: your number is what was simulated and what a
  live desk would run. The engine's read stays on none/SL30/SL50 so that the
  headline verdict is comparable across every strategy on the platform.
  Custom trailing / ratchet arm-and-give-back parameters are still not GRADED —
  the closest graded stop is SL50, and the live-desk `profit_lock` ratchet is the
  forward-only version. (You may also pick ONE built-in held-path exit rule:
  fixed / lo3 / lo5 / peak8 — defined in the CAPABILITY MAP below.)
- TAKE-PROFIT IS BANNED FROM THE VERDICT. Capping winners is a proven
  edge-killer (an earned law), so a TP can never enter the grade — remove it.
- CROSS-SECTIONAL / RELATIVE-STRENGTH is the `xrank` operand
  ({"xrank": "ret20"} → this symbol's 0..1 percentile among the universe on
  that date). For a HARD top-N cut use `top_n`: {"top_n": {"by": "ret20",
  "n": 3}} → 1.0 if this symbol is in the 3 highest by ret20 that date, else 0.0
  (same date-alignment as xrank, no look-ahead). Use as {"gte": [{"top_n":
  {"by": "ret20", "n": 3}}, 1]}.
- BENCHMARK / INDEX conditions: `spy_ret` / `qqq_ret` (SPY / QQQ 1-bar return on
  the same date), `bench_ret` (the spec's `benchmark` field, default SPY), and the
  general {"bench": "SPY", "ret": N} (any index's N-bar return). Aligned by date,
  no look-ahead; NaN — an honest skip — if the index has no bar that date. E.g.
  "only when SPY is red >=0.5%": {"lte": ["spy_ret", -0.005]}; "QQQ 20-day uptrend":
  {"gt": [{"bench": "QQQ", "ret": 20}, 0]}.
- CANDLESTICK PATTERNS are 0/1 indicators: declare {"id": "be", "type":
  "bullish_engulfing"} (also bearish_engulfing, doji [params.frac], hammer
  [params.ratio]) and read it as {"gte": ["be", 1]}.
- WEEKDAY / CALENDAR: base features dow (0=Mon..4=Fri), is_friday, is_monday —
  e.g. a Friday-only entry is {"eq": ["dow", 4]}.
- MACRO EVENT FILTER (the published Fed/BLS calendars — no feed, no look-ahead):
  is_fomc_day, is_cpi_day (1.0/0.0 flags on the bar's session) and days_to_fomc
  (TRADING SESSIONS to the next FOMC decision, capped at 99). E.g. stand aside on
  decision days: {"lte": ["is_fomc_day", 0]}. There is NO `vix` operand — the
  VIX is a licensed index feed we don't carry (closest: rvpct / regime_vol).
- NO NEWS / SOCIAL / THEME feeds. Only price / volume-derived features and the
  declared technical indicators exist — no headlines, sentiment, or theme tags.
- OPTIONS TRADE A MUCH THINNER UNIVERSE THAN EQUITIES, and the check you pass is
  NOT the coverage you get. An `option`/`credit`/`combo` spec naming an underlying
  with NO chain rows at all is REJECTED, naming what to drop — but a name with a
  FEW rows passes and then trades almost never. Read "OPTIONS COVERAGE" in the
  CAPABILITY MAP below before you trust any multi-name option scan; it tells you
  the two result fields that show which names really traded. Do not assume "all
  symbols" works for options. (An agent and a reviewer both assumed the full
  catalog here on 2026-07-29; the validator caught the hard case, but the thin-
  coverage case is the one that stays silent.)
- OPTIONS DATA WINDOW is 2024-02-12 .. 2026-05-20. A backtest outside it finds no
  option fills (NO_DATA).
- FILLS: a REAL measured OPRA NBBO when we have one (buy @ the real ask, sell @
  the real bid; NEVER MID), else a byte-identical fall back to REAL `last` +/- a
  MODELED spread. Which tier priced each fill is reported (real_nbbo_fill_share).
- A UNIVERSE IS AN EXPLICIT TICKER LIST, not a screen. You name the symbols
  (e.g. ["AAPL", "MSFT"]); there is no "top 100 by X" screen that becomes a
  universe.
- EQUITY DIRECTION — LONG OR SHORT. Shares trade LONG by default; a SHORT
  (bearish) equity strategy is fully supported. Declare it with entry.side "put"
  (bearish) OR a top-level direction:"short" (if you give both they must AGREE).
  A short SELLS at the next bar's open and BUYS-TO-COVER at exit; P&L is inverted
  (you profit when the price FALLS) and a MODELED short-borrow cost accrues per
  held day. So a plain short, a long/short book, a pairs trade, or a market-
  neutral basket all BUILD now — express the short leg as an equity/"put" (or
  direction:"short") spec ranked with xrank. The one exception that still can't:
  a SHORT-SQUEEZE / SHORT-INTEREST scanner — there is no short-interest / borrow
  / days-to-cover feed on this dataset (use price/volume rules instead).
- SHORT-BORROW IS A MODELED CONSTANT, NOT A MEASURED FEE. The short-financing
  charge is a flat annualized rate (default 3%/yr) accrued per calendar day on
  the entry notional — labeled `borrow_cost_frac` per trade and `borrow_model` on
  the result. It is NOT a real per-name locate/borrow rate (a hard-to-borrow name
  costs far more), so treat it as optimistic for thin/hard-to-borrow names — the
  same truth-in-labeling as the modeled option spread.
- CRYPTO IS SHELVED (not available yet) — an asset_class "crypto" spec is REJECTED
  with an honest message. The engine can grade crypto spot, but the only crypto data
  we can reach is VENUE-ONLY and far too thin to grade an honest
  backtest — e.g. BTC/USD shows ~2 coins/day (~$128k) on that single venue vs
  ~$30B/day globally. We refuse to ship fills we can't stand behind, so crypto
  stays off until we license a real crypto market-data feed. Do NOT send
  asset_class "crypto"; it returns when the data is real.

## CAPABILITY MAP — every feature, its UNIT, and the rules around it
Read this BEFORE you write a threshold. Every line below was checked against the
engine's own code. Most "my bot never fires" reports are one of two things: a
percent written where a FRACTION belongs, or a feature that counts BARS being read
as if it counted DAYS. Both are below.

### THE FEATURE DICTIONARY — what each id measures, and its unit
PRICE / VOLUME (attached on every timeframe)
  `c` · unit: dollars per share · this bar's CLOSE (alias `close`)
  `o` · unit: dollars per share · this bar's OPEN (alias `open`)
  `h` · unit: dollars per share · this bar's HIGH (alias `high`)
  `l` · unit: dollars per share · this bar's LOW (alias `low`)
  `v` · unit: shares · this bar's VOLUME (alias `volume`)
  `volavg` · unit: shares · the mean of `v` over the last 20 BARS

RETURNS — ALL are DECIMAL FRACTIONS. 0.02 IS +2%. Writing 2 means +200%.
  `ret` · unit: fraction · this bar's close ÷ the previous bar's close − 1
  `ret3` · unit: fraction · close vs the close 3 BARS ago
  `run5` · unit: fraction · close vs the close 5 BARS ago
  `bar_run5` · unit: fraction · the SAME number as `run5` under its honest name —
    it counts 5 BARS (25 minutes on a 5Min spec, a week only on daily)
  `ret20` · unit: fraction · close vs the close 20 BARS ago
  `gap` · unit: fraction · this bar's OPEN ÷ the previous bar's CLOSE − 1
  `bar_gap` · unit: fraction · the SAME number as `gap` under its honest name —
    ONE bar boundary (the overnight gap on daily; a micro gap intraday)

CANDLE PATTERNS — flags: 1.0 when the pattern printed on THIS bar, else 0.0.
Per-BAR shapes (a "hammer" on a 5Min spec is a 5-minute hammer).
  `doji` · unit: flag · body ≤ 10% of the bar's range (a standoff)
  `hammer` · unit: flag · lower wick ≥ 2× body, upper wick ≤ half the body
  `inside_bar` · unit: flag · this bar's high/low inside the previous bar's
  `engulf_bull` · unit: flag · up body engulfing the previous down body
  `engulf_bear` · unit: flag · down body engulfing the previous up body

CALENDAR — the calendar as an input. Month edges are CALENDAR-true (the
exchange schedule, published in advance — not look-ahead).
  `dom` · unit: day number (1-31) · the bar's session day-of-month
  `month` · unit: month number (1-12) · the bar's session month
  `is_month_start` · unit: flag · first trading session of its month
  `is_month_end` · unit: flag · last trading session of its month

LEVELS (dollars — compare them to a price, never to a percentage)
  `sma20` · unit: dollars · the mean close of the last 20 BARS
  `sma50` · unit: dollars · the mean close of the last 50 BARS
  `sma200` · unit: dollars · the mean close of the last 200 BARS
  `hi60` · unit: dollars · the HIGHEST CLOSE of the last 60 BARS
  `hi252` · unit: dollars · the HIGHEST CLOSE of the last 252 BARS. On a daily spec
      that is the 52-week high — but it is a CLOSING high, not the intraday high a
      chart shows. "Within 8% of the 52-week high" is
      {"gte": ["close", {"mul": ["hi252", 0.92]}]}.
  `atr20` · unit: dollars · the mean true range over the last 20 BARS

VOLATILITY / REGIME
  `rvpct` · unit: 0..1 FRACTION, NOT a percent · WHERE TODAY'S VOLATILITY SITS IN
      ITS OWN PAST YEAR. Two steps: first `rv` = the standard deviation of the last
      20 one-bar returns; then `rvpct` = the share of the last 252 `rv` readings
      that today's reading is ABOVE. So 0.90 = "more volatile than 90% of the past
      year", 0.10 = unusually calm. Needs ~272 bars of warmup (NaN before that).
      THE TRAP: {"gt": ["rvpct", 80]} can NEVER fire, because rvpct never goes
      above 1.0 — the rule looks fine, validates, deploys, and takes zero trades
      forever. Write {"gt": ["rvpct", 0.80]}. This exact mix-up inverted a LIVE
      bot's rule and nothing warned about it.
  `regime_trend` · unit: ordinal code · 1 = uptrend (close above sma200 AND sma50
      rising), 0 = chop, -1 = downtrend (close below sma200 AND sma50 falling);
      NaN during warmup. "Uptrend only" is {"gte": ["regime_trend", 1]}.
  `regime_vol` · unit: ordinal code · 1 = high vol (`rvpct` at or above 0.5, i.e.
      above its own one-year median), 0 = low vol; NaN during warmup.

CALENDAR — these exist, and almost nobody knows
  `dow` · unit: integer code · 0 = Monday, 1 = Tuesday, 2 = Wednesday,
      3 = Thursday, 4 = Friday. Market bars are weekdays only, so 5/6 never appear.
      A Friday-only entry is {"eq": ["dow", 4]}.
  `is_monday` · unit: 1.0 / 0.0 · 1.0 on a Monday bar, else 0.0
  `is_friday` · unit: 1.0 / 0.0 · 1.0 on a Friday bar, else 0.0
      So a "sell Friday, buy Monday" study needs no custom code:
      {"gte": ["is_friday", 1]}.

MACRO EVENT CALENDAR — the PUBLISHED Fed/BLS schedules as inputs (works on every
timeframe). These are official calendars fixed IN ADVANCE — FOMC decision days
2024-2027 and BLS CPI release days 2024-2026, transcribed as-they-happened in
vega_engine.macro_calendar — so reading them on a historical bar is NOT
look-ahead: the schedule was public before the bar printed. No feed involved.
  `is_fomc_day` · unit: 1.0 / 0.0 · 1.0 when the bar's ET SESSION is an FOMC
      rate-decision day (the second day of the scheduled meeting — the 14:00 ET
      announcement day). Stand aside on decision days:
      {"lte": ["is_fomc_day", 0]}.
  `is_cpi_day` · unit: 1.0 / 0.0 · 1.0 when the bar's session is a BLS CPI
      release day. The number prints 08:30 ET — BEFORE the open — so it is known
      for the whole session the flag marks.
  `days_to_fomc` · unit: TRADING SESSIONS, saturating at 99 · sessions until the
      next FOMC decision: 0 on the decision day itself, 1 the session before.
      Past the END of the published schedule the value is the 99 cap (the true
      distance is unknown there), so a "within N sessions" filter is honestly
      false rather than a guess. "Only trade more than 2 sessions from a
      decision" is {"gt": ["days_to_fomc", 2]}.
  There is NO `vix` operand — the VIX is a licensed index feed (Cboe) we do not
  carry yet, and we won't fake it from a volatility ETF. The closest existing
  operands are `rvpct` and `regime_vol` (above).

EARNINGS PROXIMITY — real report dates, and they look BACKWARD ONLY (works on
every timeframe). Dates come from each company's SEC **8-K item 2.02** filing
("Results of Operations and Financial Condition") — the filing a company makes
when it publishes results — so the date is point-in-time BY CONSTRUCTION: it
cannot be revised backward and a backtest cannot read one before it was public.
It is the FILING date, i.e. the announcement give or take one session (a company
reporting after the close usually files that evening, sometimes the next
morning). We store no time of day and never invent one.
  `days_since_earnings` · unit: TRADING SESSIONS, saturating at 99 · sessions
      since this company's most recent report. It starts at **1** — the first
      session that TRADES after the report — and is NEVER 0, because the release
      lands at or after the close of the session it is filed on, so a bar on the
      filing date has not seen it. Post-earnings drift is
      {"lte": ["days_since_earnings", 3]}; "stay clear for a week after a
      report" is {"gt": ["days_since_earnings", 5]}.
      **Blank (never a number) where we have no earnings history** — an ETF, an
      ADR (below), or bars before that name's first stored filing. A blank never
      fires, which is the honest outcome; 99 there would be a confident claim we
      cannot support.
  **ADRs are BLANK, deliberately — do not read it as a gap.** A foreign private
  issuer (BABA, TSM, ASML, ARM, BIDU, JD, NIO, NVO, PDD, SPOT) has no 8-K duty:
  it files **6-K**, the catch-all form on which earnings, dividends, buybacks and
  ordinary press releases all arrive with **no item code separating them**. We
  checked for a discriminator and there is none — measured across all 908 of
  their 6-Ks, the `items` field is empty on every single one, and the document
  description is a constant ("all 206 of TSM's say `6-K`"). Corroborating against
  a free vendor calendar does not rescue it either: those are forward-looking and
  return ZERO historical dates inside our graded window, and a quarterly-grid
  guess matched exactly one filing only 29% of the time. Trusting every 6-K
  instead would flag ~22% of NVO's and BABA's sessions as the reaction to a
  report, versus a true ~1.6%. So these ten names carry no earnings dates at all
  and the operands stay blank on them. **A rule using `days_since_earnings` will
  simply never fire on an ADR** — if that matters to your strategy, restrict the
  universe to domestic names rather than expecting a number to appear.
  `is_earnings_window` · unit: 1.0 / 0.0 · 1.0 on the REACTION session (the one
      day above), 0.0 on any session we can place against a known report, blank
      where `days_since_earnings` is blank. Despite the name it does NOT mean
      "near a report in either direction".
  There is **no forward days-to-earnings operand**, deliberately. A filing tells
  us when a report HAPPENED, never when its date became public — companies
  pre-announce two to four weeks ahead and the SEC does not record that — so
  grading "3 sessions before the print" would use tomorrow's news to trade today,
  in the most flattering direction there is, and it would score beautifully and
  trade differently. Asking for one gets a plain-words refusal, not a silent NaN.
  To simply not be holding around a report, bound the holding period instead
  (exit.hold_days, or exit.max_minutes on an intraday bot).
  There is no EPS, surprise, guidance or revenue data of any kind. For the SIZE
  of a surprise read the price reaction: {"gt": ["ret", 0.05]} plus
  {"gt": ["v", "volavg"]}.

INTRADAY-ONLY — attached ONLY on an intraday timeframe. On "1 day" they are never
attached, so referencing one there is an honest "unknown feature" rejection.
  `hour` · unit: integer 0..23 · this bar's own wall-clock ET hour. Gate the
      10-o'clock hour with {"gte": ["hour", 10]} AND {"lte": ["hour", 10]}.
  `rvol` · unit: ratio, 1.0 = average · this bar's volume ÷ the running mean
      bar-volume SO FAR IN THE SAME ET SESSION. It resets every morning and the
      FIRST bar of a session is always EXACTLY 1.0 (nothing to compare against
      yet), so "rvol > 1.5" can never fire on the opening bar. It answers "is today
      busier than today has been?" and cannot see yesterday.
  `rvol_trail20` · unit: ratio, 1.0 = average · this bar's volume ÷ the mean volume
      of the LAST 20 BARS (this bar included — the same window as `volavg`). NaN
      for the first 19 bars. THIS is what "volume versus its 20-bar average"
      normally means. `rvol` and `rvol_trail20` are TWO DIFFERENT MEASURES: one is
      session-anchored and resets, the other is trailing and crosses sessions. A
      rule written for one and handed the other still RUNS — it just silently
      measures something else. Pick deliberately.
  `ret_<N>m` · unit: fraction · the return over N WALL-CLOCK MINUTES. `ret_5m` is
      five minutes on EVERY bar size (one bar on a 5Min spec, five on a 1Min spec)
      — N is converted for you. An N that is not a whole number of bars is refused
      up front, naming the nearest N that works.

CROSS-SECTIONAL / BENCHMARK OPERANDS (dict operands, not plain ids)
  {"xrank": F} · unit: 0..1 percentile · this symbol's rank on F among the
      universe on that same date (1.0 = the highest of the day).
  {"top_n": {"by": F, "n": K}} · unit: 1.0 / 0.0 · 1.0 when this symbol is
      among the K highest by F that date. Use it as
      {"gte": [{"top_n": {"by": "ret20", "n": 3}}, 1]}.
  `spy_ret` / `qqq_ret` · unit: fraction · SPY's / QQQ's ONE-BAR return on the same
      date. ONE bar — for a longer look-back use the bench form below.
  `bench_ret` · unit: fraction · the same one-bar return for the spec's `benchmark`
      field (default SPY).
  {"bench": SYM, "ret": N} · unit: fraction · SYM's N-BAR return, broadcast to
      every name on that date. NaN — an honest skip — when SYM has no bar there.
  {"pair_z": {"a": A, "b": B, "window": N, "mode": "ratio"|"spread"}} · unit:
      STANDARD DEVIATIONS (a z-score, unitless — write thresholds like -2 or
      +2, NEVER a percent) · the pair's value series (close_a/close_b for
      "ratio", the default; close_a − close_b for "spread") minus its trailing
      N-BAR mean, divided by the trailing N-bar sample std. `window` counts
      BARS of the spec's own timeframe (60 daily bars on "1 day", 60
      five-minute bars on "5Min"). Computed only on dates BOTH legs have a
      real bar; the first window−1 joint bars are NaN warmup; both legs are
      loaded automatically even when neither is in the universe. No
      look-ahead. Use as {"lt": [{"pair_z": {"a": "KO", "b": "PEP",
      "window": 60}}, -2]} — "KO is 2 sigma cheap against PEP".

ARITHMETIC OPERANDS (either side of any comparison)
  {"mul": [A, B]} · A × B · {"sub": [A, B]} · A − B · {"lag": [F, N]} · F as
  of N bars ago (look-back only). They NEST: "beats SPY by 5 points over 20 days"
  is {"gte": [{"sub": ["ret20", {"bench": "SPY", "ret": 20}]}, 0.05]}.

### BAR vs TIME — the same id means a different LENGTH on each timeframe
Several ids count BARS while their names sound like TIME, and ONE `timeframe`
governs both what a feature means and when the bot may trade. Restate every
bar-counting feature in wall-clock terms before you trust an intraday spec.

  id                    "1 day"        1Min      5Min       15Min     30Min     1Hour
  -------------------   ------------   -------   --------   -------   -------   --------
  ret                   1 session      1 min     5 min      15 min    30 min    60 min
  ret3                  3 sessions     3 min     15 min     45 min    90 min    3 hours
  run5                  5 sessions     5 min     25 min     75 min    150 min   5 hours
  ret20                 20 sessions    20 min    100 min    300 min   600 min   20 hours
  sma20/atr20/volavg    20 sessions    20 min    100 min    300 min   600 min   20 hours
  sma200                200 sessions   200 min   1000 min   50 hours  100 hours 200 hours
  hi252                 252 sessions   252 min   21 hours   63 hours  126 hours 252 hours
  gap                   OVERNIGHT      one bar boundary — a micro gap, NOT the overnight gap
  ret_5m                n/a (minute-only) — 5 min on every bar size, converted for you

  "4Hour" (2 bars a session — the 13:30–16:00 bar is honestly SHORT): restate in
  SESSIONS, not hours: ret = 1 bar (≈ half a session) · ret3 = 1.5 sessions ·
  run5 = 2.5 sessions · ret20 = 10 sessions · sma200 = 100 sessions · hi252 =
  126 sessions (about half a year — NOT a 52-week high). `gap` on "4Hour" is the
  bar boundary at 13:30 within a session, or the true overnight gap on the 09:30
  bar — use `gap1035` for the overnight gap you can trust.

Plainly, because this already mis-aimed a LIVE bot:
  • ON A 5-MINUTE SPEC `run5` IS A 25-MINUTE MOVE, not a 5-day one.
  • The LAST CLOSED BAR's return is `ret` — not `ret_5m`, and not `run5`.
  • `gap` on any intraday spec is a bar-to-bar micro gap (a rounding-level
    number, median ~0.005%), NOT the ~1% overnight gap a daily spec measures. For
    the true overnight gap use `gap1035` (see SESSION ANCHORS).
  • A rule written for daily bars does not "just work faster" on 5-minute bars —
    it measures something else. Restate each feature in wall-clock terms first.

CONVERTED FOR YOU — the fields/operands that really are time/session denominated:
  {"lag_sessions": [F, N]} — F's value N trading SESSIONS ago on EVERY timeframe
      (the session-denominated twin of `lag`, which counts BARS). Same bars-per-
      session ladder as hold_days below. Validating/deploying an intraday spec
      whose `lag` looks day-sized (N >= 20) gets a heads-up naming this twin —
      advisory only, the rule always runs exactly as written.
  `exit.max_minutes` — N wall-clock MINUTES, turned into bars ROUNDED UP (a partial
      bar is still a bar you held through; rounding down would exit earlier than
      you asked). Minimum 1 bar.
  `exit.hold_days` — N trading SESSIONS on EVERY timeframe. Bars per session:
      1 day → 1 · 1Min → 390 · 5Min → 78 · 15Min → 26 · 30Min → 13 · 1Hour → 7
      · 4Hour → 2 (1Hour and 4Hour round UP — the last, shorter bar of the
      session is a real bar). So hold_days 5 on a 5-minute spec holds five
      SESSIONS, not five bars.
The realized exit is always the EARLIEST of the exit rule/hold_days,
`max_minutes`, `flatten_at` and `eod_flatten`.

### RANK — "only the best N names today"
`rank` is the per-day SELECTOR that runs AFTER your entry rule fires. Every symbol
whose rule fired on a date is scored, sorted, and only the winners are traded.

  rank.by      REQUIRED. A plain feature id STRING — a base feature, an OHLCV
               alias, a session anchor, a benchmark operand, or one of your own
               declared indicators[] ids. It is NOT an expression: a dict such as
               {"sub": [...]} is rejected by the schema. Declare an indicator and
               rank on its id instead. Read at the SIGNAL bar (no look-ahead).
  rank.top_n   REQUIRED. An integer ≥ 1 — how many names to keep on that date.
  rank.lowest  OPTIONAL boolean, default FALSE. false/absent = keep the top_n
               HIGHEST values of `by` (momentum leaders). true = keep the top_n
               LOWEST — the "deepest dip / biggest flush / cheapest vol" rank. Only
               the DIRECTION changes; the same top_n count applies.

Every signal the rule produced but rank did not select is counted as a `cap` skip
in result.metrics.skips — nothing vanishes silently (signals = fills + skips, and
the engine checks that conservation for you).
TIES: the sort is STABLE, so names with an identical `by` value hold whatever order
the universe was built in. That order is NOT a preference and you should not lean
on it — if ties are likely (a boolean or a coarse integer `by`), rank on a
finer-grained feature or raise top_n. A `by` that is NaN on that bar neither
reliably wins nor reliably loses, so pick a feature that is DEFINED at the signal
bar (mind warmup: sma200 needs 200 bars, rvpct ~272).

`rank` vs the top_n OPERAND: `rank` is a spec-level SELECTOR (fire anywhere, then
keep N). {"top_n": {"by": F, "n": K}} is an OPERAND inside entry.when — a hard
membership filter on the rule itself. Both exist and they compose.

### THE LIVE EXIT OVERLAYS × EVERY VEHICLE
`stop_loss`, `take_profit` and `profit_lock` are LIVE-desk execution preferences.
All three now apply on EVERY vehicle, and each reads THAT vehicle's own gain path —
so the same number means the same thing everywhere:

  vehicle              what "gain" is on it                    so stop_pct 0.30 means
  ------------------   -------------------------------------   ------------------------
  single option        sell price ÷ entry premium − 1          premium down 30%
  equity LONG          close ÷ entry − 1                       price down 30%
  equity SHORT         the same, INVERTED (its own P&L)        price UP ~30%
  credit structure     fraction of the CREDIT captured:        30% of the credit given
                       (credit received − cost to close now)   back
                       ÷ credit received
  combo / covered      (net value − net entry) ÷ |net entry|   the netted structure
                                                               down 30%

Two readings that trip people up:
  • On a credit structure, take_profit target_pct 0.25 IS
    "take profit once a quarter of the credit is captured".
    Not a quarter of the width, not a quarter of the margin — of the CREDIT.
  • On an equity SHORT, a stop of −12% means "I am down 12%", which is the price
    having RISEN about 12%. The sign is always YOUR P&L, never the price's.

PRECEDENCE, identical on every vehicle: the earlier BAR wins. On a tie the order is
stop_loss → take_profit → ratchet (a hard risk cap protects the position first). If
your strategy's own exit rule matures on that same bar, the RULE keeps the close.

NONE OF THE THREE IS EVER GRADED — an overlay is never graded on any vehicle. The
engine's read (best_bracket, the best of none/SL30/SL50) and the verdict are
BYTE-IDENTICAL with or without any overlay: they change only how a DEPLOYED bot
sells. The result echoes each one back under its own key so nothing is hidden.
(Your own GRADED stop is a different field — `exit.stop_pct`, see above. The
top-level `stop_loss` overlay is the live-desk one and is not graded.)
(Before 2026-07-29 they were honoured on single options only, so an equity stop and
a credit take-profit were accepted and then silently dropped on the live bot.)

HOW OFTEN THE DESK LOOKS — `check` (2026-08-27). Each of the three takes an optional
`"check": "bar" | "minute"`.
  • `"bar"` is the DEFAULT and what every already-deployed bot does: the overlay is
    looked at once per YOUR strategy's own bar, inside its settle. On a 4Hour bot
    that is 13:30 and 16:00 ET — a −12% stop crossed at 10:05 is acted on at 13:30.
  • `"minute"` opts that overlay into a per-minute sweep of the open book (shares and
    single options). A threshold crossed at 10:05 closes at 10:05, at that minute's
    REAL price — the share's 1-minute close, or the option's real BID (never a mid,
    never a guessed intrabar print). A contract with no quote that minute is skipped
    and counted, never priced from nothing.
It changes only WHEN we look. The threshold, the precedence above, and the arithmetic
are identical at both resolutions, and NEITHER IS GRADED: the verdict still comes
from none/SL30/SL50 on your own bars. What a `"minute"` spec adds to the report is
`result.overlays` — the overlay read beside the verdict, built from 1-minute history
where we hold it and labelled `overlay_resolution: "bar"` per trade where we do not.
SHELF suppresses the sweep exactly like it suppresses the settle's overlays, a
retired bot is skipped, and the sweep never opens anything.
Example: `{"stop_loss": {"stop_pct": 0.12, "check": "minute"}}`.

### SESSION ANCHORS — the 10:35-ET vocabulary on a DAILY spec
These let a DAILY-bar strategy reason about the morning without an intraday
timeframe. They come from real 5-minute session data, and each one exists only
where that data exists for that name and date — otherwise NaN, an honest skip.

  `open0930` · unit: dollars · the open of the 09:30 ET bar (the session open).
      Known at 09:30.
  `first30_high` / `first30_low` · unit: dollars · the highest / lowest price of
      the first 30 minutes (the 09:35–10:05 bars). Known at 10:05.
  `px1035` · unit: dollars · the close of the 10:30 bar — i.e. the price at 10:35.
      Known at 10:35.
  `chg1035` · unit: fraction · px1035 ÷ open0930 − 1 — how far the name has moved
      since the OPEN. Known at 10:35.
  `gap1035` · unit: fraction · the adjusted daily OPEN ÷ the prior daily CLOSE − 1
      — the TRUE overnight gap (split-consistent on both sides). Defined only on
      bars where intraday data exists. Known at 09:30, published at 10:35.
  `above_first30_high` · unit: 1.0 / 0.0 · 1.0 when px1035 is above the
      first-30-minute HIGH (a morning breakout). Known at 10:35.
  `below_first30_low` · unit: 1.0 / 0.0 · 1.0 when px1035 is below the
      first-30-minute LOW (a morning breakdown). Known at 10:35.
  `spy1035` · unit: fraction · SPY's own `chg1035`, broadcast to every symbol on
      that date — "how is the market doing this morning". Known at 10:35.

On a DAILY frame the two breakout booleans read 0.0 when the underlying data is
missing (0.0 = "did not break"), while the price/fraction anchors read NaN. On an
INTRADAY frame every one of them is masked to NaN on bars EARLIER than the ET
minute above — a 10:35 price is not knowable on the 09:45 bar, and publishing it
there would be look-ahead of the plainest kind.

ENTRY AT 10:35: `entry_at: "intraday_1035"` prices the entry at `px1035` OF THE
SIGNAL BAR instead of the next open. It is only EXECUTABLE if every operand in
entry.when is knowable by 10:35 — the safe set is `open`/`o`/`gap`, `open0930`,
`px1035`, `chg1035`, `gap1035`, `spy1035`, `above_first30_high`,
`below_first30_low`, any {"lag": [F, N]} with N ≥ 1, and plain numbers. NOTE that
`first30_high` / `first30_low` are usable in rules but are NOT in that safe set, and
neither is the same bar's close/high/low, any indicator derived from the close
(sma*, ret*, atr*, hi*), or an xrank. A rule using one of those still runs on the
normal next-open fill; it just cannot claim the 10:35 price.

### EXPIRY — how `target_dte` becomes a real expiry date
`target_dte` is a TARGET, never a promise, because we can only buy contracts that
actually existed and were quotable that day.

  1. The engine asks the chain for contracts expiring between
     asof + max(target_dte − 12, 3) days and asof + target_dte + 12 days
     (CALENDAR days; per-LEG on a combo, so each leg gets its own window).
  2. Inside that window it takes the ONE row whose STRIKE is closest to what you
     asked for (spot × your itm_pct/otm_pct offset, on the correct side of the
     money). The pick optimizes the STRIKE, not the expiry.

Two consequences to plan for:
  • The realized DTE can be up to 12 days either side of `target_dte`. You do NOT
    get "the nearest expiry to 30 days" — you get the best STRIKE inside a ±12-day
    band. Read the contract you actually received (the OCC contract_symbol carries
    its real expiry) instead of assuming.
  • The low end is FLOORED AT 3 DAYS. A 0DTE or 1DTE request on the graded daily
    path cannot be honoured — asking for target_dte 1 searches 3..13 days. Same-day
    expiries are a live/intraday concern, not a gradable one.
Our option data also caps around 98 DTE, so a "6-month LEAP" leg is not available —
the longest real long leg is ~90 DTE (a diagonal, honestly labeled).

CREDIT structures take their expiry from whichever pricing mode they run in. On the
REAL-CHAIN path (structure.pricing "chain", or auto where the chain covers the fill
date) the expiry is a LISTED expiration — the real one nearest target_dte, strictly
after the fill — and both strikes are real listed strikes. On the MODEL path the
expiry is the FIRST bar whose date is on or after entry + target_dte calendar days,
the strikes are spot x a fraction, and the price is Black-Scholes-MODELED (see the
pricing block below). On the LIVE desk the same structure is opened on REAL contracts
through the same +/-12-day expiry band every other option fill uses. Every credit
trade and every credit position row says which it got in `pricing_source` — read
that, never the asset class, to know which one you are looking at.

### OPTIONS COVERAGE — the trap that quietly shrinks a broad scan
The equity catalog is large (hundreds of names, and any qualifying US symbol can be
onboarded on demand). The OPTIONS store is not, and the two are easy to confuse.

THE GATE IS NOT COVERAGE. The API check asks only "does this underlying have ANY
row in the options store?". On the store measured 2026-07-30 that passes ~215
names — but only ~50 of them have deep history (100+ snapshot days), and the MEDIAN
passing name has just ~19 days of chain data out of ~606 sessions in the window. So
passing the gate is NOT coverage, and a name that passed can still be nearly
untradeable.

WHAT THAT DOES TO A SCAN — an option/combo/credit spec over many names
SILENTLY NARROWS to the covered ones.
A signal on a thin name finds no chain row, so it is counted as a `missing_quote`
skip: not an error, not a warning, nothing on the report card that says "18 of your
22 names never traded". In a real validation run a 22-ETF sector-rotation strategy
effectively graded 3 sectors and the scorecard looked perfectly healthy.

HOW TO CHECK BEFORE YOU TRUST A SCAN (do this every time on a multi-name option
spec):
  1. Read result.metrics.skips — `missing_quote` against the number of signals. A
     large missing_quote share means most of your universe never traded.
  2. Read result.metrics.per_symbol.by_symbol — the names that ACTUALLY traded,
     with their trade counts. If 3 of your 22 names are there, your strategy is a
     3-name strategy and you should say so.
  3. If coverage is thin, either cut the universe to the names that traded (and
     tell the user you did), or run the same rule as `equity` — the equity catalog
     is far deeper — and treat the option result as indicative only.
There is no endpoint today that returns the options-covered list on its own (GET
/v1/universe is the EQUITY catalog). When a spec names an underlying with no rows at
all, the rejection message tells you the supported count with examples.

### HELD-PATH EXIT RULES — what `exit.rule` actually does
Pick exactly one. The four ordinary ones are look-ahead-safe (each reads only bars
at or before the one it exits on) and all four are capped at 12 SESSIONS after the
fill — if the rule has not triggered by then, the position exits at the cap. The
fifth, `grid`, is not a held-path rule at all: it is the GRID's own exit and is
legal only on a spec that carries a `grid` block.

  `fixed` · exit `hold_days` SESSIONS after the fill. Needs `hold_days`.
  `lo3` · TRAILING: exit on the first bar that closes below
      the lowest of the previous 3 closes.
      "Ride it until it makes a 3-bar low."
  `lo5` · the same with five — exit on the first bar that closes below
      the lowest of the previous 5 closes.
      This IS the "ride the 5-day low" exit, and on a daily spec it is literally
      that: you stay in until the close breaks the last five days' floor.
  `peak8` · GIVE-BACK: track the highest close since the fill and exit the first
      bar that closes below 0.92 × that peak — i.e. 8% off the best close so far.
  `grid` · THE GRID EXIT (#24), and only on a spec that carries a `grid` block:
      each lot is sold one rung UP and nothing else exits it. A lot whose next
      rung never comes back is held to the end of the window and IS graded there,
      at the last real close. Using it without a grid — or a grid without it — is
      refused in plain words rather than quietly ignored.

None of these is a stop-loss — the two are different jobs and both are graded. A
held-path RULE decides when you let go of a winner; the STOP decides how much of a
loss you tolerate (your own {"exit": {"stop_pct": -60}} if you set one, with the
engine's read — the best of none / SL30 / SL50 — reported beside it).

### OPTIONS ROLLING — `exit.roll` (single-leg option specs only)
{"exit": {"rule": "fixed", "hold_days": 30, "roll": {"at_dte": 7, "max_rolls": 2}}}
When the HELD contract reaches `at_dte` days-to-expiry BEFORE your exit has fired,
the position ROLLS: it SELLS the held contract at the sacred sell price (the real
bid — never mid) and RE-BUYS the same right / target_dte / moneyness selection from
THAT session's chain at its real ask, up to `max_rolls` times (default 1); after the
budget is spent it runs to your exit / expiry exactly like an unrolled position.
  · The GRADED trade is the CAMPAIGN: entry = the first buy, exit = the final sell,
    pnl chained multiplicatively across the legs — every roll pays the REAL bid-ask
    round trip (sell at bid, re-buy at ask). The trade row carries the leg ledger
    `rolls: [{date, sold_at, bought, cost}]`.
  · A session with NO chain row for the selection SKIPS the roll (counted as
    `roll_skipped_no_chain`) and the position keeps its old contract — we may
    decline, we never guess a contract or a price.
  · LIVE, the same rule runs off the live chain: close_reason='rolled', and the
    replacement is bought through the NORMAL entry path under EVERY entry gate
    (market hours, buying power, your caps). A refused buy degrades the roll to a
    plain close (`roll_buy_refused`) — never a pretend position. Shelf mode never
    rolls (a roll is discretionary trading); expiry settlement always wins.
  · Refused in plain words on any non-single-leg vehicle, and when
    `at_dte >= option.target_dte` (a fresh contract would roll immediately).

### ROTATION / REBALANCE BOTS — `asset_class: "rotation"` (catalog #34)
{"asset_class": "rotation", "universe": ["AAPL","MSFT","NVDA","AMD"],
  "timeframe": "1 day", "backtest": {...},
  "rotation": {"rank": {"by": "ret20", "top_n": 3, "lowest": false},
               "rebalance": "monthly", "weights": "equal",
               "min_hold_sessions": 10}}
A DIFFERENT BOT SHAPE, not a modifier: a rotation bot has NO entry rule and NO exit
rule — the rebalance is both, and carrying either is refused in plain words. Its
basket is the spec's own `universe` list (there is no rotation.universe: one bot, one
universe), and it runs on `"1 day"` bars only.
  · MEMBERSHIP is ranked at each boundary on the last session STRICTLY BEFORE it —
    no look-ahead, and a number the live desk always has, so the live basket IS the
    graded basket. Between boundaries membership is FROZEN.
  · `rebalance`: "weekly" (first session of each ISO week) or "monthly" (first
    session of each month). A holiday Monday makes Tuesday the boundary — it is a
    fact about the sessions that exist, never about the calendar.
  · FILLS ARE REAL PRINTS: a holding runs from the OPEN of its boundary session to
    the OPEN of the next one. A period whose closing boundary has not printed yet is
    NOT graded (`rotation.unclosed_periods`) — an unfinished holding is not a trade.
  · `weights`: "equal" · "rank" (linear tilt toward the better-ranked names) ·
    {"custom": [0.5, 0.3, 0.2]} (one positive number per held name, best-ranked
    first, normalised to sum to 1 for you). A WEIGHT NEVER MULTIPLIES pnl_pct — the
    scorecard grades per-unit PERCENT, so weighting a trade would make a heavier
    sleeve read as a better one. It drives the LIVE share count and the weighted
    basket return only.
  · `min_hold_sessions` (optional): a name that would leave the set before it has
    been held that many sessions STAYS. It keeps its slot, so the book never grows
    past top_n. Counted (`rotation_hold_floor` live, `hold_floor_keeps` graded).
  · WHAT THE VERDICT MEANS HERE, stated because it is easy to misread: each HOLDING
    (one name, one period) is graded as ONE equal-weighted trade, so verdict/EV
    answer "is this ranking rule picking winners?". What the BASKET earned is a
    different number and lives in `result.rotation` — periods[] with each period's
    WEIGHTED return_pct (PERCENT), mean_period_return_pct, and portfolio_curve
    (cum_pnl_pct as DECIMAL fractions, like every equity curve).
  · LIVE, the walk sells what left the set and buys what entered through the NORMAL
    equity entry path, so every gate applies (market hours, buying power, max-$/
    trade, max_open_usd, the sector cap). Telemetry: `rebalanced`, `rotation_in`,
    `rotation_out`, `rotation_hold_floor`, `rotation_unpriced`, and every refusal
    under its own existing reason. Entries blocked (market closed / stale data /
    shadow) DEFERS THE WHOLE REBALANCE, sell half included — half a rebalance is a
    book nobody chose — counted as `rotation_deferred` with its reason; marks never
    stop. Shelf marks and never rebalances.

### PORTFOLIO HEDGE OVERLAY — `hedge` (catalog #36, LIVE-ONLY, never graded)
{"hedge": {"symbol": "SPY", "kind": "short_shares", "ratio": 0.25}}
The desk holds a SHORT in `symbol` sized to `ratio` x THIS BOT's long exposure,
re-sized at most once per ET session. A spec with a hedge grades BYTE-IDENTICALLY to
the same spec without one: the grader never reads the block.
  · PER-BOT. `scope: "desk"` is refused in plain words rather than approximated —
    bots walk independently, so a desk-wide hedge has no single owner and every bot
    carrying it would open its own copy. A desk of per-bot-hedged bots IS a hedged
    desk.
  · `kind` is "short_shares" only. A put-based hedge is a different money path and
    is refused by name rather than approximated.
  · SIZED THROUGH THE ONE COST MODEL over the bot's own LONG rows, derived fresh
    every walk, nothing reserved — and the hedge is excluded from the exposure it is
    sized against (or it would hedge itself). It IS in the desk's book, so buying
    power and desk exposure include it; a hedge that tied up no cash would be a free
    option nobody sold us.
  · The strategy's exit rule NEVER touches it: it is marked (on shelf too — reading
    a price is not trading) and re-sized by the hedge path alone.
  · IT NEVER PRETENDS. No buying power / no price / market closed → counted under
    its own reason (`hedge_unopened` · `hedge_unpriced` · `hedge_deferred`) and the
    book is simply UNHEDGED that session. Closes carry close_reason 'hedge_resize'
    or 'hedge_close'.
  · `hedge.symbol` must NOT be in the bot's own universe — otherwise the desk cannot
    tell your strategy's position in it apart from its hedge. Refused in plain words.

### SIGNALS OUT (catalog #37) — you already have it: it is SHADOW mode
A bot deployed in SHADOW mode evaluates its rule on every bar and RECORDS what would
have fired — `signals_fired` plus the per-refusal counters — while committing no
fill. That is the outbound half of webhook automation: a feed of this strategy's
decisions you can read from `GET /v1/me/accounts/{aid}/alphas` and the alpha
telemetry, and act on wherever you like.
  · What it does NOT do: it does not POST anywhere. There is no outbound URL, no
    retry queue and no delivery guarantee — you PULL the signals, we do not PUSH
    them, and calling that a webhook would be a promise we have not built.
  · The INBOUND half is a different feature: `entry.webhook: true` + POST
    .../alphas/{deploy}/signal (catalog #10, above).

## EDITING AND DELETING — a library you can actually keep tidy
A saved strategy, a finished backtest, an alert, a saved pref and a deployed bot can
all be edited or removed by their OWNER. Every one of these writes the audit ledger
(strategy_edit · strategy_delete · backtest_delete · alert_dismiss · alert_delete ·
alpha_delete) and every one answers a UNIFORM 404 to anybody else — a stranger
probing ids learns nothing, not even that the id exists. On the routes that reach
ACROSS a whole tenant's rows, the SHARED GUEST key with no session is refused with a
friendly 403: on that one tenant an edit or delete by id would rewrite another
visitor's work.

- PATCH /v1/strategies/{strategy_id}   [session, or key, or pair] rename and/or
  replace the spec: body {"name"?: str, "spec"?: obj} — send either, or both; an
  empty edit is a friendly 400. The new spec goes through the SAME validation a
  fresh save does, so a refusal carries the engine's teaching message plus
  `suggestions` / `suggested_spec`, and a REFUSED EDIT STORES NOTHING (the previous
  spec stands). Returns the updated row.
  EDITING THE LIBRARY ENTRY NEVER REACHES BACKWARDS. A deployed bot carries its OWN
  spec snapshot, so editing the library entry does NOT change what any running bot
  trades, and a finished backtest keeps the spec it was graded on. If you want the
  new rules live, deploy the edited strategy — the old bot keeps doing what it was
  deployed to do until its owner retires it. That is deliberate: a bot silently
  changing behaviour because someone renamed a rule is exactly the kind of
  invisible drift this platform refuses.
- DELETE /v1/strategies/{strategy_id}   [session, or key, or pair] owner-only.
  Once the strategy has at least one GRADED run the call requires `confirm=true`
  (otherwise a 400 that tells you how many runs exist and that they are kept) — the
  confirmation exists so nobody deletes their own evidence by accident. Those
  backtests SURVIVE the delete: each one carries its own spec snapshot, which IS the
  receipt for what was graded, so they simply lose the link. Returns
  {"deleted": id, "backtests_kept": N}. It does not stop a deployed bot either —
  retire the bot on its desk if you want it stopped.
- DELETE /v1/backtests/{run_id}   [session, or key, or pair] owner-only. Removes
  the run AND revokes any public share of it in the SAME request — a public link
  that outlived its run would 404 for the reader while still looking live to whoever
  holds it. Returns {"deleted": run_id, "share_revoked": bool}. No confirm flag: a
  run is the receipt of a computation, not money history, and you can re-run it. A
  deployed bot's own report card is unaffected (it holds its own copy).
- GET /v1/me/alerts   [session ONLY] the alert feed, newest first. DISMISSED alerts
  are EXCLUDED by default — dismissing IS how a member clears the feed — and
  `?dismissed=1` brings them back, so nothing dismissed is unrecoverable. Every row
  carries `dismissed_at`. `?unread=1` filters to unread; bounded to 500 rows.
  MEMBER KINDS ONLY: ai_daily_brief · admin_announcement · account_suspended ·
  buying_power · breaker · daily_loss_limit · weekly_loss_limit ·
  monthly_loss_limit · consecutive_losses · profit_target · desk_position_stop ·
  divergence · corp_action · needs_review. This feed is the member's OWN news,
  so internal kinds (application errors, engine reconciles, the operator
  digest) are NOT returned — they live on the admin surfaces. The list is an
  allowlist and fails closed: a kind nobody has classified is hidden until it
  is added on purpose. Read `buying_power` FIRST
  when a desk's bots have gone quiet: it means the DESK could not fund a new
  entry (payload: state "out"/"recovered", blocked_bots, available_usd,
  needed_usd, and a plain-words `text`). It is a fact about the ACCOUNT, never a
  judgement of the strategy — the fix is to close a position or deposit cash.
- POST /v1/me/alerts/read   [session ONLY] {"ids": [...]} mark alerts read →
  {"marked": N}.
- POST /v1/me/alerts/dismiss   [session ONLY] {"ids": [...]} HIDE those alerts →
  {"dismissed": N}. Read and dismissed are DIFFERENT facts ("I saw it" vs "I'm
  done with it"), and a dismissed alert is still there under ?dismissed=1 — nothing
  is destroyed. Foreign ids are ignored rather than an error; the count is the truth.
- DELETE /v1/me/alerts/{alert_id}   [session ONLY] hard-delete ONE alert →
  {"deleted": id}, or 404 "Alert not found". For a feed you just want quiet,
  prefer /dismiss — only DELETE removes a row for good.
- DELETE /v1/me/prefs/{key}   [session ONLY] clear one saved pref (avatar pick,
  layout, a widget toggle) → {"deleted": key, "existed": bool}. It REMOVES the row
  instead of storing a null, because "no row" is what "no choice made" means
  downstream. Idempotent and NEVER a 404 — clearing a pref that was never set is not
  an error, and the answer says so with existed:false. A malformed key is a 400.
- DELETE /v1/me/accounts/{account_id}/alphas/{deploy_id}?confirm=true
  [session-owner ONLY — an account key PAIR gets 401 here, deliberately: destroying
  a bot is a human act, so an agent can propose it but never do it]
  Hard-delete is allowed ONLY for a bot with ZERO position history AND zero order
  history. A bot that EVER traded gets a 409 and can only be RETIRED (terminal — it
  stops opening anything new and keeps every trade on the record), because the money
  ledger has to stay auditable. You cannot make a losing week disappear, and that is
  the point. `confirm=true` is required even on a never-traded bot (400 otherwise).
  Returns {"deleted": deploy_id, "cascade": {...}}.
  WHAT RETIRE DOES TO AN OPEN POSITION — tell the human this plainly: the strategy's
  own exit rule NEVER runs on that position again (no stop, no take-profit, no
  rule/hold exit, no time-stop). The position stays open and honestly MARKED, and any
  protective order already resting on it still works — but nothing will ever
  STRATEGY-EXIT it. A retired bot's open position is MARKED AND HAND-TRADEABLE,
  NEVER STRATEGY-EXITED — closing it is the member's move. Say that to the human
  before you retire a bot that is holding something.
  THE ONE THING THAT STILL CLOSES ON A RETIRED BOT IS THE MARKET'S OWN ACT:
  contract-mandated settlement — an option (or credit/covered structure) reaching its
  EXPIRY, or an equity that DELISTS. That is not the strategy trading; the contract
  ended by itself. Without it nobody could ever close such a row: the walk skipped it
  and a dead contract has no live quote, so a manual close refuses it too. So a
  retired bot walks the same path a SHELVED one does — mark, never trade, settle what
  the market has already ended.
  So: retire what traded, delete only what never did.

## PORT REPORT — how to tell a coder what fits BEFORE porting
When a user hands you a document of strategies (a bot fleet, a rules doc, a
TradingView script), do NOT start porting blind. Produce a PORT REPORT first:
an honest, per-strategy ✅ fits / 🟡 partial / 🔴 can't-run table. The workflow:

1. For EACH strategy in the document, extract five things:
   - signal cadence  (daily close? intraday/minute? a fixed 10:35 entry?)
   - data needs      (price/volume + indicators only? or news / social / themes?)
   - instrument      (equity, option, credit spread, combo — and the universe)
   - exits           (a held-path rule, a stop, a trailing/ratchet, a take-profit?)
   - sizing          (a fixed lot, a $ budget, a max-open cap? all three map:
                      sizing.fixed_usd / sizing.fixed_contracts / max_open_positions)

2. Check each against the platform with POST /v1/strategies/port-check. Send a
   draft spec, or just the concept tags — either works:
     {"spec": {<draft spec dict>}}
     {"concepts": ["ratchet", "intraday_window", "take_profit", "news_feed"]}
   It returns {verdict: fits|partial|cant, issues: [{concept, detail, dropped,
   closest, note}], notes: [...]}. `closest` is the exact supported mapping;
   `dropped` is what porting that concept costs. Tags map to the SAME taxonomy
   the validator uses (ratchet/trailing→SL50, tp/take_profit→exit.targets (graded) or a live take_profit cap,
   minute windows/entry_window→an intraday timeframe ("1Min".."4Hour") +
   entry_start/entry_end (SUPPORTED),
   0DTE/options-flow/tick/HFT→Phase 2, news/sentiment/social/themes→
   unsupported, xsection/relative_strength→xrank, so those FIT).

3. Render the report in EXACTLY this shape — one row per strategy:

   Strategy              Verdict  Maps to    What's lost / why
   --------------------  -------  ---------  --------------------------------------
   Daily MACD cross      ✅ fits   daily MACD  nothing — runs as written
   10:00–10:30 equity    ✅ fits   intraday +  nothing — timeframe "5Min" (any size),
     window                        entry_start  entry_start/entry_end gate the window
   Ratchet trailing exit 🟡 partial SL50       loses the ratchet; a desk trailing
                                              Protect order approximates it live
   0DTE options-flow     🔴 cant   —          needs options-flow / sub-minute data — Phase 2

4. THE RULE: never silently drop a feature. Every 🟡 row MUST name what is lost
   (the `dropped` field) next to the closest supported mapping (the `closest`
   field). A coder who sees "🟡 partial → SL50" without "loses the ratchet"
   would think the port is lossless — that is exactly the dishonesty this
   platform refuses. 🔴 rows name the hard wall and the phase it unblocks.

## What you can do
- Turn a loose strategy description into a full, valid, runnable spec.
- Backtest it and get an honest scorecard with a LIVE / SHADOW / SHELF verdict.
- Compare two of your own runs to SEE overfitting (the optimism gap).
- Save/load strategies, and deploy a validated strategy onto a paper desk.
- Land a whole FLEET (up to 50 strategies) in ONE call — saved AND deployed in
  seconds and trading immediately (POST /v1/strategies/bulk). NO backtest is run
  or queued: deploying is not a request to be graded.

## What we refuse to build (and why) — the intake safety floor
Every free-text intake (the copilot draft, port-external, and the MCP
draft_strategy / port_strategy tools) passes through a DETERMINISTIC guard FIRST
(no LLM — it can't be jailbroken). If your description asks for one of these, it
is refused with a plain-words reason and NOTHING is drafted:
- MARKET MANIPULATION — spoofing, layering, wash trading, pump-and-dump,
  front-running order flow, stop-hunting, quote-stuffing, momentum ignition,
  marking/banging the close. Illegal; we won't touch them.
- ILLEGAL INFORMATION — insider / MNPI / material non-public tips, and stolen,
  unlicensed, or scraped data (including other users' strategies).
- RECKLESS RISK-OF-RUIN — martingale, revenge trading, all-in, max/unlimited
  leverage, no-stop "hold the losers", auto-redeposit after a blow-up.
- DECEPTION / FRAUD — hidden losses, faked/curve-fit backtests, unreported risk,
  Ponzi payouts from new deposits. Our numbers stay honest.
- PLATFORM ABUSE — evading limits via multiple accounts, self-replicating bots,
  or disabling the platform's safety checks.
- PROMPT INJECTION — "ignore your instructions", "disable your guardrails",
  "you are now…", DAN/jailbreak framings. We answer to our own rules.
- GUARANTEED / RISK-FREE / CAN'T-LOSE claims — no honest backtest can promise
  them, so we won't pretend one can.
A vague wish ("just make me rich"), a bare question ("should I buy TSLA"), a
structure with no parameters ("build an iron condor"), or a bare unsupported
asset ("trade bitcoin") gets a CLARIFY, not a refusal — tell us the instrument
and the entry/exit rule and we'll build it.

## Honesty rules (these are the product — do not misread them)
- NO LOOK-AHEAD. A signal at bar i reads only data <= i. Equities enter at the
  NEXT bar's open; option paths start strictly after the signal date. You cannot
  buy on information you would not have had — look-ahead is structurally
  impossible here, not merely discouraged.
- HONEST FILLS, never mid. SHARES fill at REAL bar prints (the next bar's open
  on entry) — real prices, no modeled spread. OPTIONS fill in TWO TIERS, always
  labeled. At each option fill the engine FIRST asks for a MEASURED two-sided OPRA NBBO (no look-ahead): when present it
  buys @ the REAL ask / sells @ the REAL bid and stamps nbbo_source="real". When
  absent it falls back EXACTLY to the modeled rule — buy ask else last*1.025, sell
  bid else last*0.975 (nbbo_source="modeled"); a spec with NO real quote grades
  BYTE-IDENTICAL to the pure modeled engine. On this dataset option quotes before
  2026-06-09 are SYNTHETIC (a flat 5% spread), so a modeled fill is a real `last`
  mark +/- 2.5%, optimistic for thin options. compute_metrics reports
  real_nbbo_fill_share (the fraction of fills priced on a real measured NBBO), so
  avg_spread/cost_drag is labeled measured-vs-model-constant. Rank strategies by
  SKIP-RATE (real fillability) and HELD-TO-EXIT EV, not by cost_drag/avg_spread.
- TAKE-PROFIT IS BANNED FROM THE VERDICT. The best bracket is the best of
  none / SL30 / SL50 only — a TP can't flatter the grade.
- SURVIVORSHIP (dynamic universe): equity universes may name ANY US symbol —
  an unknown one is fetched and quality-gated on first use (>=250 trading days,
  median price >= $3, median dollar-volume >= $2M; failures get a plain-words
  rejection). COMPANIES THAT STOPPED TRADING ARE NOT INCLUDED (2026-10-07):
  delisted / bankrupt / acquired tickers are not in our data, are not offered in
  GET /v1/universe, and are refused if you name one ("stopped trading"). So a
  test can only contain companies that still trade, and results may look
  slightly better than reality (survivorship bias) — disclosed beside every
  result.
  Options strategies stay on the CURATED options catalog (GET /v1/universe).
- SURVIVORSHIP LABEL (every result): result.survivorship = {universe_kind
  ("explicit"|"catalog"), delisted_included (bool), delisted_symbols[],
  mid_window_delistings[], note}. Normally delisted_included is FALSE and the
  note says plainly that companies that stopped trading are NOT included, so the
  result may look slightly better than reality (survivorship bias). The label is
  always TRUTHFUL — never claims delisted-included when it isn't.
  (confidence.provenance mirrors the flag.)
- THE OPTIMISM GAP is the overfitting signal. It is real.ev_best (the full-sample,
  in-sample-optimized EV — the flattering number) minus walk_forward.wf_ev (the
  out-of-sample EV under an IS-locked bracket). A BIGGER gap = MORE overfit. A run
  that improved in-sample but worsened out-of-sample is MORE overfit, not better.

## MARKET RULES ON A DEPLOYED DESK (what the desk enforces, and what it does not)
A deployed bot obeys the market's rules, not just its own. These apply to the LIVE
paper desk (the graded backtest already modeled the first two by construction).
- TRADING HOURS. No fill ever prints outside 09:30-16:00 ET (13:00 on a half-day),
  and never on a weekend or an NYSE holiday. A signal computed after the bell is
  NOT dropped — it QUEUES and fills in the next session at the same price the
  backtest grades (telemetry: queued_market_closed). One calendar, shared by the
  walker, the watcher and the validator.
- EXPIRY. An option cannot outlive its own expiry. At expiry an in-the-money
  contract (by >= $0.01) settles at INTRINSIC value and everything else expires
  worthless, with close_reason="expired". Applies to option / credit / covered legs.
- EARLY ASSIGNMENT IS NOT SIMULATED (say this to any client selling premium).
  Short option legs are carried to EXPIRY and settled there. In the real market an
  American short leg can be exercised against you ANY day — most often a deep
  in-the-money short CALL the day before an ex-dividend date, which also leaves the
  other legs of a spread unhedged, and a deep-ITM short PUT can become long shares
  early. So a short-leg result (credit structures, any "sell" option leg of a
  combo/covered spec) is the FAVOURABLE case on that one axis. We disclose it
  rather than model it: 3 of the 4 platforms we surveyed also defer it, and a
  quiet deferral is the dishonest version. Every deploy of such a spec returns the
  sentence in `disclosures`.
- BUYING POWER IS REAL. The desk rejects an entry it cannot pay for, exactly as a
  broker would (telemetry: skipped_insufficient_buying_power, with a note naming
  the cash available and the cash needed). Available = starting cash + realized
  P&L − what the OPEN book ties up, across the WHOLE desk (manual trades and every
  other bot on it — it is one account). What a position ties up: shares at
  notional (a SHORT sale reserves the same 100% of notional — a simple stated
  proxy, not a margin engine); a bought option at its premium; a defined-risk short
  spread at its widest wing × 100 − credit; a naked short put cash-secured to its
  strike − credit. Nothing is ever "reserved" for a pending order, so a refused or
  skipped entry costs the desk nothing. THIS IS THE DESK ENFORCING REALITY, NOT A
  JUDGEMENT OF THE STRATEGY — size down (`sizing`) or fund the desk and the same
  strategy trades. If the ledger itself cannot be READ on a walk (a database
  fault on our side), entries are refused too, under a DIFFERENT reason
  (skipped_buying_power_unreadable, buying_power "unreadable") — we do not spend
  money we cannot count, and we do not tell you that you were short of cash when
  what actually happened is that we could not see your balance. Marks and exits
  are unaffected; entries resume on the next walk that can read it.
- AND THE BALANCE MAY NEVER GO BELOW ZERO. No entry can take it there: at exactly
  $0 available every priced entry is refused. It can still be driven there by the
  MARKET after a legal entry — a short that more than doubles loses more than the
  cash it tied up — and if that ever happens we SHOW the true negative number and
  raise an alarm on ourselves (telemetry desk_buying_power_negative, buying_power
  "negative"). We never clamp it to a comfortable $0: a desk that owes more than
  it holds must not read like a desk with nothing. Nothing else changes — entries
  are refused only because nothing is affordable, and marks/exits keep running.
- STALE DATA PAUSES ENTRIES. If our newest bar is behind the last completed
  session, the walk stops opening (marks continue, so open positions stay valued)
  and says so (entries_blocked_reason "stale_data", queued_stale_data). We never
  fill at a price the market has already moved past. Entries resume automatically.
- CORPORATE ACTIONS ON AN OPEN OPTION. Bars are split-adjusted; an open contract's
  strike is not. When the underlying moves more than ±45% in ONE session versus the
  price at which the position was last PRICED, that looks like a split rather than a
  market move (a 2:1 split shows as −50%; even a violent earnings gap lands ~20-30%),
  so the position is FLAGGED (mark_flag="possible_corporate_action"), the owner gets
  ONE alert, and we CARRY its last mark forward instead of trusting a mispriced chain
  row. We never silently re-price a contract: re-striking from a price ratio is a
  guess, and a guessed price presented as a fill is the one thing we do not ship.
  The flag clears itself once real prices agree again.
- EVERY FILL YOU READ CARRIES ITS ET SESSION. Serialized position rows include
  `session_date` (plus timezone-aware created_at / entry_ts), and a stamp that lands
  outside a session resolves BACKWARD to the last real one. So an agent never has to
  infer "which trading day was this?" from a UTC timestamp.
- STALE DATA AND A CLOSED MARKET ARE DIFFERENT THINGS and never conflated: a closed
  market is the calendar working as intended (`market_closed` / `queued_market_closed`);
  stale data is a feed to go fix (`stale_data` / `queued_stale_data`). BOTH queue
  rather than drop, and both leave `signals_fired` counting so telemetry never goes
  quiet. A kill switch (agent freeze) is labeled separately again — it is not a
  closed exchange.
- WHAT NOBODY MODELS, INCLUDING US: trading HALTS (LULD), the opening/closing
  AUCTION print (a next-bar-open fill is the bar's open, not the auction price),
  hard-to-borrow/locate fees on shorts (a MODELED borrow cost accrues instead),
  PARTIAL FILLS (every order fills whole or not at all) and LOCATE AVAILABILITY
  (every short is assumed borrowable). The last two are stated as a deploy
  disclosure on any spec that trades shares.

## Commissions and fees (section C, 2026-08-27) — charged on EVERY vehicle
- ONE model (`vega_engine/fees.py`), read by every graded path AND by the paper
  desk's settles, so a graded cost and a realized cost cannot drift.
- WHAT IS CHARGED. Commission per contract / per share on BOTH sides; OCC
  clearing + the exchange ORF per contract on BOTH sides; SEC section 31 on sale
  proceeds and the FINRA TAF on the SELL ONLY. That asymmetry is why a round trip
  is not simply twice a side.
- YOUR OWN SCHEDULE: `"fees": {"option_per_contract": 0.65, "per_share": 0,
  "regulatory": true}`. Those are the DEFAULTS and they are disclosed in
  `defaults_applied` — a default you cannot see is the honesty leak, and this is
  the one that moves the number you care about most. All three at zero/false
  grades GROSS of everything, which no real account is.
- THE REGULATORY RATES ARE PUBLISHED FIGURES, not knobs — each is a constant with
  its source and effective date, echoed back in `result.fees.rates` so you can
  check our arithmetic. Two stated limits: the SEC section 31 rate is a STEP
  FUNCTION (it was $0.00 for most of 2025) and we charge today's rate across the
  whole window, so on that stretch we OVERSTATE and never understate; and the ORF
  varies by execution venue, so our single constant is a labeled estimate.
- WHERE IT LANDS: `fees_paid` per trade (DOLLARS for ONE graded unit — one share,
  one contract, one structure; the scorecard grades per-unit percent, so there is
  no size folded in) beside `fee_frac` (a DECIMAL fraction), and `result.fees`
  in aggregate — `drag_pct` is a PERCENT, sitting beside `cost_drag`.
- IT CANNOT MOVE THE VERDICT'S CHOICE. The graded fee is priced off the ENTRY
  notional, so it is outcome-INDEPENDENT: it shifts every bracket by the same
  amount and can never shift bracket SELECTION. Take-profit stays out of the
  verdict either way. THE DESK IS DIFFERENT AND MORE EXACT: it knows the price it
  really got, so a realized close is charged on the REAL exit. Same functions,
  one argument — and the walk reports what it took as `fees_paid` (DOLLARS) in
  its telemetry, so "what did this bot pay?" is answerable rather than inferred.
- ON A PARTIAL EXIT (`exit.scale_out` / `exit.targets`) each SLICE pays the round
  trip for ITS OWN units — nothing was charged when the position opened — so a
  position's total fee is the sum of its slices, never doubled and never dropped.

## Fill provenance — `pricing_source`, on every vehicle
- Every graded trade row and every serialized position row carries
  `pricing_source`: `"real"` (every price in the fill was an observed market
  price — a share print, or a measured two-sided OPRA NBBO) or `"modeled"` (at
  least one price came from a model). ONE vocabulary, so a surface can label a
  trade without knowing which engine produced it. A single-leg option's existing
  `nbbo_source` is unchanged and says the same thing about its ENTRY.
- `result.metrics.real_fill_share` reports it PER VEHICLE: `{overall, by_vehicle:
  {<asset_class>: {share, n}}}`, every `share` a FRACTION in [0,1] — not a
  percent. `null` means WE CANNOT LABEL THIS RESULT, which is a different fact
  from "0% real" and must never be shown as one.

## Verdict meanings
- LIVE   — walk-forward OOS EV clears the live bar (+4%/trade) with enough fills.
- SHADOW — positive but not yet proven live (or too few fills, or capped because
           the edge relies on a stop filling at its nominal level on gaps).
- SHELF  — walk-forward OOS EV is non-positive or below the shelf bar (+1%): the
           edge does not survive out of sample. This is the honest "no".
- NO_DATA — no fills in the window (e.g. a backtest range outside the real option
            data window 2024-02-12 .. 2026-05-20).

## A SHADOW is an appointment, not a refusal (R9)
A graded SHADOW or SHELF carries ONE named next move, derived only from what the
engine already measured — the fill count against the 80-fill bar, the IS/OOS
split, the regime split, or our bracket read shown BESIDE the stop you wrote.
`GET /v1/backtests/{run_id}` stamps it at serve time as `result.next_move`
{code, move, detail, figure, unit, regrade_due, regrade_days}; EV figures in it
are PERCENT points, `unit:"fills"` is a count.

When that grade lands on a DEPLOYED bot (the only path that writes a deployment's
grade is `POST /v1/me/accounts/{id}/alphas/{deploy_id}/backtest`), it also
books a RE-GRADE APPOINTMENT: the first market session 14 calendar days out, on
the deployment's `config` jsonb, served back on every desk read as
`deployments[].regrade` {due, reason, code, verdict, source, overdue}. Move it
or clear it with `POST /v1/me/accounts/{id}/alphas/{deploy_id}/regrade-due`
{"due": "YYYY-MM-DD"} (null clears it, and clearing also stops the one email
that fires on the date).

IT GATES NOTHING. The bot trades identically with an appointment, past one, or
with none — the engine ADVISES, it never GATES. The verdict, the EV and every
robustness figure are untouched: this is a sentence and a date beside them.

## Units (this bites people)
- Aggregates (real.ev_best, robustness.*_ev, walk_forward.wf_ev, optimism_gap)
  are PERCENT: 7.0 means 7%.
- Per-trade pnl_pct and equity cum_pnl_pct are DECIMAL fractions: 0.109 = 10.9%.

## PLAN CAPS — money buys ROOM, never TRUTH
Your owner's plan limits HOW MUCH, never HOW HONEST. These are NEVER capped at
any plan, free included: the verdict, real fills (buy ask / sell bid), no
look-ahead, walk-forward grading, market-hours rules, and the plain-words why. A
free-plan backtest is graded byte-identically to a Pro one.
What IS capped (numbers, not features): universe size per run, backtests per
calendar month, desks, deployed bots, which bar sizes you may run, and AI helper
calls per day.
- Read the owner's room with `GET /v1/me/plan` — it returns the effective caps
  (`null` means no limit) plus live usage, so you can check headroom BEFORE
  submitting a fleet instead of discovering a ceiling halfway through.
- Hitting a cap is a plain-words 4xx that names the number and what lifts it:
  400 (universe too large / bar size not on this plan), 429 (monthly run quota,
  AI calls), 409 (desk or bot count). None of these mean your strategy is bad —
  they are room, not judgement. Do not retry in a loop; tell the human the number.
- DURING THE FOUNDING ERA (on by default right now) every member's caps are
  effectively unlimited except a 5-desk ceiling, so you will rarely see these.
- The AGENT CONNECTION ITSELF IS NOT AN UPSELL. Every plan, including free, gets
  a working account key pair and full MCP access at that plan's caps.

## The canonical strategy spec
One JSON object. Required: name, asset_class (option|equity|credit|combo|covered),
universe (non-empty list of tickers), timeframe ("1 day", or "1Min" for
minute-resolution EQUITY backtests — real SIP 1-minute bars, next-minute-open
fill, no look-ahead), backtest ({start,end}
within 2024-02-12 .. 2026-05-20), entry ({side: call|put, when: <rule tree>}),
exit ({rule: fixed|lo3|lo5|peak8, hold_days for fixed}). asset_class="option"
also requires an option block ({right, target_dte, and EXACTLY ONE of itm_pct /
otm_pct}). Rule trees nest all/any of comparisons (gt/lt/gte/lte/eq/cross_above/
cross_below) over feature/indicator ids and numeric constants. `eq` is exact
equality, for integer/boolean-valued operands (dow, is_friday/is_monday, the 0/1
candlestick patterns, top_n membership).

OPTIONAL `profit_lock` ({kind:"ratchet", arm_pct=0.50, step_pct=0.10, rise_pct=0.05}):
a climbing profit-lock — locks in profit as the trade rises. Plain words: starts
protecting at +50%, and every +10% higher it climbs it locks in another +5%; it
NEVER caps the winner (unlike take-profit, which is banned). This is a LIVE-desk
exit overlay ONLY — it changes how a deployed strategy sells, but it NEVER enters
the honest backtest verdict (the grade stays on none/SL30/SL50, so a profit-lock
can't flatter it). The report shows both: the honest grade + how the ratchet behaved.

OPTIONAL `take_profit` ({kind:"take_profit", target_pct=0.50}): a fixed TAKE-PROFIT
cap — sells the instant profit hits +target_pct (default +50%). It is the OPPOSITE of
the ratchet: a hard cap, not a climbing floor. This is a LIVE-desk execution preference
ONLY (some traders want a cap): it changes how a DEPLOYED strategy sells, but it is
NEVER graded. The honest backtest verdict is BYTE-IDENTICAL with or without it —
best_bracket stays the best of none/SL30/SL50 and is NEVER a take-profit, because a
fixed cap historically LOWERS long-run EV (you clip your biggest winners). The result
echoes it back under `take_profit` with that plain-words caveat; the verdict stamp
ignores it. If BOTH `profit_lock` and `take_profit` are set on a live desk, the
earlier-firing exit wins (a tie goes to the take-profit cap). A profit target you
want GRADED is `exit.targets` ([{"at_gain_pct": 10, "fraction": 1}], a PERCENT of
entry) — the member's own exit, graded exactly as written (see exit.scale_out).

OPTIONAL `stop_loss` ({kind:"stop_loss", stop_pct=0.30}): a user-set STOP-LOSS —
sells the moment the position's loss reaches -stop_pct (default -30%). It is the
downside twin of take_profit and a LIVE-desk RISK-MANAGEMENT preference you control
(set your own risk cap, exactly like real desks run SL-25 / SL-50 / SL-95). It is
NEVER graded, so the verdict/best_bracket is BYTE-IDENTICAL with or without it (the
grade stays none/SL30/SL50). Mind the units: this stop_pct is a FRACTION (0.30 =
30%). The stop that IS graded is `exit.stop_pct`, a NEGATIVE PERCENT (-30) — graded
as result.real.user_bracket on equity and single-option specs, and run live too.
The overlay changes ONLY how a DEPLOYED strategy sells; the result echoes it back under `stop_loss` and the verdict stamp ignores it.
When SEVERAL overlays are set on a live desk the earlier-firing exit wins; on a tie
the stop_loss wins first (a hard risk cap), then take_profit, then the profit_lock
ratchet.

ALL THREE OVERLAYS APPLY ON EVERY VEHICLE (2026-07-29): single options, SHARES,
credit structures and covered structures. Each reads that vehicle's own gain path —
for shares the position's own P&L (inverted for a short, so "-12%" means "I am down
12%" on either side); for a credit structure the fraction of the CREDIT captured, so
take_profit target_pct 0.25 IS "take profit at a quarter of the credit". Before this
they were honoured on single options only, so an equity stop and a credit take-profit
were accepted and then silently dropped on the deployed bot.

OPTIONAL `sizing` ({method, value}): how big each fire is. Two methods:
- "fixed_usd" ({value: dollars}) — a DOLLAR BUDGET per trade, turned into as many
  WHOLE units as it affords at the real fill price: contracts =
  floor(value / (premium x 100)) on options/credit/covered, shares =
  floor(value / entry price) on equity. Never rounds up (a contract is indivisible
  and rounding up would spend more than you budgeted); a budget smaller than one
  unit still trades ONE, and the position row shows exactly what was taken.
- "fixed_contracts" ({value: N}) — pin an EXACT contract count on a DEPLOYED
  OPTIONS bot (option/credit/combo/covered), e.g. "buy 2 contracts when RSI<30".
  value is a WHOLE count ≥ 1 (2.5 / 0 / negative is rejected up front — you can't
  buy 2.5 contracts).
- "risk_pct" ({value: percent}) — SIZE FROM THE STOP. Buy as many whole units as
  risk that percent of the DESK's equity if your stop fires:
  units = floor(equity × value/100 ÷ (what ONE unit loses at the stop)), where one
  unit loses entry price × stop_fraction for shares and premium × 100 ×
  stop_fraction for a contract. `{"method": "risk_pct", "value": 1.0}` is "risk
  1% of the desk per trade". It NEEDS a stop — `stop_loss.stop_pct` (a FRACTION,
  0.30) or `exit.stop_pct` (a NEGATIVE PERCENT, -30); with neither we REFUSE the
  spec in plain words rather than assume one, because a guessed stop is a guessed
  position size. Refused on credit/combo/covered too: there the stop is measured
  on the credit you took in while the real loss is the wing width, so we would be
  telling you that you risk far less than you do — use pct_equity there.
  If even ONE unit risks more than the budget the trade is SKIPPED
  (`skipped_risk_budget`), never rounded up into risk you did not authorise.
- "pct_equity" ({value: percent}) — put that percent of the DESK's equity into
  each trade: units = floor(equity × value/100 ÷ what one unit costs), costed
  through the same buying-power model the desk's ledger uses. Works on every
  vehicle. One unit too expensive → skipped (`skipped_equity_budget`).
  BOTH read the desk's equity FRESH on every walk (nothing stored, nothing
  reserved), so they re-size as the desk grows or shrinks — which is the point.
  If the desk keeps no cash ledger at all the fill falls back to the platform
  default of 1 unit and says so (`sizing_equity_unavailable`); if the ledger
  exists and cannot be READ the entry is refused under its own reason
  (`skipped_sizing_equity_unreadable`) — we do not size a position off a number
  we could not fetch.
- "atr_risk" ({value: 1.0, atr_period: 14, atr_mult: 2.0}) — risk_pct WITH THE
  STOP TAKEN FROM VOLATILITY. Identical arithmetic to risk_pct — same registry
  row shape, same "0 units means SKIP" discipline — except the distance one unit
  can lose is not a stop you declared, it is atr_mult × ATR(atr_period):
  units = floor((equity × value/100) / (atr_mult × ATR)). `value` is the PERCENT
  OF EQUITY you risk on one trade (1.0 = 1%). THE ATR IS MEASURED ON THIS SPEC'S
  OWN TIMEFRAME — an ATR on 5-minute bars is roughly an order of magnitude
  smaller than a daily ATR, so the same atr_mult sizes a far larger position; we
  do not convert one into the other, we tell you. EQUITY only: an option's loss
  is not linear in the underlying's ATR (it has its own delta, gamma and theta),
  so "risk 1% at two ATRs" does not describe an option position at all, and that
  is refused in plain words rather than answered wrongly.
  If even ONE share risks more than the budget the trade is SKIPPED
  (`skipped_atr_risk_budget`), exactly as risk_pct does — a floor of 1 would hand
  a member who asked to risk 1% a trade risking several. No usable ATR yet
  (warmup, a gap) refuses under its OWN reason
  (`skipped_no_atr_to_size_against`), never as "you are out of money": it is the
  same refusal risk_pct makes when a spec names no stop, because the ATR IS the
  stop here.
- "kelly" ({value: 0.25, min_trades: 30}) — FRACTIONAL KELLY, equity or
  single-leg options. `value` is the FRACTION OF FULL KELLY (0.25 =
  quarter-Kelly); above 1.0 is REFUSED, because full Kelly is already the
  aggressive end and everything past it is strictly worse than full Kelly — more
  variance for less growth. The win rate and payoff ratio come from THIS BOT'S
  OWN closed trades on the desk (f* = W − (1 − W)/R, the same formula the
  scorecard's Kelly suggestion uses — one implementation, so what we advise and
  what your desk fills can never drift). It then sizes exactly like pct_equity,
  on a percent Kelly WORKED OUT rather than one you typed.
  * THE HARD CAP IS 25% OF EQUITY IN ONE POSITION, applied AFTER your fraction,
    so even {"value": 1.0} on a wild edge cannot stake more than a quarter of
    the desk (counted as `kelly_capped`).
  * BELOW `min_trades` (default 30) THE METHOD STANDS DOWN to the platform's
    1-unit default and says so (`kelly_insufficient_history`) — that is a
    DIFFERENT thing from a skip: we could not COMPUTE a Kelly fraction, so we
    fall back to the documented default rather than refuse a trade your rule
    asked for. Sizing off a five-trade sample is how people blow up, and doing it
    silently would be worse than not doing it.
  * NO POSITIVE EDGE stands down the same way (`kelly_no_edge`) — honest Kelly
    refuses to size a losing edge.
  * If the Kelly budget cannot afford ONE unit the trade is SKIPPED
    (`skipped_kelly_budget`), like pct_equity.
Omit sizing → 1 contract / 1 share, the default. The BACKTEST is UNCHANGED for
EVERY one of these methods and that is deliberate: it grades per-unit PERCENT
returns, so size multiplies wins and losses alike and can never move EV, win-rate
or the verdict. A spec that changes ONLY its sizing block grades BYTE-IDENTICALLY.
Sizing changes the DOLLARS on a deployed desk, which is where it belongs.
ALL FOUR equity-aware methods (risk_pct · pct_equity · atr_risk · kelly) read the
desk's equity FRESH on every walk — nothing stored, nothing reserved — so they
re-size as the desk grows or shrinks, which is the point. If the desk keeps no
cash ledger at all the fill falls back to the 1-unit default and says so
(`sizing_equity_unavailable`); if the ledger EXISTS and cannot be READ the entry
is refused under its own reason (`skipped_sizing_equity_unreadable`) — we do not
size a position off a number we could not fetch.

OPTIONAL `liquidity` (wave-C #6) — THE ONE RISK KNOB THE GRADER READS:
    "liquidity": {"min_price": 5, "min_dollar_volume": 10000000,
                  "max_pct_of_volume": 1.0}
Everything else in this section is live-only because size cannot move a percent.
This one is different, and the difference is the honesty argument: IT CHANGES
WHICH FILLS HAPPEN. A backtest that fills a $2 stock trading $40k a day, or that
buys 90% of a bar's volume, is promising a fill no desk will ever get — and its EV
is built out of those fills. So the floors and the ONE-SHARE participation test
run identically in the grade and on the desk (one shared function; a test pins
that both paths call the same object).
- `min_price` / `min_dollar_volume` REFUSE a candidate outright
  (`skipped_liquidity_floor`; skip ledger `liquidity_floor`).
- `max_pct_of_volume` caps the order at that PERCENT of the bar's real volume.
  Over-cap orders SIZE DOWN on the desk (`sized_down_to_participation_cap`); if
  even ONE share exceeds the cap the fill does not happen
  (`skipped_participation_cap`) — and THAT half is what is graded. The size-down
  is live-only, because a smaller position earns the same per-unit percent.
- MEASURED ON THE SIGNAL BAR: its close, its volume, and the average dollar volume
  over the 20 bars ENDING AT IT, inclusive. Never the fill bar's own volume — that
  number has not printed when the order is sized, and using it would be a
  look-ahead in the one place a capacity check must not have one. On an intraday
  spec those 20 bars are 20 of YOUR OWN bars, not 20 days.
- A floor we cannot MEASURE (no volume array, an incomplete window) refuses under
  its OWN reason (`skipped_liquidity_unmeasurable`), never as a floor breach: one
  means "we measured it and it is too thin", the other means "we could not measure
  it", and they have different fixes.
- SHARES only. (`universe_screener`'s min_price / min_dollar_vol are a third
  thing again: they pick the UNIVERSE before any signal fires; these refuse a
  CANDIDATE at the fill.)
- WHAT WE DO NOT MODEL ON A SHARE FILL, said out loud: PARTIAL FILLS and LOCATE
  AVAILABILITY. Every share order — graded and on the paper desk — fills WHOLE at
  a real exchange print, and every short is assumed borrowable. We have no order
  book and no securities-lending feed, so modeling either would mean inventing
  data. `max_pct_of_volume` above is the honest bound we DO ship (and it is
  graded), and every short is charged a MODELED borrow labeled as modeled. This
  is surfaced as a deploy disclosure, not buried here.

OPTIONAL `liquidity`, THE OPTION SIDE (section C) — ALSO GRADED:
    "liquidity": {"min_option_volume": 50, "min_open_interest": 500,
                  "max_spread_pct": 15}
Same argument as the share floors: they change WHICH FILLS HAPPEN, so the grade
refuses the same contracts the desk does (one shared function, pinned).
- `min_option_volume` IS `min_volume` — the contract's own daily volume floor
  under two names, one reader. Setting BOTH is refused rather than guessed.
  Refusal: `option_volume_floor`.
- `min_open_interest` — HONEST LIMIT: the daily options store carries
  daily_volume / bid_size / ask_size and NO open-interest column. The floor is
  applied only where the data service genuinely supplies it; where it cannot the
  gate STANDS DOWN and is COUNTED (`option_open_interest_unknown`) rather than
  silently passed or refused on a number nobody read. Refusal:
  `option_open_interest_floor`.
- `max_spread_pct` — (ask − bid) / mid as a PERCENT. The same arithmetic and the
  same word the LIVE chain resolver already refuses a leg with
  (`option_spread_too_wide`). A one-sided or CROSSED quote is not a wide spread
  but an UNMEASURABLE one: it stands down as `option_spread_unmeasurable`.

OPTIONAL `max_open_positions` (int ≥ 1): the most positions THIS bot may hold at the
same time. Your cap, enforced for you: while it is full a fresh signal is simply not
taken (counted as `skipped_max_open` in the walk telemetry) and a later walk with
room takes the next one. Omit → NO cap: a platform default of 10 was built
and reverted (2026-08-15) because turning it on put every bot on the
interleaved walk and exposed a bug there; set your own number and it is
enforced exactly. The cap gates NEW entries only — nothing already open is
ever closed by it, and room comes back as soon as a position closes.

FOUR THINGS WE SCOPE HONESTLY RATHER THAN FAKE (wave C #7-#10). Each is a real
request; for each we built the half that is modellable on the data we have and we
REFUSE the half that is not, by name. A field we accept and quietly ignore is the
one thing this platform does not ship — it makes your backtest look more careful
than it is.

1. TIME IN FORCE / MARKET-ON-CLOSE.
   WE DO MODEL: `exit.fill_timing "moc"` — the session's real closing print (the
   same price as "close" on daily bars, genuinely different intraday). And
   `entry.order.good_for_bars` already IS a time-in-force, expressed in the bars
   we actually have.
   WE REFUSE, BY NAME: immediate-or-cancel and fill-or-kill (`time_in_force:
   "ioc"` / `"fok"`, and `tif`). Those either execute against the resting book at
   that instant or die, and a bar is four prices and a total — not an order book.
   Any answer we gave about "would it have filled instantly?" would be invented,
   and accepting the field and filling anyway would tell you your order was
   cancelled while we traded it.

2. SLIPPAGE.
   WE REFUSE, BY NAME: `max_slippage` / `slippage_pct` / `slippage_bps` /
   `max_spread_pct`, anywhere you write them. We fill SHARES at real prints — the
   real open, the real close, a resting order at its own honest level — so there
   is no simulated share spread for such a knob to bite on. (Options are already
   honest a different way: we buy at the ask and sell at the bid, never the mid,
   from a real NBBO when one exists and a labeled modeled spread when it does not.)
   WE DO MODEL the risk you are reaching for: `{"entry": {"max_gap_pct": 3.0}}`
   skips the fill when the bar you would have entered on OPENED more than 3%
   AGAINST you from your signal bar's close (above it for a long, below for a
   short). A gap in your FAVOUR is not slippage and is never refused — refusing it
   would keep only the bad half of the distribution and flatter the backtest.
   GRADED, because it changes which fills happen (skip ledger `entry_gap`;
   `skipped_entry_gap` on the desk). Equity only, and refused beside `entry.order`
   / `entry_at "intraday_1035"`, where there is no next-open gap to measure.

3. MARKET CIRCUIT BREAKER vs A HALT DETECTOR.
   WE DO MODEL: `{"circuit_breaker": {"benchmark": "SPY", "intraday_drop_pct":
   5}}` — see the spec block above.
   WE REFUSE, BY NAME: a halt detector (`circuit_breaker.halt` / `halt_detector` /
   `luld`). There is no halt feed on this dataset — no LULD bands, no exchange halt
   messages — and on bar data a halted stock and a stock with no data look
   identical. A halt we "detected" would be a guess wearing a fact's clothes.

4. PORTFOLIO VOLATILITY TARGETING.
   WE DO MODEL: `{"risk": {"target_volatility_pct": 15}}`, PER BOT, from that
   bot's own equity curve over a stated window (see the spec block above).
   WE REFUSE, BY NAME: a DESK-WIDE version (`risk.scope: "desk"`). Bots on one desk
   walk independently and concurrently, so no single walk owns the desk's size: N
   bots would each compute "the desk's" scale from their own book and each apply
   it, and the desk would be scaled N times by N different numbers. That is the
   same reason a desk-scoped hedge is refused.

THE TWO DOLLAR CAPS live on the DESK and the BOT, not in the spec (they are live-fill
controls, so changing one never re-grades anything):
- `max_usd_per_trade` — the most money ONE order may use. Over it, the order is sized
  DOWN to the largest whole quantity that fits; if even one unit is over, the trade is
  skipped (`skipped_max_per_trade`).
- `max_open_usd` — the most money THIS BOT may have committed across ALL its open
  positions at once. Over it, the new entry is not taken (`skipped_max_open_usd`), and
  the room comes back the moment one of its positions closes — nothing is ever
  reserved. It exists because the per-trade cap cannot bound total appetite: a bot with
  many positions makes many small affordable buys and eats the desk anyway.
Both cascade the same way — the bot's own value wins, else the desk's, else uncapped —
and both are set per-desk (`POST /v1/me/accounts/{id}/max-per-trade` /
`.../max-open-usd`) or per-bot (`POST /v1/me/accounts/{id}/alphas/{deploy_id}/max-per-trade`
/ `.../max-open-usd`), with null to clear. A trade must pass BOTH caps AND the desk's
buying power; each refusal has its own telemetry reason, so you always know which one
stopped it.

THE SECTOR CAP (`max_sector_frac`, #35) lives beside them — desk column + per-bot
override, same cascade, same routes shape (`POST /v1/me/accounts/{id}/max-sector-frac`
/ `.../alphas/{deploy_id}/max-sector-frac`, null to clear). It bounds the FRACTION
(0..1] of the desk's equity that ONE sector's open positions may hold, counted across
the WHOLE DESK whatever bot opened them — the concentration none of the per-bot caps
can see (five bots each buying a different chip name is 80% semis). Sectors come from
our own static GICS-style map (every ETF is one "etf" bucket; a symbol we don't know
is its own "other" bucket — never silently merged); the per-sector totals are derived
fresh every walk through the one buying-power cost model, nothing reserved. Refusals
are `skipped_sector_cap` with a note showing the math; a desk book we could not read
fails CLOSED under `skipped_sector_exposure_unreadable`, never as "you hit your cap".
Live-fill only — the grade never reads it.

THE DESK-WIDE CONCENTRATION LIMITS (Wave B) sit beside the sector cap — same
cascade (bot's own value ?? desk ?? unlimited), same "unset = nothing changes",
same "the grade never reads them". They answer the questions no per-bot dollar
cap can:
- `max_gross_exposure` — the most your open positions may be worth as a FRACTION
  of the DESK'S EQUITY, counted across every bot (1.5 = 150%). `max_open_usd` is
  an absolute dollar number and does not move when your account does; this one
  does, which is the point. Refusal: `skipped_max_gross_exposure`.
- `max_net_exposure` — the most DIRECTIONAL tilt the desk may carry:
  |longs − shorts| ÷ equity, either way. Genuinely a different number from gross
  now that short equity is supported — a market-neutral book can be 200% gross
  and 0% net, and refusing it on gross alone would be wrong. A position counts
  long or short by the SIGN OF ITS OWN QUANTITY (we do not model option delta —
  a stated proxy, like the 100% a short reserves in buying power). AN ORDER THAT
  REDUCES THE TILT IS NEVER REFUSED, even over the limit: refusing the hedge is
  how a limit would make the risk it exists to bound worse. Refusal:
  `skipped_max_net_exposure`.
- `max_positions_per_symbol` — how many open positions the WHOLE DESK may hold on
  one name. Counted by UNDERLYING, never by contract: three different NVDA calls
  are three bets on NVDA, not three instruments. Five separate bots can pile into
  the same name today and nothing notices. Refusal:
  `skipped_symbol_concentration`.
- `max_correlation` (0..1] — refuse a new name whose DAILY-RETURN correlation
  with something the desk already holds is at or above it. The other half of the
  sector cap: two names in two different sectors can still be one bet. The
  details that make it honest, stated because they change the answer:
  * measured on RETURNS, never on price levels — two unrelated names that both
    drifted up over three months correlate ~0.99 on price and near zero on
    returns;
  * the window ENDS AT THE SIGNAL'S OWN BAR, never at the newest bar the walk
    holds, so a catch-up walk cannot peek;
  * `correlation_window_sessions` is the trailing window in TRADING SESSIONS of
    daily bars — **the default is 60** (about three months);
  * a pair with fewer than HALF the window's overlapping returns is UNKNOWN and
    the limit STANDS DOWN for that pair, counted as `correlation_unknown`. Not
    enough evidence is not evidence — we never refuse on a number we did not
    measure.
  Refusal: `skipped_correlation_cap`, with a note naming the other symbol and the
  measured correlation.
- `desk_position_stop_pct` — the DESK'S EMERGENCY STOP PER POSITION: "cut
  anything down X%, whatever its strategy says". A DESK setting with NO per-bot
  override, on purpose — it is the floor UNDER the strategies, so the bot whose
  own stop is wrong is exactly the one that must not opt out of it. It is an
  EXIT, so it runs on walks where entries are refused; it NEVER pre-empts a
  tighter strategy stop (yours fires first, at its own earlier bar); it closes at
  the real mark on that bar with `close_reason='desk_position_stop'` and sends
  one alert; and a SHELVED bot is suppressed exactly like every other
  discretionary exit, because shelf means the bot does not trade.
All five entry limits are DESK-WIDE: the count, the dollars and the correlations
they measure include positions your OTHER bots opened. Desk routes:
`POST /v1/me/accounts/{id}/max-gross-exposure` · `.../max-net-exposure` ·
`.../max-positions-per-symbol` · `.../max-correlation` ·
`.../correlation-window` · `.../desk-position-stop`, body `{"value": N}` and
null to clear. Per-bot overrides at
`POST /v1/me/accounts/{id}/alphas/{deploy_id}/...` for the same five (there is
no per-bot desk stop). A desk book or equity we could not READ fails CLOSED under
its own reason (`skipped_desk_concentration_unreadable`) and never as "you hit
your limit" — a limit we never measured is not a fact. Nothing is reserved: every
total is derived fresh each walk, so closing a position frees the room on the
next one.

THE DESK'S OWN TWO CONTROLS (Wave A) are about the desk's P&L and the desk's
OWNER rather than its exposure — the limits above bound what the book LOOKS like,
these two bound what it is allowed to keep LOSING and give you one switch to stop
all of it.
- `max_daily_loss_usd` — once the WHOLE DESK's realized P&L for the ET session is
  down this much, NO bot on the desk opens anything more that session
  (`skipped_desk_daily_loss` + entries_blocked_reason "desk_daily_loss"). Desk
  column + per-bot override of the NUMBER, same cascade as the caps
  (`POST /v1/me/accounts/{id}/max-daily-loss` /
  `.../alphas/{deploy_id}/max-daily-loss`, null to clear). Note the asymmetry: the
  limit is per-bot, the LOSS it watches is the desk's — another bot's bad morning
  really can stop this one, which is the whole point.
- `trading_halted` — the kill switch. `POST /v1/me/accounts/{id}/halt` with
  {"halted": true, "reason": "..."} stops every bot on the desk from OPENING;
  {"halted": false} resumes and clears the reason. The reason and who set it are
  quoted back in the refusal (`skipped_desk_halted`).
Both stop ENTRIES ONLY. Open positions keep being marked and keep exiting on their
stops — a kill switch that froze the exits would leave you unable to get OUT of the
thing that scared you. Each bot READS this state on its own walk and derives the
desk's P&L fresh from the desk's own closed rows: nothing is written, nothing is
reserved, and a new ET session starts clean with no resume step. A desk row we could
not read fails CLOSED under its own reason (`skipped_desk_state_unreadable`) — "we
could not look" is never evidence that a desk is not halted.

OPTIONAL intraday scheduling (ANY intraday timeframe — 1Min/5Min/15Min/30Min/1Hour/4Hour;
rejected on "1 day", because a daily bar has no inside-the-day window to honour):
- entry_start / entry_end ("HH:MM" wall-clock ET, e.g. "10:00" / "10:30"): a signal
  may fire ONLY on a minute bar inside [entry_start, entry_end]. entry_end must be
  later than entry_start. Omit both → the FULL session (09:30–16:00) is assumed and
  confirmed back (defaults_applied + result.intraday_schedule). The window is
  enforced IDENTICALLY when the strategy is graded and when it is DEPLOYED (fixed
  2026-07-30 — it used to bind only in the backtest, so a lunch-hour bot could open
  a position at 09:40 on a live desk).
- REGULAR SESSION ONLY, graded and live. An intraday signal may fire only on a bar
  inside 09:30–16:00 ET, and the bar it FILLS on must be inside it too — so a 15:59
  signal is not taken (its fill would be the 16:00 post-market print). The minute
  feed DOES carry extended hours; those bars are counted and refused, never
  traded (result.intraday_schedule.bars_outside_session). Half-days come from the
  exchange calendar, so a 13:00 close is honoured.
- exit.max_minutes (int ≥ 1): a hard time-stop — force the exit at most N minutes
  after the fill. Omit → held to the exit rule.
- exit.eod_flatten (true/false): force-close at the entry session's last bar (never
  overnight). Omit/false → a hold may run into later bars if the rule runs long.
  The actual exit is the EARLIEST of the rule/hold_days, max_minutes, and eod_flatten.
- exit.flatten_at ("HH:MM" ET): force-close at the first bar of the ENTRY's own
  session at or after that time (e.g. "15:55"). It is the general form of
  eod_flatten and can never reach into a later day; on a half-day the session's
  last bar wins. Must be later than entry_start.
- Intraday FEATURES usable in entry.when on ANY intraday timeframe: ret_<N>m
  (N-MINUTE return — converted for your bar size), rvol (volume ÷ the running
  session-mean bar-volume; first session bar = 1.0), rvol_trail20 (volume ÷ the
  mean of the last 20 BARS — usually what people mean), hour (wall-clock ET hour,
  e.g. gate the 10-o'clock hour with gte hour 10 AND lte hour 10). All causal — a
  signal at bar i reads only bars ≤ i. Units and traps: CAPABILITY MAP above.
Our engine ADVISES on the result; it never blocks a deploy. A malformed value gets a
plain-words fix (what field, what's wrong), never a judgment of your strategy.

### Indicators and feature references (read this — it saves a debugging loop)
Indicators are declared in `indicators[]` as
`{id, type, params?, output?, timeframe?}` and then referenced BY THEIR `id` in
the rule tree. Rules the validator enforces up front (a bad spec is a 400 /
valid:false, never a crashed run):
- An `id` is unique within the spec, and may not reuse a built-in array or an
  engine-attached operand name (o/h/l/c/v/d, open/close/high/low/volume, the
  10:35 session family, hour/rvol, spy_ret/qqq_ret/bench_ret, the macro and
  earnings operands). Redeclaring a derived feature such as `sma200` is fine.

1. MULTI-OUTPUT INDICATORS need an explicit `output`, and it must be one of the
   legal selectors — a made-up selector is rejected, it does NOT default:
     - macd       -> line | signal | hist                    (default: line)
     - bollinger  -> upper | mid | lower | width | pct        (default: mid)
     - adx        -> adx | plus_di | minus_di                 (default: adx)
     - stoch      -> k | d                                    (default: k)
     - keltner    -> upper | mid | lower                      (default: mid)
     - donchian   -> upper | mid | lower                      (default: mid)
     - aroon      -> up | down | osc                          (default: up)
     - vortex     -> plus | minus                             (default: plus)
     - elder_ray  -> bull | bear                              (default: bull)
     - ichimoku   -> tenkan | kijun | senkou_a | senkou_b | chikou  (default: tenkan)
     - stochrsi   -> k | d                                    (default: k)
     - kst        -> line | signal                            (default: line)
     - supertrend -> line | direction                         (default: line)
     - ppo / pvo  -> line | signal | hist                     (default: line)
     - pmo        -> line | signal                            (default: line)
     - kvo        -> line | signal                            (default: line)
     - rvi        -> line | signal                            (default: line)
     - fisher     -> fisher | trigger                         (default: fisher)
     - kdj        -> k | d | j                                (default: k)
     - smi        -> smi | signal                             (default: smi)
     - wavetrend  -> wt1 | wt2                                (default: wt1)
     - stochf     -> k | d                                    (default: k)
     - alligator  -> jaw | teeth | lips                       (default: jaw)
     - gator      -> upper | lower                            (default: upper)
     - hilo       -> line | direction                         (default: line)
     - chandelier -> long | short                             (default: long)
     - starc      -> upper | mid | lower                      (default: mid)
     - accbands   -> upper | mid | lower                      (default: mid)
     - heikin_ashi-> open | high | low | close                (default: close)
     - pivot / fib_pivot -> pp | r1 | s1 | r2 | s2 | r3 | s3  (default: pp)
     - camarilla  -> pp | r1..r4 | s1..s4                     (default: pp)
     - woodie     -> pp | r1 | s1 | r2 | s2                   (default: pp)
     - demark_pivot -> pp | r1 | s1                           (default: pp)
   There is NO dotted "id.output" operand. To use the MACD histogram, declare a
   dedicated entry `{"id": "macd_hist", "type": "macd", "output": "hist"}` and
   reference the BARE id `"macd_hist"` in the rule — never `"macd.hist"` or
   `"macd_hist"` without declaring it.
   Other types (single-output, no `output` needed): rsi, ema, sma, wma, hma,
   dema, tema, kama, momentum, roc, trix, tsi, cmo, dpo, willr, cci, natr, atr,
   volume_ratio, obv, adl, williams_ad, cmf, mfi, vwap, chaikin_osc,
   ultimate_oscillator, mass_index, bop, psar,
   and (indicators-150 wave) moving averages rma/smma, vwma, evwma, trima, zlema,
   t3, alma, vidya, mcginley, lsma, zlsma, swma, sinwma, fwma, pwma, median,
   midpoint, midprice, ssf, gma, ehma; oscillators apo, ao, ac, coppock, cog,
   qstick, psl, rmi, pgo, bias, disparity, rocr, rocp, rocr100, cfo, ift_rsi,
   crsi, tii, ravi, laguerre_rsi, stc, pfe, efficiency_ratio; trend adxr, vhf,
   chop, dx, plus_dm, minus_dm; volatility stddev, variance, hv, ulcer, bbwidth,
   true_range, range, chaikin_vol; volume pvt, nvi, pvi, emv, fi, vzo, vroc;
   statistical / price zscore, linreg_slope, linreg_intercept, linreg_angle, tsf,
   skew, kurtosis, mad, pctrank, cv, clv, drawdown, typical_price, median_price,
   weighted_close, ohlc4, log_return, demarker, body, upper_shadow, lower_shadow;
   candlestick patterns (0/1) bullish_engulfing, bearish_engulfing, doji, hammer;
   plus the rolling reducers rolling_min / rolling_max (which take a
   `params.source` = a prior indicator id or a base feature).
   Param key is `length` (e.g. {"length": 14}); legacy `period` still works.
   Extra params where relevant: macd fast/slow/signal; bollinger std; keltner
   atr_length/mult; ichimoku tenkan/kijun/senkou_b/shift; stochrsi
   rsi_length/length/k/d; supertrend length/mult; tsi long/short; psar step/max;
   kama length/fast/slow; chaikin_osc fast/slow; ultimate_oscillator
   fast/medium/slow; mass_index ema_length/sum_length; stoch k/d;
   ppo/pvo/pmo/kvo fast/slow/signal; t3 length/a; alma length/offset/sigma;
   smi length/d1/d2/signal; wavetrend n1/n2; chandelier length/mult; starc
   length/atr_length/mult; accbands length/factor; rmi length/momentum; ravi
   short/long; crsi rsi/streak/rank; stc fast/slow/cycle; pfe length/smooth;
   chaikin_vol ema_length/roc_length; laguerre_rsi gamma; alligator/gator
   jaw/teeth/lips.
   Honesty notes: ichimoku's senkou spans are projected FORWARD on a chart, but
   the engine exposes the value KNOWN at each bar (derived from data <= that bar,
   i.e. a backward lag) so there is never look-ahead; chikou is exposed as the
   close 26 bars ago (a pure lag). vwap is a causal ROLLING VWAP of daily typical
   price (daily bars have no intraday session to anchor a true session VWAP).
   Pivot points (pivot/fib_pivot/camarilla/woodie/demark_pivot) use the PREVIOUS
   bar's O/H/L/C only (a backward lag — never the forming bar), so a rule may key
   off today's level with no look-ahead. Alligator/gator expose the value known
   at each bar (the plot's forward shift is omitted). Heikin-Ashi candles are a
   causal recursion. All 100+ additions are prefix-consistent and pinned
   bit-identical between the vectorized and rolling engines by
   test_vectorized_parity.py.

1b. MULTI-TIMEFRAME — an indicator may declare its OWN, LARGER bar size with an
   optional `timeframe`, so a fast bot can read a slow indicator. This is how you
   write "1-minute RSI below 30 AND a 5-minute MACD crossover":

     "timeframe": "1Min",
     "indicators": [
       {"id": "rsi14",     "type": "rsi",  "params": {"length": 14}},
       {"id": "macd_line", "type": "macd", "output": "line",   "timeframe": "5Min"},
       {"id": "macd_sig",  "type": "macd", "output": "signal", "timeframe": "5Min"}
     ],
     "entry": {"side": "call", "when": {"all": [
        {"lt": ["rsi14", 30]},
        {"cross_above": ["macd_line", "macd_sig"]}]}}

   THE RULE THAT MAKES IT HONEST: a higher-timeframe value is readable only AFTER
   its bar has CLOSED. A 5-minute bar labelled 10:00 covers 10:00–10:05, so at the
   1-minute bar 10:01 the newest readable 5-minute MACD is still the one from the
   bar labelled 09:55, and the new value first appears at 10:05. It holds flat for
   five 1-minute bars and then steps — that is correct, not a stuck feed. (The
   naive "resample and forward-fill" is wrong by exactly one bar and would let the
   bot react to the very move it is about to be told happened. We don't do that.)

   Allowed: LARGER than the spec's own `timeframe`, and a whole multiple of it.
     1Min bot  -> 5Min | 15Min | 30Min | 1Hour | 4Hour
     5Min bot  -> 15Min | 30Min | 1Hour | 4Hour
     15Min bot -> 30Min | 1Hour | 4Hour        30Min bot -> 1Hour | 4Hour
     1Hour bot -> 4Hour                        4Hour bot -> (nothing — daily is
     the top of the ladder and stays refused; a day is a session, not a block of
     minutes)
   The 4Hour close rule, because the short bar is the trap: a session's 4Hour
   bars close at 13:30 and at the SESSION CLOSE (16:00 / 13:00 on a half-day) —
   the 13:30-labelled bar is readable from 16:00, NOT from 17:30.
   Refused, in plain words naming a size that works: SMALLER than the bot's bar
   (the bot only wakes on its own bars); the SAME as the bot's bar (drop the field
   — it is not a no-op, it would hand you the previous bar); anything on a
   "1 day" spec (daily is the top of the ladder — weekly/monthly isn't built);
   and "1 day" as an indicator timeframe (a day is a session, not a block of
   minutes). Omit the field and the indicator rides the bot's own bar, which is
   what most strategies want.

2. EVERY id a rule references MUST EXIST — a typo or an undeclared id does not
   error at runtime, it makes the rule silently never fire (you'd get NO_DATA and
   not know why). A reference resolves only if it is: a declared indicators[] id;
   an OHLCV word-alias (close, open, high, low, volume); a 10:35 session anchor
   (open0930, px1035, first30_high, first30_low, chg1035, gap1035, spy1035,
   above_first30_high, below_first30_low); a benchmark operand (spy_ret, qqq_ret,
   bench_ret, or {"bench": SYM, "ret": N}); a top-N selection ({"top_n":
   {"by": F, "n": K}}); or a BASE feature the engine always attaches —
   c, o, h, l, v, ret, gap, ret3, run5, ret20, sma20, sma50, sma200, hi60, hi252,
   atr20, volavg, rvpct, regime_trend, regime_vol, dow, is_friday, is_monday. On an
   INTRADAY spec ONLY, four more resolve: hour, rvol, rvol_trail20, and ret_<N>m
   (any whole number of bars, e.g. ret_5m) — referencing them on a daily spec is
   the usual "unknown feature" reject (they're intraday-only). Every one of these
   is DEFINED WITH ITS UNIT in the CAPABILITY MAP above; read the unit before you
   pick a threshold.

3. AN INDICATOR'S `length` COUNTS BARS, AND AN INTRADAY BOT HOLDS ONLY SO MANY.
   A bot's frame carries a warmup window sized from its bar size — roughly 14
   trading sessions on 1Min/5Min, 23 on 15Min, 46 on 30Min, 62 on 1Hour and 186
   on 4Hour. An indicator longer than that is NaN at EVERY bar, and NaN compares
   False, so the bot fires ZERO times while reporting perfect health — no error,
   no warning, nothing in the logs. This is a real and recent production failure:
   bots deployed with `length: 15600` on a 5Min bar (someone's "EMA over 200
   sessions", converted with a 390-minute session while our frames carry extended
   hours) traded nothing for days. Deploy and validate now return a plain-words
   `disclosures` line when a declared indicator cannot resolve — READ IT. To act
   on a multi-session trend, either run the strategy on a "1 day" bot (where 200
   bars IS 200 sessions) or use the session-denominated operand
   {"lag_sessions": [F, N]}, which is served from the daily bars and means the
   same thing on every timeframe.

Use POST /v1/strategies/build to turn loose params into a full spec — it fills the
safe defaults (timeframe, backtest window, indicators) and returns valid + plain
errors[] if anything is wrong. Do not hand-write JSON you can have built + checked.

### Incomplete spec? You get ASK-FIRST suggestions, not just errors
A validation failure on POST /v1/strategies, /v1/strategies/bulk (per item) or
/v1/strategies/build returns EVERY problem at once (never first-error-wins),
each in plain words — plus `suggestions` ([{field, suggested_value, why}])
for the defaultable missing fields (universe -> the full catalog = the list of
stocks it trades; exit -> "sell after 5 days"; backtest -> the full honest
window; timeframe/name/asset_class) and, when it would validate as-is, a ready
`suggested_spec`. Accept by RESUBMITTING suggested_spec — nothing is ever
auto-applied. The entry rule is NEVER defaulted (when to buy IS the strategy),
and take-profit is never suggested (banned, earned law). A spec accepted from
suggested_spec carries "defaults_applied": [field, ...] permanently, so its
report can show which parts were defaulted (e.g. "universe: defaulted to full
catalog"). On a 1Min spec with no entry window, the suggestions CONFIRM the
assumed full session (entry_start "09:30" / entry_end "16:00") and note the exit
assumptions (no max_minutes → held to the rule; no eod_flatten → may run past the
close) — so you always see what the engine assumed, and can narrow it.

### FIRE-RATE PRE-FLIGHT — `fire_check`: would your rule EVER have fired?
A spec can be perfectly legal and still never fire. `valid` answers "is this
legal?"; `fire_check` answers "would it ever have done anything?", and they are
different questions. On 2026-08-19 three agents built ~500 bots each and
validate_spec passed every one of these:

  - `{"gte": ["close", "<a donchian upper band>"]}` — the upper band is the
    highest HIGH of its window INCLUDING this bar, so a close essentially never
    reaches it. FIRES 0 TIMES, EVER. (Want the breakout? Compare against the
    PREVIOUS bar's band: {"lag": ["dc_up", 1]}.)
  - `{"gt": ["mass_index", 27]}` — mass_index's real range is ~23.6-25.8.
    FIRES 0 TIMES, EVER.
  - `{"gt": ["stochrsi_k", 0.9]}` — stochrsi k is 0-100, NOT 0-1, so this is
    true on ~95% of bars. As an exit it leaves on the first bar it holds, forever.
  - `gap` on an intraday timeframe — an intraday bar opens where the last one
    closed, so gap reads 0.0 on every bar. Any `gap > x` is dead there.

A bot like that deploys, reports healthy, and trades ZERO times. Nothing else we
have can see it. So both POST /v1/strategies/build (when valid) and every deploy
response carry `fire_check`:

    "fire_check": {
      "status": "measured" | "could_not_measure",
      "headline": "Over the 1,040 bars measured, this entry would have fired 0
                   times. Of its 2 condition(s), `mass_index > 27` never fired …",
      "advisory": "This is a reading, not a verdict — your strategy deploys
                   either way. It is your call.",
      "sampled":  {"symbols": [...], "symbols_total": N, "sampled_all": bool,
                   "timeframe": "1 day", "bars": N, "first_bar": "...",
                   "last_bar": "...", "elapsed_ms": N},
      "trees": {"entry" | "exit" | "kill_switch": {
          "status": "never" | "always" | "rare" | "healthy" | "could_not_measure",
          "fires": N, "bars": N, "fire_rate": 0.0, "first_fire", "last_fire",
          "note": "<the sentence a human reads>",
          "conditions": [{"label": "mass_index > 27", "required": true,
                          "fires": 0, "fire_rate": 0.0, "status": "never",
                          "observed": {"mass_index": {"min": .., "max": ..}},
                          "note": "`mass_index` stayed between 23.6 and 25.8 over
                                   the bars measured, and the rule asks for more
                                   than 27."}]}}}

READ `trees.entry.status` BEFORE YOU DEPLOY. "never" means the rule fired 0
times on real history; the `conditions` list names WHICH leaf is holding it down
(`required: true` = it sits under an AND, so on its own it makes the whole tree
impossible) and `observed` gives the min/max we actually measured — that is the
number to compare your threshold against. "always" on an exit means the bot exits
on its first held bar.

IT IS A READING, NEVER A GATE. The engine ADVISES; it does not decide. A spec
whose entry fires 0 times STILL DEPLOYS and still returns a deploy_id — the
reading sits beside your choice, and the choice stays yours. Nothing here can
refuse a deploy or a backtest.

MEASURED, AND HONEST ABOUT ITS LIMITS. It runs your OWN rules over REAL bars,
through the same feature path the backtests use — never a simulation. It is
BOUNDED (a symbol sample, ~2 years of daily bars or ~500 intraday ones, a hard
time budget) and it always states in `sampled` exactly what it measured; it never
implies coverage it did not compute. If it cannot run — no data, an operand
nothing could attach, the time budget spent — it says
`"status": "could_not_measure"` with the reason, and NEVER a made-up number.
Absent entirely (null) only when an operator has switched the check off.

### Worked example (this exact spec validates and runs)
The RUNNABLE example in "THE FORMAT" at the top of this doc IS this exact spec — it
validates and runs as written (it is the one JSON block you can POST unchanged).

## CREDIT STRUCTURES — put-writes, put spreads, iron condors ARE supported
Premium-selling strategies port DIRECTLY: asset_class "credit" plus a
`structure` block. Do NOT mark a condor / put-write / credit-spread strategy
as unsupported — the engine backtests all three, and the paper sim
forward-walks them on a desk.

The structure block (plain words first, field in parens): how far below the
current price the short strike sits, as a fraction ("otm_pct": 0.03 = 3%
below); how many days until the options expire ("target_dte", the DTE); how
much further below the protective long strike sits ("wing_pct" — REQUIRED for
put_spread / iron_condor, n/a for put_write); and an optional volatility
mark-up on trailing realized vol ("iv_premium", default 1.10, read by the
MODEL path only); and HOW IT IS PRICED ("pricing": "chain" | "model", absent =
auto). So:
{"type": "put_write" | "put_spread" | "iron_condor", "otm_pct": 0.03,
"target_dte": 14, "wing_pct": 0.03, "iv_premium": 1.10, "pricing": "chain"}.
The entry.when rule tree gates WHEN premium is sold (e.g. only when the stock is
above its 200-day average price, or only when realized volatility is rich).

Worked examples (each structure drops into the full spec envelope exactly like
the worked example above — same name/universe/timeframe/backtest/entry/exit):

    put_write   (weekly 2%-OTM put-writing on defensive ETFs):
      "asset_class": "credit",
      "structure": {"type": "put_write", "otm_pct": 0.02, "target_dte": 7}

    put_spread  (5%-OTM bull put spread, 5% wing, held to expiry):
      "asset_class": "credit",
      "structure": {"type": "put_spread", "otm_pct": 0.05, "wing_pct": 0.05,
                    "target_dte": 14}

    iron_condor (3%/3% wings, 14-DTE):
      "asset_class": "credit",
      "structure": {"type": "iron_condor", "otm_pct": 0.03, "wing_pct": 0.03,
                    "target_dte": 14, "iv_premium": 1.10}

HOW A CREDIT STRUCTURE IS PRICED, and how to tell which you got.
"structure.pricing" takes three values and ABSENT means "auto":

  "chain"  — build the structure from the REAL end-of-day option chain on the
             fill date: the listed EXPIRATION nearest your target_dte (strictly
             after the fill), the listed STRIKE nearest each target, every SOLD
             leg filled at the BID and every BOUGHT leg at the ASK (never a
             mid, never `last`), MARKED on each held session's own chain, and
             settled at intrinsic against the real regular-session close.
  "model"  — the original Black-Scholes path: model strike, model credit, model
             marks, IV = trailing realized vol x iv_premium, and NO bid/ask
             spread at all. Grades byte-identically to before "pricing" existed.
  "auto"   — (also what ABSENT means) the real chain wherever that date has one,
             the model where it does not. This is what every existing bot gets,
             GRADED and LIVE.

AUTO NEVER TURNS A REFUSAL INTO A MODEL FILL. A date with no chain rows is
missing DATA and the model stands in. A leg nobody is quoting both sides of is a
structure the member COULD NOT HAVE OPENED — modelling it would grade the exact
trade the real chain just refused, so it is refused and counted instead
(`skipped_no_quote`, plus `chain_refusals` naming each reason: no_ask, no_bid,
crossed_book, spread_too_wide, no_volume, no_size, no_strike, no_expiration).
A held session we cannot price is DROPPED and counted
(`chain_unpriceable_marks`), never carried at a price nobody quoted.

AND READ "REAL" PRECISELY. On the chain path the CONTRACT is real — that
expiration and those strikes were listed that day — and the daily marks are
real. The two-sided QUOTE is a MEASURED NBBO only from 2026-06-09 onward; before
that date this store's bid/ask is a flat 5% band around the real daily mark, so
an earlier chain fill is a real strike at a real price +/- a modeled 2.5%. That
is a different and much better thing than Black-Scholes (a modeled price at a
strike nobody listed) and it is still not a quote somebody made. Do not tell a
member their older backtest filled on measured NBBO.

READ THE PROVENANCE, DO NOT ASSUME IT. Every credit / combo / covered trade row
carries `pricing_source` ("real" or "modeled") and every such result carries
`result.pricing` — {n_real, n_modeled, n_trades, real_share_pct,
modeled_share_pct, note}, the shares in PERCENT. A run can be BOTH; the shares
are how you say so. `result.modeled` is now MEASURED: false when every fill
priced on the real chain, true otherwise.

Optional per-leg floors for the chain path, ENTRY only (a position already held
is marked whatever today's book looks like): "liquidity": {"min_volume": N (the
contract's own daily volume), "min_size": N (quoted size on the side that leg
trades), "max_spread_pct": N (a PERCENT of the mid — there is NO default, a wide
book is still a real quote)}.

A MODELED credit row on a desk is labeled BSMODEL in its contract_symbol so a
modeled mark can never pass as a real quote.
ON THE DESK (live, since 2026-08-27) a credit structure is opened on REAL OCC LEGS
whenever the chain can price every one of them: the real expiration nearest
target_dte, the real strike nearest each leg's target, every SOLD leg at its BID
and every BOUGHT leg at its ASK — never mid, never last. One leg without a genuine
two-sided quote refuses the WHOLE structure (never a half-built spread). Those
rows carry `OCC|<type>|opt:...` in contract_symbol, a per-leg `legs` receipt (occ,
side, qty, fill, bid, ask, nbbo_source), and `pricing_source: "real"`; they mark
by summing the legs' real quotes (a short leg bought back at the real ASK when a
measured same-session NBBO exists) and they CAN be closed from the desk. BSMODEL
is the FALLBACK when the chain cannot price the legs, `pricing_source: "modeled"`,
and it still cannot be hand-closed — there is no contract to sell into. The SAME
structure.pricing values choose the mode on the desk as in the grade.


BSMODEL FLATTERS MULTI-LEG PREMIUM SELLING — say this out loud to the human.
A modeled mid-price fill costs you nothing to enter and nothing to exit. A REAL
4-leg condor pays a spread FOUR TIMES on the way in and four times on the way
out, and the legs you most want to close are the thinnest. The internal trading
rig measured exactly this gap on its own iron condor: the backtest read
+13.6%, and the same structure at REAL prices ran −5.9% PER WEEK until it was
retired. Nothing in the modeled path can see that. So:
  • Treat ANY BSMODEL result with 2 or more short legs as OPTIMISTIC — not
    wrong, but not tradeable evidence either.
  • For real-price evidence, ASK FOR IT: "pricing": "chain" prices the same
    structure off the real ladder and refuses the days it cannot. Building the
    SAME structure as asset_class "combo" (also real-chain: buy@ask, sell@bid)
    is the other way, and comparing either against "model" shows you the spread
    you were not paying.
  • Never present a BSMODEL EV to a user as "what it would have made" — and
    check `result.pricing` before you call any credit EV modeled OR real.
The engine says this for you, machine-readably: a credit result whose structure has
2 or more SHORT option legs carries `result.modeled_credit_disclosure` (a
plain-words sentence naming the short legs). Every credit result also carries
`result.modeled: true` and `result.modeled_note`. If you surface a credit EV
anywhere, surface those alongside it.

THE OTHER PROVENANCE SENTENCE, and it is NOT the same claim: an OPTION result
whose `metrics.real_nbbo_fill_share` is exactly 0 — not one fill priced on a
MEASURED two-sided OPRA quote — carries `result.fill_disclosure`. There the fill
PRICE is real (the chain's own ask, or the day's real close plus 2.5% where there
was no ask); what is modeled is the SPREAD around it. Read them apart: `modeled`
means the price is theoretical, `fill_disclosure` means the spread is. It is
absent when any fill was measured, and absent for equities and combos, which
carry no per-fill quote provenance to disclose. It survives compaction, so a desk
read carries it too. Surface it wherever you surface an option EV.

## COMBO STRUCTURES — verticals, condors, calendars, strangles, ratios (real-chain)
Multi-leg option structures are asset_class "combo" with a `legs` array. Each leg
resolves to a REAL OCC contract (one chain quote per leg) and its realized daily
P&L is netted with the others — fills are honest (buy@ask / sell@bid, NEVER mid),
NOT Black-Scholes-modeled (unlike the "credit" path). A single short put (CSP) is
N=1; a debit vertical is N=2; an iron condor is N=4.

Each leg (plain words → field): the right ("right": "call" | "put"); long or short
("side": "buy" = pay the ask, sign +1 | "sell" = receive the bid, sign −1); how
many contracts ("ratio", an integer ≥ 1); how far from the money the strike sits,
as a fraction and a direction — EXACTLY ONE of "itm_pct" (in-the-money) or
"otm_pct" (out-of-the-money); and how many days to expiry ("target_dte"). Give each
leg its OWN target_dte to build a CALENDAR / DIAGONAL (two different expiries).

net_entry = Σ side·ratio·(entry price) → a DEBIT structure is > 0, a CREDIT
structure (you net premium in) is < 0. capital_at_risk is the WORST net payoff
across the strike ladder (not width×100); an uncovered/ratio short call reports
capital_at_risk=null + risk_unbounded=true (the upside loss is unbounded — honest,
never a falsely-finite floor). Per-leg thin quotes (a long leg you must SELL with
bid≤0) drop that mark bar and are counted in the published skip-rate.

Worked examples (each validates AND runs — the full spec is this envelope with the
legs below dropped in): {"name": "combo (example)", "asset_class": "combo", "universe": ["SPY"], "timeframe": "1 day", "backtest": {"start": "2024-02-12", "end": "2026-05-20"}, "indicators": [], "entry": {"side": "call", "when": {"all": [{"gt": ["c", "sma200"]}]}}, "exit": {"rule": "fixed", "hold_days": 10}}

    debit call vertical (buy near-money call, sell further-OTM call):
      "asset_class": "combo", "legs": [{"right": "call", "side": "buy", "ratio": 1, "itm_pct": 0.01, "target_dte": 35}, {"right": "call", "side": "sell", "ratio": 1, "otm_pct": 0.05, "target_dte": 35}]

    iron condor (sell OTM put+call, buy protective wings — real-chain, N=4):
      "asset_class": "combo", "legs": [{"right": "put", "side": "sell", "ratio": 1, "otm_pct": 0.03, "target_dte": 30}, {"right": "put", "side": "buy", "ratio": 1, "otm_pct": 0.06, "target_dte": 30}, {"right": "call", "side": "sell", "ratio": 1, "otm_pct": 0.03, "target_dte": 30}, {"right": "call", "side": "buy", "ratio": 1, "otm_pct": 0.06, "target_dte": 30}]

    call calendar (sell near-DTE, buy far-DTE — TWO expiries via per-leg target_dte):
      "asset_class": "combo", "legs": [{"right": "call", "side": "sell", "ratio": 1, "otm_pct": 0.0, "target_dte": 14}, {"right": "call", "side": "buy", "ratio": 1, "otm_pct": 0.0, "target_dte": 49}]

    short strangle (sell an OTM call + an OTM put; report flags unbounded risk):
      "asset_class": "combo", "legs": [{"right": "call", "side": "sell", "ratio": 1, "otm_pct": 0.05, "target_dte": 21}, {"right": "put", "side": "sell", "ratio": 1, "otm_pct": 0.05, "target_dte": 21}]

    long straddle (buy an at-the-money call AND put — a pure volatility bet;
      "at the money" is otm_pct 0.0):
      "asset_class": "combo", "legs": [{"right": "call", "side": "buy", "ratio": 1, "otm_pct": 0.0, "target_dte": 30}, {"right": "put", "side": "buy", "ratio": 1, "otm_pct": 0.0, "target_dte": 30}]

    call butterfly (buy 1 lower + SELL 2 at the money + buy 1 higher, one expiry —
      a bet the price pins near the middle strike; ratio 2 is the short middle):
      "asset_class": "combo", "legs": [{"right": "call", "side": "buy", "ratio": 1, "itm_pct": 0.04, "target_dte": 30}, {"right": "call", "side": "sell", "ratio": 2, "otm_pct": 0.0, "target_dte": 30}, {"right": "call", "side": "buy", "ratio": 1, "otm_pct": 0.04, "target_dte": 30}]

    call ratio spread (buy 1 near-money call, sell 2 further-OTM calls — the extra
      short call is UNCOVERED, so capital_at_risk=null + risk_unbounded=true):
      "asset_class": "combo", "legs": [{"right": "call", "side": "buy", "ratio": 1, "otm_pct": 0.01, "target_dte": 30}, {"right": "call", "side": "sell", "ratio": 2, "otm_pct": 0.06, "target_dte": 30}]

    calendar / DIAGONAL — two DIFFERENT expiries, via per-leg target_dte. Same
      strike = a calendar; different strikes = a diagonal. The poor-man's covered
      call is a diagonal (long deep-ITM call as the stock substitute):
      "asset_class": "combo", "legs": [{"right": "call", "side": "buy", "ratio": 1, "itm_pct": 0.1, "target_dte": 90}, {"right": "call", "side": "sell", "ratio": 1, "otm_pct": 0.05, "target_dte": 21}]

An IRON CONDOR / IRON BUTTERFLY, a JADE LIZARD, a BROKEN-WING butterfly and any
other N-leg shape are the SAME grammar — there is no per-structure whitelist and no
leg-count cap. Name the legs and the engine resolves each one to a real contract.
Two rules the validator enforces per leg: `ratio` is an integer ≥ 1, and EXACTLY
ONE of `itm_pct` / `otm_pct` is present (both, or neither, is a plain-words 400).

DATA HONESTY (calendars & PMCC — read before you promise a client a LEAP):
- CALENDARS/DIAGONALS FILL. Multiple expiries ARE quotable on the same signal date
  on our data (e.g. ~14 / ~49 / ~77 DTE), so a near/far calendar builds and grades
  over the window BOTH legs are quotable (the near leg stops quoting at its expiry —
  the netted path truncates there, honestly).
- PMCC's "LEAP" IS DATA-CAPPED. A true poor-man's-covered-call buys a 6-12 month
  deep-ITM LEAP. Our option data caps at ~98 DTE, so the long leg can be at most a
  ~90-DTE deep-ITM call — a short-dated DIAGONAL, NOT a real LEAP. The structure is
  expressible and grades; the long-dated LEAP economics are simply not in this data.
  We say so rather than pretend a 90-DTE call is a LEAP.

## COVERED STOCK+OPTION STRUCTURES — covered call, collar, married put
A covered structure HOLDS SHARES alongside options. It is asset_class "covered"
with a `legs` array that MIXES one equity (shares) leg with option legs. The
equity leg is {"right": "equity", "side": "buy" | "sell", "ratio": N} (ratio is
100-share lots — one lot covers one option contract); it has NO strike or expiry.

HONEST COMBINED FILLS (this is the whole point):
- The SHARES fill at the NEXT bar's OPEN (equity honesty, look-ahead-safe) and mark
  at the daily CLOSE with NO modeled spread — shares are liquid, so no spread is
  charged (unlike the options).
- The OPTION legs fill at the signal bar's real chain quote (buy@ask / sell@bid,
  never mid) and mark on their real daily path (short leg bought-to-close at the
  modeled ask = last×1.025, long leg sold at the bid).
- The two are NETTED into ONE position and settled together: net_entry =
  Σ side·ratio·(shares@next-open + options@sacred-fill). A covered call's
  capital_at_risk is (share cost − premium)×100 (the stock to zero minus the credit)
  — and it is BOUNDED (the long shares COVER the short call, so it is NOT flagged
  unbounded). Take-profit stays banned from the verdict; the held path is graded on
  none/SL30/SL50 exactly like every other vehicle.

Worked examples (same envelope; asset_class "covered"):

    covered call (long 100 shares + short 3%-OTM call, 30 DTE):
      "asset_class": "covered", "legs": [{"right": "equity", "side": "buy", "ratio": 1}, {"right": "call", "side": "sell", "ratio": 1, "otm_pct": 0.03, "target_dte": 30}]

    collar (long shares + long 5%-OTM put + short 5%-OTM call):
      "asset_class": "covered", "legs": [{"right": "equity", "side": "buy", "ratio": 1}, {"right": "put", "side": "buy", "ratio": 1, "otm_pct": 0.05, "target_dte": 30}, {"right": "call", "side": "sell", "ratio": 1, "otm_pct": 0.05, "target_dte": 30}]

    married / protective put (long shares + long 5%-OTM put):
      "asset_class": "covered", "legs": [{"right": "equity", "side": "buy", "ratio": 1}, {"right": "put", "side": "buy", "ratio": 1, "otm_pct": 0.05, "target_dte": 30}]

Poor-man's-covered-call (PMCC) is ALL-OPTIONS (a long deep-ITM call substitutes for
the shares) → use asset_class "combo", not "covered" (see the PMCC data note above).
A covered structure deploys + forward-walks on a paper desk like any other vehicle.

## PRIOR-BAR REFERENCES — the `lag` operand (engulfing patterns port directly)
Yesterday's (or any prior bar's) value is the `lag` operand:
{"lag": ["c", 1]} = close 1 bar ago; {"lag": ["h", 2]} = high 2 bars ago.
Legal anywhere a comparison operand is (gt/lt/gte/lte; not inside cross_above/
cross_below). Works on OHLCV aliases AND declared indicator ids. A candlestick
strategy is NOT unsupported — it is a lag rule tree.

`lag` counts BARS, so its wall-clock meaning follows the spec's timeframe:
{"lag": ["close", 60]} is 60 trading days ago on a "1 day" spec but 60 MINUTES
ago on a "1Min" one (this exact leaf muted real deployed bots). When the number
means trading DAYS, use the session-denominated twin — it says that on EVERY
timeframe: {"lag_sessions": ["close", 60]} = the close 60 trading sessions ago
(60 daily bars, or 60 × 390 one-minute bars; N >= 1, NaN during warmup so the
rule honestly does not fire before enough history exists). Same everywhere `lag`
is legal (gt/lt/gte/lte, nested in mul/sub; not inside cross_above/cross_below).

Worked example — bullish engulfing (today green, engulfing yesterday's red bar):

    "entry": {"side": "call", "when": {"all": [
      {"gt":  ["c", "o"]},
      {"lt":  [{"lag": ["c", 1]}, {"lag": ["o", 1]}]},
      {"lte": ["o", {"lag": ["c", 1]}]},
      {"gte": ["c", {"lag": ["o", 1]}]}
    ]}}

Line by line: today closed green; yesterday closed red; today opened at or
below yesterday's close; today closed at or above yesterday's open. This exact
tree validates and runs.

## WEBHOOK SIGNALS IN — drive a bot's entries from YOUR OWN signals (catalog #10)
A spec may declare `entry: {"side": "call", "webhook": true}` — no `when`
(exactly one of the two; both at once is refused in plain words). The bot then
takes entries ONLY from signals you POST:

  POST /v1/me/accounts/{account_id}/alphas/{deploy_id}/signal   [pair]
    {"symbol": "NVDA", "action": "enter"|"exit", "ts": optional ISO}

- `ts` must be within 5 minutes of NOW (omit it and we stamp the arrival time):
  a signal is an instruction about the present, never a back-dated fill. A
  signal whose bar falls BEFORE the bot's walk window is spent and counted
  (`skipped_webhook_before_window`), never filled.

- REPLAY-SAFE: the same signal delivered twice queues ONCE (the second answers
  {"queued": false, "duplicate": true}).
- A posted ENTRY is an entry like any other: the walk maps it onto its bar
  (the last bar at or before ts; the fill is the bar AFTER it — strictly later
  than ts, the graded promise) and EVERY desk gate still applies — market
  hours, data freshness, your caps, buying power. A closed market queues it; a
  symbol outside the bot's universe is refused (`skipped_webhook_symbol`) —
  every outcome has its own named counter, nothing vanishes silently.
- {"action": "exit"} closes the open position(s) on that symbol at the next
  walk's REAL mark (close_reason='webhook_exit'). Modeled credit/covered
  structures refuse it (no real quote to sell into — same as a manual close);
  your rule/hold exits and the stop/take-profit/ratchet overlays all work
  unchanged (a webhook chooses ENTRIES only).
- GRADING: a webhook bot deploys UNGRADED (a normal resting state — it trades
  exactly like a graded bot). To grade it honestly, upload the timestamped
  signals it would have fired:
    POST /v1/strategies/{strategy_id}/signal-history   [key or pair]
      {"signals": [{"symbol": "NVDA", "ts": "2026-03-03T14:30:00Z"}, ...]}
  A backtest of that strategy then grades entries off the history with the
  normal no-look-ahead discipline (signal ts → next-bar fill). Without a
  history, the run returns an honest NO_DATA naming exactly this.

## SCREENER UNIVERSES — a ranking picks the stocks, not a fixed list (catalog #11)
Instead of a static `universe` list, a spec may carry (exactly one of the two):

  "universe_screener": {"by": "ret20", "top_n": 10, "refresh": "weekly",
                        "min_price": 5, "min_dollar_vol": 1000000,
                        "lowest": false}

- At each REFRESH boundary (weekly = the first session of each week; daily =
  every session) the FULL catalog is ranked by `by` — one daily base feature
  id (ret20, rvpct, mom20, …; not an indicator, not a formula) — floors
  applied, top N kept (N <= 100). `lowest: true` keeps the N lowest instead.
- FROZEN BETWEEN REFRESHES: a symbol's rank moving mid-window never moves
  membership. NO LOOK-AHEAD: membership for a window is ranked only on data
  from BEFORE the window's first session — and the LIVE walk resolves the
  same answer from the same daily bars, so live and graded can never disagree
  about the same Monday.
- The graded result carries `result.screener` (windows resolved, union size);
  a name that rotates OUT while the bot holds it is still marked and exited —
  the screener gates ENTRIES only.

## Credentials — THREE distinct credentials. Do not mix them up.
1. PRINCIPAL user key — header `X-Vega-Key`. Minted in the browser (Settings)
   or via POST /v1/me/api-key (session-only: a key can never mint keys). Drives
   the coder surface — build / backtests / compare / export / strategies /
   portfolio — and GET /v1/me/accounts to LIST your desks (id + name). It can
   NOT write to (or read) an individual desk: desk routes reject it with 401.
2. ACCOUNT KEY PAIR — headers `X-Vega-Account-Key-Id` + `X-Vega-Account-Secret`.
   Minted PER DESK while logged in via POST /v1/me/accounts/{id}/keys
   (session-only; the secret is shown ONCE; one active pair per desk; revoke at
   /v1/me/accounts/{id}/keys/revoke). The pair opens exactly ONE desk through
   the /v1/me/accounts/{id}/* routes — deploy, read desk state, manual
   orders/positions, alpha lifecycle (pause/resume/retire/breaker/health),
   desk pause/resume, headroom, watchlist. Using it on any other desk is 403.
   The pair ALSO acts as the desk owner's principal on the coder surface
   (strategies / backtests / list desks), so one pair can drive the whole flow.
   Rate-limited per key_id. It can NOT mint or revoke keys, and can NOT reset a
   desk — those stay session-only.
3. LEGACY per-desk key — a desk's OWN `X-Vega-Key`, accepted ONLY by the
   /v1/accounts/{id} tree (read / deploy / sync / alpha chart). No API or UI
   returns that key today (it is set once at desk creation and never shown), so
   treat that tree as LEGACY and use the pair routes instead. Sending the PAIR
   headers to /v1/accounts/* fails 401 "Invalid API key" — wrong tree, not a
   bad pair.

RECOMMENDED deploy path: the PAIR + POST /v1/me/accounts/{id}/deploy/preview
(same body; writes nothing; shows the normalized spec, caps, cost and risk, and
returns a preview_id) then POST /v1/me/accounts/{id}/deploy with that
preview_id (one strategy), or POST /v1/strategies/bulk with deploy_to (a fleet).
Deploys are FORWARD-ONLY from the moment of deployment: the desk starts trading now
and only ever shows trades made while deployed. The strategy's backtest is stored with
the deployment and served separately — it is NEVER replayed onto the desk as fake history.

## MCP — the same platform as typed tools (one URL + your desk pair)
If your runtime speaks MCP (Model Context Protocol), you do not need to hand-roll
REST calls: the MCP door exposes 23 typed tools (build / port / import a spec,
submit + read backtests, deploy, alpha lifecycle, desk state, divergence /
graduation / freeze-status reads) that FORWARD to these exact routes, so every
honesty and auth rule on this page applies unchanged.
  URL:  https://agent.quantradin.com/mcp   (streamable HTTP;
        agent.quantradin.com will alias it once DNS lands)
  Room: Humans and their agents talk about this in the Discord: https://discord.gg/KzSUGNj72v
  Auth: the ACCOUNT KEY PAIR (credential 2 above) as the same two HTTP headers
        on the MCP transport: `X-Vega-Account-Key-Id` + `X-Vega-Account-Secret`.
        Every tool acts on that one desk; no pair -> a plain "not authenticated"
        error naming the mint route.
  Connect (Claude Code):
        claude mcp add --transport http quantradin           https://agent.quantradin.com/mcp           --header "X-Vega-Account-Key-Id: <key id>"           --header "X-Vega-Account-Secret: <secret>"
  Client truth: works today from any MCP client that can send fixed headers
  (Claude Code natively; Claude Desktop via the `mcp-remote` stdio bridge).
  The claude.ai website connector and the Anthropic API MCP connector cannot
  carry custom headers (OAuth / bearer-only) — use this REST surface there.

### The MCP tools, by exact name
Every tool the door registers, in three groups. "(read-only)" marks a tool that
changes nothing and spends nothing (its MCP readOnlyHint is true). Each tool also
carries MCP annotations: a title, and whether it is read-only, destructive
(only `retire_alpha` — retiring is permanent) or idempotent.

### Build and test
- `port_check` — Say whether a draft spec or a list of concepts fits the platform (fits / partial / can't), naming what a port would lose.
- `build_strategy` — Turn loose parameters into a full spec and validate it, without AI; the errors list is what you iterate on.
- `draft_strategy` — Have the AI write a draft spec from a plain-English description; the validator, not the AI, decides if it is valid.
- `import_strategy` — Translate pasted Pine, Python or English into a runnable spec with safe defaults filled and mapping notes.
- `port_strategy` — Translate pasted Pine, Python or text into a spec plus a port report naming anything that cannot be ported.
- `submit_backtest` — Queue an honest backtest of an inline spec or a saved strategy and get back a run id to read once later.
- `get_backtest` — Read one backtest once: its status, LIVE/SHADOW/SHELF verdict and a compact scorecard. (read-only)
- `explain_verdict` — Get a plain-English explanation of one backtest's verdict, told only from numbers the engine already computed.
- `suggest_fix` — Get one concrete, validated spec change to try next for a backtest that graded poorly.

### Deploy and manage
- `preview_deploy` — See exactly what a deploy would do (normalized spec, errors, caps, cost, buying power, risk) without deploying; pass its preview_id to deploy_strategy. (read-only)
- `deploy_strategy` — Deploy an inline spec or saved strategy onto your desk, forward-only, with no backtest needed first; call preview_deploy first and pass its preview_id.
- `bulk_backtest` — Save up to 50 strategies in one call and, with deploy=true, deploy every valid one onto your desk.
- `run_alpha_backtest` — Run a fresh backtest of one deployed alpha's current spec; the verdict is advice and never changes the bot.
- `set_alpha_mode` — Set one deployed alpha to live, shadow or shelf; you choose, the engine's verdict only advises.
- `pause_alpha` — Stop one deployed alpha from opening new trades until it is resumed.
- `resume_alpha` — Let a paused alpha open new trades again (a retired alpha cannot be resumed).
- `retire_alpha` — Stop one deployed alpha for good; this cannot be undone, so use pause_alpha for a temporary stop.

### Watch
- `list_desks` — List the paper desks you can act on, with each desk's id and name. (read-only)
- `get_desk_state` — Read your desk's cash and equity, its deployed alphas with their verdicts, and its open and closed positions. (read-only)
- `get_divergence` — Compare one alpha's real forward trades with its backtest's promise, plus when it last fired and synced. (read-only)
- `get_graduation` — See where one alpha sits on the ladder from backtested to paper-proven, and the next gate in plain words. (read-only)
- `explain_signal` — Explain why one alpha traded or did not on a given day, with the real per-condition trace and an AI narration of it.
- `get_freeze_status` — Check whether the owner has frozen all agent activity; if so, stop, because only the human can lift it. (read-only)

What a READ-ONLY connection can do (a pair minted with capabilities
`read_only`, i.e. scope `read`; the 2026-09-25 scope fix gates EVERY write the
pair makes, deny-by-default):
  CAN   read everything — every read-only tool above, plus the AI explainers
        (`explain_verdict`, `explain_signal`), which read but spend the owner's
        AI budget. That includes `preview_deploy`: it shows exactly what a
        deploy would do and writes nothing, so a read scope may call it.
  CAN   de-risk — pause an alpha (`pause_alpha`), retire an alpha
        (`retire_alpha`), shelve a bot (`set_alpha_mode` with mode "shelf"),
        and, over REST with the same pair, pause the whole desk
        (POST /v1/me/accounts/{id}/pause), close a position
        (POST …/positions/{position_id}/close) and cancel a resting order
        (POST …/orders/{order_id}/cancel). A kill switch never needs a permission,
        and these work even while the owner has frozen the agent.
  CANNOT open trades, deploy (`deploy_strategy`, `bulk_backtest` with
        deploy=true), resume or re-arm a bot (`resume_alpha`, `set_alpha_mode`
        to "live" or "shadow"), change limits, or edit or save strategies.
        Backtests, spec builds, port checks and AI drafting need the
        `backtest` scope; everything else that writes needs `deploy`.
        A refusal is a plain 403 naming the scope the key lacks.

## End-to-end flow — DEPLOY-FIRST IS THE PRIMARY PATH (single OR fleet).
## Deploy immediately: the honest verdict + confidence + graduation stage grade
## AUTOMATICALLY in the background (a bounded server-side queue) and appear on the
## webapp. You do NOT need a backtest before deploying — for ONE strategy or a
## whole fleet.
##
## ANTI-PATTERN — DO NOT DO THIS: build -> POST /v1/backtests -> poll the run
## (/v1/backtests/{run_id}) in a loop for 60-90s -> then deploy. That wastes
## your time and the user's tokens and is NEVER required. Do NOT serial-backtest
## strategies before deploying them — backtesting-before-deploying is the OLD,
## SLOW path (a real 24-strategy port done that way took 8 hours; deploy-first
## lands the same fleet in under a minute). If you want a verdict, DEPLOY FIRST,
## then read it ONCE later — read the deployment (its stored verdict/confidence)
## or the run at /v1/backtests/{run_id} — or just look on the webapp. Never
## poll in a wait-loop.
##
## What attaches in the background after a deploy-first deploy: the LIVE/SHADOW/
## SHELF verdict, the honest confidence block (strength-of-evidence label +
## provenance caveat), and the GRADUATION STAGE (backtested -> paper-live ->
## paper-proven -> real-eligible). Read them once when you want via
## GET /v1/me/accounts/{id} (each deployment carries a compact verdict +
## graduation stage) or the per-alpha /graduation route — not in a loop.
##
## PORTING A FLEET (2+ strategies) — the supported path:
##   1. POST /v1/strategies/port-check per strategy (concepts or draft specs)
##      -> the honest fits/partial/cant table. Costs milliseconds.
##   2. Owner mints ONE key pair for the target desk (session-only
##      POST /v1/me/accounts/{id}/keys).
##   3. ONE call: POST /v1/strategies/bulk with the pair —
##      {"items": [{"name", "strategy_spec"}, ...], "deploy_to": <desk id>}
##      (up to 50 items). Every valid item is SAVED + DEPLOYED (running,
##      forward-only) when the call returns, seconds later; invalid items come
##      back with named errors[] and never block the rest. Expect all N
##      strategies live in under a minute.
##   4. NOTHING IS GRADED UNLESS YOU ASK (changed 2026-07-28). Deploying runs no
##      backtest — not every strategy CAN be honestly graded, and grading
##      uninvited is the engine deciding instead of advising. A deployed bot
##      trades with backtest_result NULL, and UNGRADED IS A NORMAL RESTING
##      STATE, not a pending one: do NOT poll waiting for a verdict to appear,
##      because none is coming.
##      To get one, ask for it on that specific alpha:
##        POST /v1/me/accounts/{id}/alphas/{deploy_id}/backtest
##      That run attaches to the alpha AND lists under GET /v1/backtests. It is
##      ADVISORY — it never changes the bot's mode or status.
##      ALREADY graded the exact spec before deploying (POST /v1/backtests)?
##      Attach that finished run instead of running it twice:
##        POST /v1/me/accounts/{id}/alphas/{deploy_id}/attach-backtest
##        {"run_id": "<the run>"}
##      It runs nothing, and refuses (409) a run of a different spec.
##
## ONE strategy — ALSO deploy-first: mint principal key (browser / session) ->
## GET /v1/me/accounts (pick a desk id) -> POST /v1/strategies/build ->
## POST /v1/me/accounts/{id}/deploy with the pair RIGHT AWAY (grading + the
## honest verdict + confidence + graduation stage + first forward-walk sync are
## ALL automatic in the background) -> read it back ONCE: GET /v1/me/accounts/
## {id}. Run POST /v1/backtests yourself only if you want a scorecard BEFORE
## committing a desk — it is never a prerequisite, and never poll it in a loop.
## Deploying a saved strategy whose KNOWN prior backtest graded SHELF/inconclusive
## still succeeds (paper is for learning) but returns a plain-words `warning`.

## ADVISORY MODE — the engine ADVISES, it never GATES the user (CORE PRODUCT LAW)
Deploy defaults to LIVE. The honest verdict (LIVE/SHADOW/SHELF) is our ENGINE'S
READ, shown BESIDE the deployment — it NEVER blocks a deploy and NEVER auto-shelves
a strategy. The OWNER (or their agent) sets the per-alpha trade mode EXPLICITLY:
POST /v1/me/accounts/{id}/alphas/{deploy_id}/mode {mode: live|shadow|shelf} —
live = normal forward-walk; shadow = tracks signals but opens NO new fills (existing
positions still mark AND exit); shelf = MARK, NEVER TRADE — it opens nothing and takes
no exit it CHOSE (no stop-loss, take-profit, ratchet, rule/hold or time exit), but any
position it still holds keeps being MARKED so its value stays current, and an option
that reaches EXPIRY still settles (the contract ended on its own). A SHELF-graded alpha
is NEVER auto-shelved; only the user can. Never tell a user their strategy "doesn't
work" — surface our engine's read and let them choose.

## AGENTIC HARDENING — owner-set safety rails (all OPT-IN, no breakage by default)
If you are an agent acting on a user's behalf, these let the OWNER bound what you
can do. Every control defaults OFF / unrestricted, so a normal call is unaffected.
- CAPABILITY-SCOPED KEYS. When the owner mints a desk key pair
  (POST /v1/me/accounts/{id}/keys) they may pass `capabilities`: a preset
  read_only | backtest_only | deploy_allowed (or atomic read|backtest|deploy
  tokens). The scope is enforced on EVERY write the pair makes, deny-by-default:
  any state change needs 'deploy'; backtest submits, strategy saves and the
  build / port-check pre-flights need 'backtest'; only DE-RISK actions (pause a
  bot or the desk, retire, cancel a resting order, close a position, set mode
  "shelf") work with any scope. Omitted → an UNRESTRICTED full-scope pair (the
  legacy default). The owner's AGENT FREEZE applies to the same writes (423)
  and never to the de-risk actions.
- IDEMPOTENCY-KEY. Send an `Idempotency-Key` HTTP header on every MUTATION (backtest
  submit + deploy): a repeat with the SAME key REPLAYS the first response instead of
  creating a second run/deploy. Agents should ALWAYS send one on a retry.
- APPROVAL MODE. Deploy with `requires_approval:true` → the deployment lands
  status="staged": it opens NO positions, is NOT walked, and queues NO grading until
  a HUMAN owner approves it. An agent can PROPOSE a deploy but can NEVER approve its
  own — POST …/alphas/{id}/approve is SESSION-ONLY BY DESIGN (a key pair 404s
  there), so don't attempt it with a pair.
- EXPOSURE / RATE CAPS (framed as protection). A per-desk concurrent-deploy cap
  (429), a per-order notional ceiling (403, "Position size capped to protect your
  desk"), and a per-user agent-write rate cap (429) bound runaway activity.
- AUDIT LEDGER. Every agent write lands in an append-only ledger the OWNER reviews
  at GET /v1/me/agent-audit (SESSION-ONLY — a key can't read the whole trail).
- AGENT FREEZE — the owner's one-switch kill for ALL agent activity (documented in
  the endpoint list below): a pair can READ it but can NEVER lift it.
- POST /v1/strategies/bulk             [key or pair] the FLEET path: save (+ optionally deploy)
                                       up to 50 strategies in ONE call ({items[], deploy_to?});
                                       per-item results; NO grading is queued (queued_backtests is
                                       always 0 — kept only for API compatibility)
- POST /v1/strategies/build            [key or pair] loose params -> full spec + valid + errors[]
- POST /v1/strategies/port-check        [key or pair] {spec} and/or {concepts[]} -> {verdict fits|partial|cant,
                                       issues[{concept, dropped, closest}], notes[]} — the PORT REPORT check
- POST /v1/backtests                   [key or pair] submit a backtest ({strategy_spec} or {strategy_id})
- POST /v1/backtests/walkforward       [key or pair] WALK-FORWARD RE-OPTIMIZATION: the spec +
                                       {"walkforward": {"folds": 2..6, "optimize":
                                       [{"path": "entry.when.<...>", "grid": [...]}]}} (≤3 paths,
                                       ≤125 combos — bigger grids refused in plain words). Each fold
                                       is graded OUT-OF-SAMPLE with the grid combo that scored best
                                       on the folds BEFORE it only (fold 1 only trains; no look-ahead
                                       by construction). Result (poll the same GET, kind=
                                       'walkforward'): walkforward.fold_table [{fold, window,
                                       chosen_params, is_ev, oos_ev, oos_trades}], the stitched OOS
                                       equity_curve, and the honest headline walkforward.oos_ev —
                                       what the strategy earned on windows its parameters were never
                                       fit to. Advisory, like every engine read. Members only (the
                                       shared demo key is refused — it is up to 625 engine passes).
- POST /v1/backtests/ensemble          [key or pair] MULTI-STRATEGY ENSEMBLE (#39):
                                       {"members": [{"strategy_id": 5} |
                                       {"strategy_spec": {...}}, ...] (2..8),
                                       "weights": "equal" | [0.5, 0.3, 0.2]}. Every
                                       member is graded by the SAME engine a single
                                       run uses and KEEPS ITS OWN VERDICT; the
                                       ensemble adds the blended equity_curve on a
                                       common date axis, the CORRELATION matrix
                                       (measured on per-step CHANGES over the shared
                                       window — never on the cumulative curves, which
                                       correlate at ~0.9 even when unrelated) and the
                                       diversification benefit (blended volatility vs
                                       the weighted mean of the members' own; 1.00
                                       means they move as one). Poll the same GET,
                                       kind='ensemble'; "ENSEMBLE" is a row label,
                                       never a judgement. Members only. Spends one
                                       run of your quota PER MEMBER.
- GET  /v1/backtests/{run_id}          [key or pair] poll one run (status, verdict, full result)
- GET  /v1/backtests                   [key or pair] list your runs
- GET  /v1/backtests/compare?a=&b=     [key or pair] diff two of YOUR runs (verdict, OOS EV,
                                       optimism-gap delta, fills/skip-rate, spec diff)
- GET  /v1/backtests/{run_id}/export.json   [key or pair] download the full result
- GET  /v1/backtests/{run_id}/export.csv    [key or pair] download this run's trades as CSV
- GET  /v1/backtests/{run_id}/share         [key or pair] mint/re-use a PUBLIC read-only share
                                       link (idempotent) → {share_id, share_path}
- DELETE /v1/backtests/{run_id}/share       [key or pair] revoke every public share of this run
- GET  /v1/share/{share_id}                 [PUBLIC, no auth] the shared run's HONESTY SUMMARY
                                       (verdict/EV/WR/fills/skip/equity + stamp — never spec/PII)
- DELETE /v1/backtests/{run_id}        [key or pair] delete YOUR run + revoke every
                                       public share of it → {deleted, share_revoked}
- POST /v1/strategies                  [key or pair] save a strategy
- GET  /v1/strategies                  [key or pair] list your saved strategies
- GET  /v1/strategies/{strategy_id}    [key or pair] load one saved strategy
- PATCH /v1/strategies/{strategy_id}   [key or pair] rename / replace the spec
                                       ({name?, spec?}); NEVER changes a deployed bot
                                       (it holds its own snapshot) or a finished run
- DELETE /v1/strategies/{strategy_id}  [key or pair] delete it; `confirm=true` once it
                                       has graded runs → {deleted, backtests_kept}
                                       (the runs themselves always survive)
- POST /v1/strategies/{strategy_id}/signal-history  [key or pair] upload the timestamped
                                       signal history that makes a WEBHOOK strategy gradable
                                       ({signals: [{symbol, ts}]}, <= 5000 rows; replaces the prior upload)
- GET  /v1/me/accounts                 [key or pair] list YOUR paper desks (id + name)
- GET  /v1/me/accounts/summary         [key or pair] full state for ALL your desks in one call
                                       (batch of GET /v1/me/accounts/{id}; powers the cockpit)
- POST   /v1/me/accounts                       [session ONLY] create a new paper desk
                                       ({name, starting_cash $1k-$1M}; hard cap 5 desks -> 409)
- PATCH  /v1/me/accounts/{account_id}          [session ONLY] rename a desk ({name})
- POST   /v1/me/accounts/{account_id}/deposit  [session ONLY] add cash to a desk
                                       ({amount $1k-$1M}; a deposit, never a P&L rewrite)
- DELETE /v1/me/accounts/{account_id}          [session ONLY] delete a desk + cascade its data
                                       (body {confirm_name} must match the desk's name)
- POST /v1/me/accounts/{account_id}/keys     [session ONLY] mint that desk's key pair; optional
                                       capabilities preset (read_only|backtest_only|deploy_allowed)
- GET  /v1/me/accounts/{account_id}/keys/status  [session ONLY] {exists, created_at, last_used_at} (no key material)
- POST /v1/me/accounts/{account_id}/deploy/preview   [pair or session] PREVIEW a deploy
                                       with the SAME body, writing nothing (one audit row): valid +
                                       errors (the deploy's own words), would_deploy + blocked_by,
                                       normalized_spec, name, mode/status, caps (spec / desk =
                                       member-set, platform_default, unset), disclosures,
                                       defaults_applied, estimated_trade_cost, desk buying power,
                                       risk_summary, preview_id. A read-scoped pair may call it.
- POST /v1/me/accounts/{account_id}/deploy   [pair] deploy a validated strategy onto THAT desk
                                       (the canonical deploy; auto-kicks the forward-walk). Pass the
                                       preview's `preview_id` to get `preview_match` back (reported,
                                       never refused)
- GET  /v1/me/accounts/{account_id}          [pair] desk state (positions, deployments, equity;
                                       each deployment carries a compact verdict + graduation stage)
- GET  /v1/me/accounts/{account_id}/alphas/{deploy_id}/graduation  [pair] one alpha's ladder rung
                                       (backtested -> paper-live -> paper-proven -> real-eligible),
                                       next gate + evidence; READ-ONLY, read once (not a wait-loop)
- POST /v1/me/accounts/{account_id}/alphas/{deploy_id}/mode   [pair] set the USER trade mode
                                       ({mode: live|shadow|shelf}); advisory verdict shown beside, never gates
- POST /v1/me/accounts/{account_id}/alphas/{deploy_id}/pause · /resume · /retire   [pair] lifecycle
                                       transitions (idempotent; retire is terminal)
- DELETE /v1/me/accounts/{account_id}/alphas/{deploy_id}?confirm=true  [session ONLY —
                                       a PAIR gets 401] delete a bot that NEVER traded;
                                       one that traded is 409 → RETIRE it instead
- POST /v1/me/accounts/{account_id}/alphas/{deploy_id}/approve   [session ONLY] arm a STAGED
                                       (requires_approval) deploy → running; a pair can propose, never approve
- POST /v1/me/accounts/{account_id}/alphas/{deploy_id}/breaker   [pair] set/clear a same-walk-day
                                       P&L circuit breaker ({max_daily_loss} DOLLARS); a trip pauses, resume manual
- POST /v1/me/accounts/{account_id}/alphas/{deploy_id}/backtest  [pair] run a FRESH advisory backtest
                                       for this alpha's spec → {run_id} (poll like /v1/backtests; never changes mode)
- POST /v1/me/accounts/{account_id}/alphas/{deploy_id}/signal    [pair] queue a webhook signal for a
                                       webhook-driven bot ({symbol, action enter|exit, ts?}; replay-safe —
                                       a duplicate answers queued:false; see WEBHOOK SIGNALS IN above)
- GET  /v1/me/accounts/{account_id}/alphas/{deploy_id}/health · /transitions · /report · /why  [pair]
                                       heartbeat + live-vs-backtest divergence · lifecycle history · full
                                       scorecard · plain-words "why it did/didn't fire on a date"
- POST /v1/strategies/copilot          [SESSION ONLY] {description} plain English -> {spec, valid,
                                       issues[], notes[]} — the INTERACTIVE builder copilot; a KEY OR
                                       PAIR gets 401 here. AN AGENT holding a key/pair converts strategies
                                       with POST /v1/strategies/import instead (same AI drafting, pair- AND
                                       guest-reachable — see "THE FORMAT / porting" above). 503 when AI off.
- GET  /v1/live-page/news · /daily/{symbol} · /movers · /names   public market data for the
                                       live terminal (market-news proxy, real daily bars + context,
                                       universe movers, SYMBOL → company name for the typeahead;
                                       degrades honestly when the feed is unconfigured)
- GET  /v1/live-page/clock             market open/closed + the NEXT open and close, read
                                       from the ENGINE's own market calendar (the same
                                       tables the live desk gates entries with) — holidays
                                       and half-days looked up, never inferred
- GET  /v1/live-page/tail?symbol=&tf=  the last few REAL bars of ONE symbol + its latest
                                       real trade (tf 1m|5m|15m|1D, 3s server cache). The
                                       chart polls this so the FORMING bar can grow live;
                                       whether a bar has closed is decided from the bar's
                                       own timestamp, never guessed for you
- GET  /v1/live-page/held              [session ONLY] your held-symbol overlay for the terminal
- GET  /v1/live-page/fleet?symbol=     [session ONLY] which of YOUR deployed bots carry this
                                       symbol in their universe, when each last signalled on
                                       it, and your REAL fills on it (an option fill carries
                                       price_is_underlying:false — its price is a PREMIUM,
                                       not a price on that underlying)
- GET  /v1/me/alerts                   [session ONLY] your alert feed (?unread=1 /
                                       ?dismissed=1)
- POST /v1/me/alerts/read · /dismiss   [session ONLY] {ids[]} → {marked} / {dismissed}
- DELETE /v1/me/alerts/{alert_id}      [session ONLY] hard-delete one alert
- GET|DELETE /v1/me/sessions[/{sid}]   [session ONLY] list / revoke your login sessions
- GET|PATCH  /v1/me/prefs              [session ONLY] notification + AI toggles (brief, divergence,
                                       deploy events, personal AI)
- DELETE /v1/me/prefs/{key}            [session ONLY] clear ONE saved pref (avatar / layout /
                                       widget) → {deleted, existed}; idempotent, never a 404
- GET  /v1/me/profile-stats · /v1/me/timeline · /v1/me/ai-usage   [session ONLY] profile page data
- POST /v1/me/delete-account           [session ONLY] {confirm_email, password} — full cascade delete
- GET  /v1/me/agent-audit              [session ONLY] your append-only agent-write audit ledger
                                       (newest-first; a key pair can't read the whole trail)
- GET  /v1/me/agent-freeze             [key or pair] read the kill switch {frozen, frozen_at, reason}
- POST|DELETE /v1/me/agent-freeze      [session ONLY] pause / resume ALL agent activity. THE KILL
                                       SWITCH: while frozen, every mutating action (deploy, backtest,
                                       save, resume) is refused with 423 and running deployments open
                                       NO new positions (marks/exits continue). Only the human can
                                       set/clear it from their session — a key pair can READ it but
                                       NEVER lift it, so a rogue agent cannot un-freeze itself.
- GET  /v1/health                      liveness + data freshness (no auth)
- LEGACY (desk's own X-Vega-Key only — not obtainable via API/UI; prefer the pair):
  GET /v1/accounts/{account_id} · POST /v1/accounts/{account_id}/deploy ·
  POST /v1/accounts/{account_id}/sync

Everything you read from these endpoints is scoped to YOU — you can only see and
diff your own runs and your own desks. Trust the OOS numbers, respect the skip
rate, and let SHELF mean no.