Update instructions for humans and agents

3 files changed, 41 insertions, 9 deletions

diff --git a/AGENTS.md b/AGENTS.md
index a86f7dffb..412f6fa21 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,6 +1,23 @@
-# ALE Agent instructions
+# ALE Instructions
 
-1. Read documentation from `doc/ale-development.txt` to understand how to be an
-   ALE developer.
-2. Run Vader/Vim tests with `./run-tests -q --fast test/path/some_file.vader`
-3. When editing Lua code run Lua tests with `./run-tests -q --lua-only`
+## Basic Instructions
+
+Read documentation from @doc/ale-development.txt to understand how to be an
+ALE developer and how to match our standards.
+
+Run all tests quickly with `./run-tests -q --fast`, which picks the quickest
+version of Neovim we can run, and runs our linting checks.
+
+You can quickly check an individual Vader test file by passing them as arguments
+such as `./run-tests -q --fast test/path/some_file.vader`.
+
+You can quickly run all Lua tests with `./run-tests -q --lua-only`.
+
+
+For new Vim files, set `Author:` comments to the person doing the work.
+Do not use Codex, OpenAI, or other tool names as the author.
+
+## Writing Tests
+
+For `test/test-files` they should almost always be 0 bytes in size and files
+may be marked executable when testing searching for executables.
diff --git a/doc/ale-development.txt b/doc/ale-development.txt
index 32a9501f5..90c439d34 100644
--- a/doc/ale-development.txt
+++ b/doc/ale-development.txt
@@ -202,9 +202,24 @@ See |ale-development-linter-tests| for more information on how to write linter
 tests.
 
 When you add new linters or fixers, make sure to add them into the tables in
-supported-tools.md and |ale-supported-languages-and-tools.txt|. If you forget to
-keep them both in sync, you should see an error like the following in the
-builds run for GitHub Actions.
+`../supported-tools.md` and |ale-supported-languages-and-tools.txt|.
+
+The supported tools lists are very long, so please bear in mind the meanings
+of the emojis and special characters in the Vim help file.
+>
+    |      Key       |             Definition                                |
+    | -------------- | ----------------------------------------------------- |
+    |:speech_balloon:| Language Server Protocol (LSP)                        |
+    | :floppy_disk:  | Only runs on disk (see: `help ale-lint-file-linters`) |
+    |   :warning:    | Disabled by default                                   |
+<
+>
+    `^` No linters for text or Vim help filetypes are enabled by default.
+    `!!` These linters check only files on disk. See |ale-lint-file-linters|
+<
+
+If you forget to keep them both in sync, you should see an error like the
+following in the builds run for GitHub Actions.
 >
   ========================================
   diff supported-tools.md and doc/ale-supported-languages-and-tools.txt tables
diff --git a/supported-tools.md b/supported-tools.md
index 9e4a2cf2e..e330557cf 100644
--- a/supported-tools.md
+++ b/supported-tools.md
@@ -17,7 +17,7 @@ formatting.
 |      Key       |             Definition                                            |
 | -------------- | ----------------------------------------------------------------- |
 |:speech_balloon:| Language Server Protocol (LSP)                                    |
-| :floppy_disk:  | May only run on files on disk (see: `help ale-lint-file-linters`  |
+| :floppy_disk:  | May only run on files on disk (see: `help ale-lint-file-linters`) |
 |   :warning:    | Disabled by default                                               |
 
 ---