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.

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. backtest shows how it would have traded
  a symbol recently. 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.

  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 15 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.
  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.
