From 8f94086ed65068f24076a4df033792fd2990811f Mon Sep 17 00:00:00 2001
From: George Liu <eva2000@centminmod.com>
Date: Tue, 25 Nov 2025 15:55:44 +1000
Subject: [PATCH] add AGENTS.md for Codex etc

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

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..be62f12
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,99 @@
+## ALWAYS START WITH THESE COMMANDS FOR COMMON TASKS
+
+**Task: "List/summarize all files and directories"**
+
+```bash
+fd . -t f           # Lists ALL files recursively (FASTEST)
+# OR
+rg --files          # Lists files (respects .gitignore)
+```
+
+**Task: "Search for content in files"**
+
+```bash
+rg "search_term"    # Search everywhere (FASTEST)
+```
+
+**Task: "Find files by name"**
+
+```bash
+fd "filename"       # Find by name pattern (FASTEST)
+```
+
+### Directory/File Exploration
+
+```bash
+# FIRST CHOICE - List all files/dirs recursively:
+fd . -t f           # All files (fastest)
+fd . -t d           # All directories
+rg --files          # All files (respects .gitignore)
+
+# For current directory only:
+ls -la              # OK for single directory view
+```
+
+### BANNED - Never Use These Slow Tools
+
+* ❌ `tree` - NOT INSTALLED, use `fd` instead
+* ❌ `find` - use `fd` or `rg --files`
+* ❌ `grep` or `grep -r` - use `rg` instead
+* ❌ `ls -R` - use `rg --files` or `fd`
+* ❌ `cat file | grep` - use `rg pattern file`
+
+### Use These Faster Tools Instead
+
+```bash
+# ripgrep (rg) - content search 
+rg "search_term"                # Search in all files
+rg -i "case_insensitive"        # Case-insensitive
+rg "pattern" -t py              # Only Python files
+rg "pattern" -g "*.md"          # Only Markdown
+rg -1 "pattern"                 # Filenames with matches
+rg -c "pattern"                 # Count matches per file
+rg -n "pattern"                 # Show line numbers 
+rg -A 3 -B 3 "error"            # Context lines
+rg " (TODO| FIXME | HACK)"      # Multiple patterns
+
+# ripgrep (rg) - file listing 
+rg --files                      # List files (respects •gitignore)
+rg --files | rg "pattern"       # Find files by name 
+rg --files -t md                # Only Markdown files 
+
+# fd - file finding 
+fd -e js                        # All •js files (fast find) 
+fd -x command {}                # Exec per-file 
+fd -e md -x ls -la {}           # Example with ls 
+
+# jq - JSON processing 
+jq. data.json                   # Pretty-print 
+jq -r .name file.json           # Extract field 
+jq '.id = 0' x.json             # Modify field
+```
+
+### Search Strategy
+
+1. Start broad, then narrow: `rg "partial" | rg "specific"`
+2. Filter by type early: `rg -t python "def function_name"`
+3. Batch patterns: `rg "(pattern1|pattern2|pattern3)"`
+4. Limit scope: `rg "pattern" src/`
+
+### INSTANT DECISION TREE
+
+```
+User asks to "list/show/summarize/explore files"?
+  → USE: fd . -t f  (fastest, shows all files)
+  → OR: rg --files  (respects .gitignore)
+
+User asks to "search/grep/find text content"?
+  → USE: rg "pattern"  (NOT grep!)
+
+User asks to "find file/directory by name"?
+  → USE: fd "name"  (NOT find!)
+
+User asks for "directory structure/tree"?
+  → USE: fd . -t d  (directories) + fd . -t f  (files)
+  → NEVER: tree (not installed!)
+
+Need just current directory?
+  → USE: ls -la  (OK for single dir)
+```