# BidBrain: bringing your copy up to date with the shared version

Written 2026-08-20 for Steven. Mark has been working on BidBrain from his own
copy at Right Drive and set up a private, shared GitHub repo so improvements
go both ways from here. This is how you pull his changes into your own copy
without touching your own data, logins or buying rules.

**Nothing here shares your data with Mark, or his with you.** The repo only
ever carries code and the CLAUDE.md rulebook. Your database, logins, saved
searches and accounts email stay on your own Mac the whole time, exactly as
they do today. Full detail in the "Keeping this private" section at the
bottom.

The fastest way to do all of this is to open your BidBrain folder in Claude
Code (your own Claude) and say: "Read this file and bring my copy up to date
with the shared repo." Everything below is what it will do, so you know what
to expect and can check it as it goes.

## 0. Before you start (Mark needs to do this first)

You need access to the private GitHub repo. Mark has to add your GitHub
account as a collaborator on it (or send you the invite) before step 1 below
will work. If you don't have a GitHub account yet, create a free one first
and give Mark the username. This is the one step Mark has to do by hand, on
his side, nothing here can do it for him.

## 1. What's new since you last looked at this

A quick heads up so the cockpit doesn't feel unfamiliar when you open it:

- **A third platform, Auction4Cars**, alongside Motorway and Carwow. Its
  auctions run 3, 5 or 7 days rather than closing at 3:30pm like the other
  two, so each of its cards now shows a live countdown to when that specific
  lot closes.
- **A DealerKit stock reader**, an alternative to Clickdealer for the "fills a
  gap / in stock" flags, if you ever want to switch DMS. Clickdealer keeps
  working exactly as it does today if you don't touch this, nothing is
  forced.
- **A proper settings page** (the wrench icon, top right of the cockpit).
  Every hard gate limit, mileage, reserve, age, distance, grade, owners, is
  now editable there per platform, so Motorway, Carwow and Auction4Cars can
  each have their own limits instead of one shared set. Auction4Cars also
  gets its own depot list there, since it only ever gives a location name,
  never exact miles. The retail uplift percentage and the flat spread are
  editable there too now, previously code only.
- **The search and filter controls moved to a left sidebar**, with extra
  filters added (transmission, body style, min and max Reserve, Max bid and
  Retail guide), plus a Reset link to clear them all in one go.
- **A "Cazana price" sort chip** next to the Shortlisted star, a standalone
  low to high / high to low sort by Cazana retail price, independent of the
  main Sort dropdown and unaffected by whichever filters are active.
- **A notification bell**, top right, replacing the old stack of banners
  across the top of the page. Anything needing attention (Glass's not run
  yet, a stale DealerKit read) shows as a small red dot on the relevant Run
  button, with the full detail in the bell's dropdown.
- **Carwow's reserve now reads "Trade value"**, not "Reserve". Carwow itself
  stopped publishing a real reserve at some point, the card has been using
  CAP Clean as a stand in for a while, this just stops it being labelled as
  if it were the genuine figure. Auction4Cars, on the other hand, turned out
  to disclose its real reserve after all, just never as visible text (it was
  hidden in the page's own source), so that one now reads correctly too.

None of this touched the buying brain itself (`bidbrain/pricing.py`), the
formula and gate logic behave exactly as before unless you deliberately
change a limit on the new settings page.

## 2. Bringing in the new code, without losing your own data

Your database, logins and `dealer_config.py` were never part of git and stay
completely untouched by any of this. The safest way to pull in the new code:

1. **Do not delete or touch your existing BidBrain folder yet.** Rename it
   aside for now, for example `mv ~/BidBrain ~/BidBrain-old`.
2. Clone the shared repo into the same path your launchd jobs already expect:
   `git clone git@github.com:CarDealer-OS/Bidbrain.git ~/BidBrain`
   (Ask Mark for the exact repo URL if this one doesn't work, or check
   whether you're set up for SSH or HTTPS access to GitHub.)
3. Copy your own data across, nothing here was ever tracked by git so this is
   a plain folder copy: `cp -R ~/BidBrain-old/data ~/BidBrain/data`. This
   brings your whole database, sightings, learned models, hidden cars, saved
   shortlist and login sessions across exactly as they are.
4. Copy your own `dealer_config.py` across too:
   `cp ~/BidBrain-old/dealer_config.py ~/BidBrain/` if you already have one
   from an earlier setup. If you don't, copy `dealer_config.example.py` to
   `dealer_config.py` and fill in your own `CARWOW_SAVED_FILTER_ID`,
   `MOTORWAY_STOCK_URL` and `ACCOUNTS_EMAIL`, the same values you're already
   using today.
5. Reinstall the one dependency in the new folder (it's per Python
   environment, not per folder, but do this to be sure):
   `python3 -m pip install --user playwright`
   `python3 -m playwright install chromium`
6. Check everything still passes: `python3 test_pricing.py`. All tests
   should pass, this touches nothing of yours, it's just confirming the code
   itself is sound.
7. Rebuild the cockpit from your existing data without re reading anything
   live: `python3 daily_run.py --render-only`, then
   `python3 serve.py` and open `http://localhost:8765/cockpit.html`. Your
   shortlist, hidden cars and history should all be exactly as you left
   them.
8. If you had launchd jobs (`com.bidbrain.daily`, `com.bidbrain.serve`)
   pointed at the old folder path, they need no changes as long as the new
   folder is at the same path. If you renamed it to somewhere else, ask your
   Claude to update the plist files in `~/Library/LaunchAgents`.
9. Once you've confirmed everything looks right, `~/BidBrain-old` is safe to
   keep as a backup for a while, or remove once you're confident.

## 3. If you want to try the new platform or the new DMS reader

Both are optional, nothing breaks if you skip this section.

- **Auction4Cars**: `python3 login.py auction4cars` to log into your own
  dealer account there, same pattern as Motorway and Carwow. It'll start
  showing up in the next daily run automatically once logged in.
- **DealerKit**: only relevant if you actually use DealerKit as your DMS.
  `python3 login.py dealerkit` to log in, then set `DEALERKIT_BASE_URL` in
  your `dealer_config.py` to your own tenant address, and ask your Claude to
  flip `STOCK_FLAGS_ENABLED` and switch the stock reader from Clickdealer to
  DealerKit in `daily_run.py` if you want to move over.

## 4. Keeping up to date from here

Whenever Mark pushes further improvements, pulling them in is much simpler
than the first migration above, since your folder is now a real git
checkout:

```
cd ~/BidBrain
git pull origin main
```

This only ever touches tracked code files, never `data/`, `dealer_config.py`
or anything else gitignored. Run `python3 test_pricing.py` afterwards as a
quick sanity check, same as always.

## Keeping this private

- `dealer_config.py` (your saved searches, filter ids, accounts email) is
  gitignored, it has never been part of any commit and `git pull` cannot
  touch it.
- `data/` (your whole database, browser logins, run cache) is gitignored the
  same way. Mark's copy of it lives only on his own Mac, and yours only on
  yours.
- The shared repo carries only the code and `CLAUDE.md`, the build log and
  rulebook. If you ever see a real setting, email or account detail of
  Mark's own written into `CLAUDE.md`, flag it, that would be a mistake, not
  something either of you should expect from the other's copy.