Merge pull request #1 from PennockTech/claude/evaluate-aifr-skills-748FH

Restructure aifr documentation for clarity and routing guidance

Author: philpennock

internal/mcpserver/skill.md

@@ -1,218 +1,70 @@
 # aifr — AI File Reader
 
-Use `aifr` instead of shell pipelines (`sed -n`, `find | grep`, `head/tail`)
-for reading files, searching content, and browsing git trees. It is always
-safe (read-only) and always scoped (enforces allow/deny lists with a built-in
-sensitive-file blocklist).
-
-## When to Use aifr
-
-- Reading file contents (instead of `cat`, `head`, `tail`, `sed -n`)
-- Searching file content (instead of `grep`, `rg`)
-- Finding files by name/pattern (instead of `find`)
-- Listing directory contents (instead of `ls`, `find`)
-- Getting file metadata (instead of `stat`)
-- Reading files from git history without checkout
-- Comparing files or git refs (line diff or byte-level cmp)
-- Counting lines/words/bytes (instead of `wc`)
-- Computing file checksums (instead of `sha256sum`, `md5sum`)
-- Hex-dumping binary files (instead of `xxd`, `hexdump`)
-- Resolving git refs to commit hashes (instead of `git rev-parse`)
-- System inspection: OS, date, hostname, uptime, network, routing (instead of `uname`, `date`, `hostname`, `ip addr`)
-- Querying system databases (instead of `getent`, `grep /etc/passwd`, `cut`)
-
-## CLI Commands
-
-### Read file contents
-```
-aifr read <path>
-aifr read --lines 1:50 <path>
-aifr read --chunk-id <token>
-aifr read HEAD:src/main.go
-aifr read myrepo:v2.0:config.toml
-```
-
-### Concatenate multiple files
-```
-aifr cat file1.go file2.go file3.go
-aifr cat --format text --divider xml file1.go file2.go
-aifr cat --name '*.go' --exclude-path '**/vendor/**' ./src/
-aifr cat --name '*.go' --lines 10 --divider plain --format text .
-aifr cat --name '*.yaml' --max-depth 2 ./config/
-```
-
-### Get file/directory metadata
-```
-aifr stat <path>
-aifr stat HEAD:README.md
-```
-
-### List directory
-```
-aifr list <path>
-aifr list --depth -1 <path>
-aifr list --pattern "*.go" --type f <path>
-aifr list HEAD:src/
-```
-
-### Search content (grep-like)
-```
-aifr search "pattern" <path>
-aifr search --fixed-string "exact text" <path>
-aifr search --ignore-case --context 2 "TODO" <path>
-aifr search --include "*.go" "func.*Handler" ./
-```
-
-### Find files
-```
-aifr find --name "*.go" <path>
-aifr find --type f --min-size 1024 <path>
-aifr find --newer-than 24h <path>
-```
-
-### Git refs and log
-```
-aifr refs
-aifr refs --branches --tags
-aifr refs /path/to/repo
-aifr log --max-count 10
-aifr log HEAD
-aifr log /path/to/repo:main
-```
-
-### Compare files
-```
-aifr diff file1.go file2.go
-aifr diff --cmp file1.bin file2.bin      # byte-level comparison
-aifr diff HEAD~1:main.go main.go
-aifr diff main:lib.go feature:lib.go
-```
-
-### Count lines/words/bytes
-```
-aifr wc file.go
-aifr wc -l *.go
-aifr wc --total-only -l src/**/*.go      # combined total only
-aifr wc HEAD:README.md
-```
-
-### File checksums
-```
-aifr checksum file.go
-aifr checksum -a sha512 *.go
-aifr checksum -a sha3-256 -e base64 file.go
-aifr checksum HEAD:README.md
-```
-
-### Hex dump
-```
-aifr hexdump binary.dat
-aifr hexdump -s 1024 -l 512 binary.dat   # offset + length
-aifr hexdump HEAD:binary.dat
-```
-
-### Git reflog
-```
-aifr reflog                                  # HEAD reflog
-aifr reflog main                             # branch reflog
-aifr reflog --max-count 10 HEAD
-```
-
-### Git stash list
-```
-aifr stash-list
-aifr stash-list --max-count 5
-```
-
-### Resolve git refs
-```
-aifr rev-parse HEAD
-aifr rev-parse main
-aifr rev-parse --repo myrepo v2.0
-aifr rev-parse HEAD~3
-```
-
-### System inspection
-```
-aifr sysinfo
-aifr sysinfo --sections date             # just date/time
-aifr sysinfo --sections os,hostname,uptime
-```
-
-### Git config
-```
-aifr git-config remote.origin.url             # local key lookup
-aifr git-config --scope merged user.email     # merged with includes
-aifr git-config --identity                    # structured identity (merged)
-aifr git-config --remotes                     # structured remotes
-aifr git-config --branches                    # structured branches
-aifr git-config --regexp 'branch\..*\.remote' # pattern match
-aifr git-config --section remote.origin       # section listing
-aifr git-config --list --scope local          # dump local config
-```
-
-### Query system databases
-```
-aifr getent passwd                           # all users
-aifr getent passwd root                      # lookup by name
-aifr getent passwd 1000                      # lookup by UID
-aifr getent passwd --fields name,uid,home    # field selection
-aifr getent group docker                     # group lookup
-aifr getent services --fields name,port 443  # service by port
-```
-
-### Find commands in PATH
-```
-aifr pathfind git
-aifr pathfind 'git-*'
-aifr pathfind python3 --search-list 'envvar:PATH'
-aifr pathfind javac --search-list 'dirlist:/usr/lib/jvm/bin:/usr/bin'
-```
-
-### Other
-```
-aifr config          # show effective configuration
-aifr sensitive       # list sensitive file patterns (for auditing)
-aifr version         # version info
-```
-
-## Git Path Syntax
-
-Git objects are addressed as `[repo:]<ref>:<path>`:
-- `HEAD:README.md` — HEAD of auto-detected repo
-- `main:src/lib.go` — main branch
-- `v2.0:config.toml` — tag v2.0
-- `HEAD~3:file.go` — 3 commits back
-- `myrepo:main:src/` — named repo "myrepo" at branch main
-- `/path/to/repo:HEAD:README.md` — repo at filesystem path
-
-## Chunked Reading
-
-Large files are returned in chunks. Use the continuation token to read more:
-1. `aifr read large-file.log` → returns first chunk + `continuation` token
-2. `aifr read --chunk-id <token>` → returns next chunk
-3. Repeat until `"complete": true`
-
-## Error Handling
-
-- `ACCESS_DENIED_SENSITIVE` — file matches sensitive pattern (credentials, keys, etc.).
-  Do NOT retry. Ask the user to read it manually if needed.
-- `ACCESS_DENIED` — path is outside allow-list or in deny-list.
-- `NOT_FOUND` — path does not exist.
-- `STALE_CONTINUATION` — file changed since continuation token was issued. Re-read from start.
-
-## Output
-
-All commands output JSON by default. Use `--format text` for human-readable output.
-
-## MCP Server
-
-`aifr mcp` starts the MCP server (stdio by default). The same operations are
-available as MCP tools: `aifr_read`, `aifr_cat`, `aifr_stat`, `aifr_list`,
-`aifr_search`, `aifr_find`, `aifr_refs`, `aifr_log`, `aifr_diff`,
-`aifr_pathfind`, `aifr_wc`, `aifr_checksum`, `aifr_hexdump`,
-`aifr_rev_parse`, `aifr_sysinfo`, `aifr_getent`, `aifr_reflog`,
-`aifr_stash_list`, `aifr_self`, `aifr_git_config`.
-
-For `aifr_cat`, use `format="text"` with `divider="xml"` for token-efficient
-multi-file reading with `<file path="...">` wrappers.
+Read-only access to filesystem, git trees, and system state.
+All aifr_* tool calls are permission-free — no Bash approval prompts.
+
+## Routing Rules
+
+ALWAYS prefer aifr_* tools over Bash for read-only operations.
+
+| Instead of | Use |
+|---|---|
+| `cat`, `head`, `tail`, `sed -n` | `aifr_read` |
+| reading 2+ files separately | `aifr_cat` (one call) |
+| `ls`, `tree` | `aifr_list` |
+| `grep -r`, `rg` | `aifr_search` |
+| `find` | `aifr_find` |
+| `stat` | `aifr_stat` |
+| `diff` | `aifr_diff` |
+| `wc` | `aifr_wc` |
+| `sha256sum`, `md5sum` | `aifr_checksum` |
+| `xxd`, `hexdump` | `aifr_hexdump` |
+| `git log` | `aifr_log` |
+| `git branch`, `git tag` | `aifr_refs` |
+| `git show <ref>:<path>` | `aifr_read` with ref:path |
+| `git diff <ref>` | `aifr_diff` with ref:paths |
+| `git rev-parse` | `aifr_rev_parse` |
+| `git reflog` | `aifr_reflog` |
+| `git stash list` | `aifr_stash_list` |
+| `git config` | `aifr_git_config` |
+| `uname`, `date`, `hostname`, `uptime` | `aifr_sysinfo` |
+| `ip addr`, `ip route` | `aifr_sysinfo` (sections: network, routing) |
+| `getent`, `grep /etc/passwd`, `id` | `aifr_getent` |
+| `which`, `command -v`, `type -p` | `aifr_pathfind` |
+
+### Pipeline detection
+
+If you are about to construct a shell pipeline (`|`), stop — aifr handles it
+in one call. Examples: `find | xargs grep` → `aifr_search` with `include`,
+`find | xargs cat` → `aifr_cat` with `name`, `cat | head -N` → `aifr_read`
+with `lines`, `cat | wc` → `aifr_wc`, `git log | head` → `aifr_log` with
+`max_count`, `ls | sort` → `aifr_list` with `sort`, `cat /etc/passwd | grep`
+→ `aifr_getent` with `key`.
+
+### With built-in Read / Grep / Glob tools
+
+- **Prefer aifr_read** for: git ref paths (`HEAD:file.go`), line ranges, chunked large files
+- **Prefer aifr_cat** over multiple Read calls when reading 2+ related files
+- **Always use aifr** for: git ops, system queries, diff, wc, checksum, hexdump (no built-in equivalent)
+- Built-in Read/Grep/Glob remain fine for simple single-file reads and basic searches
+
+## Git Ref Path Syntax
+
+`[repo:]<ref>:<path>` — reads from git object store, no checkout.
+Examples: `HEAD:README.md`, `main:src/lib.go`, `v2.0:config.toml`, `HEAD~3:file.go`, `myrepo:main:src/`
+
+## Key Patterns
+
+**Multi-file**: `aifr_cat(root=".", name="*.go", format="text", divider="xml")` → `<file path="...">content</file>` per file. Use `lines` for head mode, `exclude_path` to skip directories.
+
+**Chunked read**: `aifr_read(path=...)` → get continuation token → `aifr_read(path=..., chunk_id="<token>")` → repeat until `complete: true`.
+
+**Git config**: `structured="identity"` for name/email, `structured="remotes"`, `structured="branches"`. Use `scope="merged"` for full cascade with gitdir: includes.
+
+**System info**: `aifr_sysinfo(sections=["date"])` for current date/time/year. Sections: os, date, hostname, uptime, network, routing.
+
+## Errors
+
+- `ACCESS_DENIED_SENSITIVE` — credential file. **Do NOT retry.** Tell user to read manually.
+- `STALE_CONTINUATION` — file changed since chunk issued. Re-read from start.
+- `ACCESS_DENIED` — outside allow-list. `NOT_FOUND` — path doesn't exist.