# AGENTS.md

> context-mode MCP active. One unrouted command = 56 KB context flood. Follow routing rules.

---

## Tool Routing — MANDATORY

| Need | Tool |
|------|------|
| Library docs, API usage, framework setup | **context7** → `resolve_library_id` → `get_library_docs` |
| Codebase search, file analysis, indexing | **ctx** → see Tool Selection below |
| Fetch external URL | `ctx_fetch_and_index(url, source)` → `ctx_search(queries)` |

---

## Hard Rules

- ALWAYS `ctx_execute` — never read files directly into context
- NEVER scan entire project unless explicitly asked
- ALWAYS narrow scope before executing
- ALWAYS write artifacts to FILES — never inline — return path + 1-line desc
- Plan first → execute minimal steps → minimize token usage

---

## Think in Code — MANDATORY

Analyze / count / filter / compare / search / parse / transform:
→ write code via `ctx_execute(language, code)`, `console.log()` the answer only.
Do NOT read raw data into context. PROGRAM the analysis.

```
Language: JavaScript (Node.js built-ins only — fs, path, child_process)
Always: try/catch, handle null/undefined
1 script = replaces 10+ tool calls
```

---

## BLOCKED — do NOT attempt, do NOT retry

| Blocked | Use instead |
|---------|-------------|
| `curl`, `wget` in shell | `ctx_fetch_and_index(url, source)` |
| Inline HTTP: `fetch('http...`)`, `requests.get(`, `http.get(` | `ctx_execute(language, code)` — stdout only enters context |
| Direct web fetch of any kind | `ctx_fetch_and_index(url, source)` → `ctx_search(queries)` |

---

## REDIRECTED — use sandbox

| Situation | Don't | Use |
|-----------|-------|-----|
| Shell output >20 lines | direct shell | `ctx_batch_execute` or `ctx_execute(shell, ...)` |
| File reading for **analysis** | `read_file` | `ctx_execute_file(path, lang, code)` |
| File reading for **editing** | — | `read_file` ✓ |
| grep / large search results | inline grep | `ctx_execute(shell, "grep ...")` |
| Shell allowed commands | — | `git`, `mkdir`, `rm`, `mv`, `cd`, `ls`, `npm install`, `pip install` |

---

## Tool Selection Priority

```
1. DOCS      → context7: resolve_library_id → get_library_docs
               All library / API / framework questions.

2. GATHER    → ctx_batch_execute(commands, queries)
               Run all commands at once, auto-index, return search.
               1 call replaces 30+. Format: {label: "header", command: "..."}

3. FOLLOW-UP → ctx_search(queries: ["q1", "q2", ...])
               All questions in one array, one call.

4. PROCESS   → ctx_execute(language, code)
               ctx_execute_file(path, language, code)
               Sandbox — only stdout enters context.

5. WEB       → ctx_fetch_and_index(url, source) → ctx_search(queries)
               Raw HTML never enters context.

6. INDEX     → ctx_index(content, source)
               Store in FTS5 for later search. Use descriptive source labels.
```

---

## Search Strategy

1. Start targeted — file name, function name, keyword
2. Avoid broad queries like "explore project"
3. One `ctx_search` call, multiple queries as array

---

## Output Style

Terse. Technical exact. No fluff.
Drop: articles, filler (just/really/basically), pleasantries, hedging.
Fragments OK. Short synonyms. Code unchanged.
Pattern: `[thing] [action] [reason]. [next step].`
Auto-expand for: security warnings, irreversible actions, user confusion.

---

## ctx Commands

| Command | Action |
|---------|--------|
| `ctx stats` | Call `stats` MCP tool, display output verbatim |
| `ctx doctor` | Call `doctor` MCP tool, run returned shell cmd, display as checklist |
| `ctx upgrade` | Call `upgrade` MCP tool, run returned shell cmd, display as checklist |
| `ctx purge` | Call `purge` MCP tool with `confirm: true` — wipes knowledge base |

After `/clear` or `/compact`: knowledge base & session stats preserved. Use `ctx purge` to start fresh.