feat: Send user-defined context with `TERMINAL.md` (#3443)

This PR adds the ability to inject user-defined content into Atuin AI
requests, a la `AGENTS.md` or `CLAUDE.md`.

* `.atuin/TERMINAL.md` (or alternatively just `TERMINAL.md`) is checked in every directory from the cwd up to the root
* `~/.config/atuin/TERMINAL.md` (or equivalent config dir) is also
checked
* Supports Claude-style ``` !`` ``` and ```` ```!...``` ```` style shell
interpolation

2 files changed, 40 insertions, 0 deletions

diff --git a/docs/docs/ai/user-context.md b/docs/docs/ai/user-context.md
new file mode 100644
index 00000000..929ee579
--- /dev/null
+++ b/docs/docs/ai/user-context.md
@@ -0,0 +1,39 @@
+# Sending Additional Context in Atuin AI
+
+Atuin AI allows you to send additional context to the LLM beyond just your prompt, similar to `AGENTS.md`.
+
+## Additional Context Search Paths
+
+Atuin AI looks for additional context in `TERMINAL.md` and `.atuin/TERMINAL.md` files in the current directory and its parent directories. It also checks `TERMINAL.md` in your Atuin config directory (`~/.config/atuin/TERMINAL.md` by default). If it finds any of these files, it sends their contents as additional context to the LLM.
+
+Atuin AI will send at maximum 10 additional context files, prioritizing files found globally first and then other files in order of filesystem depth, shallowest to deepest, and each file is limited to 10,000 characters.
+
+## Dynamic Content
+
+You can send dynamic content by using shell substitution in your `TERMINAL.md` file:
+
+```markdown
+My username: !`whoami`
+```
+
+When Atuin AI reads this file, it will execute the `whoami` command and include its output in the context sent to the LLM. So if your username is `binarymuse`, the context sent to the LLM would include:
+
+```markdown
+My username: binarymuse
+```
+
+Atuin AI can also run substitutions for code blocks, to run multi-line commands. For example:
+
+````markdown
+```!
+node --version
+npm --version
+git status --short
+```
+````
+
+## Why not `AGENTS.md`?
+
+Most agent files are optimized for _coding_ agents: patterns, tools, coding style, and so on. This is great for coding agents, but not as useful for general-purpose agents. By using `TERMINAL.md` instead, we can provide a more flexible way to send additional context that is not tied to coding-specific patterns. This allows users to provide any kind of context they want, without being constrained by the structure of an agent file.
+
+If your agent file has relevant information, you can instruct the LLM in `TERMINAL.md` to read from it.
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 1d6d7006..84ae106d 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -100,6 +100,7 @@ nav:
   - AI:
       - Introduction: ai/introduction.md
       - Settings: ai/settings.md
+      - "User-Defined Context": ai/user-context.md
       - "Tools & Permissions": ai/tools-permissions.md
   - Known Issues: known-issues.md
   - Integrations: integrations.md