# Semantic Search Index for AI Agents

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

Semantic search index mapping common queries and task types to relevant documentation locations. This helps AI agents quickly discover the right documentation for specific tasks.

## Excluded but Accessible (Indexing-Optimized Paths)

These paths are not indexed for search (see `.cursorindexingignore`) but remain **@-mentionable**. Use `@path` when you need them:

| Path | When to @mention |
|------|-------------------|
| `docs/content/blog/posts/{category}/{slug}/data/` | Editing a specific post's FAQ, competitor analysis, or reports |
| `docs/content/blog/posts/ratgeber/gastronomie-mindestlohn/data/faq-questions.json` | Example: working on that post's FAQs |
| `docs/data/**/*.json` | When you need generated reports (blog-image-audit, mobile-app analysis, etc.) |

**Blog post data location:** `docs/content/blog/posts/{category}/{slug}/data/` contains per-post JSON (competitor-analysis, faq-questions, seo-analysis, etc.). Use `@docs/content/blog/` for guides and templates.

## Common Queries → Documentation Mapping

### Page Creation Queries

**"How do I create a comparison page?"**
→ `docs/guides/comparison-pages/COMPARISON_PAGES_GUIDE.md`
→ Rules: `comparison-pages-core.mdc`, `comparison-pages-content.mdc`

**"How do I create a tools page?"**
→ `docs/guides/tools-pages/README.md`
→ Rules: `tools-pages-core-design.mdc`, `tools-pages-core-validation.mdc`, `tools-pages-schema.mdc`

**"How do I create a product page?"**
→ `docs/guides/PAGE_TYPE_GUIDES.md`
→ Rules: `product-pages.mdc`

**"How do I create an industry page?"**
→ `docs/guides/PAGE_TYPE_GUIDES.md`
→ Rules: `industry-pages.mdc`

**"How do I create a template page?"**
→ `docs/guides/PAGE_TYPE_GUIDES.md`
→ Rules: `templates-pages.mdc`, `templates-cta.mdc`

### System Development Queries

**"How does ShiftOps work?"**
→ `docs/systems/shiftops/README.md`
→ Rules: `shiftops-backend.mdc`, `shiftops-frontend-core.mdc`, `shiftops-frontend-qa.mdc`

**"How do I work with lead capture?"**
→ `docs/systems/lead-capture/README.md`
→ Rules: `lead-capture.mdc`, `form-tracking.mdc`

**"How do I work with product updates?"**
→ `docs/systems/product-updates/README.md`
→ Rules: `product-updates.mdc`

**"How do I generate Excel templates?"**
→ `docs/systems/excel-generator/README.md`
→ Rules: `excel-template-generator.mdc`

### API Development Queries

**"How do I create an API endpoint?"**
→ `docs/reference/api/` (if exists)
→ Rules: `api-endpoints-core.mdc`, `api-endpoints-security.mdc`

**"How do I handle form submissions?"**
→ `docs/guides/HUBSPOT_INTEGRATION_GUIDE.md`
→ Rules: `api-endpoints-core.mdc`, `form-tracking.mdc`

### Content Management Queries

**"Where is competitor data stored?"**
→ `docs/content/competitors/COMPETITORS_INVENTORY.md`
→ `v2/data/competitors.php`
→ Rules: `comparison-pages-core.mdc`, `comparison-pages-content.mdc`

**"Where are tool documentation files?"**
→ `docs/content/tools/TOOLS_INVENTORY.md`
→ `docs/guides/tools-pages/`
→ Rules: `tools-pages-documentation.mdc`

**"What product features are documented?"**
→ `docs/content/product-features/PRODUCT_FEATURES_INVENTORY.md`
→ Rules: `product-pages.mdc`

### Validation and Quality Queries

**"What dev tools and validators are available?"**
→ `docs/development/DEV_TOOLING.md`

**"How do I run all validators?"**
→ `make validate` (see `docs/development/DEV_TOOLING.md`)

**"What validation checklist should I use?"**
→ `docs/ai/RULE_TO_DOC_MAPPING.md` (find rule, then check rule file)
→ Rules: `shared-patterns.mdc` (universal checklist)

**"How do I validate schemas?"**
→ `npm run validate:schema <file>` or `composer schema` (see `docs/development/DEV_TOOLING.md`)
→ `docs/guides/PAGE_TYPE_GUIDES.md`
→ Rules: `tools-pages-schema.mdc`, `shared-patterns.mdc`

**"How do I check for broken links?"**
→ `npm run check-links` (markdown-link-check on docs/)
→ `scripts/documentation/validate-links.py`
→ `docs/LINK_VALIDATION_REPORT.md`

### Documentation Maintenance Queries

**"How do I update documentation?"**
→ `docs/DOCUMENTATION_MAINTENANCE_PROCESS.md`
→ `docs/DOCUMENTATION_STANDARDS.md`

**"What documentation templates exist?"**
→ `docs/guides/tools-pages/TOOL_DOCUMENTATION_TEMPLATE.md`
→ `docs/DOCUMENTATION_STANDARDS.md`

**"How do I find existing documentation?"**
→ `docs/AI_AGENT_GUIDE.md`
→ `docs/DOCUMENTATION_INVENTORY.md`

## Task Types → Relevant Rules

### Creating New Pages

**Comparison Page:**

- Rules: `comparison-pages-core.mdc`, `comparison-pages-content.mdc`, `shared-patterns.mdc`
- Docs: `docs/guides/comparison-pages/COMPARISON_PAGES_GUIDE.md`

**Tools Page:**

- Rules: `tools-pages-core-design.mdc`, `tools-pages-core-validation.mdc`, `tools-pages-schema.mdc`, `tools-pages-faq.mdc`, `shared-patterns.mdc`
- Docs: `docs/guides/tools-pages/README.md`

**Product Page:**

- Rules: `product-pages.mdc`, `shared-patterns.mdc`
- Docs: `docs/guides/PAGE_TYPE_GUIDES.md`

### Working with Systems

**ShiftOps:**

- Rules: `shiftops-backend.mdc`, `shiftops-frontend-core.mdc`, `shiftops-frontend-qa.mdc`, `api-endpoints-core.mdc`
- Docs: `docs/systems/shiftops/`

**Lead Capture:**

- Rules: `lead-capture.mdc`, `form-tracking.mdc`, `api-endpoints-core.mdc`
- Docs: `docs/systems/lead-capture/`

**Excel Generator:**

- Rules: `excel-template-generator.mdc`, `api-endpoints-core.mdc`, `api-endpoints-security.mdc`
- Docs: `docs/systems/excel-generator/`

### Editing Shared Components

**Base Components (HIGH PROTECTION):**

- Rules: `base-components.mdc`, `shared-patterns.mdc`
- Docs: `docs/guides/PAGE_TYPE_GUIDES.md`
- ⚠️ Requires explicit approval

**API Endpoints:**

- Rules: `api-endpoints-core.mdc`, `api-endpoints-security.mdc`, `shared-patterns.mdc`
- Docs: `docs/reference/api/` (if exists)

## File Patterns → Applicable Rules

### Page Files

**`v2/pages/compare_*.php`**
→ `comparison-pages-core.mdc`, `comparison-pages-content.mdc`

**`v2/pages/tools_*.php`**
→ `tools-pages-core-design.mdc`, `tools-pages-core-validation.mdc`, `tools-pages-schema.mdc`, `tools-pages-faq.mdc`, plus others as needed

**`v2/pages/product_*.php`**
→ `product-pages.mdc`

**`v2/pages/industry_*.php`**
→ `industry-pages.mdc`

**`v2/pages/templates_*.php`**
→ `templates-pages.mdc`, `templates-cta.mdc`

### Component Files

**`v2/base/*.php`**
→ `base-components.mdc` (⚠️ HIGH PROTECTION)

**`v2/api/shiftops*.php`**
→ `shiftops-backend.mdc`, `api-endpoints-core.mdc`

**`v2/api/*.php`** (non-ShiftOps)
→ `api-endpoints-core.mdc`, `api-endpoints-security.mdc`

### System Files

**`v2/components/lead-capture*.php`**
→ `lead-capture.mdc`, `form-tracking.mdc`

**`v2/systems/excel-template-generator/**/\*`**
→ `excel-template-generator.mdc`

**`v2/pages/produkt_updates*.php`**
→ `product-updates.mdc`

## Content Types → Documentation Paths

### Tools Documentation

**Pattern:** `docs/content/tools/[tool-slug]-documentation.md`
**Index:** `docs/content/tools/TOOLS_INVENTORY.md`
**Guides:** `docs/guides/tools-pages/`

### Competitor Documentation

**Pattern:** `docs/content/competitors/[competitor-slug]-profile.md`
**Index:** `docs/content/competitors/COMPETITORS_INVENTORY.md`
**Distinction:** `docs/content/competitors/COMPETITORS_VS_COMPARISON_PAGES.md`

### Product Feature Documentation

**Pattern:** `docs/content/product-features/[feature-slug]-documentation.md`
**Index:** `docs/content/product-features/PRODUCT_FEATURES_INVENTORY.md`

### Page Documentation

**Comparison Pages:**

- Pattern: `docs/content/pages/comparison-pages/[page-slug]-documentation.md`
- Index: `docs/content/pages/comparison-pages/COMPARISON_PAGES_INVENTORY.md`

**Product Pages:**

- Pattern: `docs/content/pages/product-pages/[page-slug]-documentation.md`
- Index: `docs/content/pages/product-pages/PRODUCT_PAGES_INVENTORY.md`

## Search Strategies

### 1. Start with Master Index

Always check `docs/README.md` first for navigation and quick links.

### 2. Use Inventory Files

Each content type has an inventory file:

- Tools → `docs/content/tools/TOOLS_INVENTORY.md`
- Competitors → `docs/content/competitors/COMPETITORS_INVENTORY.md`
- Product Features → `docs/content/product-features/PRODUCT_FEATURES_INVENTORY.md`
- Pages → `docs/content/pages/[page-type]/[PAGE_TYPE]_INVENTORY.md`

### 3. Check Rule-to-Doc Mapping

Use `docs/ai/RULE_TO_DOC_MAPPING.md` to find documentation for specific rules.

### 4. Use Rule Dependency Graph

Use `docs/ai/RULE_DEPENDENCY_GRAPH.md` to understand which rules apply together.

### 5. Search by File Pattern

Match file path against glob patterns in rule files to find applicable rules.

## Blog-Related Queries

### Blog Templates & Components

**"How do I create a blog post template?"**
→ `docs/content/blog/guides/TEMPLATE_DEVELOPMENT_GUIDE.md`
→ Rules: `blog-templates.mdc`
→ Reference: `docs/content/blog/reference/COMPONENT_API.md`

**"What components are available for blog posts?"**
→ `docs/content/blog/reference/COMPONENT_API.md`
→ `docs/content/blog/guides/TEMPLATE_DEVELOPMENT_GUIDE.md`
→ Rules: `blog-templates.mdc`

**"How do I add a CTA to a blog post?"**
→ Rules: `blog-cta-patterns.mdc`
→ Reference: `docs/content/blog/reference/DEMO_CTA_PATTERN.md`
→ Guide: `docs/content/blog/guides/TEMPLATE_DEVELOPMENT_GUIDE.md`

### Blog Data Collection

**"How do I collect SISTRIX data for blog posts?"**
→ `docs/content/blog/guides/DATA_COLLECTION_GUIDE.md`
→ Rules: `blog-data-collection.mdc`
→ Integration: `docs/content/blog/guides/DATA_INTEGRATION_GUIDE.md`

**"How do I run data collection for all posts?"**
→ `docs/content/blog/guides/DATA_COLLECTION_GUIDE.md`
→ Quick Reference: `docs/content/blog/BLOG_QUICK_REFERENCE.md`
→ Script: `v2/scripts/blog/run-all-data-collection.php`

**"What APIs are used for blog data collection?"**
→ `docs/content/blog/guides/DATA_COLLECTION_GUIDE.md`
→ Rules: `blog-data-collection.mdc`
→ Integration: `docs/content/blog/guides/DATA_INTEGRATION_GUIDE.md`

### Blog Documentation

**"How do I generate blog post documentation?"**
→ `docs/content/blog/guides/MANUAL_REVIEW_WORKFLOW.md`
→ Rules: `blog-post-documentation.mdc`
→ Script: `v2/scripts/blog/generate-post-documentation.php`

**"What documentation is required for each blog post?"**
→ Rules: `blog-post-documentation.mdc`
→ Structure: `docs/content/blog/posts/README.md`
→ Workflow: `docs/content/blog/guides/MANUAL_REVIEW_WORKFLOW.md`

**"How do I conduct manual review of blog posts?"**
→ `docs/content/blog/guides/MANUAL_REVIEW_WORKFLOW.md`
→ Rules: `blog-manual-review.mdc`
→ Checklist: `docs/content/blog/POST_REVIEW_CHECKLIST.md`

### Blog Backup & Restoration

**"How do I backup blog content?"**
→ `docs/content/blog/guides/BACKUP_GUIDE.md`
→ Rules: `blog-backup.mdc`
→ Process: `docs/content/blog/guides/BACKUP_PROCESS.md`

**"How do I restore blog content from backup?"**
→ `docs/content/blog/guides/BACKUP_GUIDE.md`
→ `docs/content/blog/guides/RESTORATION_GUIDE.md`
→ Rules: `blog-backup.mdc`

### Blog Internal Linking

**"How do I add internal links to blog posts?"**
→ `docs/content/blog/guides/LINKING_STRATEGY_GUIDE.md`
→ `docs/content/blog/guides/INTERNAL_LINKING_GUIDE.md`
→ Formatting: `docs/content/blog/ANCHOR_TEXT_FORMATTING.md`

**"What are the anchor text guidelines?"**
→ `docs/content/blog/ANCHOR_TEXT_FORMATTING.md`
→ `docs/content/blog/ANCHOR_TEXT_GUIDELINES.md`
→ Strategy: `docs/content/blog/guides/LINKING_STRATEGY_GUIDE.md`

### Blog SEO

**"How do I optimize blog posts for SEO?"**
→ `docs/content/blog/guides/SEO_BEST_PRACTICES_2026.md`
→ `docs/content/blog/guides/SEO_OPTIMIZATION_GUIDE.md`
→ Rules: `blog-post-documentation.mdc`

**"What meta tags are required for blog posts?"**
→ `docs/content/blog/guides/TEMPLATE_DEVELOPMENT_GUIDE.md`
→ Rules: `blog-templates.mdc`
→ Reference: `docs/content/blog/reference/COMPONENT_API.md`

### Blog Scripts

**"What scripts are available for blog tasks?"**
→ `docs/content/blog/SCRIPTS_INVENTORY.md`
→ Quick Reference: `docs/content/blog/BLOG_QUICK_REFERENCE.md`
→ Usage Guide: `docs/content/blog/HOW_TO_USE_THIS_SYSTEM.md`

**"How do I validate blog documentation?"**
→ Quick Reference: `docs/content/blog/BLOG_QUICK_REFERENCE.md`
→ Script: `v2/scripts/blog/validate-post-documentation.php`
→ Workflow: `docs/content/blog/guides/MANUAL_REVIEW_WORKFLOW.md`

### Blog Rule Discovery

**"Which rules apply to blog files?"**
→ `docs/content/blog/BLOG_RULE_DISCOVERY_PATTERNS.md`
→ Rule Index: `.cursor/rules/README.md`
→ Patterns: `docs/ai/RULE_DISCOVERY_PATTERNS.md`

**"How do I find the right rule for a blog task?"**
→ `docs/content/blog/BLOG_RULE_DISCOVERY_PATTERNS.md`
→ Quick Reference: `docs/content/blog/BLOG_QUICK_REFERENCE.md`
→ Rule Index: `.cursor/rules/README.md`

## Related Documentation

- **[AI Agent Guide](AI_AGENT_GUIDE.md)** - Complete documentation discovery guide
- **[Rule Discovery Patterns](RULE_DISCOVERY_PATTERNS.md)** - How to discover relevant rules
- **[Blog Rule Discovery Patterns](content/blog/BLOG_RULE_DISCOVERY_PATTERNS.md)** - Blog-specific rule discovery
- **[Blog Quick Reference](content/blog/BLOG_QUICK_REFERENCE.md)** - Blog quick reference guide
- **[Rule to Documentation Mapping](RULE_TO_DOC_MAPPING.md)** - Bidirectional mapping
- **[Rule Dependency Graph](RULE_DEPENDENCY_GRAPH.md)** - Visual rule relationships