chore: contributor onboarding — issue/PR templates, roadmap, README surfacing

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,59 @@
+name: "🐛 Bug report"
+description: Report a defect in Selenium Boot so we can reproduce and fix it.
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to file a bug! A minimal reproduction is the single most
+        helpful thing you can provide — it usually turns a multi-day investigation into a quick fix.
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: A clear description of the bug and what you expected instead.
+      placeholder: "When I run tests with `parallel: methods`, the driver from thread A is reused in thread B…"
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      description: Minimal steps (ideally a tiny test class + the relevant `selenium-boot.yml`).
+      placeholder: |
+        1. selenium-boot.yml with `execution.parallel: methods`, `threadCount: 4`
+        2. Two test classes extending BaseTest that call `getDriver()`
+        3. Run `mvn test`
+        4. See NPE / wrong session in the report
+    validations:
+      required: true
+  - type: input
+    id: sb-version
+    attributes:
+      label: Selenium Boot version
+      placeholder: "3.1.1"
+    validations:
+      required: true
+  - type: input
+    id: java-version
+    attributes:
+      label: Java version
+      placeholder: "17.0.10 (Temurin)"
+    validations:
+      required: true
+  - type: input
+    id: browser
+    attributes:
+      label: Browser + driver version
+      placeholder: "Chrome 126 / chromedriver via Selenium Manager"
+    validations:
+      required: true
+  - type: textarea
+    id: stacktrace
+    attributes:
+      label: Stack trace / logs
+      description: Paste the full stack trace if applicable. This will be rendered as code, no backticks needed.
+      render: shell
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 💬 Questions & feature discussions
+    url: https://github.com/seleniumboot/selenium-boot/discussions
+    about: Ask how-to questions or float an idea before opening a feature request.
+  - name: 📖 Documentation
+    url: https://seleniumboot.github.io/selenium-boot
+    about: Guides, configuration reference, and recipes.
+  - name: 🙌 Good first issues
+    url: https://github.com/seleniumboot/selenium-boot/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22
+    about: New here? These are scoped, self-contained tasks to get started.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,47 @@
+name: "✨ Feature request"
+description: Suggest a feature or improvement that fits the framework's philosophy.
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Selenium Boot is deliberately opinionated — **simplicity is its main feature.** Features that
+        add significant complexity without clear user value may be declined. For open-ended ideas,
+        please start a [Discussion](https://github.com/seleniumboot/selenium-boot/discussions) first.
+  - type: textarea
+    id: problem
+    attributes:
+      label: The problem
+      description: Describe the problem you're solving — not just the solution. What can't you do today?
+      placeholder: "There's no built-in way to assert on a downloaded PDF's contents, only that a file appeared."
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: What would the API / behaviour look like? A code sketch of the ideal usage helps a lot.
+      placeholder: |
+        downloads().waitForFile("*.pdf").assertTextContains("Invoice #123");
+    validations:
+      required: true
+  - type: dropdown
+    id: philosophy
+    attributes:
+      label: Philosophy fit
+      description: How does this fit "zero boilerplate, convention over configuration, single dependency"?
+      options:
+        - "Works with zero config (a sensible default)"
+        - "Opt-in via selenium-boot.yml, off by default"
+        - "Opt-in via annotation / method call"
+        - "Not sure — happy to discuss"
+    validations:
+      required: true
+  - type: checkboxes
+    id: constraints
+    attributes:
+      label: Constraints
+      options:
+        - label: This can be added without a new external dependency (or I've noted why one is needed)
+        - label: This does not break existing `@SeleniumBootApi` public APIs

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,29 @@
+<!-- Thanks for contributing to Selenium Boot! Please fill this out so reviewers have context. -->
+
+## What & why
+
+<!-- What does this PR change, and what problem does it solve? Link the issue it closes. -->
+
+Closes #
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] New feature (opt-in, aligned with the framework philosophy)
+- [ ] Documentation
+- [ ] Internal refactor / test coverage
+
+## Checklist
+
+<!-- From CONTRIBUTING.md — please confirm each item. -->
+
+- [ ] All existing tests pass (`mvn clean verify`)
+- [ ] New behaviour is covered by unit tests
+- [ ] No new external dependencies introduced without prior discussion
+- [ ] Code follows existing conventions (no new frameworks, minimal abstraction)
+- [ ] No breaking changes to `@SeleniumBootApi` public APIs (or a major version bump is justified below)
+- [ ] Docs updated if user-facing behaviour changed (`docs-site/`)
+
+## Notes for reviewers
+
+<!-- Anything reviewers should pay special attention to, trade-offs, follow-ups, etc. -->

README.md

@@ -4,6 +4,8 @@
 
 [![Maven Central](https://img.shields.io/maven-central/v/io.github.seleniumboot/selenium-boot)](https://central.sonatype.com/artifact/io.github.seleniumboot/selenium-boot)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
+[![Good first issues](https://img.shields.io/github/issues/seleniumboot/selenium-boot/good%20first%20issue?label=good%20first%20issues&color=7057ff)](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)**
 
@@ -677,7 +679,16 @@ Licensed under the [Apache License, Version 2.0](LICENSE).
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md).
+Contributions are warmly welcome — Selenium Boot is opinionated, and contributions that align with its philosophy (zero boilerplate, convention over configuration, never hide Selenium) help the whole community.
+
+**New here?** The best place to start:
+
+- 🙌 [**Good first issues**](https://github.com/seleniumboot/selenium-boot/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) — scoped, self-contained tasks
+- 🤝 [**Help wanted**](https://github.com/seleniumboot/selenium-boot/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) — larger pieces we'd love a hand with
+- 🗺️ [**Roadmap**](ROADMAP.md) — where the project is heading and where help fits
+- 💬 [**Discussions**](https://github.com/seleniumboot/selenium-boot/discussions) — questions and feature ideas
+
+Then read [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup, the PR checklist, and the backward-compatibility policy. Bug reports and feature requests both have [issue templates](https://github.com/seleniumboot/selenium-boot/issues/new/choose) to guide you.
 
 ---
 

ROADMAP.md

@@ -4,6 +4,44 @@ This document outlines the planned evolution of Selenium Boot from MVP to a stab
 
 The roadmap is intentionally opinionated and incremental. Each phase focuses on delivering production value before expanding scope.
 
+> **Contributors, start here.** Phases 0–5 below are complete (the framework is past v1.0). The list
+> immediately below is where active work and **open contribution opportunities** live today. The
+> [issue tracker](https://github.com/seleniumboot/selenium-boot/issues) is the source of truth for what's
+> actionable right now — this document is the higher-level picture.
+
+---
+
+## Post-1.0 — current focus & where help is welcome
+
+Items tagged **`good first issue`** or **`help wanted`** are open for contribution. Read
+[CONTRIBUTING.md](CONTRIBUTING.md), comment on the issue to claim it, then open a PR against `master`.
+
+### Documentation & discoverability (current priority)
+
+Most users find a framework by searching, not by browsing GitHub.
+
+- **Per-page SEO descriptions** across all docs pages — *in progress*.
+- **"Why" pages** — Why Selenium Boot? · Why not plain Selenium? · Why not Playwright? · Why accessibility-first locators? · Why WaitEngine? `good first issue`
+- **Recipes section** — task-titled, search-matched guides: upload a file, download a PDF, iframes, Shadow DOM, tables, infinite scroll, OAuth/SSO, alerts, drag & drop, REST + UI. `good first issue`
+- **Migration guides** — from Selenium + TestNG, from WebDriverManager, from Selenide, from Serenity; plus a "coming from Playwright" bridge (familiar vs. different, **not** a replacement claim). `help wanted`
+- **Homepage before/after** — a visual `wait.until(...)` → `click("#login")` comparison component. `enhancement`
+- **SEO hygiene** — verify `sitemap.xml` generation, tighten generic page `<title>`s. `good first issue`
+
+### Framework & ecosystem
+
+- More built-in `WaitEngine` conditions requested by users. `help wanted`
+- Additional first-class browser providers (Edge, Safari) via the existing SPI. `help wanted`
+- **seleniumboot-mcp** — keep MCP codegen output framework-native and accessibility-first as the API evolves. (See the [MCP repo](https://github.com/seleniumboot/selenium-mcp).)
+
+### Ongoing quality
+
+- Grow unit-test coverage for untested code paths. `good first issue`
+- Keep the consumer sample project (`selenium-boot-test`) in step with new features.
+
+> Don't see what you want to work on? Open a
+> [Discussion](https://github.com/seleniumboot/selenium-boot/discussions) — ideas that fit the
+> philosophy are welcome, and we'll turn agreed ones into issues.
+
 ---
 
 ## Guiding Roadmap Principles