Rewrite section on acceptance tests in AGENTS.md (#4476)

## Changes
Update AGENTS.md with regard to acceptance tests.

## Why
Things I want to correct:
- ClaudeCode updates out.test.toml instead of test.toml
- ClaudeCode tries to run subtest by setting env var
DATABRICKS_BUNDLE_ENGINE=direct go test ...
- ClaudeCode does not use scripts from acceptance/bin
- ClaudeCode is confused when updating tests if different variants
generate different output.txt, overwriting each other.

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: denik

AGENTS.md

@@ -148,54 +148,39 @@ When writing tests, please don't include an explanation in each
 test case in your responses. I am just interested in the tests.
 
 ### Acceptance Tests
-- Located in `acceptance/` with nested directory structure
-- Each test directory contains `databricks.yml`, `script`, and `output.txt`
-- Run with `go test ./acceptance -run TestAccept/bundle/<path>/<to>/<folder> -tail -test.v`
-- Use `-update` flag to regenerate expected output files
-- When a test fails because it has an old output, just run it one more time with an `-update` flag instead of changing the `output.txt` directly
-
-**When asked to update acceptance tests, follow this workflow**:
-
-1. **Run the update command**:
-   - For all acceptance tests: `make test-update`
-   - When asked to update acceptance tests for templates specifically: `make test-update-templates`
-
-2. **Verify code quality**:
-   - Run `make fmt` and `make lint`
-   - **Critical**: If these commands modify any files in `acceptance/`, this indicates an issue in the source files (e.g., in `libs/template/templates/` for template tests)!
-
-3. **Fix the root cause**:
-   - **Never manually edit files in `acceptance/`** - they are auto-generated outputs
-   - Find and fix the corresponding source file that generated the problematic acceptance test output
-   - For template tests: fix files in `libs/template/templates/`
-   - Common issues: trailing whitespace, missing/extra newlines, formatting problems
-
-4. **Regenerate after fixing**:
-   - After fixing the source files, run the update command again (e.g., `make test-update-templates`)
-   - This regenerates the acceptance test outputs from the corrected sources
-   - Now `make fmt` and `make lint` should pass with no changes
-
-**Example workflow**:
-```bash
-# Update acceptance tests
-make test-update  # or make test-update-templates for templates only
-
-# Check for issues - if these modify files in acceptance/, you have a source file problem
-make fmt
-make lint
-
-# If there are modifications in acceptance/:
-# 1. Find the corresponding source file (e.g., in libs/template/templates/ for templates)
-# 2. Fix the issue there (e.g., whitespace, newlines)
-# 3. Regenerate from the fixed source
-make test-update  # or make test-update-templates
-
-# Verify everything is clean
-make fmt    # Should show no changes now
-make lint   # Should show no issues now
-```
 
-**Key principle**: Files in `acceptance/` are outputs, not sources. Always fix the source files and regenerate.
+- Located in `acceptance/` with nested directory structure.
+- Each test directory contains `databricks.yml`, `script`, and `output.txt`.
+- Source files: `test.toml`, `script`, `script.prepare`, `databricks.yml`, etc.
+- Tests are configured via `test.toml`. Config schema and explanation is in `acceptance/internal/config.go`. Config is inherited from parent directories. Certain options are also dumped to `out.test.toml` so that inherited values are visible on PRs.
+- Generated output files start with `out`: `output.txt`, `out.test.toml`, `out.requests.txt`. Never edit these directly — use `-update` to regenerate. Exception: mass string replacement when the change is predictable and much cheaper than re-running the test suite.
+- Run a single test: `go test ./acceptance -run TestAccept/bundle/<path>/<to>/<folder>`
+- Run a specific variant by appending EnvMatrix values to the test name: `go test ./acceptance -run 'TestAccept/.../DATABRICKS_BUNDLE_ENGINE=direct'`. When there are multiple EnvMatrix variables, they appear in alphabetical order.
+- Useful flags: `-v` for verbose output, `-tail` to follow test output (requires `-v`), `-logrequests` to log all HTTP requests/responses (requires `-v`).
+- Run tests on cloud: `deco env run -i -n aws-prod-ucws -- <go test command>` (requires `deco` tool and access to test env).
+- Use `-update` flag to regenerate expected output files. When a test fails because of stale output, re-run with `-update` instead of editing output files.
+- All EnvMatrix variants share the same output files — they MUST produce identical output. Exception: filenames containing `$DATABRICKS_BUNDLE_ENGINE` (e.g. `output.direct.txt`) are recorded per-engine.
+- `-update` with divergent variant outputs is destructive: overwrites with last variant, breaking others. To debug: run a single variant you consider correct with `-update`, then debug the other variant to find why it diverges.
+- `test.toml` is inherited — put common options into a parent directory.
+- Add test artifacts (e.g. `.databricks`) to `Ignore` in `test.toml`.
+- `script.prepare` files from parent directories are concatenated into the test script — use them for shared bash helpers.
+
+**Helper scripts** in `acceptance/bin/` are available on `PATH` during test execution:
+- `contains.py SUBSTR [!SUBSTR_NOT]` — passthrough filter (stdin→stdout) that checks substrings are present (or absent with `!` prefix). Errors are reported on stderr.
+- `print_requests.py //path [^//exclude] [--get] [--sort] [--keep]` — print recorded HTTP requests matching path filters. Requires `RecordRequests=true` in `test.toml`. Clears `out.requests.txt` afterwards unless `--keep`. Use `--get` to include GET requests (excluded by default). Use `^` prefix to exclude paths.
+- `replace_ids.py [-t TARGET]` — read deployment state and add `[NAME_ID]` replacements for all resource IDs.
+- `read_id.py [-t TARGET] NAME` — read ID of a single resource from state, print it, and add a `[NAME_ID]` replacement.
+- `add_repl.py VALUE REPLACEMENT` — add a custom replacement (VALUE will be replaced with `[REPLACEMENT]` in output).
+- `update_file.py FILENAME OLD NEW` — replace all occurrences of OLD with NEW in FILENAME. Errors if OLD is not found. Cannot be used on `output.txt`.
+- `find.py REGEX [--expect N]` — find files matching regex in current directory. `--expect N` to assert exact count.
+- `diff.py DIR1 DIR2` or `diff.py FILE1 FILE2` — recursive diff with test replacements applied.
+- `print_state.py [-t TARGET] [--backup]` — print deployment state (terraform or direct).
+- `edit_resource.py TYPE ID < script.py` — fetch resource by ID, execute Python on it (resource in `r`), then update it. TYPE is `jobs` or `pipelines`.
+- `jq` is also available for JSON processing.
+
+**Update workflow**: Run `make test-update` to regenerate outputs. Then run `make fmt` and `make lint` — if these modify files in `acceptance/`, there's an issue in source files. Fix the source, regenerate, and verify lint/fmt pass cleanly.
+
+**Template tests**: Tests in `acceptance/bundle/templates` include materialized templates in output directories. These directories follow the same `out` convention — everything starting with `out` is generated output. Sources are in `libs/template/templates/`. Use `make test-update-templates` to regenerate. If linters or formatters find issues in materialized templates, do not fix the output files — fix the source in `libs/template/templates/`, then regenerate.
 
 # Logging