PLAYBOOK RUNNER — QUICK START
The Skill Mill

START HERE — full guide: https://aitradingcompetition.com/runner-guide.html
  1. Install Node.js 20+ from https://nodejs.org
  2. Unzip this folder anywhere; put your .playbook.json next to start.cmd
  3. Run:  start.cmd setup    (asks for your license + broker keys)
  4. Run:  start.cmd doctor   (checks everything, prints the fix if not)
  5. Run:  start.cmd run      (dry-run by default — watch it for a session)
  6. When ready, set "mode" to "paper" in runner.config.json, later "live"

This is a trading strategy ("playbook") that YOU run, on YOUR OWN computer,
with YOUR OWN broker account. We never see your money or your keys.

THE PROMISE
  If the Runner and your broker ever disagree about a symbol, the Runner
  stops trading that symbol and tells you what it sees. It does not guess.
  It manages only positions it opened. It settles every trade from its own
  order ids, never from your account totals. It attempts protective stop
  placement after fills; placement and execution price are not guaranteed.
  If it finds shares it cannot account for, it requests cancellation of its own resting orders in that
  symbol (never yours), stops entering/exiting/stopping that symbol, prints
  one plain-English report naming the symbol and the numbers, and waits for
  you.

  "WHEN THE RUNNER STOPS ON A SYMBOL" below explains what that looks like.

STEP 1 — Install Node.js
  Go to https://nodejs.org and install the LTS version (20 or newer).
  Not sure if you already have it? Open a terminal and type: node --version
  (start.cmd / start.sh check this for you and tell you if it is too old.)

STEP 2 — Unzip this folder anywhere you like.
  Bought a playbook? Put the .playbook.json file you downloaded in THIS
  folder, next to start.cmd. The app finds it automatically and says so.
  (No purchased file here means it runs the bundled starter — a frozen
  demo snapshot, clearly labeled.)

  Windows SmartScreen: because this zip came from the internet, Windows
  may show "Windows protected your PC" the first time. Click "More info"
  -> "Run anyway". Everything the app does is in playbook-runner.mjs —
  a plain text file you can open and read, line by line.

WHAT IS IN A PURCHASED FILE  (Runner 0.7.0 and later)
  You get the bot's full rulebook set: all three adopted books for short,
  medium and long horizons, and the latest published rules with Live-Sync. The
  stock scan runs on your machine with your own Alpaca keys, against the
  same list we use.
    - A Core bot's file is its whole rulebook: one book. The publication
      default remains 15m; legacy files use 15m while the hosted lane uses
      5m. Native 5m publication remains held pending an approved compatible
      client and customer/feed cutover. Run verify for your file's interval.
    - The System file contains all 15 setup definitions in a fixed hourly
      adaptation with shared risk settings, not the hosted account's
      per-strategy execution. Earnings Quality Trend acts only as an exit.
    - Weather and Super Bot files only: their app-side account layers
      (volatility-targeted sizing and the hourly allocator; Super Bot
      also intraday posture, its entry tape guards and its tape rules -
      daily entry filters such as 'don't short a stock that is strong
      today') run in the Arena engine and are NOT in the file. The
      file's own note says so; verify prints it.
  verify lists every book in the file with its rules; run trades all of
  them in ONE account and ONE position pool, bounded by the bot's own
  limits (max positions, per-book cap, short exposure) - your caps in
  runner.config.json can only tighten those. The 4h book's bars are
  built here from 1h bars with the site's candle arithmetic, anchored
  to each session's open (09:30-13:30 and 13:30-16:00 ET); a candle is
  only judged once every one of its hourly bars has arrived. Early closes
  use the shared exchange calendar. The hosted site's rolling 4h grouping
  is different; equal arithmetic does not mean equal signals.
  The Runner executes rules; it does not include a hosted AI model,
  research database, news service or autonomous daily learning process.
  Your data, execution timing, limits and fills can differ from the site.
  update treats a change to ANY one book as a new version.

  THE SCAN: give setup your Alpaca keys (paper or live - the free IEX
  feed comes with every Alpaca account) and each cycle the Runner ranks
  the same list of roughly 1,000 US stocks we scan, on your machine,
  then studies the shortlist. With no keys it prints, on EVERY cycle:
    scan: no Alpaca keys - using the universe ladder
  That means it is choosing from the smaller list built into the file,
  not scanning the whole market. Adding keys enables the local stock scan;
  the hosted AI, news research and learning services remain on the website.

  Your own record starts the day you run it. No file reproduces a bot's
  public return: data timing, stock selection, account limits and fills
  can differ from the hosted account.

STEP 3 — Open a terminal IN THIS FOLDER and try the commands.
  Windows 11: right-click an empty spot inside the folder, then choose
              "Open in Terminal".
  Windows 10: hold Shift and right-click inside the folder, then choose
              "Open PowerShell window here".
  Mac:        drag the folder onto Terminal in your dock, or cd into it.

  Then type EXACTLY (on Windows the ".\" at the front is required —
  PowerShell will not run "start.cmd" without it):

  Windows:
    .\start.cmd doctor
    .\start.cmd verify
    .\start.cmd backtest --symbol NVDA
    .\start.cmd run

  Mac/Linux:
    ./start.sh doctor
    ./start.sh verify
    ./start.sh backtest --symbol NVDA
    ./start.sh run
    (If you see "Permission denied", first run:  chmod +x start.sh)

  Prefer clicking? Double-click start.cmd (Mac: run ./start.sh with no
  arguments) for a small menu: 1 verify, 2 backtest, 3 run, 4 setup,
  5 doctor.

  Two more you will only need occasionally:
    .\start.cmd status                positions, results, and any symbol the
                                      Runner has stopped trading
    .\start.cmd reconcile SYM         clear a halt after you have checked
                                      that symbol at your broker

  doctor checks everything at once — Node version, your config, your
  Alpaca keys (it actually connects), the market clock, price data, the
  playbook file — and prints one line per check with the fix.
  verify explains the playbook in plain English — check the FIRST LINE of
  its output: it names exactly which playbook file will trade, and prints
  the caps from your own config. For a purchased bot it then lists every
  book in the file (15m, 1h, 4h), each with its entry rules, exits, side
  and version, plus the bot's own position limits. backtest shows how it
  would have traded a symbol recently, book by book and combined. run
  starts it trading (below).

WHAT "run" ACTUALLY DOES
  By default, run is DRY-RUN: it watches real prices and prints what it
  WOULD do. No account, no money, no risk. This is the safe default.

  To go further you need a config file. The easy way:

    .\start.cmd setup        (Mac/Linux: ./start.sh setup)

  setup asks a few questions (mode, keys, caps), CONNECTS to Alpaca on
  the spot so a wrong key is caught immediately, and writes
  runner.config.json for you. Then run doctor to see everything green.

  Prefer to write the file yourself? runner.config.json goes next to
  start.cmd and looks like this (one file, all optional lines together):

    {
      "mode": "paper",
      "alpacaKeyId": "your key here",
      "alpacaSecret": "your secret here",
      "playbookPath": "horizon-1h.playbook.json",
      "email": "you@example.com",
      "licenseKey": "PB-XXXX-XXXX-XXXX-XXXX"
    }

  Paper trading also needs the account-binding startup check described
  below; purchased playbooks need activation. playbookPath
  pins which playbook runs (leave it out and the app auto-picks the single
  purchased file sitting in the folder). email + licenseKey enable update.
  "mode" must be exactly dryrun, paper or live (lower-case). If you use
  Notepad, choose "Save as type: All files" so it does not become
  runner.config.json.txt — doctor warns you if that happened.

  +----------------------------------------------------------------------+
  | WHERE TO GET ALPACA KEYS                                             |
  |  1. Sign up free at https://alpaca.markets and open the dashboard.   |
  |  2. Top-left, switch the toggle to "Paper" (fake money) — or stay on |
  |     "Live" only when you mean real money.                            |
  |  3. Right side: "API Keys" -> "Generate". Copy the Key ID AND the    |
  |     Secret — the secret is shown ONCE. Paste both into setup.        |
  |  Paper and live are DIFFERENT key pairs; a paper key will not work   |
  |  in live mode and vice-versa (doctor tells you which one it sees).   |
  +----------------------------------------------------------------------+

  paper trades a free, fake-money account at alpaca.markets — real order
  flow, no real money. Stay here as long as you like.

  live trades your ACTUAL Alpaca account with REAL money. Only set "mode"
  to "live" when you mean it. Every time live mode starts, the Runner
  first connects to your account and shows you the real numbers — equity,
  dollars per position, the day-loss halt in dollars — and then you must
  type, in CAPITALS, exactly:  I UNDERSTAND THE RISK
  It has to be typed at the keyboard. Starting it from a script or a
  scheduler with no keyboard attached is refused ("cannot confirm live
  mode without a keyboard") unless you pass --i-understand-the-risk on the
  command line, which records that you chose this on purpose. There is no
  way to reach live mode by accident.

  ABOUT YOUR LIVE ACCOUNT: Alpaca allows one live account per person
  (individual accounts), so "use a separate account" is not an option
  there. Instead, keep only the money you want the Runner to manage in
  Alpaca and hold long-term investments at another broker. The Runner
  only ever sells shares it bought itself and never touches orders it did
  not place — but a clean account keeps the accounting unmistakable.

  Your caps are yours: maxPositions x maxPositionPct may never exceed 100%
  of your account (that would be margin — the Runner refuses the config),
  and the Runner never quietly loosens a cap you typed.

STOPPING IT
  Press Ctrl+C in the terminal. Stopping the program does not cancel orders
  or close positions. Stop placement can fail, fractional stops can expire
  that day, and price gaps can produce losses beyond the stop level.
  Supervise the brokerage account even while the Runner is off.

  To close a position manually, stop the Runner first. At the broker,
  cancel its outstanding orders and verify their final status before
  sending a separate close; a cancellation request alone is not enough.
  Closing a LONG sells shares; closing a SHORT buys shares back (cover).
  Check remaining positions AND orders afterward, then run reconcile.

ONE RUNNER PER BROKERAGE ACCOUNT
  Paper and live accounts each allow one installation, one ledger and
  one running process. This includes the free starter. Three license
  activations do not allow three Runners on one brokerage account. Do not
  run another bot or place manual trades in a Runner-managed account.

  Brokerage execution requires our account-binding service at startup,
  including halt and reconcile. It receives hashed account and ledger-path
  identifiers, random installation and ledger identifiers, and a random
  binding token. We receive no brokerage keys, account number, balances,
  positions, trades or literal filesystem path. A failed check prevents
  startup. Dry-run, verify and backtest do not require this registration.

  The binding is permanent: another installation cannot take over just
  because the original is offline. Keep the original state file, its path,
  and the ownership record under your user's .playbook-runner/accounts.
  Back them up securely. Stop the Runner before upgrading and preserve
  these records. There is no automatic transfer or reset; contact support
  before moving machines, changing the ledger path or replacing lost files.
  Deactivating a license does not transfer the brokerage account binding.
  Do not delete a lock or ledger to bypass an error. A crash recovery uses
  the original order journal; an uncertain order must be verified before
  the Runner can submit any new order.

GETTING NEW VERSIONS (Live-Sync and re-downloads)
  Your license key is shown ON THE PURCHASE PAGE right after checkout —
  copy it somewhere safe when you buy. (Lost it? Use the Contact page on
  aitradingcompetition.com from your purchase email address.)

  Add it to runner.config.json (setup asks for it) — that's it. While
  run is going it checks for a new version on its own: once at startup,
  once a day after the US market closes, and at least once every 24
  hours either way. Computer on + run going = up to date, automatically.
  A new playbook is only ever swapped in BETWEEN cycles, never mid-order,
  and any position you already hold keeps the exact stop and target it
  was opened with — only NEW entries follow the new rules. A change to
  ANY one of a bot's three books is a new version; update says which
  books changed. If you bought a single-book file before bundles
  existed, update hands you the full bundle free — it contains the book
  you bought.

  Prefer to control it yourself? update still works by hand, any time:
    .\start.cmd update      (Mac/Linux: ./start.sh update)

  Either way, it downloads the newest signed copy of every playbook your
  license includes and REFUSES any file whose signature does not verify —
  a bad download can never replace a working strategy. A hand-run update
  still needs "restart run so it loads the new file" if run is not
  already watching; run itself never needs that restart, it just swaps in.

  doctor shows when the automatic check last ran and when the next one is.

ACTIVATION (needed to TRADE a purchased playbook, not to read or test it)
  verify and backtest are always free, on any computer, with or without a
  license — read the playbook and watch it trade the past all you like.
  Actually trading one (run in paper or live mode) needs it activated on
  THIS computer first:

    .\start.cmd activate      (Mac/Linux: ./start.sh activate)

  It uses the same email + licenseKey as update (setup asks for both, or
  pass --email / --license). What it sends: your email, your license key,
  and a device id computed from THIS computer (hostname + network adapter
  + username) — never your broker keys, never anything about your trades.
  The bundled starter never needs this.

  Up to 3 computers per license — deactivate an old one on the purchase
  page to free a slot. A buy-once playbook stays activated on that
  computer without expiring, but brokerage execution still requires the
  account-binding startup check above. A Live-Sync (subscription) playbook's
  activation is renewed automatically — by run's own daily check while
  it is going, and by a hand-run update too; if run is never left going
  and update is never typed, or your subscription lapses, trading on it
  stops within about 10 days — a short trip offline never halts it
  outright.

  Skipped this step? run stops with one line before touching your broker:
    "This playbook is licensed per buyer. Run .\start.cmd activate with
    the email and license key from your purchase (up to 3 computers per
    license). Reading the rules (verify) and back-testing stay free."
  doctor also reports license status alongside everything else it checks.

KEEPING IT RUNNING
  The Runner checks the market every 5 minutes by default (set
  "cycleMinutes" in runner.config.json, 5 to 120) and only acts while the
  US stock market is open.

  It has to be RUNNING on your computer to place NEW trades. If your
  laptop sleeps, the lid is closed, or you stop the program, no new
  trades happen until you start it again — it does not catch up or trade
  in the background.

  Existing broker orders may remain executable while the Runner is off.
  Alpaca automatic venue-stop repricing is not implemented. When the
  software trail moves, Runner keeps existing venue stops at their prior
  verified level and warns; software trailing exits require Runner running.
  Manual or unreadable stop inventory pauses that symbol's automated
  management, including software exits. Other symbols can continue.
  The bounded developer paper probe tests explicit cancel/confirm/replace
  mechanics only. It does not prove automatic repricing or uninterrupted
  protection and is never a live-mode or normal-cycle fallback.

  Do not assume every position has protection: stop placement can fail,
  fractional stops can expire, and execution price is not guaranteed.
  Restarting recovers recorded orders before permitting another submission;
  an unreadable or conflicting order stops trading rather than being guessed.

  Want it running around the clock? Install it on any always-on computer
  you control — a spare mini PC at home, or a small cloud server for a
  few dollars a month. It's the same install, same steps as above. We
  never host it for you: we never hold your broker keys or your money
  (see TERMS below).

WHEN THE RUNNER STOPS ON A SYMBOL  (new in 0.6.0)
  Sometimes an account and a program stop agreeing. Shares get sold by
  hand. A broker buys back a borrowed stock. A protective stop fills in
  the same second the Runner cancels it. A corporate action changes a
  holding overnight.

  Older versions tried to work out, on their own, which shares were theirs
  and then traded to fix the difference. That is guesswork about your
  money, and it is now gone. Instead the Runner HALTS that one symbol:

    HALTED AAPL - this Runner and your broker disagree about this symbol,
    so it has stopped trading it.
      Your ledger here says: 3.0000 sh LONG, opened 4 Sep at 100.00,
        protective stop 97.00.
      Your broker said: 2.0000 sh LONG, read 4 Sep at 11:16 am ET. This
        Runner has not asked again since - while a symbol is halted it does
        not touch it.
      Our own stop orders: gtc-A - cancellation requested; not yet verified final.
      What this Runner did: it requested cancellation of gtc-A. That order
        may still execute. It has recorded no trade for these AAPL shares.
        It will not buy, sell, or place another stop in AAPL while halted.
        Check outstanding orders and protection at your broker.
      Why this can happen: ...
      What you can do: open AAPL at your broker. Either flatten it, or put
        the long position back to 3.0000. Cancel any leftover order
        yourself. Then run:  reconcile AAPL

  WHAT A HALT MEANS, PLAINLY
    - An ordinary position disagreement halts ONE symbol. An uncertain
      order, storage failure or lost ownership can stop the entire Runner.
    - No trade is recorded for it. The Runner will not invent a price for
      shares it never saw fill, so your results stay honest.
    - The position stays on the Runner's books, because the money is still
      at risk: it still counts toward your maximum number of positions.
    - IMPORTANT: the Runner requests cancellation of ITS OWN stop in that symbol
      and does not place another one. Sizing a replacement would mean
      guessing how many shares are yours, which is the thing in dispute.
      Cancellation may be pending or refused. Do not assume protection or
      assume the old order is gone; check your broker. The
      report says so every cycle, `status` repeats it, and `doctor` fails
      while any symbol is halted.

  CLEARING IT — you look, then you tell it
    1. Open the symbol at your broker and decide what you want.
    2. Cancel any leftover order from the Runner yourself, at the broker.
    3. Then run:   .\start.cmd reconcile AAPL     (Mac/Linux: ./start.sh ...)

    reconcile re-reads everything fresh and has exactly three answers:
      - Your broker and the ledger now agree exactly: the halt clears and
        the position resumes (the next cycle puts its stop back).
      - Your broker holds nothing: the halt clears and the Runner drops the
        row with NO profit or loss recorded - it never saw a fill for those
        shares, so it will not invent a price for them.
      - Anything else: it refuses, prints both sides, and changes nothing.
        It will not adopt shares it did not open.

    reconcile never sends an order, never cancels anything at your broker,
    and only ever does one symbol at a time - typing the symbol is how you
    tell it you have looked.

    If you would rather handle the symbol entirely yourself:
      .\start.cmd reconcile AAPL --forget
    This still refuses while recorded orders or unresolved fills remain.
    Once checks pass it clears the halt and drops the row without sending
    an order. Do not delete state to bypass that refusal.

  You can also stop the Runner trading a symbol whenever you want:
      .\start.cmd halt AAPL
    Same report, same one way back: reconcile AAPL.

SIZING & PROTECTION (how it adapts to YOUR account)
  - Position sizes are a PERCENT of your account, re-read from your broker
    every cycle. A $2,000 account and a $200,000 account trade the same
    playbook at their own scale. Buys use fractional shares, so small
    accounts get correctly sized slices instead of "can't afford one share".
  - The Runner skips entries when its broker checks show insufficient
    buying power or borrow. Conditions can change before execution and the
    broker can still reject an order. Shorts use whole shares, not fractions.
  - It only trades while the market is OPEN. Off-hours and weekend cycles
    just check on your positions; no order is ever queued into a closed
    market.
  - In paper/live mode the Runner attempts broker-side stop placement after
    fills. A replacement waits until the old order is verified final with
    no unaccounted fill. A request to cancel is not final cancellation.
    Stops can be rejected or expire; price gaps remain a risk.
  - It never touches orders or shares it didn't create: your own resting
    orders and your own holdings in the same account are left alone. If the
    account holds a different amount than its own ledger after recorded
    fills are settled, it halts rather than inferring who owns the excess.
  - If it ever cannot account for what it sees, it halts that symbol rather
    than guessing (see "WHEN THE RUNNER STOPS ON A SYMBOL"). A halted symbol
    has no protective stop from this Runner until you clear it.
  - Heads-up for accounts under $25,000: US brokers apply the pattern-day-
    trader rule to margin accounts (4 same-day round trips in 5 business
    days). This playbook usually holds longer than a day; the Runner warns
    you once a day when the rule could apply.

YOUR KEYS, YOUR DATA
  Your config file and keys stay on this computer, in THIS folder — treat
  the folder as the secret (do not share it or sync it somewhere public).
  On Mac/Linux, setup makes runner.config.json readable by you only. All
  analytics stay on your machine — nothing about your usage or results is
  sent anywhere. The ledger (runner-state.json) keeps a .bak copy of its
  last good save. Corporate proxies are not supported by Node's networking
  — run it from a home network.
  The backup is not permission to roll back over a submitted order. If the
  current state is damaged or missing, restore and review it; do not start
  a fresh ledger. Account-binding registration is described above; prices,
  broker orders, optional AI calls, downloads and activation also use the
  network. Broker credentials are sent only to the broker, never to us.

RISK DISCLAIMER
  Trading involves risk of loss. Nothing here is investment advice. Past
  results do not predict future results. Start in dry-run, stay in paper
  as long as you want, and move to live only when you decide that for
  yourself.

TERMS
  Your purchase and your use of this software are governed by the Terms
  of Use & Sale and the Risk Disclosure you agreed to at checkout:
    https://aitradingcompetition.com/terms
    https://aitradingcompetition.com/risk
  Short version: this is beta software plus published strategies, not
  financial advice; you run it on your own accounts entirely at your own
  risk, and only ever with money you can afford to lose.
