agentic-stealth-browser 0.8.0__tar.gz

agentic_stealth_browser-0.8.0/.env.example

@@ -0,0 +1,2 @@
+STEALTH_REGION=japan
+PROXY_URL=

agentic_stealth_browser-0.8.0/CHANGELOG.md

@@ -0,0 +1,82 @@
+# Changelog
+
+All notable changes to the Agentic Stealth Browser will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [Unreleased] — Phase 8 DX & Debug Release (2026-05)
+
+### Added — High-Value DX Features (closes #265, #273, #288, #281, #257, #297, #241 and many documentation issues)
+
+- **Debug Mode (#265)**: `AgentBrowser(launch(debug=True))` now produces exact, machine-readable + human-pretty dumps of:
+  - TLS fingerprint (full ciphers, extensions, curves, signature algorithms, launch args)
+  - Exact HTTP headers sent to Playwright
+  - All stealth JS patches applied
+  - Full `debug_report(print_report=True)` and `stealth_debug_report()` in MCP
+  - Structured debug JSONL logs alongside normal audit trails (`AuditLogger` + `DebugReporter`)
+
+- **"Explain Why Blocked" Analyzer (#273)**: New `explain_why_blocked()` + orchestrator integration + MCP `stealth_explain_blocked()`.
+  - Returns clear English explanation, root cause hypothesis, and **prioritized, copy-paste actionable recommendations**.
+  - LinkedIn/Amazon/Cloudflare-specific advice.
+  - Perfect companion to debug dumps when you hit a wall.
+
+- **Platform Presets for 2026 (#288)**: `stealth/presets.py` + first-class support in `launch(preset=...)` and `apply_preset()`.
+  - `linkedin_2026` (P1 target): US TLS, heavy behavior, heavy warm-up, 6 retries, professional persona notes.
+  - `amazon_2026`, `upwork_2026`, `cloudflare_generic`, `general_high_stealth`.
+  - `stealth_list_presets()`, `stealth_apply_preset("linkedin_2026")`, MCP exposure.
+  - `build_launch_config_from_preset` for easy extension.
+
+- **Status / Health Command (#281)**: `get_health_status()`, enhanced `stealth_status()`, `stealth_health()`.
+  - Launched state, current preset, TLS profile, recent blocks, cookie health, current URL, recovery stats.
+  - Immediately useful for operators, dashboards, and MCP consumers.
+
+- **Quick-Start Notebook (#257)**: `examples/quick_start.ipynb` (created) with runnable cells covering:
+  - Basic launch, safe_goto, warm-up
+  - Debug mode + full fingerprint dump
+  - LinkedIn 2026 preset end-to-end
+  - explain_blocked + health checks
+  - MCP usage patterns
+
+- **Changelog & Release Notes Experience (#297)**: This `CHANGELOG.md` + docs/THREAT_MODEL.md + improved README sections.
+  - Clear "Unreleased" section linking to closed issues.
+  - Future releases will follow the same format.
+
+- **Security / Threat Model Documentation (#241)**: `docs/THREAT_MODEL.md`
+  - What the library actually defends against vs. limitations
+  - Operational security best practices for 2026
+  - Responsible use guidance
+
+### Changed / Improved
+- `AgentBrowser.launch()` now accepts `debug`, `preset`, `region` — fully backwards compatible.
+- MCP tools (`stealth-playwright-mcp/mcp_tools.py` + `stealth_mcp.py`) expose all new DX capabilities.
+- `AuditLogger` extended with `enable_debug_mode()`, `log_debug_dump()`, `DebugReporter` class.
+- Recovery orchestrator now produces richer logs when blocks occur.
+- README updated with "Quick Start", "Debugging & Diagnostics", "Platform Presets 2026", "Health & Status", "MCP DX Tools".
+
+### Documentation
+- Many [documentation] and [DX] issues addressed via the above + inline docstrings, preset notes, and threat model.
+
+---
+
+## [0.2.0] — 2026-05 (Phase 7 Reliability)
+
+- Core context manager (`async with AgentBrowser()`) — #292
+- Major bug fixes (BUG-01..05): rng, Page vs Context, page_getter for detection, rate limiter correctness
+- Recovery integration improvements
+- Test coverage for critical paths (`tests/test_phase7_fixes.py`)
+
+---
+
+## [0.1.0] — Initial Public Foundation (2026-05)
+
+- First release of modular stealth + recovery + human behavior + TLS fingerprinting architecture.
+- Basic AgentBrowser, AuditLogger, presets groundwork, MCP skill skeleton.
+
+---
+
+[Unreleased]: https://github.com/shanewas/agentic-stealth-browser/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/shanewas/agentic-stealth-browser/releases/tag/v0.2.0
+[0.1.0]: https://github.com/shanewas/agentic-stealth-browser/releases/tag/v0.1.0

agentic_stealth_browser-0.8.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shane W
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentic_stealth_browser-0.8.0/MANIFEST.in

@@ -0,0 +1,10 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+include .env.example
+include docs/THREAT_MODEL.md
+include docs/using-as-library.md
+recursive-include stealth *.js *.json
+recursive-include production Dockerfile docker-healthcheck.py
+recursive-include examples *.md
+recursive-include tests *.py *.json

agentic_stealth_browser-0.8.0/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: agentic-stealth-browser
+Version: 0.8.0
+Summary: Production-grade, human-mimicking browser automation framework for autonomous agents. Survives modern anti-bot systems.
+Author-email: Shane W <shanewas@users.noreply.github.com>
+License: MIT
+Project-URL: Homepage, https://github.com/shanewas/agentic-stealth-browser
+Project-URL: Repository, https://github.com/shanewas/agentic-stealth-browser
+Project-URL: Issues, https://github.com/shanewas/agentic-stealth-browser/issues
+Project-URL: Documentation, https://github.com/shanewas/agentic-stealth-browser/tree/master/docs
+Project-URL: Changelog, https://github.com/shanewas/agentic-stealth-browser/blob/master/CHANGELOG.md
+Keywords: stealth,browser,automation,playwright,anti-bot,scraping,agent
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Classifier: Topic :: Software Development :: Testing
+Classifier: Framework :: AsyncIO
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: playwright
+Requires-Dist: aiohttp
+Requires-Dist: cryptography
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Dynamic: license-file
+
+# Agentic Stealth Browser
+
+[![CI](https://github.com/shanewas/agentic-stealth-browser/actions/workflows/ci.yml/badge.svg)](https://github.com/shanewas/agentic-stealth-browser/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![Tests](https://img.shields.io/badge/tests-493%20passing-brightgreen)](tests/)
+
+A Python framework that makes browser automation look human. Built for autonomous agents that need to navigate websites protected by Cloudflare, LinkedIn, Amazon, and other anti-bot systems.
+
+## Why This Exists
+
+Standard browser automation (`page.goto()`, `page.click()`) gets detected instantly. This framework solves that by combining:
+
+- **TLS fingerprint spoofing** — matches real browser TLS handshakes
+- **Human behavior simulation** — natural mouse, typing, scrolling with realistic imperfections
+- **Automatic recovery** — detects blocks (CAPTCHAs, rate limits) and recovers without crashing
+- **Account lifecycle management** — warming, health scoring, cooling off
+
+## Installation
+
+```bash
+pip install agentic-stealth-browser
+playwright install --with-deps chromium
+```
+
+## Quick Start
+
+```python
+from core.agent_browser import AgentBrowser
+import asyncio
+
+async def main():
+    browser = AgentBrowser(session_name="demo")
+    await browser.launch(headless=True)
+
+    # This handles stealth, human behavior, and recovery automatically
+    await browser.safe_goto("https://example.com")
+
+    # Add human-like actions
+    await browser.human.scroll_naturally(400)
+    await browser.human.think(1500, 2800)
+
+    await browser.close()
+
+asyncio.run(main())
+```
+
+## Real-World Example
+
+For protected sites, load real cookies and use a platform preset:
+
+```python
+browser = AgentBrowser(session_name="linkedin")
+await browser.launch(preset="linkedin_2026")
+await browser.load_cookies_from_file("cookies.json")
+await browser.warm_up_before_work(intensity="heavy")
+await browser.safe_goto("https://www.linkedin.com/feed/", platform="linkedin")
+```
+
+The flow: **cookies → warm-up → navigate → recover if blocked → act human**.
+
+## How It Works
+
+```
+AgentBrowser
+├── Stealth      → TLS profiles, canvas/WebGL spoofing, WebRTC isolation
+├── Behavior     → Bézier mouse, natural typing, distraction simulation
+├── Recovery     → Detects blocks → rotates proxy/session → retries
+├── Accounts     → Health scoring, 14-day warming, session checkpointing
+└── Proxy        → Residential proxy with rotation and health tracking
+```
+
+## Key Features
+
+| Feature | What It Does |
+|---|---|
+| **TLS Fingerprinting** | Region-specific profiles (US, Japan, EU, Korea) with JA3/JA4 support |
+| **Human Behavior** | Mouse with wobble, typing with mistakes, variable scrolling, fatigue |
+| **Auto Recovery** | Detects CAPTCHAs, rate limits, blocks — recovers automatically |
+| **Account Warming** | 14-day gradual ramp-up so new accounts don't get flagged |
+| **Session Checkpoints** | Export/import browser state for cross-host migration |
+| **Platform Presets** | Pre-configured profiles for LinkedIn, Amazon, Cloudflare |
+| **MCP Server** | Integration with AI agents via Model Context Protocol |
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|---|---|---|
+| `STEALTH_REGION` | TLS fingerprint region | `japan` |
+| `STEALTH_HEADLESS` | Run browser headless | `true` |
+| `STEALTH_PROXY` | Use residential proxy | `false` |
+
+### Platform Presets
+
+```python
+await browser.launch(preset="linkedin_2026")   # LinkedIn
+await browser.launch(preset="amazon_2026")     # Amazon
+await browser.launch(preset="cloudflare")      # Cloudflare-protected sites
+```
+
+## Project Structure
+
+```
+agentic-stealth-browser/
+├── core/           # AgentBrowser main class
+├── stealth/        # TLS fingerprinting, script injection, caching
+├── behavior/       # Human-like mouse, typing, scrolling, personas
+├── recovery/       # Block detection, anti-block orchestrator
+├── proxy/          # Proxy management and rotation
+├── sessions/       # Session and cookie management
+├── audit/          # Structured logging and audit trails
+├── ai/             # AI hooks and content analysis
+├── production/     # CLI, Docker, rate limiting, metrics
+├── linkedin/       # LinkedIn-specific actions
+├── scraping/       # Safe page scraping utilities
+├── docs/           # Architecture Decision Records and guides
+└── tests/          # 493 tests across 23 files
+```
+
+## Documentation
+
+- [Architecture Decision Records](docs/adr/)
+- [Visual Debugging Guide](docs/VISUAL_DEBUGGING.md)
+- [Stealth Limitations](docs/STEALTH_LIMITATIONS.md)
+- [Threat Model](docs/THREAT_MODEL.md)
+- [Common Pitfalls](docs/COMMON_PITFALLS.md)
+- [Rate Limiting & Backoff](docs/RATE_LIMITING_BACKOFF.md)
+- [Cookie & Session Resilience](docs/COOKIE_SESSION_RESILIENCE.md)
+
+## Security
+
+See [SECURITY.md](SECURITY.md) for vulnerability reporting and best practices.
+
+## Responsible Use
+
+This framework is designed for legitimate automation use cases such as:
+
+- Testing your own applications and infrastructure
+- Automating workflows on platforms that permit automation
+- Research and security analysis
+- Accessibility testing
+
+**Important:** Many websites (including LinkedIn, Amazon, and others) prohibit automated access in their Terms of Service. Always:
+
+1. Review the target site's Terms of Service and robots.txt
+2. Obtain proper authorization before automating access
+3. Respect rate limits and avoid causing harm to services
+4. Use this tool responsibly and legally
+
+This project is provided as-is under the MIT License. Users are responsible for complying with applicable laws and terms of service.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

agentic_stealth_browser-0.8.0/README.md

@@ -0,0 +1,160 @@
+# Agentic Stealth Browser
+
+[![CI](https://github.com/shanewas/agentic-stealth-browser/actions/workflows/ci.yml/badge.svg)](https://github.com/shanewas/agentic-stealth-browser/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![Tests](https://img.shields.io/badge/tests-493%20passing-brightgreen)](tests/)
+
+A Python framework that makes browser automation look human. Built for autonomous agents that need to navigate websites protected by Cloudflare, LinkedIn, Amazon, and other anti-bot systems.
+
+## Why This Exists
+
+Standard browser automation (`page.goto()`, `page.click()`) gets detected instantly. This framework solves that by combining:
+
+- **TLS fingerprint spoofing** — matches real browser TLS handshakes
+- **Human behavior simulation** — natural mouse, typing, scrolling with realistic imperfections
+- **Automatic recovery** — detects blocks (CAPTCHAs, rate limits) and recovers without crashing
+- **Account lifecycle management** — warming, health scoring, cooling off
+
+## Installation
+
+```bash
+pip install agentic-stealth-browser
+playwright install --with-deps chromium
+```
+
+## Quick Start
+
+```python
+from core.agent_browser import AgentBrowser
+import asyncio
+
+async def main():
+    browser = AgentBrowser(session_name="demo")
+    await browser.launch(headless=True)
+
+    # This handles stealth, human behavior, and recovery automatically
+    await browser.safe_goto("https://example.com")
+
+    # Add human-like actions
+    await browser.human.scroll_naturally(400)
+    await browser.human.think(1500, 2800)
+
+    await browser.close()
+
+asyncio.run(main())
+```
+
+## Real-World Example
+
+For protected sites, load real cookies and use a platform preset:
+
+```python
+browser = AgentBrowser(session_name="linkedin")
+await browser.launch(preset="linkedin_2026")
+await browser.load_cookies_from_file("cookies.json")
+await browser.warm_up_before_work(intensity="heavy")
+await browser.safe_goto("https://www.linkedin.com/feed/", platform="linkedin")
+```
+
+The flow: **cookies → warm-up → navigate → recover if blocked → act human**.
+
+## How It Works
+
+```
+AgentBrowser
+├── Stealth      → TLS profiles, canvas/WebGL spoofing, WebRTC isolation
+├── Behavior     → Bézier mouse, natural typing, distraction simulation
+├── Recovery     → Detects blocks → rotates proxy/session → retries
+├── Accounts     → Health scoring, 14-day warming, session checkpointing
+└── Proxy        → Residential proxy with rotation and health tracking
+```
+
+## Key Features
+
+| Feature | What It Does |
+|---|---|
+| **TLS Fingerprinting** | Region-specific profiles (US, Japan, EU, Korea) with JA3/JA4 support |
+| **Human Behavior** | Mouse with wobble, typing with mistakes, variable scrolling, fatigue |
+| **Auto Recovery** | Detects CAPTCHAs, rate limits, blocks — recovers automatically |
+| **Account Warming** | 14-day gradual ramp-up so new accounts don't get flagged |
+| **Session Checkpoints** | Export/import browser state for cross-host migration |
+| **Platform Presets** | Pre-configured profiles for LinkedIn, Amazon, Cloudflare |
+| **MCP Server** | Integration with AI agents via Model Context Protocol |
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|---|---|---|
+| `STEALTH_REGION` | TLS fingerprint region | `japan` |
+| `STEALTH_HEADLESS` | Run browser headless | `true` |
+| `STEALTH_PROXY` | Use residential proxy | `false` |
+
+### Platform Presets
+
+```python
+await browser.launch(preset="linkedin_2026")   # LinkedIn
+await browser.launch(preset="amazon_2026")     # Amazon
+await browser.launch(preset="cloudflare")      # Cloudflare-protected sites
+```
+
+## Project Structure
+
+```
+agentic-stealth-browser/
+├── core/           # AgentBrowser main class
+├── stealth/        # TLS fingerprinting, script injection, caching
+├── behavior/       # Human-like mouse, typing, scrolling, personas
+├── recovery/       # Block detection, anti-block orchestrator
+├── proxy/          # Proxy management and rotation
+├── sessions/       # Session and cookie management
+├── audit/          # Structured logging and audit trails
+├── ai/             # AI hooks and content analysis
+├── production/     # CLI, Docker, rate limiting, metrics
+├── linkedin/       # LinkedIn-specific actions
+├── scraping/       # Safe page scraping utilities
+├── docs/           # Architecture Decision Records and guides
+└── tests/          # 493 tests across 23 files
+```
+
+## Documentation
+
+- [Architecture Decision Records](docs/adr/)
+- [Visual Debugging Guide](docs/VISUAL_DEBUGGING.md)
+- [Stealth Limitations](docs/STEALTH_LIMITATIONS.md)
+- [Threat Model](docs/THREAT_MODEL.md)
+- [Common Pitfalls](docs/COMMON_PITFALLS.md)
+- [Rate Limiting & Backoff](docs/RATE_LIMITING_BACKOFF.md)
+- [Cookie & Session Resilience](docs/COOKIE_SESSION_RESILIENCE.md)
+
+## Security
+
+See [SECURITY.md](SECURITY.md) for vulnerability reporting and best practices.
+
+## Responsible Use
+
+This framework is designed for legitimate automation use cases such as:
+
+- Testing your own applications and infrastructure
+- Automating workflows on platforms that permit automation
+- Research and security analysis
+- Accessibility testing
+
+**Important:** Many websites (including LinkedIn, Amazon, and others) prohibit automated access in their Terms of Service. Always:
+
+1. Review the target site's Terms of Service and robots.txt
+2. Obtain proper authorization before automating access
+3. Respect rate limits and avoid causing harm to services
+4. Use this tool responsibly and legally
+
+This project is provided as-is under the MIT License. Users are responsible for complying with applicable laws and terms of service.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

agentic_stealth_browser-0.8.0/agentic_stealth_browser.egg-info/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: agentic-stealth-browser
+Version: 0.8.0
+Summary: Production-grade, human-mimicking browser automation framework for autonomous agents. Survives modern anti-bot systems.
+Author-email: Shane W <shanewas@users.noreply.github.com>
+License: MIT
+Project-URL: Homepage, https://github.com/shanewas/agentic-stealth-browser
+Project-URL: Repository, https://github.com/shanewas/agentic-stealth-browser
+Project-URL: Issues, https://github.com/shanewas/agentic-stealth-browser/issues
+Project-URL: Documentation, https://github.com/shanewas/agentic-stealth-browser/tree/master/docs
+Project-URL: Changelog, https://github.com/shanewas/agentic-stealth-browser/blob/master/CHANGELOG.md
+Keywords: stealth,browser,automation,playwright,anti-bot,scraping,agent
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Classifier: Topic :: Software Development :: Testing
+Classifier: Framework :: AsyncIO
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: playwright
+Requires-Dist: aiohttp
+Requires-Dist: cryptography
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Dynamic: license-file
+
+# Agentic Stealth Browser
+
+[![CI](https://github.com/shanewas/agentic-stealth-browser/actions/workflows/ci.yml/badge.svg)](https://github.com/shanewas/agentic-stealth-browser/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![Tests](https://img.shields.io/badge/tests-493%20passing-brightgreen)](tests/)
+
+A Python framework that makes browser automation look human. Built for autonomous agents that need to navigate websites protected by Cloudflare, LinkedIn, Amazon, and other anti-bot systems.
+
+## Why This Exists
+
+Standard browser automation (`page.goto()`, `page.click()`) gets detected instantly. This framework solves that by combining:
+
+- **TLS fingerprint spoofing** — matches real browser TLS handshakes
+- **Human behavior simulation** — natural mouse, typing, scrolling with realistic imperfections
+- **Automatic recovery** — detects blocks (CAPTCHAs, rate limits) and recovers without crashing
+- **Account lifecycle management** — warming, health scoring, cooling off
+
+## Installation
+
+```bash
+pip install agentic-stealth-browser
+playwright install --with-deps chromium
+```
+
+## Quick Start
+
+```python
+from core.agent_browser import AgentBrowser
+import asyncio
+
+async def main():
+    browser = AgentBrowser(session_name="demo")
+    await browser.launch(headless=True)
+
+    # This handles stealth, human behavior, and recovery automatically
+    await browser.safe_goto("https://example.com")
+
+    # Add human-like actions
+    await browser.human.scroll_naturally(400)
+    await browser.human.think(1500, 2800)
+
+    await browser.close()
+
+asyncio.run(main())
+```
+
+## Real-World Example
+
+For protected sites, load real cookies and use a platform preset:
+
+```python
+browser = AgentBrowser(session_name="linkedin")
+await browser.launch(preset="linkedin_2026")
+await browser.load_cookies_from_file("cookies.json")
+await browser.warm_up_before_work(intensity="heavy")
+await browser.safe_goto("https://www.linkedin.com/feed/", platform="linkedin")
+```
+
+The flow: **cookies → warm-up → navigate → recover if blocked → act human**.
+
+## How It Works
+
+```
+AgentBrowser
+├── Stealth      → TLS profiles, canvas/WebGL spoofing, WebRTC isolation
+├── Behavior     → Bézier mouse, natural typing, distraction simulation
+├── Recovery     → Detects blocks → rotates proxy/session → retries
+├── Accounts     → Health scoring, 14-day warming, session checkpointing
+└── Proxy        → Residential proxy with rotation and health tracking
+```
+
+## Key Features
+
+| Feature | What It Does |
+|---|---|
+| **TLS Fingerprinting** | Region-specific profiles (US, Japan, EU, Korea) with JA3/JA4 support |
+| **Human Behavior** | Mouse with wobble, typing with mistakes, variable scrolling, fatigue |
+| **Auto Recovery** | Detects CAPTCHAs, rate limits, blocks — recovers automatically |
+| **Account Warming** | 14-day gradual ramp-up so new accounts don't get flagged |
+| **Session Checkpoints** | Export/import browser state for cross-host migration |
+| **Platform Presets** | Pre-configured profiles for LinkedIn, Amazon, Cloudflare |
+| **MCP Server** | Integration with AI agents via Model Context Protocol |
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|---|---|---|
+| `STEALTH_REGION` | TLS fingerprint region | `japan` |
+| `STEALTH_HEADLESS` | Run browser headless | `true` |
+| `STEALTH_PROXY` | Use residential proxy | `false` |
+
+### Platform Presets
+
+```python
+await browser.launch(preset="linkedin_2026")   # LinkedIn
+await browser.launch(preset="amazon_2026")     # Amazon
+await browser.launch(preset="cloudflare")      # Cloudflare-protected sites
+```
+
+## Project Structure
+
+```
+agentic-stealth-browser/
+├── core/           # AgentBrowser main class
+├── stealth/        # TLS fingerprinting, script injection, caching
+├── behavior/       # Human-like mouse, typing, scrolling, personas
+├── recovery/       # Block detection, anti-block orchestrator
+├── proxy/          # Proxy management and rotation
+├── sessions/       # Session and cookie management
+├── audit/          # Structured logging and audit trails
+├── ai/             # AI hooks and content analysis
+├── production/     # CLI, Docker, rate limiting, metrics
+├── linkedin/       # LinkedIn-specific actions
+├── scraping/       # Safe page scraping utilities
+├── docs/           # Architecture Decision Records and guides
+└── tests/          # 493 tests across 23 files
+```
+
+## Documentation
+
+- [Architecture Decision Records](docs/adr/)
+- [Visual Debugging Guide](docs/VISUAL_DEBUGGING.md)
+- [Stealth Limitations](docs/STEALTH_LIMITATIONS.md)
+- [Threat Model](docs/THREAT_MODEL.md)
+- [Common Pitfalls](docs/COMMON_PITFALLS.md)
+- [Rate Limiting & Backoff](docs/RATE_LIMITING_BACKOFF.md)
+- [Cookie & Session Resilience](docs/COOKIE_SESSION_RESILIENCE.md)
+
+## Security
+
+See [SECURITY.md](SECURITY.md) for vulnerability reporting and best practices.
+
+## Responsible Use
+
+This framework is designed for legitimate automation use cases such as:
+
+- Testing your own applications and infrastructure
+- Automating workflows on platforms that permit automation
+- Research and security analysis
+- Accessibility testing
+
+**Important:** Many websites (including LinkedIn, Amazon, and others) prohibit automated access in their Terms of Service. Always:
+
+1. Review the target site's Terms of Service and robots.txt
+2. Obtain proper authorization before automating access
+3. Respect rate limits and avoid causing harm to services
+4. Use this tool responsibly and legally
+
+This project is provided as-is under the MIT License. Users are responsible for complying with applicable laws and terms of service.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.