docs(events): describe the paginated share-review source API

Document the Nextcloud 36 additions to the share-review events: the
IPaginatedShareReviewSource interface collected through
RegisterShareReviewSourceEvent (page-wise listing with sorting, search,
filters and counts, keyed lookup, localized label, optional remediation
and snapshot capabilities) and the action, acting user and scope carried
by ShareReviewAccessCheckEvent.

Assisted-by: Claude Code:claude-opus-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>

Author: AndyScherzinger

developer_manual/basics/_available_events_ocp.rst

@@ -828,13 +828,30 @@ Event that allows to register a feature policy header to a request.
 
 .. versionadded:: 34.0.2
 
-Authorization gate for deleting an app-managed share through a share-review app. Dispatched by the app that owns
+Authorization gate for acting on an app-managed share through a share-review app. Dispatched by the app that owns
 the share (its ``OCP\Share\ShareReview\IShareReviewSource`` implementation) at the beginning of ``deleteShare()``,
 before anything is deleted. The share-review app listens to this event and answers with ``grantAccess()`` or
 ``denyAccess()`` depending on whether the current user is an authorized share-review operator; apps that merely
 expose shares must not listen to it. The event is default-deny: if no listener responds, the share must not be
 deleted. Once denied, further grants are ignored and event propagation is stopped.
 
+.. versionchanged:: 36
+
+   The event carries the operation being authorized (``getAction()``: ``ACTION_DELETE``, ``ACTION_REMEDIATE`` for
+   the password/expiration mutators of ``OCP\Share\ShareReview\IShareReviewSourceRemediation``, ``ACTION_RESTORE``
+   for ``OCP\Share\ShareReview\IShareReviewSourceSnapshot::restoreShare()``), the acting user (``getActingUserId()``,
+   ``null`` for the session user) and the scope (``getScope()``: ``SCOPE_OPERATOR`` for an instance-wide review,
+   ``SCOPE_SELF`` for a user reviewing their own shares, where the listener must additionally verify that the acting
+   user is the share's initiator). The acting user and the scope reach the owning app through an optional
+   ``OCP\Share\ShareReview\ShareReviewActionContext`` that the share-review app passes to ``deleteShare()`` and to
+   the mutators of the two capability interfaces; the owning app forwards both values into this event verbatim and
+   never decides them itself. Passing no context means the session user acts as an operator, exactly as in 34.0.2.
+   Listeners written against the 34.0.2 event keep working and keep failing closed
+   for non-operators — but for operators the new actions extend the granted capability set: ``ACTION_REMEDIATE``
+   includes removing a link share's password, which can expose content deletion never could. A listener that
+   distinguishes reviewers with delete-only rights must check ``getAction()`` and deny actions it does not
+   recognize.
+
 ``OCP\Share\ShareReview\RegisterShareReviewSourceEvent``
 ********************************************************
 
@@ -844,6 +861,34 @@ Event dispatched by a share-review app to collect share sources from other apps.
 of their ``OCP\Share\ShareReview\IShareReviewSource`` implementation, whose ``getShares()`` method returns a list of
 ``OCP\Share\ShareReview\ShareReviewEntry`` objects.
 
+.. versionchanged:: 36
+
+   Sources with many shares should implement ``OCP\Share\ShareReview\IPaginatedShareReviewSource`` instead, which
+   extends ``IShareReviewSource`` and lists shares page by page: ``queryShares()`` takes an
+   ``OCP\Share\ShareReview\ShareReviewQuery`` (page size and offset, sort field and direction, a case-insensitive
+   substring search across object, initiator and recipient, and filters for share types, password protection,
+   expiration date and range, modification range, scoped identity substrings, exact initiator, recipient and access
+   token lists, and opaque permission ids) and returns an ``OCP\Share\ShareReview\ShareReviewPage`` carrying the
+   entries and the total and filtered counts (``ShareReviewCounts``); ``countShares()``, ``countSharesByType()`` and
+   ``countSharesByInitiator()`` return counts without rows, ``getShare()`` looks a single share up by its deletion
+   identifier, and ``getDisplayName()`` provides a localized label while ``getName()`` stays a stable, untranslated
+   identifier. The share-review app detects the paginated interface with ``instanceof`` and falls back to
+   ``getShares()`` otherwise.
+
+   The contract is identical for every source, so a share-review app can offer the same table controls on every tab.
+   An implementation evaluates it in the database rather than in PHP and must honour the rules the interface
+   docblocks state: append the primary key as a secondary sort so equal-keyed rows never straddle a page boundary,
+   order NULL sort keys last in both directions, escape LIKE wildcards in every substring input, compare access
+   tokens exactly (never as a prefix — they are bearer credentials), treat an empty list filter as matching nothing,
+   and answer the grouped counts with a single ``GROUP BY`` scan rather than a count per group.
+
+   Two optional capability interfaces can be implemented alongside: ``IShareReviewSourceRemediation`` sets or removes
+   passwords and expiration dates (declared per source through ``canSetPassword()`` and ``canSetExpiration()``;
+   because only link and mail shares carry them, a mutator called for an entry of any other type returns ``false``
+   without dispatching the access check), and ``IShareReviewSourceSnapshot`` serializes a share before deletion and
+   restores it later from that opaque, app-owned string. Both are discovered with ``instanceof`` and gated by the
+   access-check event with ``ACTION_REMEDIATE`` and ``ACTION_RESTORE`` respectively.
+
 ``OCP\SpeechToText\Events\TranscriptionFailedEvent``
 ****************************************************