Reliable way to get cursor to use docs in /vendor/ folder?

Discussions
, ,
1

I have a bunch of php packages I reuse across projects using composer. These are internal packages and not published with public documentation.

I want to include agent.md files for each of the packages to provide instructions on how the package can be used. This would keep the instructions correct for whatever version of the package is installed.

From what I’ve read, cursor will ignore folders like vendor/ or node_modules/ folders which makes sense. But according to everything I can find even if my projects agent.md file says “Use documentation out of /vendor/mypackages/*” that this is unreliable and cursor may not index it.

Cursor suggests that I negate the folder in .cursorindexingignore like !vendor/mypackages/but seems unsure if this solution is valid.

Instead it suggests I make a composer script to copy all my docs out of the vendor folder and I could run that on post-install-cmd to keep stuff in sync.

What’re people doing to provide cursor context to their internal private packages?

1 Like
3

Hey, good question. This is a common pain point with vendored dependencies.

There are a few approaches, from most to least reliable:

  1. .cursorignore negation official way

Since vendor/ is ignored via .gitignore, you can override it in .cursorignore with negation patterns:

!vendor/mypackages/

Important caveat from the docs: negation doesn’t work if a parent directory was excluded via wildcard. So if you need specific subpackages, be explicit:

!vendor/mypackages/package-a/
!vendor/mypackages/package-b/

After adding this, reindex Cmd+Shift+P then Reindex, and check if the files show up in codebase search.

That said, negation patterns for gitignored paths have some known quirks with Agent search tools, so results can be inconsistent. Still worth trying first.

  1. Symlink or copy approach most reliable

Your idea with the Composer post-install-cmd script is honestly the most reliable option right now. Copy or symlink only the agent.md or doc files into a docs/vendor/ folder at the project root. This keeps them outside the .gitignore scope entirely, so indexing works cleanly.

  1. Project rules as a bridge

You can create a rule in .cursor/rules/ that references the vendor docs explicitly:

---
description: Internal package documentation
alwaysApply: true
---

When working with packages from vendor/mypackages/, read the corresponding
agent.md file in that package's root for usage instructions.

This tells Agent to look at those files when relevant, but it still needs the files to be indexed, so pair it with option 1 or 2.

Docs for reference:

The team is aware of the inconsistencies with negation patterns for gitignored paths. If the .cursorignore approach isn’t reliable for you, the copy or symlink workaround is the safe bet for now.

Let me know how it goes.

4

Awesome, thanks for the fast response. I will stick to having a composer script copy out the docs. I guess the added benefit there is it also becomes easier for devs to look at the docs.

1 Like
5

Hey Joe,

Would you be willing to share that script?

cheers
Dan

6

Is it known whether this issue is being worked on in the near future? The problem isn’t limited to documentation, but more generally to using information contained in “vendor” files. I’ve noticed that code accuracy improves significantly when Cursor has that folder indexed and can search it first, only falling back to documentation or online resources afterward.

In my case, my team and I work on quite a large number of projects simultaneously. Currently, when we need to write code that depends on vendor packages (e.g., ApiPlatform, Symfony, Elasticsearch, payment integrations, etc.), we uncomment the required packages using negation patterns, let Cursor index the selected folders, and only then start writing prompts. This approach yields very good results, but unfortunately it’s somewhat time-consuming. On the plus side, Cursor works directly with the exact code used in the project (a specific package version), so it avoids mistakes like suggesting solutions that are inconsistent with the actual codebase.

A read-only mode would be a highly anticipated solution. Cursor could use the vendor code but wouldn’t be able to edit it (it can already behave somewhat like this, but it requires modifying .gitignore with negation patterns).

7

Hey @Igor_Tomalski, good question.

The issue with negation patterns for gitignored paths in agent tools rg and glob is known and on the team’s radar. There’s a separate bug report about it here: Rg and Glob tools failing on directory search for gitignored paths. I can’t share an ETA, but it’s being tracked.

The idea of a read-only mode for vendor/ would be really handy. For now, the workaround with negation patterns in .cursorignore plus a manual reindex works somewhat, but like you noticed, it’s not always reliable with agent tools.

What works best right now:

  1. Add the vendor packages as a separate workspace folder via File > Add Folder to Workspace. This avoids the .gitignore conflict entirely.
  2. Symlink the needed packages outside of vendor/ like we discussed above with a Composer script.

Both options give agent tools full access to the code without having to fight ignore files.

Let me know if either of these fits your workflow.