Proposal: pinned / priority documents that always appear in retrieval

[mvanhorn]

Power users want to pin specific docs as "always use this in retrieval." AnythingLLM users have requested the same in #5413. SurfSense today supports @doc mention QnA (query-scoped) but no persistent pin.

I'd add an is_priority boolean on documents + a budget-split in the retriever: reserve 25% of the top-K retrieval budget for priority docs regardless of vector similarity (so a pinned doc still appears when the query is tangential). Controlled by env RAG_PRIORITY_BUDGET_RATIO for self-hosters. Frontend adds a pin icon in DocumentsSidebar.tsx.

Scope: ~200–250 LOC, single PR. Migration is additive (DEFAULT false, NOT NULL), existing behavior preserved when no docs are pinned.

Two decisions I'd like your input on:

1. Budget ratio: 25% default sound reasonable, or would you prefer different tiers per search space size (e.g., 50% for small spaces)?
2. Should the prompt instruction about "user-pinned docs are authoritative" only activate when priority docs exist in the context, or always be present? (I lean toward only-when-present to avoid confusing the model on spaces without any pins.)

I've shipped #1215 / #1220 / #1233. This would be my second backend PR after the scheduled-research proposal. Targeting dev, full migration up/down test plus 3 unit tests covering the budget-split edge cases.