From d2a4d58d972daee225dc1d7fa9f6bd2c0d40b267 Mon Sep 17 00:00:00 2001 From: Stephen Umunna Date: Sun, 21 Jun 2026 22:00:14 -0700 Subject: [PATCH 1/3] docs: sync README and authoring guide with current implementation The README and CONTENT_GUIDE had drifted from the shipped product. Correct every stale count and capability claim against the source of truth: - 225 lessons (was 124): 115 across 9 role paths + 110 across 11 verticals, counted from Curriculum.swift and Content/Lessons/. - 20 certification exams (was "9 role"): 9 role + 11 vertical. - 5,127 native known-answer checks (was "2,500+"), from ./Scripts/test.sh. - Web demo is 13 interactive explorables incl. Pixel Setup (was listed as 3), 147 web tests; added a web build/test quickstart. - Latest release is v1.1.1 (Status said "BidLab 1.0"); link docs/ACCEPTANCE.md. - CONTENT_GUIDE: track list now includes adops, ai, and all 11 verticals; the widget catalog adds the pixel widgets; the stale "only 3 are interactive" note is replaced (all catalog types render live except monteCarlo) with the WidgetRegistry + knownWidgets-whitelist gotcha. Co-Authored-By: Claude Opus 4.8 --- Content/CONTENT_GUIDE.md | 20 ++++++++++++---- README.md | 50 +++++++++++++++++++++++++++------------- 2 files changed, 49 insertions(+), 21 deletions(-) diff --git a/Content/CONTENT_GUIDE.md b/Content/CONTENT_GUIDE.md index 971a37e..d510ec2 100644 --- a/Content/CONTENT_GUIDE.md +++ b/Content/CONTENT_GUIDE.md @@ -48,7 +48,11 @@ explain: One or two sentences on why the answer is correct. ## Rules - Frontmatter keys: `id`, `track`, `module`, `title`, `summary`. `track` is one - of: foundations, core, dsp, sales, planning, analytics, engineering. + of: foundations, core, adops, dsp, sales, planning, analytics, engineering, ai, + or an industry vertical (`vertical-retail`, `vertical-cpg`, + `vertical-ecommerce`, `vertical-dtc`, `vertical-auto`, `vertical-finance`, + `vertical-travel`, `vertical-telecom`, `vertical-healthcare`, `vertical-qsr`, + `vertical-b2b`). - Structure each lesson as 3 to 5 short sections: a `# heading` then prose. - Include exactly one display-math block `$$ ... $$` where the concept has a formula. Keep LaTeX simple. Supported: greek (`\pi \mu \sigma \lambda \alpha @@ -92,10 +96,16 @@ explain: One or two sentences on why the answer is correct. - `codeLab` — read the algorithm behind a system - `didExplorer` — difference-in-differences lift - `yieldExplorer` — fill rate and yield - -Only `bidPlayground`/`auctionSimulator`, `reachFrequency`, and `experimentPower` -are interactive today. The rest render as a labeled placeholder, which is fine. -Reference whichever is most apt for the lesson. +- `pixelSetup` / `pixelWalkthrough` — step-by-step conversion-pixel setup walkthrough +- `pixelCalculators` / `trackingCalculators` — capture rate, dedup inflation, and discrepancy calculators + +Every type listed above renders as a live, interactive SwiftUI widget today; the +one exception is `monteCarlo`, which still renders as a labeled placeholder. The +registry that resolves a `:::widget ` directive to a view is +`Sources/BidLab/Widgets/WidgetRegistry.swift`. Reference whichever is most apt +for the lesson. If you add a new type, register it there and add it to the +`knownWidgets` whitelist in `Tests/BidLabCoreTests/ContentValidationTests.swift`, +or `Scripts/test.sh` will fail. ## Output diff --git a/README.md b/README.md index 004decd..1392a0a 100644 --- a/README.md +++ b/README.md @@ -5,8 +5,9 @@ The flight simulator for programmatic advertising. A native macOS app that teaches the math of programmatic by doing it: nine learning paths (Foundations and Programmatic Core, plus Ad Operations, DSP/Trader, Sales, Planning, -Analytics, Engineering, and AI in AdTech), 124 interactive lessons, 9 role -certification exams, a math-true bidding simulator, and a shareable credential. +Analytics, Engineering, and AI in AdTech) and eleven industry verticals, 225 +interactive lessons, 20 certification exams, a math-true bidding simulator, and a +shareable credential. Every concept is interactive and every number is real. Train the bid, the plan, the deal, the experiment, and the bidder itself, without spending a dollar of @@ -17,12 +18,14 @@ media. **▶ [Open the interactive web demo](https://scumunna.github.io/BidLab/)** — the *actual* BidLab engine running in your browser, free and on any device: drag a bid and run 50,000 auctions scored against the optimum, model reach and -frequency, and size an A/B test. No Mac required. +frequency, size an A/B test, and explore ten more (budget allocation, +attribution, yield, pacing, latency, conversion-pixel setup, and more). No Mac +required. [![BidLab web demo](web/public/og.png)](https://scumunna.github.io/BidLab/) Prefer the full experience? **[Download for macOS](https://github.com/scumunna/BidLab/releases)** -— 124 lessons, exams, spaced-repetition review, and shareable credentials — or +— 225 lessons, 20 exams, spaced-repetition review, and shareable credentials — or build from source below. > The web demo is a faithful TypeScript port of the pure `BidLabCore` Swift @@ -31,7 +34,7 @@ build from source below. ## Screenshots -**Learn — nine role-based paths and 124 cited, interactive lessons** +**Learn — nine role-based paths plus eleven industry verticals, 225 cited, interactive lessons** ![BidLab Learn surface](docs/screenshots/learn.png) @@ -62,23 +65,25 @@ build from source below. ## What is in here - **`BidLabCore`** (built as a SwiftPM-style library): a pure, UI-free Swift - engine validated by a known-answer test suite (2,500+ checks) covering pricing, + engine validated by a known-answer test suite (5,127 checks) covering pricing, auctions, probability, statistics, reach and frequency, budget allocation, pacing, a seeded market simulation, scoring, analytics (power, difference-in- - differences, adstock, saturation, OLS), DSP systems (latency, queueing), and - the lesson parser. + differences, adstock, saturation, OLS), DSP systems (latency, queueing), + conversion tracking, and the lesson parser. - **The app** (`Sources/BidLab`): a SwiftUI shell with nine surfaces (Learn, Review, Industries, Trading Floor, Tools, Exams, Progress, Explorable, and Settings), an original design system, interactive widgets, a native math renderer, the "open the hood" transparency panel, an embedded SQLite SQL lab, branded PNG/CSV/JSON export, and progress with a shareable certificate. -- **Content** (`Content/Lessons/*.md`): 124 authored, cited lessons in an original +- **Content** (`Content/Lessons/*.md`): 225 authored, cited lessons in an original Markdown-flavored format, parsed at launch from the app bundle. See `Content/CONTENT_GUIDE.md` for the format. -- **Web demo** (`web/`): a Vite + React + TypeScript reimplementation of the hero - explorables (Trading Floor, Reach & Frequency, A/B Power), deployed free to - GitHub Pages. The math is a faithful port of `BidLabCore`, verified against the - Swift engine in a golden-master test, and the build/deploy is automated in +- **Web demo** (`web/`): a Vite + React + TypeScript reimplementation of thirteen + interactive explorables (the Trading Floor plus Reach & Frequency, A/B Power, + Budget Allocator, Latency, Margin, Pixel Setup, Attribution, Forecast, Yield, + Pricing, Adstock, and Distribution), deployed free to GitHub Pages. The math is + a faithful port of `BidLabCore`, verified against the Swift engine in + golden-master tests (147 web tests), and the build and deploy are automated in `.github/workflows/pages.yml`. ## Building and running @@ -88,11 +93,20 @@ Xcode). This project builds entirely with `swiftc` (no full Xcode required), because the Command Line Tools on the original machine shipped a broken SwiftPM. ```sh -./Scripts/test.sh # build the core and run the test suite (2,500+ checks) +./Scripts/test.sh # build the core and run the test suite (5,127 checks) ./Scripts/build.sh # build the app -> build/BidLab.app open build/BidLab.app # run it ``` +For the web demo: + +```sh +cd web +npm install +npm test # run the engine + acceptance test suite (147 checks) +npm run dev # serve the demo locally +``` + To produce a distributable disk image: ```sh @@ -111,8 +125,12 @@ hdiutil create -volname BidLab -srcfolder build/BidLab.app -ov -format UDZO buil ## Status -BidLab 1.0. All nine paths are complete (124 lessons), every widget is -interactive, and the product has been verified running in the live environment. +BidLab is feature-complete: all nine role paths and eleven industry verticals are +authored (225 lessons, 20 certification exams), every widget is interactive, and +the free web demo is live on GitHub Pages. The engine is covered by 5,127 native +and 147 web known-answer checks; see [docs/ACCEPTANCE.md](docs/ACCEPTANCE.md) for +the full acceptance-evidence report. Latest release: +[v1.1.1](https://github.com/scumunna/BidLab/releases). ## License From dc4b6d71d962fcfe654f6a1fa4edf11085579686 Mon Sep 17 00:00:00 2001 From: Stephen Umunna Date: Sun, 21 Jun 2026 22:00:14 -0700 Subject: [PATCH 2/3] fix(web): correct stale lesson/exam counts in the demo footer The public web demo footer claimed "124 interactive lessons ... certification exams". Update to 225 lessons and 20 certification exams to match the app. Co-Authored-By: Claude Opus 4.8 --- web/src/App.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/web/src/App.tsx b/web/src/App.tsx index be65c0c..6ea27bd 100644 --- a/web/src/App.tsx +++ b/web/src/App.tsx @@ -150,7 +150,7 @@ export default function App() { matches the native app bit-for-bit).

- The full app adds 124 interactive lessons across 9 roles and 11 industry verticals, certification exams, spaced-repetition + The full app adds 225 interactive lessons across 9 roles and 11 industry verticals, 20 certification exams, spaced-repetition review, and shareable credentials.{' '} See the project on GitHub → From 85dd9e35cd1205f2ce2bfcfb1e12efb5c0403cbd Mon Sep 17 00:00:00 2001 From: Stephen Umunna Date: Tue, 23 Jun 2026 11:07:58 -0700 Subject: [PATCH 3/3] docs: sync test counts to the merged coverage work (5,271 native / 180 web) #9 raised the native suite to 5,271 checks and #10 the web suite to 180; update the README and ACCEPTANCE.md to match, and add the CI coverage-gate story (web 100%, native 100% of reachable code). ACCEPTANCE.md's web engine-suite row now includes the added boundary tests (47 -> 80). Co-Authored-By: Claude Opus 4.8 --- README.md | 17 +++++++++-------- docs/ACCEPTANCE.md | 12 +++++++----- 2 files changed, 16 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 1392a0a..cf15057 100644 --- a/README.md +++ b/README.md @@ -65,7 +65,7 @@ build from source below. ## What is in here - **`BidLabCore`** (built as a SwiftPM-style library): a pure, UI-free Swift - engine validated by a known-answer test suite (5,127 checks) covering pricing, + engine validated by a known-answer test suite (5,271 checks) covering pricing, auctions, probability, statistics, reach and frequency, budget allocation, pacing, a seeded market simulation, scoring, analytics (power, difference-in- differences, adstock, saturation, OLS), DSP systems (latency, queueing), @@ -83,7 +83,7 @@ build from source below. Budget Allocator, Latency, Margin, Pixel Setup, Attribution, Forecast, Yield, Pricing, Adstock, and Distribution), deployed free to GitHub Pages. The math is a faithful port of `BidLabCore`, verified against the Swift engine in - golden-master tests (147 web tests), and the build and deploy are automated in + golden-master tests (180 web tests; the engine is gated at 100% coverage), and the build and deploy are automated in `.github/workflows/pages.yml`. ## Building and running @@ -93,7 +93,7 @@ Xcode). This project builds entirely with `swiftc` (no full Xcode required), because the Command Line Tools on the original machine shipped a broken SwiftPM. ```sh -./Scripts/test.sh # build the core and run the test suite (5,127 checks) +./Scripts/test.sh # build the core and run the test suite (5,271 checks) ./Scripts/build.sh # build the app -> build/BidLab.app open build/BidLab.app # run it ``` @@ -103,7 +103,7 @@ For the web demo: ```sh cd web npm install -npm test # run the engine + acceptance test suite (147 checks) +npm test # run the engine + acceptance test suite (180 checks) npm run dev # serve the demo locally ``` @@ -127,10 +127,11 @@ hdiutil create -volname BidLab -srcfolder build/BidLab.app -ov -format UDZO buil BidLab is feature-complete: all nine role paths and eleven industry verticals are authored (225 lessons, 20 certification exams), every widget is interactive, and -the free web demo is live on GitHub Pages. The engine is covered by 5,127 native -and 147 web known-answer checks; see [docs/ACCEPTANCE.md](docs/ACCEPTANCE.md) for -the full acceptance-evidence report. Latest release: -[v1.1.1](https://github.com/scumunna/BidLab/releases). +the free web demo is live on GitHub Pages. The pure engines are covered to 100% +(web) and 100% of reachable code (native), enforced by CI coverage gates, across +5,271 native and 180 web known-answer checks; see +[docs/COVERAGE.md](docs/COVERAGE.md) and [docs/ACCEPTANCE.md](docs/ACCEPTANCE.md). +Latest release: [v1.1.1](https://github.com/scumunna/BidLab/releases). ## License diff --git a/docs/ACCEPTANCE.md b/docs/ACCEPTANCE.md index a003efa..92392e9 100644 --- a/docs/ACCEPTANCE.md +++ b/docs/ACCEPTANCE.md @@ -16,12 +16,14 @@ A reproducible, deterministic acceptance pass over every major capability of the | Layer | What it proves | Scenarios | Result | |---|---|---|---| | **Engine acceptance suite** (`web/src/eval/acceptance.test.ts`) | Every engine capability: golden + invariant + edge | **100** | ✅ 100 / 100 | -| Web unit suite (`web/src/engine/*.test.ts`) | Golden parity vs the compiled Swift engine | 47 | ✅ 47 / 47 | +| Web engine suite (`web/src/engine/*.test.ts`) | Golden parity vs the compiled Swift engine + 100% engine boundary coverage | 80 | ✅ 80 / 80 | | Live UI run (Playwright, headless) | Entry, routing, the hero in 3 modes, onboarding, all explorables, the pixel widget, responsiveness @375px | 20 | ✅ 20 / 20 | -| Native known-answer suite (`./Scripts/test.sh`) | Swift engine + all lessons/exams/widgets | 5,127 | ✅ 5,127 / 5,127 | +| Native known-answer suite (`./Scripts/test.sh`) | Swift engine + all lessons/exams/widgets | 5,271 | ✅ 5,271 / 5,271 | **The complete set passed on the first run and again on rerun (stable).** No failures occurred, so the fix-and-rerun loop completed with no changes required — the product already cleared the bar. +Both pure engines are additionally **gated to 100% coverage in CI**: the web engine via `vitest` v8 (`.github/workflows/web.yml`) and `BidLabCore` via `llvm-cov` of reachable code (`.github/workflows/ci.yml`). See [COVERAGE.md](COVERAGE.md). + ## The 100 acceptance scenarios, by capability Each row is a numbered, named `it(...)` in `web/src/eval/acceptance.test.ts`; that file is the line-by-line evidence. @@ -46,11 +48,11 @@ Each row is a numbered, named `it(...)` in `web/src/eval/acceptance.test.ts`; th ## Reproduce ```sh -# Engine acceptance + web unit (100 + 47), deterministic: -cd web && npm test # -> 147 passed +# Engine acceptance + web engine suites (100 + 80), deterministic: +cd web && npm test # -> 180 passed # Native engine + all curriculum (lessons, exams, widgets): -./Scripts/test.sh # -> all 5,127 checks passed +./Scripts/test.sh # -> all 5,271 checks passed ``` The web demo's numbers are not illustrative — they are the *same* engine, asserted equal to the native macOS app. That parity is the whole point: what a CEO clicks in the browser is the production math.