diff --git a/CLAUDE.md b/CLAUDE.md
index 8806bf8..7389188 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -77,7 +77,7 @@ All source lives under `src/main/java/com/seleniumboot/`. Key packages:
- **Registry + SPI** — `DriverProviderRegistry`, `PluginRegistry`, `ReportAdapterRegistry` use `ServiceLoader` for extensibility.
- **ThreadLocal driver isolation** — `DriverManager` stores `WebDriver` per thread; safe for parallel TestNG execution.
- **Template Method** — `BaseTest` / `BasePage` define framework-managed lifecycle; users override hook methods.
-- **Convention over configuration** — `SeleniumBootDefaults` provides sensible defaults; `selenium-boot.yml` is optional.
+- **Convention over configuration** — `SeleniumBootDefaults` supplies fallbacks for optional fields, but `selenium-boot.yml` itself is **required**: `ConfigurationLoader` throws if the file is absent, and validates that `execution.mode`, `browser.name` (or `browser.matrix`), `timeouts.explicit` and `timeouts.pageLoad` are all present and positive.
### Public API Contract
diff --git a/README.md b/README.md
index e832913..59e85e2 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,89 @@
[](CONTRIBUTING.md)
[](https://github.com/seleniumboot/selenium-boot/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
-**[Documentation](https://seleniumboot.github.io/selenium-boot) · [Sample Project](https://github.com/seleniumboot/selenium-boot-test) · [Changelog](#project-status)**
+**[Documentation](https://docs.seleniumboot.com) · [Sample Project](https://github.com/seleniumboot/selenium-boot-test) · [Changelog](#project-status)**
+
+---
+
+## Quickstart — a green test in 60 seconds
+
+Three files. Copy them as-is and `mvn test` goes green against a real Chrome.
+
+**Prerequisites:** Java 17+, Maven 3.8+, Chrome installed. No WebDriver binaries — Selenium Manager fetches them.
+
+**1. `pom.xml`**
+
+```xml
+
+ 17
+
+
+
+
+ io.github.seleniumboot
+ selenium-boot
+ 3.2.0
+
+
+
+
+
+
+ org.apache.maven.plugins
+ maven-compiler-plugin
+ 3.11.0
+
+
+ org.apache.maven.plugins
+ maven-surefire-plugin
+ 3.2.5
+
+
+
+```
+
+**2. `selenium-boot.yml`** — project root, next to `pom.xml`. This is the complete minimum; every key below is required.
+
+```yaml
+execution:
+ mode: local
+ baseUrl: https://example.com
+
+browser:
+ name: chrome
+
+timeouts:
+ explicit: 10
+ pageLoad: 30
+```
+
+**3. `src/test/java/SmokeTest.java`**
+
+```java
+import com.seleniumboot.test.BaseTest;
+import org.testng.annotations.Test;
+
+import static org.testng.Assert.assertTrue;
+
+public class SmokeTest extends BaseTest {
+
+ @Test
+ public void opensThePage() {
+ open();
+ assertTrue(getDriver().getTitle().contains("Example Domain"));
+ }
+}
+```
+
+Then:
+
+```bash
+mvn test
+```
+
+No driver setup, no teardown, no waits, no `WebDriver` to manage — `BaseTest` owns the lifecycle. The HTML report lands at `target/selenium-boot-report.html`.
+
+Next: [the full Getting Started walkthrough](#getting-started) adds page objects, parallel execution, and reporting.
---
@@ -30,7 +112,7 @@ It eliminates repetitive boilerplate by providing sensible defaults, a standardi
Selenium Boot is **the Spring Boot of Java test automation** — and that positioning is deliberately layered:
-1. **Opinionated core (primary).** Convention over configuration, zero boilerplate by default. Add one dependency, extend `BaseTest` / `BasePage`, and the framework has already made the sensible decisions — driver lifecycle, waits, retries, reporting, CI wiring. `selenium-boot.yml` is optional; `SeleniumBootDefaults` covers you if you never write it.
+1. **Opinionated core (primary).** Convention over configuration, zero boilerplate by default. Add one dependency, extend `BaseTest` / `BasePage`, and the framework has already made the sensible decisions — driver lifecycle, waits, retries, reporting, CI wiring. `selenium-boot.yml` stays short — a handful of required keys, and `SeleniumBootDefaults` covers the rest.
2. **Never hides Selenium (the constraint).** Unlike heavier abstractions, Selenium Boot never takes the raw `WebDriver` away from you. When the conventions don't fit, drop straight down to `WebDriver` / `By` / `WebElement`. Opinionated without being a cage.
3. **Extensible toolkit (the escape hatch).** An SPI/registry plugin system (`DriverProviderRegistry`, `PluginRegistry`, `ReportAdapterRegistry`) makes it modular for the power users who need it — serving the opinionated core, not replacing it. Most users never touch it.
@@ -90,11 +172,20 @@ Add to your `pom.xml`:
```
-Also add the Surefire plugin so `mvn test` discovers TestNG tests:
+Also pin the compiler plugin and add Surefire so `mvn test` discovers TestNG tests:
```xml
+
+ 17
+
+
+
+ org.apache.maven.plugins
+ maven-compiler-plugin
+ 3.11.0
+
org.apache.maven.plugins
maven-surefire-plugin
@@ -104,6 +195,8 @@ Also add the Surefire plugin so `mvn test` discovers TestNG tests:
```
+> Pinning `maven-compiler-plugin` matters: on Maven 3.8.x and earlier the default compiler level falls back to source/target 5, and the build fails with *"Source option 5 is no longer supported"* on any modern JDK.
+
---
### Step 2: Create the Configuration File
@@ -136,7 +229,7 @@ timeouts:
pageLoad: 30 # seconds
```
-That is the only configuration file needed. All fields have defaults — start with the minimum:
+That is the only configuration file needed, and it is **required** — Selenium Boot fails fast at startup if it is missing. Most fields are optional, but `execution.mode`, `browser.name` (or `browser.matrix`), and both `timeouts` values are validated and must be present:
```yaml
execution:
@@ -145,6 +238,10 @@ execution:
browser:
name: chrome
+
+timeouts:
+ explicit: 10
+ pageLoad: 30
```
---