feat: add Proofing Gallery tools

[soerennb]

Adds first-party Context Agent tools for the Proofing Gallery Nextcloud app.

The module provides:

• privacy-bounded gallery, readiness, feedback, review, media, and preset reads
• explicit dangerous-tool wrappers for reversible draft, publishing, workflow, manager, and review actions
• capability-based availability detection
• optimistic revisions and per-request idempotency keys for mutations

The PHP app contract keeps public-link passwords, guest PII, arbitrary file reads, and permanent deletion out of scope.

Validation: ruff check ex_app/lib/all_tools/proofing_gallery.py and python -m py_compile ex_app/lib/all_tools/proofing_gallery.py.

[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.