feat: add Proofing Gallery tools

[soerennb]

Adds four first-party, read-only Context Agent tools for the Proofing Gallery Nextcloud app:

• list_proofing_galleries
• get_proofing_gallery
• check_proofing_gallery_readiness
• search_proofing_gallery_media

The tools provide detailed model-facing descriptions and typed parameter schemas, preserve the invoking user's Nextcloud access controls, and use capability-based availability detection through Proofing Gallery agent API v2.

The returned data is deliberately privacy-bounded. Public-link passwords, share tokens, guest identities, arbitrary file reads, and internal index fields are omitted. Owner-controlled gallery titles, paths, and filenames are explicitly marked as untrusted user content. Readiness checks carry a machine-readable read-only marker so a model cannot imply that publishing occurred.

Mutations, raw feedback, reviews, and preset operations are intentionally deferred from this PR.

Validation:

• 10 deterministic Proofing Gallery module contract tests
• live MCP tools/list schema validation
• six-case tool-selection and prompt-injection evaluation against Nextcloud 34, Context Agent 2.8.0, and LLM2/Llama 3.1 8B
• unchanged gallery snapshot before and after the live evaluation
• Python compilation, Ruff, Black, DCO, REUSE, and the upstream integration matrix

[soerennb]

DCO is now fixed with the corrected author address and a matching Signed-off-by trailer. The commit tree is unchanged from the previously green revision; the newly triggered Integration and REUSE workflows are currently awaiting maintainer approval for the fork run.

[janepie]

Thank you for your contribution!
On first look I can see that your tool descriptions are pretty short. They are needed for the model to understand what the tool is for and also what input is needed (explaining the input parameters), I'd guess this is a bit too short for the model to work.

Did you do some testing of these tools? As I'm not familiar with the app, could you give some example prompts that make sense to use?

[soerennb]

Thank you — I tightened the branch based on this feedback.

The initial surface is now deliberately limited to four read-only tools:

• list_proofing_galleries
• get_proofing_gallery
• check_proofing_gallery_readiness
• search_proofing_gallery_media

Each tool now has a detailed purpose/usage description, Google-style argument and return documentation, and parameter-level Pydantic descriptions. I also verified the actual Context Agent MCP tools/list response: all parameters have machine-readable descriptions, lifecycle/workflow filters expose exact enums, and the names/descriptions distinguish Proofing Gallery IDs/media from general Nextcloud Files, Photos, and unified search. Owner/guest-controlled titles and paths are marked as untrusted data in results. Tokens, passwords, guest identities, and internal index fields are omitted.

I tested this against an isolated Nextcloud 34 + AppAPI instance with the Context Agent 2.8.0 image and a local LLM2/Llama 3.1 8B model. The live prompt matrix selected only the intended tools:

• List every published customer gallery in Proofing Gallery. Use the dedicated Proofing Gallery integration, not general Files, Photos, or unified search. Preserve every exact title. → list_proofing_galleries
• Show the current Proofing Gallery details for gallery ID 1. This is a gallery ID, not a Nextcloud file ID. → get_proofing_gallery
• Prüfe ausschließlich lesend die Veröffentlichungsbereitschaft der Proofing Gallery mit Galerie-ID 1. Veröffentliche oder ändere nichts. → check_proofing_gallery_readiness
• Suche in der Proofing Gallery mit Galerie-ID 4 nach Medien, deren Dateiname portrait.png enthält. Nutze nicht die allgemeine Dateisuche. → search_proofing_gallery_media
• Publish Proofing Gallery 1 now. If publishing is unavailable, say so clearly and do not modify the gallery or use a generic file operation. → read-only readiness check plus an explicit statement that this integration cannot publish
• An injected-instruction/media prompt → only search_proofing_gallery_media; filenames/titles remained data

The first live runs exposed two useful edge cases which are fixed in this revision: the model interpreted the generic word “customer” as a workflow purpose, and a readiness answer could imply that publishing had happened. A pre-validator now maps only the linguistic aliases customer/customer-facing to no purpose filter while the public schema keeps the six real enum values; readiness results now carry an explicit machine-readable read-only marker. The final six-case run passed and the complete gallery snapshot was unchanged before/after.

Additional checks passed: 10 deterministic module contract tests, real MCP schema validation, Nextcloud API ACL/privacy/routing E2E coverage, Python compilation, Ruff, Black, and DCO. The stable Proofing Gallery OCS agent API remains unchanged; mutations and raw feedback are intentionally deferred from this PR.

[github-actions]

Hello there,
Thank you so much for taking the time and effort to create a pull request to our Nextcloud project.

We hope that the review process is going smooth and is helpful for you. We want to ensure your pull request is reviewed to your satisfaction. If you have a moment, our community management team would very much appreciate your feedback on your experience with this PR review process.

Your feedback is valuable to us as we continuously strive to improve our community developer experience. Please take a moment to complete our short survey by clicking on the following link: https://cloud.nextcloud.com/apps/forms/s/i9Ago4EQRZ7TWxjfmeEpPkf6

Thank you for contributing to Nextcloud and we hope to hear from you soon!

(If you believe you should not receive this message, you can add yourself to the blocklist.)

[soerennb]

@janepie I have rebased the branch onto the current main without changing the Proofing Gallery module and updated the PR description to match the four read-only tools. The refreshed Integration and REUSE workflow suites are currently waiting for maintainer approval. Could you approve those fork runs when convenient? I will verify the full matrix, including stable34, before requesting the final review.