AI Norden connector for macOS
=============================

What this is: a tiny background agent that watches the folder where the
Norden Statistics addon writes your closed trades and uploads every new
or changed file to your AI Norden dashboard. It reads nothing else on
your machine and does no analysis locally; the coaching happens server
side.

It only uploads sessions traded from the day you install it onwards.
Whatever you traded before that stays on your computer.

ONE TIME SETUP, THEN FORGET IT

1. Sign in to your dashboard and click "Get pairing code". Copy the code.

2. Move this folder somewhere permanent, for example your home folder or
   Applications.
   IMPORTANT: pick a place you will not delete or move later. Do not
   leave it in Downloads. The connector runs from here and remembers this
   location so it can start automatically when you log in, and moving or
   deleting it afterwards breaks that.

3. Open Terminal in this folder and run:

       python3 ai_norden_connector.py

   If macOS offers to install the command line developer tools the first
   time you use python3, accept and run the command again.

4. A small window asks for your pairing code. Paste it and click OK.

5. You will see "All set". That is it.

ONE FIRST STEP IN BOOKMAP, IMPORTANT THE FIRST TIME

Install the Norden Statistics addon and tick it on every instrument you
trade. It is what writes the files this connector reads, so until it is
on, your dashboard stays empty. The download and the steps are on the
Setup page of your dashboard.

From then on the connector runs silently in the background and starts
automatically every time you log in, so you never have to open Terminal
again. For this first session, either leave the Terminal window open
while you trade or log out and back in once. Just trade in Bookmap and
watch your dashboard update while you trade.

THE SECOND PIECE: THE NORDEN STATISTICS ADDON

The connector sends files. Something has to write them, and that is our
addon, which runs inside Bookmap.

It writes your closed trades, and alongside them what the market was
doing around each of your orders: the book around your price, where you
stood in the queue, and the exact moment each order was placed, moved,
cancelled or filled. That is what makes time to fill and distance to the
spread real measurements instead of estimates.

It installs separately and takes a few minutes. The install steps and the
download are on the Setup page of your dashboard.

The connector picks up its files automatically once it is running. There
is nothing to configure here.

RUNNING IT, STOPPING IT, REMOVING IT

  Is it running?

      pgrep -fl ai_norden_connector.py

  Stop it, now and at next login:

      launchctl unload ~/Library/LaunchAgents/com.ainorden.connector.plist
      pkill -f ai_norden_connector.py

  Start it again:

      launchctl load ~/Library/LaunchAgents/com.ainorden.connector.plist

  Remove it completely: run the two stop commands, then

      rm ~/Library/LaunchAgents/com.ainorden.connector.plist

  and delete this folder. Nothing else is left behind.

SETTINGS

Edit ai-norden-connector.json in this folder, then stop and start the
connector for the change to take effect. That file is the one that
counts; the values inside the .py are only the defaults used the very
first time, so editing the .py after setup changes nothing.

  installed_on     Sessions traded before this day are never uploaded.
                   Stamped once, on the day you installed. Write it as
                   2026-08-01, four digit year, month and day. A day
                   written 2026-8-1 is read and corrected on the next
                   start; anything that is not a date falls back to today.
  upload_history   Set to true to also upload everything you traded
                   before installing. Off by default.
  poll_seconds     How often the folder is checked, in whole seconds and
                   without quotes. Lowering it does not make the dashboard
                   faster: Bookmap rewrites the export roughly once or
                   twice a minute, and that is the limit.
  folder           Force a specific export folder. Leave empty to detect
                   it automatically.

STAYING UP TO DATE

From this version on the connector keeps itself current. It checks for a
new release a few times a day and installs it when you are not in a
session, then starts the new one by itself. There is nothing to download
again.

The version it replaces is kept right next to it as
ai_norden_connector.py.old, so it can always be put back by hand.

To stay on the version you have, add this to ai-norden-connector.json:

  "auto_update": false

GOOD TO KNOW

* No Bookmap yet? Run the connector anyway. It waits and begins the
  moment there is a closed trade to send.
* It finds the folder on its own, wherever your version keeps it.
* Your first closed trade is what starts it. Nothing appears before that.
* The addon records only the instruments you ticked it on. Tick it on
  every one you trade.
* If the connector cannot reach the server, a firewall, proxy or
  antivirus may be blocking it. It tells you instead of saying All set,
  and keeps retrying.
* A connection log is saved as ai-norden-connector.log next to the
  program.

If the dashboard stays empty, check that log and reach out.
