Index

Knowledge Base Indexing

$ARGUMENTS

Reindex the knowledge base for semantic search.

> Prerequisite: This command requires a vector store (e.g., Qdrant) and an indexing pipeline configured for your project. If not configured, this command provides guidance on setup.

Usage

/index              # Incremental index (detect changes)
/index --full       # Full rebuild

Execution

Direct Execution

# Incremental index (auto-detects changes)
make index

# Full rebuild
make index-full

Docker Execution

docker exec {app-container} make index
docker exec {app-container} make index-full

Change Detection

The indexer uses content hashing to detect changes:

| Scenario | Action | |----------|--------| | New document | Index | | Changed content | Reindex | | No changes | Skip | | Deleted document | Remove from index |

Frontmatter Validation

Before indexing, ensure all KB documents have valid frontmatter:

---
title: "Document Title"
service: {service-name}
category: reference|howto|procedures|troubleshooting|decisions|best-practices
tags: [tag1, tag2]
last_updated: "YYYY-MM-DD"
---

Troubleshooting

| Problem | Solution | |---------|----------| | Index not updating | Check file timestamps, run full rebuild | | Missing documents | Verify frontmatter is valid | | Slow indexing | Check embedding service performance | | No vector store | Set up Qdrant or compatible vector DB |

Rules

• MUST require explicit user permission before running make index or make index-full — never self-trigger
• NEVER trigger a full rebuild to "clean up" unless the user asked for it
• CRITICAL: validate KB frontmatter before indexing — abort on invalid documents rather than indexing a broken state
• MANDATORY: respect change-detection hashes; do not force reindexing of unchanged documents

Gotchas

• Content-hash change detection keys on the file's content AND path. A moved document (same content, new path) looks new to the indexer — both the old path vector and the new one will exist until a full rebuild. Plan a full rebuild after mass reorganizations.
• Deleting a document on disk does not automatically remove its vectors from Qdrant; the indexer emits tombstones only if run with a directory scan. Without --delete-missing, orphan vectors stay for weeks.
• Embedding providers rate-limit by requests-per-minute AND by tokens-per-minute. A reindex of 1000+ docs hits the token cap first and stalls silently — watch for 429s in the indexer log before concluding "slow indexing".
• make index-full truncates the collection before re-embedding; if the embedding job crashes mid-way, the collection is left partially populated with no query-time indicator of the gap.

When NOT to Use

• For searching the KB — use /research-mastery or call smart_query() via the rag-mcp tool
• For fixing indexing bugs — use /debug on the indexer pipeline
• To evaluate RAG quality after reindexing — use /evaluate
• When no vector store is configured — document the gap, do not invent one

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: softspark
• Source: softspark/ai-toolkit
• License: MIT
• Homepage: https://softspark.eu

Install and usage instructions live in the source repository linked above.