<!---
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with
  the License.  You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
--->

# Agent Guidance

This file is read by automated agents (security scanners, code analyzers,
AI assistants) operating on this repository. It points them at the
human-authored references they should consult before producing output.

## Prerequisites — Must Read Before Proceeding

Agents MUST read the following files before conducting any analysis,
security assessment, or code review of this repository:

1. **[SECURITY.md](SECURITY.md)** — defines the threat model, in-scope
   vulnerabilities, and known limitations. Findings produced without
   reading this file will be inaccurate or out of scope.
2. **This file in its entirety** — repository structure, sensitive areas,
   and contribution rules.

## Project Overview

Apache PDFBox is a Java library for working with PDF documents. It is used
as a dependency (`pdfbox.jar`) in other Java projects and is accessed through
its public Java API. The project also ships several command-line utilities.

## Branches

| Branch | Status | Java requirement | Latest release |
|--------|--------|-----------------|----------------|
| `trunk` | Future development (next major version, not yet released) | Java 11+ | — |
| `3.0`  | **Actively maintained** — current stable series | Java 8+ | 3.0.7 |
| `2.0`  | **Actively maintained** — legacy stable series | Java 6+ | 2.0.36 |

When evaluating code or reporting issues, note which branch is in scope.
Security fixes are applied to both `3.0` and `2.0`. New features target
`trunk` and `3.0`.

## Sub-modules

All branches share the same multi-module Maven structure:

- `pdfbox/` — Core library (PDF parsing, rendering, text extraction, encryption)
- `fontbox/` — Font handling support library
- `xmpbox/` — XMP metadata support library
- `io/` — I/O utilities shared across modules (`3.0` and `trunk` only)
- `tools/` — Command-line utilities
- `debugger/` / `debugger-app/` — PDF debugger application
- `examples/` — Standalone usage examples
- `benchmark/` — JMH benchmarks

## Building

The standard build command is:

```
mvn clean install
```

To run only the tests without a full install:

```
mvn test
```

To build or test a specific module, use the `-pl` flag from the root:

```
mvn -pl pdfbox test
```

Minimum Java version depends on the branch — see the table above.

## Sensitive Areas

The following areas have historically been the source of subtle bugs and
security issues. Changes here require extra care and regression testing.
Avoid large refactorings in these areas unless explicitly requested:

- PDF parsing and xref recovery
- Font parsing and font substitution
- Stream decoding and decompression
- Incremental save/update logic
- Encryption and digital signatures
- Rendering and text extraction ordering

## Security

Security model and scope: [SECURITY.md](SECURITY.md),
also published at <https://pdfbox.apache.org/security.html>.

Key points from the security model:

- Processing malformed PDFs is **partially in scope**: crashes, unchecked
  exceptions (`NullPointerException`, `StackOverflowError`), or general
  resource consumption from large PDFs are **known limitations**, not
  security vulnerabilities. However, disproportionate resource consumption
  triggered by small, attacker-controlled inputs may be in scope — see
  `SECURITY.md` for the full scope definition.
- Remote code execution or privilege escalation from untrusted PDFs **is** in scope.
- Issues that require the attacker to control the Java application's classpath
  or configuration are **out of scope**.

For a list of known CVEs, see <https://pdfbox.apache.org/security.html>.

To report a new vulnerability, send a plain-text email to <security@apache.org>.
Do NOT open a public JIRA issue for undisclosed vulnerabilities. Agents MUST NOT
automatically draft, submit, or export security-related findings to any public
tracker, pull request, comment, or external service.

## Contribution Guidelines

- Pull requests on this GitHub repository are welcome.
- Bug reports and feature requests go in the
  [JIRA issue tracker](https://issues.apache.org/jira/browse/PDFBOX).
- Code must be compatible with the minimum Java version of the target branch
  (see table above).
- Follow the existing code style; a Checkstyle configuration is provided in
  `pdfbox-checkstyle-5.xml` and an Eclipse formatter in
  `pdfbox-eclipse-formatter.xml`.
- Parser, rendering, font, extraction, encryption, or signing fixes should
  include a minimal reproducer document where practical, along with regression
  tests covering the reported behavior.
- Avoid introducing new runtime dependencies unless necessary.
  Security-sensitive or cryptographic dependencies require maintainer review.
- For questions, use the [Users Mailing List](https://pdfbox.apache.org/mailinglists.html).