Canonical approach to supporting AI agent directions

.github/copilot-instructions.md

@@ -0,0 +1 @@
+Always read AGENTS.md before answering

.gitignore

@@ -147,3 +147,25 @@ javascript/selenium-webdriver/.vscode/settings.json
 dotnet-bin
 .metadata/
 .npmrc
+
+# Security
+.env
+.env.local
+
+# AI agent local state (most common)
+.claude/
+.cursor/
+.continue/
+.cline/
+.windsurf/
+.zencoder/
+
+# Common per-tool config/rules files people accidentally add
+.cursorignore
+.cursorrules
+.windsurfrules
+.continuerc.json
+
+# Common generated transcripts
+*_cline_transcript.json
+.copilot-chat-history.json

AGENTS.md

@@ -0,0 +1,78 @@
+<!--
+Guidance for AI agents working in the Selenium monorepo.
+Language-specific details live in respective subdirectories.
+-->
+
+Selenium is a Bazel-built monorepo implementing the W3C WebDriver (and related) protocols,
+shipping multiple language bindings plus Grid and Selenium Manager.
+The repository README is aimed at contributors; end-user docs live elsewhere.
+
+If the user is asking a question (no code change requested), answer directly—no plans/checklists.
+If the user requests a patch, follow the guidance below.
+
+## Execution model (important)
+In many AI-agent environments, Bazel cannot be executed (restricted network/toolchain/browser access).
+Agents MUST:
+- Never claim commands/tests ran unless the user provides output.
+- Provide copy/paste-ready commands for the user to run in an admin terminal.
+- Ask for the exact output needed (errors, failing targets, stack traces), then iterate.
+
+### Terminal run request format:
+Goal: <why this is being run>
+Run: <command>
+
+## Invariants (don’t violate unless explicitly asked)
+- Treat `bazel-*` as generated output.
+- Treat `third_party/` as read-only.
+- Preserve Apache 2.0 headers and NOTICE/LICENSE content.
+- Avoid repo-wide refactors/formatting; prefer small, reversible diffs.
+
+## Repo layout
+Bindings:
+- Java: `java/` (see `java/AGENTS.md`)
+- Python: `py/` (see `py/AGENTS.md`)
+- Ruby: `rb/` (see `rb/AGENTS.md`)
+- JavaScript: `javascript/selenium-webdriver/` (see `javascript/selenium-webdriver/AGENTS.md`)
+- .NET: `dotnet/` (see `dotnet/AGENTS.md`)
+Other components:
+- `rust/` (Selenium Manager, see `rust/AGENTS.md`)
+- `common/` (shared build/test wiring; changes can affect multiple areas)
+- `common/src/` (test HTML fixtures; changes can break tests)
+- `javascript/atoms/` (shared JS atoms; very high blast radius)
+- `scripts/`, `rake_tasks/`, `.github/`, `Rakefile` (tooling/build; high risk)
+
+## Toolchain
+- Expect Bazelisk + JDK 17+ (JAVA_HOME should point to a JDK)
+- Prefer `./go <task>` if applicable (Rake tasks execute bazel & scripts, used by CI)
+- Use targeted Bazel commands. Use `bazel query ...` to locate labels before build/test
+
+## Cross-binding consistency checks
+When changing user-visible behavior, compare with at least one other binding:
+- `rg <term> java/ py/ rb/ dotnet/ javascript/selenium-webdriver/`
+
+If behavior is shared/low-level (protocol, serialization, “remote”/transport), expect follow-up parity work or file an issue explicitly.
+
+## Testing
+Use each binding’s testing guide (see `<dir>/TESTING.md`).
+Consider these flags when testing locally:
+- `--test_size_filters=small` (unit tests only)
+- `--test_output=all|streamed` (displays console output to debug)
+- `--cache_test_results=no` (force re-running all tests)
+- `--test_env FOO=bar` (if tests need environment variables)
+
+## Dependencies & lockfiles
+- Don’t hand-edit lockfiles (`pnpm-lock.yaml`, `multitool.lock.json`, `Cargo.Bazel.lock`, etc).
+- Use the binding’s documented update/repin flow (see `<dir>/AGENTS.md`).
+
+## High risk changes (request verification before modifying unless explicitly instructed)
+- Everything referenced above as high risk
+- WebDriver/BiDi semantics, capability parsing, wire-level behavior
+- Dependency updates / `MODULE.bazel` / repin flows
+- Grid routing/distributor/queue logic
+
+## After making code changes
+- Call out any high risk areas touched
+- List exact commands the user ran (or needs to run) + outcomes
+- Note cross-binding impact and any follow-up issues needed
+- Recommend formatting/lint if applicable (e.g., `./scripts/format.sh`)
+- 

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

README.md

@@ -278,8 +278,8 @@ If you want to use [RubyMine](https://www.jetbrains.com/ruby/) for development,
 you can configure it use Bazel artifacts:
 
 1. Open `rb/` as a main project directory.
-2. Run `bundle exec rake update` as necessary to create up-to-date artifacts. If this does not work, run `./go rb:update` from the `selenium` (parent) directory.
-3. In <kbd>Settings / Languages & Frameworks / Ruby SDK and Gems</kbd> add new <kbd>Interpreter</kbd> pointing to `../bazel-selenium/external/rules_ruby_dist/dist/bin/ruby`.
+2. Run `bundle exec rake update` as necessary to create up-to-date artifacts. If this does not work, run `./go rb:local_dev` from the `selenium` (parent) directory.
+3. In <kbd>Settings / Languages & Frameworks / Ruby SDK and Gems</kbd> add new <kbd>Interpreter</kbd> pointing to `../bazel-selenium/external/rules_ruby++ruby+ruby/dist/bin/ruby`.
 4. You should now be able to run and debug any spec. It uses Chrome by default, but you can alter it using environment variables specified in [Ruby Testing](#ruby-2) section below.
 
 ### Rust

dotnet/AGENTS.md

@@ -0,0 +1,15 @@
+<!-- Guidance for AI agents working in Selenium .NET Bindings -->
+
+## Code location
+- Core: `dotnet/src/webdriver/`
+- Support: `dotnet/src/support/`
+- Tests: `dotnet/test/common/`
+
+## Common commands
+- Build: `bazel build //dotnet/...`
+
+## Dependency management
+???
+
+## Testing
+See `dotnet/TESTING.md`

java/AGENTS.md

@@ -0,0 +1,15 @@
+<!-- Guidance for AI agents working in Selenium Java Bindings and Grid. -->
+
+## Code location
+- Java Bindings: `java/src/`, `java/test/`
+- Grid Server: `java/src/org/openqa/selenium/grid/`, `java/test/org/openqa/selenium/grid`
+
+## Common commands
+- Build: `bazel build //java/...`
+
+## Dependency management
+- Dependencies live in `MODULE.bazel`; after edits:
+  - `RULES_JVM_EXTERNAL_REPIN=1 bazel run @maven//:pin`
+
+## Testing
+See `java/TESTING.md`.

javascript/selenium-webdriver/AGENTS.md

@@ -0,0 +1,15 @@
+<!-- Guidance for AI agents working in Selenium JavaScript Bindings -->
+
+## Code location
+
+-`javascript/selenium-webdriver/`
+
+## Common commands
+
+- Build: `bazel build //javascript/...`
+
+## Dependency management
+
+## Testing
+
+See `javascript/selenium-webdriver/TESTING.md`.

py/AGENTS.md

@@ -0,0 +1,15 @@
+<!-- Guidance for AI agents working in Selenium Python Bindings -->
+
+## Code location
+- Package: `py/selenium/`
+- Remote/transport: `py/selenium/webdriver/remote/`
+
+## Common commands
+- Build: `bazel build //py/...`
+
+## Dependency management
+- Dev dependencies must be updated in `py/requirements.txt` and then run `scripts/update_py_dependencies.sh`
+- Package dependencies must be updated in `py/pyproject.toml` and `py/BUILD.bazel`
+
+## Testing
+See `py/TESTING.md`

rb/AGENTS.md

@@ -0,0 +1,16 @@
+<!-- Guidance for AI agents working in Selenium Ruby Bindings -->
+
+## Code location
+- Library: `rb/lib/selenium/webdriver`
+- Tests: `rb/spec/unit/selenium/webdriver` and `rb/spec/integration/selenium/webdriver` 
+- Bazel will build and use the version of Ruby specified in `rb/.ruby-version`
+
+## Common commands
+- `bazel build //rb/...`
+
+## Dependency management
+- Dependencies must be updated in `rb/selenium-webdriver.gemspec`
+- Then run `bazel build @bundle//:bundle`
+
+## Testing
+See `rb/TESTING.md`

rust/AGENTS.md

@@ -0,0 +1,13 @@
+<!-- Guidance for AI agents working in Selenium Manager code -->
+
+## Code location
+- `rust/src` and `rust/tests`
+
+## Common commands
+
+## Dependency management
+Keep `Cargo.Bazel.lock` synchronized with `Cargo.lock`:
+- `CARGO_BAZEL_REPIN=true bazel sync --only=crates`
+
+## Testing
+See `rust/TESTING.md`