feat(API): improve get /projects/{project_id}/documents documentation

[Stephen Lumenta (sbl)]

Improves the documentation for get /projects/{project_id}/documents: sharper descriptions, parameter docs, error responses, and usage examples.

Drafted with AI assistance and grounded in the API implementation. Please review for technical accuracy before merging; nothing is merged automatically.

🤖 Generated with Claude Code

[github-actions]

API changelog (oasdiff)

Doc-only edits (descriptions, examples) do not appear here.

No changes to report, but the specs are different.
Run 'oasdiff diff' to see structural differences.

[Stephen Lumenta (sbl)]

This PR replaces #1178, which was closed after reviews from jablan and theSoenke.

Feedback addressed from #1178:

Reviewer	Comment	Status
theSoenke	"The policy should not be part of the API docs"	✅ Fixed
theSoenke	"per_page and rate limit details do not need to be repeated per endpoint"	✅ Fixed
jablan	"I don't think it's helpful to say the list is paginated here"	✅ Fixed
jablan	"Pagination information is superfluous here" (RFC 5988 / Link header sentence)	✅ Fixed
jablan	"Please do not expose identifier names from internal applications"	✅ Fixed
jablan	"Rate limiting applies universally and is explained on a dedicated place"	✅ Fixed

What changed: The description is fully rewritten. All six flagged items are removed:

• No DocumentPolicy#list_documents? or any internal class/policy name
• No pagination prose ("returns a paginated list", RFC 5988, Link header)
• No per_page cap or default
• No rate-limit pitfall

What remains is endpoint-specific: what a document is, when you'd use this endpoint, how the q prefix match works, and the auth requirement.

🤖 Generated with Claude Code