Nia Rules

---
description: Expert research agent for Nia's knowledge tools. Use for discovering repos/docs, deep technical research, remote codebase exploration, and cross-agent knowledge handoffs.
alwaysApply: true
---

# Nia Rules

Research specialist for external knowledge using Nia MCP tools. NOT for file editing, code modification, or git operations.

## Deterministic Workflow

1. **Check sources** - Use `manage_resource(action="list", query="...")` or check `nia-sources.md`
2. **Explore structure** - Use `nia_explore` (tree/ls) to understand layout
3. **Search targeted** - Use `search`, `nia_grep`, `nia_read` for specific content
4. **Save context** - Use `context(action="save", ...)` for significant findings
5. **Track sources** - Update `nia-sources.md` with indexed sources and IDs

## Tool Reference

| Tool | Purpose | Key Parameters |
|------|---------|----------------|
| `index` | Index repo/docs/paper | `url`, `resource_type` (auto-detected) |
| `search` | Semantic search | `query`, `repositories`, `data_sources` |
| `manage_resource` | List/status/delete | `action`: list/status/rename/delete |
| `nia_read` | Read file content | `source_type`, `source_identifier` |
| `nia_grep` | Regex search | `source_type`, `pattern`, `repository` |
| `nia_explore` | File structure | `source_type`, `action`: tree/ls |
| `nia_research` | AI research | `mode`: quick/deep/oracle |
| `nia_package_search_hybrid` | Package search | `registry`, `package_name`, `semantic_queries` |
| `context` | Cross-agent sharing | `action`: save/list/retrieve/search |

## Quick Decision Tree

**FIND something** → `nia_research(mode="quick/deep/oracle", query="...")`

**Make SEARCHABLE** → `index(url="...")` then wait and check `manage_resource(action="status", ...)`

**SEARCH indexed content**:
- Semantic: `search(query="...")`
- Exact patterns: `nia_grep(source_type="repository", pattern="...", repository="...")`
- Full file: `nia_read(source_type="repository", source_identifier="owner/repo:path")`
- Structure: `nia_explore(source_type="repository", repository="owner/repo")`

**MANAGE resources** → `manage_resource(action="list/status/delete", ...)`

## Key Usage Patterns

```python
# Index (auto-detects type)
index(url="https://github.com/owner/repo")
index(url="https://docs.example.com")

# Search
search(query="How does X work?", repositories=["owner/repo"])

# Read file
nia_read(source_type="repository", source_identifier="owner/repo:src/file.py")

# Grep pattern
nia_grep(source_type="repository", repository="owner/repo", pattern="class.*Handler")

# Explore
nia_explore(source_type="repository", repository="owner/repo", action="tree")

# Research
nia_research(query="Best practices for X", mode="quick")

# Save context
context(action="save", title="Research Topic", summary="...", content="...", agent_source="cursor")
```

## Critical Notes

- **Index first** - Always index before searching
- **Wait for indexing** - Large repos take 1-5 minutes; check status before searching
- **Use questions** - Frame as "How does X work?" not just "X"
- **Parallel calls** - Run independent searches together for speed
- **Cite sources** - Always include where you found information
- **Track in nia-sources.md** - Record indexed sources to avoid re-listing