diff --git a/AGENTS.md b/AGENTS.md
index 1a450309e..66505a754 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -126,9 +126,21 @@ make install # build and install bd to ~/.local/bin (canonical)
certificate `--config=remote-exec`, agent hosts whose `~/.bazelrc` names the
executor neither. Make yours the default with a `build --config=...` line in
the gitignored `.bazelrc.local`, or pass `BAZEL_FLAGS=...` to make.
-- `go test` (`./scripts/test.sh`, `make test-go`) is an inner-loop
- convenience only. CI does not enforce it, and it skips nogo, gofmt and the
- guards; finish with `make test`.
+- Agents run tests only with `bazel test`, also while iterating on one
+ behavior: `bazel test //cmd/bd:bd_test --config=ci
+ --test_filter='^TestName$'` (a package's tests are
+ `//
:_test`, the root package's `//:beads_test`; one
+ `--test_filter` covers every target named). Results are cached by input,
+ so re-running an unchanged target is free and the cached result is the same
+ evidence. `--config=ci` sets `BEADS_TEST_SKIP=dolt`, so Dolt-backed tests
+ skip and still pass; run them with `--test_env=BEADS_TEST_SKIP=
+ --test_env=BEADS_TEST_DOLT_SERVER=local
+ --test_env=BEADS_TEST_REQUIRE_DOLT_CONTAINER=1` or their lane in
+ engdocs/TESTING.md. Bazel runs only the test files `BUILD.bazel` lists:
+ run `make bazel-sync` after adding one. Finish with `make test`.
+- Agents do not run `go test` (`./scripts/test.sh`, `make test-go`): CI does
+ not enforce it, it skips nogo, gofmt and the guards, and agent hosts may
+ refuse it. It stays a convenience for humans working offline.
- **Do NOT** use `go build -o bd ./cmd/bd`, `go install ./cmd/bd`, or raw
`go run ./cmd/bd ...`: they bypass the canonical build path, leave stale
binaries, and raw `go run` misses the `gms_pure_go` tag. Use `make install`,
diff --git a/engdocs/TESTING.md b/engdocs/TESTING.md
index d92a75a2e..2620ccd6c 100644
--- a/engdocs/TESTING.md
+++ b/engdocs/TESTING.md
@@ -96,7 +96,7 @@ a unit test: use the real boundary when the defect could live there.
| Need | Run | When |
|---|---|---|
| Docs-only validation | `git diff --check` and `make check-docs` | For prose-only changes; add any generated-doc or surface-specific link check the changed paths require. Do not run the full suite merely because a Markdown file changed. |
-| Focused red/green loop | `bazel test //path/to/package:package_test --config=ci --test_filter='^TestExactName$'`, or the plain-Go `./scripts/test.sh -run '^TestExactName$' ./path/to/package/...` | While writing or fixing one behavior. The `go test` loop is fine here; the Bazel targets below are the gate. |
+| Focused red/green loop | `bazel test //path/to/package:package_test --config=ci --test_filter='^TestExactName$'` | While writing or fixing one behavior. Agents use only this form; an unchanged target returns its cached result. Humans working offline may use the plain-Go `./scripts/test.sh -run '^TestExactName$' ./path/to/package/...`, which is not the gate. |
| Affected-package confidence | `bazel test //path/to/package/... --config=ci` | After the focused test passes; include directly affected neighbors when their contract changed. |
| Final gate | `make test` | Once after focused work on Go code is green: the whole test lane, mostly cache hits. |
| Another lane's risk | that lane's command from the table above | When the change touches what that lane covers (integration-tagged files, the Dolt server path, embedded Dolt, pure-Go builds). |
@@ -121,11 +121,12 @@ the suite CI gates on.
## Plain `go test` (Inner Loop)
-`./scripts/test.sh` is the plain-Go runner behind `make test-go`. It sources
-`.buildflags`, creates an isolated test environment, applies `.test-skip`, and
-defaults to a **25m per-package** Go-test timeout. The timeout is a hang
-backstop, not a target runtime. Override it only when diagnosing a legitimate
-slow path:
+This section is for humans working offline; agents run `bazel test` (see
+"Choose the Smallest Useful Test" above). `./scripts/test.sh` is the plain-Go
+runner behind `make test-go`. It sources `.buildflags`, creates an isolated
+test environment, applies `.test-skip`, and defaults to a **25m per-package**
+Go-test timeout. The timeout is a hang backstop, not a target runtime.
+Override it only when diagnosing a legitimate slow path:
```bash
TEST_TIMEOUT=30m ./scripts/test.sh ./cmd/bd/...