. d Better docs and agents.md

Co-authored-by: Llewellyn Falco <llewellyn.falco@gmail.com>
Co-authored-by: Stefan Sator <satorstefan@users.noreply.github.com>

Author: 3 people

README.md

@@ -50,3 +50,8 @@ No files were deleted.
 ```
 <sup><a href='/test_remove_abandoned_files.test__reject.approved.txt#L1-L7' title='Snippet source file'>snippet source</a> | <a href='#snippet-test_remove_abandoned_files.test__reject.approved.txt' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
+
+## See Also
+
+- [Agents](docs/agents.md) - AI agent instructions and script documentation
+- [Map](docs/map.md) - Codebase structure overview

docs/agents.md

@@ -0,0 +1,28 @@
+# Agents
+
+## About the Scripts
+
+ApprovalTests (Java, Python, Go, Node) creates a `.approval_tests_temp/` directory when run,
+and will download these scripts into that directory when needed.
+
+### approve_all.py
+
+Batch approves all mismatched approval test files by copying `.received` files to `.approved` files.
+
+**Usage:** `.approval_tests_temp/approve_all.py`
+
+**Behavior:**
+- Displays count of mismatched files
+- Copies `.received` to `.approved` for each mismatch
+- Reports number of files approved
+
+### remove_abandoned_files.py
+
+Identifies and optionally deletes orphaned `.approved` files that no longer have corresponding tests.
+
+**Usage:** `.approval_tests_temp/remove_abandoned_files.py`
+
+**Behavior:**
+- Lists all abandoned files found
+- Prompts user for confirmation before deletion
+- Deletes files only if user confirms

docs/map.md

@@ -0,0 +1,18 @@
+# Codebase Map
+
+## Directory Structure
+
+**Root**
+- Main scripts: `approve_all.py`, `remove_abandoned_files.py`
+- Tests: `test_*.py` and `*.approved.txt` files
+- Build/test scripts: `build_and_test*`, `format_code*`
+- Configuration: `pyproject.toml`, `requirements.dev.txt`, `mdsnippets.json`
+
+**docs/**
+- Documentation files
+
+**docs/how_to/**
+- Usage guides and instructions
+
+**.github/**
+- GitHub Actions workflows and CI configuration