# Knot CLI: Agent Skill Index

**Quick navigation for using the `knot` CLI to search, explore, and analyze indexed codebases.**

---

## 📥 Quick Download

Get all agent-skills documentation in one command:

```bash
# Option 1: From the repository (recommended)
bash scripts/install-agent-skills.sh

# Option 2: Specify custom directory
bash scripts/install-agent-skills.sh ~/.config/knot/docs

# Option 3: Download and install (one-liner)
curl -fsSL https://raw.githubusercontent.com/user/knot/master/scripts/install-agent-skills.sh | bash
```

This creates a `.knot-agent-skills` directory (or your custom location) with:
- `search.md` — Semantic code discovery guide
- `callers.md` — Reverse dependency lookup guide  
- `explore.md` — File anatomy discovery guide
- `workflows.md` — Common patterns & best practices

---

## Prerequisites

- `knot` CLI binary installed and in PATH
- Repository indexed via `knot-indexer`
- Environment variables configured:
  - `QDRANT_URL` (default: http://localhost:6333)
  - `QDRANT_COLLECTION` (default: knot)
  - `NEO4J_URI` (default: bolt://localhost:7687)
  - `NEO4J_USER` and `NEO4J_PASSWORD`

---

## Core Commands at a Glance

| Command | Purpose | When to Use |
|---------|---------|-----------|
| **`knot search "<query>"`** | Find code by semantic meaning | Exploring features, discovery, pattern location |
| **`knot callers "<EntityName>"`** | Find who uses an entity (reverse dependencies) | Impact analysis, dead code detection, understanding usage |
| **`knot explore "<file_path>"`** | List all entities in a file | Understand file structure, navigate codebases |

---

## 1. Search: Semantic Code Discovery

**Command:** `knot search "<query>" [--max-results N] [--repo name]`

**Purpose:** Find code entities by what they *do*, not by exact names.

**Example:**
```bash
knot search "user authentication" --max-results 10
```

**Key points:**
- Use natural language descriptions
- Great for exploratory searches
- Returns functions, classes, methods organized by type
- Fast (< 1 second response time)

📖 **Full guide:** [`docs/agent-skills/search.md`](docs/agent-skills/search.md)

---

## 2. Callers: Reverse Dependency Lookup

**Command:** `knot callers "<EntityName>" [--repo name]`

**Purpose:** Find all references to a specific entity (Who uses this? What breaks if I change it?)

**Example:**
```bash
knot callers "PaymentProcessor" --repo billing-service
```

**⚠️ CRITICAL WARNING:**

For common method names (`accept`, `process`, `handle`, `get`, `run`, etc.), **use signature fragments** to avoid thousands of irrelevant results:

```bash
# ❌ Bad - Bare name (returns too much)
knot callers "handle"

# ✅ Good - With signature fragment (targeted)
knot callers "handle(Request"
```

**Key points:**
- Groups results by relationship type (Calls, Extends, Implements, References)
- Shows line numbers for navigation
- Medium speed (1-2 seconds for graph traversal)
- Essential for impact analysis and dead code detection

📖 **Full guide with critical rules:** [`docs/agent-skills/callers.md`](docs/agent-skills/callers.md)

---

## 3. Explore: File Anatomy

**Command:** `knot explore "<file_path>" [--repo name]`

**Purpose:** List all classes, methods, functions, and properties in a file.

**Example:**
```bash
knot explore "src/services/user.ts"
```

**Output includes:**
- Entity names and line numbers
- Method signatures
- Decorators/annotations
- Documentation (first line)

**Key points:**
- Very fast (< 100ms)
- Organized by entity type
- Perfect for quick file overview
- Includes links for editor navigation

📖 **Full guide:** [`docs/agent-skills/explore.md`](docs/agent-skills/explore.md)

---

## Common Workflows

### Workflow 1: Feature Discovery

1. **Search** for the feature:
   ```bash
   knot search "user login flow" --max-results 10
   ```

2. **Explore** files from results:
   ```bash
   knot explore "src/auth/login.ts"
   ```

3. **Find** dependencies:
   ```bash
   knot callers "loginUser"
   ```

### Workflow 2: Impact Analysis Before Refactoring

1. Find the entity to change
2. Run `knot callers` to see all dependents
3. Run `knot explore` on each caller to understand impact
4. Plan refactoring with confidence

### Workflow 3: Dead Code Detection

1. Run `knot callers "suspectedFunction"`
2. If "No references found" → likely dead code
3. Verify with `knot explore "src/file.ts"`

📖 **More workflows:** [`docs/agent-skills/workflows.md`](docs/agent-skills/workflows.md)

---

## Quick Tips

- **Omit `--repo`** when in the repository directory (auto-detected)
- **Search semantically first**, then drill down with explore/callers
- **Use `--max-results 20`** for broad searches, `--max-results 5` for focused results
- **Combine commands** for deep context: Search → Explore → Callers → Explore
- **For common method names, always use signature fragments** (see Callers guide)

---

## Command Reference

```bash
# Semantic search
knot search "description" --max-results 10 --repo my-repo

# Find references (avoid common names without signature)
knot callers "EntityName" --repo my-repo
knot callers "method(ParamType" --repo my-repo    # Signature fragment

# File structure
knot explore "src/path/to/file.ts" --repo my-repo

# Combine for analysis
knot search "thing" && knot explore "result.ts" && knot callers "Entity"
```

---

## Choosing Which Skill to Read

- **First time using knot?** → Read [`search.md`](docs/agent-skills/search.md)
- **Need to find who uses something?** → Read [`callers.md`](docs/agent-skills/callers.md) (includes critical warnings)
- **Want to understand a file's structure?** → Read [`explore.md`](docs/agent-skills/explore.md)
- **Learning common patterns?** → Read [`workflows.md`](docs/agent-skills/workflows.md)

---

## CLI vs MCP Server

Both tools access the **same databases** and produce **identical results**:

| Scenario | CLI | MCP |
|----------|-----|-----|
| Terminal/scripting | ✅ | ❌ |
| IDE integration | ❌ | ✅ |
| LLM-based analysis | ✅ | ✅ |
| CI/CD pipelines | ✅ | ❌ |

---

## Performance Notes

- **Search:** < 1 sec (vector similarity in Qdrant)
- **Callers:** 1-2 sec (graph traversal in Neo4j)
- **Explore:** < 100ms (direct file lookup)

For large codebases, use `--repo` and `--max-results` to optimize speed.

---

## Troubleshooting

**"No results"** → Try broader search terms, check repo name, re-index with `knot-indexer`

**"Too many results"** → Be more specific in search, use signature fragments for common names, reduce `--max-results`

**"No references found" for a method** → May be dead code, or called via reflection/strings

**Connection errors** → Check `QDRANT_URL`, `NEO4J_URI`, and database services running

---

## Questions?

Each skill file contains detailed examples, troubleshooting guides, and language-specific usage patterns:

- 📖 [`docs/agent-skills/search.md`](docs/agent-skills/search.md) — Semantic search patterns
- 📖 [`docs/agent-skills/callers.md`](docs/agent-skills/callers.md) — Reverse dependencies (with critical rules)
- 📖 [`docs/agent-skills/explore.md`](docs/agent-skills/explore.md) — File exploration
- 📖 [`docs/agent-skills/workflows.md`](docs/agent-skills/workflows.md) — Common workflows & best practices
