From cc0617437608ca11895476bdee031746866746ac Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Moritz=20Gro=C3=9F?= <hi@mgross.dev>
Date: Wed, 18 Feb 2026 03:15:30 +0100
Subject: [PATCH 1/2] add AGENTS.md

---
 AGENTS.md | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..8cee4405
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,34 @@
+# Agent Notes (MathCAT)
+
+Purpose: fast orientation for coding agents. try to keep low overlap with README.md etc., 
+but add common mistakes of AI agents here instead.
+
+## Project Scope
+- MathCAT converts MathML to speech, braille, and navigation output.
+- Core flow: `set_mathml()` -> `canonicalize.rs` -> optional `infer_intent.rs` -> `speech.rs` / `braille.rs`.
+
+## Rules System (`Rules/`)
+- YAML rules are loaded at runtime by domain:
+- Common per-language files:
+  - `ClearSpeak_Rules.yaml`, `SimpleSpeak_Rules.yaml`
+  - `SharedRules/`, `unicode.yaml`, `unicode-full.yaml`, `definitions.yaml`, `navigate.yaml`
+- `build.rs` can bundle rules into `rules.zip` when `include-zip` is enabled.
+
+## Translation Conventions
+- `t:` means untranslated or unverified.
+- `T:` means translated and verified.
+- tool for comparing rules across languages: `uv run --project PythonScripts audit-translations <language-code>`
+
+## Python Tooling (`uv`)
+- `uv` is the Python dependency and project manager for repo tooling. Use `uv run <command-name>`
+- In sandboxed runs, if needed:
+  - set `UV_CACHE_DIR=/tmp/uv-cache`
+  - rerun with escalated permissions if macOS `system-configuration` panics occur.
+- *always* self-validate: `ùv run pytest`
+
+## Agent Instructions
+- Do not mirror README content here; keep guidance agent-specific.
+- Avoid broad formatting sweeps; do not run `cargo fmt` in this repo.
+- Keep code/rule changes focused and validate with targeted tests first: `cargo test <relevant-tests>`
+- do not do any git commands unless explicitly asked for
+- Rust coverage is in `target/coverage/`.

From ba537583aabbe6361e448c730bbad424e8326841 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Moritz=20Gro=C3=9F?= <hi@mgross.dev>
Date: Wed, 18 Feb 2026 03:50:16 +0100
Subject: [PATCH 2/2] explain python package usage

---
 AGENTS.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/AGENTS.md b/AGENTS.md
index 8cee4405..295c4ca4 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -21,6 +21,7 @@ but add common mistakes of AI agents here instead.
 
 ## Python Tooling (`uv`)
 - `uv` is the Python dependency and project manager for repo tooling. Use `uv run <command-name>`
+- discuss new packages before adding them. use `uv add <package-name>` and `uv sync` on confirmation
 - In sandboxed runs, if needed:
   - set `UV_CACHE_DIR=/tmp/uv-cache`
   - rerun with escalated permissions if macOS `system-configuration` panics occur.