# BidBrain Build Brief for Claude Code A daily car buying assistant for Really Easy Car Credit. It trawls Motorway and Carwow every day, keeps only the cars that fit Steven's rules, prices each one, and shows them on a private web page that Steven and his team open on any device. Steven places every bid himself. The app never bids. --- ## 0\. How to use this document Steven: you do not need to understand the technical parts. Read sections 1 to 4 so you know what it does, then paste the prompts in section 9 into Claude Code on the Mac Studio, one phase at a time. Claude Code: this is the master spec. Build it in the phases set out in section 8, simplest first. Confirm the open items in section 10 by inspecting the live pages rather than guessing. Keep a human in control of every bid. Any text the app shows on screen must avoid hyphens and dashes, using commas or full stops instead, to match Steven's house style. --- ## 1\. What BidBrain is Every day, BidBrain reads the new stock on Motorway and Carwow, throws out anything that breaks Steven's buying rules, works out the most he should pay for each car that survives, and lays them out cheapest first on a clean web page with a link to go and bid. It also learns from Really Easy Car Credit's own sold stock, so over time it tells Steven which models turn fast and hold their margin and which ones quietly bite. It runs on the Mac Studio in the office, which is always on, and is reachable on a private web address so the whole team can use it. --- ## 2\. Non negotiable rules 1. BidBrain never places a bid. It only recommends. Steven enters every bid himself. 2. No platform APIs are used. Everything is done by reading the logged in screens, downloading the reports the platforms already provide, and reading local files. 3. When the app cannot be certain which engine a car has, it excludes the car. Play safe, always. 4. All text the app displays avoids hyphens and dashes. 5. Steven's purchase, sales and prep data stays local on the Mac Studio. Nothing about his margins or buying logic is exposed to anyone without the private link. --- ## 3\. The buying brain This is the signed off logic. It does not change without Steven's say so. ### 3.1 How a car is priced 1. Look up the Glass's retail value and the Cazana retail value for the car. 2. Add 15 percent to each. Call these the calculated Glass's value and the calculated Cazana value. 3. Choose which one governs: - If the calculated Glass's value is over 10,000 pounds, use the calculated Glass's value. - If the calculated Glass's value is under 10,000 pounds, use the higher of the calculated Glass's value or the calculated Cazana value. 4. Recommended maximum bid equals the governing value minus 3,000 pounds. 5. The 3,000 pounds is a flat spread on every car, whatever the price. It is the whole spread, meaning it has to cover prep, buyer fees, VAT on the margin, transport and profit. Real profit is whatever is left after those costs, which is what the learning loop measures. ### 3.2 The hard gate A car must pass every one of these or it is never shown: - Mileage under 90,000 - Reserve price under 11,000 pounds - Age between 2 and 10 years - Within 210 miles of postcode NE3 5HE - Condition grade 1, 2 or 3 only. Never grade 4 or 5 - 4 previous owners maximum ### 3.3 Banned outright Instant rejection, no matter how good the rest looks. Engines: - 1.2 PureTech - Ford 1.0 EcoBoost, wet belt versions, 2014 to 2019 - Ford 1.5 EcoBoost - Ford 2.0 EcoBoost, pre 2019 - VW and Audi 1.5 TSI (EA211 evo) - Hyundai and Kia 1.6 Gamma and Nu GDI - Nissan 1.2 DIG-T (HR12DDR) - Renault and Nissan 0.9 TCe - Renault 1.2 TCe (H5Ft) - Vauxhall and Opel 1.4 Turbo (A14NET and B14NET) - Fiat and Alfa 0.9 TwinAir - Jaguar and Land Rover 2.0 Ingenium petrol - Audi and VW 2.0 TFSI (EA888 Gen 2\) - Audi and VW 2.0 TFSI (EA888 Gen 3, early units) - Audi and VW 1.8 TFSI (EA888) - Fiat 1.4 MultiAir (500 and Tipo) - Vauxhall and Opel 1.0 Turbo (B10XFL) Makes: - Land Rover - Volvo - Jeep Uncertainty rule: if the listing does not give enough to prove which exact engine the car has, exclude it. This will correctly drop most older Audi and VW 2.0 and 1.8 TFSI petrol turbos, which is intended. ### 3.4 Preference, not a knockout - Full service history is preferred. Cars without it still appear, but are flagged and noted as a lower quality buy. ### 3.5 Out of scope BidBrain ignores finance commission, warranty, GAP, paint protection, admin fees and the deal itself. That is Steven's department. The buying recommendation is purely the 3,000 pound rule. --- ## 4\. The daily order of play 1. Before the auctions, log into Clickdealer and pull the current in stock list. Count how many of each model are in stock now. 2. Read the new daily stock on Motorway and Carwow. For each car capture: registration, make, model and derivative, year, mileage, previous owners, condition grade, reserve price, CAP Clean price, location and distance from NE3 5HE, service history status, VAT qualifying status, photos and the direct listing link. 3. Apply the hard gate and the bans from section 3\. Discard everything that fails. 4. For each survivor, look up Glass's retail and Cazana retail, then work out the recommended maximum bid using the rule in section 3.1. 5. Annotate each car with three things: - History from Really Easy Car Credit's own sold data: typical days to sell for that model, prep it tends to need, whether the 3,000 pound spread has held, and a plain verdict such as strong repeater or caution. - Current stock: how many of that model are in stock now, flagged as a gap, low, or too many. - A VAT qualifying flag where it applies. The car is still priced by the normal rule, just flagged. 6. Sort the list cheapest reserve first. 7. Publish to the private web page. 8. Steven and the team open the page on any device, review, and place bids directly on the platforms. --- ## 5\. Where the data comes from, with no API Everything runs through the Mac Studio using browser sessions that Steven has logged into once. Logins are kept alive so the runs do not need him each time. He re authenticates only occasionally when a session expires. - Motorway daily stock: read off the logged in dealer screens. Reserve price and CAP Clean are shown on the listing, so they are read straight from the page. - Carwow daily stock: same approach. The catalogue appears at 5pm the night before, so the read can run in the evening or early morning. Reserve and CAP Clean are on the listing. - Glass's retail and Cazana retail: looked up per car in Steven's logged in Glass's and Cazana accounts. These are the only two values that need a separate lookup, since the platforms do not show them. - Clickdealer in stock list: pulled daily, filtered to stock status of in stock, for the stock count. - Clickdealer sales margins: the monthly report, downloaded as CSV on the 10th of each month for the previous month. The report has a Download CSV button. Ignore the totals line at the foot of the file and read only the real car rows. - Clickdealer SIV reports: after the monthly CSV is in, walk each sold car by its stock number, open its SIV report, and capture the prep expense lines by type and cost. Steven does not do this clicking, the Studio does. - Later, the Clickdealer sources above are swapped for the DealerKit equivalents. The shape of the data is the same. --- ## 6\. What BidBrain learns From the monthly sales data and SIV harvest, per model: - Real average days to sell - Real prep cost, both the total and the split by type such as tyres, bodywork, mechanical and MOT - Whether the 3,000 pound spread survived after prep - How Motorway compares to Carwow on days to sell and on margin These learnings drive the history annotations on each daily card. Married to the daily stock count, the app can eventually say not just how many of a model are in stock but whether that is a problem given how fast they move. --- ## 7\. How it is built, in plain English - The Mac Studio does two jobs. It runs the engine that reads, filters, prices and learns, and it serves the web page. It never sleeps, which is why it is the right machine. - A single local database on the Studio holds the learned model figures, the daily stock snapshots, the daily shortlists and the ingested sales history. - Browser automation drives Motorway, Carwow, Glass's, Cazana and Clickdealer through Steven's logged in sessions. - A small web page, built by Claude Code, renders the cockpit: cars cheapest first, each with photo, stats, reserve, CAP Clean, Glass's, Cazana, the recommended maximum bid, the history and stock annotations, the VAT flag, and a link to bid. - The page is put on a real web address through a private secure tunnel, reachable by an unguessable link. The team use the link, no password. Nothing is indexed by search engines. - The whole project is kept as a master copy in a private online store, so Steven can edit it by talking to Claude Code on either the Studio or his laptop, and the Studio always serves the latest version. - The daily run and the monthly run are scheduled to fire on their own on the Studio. Claude Code should choose tools it can run reliably on macOS, keep the design simple and robust, and favour something that survives small changes to the platform pages. --- ## 8\. The build in phases Build simplest first. Do not move to the next phase until the current one is proven. ### Phase 1, the brain and the page on sample data Goal: prove the pricing and the layout before any scraping. - Build the pricing rule, the hard gate and the bans from section 3\. - Build the cockpit page exactly as described in section 4, fed by a small set of cars entered by hand. - Test the recommended maximum bids against cars Steven has already bought. If the numbers line up with what he actually paid on past winners, the brain is sound. Done when: Steven can look at a sample day on the page and trust the prices. ### Phase 2, automatic reading Goal: the page builds itself each day. - Automate the reads of Motorway and Carwow, then the lookups of Glass's and Cazana. - Put the page on its private web address so all three devices and the team can reach it. Done when: the day's real shortlist appears on its own each morning, priced, on every device. ### Phase 3, the learning loop Goal: the app gets smarter from real history. - Wire in the daily in stock list for the stock annotations. - Wire in the monthly CSV and the SIV harvest for the model learning. - Switch on the history annotations on each card. Done when: cards carry true history and stock notes drawn from Really Easy Car Credit's own data. ### Phase 4, polish - Real listing photos, simple filters and search, the full VAT, stock and history flags, and a phone home screen shortcut. - Prepare the swap from Clickdealer to DealerKit. --- ## 9\. Prompts to give Claude Code Paste these one at a time, in order. Adjust wording freely. Phase 1: "Read the file BidBrain\_Build\_Brief.md. Build Phase 1 only. Create the project, the local database, and the pricing brain from section 3\. Build the cockpit web page from section 4 using a small set of cars I will paste in by hand. Show me the page so I can check the prices against cars I have already bought. Do not build any scraping yet." Phase 2: "Now build Phase 2\. Automate reading the daily stock from Motorway and Carwow through my logged in browser, then look up Glass's retail and Cazana retail for each car that passes the gate. Put the cockpit page on a private web address with an unguessable link so my team can reach it without a password. Walk me through logging in to each site the first time." Phase 3: "Now build Phase 3, the learning loop. Pull my Clickdealer in stock list every morning for the stock counts. On the 10th of each month, download my previous month sales margins CSV, ignore the totals line, then open each sold car's SIV report by its stock number and capture the prep costs by type. Use all of this to annotate each daily car with its history and stock notes." Phase 4: "Now build Phase 4\. Add real photos, filters and search, the VAT, stock and history flags in full, and a phone home screen shortcut. Show me how I would later switch the data source from Clickdealer to DealerKit." Editing later, from either machine: "Open the BidBrain project from my private store and make this change, then publish it so the live page updates: \[describe the change in plain English\]." --- ## 10\. Open items to confirm during the build Confirm these by looking at the live pages, not by assuming. - The exact layout and field names on the Motorway and Carwow listing pages, so the right values are read. - How Glass's and Cazana show the retail value on screen for a given registration. - Whether the Clickdealer SIV report page has its own download, or must be read from the screen. - How to turn a listing location into a distance in miles from NE3 5HE. - Steven to confirm with Glass's and Cazana that reading valuations through his own logged in account is acceptable to them, since his permission from the platform owners covers Motorway and Carwow only. --- ## 11\. The bits that can break, honestly - Reading screens is the fragile part. When a platform changes its page, a read can stall. Build it to fail loudly and tell Steven, rather than guess. Budget a little maintenance each month. - If a value cannot be read with confidence, hold that car back and flag it rather than pricing it on a bad number. - The learning is only as good as the data. Days to sell come only from cars that have actually sold, so treat early figures as a guide until a few months of history build up. - Above all, the app recommends and Steven decides. Keep it that way.