chore: add known gotchas to agent docs for ref refiner

[nsantacruz]

This pull request adds a new "Known Gotchas" section to the agent_docs/model/linker/ref_resolver.md documentation. The section highlights several subtle issues and edge cases in the ibid resolution logic, helping developers understand potential pitfalls in the current implementation.

Key documentation updates:

Known limitations and edge cases in ibid resolution

• Added a note that is_empty() can cause correct ibid resolutions to be dropped if the target book has no text for a section, potentially resulting in the wrong book being selected.
• Documented how shared named-part terms in the schema can lead to unexpected cross-book ibid candidates, especially when commentary and base texts share term names.
• Explained that the ibid refinement path depends on shared base_text_titles, which can result in both section-context and context-free refinement producing valid refs, allowing incorrect books to survive to the pruning stage.
• Added guidance on simulating multi-level range refs using crrd, clarifying how the grouping of numbered parts before and after a range symbol works.

[gitvelocity-reviewer]

📊 Code Quality Score: 1/100

8 × 0.1 (Nano ESF) = 0.8, floored to 1

Category	Score	Factors
🔭 Scope	2/20	Single documentation file, no code changes, no new APIs or subsystems touched
🏗️ Architecture	0/20	No architectural changes; purely additive prose documentation
⚙️ Implementation	2/20	Content references specific method names, file paths, and Hebrew text examples with technical precision; not trivial prose
⚠️ Risk	1/20	Documentation-only change; trivially reversible with no operational risk
✅ Quality	3/15	Well-structured with concrete examples and consistent style; no tests applicable for doc-only change
🔒 Perf / Security	0/5	No performance or security considerations applicable to documentation change

_{Scored by GitVelocity · How are scores calculated?}

[gitvelocity-reviewer]

📊 Code Quality Score: 1/100

5 × 0.1 (Nano ESF) = 0.5, floored to minimum score of 1

Category	Score	Factors
🔭 Scope	1/20	Single file, pure documentation addition, no logic or behavioral changes
🏗️ Architecture	0/20	No architectural changes; additive prose documentation only
⚙️ Implementation	1/20	No implementation code; documents existing system behavior with concrete examples
⚠️ Risk	1/20	Minimal risk; documentation-only change, trivially reversible
✅ Quality	2/15	Adds useful gotcha documentation with concrete examples (ibid resolution, range notation); no formal tests or structured behavioral spec
🔒 Perf / Security	0/5	No performance or security considerations addressed

_{Scored by GitVelocity · How are scores calculated?}