# AGENTS.md — Build guide for Xodo Pro

## Project scope
View and annotate local PDFs, reorder or combine pages and export new copies through a private workbench. Add optional OCR and Office conversion only as separately visible operations with fidelity warnings.

Catalogue verdict: kinda. The core loop is buildable, but a dependable replacement becomes a real weekend or multi-day project. For Xodo Pro, view, annotate, convert, and organize PDFs across local devices. The hard boundary is cross-platform apps, cloud integrations, format coverage, and mobile polish, plus document fidelity, identity, and compliance.
Use the implementation prompt below to define the deliverable. Complete each phase's acceptance checks before extending the scope.

## Working agreement
- Inspect the repository and its existing instructions before choosing paths, dependencies or commands. Keep one coherent stack and explain changes to the proposed architecture.
- Plan a vertical slice that accepts a real input and produces the useful output described below. Persist only the state the prompt calls for; respect memory-only and upstream-managed workflows. Use fixtures only when they are clearly labelled.
- After scaffolding, document the actual install, development, check and build commands in README and keep them synchronized with the package or project manifest. Do not report commands as successful unless they ran.
- Work in small steps. At handoff, list implemented flows, checks actually performed, remaining blockers, and any credentials or provider setup the owner must supply.
- Do not publish, spend money, contact customers, delete source data or run irreversible migrations without the project owner's authorization.

## Prerequisites
- Python, a private localhost workbench, PDF.js assets and licensed compatible pypdf/PyMuPDF installations. Start with unsigned synthetic PDFs and a private output directory. Install OCR or LibreOffice only for an explicitly enabled operation; document dependencies, resource limits and fidelity warnings.
- Implementation components: Python, FastAPI and SQLite job metadata, with immutable user-selected PDF files and a static PDF.js viewer. pypdf for supported page selection/merge, and a chosen PyMuPDF release for rendering and supported annotation export after checking its license. Pin library versions and document the supported PDF feature subset. Optional OCRmyPDF/Tesseract for scanned PDFs and separately installed LibreOffice headless for supported Office-to-PDF conversions; run each in a bounded isolated job, with no claim of universal reverse conversion.
- Scope boundary: Cross-device sync, certified signing and universal file fidelity are excluded.

## Stack and architecture
- Python, FastAPI and SQLite job metadata, with immutable user-selected PDF files and a static PDF.js viewer.
- pypdf for supported page selection/merge, and a chosen PyMuPDF release for rendering and supported annotation export after checking its license. Pin library versions and document the supported PDF feature subset.
- Optional OCRmyPDF/Tesseract for scanned PDFs and separately installed LibreOffice headless for supported Office-to-PDF conversions; run each in a bounded isolated job, with no claim of universal reverse conversion.
- Domain model: PDF documents, page selections, annotation revisions, conversion jobs and output manifests

## Security and data integrity
- Accept user-selected local documents only. Validate file types and size/page limits, keep originals immutable, deny path escapes and run converters without shell interpolation in isolated temporary directories. Treat PDF links/actions and imported annotations as untrusted, protect private outputs, and never present overlays as secure redaction.
- Correctness boundary: PDF signatures and forms may be invalidated by edits; an overlay is not secure redaction and originals are never overwritten.
- Create a page/annotation revision before processing, render the preview from that revision and export to a new file. Save output only after successful parsing/rendering, keep warnings for signature/form changes visible, and retain the source after failed OCR/conversion.
- Export the source reference, page selections, annotation revisions and completed output manifest. Restore settings/jobs separately from originals; temporary conversion files can be discarded after failure without losing user source files.

## Agent implementation rules
- Project rule — data model: PDF documents, page selections, annotation revisions, conversion jobs and output manifests
- Project rule — preserve this invariant: PDF signatures and forms may be invalidated by edits; an overlay is not secure redaction and originals are never overwritten.
- Project rule — acceptance evidence: An annotated export reopens with the intended marks; a failed conversion retains its source and displays which operation failed.

## Optional agent skills and references
- Optional external skill: [modern-python](https://github.com/trailofbits/skills/blob/main/plugins/modern-python/skills/modern-python/SKILL.md) — Set up Python projects with pyproject.toml, dependency management, linting, typing and automated checks. Review its instructions and compatibility before use; it does not grant deployment, data-access or publication permission.
- Optional external skill: [pdf](https://github.com/anthropics/skills/blob/main/skills/pdf/SKILL.md) — Process PDFs through extraction, generation, page operations, form filling and OCR workflows. Review its instructions and compatibility before use; it does not grant deployment, data-access or publication permission.
- Optional external skill: [sharp-edges](https://github.com/trailofbits/skills/blob/main/plugins/sharp-edges/skills/sharp-edges/SKILL.md) — Review security-sensitive APIs and configuration for dangerous defaults and easy-to-misuse interfaces. Review its instructions and compatibility before use; it does not grant deployment, data-access or publication permission.

Read the linked SKILL.md and its dependencies before adding a skill. Select only the skills matching this project's runtime and task; their documentation does not supply API access, credentials or approval to perform external actions. Pin the reviewed revision where the tool supports it. Follow the chosen agent's documented project-level installation mechanism.

## Distribution ideas
These are optional planning notes. Obtain the owner's approval before publishing or contacting anyone.
- Demonstrate the actual Xodo Pro-inspired workflow with owned or clearly labeled sample data: View and annotate local PDFs, reorder or combine pages and export new copies through a private workbench. Add optional OCR and Office conversion only as separately visible operations with fidelity warnings.
- Publish a reproducible walkthrough with this observable result: An annotated export reopens with the intended marks; a failed conversion retains its source and displays which operation failed.
- Explain who can operate this scoped tool, its setup and ongoing costs, and these remaining product gaps: Cross-device sync, certified signing and universal file fidelity are excluded. Avoid guaranteed savings, performance scores or implied endorsement.

## Engineering roadmap
1. Phase 1 — Scope and fixtures. Implement this bounded workflow: View and annotate local PDFs, reorder or combine pages and export new copies through a private workbench. Add optional OCR and Office conversion only as separately visible operations with fidelity warnings. Record prerequisites, select representative user-owned fixtures and document the unsupported features: Cross-device sync, certified signing and universal file fidelity are excluded.
2. Phase 2 — Durable model. Model PDF documents, page selections, annotation revisions, conversion jobs and output manifests Add migrations or a versioned document format, explicit validation, stable IDs and a visible import-error report. Preserve this rule: PDF signatures and forms may be invalidated by edits; an overlay is not secure redaction and originals are never overwritten.
3. Phase 3 — Complete the first useful path. Implement the workflow's input, review and output interface, with clear controls and explicit empty/error states. Create a page/annotation revision before processing, render the preview from that revision and export to a new file. Save output only after successful parsing/rendering, keep warnings for signature/form changes visible, and retain the source after failed OCR/conversion.
4. Phase 4 — Permissions and integration failure. Accept user-selected local documents only. Validate file types and size/page limits, keep originals immutable, deny path escapes and run converters without shell interpolation in isolated temporary directories. Treat PDF links/actions and imported annotations as untrusted, protect private outputs, and never present overlays as secure redaction. Request integration credentials and permissions only for the enabled feature; show a disconnected state instead of mock results.
5. Phase 5 — Portable handoff. Export the source reference, page selections, annotation revisions and completed output manifest. Restore settings/jobs separately from originals; temporary conversion files can be discarded after failure without losing user source files. Include setup, operating limits, fixture walkthrough and shutdown/restart instructions in the README.
6. Phase 6 — Acceptance scenarios. An annotated export reopens with the intended marks; a failed conversion retains its source and displays which operation failed. Repeat the workflow after restart and with a denied permission or unavailable dependency; show recoverable failure rather than a success placeholder.

## Paid-product capabilities outside this build
- cross-platform apps, cloud integrations, format coverage, and mobile polish
- pixel-perfect proprietary PDF engine
- identity verification
- qualified trust services
- large template and integration ecosystem

## Implementation prompt
WORKING SLICE
View and annotate local PDFs, reorder or combine pages and export new copies through a private workbench. Add optional OCR and Office conversion only as separately visible operations with fidelity warnings.

Build this scoped Xodo Pro-inspired workflow with a documented data model and visible failure states.

Architecture
- Python, FastAPI and SQLite job metadata, with immutable user-selected PDF files and a static PDF.js viewer.
- pypdf for supported page selection/merge, and a chosen PyMuPDF release for rendering and supported annotation export after checking its license. Pin library versions and document the supported PDF feature subset.
- Optional OCRmyPDF/Tesseract for scanned PDFs and separately installed LibreOffice headless for supported Office-to-PDF conversions; run each in a bounded isolated job, with no claim of universal reverse conversion.

Prerequisites and limits
Python, a private localhost workbench, PDF.js assets and licensed compatible pypdf/PyMuPDF installations. Start with unsigned synthetic PDFs and a private output directory. Install OCR or LibreOffice only for an explicitly enabled operation; document dependencies, resource limits and fidelity warnings.
Outside this release: Cross-device sync, certified signing and universal file fidelity are excluded.

Data model and correctness
PDF documents, page selections, annotation revisions, conversion jobs and output manifests
Invariant: PDF signatures and forms may be invalidated by edits; an overlay is not secure redaction and originals are never overwritten.
Create a page/annotation revision before processing, render the preview from that revision and export to a new file. Save output only after successful parsing/rendering, keep warnings for signature/form changes visible, and retain the source after failed OCR/conversion.

Security and privacy
Accept user-selected local documents only. Validate file types and size/page limits, keep originals immutable, deny path escapes and run converters without shell interpolation in isolated temporary directories. Treat PDF links/actions and imported annotations as untrusted, protect private outputs, and never present overlays as secure redaction.

Recovery and export
Export the source reference, page selections, annotation revisions and completed output manifest. Restore settings/jobs separately from originals; temporary conversion files can be discarded after failure without losing user source files.

Implementation order
1. Phase 1 — Scope and fixtures. Implement this bounded workflow: View and annotate local PDFs, reorder or combine pages and export new copies through a private workbench. Add optional OCR and Office conversion only as separately visible operations with fidelity warnings. Record prerequisites, select representative user-owned fixtures and document the unsupported features: Cross-device sync, certified signing and universal file fidelity are excluded.
2. Phase 2 — Durable model. Model PDF documents, page selections, annotation revisions, conversion jobs and output manifests Add migrations or a versioned document format, explicit validation, stable IDs and a visible import-error report. Preserve this rule: PDF signatures and forms may be invalidated by edits; an overlay is not secure redaction and originals are never overwritten.
3. Phase 3 — Complete the first useful path. Implement the workflow's input, review and output interface, with clear controls and explicit empty/error states. Create a page/annotation revision before processing, render the preview from that revision and export to a new file. Save output only after successful parsing/rendering, keep warnings for signature/form changes visible, and retain the source after failed OCR/conversion.
4. Phase 4 — Permissions and integration failure. Accept user-selected local documents only. Validate file types and size/page limits, keep originals immutable, deny path escapes and run converters without shell interpolation in isolated temporary directories. Treat PDF links/actions and imported annotations as untrusted, protect private outputs, and never present overlays as secure redaction. Request integration credentials and permissions only for the enabled feature; show a disconnected state instead of mock results.
5. Phase 5 — Portable handoff. Export the source reference, page selections, annotation revisions and completed output manifest. Restore settings/jobs separately from originals; temporary conversion files can be discarded after failure without losing user source files. Include setup, operating limits, fixture walkthrough and shutdown/restart instructions in the README.
6. Phase 6 — Acceptance scenarios. An annotated export reopens with the intended marks; a failed conversion retains its source and displays which operation failed. Repeat the workflow after restart and with a denied permission or unavailable dependency; show recoverable failure rather than a success placeholder.

Acceptance
An annotated export reopens with the intended marks; a failed conversion retains its source and displays which operation failed.
Use real source data or clearly labeled fixtures. Explain unsupported input and provider failures; do not fabricate analytics, delivery receipts, accuracy claims or security guarantees.

Optional agent guidance
Optional external skill: [modern-python](https://github.com/trailofbits/skills/blob/main/plugins/modern-python/skills/modern-python/SKILL.md) — Set up Python projects with pyproject.toml, dependency management, linting, typing and automated checks. Review its instructions and compatibility before use; it does not grant deployment, data-access or publication permission.
Optional external skill: [pdf](https://github.com/anthropics/skills/blob/main/skills/pdf/SKILL.md) — Process PDFs through extraction, generation, page operations, form filling and OCR workflows. Review its instructions and compatibility before use; it does not grant deployment, data-access or publication permission.
Optional external skill: [sharp-edges](https://github.com/trailofbits/skills/blob/main/plugins/sharp-edges/skills/sharp-edges/SKILL.md) — Review security-sensitive APIs and configuration for dangerous defaults and easy-to-misuse interfaces. Review its instructions and compatibility before use; it does not grant deployment, data-access or publication permission.
Project rule — data model: PDF documents, page selections, annotation revisions, conversion jobs and output manifests
Project rule — preserve this invariant: PDF signatures and forms may be invalidated by edits; an overlay is not secure redaction and originals are never overwritten.
Project rule — acceptance evidence: An annotated export reopens with the intended marks; a failed conversion retains its source and displays which operation failed.

## Completion evidence
Demonstrate the prompt's acceptance scenarios against the scoped workflow. Include setup from a clean checkout and failure recovery. Check persistence across restart and export/restore only for the state the prompt says to store; for memory-only tools, confirm that temporary content is discarded as specified. Record actual results and remaining limitations. A detailed plan alone does not establish a working replacement.