Why is adding custom docs so hit or miss with Cursor?

I have been trying to add custom documentation for Tamagui UI (Tamagui UI — Tamagui — style library, design system, and UI kit for React (Native and web)), but it fails to index any pages beyond the first page provided, even though all the other pages are clearly linked on the first page, and they all follow the same prefix (https://tamagui.dev/ui).

Often, it doesn’t index the provided page as well. And I’ve had similar issues when trying to add other documentation as well in the past.

This seems like a bug, but more than anything else, I’m just curious as to:

  1. Why would such a thing behave differently in separate attempts?
  2. Are there any workarounds? Are people just adding each important page as a separate @doc, or maybe just providing the relevant links within the chat itself?