noxfile, docs: Add detailed coverage report generation and documentation updates

- Updated `noxfile.py` to include coverage reports in HTML, XML, and Markdown,
  stored under `coverage/py<version>/`.
- Extended `TESTING_GUIDELINES.md` and `AGENTS.md` to document new coverage
  report formats and locations.
- Reinforced maintaining high client coverage for key methods and ensuring
  serialization of optional payload branches is tested.

Assisted-by: Codex

Author: datalogics-kam

.gitignore

@@ -453,3 +453,4 @@ $RECYCLE.BIN/
 *.speedscope.json
 
 !pyrightconfig.json
+/coverage/

AGENTS.md

@@ -28,6 +28,10 @@
 - `nox` executes pytest sessions with built-in parallelism; when invoking pytest
   directly use `pytest -n 8 --maxschedchunk 2` to mirror the parallel test
   scheduling and keep runtimes predictable.
+- Coverage reports (XML/Markdown/HTML) are produced by the nox `tests` session
+  and stored under `coverage/py<version>/` (for example,
+  `coverage/py3.12/coverage.xml`, `coverage/py3.12/coverage.md`,
+  `coverage/py3.12/html/`).
 
 ## Coding Style & Naming Conventions
 
@@ -138,6 +142,13 @@
   description with the reason and the follow-up plan; otherwise reviewers should
   block the change. Treat this as a release gate on par with unit tests.
 
+- **Client coverage criteria:** `PdfRestClient` and `AsyncPdfRestClient` are
+  customer-facing entry points and must retain high coverage. Every public
+  client method must have at least one unit test that exercises the REST call
+  path (MockTransport + request assertions), with distinct sync and async tests.
+  Optional payload branches (`pages`, `output`, `rgb_color`, etc.) need explicit
+  coverage so serialization regressions are caught.
+
 - Write pytest tests: files named `test_*.py`, test functions `test_*`, fixtures
   in `conftest.py` where shared.
 

TESTING_GUIDELINES.md

@@ -13,13 +13,23 @@ iteration required.
   request customization, validation failures, file helpers, and live calls. Do
   not hide the transport behind a parameter; the test name itself should reveal
   which client is under test.
+- **Maintain high client coverage.** `PdfRestClient` and `AsyncPdfRestClient`
+  are the primary customer-facing entry points. Every public client method must
+  have at least one unit test that exercises the REST call path (MockTransport
+  asserting method/path/headers/body). Optional payload branches (for example,
+  `pages`, `output`, `rgb_color`, and output-prefix fields) require explicit
+  tests so serialization differences are caught early.
 - **Check parity regularly.** Run `scripts/check_test_parity.sh` (defaults to
   `upstream/main..HEAD`) to spot missing sync/async counterparts, keeping
   parameterized test IDs aligned between transports.
 - **Exercise both sides of the contract.** Hermetic tests (via
   `httpx.MockTransport`) validate serialization and local validation. Live
   suites prove the server behaves the same way, including invalid literal
   handling.
+- **Know where coverage lands.** The nox `tests` session writes coverage reports
+  to `coverage/py<version>/` (XML, Markdown, and HTML). Example:
+  `coverage/py3.12/coverage.xml`, `coverage/py3.12/coverage.md`,
+  `coverage/py3.12/html/`.
 - **Reset global state per test.** Use
   `monkeypatch.delenv("PDFREST_API_KEY", raising=False)` (or `setenv`) so
   clients never inherit accidental API keys. Patch `importlib.metadata.version`

noxfile.py

@@ -189,10 +189,18 @@ def tests(session: nox.Session) -> None:
         f"--python={session.virtualenv.location}",
         env={"UV_PROJECT_ENVIRONMENT": session.virtualenv.location},
     )
+    coverage_dir = PROJECT_ROOT / "coverage" / f"py{session.python}"
+    coverage_dir.mkdir(parents=True, exist_ok=True)
+    htmlcov_dir = coverage_dir / "html"
+    xml_report = coverage_dir / "coverage.xml"
+    md_report = coverage_dir / "coverage.md"
     _ = session.run(
         "pytest",
         "--cov=pdfrest",
         "--cov-report=term-missing",
+        f"--cov-report=html:{htmlcov_dir}",
+        f"--cov-report=xml:{xml_report}",
+        f"--cov-report=markdown:{md_report}",
         *pytest_args,
     )