# Cursor Indexing Setup Guide

**Last Updated:** 2026-02-12

## Overview

This guide explains how Cursor IDE handles file indexing and how to ensure that important directories like `docs/` and `.cursor/rules/` are accessible to AI agents via `@` mentions.

## Index Optimization

Cursor indexes ~9.5K files. To reduce indexing and improve performance:

- **`.cursorignore`** – Full exclusions (files not indexed, not @-mentionable). Excludes: images (`.webp`, `.svg`, `.jpg`, etc.), `node_modules`, `vendor`, large data dirs.
- **`.cursorindexingignore`** – Index-only exclusions. Files remain @-mentionable but are not indexed for search. Excludes: `docs/content/blog/posts/**/data/`, `docs/data/**/*.json`.

See [CURSOR_INDEXING_BASELINE.md](CURSOR_INDEXING_BASELINE.md) and [CURSOR_INDEXING_OPTIMIZATION.md](CURSOR_INDEXING_OPTIMIZATION.md) for details.

## Problem: Files Not Accessible in Cursor

If you find that files in `docs/` or `.cursor/rules/` cannot be referenced using `@` mentions in Cursor, it's likely because:

1. **`.gitignore` is blocking them** - Cursor respects `.gitignore` by default
2. **`.cursorignore` patterns are incorrect** - Negation patterns must be properly formatted
3. **Pattern order matters** - Negations must come after ignore patterns

## Understanding Ignore Files

### `.gitignore` vs `.cursorignore` vs `.cursorindexingignore`

Cursor IDE uses three ignore mechanisms:

- **`.gitignore`**: Git ignores these files, and Cursor respects `.gitignore` by default
- **`.cursorignore`**: Full exclusions – files are not indexed and not @-mentionable (security, performance)
- **`.cursorindexingignore`**: Index-only exclusions – files are not indexed but **remain @-mentionable**. Use for large data you rarely need in search but may need occasionally via `@path`

### How Cursor Processes Ignore Files

1. Cursor first reads `.gitignore` patterns
2. Then applies `.cursorignore` patterns
3. `.cursorindexingignore` limits indexing only (files stay accessible via @)
4. Patterns are processed in order - later patterns can override earlier ones
5. Negation patterns (`!`) only work if the path was previously ignored

### Image Exclusions (`.cursorignore`)

Image formats have no semantic value for AI indexing. Excluded: `*.webp`, `*.svg`, `*.jpg`, `*.jpeg`, `*.gif`, `*.ico`, `*.png`, `*.pdf`, `*.mp4`. Use `@path/to/image.webp` if you need a specific image.

## Solution: Proper `.cursorignore` Configuration

To make `docs/` and `.cursor/rules/` accessible in Cursor, add these patterns at the **very top** of `.cursorignore`:

```gitignore
# Explicitly include docs/ and .cursor/ directories for Cursor indexing
# Must be at the very top - Cursor respects .gitignore, so we need to override
# These directories are ignored in .gitignore but we want them accessible in Cursor
# Simply unignore them - no need to ignore first since .gitignore already does that
!docs/
!docs/**
!.cursor/
!.cursor/**
!.cursor/rules/
!.cursor/rules/**
```

### Pattern Quirks and Limitations

- **Patterns are relative to project root** – Same as `.gitignore`. Paths like `docs/data/*.json` match from repo root.
- **Test `.cursorignore` with git** – `git check-ignore -v path/to/file` validates `.cursorignore` patterns. Note: `git check-ignore` does **not** read `.cursorindexingignore`; use `verify-index-config.py` instead.
- **Large codebases** – Forum reports indicate Cursor may not apply ignore rules when indexing folders with "too many files." If index stays high after Delete Index + Sync, see [CURSOR_INDEXING_DEBUGGING.md](CURSOR_INDEXING_DEBUGGING.md).
- **Trailing slash** – `docs/archive/` matches the directory and everything under it. Use `*` for single path segment, `**` for zero or more path segments (per gitignore spec).

### Pattern Explanation

1. **`!docs/`** - Unignore the directory itself (overrides `.gitignore`)
2. **`!docs/**`** - Unignore all contents recursively
3. Same pattern for `.cursor/` and `.cursor/rules/`

### Why This Works

- `.gitignore` already ignores these directories (lines 124 and 174)
- Cursor respects `.gitignore` by default, so we need to explicitly override it
- The negation patterns (`!docs/`, `!docs/**`) tell Cursor to include them despite `.gitignore`
- **No need to ignore first** - since `.gitignore` already does that, we just need to unignore
- Pattern order is critical - unignore patterns must be at the very top of `.cursorignore`

## Verification

### Index Analysis Script

Simulate ignore behavior and report file counts:

```bash
python3 v2/scripts/dev-helpers/analyze-cursor-index.py
python3 v2/scripts/dev-helpers/analyze-cursor-index.py --output docs/development/cursor-index-baseline.json
```

Use before/after optimization to compare indexed counts.

### After Changing Ignore Files

1. **Cursor Settings** > Indexing & Docs > **Delete Index** > **Sync**
2. Wait for indexing to complete
3. Note the new "X files" count in Cursor UI
4. Run the analysis script and compare to baseline: `python3 v2/scripts/dev-helpers/analyze-cursor-index.py`
5. **If changes don't apply:** Restart Cursor, then run Delete Index + Sync again

See [Cursor: Ignore files](https://docs.cursor.com/context/ignore-files) and [Codebase indexing](https://docs.cursor.com/context/codebase-indexing).

### Manual Testing

1. **In Cursor Chat**, type `@` and check if files appear:

   - `@docs/README.md` should appear
   - `@docs/ai/cursor-playbook.md` should appear
   - `@.cursor/rules/global.mdc` should appear
   - `@docs/content/blog/posts/ratgeber/gastronomie-mindestlohn/data/faq-questions.json` – should appear (cursorindexingignore = @-mentionable)

2. **Check file search** (Ctrl+P / Cmd+P):
   - Search for files in `docs/` - should find them
   - Search for files in `.cursor/rules/` - should find them

### Index Optimization Checklist

- [ ] Run `analyze-cursor-index.py` before changes
- [ ] Update `.cursorignore` (images) and/or `.cursorindexingignore` (blog data)
- [ ] Delete Index + Sync in Cursor
- [ ] Verify @ mentions work for excluded-but-accessible paths
- [ ] Run analysis script again and compare counts

## Troubleshooting

### Files Still Not Accessible

1. **Restart Cursor** - Changes to `.cursorignore` may require a restart
2. **Reload Workspace** - Use "Reload Window" command
3. **Check Pattern Order** - Ensure unignore patterns are at the top
4. **Verify Syntax** - Ensure no typos in patterns
5. **Check for Conflicting Patterns** - Later patterns in `.cursorignore` might override

### Common Issues

**Issue:** Patterns at bottom of file don't work

- **Solution:** Move unignore patterns to the very top

**Issue:** Only some subdirectories are accessible

- **Solution:** Add `!docs/**` pattern for recursive inclusion

**Issue:** `.cursor/rules/` files not accessible

- **Solution:** Add explicit patterns for `.cursor/` directory

**Issue:** Test script shows accessible but Cursor doesn't

- **Solution:** Restart Cursor and reload workspace

## Best Practices

1. **Keep unignore patterns at the top** - Pattern order matters
2. **Use explicit recursive patterns** - `!docs/**` ensures all subdirectories
3. **Document why patterns exist** - Add comments explaining overrides
4. **Test after changes** - Use test script to verify
5. **Version control `.cursorignore`** - Keep it in Git for team consistency

## Related Files

- `.cursorignore` - Full exclusions (images, node_modules, etc.)
- `.cursorindexingignore` - Index-only exclusions (blog data, docs/data JSON)
- `.gitignore` - Git ignore patterns
- `v2/scripts/dev-helpers/analyze-cursor-index.py` - Index analysis script

## Additional Resources

- [Cursor Documentation: Ignore Files](https://docs.cursor.com/context/ignore-files)
- [Cursor Documentation: Codebase Indexing](https://docs.cursor.com/context/codebase-indexing)
- [Gitignore Pattern Syntax](https://git-scm.com/docs/gitignore)
- [CURSOR_INDEXING_BASELINE.md](CURSOR_INDEXING_BASELINE.md) - Baseline metrics
- [CURSOR_INDEXING_OPTIMIZATION.md](CURSOR_INDEXING_OPTIMIZATION.md) - Optimization plan

## History

**2025-12-02**: Initial documentation created after fixing indexing issues for `docs/` and `.cursor/rules/` directories.

**2026-02-12**: Added `.cursorindexingignore`, image exclusions, index optimization, and analysis script.