docs: add links section, fix download badges, post-download CTAs

- Add Links section to both READMEs (website, issues, PyPI, npm, email)
- Replace broken pepy.tech badge with shields.io PyPI + npm download badges
- Post-download messages: website, issues link, star CTA (Python + JS)
- Fix CLOAKBROWSER_DOWNLOAD_URL default in docs (github → cloakbrowser.dev)
- Fix tests: download URL assertions, platform-aware stealth args test

README.md

@@ -4,21 +4,25 @@
 
 # CloakBrowser
 
-[![PyPI](https://img.shields.io/pypi/v/cloakbrowser)](https://pypi.org/project/cloakbrowser/)
+<p align="center">
-[![npm](https://img.shields.io/npm/v/cloakbrowser)](https://www.npmjs.com/package/cloakbrowser)
+<a href="https://pypi.org/project/cloakbrowser/"><img src="https://img.shields.io/pypi/v/cloakbrowser" alt="PyPI"></a>
-[![Python](https://img.shields.io/pypi/pyversions/cloakbrowser)](https://pypi.org/project/cloakbrowser/)
+<a href="https://www.npmjs.com/package/cloakbrowser"><img src="https://img.shields.io/npm/v/cloakbrowser" alt="npm"></a>
-[![License](https://img.shields.io/github/license/CloakHQ/CloakBrowser)](LICENSE)
+<a href="https://pypi.org/project/cloakbrowser/"><img src="https://img.shields.io/pypi/pyversions/cloakbrowser" alt="Python"></a>
-[![Downloads](https://img.shields.io/pepy/dt/cloakbrowser)](https://pepy.tech/project/cloakbrowser)
+<a href="LICENSE"><img src="https://img.shields.io/github/license/CloakHQ/CloakBrowser" alt="License"></a>
-[![Stars](https://img.shields.io/github/stars/CloakHQ/CloakBrowser)](https://github.com/CloakHQ/CloakBrowser)
+<br>
-[![Last Commit](https://img.shields.io/github/last-commit/CloakHQ/CloakBrowser)](https://github.com/CloakHQ/CloakBrowser)
+<a href="https://github.com/CloakHQ/CloakBrowser"><img src="https://img.shields.io/github/stars/CloakHQ/CloakBrowser" alt="Stars"></a>
+<a href="https://pypi.org/project/cloakbrowser/"><img src="https://img.shields.io/pypi/dm/cloakbrowser" alt="PyPI Downloads"></a>
+<a href="https://www.npmjs.com/package/cloakbrowser"><img src="https://img.shields.io/npm/dm/cloakbrowser" alt="npm Downloads"></a>
+<a href="https://github.com/CloakHQ/CloakBrowser"><img src="https://img.shields.io/github/last-commit/CloakHQ/CloakBrowser" alt="Last Commit"></a>
+</p>
 
 **Stealth Chromium that passes every bot detection test.**
 
-Drop-in Playwright/Puppeteer replacement for Python and JavaScript. Same API, same code — just swap the import. Your browser now scores **0.9 on reCAPTCHA v3**, passes **Cloudflare Turnstile**, and clears **14 out of 14** stealth detection tests.
+Drop-in Playwright/Puppeteer replacement for Python and JavaScript. Same API, same code — just swap the import. Your browser now scores **0.9 on reCAPTCHA v3**, passes **Cloudflare Turnstile**, and clears **30 out of 30** stealth detection tests.
 
 - 🔒 **16 source-level C++ patches** — not JS injection, not config flags
 - 🎯 **0.9 reCAPTCHA v3 score** — human-level, server-verified
-- ☁️ **Passes Cloudflare Turnstile**, FingerprintJS, BrowserScan — 14/14 tests
+- ☁️ **Passes Cloudflare Turnstile**, FingerprintJS, BrowserScan — 30/30 tests
 - 🔄 **Drop-in replacement** — works with Playwright (Python & JS) and Puppeteer (JS)
 - 📦 **`pip install cloakbrowser`** or **`npm install cloakbrowser`** — binary auto-downloads, zero config
 - 🦊 **Fills the Camoufox vacuum** — Chromium-based, actively maintained
@@ -98,7 +102,7 @@ All tests verified against live detection services. Last tested: Feb 2026 (Chrom
 | CDP detection | Detected | **Not detected** | `isAutomatedWithCDP: false` |
 | TLS fingerprint | Mismatch | **Identical to Chrome** | ja3n/ja4/akamai match |
 
-**14/14 tests passed.**
+**30/30 tests passed.**
 
 ### Proof
 
@@ -127,7 +131,7 @@ All tests verified against live detection services. Last tested: Feb 2026 (Chrom
 CloakBrowser is a thin wrapper (Python + JavaScript) around a custom-built Chromium binary:
 
 1. **You install** → `pip install cloakbrowser` or `npm install cloakbrowser`
-2. **First launch** → binary auto-downloads for your platform (Linux x64 / macOS arm64)
+2. **First launch** → binary auto-downloads for your platform (Linux x64, macOS arm64/x64)
 3. **Every launch** → Playwright or Puppeteer starts with our binary + stealth args
 4. **You write code** → standard Playwright/Puppeteer API, nothing new to learn
 
@@ -283,7 +287,7 @@ clearCache();
 |---|---|---|
 | `CLOAKBROWSER_BINARY_PATH` | — | Skip download, use a local Chromium binary |
 | `CLOAKBROWSER_CACHE_DIR` | `~/.cloakbrowser` | Binary cache directory |
-| `CLOAKBROWSER_DOWNLOAD_URL` | GitHub Releases | Custom download URL for binary |
+| `CLOAKBROWSER_DOWNLOAD_URL` | `cloakbrowser.dev` | Custom download URL for binary |
 | `CLOAKBROWSER_AUTO_UPDATE` | `true` | Set to `false` to disable background update checks |
 
 ## Fingerprint Management
@@ -394,8 +398,9 @@ page.goto("https://example.com")
 | macOS x86_64 (Intel) | ✅ Available |
 | Windows | Planned |
 
-**On Windows?** You can still use CloakBrowser via Docker or with your own Chromium binary by setting `CLOAKBROWSER_BINARY_PATH=/path/to/chrome`.
+**macOS first launch:** The binary is ad-hoc signed. On first run, macOS Gatekeeper will block it. Right-click the app → **Open** → click **Open** in the dialog. This is only needed once.
 
+**On Windows?** You can still use CloakBrowser via Docker or with your own Chromium binary by setting `CLOAKBROWSER_BINARY_PATH=/path/to/chrome`.
 ## Examples
 
 **Python** — see [`examples/`](examples/):
@@ -505,10 +510,18 @@ A: Yes. Pass `proxy="http://user:pass@host:port"` to `launch()`.
 **Q: Can I use this with Docker?**
 A: Yes. A ready-to-use Dockerfile is included — see the [Docker](#docker) section above.
 
+## Links
+
+- 🌐 **Website** — [cloakbrowser.dev](https://cloakbrowser.dev)
+- 🐛 **Bug reports & feature requests** — [GitHub Issues](https://github.com/CloakHQ/CloakBrowser/issues)
+- 📦 **PyPI** — [pypi.org/project/cloakbrowser](https://pypi.org/project/cloakbrowser/)
+- 📦 **npm** — [npmjs.com/package/cloakbrowser](https://www.npmjs.com/package/cloakbrowser)
+- 📧 **Contact** — cloakhq@pm.me
+
 ## License
 
 MIT — see [LICENSE](LICENSE).
 
 ## Contributing
 
-Issues and PRs welcome. Contact: cloakhq@pm.me
+Issues and PRs welcome. If something isn't working, [open an issue](https://github.com/CloakHQ/CloakBrowser/issues) — we respond fast.

cloakbrowser/download.py

@@ -115,7 +115,9 @@ def _download_and_extract(version: str | None = None) -> None:
     try:
         _download_file(url, tmp_path)
         _extract_archive(tmp_path, binary_dir, binary_path)
-        logger.info("Visit https://cloakbrowser.dev for updates and release notifications.")
+        logger.info("Visit https://cloakbrowser.dev for docs and release notifications.")
+        logger.info("Issues? https://github.com/CloakHQ/CloakBrowser/issues")
+        logger.info("Star us if CloakBrowser helps: https://github.com/CloakHQ/CloakBrowser")
     finally:
         # Clean up temp file
         tmp_path.unlink(missing_ok=True)

js/README.md

@@ -9,11 +9,11 @@
 
 **Stealth Chromium that passes every bot detection test.**
 
-Drop-in Playwright/Puppeteer replacement. Same API — just swap the import. Scores **0.9 on reCAPTCHA v3**, passes **Cloudflare Turnstile**, and clears **14/14** stealth detection tests.
+Drop-in Playwright/Puppeteer replacement. Same API — just swap the import. Scores **0.9 on reCAPTCHA v3**, passes **Cloudflare Turnstile**, and clears **30/30** stealth detection tests.
 
 - 🔒 **16 source-level C++ patches** — not JS injection, not config flags
 - 🎯 **0.9 reCAPTCHA v3 score** — human-level, server-verified
-- ☁️ **Passes Cloudflare Turnstile**, FingerprintJS, BrowserScan — 14/14 tests
+- ☁️ **Passes Cloudflare Turnstile**, FingerprintJS, BrowserScan — 30/30 tests
 - 🔄 **Drop-in replacement** — works with both Playwright and Puppeteer
 - 📦 **`npm install cloakbrowser`** — binary auto-downloads, zero config
 
@@ -120,7 +120,7 @@ if (newVersion) console.log(`Updated to ${newVersion}`);
 |---|---|---|
 | `CLOAKBROWSER_BINARY_PATH` | — | Skip download, use a local Chromium binary |
 | `CLOAKBROWSER_CACHE_DIR` | `~/.cloakbrowser` | Binary cache directory |
-| `CLOAKBROWSER_DOWNLOAD_URL` | GitHub Releases | Custom download URL |
+| `CLOAKBROWSER_DOWNLOAD_URL` | `cloakbrowser.dev` | Custom download URL |
 | `CLOAKBROWSER_AUTO_UPDATE` | `true` | Set to `false` to disable background update checks |
 
 ## Migrate From Playwright
@@ -151,12 +151,14 @@ const page = await browser.newPage();
 - Node.js >= 18
 - One of: `playwright-core` >= 1.40 or `puppeteer-core` >= 21
 
+## Links
+
+- 🌐 [Website](https://cloakbrowser.dev)
+- 🐛 [Bug reports & feature requests](https://github.com/CloakHQ/CloakBrowser/issues)
+- 📦 [PyPI (Python package)](https://pypi.org/project/cloakbrowser/)
+- 📖 [Full documentation](https://github.com/CloakHQ/CloakBrowser#readme)
+- 📧 Contact: cloakhq@pm.me
+
 ## License
 
 MIT — see [LICENSE](https://github.com/CloakHQ/CloakBrowser/blob/main/LICENSE).
-
-## Links
-
-- [GitHub](https://github.com/CloakHQ/CloakBrowser)
-- [PyPI (Python package)](https://pypi.org/project/cloakbrowser/)
-- [Full documentation](https://github.com/CloakHQ/CloakBrowser#readme)

js/src/download.ts

@@ -151,7 +151,13 @@ async function downloadAndExtract(version?: string): Promise<void> {
     await downloadFile(url, tmpPath);
     await extractArchive(tmpPath, binaryDir, binaryPath);
     console.log(
-      `[cloakbrowser] Visit https://cloakbrowser.dev for updates and release notifications.`
+      `[cloakbrowser] Visit https://cloakbrowser.dev for docs and release notifications.`
+    );
+    console.log(
+      `[cloakbrowser] Issues? https://github.com/CloakHQ/CloakBrowser/issues`
+    );
+    console.log(
+      `[cloakbrowser] Star us if CloakBrowser helps: https://github.com/CloakHQ/CloakBrowser`
     );
   } finally {
     // Clean up temp file

js/tests/config.test.ts

@@ -14,11 +14,19 @@ describe("config", () => {
 
   it("getDefaultStealthArgs returns expected flags", () => {
     const args = getDefaultStealthArgs();
+    const isMac = process.platform === "darwin";
 
     expect(args).toContain("--no-sandbox");
     expect(args).toContain("--disable-blink-features=AutomationControlled");
+
+    if (isMac) {
+      expect(args).toContain("--fingerprint-platform=macos");
+      // macOS: no hardware-concurrency or GPU spoofing (uses native values)
+      expect(args.some((a) => a.includes("hardware-concurrency"))).toBe(false);
+    } else {
       expect(args).toContain("--fingerprint-platform=windows");
       expect(args).toContain("--fingerprint-hardware-concurrency=8");
+    }
 
     // Should have a random fingerprint seed
     const fingerprintArg = args.find((a) => a.startsWith("--fingerprint="));
@@ -54,6 +62,6 @@ describe("config", () => {
     expect(url).toContain(CHROMIUM_VERSION);
     expect(url).toContain("cloakbrowser-");
     expect(url).toContain(".tar.gz");
-    expect(url).toContain("github.com/CloakHQ/");
+    expect(url).toContain("cloakbrowser.dev");
   });
 });

js/tests/update.test.ts

@@ -37,7 +37,7 @@ describe("version comparison", () => {
 describe("download URL", () => {
   it("uses chromium-v prefix and cloakbrowser repo", () => {
     const url = getDownloadUrl();
-    expect(url).toContain("github.com/CloakHQ/cloakbrowser/releases/download");
+    expect(url).toContain("cloakbrowser.dev");
     expect(url).toContain(`chromium-v${CHROMIUM_VERSION}`);
     expect(url.endsWith(".tar.gz")).toBe(true);
   });

tests/test_update.py

@@ -45,7 +45,7 @@ class TestVersionComparison:
 class TestDownloadUrl:
     def test_default_url_format(self):
         url = get_download_url()
-        assert "github.com/CloakHQ/cloakbrowser/releases/download" in url
+        assert "cloakbrowser.dev" in url
         assert f"chromium-v{CHROMIUM_VERSION}" in url
         assert url.endswith(".tar.gz")