Per-project @Docs scoping — essential for multi-app workflows with conflicting tech stacks

Ideas Feature Requests
, ,
1

Describe the request

Per-project @Docs scoping — essential for multi-app workflows with conflicting tech stacks

The Problem

I manage multiple applications that are part of the same business ecosystem. They are interconnected but have radically different tech stacks:

App A (Backend) App B (Frontend) App C (microservices)
PHP version PHP 7.x PHP 5.x PHP 8.x
Framework Laravel 5.5 Vanilla PHP Laravel 12
Admin panel — — Filament
ORM Eloquent Raw SQL / custom DAL Eloquent
Relationship Tightly coupled back-front with App B Tightly coupled back-front with App A Connected via APIs/DB to A and B

App A and App B are the core system — a tightly coupled backend/frontend pair that I work on simultaneously, often switching between the two multiple times a day. App C is a newer admin platform built on a modern stack that interfaces with the same data layer.

Currently, @Docs are global. Every doc I add in Cursor Settings → Indexing & Docs is available across all projects. There is no way to scope documentation to a specific project or workspace.

This means that when I’m working on App B (vanilla PHP 5), Cursor has Laravel 12, Filament, and PHP 8 docs in its context. It suggests match expressions, named arguments, Eloquent methods, Filament components — none of which exist in that codebase. When I switch to App A (Laravel 5.5), it picks up Laravel 12 syntax and suggests features that were introduced 7 major versions later. The result is code that looks perfectly valid but breaks on the target runtime.

Why Project Rules alone don’t solve this

Yes, I use .cursor/rules/ extensively. But rules and docs serve fundamentally different purposes:

  • Project Rules = high-level instructions (“use PHP 5.6 syntax”, “don’t use Laravel helpers”, “no Filament here”)
  • @Docs = deep technical reference that the model uses to generate accurate code (API signatures, method parameters, available functions, migration syntax, etc.)

You can write a rule that says “this project uses PHP 5.6 only”, but without the correct PHP docs scoped to that version, the model will still draw from PHP 8 knowledge and produce code using functions or syntax that don’t exist in PHP 5. Similarly, you can tell Cursor “this is Laravel 5.5”, but if the Laravel 12 docs are loaded, it will hallucinate method signatures, suggest non-existent Eloquent features, and reference Blade directives that were introduced years later.

Rules tell the model what to do. Docs give the model the ground truth to do it correctly. Without scoped docs, rules become guardrails with no road underneath.

Proposed Solution

Allow a .cursor/docs.json (or similar) file in each project that declares which docs should be active for that project:

// App A - .cursor/docs.json
{
  "docs": [
    { "name": "Laravel 5.5", "url": "https://laravel.com/docs/5.5" },
    { "name": "PHP 7.x", "url": "https://www.php.net/manual/en/" }
  ]
}

// App B - .cursor/docs.json
{
  "docs": [
    { "name": "PHP 5.6", "url": "https://www.php.net/manual/en/" }
  ]
}

// App C - .cursor/docs.json
{
  "docs": [
    { "name": "Laravel 12", "url": "https://laravel.com/docs/12.x" },
    { "name": "Filament v3", "url": "https://filamentphp.com/docs/3.x" },
    { "name": "PHP 8.x", "url": "https://www.php.net/manual/en/" }
  ]
}

Key behaviors:

  1. Auto-indexing on project open — When a developer opens the project, Cursor automatically indexes/activates the declared docs (if not already indexed).
  2. Project-scoped visibility — Only the declared docs are suggested/available via @Docs when working in that project. Global docs from Settings remain available everywhere unless overridden.
  3. Version-controlled and team-shareable — Since it lives in .cursor/, the whole team gets the same doc context automatically. No more onboarding friction.
  4. Auto-attached option — Similar to how rules can be alwaysApply, allow docs to be auto-attached to every prompt within the project, so developers don’t need to manually @Docs every time.

Real-world impact

This isn’t a nice-to-have. In a multi-app environment with three different PHP versions and two different Laravel versions coexisting in the same business ecosystem, wrong documentation context = wrong code generation = bugs in production.

The current workaround is to mentally track which docs are relevant, manually @ the right ones every single time, and hope the model doesn’t draw from unrelated docs that are still globally loaded. That defeats the purpose of AI-assisted development.

The tighter the coupling between apps (like my A/B back-front pair), the more frequently you switch contexts, and the more critical it becomes that the right docs are loaded automatically.

Related discussions

This has been requested multiple times in various forms:

The fact that this keeps coming up from different users with different use cases (Django/Flutter, Ruby/Rails, PHP multi-version, etc.) suggests it’s a real gap in the current feature set.

Would love to hear from the team if this is on the roadmap, and from other developers dealing with similar multi-stack workflows.

Operating System (if it applies)

Windows 10/11

3

I did the first post. As long as you don’t @ refer the docs, they are not in the context. So the point is mute for me now. I also almost don’t use @ docs now, since good LLMs are good at websearch anyway.

If you have TONs of docs, you could name them broad to fine like an URL:

django.jwt
django.be

flutter.notifications.local
flutter.notifications.push

as a workaround, to auto-complete select them more easily.