Add AI agents documentation page

[AutomatedTester]

Description

Adds a new documentation page, Documentation → AI Agents (/documentation/ai_agents/), on getting AI coding agents and LLMs to write Selenium code that is current, correct, and not flaky. It sits in the sidebar between IDE and Test Practices (weight 11).

The page is structured as:

1. Give the agent the current documentation — llms.txt first, then this site, the examples/ directory, the per-binding API docs, and the changelogs, with the instruction that matters most: if an API isn't in the current docs, it doesn't exist.
2. Write the project rules down — a paste-ready block for AGENTS.md / CLAUDE.md / rules files, followed by a tabpane of the binding-specific removals models get wrong most often (Java Duration and findElementBy*, Python find_element_by_* / executable_path / desired_capabilities, C# AddAdditionalCapability, Ruby webdrivers, JavaScript unawaited promises, Kotlin).
3. What to correct, and why — the reasoning behind each rule: Selenium Manager vs third-party driver managers, Options vs DesiredCapabilities, explicit waits vs sleeping (including the second-order failure where an agent "fixes" a flaky test by raising a timeout), locator durability, BiDi vs CDP, and Grid 4 subcommands vs Grid 3 -role hub.
4. Let the agent drive a real browser — the throwaway-script approach first, since it needs no new tooling and exercises the same stack the real test will; then MCP servers as a category.
5. Let the agent read the failure — pointing agents at our common errors pages and at logging, rather than at "the test failed".
6. A workflow that works and Next steps.

Motivation and Context

A large share of Selenium code is now written with an agent's help, and it is wrong in a consistent, predictable set of ways. The cause is the training data: models learned Selenium from more than a decade of blog posts, forum answers, and tutorials describing Selenium 2 and 3. Those APIs were removed years ago, and the most-repeated patterns in that material — sleeping to wait for the page, downloading driver binaries by hand, copying XPath out of DevTools — were never good practice even when they compiled.

We already document all of the correct answers, but they are spread across the upgrade guide, the waits page, Selenium Manager, locators, and BiDi. This page collects what an agent specifically gets wrong into one place, and gives users something they can paste into a rules file today.

On llms.txt

The second commit links llms.txt as the first entry in the documentation table and adds it to the sample rules block, along with a rule against using the legacy and CDP pages as a basis for new code. The page explains that the index is curated rather than exhaustive, and why those two sets of pages are deliberately excluded from it.

No change to layouts/index.llms.txt was needed: the curated index picks up new pages under /documentation automatically, so the new page is already listed under "Getting started" in the generated output, and the template's drift check reports nothing.

Notes for reviewers

A couple of judgment calls worth a second opinion:

• No MCP server is named. Several community Selenium MCP servers exist and none is official, so the page describes the category and says to evaluate them as you would any dependency, rather than linking one from selenium.dev. Happy to name one if the project wants to.
• Version-specific claims. The sample rules block pins 4.49.0 to match examples/. The per-binding removal claims are worth an eye — particularly Ruby's :desired_capabilities and Python's options.headless.
• English only for now, per the translation process in the style guide.

Types of changes

• Change to the site (I have double-checked the Netlify deployment, and my changes look good)
• Code example added (and I also added the example to all translated languages)
• Improved translation
• Added new translation (and I also added a notice to each document missing translation)

Checklist

• I have read the contributing document.
• I have used hugo to render the site/docs locally and I am sure it works.

Verified locally with a full hugo --minify build — clean, no warnings, every cross-reference resolves and the llms.txt drift check is silent — and visually in hugo server: the tabpane, the table, the cross-links, and the sidebar ordering all render correctly.

[netlify]

✅ Deploy Preview for selenium-dev ready!

Name	Link
🔨 Latest commit	68d5b3c
🔍 Latest deploy log	https://app.netlify.com/projects/selenium-dev/deploys/6aba43545717ec00084ef910
😎 Deploy Preview	https://deploy-preview-2846--selenium-dev.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[diemol]

Shouldn't this be a blog post? Maybe I don't see it the same way.

[AutomatedTester]

Fair question, and I went back and forth on it.

The main argument for docs is that the whole point of this page is to be found by an agent reading our documentation. llms.txt only lists the blog under Optional — "release announcements and technical deep dives" — so as a post it is much less likely to end up in front of the thing it is trying to correct. As a docs page the curated index picks it up automatically; it is already listed under "Getting started" in the generated output.

The other pull is maintenance. This is probably the most time-sensitive content on the site, because the specific things models get wrong will shift as they improve. Docs get reviewed, translated and updated as part of the normal process. A post dated 2026 stays frozen and keeps ranking.

And a fair amount of the page is really just routing — waits, Selenium Manager, locators, BiDi, the upgrade guide. It is mostly a navigation layer over things we already document, which feels like a docs job.

That said, I don't think it has to be either/or, and the blog is much better at attention than the docs are. Happy to write a post announcing it and pointing at the page — blog for reach, docs for durability. Want me to do that as a follow-up?

[AutomatedTester]

Also, I got the idea from wdio, they are adding this as a separate page.