From 71e411640b6d5a5e93c7fdb9ca0cf823d748f7a5 Mon Sep 17 00:00:00 2001
From: Ross Lawley <ross.lawley@gmail.com>
Date: Thu, 7 May 2026 11:00:31 +0100
Subject: [PATCH 1/2] =?UTF-8?q?Add=20AI=20agent=20instructions=20using=20t?=
 =?UTF-8?q?he=20AGENTS.md=20open=20standard=20Adds=20structured=20AI=20age?=
 =?UTF-8?q?nt=20documentation=20across=20the=20MongoDB=20Java=20Driver=20u?=
 =?UTF-8?q?sing=20the=20AGENTS.md=20convention=20=E2=80=94=20an=20open=20s?=
 =?UTF-8?q?tandard=20for=20providing=20codebase=20context=20to=20AI=20codi?=
 =?UTF-8?q?ng=20agents.?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Root AGENTS.md with build commands, style rules, testing policy, API
  design guidelines, safety-critical code boundaries, and dependency rules
- Per-module AGENTS.md files (bson, driver-core, driver-sync, etc.) with
  module-specific packages, dependencies, and patterns
- CLAUDE.md files that reference AGENTS.md (for Claude Code compatibility)
- `.agents/references/` for passive knowledge (contextually loaded):
  project-guide, style-reference, api-design, testing-guide, spec-tests
- `.agents/skills/` for procedural workflows:
  evergreen (CI validation), sync-agents-docs (documentation sync checklist)
- `scripts/symlink-claude-md.sh` for maintaining CLAUDE.md symlinks

- References over skills for static knowledge: references are loaded
  contextually based on description relevance rather than requiring
  explicit invocation. This avoids bloating every conversation with all
  documentation while still surfacing it when needed.
- Flat file layout for references (.agents/references/api-design.md)
  rather than directory-per-reference (.agents/references/api-design/REFERENCE.md):
  simpler structure; supplementary files use name-prefixing
  (e.g. testing-guide-examples.md) instead of subdirectories.
- Markdown links (See [name](path)) rather than @ syntax for referencing
  from AGENTS.md: @ auto-includes file contents on every load, which
  defeats contextual loading. Links let agents follow them on demand.
- Skills retained only for procedural workflows that have tool constraints
  (allowed-tools) or explicit trigger conditions (disable-model-invocation),
  not for passive knowledge lookup.

JAVA-6143
---
 .agents/references/api-design.md             |  31 ++++++
 .agents/references/project-guide.md          |  63 +++++++++++
 .agents/references/spec-tests.md             |  40 +++++++
 .agents/references/style-reference.md        |  55 ++++++++++
 .agents/references/testing-guide-examples.md |  92 ++++++++++++++++
 .agents/references/testing-guide.md          |  69 ++++++++++++
 .agents/skills/evergreen/SKILL.md            |  36 +++++++
 .agents/skills/sync-agents-docs/SKILL.md     |  27 +++++
 .claude/skills                               |   1 +
 .gitignore                                   |   6 ++
 AGENTS.md                                    | 104 ++++++++++++++++++
 CLAUDE.md                                    |   1 +
 README.md                                    |  12 +++
 bson-kotlin/AGENTS.md                        |  18 ++++
 bson-kotlin/CLAUDE.md                        |   1 +
 bson-kotlinx/AGENTS.md                       |  19 ++++
 bson-kotlinx/CLAUDE.md                       |   1 +
 bson-record-codec/AGENTS.md                  |  21 ++++
 bson-record-codec/CLAUDE.md                  |   1 +
 bson-scala/AGENTS.md                         |  24 +++++
 bson-scala/CLAUDE.md                         |   1 +
 bson/AGENTS.md                               |  24 +++++
 bson/CLAUDE.md                               |   1 +
 buildSrc/AGENTS.md                           |  54 ++++++++++
 buildSrc/CLAUDE.md                           |   1 +
 driver-benchmarks/AGENTS.md                  |  21 ++++
 driver-benchmarks/CLAUDE.md                  |   1 +
 driver-core/AGENTS.md                        |  31 ++++++
 driver-core/CLAUDE.md                        |   1 +
 driver-kotlin-coroutine/AGENTS.md            |  19 ++++
 driver-kotlin-coroutine/CLAUDE.md            |   1 +
 driver-kotlin-extensions/AGENTS.md           |  20 ++++
 driver-kotlin-extensions/CLAUDE.md           |   1 +
 driver-kotlin-sync/AGENTS.md                 |  19 ++++
 driver-kotlin-sync/CLAUDE.md                 |   1 +
 driver-legacy/AGENTS.md                      |  22 ++++
 driver-legacy/CLAUDE.md                      |   1 +
 driver-reactive-streams/AGENTS.md            |  24 +++++
 driver-reactive-streams/CLAUDE.md            |   1 +
 driver-scala/AGENTS.md                       |  25 +++++
 driver-scala/CLAUDE.md                       |   1 +
 driver-sync/AGENTS.md                        |  24 +++++
 driver-sync/CLAUDE.md                        |   1 +
 gradle/AGENTS.md                             |  20 ++++
 gradle/CLAUDE.md                             |   1 +
 mongodb-crypt/AGENTS.md                      |  26 +++++
 mongodb-crypt/CLAUDE.md                      |   1 +
 scripts/symlink-claude-md.sh                 | 105 +++++++++++++++++++
 testing/AGENTS.md                            |  11 ++
 testing/CLAUDE.md                            |   1 +
 50 files changed, 1082 insertions(+)
 create mode 100644 .agents/references/api-design.md
 create mode 100644 .agents/references/project-guide.md
 create mode 100644 .agents/references/spec-tests.md
 create mode 100644 .agents/references/style-reference.md
 create mode 100644 .agents/references/testing-guide-examples.md
 create mode 100644 .agents/references/testing-guide.md
 create mode 100644 .agents/skills/evergreen/SKILL.md
 create mode 100644 .agents/skills/sync-agents-docs/SKILL.md
 create mode 120000 .claude/skills
 create mode 100644 AGENTS.md
 create mode 100644 CLAUDE.md
 create mode 100644 bson-kotlin/AGENTS.md
 create mode 100644 bson-kotlin/CLAUDE.md
 create mode 100644 bson-kotlinx/AGENTS.md
 create mode 100644 bson-kotlinx/CLAUDE.md
 create mode 100644 bson-record-codec/AGENTS.md
 create mode 100644 bson-record-codec/CLAUDE.md
 create mode 100644 bson-scala/AGENTS.md
 create mode 100644 bson-scala/CLAUDE.md
 create mode 100644 bson/AGENTS.md
 create mode 100644 bson/CLAUDE.md
 create mode 100644 buildSrc/AGENTS.md
 create mode 100644 buildSrc/CLAUDE.md
 create mode 100644 driver-benchmarks/AGENTS.md
 create mode 100644 driver-benchmarks/CLAUDE.md
 create mode 100644 driver-core/AGENTS.md
 create mode 100644 driver-core/CLAUDE.md
 create mode 100644 driver-kotlin-coroutine/AGENTS.md
 create mode 100644 driver-kotlin-coroutine/CLAUDE.md
 create mode 100644 driver-kotlin-extensions/AGENTS.md
 create mode 100644 driver-kotlin-extensions/CLAUDE.md
 create mode 100644 driver-kotlin-sync/AGENTS.md
 create mode 100644 driver-kotlin-sync/CLAUDE.md
 create mode 100644 driver-legacy/AGENTS.md
 create mode 100644 driver-legacy/CLAUDE.md
 create mode 100644 driver-reactive-streams/AGENTS.md
 create mode 100644 driver-reactive-streams/CLAUDE.md
 create mode 100644 driver-scala/AGENTS.md
 create mode 100644 driver-scala/CLAUDE.md
 create mode 100644 driver-sync/AGENTS.md
 create mode 100644 driver-sync/CLAUDE.md
 create mode 100644 gradle/AGENTS.md
 create mode 100644 gradle/CLAUDE.md
 create mode 100644 mongodb-crypt/AGENTS.md
 create mode 100644 mongodb-crypt/CLAUDE.md
 create mode 100755 scripts/symlink-claude-md.sh
 create mode 100644 testing/AGENTS.md
 create mode 100644 testing/CLAUDE.md

diff --git a/.agents/references/api-design.md b/.agents/references/api-design.md
new file mode 100644
index 00000000000..23e89ebe457
--- /dev/null
+++ b/.agents/references/api-design.md
@@ -0,0 +1,31 @@
+---
+name: api-design
+description: API stability annotations, design principles, and patterns for the MongoDB Java Driver. Use when adding or modifying public API surface — new classes, methods, interfaces, or changing method signatures.
+---
+# API Design
+
+## API Stability Annotations
+
+- `@Alpha` — Early development, may be removed.
+  Not recommended for production use.
+- `@Beta` — Subject to change or removal.
+  It's not recommended for Libraries to depend on these APIs.
+- `@Evolving` — May add abstract methods in future releases.
+  Safe to use, but implementing/extending bears upgrade risk.
+- `@Sealed` — Must not be extended or implemented by consumers.
+  Safe to use, but not to subclass.
+- `@Deprecated` — Supported until next major release but should be migrated away from.
+
+## Design Principles
+
+- **Deep modules:** Prefer simple interfaces with powerful implementations over shallow wrappers.
+- **Information hiding:** Bury complexity behind simple interfaces.
+- **Pull complexity downward:** Make the implementer work harder so callers work less.
+- **General-purpose over special-case:** Fewer flexible methods over many specialized ones.
+- **Define errors out of existence:** Design APIs so errors cannot happen rather than detecting and handling them.
+
+## Key Patterns
+
+- Static factory methods: `Filters.eq()`, `Updates.set()`, `Aggregates.match()`
+- Fluent builders: `MongoClientSettings.builder()` is the primary entry point
+- Abstract core with pluggable transports
diff --git a/.agents/references/project-guide.md b/.agents/references/project-guide.md
new file mode 100644
index 00000000000..a068414426e
--- /dev/null
+++ b/.agents/references/project-guide.md
@@ -0,0 +1,63 @@
+---
+name: project-guide
+description: Project structure, dependency graph, and guide for finding the right project to work in. Use when starting a task and unsure which project owns the relevant code, or when you need to understand cross-project dependencies.
+---
+# Project Guide
+
+## Project Structure
+
+| Project | Purpose |
+| --- | --- |
+| `bson` | BSON library (core serialization) |
+| `bson-kotlin` | Kotlin BSON extensions |
+| `bson-kotlinx` | Kotlin serialization BSON codec |
+| `bson-record-codec` | Java record codec support |
+| `bson-scala` | Scala BSON extensions |
+| `driver-core` | Core driver internals (connections, protocol, operations) |
+| `driver-sync` | Synchronous Java driver |
+| `driver-legacy` | Legacy MongoDB Java driver API |
+| `driver-reactive-streams` | Reactive Streams driver |
+| `driver-kotlin-coroutine` | Kotlin Coroutines driver |
+| `driver-kotlin-extensions` | Kotlin driver extensions |
+| `driver-kotlin-sync` | Kotlin synchronous driver |
+| `driver-scala` | Scala driver |
+| `mongodb-crypt` | Client-side field-level encryption |
+| `bom` | Bill of Materials for dependency management |
+| `testing` | Shared test resources and MongoDB specifications |
+| `buildSrc` | Gradle convention plugins and build infrastructure |
+| `driver-benchmarks` | JMH and custom performance benchmarks (not published) |
+| `driver-lambda` | AWS Lambda test application (not published) |
+| `graalvm-native-image-app` | GraalVM Native Image compatibility testing (not published) |
+
+## Dependency Graph (simplified)
+
+```
+bson
+ ├── bson-kotlin
+ ├── bson-kotlinx
+ ├── bson-record-codec
+ ├── bson-scala
+ └── driver-core
+      ├── driver-sync
+      │    ├── driver-legacy
+      │    ├── driver-kotlin-sync
+      │    └── driver-lambda
+      ├── driver-reactive-streams
+      │    ├── driver-kotlin-coroutine
+      │    └── driver-scala
+      └── driver-kotlin-extensions
+```
+
+## Finding the Right Module
+
+- **BSON serialization/codecs:** `bson` (or `bson-kotlin`/`bson-kotlinx`/`bson-scala` for language-specific)
+- **Query builders, filters, aggregates:** `driver-core` (`com.mongodb.client.model`)
+- **Sync Java API:** `driver-sync`
+- **Reactive API:** `driver-reactive-streams`
+- **Kotlin coroutines:** `driver-kotlin-coroutine`
+- **Kotlin DSL builders:** `driver-kotlin-extensions`
+- **Scala driver:** `driver-scala`
+- **Connection, protocol, auth internals:** `driver-core` (`com.mongodb.internal.*`)
+- **Build plugins, formatting, test infra:** `buildSrc`
+
+Each module has its own `AGENTS.md` with module-specific packages, patterns, and notes.
diff --git a/.agents/references/spec-tests.md b/.agents/references/spec-tests.md
new file mode 100644
index 00000000000..5ba9041cfbc
--- /dev/null
+++ b/.agents/references/spec-tests.md
@@ -0,0 +1,40 @@
+---
+name: spec-tests
+description: How to work with MongoDB specification tests — structure, rules, and adding new spec test support. Use when implementing or modifying behavior defined by the MongoDB Driver Specifications.
+---
+# MongoDB Specification Tests
+
+## Overview
+
+The driver implements the [MongoDB Driver Specifications](https://github.com/mongodb/specifications).
+Specification test data files live in `testing/resources/specifications/` — a git submodule.
+
+## Rules
+
+- **Do not modify spec test data files** (JSON/YAML in `testing/resources/specifications/`) — managed upstream
+- Test runners (Java code) may be modified to fix bugs or add support for new spec tests
+- Update the submodule via `git submodule update`
+
+## Structure
+
+Spec test data is organized by specification area:
+
+- CRUD, SDAM, auth, CSFLE, retryable operations, and more
+- Each spec area has JSON/YAML test data files defining inputs and expected outputs
+- Driver test runners parse these files and execute against the driver
+
+## Test Data Location
+
+```
+testing/
+  resources/
+    specifications/    # Git submodule — do not edit directly
+    logback-test.xml   # Shared logback configuration for tests
+```
+
+## Adding Spec Test Support
+
+1. Check `testing/resources/specifications/` for the relevant spec test data
+2. Find existing test runners in the module (look for `*SpecificationTest*` or similar)
+3. Extend existing patterns — each module handles spec tests slightly differently
+4. Ensure tests run with `./gradlew check` or the module’s test task
diff --git a/.agents/references/style-reference.md b/.agents/references/style-reference.md
new file mode 100644
index 00000000000..fa9adfe85f2
--- /dev/null
+++ b/.agents/references/style-reference.md
@@ -0,0 +1,55 @@
+---
+name: style-reference
+description: Detailed code style rules for Java, Kotlin, Scala, and Groovy in the MongoDB Java Driver. Use when you need specific formatting rules beyond the basics in root AGENTS.md — e.g., line length, import ordering, brace style.
+---
+# Style Reference
+
+## Java Style Rules
+
+- **Max line length:** 140 characters
+- **Indentation:** 4 spaces (no tabs)
+- **Line endings:** LF (Unix)
+- **Charset:** UTF-8
+- **Star imports:** Prohibited (AvoidStarImport)
+- **Final parameters:** Required (FinalParameters checkstyle rule)
+- **Braces:** Required for all control structures (NeedBraces)
+- **Else placement:** `} else {` on the same line (Palantir Java Format default)
+- **Copyright header:** Every Java / Kotlin / Scala file must contain `Copyright 2008-present MongoDB, Inc.`
+- **Formatter:** Palantir Java Format
+
+## Kotlin Style Rules
+
+- **Formatter:** ktfmt dropbox style, max width 120
+- **Static analysis:** detekt
+
+## Scala Style Rules
+
+- **Formatter:** scalafmt
+- **Supported versions:** 2.11, 2.12, 2.13, 3 (default: 2.13)
+
+## Groovy Style Rules
+
+- **Static analysis:** CodeNarc
+
+## Javadoc / KDoc / Scaladoc
+
+- All public classes and interfaces **must** have class-level Javadoc (enforced by checkstyle)
+- Public methods should have Javadoc with `@param`, `@return`, and `@since` tags
+- Use `@since X.Y` to indicate the version when the API was introduced
+- Use `@mongodb.driver.manual <path> <label>` for MongoDB manual links
+- Use `@mongodb.server.release <version>` to indicate the minimum server version required
+- Scala modules use Scaladoc — follow Scaladoc conventions (`@param`, `@return`, `@since`, `@see`)
+- Internal packages (`com.mongodb.internal.*`, `org.bson.internal.*`) are excluded from doc generation
+- Run `./gradlew doc` to validate Javadoc/KDoc/Scaladoc builds cleanly
+
+## Prohibited Patterns
+
+- `System.out.println` / `System.err.println` — Use SLF4J logging
+- `e.printStackTrace()` — Use proper logging/error handling
+
+## Formatting Commands
+
+```bash
+./gradlew spotlessApply    # Auto-fix all formatting
+./gradlew spotlessCheck    # Check without modifying
+```
diff --git a/.agents/references/testing-guide-examples.md b/.agents/references/testing-guide-examples.md
new file mode 100644
index 00000000000..96f24b141c3
--- /dev/null
+++ b/.agents/references/testing-guide-examples.md
@@ -0,0 +1,92 @@
+---
+name: testing-guide-examples
+description: Test skeleton templates for Java (JUnit 5), Scala (ScalaTest), and Kotlin (kotlin.test) in the MongoDB Java Driver. Use when writing new tests to match structural conventions.
+---
+# Test Skeletons
+
+Match these structural conventions when writing new tests.
+
+## Java — JUnit 5
+
+```java
+public class FeatureUnderTestTest extends OperationTest {
+
+    private ResourceType resource;
+
+    @BeforeEach
+    void setup() {
+        // Insert test data, acquire resources
+    }
+
+    @AfterEach
+    void cleanup() {
+        // Release resources to prevent leaks
+    }
+
+    @Test
+    @DisplayName("should do expected behavior")
+    void shouldDoExpectedBehavior() {
+        // given
+        // when
+        // then
+    }
+
+    @ParameterizedTest(name = "{index} => input={0}, expected={1}")
+    @MethodSource
+    @DisplayName("should handle varied inputs")
+    void shouldHandleVariedInputs(final int input, final int expected) {
+        assertEquals(expected, methodUnderTest(input));
+    }
+
+    private static Stream<Arguments> shouldHandleVariedInputs() {
+        return Stream.of(arguments(1, 1), arguments(2, 4));
+    }
+}
+```
+
+## Scala — ScalaTest with Mockito
+
+```scala
+class FeatureUnderTestSpec extends BaseSpec with MockitoSugar {
+
+  val wrapped = mock[JWrappedType]
+  val underTest = new ScalaWrapper(wrapped)
+
+  "ScalaWrapper" should "have the same methods as the wrapped type" in {
+    val wrappedMethods = classOf[JWrappedType].getMethods.map(_.getName).toSet
+    val localMethods = classOf[ScalaWrapper].getMethods.map(_.getName)
+    // Assert parity
+  }
+
+  it should "delegate to underlying method" in {
+    underTest.someMethod("arg")
+    verify(wrapped).someMethod("arg")
+  }
+}
+```
+
+## Kotlin — kotlin.test with Mockito-Kotlin
+
+```kotlin
+class FeatureUnderTestTest {
+
+    companion object {
+        @Mock internal val wrapped: com.mongodb.client.MongoCollection<MyType> = mock()
+        lateinit var collection: MongoCollection<MyType>
+
+        @JvmStatic
+        @BeforeAll
+        internal fun setUpMocks() {
+            collection = MongoCollection(wrapped)
+            whenever(wrapped.namespace).doReturn(MongoNamespace("db", "coll"))
+        }
+    }
+
+    @Test
+    fun shouldProduceCorrectBson() {
+        assertEquals(BsonDocument.parse("""{"expected": 1}"""), resultUnderTest.toBsonDocument())
+    }
+
+    data class MyType(val id: String, val name: String)
+}
+```
diff --git a/.agents/references/testing-guide.md b/.agents/references/testing-guide.md
new file mode 100644
index 00000000000..a7b5c128a2c
--- /dev/null
+++ b/.agents/references/testing-guide.md
@@ -0,0 +1,69 @@
+---
+name: testing-guide
+description: Testing frameworks, conventions, and commands for the MongoDB Java Driver. Use when writing or running tests — covers framework selection per module, test naming conventions, integration test setup, and how to run specific test subsets.
+---
+# Testing Guide
+
+## Frameworks
+
+| Framework | Usage | Notes |
+| --- | --- | --- |
+| JUnit 5 (Jupiter) | Primary unit test framework | All new tests |
+| Spock (Groovy) | Legacy tests | Do not add new Spock tests |
+| Mockito | Mocking | Use `mockito-junit-jupiter` integration |
+| ScalaTest | Scala module testing | FlatSpec + ShouldMatchers |
+| Project Reactor | Reactive test utilities | `driver-reactive-streams` tests |
+
+## Assertions
+
+- **JUnit Jupiter Assertions** (`org.junit.jupiter.api.Assertions`) is the standard for all new tests
+- Hamcrest matchers appear in older tests but should not be used in new code
+- AssertJ is in the dependency catalog but is not used — do not introduce it
+- Spock tests use Spock's built-in `expect:`/`then:` assertions (no external assertion library)
+
+## Writing Tests
+
+- Every code change must include tests
+- Extend existing test patterns in the module you are modifying
+- Unit tests must not require a running MongoDB instance
+- Descriptive method names: `shouldReturnEmptyListWhenNoDocumentsMatch()` not `test1()`
+- Use `@DisplayName` for human-readable names
+- Clean up test data in `@AfterEach` / `cleanup()` to prevent pollution
+
+## Running Tests
+
+```bash
+# All tests (unit + integration)
+./gradlew check
+
+# Single module
+./gradlew :driver-core:test
+
+# Integration tests (requires MongoDB)
+./gradlew integrationTest -Dorg.mongodb.test.uri="mongodb://localhost:27017"
+
+# Specific test class
+./gradlew :driver-core:test --tests "com.mongodb.internal.operation.FindOperationTest"
+
+# Alternative JDK
+./gradlew test -PjavaVersion=11
+
+# Scala tests (all versions)
+./gradlew scalaCheck
+```
+
+## Module-Specific Notes
+
+- **driver-core:** Largest test suite — JUnit 5 + Spock + Mockito
+- **driver-sync:** JUnit 5 + Spock (heavy Spock usage, but don’t add new)
+- **driver-reactive-streams:** JUnit 5 + Spock + Project Reactor
+- **bson-scala / driver-scala:** ScalaTest, test per Scala version
+- **Kotlin modules:** JUnit 5 + mockito-kotlin
+
+## Integration Tests
+
+- Require a running MongoDB instance
+- Set connection URI: `-Dorg.mongodb.test.uri="mongodb://localhost:27017"`
+- Integration test source set configured via `conventions/testing-integration.gradle.kts`
+
+See [testing-guide-examples.md](testing-guide-examples.md) for Java, Scala, and Kotlin test skeletons.
diff --git a/.agents/skills/evergreen/SKILL.md b/.agents/skills/evergreen/SKILL.md
new file mode 100644
index 00000000000..37b73a03f78
--- /dev/null
+++ b/.agents/skills/evergreen/SKILL.md
@@ -0,0 +1,36 @@
+---
+name: evergreen
+description: Evergreen CI infrastructure, configuration validation. Use when modifying .evergreen/ config, preparing to submit changes or understanding the Evergreen test matrix.
+disable-model-invocation: true
+allowed-tools: Bash(evergreen *)
+---
+# Evergreen
+
+## Evergreen (MongoDB Internal CI)
+
+Primary CI runs on MongoDB’s Evergreen system.
+Configuration lives in `.evergreen/`.
+
+- Do not modify `.evergreen/` configuration without review
+- Evergreen runs the full test matrix across MongoDB versions, OS platforms, and JDK versions
+
+## Validating Evergreen Configuration
+
+After modifying `.evergreen/` files, validate the config locally:
+
+```bash
+evergreen validate .evergreen/.evg.yml
+```
+
+Always run this before submitting changes to `.evergreen/` to catch syntax errors and invalid task definitions.
+
+## Testing with a Patch Build
+
+To test your changes on Evergreen before merging, create a patch build:
+
+```bash
+evergreen patch -u
+```
+
+This uploads your uncommitted and committed local changes as a patch build on Evergreen, allowing you to run the full CI
+test matrix against your branch.
diff --git a/.agents/skills/sync-agents-docs/SKILL.md b/.agents/skills/sync-agents-docs/SKILL.md
new file mode 100644
index 00000000000..a466749b1a0
--- /dev/null
+++ b/.agents/skills/sync-agents-docs/SKILL.md
@@ -0,0 +1,27 @@
+---
+name: sync-agents-docs
+description: Sync AGENTS.md files, skills, and references after buildSrc or convention changes. Use after modifying build plugins, formatting rules, testing conventions, or task names to keep documentation consistent.
+disable-model-invocation: true
+---
+# Sync Documentation After Build Changes
+
+After modifying `buildSrc` or build conventions, check whether AGENTS.md files, skills, and references need updating.
+Review your changes against the checklist below and update only the affected files.
+
+## Checklist
+
+| What changed | What to update |
+| --- | --- |
+| Formatting conventions (`spotless.gradle.kts`) | Root `AGENTS.md` Style section, `style-reference` reference, affected module AGENTS.md files |
+| Convention plugins added or removed | `buildSrc/AGENTS.md` plugin table, root `AGENTS.md` if build commands or workflow changed |
+| Testing conventions (`testing-*.gradle.kts`) | Root `AGENTS.md` Testing section, `testing-guide` reference, affected module AGENTS.md files |
+| Project plugins added or removed | `buildSrc/AGENTS.md` project plugin table |
+| Build commands or task names changed | Root `AGENTS.md` Build and Before Submitting sections, `evergreen` skill, module AGENTS.md files |
+| CI/CD or publishing changes | `evergreen` skill |
+
+## How to use
+
+1. Review the diff of your buildSrc changes
+2. Walk through the checklist above — only rows matching your changes need action
+3. Update the affected files, keeping changes minimal and accurate
+4. Verify no stale references remain (e.g., renamed tasks, removed plugins)
diff --git a/.claude/skills b/.claude/skills
new file mode 120000
index 00000000000..2b7a412b8fa
--- /dev/null
+++ b/.claude/skills
@@ -0,0 +1 @@
+../.agents/skills
\ No newline at end of file
diff --git a/.gitignore b/.gitignore
index 6398e8490e8..8cc6afec7da 100644
--- a/.gitignore
+++ b/.gitignore
@@ -51,10 +51,16 @@ local.properties
 # shell scripts
 *.sh
 !.evergreen/*.sh
+!scripts/*.sh
 
 # security-sensitive files
 *.gpg
 
+# per-developer Agent overrides
+.AGENTS.md
+.claude/settings.local.json
+CLAUDE.local.md
+
 # bin build directories
 **/bin
 
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000000..a4c2042e5f8
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,104 @@
+# AGENTS.md - MongoDB Java Driver
+
+All changes require human review.
+Breaking changes to public API require a major version bump — always warn if binary compatibility is affected.
+Also consult `.AGENTS.md` / `~/.AGENTS.md` if present for local agent settings.
+
+**Architecture:** Multi-module Gradle project: `bson` → `driver-core` → `driver-sync`/`driver-reactive-streams` → language wrappers (`driver-kotlin-sync`, `driver-kotlin-coroutine`, `driver-scala`).
+
+See [`.agents/references/project-guide`](.agents/references/project-guide.md) for module structure and dependency graph.
+Each module has its own `AGENTS.md`.
+
+## Git
+
+The default branch is `main` (not `master`). Always use `main` when comparing, diffing, or creating branches.
+
+- **Branch naming:** `JAVA-XXXX` matching the Jira ticket (e.g., `JAVA-6143`)
+- **Commits:** Keep commits logical and reviewable — each commit should be a coherent unit of change
+- **TODO comments:** Must reference a Jira ticket if the work belongs to a different ticket:
+  `// TODO JAVA-XXXX reasoning for the todo`
+
+## Core Rules
+
+- Read before modifying — understand existing code and patterns first
+- Minimal changes only — no drive-by refactoring or unrelated changes
+- Preserve existing comments — only remove if provably incorrect
+- No rewrites without explicit permission
+- When stuck or uncertain: stop, explain, propose alternatives, ask
+
+## Build
+
+Gradle with Kotlin DSL. Build JDK: 17+. Source baseline: Java 8. Versions in `gradle/libs.versions.toml`.
+
+**Java 8 language constraint:** Most modules target Java 8. Do not use features from Java 9+ (`var`,
+records, text blocks, sealed classes, `Stream.toList()`, switch expressions, pattern matching, etc.)
+unless the module's `build.gradle.kts` explicitly sets a higher `sourceCompatibility`.
+
+**Kotlin language constraint:** Kotlin modules use Kotlin 1.8 with JVM target 1.8. All Kotlin modules
+enforce `explicitApi()` — all public declarations must have explicit visibility modifiers and types.
+Do not use Kotlin language features or standard library APIs introduced after 1.8.
+
+```bash
+./gradlew check                        # Full validation (format + static checks + tests)
+./gradlew :driver-core:test            # Single module tests
+./gradlew integrationTest -Dorg.mongodb.test.uri="mongodb://localhost:27017"
+```
+
+## Style
+
+`check` runs `spotlessCheck` to verify formatting — run `./gradlew spotlessApply` to auto-format when needed.
+Do not reformat outside your changes.
+See [`.agents/references/style-reference`](.agents/references/style-reference.md) for full rules.
+
+- No `System.out.println` / `System.err.println` — use SLF4J
+- No `e.printStackTrace()` — use proper error handling
+- Copyright header required: `Copyright 2008-present MongoDB, Inc.`
+- Every public package must have a `package-info.java`
+
+## Testing
+
+- Every code change must include tests.
+  Do not reduce coverage.
+- Integration tests require a running MongoDB instance (see the test URI in Build section).
+  Do not attempt to run `integrationTest` without a configured server.
+- See [`.agents/references/testing-guide`](.agents/references/testing-guide.md) for framework details and running specific
+  tests.
+- See [`.agents/references/spec-tests`](.agents/references/spec-tests.md) for MongoDB specification test conventions.
+
+## API
+
+All `com.mongodb.internal.*` / `org.bson.internal.*` is private API — never expose in public APIs.
+See [`.agents/references/api-design`](.agents/references/api-design.md) for stability annotations and design principles.
+
+**Java nullability:** Use `com.mongodb.lang.Nullable` / `NonNull` / `NonNullApi` annotations.
+Packages with `@NonNullApi` in `package-info.java` are non-null by default — only annotate exceptions
+with `@Nullable`. New packages must include `@NonNullApi`. Older packages without it are nullable by
+default and require explicit `@NonNull` where needed.
+
+**Thread safety:** Use `com.mongodb.annotations`; `@ThreadSafe`, `@NotThreadSafe`, or `@Immutable`.
+All public API classes must be thread-safe unless annotated otherwise. Concurrent code — particularly
+in async `driver-core` paths — must use locks (via `Locks.withLock()`), `volatile` fields, or
+`java.util.concurrent` atomics; never rely on external synchronization.
+
+## Do Not Modify Without Human Approval
+
+- Wire protocol / authentication handshakes (`com.mongodb.internal.connection`)
+- Connection pool core code (`com.mongodb.internal.connection.pool`)
+- Security-critical encryption code / JNA bindings (`mongodb-crypt`)
+- Public API contracts (breaking changes need major version bump)
+- BSON specification compliance
+- Spec test data submodule (`testing/resources/specifications/`)
+- Release/versioning scripts, `.evergreen/` config, credentials/secrets
+
+See [`.agents/skills/evergreen`](.agents/skills/evergreen/SKILL.md) for CI validation and patch builds.
+
+## Dependencies
+
+- Never add dependencies without justification
+- All dependency versions are managed in `gradle/libs.versions.toml` — never declare versions inline in `build.gradle.kts`
+
+## Before Submitting
+
+```bash
+./gradlew spotlessApply doc check scalaCheck   # formatting + Docs + static checks + all tests
+```
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000000..43c994c2d36
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md
diff --git a/README.md b/README.md
index 7cf774eb9fb..8a28cd89cb2 100644
--- a/README.md
+++ b/README.md
@@ -125,6 +125,18 @@ $ mongod --dbpath ./data/db --logpath ./data/mongod.log --port 27017 --logappend
 If you encounter `"Too many open files"` errors when running the tests then you will need to increase 
 the number of available file descriptors prior to starting mongod as described in [https://www.mongodb.com/docs/manual/reference/ulimit/](https://www.mongodb.com/docs/manual/reference/ulimit/)
 
+## AI Agent Configuration
+
+This repository uses [agentskills.io](https://agentskills.io) conventions for AI coding
+agent instructions. `AGENTS.md` is the canonical source of truth — tool-specific files
+like `CLAUDE.md` are generated references.
+
+### Adding a nested AGENTS.md
+
+1. Create an `AGENTS.md` in the target directory.
+2. Run `scripts/symlink-claude-md.sh` to generate the companion `CLAUDE.md`.
+3. Stage and commit both files.
+
 ## IntelliJ IDEA
 
 A couple of manual configuration steps are required to run the code in IntelliJ:
diff --git a/bson-kotlin/AGENTS.md b/bson-kotlin/AGENTS.md
new file mode 100644
index 00000000000..f9745b51d38
--- /dev/null
+++ b/bson-kotlin/AGENTS.md
@@ -0,0 +1,18 @@
+# AGENTS.md - bson-kotlin
+
+Kotlin extensions for the BSON library, providing idiomatic Kotlin codec support.
+
+**Depends on:** `bson`
+
+- Work here if: modifying Kotlin-specific BSON codecs or inline reified functions
+
+## Key Packages
+
+- `org.bson.codecs.kotlin` — Kotlin-specific codecs with inline reified functions
+
+## Build & Test
+
+```bash
+./gradlew :bson-kotlin:test
+./gradlew :bson-kotlin:check
+```
diff --git a/bson-kotlin/CLAUDE.md b/bson-kotlin/CLAUDE.md
new file mode 100644
index 00000000000..43c994c2d36
--- /dev/null
+++ b/bson-kotlin/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md
diff --git a/bson-kotlinx/AGENTS.md b/bson-kotlinx/AGENTS.md
new file mode 100644
index 00000000000..a5499429425
--- /dev/null
+++ b/bson-kotlinx/AGENTS.md
@@ -0,0 +1,19 @@
+# AGENTS.md - bson-kotlinx
+
+Kotlinx serialization integration for BSON, providing a pluggable serialization format.
+
+**Depends on:** `bson`
+
+- Work here if: modifying the kotlinx-serialization BSON codec integration
+
+## Key Packages
+
+- `org.bson.codecs.kotlinx` — Kotlinx serialization BSON format support
+- `org.bson.codecs.kotlinx.utils` — Helper utilities
+
+## Build & Test
+
+```bash
+./gradlew :bson-kotlinx:test
+./gradlew :bson-kotlinx:check
+```
diff --git a/bson-kotlinx/CLAUDE.md b/bson-kotlinx/CLAUDE.md
new file mode 100644
index 00000000000..43c994c2d36
--- /dev/null
+++ b/bson-kotlinx/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md
diff --git a/bson-record-codec/AGENTS.md b/bson-record-codec/AGENTS.md
new file mode 100644
index 00000000000..6935fe72740
--- /dev/null
+++ b/bson-record-codec/AGENTS.md
@@ -0,0 +1,21 @@
+# AGENTS.md - bson-record-codec
+
+Java record codec support for BSON serialization.
+**Requires Java 17+.**
+
+**Depends on:** `bson`
+
+- Work here if: modifying Java record serialization support
+- This module targets **Java 17** (`sourceCompatibility = 17`) — Java 17 features (records, sealed classes, text blocks,
+  etc.) are permitted here, unlike most other modules which target Java 8
+
+## Key Packages
+
+- `org.bson.codecs.record` — `RecordCodecProvider` and record field accessors
+
+## Build & Test
+
+```bash
+./gradlew :bson-record-codec:test
+./gradlew :bson-record-codec:check
+```
diff --git a/bson-record-codec/CLAUDE.md b/bson-record-codec/CLAUDE.md
new file mode 100644
index 00000000000..43c994c2d36
--- /dev/null
+++ b/bson-record-codec/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md
diff --git a/bson-scala/AGENTS.md b/bson-scala/AGENTS.md
new file mode 100644
index 00000000000..dc56818ff19
--- /dev/null
+++ b/bson-scala/AGENTS.md
@@ -0,0 +1,24 @@
+# AGENTS.md - bson-scala
+
+Scala extensions for the BSON library, providing Scala-idiomatic wrappers and macro-based codecs.
+
+**Depends on:** `bson`
+
+**Supported Scala versions:** 2.11, 2.12, 2.13, 3 (default: 2.13, configured in root `gradle.properties`).
+
+- Work here if: modifying Scala BSON wrappers, macro codecs, or Scala collection support
+
+## Key Packages
+
+- `org.mongodb.scala.bson` — Core Scala BSON wrappers
+- `org.mongodb.scala.bson.codecs` — Macro-based codecs (Scala 2/3)
+
+## Build & Test
+
+```bash
+./gradlew :bson-scala:test
+./gradlew :bson-scala:scalaCheck                          # Static checks + tests (default Scala version)
+./gradlew :bson-scala:scalaCheck -PscalaVersion=<version> # Test specific Scala version
+```
+
+See [README.md](./README.md) for directory layout details.
diff --git a/bson-scala/CLAUDE.md b/bson-scala/CLAUDE.md
new file mode 100644
index 00000000000..43c994c2d36
--- /dev/null
+++ b/bson-scala/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md
diff --git a/bson/AGENTS.md b/bson/AGENTS.md
new file mode 100644
index 00000000000..f41ce59895f
--- /dev/null
+++ b/bson/AGENTS.md
@@ -0,0 +1,24 @@
+# AGENTS.md - bson
+
+Core BSON (Binary JSON) library — the foundation module.
+All other modules depend on it.
+
+**Depends on:** None (foundation module)
+
+- Work here if: adding/modifying BSON types, codecs, JSON conversion, or binary I/O
+- Do not: expose `org.bson.internal` types in public API
+
+## Key Packages
+
+- `org.bson` — Core types (`BsonDocument`, `BsonValue`, `BsonReader`, `BsonWriter`)
+- `org.bson.codecs` — Codec framework (`Encoder`, `Decoder`, `Codec`, `CodecRegistry`)
+- `org.bson.codecs.pojo` — POJO codec support
+- `org.bson.json` — JSON conversion (`JsonReader`, `JsonWriter`)
+- `org.bson.internal` — Private API — do not expose
+
+## Build & Test
+
+```bash
+./gradlew :bson:test
+./gradlew :bson:check
+```
diff --git a/bson/CLAUDE.md b/bson/CLAUDE.md
new file mode 100644
index 00000000000..43c994c2d36
--- /dev/null
+++ b/bson/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md
diff --git a/buildSrc/AGENTS.md b/buildSrc/AGENTS.md
new file mode 100644
index 00000000000..bdd23ab1632
--- /dev/null
+++ b/buildSrc/AGENTS.md
@@ -0,0 +1,54 @@
+# AGENTS.md - buildSrc
+
+Gradle build infrastructure providing convention plugins and shared configuration for all modules.
+
+## Key Directories
+
+- `src/main/kotlin/conventions/` — Convention plugins applied by modules (formatting, testing, publishing, static
+  analysis)
+- `src/main/kotlin/project/` — Base project plugins for Java, Kotlin, and Scala modules
+- `src/main/kotlin/ProjectExtensions.kt` — Shared Gradle extension utilities
+
+## Convention Plugins
+
+| Plugin | Purpose |
+| --- | --- |
+| `spotless` | Code formatting (Java: Palantir; Kotlin: ktfmt dropbox, max 120; Scala: scalafmt) |
+| `codenarc` | Groovy static analysis |
+| `detekt` | Kotlin static analysis |
+| `spotbugs` | Java bug detection |
+| `bnd` | OSGi bundle metadata |
+| `dokka` | Kotlin documentation generation |
+| `javadoc` | Java documentation generation |
+| `scaladoc` | Scala documentation generation |
+| `publishing` | Maven Central publishing configuration |
+| `git-version` | Version derivation from git tags |
+| `optional` | Optional dependency support (`optionalImplementation`) |
+| `testing-base` | Shared test configuration |
+| `testing-integration` | Integration test source set and tasks |
+| `testing-junit` | JUnit 5 test setup |
+| `testing-junit-vintage` | JUnit 4 compatibility |
+| `testing-spock` | Spock framework setup |
+| `testing-spock-exclude-slow` | Spock with slow test exclusion |
+| `testing-mockito` | Mockito setup |
+| `test-artifacts` | Test artifact sharing between modules |
+| `test-artifacts-runtime-dependencies` | Runtime dependency sharing for tests |
+| `test-include-optionals` | Include optional dependencies in tests |
+
+## Project Plugins
+
+| Plugin | Purpose |
+| --- | --- |
+| `project/base` | Common settings for all modules |
+| `project/java` | Java module conventions (source compatibility, checkstyle) |
+| `project/kotlin` | Kotlin module conventions |
+| `project/scala` | Scala module conventions (multi-version support) |
+
+## Notes
+
+- Formatting: ktfmt dropbox style, max width 120 (for buildSrc’s own code)
+- `check` depends on `spotlessCheck` in buildSrc itself
+- Java toolchain is set to Java 17
+
+After modifying buildSrc, run the [`sync-agents-docs`](../.agents/skills/sync-agents-docs/SKILL.md) skill to update
+AGENTS.md files and skills that may be affected.
diff --git a/buildSrc/CLAUDE.md b/buildSrc/CLAUDE.md
new file mode 100644
index 00000000000..43c994c2d36
--- /dev/null
+++ b/buildSrc/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md
diff --git a/driver-benchmarks/AGENTS.md b/driver-benchmarks/AGENTS.md
new file mode 100644
index 00000000000..75c9ff42c87
--- /dev/null
+++ b/driver-benchmarks/AGENTS.md
@@ -0,0 +1,21 @@
+# AGENTS.md - driver-benchmarks
+
+Performance benchmarks for the MongoDB Java Driver using JMH and a custom benchmark framework.
+
+**Depends on:** `driver-sync`, `mongodb-crypt`
+
+## Key Packages
+
+- `com.mongodb.benchmark.benchmarks` — Benchmark suite and individual benchmarks (BSON, single/multi-doc, bulk
+  operations)
+- `com.mongodb.benchmark.benchmarks.bulk` — Bulk write benchmarks
+- `com.mongodb.benchmark.benchmarks.netty` — Netty transport benchmarks
+- `com.mongodb.benchmark.framework` — Custom benchmark harness
+- `com.mongodb.benchmark.jmh` — JMH microbenchmarks
+
+## Notes
+
+- Not published — internal testing only
+- Non-standard source layout: `src/main` (no `java` subdirectory)
+- Run benchmarks: `./gradlew :driver-benchmarks:run` or `./gradlew :driver-benchmarks:jmh`
+- Requires `-Dorg.mongodb.benchmarks.data` and `-Dorg.mongodb.benchmarks.output` system properties
diff --git a/driver-benchmarks/CLAUDE.md b/driver-benchmarks/CLAUDE.md
new file mode 100644
index 00000000000..43c994c2d36
--- /dev/null
+++ b/driver-benchmarks/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md
diff --git a/driver-core/AGENTS.md b/driver-core/AGENTS.md
new file mode 100644
index 00000000000..d1ad09af42f
--- /dev/null
+++ b/driver-core/AGENTS.md
@@ -0,0 +1,31 @@
+# AGENTS.md - driver-core
+
+Core driver internals shared by all driver variants (sync, reactive, Kotlin, Scala).
+Largest and most complex module.
+
+**Depends on:** `bson`, `bson-record-codec`, optionally `bson-kotlin`, `bson-kotlinx`, `mongodb-crypt`
+
+- Work here if: modifying query builders (`Filters`, `Updates`, `Aggregates`), connection handling, wire protocol,
+  server selection, or operation execution
+- Do not: block in async code paths, modify wire protocol or auth without human approval
+
+## Key Packages
+
+- `com.mongodb.client.model` — `Filters`, `Updates`, `Projections`, `Aggregates`, `Sorts`, `Indexes`
+- `com.mongodb.internal.connection` — Wire protocol, command execution (safety-critical)
+- `com.mongodb.internal.operation` — Concrete operations (find, insert, aggregate)
+- `com.mongodb.internal.authentication` — SASL, SCRAM, X.509, OIDC (safety-critical)
+
+## Build & Test
+
+```bash
+./gradlew :driver-core:test
+./gradlew :driver-core:check
+./gradlew :driver-core:generateMongoDriverVersion   # If MongoDriverVersion is missing
+```
+
+## Notes
+
+- Most extensive test suite — JUnit 5 + Spock + Mockito.
+  Match surrounding patterns carefully.
+- `MongoDriverVersion` is auto-generated by the `com.github.gmazzo.buildconfig` plugin
diff --git a/driver-core/CLAUDE.md b/driver-core/CLAUDE.md
new file mode 100644
index 00000000000..43c994c2d36
--- /dev/null
+++ b/driver-core/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md
diff --git a/driver-kotlin-coroutine/AGENTS.md b/driver-kotlin-coroutine/AGENTS.md
new file mode 100644
index 00000000000..94a0da4f409
--- /dev/null
+++ b/driver-kotlin-coroutine/AGENTS.md
@@ -0,0 +1,19 @@
+# AGENTS.md - driver-kotlin-coroutine
+
+Kotlin Coroutines driver providing `suspend` function-based async API.
+
+**Depends on:** `bson`, `driver-reactive-streams`, `bson-kotlin`
+
+- Work here if: modifying the Kotlin coroutine-based driver API
+- Do not: block in any code path — all suspend functions wrap `driver-reactive-streams`
+
+## Key Packages
+
+- `com.mongodb.kotlin.client.coroutine` — Coroutine-based driver API (`MongoClient`, `MongoDatabase`, `MongoCollection`)
+
+## Build & Test
+
+```bash
+./gradlew :driver-kotlin-coroutine:test
+./gradlew :driver-kotlin-coroutine:check
+```
diff --git a/driver-kotlin-coroutine/CLAUDE.md b/driver-kotlin-coroutine/CLAUDE.md
new file mode 100644
index 00000000000..43c994c2d36
--- /dev/null
+++ b/driver-kotlin-coroutine/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md
diff --git a/driver-kotlin-extensions/AGENTS.md b/driver-kotlin-extensions/AGENTS.md
new file mode 100644
index 00000000000..8cbd2e3d3ca
--- /dev/null
+++ b/driver-kotlin-extensions/AGENTS.md
@@ -0,0 +1,20 @@
+# AGENTS.md - driver-kotlin-extensions
+
+Kotlin extensions providing type-safe DSLs for query and update construction.
+
+**Depends on:** `driver-core`, optionally `driver-kotlin-sync`, `driver-kotlin-coroutine`
+
+- Work here if: adding or modifying Kotlin type-safe DSL builders for `Filters`, `Updates`, `Aggregates`, etc.
+- Works with both `driver-kotlin-sync` and `driver-kotlin-coroutine`
+
+## Key Packages
+
+- `com.mongodb.kotlin.client.model` — Type-safe DSL builders
+- `com.mongodb.kotlin.client.property` — `KPropertyPath` for property-based queries
+
+## Build & Test
+
+```bash
+./gradlew :driver-kotlin-extensions:test
+./gradlew :driver-kotlin-extensions:check
+```
diff --git a/driver-kotlin-extensions/CLAUDE.md b/driver-kotlin-extensions/CLAUDE.md
new file mode 100644
index 00000000000..43c994c2d36
--- /dev/null
+++ b/driver-kotlin-extensions/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md
diff --git a/driver-kotlin-sync/AGENTS.md b/driver-kotlin-sync/AGENTS.md
new file mode 100644
index 00000000000..983ea0eae0b
--- /dev/null
+++ b/driver-kotlin-sync/AGENTS.md
@@ -0,0 +1,19 @@
+# AGENTS.md - driver-kotlin-sync
+
+Kotlin synchronous (blocking) driver — idiomatic Kotlin wrapper over `driver-sync`.
+
+**Depends on:** `bson`, `driver-sync`, `bson-kotlin`
+
+- Work here if: modifying the Kotlin blocking API surface
+- Do not: add internal connection/protocol code (that belongs in `driver-core`)
+
+## Key Packages
+
+- `com.mongodb.kotlin.client` — Blocking sync API (`MongoClient`, `MongoDatabase`, `MongoCollection`)
+
+## Build & Test
+
+```bash
+./gradlew :driver-kotlin-sync:test
+./gradlew :driver-kotlin-sync:check
+```
diff --git a/driver-kotlin-sync/CLAUDE.md b/driver-kotlin-sync/CLAUDE.md
new file mode 100644
index 00000000000..43c994c2d36
--- /dev/null
+++ b/driver-kotlin-sync/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md
diff --git a/driver-legacy/AGENTS.md b/driver-legacy/AGENTS.md
new file mode 100644
index 00000000000..1470a38760a
--- /dev/null
+++ b/driver-legacy/AGENTS.md
@@ -0,0 +1,22 @@
+# AGENTS.md - driver-legacy
+
+Legacy MongoDB Java driver API — backwards compatibility facade for the 3.x API.
+
+**Depends on:** `bson`, `driver-core`, `driver-sync`
+
+- Work here if: fixing bugs in the legacy 3.x API compatibility layer
+- Do not: add new features (new functionality goes in `driver-sync` or `driver-core`)
+- Do not: add new Spock tests
+
+## Key Packages
+
+- `com.mongodb` — Legacy API (`MongoClient`, `DB`, `DBCollection`, `DBCursor`) — distinct from `driver-core` classes in
+  the same namespace
+- `com.mongodb.gridfs` — Legacy GridFS
+
+## Build & Test
+
+```bash
+./gradlew :driver-legacy:test
+./gradlew :driver-legacy:check
+```
diff --git a/driver-legacy/CLAUDE.md b/driver-legacy/CLAUDE.md
new file mode 100644
index 00000000000..43c994c2d36
--- /dev/null
+++ b/driver-legacy/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md
diff --git a/driver-reactive-streams/AGENTS.md b/driver-reactive-streams/AGENTS.md
new file mode 100644
index 00000000000..f7edd6a09b9
--- /dev/null
+++ b/driver-reactive-streams/AGENTS.md
@@ -0,0 +1,24 @@
+# AGENTS.md - driver-reactive-streams
+
+Reactive Streams driver implementing the [Reactive Streams specification](https://www.reactive-streams.org/).
+
+**Depends on:** `bson`, `driver-core`
+
+- Work here if: modifying the Publisher-based async API
+- Do not: block in any code path, break backpressure contracts
+
+## Key Packages
+
+- `com.mongodb.reactivestreams.client` — Publisher-based API (`MongoClient`, `MongoDatabase`, `MongoCollection`)
+
+## Build & Test
+
+```bash
+./gradlew :driver-reactive-streams:test
+./gradlew :driver-reactive-streams:check
+```
+
+## Notes
+
+- All operations return `Publisher<T>` — never block
+- `driver-kotlin-coroutine` and `driver-scala` both build on top of this module
diff --git a/driver-reactive-streams/CLAUDE.md b/driver-reactive-streams/CLAUDE.md
new file mode 100644
index 00000000000..43c994c2d36
--- /dev/null
+++ b/driver-reactive-streams/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md
diff --git a/driver-scala/AGENTS.md b/driver-scala/AGENTS.md
new file mode 100644
index 00000000000..3e22456ea26
--- /dev/null
+++ b/driver-scala/AGENTS.md
@@ -0,0 +1,25 @@
+# AGENTS.md - driver-scala
+
+Scala async driver providing Observable-based API wrapping `driver-reactive-streams`.
+
+**Depends on:** `bson-scala`, `driver-reactive-streams`
+
+**Supported Scala versions:** 2.11, 2.12, 2.13, 3 (default: 2.13, configured in root `gradle.properties`).
+
+- Work here if: modifying the Scala Observable-based driver API or Scala model wrappers
+- Do not: block in any code path
+
+## Key Packages
+
+- `org.mongodb.scala` — Scala async driver (`MongoClient`, `MongoDatabase`, `MongoCollection`)
+- `org.mongodb.scala.model` — Scala wrappers around filter/update builders
+
+## Build & Test
+
+```bash
+./gradlew :driver-scala:test
+./gradlew :driver-scala:scalaCheck                          # Static checks + tests (default Scala version)
+./gradlew :driver-scala:scalaCheck -PscalaVersion=<version> # Test specific Scala version
+```
+
+See [README.md](./README.md) for directory layout details.
diff --git a/driver-scala/CLAUDE.md b/driver-scala/CLAUDE.md
new file mode 100644
index 00000000000..43c994c2d36
--- /dev/null
+++ b/driver-scala/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md
diff --git a/driver-sync/AGENTS.md b/driver-sync/AGENTS.md
new file mode 100644
index 00000000000..9a3376e80a1
--- /dev/null
+++ b/driver-sync/AGENTS.md
@@ -0,0 +1,24 @@
+# AGENTS.md - driver-sync
+
+Synchronous (blocking) Java driver — the most commonly used entry point for Java applications.
+
+**Depends on:** `bson`, `driver-core`
+
+- Work here if: modifying the blocking Java API surface (`MongoClient`, `MongoDatabase`, `MongoCollection`), GridFS, or
+  CSFLE vault client
+- Do not: add new Spock tests (legacy only), add internal connection/protocol code (that belongs in `driver-core`)
+
+## Key Packages
+
+- `com.mongodb.client` — Public sync API
+- `com.mongodb.client.gridfs` — GridFS sync implementation
+- `com.mongodb.client.vault` — Client-side field-level encryption client
+
+## Build & Test
+
+```bash
+./gradlew :driver-sync:test
+./gradlew :driver-sync:check
+```
+
+Primary entry point: `MongoClients.create()` or `MongoClients.create(MongoClientSettings)`.
diff --git a/driver-sync/CLAUDE.md b/driver-sync/CLAUDE.md
new file mode 100644
index 00000000000..43c994c2d36
--- /dev/null
+++ b/driver-sync/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md
diff --git a/gradle/AGENTS.md b/gradle/AGENTS.md
new file mode 100644
index 00000000000..7bdb8910d0f
--- /dev/null
+++ b/gradle/AGENTS.md
@@ -0,0 +1,20 @@
+# AGENTS.md - gradle
+
+Gradle configuration and infrastructure for the build system.
+
+## Key Files
+
+- `libs.versions.toml` — Central version catalog defining all dependency versions, library coordinates, bundles, and
+  plugin versions
+- `wrapper/` — Gradle wrapper JAR and properties (do not modify manually — use
+  `./gradlew wrapper --gradle-version=<version>`)
+- `scala/lib/` — Bundled Scala Ant JAR for Scala compilation support
+
+## Notes
+
+- All dependency versions are managed in `libs.versions.toml` — never declare versions inline in `build.gradle.kts`
+  files
+- Never add dependencies without justification
+- The version catalog defines `[versions]`, `[libraries]`, `[bundles]`, and `[plugins]` sections
+- Scala test libraries are declared per Scala version (v3, v2-v13, v2-v12, v2-v11)
+- When adding or updating dependencies, modify `libs.versions.toml` and reference via `libs.<alias>` in build scripts
diff --git a/gradle/CLAUDE.md b/gradle/CLAUDE.md
new file mode 100644
index 00000000000..43c994c2d36
--- /dev/null
+++ b/gradle/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md
diff --git a/mongodb-crypt/AGENTS.md b/mongodb-crypt/AGENTS.md
new file mode 100644
index 00000000000..bf9737febf7
--- /dev/null
+++ b/mongodb-crypt/AGENTS.md
@@ -0,0 +1,26 @@
+# AGENTS.md - mongodb-crypt
+
+Client-side field-level encryption (CSFLE) support via JNA bindings to libmongocrypt.
+
+**Depends on:** `bson`
+
+- Work here if: modifying CSFLE encryption/decryption logic or JNA bindings
+- Do not: move, re-expose, or refactor JNA/libmongocrypt bindings without human approval — this is security-critical
+  code
+- Do not: modify the C API binding layer without understanding the libmongocrypt contract
+
+## Key Packages
+
+- `com.mongodb.crypt.capi` — mongocryptd C API bindings (JNA) — **security-critical, do not modify without human
+  review**
+- `com.mongodb.internal.crypt.capi` — Internal encryption state management
+
+## Build & Test
+
+```bash
+./gradlew :mongodb-crypt:test
+./gradlew :mongodb-crypt:check
+```
+
+Tests are primarily integration tests requiring libmongocrypt native libraries.
+Build downloads JNA libs for multiple platforms, embedded in the JAR.
diff --git a/mongodb-crypt/CLAUDE.md b/mongodb-crypt/CLAUDE.md
new file mode 100644
index 00000000000..43c994c2d36
--- /dev/null
+++ b/mongodb-crypt/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md
diff --git a/scripts/symlink-claude-md.sh b/scripts/symlink-claude-md.sh
new file mode 100755
index 00000000000..95a060eaf41
--- /dev/null
+++ b/scripts/symlink-claude-md.sh
@@ -0,0 +1,105 @@
+#!/usr/bin/env bash
+# 1. Ensure every staged AGENTS.md has a companion CLAUDE.md containing
+#    "@AGENTS.md" (a Claude Code import reference).
+# 2. Ensure .claude/skills is a symlink to .agents/skills.
+
+set -euo pipefail
+
+claude_file_for_agents() {
+  local agents_file="$1"
+  local dir
+
+  dir=$(dirname "$agents_file")
+
+  if [ "$dir" = "." ]; then
+    printf 'CLAUDE.md\n'
+  else
+    printf '%s/CLAUDE.md\n' "$dir"
+  fi
+}
+
+remove_generated_file() {
+  local generated_file="$1"
+
+  if git ls-files --error-unmatch -- "$generated_file" > /dev/null 2>&1 || [ -e "$generated_file" ]; then
+    rm -f "$generated_file"
+    git add -u -- "$generated_file"
+    echo "auto-removed: $generated_file"
+  fi
+}
+
+sync_claude_skills_dir() {
+  local claude_skills_dir=".claude/skills"
+  local expected_target="../.agents/skills"
+  local current_target
+
+  if [ -L "$claude_skills_dir" ]; then
+    current_target=$(readlink "$claude_skills_dir")
+    if [ "$current_target" = "$expected_target" ]; then
+      return
+    fi
+
+    rm -f "$claude_skills_dir"
+  elif [ -e "$claude_skills_dir" ]; then
+    rm -rf "$claude_skills_dir"
+  fi
+
+  mkdir -p .claude
+  ln -s "$expected_target" "$claude_skills_dir"
+  git add "$claude_skills_dir"
+  echo "auto-synced: $claude_skills_dir -> $expected_target"
+}
+
+sync_claude_skills_dir
+
+staged_agents=()
+deleted_agents=()
+
+while IFS=$'\t ' read -r status first_path second_path; do
+  [ -n "$status" ] || continue
+
+  case "$status" in
+    R*)
+      if [[ "$first_path" =~ (^|/)AGENTS\.md$ ]]; then
+        deleted_agents+=("$first_path")
+      fi
+      if [[ "$second_path" =~ (^|/)AGENTS\.md$ ]]; then
+        staged_agents+=("$second_path")
+      fi
+      ;;
+    D)
+      if [[ "$first_path" =~ (^|/)AGENTS\.md$ ]]; then
+        deleted_agents+=("$first_path")
+      fi
+      ;;
+    *)
+      if [[ "$first_path" =~ (^|/)AGENTS\.md$ ]]; then
+        staged_agents+=("$first_path")
+      fi
+      ;;
+  esac
+done < <(git diff --cached --name-status --find-renames --diff-filter=ADMR)
+
+# --- CLAUDE.md sync ---
+if [ "${#staged_agents[@]}" -gt 0 ]; then
+  for agents_file in "${staged_agents[@]}"; do
+    claude_file=$(claude_file_for_agents "$agents_file")
+
+    # Skip if already a regular file with the correct content
+    if [ -f "$claude_file" ] && ! [ -L "$claude_file" ] && [ "$(cat "$claude_file")" = "@AGENTS.md" ]; then
+      continue
+    fi
+
+    # Remove symlink if present, then write the reference file
+    rm -f "$claude_file"
+    printf '@AGENTS.md\n' > "$claude_file"
+    git add "$claude_file"
+    echo "auto-created: $claude_file with @AGENTS.md reference"
+  done
+fi
+
+if [ "${#deleted_agents[@]}" -gt 0 ]; then
+  for agents_file in "${deleted_agents[@]}"; do
+    remove_generated_file "$(claude_file_for_agents "$agents_file")"
+  done
+fi
diff --git a/testing/AGENTS.md b/testing/AGENTS.md
new file mode 100644
index 00000000000..ea168df20ac
--- /dev/null
+++ b/testing/AGENTS.md
@@ -0,0 +1,11 @@
+# AGENTS.md - testing
+
+Shared test resources and MongoDB specification test data.
+
+## Notes
+
+- `resources/specifications/` — Git submodule containing MongoDB specification test data (CRUD, SDAM, auth, CSFLE,
+  retryable ops, etc.)
+- `resources/logback-test.xml` — Shared logback configuration for tests
+- **Do not modify spec test data** — managed upstream.
+  Update via `git submodule update`.
diff --git a/testing/CLAUDE.md b/testing/CLAUDE.md
new file mode 100644
index 00000000000..43c994c2d36
--- /dev/null
+++ b/testing/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md

From 6e2c0b436229c9e93366b2f1d87d8384b28ed3ed Mon Sep 17 00:00:00 2001
From: Ross Lawley <ross.lawley@gmail.com>
Date: Thu, 7 May 2026 15:17:44 +0100
Subject: [PATCH 2/2] PR feedback

---
 .agents/references/api-design.md              | 22 ++++++++++++++++---
 .agents/references/project-guide.md           |  2 ++
 .agents/references/style-reference.md         |  2 +-
 .agents/references/testing-guide-examples.md  |  2 +-
 .agents/skills/sync-agents-docs/SKILL.md      |  3 +++
 AGENTS.md                                     |  4 ++--
 README.md                                     |  4 +++-
 bom/AGENTS.md                                 |  7 ++++++
 bom/CLAUDE.md                                 |  1 +
 buildSrc/AGENTS.md                            |  2 +-
 ...symlink-claude-md.sh => sync-claude-md.sh} |  9 ++++++++
 11 files changed, 49 insertions(+), 9 deletions(-)
 create mode 100644 bom/AGENTS.md
 create mode 100644 bom/CLAUDE.md
 rename scripts/{symlink-claude-md.sh => sync-claude-md.sh} (88%)

diff --git a/.agents/references/api-design.md b/.agents/references/api-design.md
index 23e89ebe457..adb9d2a8233 100644
--- a/.agents/references/api-design.md
+++ b/.agents/references/api-design.md
@@ -16,8 +16,23 @@ description: API stability annotations, design principles, and patterns for the
   Safe to use, but not to subclass.
 - `@Deprecated` — Supported until next major release but should be migrated away from.
 
+## API Lifecycle
+
+- **@Deprecated:** Deprecate in minor release, remove in next major. Always include `@deprecated Use {@link Replacement}` with a migration path.
+- **@Alpha:** Early development, subject to incompatible changes or removal. Exempt from compatibility guarantees. Not for production use by applications; libraries must not depend on Alpha APIs.
+- **@Beta:** Subject to incompatible changes or removal. Exempt from compatibility guarantees. Safe for applications (at the cost of extra upgrade work), but libraries should not depend on Beta APIs.
+- **@Sealed:** Use when the driver provides internal implementations but consumers must not subclass (e.g., `ReadPreference`, `WriteConcern`).
+
+## Module Ownership
+
+- Public API lives in `driver-sync`, `driver-reactive-streams`, and language wrappers (`driver-kotlin-sync`, `driver-kotlin-coroutine`, `driver-scala`)
+- `driver-core` owns shared internals, query builders (`Filters`, `Updates`, `Aggregates`), and the async execution layer
+- Sync wrappers delegate to async core — never add sync-only logic that diverges from the async path
+
 ## Design Principles
 
+These guide the driver's API surface:
+
 - **Deep modules:** Prefer simple interfaces with powerful implementations over shallow wrappers.
 - **Information hiding:** Bury complexity behind simple interfaces.
 - **Pull complexity downward:** Make the implementer work harder so callers work less.
@@ -26,6 +41,7 @@ description: API stability annotations, design principles, and patterns for the
 
 ## Key Patterns
 
-- Static factory methods: `Filters.eq()`, `Updates.set()`, `Aggregates.match()`
-- Fluent builders: `MongoClientSettings.builder()` is the primary entry point
-- Abstract core with pluggable transports
+- **Static factory methods:** `Filters.eq()`, `Updates.set()`, `Aggregates.match()` — prefer these over constructors for public API
+- **Fluent builders:** `MongoClientSettings.builder()` is the primary entry point — use for any class with more than 2–3 configuration options
+- **Abstract core with pluggable transports:** `driver-core` defines operations; transport modules (`driver-sync`, `driver-reactive-streams`) execute them
+- **Immutable value objects:** `MongoNamespace`, `WriteConcern`, `ReadPreference` are immutable — modifications return new instances
diff --git a/.agents/references/project-guide.md b/.agents/references/project-guide.md
index a068414426e..8e72a762a14 100644
--- a/.agents/references/project-guide.md
+++ b/.agents/references/project-guide.md
@@ -61,3 +61,5 @@ bson
 - **Build plugins, formatting, test infra:** `buildSrc`
 
 Each module has its own `AGENTS.md` with module-specific packages, patterns, and notes.
+Modules marked "(not published)" (`driver-lambda`, `graalvm-native-image-app`, `driver-benchmarks`) are
+test/example apps — not normal development targets and intentionally have no `AGENTS.md`.
diff --git a/.agents/references/style-reference.md b/.agents/references/style-reference.md
index fa9adfe85f2..d0ff3840278 100644
--- a/.agents/references/style-reference.md
+++ b/.agents/references/style-reference.md
@@ -40,7 +40,7 @@ description: Detailed code style rules for Java, Kotlin, Scala, and Groovy in th
 - Use `@mongodb.server.release <version>` to indicate the minimum server version required
 - Scala modules use Scaladoc — follow Scaladoc conventions (`@param`, `@return`, `@since`, `@see`)
 - Internal packages (`com.mongodb.internal.*`, `org.bson.internal.*`) are excluded from doc generation
-- Run `./gradlew doc` to validate Javadoc/KDoc/Scaladoc builds cleanly
+- Run `./gradlew docs` to validate Javadoc/KDoc/Scaladoc builds cleanly
 
 ## Prohibited Patterns
 
diff --git a/.agents/references/testing-guide-examples.md b/.agents/references/testing-guide-examples.md
index 96f24b141c3..742cad09eb9 100644
--- a/.agents/references/testing-guide-examples.md
+++ b/.agents/references/testing-guide-examples.md
@@ -71,7 +71,7 @@ class FeatureUnderTestSpec extends BaseSpec with MockitoSugar {
 class FeatureUnderTestTest {
 
     companion object {
-        @Mock internal val wrapped: com.mongodb.client.MongoCollection<MyType> = mock()
+        internal val wrapped: com.mongodb.client.MongoCollection<MyType> = mock()
         lateinit var collection: MongoCollection<MyType>
 
         @JvmStatic
diff --git a/.agents/skills/sync-agents-docs/SKILL.md b/.agents/skills/sync-agents-docs/SKILL.md
index a466749b1a0..963343616e3 100644
--- a/.agents/skills/sync-agents-docs/SKILL.md
+++ b/.agents/skills/sync-agents-docs/SKILL.md
@@ -5,6 +5,9 @@ disable-model-invocation: true
 ---
 # Sync Documentation After Build Changes
 
+This is a manual checklist — `disable-model-invocation: true` means agents cannot execute it autonomously.
+Human developers should walk through this after buildSrc changes.
+
 After modifying `buildSrc` or build conventions, check whether AGENTS.md files, skills, and references need updating.
 Review your changes against the checklist below and update only the affected files.
 
diff --git a/AGENTS.md b/AGENTS.md
index a4c2042e5f8..b25f3f1e875 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -46,7 +46,7 @@ Do not use Kotlin language features or standard library APIs introduced after 1.
 
 ## Style
 
-`check` runs `spotlessCheck` to verify formatting — run `./gradlew spotlessApply` to auto-format when needed.
+`check` depends on `spotlessApply` to auto-fix formatting — run `./gradlew spotlessApply` independently when needed.
 Do not reformat outside your changes.
 See [`.agents/references/style-reference`](.agents/references/style-reference.md) for full rules.
 
@@ -100,5 +100,5 @@ See [`.agents/skills/evergreen`](.agents/skills/evergreen/SKILL.md) for CI valid
 ## Before Submitting
 
 ```bash
-./gradlew spotlessApply doc check scalaCheck   # formatting + Docs + static checks + all tests
+./gradlew spotlessApply docs check scalaCheck   # formatting + docs + static checks + all tests
 ```
diff --git a/README.md b/README.md
index 8a28cd89cb2..5ef9ba78ac9 100644
--- a/README.md
+++ b/README.md
@@ -134,7 +134,9 @@ like `CLAUDE.md` are generated references.
 ### Adding a nested AGENTS.md
 
 1. Create an `AGENTS.md` in the target directory.
-2. Run `scripts/symlink-claude-md.sh` to generate the companion `CLAUDE.md`.
+2. Run `scripts/sync-claude-md.sh` to generate the companion `CLAUDE.md`.
+   This script should be run before staging — it creates/removes `CLAUDE.md` files
+   to match staged `AGENTS.md` changes and maintains the `.claude/skills` symlink.
 3. Stage and commit both files.
 
 ## IntelliJ IDEA
diff --git a/bom/AGENTS.md b/bom/AGENTS.md
new file mode 100644
index 00000000000..b8e30dc442e
--- /dev/null
+++ b/bom/AGENTS.md
@@ -0,0 +1,7 @@
+# AGENTS.md - bom
+
+Bill of Materials (BOM) for MongoDB Java Driver dependency management.
+
+- All dependency versions are managed in `gradle/libs.versions.toml` — never declare versions inline
+- This module publishes a BOM POM only — no source code
+- Do not add implementation dependencies here
diff --git a/bom/CLAUDE.md b/bom/CLAUDE.md
new file mode 100644
index 00000000000..43c994c2d36
--- /dev/null
+++ b/bom/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md
diff --git a/buildSrc/AGENTS.md b/buildSrc/AGENTS.md
index bdd23ab1632..b90ba93dda0 100644
--- a/buildSrc/AGENTS.md
+++ b/buildSrc/AGENTS.md
@@ -13,7 +13,7 @@ Gradle build infrastructure providing convention plugins and shared configuratio
 
 | Plugin | Purpose |
 | --- | --- |
-| `spotless` | Code formatting (Java: Palantir; Kotlin: ktfmt dropbox, max 120; Scala: scalafmt) |
+| `spotless` | Code formatting (Kotlin: ktfmt dropbox, max 120; Scala: scalafmt; KotlinGradle: ktfmt; XML/YML/MD: whitespace). Note: Java uses Palantir Java Format via Checkstyle, not Spotless |
 | `codenarc` | Groovy static analysis |
 | `detekt` | Kotlin static analysis |
 | `spotbugs` | Java bug detection |
diff --git a/scripts/symlink-claude-md.sh b/scripts/sync-claude-md.sh
similarity index 88%
rename from scripts/symlink-claude-md.sh
rename to scripts/sync-claude-md.sh
index 95a060eaf41..e760e218dfc 100755
--- a/scripts/symlink-claude-md.sh
+++ b/scripts/sync-claude-md.sh
@@ -1,10 +1,19 @@
 #!/usr/bin/env bash
+# Sync CLAUDE.md companion files for staged AGENTS.md changes and maintain
+# the .claude/skills symlink. Run from the repository root before staging.
+#
 # 1. Ensure every staged AGENTS.md has a companion CLAUDE.md containing
 #    "@AGENTS.md" (a Claude Code import reference).
 # 2. Ensure .claude/skills is a symlink to .agents/skills.
 
 set -euo pipefail
 
+# Ensure we are running from the repository root
+if [ ! -f "settings.gradle.kts" ] || [ ! -d ".git" ]; then
+  echo "Error: must be run from the repository root (where settings.gradle.kts and .git/ exist)" >&2
+  exit 1
+fi
+
 claude_file_for_agents() {
   local agents_file="$1"
   local dir