diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 94d0b7b..66bc4c8 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -77,10 +77,10 @@ fonts/            # Pre-built font data modules (.js/.d.ts) — 22 scripts + mat
 tools/            # CLI tools: build-font-data.cjs (TTF → data module); build-emoji-font (bundled via tsup from scripts/build-emoji-font.ts → dist/tools/, npx pdfnative-build-emoji-font — generates colour-emoji data modules up to the full ~3,600-glyph set)
 scripts/          # Modular sample PDF generation (48 generators; persian-showcase.ts + print-showcase.ts, signature-ltv.ts + incremental-metadata.ts added in v1.7.0; text-extract-showcase.ts added in v1.6.0; math-symbols.ts + svg-text-labels.ts + layout-debug-overlay.ts + annotations-showcase.ts + font-compiler-demo.ts added in v1.5.0; outline-bookmarks.ts + pdf-manipulation.ts added in v1.4.0; currency-symbols.ts + color-emoji-showcase real-world rewrite added in v1.3.0; signature-placeholder.ts, bidi-embeddings-showcase.ts, document-table-parity.ts, use-lite-showcase.ts added in v1.2.0/v1.3.0). scripts/lib/ holds the shared deterministic emoji-build core (emoji-font-core.ts, curated-emoji.ts, emoji-cli.ts) used by both build-color-emoji-data.ts and the bundled build-emoji-font CLI
 test-output/extreme/  # Visual regression baselines for extreme scripts (extreme-bidi.pdf, extreme-tamil.pdf, extreme-bengali-devanagari.pdf, extreme-arabic-harakat.pdf, extreme-bidi-isolates.pdf)
-tests/            # 2665+ tests (122 files: unit/integration/fuzz/parser/visual) mirroring src/ structure
+tests/            # 2686+ tests (123 files: unit/integration/fuzz/parser/visual/docs) mirroring src/ structure
 bench/            # Performance benchmarks (vitest bench)
 docs/             # GitHub Pages landing site (pdfnative.dev) — pure HTML/CSS/JS, zero build deps
-  └── playgrounds/  # Interactive browser playgrounds (extreme-scripts.html, scale.html)
+  └── playgrounds/  # 9 interactive browser playgrounds (extreme-scripts, all-scripts, toolkit, charts, authoring-plus, scale, cli, mcp, react)
 ```
 
 - **Single entry point**: `src/index.ts` re-exports everything. All public API surfaces live there.
@@ -103,7 +103,7 @@ docs/             # GitHub Pages landing site (pdfnative.dev) — pure HTML/CSS/
 
 ```bash
 npm run build           # tsup → dist/ (ESM + CJS + .d.ts)
-npm run test            # vitest run (2665+ tests, 122 files)
+npm run test            # vitest run (2686+ tests, 123 files)
 npm run test:watch      # vitest (watch mode)
 npm run test:coverage   # vitest with v8 coverage (thresholds: 88/80/85/90)
 npm run test:generate   # Generate ~242 sample PDFs → test-output/ (incl. extreme/, emoji/, pdfa-latin/, forms/, charts/, parser/ baselines)
@@ -113,14 +113,14 @@ npm run typecheck:scripts # tsc --project tsconfig.scripts.json --noEmit
 npm run typecheck:all   # typecheck src/ + tests/ + scripts/
 npm run lint            # eslint src/ (ESLint 9 + typescript-eslint strict)
 npm run validate:pdfa   # veraPDF over every PDF/A-claiming sample (auto-detected; coverage canary vs declared.pdfaSamples; skips with exit 0 when veraPDF is absent, blocking in CI)
-npm run verify:docs     # 17 offline rules over docs/, playgrounds, README, llms files (ecosystem.json is the source of truth)
+npm run verify:docs     # 22 offline rules over docs/, playgrounds, README, llms files (ecosystem.json is the source of truth)
 ```
 
 - Build tool: **tsup** (dual ESM/CJS, tree-shakeable, sourcemaps)
 - Test runner: **vitest** (fast, native ESM, watch mode, v8 coverage)
 - CI: GitHub Actions — lint/typecheck/test/build on Node 22/24
 - Publish: GitHub Actions OIDC Trusted Publishing (`npm publish --access public`; provenance is attached automatically via the workflow's `id-token: write`)
-- All new code must have tests. 95%+ statements measured at the v1.6.0 release; CI enforces 88/80/85/90. 2665+ tests (122 files)
+- All new code must have tests. 95%+ statements measured at the v1.6.0 release; CI enforces 88/80/85/90. 2686+ tests (123 files)
 
 ## Conventions
 
@@ -186,7 +186,7 @@ npm run verify:docs     # 17 offline rules over docs/, playgrounds, README, llms
 - Watermarks: ExtGState for transparency (`/ca opacity`), text rotation via `cos(θ) sin(θ) -sin(θ) cos(θ) cx cy Tm`, image centering with aspect ratio
 - Watermark validation: PDF/A-1b blocks transparency (ISO 19005-1 §6.4) — `validateWatermark()` throws
 - Watermark position: `'background'` = ops before content stream; `'foreground'` = ops after content stream
-- Table of contents: `TocBlock` with multi-pass pagination (max 3 passes), `_renderToc()` with dot leaders, right-aligned page numbers
+- Table of contents: `TocBlock` with multi-pass pagination (max 3 passes), `renderToc()` with dot leaders, right-aligned page numbers
 - TOC internal links: named destinations `/Dests << /toc_h_N [pageObj /XYZ x y null] >>` in catalog; annotations use `/Dest /toc_h_N` (not `/URI`)
 - TOC tagged mode: `/TOC` structure element with `/TOCI` children for PDF/UA compliance
 - Smart tables (v1.2.0): `TableBlock` gains six optional fields — `wrap` (`'auto'`|`'always'`|`'never'`, default `'auto'`), `repeatHeader` (default `true`), `zebra` (`boolean|PdfColor`, default `false`, true uses `'0.969 0.973 0.984'`), `caption`, `minRowHeight` (default `12`), `cellPadding` (default `3`). Architecture: `planTable()` in `pdf-renderers.ts` measures once; `_paginateBlocks()` in `pdf-document.ts` slices at row boundaries into `TableSlice` items; `renderTable()` is page-lifecycle-free and accepts an optional `slice` arg. Tagged-mode `/Table` continues across slices via shared `tableStructAccum` array (ISO 14289-1 §7.10.6); `/Caption` emitted once. Single-page tables that fit without wrapping are byte-identical to v1.1.0 in their **body** rendering (header baseline `+4`, data baseline `+3`, `ROW_H=12`, `TH_H=15` preserved); right- and centre-aligned **header** glyph positioning shifts 2–5pt because v1.2.0 corrects a pre-1.2.0 width-measurement bug (see next bullet). `planTable()` and `TableSlice` are internal — NOT re-exported from `src/index.ts`.
@@ -256,7 +256,7 @@ npm run verify:docs     # 17 offline rules over docs/, playgrounds, README, llms
 - Latin VF (PDF/A): Noto Sans VF (OFL-1.1) bundled as `fonts/noto-sans-data.{js,d.ts}` under lang `'latin'`. Activates automatically for PDF/A documents containing non-WinAnsi Latin (curly quotes, em-dash, ellipsis…). Opt-in via `registerFont('latin', () => import('pdfnative/fonts/noto-sans-data.js'))`.
 - Document outline/bookmarks (v1.4.0): `buildOutlineObjects(items, startObjNum, pageObjNumFor, defaultY, fmtNum, pageCount)` in `src/core/pdf-outline.ts` builds the `/Outlines` tree (`/First /Last /Next /Prev /Parent /Count`, nested children, `/F` flags bold=2 italic=1, `/C` color, `/Dest [pageObj /XYZ 0 y null]`). Titles via `encodePdfTextString`. `OutlineItem.open?: boolean` (default true) — `false` emits a **negative** `/Count` (collapsed, ISO 32000-1 §12.3.3); a collapsed node contributes only itself (not its hidden descendants) to ancestors' visible counts (`openDescendantCount` magnitude + sign by `open`). Wired into `pdf-document.ts` as **trailing indirect objects** appended after embedded files (`totalObjs = outlineStart + built.totalObjects - 1`) so the catalog-rewrite offset-adjustment loop covers them — same pattern as colour-emoji/embedded-files. `DocumentParams.outline?: readonly OutlineItem[] | 'auto'`; `'auto'` derives a nested tree from heading levels via `autoOutlineFromHeadings()`. Catalog gains `/Outlines N 0 R`.
 - Page labels (v1.4.0): `buildPageLabelsDict(ranges, pageCount)` in `src/core/pdf-page-labels.ts` emits an inline `/PageLabels << /Nums [...] >>` number tree. `PageLabelStyle` decimal/roman/Roman/alpha/Alpha/none → `/S /D|r|R|a|A` (none omits `/S`). `PageLabelRange { startPage, style?, prefix?, start? }` — validated for ordering/bounds; prefix parens escaped. `DocumentParams.pageLabels?: readonly PageLabelRange[]`. Inline (not indirect) so no object-number impact.
-- Page-tree manipulation (v1.4.0): `mergePdfs(sources, opts?)`, `splitPdf(src, ranges)`, `extractPages(src, indices)` in `src/parser/pdf-pagetree.ts` deep-copy kept pages + their transitive object graph into a fresh object-number space (obj 1=Catalog, 2=Pages, 3+=graph). `copyObject()` is memoized per-reader and cycle-safe; `rewrite()`/`copyObject()`/`serializeStreamBody()` thread a `depth` capped at `MAX_COPY_DEPTH=2000` (throws on deeper nesting/ref-chains — stack-overflow hardening). `resolveInherited()` folds MediaBox/CropBox/Rotate/Resources from ancestors onto each page; `filterAnnotations()` keeps only URI `/Link` annots; `serializeValue/Dict` are binary-safe (Latin-1). `serializeDocument()` emits a deterministic content-addressed trailer `/ID [<hex> <hex>]` via `md5(...)` imported from `core/pdf-encrypt.js` (parser→core is an allowed edge). `assertNotEncrypted()` throws on `/Encrypt`. `MAX_MERGE_SOURCES=50`. `MergeOptions { dropSignatures?, dropAnnotations?, maxOutputSize?, password?, encrypt? }` (`password` decrypts encrypted sources and `encrypt` re-encrypts the rebuilt output — both added in v1.6.0) — `maxOutputSize` (default `DEFAULT_MAX_OUTPUT_SIZE = 256*1024*1024`; `Infinity` disables) is a secure-by-default output ceiling enforced via `accountBytes()`/`setBody()` and a pre-flight `accountBytes(ctx, stream.data.length)` in `serializeStreamBody()` *before* the Latin-1 conversion (rejects multi-GB streams before they materialise — OOM hardening); validated at entry via `resolveMaxOutputSize()`. `splitPdf(src, ranges, opts?)` and `extractPages(src, indices, opts?)` also accept `MergeOptions` (additive trailing param). Full rebuild (not in-place surgery) — unblocks `pdfnative-mcp` merge_pdfs/split_pdf.
+- Page-tree manipulation (v1.4.0): `mergePdfs(sources, opts?)`, `splitPdf(src, ranges)`, `extractPages(src, indices)` in `src/parser/pdf-pagetree.ts` deep-copy kept pages + their transitive object graph into a fresh object-number space (obj 1=Catalog, 2=Pages, 3+=graph). `copyObject()` is memoized per-reader and cycle-safe; `rewrite()`/`copyObject()`/`serializeStreamBody()` thread a `depth` capped at `MAX_COPY_DEPTH=2000` (throws on deeper nesting/ref-chains — stack-overflow hardening). `resolveInherited()` folds MediaBox/CropBox/Rotate/Resources from ancestors onto each page; `filterAnnotations()` keeps only URI `/Link` annots; `serializeValue/Dict` are binary-safe (Latin-1). `serializeDocument()` emits a deterministic content-addressed trailer `/ID [<hex> <hex>]` via `md5(...)` imported from `core/pdf-encrypt.js` (parser→core is an allowed edge). `MAX_MERGE_SOURCES=50`. `MergeOptions { dropSignatures?, dropAnnotations?, maxOutputSize?, password?, encrypt? }` (`password` decrypts encrypted sources and `encrypt` re-encrypts the rebuilt output — both added in v1.6.0) — `maxOutputSize` (default `DEFAULT_MAX_OUTPUT_SIZE = 256*1024*1024`; `Infinity` disables) is a secure-by-default output ceiling enforced via `accountBytes()`/`setBody()` and a pre-flight `accountBytes(ctx, stream.data.length)` in `serializeStreamBody()` *before* the Latin-1 conversion (rejects multi-GB streams before they materialise — OOM hardening); validated at entry via `resolveMaxOutputSize()`. `splitPdf(src, ranges, opts?)` and `extractPages(src, indices, opts?)` also accept `MergeOptions` (additive trailing param). Full rebuild (not in-place surgery) — unblocks `pdfnative-mcp` merge_pdfs/split_pdf.
 - streamToFile (v1.4.0): `streamToFile(stream, filePath, { signal? })` in `src/core/pdf-stream-writer.ts` drains any `AsyncGenerator<Uint8Array>` to disk in Node, honouring write back-pressure (awaits `'drain'`) and `AbortSignal`; returns `{ bytesWritten, path }`. On abort (pre-start, mid-iter, or post-loop) or any write error it releases the fd (awaits `'close'`) and best-effort `fs.rmSync(filePath, { force: true })` so no orphaned partial file is left behind. Uses top-level `import type * as NodeFs from 'node:fs'` + dynamic `await import('node:fs')` (no static node dep — keeps browser/Deno builds clean). ESLint forbids inline `import()` type annotations, so the type-only import MUST be top-level.
 - COLRv1 advanced compositing (v1.4.0): `colr-parser.ts` resolves `PaintSweepGradient` (format 8) → `SweepGradientPaint { kind:'sweep', center, startAngle, endAngle, stops, extend }` (matrix rotation folded via `Math.atan2`), and `PaintComposite` (format 32) → backdrop+source layers with the source tagged `ColorLayer.blendMode` via `compositeModeToBlendMode(mode)` (separable modes 3/13–27 → Normal/Multiply/Screen/Overlay/Darken/Lighten/ColorDodge/ColorBurn/HardLight/SoftLight/Difference/Exclusion/Hue/Saturation/Color/Luminosity; structural Porter-Duff modes → `null` → `UnsupportedPaint` → mono fallback). `pdf-color-glyph.ts`: `emitSweep()` renders flat triangular wedges (no `/Shading` resource); unified `gsFor(alpha, bm)` ExtGState helper combines `/ca`+`/BM`. New types `SweepGradientPaint` + `ColorLayer.blendMode?` in `src/types/pdf-types.ts`.
 - Pluggable signature crypto provider (v1.4.0): `src/crypto/crypto-provider.ts` mirrors the `setDeflateImpl` global-registry pattern — module-level `_cryptoProvider`, `setCryptoProvider(provider | null)`, `getCryptoProvider()`. `CryptoProvider { sign(tbs, algorithm): Uint8Array }` receives the **DER-encoded CMS signed attributes** (`signedAttrsForSig`, a SET tag 0x31) and hashes them internally (native `crypto.sign('sha256', …)`); RSA → PKCS#1 v1.5 over SHA-256(tbs), ECDSA → DER-encoded sig. Dispatch lives in `buildSignerInfo()` in `src/crypto/cms.ts`: `const provider = options.provider ?? getCryptoProvider()` — when present, `signatureValue = provider.sign(...)` and `rsaKey`/`ecKey` are not required; else the pure-JS `rsaSignHash`/`ecdsaSignHash` fallback runs. `CmsSignOptions.provider` and `PdfSignOptions.provider` thread the per-call provider (per-call wins over global). Exported from `src/index.ts`. This is the in-library escape hatch for the SECURITY.md BigInt timing caveat.
@@ -305,7 +305,7 @@ npm run verify:docs     # 17 offline rules over docs/, playgrounds, README, llms
 - **PDF /Info metadata** — Title, Producer (pdfnative), CreationDate in D:YYYYMMDDHHmmss format
 - **Input validation** — at `buildPDF()` boundary: null/undefined/type checks, 100K row limit
 - **URL validation** — at `validateURL()`: blocks javascript:, file:, data: schemes
-- **Test coverage** — 95%+ statements measured at the v1.6.0 release; CI enforces 88/80/85/90 (statements/branches/functions/lines). 2665+ tests (122 files), 89 fuzz tests across 5 files (including recursion/zip-bomb/xref-chain hardening), dual-mode visual-regression suite, performance benchmarks
+- **Test coverage** — 95%+ statements measured at the v1.6.0 release; CI enforces 88/80/85/90 (statements/branches/functions/lines). 2686+ tests (123 files), 89 fuzz tests across 5 files (including recursion/zip-bomb/xref-chain hardening), dual-mode visual-regression suite, performance benchmarks
 - **NPM provenance** — signed builds via GitHub Actions OIDC
 - Security: no `eval()`, no `Function()`, no dynamic code execution
 - No `console.log` in library code (only in tools/ and scripts/). `console.warn` is allowed **only** inside `src/core/pdf-diagnostics.ts` — the single sanctioned sink for conformance diagnostics (silence or redirect via `onDiagnostic`, escalate via `strict`)
diff --git a/.github/instructions/api-design.instructions.md b/.github/instructions/api-design.instructions.md
index cd1023a..6c9775f 100644
--- a/.github/instructions/api-design.instructions.md
+++ b/.github/instructions/api-design.instructions.md
@@ -48,7 +48,10 @@ applyTo: "src/index.ts"
 17. Core — Digital Signatures (`buildSigDict`, `signPdfBytes`, `estimateContentsSize`, `addSignaturePlaceholder`, `PdfSignOptions`, `SigDictMetadata`)
 18. Core — Streaming (`buildPDFStream`, `buildDocumentPDFStream`, `buildPDFStreamTrue`, `buildDocumentPDFStreamTrue`, `buildPDFStreamPageByPage`, `buildDocumentPDFStreamPageByPage`, `streamToFile`, `StreamOptions`)
 19. Crypto — Primitives (`sha384`, `sha512`, `hmacSha256`, `rsaSign`, `ecdsaSign`, `parseCertificate`, `buildCmsSignedData`, `setCryptoProvider`)
-20. Parser — Read & Modify (`openPdf`/`PdfReader`, `createModifier`/`PdfModifier`, `createTokenizer`/`PdfTokenizer`, `parseValue`, `parseIndirectObject`, `parseXrefTable`, `PdfValue`, `ParsedDict`, `PdfRef`, `extractText`, `readFormFields`-family lives in core, `mergePdfs`/`splitPdf`/`extractPages` + streaming variants, `validatePdfUA`, decode filters)
+20. Parser — Read & Modify (`openPdf`/`PdfReader`, `createModifier`/`PdfModifier`, `createTokenizer`/`PdfTokenizer`, `parseValue`, `parseIndirectObject`, `parseXrefTable`, `PdfValue`, `ParsedDict`, `PdfRef`, `extractText`, `readFormFields`-family lives in core, `mergePdfs`/`splitPdf`/`extractPages` + streaming variants, `validatePdfUA`, decode filters, `PdfModifier.updateMetadata` (v1.7.0))
+21. Core — LTV / PAdES (v1.7.0: `signPdfBytesWithTimestamp`, `collectValidationInfo`, `embedValidationInfo`, `addValidationInfo`, `addDocumentTimestamp`, `listSignatures`, `vriKeyForContents`, `buildDocTimeStampDict`; injected transports: `setTimestampProvider`/`getTimestampProvider`, `setRevocationProvider`/`getRevocationProvider`, `TimestampProvider`, `RevocationProvider` — the engine itself never opens a socket)
+22. Core — Print Production (v1.7.0: `layout.print` page boxes + `bleed` shorthand + `marks`, `/Trapped` metadata with XMP parity, custom OutputIntent ICC, `/UserUnit`, print-dialog `viewerPreferences`: `duplex`, `pickTrayByPDFSize`, `printPageRange`, `numCopies`)
+23. Core — PDF/A Diagnostics (v1.7.0: `strict`, `onDiagnostic`, `PdfDiagnostic`, `PdfDiagnosticCode` — codes `PDFA_NO_FONT_ENTRIES`, `PDFA_UNEMBEDDED_FORM_FONT`, `PDFA_DEVICE_CMYK_IMAGE`)
 
 ## Parser Option-Type Precedent
 - Parser-module option/result types live in the module itself (`MergeOptions`,
diff --git a/.github/instructions/pdf-core.instructions.md b/.github/instructions/pdf-core.instructions.md
index 8f1c706..baf6b22 100644
--- a/.github/instructions/pdf-core.instructions.md
+++ b/.github/instructions/pdf-core.instructions.md
@@ -127,7 +127,7 @@ applyTo: "src/core/**"
 - LTR runs: standard encoding path (no BiDi processing)
 - Arabic shaping (`shapeArabicText()`) returns glyphs in logical order — must reverse for RTL visual rendering
 - Hebrew text detected by `containsHebrew()` — uses RTL ordering without shaping
-- Glyph mirroring for brackets/parentheses in RTL context via `MIRROR_MAP`
+- Glyph mirroring for brackets/parentheses in RTL context via `BIDI_MIRRORING_PAIRS` (`bidi-mirroring-data.ts`, full 428-pair UCD table since v1.7.0)
 - CRITICAL: never call `shapeArabicText()` on already-reversed text — always un-reverse to logical first
 
 ## PDF Encryption (ISO 32000-1 §7.6)
@@ -201,7 +201,7 @@ applyTo: "src/core/**"
 - `headerTemplate` / `footerTemplate` on `PdfLayoutOptions` — both builders support them
 - `HEADER_H = 15` constant in `pdf-layout.ts` — header zone reduces available content height
 - Backward compat: `footerText` maps to `{ left: footerText, right: '{page}/{pages}' }`
-- `_renderPageTemplate()` (pdf-document.ts) / `_buildPageTemplate()` (pdf-builder.ts) — renders left/center/right at given Y
+- `renderPageTemplate()` (pdf-document.ts) / `_buildPageTemplate()` (pdf-builder.ts) — renders left/center/right at given Y
 - Default color from `colors.footer` (`PdfColor`), parsed via `parseColor()`
 - Tagged mode: template text wrapped in `/P` structure elements with marked content
 
@@ -225,9 +225,9 @@ applyTo: "src/core/**"
 - **Document builder only** — table builder has no headings concept
 - **Multi-pass pagination** (max 3 iterations):
   1. Pass 1: paginate without TOC → collect `HeadingDestination[]` (destName, text, level, pageIndex, y)
-  2. Pass 2: estimate TOC height via `_estimateTocHeight()`, re-paginate with TOC height included
+  2. Pass 2: estimate TOC height via `estimateTocHeight()`, re-paginate with TOC height included
   3. Pass 3 (if needed): if heading page assignments shifted, re-paginate one more time
-- `_renderToc()`: renders TOC title (bold, larger font), indented entries with dot leaders, right-aligned page numbers
+- `renderToc()`: renders TOC title (bold, larger font), indented entries with dot leaders, right-aligned page numbers
 - TOC entries are `/GoTo` annotations: `<< /Type /Annot /Subtype /Link /Rect [...] /Dest /toc_h_N >>`
 - Annotations starting with `#` prefix → `/Dest` (internal); others → `/URI` (external)
 - **Named destinations** in catalog: `/Dests << /toc_h_0 [pageObj /XYZ x y null] ... >>`
@@ -263,7 +263,7 @@ applyTo: "src/core/**"
 ## Digital Signature Model (pdf-signature.ts — ISO 32000-1 §12.8)
 - `buildSigDict(options, contentsSize?)`: builds the `/Sig` dictionary with `/ByteRange` placeholder (`SigDictMetadata` options: signingTime, name, reason, location, contact)
 - Signature includes `/Filter /Adobe.PPKLite /SubFilter /adbe.pkcs7.detached`
-- `signPdfBytes(pdfBytes, options)`: round-trip sign → inject CMS into `/Contents`; `PdfSignOptions = { signerCert: X509Certificate, rsaKey? | ecKey?, certChain?, algorithm?: 'rsa-sha256' | 'ecdsa-sha256', provider?, ...SigDictMetadata }`
+- `signPdfBytes(pdfBytes, options)`: round-trip sign → inject CMS into `/Contents`; `PdfSignOptions = { signerCert: X509Certificate, rsaKey? | ecKey?, certChain?, algorithm?: 'rsa-sha256' | 'rsa-sha384' | 'rsa-sha512' | 'ecdsa-sha256', provider?, ...SigDictMetadata }`
 - `/ByteRange [0 before after end]`: specifies which bytes are signed (excludes `/Contents` hex)
 - CMS SignedData via `crypto/cms.ts`: signed attributes, certificate embedding, digest
 
diff --git a/.github/instructions/pdfa-conformance.instructions.md b/.github/instructions/pdfa-conformance.instructions.md
index cba5e4f..79bcce0 100644
--- a/.github/instructions/pdfa-conformance.instructions.md
+++ b/.github/instructions/pdfa-conformance.instructions.md
@@ -74,6 +74,22 @@ applyTo: 'src/core/pdf-tags.ts,src/core/pdf-builder.ts,src/core/pdf-document.ts,
   embedded fonts. Do not reintroduce unembedded base-14 references in any
   PDF/A code path.
 
+## Declaration guards (v1.7.0)
+
+- Configurations that would break the declared PDF/A level surface a
+  diagnostic through `src/core/pdf-diagnostics.ts`: `console.warn` by default
+  (deduplicated once per code), a caller-supplied `onDiagnostic` sink, or a
+  thrown error under `strict: true` (`onDiagnostic` is ignored when `strict`
+  is set — diagnostics throw instead).
+- Current codes (stable, additions-only union `PdfDiagnosticCode`):
+  `PDFA_NO_FONT_ENTRIES` (base-14 text without embedded fonts under a claim),
+  `PDFA_UNEMBEDDED_FORM_FONT` (any form field under a claim — the AcroForm
+  `/DR /Helv` is an unembedded Type 1), `PDFA_DEVICE_CMYK_IMAGE` (CMYK JPEG
+  against the sRGB OutputIntent).
+- When adding a new guard: extend the union (never remove or rename a code),
+  include the remedy in the message, and cover both the warn path and the
+  `strict` throw path in tests.
+
 ## Validator workflow
 
 1. `npm run test:generate` — regenerate `test-output/`.
diff --git a/.github/instructions/testing.instructions.md b/.github/instructions/testing.instructions.md
index 97bf442..a2fa9fb 100644
--- a/.github/instructions/testing.instructions.md
+++ b/.github/instructions/testing.instructions.md
@@ -25,15 +25,18 @@ tests/
 ├── worker/         # worker-api
 ├── integration/    # full PDF generation end-to-end, pdf-compression
 ├── fuzzing/        # edge-case & adversarial input tests
+├── docs/           # documentation verifier mirror test (verify-docs)
+├── tools/          # font-data tooling tests
+├── visual/         # dual-mode visual-regression suite
 └── fixtures/       # test data, sample fonts, expected outputs
 scripts/
 ├── generate-samples.ts  # Orchestrator for modular PDF sample generation
-├── generators/          # Per-category sample generators (44 modules)
+├── generators/          # Per-category sample generators (48 modules)
 └── helpers/             # Shared utilities (fonts, images, I/O)
 ```
 
 ## Current State (maintain these thresholds)
-- **2396+ tests** across 105 test files + 1 benchmark file
+- **2686+ tests** across 123 test files + 1 benchmark file
 - Statements: ~95% (threshold: 88%)
 - Branches: ~88% (threshold: 80%)
 - Functions: ~98% (threshold: 85%)
diff --git a/.github/instructions/text-shaping.instructions.md b/.github/instructions/text-shaping.instructions.md
index 7050a70..c93abdf 100644
--- a/.github/instructions/text-shaping.instructions.md
+++ b/.github/instructions/text-shaping.instructions.md
@@ -51,13 +51,13 @@ applyTo: "src/shaping/**"
 - Critical for Thai, Devanagari, Bengali, Tamil, and Vietnamese where combining marks get spatially repositioned
 
 ## BiDi Resolution (UAX #9)
-- Simplified UBA: paragraph level detection (P2-P3), weak type resolution (W1-W7), neutral resolution (N1-N2)
+- Simplified UBA: paragraph level detection (P2-P3), weak type resolution (W1-W7), neutral resolution (N1-N2), and — since v1.7.0 — implicit even-level embedding (I1/I2) so digit runs (EN/AN, incl. Extended Arabic-Indic) keep logical order inside RTL text
 - `BidiType` classification: L (Latin), R (Hebrew), AL (Arabic), EN, AN, ES, ET, CS, WS, ON, NSM, BN
 - Character classification order matters: check NSM/BN/AN/EN specific ranges BEFORE broad Arabic block (0x0600-06FF)
 - General Punctuation (U+2010–U+2027, U+2030–U+205E) classified as ON — covers dashes, quotes, ellipsis, primes
 - `resolveBidiRuns(text)`: main API — returns `BidiRun[]` in visual order (L2 reordering: runs reversed for RTL paragraphs so LTR text renders first at leftmost position)
 - `containsRTL(text)`: fast O(n) check for Arabic/Hebrew content
-- Glyph mirroring via `MIRROR_MAP`: ~40 pairs (parentheses, brackets, guillemets, math symbols)
+- Glyph mirroring via `BIDI_MIRRORING_PAIRS` (`bidi-mirroring-data.ts`): the complete 428-pair UCD `BidiMirroring.txt` table under rule L4 (since v1.7.0 — replaces the former ~40-pair `MIRROR_MAP`)
 - `reverseString()`: surrogate-pair safe reversal for RTL run reordering
 - Levels: 0 = LTR, 1 = RTL, 2 = LTR embedded in RTL
 
diff --git a/.github/prompts/compliance-audit.prompt.md b/.github/prompts/compliance-audit.prompt.md
index 8dead6d..2de2fee 100644
--- a/.github/prompts/compliance-audit.prompt.md
+++ b/.github/prompts/compliance-audit.prompt.md
@@ -65,7 +65,7 @@ Perform a comprehensive compliance audit of pdfnative.
 ### 10. Digital Signature Compliance (ISO 32000-1 §12.8)
 - `/ByteRange` covers entire PDF minus `/Contents` hex
 - CMS SignedData structure embeds X.509 certificate chain
-- `/Filter /Adobe.PPKLite /SubFilter /adbe.pkcs7.detached`
+- `/Filter /Adobe.PPKLite` with `/SubFilter /adbe.pkcs7.detached`, `/ETSI.CAdES.detached` (PAdES profile, v1.7.0), or `/ETSI.RFC3161` (document timestamps, v1.7.0)
 - RSA and ECDSA signatures produce valid ASN.1 DER output
 
 ### 11. Streaming Output Compliance
diff --git a/.github/prompts/quality-gate.prompt.md b/.github/prompts/quality-gate.prompt.md
index 5b08a8a..b12300c 100644
--- a/.github/prompts/quality-gate.prompt.md
+++ b/.github/prompts/quality-gate.prompt.md
@@ -10,7 +10,7 @@ Run the full pdfnative quality gate and report results.
 
 1. `npm run typecheck:all` — verify zero TypeScript errors across src/, tests/, and scripts/
 2. `npm run lint` — verify zero ESLint warnings/errors
-3. `npm run test` — run all unit tests (2396+ expected)
+3. `npm run test` — run all unit tests (2686+ expected)
 4. `npm run test:coverage` — verify coverage thresholds (88% statements / 80% branches / 85% functions / 90% lines)
 5. `npm run build` — verify clean build (ESM + CJS + .d.ts)
 6. Verify `dist/` output contains: `index.js`, `index.cjs`, `index.d.ts`, `worker/index.js`, `tools/index.js`, `tools/build-emoji-font.js` (the last two are required by package.json `exports`/`bin`)
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 75b7ed5..21c8dd5 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -24,8 +24,12 @@ on:
       - 'docs/**'
       - '**.md'
       - 'llms.txt'
+      - 'recipes/**'
+      - 'bench/**'
       - 'scripts/verify-docs.ts'
       - 'scripts/build-llms-full.ts'
+      - 'scripts/build-guides.ts'
+      - 'scripts/build-api-json.ts'
       - '.github/workflows/docs.yml'
       # The api-exists rule cross-checks documented identifiers against src/,
       # so a rename there can break the docs without touching them.
@@ -37,8 +41,12 @@ on:
       - 'docs/**'
       - '**.md'
       - 'llms.txt'
+      - 'recipes/**'
+      - 'bench/**'
       - 'scripts/verify-docs.ts'
       - 'scripts/build-llms-full.ts'
+      - 'scripts/build-guides.ts'
+      - 'scripts/build-api-json.ts'
       - '.github/workflows/docs.yml'
       - 'src/**'
       - 'package.json'
diff --git a/AGENTS.md b/AGENTS.md
index 58031f1..f2ded95 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -8,7 +8,7 @@ Guidance for AI coding agents (Cursor, Aider, Claude Code, Continue, Zed, Cline,
 
 pdfnative is a **zero-runtime-dependency** TypeScript library that generates ISO 32000-1 (PDF 1.7) and ISO 19005 (PDF/A) compliant PDFs. Pure native — no Cairo, no PDFKit, no node-forge, no fontkit, no anything.
 
-Quality bar: GAFAM-grade. 2664+ tests, 95%+ statement coverage measured at v1.6.0 (CI enforces ≥88%), blocking veraPDF validation in CI, SLSA provenance on npm.
+Quality bar: GAFAM-grade. 2686+ tests, 95%+ statement coverage measured at v1.6.0 (CI enforces ≥88%), blocking veraPDF validation in CI, SLSA provenance on npm.
 
 Since v1.6.0 the parser side also **decrypts** (Standard Security Handler, RC4 + AES-128/256), **streams** page-tree merge/split/extract, **fills & flattens** AcroForms — including encrypted sources via encrypted incremental update — **extracts text** with positions (`extractText`), renders native **vector charts**, and **re-encrypts** output (`MergeOptions.encrypt`). All exported from `src/index.ts` like everything else.
 
@@ -16,10 +16,10 @@ Since v1.6.0 the parser side also **decrypts** (Standard Security Handler, RC4 +
 
 ```bash
 npm run build              # tsup → dist/ (ESM + CJS + .d.ts)
-npm run test               # vitest run (2664+ tests)
+npm run test               # vitest run (2686+ tests)
 npm run typecheck:all      # src/ + tests/ + scripts/
 npm run lint               # eslint
-npm run test:generate      # produce ~241 sample PDFs → test-output/
+npm run test:generate      # produce ~242 sample PDFs → test-output/
 npm run validate:pdfa      # local veraPDF run
 ```
 
@@ -102,7 +102,7 @@ See [.github/copilot-instructions.md](.github/copilot-instructions.md) §Archite
 ## Ecosystem context
 
 - [pdfnative-cli](https://github.com/Nizoka/pdfnative-cli) v1.3.0 — terminal wrapper (render, fill, annotate, merge, split, extract, sign, verify, encrypt, decrypt, inspect, extract-text, batch, doctor, schema, completion, govern). Pins pdfnative `^1.6.0` in its `package.json` (semver-accepts 1.7.0); coordinates via that explicit pin.
-- [pdfnative-mcp](https://github.com/Nizoka/pdfnative-mcp) v1.5.0 — Model Context Protocol server exposing 24 AI tools (adds `add_chart`, `read_form_fields`/`fill_form` and `encrypt_pdf`/`decrypt_pdf` on top of the v1.4.0 annotation and governance tools). Pins pdfnative `^1.6.0` (semver-accepts 1.7.0). Same coordination model.
+- [pdfnative-mcp](https://github.com/Nizoka/pdfnative-mcp) v1.6.0 — Model Context Protocol server exposing 28 AI tools (adds `add_ltv`, `timestamp_pdf`, `update_metadata` and `inspect_layout` on top of the v1.5.0 chart, form and encryption tools; completes the PAdES ladder B-B → B-LTA and speaks MCP 2026-07-28 with legacy fallback). Pins pdfnative `^1.7.0`. Same coordination model.
 - [pdfnative-react](https://github.com/Nizoka/pdfnative-react) v1.1.0 — React renderer: declarative JSX compiled on-device to pdfnative blocks via a custom reconciler. React 19 is a peer dependency of *that* package only — pdfnative itself stays zero-dependency. Same coordination model.
 
 Downstream-impacting changes (new public APIs, removed APIs, behaviour shifts) must be documented in the **Downstream integration notes** section of the relevant `release-notes/vX.Y.Z.md`.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e7e57b5..1dd91a8 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -54,12 +54,12 @@ Then open:
 ## Test
 
 ```bash
-npm run test           # vitest run (2665+ tests)
+npm run test           # vitest run (2686+ tests)
 npm run test:watch     # vitest (watch mode)
 npm run test:coverage  # vitest with v8 coverage (95%+ stmts measured at the v1.6.0 release; CI enforces ≥88%)
 npm run test:generate  # Generate 242 sample PDFs → test-output/
 npm run validate:pdfa  # veraPDF validation of every PDF/A-claiming sample (see below)
-npm run verify:docs    # 17 offline rules over docs/, playgrounds, README, llms files
+npm run verify:docs    # 22 offline rules over docs/, playgrounds, README, llms files
 npm run bench          # Performance benchmarks (vitest bench)
 ```
 
@@ -146,7 +146,7 @@ src/
 fonts/            # 26 pre-built font-data modules (22 scripts + Latin + math + mono and colour emoji)
 tools/            # CLI tool for converting TTF → importable data modules
 scripts/          # Modular sample PDF generation (48 generators, 242 PDFs)
-tests/            # 2665+ tests (122 files: unit + integration + fuzz + parser), mirrors src/ structure
+tests/            # 2686+ tests (123 files: unit + integration + fuzz + parser + docs), mirrors src/ structure
 bench/            # Performance benchmarks (vitest bench)
 ```
 
diff --git a/README.md b/README.md
index 4903d5b..9307dd5 100644
--- a/README.md
+++ b/README.md
@@ -24,7 +24,7 @@ pdfnative ships as four coordinated packages — pick whichever entry point fits
 |---|:---:|---|
 | [`pdfnative`](https://www.npmjs.com/package/pdfnative) | **v1.7.0** | The library itself — call from Node, browsers, Workers, Deno, Bun. |
 | [`pdfnative-cli`](https://www.npmjs.com/package/pdfnative-cli) | **v1.3.0** | Render JSON → PDF, sign (RSA + ECDSA-SHA256, native constant-time crypto by default), inspect, verify (PAdES-T + OCSP/CRL), **merge / split / extract** pages, **annotate** (markup annotations), **govern** (AI-governance / HITL gate), batch, and emit JSON Schemas from the shell. Pins pdfnative `^1.6.0` (semver-accepts 1.7.0): 22 scripts + COLRv1 emoji, `--font math`, PDF bookmarks (`--outline`), layout introspection (`--inspect-layout` / `--debug-layout`), and an agent-native `--json`/`E_*`/`--dry-run`/`--summary` contract. |
-| [`pdfnative-mcp`](https://www.npmjs.com/package/pdfnative-mcp) | **v1.5.0** | Use pdfnative from Claude Desktop, Cursor, Continue, Zed (or any stdio MCP client) — **24 production tools** including the page-tree trio `merge_pdfs`, `split_pdf`, `extract_pages`, markup `annotate_pdf`, the network-free `draft_governance_issue` (AI-governance / HITL), plus `validate_pdf`, `verify_pdf`, `add_attachment`, `extract_attachments`, and `extract_text`; watermark support, Unicode `normalize`, token-frugal read modes (`verbosity` / `fields`), `pdfA` flags, enriched authoring options (`outline`, `pageLabels`, nested lists, `viewerPreferences`, `cellBorders`, `cellVAlign`), the explicit `math` script, an MCP `prompts` capability, a constant-time `node:crypto` signing provider, DNS-rebinding-protected HTTP transport, and per-tool `_meta.apiVersion`. Pins pdfnative `^1.6.0` (semver-accepts 1.7.0). |
+| [`pdfnative-mcp`](https://www.npmjs.com/package/pdfnative-mcp) | **v1.6.0** | Use pdfnative from Claude Desktop, Cursor, Continue, Zed (or any MCP client, stdio or HTTP) — **28 production tools** spanning the engine's full document model: all 13 block kinds in `generate_basic_pdf`, layout options, build-time `encrypt` that keeps the AcroForm, image watermarks, print production (page boxes, bleed, marks, `/UserUnit`, OutputIntent), charts v2 (stacked / area / scatter, dual axis, log & time scales), the complete PAdES ladder B-B → B-LTA (`sign_pdf` with RFC 3161 timestamps, `add_ltv`, `timestamp_pdf`, `verify_pdf ltv: true`), `update_metadata`, the read-only `inspect_layout` pagination preview, honest PDF/A (`embedFonts` / `strict` / diagnostics), six MCP prompts, token-frugal read modes (`verbosity` / `fields`), the network-free `draft_governance_issue` (AI-governance / HITL), and the MCP **2026-07-28** spec with automatic legacy fallback. No outbound request by default — the only permitted egress is operator-configured TSA / OCSP / CRL. Pins pdfnative `^1.7.0`. |
 | [`pdfnative-react`](https://www.npmjs.com/package/pdfnative-react) | **v1.1.0** | Write PDFs as declarative JSX — `<Document>`, `<Page>`, `<Table>`, `<Barcode>`, `<Svg>`, `<FormField>`… compiled on-device to pdfnative blocks by a custom React 19 reconciler. Render functions (`renderToBytes` / `renderToStream` / `renderToFile`), client hooks & components (`usePdf`, `PDFViewer`, `PDFDownloadLink`), and a versioned `DocSpec` grammar (`docSpecSchema()`) for AI agents. Peer: pdfnative ^1.6.0, React ^19.0.0, Node ≥22. (A 1.5 engine would silently drop the new `<Chart>` block.) |
 
 ```bash
@@ -77,11 +77,11 @@ Detailed docs: [CLI guide](docs/guides/cli.md) · [MCP guide](docs/guides/mcp.md
 - **FlateDecode compression** — zlib stream compression (50–90% size reduction), zero-dependency, platform-native
 - **Web Worker support** — off-main-thread generation for large datasets
 - **Tree-shakeable** — ESM + CJS dual build with TypeScript declarations
-- **Heavily tested** — 2665+ tests across 122 files, fuzz suite, dual-mode visual-regression suite, performance benchmarks; 95.41% statement coverage measured at the v1.6.0 release, with CI enforcing ≥88% statements / 80% branches / 85% functions / 90% lines (vitest.config.ts)
+- **Heavily tested** — 2686+ tests across 123 files, fuzz suite, dual-mode visual-regression suite, performance benchmarks; 95.41% statement coverage measured at the v1.6.0 release, with CI enforcing ≥88% statements / 80% branches / 85% functions / 90% lines (vitest.config.ts)
 - **NPM provenance** — signed builds via GitHub Actions OIDC
 - **On-device generation** — runs in Node, browsers, Workers, Deno, Bun. No SaaS round-trip; documents never leave the calling process unless your application explicitly sends them
 - **No telemetry, no network calls** — verifiable in source. The library never opens a socket, fetches remote fonts, or phones home
-- **AI client integration** — use pdfnative from Claude Desktop, Cursor, Continue, and Zed via [`pdfnative-mcp`](https://github.com/Nizoka/pdfnative-mcp) — **24 production tools** (generate, tables, barcodes, forms, sign, verify, validate, attachments, extraction, inspect, plus page-tree `merge_pdfs` / `split_pdf` / `extract_pages`)
+- **AI client integration** — use pdfnative from Claude Desktop, Cursor, Continue, and Zed via [`pdfnative-mcp`](https://github.com/Nizoka/pdfnative-mcp) — **28 production tools** (generate, tables, barcodes, forms, sign with the full PAdES ladder, verify, validate, attachments, extraction, inspect, metadata, layout preview, plus page-tree `merge_pdfs` / `split_pdf` / `extract_pages`)
 - **Command-line interface** — render, sign, verify, inspect, and batch-render PDFs from the shell with [`pdfnative-cli`](https://github.com/Nizoka/pdfnative-cli) — zero-config, scriptable, agent-native (`--json`/`E_*`/`--dry-run`), ideal for CI/CD pipelines
 - **React renderer** — author PDFs as declarative JSX with [`pdfnative-react`](https://github.com/Nizoka/pdfnative-react): `<Document>`/`<Table>`/`<Barcode>` components, `usePdf`/`PDFViewer` client hooks, on-device rendering with no DOM or headless browser
 
@@ -102,7 +102,7 @@ npm install pdfnative
 - ❓ **FAQ:** [docs/guides/faq.md](docs/guides/faq.md) — fonts, encryption, signatures, comparisons.
 - 🤖 **Agentic workflows:** [docs/guides/agentic-workflows.md](docs/guides/agentic-workflows.md) — extend the engine at runtime (register fonts without a release) and embed agent-generated images.
 - 🛠️ **Troubleshooting:** [docs/guides/troubleshooting.md](docs/guides/troubleshooting.md) — common pitfalls.
-- 🎮 **Playgrounds:** nine interactive demos at [docs/playgrounds/](docs/playgrounds/) — [extreme-scripts](docs/playgrounds/extreme-scripts.html) (live BiDi/Indic stress tests), [all-scripts](docs/playgrounds/all-scripts.html) (every Unicode script), [scale](docs/playgrounds/scale.html) (1k-100k pages, Web Worker + true streaming), [authoring-plus](docs/playgrounds/authoring-plus.html) (SVG text, layout overlay, annotations), [toolkit](docs/playgrounds/toolkit.html) (bookmarks, page labels, viewer prefs, merge/split/extract, and v1.6.0 form fill/flatten), [charts](docs/playgrounds/charts.html) (native vector charts — all 9 v1.7.0 types), plus [cli](docs/playgrounds/cli.html), [mcp](docs/playgrounds/mcp.html) and [react](docs/playgrounds/react.html) ecosystem explorers.
+- 🎮 **Playgrounds:** ten interactive demos at [docs/playgrounds/](docs/playgrounds/) — [extreme-scripts](docs/playgrounds/extreme-scripts.html) (live BiDi/Indic stress tests), [all-scripts](docs/playgrounds/all-scripts.html) (every Unicode script), [scale](docs/playgrounds/scale.html) (1k-100k pages, Web Worker + true streaming), [authoring-plus](docs/playgrounds/authoring-plus.html) (SVG text, layout overlay, annotations), [toolkit](docs/playgrounds/toolkit.html) (bookmarks, page labels, viewer prefs, merge/split/extract, and v1.6.0 form fill/flatten), [charts](docs/playgrounds/charts.html) (native vector charts — all 9 v1.7.0 types), [inspect](docs/playgrounds/inspect.html) (drop any PDF and read a full report, entirely client-side), plus [cli](docs/playgrounds/cli.html), [mcp](docs/playgrounds/mcp.html) and [react](docs/playgrounds/react.html) ecosystem explorers.
 - 🧪 **Sample PDFs:** [scripts/generators/](scripts/generators/) — 242 sample PDFs across 37 categories (48 generators) (see [Sample PDFs](#sample-pdfs) below).
 - 🎓 **Learn:** [docs/learn/](docs/learn/) — an eight-step guided path from installing the package to generating 100,000 pages, live at [pdfnative.dev/learn/](https://pdfnative.dev/learn/).
 - 🤖 **Machine-readable:** [llms.txt](llms.txt) (doc index for LLMs), [AGENTS.md](AGENTS.md) (agent guidance), and [docs/assets/ecosystem.json](docs/assets/ecosystem.json) — the canonical manifest of ecosystem versions and counts, enforced by `npm run verify:docs`.
@@ -1026,7 +1026,7 @@ pdfnative ships as a library, but three official companion packages cover the mo
 <!-- verify-docs:allow version-token (historical: CLI v1.2.0 shipped on the pdfnative 1.5.0 engine) -->
 **New in v1.2.0:** five new commands — **`merge`**, **`split`**, **`extract`** (page-tree manipulation via pdfnative 1.5.0), **`annotate`** (markup annotations via incremental save, so existing signatures stay intact), and **`govern`** (the AI-governance / Human-in-the-Loop contract: `govern rules` / `govern policy` / `govern verify-issue`, with a stable `E_POLICY` error code). Plus PDF bookmarks (`--outline auto` or an explicit tree), the bundled math font (`--font math`), layout introspection (`--inspect-layout` / `--debug-layout`), and native constant-time crypto by default in `sign` (opt out with `--pure-crypto`).
 
-**New in v1.3.0:** five more commands on the pdfnative 1.7.0 engine — **`fill`** (fill, flatten, and export existing AcroForms via incremental save, encrypted PDFs included), **`encrypt`** / **`decrypt`** (AES-128/256 re-securing and password removal; RC4 never emitted), **`extract-text`** (reading-order Unicode text as text/JSON/NDJSON, `--runs`, `--password`), and **`doctor`** (offline environment preflight). Also native vector charts in `render`, `--password` + `--encrypt` re-encryption on merge/split/extract, an agent capability manifest (`schema manifest` + `llms.txt`), and PowerShell completion.
+**New in v1.3.0:** five more commands on the pdfnative 1.6 engine — **`fill`** (fill, flatten, and export existing AcroForms via incremental save, encrypted PDFs included), **`encrypt`** / **`decrypt`** (AES-128/256 re-securing and password removal; RC4 never emitted), **`extract-text`** (reading-order Unicode text as text/JSON/NDJSON, `--runs`, `--password`), and **`doctor`** (offline environment preflight). Also native vector charts in `render`, `--password` + `--encrypt` re-encryption on merge/split/extract, an agent capability manifest (`schema manifest` + `llms.txt`), and PowerShell completion.
 
 ```bash
 # render with full layout coverage (encryption + watermark + PDF/A-2b)
@@ -1053,7 +1053,7 @@ See the [CLI Guide](https://pdfnative.dev/guides/cli.html) for the full v1.3.0 r
 
 ### pdfnative-mcp — Model Context Protocol server
 
-[`pdfnative-mcp`](https://github.com/Nizoka/pdfnative-mcp) v1.5.0 is a **Model Context Protocol server** that bridges pdfnative to any MCP-compatible AI client. Once configured, your AI assistant can generate PDFs and native vector charts, embed barcodes, create, read, fill and flatten forms, sign and verify documents, encrypt and decrypt PDFs, validate PDF/UA structure, embed and extract attachments, extract Unicode text, render international text, merge, split and extract pages, annotate existing PDFs, draft governance-compliant GitHub issues (human-in-the-loop), and inspect existing PDFs — all without writing code.
+[`pdfnative-mcp`](https://github.com/Nizoka/pdfnative-mcp) v1.6.0 is a **Model Context Protocol server** that bridges pdfnative to any MCP-compatible AI client. Once configured, your AI assistant can generate PDFs and native vector charts, embed barcodes, create, read, fill and flatten forms, sign documents through the complete PAdES ladder (B-B → B-LTA with RFC 3161 timestamps and embedded revocation material), verify signatures and document timestamps, encrypt and decrypt PDFs, validate PDF/UA structure, embed and extract attachments, extract Unicode text, render international text, merge, split and extract pages, annotate existing PDFs, rewrite document metadata, preview pagination without producing a PDF, draft governance-compliant GitHub issues (human-in-the-loop), and inspect existing PDFs — all without writing code.
 
 <!-- verify-docs:allow stale-token (historical: MCP v1.0.0 shipped 12 tools) -->
 **v1.0.0:** first stable MCP release with 12 tools, `verify_pdf`, `add_attachment` (Factur-X / ZUGFeRD PDF/A-3), `extract_text`, smart-table options, auto-placeholder signing, and `_meta.apiVersion`.
@@ -1066,7 +1066,9 @@ See the [CLI Guide](https://pdfnative.dev/guides/cli.html) for the full v1.3.0 r
 
 **v1.4.0:** adds `annotate_pdf` (markup via incremental update) and the network-free `draft_governance_issue` (**19 tools**)<!-- verify-docs:allow stale-token (historical: MCP v1.4.0 total, on the pdfnative 1.5.0 engine) -->, the MCP `prompts` capability (`governance_contract`, `draft_issue_workflow`), `pageLabels[]` in `inspect_pdf`, and the explicit `math` script — via the pdfnative 1.5.0 engine.
 
-**v1.5.0:** adds `add_chart`, `read_form_fields`, `fill_form`, `encrypt_pdf`, `decrypt_pdf` (**24 tools**), `password` support on the read-only and page-tree tools, MCP resources (`pdfnative://output/…`), and tool annotations — via the pdfnative 1.7.0 engine.
+**v1.5.0:** adds `add_chart`, `read_form_fields`, `fill_form`, `encrypt_pdf`, `decrypt_pdf` (**24 tools**)<!-- verify-docs:allow stale-token (historical: MCP v1.5.0 total) -->, `password` support on the read-only and page-tree tools, MCP resources (`pdfnative://output/…`), and tool annotations — via the pdfnative 1.6.0 engine.
+
+**v1.6.0:** adds `add_ltv`, `timestamp_pdf`, `update_metadata`, `inspect_layout` (**28 tools**), all 13 block kinds in `generate_basic_pdf`, layout options and build-time `encrypt` on the document tools, image watermarks, print production, charts v2, honest PDF/A (`embedFonts` / `strict` / diagnostics), PAdES timestamps on `sign_pdf`, four new recipe prompts, and the MCP 2026-07-28 spec — via the pdfnative 1.7.0 engine.
 
 ```bash
 npx -y pdfnative-mcp
@@ -1076,16 +1078,18 @@ npx -y pdfnative-mcp
 
 | Tool | Purpose |
 |------|---------|
-| `generate_basic_pdf` | Multi-page documents from structured blocks (headings, paragraphs, lists, spacers, charts); optional `outline`, `pageLabels`, `pdfA` |
+| `generate_basic_pdf` | Multi-page documents from structured blocks — all 13 block kinds since v1.6.0 (incl. tables, images, links, TOC, barcodes, SVG, form fields); optional `outline`, `pageLabels`, `pdfA`, layout options, build-time `encrypt`, print production |
 | `add_table` | Smart tables (`wrap`, `repeatHeader`, `zebra`, `caption`, `minRowHeight`, `cellPadding`, `cellBorders`, `cellVAlign`) |
 | `add_barcode` | QR Code, Code 128, EAN-13, Data Matrix, PDF417 |
-| `add_international_text` | 24 script/font codes (22 Unicode scripts + `latin` + `emoji`, plus explicit `math`) with BiDi and OpenType shaping |
-| `add_form` | Interactive AcroForm PDFs (`text`, `textarea`, `checkbox`, `radio`, `dropdown`) |
-| `embed_image` | Embed a JPEG or PNG image (base64) |
-| `prepare_signature_placeholder` | PDF with a `/Sig` field ready to be signed (optional — `sign_pdf` auto-injects one) |
-| `sign_pdf` | PAdES CMS signatures (RSA-SHA256 / ECDSA-SHA256 P-256) |
+| `add_international_text` | 25 `lang` font codes (22 Unicode scripts + `latin` + `emoji` + explicit `math`) with BiDi and OpenType shaping |
+| `add_form` | Interactive AcroForm PDFs (`text`, `textarea`, `checkbox`, `radio`, `dropdown`, `listbox` since v1.6.0) |
+| `embed_image` | Embed a JPEG or PNG image (base64), with `align` / `alt` since v1.6.0 |
+| `prepare_signature_placeholder` | PDF with a `/Sig` field ready to be signed (optional — `sign_pdf` auto-injects one); `subFilter` / `reserveTimestamp` since v1.6.0 |
+| `sign_pdf` | PAdES CMS signatures (RSA-SHA256/384/512 / ECDSA-SHA256 P-256); `profile: 'pades'`, RFC 3161 `timestamp`, cert chains, multiple signatures since v1.6.0 |
+| `add_ltv` | Embed `/DSS` + `/VRI` long-term-validation material — PAdES B-LT (v1.6.0) |
+| `timestamp_pdf` | Append a `/DocTimeStamp` through the operator TSA — PAdES B-LTA (v1.6.0) |
 | `validate_pdf` | Read-only PDF/UA structural validation |
-| `verify_pdf` | Verify every PAdES signature (integrity + value + optional chain trust) |
+| `verify_pdf` | Verify every PAdES signature and `/DocTimeStamp` (integrity + value + optional chain trust; `ltv: true` reports the achieved PAdES level since v1.6.0) |
 | `add_attachment` | PDF/A-3 with embedded files (Factur-X / ZUGFeRD) |
 | `extract_attachments` | Extract embedded files (optionally metadata-only) |
 | `extract_text` | Unicode text extraction (positioned runs; `password` since v1.5.0) |
@@ -1094,12 +1098,14 @@ npx -y pdfnative-mcp
 | `extract_pages` | Pull an arbitrary, order-preserving page subset into a new PDF |
 | `annotate_pdf` | Overlay markup annotations (9 types) via incremental update; not a redaction |
 | `draft_governance_issue` | Governance-compliant GitHub-issue draft, network-free, never submits (HITL) |
-| `add_chart` | Native vector `bar` / `barH` / `line` / `pie` / `donut` charts, zero rasterisation |
+| `add_chart` | Native vector charts, zero rasterisation — nine types since v1.6.0 (bar, horizontal bar, stacked bar, stacked horizontal bar, line, area, scatter, pie, donut), dual axis, log & time scales |
 | `read_form_fields` | List an existing AcroForm's fields (types, values, options) |
 | `fill_form` | Fill and optionally flatten an existing AcroForm (encrypted PDFs supported) |
 | `encrypt_pdf` | Re-secure with AES-128/AES-256, owner/user passwords + permissions |
 | `decrypt_pdf` | Remove encryption in-server (RC4 / AES-128 / AES-256 sources) |
-| `inspect_pdf` | Structured report (metadata, pages, signatures, PDF/A, attachments, `encryptionInfo`, `pageLabels`) |
+| `update_metadata` | Rewrite `/Info` (+ XMP) of an existing PDF via incremental update (v1.6.0) |
+| `inspect_pdf` | Structured report (metadata, pages, signatures, PDF/A, attachments, `encryptionInfo`, `pageLabels`; annotation and signature inventories, `dss`, page boxes since v1.6.0) |
+| `inspect_layout` | Read-only pagination dry run — page count and block geometry, no PDF produced (v1.6.0) |
 
 ### Claude Desktop configuration
 
@@ -1206,7 +1212,7 @@ src/
 fonts/                    # Pre-built font data modules (22 scripts)
 tools/                    # CLI: build-font-data.cjs (TTF → JS module)
 scripts/                  # Modular sample PDF generation (48 generators, 242 PDFs)
-tests/                    # 2665+ tests (122 files: unit + integration + fuzz + parser)
+tests/                    # 2686+ tests (123 files: unit + integration + fuzz + parser + docs)
 bench/                    # Performance benchmarks (vitest bench)
 ```
 
@@ -1218,7 +1224,7 @@ cd pdfnative
 npm install
 
 npm run build            # tsup → dist/ (ESM + CJS + .d.ts)
-npm run test             # vitest run (2665+ tests)
+npm run test             # vitest run (2686+ tests)
 npm run test:coverage    # vitest with v8 coverage (95.41% statements at the v1.6.0 release; CI gates: 88/80/85/90)
 npm run test:generate       # Generate 242 sample PDFs → test-output/
 npm run lint                # ESLint 9 + typescript-eslint strict
@@ -1233,7 +1239,7 @@ npm run bench               # Performance benchmarks (vitest bench)
 
 | Metric | Value |
 |--------|-------|
-| Tests | 2665+ (122 files) |
+| Tests | 2686+ (123 files) |
 | Statement coverage | 95.41% (measured at the v1.6.0 release; CI enforces ≥88%, vitest.config.ts) |
 | Branch coverage | 87.79% (measured at the v1.6.0 release; CI enforces ≥80%) |
 | Function coverage | 98.5% (measured at the v1.6.0 release; CI enforces ≥85%; lines gate: ≥90%) |
diff --git a/ROADMAP.md b/ROADMAP.md
index 74aae2b..cdd2826 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -33,11 +33,11 @@ This document outlines the planned development direction for pdfnative. Prioriti
 - [x] **Barcode & QR code generation** — Code 128 (ISO 15417), EAN-13 (ISO 15420), QR Code (ISO 18004), Data Matrix ECC 200 (ISO 16022), PDF417 (ISO 15438) — pure PDF path operators (no image dependency)
 - [x] **SVG path rendering** — 7 SVG element types (path, rect, circle, ellipse, line, polyline, polygon) rendered as native PDF path operators
 - [x] **Form fields** — AcroForm interactive fields (ISO 32000-1 §12.7): text, multiline, checkbox, radio, dropdown, listbox with appearance streams
-- [x] **Digital signatures** — CMS/PKCS#7 detached signatures (ISO 32000-1 §12.8): RSA PKCS#1 v1.5 + ECDSA P-256 (`rsa-sha256` / `ecdsa-sha256`, the two selectable signature algorithms; SHA-384/512 are standalone hash exports), X.509 certificate parsing, zero-dependency crypto
+- [x] **Digital signatures** — CMS/PKCS#7 detached signatures (ISO 32000-1 §12.8): RSA PKCS#1 v1.5 + ECDSA P-256 (`rsa-sha256` / `rsa-sha384` / `rsa-sha512` / `ecdsa-sha256`, the four selectable signature algorithms since v1.7.0), X.509 certificate parsing, zero-dependency crypto
 - [x] **Streaming output** — AsyncGenerator-based progressive PDF emission with configurable chunk size (64 KB default), validation for TOC/template incompatibility, concatChunks utility
 - [x] **PDF parser & modifier** — full PDF reader (tokenizer, object parser, xref table/stream, page tree, FlateDecode inflate) + incremental modification (non-destructive save with /Prev chain)
 - [x] **npm metadata enrichment** — description enumerates 16 scripts<!-- verify-docs:allow stale-token (historical: v1.0.2 metadata) --> + headline features (BiDi, PDF/A, encryption, signatures, AcroForm, barcodes, SVG); keywords expanded to 27 entries for npm search discoverability (v1.0.2)
-- [x] **pdfnative-mcp** — Model Context Protocol server bridging pdfnative to AI clients (Claude Desktop, Cursor, Continue, Zed, ChatGPT): **24 production tools** (`generate_basic_pdf`, `add_table`, `add_barcode`, `add_international_text`, `add_form`, `embed_image`, `prepare_signature_placeholder`, `sign_pdf`, `inspect_pdf`, `verify_pdf`, `add_attachment`, `extract_text`, `validate_pdf`, `extract_attachments`, `merge_pdfs`, `split_pdf`, `extract_pages`, `annotate_pdf`, `draft_governance_issue`, `add_chart`, `read_form_fields`, `fill_form`, `encrypt_pdf`, `decrypt_pdf`), stdio/HTTP transport (with DNS-rebinding protection), sandboxed file output, token-frugal read modes (`verbosity`/`fields`), watermark + Unicode normalization options, enriched authoring (`outline`, `pageLabels`, nested lists, `viewerPreferences`, `cellBorders`, `cellVAlign`), an MCP `prompts` capability, and a constant-time `node:crypto` signing provider. Built on pdfnative 1.6.0 as of v1.5.0. See [pdfnative-mcp on GitHub](https://github.com/Nizoka/pdfnative-mcp)
+- [x] **pdfnative-mcp** — Model Context Protocol server bridging pdfnative to AI clients (Claude Desktop, Cursor, Continue, Zed, ChatGPT): **28 production tools** (`generate_basic_pdf`, `add_table`, `add_barcode`, `add_international_text`, `add_form`, `embed_image`, `prepare_signature_placeholder`, `sign_pdf`, `add_ltv`, `timestamp_pdf`, `inspect_pdf`, `inspect_layout`, `verify_pdf`, `add_attachment`, `extract_text`, `validate_pdf`, `extract_attachments`, `merge_pdfs`, `split_pdf`, `extract_pages`, `annotate_pdf`, `update_metadata`, `draft_governance_issue`, `add_chart`, `read_form_fields`, `fill_form`, `encrypt_pdf`, `decrypt_pdf`), the complete PAdES ladder B-B → B-LTA, print production, charts v2, all 13 block kinds, stdio/HTTP transport (with DNS-rebinding protection and an opt-in bearer token), sandboxed file output, token-frugal read modes (`verbosity`/`fields`), watermark + Unicode normalization options, enriched authoring (`outline`, `pageLabels`, nested lists, `viewerPreferences`, `cellBorders`, `cellVAlign`), six MCP prompts, a constant-time `node:crypto` signing provider, and the MCP 2026-07-28 spec with legacy fallback. Built on pdfnative 1.7.0 as of v1.6.0. See [pdfnative-mcp on GitHub](https://github.com/Nizoka/pdfnative-mcp)
 - [x] **Watermark auto-fit** (v1.1.0) — text watermarks with aggressive `fontSize` + `angle` combinations are now scaled down so the rotated bounding box fits within the page. Default `autoFit: true`; opt-out via `autoFit: false` for byte-stable v1.0.x output. ([src/core/pdf-watermark.ts](src/core/pdf-watermark.ts))
 - [x] **Unicode ellipsis** (v1.1.0) — `truncate()` and TOC truncation use `…` (U+2026) instead of `..` / `...` for professional typographic output (single grapheme cluster, ~50% narrower in Latin mode, identical glyph in CIDFont mode).
 - [x] **Pixel-based truncation API** (v1.1.0) — new `truncateToWidth(str, maxWidthPt, sz, enc)` exported from the root for measurement-based string shortening that respects proportional font widths.
diff --git a/SECURITY.md b/SECURITY.md
index 66fd1d8..8b1a901 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -14,9 +14,9 @@ We will acknowledge receipt within 48 hours and target a fix within 7 days for C
 
 | Version | Supported |
 |---------|-----------|
-| 1.6.x   | ✅        |
-| 1.5.x   | ✅ (security fixes) |
-| < 1.5   | ❌        |
+| 1.7.x   | ✅        |
+| 1.6.x   | ✅ (security fixes) |
+| < 1.6   | ❌        |
 
 ## Security Model
 
@@ -40,7 +40,7 @@ pdfnative is a pure TypeScript library with **zero runtime dependencies**. This
 ### Digital Signatures
 
 - CMS/PKCS#7 detached signatures (ISO 32000-1 §12.8)
-- RSA PKCS#1 v1.5 (SHA-256) and ECDSA P-256 — pure TypeScript, zero external dependencies
+- RSA PKCS#1 v1.5 (SHA-256, and SHA-384/512 since v1.7.0) and ECDSA P-256 (SHA-256) — pure TypeScript, zero external dependencies
 - X.509 DER certificate parsing for certificate chain embedding
 - `/ByteRange` ensures only the signature `/Contents` is excluded from the signed digest
 
diff --git a/docs/agent-brief.md b/docs/agent-brief.md
new file mode 100644
index 0000000..2908cdf
--- /dev/null
+++ b/docs/agent-brief.md
@@ -0,0 +1,125 @@
+# pdfnative — agent brief
+
+> A compact, paste-into-your-context briefing for AI agents writing code with
+> [pdfnative](https://pdfnative.dev). Everything here is declarative and
+> verified against the source tree by the repository's documentation CI.
+> Longer forms: [llms.txt](https://pdfnative.dev/llms.txt) (index),
+> [llms-full.txt](https://pdfnative.dev/llms-full.txt) (full corpus),
+> [llms-index.json](https://pdfnative.dev/llms-index.json) (per-page sizes and anchors).
+
+## What it is
+
+pdfnative is a zero-runtime-dependency TypeScript library that generates and
+parses ISO 32000-1 (PDF 1.7) and ISO 19005 (PDF/A) conformant PDFs on-device —
+Node ≥ 22, browsers, Deno, Bun, Web Workers. No SaaS round-trip, no telemetry,
+no sockets. Current version: 1.7.0. It writes (documents, tables, charts,
+barcodes, SVG, forms, watermarks, signatures with long-term validation, print
+production) and reads (parse, decrypt, extract text, read/fill/flatten forms,
+merge/split/extract pages, verify structure) — 22 Unicode scripts, with
+OpenType GSUB/GPOS shaping for the complex ones (Thai, Arabic, Devanagari,
+Bengali, Tamil, Telugu, Sinhala, Tibetan, Khmer, Myanmar) and full UAX #9 BiDi.
+
+## Choose your surface
+
+- **Writing application code** → the library: `npm install pdfnative`, `import { … } from 'pdfnative'`.
+- **Driving a shell, CI, or Makefile** → `pdfnative-cli` (17 commands, JSON-in/JSON-out agent contract with stable `E_*` error codes).
+- **You are a conversational assistant with tool access** → `pdfnative-mcp` (28 tools, MCP 2026-07-28 spec; config: `npx -y pdfnative-mcp`).
+- **The host app is React 19** → `pdfnative-react` (declarative JSX compiled on-device to pdfnative blocks).
+
+All four produce the same PDFs from the same engine. Details: [onboarding](https://pdfnative.dev/guides/onboarding.md).
+
+## The core API (library)
+
+```ts
+import { buildDocumentPDFBytes } from 'pdfnative';
+
+// Synchronous — returns a Uint8Array, not a Promise.
+const bytes = buildDocumentPDFBytes({
+  title: 'Invoice 42',                    // top-level, not inside metadata
+  metadata: { author: 'Me' },             // author / subject / keywords / trapped (v1.7.0)
+  blocks: [
+    { type: 'heading', text: 'Invoice 42', level: 1 },
+    { type: 'paragraph', text: 'Thank you for your order.' },
+    { type: 'table', headers: ['Item', 'Price'], rows: [{ cells: ['Widget', '€10'] }] },
+  ],
+  layout: { tagged: 'pdfa2b' },           // optional PDF/A claim lives in layout
+});
+// Node:    await fs.writeFile('out.pdf', bytes);
+// Browser: new Blob([bytes], { type: 'application/pdf' });
+```
+
+Thirteen block kinds: `heading`, `paragraph`, `list`, `table`, `image`, `link`,
+`toc`, `barcode`, `svg`, `formField`, `chart`, `pageBreak`, `spacer`.
+
+Functions an agent reaches for most, all exported from `'pdfnative'`:
+
+| Export | Role |
+|---|---|
+| `buildDocumentPDFBytes(params)` | Document builder (blocks) → `Uint8Array`. Synchronous. |
+| `buildPDFBytes(params)` | Table-centric builder (headers/rows) → `Uint8Array`. |
+| `registerFont(lang, loader)` / `loadFontData(lang)` | Enable a non-Latin script; pass the result via `fontEntries`. |
+| `downloadBlob(bytes, name)` | Browser download helper. |
+| `inspectDocumentLayout(params)` | Pagination dry run — page count and block geometry, no PDF produced. |
+| `extractText(bytes, options?)` | Reading-order Unicode text (+ positioned runs) from an existing PDF. |
+| `openPdf(bytes, { password? })` | Parse (and decrypt) an existing PDF — metadata, pages, encryption info. |
+| `validatePdfUA(bytes)` | Read-only PDF/UA structural check → `{ valid, errors, warnings }`. |
+| `readFormFields` / `fillForm` / `flattenForm` | AcroForm round-trip on existing PDFs (incremental update; encrypted sources supported). |
+| `mergePdfs` / `splitPdf` / `extractPages` | Page-tree manipulation (with streaming variants). |
+| `signPdfBytes(bytes, options)` | PAdES CMS signature (RSA-SHA256/384/512, ECDSA P-256); `addSignaturePlaceholder` prepares the `/Sig` field. |
+| `listSignatures(bytes)` | Inventory of signatures and document timestamps. |
+| `buildDocumentPDFStreamTrue(params)` | Constant-memory streaming for very large documents. |
+
+## What agents get wrong (verified pitfalls)
+
+1. **`buildDocumentPDFBytes` is synchronous.** It returns a `Uint8Array`, not a
+   Promise — do not `await` it (harmless) and do not `.then()` it (breaks).
+2. **`title` is top-level**, not inside `metadata` (`metadata` takes
+   `author` / `subject` / `keywords`, plus `trapped` since v1.7.0).
+3. **`registerFont` alone is a no-op.** You must also `await loadFontData(lang)`
+   and pass the result in `fontEntries: [{ fontData, fontRef, lang }]`.
+4. **`/F1` and `/F2` are reserved font refs** — start custom `fontRef` at `/F3`.
+5. **The PDF/A claim lives in `layout`** (`layout: { tagged: 'pdfa2b' }`), not at
+   the top level; it is mutually exclusive with encryption. A claim on base-14
+   text needs embedded fonts to pass veraPDF (see the
+   [PDF/A guide](https://pdfnative.dev/guides/pdfa.md)).
+6. **This is not pdfkit / jsPDF / pdf-lib.** There is no `new PDFDocument()`,
+   no `doc.text(…)`, no `pdf.save()`, no `doc.pipe(…)` — documents are plain
+   data (`blocks` arrays) passed to pure functions.
+   <!-- verify-docs:allow api-exists (deliberately naming the ghost identifiers to warn against them) -->
+   `streamDocumentPdf`, `streamPdf` and `buildPdfStream` have never existed;
+   <!-- verify-docs:allow api-exists (same warning, continued) -->
+   the streaming exports are `buildDocumentPDFStream`, `buildPDFStream` and their `…True` variants.
+
+## Verify your own output
+
+pdfnative can read what it writes — use that to close the loop instead of
+shipping blind:
+
+```ts
+import { buildDocumentPDFBytes, inspectDocumentLayout, extractText, validatePdfUA } from 'pdfnative';
+
+const params = { title: 'Report', blocks: [/* … */] };
+
+// Before generating: how will it paginate?
+const layout = inspectDocumentLayout(params);
+if (layout.totalPages > 3) { /* tighten the layout */ }
+
+const bytes = buildDocumentPDFBytes(params);
+
+// After generating: is the content really there? Is the structure valid?
+const pages = extractText(bytes);          // → ExtractedPageText[], one per page
+if (!pages[0].text.includes('Report')) throw new Error('content missing');
+const ua = validatePdfUA(bytes);
+if (!ua.valid) console.warn(ua.errors);
+```
+
+The same loop exists on every surface: `pdfnative-cli inspect --check … --json`
+(exit 1 on failure), and the MCP tools `inspect_pdf`, `inspect_layout`,
+`validate_pdf`, `verify_pdf`.
+
+## Where to read more
+
+- [Quick start](https://pdfnative.dev/guides/quickstart.md) · [Onboarding](https://pdfnative.dev/guides/onboarding.md) — first PDF in each surface.
+- [MCP guide](https://pdfnative.dev/guides/mcp.md) — the 28 tools, schemas, error codes.
+- [CLI guide](https://pdfnative.dev/guides/cli.md) — 17 commands and the `--json` / `E_*` agent contract.
+- Every guide serves raw Markdown at the same URL with `.md`; sizes and anchors are in [llms-index.json](https://pdfnative.dev/llms-index.json).
diff --git a/docs/app.js b/docs/app.js
index f5a4b74..aade23e 100644
--- a/docs/app.js
+++ b/docs/app.js
@@ -54,11 +54,32 @@
   }
 
   // ── Copy to clipboard ─────────────────────────────────────
+  // Single helper for every copy affordance: the Clipboard API only exists
+  // in secure contexts, so guard it and fall back to execCommand on a
+  // temporary textarea instead of throwing synchronously in the handler.
+  function copyText(text) {
+    if (navigator.clipboard && window.isSecureContext) {
+      return navigator.clipboard.writeText(text);
+    }
+    return new Promise(function (res, rej) {
+      var ta = document.createElement('textarea');
+      ta.value = text;
+      ta.style.position = 'fixed';
+      ta.style.opacity = '0';
+      document.body.appendChild(ta);
+      ta.select();
+      var ok = false;
+      try { ok = document.execCommand('copy'); } catch (_) { /* fall through */ }
+      ta.remove();
+      if (ok) res(); else rej(new Error('Clipboard unavailable'));
+    });
+  }
+
   document.querySelectorAll('.copy-btn').forEach(function (btn) {
     btn.addEventListener('click', function () {
       var text = btn.getAttribute('data-copy');
       if (!text) return;
-      navigator.clipboard.writeText(text).then(function () {
+      copyText(text).then(function () {
         btn.classList.add('copied');
         var prev = btn.innerHTML;
         btn.innerHTML = '✓';
@@ -66,12 +87,78 @@
           btn.innerHTML = prev;
           btn.classList.remove('copied');
         }, 1500);
+      }, function () {
+        btn.classList.add('copied');
+        var prev = btn.innerHTML;
+        btn.innerHTML = '✗';
+        setTimeout(function () {
+          btn.innerHTML = prev;
+          btn.classList.remove('copied');
+        }, 1500);
       });
     });
   });
 
+  // ── Copy-a-URL's-content buttons (e.g. the agent brief) ───
+  document.querySelectorAll('[data-copy-url]').forEach(function (btn) {
+    btn.addEventListener('click', function () {
+      var url = btn.getAttribute('data-copy-url');
+      fetch(url, { cache: 'no-cache' })
+        .then(function (r) { if (!r.ok) throw new Error('HTTP ' + r.status); return r.text(); })
+        .then(function (text) { return copyText(text); })
+        .then(function () {
+          var prev = btn.textContent;
+          btn.textContent = '✓ Copied';
+          setTimeout(function () { btn.textContent = prev; }, 1500);
+        })
+        .catch(function () { btn.textContent = 'Copy failed'; });
+    });
+  });
+
+  // ── Comparison quiz — verdicts derived from the table itself ──
+  var quiz = document.getElementById('cmp-quiz');
+  if (quiz) {
+    var quizBoxes = quiz.querySelectorAll('input[data-quiz-cap]');
+    var verdictEl = document.getElementById('cmp-quiz-verdict');
+    var updateQuiz = function () {
+      var caps = [];
+      quizBoxes.forEach(function (b) {
+        if (b.checked) b.getAttribute('data-quiz-cap').split(',').forEach(function (c) { caps.push(c); });
+      });
+      document.querySelectorAll('.cmp-table tr[data-cap]').forEach(function (tr) {
+        tr.classList.toggle('cmp-hot', caps.indexOf(tr.getAttribute('data-cap')) !== -1);
+      });
+      if (!caps.length) { verdictEl.hidden = true; return; }
+      // Facts, straight from the table rows above: which needs are
+      // pdfnative-only, and which are served elsewhere too.
+      var only = [];
+      if (caps.indexOf('bidi') !== -1) only.push('BiDi shaping');
+      if (caps.indexOf('pdfa') !== -1) only.push('built-in PDF/A');
+      if (caps.indexOf('sign') !== -1) only.push('digital signatures');
+      var msg;
+      if (only.length) {
+        msg = 'Of the libraries in this table, only pdfnative offers ' + only.join(', ') +
+          ' built in (highlighted rows). The others can sometimes get there with extra work — a different claim.';
+      } else if (caps.indexOf('parse') !== -1 && caps.length === 1) {
+        msg = 'Both pdf-lib and pdfnative read and modify existing PDFs. If that is your whole need, pdf-lib is a solid, widely used choice; pdfnative adds the generation, extraction and verification stack around it.';
+      } else if (caps.indexOf('encrypt') !== -1 && caps.length === 1) {
+        msg = 'pdfkit, jsPDF and pdfmake also offer AES encryption (pdf-lib does not). pdfnative adds AES-256 write plus RC4/AES read-and-decrypt if you also work with existing files.';
+      } else if (caps.indexOf('barcodes') !== -1 && caps.length === 1) {
+        msg = 'pdfmake offers QR codes; the five-format barcode set (QR, Code 128, EAN-13, Data Matrix, PDF417) is pdfnative-only in this table.';
+      } else {
+        msg = 'Several libraries in the table cover parts of this combination — the highlighted rows show who covers what. pdfnative covers all of the ticked rows in one dependency-free package.';
+      }
+      verdictEl.textContent = msg;
+      verdictEl.hidden = false;
+    };
+    quizBoxes.forEach(function (b) { b.addEventListener('change', updateQuiz); });
+  }
+
   // ── Code tabs ─────────────────────────────────────────────
-  var tabBtns = document.querySelectorAll('.tab-btn');
+  // Scoped to the Examples section: other page controls (e.g. the demo's
+  // Code/JSON mode switch) must never be captured by this tablist.
+  var exampleTabBar = document.querySelector('#examples .tab-bar');
+  var tabBtns = exampleTabBar ? exampleTabBar.querySelectorAll('.tab-btn') : [];
   var tabPanels = document.querySelectorAll('.tab-panel');
 
   function activateTab(btn) {
@@ -159,6 +246,16 @@
   var demoReset = document.getElementById('demo-reset');
   var demoDescription = document.getElementById('demo-description');
   var demoSourceLink = document.getElementById('demo-source-link');
+  var demoDownload = document.getElementById('demo-download');
+  var demoShare = document.getElementById('demo-share');
+  var demoPreview = document.getElementById('demo-preview');
+  var demoPreviewNote = document.getElementById('demo-preview-note');
+  var demoJson = document.getElementById('demo-json');
+  var demoJsonNote = document.getElementById('demo-json-note');
+  var demoModeCode = document.getElementById('demo-mode-code');
+  var demoModeJson = document.getElementById('demo-mode-json');
+  var demoCopyCli = document.getElementById('demo-copy-cli');
+  var demoCopyMcp = document.getElementById('demo-copy-mcp');
   var pdfnativeModule = null;
 
   // ── Examples gallery ──────────────────────────────────────
@@ -529,6 +626,8 @@
       label: 'Extract text & re-encrypt (v1.6.0)',
       description: 'The 1.6.0 parser round trip: build a PDF, extract its text with positions (open the browser console), then merge it with an AES-256 encrypted annex and re-encrypt the result with a new password.',
       source: GENERATORS_BASE + 'text-extract-showcase.ts',
+      encryptedOutput: true,
+      previewNote: 'This example produces an AES-256 encrypted PDF (password: rotated). The inline preview is skipped — the browser viewer would ask for the password inside a cramped frame. Use Download and open the file in your PDF reader.',
       code: [
         "import { buildDocumentPDFBytes, extractText, mergePdfs, downloadBlob } from 'pdfnative';",
         '',
@@ -591,6 +690,8 @@
     // ── Populate picker and select default ──────────────────
     var DEFAULT_ID = 'quickstart';
     var currentId = null;
+    var lastPdf = null;       // { bytes, name } captured from the last run
+    var lastPreviewUrl = null;
 
     function loadExample(id) {
       var ex = EXAMPLES.find(function (e) { return e.id === id; });
@@ -610,6 +711,11 @@
         opt.textContent = ex.label;
         demoPicker.appendChild(opt);
       });
+      // `#preset=<id>` permalinks restore the selected example.
+      var presetMatch = /(?:^|[#&])preset=([\w-]+)/.exec(location.hash);
+      if (presetMatch && EXAMPLES.some(function (e) { return e.id === presetMatch[1]; })) {
+        DEFAULT_ID = presetMatch[1];
+      }
       demoPicker.value = DEFAULT_ID;
       demoPicker.addEventListener('change', function () { loadExample(demoPicker.value); });
     }
@@ -620,77 +726,404 @@
 
     loadExample(DEFAULT_ID);
 
-    demoBtn.addEventListener('click', async function () {
+    // ── Inline PDF preview ──────────────────────────────────
+    // Same Blob → object-URL pattern as the React playground. Some browsers
+    // (most mobile ones) cannot render PDFs in an iframe; when the engine
+    // says so, be honest about it instead of showing an empty frame.
+    // Explicit opt-in: on browsers that predate the API the property is
+    // undefined, and most of those cannot render a PDF in an iframe anyway —
+    // an honest note beats an empty grey frame.
+    var canPreview = navigator.pdfViewerEnabled === true;
+    if (!canPreview && demoPreview && demoPreviewNote) {
+      demoPreview.hidden = true;
+      demoPreviewNote.hidden = false;
+    }
+
+    function showPreview(bytes) {
+      if (!demoPreview || !canPreview) return;
+      var blob = new Blob([bytes], { type: 'application/pdf' });
+      if (lastPreviewUrl) URL.revokeObjectURL(lastPreviewUrl);
+      lastPreviewUrl = URL.createObjectURL(blob);
+      demoPreview.src = lastPreviewUrl;
+    }
+
+    // An encrypted PDF in the preview iframe makes the browser's viewer ask
+    // for the password inside a cramped frame. Primary signal: the example's
+    // own declaration; safety net for user-authored code: the /Encrypt token
+    // in the byte tail (trailer region).
+    function looksEncrypted(bytes) {
+      var tail = bytes.subarray(Math.max(0, bytes.length - 2048));
+      var text = '';
+      for (var i = 0; i < tail.length; i++) text += String.fromCharCode(tail[i]);
+      return text.indexOf('/Encrypt') !== -1;
+    }
+
+    // The demo module calls `downloadBlob` like real pdfnative code; the demo
+    // routes those bytes to the preview pane and only downloads on request.
+    function captureSink(bytes, name) {
+      lastPdf = { bytes: bytes, name: name || 'document.pdf' };
+      var ex = EXAMPLES.find(function (e) { return e.id === currentId; });
+      var encrypted = (demoMode === 'code' && ex && ex.encryptedOutput) || looksEncrypted(bytes);
+      if (encrypted) {
+        if (demoPreview) { demoPreview.hidden = true; demoPreview.removeAttribute('src'); }
+        if (demoPreviewNote) {
+          demoPreviewNote.textContent = (ex && ex.previewNote) ||
+            'This PDF is encrypted — the inline viewer would prompt for its password in a cramped frame. Use Download and open it in your PDF reader.';
+          demoPreviewNote.hidden = false;
+        }
+      } else {
+        if (demoPreview && canPreview) demoPreview.hidden = false;
+        if (demoPreviewNote && canPreview) demoPreviewNote.hidden = true;
+        showPreview(bytes);
+      }
+      if (demoDownload) demoDownload.disabled = false;
+    }
+
+    if (demoDownload) {
+      demoDownload.addEventListener('click', function () {
+        if (lastPdf && pdfnativeModule) pdfnativeModule.downloadBlob(lastPdf.bytes, lastPdf.name);
+      });
+    }
+
+    // ── JSON mode: the DocumentParams the whole ecosystem consumes ──
+    var demoMode = 'code';
+    var BLOCK_TYPES = ['heading', 'paragraph', 'list', 'table', 'image', 'link', 'toc', 'barcode', 'svg', 'formField', 'chart', 'pageBreak', 'spacer'];
+    var STARTER_DOC = {
+      title: 'Shared document',
+      blocks: [
+        { type: 'heading', text: 'Shared document', level: 1 },
+        { type: 'paragraph', text: 'Edit this JSON and generate — the same object drives the library, pdfnative-cli render, and the generate_basic_pdf MCP tool.' },
+        { type: 'table', headers: ['Surface', 'Entry point'], rows: [
+          { cells: ['Library', 'buildDocumentPDFBytes(params)'] },
+          { cells: ['CLI', 'pdfnative render --input doc.json'] },
+          { cells: ['MCP', 'generate_basic_pdf'] }
+        ] }
+      ]
+    };
+
+    function setMode(mode) {
+      demoMode = mode;
+      var json = mode === 'json';
+      if (demoModeCode) demoModeCode.setAttribute('aria-pressed', String(!json));
+      if (demoModeJson) demoModeJson.setAttribute('aria-pressed', String(json));
+      if (demoCode) demoCode.hidden = json;
+      if (demoJson) {
+        demoJson.hidden = !json;
+        if (json && !demoJson.value) demoJson.value = JSON.stringify(STARTER_DOC, null, 2);
+      }
+      if (demoPicker) demoPicker.disabled = json;
+      if (demoSourceLink) demoSourceLink.hidden = json;
+      if (demoJsonNote) demoJsonNote.hidden = !json;
+      if (demoCopyCli) demoCopyCli.hidden = !json;
+      if (demoCopyMcp) demoCopyMcp.hidden = !json;
+      if (demoModeCode) demoModeCode.classList.toggle('active', !json);
+      if (demoModeJson) demoModeJson.classList.toggle('active', json);
+    }
+    if (demoModeCode) demoModeCode.addEventListener('click', function () { setMode('code'); });
+    if (demoModeJson) demoModeJson.addEventListener('click', function () { setMode('json'); });
+
+    // Defensive parse: a #doc= payload is untrusted input. Data only — the
+    // hash can never carry code — with a size cap and a block-type check
+    // against the engine's 13-kind union. Anything off-shape is rejected.
+    function parseDocJson(text) {
+      if (typeof text !== 'string' || text.length > 100000) throw new Error('Document JSON too large.');
+      var doc = JSON.parse(text);
+      if (!doc || typeof doc !== 'object' || Array.isArray(doc)) throw new Error('Document must be a JSON object.');
+      if (!Array.isArray(doc.blocks)) throw new Error('Document needs a "blocks" array.');
+      for (var i = 0; i < doc.blocks.length; i++) {
+        var b = doc.blocks[i];
+        if (!b || typeof b !== 'object' || BLOCK_TYPES.indexOf(b.type) === -1) {
+          throw new Error('blocks[' + i + '].type must be one of: ' + BLOCK_TYPES.join(', '));
+        }
+        // Shared #doc= payloads are untrusted: only the schemes the engine
+        // itself allows may reach a link annotation.
+        if (b.type === 'link' && typeof b.url === 'string' && !/^(https?:|mailto:|#)/i.test(b.url)) {
+          throw new Error('blocks[' + i + '].url must use http:, https:, mailto: or a #fragment.');
+        }
+      }
+      return doc;
+    }
+
+    // #doc= payload: base64url, deflate-raw-compressed when the native
+    // CompressionStream API exists ("d." prefix), raw otherwise ("r.").
+    function toBase64Url(bytes) {
+      var bin = '';
+      for (var i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i]);
+      return btoa(bin).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+    }
+    function fromBase64Url(s) {
+      s = s.replace(/-/g, '+').replace(/_/g, '/');
+      var bin = atob(s);
+      var bytes = new Uint8Array(bin.length);
+      for (var i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
+      return bytes;
+    }
+    async function encodeDocHash(jsonText) {
+      var raw = new TextEncoder().encode(jsonText);
+      if (typeof CompressionStream === 'function') {
+        var stream = new Blob([raw]).stream().pipeThrough(new CompressionStream('deflate-raw'));
+        var packed = new Uint8Array(await new Response(stream).arrayBuffer());
+        return 'd.' + toBase64Url(packed);
+      }
+      return 'r.' + toBase64Url(raw);
+    }
+    async function decodeDocHash(payload) {
+      if (payload.length > 20000) throw new Error('Link payload too large.');
+      var kind = payload.slice(0, 2);
+      var bytes = fromBase64Url(payload.slice(2));
+      if (kind === 'd.') {
+        if (typeof DecompressionStream !== 'function') throw new Error('This browser cannot decompress the link.');
+        // Read the inflated stream chunk by chunk and abort past the JSON
+        // size cap — deflate can expand ~1000:1, so never materialise an
+        // unbounded payload before checking its size.
+        var reader = new Blob([bytes]).stream().pipeThrough(new DecompressionStream('deflate-raw')).getReader();
+        var chunks = [];
+        var total = 0;
+        for (;;) {
+          var step = await reader.read();
+          if (step.done) break;
+          total += step.value.length;
+          if (total > 150000) {
+            reader.cancel();
+            throw new Error('Link payload too large after decompression.');
+          }
+          chunks.push(step.value);
+        }
+        bytes = new Uint8Array(total);
+        var off = 0;
+        for (var ci = 0; ci < chunks.length; ci++) { bytes.set(chunks[ci], off); off += chunks[ci].length; }
+      } else if (kind !== 'r.') {
+        throw new Error('Unrecognised link format.');
+      }
+      return new TextDecoder().decode(bytes);
+    }
+
+    if (demoShare) {
+      demoShare.addEventListener('click', async function () {
+        var base = location.origin + location.pathname;
+        var url;
+        try {
+          if (demoMode === 'json') {
+            var doc = parseDocJson(demoJson.value);
+            url = base + '#doc=' + (await encodeDocHash(JSON.stringify(doc)));
+          } else {
+            url = base + '#preset=' + (currentId || DEFAULT_ID);
+          }
+          await copyText(url);
+          var prev = demoShare.textContent;
+          demoShare.textContent = '✓ Copied';
+          setTimeout(function () { demoShare.textContent = prev; }, 1500);
+        } catch (e) {
+          demoError.textContent = 'Share failed: ' + (e.message || e);
+          demoError.style.display = 'block';
+        }
+      });
+    }
+
+    function copyWithFeedback(btn, text) {
+      copyText(text).then(function () {
+        var prev = btn.textContent;
+        btn.textContent = '✓ Copied';
+        setTimeout(function () { btn.textContent = prev; }, 1500);
+      });
+    }
+    if (demoCopyCli) {
+      demoCopyCli.addEventListener('click', function () {
+        try {
+          var doc = parseDocJson(demoJson.value);
+          copyWithFeedback(demoCopyCli,
+            '# Save the JSON below as doc.json, then:\n' +
+            'npx pdfnative-cli render --input doc.json --output out.pdf\n\n' +
+            JSON.stringify(doc, null, 2) + '\n');
+        } catch (e) { demoError.textContent = e.message; demoError.style.display = 'block'; }
+      });
+    }
+    if (demoCopyMcp) {
+      demoCopyMcp.addEventListener('click', function () {
+        try {
+          var doc = parseDocJson(demoJson.value);
+          copyWithFeedback(demoCopyMcp, JSON.stringify({
+            tool: 'generate_basic_pdf',
+            input: { title: doc.title || 'Document', blocks: doc.blocks, outputMode: 'base64' }
+          }, null, 2) + '\n');
+        } catch (e) { demoError.textContent = e.message; demoError.style.display = 'block'; }
+      });
+    }
+
+    // Restore a shared document from the URL hash. `hashReady` lets the
+    // autorun observer wait for the (async) decode instead of racing it and
+    // rendering the default example over the shared one; #doc= is not an
+    // element id, so we also bring the visitor to the demo ourselves.
+    var hashReady = Promise.resolve();
+    var docMatch = /(?:^|[#&])doc=([\w.~-]+)/.exec(location.hash);
+    if (docMatch && demoJson) {
+      hashReady = decodeDocHash(docMatch[1])
+        .then(function (text) {
+          var doc = parseDocJson(text);
+          setMode('json');
+          demoJson.value = JSON.stringify(doc, null, 2);
+          var demoSection = document.getElementById('demo');
+          if (demoSection) demoSection.scrollIntoView();
+        })
+        .catch(function () { /* off-shape payloads are silently ignored */ });
+    }
+
+    // ── Execution: real ES module via a Blob URL ─────────────
+    // The example code is executed as an actual module, so its
+    // `import { … } from 'pdfnative'` lines are real, top-level `await`
+    // works natively, and errors carry genuine line numbers. The pdfnative
+    // specifier is resolved to the already-loaded module through a global
+    // (no second CDN request), with `downloadBlob` routed to the preview.
+    function rewriteImports(code) {
+      return code
+        // Named imports — single- or multi-line.
+        .replace(
+          /^(\s*)import\s*\{([\s\S]*?)\}\s*from\s*['"]pdfnative['"]\s*;?[ \t]*$/gm,
+          '$1const {$2} = globalThis.__pdfnativeDemo.mod;'
+        )
+        // Namespace imports: import * as pdf from 'pdfnative'.
+        .replace(
+          /^(\s*)import\s*\*\s*as\s+([A-Za-z_$][\w$]*)\s+from\s*['"]pdfnative['"]\s*;?[ \t]*$/gm,
+          '$1const $2 = globalThis.__pdfnativeDemo.mod;'
+        );
+    }
+
+    function lineFromStack(err) {
+      var m = /blob:[^\s)]+:(\d+):\d+/.exec(err && err.stack ? err.stack : '');
+      return m ? Number(m[1]) : null;
+    }
+
+    async function runDemo() {
       demoStatus.textContent = 'Loading pdfnative…';
       demoError.style.display = 'none';
       demoError.textContent = '';
       demoBtn.disabled = true;
 
+      var moduleUrl = null;
       try {
         // Lazy-load pdfnative from ESM CDN on first use
         if (!pdfnativeModule) {
           pdfnativeModule = await loadPdfnative();
-          demoStatus.textContent = 'Generating PDF…';
         }
+        demoStatus.textContent = 'Generating PDF…';
 
-        // Extract user code and execute
-        var code = demoCode.value;
-
-        // Strip top-level static `import {…} from 'pdfnative'` statements —
-        // we provide those bindings via the function arguments below.
-        // Keep dynamic `import('…')` calls intact for examples that need them
-        // (e.g. multi-language font modules).
-        var cleanCode = code
-          .replace(/^\s*import\s*\{[^}]+\}\s*from\s*['"]pdfnative['"]\s*;?/gm, '')
-          .trim();
-
-        // Wrap in async IIFE so user code can use top-level `await`
-        var wrapped = '"use strict"; return (async () => {\n' + cleanCode + '\n})();';
-
-        var fn = new Function(
-          'buildPDFBytes', 'buildDocumentPDFBytes', 'downloadBlob',
-          'buildPDF', 'buildDocumentPDF', 'wrapText',
-          'buildDocumentPDFStream', 'buildPDFStream', 'concatChunks',
-          'registerFonts', 'loadFontData',
-          'initNodeCompression', 'signPdfBytes',
-          'extractText', 'mergePdfs', 'splitPdf', 'extractPages',
-          'openPdf', 'readFormFields', 'fillForm', 'flattenForm',
-          wrapped
-        );
+        if (demoMode === 'json') {
+          var doc = parseDocJson(demoJson.value);
+          captureSink(pdfnativeModule.buildDocumentPDFBytes(doc), (doc.title || 'document') + '.pdf');
+        } else {
+          globalThis.__pdfnativeDemo = {
+            mod: Object.assign({}, pdfnativeModule, { downloadBlob: captureSink })
+          };
 
-        await fn(
-          pdfnativeModule.buildPDFBytes,
-          pdfnativeModule.buildDocumentPDFBytes,
-          pdfnativeModule.downloadBlob,
-          pdfnativeModule.buildPDF,
-          pdfnativeModule.buildDocumentPDF,
-          pdfnativeModule.wrapText,
-          pdfnativeModule.buildDocumentPDFStream,
-          pdfnativeModule.buildPDFStream,
-          pdfnativeModule.concatChunks,
-          pdfnativeModule.registerFonts,
-          pdfnativeModule.loadFontData,
-          pdfnativeModule.initNodeCompression,
-          pdfnativeModule.signPdfBytes,
-          pdfnativeModule.extractText,
-          pdfnativeModule.mergePdfs,
-          pdfnativeModule.splitPdf,
-          pdfnativeModule.extractPages,
-          pdfnativeModule.openPdf,
-          pdfnativeModule.readFormFields,
-          pdfnativeModule.fillForm,
-          pdfnativeModule.flattenForm
-        );
+          var source = rewriteImports(demoCode.value);
+          if (/from\s*['"]pdfnative['"]/.test(source)) {
+            throw new Error("This demo can only resolve `import { name } from 'pdfnative'` or `import * as pdf from 'pdfnative'` — rewrite the import in one of those forms.");
+          }
+          moduleUrl = URL.createObjectURL(new Blob([source], { type: 'text/javascript' }));
+          await import(moduleUrl);
+        }
 
-        demoStatus.textContent = 'PDF generated!';
+        demoStatus.textContent = lastPdf ? 'PDF generated — preview updated.' : 'Done (no PDF produced).';
         setTimeout(function () { demoStatus.textContent = ''; }, 3000);
       } catch (err) {
-        demoError.textContent = err.message || String(err);
+        var line = lineFromStack(err);
+        demoError.textContent = (line ? 'Line ' + line + ': ' : '') + (err.message || String(err));
         demoError.style.display = 'block';
         demoStatus.textContent = '';
       } finally {
+        if (moduleUrl) URL.revokeObjectURL(moduleUrl);
         demoBtn.disabled = false;
       }
-    });
+    }
+
+    demoBtn.addEventListener('click', runDemo);
+
+    // ── Live benchmark (never reuses .bench-label/.bench-value: those
+    //    classes are tied to bench/RESULTS.md by the bench-parity CI rule) ──
+    var benchBtn = document.getElementById('bench-live-run');
+    if (benchBtn) {
+      benchBtn.addEventListener('click', async function () {
+        var rowsEl = document.getElementById('bench-live-rows');
+        var noteEl = document.getElementById('bench-live-note');
+        benchBtn.disabled = true;
+        benchBtn.textContent = 'Loading pdfnative…';
+        try {
+          if (!pdfnativeModule) pdfnativeModule = await loadPdfnative();
+          benchBtn.textContent = 'Measuring…';
+          var makeParams = function (n) {
+            var rows = [];
+            for (var i = 0; i < n; i++) {
+              rows.push({ cells: ['2026-08-' + ((i % 28) + 1), 'Line item ' + i, '$' + (i * 3.5).toFixed(2)] });
+            }
+            // PdfParams requires infoItems/balanceText/countText/footerText —
+            // the engine's boundary validation does not (yet) guard them.
+            return {
+              title: 'Benchmark ' + n,
+              infoItems: [{ label: 'Rows', value: String(n) }],
+              balanceText: 'Synthetic dataset',
+              countText: n + ' rows',
+              headers: ['Date', 'Description', 'Amount'],
+              rows: rows,
+              footerText: 'pdfnative.dev live benchmark'
+            };
+          };
+          pdfnativeModule.buildPDFBytes(makeParams(50)); // warm-up
+          var sizes = [100, 500, 1000];
+          var results = [];
+          for (var s = 0; s < sizes.length; s++) {
+            var t0 = performance.now();
+            pdfnativeModule.buildPDFBytes(makeParams(sizes[s]));
+            results.push({ n: sizes[s], ms: performance.now() - t0 });
+            await new Promise(function (r) { setTimeout(r, 0); }); // keep the tab responsive
+          }
+          var max = Math.max.apply(null, results.map(function (r) { return r.ms; }));
+          rowsEl.innerHTML = results.map(function (r) {
+            var pct = Math.max(4, Math.round((r.ms / max) * 100));
+            return '<div class="bench-row">' +
+              '<span class="bench-live-label">' + r.n.toLocaleString('en-GB') + ' rows — this device</span>' +
+              '<div class="bench-bar-bg"><div class="bench-bar bench-live-bar" style="width:' + pct + '%"></div></div>' +
+              '<span class="bench-live-value">' + r.ms.toFixed(1) + ' ms</span>' +
+              '</div>';
+          }).join('');
+          rowsEl.hidden = false;
+          noteEl.hidden = false;
+        } catch (e) {
+          // Never destroy the button label with an error message.
+          noteEl.textContent = 'Benchmark failed: ' + (e.message || e);
+          noteEl.setAttribute('role', 'alert');
+          noteEl.hidden = false;
+        } finally {
+          benchBtn.textContent = '↺ Run again';
+          benchBtn.disabled = false;
+        }
+      });
+    }
+
+    // First render without a click, once the demo scrolls into view — the
+    // visitor sees a real PDF instead of an empty pane. One shot only, and
+    // desktop only: auto-loading the CDN engine on mobile data without a
+    // click would be presumptuous.
+    if ('IntersectionObserver' in window && canPreview && matchMedia('(min-width: 901px)').matches) {
+      var demoSection = document.getElementById('demo');
+      if (demoSection) {
+        var ran = false;
+        var io = new IntersectionObserver(function (entries) {
+          entries.forEach(function (entry) {
+            if (entry.isIntersecting && !ran) {
+              ran = true;
+              io.disconnect();
+              // Never auto-run an example whose output is encrypted — the
+              // visitor would face a password prompt without having clicked.
+              var ex = EXAMPLES.find(function (e) { return e.id === DEFAULT_ID; });
+              if (ex && ex.encryptedOutput) return;
+              // A shared #doc= link may still be decoding: wait for it so the
+              // first render shows the shared document, not the default.
+              hashReady.then(runDemo);
+            }
+          });
+        }, { rootMargin: '200px' });
+        io.observe(demoSection);
+      }
+    }
   }
 })();
diff --git a/docs/assets/api.json b/docs/assets/api.json
new file mode 100644
index 0000000..9a236a1
--- /dev/null
+++ b/docs/assets/api.json
@@ -0,0 +1,3123 @@
+{
+  "$comment": "Public API surface of pdfnative, derived mechanically from the export statements of src/index.ts by scripts/build-api-json.ts and policed by the api-json-sync rule of scripts/verify-docs.ts. Fields that cannot be extracted mechanically are null, never guessed. Regenerate with `npm run docs:api`.",
+  "package": "pdfnative",
+  "source": "src/index.ts",
+  "exportCount": 445,
+  "exports": [
+    {
+      "name": "AddDocumentTimestampOptions",
+      "kind": "type",
+      "module": "src/core/pdf-doc-timestamp.ts",
+      "signature": "export interface AddDocumentTimestampOptions",
+      "summary": "Options for addDocumentTimestamp."
+    },
+    {
+      "name": "AddSignaturePlaceholderOptions",
+      "kind": "type",
+      "module": "src/core/pdf-sig-placeholder.ts",
+      "signature": "export interface AddSignaturePlaceholderOptions",
+      "summary": "Options for addSignaturePlaceholder."
+    },
+    {
+      "name": "Annotation",
+      "kind": "type",
+      "module": "src/core/pdf-annot.ts",
+      "signature": "export type Annotation = LinkAnnotation | InternalLink;",
+      "summary": "Union of all annotation types."
+    },
+    {
+      "name": "AnnotationBase",
+      "kind": "type",
+      "module": "src/core/pdf-annot-markup.ts",
+      "signature": "export interface AnnotationBase",
+      "summary": "Fields shared by every markup / drawing annotation."
+    },
+    {
+      "name": "AnnotationRect",
+      "kind": "type",
+      "module": "src/core/pdf-annot-markup.ts",
+      "signature": "export type AnnotationRect = readonly [number, number, number, number];",
+      "summary": "Rectangle `[x1, y1, x2, y2]` in PDF user space (points)."
+    },
+    {
+      "name": "Asn1Node",
+      "kind": "type",
+      "module": "src/crypto/asn1.ts",
+      "signature": "export interface Asn1Node",
+      "summary": null
+    },
+    {
+      "name": "BAL_H",
+      "kind": "value",
+      "module": "src/core/pdf-layout.ts",
+      "signature": "export const BAL_H = 32;",
+      "summary": null
+    },
+    {
+      "name": "BarcodeBlock",
+      "kind": "type",
+      "module": "src/types/pdf-document-types.ts",
+      "signature": "export interface BarcodeBlock",
+      "summary": "Barcode block — renders a 1D or 2D barcode using PDF path operators."
+    },
+    {
+      "name": "BarcodeFormat",
+      "kind": "type",
+      "module": "src/core/pdf-barcode.ts",
+      "signature": "export type BarcodeFormat = 'code128' | 'ean13' | 'qr' | 'datamatrix' | 'pdf417';",
+      "summary": "Supported barcode formats."
+    },
+    {
+      "name": "BidiRun",
+      "kind": "type",
+      "module": "src/shaping/bidi.ts",
+      "signature": "export interface BidiRun",
+      "summary": "A run of text with a resolved embedding level."
+    },
+    {
+      "name": "CellBorders",
+      "kind": "type",
+      "module": "src/types/pdf-document-types.ts",
+      "signature": "export interface CellBorders",
+      "summary": "Per-cell border configuration for a TableBlock."
+    },
+    {
+      "name": "ChartBlock",
+      "kind": "type",
+      "module": "src/types/pdf-document-types.ts",
+      "signature": "export interface ChartBlock",
+      "summary": "Chart block — native vector charts rendered as pure PDF path operators (zero dependencies, no rasterisation)."
+    },
+    {
+      "name": "ChartSeries",
+      "kind": "type",
+      "module": "src/types/pdf-document-types.ts",
+      "signature": "export interface ChartSeries",
+      "summary": "A single data series in a ChartBlock."
+    },
+    {
+      "name": "ChartType",
+      "kind": "type",
+      "module": "src/types/pdf-document-types.ts",
+      "signature": "export type ChartType = 'bar' | 'barH' | 'line' | 'pie' | 'donut'",
+      "summary": "Supported chart types (v1.6.0; `stackedBar`/`stackedBarH`/`area`/`scatter` since v1.7.0)."
+    },
+    {
+      "name": "CmsDigestAlgorithm",
+      "kind": "type",
+      "module": "src/crypto/cms.ts",
+      "signature": "export type CmsDigestAlgorithm = 'sha256' | 'sha384' | 'sha512';",
+      "summary": "Message-digest algorithm used across the CMS structure (digestAlgorithms set, message-digest attribute, SignerInfo digestAlgorithm, certHash)."
+    },
+    {
+      "name": "CmsProfile",
+      "kind": "type",
+      "module": "src/crypto/cms.ts",
+      "signature": "export type CmsProfile = 'pkcs7' | 'pades';",
+      "summary": "CMS profile: - `'pkcs7'` (default) — classic adbe.pkcs7.detached signed attributes: content-type, message-digest, signing-time."
+    },
+    {
+      "name": "CmsSignOptions",
+      "kind": "type",
+      "module": "src/crypto/cms.ts",
+      "signature": "export interface CmsSignOptions",
+      "summary": null
+    },
+    {
+      "name": "CollectLtvOptions",
+      "kind": "type",
+      "module": "src/core/pdf-dss.ts",
+      "signature": "export interface CollectLtvOptions",
+      "summary": "Options for collectValidationInfo / addValidationInfo."
+    },
+    {
+      "name": "ColorGlyph",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export interface ColorGlyph",
+      "summary": "A resolved colour glyph: ordered layers painted back-to-front."
+    },
+    {
+      "name": "ColorGlyphForm",
+      "kind": "type",
+      "module": "src/core/pdf-color-glyph.ts",
+      "signature": "export interface ColorGlyphForm",
+      "summary": "A rendered colour glyph ready to be assembled into a Form XObject."
+    },
+    {
+      "name": "ColorLayer",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export interface ColorLayer",
+      "summary": "A single colour-glyph layer: a base outline filled by a paint."
+    },
+    {
+      "name": "ColorPaint",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export type ColorPaint = SolidPaint | LinearGradientPaint | RadialGradientPaint | SweepGradientPaint;",
+      "summary": "A paint used to fill a colour-glyph layer."
+    },
+    {
+      "name": "ColorStop",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export interface ColorStop",
+      "summary": "A gradient colour stop: `offset` in [0,1] with a resolved colour."
+    },
+    {
+      "name": "ColumnDef",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export interface ColumnDef",
+      "summary": "Column definition for the table layout."
+    },
+    {
+      "name": "Contour",
+      "kind": "type",
+      "module": "src/fonts/glyf-outline.ts",
+      "signature": "export type Contour = OutlinePoint[];",
+      "summary": "A closed contour: an ordered ring of on/off-curve points."
+    },
+    {
+      "name": "CpalColor",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export type CpalColor = readonly [number, number, number, number];",
+      "summary": "An sRGB colour with alpha, each channel 0–255."
+    },
+    {
+      "name": "CrlRevokedEntry",
+      "kind": "type",
+      "module": "src/crypto/crl.ts",
+      "signature": "export interface CrlRevokedEntry",
+      "summary": "One revokedCertificates entry."
+    },
+    {
+      "name": "CryptFilterMethod",
+      "kind": "type",
+      "module": "src/parser/pdf-decrypt.ts",
+      "signature": "export type CryptFilterMethod = 'V2' | 'AESV2' | 'AESV3' | 'Identity';",
+      "summary": "Crypt-filter method resolved for streams or strings."
+    },
+    {
+      "name": "CryptoProvider",
+      "kind": "type",
+      "module": "src/crypto/crypto-provider.ts",
+      "signature": "export interface CryptoProvider",
+      "summary": "A pluggable signer that replaces pdfnative's pure-JS RSA/ECDSA math with a native, constant-time implementation."
+    },
+    {
+      "name": "CustomOutputIntent",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export interface CustomOutputIntent",
+      "summary": "Caller-supplied OutputIntent for tagged/PDF-A documents (v1.7.0): replaces the built-in minimal sRGB profile with a real ICC profile (e.g."
+    },
+    {
+      "name": "DEFAULT_COLORS",
+      "kind": "value",
+      "module": "src/core/pdf-layout.ts",
+      "signature": "export const DEFAULT_COLORS: PdfColors =",
+      "summary": null
+    },
+    {
+      "name": "DEFAULT_COLUMNS",
+      "kind": "value",
+      "module": "src/core/pdf-layout.ts",
+      "signature": "export const DEFAULT_COLUMNS: ColumnDef[] = [",
+      "summary": null
+    },
+    {
+      "name": "DEFAULT_CW",
+      "kind": "value",
+      "module": "src/core/pdf-layout.ts",
+      "signature": "export const DEFAULT_CW = PG_W - DEFAULT_MARGINS.l - DEFAULT_MARGINS.r;",
+      "summary": null
+    },
+    {
+      "name": "DEFAULT_FONT_SIZES",
+      "kind": "value",
+      "module": "src/core/pdf-layout.ts",
+      "signature": "export const DEFAULT_FONT_SIZES = { title: 16, info: 9, th: 8, td: 7.5, ft: 7 };",
+      "summary": null
+    },
+    {
+      "name": "DEFAULT_MARGINS",
+      "kind": "value",
+      "module": "src/core/pdf-layout.ts",
+      "signature": "export const DEFAULT_MARGINS = { t: 45, r: 36, b: 35, l: 36 };",
+      "summary": null
+    },
+    {
+      "name": "DEFAULT_MAX_BLOCKS",
+      "kind": "value",
+      "module": "src/core/pdf-layout.ts",
+      "signature": "export const DEFAULT_MAX_BLOCKS = 100_000;",
+      "summary": "Default ceiling for `buildDocumentPDF` block count, overridable per call via `PdfLayoutOptions.maxBlocks`."
+    },
+    {
+      "name": "DEFAULT_MAX_INFLATE_OUTPUT",
+      "kind": "value",
+      "module": "src/parser/pdf-inflate.ts",
+      "signature": "export const DEFAULT_MAX_INFLATE_OUTPUT = 100 * 1024 * 1024;",
+      "summary": "Default maximum decompressed size (bytes) for inflate operations."
+    },
+    {
+      "name": "DecryptionContext",
+      "kind": "type",
+      "module": "src/parser/pdf-decrypt.ts",
+      "signature": "export interface DecryptionContext",
+      "summary": "Everything needed to decrypt the objects of one document, produced by a successful authenticate call."
+    },
+    {
+      "name": "DocumentBlock",
+      "kind": "type",
+      "module": "src/types/pdf-document-types.ts",
+      "signature": "export type DocumentBlock =",
+      "summary": "Union of all supported document blocks."
+    },
+    {
+      "name": "DocumentMetadata",
+      "kind": "type",
+      "module": "src/types/pdf-document-types.ts",
+      "signature": null,
+      "summary": null
+    },
+    {
+      "name": "DocumentParams",
+      "kind": "type",
+      "module": "src/types/pdf-document-types.ts",
+      "signature": "export interface DocumentParams",
+      "summary": "Parameters for the free-form document PDF builder."
+    },
+    {
+      "name": "EcPrivateKey",
+      "kind": "type",
+      "module": "src/crypto/ecdsa.ts",
+      "signature": "export interface EcPrivateKey",
+      "summary": "ECDSA P-256 private key."
+    },
+    {
+      "name": "EcPublicKey",
+      "kind": "type",
+      "module": "src/crypto/ecdsa.ts",
+      "signature": "export interface EcPublicKey",
+      "summary": "ECDSA P-256 public key."
+    },
+    {
+      "name": "EmbeddedFilesResult",
+      "kind": "type",
+      "module": "src/core/pdf-tags.ts",
+      "signature": "export interface EmbeddedFilesResult",
+      "summary": "Result of building embedded file objects for PDF/A-3."
+    },
+    {
+      "name": "EncodingContext",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export interface EncodingContext",
+      "summary": "Encoding context encapsulating text encoding and font reference logic."
+    },
+    {
+      "name": "EncryptionOptions",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export interface EncryptionOptions",
+      "summary": "Options for PDF encryption (password protection)."
+    },
+    {
+      "name": "ExtractTextOptions",
+      "kind": "type",
+      "module": "src/parser/pdf-text-extract.ts",
+      "signature": "export interface ExtractTextOptions",
+      "summary": null
+    },
+    {
+      "name": "ExtractedPageText",
+      "kind": "type",
+      "module": "src/parser/pdf-text-extract.ts",
+      "signature": "export interface ExtractedPageText",
+      "summary": null
+    },
+    {
+      "name": "ExtractedTextRun",
+      "kind": "type",
+      "module": "src/parser/pdf-text-extract.ts",
+      "signature": "export interface ExtractedTextRun",
+      "summary": "One text-showing operation (`Tj`, one `TJ` string, `'` or `\"`)."
+    },
+    {
+      "name": "FT_H",
+      "kind": "value",
+      "module": "src/core/pdf-layout.ts",
+      "signature": "export const FT_H = 15;",
+      "summary": null
+    },
+    {
+      "name": "FillFormOptions",
+      "kind": "type",
+      "module": "src/core/pdf-form-fill.ts",
+      "signature": "export interface FillFormOptions",
+      "summary": "Options for fillForm."
+    },
+    {
+      "name": "FlattenFormOptions",
+      "kind": "type",
+      "module": "src/core/pdf-form-fill.ts",
+      "signature": "export interface FlattenFormOptions",
+      "summary": "Options for flattenForm."
+    },
+    {
+      "name": "FontData",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export interface FontData",
+      "summary": "Pre-built font data loaded from font data modules."
+    },
+    {
+      "name": "FontEntry",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export interface FontEntry",
+      "summary": "A font entry binding FontData to a PDF font reference."
+    },
+    {
+      "name": "FontLoader",
+      "kind": "type",
+      "module": "src/fonts/font-loader.ts",
+      "signature": "export type FontLoader = () => Promise<FontData | { default: FontData }>;",
+      "summary": "Font loader function type — returns a FontData or module with default export"
+    },
+    {
+      "name": "FontMetrics",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export interface FontMetrics",
+      "summary": "Font metrics embedded in font data modules."
+    },
+    {
+      "name": "FontRun",
+      "kind": "type",
+      "module": "src/shaping/multi-font.ts",
+      "signature": "export interface FontRun",
+      "summary": "A text run with its assigned font entry"
+    },
+    {
+      "name": "FontValidationResult",
+      "kind": "type",
+      "module": "src/fonts/font-validator.ts",
+      "signature": "export interface FontValidationResult",
+      "summary": "Result of validateFontData."
+    },
+    {
+      "name": "FormField",
+      "kind": "type",
+      "module": "src/core/pdf-form.ts",
+      "signature": "export interface FormField",
+      "summary": "Resolved form field descriptor ready for PDF object emission."
+    },
+    {
+      "name": "FormFieldBlock",
+      "kind": "type",
+      "module": "src/types/pdf-document-types.ts",
+      "signature": "export interface FormFieldBlock",
+      "summary": "Form field block — interactive AcroForm widget (ISO 32000-1 §12.7)."
+    },
+    {
+      "name": "FormFieldNotFoundError",
+      "kind": "value",
+      "module": "src/core/pdf-form-fill.ts",
+      "signature": "export class FormFieldNotFoundError extends Error",
+      "summary": "A named field was not found in the document."
+    },
+    {
+      "name": "FormFieldType",
+      "kind": "type",
+      "module": "src/core/pdf-form.ts",
+      "signature": "export type FormFieldType =",
+      "summary": "Supported AcroForm field types (ISO 32000-1 §12.7.3–12.7.4)."
+    },
+    {
+      "name": "FormFillValue",
+      "kind": "type",
+      "module": "src/core/pdf-form-fill.ts",
+      "signature": "export type FormFillValue = string | boolean | readonly string[];",
+      "summary": null
+    },
+    {
+      "name": "FormUnsupportedError",
+      "kind": "value",
+      "module": "src/core/pdf-form-fill.ts",
+      "signature": "export class FormUnsupportedError extends Error",
+      "summary": "The field or document uses a feature fill/flatten does not support."
+    },
+    {
+      "name": "FormValueTypeError",
+      "kind": "value",
+      "module": "src/core/pdf-form-fill.ts",
+      "signature": "export class FormValueTypeError extends Error",
+      "summary": "A supplied value has the wrong type for its field, or is not a valid option."
+    },
+    {
+      "name": "FormWidgetResult",
+      "kind": "type",
+      "module": "src/core/pdf-form.ts",
+      "signature": "export interface FormWidgetResult",
+      "summary": "Result of building a form field: widget annotation dict + appearance stream(s)."
+    },
+    {
+      "name": "FreeTextAnnotation",
+      "kind": "type",
+      "module": "src/core/pdf-annot-markup.ts",
+      "signature": "export interface FreeTextAnnotation extends AnnotationBase",
+      "summary": "Free-text (typewriter) annotation (`/Subtype /FreeText`)."
+    },
+    {
+      "name": "GlyfFont",
+      "kind": "type",
+      "module": "src/fonts/glyf-outline.ts",
+      "signature": "export interface GlyfFont",
+      "summary": "A parsed TrueType font exposing just enough to read glyph outlines."
+    },
+    {
+      "name": "GradientExtend",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export type GradientExtend = 'pad' | 'repeat' | 'reflect';",
+      "summary": "How a gradient extends beyond its [0,1] range (COLR Extend / PDF Extend)."
+    },
+    {
+      "name": "HEADER_H",
+      "kind": "value",
+      "module": "src/core/pdf-layout.ts",
+      "signature": "export const HEADER_H = 15;",
+      "summary": null
+    },
+    {
+      "name": "HeadingBlock",
+      "kind": "type",
+      "module": "src/types/pdf-document-types.ts",
+      "signature": "export interface HeadingBlock",
+      "summary": "Heading block — rendered at a predefined size based on level."
+    },
+    {
+      "name": "INFO_LN",
+      "kind": "value",
+      "module": "src/core/pdf-layout.ts",
+      "signature": "export const INFO_LN = 13;",
+      "summary": null
+    },
+    {
+      "name": "ImageBlock",
+      "kind": "type",
+      "module": "src/types/pdf-document-types.ts",
+      "signature": "export interface ImageBlock",
+      "summary": "Image block — embeds a JPEG or PNG image."
+    },
+    {
+      "name": "InspectedBlock",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export interface InspectedBlock",
+      "summary": "One block's laid-out footprint, as reported by inspectDocumentLayout."
+    },
+    {
+      "name": "InspectedPage",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export interface InspectedPage",
+      "summary": "One page's worth of InspectedBlocks."
+    },
+    {
+      "name": "InternalLink",
+      "kind": "type",
+      "module": "src/core/pdf-annot.ts",
+      "signature": "export interface InternalLink",
+      "summary": "Internal link annotation (GoTo action — page destination)."
+    },
+    {
+      "name": "KNOWN_DECODE_FILTERS",
+      "kind": "value",
+      "module": "src/parser/pdf-decode-filters.ts",
+      "signature": "export const KNOWN_DECODE_FILTERS = new Set<string>([",
+      "summary": "Known non-Flate decode filter names (for membership checks)."
+    },
+    {
+      "name": "LayoutDebugOptions",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export interface LayoutDebugOptions",
+      "summary": "Fine-grained control over the PdfLayoutOptions.debug overlay layers."
+    },
+    {
+      "name": "LayoutInspection",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export interface LayoutInspection",
+      "summary": "Deterministic, read-only description of how inspectDocumentLayout expects the document builder to paginate and place a set of blocks."
+    },
+    {
+      "name": "LineAnnotation",
+      "kind": "type",
+      "module": "src/core/pdf-annot-markup.ts",
+      "signature": "export interface LineAnnotation extends AnnotationBase",
+      "summary": "Straight-line annotation (`/Subtype /Line`)."
+    },
+    {
+      "name": "LinearGradientPaint",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export interface LinearGradientPaint",
+      "summary": "A linear (axial) gradient fill (COLR PaintLinearGradient → PDF Shading 2)."
+    },
+    {
+      "name": "LinkAnnotation",
+      "kind": "type",
+      "module": "src/core/pdf-annot.ts",
+      "signature": "export interface LinkAnnotation",
+      "summary": "External link annotation (URI action)."
+    },
+    {
+      "name": "LinkBlock",
+      "kind": "type",
+      "module": "src/types/pdf-document-types.ts",
+      "signature": "export interface LinkBlock",
+      "summary": "Link block — clickable hyperlink text."
+    },
+    {
+      "name": "ListBlock",
+      "kind": "type",
+      "module": "src/types/pdf-document-types.ts",
+      "signature": "export interface ListBlock",
+      "summary": "List block — bullet or numbered items."
+    },
+    {
+      "name": "ListItem",
+      "kind": "type",
+      "module": "src/types/pdf-document-types.ts",
+      "signature": "export interface ListItem",
+      "summary": "A single hierarchical list entry: text plus an optional nested sub-list."
+    },
+    {
+      "name": "LtvData",
+      "kind": "type",
+      "module": "src/core/pdf-dss.ts",
+      "signature": "export interface LtvData",
+      "summary": "Transport-free validation material, serializable and replayable."
+    },
+    {
+      "name": "MAX_PARSE_DEPTH",
+      "kind": "value",
+      "module": "src/parser/pdf-object-parser.ts",
+      "signature": "export const MAX_PARSE_DEPTH = 1000;",
+      "summary": "Maximum depth for recursive PDF object parsing (nested arrays/dicts)."
+    },
+    {
+      "name": "MAX_XREF_CHAIN",
+      "kind": "value",
+      "module": "src/parser/pdf-xref-parser.ts",
+      "signature": "export const MAX_XREF_CHAIN = 100;",
+      "summary": "Maximum depth of the xref `/Prev` chain."
+    },
+    {
+      "name": "MarkupAnnotation",
+      "kind": "type",
+      "module": "src/core/pdf-annot-markup.ts",
+      "signature": "export type MarkupAnnotation =",
+      "summary": "Any builder-supported annotation."
+    },
+    {
+      "name": "MergeOptions",
+      "kind": "type",
+      "module": "src/parser/pdf-pagetree.ts",
+      "signature": "export interface MergeOptions",
+      "summary": "Options for the page-tree manipulation API (mergePdfs, splitPdf, extractPages)."
+    },
+    {
+      "name": "OcspCertStatus",
+      "kind": "type",
+      "module": "src/crypto/ocsp.ts",
+      "signature": "export type OcspCertStatus = 'good' | 'revoked' | 'unknown';",
+      "summary": "SingleResponse certStatus."
+    },
+    {
+      "name": "OcspRequestOptions",
+      "kind": "type",
+      "module": "src/crypto/ocsp.ts",
+      "signature": "export interface OcspRequestOptions",
+      "summary": "Options for buildOcspRequest."
+    },
+    {
+      "name": "OcspResponse",
+      "kind": "type",
+      "module": "src/crypto/ocsp.ts",
+      "signature": "export interface OcspResponse",
+      "summary": "Parsed OCSPResponse (RFC 6960 §4.2.1)."
+    },
+    {
+      "name": "OpenPdfOptions",
+      "kind": "type",
+      "module": "src/parser/pdf-reader.ts",
+      "signature": "export interface OpenPdfOptions",
+      "summary": "Options for openPdf."
+    },
+    {
+      "name": "OutlineItem",
+      "kind": "type",
+      "module": "src/types/pdf-document-types.ts",
+      "signature": "export interface OutlineItem",
+      "summary": "A document outline (bookmark) entry — ISO 32000-1 §12.3.3."
+    },
+    {
+      "name": "OutlinePoint",
+      "kind": "type",
+      "module": "src/fonts/glyf-outline.ts",
+      "signature": "export interface OutlinePoint",
+      "summary": "A single outline point in font units."
+    },
+    {
+      "name": "OutlineProvider",
+      "kind": "type",
+      "module": "src/core/pdf-color-glyph.ts",
+      "signature": "export type OutlineProvider = (glyphId: number) => Contour[];",
+      "summary": "Provider of glyph outlines (decoupled from the font parser for testing)."
+    },
+    {
+      "name": "PAGE_SIZES",
+      "kind": "value",
+      "module": "src/core/pdf-layout.ts",
+      "signature": "export const PAGE_SIZES =",
+      "summary": null
+    },
+    {
+      "name": "PDF_A_CONFORMANCE_TARGETS",
+      "kind": "value",
+      "module": "src/core/pdf-tags.ts",
+      "signature": "export const PDF_A_CONFORMANCE_TARGETS = ['pdfa1b', 'pdfa2b', 'pdfa2u', 'pdfa3b'] as const;",
+      "summary": "Canonical list of PDF/A conformance targets accepted by the `tagged` layout option."
+    },
+    {
+      "name": "PG_H",
+      "kind": "value",
+      "module": "src/core/pdf-layout.ts",
+      "signature": "export const PG_H = 841.89; // A4 height (297mm)",
+      "summary": null
+    },
+    {
+      "name": "PG_W",
+      "kind": "value",
+      "module": "src/core/pdf-layout.ts",
+      "signature": "export const PG_W = 595.28; // A4 width (210mm)",
+      "summary": null
+    },
+    {
+      "name": "PageBox",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export type PageBox = readonly [number, number, number, number];",
+      "summary": "A page box rectangle `[x0, y0, x1, y1]` in points, PDF user space."
+    },
+    {
+      "name": "PageBreakBlock",
+      "kind": "type",
+      "module": "src/types/pdf-document-types.ts",
+      "signature": "export interface PageBreakBlock",
+      "summary": "Page break block — forces a new page."
+    },
+    {
+      "name": "PageLabelRange",
+      "kind": "type",
+      "module": "src/types/pdf-document-types.ts",
+      "signature": null,
+      "summary": null
+    },
+    {
+      "name": "PageLabelStyle",
+      "kind": "type",
+      "module": "src/types/pdf-document-types.ts",
+      "signature": null,
+      "summary": null
+    },
+    {
+      "name": "PageRange",
+      "kind": "type",
+      "module": "src/parser/pdf-pagetree.ts",
+      "signature": "export interface PageRange",
+      "summary": "A contiguous, inclusive page range (0-based)."
+    },
+    {
+      "name": "PageTemplate",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export interface PageTemplate",
+      "summary": "Template for page headers and footers with placeholder support."
+    },
+    {
+      "name": "ParagraphBlock",
+      "kind": "type",
+      "module": "src/types/pdf-document-types.ts",
+      "signature": "export interface ParagraphBlock",
+      "summary": "Paragraph block — text wrapping with configurable alignment."
+    },
+    {
+      "name": "ParsedAnnotation",
+      "kind": "type",
+      "module": "src/parser/pdf-reader.ts",
+      "signature": "export interface ParsedAnnotation",
+      "summary": "A page annotation parsed by PdfReader.getAnnotations."
+    },
+    {
+      "name": "ParsedArray",
+      "kind": "type",
+      "module": "src/parser/pdf-object-parser.ts",
+      "signature": null,
+      "summary": null
+    },
+    {
+      "name": "ParsedCms",
+      "kind": "type",
+      "module": "src/crypto/cms-utils.ts",
+      "signature": "export interface ParsedCms",
+      "summary": "Structural view over a DER-encoded CMS ContentInfo/SignedData."
+    },
+    {
+      "name": "ParsedCrl",
+      "kind": "type",
+      "module": "src/crypto/crl.ts",
+      "signature": "export interface ParsedCrl",
+      "summary": "Parsed CertificateList (RFC 5280 §5.1)."
+    },
+    {
+      "name": "ParsedDict",
+      "kind": "type",
+      "module": "src/parser/pdf-object-parser.ts",
+      "signature": null,
+      "summary": null
+    },
+    {
+      "name": "ParsedFieldType",
+      "kind": "type",
+      "module": "src/core/pdf-form-fill.ts",
+      "signature": "export type ParsedFieldType =",
+      "summary": null
+    },
+    {
+      "name": "ParsedFormField",
+      "kind": "type",
+      "module": "src/core/pdf-form-fill.ts",
+      "signature": "export interface ParsedFormField",
+      "summary": "A form field parsed from an existing document by readFormFields."
+    },
+    {
+      "name": "ParsedImage",
+      "kind": "type",
+      "module": "src/core/pdf-image.ts",
+      "signature": "export interface ParsedImage",
+      "summary": "Parsed image data ready for PDF embedding."
+    },
+    {
+      "name": "PdfAConfig",
+      "kind": "type",
+      "module": "src/core/pdf-tags.ts",
+      "signature": "export interface PdfAConfig",
+      "summary": "Resolved PDF/A configuration from the `tagged` layout option."
+    },
+    {
+      "name": "PdfAConformanceTarget",
+      "kind": "type",
+      "module": "src/core/pdf-tags.ts",
+      "signature": "export type PdfAConformanceTarget = typeof PDF_A_CONFORMANCE_TARGETS[number];",
+      "summary": "Type alias for the string literal members of PDF_A_CONFORMANCE_TARGETS."
+    },
+    {
+      "name": "PdfAttachment",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export interface PdfAttachment",
+      "summary": "Embedded file attachment for PDF/A-3 (ISO 19005-3)."
+    },
+    {
+      "name": "PdfAttachmentRelationship",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export type PdfAttachmentRelationship = 'Source' | 'Data' | 'Alternative' | 'Supplement' | 'Unspecified';",
+      "summary": "Relationship of an embedded file to the PDF document (ISO 19005-3 §6.8)."
+    },
+    {
+      "name": "PdfColor",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export type PdfColor = PdfRgbString | PdfRgbTuple | (string & {});",
+      "summary": "Color input accepted by pdfnative."
+    },
+    {
+      "name": "PdfColors",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export interface PdfColors",
+      "summary": "Color palette for the PDF."
+    },
+    {
+      "name": "PdfDiagnostic",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export interface PdfDiagnostic",
+      "summary": "A single conformance diagnostic surfaced by the builders."
+    },
+    {
+      "name": "PdfDiagnosticCode",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export type PdfDiagnosticCode =",
+      "summary": "Machine-readable conformance diagnostic codes (stable API — additions only)."
+    },
+    {
+      "name": "PdfDiagnosticHandler",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export type PdfDiagnosticHandler = (diagnostic: PdfDiagnostic) => void;",
+      "summary": "Sink for conformance diagnostics."
+    },
+    {
+      "name": "PdfEncryptionInfo",
+      "kind": "type",
+      "module": "src/parser/pdf-reader.ts",
+      "signature": "export interface PdfEncryptionInfo",
+      "summary": "Encryption details of an opened document, or `null` when it is not encrypted."
+    },
+    {
+      "name": "PdfEncryptionUnsupportedError",
+      "kind": "value",
+      "module": "src/parser/pdf-decrypt.ts",
+      "signature": "export class PdfEncryptionUnsupportedError extends Error",
+      "summary": "Thrown when the document uses an encryption scheme pdfnative cannot read."
+    },
+    {
+      "name": "PdfIndirectObject",
+      "kind": "type",
+      "module": "src/parser/pdf-object-parser.ts",
+      "signature": "export interface PdfIndirectObject",
+      "summary": null
+    },
+    {
+      "name": "PdfInfoItem",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export interface PdfInfoItem",
+      "summary": "An info key/value pair displayed in the header section."
+    },
+    {
+      "name": "PdfLayoutOptions",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export interface PdfLayoutOptions",
+      "summary": "Layout options (all optional, A4 defaults applied)."
+    },
+    {
+      "name": "PdfMetadataUpdate",
+      "kind": "type",
+      "module": "src/parser/pdf-modifier.ts",
+      "signature": "export interface PdfMetadataUpdate",
+      "summary": "Metadata fields applied by PdfModifier.updateMetadata."
+    },
+    {
+      "name": "PdfModifier",
+      "kind": "type",
+      "module": "src/parser/pdf-modifier.ts",
+      "signature": "export interface PdfModifier",
+      "summary": null
+    },
+    {
+      "name": "PdfName",
+      "kind": "type",
+      "module": "src/parser/pdf-object-parser.ts",
+      "signature": "export interface PdfName",
+      "summary": null
+    },
+    {
+      "name": "PdfParams",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export interface PdfParams",
+      "summary": "Parameters for PDF generation."
+    },
+    {
+      "name": "PdfPasswordError",
+      "kind": "value",
+      "module": "src/parser/pdf-decrypt.ts",
+      "signature": "export class PdfPasswordError extends Error",
+      "summary": "Thrown when a password is missing or rejected."
+    },
+    {
+      "name": "PdfReader",
+      "kind": "type",
+      "module": "src/parser/pdf-reader.ts",
+      "signature": "export interface PdfReader",
+      "summary": null
+    },
+    {
+      "name": "PdfRef",
+      "kind": "type",
+      "module": "src/parser/pdf-object-parser.ts",
+      "signature": "export interface PdfRef",
+      "summary": null
+    },
+    {
+      "name": "PdfRgbString",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export type PdfRgbString = `${number} ${number} ${number}`;",
+      "summary": "PDF RGB color string in operator format: \"R G B\" (values 0.0–1.0)."
+    },
+    {
+      "name": "PdfRgbTuple",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export type PdfRgbTuple = readonly [r: number, g: number, b: number];",
+      "summary": "RGB color as a 3-tuple of values 0–255."
+    },
+    {
+      "name": "PdfRow",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export interface PdfRow",
+      "summary": "A single row in the PDF table."
+    },
+    {
+      "name": "PdfSignOptions",
+      "kind": "type",
+      "module": "src/core/pdf-signature.ts",
+      "signature": "export interface PdfSignOptions extends SigDictMetadata",
+      "summary": null
+    },
+    {
+      "name": "PdfSignTimestampOptions",
+      "kind": "type",
+      "module": "src/core/pdf-sign-timestamp.ts",
+      "signature": "export interface PdfSignTimestampOptions extends PdfSignOptions",
+      "summary": "Options for signPdfBytesWithTimestamp."
+    },
+    {
+      "name": "PdfSignatureInfo",
+      "kind": "type",
+      "module": "src/core/pdf-sig-utils.ts",
+      "signature": "export interface PdfSignatureInfo",
+      "summary": "One signature field entry, in AcroForm /Fields order."
+    },
+    {
+      "name": "PdfSourceInput",
+      "kind": "type",
+      "module": "src/parser/pdf-pagetree.ts",
+      "signature": "export type PdfSourceInput = Uint8Array | { readonly bytes: Uint8Array; readonly password?: string };",
+      "summary": "A merge source: raw PDF bytes, or bytes paired with the password needed to decrypt an encrypted source."
+    },
+    {
+      "name": "PdfStream",
+      "kind": "type",
+      "module": "src/parser/pdf-object-parser.ts",
+      "signature": "export interface PdfStream",
+      "summary": null
+    },
+    {
+      "name": "PdfToken",
+      "kind": "type",
+      "module": "src/parser/pdf-tokenizer.ts",
+      "signature": "export interface PdfToken",
+      "summary": null
+    },
+    {
+      "name": "PdfTokenizer",
+      "kind": "type",
+      "module": "src/parser/pdf-tokenizer.ts",
+      "signature": "export interface PdfTokenizer",
+      "summary": null
+    },
+    {
+      "name": "PdfUAValidationResult",
+      "kind": "type",
+      "module": "src/parser/pdf-ua-validator.ts",
+      "signature": "export interface PdfUAValidationResult",
+      "summary": "Result of a PDF/UA structural validation."
+    },
+    {
+      "name": "PdfValue",
+      "kind": "type",
+      "module": "src/parser/pdf-object-parser.ts",
+      "signature": "export type PdfValue =",
+      "summary": "Union of all PDF object types (ISO 32000-1 §7.3)."
+    },
+    {
+      "name": "PrintOptions",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export interface PrintOptions",
+      "summary": "Professional print-production options (`layout.print`, v1.7.0): page geometry boxes (ISO 32000-1 §14.11.2), printer's marks (§14.11.3) and large-format `/UserUnit`."
+    },
+    {
+      "name": "PrinterMarksOptions",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export interface PrinterMarksOptions",
+      "summary": "Printer's-marks options for PrintOptions.marks."
+    },
+    {
+      "name": "QRErrorLevel",
+      "kind": "type",
+      "module": "src/core/pdf-barcode.ts",
+      "signature": "export type QRErrorLevel = 'L' | 'M' | 'Q' | 'H';",
+      "summary": "QR Code error correction levels."
+    },
+    {
+      "name": "ROW_H",
+      "kind": "value",
+      "module": "src/core/pdf-layout.ts",
+      "signature": "export const ROW_H = 12;",
+      "summary": null
+    },
+    {
+      "name": "RadialGradientPaint",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export interface RadialGradientPaint",
+      "summary": "A radial gradient fill (COLR PaintRadialGradient → PDF Shading 3)."
+    },
+    {
+      "name": "RadioGroupContext",
+      "kind": "type",
+      "module": "src/core/pdf-form.ts",
+      "signature": "export interface RadioGroupContext",
+      "summary": "Context for building a radio button child widget within a group."
+    },
+    {
+      "name": "ResolvedPrintBoxes",
+      "kind": "type",
+      "module": "src/core/pdf-print.ts",
+      "signature": "export interface ResolvedPrintBoxes",
+      "summary": "Resolved print geometry: the page-dict fragment and the trim rectangle."
+    },
+    {
+      "name": "RevocationProvider",
+      "kind": "type",
+      "module": "src/crypto/revocation-provider.ts",
+      "signature": "export interface RevocationProvider",
+      "summary": "A pluggable revocation-data transport."
+    },
+    {
+      "name": "RsaDigest",
+      "kind": "type",
+      "module": "src/crypto/rsa.ts",
+      "signature": "export type RsaDigest = 'sha256' | 'sha384' | 'sha512';",
+      "summary": "Digest algorithm selector for the RSA PKCS#1 v1.5 entry points."
+    },
+    {
+      "name": "RsaPrivateKey",
+      "kind": "type",
+      "module": "src/crypto/rsa.ts",
+      "signature": "export interface RsaPrivateKey",
+      "summary": "RSA private key (CRT form for efficiency)."
+    },
+    {
+      "name": "RsaPublicKey",
+      "kind": "type",
+      "module": "src/crypto/rsa.ts",
+      "signature": "export interface RsaPublicKey",
+      "summary": "RSA public key."
+    },
+    {
+      "name": "ShapeAnnotation",
+      "kind": "type",
+      "module": "src/core/pdf-annot-markup.ts",
+      "signature": "export interface ShapeAnnotation extends AnnotationBase",
+      "summary": "Rectangle / ellipse drawing annotation."
+    },
+    {
+      "name": "ShapedGlyph",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export interface ShapedGlyph",
+      "summary": "A single positioned glyph output from the Thai shaper."
+    },
+    {
+      "name": "SigDictMetadata",
+      "kind": "type",
+      "module": "src/core/pdf-signature.ts",
+      "signature": "export interface SigDictMetadata",
+      "summary": "Metadata-only subset of PdfSignOptions used by buildSigDict and addSignaturePlaceholder."
+    },
+    {
+      "name": "SignatureAlgorithm",
+      "kind": "type",
+      "module": "src/crypto/cms.ts",
+      "signature": "export type SignatureAlgorithm = 'rsa-sha256' | 'ecdsa-sha256' | 'rsa-sha384' | 'rsa-sha512';",
+      "summary": null
+    },
+    {
+      "name": "SolidPaint",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export interface SolidPaint",
+      "summary": "A flat colour fill (COLR PaintSolid / COLRv0 layer)."
+    },
+    {
+      "name": "SpacerBlock",
+      "kind": "type",
+      "module": "src/types/pdf-document-types.ts",
+      "signature": "export interface SpacerBlock",
+      "summary": "Spacer block — vertical whitespace."
+    },
+    {
+      "name": "SplitPdfStream",
+      "kind": "type",
+      "module": "src/parser/pdf-pagetree.ts",
+      "signature": "export interface SplitPdfStream",
+      "summary": "One emitted document from streamSplitPdf."
+    },
+    {
+      "name": "StreamMergeOptions",
+      "kind": "type",
+      "module": "src/parser/pdf-pagetree.ts",
+      "signature": "export interface StreamMergeOptions extends MergeOptions",
+      "summary": "Options for the streaming page-tree variants."
+    },
+    {
+      "name": "StreamOptions",
+      "kind": "type",
+      "module": "src/core/pdf-stream-writer.ts",
+      "signature": "export interface StreamOptions",
+      "summary": "Options for streaming PDF output."
+    },
+    {
+      "name": "StreamToFileResult",
+      "kind": "type",
+      "module": "src/core/pdf-stream-writer.ts",
+      "signature": "export interface StreamToFileResult",
+      "summary": "Result of streamToFile."
+    },
+    {
+      "name": "SvgBlock",
+      "kind": "type",
+      "module": "src/types/pdf-document-types.ts",
+      "signature": "export interface SvgBlock",
+      "summary": "SVG block — renders vector graphics via PDF path operators."
+    },
+    {
+      "name": "SvgRenderOptions",
+      "kind": "type",
+      "module": "src/core/pdf-svg.ts",
+      "signature": "export interface SvgRenderOptions",
+      "summary": "Options for SVG rendering to PDF operators."
+    },
+    {
+      "name": "SvgSegment",
+      "kind": "type",
+      "module": "src/core/pdf-svg.ts",
+      "signature": "export interface SvgSegment",
+      "summary": "Parsed SVG path segment in absolute coordinates (M, L, C, Z only)."
+    },
+    {
+      "name": "TH_H",
+      "kind": "value",
+      "module": "src/core/pdf-layout.ts",
+      "signature": "export const TH_H = 15;",
+      "summary": null
+    },
+    {
+      "name": "TITLE_LN",
+      "kind": "value",
+      "module": "src/core/pdf-layout.ts",
+      "signature": "export const TITLE_LN = 22;",
+      "summary": null
+    },
+    {
+      "name": "TableBlock",
+      "kind": "type",
+      "module": "src/types/pdf-document-types.ts",
+      "signature": "export interface TableBlock",
+      "summary": "Table block — reuses existing PdfRow/ColumnDef types."
+    },
+    {
+      "name": "TextAnnotation",
+      "kind": "type",
+      "module": "src/core/pdf-annot-markup.ts",
+      "signature": "export interface TextAnnotation extends AnnotationBase",
+      "summary": "Sticky-note text annotation (`/Subtype /Text`)."
+    },
+    {
+      "name": "TextMarkupAnnotation",
+      "kind": "type",
+      "module": "src/core/pdf-annot-markup.ts",
+      "signature": "export interface TextMarkupAnnotation extends AnnotationBase",
+      "summary": "Text-markup annotation (highlight / underline / strike-out / squiggly)."
+    },
+    {
+      "name": "TextRun",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export interface TextRun",
+      "summary": "A text run produced by the encoding context's textRuns() method."
+    },
+    {
+      "name": "TimestampProvider",
+      "kind": "type",
+      "module": "src/crypto/timestamp-provider.ts",
+      "signature": "export interface TimestampProvider",
+      "summary": "A pluggable RFC 3161 transport: sends a DER `TimeStampReq` to a TSA and resolves with the DER `TimeStampResp`."
+    },
+    {
+      "name": "TimestampRequestOptions",
+      "kind": "type",
+      "module": "src/crypto/rfc3161.ts",
+      "signature": "export interface TimestampRequestOptions",
+      "summary": "Options for buildTimestampRequest."
+    },
+    {
+      "name": "TimestampResponse",
+      "kind": "type",
+      "module": "src/crypto/rfc3161.ts",
+      "signature": "export interface TimestampResponse",
+      "summary": "Parsed TimeStampResp (RFC 3161 §2.4.2)."
+    },
+    {
+      "name": "TocBlock",
+      "kind": "type",
+      "module": "src/types/pdf-document-types.ts",
+      "signature": "export interface TocBlock",
+      "summary": "Table of Contents block — auto-generated from heading blocks."
+    },
+    {
+      "name": "TokenType",
+      "kind": "type",
+      "module": "src/parser/pdf-tokenizer.ts",
+      "signature": "export type TokenType =",
+      "summary": null
+    },
+    {
+      "name": "TstInfo",
+      "kind": "type",
+      "module": "src/crypto/rfc3161.ts",
+      "signature": "export interface TstInfo",
+      "summary": "Parsed TSTInfo from a TimeStampToken (RFC 3161 §2.4.2)."
+    },
+    {
+      "name": "UseCategory",
+      "kind": "type",
+      "module": "src/shaping/use-lite.ts",
+      "signature": "export type UseCategory =",
+      "summary": "USE-lite cluster categories."
+    },
+    {
+      "name": "UseClassifiedCp",
+      "kind": "type",
+      "module": "src/shaping/use-lite.ts",
+      "signature": "export interface UseClassifiedCp",
+      "summary": "Classified code point with its USE-lite category."
+    },
+    {
+      "name": "UseCluster",
+      "kind": "type",
+      "module": "src/shaping/use-lite.ts",
+      "signature": "export interface UseCluster",
+      "summary": "A USE-lite cluster: a base plus its prefixed/suffixed marks and signs."
+    },
+    {
+      "name": "ViewerPreferences",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export interface ViewerPreferences",
+      "summary": "Viewer presentation preferences (ISO 32000-1 §12.2, Table 150 + §7.7.2)."
+    },
+    {
+      "name": "WORKER_THRESHOLD",
+      "kind": "value",
+      "module": "src/worker/worker-api.ts",
+      "signature": "export const WORKER_THRESHOLD = 500;",
+      "summary": "Default threshold: use Worker for datasets above this row count."
+    },
+    {
+      "name": "WORKER_TIMEOUT_MS",
+      "kind": "value",
+      "module": "src/worker/worker-api.ts",
+      "signature": "export const WORKER_TIMEOUT_MS = 60000;",
+      "summary": "Worker timeout in milliseconds (used when options.timeout is not supplied)."
+    },
+    {
+      "name": "WatermarkImage",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export interface WatermarkImage",
+      "summary": "Image watermark configuration."
+    },
+    {
+      "name": "WatermarkOptions",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export interface WatermarkOptions",
+      "summary": "Watermark options for PDF pages."
+    },
+    {
+      "name": "WatermarkState",
+      "kind": "type",
+      "module": "src/core/pdf-watermark.ts",
+      "signature": "export interface WatermarkState",
+      "summary": "Resolved watermark state for use during PDF assembly."
+    },
+    {
+      "name": "WatermarkText",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export interface WatermarkText",
+      "summary": "Text watermark configuration."
+    },
+    {
+      "name": "WorkerGenerationOptions",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export interface WorkerGenerationOptions",
+      "summary": "Options for generating a PDF in a Web Worker via `generatePDFInWorker()`."
+    },
+    {
+      "name": "WorkerInputMessage",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export interface WorkerInputMessage",
+      "summary": "Message sent to the PDF Worker."
+    },
+    {
+      "name": "WorkerOutputMessage",
+      "kind": "type",
+      "module": "src/types/pdf-types.ts",
+      "signature": "export type WorkerOutputMessage =",
+      "summary": "Messages received from the PDF Worker."
+    },
+    {
+      "name": "X509Certificate",
+      "kind": "type",
+      "module": "src/crypto/x509.ts",
+      "signature": "export interface X509Certificate",
+      "summary": null
+    },
+    {
+      "name": "X509Name",
+      "kind": "type",
+      "module": "src/crypto/x509.ts",
+      "signature": "export interface X509Name",
+      "summary": null
+    },
+    {
+      "name": "XrefEntry",
+      "kind": "type",
+      "module": "src/parser/pdf-xref-parser.ts",
+      "signature": "export interface XrefEntry",
+      "summary": null
+    },
+    {
+      "name": "XrefTable",
+      "kind": "type",
+      "module": "src/parser/pdf-xref-parser.ts",
+      "signature": "export interface XrefTable",
+      "summary": null
+    },
+    {
+      "name": "addDocumentTimestamp",
+      "kind": "value",
+      "module": "src/core/pdf-doc-timestamp.ts",
+      "signature": "export async function addDocumentTimestamp( pdfBytes: Uint8Array, options: AddDocumentTimestampOptions = {}, ): Promise<Uint8Array>",
+      "summary": "Append a document-timestamp revision covering every byte of the current document (all earlier revisions stay byte-identical)."
+    },
+    {
+      "name": "addSignaturePlaceholder",
+      "kind": "value",
+      "module": "src/core/pdf-sig-placeholder.ts",
+      "signature": "export function addSignaturePlaceholder( pdfBytes: Uint8Array, options: AddSignaturePlaceholderOptions = {}, ): Uint8Array",
+      "summary": "Inject an AcroForm + signature widget placeholder into an existing PDF via incremental update."
+    },
+    {
+      "name": "addUnsignedAttribute",
+      "kind": "value",
+      "module": "src/crypto/cms-utils.ts",
+      "signature": "export function addUnsignedAttribute(cmsDer: Uint8Array, attributeTlv: Uint8Array): Uint8Array",
+      "summary": "Append an attribute to the `[1] IMPLICIT unsignedAttrs` slot of the first SignerInfo in a CMS SignedData, creating the slot when absent."
+    },
+    {
+      "name": "addValidationInfo",
+      "kind": "value",
+      "module": "src/core/pdf-dss.ts",
+      "signature": "export async function addValidationInfo( pdfBytes: Uint8Array, options: CollectLtvOptions = {}, ): Promise<Uint8Array>",
+      "summary": "Convenience: collectValidationInfo + embedValidationInfo."
+    },
+    {
+      "name": "applyDecodeFilter",
+      "kind": "value",
+      "module": "src/parser/pdf-decode-filters.ts",
+      "signature": "export function applyDecodeFilter(name: string, data: Uint8Array): Uint8Array",
+      "summary": "Apply a single PDF stream filter by name."
+    },
+    {
+      "name": "buildAcroFormDict",
+      "kind": "value",
+      "module": "src/core/pdf-form.ts",
+      "signature": "export function buildAcroFormDict(fieldObjNums: readonly number[], fontObjNum?: number): string",
+      "summary": "Build the /AcroForm dictionary content for the catalog."
+    },
+    {
+      "name": "buildAnnotation",
+      "kind": "value",
+      "module": "src/core/pdf-annot-markup.ts",
+      "signature": "export function buildAnnotation(annot: MarkupAnnotation, objNum: number): string",
+      "summary": "Build a markup / drawing annotation as a PDF indirect object."
+    },
+    {
+      "name": "buildAnnotationBody",
+      "kind": "value",
+      "module": "src/core/pdf-annot-markup.ts",
+      "signature": "export function buildAnnotationBody(annot: MarkupAnnotation): string",
+      "summary": "Build just the annotation dictionary (`<< … >>`), without the `obj`/`endobj` wrapper."
+    },
+    {
+      "name": "buildAppearanceStreamDict",
+      "kind": "value",
+      "module": "src/core/pdf-form.ts",
+      "signature": "export function buildAppearanceStreamDict(w: number, h: number, streamLength: number, fontObjNum?: number): string",
+      "summary": "Build the Form XObject dictionary header for an appearance stream."
+    },
+    {
+      "name": "buildAttribute",
+      "kind": "value",
+      "module": "src/crypto/cms-utils.ts",
+      "signature": "export function buildAttribute(oidBytes: Uint8Array, ...values: Uint8Array[]): Uint8Array",
+      "summary": "Build a CMS Attribute TLV: `SEQUENCE { attrType OID, attrValues SET OF }`."
+    },
+    {
+      "name": "buildCmsSignedData",
+      "kind": "value",
+      "module": "src/crypto/cms.ts",
+      "signature": "export function buildCmsSignedData(options: CmsSignOptions): Uint8Array",
+      "summary": "Build a CMS SignedData structure for a PDF detached signature."
+    },
+    {
+      "name": "buildDocTimeStampDict",
+      "kind": "value",
+      "module": "src/core/pdf-signature.ts",
+      "signature": "export function buildDocTimeStampDict(contentsSize: number = DEFAULT_CONTENTS_SIZE): string",
+      "summary": "Build a `/DocTimeStamp` dictionary string (ISO 32000-2 §12.8.5) with the same byte-patchable /Contents + /ByteRange placeholders as buildSigDict."
+    },
+    {
+      "name": "buildDocumentPDF",
+      "kind": "value",
+      "module": "src/core/pdf-document.ts",
+      "signature": "export function buildDocumentPDF(params: DocumentParams, layoutOptions?: Partial<PdfLayoutOptions>): string",
+      "summary": "Build a free-form PDF document from content blocks."
+    },
+    {
+      "name": "buildDocumentPDFBytes",
+      "kind": "value",
+      "module": "src/core/pdf-document.ts",
+      "signature": "export function buildDocumentPDFBytes(params: DocumentParams, layoutOptions?: Partial<PdfLayoutOptions>): Uint8Array",
+      "summary": "Build a free-form PDF document and return as Uint8Array."
+    },
+    {
+      "name": "buildDocumentPDFStream",
+      "kind": "value",
+      "module": "src/core/pdf-stream-writer.ts",
+      "signature": "export async function* buildDocumentPDFStream( params: DocumentParams, layoutOptions?: Partial<PdfLayoutOptions>, streamOptions?: StreamOptions, ): AsyncGenerator<Uint8Array>",
+      "summary": "Build a free-form PDF document and yield Uint8Array chunks progressively."
+    },
+    {
+      "name": "buildDocumentPDFStreamPageByPage",
+      "kind": "value",
+      "module": "src/core/pdf-stream-writer.ts",
+      "signature": "export async function* buildDocumentPDFStreamPageByPage( params: DocumentParams, layoutOptions?: Partial<PdfLayoutOptions>, ): AsyncGenerator<Uint8Array>",
+      "summary": "Build a free-form PDF document and yield Uint8Array chunks aligned at PDF object boundaries (one indirect object per chunk, plus a header chunk and a trailing xref/trailer chunk)."
+    },
+    {
+      "name": "buildDocumentPDFStreamTrue",
+      "kind": "value",
+      "module": "src/core/pdf-stream-writer.ts",
+      "signature": "export async function* buildDocumentPDFStreamTrue( params: DocumentParams, layoutOptions?: Partial<PdfLayoutOptions>, streamOptions?: StreamOptions, ): AsyncGenerator<Uint8Array>",
+      "summary": "Build a free-form PDF document, streaming it out **without ever joining the binary**."
+    },
+    {
+      "name": "buildEmbeddedFiles",
+      "kind": "value",
+      "module": "src/core/pdf-tags.ts",
+      "signature": "export function buildEmbeddedFiles(attachments: readonly PdfAttachment[], startObjNum: number): EmbeddedFilesResult",
+      "summary": "Build PDF objects for embedded file attachments (PDF/A-3)."
+    },
+    {
+      "name": "buildFormWidget",
+      "kind": "value",
+      "module": "src/core/pdf-form.ts",
+      "signature": "export function buildFormWidget(field: FormField, apObjNum: number, radioCtx?: RadioGroupContext): FormWidgetResult",
+      "summary": "Build a form field widget annotation dictionary and its appearance stream."
+    },
+    {
+      "name": "buildImageOperators",
+      "kind": "value",
+      "module": "src/core/pdf-image.ts",
+      "signature": "export function buildImageOperators( imgRef: string, x: number, y: number, width: number, height: number, ): string",
+      "summary": "Build the content stream operators to paint an image at the given position and size."
+    },
+    {
+      "name": "buildImageXObject",
+      "kind": "value",
+      "module": "src/core/pdf-image.ts",
+      "signature": "export function buildImageXObject(img: ParsedImage, smaskObjNum?: number): string",
+      "summary": "Build a PDF Image XObject dictionary + stream for an image."
+    },
+    {
+      "name": "buildInternalLinkAnnotation",
+      "kind": "value",
+      "module": "src/core/pdf-annot.ts",
+      "signature": "export function buildInternalLinkAnnotation(annot: InternalLink, pageObjNum: number, objNum: number): string",
+      "summary": "Build a PDF link annotation object for an internal page link (GoTo action)."
+    },
+    {
+      "name": "buildLinkAnnotation",
+      "kind": "value",
+      "module": "src/core/pdf-annot.ts",
+      "signature": "export function buildLinkAnnotation(annot: LinkAnnotation, objNum: number): string",
+      "summary": "Build a PDF link annotation object for an external URI."
+    },
+    {
+      "name": "buildOcspRequest",
+      "kind": "value",
+      "module": "src/crypto/ocsp.ts",
+      "signature": "export function buildOcspRequest(cert: X509Certificate, issuer: X509Certificate, options?: OcspRequestOptions): Uint8Array",
+      "summary": "Build an unsigned DER OCSPRequest (RFC 6960 §4.1.1) for one certificate: ``` CertID ::= SEQUENCE { hashAlgorithm  AlgorithmIdentifier (SHA-1), issuerNameHash OCTET STRING,  -- SHA-1 of issuer Name DER issuerKeyHash  OCTET STRING,  -- SHA-1 "
+    },
+    {
+      "name": "buildPDF",
+      "kind": "value",
+      "module": "src/core/pdf-builder.ts",
+      "signature": "export function buildPDF(params: PdfParams, layoutOptions?: Partial<PdfLayoutOptions>): string",
+      "summary": "Build a complete PDF document as a single-byte string."
+    },
+    {
+      "name": "buildPDFBytes",
+      "kind": "value",
+      "module": "src/core/pdf-builder.ts",
+      "signature": "export function buildPDFBytes(params: PdfParams, layoutOptions?: Partial<PdfLayoutOptions>): Uint8Array",
+      "summary": "Build a PDF and return it as a Uint8Array (ready for download or Blob)."
+    },
+    {
+      "name": "buildPDFStream",
+      "kind": "value",
+      "module": "src/core/pdf-stream-writer.ts",
+      "signature": "export async function* buildPDFStream( params: PdfParams, layoutOptions?: Partial<PdfLayoutOptions>, streamOptions?: StreamOptions, ): AsyncGenerator<Uint8Array>",
+      "summary": "Build a table-centric PDF and yield Uint8Array chunks progressively."
+    },
+    {
+      "name": "buildPDFStreamPageByPage",
+      "kind": "value",
+      "module": "src/core/pdf-stream-writer.ts",
+      "signature": "export async function* buildPDFStreamPageByPage( params: PdfParams, layoutOptions?: Partial<PdfLayoutOptions>, ): AsyncGenerator<Uint8Array>",
+      "summary": "Build a table-centric PDF and yield Uint8Array chunks aligned at PDF object boundaries."
+    },
+    {
+      "name": "buildPDFStreamTrue",
+      "kind": "value",
+      "module": "src/core/pdf-stream-writer.ts",
+      "signature": "export async function* buildPDFStreamTrue( params: PdfParams, layoutOptions?: Partial<PdfLayoutOptions>, streamOptions?: StreamOptions, ): AsyncGenerator<Uint8Array>",
+      "summary": "Build a table-centric PDF, streaming it out **without ever joining the binary**."
+    },
+    {
+      "name": "buildPrinterMarksOps",
+      "kind": "value",
+      "module": "src/core/pdf-print.ts",
+      "signature": "export function buildPrinterMarksOps( trim: PageBox, pgW: number, pgH: number, marks: boolean | PrinterMarksOptions, ): string",
+      "summary": "Build the printer's-marks operator block for one page geometry."
+    },
+    {
+      "name": "buildRadioGroupParent",
+      "kind": "value",
+      "module": "src/core/pdf-form.ts",
+      "signature": "export function buildRadioGroupParent( name: string, selectedValue: string, childObjNums: readonly number[], readOnly: boolean, required: boolean, ): string",
+      "summary": "Build the parent field dictionary for a radio button group (ISO 32000-1 §12.7.4.2.4)."
+    },
+    {
+      "name": "buildSMaskXObject",
+      "kind": "value",
+      "module": "src/core/pdf-image.ts",
+      "signature": "export function buildSMaskXObject(smaskData: string, width: number, height: number): string",
+      "summary": "Build a PDF SMask (soft mask) XObject for PNG alpha channel."
+    },
+    {
+      "name": "buildSigDict",
+      "kind": "value",
+      "module": "src/core/pdf-signature.ts",
+      "signature": "export function buildSigDict(options: SigDictMetadata, contentsSize: number = DEFAULT_CONTENTS_SIZE): string",
+      "summary": "Build a /Sig signature dictionary string for embedding in a PDF."
+    },
+    {
+      "name": "buildTimestampRequest",
+      "kind": "value",
+      "module": "src/crypto/rfc3161.ts",
+      "signature": "export function buildTimestampRequest(messageImprint: Uint8Array, options?: TimestampRequestOptions): Uint8Array",
+      "summary": "Build a DER-encoded TimeStampReq (RFC 3161 §2.4.1, version 1): ``` TimeStampReq ::= SEQUENCE { version        INTEGER { v1(1) }, messageImprint MessageImprint, reqPolicy      TSAPolicyId          OPTIONAL, nonce          INTEGER            "
+    },
+    {
+      "name": "buildWatermarkState",
+      "kind": "value",
+      "module": "src/core/pdf-watermark.ts",
+      "signature": "export function buildWatermarkState( watermark: WatermarkOptions, pgW: number, pgH: number, enc: EncodingContext, ): WatermarkState",
+      "summary": "Build watermark content operators and collect resources."
+    },
+    {
+      "name": "certHasEku",
+      "kind": "value",
+      "module": "src/crypto/x509.ts",
+      "signature": "export function certHasEku(cert: X509Certificate, oidBytes: Uint8Array): boolean",
+      "summary": "Check whether a certificate carries a given Extended Key Usage purpose (2.5.29.37), e.g."
+    },
+    {
+      "name": "chunkBinaryString",
+      "kind": "value",
+      "module": "src/core/pdf-stream-writer.ts",
+      "signature": "export function* chunkBinaryString(str: string, chunkSize: number): Generator<Uint8Array>",
+      "summary": "Convert a binary string to Uint8Array chunks without allocating the full Uint8Array at once."
+    },
+    {
+      "name": "classifyClusters",
+      "kind": "value",
+      "module": "src/shaping/use-lite.ts",
+      "signature": "export function classifyClusters(codePoints: readonly number[]): UseCluster[]",
+      "summary": "Split a code-point sequence into USE-lite clusters."
+    },
+    {
+      "name": "classifyUseCategory",
+      "kind": "value",
+      "module": "src/shaping/use-lite.ts",
+      "signature": "export function classifyUseCategory(cp: number): UseCategory",
+      "summary": "Classify a single Unicode code point into a USE-lite category."
+    },
+    {
+      "name": "clearFontCache",
+      "kind": "value",
+      "module": "src/fonts/font-loader.ts",
+      "signature": "export function clearFontCache(): void",
+      "summary": "Clear font cache (useful for testing)."
+    },
+    {
+      "name": "collectValidationInfo",
+      "kind": "value",
+      "module": "src/core/pdf-dss.ts",
+      "signature": "export async function collectValidationInfo( pdfBytes: Uint8Array, options: CollectLtvOptions = {}, ): Promise<LtvData>",
+      "summary": "Collect validation material for every signed signature in the document."
+    },
+    {
+      "name": "computeColumnPositions",
+      "kind": "value",
+      "module": "src/core/pdf-layout.ts",
+      "signature": "export function computeColumnPositions( columns: readonly ColumnDef[], marginLeft: number, contentWidth: number ):",
+      "summary": "Compute column X positions and widths given columns and content width."
+    },
+    {
+      "name": "concatChunks",
+      "kind": "value",
+      "module": "src/core/pdf-stream-writer.ts",
+      "signature": "export function concatChunks(chunks: readonly Uint8Array[]): Uint8Array",
+      "summary": "Concatenate an array of Uint8Array chunks into a single Uint8Array."
+    },
+    {
+      "name": "containsArabic",
+      "kind": "value",
+      "module": "src/shaping/script-registry.ts",
+      "signature": "export function containsArabic(text: string): boolean",
+      "summary": "Check if text contains Arabic characters requiring shaping."
+    },
+    {
+      "name": "containsBengali",
+      "kind": "value",
+      "module": "src/shaping/script-registry.ts",
+      "signature": "export function containsBengali(str: string): boolean",
+      "summary": "Check whether a string contains any Bengali characters."
+    },
+    {
+      "name": "containsDevanagari",
+      "kind": "value",
+      "module": "src/shaping/script-registry.ts",
+      "signature": "export function containsDevanagari(str: string): boolean",
+      "summary": "Check whether a string contains any Devanagari characters."
+    },
+    {
+      "name": "containsEthiopic",
+      "kind": "value",
+      "module": "src/shaping/script-registry.ts",
+      "signature": "export function containsEthiopic(str: string): boolean",
+      "summary": "Check whether a string contains any Ethiopic characters."
+    },
+    {
+      "name": "containsHebrew",
+      "kind": "value",
+      "module": "src/shaping/script-registry.ts",
+      "signature": "export function containsHebrew(text: string): boolean",
+      "summary": "Check if text contains Hebrew characters."
+    },
+    {
+      "name": "containsKhmer",
+      "kind": "value",
+      "module": "src/shaping/script-registry.ts",
+      "signature": "export function containsKhmer(str: string): boolean",
+      "summary": "Check whether a string contains any Khmer characters."
+    },
+    {
+      "name": "containsMath",
+      "kind": "value",
+      "module": "src/shaping/script-registry.ts",
+      "signature": "export function containsMath(str: string): boolean",
+      "summary": "Check whether a string contains any mathematical symbols."
+    },
+    {
+      "name": "containsMyanmar",
+      "kind": "value",
+      "module": "src/shaping/script-registry.ts",
+      "signature": "export function containsMyanmar(str: string): boolean",
+      "summary": "Check whether a string contains any Myanmar characters."
+    },
+    {
+      "name": "containsRTL",
+      "kind": "value",
+      "module": "src/shaping/bidi.ts",
+      "signature": "export function containsRTL(text: string): boolean",
+      "summary": "Check if text contains any RTL characters (Arabic or Hebrew) or an explicit directional override (LRO U+202D / RLO U+202E)."
+    },
+    {
+      "name": "containsSinhala",
+      "kind": "value",
+      "module": "src/shaping/script-registry.ts",
+      "signature": "export function containsSinhala(str: string): boolean",
+      "summary": "Check whether a string contains any Sinhala characters."
+    },
+    {
+      "name": "containsTamil",
+      "kind": "value",
+      "module": "src/shaping/script-registry.ts",
+      "signature": "export function containsTamil(str: string): boolean",
+      "summary": "Check whether a string contains any Tamil characters."
+    },
+    {
+      "name": "containsTelugu",
+      "kind": "value",
+      "module": "src/shaping/script-registry.ts",
+      "signature": "export function containsTelugu(str: string): boolean",
+      "summary": "Check whether a string contains any Telugu characters."
+    },
+    {
+      "name": "containsThai",
+      "kind": "value",
+      "module": "src/shaping/script-registry.ts",
+      "signature": "export function containsThai(str: string): boolean",
+      "summary": "Check whether a string contains any Thai characters."
+    },
+    {
+      "name": "containsTibetan",
+      "kind": "value",
+      "module": "src/shaping/script-registry.ts",
+      "signature": "export function containsTibetan(str: string): boolean",
+      "summary": "Check whether a string contains any Tibetan characters."
+    },
+    {
+      "name": "contoursToPath",
+      "kind": "value",
+      "module": "src/core/pdf-color-glyph.ts",
+      "signature": "export function contoursToPath(contours: Contour[], m: Mat = ID): string",
+      "summary": "Convert a set of TrueType quadratic contours into PDF path operators (cubic Béziers), applying matrix `m`."
+    },
+    {
+      "name": "createEncodingContext",
+      "kind": "value",
+      "module": "src/core/encoding-context.ts",
+      "signature": "export function createEncodingContext(fontEntries: FontEntry[], pdfA: boolean = false, normalize: 'NFC' | 'NFD' | 'NFKC' | 'NFKD' | false = false): EncodingContext",
+      "summary": "Create an encoding context that encapsulates text encoding and font reference logic."
+    },
+    {
+      "name": "createModifier",
+      "kind": "value",
+      "module": "src/parser/pdf-modifier.ts",
+      "signature": "export function createModifier(reader: PdfReader): PdfModifier",
+      "summary": "Create a modifier for an existing PDF document."
+    },
+    {
+      "name": "createPDF",
+      "kind": "value",
+      "module": "src/worker/worker-api.ts",
+      "signature": "export async function createPDF( pdfParams: PdfParams, options?: { workerUrl?: string | URL; threshold?: number; timeout?: number; onProgress?: (percent: number) => void",
+      "summary": "Smart PDF generation: uses Worker for large datasets, main thread for small ones."
+    },
+    {
+      "name": "createTokenizer",
+      "kind": "value",
+      "module": "src/parser/pdf-tokenizer.ts",
+      "signature": "export function createTokenizer(buf: Uint8Array, startPos: number = 0): PdfTokenizer",
+      "summary": "Create a PDF tokenizer for the given byte buffer."
+    },
+    {
+      "name": "decodeASCII85",
+      "kind": "value",
+      "module": "src/parser/pdf-decode-filters.ts",
+      "signature": "export function decodeASCII85(data: Uint8Array): Uint8Array",
+      "summary": "Decode an ASCII85Decode stream (Adobe variant)."
+    },
+    {
+      "name": "decodeASCIIHex",
+      "kind": "value",
+      "module": "src/parser/pdf-decode-filters.ts",
+      "signature": "export function decodeASCIIHex(data: Uint8Array): Uint8Array",
+      "summary": "Decode an ASCIIHexDecode stream."
+    },
+    {
+      "name": "decodeEcPublicKey",
+      "kind": "value",
+      "module": "src/crypto/ecdsa.ts",
+      "signature": "export function decodeEcPublicKey(bytes: Uint8Array): EcPublicKey",
+      "summary": "Decode an uncompressed EC public key (65 bytes: 0x04 || x || y)."
+    },
+    {
+      "name": "decodeLZW",
+      "kind": "value",
+      "module": "src/parser/pdf-decode-filters.ts",
+      "signature": "export function decodeLZW(data: Uint8Array): Uint8Array",
+      "summary": "Decode an LZWDecode stream with variable-width codes (9–12 bits) and automatic table reset on the CLEAR code (256)."
+    },
+    {
+      "name": "decodeRunLength",
+      "kind": "value",
+      "module": "src/parser/pdf-decode-filters.ts",
+      "signature": "export function decodeRunLength(data: Uint8Array): Uint8Array",
+      "summary": "Decode a RunLengthDecode stream."
+    },
+    {
+      "name": "defaultFieldHeight",
+      "kind": "value",
+      "module": "src/core/pdf-form.ts",
+      "signature": "export function defaultFieldHeight(fieldType: FormFieldType): number",
+      "summary": "Get default widget height for a given field type."
+    },
+    {
+      "name": "derBitString",
+      "kind": "value",
+      "module": "src/crypto/asn1.ts",
+      "signature": "export function derBitString(data: Uint8Array): Uint8Array",
+      "summary": "Encode a BIT STRING (with 0 unused bits)."
+    },
+    {
+      "name": "derDecode",
+      "kind": "value",
+      "module": "src/crypto/asn1.ts",
+      "signature": "export function derDecode(buf: Uint8Array): Asn1Node",
+      "summary": "Parse a DER-encoded ASN.1 structure."
+    },
+    {
+      "name": "derGeneralizedTime",
+      "kind": "value",
+      "module": "src/crypto/asn1.ts",
+      "signature": "export function derGeneralizedTime(date: Date): Uint8Array",
+      "summary": "Encode a GeneralizedTime from a Date."
+    },
+    {
+      "name": "derInteger",
+      "kind": "value",
+      "module": "src/crypto/asn1.ts",
+      "signature": "export function derInteger(value: bigint | Uint8Array): Uint8Array",
+      "summary": "Encode an INTEGER from a BigInt or Uint8Array (big-endian)."
+    },
+    {
+      "name": "derOctetString",
+      "kind": "value",
+      "module": "src/crypto/asn1.ts",
+      "signature": "export function derOctetString(data: Uint8Array): Uint8Array",
+      "summary": "Encode an OCTET STRING."
+    },
+    {
+      "name": "derOid",
+      "kind": "value",
+      "module": "src/crypto/asn1.ts",
+      "signature": "export function derOid(oidBytes: Uint8Array): Uint8Array",
+      "summary": "Encode an OID from byte values (already encoded arc values)."
+    },
+    {
+      "name": "derSequence",
+      "kind": "value",
+      "module": "src/crypto/asn1.ts",
+      "signature": "export function derSequence(...children: Uint8Array[]): Uint8Array",
+      "summary": "Encode a SEQUENCE (0x30) from child TLVs."
+    },
+    {
+      "name": "derSetOf",
+      "kind": "value",
+      "module": "src/crypto/asn1.ts",
+      "signature": "export function derSetOf(...children: Uint8Array[]): Uint8Array",
+      "summary": "Encode a DER SET OF (0x31) from child TLVs with the canonical X.690 §11.6 ordering: the encodings are sorted as octet strings in ascending lexicographic order, and when one encoding is a prefix of another the shorter one sorts first."
+    },
+    {
+      "name": "detectCharLang",
+      "kind": "value",
+      "module": "src/shaping/script-detect.ts",
+      "signature": "export function detectCharLang(cp: number): string | null",
+      "summary": "Detect the preferred font language for a single Unicode codepoint."
+    },
+    {
+      "name": "detectFallbackLangs",
+      "kind": "value",
+      "module": "src/shaping/script-detect.ts",
+      "signature": "export function detectFallbackLangs(texts: string[], primaryLang: string): Set<string>",
+      "summary": "Detect which additional font languages are needed to render user text containing scripts foreign to the primary language."
+    },
+    {
+      "name": "detectImageFormat",
+      "kind": "value",
+      "module": "src/core/pdf-image.ts",
+      "signature": "export function detectImageFormat(bytes: Uint8Array): 'jpeg' | 'png' | null",
+      "summary": "Detect the image format from magic bytes."
+    },
+    {
+      "name": "dictGet",
+      "kind": "value",
+      "module": "src/parser/pdf-object-parser.ts",
+      "signature": "export function dictGet(dict: PdfDict, key: string): PdfValue | undefined",
+      "summary": null
+    },
+    {
+      "name": "dictGetArray",
+      "kind": "value",
+      "module": "src/parser/pdf-object-parser.ts",
+      "signature": "export function dictGetArray(dict: PdfDict, key: string): PdfArray | undefined",
+      "summary": null
+    },
+    {
+      "name": "dictGetDict",
+      "kind": "value",
+      "module": "src/parser/pdf-object-parser.ts",
+      "signature": "export function dictGetDict(dict: PdfDict, key: string): PdfDict | undefined",
+      "summary": null
+    },
+    {
+      "name": "dictGetName",
+      "kind": "value",
+      "module": "src/parser/pdf-object-parser.ts",
+      "signature": "export function dictGetName(dict: PdfDict, key: string): string | undefined",
+      "summary": null
+    },
+    {
+      "name": "dictGetNum",
+      "kind": "value",
+      "module": "src/parser/pdf-object-parser.ts",
+      "signature": "export function dictGetNum(dict: PdfDict, key: string): number | undefined",
+      "summary": null
+    },
+    {
+      "name": "dictGetRef",
+      "kind": "value",
+      "module": "src/parser/pdf-object-parser.ts",
+      "signature": "export function dictGetRef(dict: PdfDict, key: string): PdfRef | undefined",
+      "summary": null
+    },
+    {
+      "name": "downloadBlob",
+      "kind": "value",
+      "module": "src/core/pdf-stream.ts",
+      "signature": "export function downloadBlob(bytes: Uint8Array, filename: string): void",
+      "summary": "Trigger a file download in the browser via a temporary <a> element."
+    },
+    {
+      "name": "ean13CheckDigit",
+      "kind": "value",
+      "module": "src/core/pdf-barcode.ts",
+      "signature": "export function ean13CheckDigit(digits12: string): number",
+      "summary": "Calculate EAN-13 check digit."
+    },
+    {
+      "name": "ecPublicKeyFromPrivate",
+      "kind": "value",
+      "module": "src/crypto/ecdsa.ts",
+      "signature": "export function ecPublicKeyFromPrivate(privateKey: EcPrivateKey): EcPublicKey",
+      "summary": "Derive the public key from a private key."
+    },
+    {
+      "name": "ecdsaSign",
+      "kind": "value",
+      "module": "src/crypto/ecdsa.ts",
+      "signature": "export function ecdsaSign(message: Uint8Array, privateKey: EcPrivateKey): { r: bigint; s: bigint }",
+      "summary": "Sign a message with ECDSA P-256 + SHA-256, using RFC 6979 deterministic k."
+    },
+    {
+      "name": "ecdsaVerify",
+      "kind": "value",
+      "module": "src/crypto/ecdsa.ts",
+      "signature": "export function ecdsaVerify(message: Uint8Array, r: bigint, s: bigint, publicKey: EcPublicKey): boolean",
+      "summary": "Verify an ECDSA P-256 + SHA-256 signature."
+    },
+    {
+      "name": "embedValidationInfo",
+      "kind": "value",
+      "module": "src/core/pdf-dss.ts",
+      "signature": "export function embedValidationInfo(pdfBytes: Uint8Array, data: LtvData): Uint8Array",
+      "summary": "Embed pre-collected LtvData as a `/DSS` dictionary via incremental update."
+    },
+    {
+      "name": "encodeCode128",
+      "kind": "value",
+      "module": "src/core/pdf-barcode.ts",
+      "signature": "export function encodeCode128(data: string): number[]",
+      "summary": "Encode a string as Code 128 symbol values."
+    },
+    {
+      "name": "encodeEcPublicKey",
+      "kind": "value",
+      "module": "src/crypto/ecdsa.ts",
+      "signature": "export function encodeEcPublicKey(key: EcPublicKey): Uint8Array",
+      "summary": "Encode an ECDSA public key as uncompressed point (65 bytes: 0x04 || x || y)."
+    },
+    {
+      "name": "encodePDF417",
+      "kind": "value",
+      "module": "src/core/pdf-barcode.ts",
+      "signature": "export function encodePDF417(data: string, ecLevel: number = 2): { codewords: number[]; rows: number; cols: number }",
+      "summary": "Encode data as PDF417 codewords (text compaction)."
+    },
+    {
+      "name": "encodePdfTextString",
+      "kind": "value",
+      "module": "src/core/pdf-text.ts",
+      "signature": "export function encodePdfTextString(str: string): string",
+      "summary": "Encode a string for the PDF /Info dictionary (ISO 32000-1 §7.9.2)."
+    },
+    {
+      "name": "estimateChartHeight",
+      "kind": "value",
+      "module": "src/core/pdf-chart.ts",
+      "signature": "export function estimateChartHeight(block: ChartBlock): number",
+      "summary": "Total footprint of a chart block (title + plot + axis labels + legend)."
+    },
+    {
+      "name": "estimateCmsSize",
+      "kind": "value",
+      "module": "src/crypto/cms.ts",
+      "signature": "export function estimateCmsSize(certSizes: readonly number[], algorithm: SignatureAlgorithm): number",
+      "summary": "Estimate the DER-encoded size of a CMS SignedData for allocation."
+    },
+    {
+      "name": "estimateContentsSize",
+      "kind": "value",
+      "module": "src/core/pdf-signature.ts",
+      "signature": "export function estimateContentsSize( certSizes: readonly number[], algorithm: SignatureAlgorithm = 'rsa-sha256', options?: { readonly timestamp?: boolean }, ): number",
+      "summary": "Estimate the allocation size needed for /Contents placeholder."
+    },
+    {
+      "name": "extractGlyphContours",
+      "kind": "value",
+      "module": "src/fonts/glyf-outline.ts",
+      "signature": "export function extractGlyphContours(font: GlyfFont, gid: number, depth = 0): Contour[]",
+      "summary": "Extract the contours of a single glyph in font units."
+    },
+    {
+      "name": "extractPages",
+      "kind": "value",
+      "module": "src/parser/pdf-pagetree.ts",
+      "signature": "export function extractPages( src: PdfSourceInput, pageIndices: readonly number[], opts?: MergeOptions, ): Uint8Array",
+      "summary": "Extract a subset of pages from a single document into a new PDF."
+    },
+    {
+      "name": "extractText",
+      "kind": "value",
+      "module": "src/parser/pdf-text-extract.ts",
+      "signature": "export function extractText(bytes: Uint8Array, options?: ExtractTextOptions): ExtractedPageText[]",
+      "summary": "Extract Unicode text from a PDF document, page by page."
+    },
+    {
+      "name": "fillForm",
+      "kind": "value",
+      "module": "src/core/pdf-form-fill.ts",
+      "signature": "export function fillForm( pdfBytes: Uint8Array, values: Record<string, FormFillValue>, opts?: FillFormOptions, ): Uint8Array",
+      "summary": "Fill the form fields of an existing PDF and return a new PDF (incremental update — original bytes are preserved, so any existing signature stays valid for its revision)."
+    },
+    {
+      "name": "findStartxref",
+      "kind": "value",
+      "module": "src/parser/pdf-xref-parser.ts",
+      "signature": "export function findStartxref(buf: Uint8Array): number",
+      "summary": "Find the startxref offset from the end of the PDF file."
+    },
+    {
+      "name": "flattenForm",
+      "kind": "value",
+      "module": "src/core/pdf-form-fill.ts",
+      "signature": "export function flattenForm(pdfBytes: Uint8Array, opts?: FlattenFormOptions): Uint8Array",
+      "summary": "Flatten an existing PDF's form: stamp each widget's normal appearance into its page content and remove the interactive fields (`/AcroForm`, widget `/Annots`)."
+    },
+    {
+      "name": "generateDataMatrix",
+      "kind": "value",
+      "module": "src/core/pdf-barcode.ts",
+      "signature": "export function generateDataMatrix(data: string): boolean[][]",
+      "summary": "Generate a Data Matrix ECC 200 module matrix."
+    },
+    {
+      "name": "generatePDFInWorker",
+      "kind": "value",
+      "module": "src/worker/worker-api.ts",
+      "signature": "export function generatePDFInWorker( workerUrl: string | URL, pdfParams: PdfParams, options?: WorkerGenerationOptions ): Promise<Uint8Array>",
+      "summary": "Generate PDF in a Web Worker (off-main-thread)."
+    },
+    {
+      "name": "generatePDFMainThread",
+      "kind": "value",
+      "module": "src/worker/worker-api.ts",
+      "signature": "export function generatePDFMainThread(pdfParams: PdfParams, layoutOptions?: Partial<PdfLayoutOptions>): Uint8Array",
+      "summary": "Main-thread fallback: generate PDF synchronously."
+    },
+    {
+      "name": "generateQR",
+      "kind": "value",
+      "module": "src/core/pdf-barcode.ts",
+      "signature": "export function generateQR(data: string, ecLevel: QRErrorLevel = 'M'): boolean[][]",
+      "summary": "Generate a QR Code module matrix."
+    },
+    {
+      "name": "getCryptoProvider",
+      "kind": "value",
+      "module": "src/crypto/crypto-provider.ts",
+      "signature": "export function getCryptoProvider(): CryptoProvider | null",
+      "summary": "The currently-installed global CryptoProvider, or `null` if none."
+    },
+    {
+      "name": "getMaxInflateOutputSize",
+      "kind": "value",
+      "module": "src/parser/pdf-inflate.ts",
+      "signature": "export function getMaxInflateOutputSize(): number",
+      "summary": "Get the current maximum decompressed output size."
+    },
+    {
+      "name": "getRegisteredLangs",
+      "kind": "value",
+      "module": "src/fonts/font-loader.ts",
+      "signature": "export function getRegisteredLangs(): string[]",
+      "summary": "Get all registered language codes."
+    },
+    {
+      "name": "getRevocationProvider",
+      "kind": "value",
+      "module": "src/crypto/revocation-provider.ts",
+      "signature": "export function getRevocationProvider(): RevocationProvider | null",
+      "summary": "The currently-installed global RevocationProvider, or `null` if none."
+    },
+    {
+      "name": "getTimestampProvider",
+      "kind": "value",
+      "module": "src/crypto/timestamp-provider.ts",
+      "signature": "export function getTimestampProvider(): TimestampProvider | null",
+      "summary": "The currently-installed global TimestampProvider, or `null` if none."
+    },
+    {
+      "name": "getTrailerRef",
+      "kind": "value",
+      "module": "src/parser/pdf-xref-parser.ts",
+      "signature": "export function getTrailerRef(trailer: PdfDict, key: string): PdfRef | undefined",
+      "summary": null
+    },
+    {
+      "name": "getTrailerValue",
+      "kind": "value",
+      "module": "src/parser/pdf-xref-parser.ts",
+      "signature": "export function getTrailerValue(trailer: PdfDict, key: string): PdfValue | undefined",
+      "summary": null
+    },
+    {
+      "name": "hasFontLoader",
+      "kind": "value",
+      "module": "src/fonts/font-loader.ts",
+      "signature": "export function hasFontLoader(lang: string): boolean",
+      "summary": "Check if a font loader is registered for the given language."
+    },
+    {
+      "name": "helveticaBoldWidth",
+      "kind": "value",
+      "module": "src/fonts/encoding.ts",
+      "signature": "export function helveticaBoldWidth(str: string, sz: number): number",
+      "summary": "Approximate text width in points using **Helvetica-Bold** character metrics."
+    },
+    {
+      "name": "helveticaWidth",
+      "kind": "value",
+      "module": "src/fonts/encoding.ts",
+      "signature": "export function helveticaWidth(str: string, sz: number): number",
+      "summary": "Approximate text width in points using Helvetica character metrics."
+    },
+    {
+      "name": "hmacSha256",
+      "kind": "value",
+      "module": "src/crypto/sha.ts",
+      "signature": "export function hmacSha256(key: Uint8Array, message: Uint8Array): Uint8Array",
+      "summary": "HMAC-SHA256."
+    },
+    {
+      "name": "inflateSync",
+      "kind": "value",
+      "module": "src/parser/pdf-inflate.ts",
+      "signature": "export function inflateSync(data: Uint8Array): Uint8Array",
+      "summary": "Decompress zlib-format data (RFC 1950 + RFC 1951)."
+    },
+    {
+      "name": "initCrypto",
+      "kind": "value",
+      "module": "src/crypto/index.ts",
+      "signature": "export async function initCrypto(): Promise<void>",
+      "summary": "Initialize all crypto module cross-dependencies."
+    },
+    {
+      "name": "initNodeCompression",
+      "kind": "value",
+      "module": "src/core/pdf-compress.ts",
+      "signature": "export async function initNodeCompression(): Promise<void>",
+      "summary": "Initialize Node.js compression for ESM contexts."
+    },
+    {
+      "name": "initNodeDecompression_parser",
+      "kind": "value",
+      "module": "src/parser/pdf-inflate.ts",
+      "signature": null,
+      "summary": null
+    },
+    {
+      "name": "inspectDocumentLayout",
+      "kind": "value",
+      "module": "src/core/pdf-layout-inspect.ts",
+      "signature": "export function inspectDocumentLayout( params: DocumentParams, layoutOptions?: Partial<PdfLayoutOptions>, ): LayoutInspection",
+      "summary": "Inspect how DocumentParams.blocks will paginate and where each block is placed, without building a PDF."
+    },
+    {
+      "name": "isArmenianCodepoint",
+      "kind": "value",
+      "module": "src/shaping/script-registry.ts",
+      "signature": "export function isArmenianCodepoint(cp: number): boolean",
+      "summary": "Check if a codepoint falls in any Armenian Unicode block."
+    },
+    {
+      "name": "isArray",
+      "kind": "value",
+      "module": "src/parser/pdf-object-parser.ts",
+      "signature": "export function isArray(v: PdfValue | undefined): v is PdfArray",
+      "summary": null
+    },
+    {
+      "name": "isBengaliCodepoint",
+      "kind": "value",
+      "module": "src/shaping/script-registry.ts",
+      "signature": "export function isBengaliCodepoint(cp: number): boolean",
+      "summary": "Check if a codepoint falls in the Bengali Unicode block."
+    },
+    {
+      "name": "isCyrillicCodepoint",
+      "kind": "value",
+      "module": "src/shaping/script-registry.ts",
+      "signature": "export function isCyrillicCodepoint(cp: number): boolean",
+      "summary": "Check if a codepoint falls in any Cyrillic Unicode block."
+    },
+    {
+      "name": "isDevanagariCodepoint",
+      "kind": "value",
+      "module": "src/shaping/script-registry.ts",
+      "signature": "export function isDevanagariCodepoint(cp: number): boolean",
+      "summary": "Check if a codepoint falls in any Devanagari Unicode block."
+    },
+    {
+      "name": "isDict",
+      "kind": "value",
+      "module": "src/parser/pdf-object-parser.ts",
+      "signature": "export function isDict(v: PdfValue): v is PdfDict",
+      "summary": null
+    },
+    {
+      "name": "isEthiopicCodepoint",
+      "kind": "value",
+      "module": "src/shaping/script-registry.ts",
+      "signature": "export function isEthiopicCodepoint(cp: number): boolean",
+      "summary": "Check if a codepoint falls in any Ethiopic Unicode block."
+    },
+    {
+      "name": "isGeorgianCodepoint",
+      "kind": "value",
+      "module": "src/shaping/script-registry.ts",
+      "signature": "export function isGeorgianCodepoint(cp: number): boolean",
+      "summary": "Check if a codepoint falls in any Georgian Unicode block."
+    },
+    {
+      "name": "isKhmerCodepoint",
+      "kind": "value",
+      "module": "src/shaping/script-registry.ts",
+      "signature": "export function isKhmerCodepoint(cp: number): boolean",
+      "summary": "Check if a codepoint falls in any Khmer Unicode block."
+    },
+    {
+      "name": "isLinkAnnotation",
+      "kind": "value",
+      "module": "src/core/pdf-annot.ts",
+      "signature": "export function isLinkAnnotation(annot: Annotation): annot is LinkAnnotation",
+      "summary": "Check if an annotation is an external link (has `url` property)."
+    },
+    {
+      "name": "isMathCodepoint",
+      "kind": "value",
+      "module": "src/shaping/script-registry.ts",
+      "signature": "export function isMathCodepoint(cp: number): boolean",
+      "summary": "Check if a codepoint should be routed to a mathematical font (e.g."
+    },
+    {
+      "name": "isMyanmarCodepoint",
+      "kind": "value",
+      "module": "src/shaping/script-registry.ts",
+      "signature": "export function isMyanmarCodepoint(cp: number): boolean",
+      "summary": "Check if a codepoint falls in any Myanmar Unicode block."
+    },
+    {
+      "name": "isName",
+      "kind": "value",
+      "module": "src/parser/pdf-object-parser.ts",
+      "signature": "export function isName(v: PdfValue | undefined): v is PdfName",
+      "summary": null
+    },
+    {
+      "name": "isRef",
+      "kind": "value",
+      "module": "src/parser/pdf-object-parser.ts",
+      "signature": "export function isRef(v: PdfValue | undefined): v is PdfRef",
+      "summary": null
+    },
+    {
+      "name": "isSelfSigned",
+      "kind": "value",
+      "module": "src/crypto/x509.ts",
+      "signature": "export function isSelfSigned(cert: X509Certificate): boolean",
+      "summary": "Check if a certificate is self-signed."
+    },
+    {
+      "name": "isSerialRevoked",
+      "kind": "value",
+      "module": "src/crypto/crl.ts",
+      "signature": "export function isSerialRevoked(crl: ParsedCrl, serial: bigint): boolean",
+      "summary": "Check whether a serial number appears in a CRL's revokedCertificates list."
+    },
+    {
+      "name": "isSinhalaCodepoint",
+      "kind": "value",
+      "module": "src/shaping/script-registry.ts",
+      "signature": "export function isSinhalaCodepoint(cp: number): boolean",
+      "summary": "Check if a codepoint falls in the Sinhala Unicode block."
+    },
+    {
+      "name": "isStream",
+      "kind": "value",
+      "module": "src/parser/pdf-object-parser.ts",
+      "signature": "export function isStream(v: PdfValue): v is PdfStream",
+      "summary": null
+    },
+    {
+      "name": "isTamilCodepoint",
+      "kind": "value",
+      "module": "src/shaping/script-registry.ts",
+      "signature": "export function isTamilCodepoint(cp: number): boolean",
+      "summary": "Check if a codepoint falls in the Tamil Unicode block."
+    },
+    {
+      "name": "isTeluguCodepoint",
+      "kind": "value",
+      "module": "src/shaping/script-registry.ts",
+      "signature": "export function isTeluguCodepoint(cp: number): boolean",
+      "summary": "Check if a codepoint falls in the Telugu Unicode block."
+    },
+    {
+      "name": "isTibetanCodepoint",
+      "kind": "value",
+      "module": "src/shaping/script-registry.ts",
+      "signature": "export function isTibetanCodepoint(cp: number): boolean",
+      "summary": "Check if a codepoint falls in the Tibetan Unicode block."
+    },
+    {
+      "name": "isValidPdfRgb",
+      "kind": "value",
+      "module": "src/core/pdf-color.ts",
+      "signature": "export function isValidPdfRgb(str: string): boolean",
+      "summary": "Check whether a string is a valid PDF RGB operator color."
+    },
+    {
+      "name": "listSignatures",
+      "kind": "value",
+      "module": "src/core/pdf-sig-utils.ts",
+      "signature": "export function listSignatures(pdfBytes: Uint8Array): readonly PdfSignatureInfo[]",
+      "summary": "List every signature field in the document, in AcroForm order — signed signatures, document timestamps, and unsigned placeholders."
+    },
+    {
+      "name": "loadFontData",
+      "kind": "value",
+      "module": "src/fonts/font-loader.ts",
+      "signature": "export async function loadFontData(lang: string): Promise<FontData | null>",
+      "summary": "Lazy-load pre-built font data for a language."
+    },
+    {
+      "name": "mergePdfs",
+      "kind": "value",
+      "module": "src/parser/pdf-pagetree.ts",
+      "signature": "export function mergePdfs(sources: readonly PdfSourceInput[], opts?: MergeOptions): Uint8Array",
+      "summary": "Concatenate multiple PDF documents into one, preserving page order."
+    },
+    {
+      "name": "nameValue",
+      "kind": "value",
+      "module": "src/parser/pdf-object-parser.ts",
+      "signature": "export function nameValue(v: PdfValue): string | undefined",
+      "summary": "Extract the string value from a PdfName, or undefined if not a name."
+    },
+    {
+      "name": "needsUnicodeFont",
+      "kind": "value",
+      "module": "src/shaping/script-detect.ts",
+      "signature": "export function needsUnicodeFont(lang: string): boolean",
+      "summary": "Languages requiring Unicode font embedding (non-WinAnsi scripts)."
+    },
+    {
+      "name": "niceTicks",
+      "kind": "value",
+      "module": "src/core/pdf-chart.ts",
+      "signature": "export function niceTicks(min: number, max: number, target = 5): { lo: number; hi: number; step: number }",
+      "summary": "Compute rounded tick bounds/step covering [min, max] (1/2/5×10ⁿ)."
+    },
+    {
+      "name": "normalizeBidiEmbeddings",
+      "kind": "value",
+      "module": "src/shaping/bidi.ts",
+      "signature": "export function normalizeBidiEmbeddings(text: string): string",
+      "summary": "UAX #9 explicit embedding normalization (v1.2.0, refined v1.3.0)."
+    },
+    {
+      "name": "normalizeColors",
+      "kind": "value",
+      "module": "src/core/pdf-color.ts",
+      "signature": "export function normalizeColors(colors: PdfColors): PdfColors",
+      "summary": "Validate and normalize all color fields in a PdfColors object."
+    },
+    {
+      "name": "openPdf",
+      "kind": "value",
+      "module": "src/parser/pdf-reader.ts",
+      "signature": "export function openPdf(bytes: Uint8Array, options?: OpenPdfOptions): PdfReader",
+      "summary": "Open a PDF file for reading."
+    },
+    {
+      "name": "parseCertificate",
+      "kind": "value",
+      "module": "src/crypto/x509.ts",
+      "signature": "export function parseCertificate(der: Uint8Array): X509Certificate",
+      "summary": "Parse a DER-encoded X.509 certificate."
+    },
+    {
+      "name": "parseCmsSignedData",
+      "kind": "value",
+      "module": "src/crypto/cms-utils.ts",
+      "signature": "export function parseCmsSignedData(der: Uint8Array): ParsedCms",
+      "summary": "Parse a DER-encoded CMS ContentInfo containing a SignedData (RFC 5652 §5.1) into its LTV-relevant parts."
+    },
+    {
+      "name": "parseColor",
+      "kind": "value",
+      "module": "src/core/pdf-color.ts",
+      "signature": "export function parseColor(input: PdfColor): string",
+      "summary": "Parse a color input into a validated PDF RGB operator string."
+    },
+    {
+      "name": "parseColrCpal",
+      "kind": "value",
+      "module": "src/fonts/colr-parser.ts",
+      "signature": "export function parseColrCpal(bytes: Uint8Array): Record<number, ColorGlyph> | null",
+      "summary": "Parse the COLR + CPAL tables of a font into a colour-glyph map keyed by base glyph id."
+    },
+    {
+      "name": "parseCpal",
+      "kind": "value",
+      "module": "src/fonts/colr-parser.ts",
+      "signature": "export function parseCpal(bytes: Uint8Array): CpalColor[] | null",
+      "summary": "Parse the CPAL table's first palette into an array of CpalColors (sRGB + alpha, each channel 0–255), indexed by palette entry."
+    },
+    {
+      "name": "parseCrl",
+      "kind": "value",
+      "module": "src/crypto/crl.ts",
+      "signature": "export function parseCrl(der: Uint8Array): ParsedCrl",
+      "summary": "Parse a DER-encoded CertificateList (RFC 5280 §5.1): ``` CertificateList ::= SEQUENCE { tbsCertList        TBSCertList, signatureAlgorithm AlgorithmIdentifier, signatureValue     BIT STRING } TBSCertList ::= SEQUENCE { version             I"
+    },
+    {
+      "name": "parseGlyfFont",
+      "kind": "value",
+      "module": "src/fonts/glyf-outline.ts",
+      "signature": "export function parseGlyfFont(bytes: Uint8Array): GlyfFont | null",
+      "summary": "Parse the table directory, `head`, `maxp` and `loca` so that subsequent extractGlyphContours calls are O(1) lookups."
+    },
+    {
+      "name": "parseImage",
+      "kind": "value",
+      "module": "src/core/pdf-image.ts",
+      "signature": "export function parseImage(bytes: Uint8Array): ParsedImage",
+      "summary": "Parse an image from raw bytes (auto-detect JPEG or PNG)."
+    },
+    {
+      "name": "parseIndirectObject",
+      "kind": "value",
+      "module": "src/parser/pdf-object-parser.ts",
+      "signature": "export function parseIndirectObject(tok: PdfTokenizer): PdfIndirectObject | null",
+      "summary": "Parse a PDF indirect object definition: `num gen obj ..."
+    },
+    {
+      "name": "parseJPEG",
+      "kind": "value",
+      "module": "src/core/pdf-image.ts",
+      "signature": "export function parseJPEG(bytes: Uint8Array): ParsedImage",
+      "summary": "Parse a JPEG image to extract dimensions and color space."
+    },
+    {
+      "name": "parseOcspResponse",
+      "kind": "value",
+      "module": "src/crypto/ocsp.ts",
+      "signature": "export function parseOcspResponse(der: Uint8Array): OcspResponse",
+      "summary": "Parse a DER OCSPResponse (RFC 6960 §4.2.1)."
+    },
+    {
+      "name": "parsePNG",
+      "kind": "value",
+      "module": "src/core/pdf-image.ts",
+      "signature": "export function parsePNG(bytes: Uint8Array): ParsedImage",
+      "summary": "Parse a PNG image to extract dimensions, color type, and compressed image data."
+    },
+    {
+      "name": "parseRsaPrivateKey",
+      "kind": "value",
+      "module": "src/crypto/rsa.ts",
+      "signature": "export function parseRsaPrivateKey(der: Uint8Array): RsaPrivateKey",
+      "summary": "Parse an RSA private key from PKCS#8 DER bytes."
+    },
+    {
+      "name": "parseRsaPublicKey",
+      "kind": "value",
+      "module": "src/crypto/rsa.ts",
+      "signature": "export function parseRsaPublicKey(der: Uint8Array): RsaPublicKey",
+      "summary": "Parse an RSA public key from SubjectPublicKeyInfo DER bytes."
+    },
+    {
+      "name": "parseSvgPath",
+      "kind": "value",
+      "module": "src/core/pdf-svg.ts",
+      "signature": "export function parseSvgPath(d: string): SvgSegment[]",
+      "summary": "Parse SVG path `d` string into normalized absolute-coordinate segments."
+    },
+    {
+      "name": "parseTimestampResponse",
+      "kind": "value",
+      "module": "src/crypto/rfc3161.ts",
+      "signature": "export function parseTimestampResponse(der: Uint8Array): TimestampResponse",
+      "summary": "Parse a DER-encoded TimeStampResp (RFC 3161 §2.4.2): `SEQUENCE { status PKIStatusInfo, timeStampToken OPTIONAL }`."
+    },
+    {
+      "name": "parseTimestampToken",
+      "kind": "value",
+      "module": "src/crypto/rfc3161.ts",
+      "signature": "export function parseTimestampToken(tokenDer: Uint8Array): TstInfo",
+      "summary": "Parse a TimeStampToken (a CMS SignedData whose eContent is a TSTInfo, eContentType id-ct-TSTInfo 1.2.840.113549.1.9.16.1.4) into its TSTInfo fields plus the embedded TSA certificates."
+    },
+    {
+      "name": "parseValue",
+      "kind": "value",
+      "module": "src/parser/pdf-object-parser.ts",
+      "signature": "export function parseValue(tok: PdfTokenizer, depth = 0): PdfValue",
+      "summary": "Parse a single PDF value from the token stream."
+    },
+    {
+      "name": "parseXrefTable",
+      "kind": "value",
+      "module": "src/parser/pdf-xref-parser.ts",
+      "signature": "export function parseXrefTable(buf: Uint8Array): XrefTable",
+      "summary": "Parse the complete xref table including incremental updates (via /Prev chain)."
+    },
+    {
+      "name": "pdfString",
+      "kind": "value",
+      "module": "src/fonts/encoding.ts",
+      "signature": "export function pdfString(str: string): string",
+      "summary": "Create a PDF string literal: encode to WinAnsi and escape (, ), \\."
+    },
+    {
+      "name": "readFormFields",
+      "kind": "value",
+      "module": "src/core/pdf-form-fill.ts",
+      "signature": "export function readFormFields(pdfBytes: Uint8Array, opts?: { password?: string }): ParsedFormField[]",
+      "summary": "Enumerate the interactive form fields of an existing PDF."
+    },
+    {
+      "name": "registerFont",
+      "kind": "value",
+      "module": "src/fonts/font-loader.ts",
+      "signature": "export function registerFont(lang: string, loader: FontLoader): void",
+      "summary": "Register a font data loader for a language."
+    },
+    {
+      "name": "registerFonts",
+      "kind": "value",
+      "module": "src/fonts/font-loader.ts",
+      "signature": "export function registerFonts(fonts: Record<string, FontLoader>): void",
+      "summary": "Register multiple font loaders at once."
+    },
+    {
+      "name": "renderBarcode",
+      "kind": "value",
+      "module": "src/core/pdf-barcode.ts",
+      "signature": "export function renderBarcode( format: BarcodeFormat, data: string, x: number, y: number, width: number, height: number, options?: { readonly ecLevel?: QRErrorLevel; readonly pdf417ECLevel?: number }, ): string",
+      "summary": "Render a barcode as PDF path operators."
+    },
+    {
+      "name": "renderChartBlock",
+      "kind": "value",
+      "module": "src/core/pdf-chart.ts",
+      "signature": "export function renderChartBlock( block: ChartBlock, y: number, mgL: number, cw: number, enc: EncodingContext, tagCtx?: TagContext, documentChildren?: (StructElement | MCRef)[],",
+      "summary": "Render a chart block."
+    },
+    {
+      "name": "renderCode128",
+      "kind": "value",
+      "module": "src/core/pdf-barcode.ts",
+      "signature": "export function renderCode128(data: string, x: number, y: number, width: number, height: number): string",
+      "summary": "Render Code 128 barcode as PDF path operators."
+    },
+    {
+      "name": "renderColorGlyph",
+      "kind": "value",
+      "module": "src/core/pdf-color-glyph.ts",
+      "signature": "export function renderColorGlyph( glyph: ColorGlyph, outlines: OutlineProvider, unitsPerEm: number, ): ColorGlyphForm",
+      "summary": "Render a colour glyph into a ColorGlyphForm."
+    },
+    {
+      "name": "renderDataMatrix",
+      "kind": "value",
+      "module": "src/core/pdf-barcode.ts",
+      "signature": "export function renderDataMatrix(data: string, x: number, y: number, size: number): string",
+      "summary": "Render a Data Matrix barcode as PDF path operators."
+    },
+    {
+      "name": "renderEAN13",
+      "kind": "value",
+      "module": "src/core/pdf-barcode.ts",
+      "signature": "export function renderEAN13(data: string, x: number, y: number, width: number, height: number): string",
+      "summary": "Render EAN-13 barcode as PDF path operators."
+    },
+    {
+      "name": "renderPDF417",
+      "kind": "value",
+      "module": "src/core/pdf-barcode.ts",
+      "signature": "export function renderPDF417(data: string, x: number, y: number, width: number, height: number, ecLevel: number = 2): string",
+      "summary": "Render PDF417 as PDF path operators."
+    },
+    {
+      "name": "renderQR",
+      "kind": "value",
+      "module": "src/core/pdf-barcode.ts",
+      "signature": "export function renderQR(data: string, x: number, y: number, size: number, ecLevel: QRErrorLevel = 'M'): string",
+      "summary": "Render a QR Code as PDF path operators."
+    },
+    {
+      "name": "renderSvg",
+      "kind": "value",
+      "module": "src/core/pdf-svg.ts",
+      "signature": "export function renderSvg( data: string, x: number, y: number, w: number, h: number, options?: SvgRenderOptions, enc?: EncodingContext, ): string",
+      "summary": "Render SVG content as PDF path operators."
+    },
+    {
+      "name": "resetFontRegistry",
+      "kind": "value",
+      "module": "src/fonts/font-loader.ts",
+      "signature": "export function resetFontRegistry(): void",
+      "summary": "Clear all registered fonts and cache (useful for testing)."
+    },
+    {
+      "name": "resolveBidiRuns",
+      "kind": "value",
+      "module": "src/shaping/bidi.ts",
+      "signature": "export function resolveBidiRuns(text: string): BidiRun[]",
+      "summary": "Resolve bidirectional text into ordered runs with embedding levels."
+    },
+    {
+      "name": "resolveLayout",
+      "kind": "value",
+      "module": "src/core/pdf-layout.ts",
+      "signature": "export function resolveLayout(options?: Partial<PdfLayoutOptions>):",
+      "summary": "Create a resolved layout configuration from user options + defaults."
+    },
+    {
+      "name": "resolvePdfAConfig",
+      "kind": "value",
+      "module": "src/core/pdf-tags.ts",
+      "signature": "export function resolvePdfAConfig(tagged: boolean | string | undefined): PdfAConfig",
+      "summary": "Parse the `tagged` layout option into a resolved PDF/A configuration."
+    },
+    {
+      "name": "resolvePrintBoxes",
+      "kind": "value",
+      "module": "src/core/pdf-print.ts",
+      "signature": "export function resolvePrintBoxes(print: PrintOptions, pgW: number, pgH: number): ResolvedPrintBoxes",
+      "summary": "Resolve the page-dictionary fragment for the configured boxes."
+    },
+    {
+      "name": "resolveTemplate",
+      "kind": "value",
+      "module": "src/core/pdf-layout.ts",
+      "signature": "export function resolveTemplate( tpl: string | undefined, page: number, pages: number, title: string, date: string, ): string",
+      "summary": "Replace placeholder tokens in a header/footer template string."
+    },
+    {
+      "name": "rsaSign",
+      "kind": "value",
+      "module": "src/crypto/rsa.ts",
+      "signature": "export function rsaSign(message: Uint8Array, privateKey: RsaPrivateKey, digest: RsaDigest = 'sha256'): Uint8Array",
+      "summary": "Sign a message with RSA PKCS#1 v1.5."
+    },
+    {
+      "name": "rsaSignHash",
+      "kind": "value",
+      "module": "src/crypto/rsa.ts",
+      "signature": "export function rsaSignHash(hash: Uint8Array, privateKey: RsaPrivateKey, digest: RsaDigest = 'sha256'): Uint8Array",
+      "summary": "Sign a pre-computed hash with RSA PKCS#1 v1.5."
+    },
+    {
+      "name": "rsaVerify",
+      "kind": "value",
+      "module": "src/crypto/rsa.ts",
+      "signature": "export function rsaVerify(message: Uint8Array, signature: Uint8Array, publicKey: RsaPublicKey, digest: RsaDigest = 'sha256'): boolean",
+      "summary": "Verify an RSA PKCS#1 v1.5 signature over a message."
+    },
+    {
+      "name": "rsaVerifyHash",
+      "kind": "value",
+      "module": "src/crypto/rsa.ts",
+      "signature": "export function rsaVerifyHash(hash: Uint8Array, signature: Uint8Array, publicKey: RsaPublicKey, digest: RsaDigest = 'sha256'): boolean",
+      "summary": "Verify an RSA PKCS#1 v1.5 signature against a pre-computed hash."
+    },
+    {
+      "name": "setCryptoProvider",
+      "kind": "value",
+      "module": "src/crypto/crypto-provider.ts",
+      "signature": "export function setCryptoProvider(provider: CryptoProvider | null): void",
+      "summary": "Install (or clear) a global signature CryptoProvider."
+    },
+    {
+      "name": "setDeflateImpl",
+      "kind": "value",
+      "module": "src/core/pdf-compress.ts",
+      "signature": "export function setDeflateImpl(fn: ((buf: Uint8Array) => Uint8Array) | null): void",
+      "summary": "Inject a custom deflate implementation (e.g."
+    },
+    {
+      "name": "setInflateImpl",
+      "kind": "value",
+      "module": "src/parser/pdf-inflate.ts",
+      "signature": "export function setInflateImpl(fn: ((buf: Uint8Array) => Uint8Array) | null): void",
+      "summary": "Inject a custom inflate implementation."
+    },
+    {
+      "name": "setMaxInflateOutputSize",
+      "kind": "value",
+      "module": "src/parser/pdf-inflate.ts",
+      "signature": "export function setMaxInflateOutputSize(size: number): void",
+      "summary": "Set the global maximum decompressed output size for inflateSync."
+    },
+    {
+      "name": "setRevocationProvider",
+      "kind": "value",
+      "module": "src/crypto/revocation-provider.ts",
+      "signature": "export function setRevocationProvider(provider: RevocationProvider | null): void",
+      "summary": "Install (or clear) a global RevocationProvider."
+    },
+    {
+      "name": "setTimestampProvider",
+      "kind": "value",
+      "module": "src/crypto/timestamp-provider.ts",
+      "signature": "export function setTimestampProvider(provider: TimestampProvider | null): void",
+      "summary": "Install (or clear) a global TimestampProvider."
+    },
+    {
+      "name": "sha1",
+      "kind": "value",
+      "module": "src/crypto/sha.ts",
+      "signature": "export function sha1(input: Uint8Array): Uint8Array",
+      "summary": "SHA-1 hash (FIPS 180-4)."
+    },
+    {
+      "name": "sha384",
+      "kind": "value",
+      "module": "src/crypto/sha.ts",
+      "signature": "export function sha384(input: Uint8Array): Uint8Array",
+      "summary": "SHA-384 hash (FIPS 180-4)."
+    },
+    {
+      "name": "sha512",
+      "kind": "value",
+      "module": "src/crypto/sha.ts",
+      "signature": "export function sha512(input: Uint8Array): Uint8Array",
+      "summary": "SHA-512 hash (FIPS 180-4)."
+    },
+    {
+      "name": "shapeArabicText",
+      "kind": "value",
+      "module": "src/shaping/arabic-shaper.ts",
+      "signature": "export function shapeArabicText(str: string, fontData: FontData): ShapedGlyph[]",
+      "summary": "Shape Arabic text using Unicode Presentation Forms."
+    },
+    {
+      "name": "shapeBengaliText",
+      "kind": "value",
+      "module": "src/shaping/bengali-shaper.ts",
+      "signature": "export function shapeBengaliText(str: string, fontData: FontData): ShapedGlyph[]",
+      "summary": "Shape a string of Bengali text into an array of positioned glyphs."
+    },
+    {
+      "name": "shapeDevanagariText",
+      "kind": "value",
+      "module": "src/shaping/devanagari-shaper.ts",
+      "signature": "export function shapeDevanagariText(str: string, fontData: FontData): ShapedGlyph[]",
+      "summary": "Shape a string of Devanagari text into an array of positioned glyphs."
+    },
+    {
+      "name": "shapeKhmerText",
+      "kind": "value",
+      "module": "src/shaping/khmer-shaper.ts",
+      "signature": "export function shapeKhmerText(str: string, fontData: FontData): ShapedGlyph[]",
+      "summary": "Shape a string of Khmer text into an array of positioned glyphs."
+    },
+    {
+      "name": "shapeMyanmarText",
+      "kind": "value",
+      "module": "src/shaping/myanmar-shaper.ts",
+      "signature": "export function shapeMyanmarText(str: string, fontData: FontData): ShapedGlyph[]",
+      "summary": "Shape a string of Myanmar text into an array of positioned glyphs."
+    },
+    {
+      "name": "shapeSinhalaText",
+      "kind": "value",
+      "module": "src/shaping/sinhala-shaper.ts",
+      "signature": "export function shapeSinhalaText(str: string, fontData: FontData): ShapedGlyph[]",
+      "summary": "Shape a string of Sinhala text into an array of positioned glyphs."
+    },
+    {
+      "name": "shapeTamilText",
+      "kind": "value",
+      "module": "src/shaping/tamil-shaper.ts",
+      "signature": "export function shapeTamilText(str: string, fontData: FontData): ShapedGlyph[]",
+      "summary": "Shape a string of Tamil text into an array of positioned glyphs."
+    },
+    {
+      "name": "shapeTeluguText",
+      "kind": "value",
+      "module": "src/shaping/telugu-shaper.ts",
+      "signature": "export function shapeTeluguText(str: string, fontData: FontData): ShapedGlyph[]",
+      "summary": "Shape a string of Telugu text into an array of positioned glyphs."
+    },
+    {
+      "name": "shapeThaiText",
+      "kind": "value",
+      "module": "src/shaping/thai-shaper.ts",
+      "signature": "export function shapeThaiText(str: string, fontData: FontData): ShapedGlyph[]",
+      "summary": "Shape a string of Thai text into an array of positioned glyphs."
+    },
+    {
+      "name": "shapeTibetanText",
+      "kind": "value",
+      "module": "src/shaping/tibetan-shaper.ts",
+      "signature": "export function shapeTibetanText(str: string, fontData: FontData): ShapedGlyph[]",
+      "summary": "Shape a string of Tibetan text into an array of positioned glyphs."
+    },
+    {
+      "name": "signPdfBytes",
+      "kind": "value",
+      "module": "src/core/pdf-signature.ts",
+      "signature": "export function signPdfBytes(pdfBytes: Uint8Array, options: PdfSignOptions): Uint8Array",
+      "summary": "Sign a PDF that contains a signature placeholder."
+    },
+    {
+      "name": "signPdfBytesWithTimestamp",
+      "kind": "value",
+      "module": "src/core/pdf-sign-timestamp.ts",
+      "signature": "export async function signPdfBytesWithTimestamp( pdfBytes: Uint8Array, options: PdfSignTimestampOptions, ): Promise<Uint8Array>",
+      "summary": "Sign a placeholder-carrying PDF and embed an RFC 3161 signature timestamp in the CMS unsigned attributes (PAdES B-T when combined with `profile: 'pades'`)."
+    },
+    {
+      "name": "slugify",
+      "kind": "value",
+      "module": "src/core/pdf-stream.ts",
+      "signature": "export function slugify(str: string): string",
+      "summary": "Sanitize string for use in filename (filesystem-safe)."
+    },
+    {
+      "name": "splitPdf",
+      "kind": "value",
+      "module": "src/parser/pdf-pagetree.ts",
+      "signature": "export function splitPdf( src: PdfSourceInput, ranges: readonly PageRange[], opts?: MergeOptions, ): Uint8Array[]",
+      "summary": "Split a document into multiple PDFs, one per page range."
+    },
+    {
+      "name": "splitTextByFont",
+      "kind": "value",
+      "module": "src/shaping/multi-font.ts",
+      "signature": "export function splitTextByFont(str: string, fontEntries: FontEntry[]): FontRun[]",
+      "summary": "Split a string into text runs, each assigned to the font whose cmap covers it."
+    },
+    {
+      "name": "streamByteLength",
+      "kind": "value",
+      "module": "src/core/pdf-stream-writer.ts",
+      "signature": "export async function streamByteLength(stream: AsyncGenerator<Uint8Array>): Promise<number>",
+      "summary": "Count total byte length from streaming chunks without buffering."
+    },
+    {
+      "name": "streamExtractPages",
+      "kind": "value",
+      "module": "src/parser/pdf-pagetree.ts",
+      "signature": "export async function* streamExtractPages( src: PdfSourceInput, pageIndices: readonly number[], opts?: StreamMergeOptions, ): AsyncGenerator<Uint8Array>",
+      "summary": "Streaming extractPages: yields the extracted PDF as fixed-size chunks, byte-identical to `extractPages`."
+    },
+    {
+      "name": "streamMergedPdfs",
+      "kind": "value",
+      "module": "src/parser/pdf-pagetree.ts",
+      "signature": "export async function* streamMergedPdfs( sources: readonly PdfSourceInput[], opts?: StreamMergeOptions, ): AsyncGenerator<Uint8Array>",
+      "summary": "Streaming mergePdfs: yields the merged PDF as fixed-size chunks."
+    },
+    {
+      "name": "streamSplitPdf",
+      "kind": "value",
+      "module": "src/parser/pdf-pagetree.ts",
+      "signature": "export async function* streamSplitPdf( src: PdfSourceInput, ranges: readonly PageRange[], opts?: StreamMergeOptions, ): AsyncGenerator<SplitPdfStream>",
+      "summary": "Streaming splitPdf: yields one SplitPdfStream per range, in order."
+    },
+    {
+      "name": "streamToFile",
+      "kind": "value",
+      "module": "src/core/pdf-stream-writer.ts",
+      "signature": "export async function streamToFile( stream: AsyncGenerator<Uint8Array>, filePath: string, opts?: { readonly signal?: AbortSignal }, ): Promise<StreamToFileResult>",
+      "summary": "Write a streaming PDF — any of the `buildPDFStream*` / `buildDocumentPDFStream*` generators — directly to a file on disk, honouring write back-pressure so only one chunk is held at a time."
+    },
+    {
+      "name": "stripBidiControls",
+      "kind": "value",
+      "module": "src/shaping/bidi.ts",
+      "signature": "export function stripBidiControls(text: string): string",
+      "summary": "Strip invisible Unicode bidirectional formatting characters."
+    },
+    {
+      "name": "toBytes",
+      "kind": "value",
+      "module": "src/core/pdf-stream.ts",
+      "signature": "export function toBytes(str: string): Uint8Array",
+      "summary": "Convert a single-byte string to Uint8Array."
+    },
+    {
+      "name": "toWinAnsi",
+      "kind": "value",
+      "module": "src/fonts/encoding.ts",
+      "signature": "export function toWinAnsi(str: string): string",
+      "summary": "Encode a JavaScript string to WinAnsiEncoding (ISO-8859-1 superset)."
+    },
+    {
+      "name": "truncate",
+      "kind": "value",
+      "module": "src/fonts/encoding.ts",
+      "signature": "export function truncate(str: string, max: number): string",
+      "summary": "Truncate string to max characters, appending Unicode ellipsis (…, U+2026) if needed."
+    },
+    {
+      "name": "truncateToWidth",
+      "kind": "value",
+      "module": "src/fonts/encoding.ts",
+      "signature": "export function truncateToWidth( str: string, maxWidthPt: number, sz: number, enc: EncodingContext, ): string",
+      "summary": "Truncate string so that its rendered width does not exceed `maxWidthPt`, appending the Unicode ellipsis (…, U+2026) when truncation occurs."
+    },
+    {
+      "name": "validateAttachments",
+      "kind": "value",
+      "module": "src/core/pdf-tags.ts",
+      "signature": "export function validateAttachments(attachments: readonly PdfAttachment[] | undefined, tagged: boolean | string | undefined): void",
+      "summary": "Validate attachments against PDF/A configuration."
+    },
+    {
+      "name": "validateDocumentStreamable",
+      "kind": "value",
+      "module": "src/core/pdf-stream-writer.ts",
+      "signature": "export function validateDocumentStreamable(params: DocumentParams, layoutOptions?: Partial<PdfLayoutOptions>): void",
+      "summary": "Validate that document params are compatible with streaming output."
+    },
+    {
+      "name": "validateFontData",
+      "kind": "value",
+      "module": "src/fonts/font-validator.ts",
+      "signature": "export function validateFontData(data: unknown): FontValidationResult",
+      "summary": "Structurally validate a FontData module."
+    },
+    {
+      "name": "validatePdfUA",
+      "kind": "value",
+      "module": "src/parser/pdf-ua-validator.ts",
+      "signature": "export function validatePdfUA(bytes: Uint8Array): PdfUAValidationResult",
+      "summary": "Validate the PDF/UA (ISO 14289-1) structural prerequisites of a tagged PDF."
+    },
+    {
+      "name": "validatePrintOptions",
+      "kind": "value",
+      "module": "src/core/pdf-print.ts",
+      "signature": "export function validatePrintOptions( print: PrintOptions, pgW: number, pgH: number, tagged: boolean | string | undefined, ): void",
+      "summary": "Validate `layout.print` against the page geometry and conformance target."
+    },
+    {
+      "name": "validateTableStreamable",
+      "kind": "value",
+      "module": "src/core/pdf-stream-writer.ts",
+      "signature": "export function validateTableStreamable(_params: PdfParams, layoutOptions?: Partial<PdfLayoutOptions>): void",
+      "summary": "Validate that table params are compatible with streaming output."
+    },
+    {
+      "name": "validateURL",
+      "kind": "value",
+      "module": "src/core/pdf-annot.ts",
+      "signature": "export function validateURL(url: string): boolean",
+      "summary": "Validate a URL for use in PDF link annotations."
+    },
+    {
+      "name": "validateWatermark",
+      "kind": "value",
+      "module": "src/core/pdf-watermark.ts",
+      "signature": "export function validateWatermark( watermark: WatermarkOptions, pdfaLevel: boolean | string | undefined, ): void",
+      "summary": "Validate watermark options against PDF/A constraints."
+    },
+    {
+      "name": "verifyCertSignature",
+      "kind": "value",
+      "module": "src/crypto/x509.ts",
+      "signature": "export function verifyCertSignature(cert: X509Certificate, issuerCert: X509Certificate): boolean",
+      "summary": "Verify a certificate's signature using the issuer's public key."
+    },
+    {
+      "name": "verifyTimestampImprint",
+      "kind": "value",
+      "module": "src/crypto/rfc3161.ts",
+      "signature": "export function verifyTimestampImprint(info: TstInfo, expectedHash: Uint8Array): boolean",
+      "summary": "Check that a parsed timestamp token covers the expected data: byte-compare the TSTInfo messageImprint against `expectedHash`."
+    },
+    {
+      "name": "vriKeyForContents",
+      "kind": "value",
+      "module": "src/core/pdf-dss.ts",
+      "signature": "export function vriKeyForContents(contents: Uint8Array): string",
+      "summary": "Uppercase-hex SHA-1 of the full /Contents value — the /VRI key."
+    },
+    {
+      "name": "wrapText",
+      "kind": "value",
+      "module": "src/core/pdf-document.ts",
+      "signature": null,
+      "summary": null
+    }
+  ]
+}
diff --git a/docs/assets/architecture.svg b/docs/assets/architecture.svg
index 62687cb..999eca6 100644
--- a/docs/assets/architecture.svg
+++ b/docs/assets/architecture.svg
@@ -1,6 +1,6 @@
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 960 600" role="img" aria-labelledby="arch-title arch-desc" font-family="Inter,-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,'Helvetica Neue',Arial,sans-serif">
   <title id="arch-title">pdfnative — module architecture</title>
-  <desc id="arch-desc">Layered dependency diagram for pdfnative 1.7.0. Top band: three ecosystem consumers install pdfnative from npm — pdfnative-cli (command-line interface, 17 commands: render, fill, annotate, merge, split, extract, sign, verify, encrypt, decrypt, inspect, extract-text, batch, doctor, schema, completion, govern), pdfnative-mcp (Model Context Protocol server exposing 24 tools to Claude, Cursor, Zed and any stdio MCP client), and pdfnative-react (on-device JSX-to-PDF renderer). Bottom band: the zero-dependency library. Strict unidirectional flow — types feeds core; fonts imports into core; shaping imports into fonts; worker imports into shaping. Core groups pdf-builder, pdf-document, pdf-encrypt, pdf-tags plus outline, page labels, annotations and layout inspection. fonts covers encoding, subsetting, CMap and the font-data tools sub-path. Shaping covers GSUB, GPOS, BiDi and 22 Unicode scripts. crypto is a standalone module (AES, RSA, ECDSA, SHA, CMS and a pluggable native signing provider). parser is standalone, imports the compression layer, and provides page-tree manipulation: read, decrypt, extract text, modify, annotate, merge, split and re-encrypt. A header badge notes the repository's AI-agent governance with a human-in-the-loop (HITL) contribution gate. A legend explains the four edge types: imports, consumes via npm, standalone, and imports compress.</desc>
+  <desc id="arch-desc">Layered dependency diagram for pdfnative 1.7.0. Top band: three ecosystem consumers install pdfnative from npm — pdfnative-cli (command-line interface, 17 commands: render, fill, annotate, merge, split, extract, sign, verify, encrypt, decrypt, inspect, extract-text, batch, doctor, schema, completion, govern), pdfnative-mcp (Model Context Protocol server exposing 28 tools to Claude, Cursor, Zed and any MCP client), and pdfnative-react (on-device JSX-to-PDF renderer). Bottom band: the zero-dependency library. Strict unidirectional flow — types feeds core; fonts imports into core; shaping imports into fonts; worker imports into shaping. Core groups pdf-builder, pdf-document, pdf-encrypt, pdf-tags plus outline, page labels, annotations and layout inspection. fonts covers encoding, subsetting, CMap and the font-data tools sub-path. Shaping covers GSUB, GPOS, BiDi and 22 Unicode scripts. crypto is a standalone module (AES, RSA, ECDSA, SHA, CMS and a pluggable native signing provider). parser is standalone, imports the compression layer, and provides page-tree manipulation: read, decrypt, extract text, modify, annotate, merge, split and re-encrypt. A header badge notes the repository's AI-agent governance with a human-in-the-loop (HITL) contribution gate. A legend explains the four edge types: imports, consumes via npm, standalone, and imports compress.</desc>
 
   <defs>
     <!-- Directional arrowheads -->
@@ -102,7 +102,7 @@
     <path d="M379 143 l4 12 M391 143 l-4 12 M379 141 h12"/>
   </g>
   <text x="414" y="146" font-size="15.5" font-weight="700" fill="#4338CA">pdfnative-mcp</text>
-  <text x="414" y="164" font-size="11" font-weight="600" fill="#6366F1">MCP server · 24 tools</text>
+  <text x="414" y="164" font-size="11" font-weight="600" fill="#6366F1">MCP server · 28 tools</text>
   <text x="414" y="181" font-size="10" fill="#818CF8">Claude · Cursor · Zed · any client</text>
 
   <!-- pdfnative-react -->
@@ -167,7 +167,7 @@
   <!-- parser (standalone) -->
   <g filter="url(#soft-sm)"><rect x="500" y="462" width="196" height="62" rx="12" fill="url(#g-parser)" stroke="#FB923C" stroke-width="1.25"/></g>
   <text x="598" y="489" text-anchor="middle" font-size="14.5" font-weight="700" fill="#C2410C">parser</text>
-  <text x="598" y="503" text-anchor="middle" font-size="8.5" fill="#F97316">read · decrypt · extract text · modify</text>
+  <text x="598" y="503" text-anchor="middle" font-size="8.5" fill="#F97316">read · decrypt · extract text · modify</text>
   <text x="598" y="514" text-anchor="middle" font-size="8.5" fill="#F97316">merge / split · re-encrypt · stream</text>
 
   <!-- ─── Edges ─── -->
diff --git a/docs/assets/ecosystem.json b/docs/assets/ecosystem.json
index 360989b..fcbed70 100644
--- a/docs/assets/ecosystem.json
+++ b/docs/assets/ecosystem.json
@@ -1,6 +1,6 @@
 {
   "$comment": "Single source of truth for every version, count and inventory quoted anywhere in the documentation. Edit THIS file, then run `npm run verify:docs` — it reports every doc that disagrees. Never hand-edit a number in a doc without updating this manifest first.",
-  "verifiedOn": "2026-08-21",
+  "verifiedOn": "2026-08-25",
   "packages": {
     "pdfnative": {
       "version": "1.7.0",
@@ -46,17 +46,18 @@
       }
     },
     "pdfnative-mcp": {
-      "version": "1.5.0",
+      "version": "1.6.0",
       "pinField": "dependencies",
-      "pin": "^1.6.0",
+      "pin": "^1.7.0",
       "repo": "https://github.com/Nizoka/pdfnative-mcp",
-      "toolCount": 24,
+      "toolCount": 28,
       "tools": [
         "add_attachment",
         "add_barcode",
         "add_chart",
         "add_form",
         "add_international_text",
+        "add_ltv",
         "add_table",
         "annotate_pdf",
         "decrypt_pdf",
@@ -68,18 +69,25 @@
         "extract_text",
         "fill_form",
         "generate_basic_pdf",
+        "inspect_layout",
         "inspect_pdf",
         "merge_pdfs",
         "prepare_signature_placeholder",
         "read_form_fields",
         "sign_pdf",
         "split_pdf",
+        "timestamp_pdf",
+        "update_metadata",
         "validate_pdf",
         "verify_pdf"
       ],
       "prompts": [
         "governance_contract",
-        "draft_issue_workflow"
+        "draft_issue_workflow",
+        "pades_ladder",
+        "print_ready",
+        "reproducible_output",
+        "pdfa_valid"
       ]
     },
     "pdfnative-react": {
@@ -97,16 +105,17 @@
   },
   "derived": {
     "$comment": "Asserted against the filesystem by verify-docs. Never hand-edit to make a check pass — fix the docs or the tree instead.",
-    "testFiles": 122,
+    "testFiles": 123,
     "sampleGenerators": 48,
     "samplePdfs": 242,
-    "guides": 28,
-    "playgrounds": 9,
-    "learnSteps": 8
+    "guides": 30,
+    "playgrounds": 10,
+    "learnSteps": 8,
+    "recipes": 14
   },
   "declared": {
     "$comment": "Hand-maintained figures that no filesystem walk can derive. Every doc must echo these exactly.",
-    "tests": 2665,
+    "tests": 2686,
     "scripts": 22,
     "bundledFontModules": 26,
     "blockTypes": 13,
@@ -148,9 +157,9 @@
     },
     {
       "id": "mcp-tool-count",
-      "canonical": "24 tools",
+      "canonical": "28 tools",
       "match": "\\b(\\d+)\\s+(?:[A-Za-z][\\w-]*\\s+){0,2}tools\\b",
-      "expect": 24,
+      "expect": 28,
       "requireIn": [
         "docs/guides/mcp.md",
         "docs/index.html",
@@ -182,7 +191,7 @@
     {
       "id": "test-count-homepage",
       "$comment": "The homepage quoted a stale test count for a full release train; no assertion covered it. canonical-present pins the current figure where it is displayed.",
-      "canonical": "665+ tests across 122 files",
+      "canonical": "2686+ tests across 123 files",
       "requireIn": [
         "docs/index.html"
       ]
diff --git a/docs/assets/og-image.png b/docs/assets/og-image.png
index 41b6653..1c2c650 100644
Binary files a/docs/assets/og-image.png and b/docs/assets/og-image.png differ
diff --git a/docs/assets/og-image.svg b/docs/assets/og-image.svg
index e2a4194..4d040fa 100644
--- a/docs/assets/og-image.svg
+++ b/docs/assets/og-image.svg
@@ -58,7 +58,7 @@
 
   <!-- Subtitle -->
   <text x="80" y="446" font-family="'Segoe UI', -apple-system, BlinkMacSystemFont, Roboto, 'Helvetica Neue', Arial, sans-serif" font-size="27" font-weight="500" fill="#e2e8f0">Zero dependencies · ISO 32000-1 · PDF/A · TypeScript-first</text>
-  <text x="80" y="480" font-family="'Segoe UI', -apple-system, BlinkMacSystemFont, Roboto, 'Helvetica Neue', Arial, sans-serif" font-size="22" font-weight="400" fill="#94a3b8">Charts · Forms · Merge / Split · Encryption · Signatures · 22 Unicode scripts</text>
+  <text x="80" y="480" font-family="'Segoe UI', -apple-system, BlinkMacSystemFont, Roboto, 'Helvetica Neue', Arial, sans-serif" font-size="22" font-weight="400" fill="#94a3b8">Charts · Forms · Merge / Split · LTV Signatures · Print Production · 22 Unicode scripts</text>
 
   <!-- Capability pills -->
   <g font-family="'Segoe UI', -apple-system, BlinkMacSystemFont, Roboto, 'Helvetica Neue', Arial, sans-serif" font-size="22" font-weight="600">
diff --git a/docs/assets/versions.js b/docs/assets/versions.js
index fd46872..f14d64b 100644
--- a/docs/assets/versions.js
+++ b/docs/assets/versions.js
@@ -33,9 +33,9 @@
     // the whole site; these mirror the latest published releases so an offline
     // visitor still sees a sensible value. Bumped at every release.
     var FALLBACK = {
-        'pdfnative': { version: '1.6.0', pin: null, pinField: null },
+        'pdfnative': { version: '1.7.0', pin: null, pinField: null },
         'pdfnative-cli': { version: '1.3.0', pin: '^1.6.0', pinField: 'dependencies' },
-        'pdfnative-mcp': { version: '1.5.0', pin: '^1.6.0', pinField: 'dependencies' },
+        'pdfnative-mcp': { version: '1.6.0', pin: '^1.7.0', pinField: 'dependencies' },
         'pdfnative-react': { version: '1.1.0', pin: '^1.6.0', pinField: 'peerDependencies' }
     };
 
diff --git a/docs/data/errors.json b/docs/data/errors.json
new file mode 100644
index 0000000..a725d90
--- /dev/null
+++ b/docs/data/errors.json
@@ -0,0 +1,39 @@
+{
+  "$comment": "Machine-readable registry of the diagnostic codes the pdfnative ENGINE emits (src/core/pdf-diagnostics.ts). Meanings and remedies are restated from the source messages; the error-parity rule of scripts/verify-docs.ts checks that every code named in the documentation exists here and in src/, and vice versa. The CLI's E_* codes and the MCP server's tool error codes belong to their own repositories (pdfnative-cli llms.txt / schema manifest, and the MCP guide's error table, checked against the published package by the weekly --online run) and are deliberately not mirrored here.",
+  "package": "pdfnative",
+  "verifiedOn": "2026-08-25",
+  "diagnostics": [
+    {
+      "code": "PDFA_NO_FONT_ENTRIES",
+      "severity": "warning",
+      "since": "1.7.0",
+      "raisedWhen": "A document claims a PDF/A level (layout.tagged) while rendering text through the unembedded standard-14 Helvetica — no fontEntries were supplied.",
+      "standard": "ISO 19005 §6.2.11.4.1 (every font embedded; veraPDF rejects the file)",
+      "remedy": "Register an embedded Latin font (e.g. Noto Sans via registerFont('latin', …) + fontEntries) or drop the PDF/A level.",
+      "guide": "https://pdfnative.dev/guides/pdfa.md"
+    },
+    {
+      "code": "PDFA_UNEMBEDDED_FORM_FONT",
+      "severity": "warning",
+      "since": "1.7.0",
+      "raisedWhen": "An AcroForm field appears under a PDF/A claim — field appearances render through the unembedded base-14 /Helv font.",
+      "standard": "ISO 19005 §6.2.11.4.1 (veraPDF rejects the file)",
+      "remedy": "Drop the PDF/A level for form documents, or flatten the form before claiming conformance.",
+      "guide": "https://pdfnative.dev/guides/pdfa.md"
+    },
+    {
+      "code": "PDFA_DEVICE_CMYK_IMAGE",
+      "severity": "warning",
+      "since": "1.7.0",
+      "raisedWhen": "A DeviceCMYK image is embedded under a PDF/A claim whose OutputIntent is sRGB.",
+      "standard": "ISO 19005-2 §6.2.4.3 (device colour must match the output intent; veraPDF rejects the file)",
+      "remedy": "Convert the image to RGB or drop the PDF/A level.",
+      "guide": "https://pdfnative.dev/guides/pdfa.md"
+    }
+  ],
+  "sink": {
+    "default": "console.warn, deduplicated once per code per build",
+    "custom": "layout.onDiagnostic receives every diagnostic (no deduplication)",
+    "strict": "layout.strict: true throws instead (onDiagnostic is then ignored)"
+  }
+}
diff --git a/docs/data/surfaces.json b/docs/data/surfaces.json
new file mode 100644
index 0000000..7f01372
--- /dev/null
+++ b/docs/data/surfaces.json
@@ -0,0 +1,102 @@
+{
+  "$comment": "Machine-readable form of the capability × surface table in docs/guides/choose.md. Hand-maintained, verified against the sources on the date below: library `call` names against src/index.ts exports, CLI `command` names against packages.pdfnative-cli.commandGroups and MCP `tool` names against packages.pdfnative-mcp.tools in docs/assets/ecosystem.json (the single source of truth for names and counts — regenerate nothing from this file), React entries against docs/guides/react.md. Each `since` is a version of that surface's OWN package (pdfnative, pdfnative-cli, pdfnative-mcp or pdfnative-react); it is omitted where the capability predates 1.0.0 or the introducing release is not documented. `supported: false` cells carry a note naming the honest alternative where one exists.",
+  "verifiedOn": "2026-08-25",
+  "capabilities": [
+    {
+      "id": "generate",
+      "label": "Generate documents",
+      "library": { "supported": true, "call": "buildDocumentPDFBytes / buildPDFBytes" },
+      "cli": { "supported": true, "command": "render" },
+      "mcp": { "supported": true, "tool": "generate_basic_pdf", "notes": "Plus the dedicated document tools (add_table, add_barcode, add_international_text, add_form, embed_image, add_chart, prepare_signature_placeholder, add_attachment)." },
+      "react": { "supported": true, "call": "renderToBytes / renderToBlob / renderToStream / renderToFile / renderToResponse over a <Document> tree" }
+    },
+    {
+      "id": "tables",
+      "label": "Smart tables",
+      "library": { "supported": true, "call": "table block in buildDocumentPDFBytes (or the table-centric buildPDFBytes)" },
+      "cli": { "supported": true, "command": "render", "notes": "table block in the document JSON, or --variant table; smart-table flags since v1.3.0." },
+      "mcp": { "supported": true, "tool": "add_table" },
+      "react": { "supported": true, "call": "<Table> / <Row> / <Cell>" }
+    },
+    {
+      "id": "charts",
+      "label": "Native vector charts",
+      "library": { "supported": true, "call": "chart block in buildDocumentPDFBytes", "since": "1.6.0" },
+      "cli": { "supported": true, "command": "render", "since": "1.3.0", "notes": "chart blocks in the document JSON." },
+      "mcp": { "supported": true, "tool": "add_chart", "since": "1.5.0", "notes": "Also as a chart block inside generate_basic_pdf." },
+      "react": { "supported": true, "call": "<Chart>", "since": "1.1.0" }
+    },
+    {
+      "id": "sign",
+      "label": "Digital signatures (PAdES CMS)",
+      "library": { "supported": true, "call": "addSignaturePlaceholder + signPdfBytes", "since": "1.2.0" },
+      "cli": { "supported": true, "command": "sign" },
+      "mcp": { "supported": true, "tool": "sign_pdf", "notes": "prepare_signature_placeholder creates the /Sig placeholder; sign_pdf auto-injects one when absent." },
+      "react": { "supported": false, "notes": "Sign the rendered bytes with the library or the CLI." }
+    },
+    {
+      "id": "ltv",
+      "label": "LTV ladder (PAdES B-T → B-LTA)",
+      "library": { "supported": true, "call": "signPdfBytesWithTimestamp + addValidationInfo + addDocumentTimestamp", "since": "1.7.0", "notes": "Network transport is injected by the caller via setTimestampProvider / setRevocationProvider — the engine opens no socket." },
+      "cli": { "supported": false, "notes": "Verification only: verify --revocation validates RFC 3161 timestamps and OCSP/CRL material; sign-side LTV is documented as out of scope." },
+      "mcp": { "supported": true, "tool": "add_ltv + timestamp_pdf", "since": "1.6.0", "notes": "Transport is operator-configured via PDFNATIVE_MCP_TSA_URL / PDFNATIVE_MCP_REVOCATION and a host allow-list — never from tool arguments. verify_pdf with ltv: true reports the achieved level." },
+      "react": { "supported": false }
+    },
+    {
+      "id": "encrypt-decrypt",
+      "label": "Encrypt / decrypt",
+      "library": { "supported": true, "call": "encryption layout option at build time; page-tree encrypt option and openPdf with a password for existing PDFs" },
+      "cli": { "supported": true, "command": "encrypt / decrypt", "since": "1.3.0" },
+      "mcp": { "supported": true, "tool": "encrypt_pdf / decrypt_pdf", "since": "1.5.0", "notes": "Build-time encrypt on the document tools (since 1.6.0) keeps the AcroForm; encrypt_pdf rebuilds the page tree and drops signatures and /AcroForm." },
+      "react": { "supported": true, "call": "layout render option (build-time encryption only)", "notes": "No decryption of existing PDFs." }
+    },
+    {
+      "id": "fill-forms",
+      "label": "Fill / flatten forms",
+      "library": { "supported": true, "call": "readFormFields + fillForm + flattenForm", "since": "1.6.0" },
+      "cli": { "supported": true, "command": "fill", "since": "1.3.0" },
+      "mcp": { "supported": true, "tool": "read_form_fields + fill_form", "since": "1.5.0" },
+      "react": { "supported": false, "notes": "<FormField> creates form widgets in new documents; filling existing AcroForms is a library / CLI / MCP capability." }
+    },
+    {
+      "id": "extract-text",
+      "label": "Extract text",
+      "library": { "supported": true, "call": "extractText", "since": "1.6.0" },
+      "cli": { "supported": true, "command": "extract-text", "since": "1.3.0" },
+      "mcp": { "supported": true, "tool": "extract_text" },
+      "react": { "supported": false }
+    },
+    {
+      "id": "merge-split",
+      "label": "Merge / split / extract pages",
+      "library": { "supported": true, "call": "mergePdfs + splitPdf + extractPages", "since": "1.4.0" },
+      "cli": { "supported": true, "command": "merge / split / extract", "since": "1.2.0" },
+      "mcp": { "supported": true, "tool": "merge_pdfs / split_pdf / extract_pages", "since": "1.3.0" },
+      "react": { "supported": false }
+    },
+    {
+      "id": "annotate",
+      "label": "Markup annotations",
+      "library": { "supported": true, "call": "buildAnnotation + PdfModifier.addAnnotation", "since": "1.5.0" },
+      "cli": { "supported": true, "command": "annotate", "since": "1.2.0" },
+      "mcp": { "supported": true, "tool": "annotate_pdf", "since": "1.4.0" },
+      "react": { "supported": false }
+    },
+    {
+      "id": "inspect-layout",
+      "label": "Inspect layout (pagination dry run)",
+      "library": { "supported": true, "call": "inspectDocumentLayout", "since": "1.5.0" },
+      "cli": { "supported": true, "command": "render", "since": "1.2.0", "notes": "render --inspect-layout emits the LayoutInspection report instead of a PDF." },
+      "mcp": { "supported": true, "tool": "inspect_layout", "since": "1.6.0" },
+      "react": { "supported": true, "call": "inspectDocument" }
+    },
+    {
+      "id": "validate-pdfua",
+      "label": "Validate PDF/UA",
+      "library": { "supported": true, "call": "validatePdfUA", "since": "1.3.0" },
+      "cli": { "supported": true, "command": "inspect", "since": "1.1.0", "notes": "inspect --pdfua, and --check pdfua as a CI assertion." },
+      "mcp": { "supported": true, "tool": "validate_pdf", "since": "1.1.0" },
+      "react": { "supported": false, "notes": "lintDocument checks the authoring model before rendering; it is not a validation of the emitted PDF." }
+    }
+  ]
+}
diff --git a/docs/guides/accessibility.html b/docs/guides/accessibility.html
index ee7b799..225cb55 100644
--- a/docs/guides/accessibility.html
+++ b/docs/guides/accessibility.html
@@ -9,6 +9,7 @@
   <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/accessibility.html">
   <link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/accessibility.html">
   <link rel="alternate" type="text/markdown" href="accessibility.md">
+  <link rel="alternate" type="text/plain" href="../llms.txt" title="llms.txt — machine-readable documentation index">
   <meta property="og:type" content="article">
   <meta property="og:site_name" content="pdfnative">
   <meta property="og:locale" content="en_US">
@@ -26,6 +27,9 @@
   <link rel="stylesheet" href="../style.css">
   <link rel="stylesheet" href="guide.css">
   <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
+  <!-- guide:ld:start -->
+  <script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://pdfnative.dev/"},{"@type":"ListItem","position":2,"name":"Guides","item":"https://pdfnative.dev/guides/"},{"@type":"ListItem","position":3,"name":"Accessibility","item":"https://pdfnative.dev/guides/accessibility.html"}]},{"@type":"TechArticle","headline":"Accessibility","description":"Build tagged, accessible PDFs with pdfnative — PDF/UA (ISO 14289-1) structure tree, PDF/A Unicode mapping, and screen-reader-friendly reading order out of the box.","inLanguage":"en","author":{"@type":"Organization","name":"Nizoka","url":"https://github.com/Nizoka"},"publisher":{"@type":"Organization","name":"pdfnative","url":"https://pdfnative.dev","logo":{"@type":"ImageObject","url":"https://pdfnative.dev/assets/logo.svg"}},"mainEntityOfPage":{"@type":"WebPage","@id":"https://pdfnative.dev/guides/accessibility.html"},"isPartOf":{"@type":"WebSite","name":"pdfnative","url":"https://pdfnative.dev"}}]}</script>
+  <!-- guide:ld:end -->
 </head>
 <body>
 
@@ -57,9 +61,174 @@
 
 <main class="guide-shell" id="main-content" tabindex="-1">
   <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; Accessibility</p>
-  <article id="guide-content" class="guide-content" data-md="accessibility.md">
-    <p class="guide-loading">Loading…</p>
-    <noscript><p>This guide is written in Markdown: <a href="accessibility.md">read accessibility.md</a>.</p></noscript>
+  <article id="guide-content" class="guide-content" data-md="accessibility.md" data-prerendered="true">
+<!-- guide:render:start -->
+<h1 id="accessibility">Accessibility</h1>
+<blockquote>
+<p><strong>Tagged PDF, PDF/UA and screen-reader-friendly output.</strong> Pass <code>layout: { tagged: true }</code> (or a PDF/A level) and pdfnative emits the structure tree, <code>/ActualText</code> and metadata that assistive technology needs — then check the result with the read-only <code>validatePdfUA()</code>.</p>
+</blockquote>
+<p>pdfnative produces <strong>tagged, accessible PDFs</strong> out of the box. This guide covers PDF/UA, PDF/A, the structure tree, and best practices for screen-reader-friendly output.</p>
+<h2 id="why-tagged-pdf-matters">Why tagged PDF matters<a class="heading-anchor" href="#why-tagged-pdf-matters" aria-label="Link to this section">#</a></h2>
+<p>A tagged PDF carries a parallel <strong>structure tree</strong> alongside the visual content. Assistive technologies (screen readers, refreshable braille displays, reflow tools) walk the structure tree to present the document in reading order — without it, they fall back to heuristic guessing of what&#39;s a heading, a paragraph, or a table cell.</p>
+<p>pdfnative&#39;s tagged mode targets two related standards:</p>
+<ul>
+<li><strong>PDF/UA</strong> (ISO 14289-1) — accessibility conformance, structure tree required.</li>
+<li><strong>PDF/A</strong> (ISO 19005) — long-term archival, with PDF/A-2u additionally requiring Unicode mapping for every glyph.</li>
+</ul>
+<h2 id="enabling-tagged-mode">Enabling tagged mode<a class="heading-anchor" href="#enabling-tagged-mode" aria-label="Link to this section">#</a></h2>
+<pre><code class="language-typescript">const pdf = buildDocumentPDFBytes(params, { tagged: true });
+</code></pre>
+<p><code>tagged: true</code> is shorthand for <code>tagged: &#39;pdfa2b&#39;</code> — the modern default.</p>
+<table>
+<thead>
+<tr>
+<th>Option</th>
+<th>PDF version</th>
+<th>Standard</th>
+<th>Use case</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>tagged: false</code> (default)</td>
+<td>1.4</td>
+<td>ISO 32000-1</td>
+<td>Simple PDFs, no accessibility guarantees</td>
+</tr>
+<tr>
+<td><code>tagged: true</code></td>
+<td>1.7</td>
+<td>PDF/A-2b</td>
+<td><strong>Recommended</strong> — accessible + archival</td>
+</tr>
+<tr>
+<td><code>tagged: &#39;pdfa1b&#39;</code></td>
+<td>1.4</td>
+<td>PDF/A-1b</td>
+<td>Legacy archives requiring PDF 1.4</td>
+</tr>
+<tr>
+<td><code>tagged: &#39;pdfa2u&#39;</code></td>
+<td>1.7</td>
+<td>PDF/A-2u</td>
+<td>Archive with mandatory text extraction</td>
+</tr>
+<tr>
+<td><code>tagged: &#39;pdfa3b&#39;</code></td>
+<td>1.7</td>
+<td>PDF/A-3b</td>
+<td>PDF/A-2b + embedded files (e.g. ZUGFeRD invoices)</td>
+</tr>
+</tbody></table>
+<h2 id="what-pdfnative-emits">What pdfnative emits<a class="heading-anchor" href="#what-pdfnative-emits" aria-label="Link to this section">#</a></h2>
+<p>When <code>tagged</code> is enabled, the document gets:</p>
+<ul>
+<li><strong>Structure tree</strong> (<code>/StructTreeRoot</code>) with semantic roles:<ul>
+<li><code>/Document</code> (root)</li>
+<li><code>/H1</code>, <code>/H2</code>, <code>/H3</code> for headings</li>
+<li><code>/P</code> for paragraphs</li>
+<li><code>/L</code> → <code>/LI</code> for lists</li>
+<li><code>/Table</code> → <code>/TR</code> → <code>/TH</code> / <code>/TD</code> for tables</li>
+<li><code>/Figure</code> for images, barcodes, SVG (with <code>/Alt</code> text)</li>
+<li><code>/Link</code> for hyperlinks (with <code>/Contents</code> description)</li>
+<li><code>/Form</code> for AcroForm fields</li>
+<li><code>/TOC</code> → <code>/TOCI</code> for tables of contents</li>
+</ul>
+</li>
+<li><strong>Marked content</strong> (<code>/Span &lt;&lt; /MCID n /ActualText &lt;hex&gt; &gt;&gt; BDC</code>) wrapping every text run, so screen readers receive the original Unicode even when the visible glyph is a shaped Arabic ligature or Devanagari conjunct.</li>
+<li><strong>Per-page parent trees</strong> (<code>/StructParents</code> + <code>/ParentTree</code>) — required by ISO 14289-1 §7.10.3.</li>
+<li><strong>Document metadata</strong> in XMP (PDF/A-required).</li>
+<li><strong>sRGB ICC OutputIntent</strong> so colors remain stable across viewers.</li>
+</ul>
+<h2 id="block-level-accessibility-hints">Block-level accessibility hints<a class="heading-anchor" href="#block-level-accessibility-hints" aria-label="Link to this section">#</a></h2>
+<h3 id="images-and-svg--require-alt">Images and SVG → require <code>alt</code><a class="heading-anchor" href="#images-and-svg--require-alt" aria-label="Link to this section">#</a></h3>
+<pre><code class="language-typescript">{ type: &#39;image&#39;,  data: pngBytes, width: 300, alt: &#39;Q1 revenue chart, $1.2M peak in March&#39; }
+{ type: &#39;svg&#39;,    data: logoSvg, width: 200, alt: &#39;Company logo&#39; }   // note: property is `data`
+</code></pre>
+<p>Only <code>image</code> and <code>svg</code> blocks accept an <code>alt</code> property (and <code>chart</code> accepts <code>altText</code>, auto-generated when omitted); a <code>barcode</code> block has <strong>no</strong> <code>alt</code> field — its accessible description cannot currently be customised. Every <code>/Figure</code> in the structure tree gets an <code>/Alt</code> entry from the <code>alt</code> property. <strong>Always provide alt text</strong> for non-decorative images — empty strings are treated as decorative and may be skipped by screen readers.</p>
+<h3 id="links--meaningful-link-text">Links → meaningful link text<a class="heading-anchor" href="#links--meaningful-link-text" aria-label="Link to this section">#</a></h3>
+<pre><code class="language-typescript">{ type: &#39;link&#39;, text: &#39;Read the API reference&#39;, url: &#39;https://github.com/Nizoka/pdfnative#api&#39; }
+</code></pre>
+<p>Avoid <code>text: &#39;click here&#39;</code> — screen reader users who navigate by link list lose context.</p>
+<h3 id="tables--header-rows-are-detected-automatically">Tables → header rows are detected automatically<a class="heading-anchor" href="#tables--header-rows-are-detected-automatically" aria-label="Link to this section">#</a></h3>
+<p>When you pass a <code>headers</code> array, those cells are tagged <code>/TH</code> and the data rows are tagged <code>/TD</code>. For complex tables with span-cells or merged headers, pdfnative currently emits flat <code>/Table → /TR → /TH|TD</code> — explicit cell scopes (<code>/Scope = Row|Column</code>) are not yet exposed.</p>
+<h3 id="forms--label-every-field">Forms → label every field<a class="heading-anchor" href="#forms--label-every-field" aria-label="Link to this section">#</a></h3>
+<pre><code class="language-typescript">{ type: &#39;formField&#39;, fieldType: &#39;text&#39;, name: &#39;email&#39;, label: &#39;Email address&#39;, width: 400 }
+</code></pre>
+<p>The <code>label</code> is drawn as a visible text label next to the widget. pdfnative does not emit a <code>/TU</code> (tooltip) entry, so the visible label is the field&#39;s only accessible name — keep it present and descriptive.</p>
+<h2 id="verifying-conformance">Verifying conformance<a class="heading-anchor" href="#verifying-conformance" aria-label="Link to this section">#</a></h2>
+<h3 id="verapdf-pdfa">veraPDF (PDF/A)<a class="heading-anchor" href="#verapdf-pdfa" aria-label="Link to this section">#</a></h3>
+<pre><code class="language-bash"># veraPDF is a Java application, not an npm package — install it from
+# https://verapdf.org/software/ (installer) or run it via Docker:
+docker run --rm -v &quot;$PWD:/data&quot; verapdf/cli --format text /data/my-document.pdf
+</code></pre>
+<p>veraPDF is the reference PDF/A validator. The pdfnative test suite generates 242 sample PDFs and the PDF/A samples are validated against veraPDF on every release.</p>
+<h3 id="pac-2024-pdfua">PAC 2024 (PDF/UA)<a class="heading-anchor" href="#pac-2024-pdfua" aria-label="Link to this section">#</a></h3>
+<p><a href="https://pac.pdf-accessibility.org/" target="_blank" rel="noopener">PAC</a> (PDF Accessibility Checker) is a free Windows tool that walks the structure tree and reports PDF/UA issues. Run it on samples in <code>test-output/tagged/</code>.</p>
+<h3 id="screen-reader-spot-check">Screen reader spot-check<a class="heading-anchor" href="#screen-reader-spot-check" aria-label="Link to this section">#</a></h3>
+<p>For a real-world test, open your PDF with <strong>NVDA</strong> (Windows, free), <strong>VoiceOver</strong> (macOS, built in), or <strong>TalkBack</strong> (Android). Listen to the reading order — it should match the visual order.</p>
+<h2 id="limitations-and-known-caveats">Limitations and known caveats<a class="heading-anchor" href="#limitations-and-known-caveats" aria-label="Link to this section">#</a></h2>
+<table>
+<thead>
+<tr>
+<th>Area</th>
+<th>Status</th>
+</tr>
+</thead>
+<tbody><tr>
+<td>Heading roles <code>/H1</code>–<code>/H3</code></td>
+<td>Supported</td>
+</tr>
+<tr>
+<td><code>/H4</code>–<code>/H6</code></td>
+<td>Mapped to <code>/H3</code> (PDF/UA permits this)</td>
+</tr>
+<tr>
+<td>Cell scope <code>/Scope</code></td>
+<td>Not yet exposed — flat table tags</td>
+</tr>
+<tr>
+<td>Reading order overrides</td>
+<td>Implicit (block insertion order) — no explicit <code>/Order</code> array</td>
+</tr>
+<tr>
+<td>Language tags per text run</td>
+<td>Document-level only (<code>/Lang</code> in catalog)</td>
+</tr>
+<tr>
+<td>Artifact tagging (decorative content)</td>
+<td>Not yet exposed — header/footer/watermark are tagged as content</td>
+</tr>
+</tbody></table>
+<p>Contributions to address these are welcome — see the <a href="https://github.com/Nizoka/pdfnative/blob/main/ROADMAP.md" target="_blank" rel="noopener">Roadmap</a>.</p>
+<blockquote>
+<p><strong>PDF/A declaration guards</strong> <em>(v1.7.0)</em>. Tagged documents that also claim
+PDF/A are now checked at build time: configurations that would break the
+declared level (base-14 text without embedded fonts, form fields under a
+claim, DeviceCMYK images against the sRGB OutputIntent) surface a diagnostic
+— <code>console.warn</code> by default, a custom <code>onDiagnostic</code> sink, or a thrown error
+under <code>strict: true</code>. Base-14 dictionaries under tagged mode also gain full
+<code>/ToUnicode</code> coverage, which changes output bytes versus 1.6.0. Details in
+the <a href="pdfa.html">PDF/A guide</a>.</p>
+</blockquote>
+<h2 id="testing-your-pdfs-are-accessible">Testing your PDFs are accessible<a class="heading-anchor" href="#testing-your-pdfs-are-accessible" aria-label="Link to this section">#</a></h2>
+<p>A pragmatic checklist for solo developers:</p>
+<ul>
+<li><input disabled="" type="checkbox"> <code>tagged: true</code> is set on every user-facing PDF.</li>
+<li><input disabled="" type="checkbox"> Every <code>image</code> / <code>svg</code> / <code>barcode</code> block has a meaningful <code>alt</code>.</li>
+<li><input disabled="" type="checkbox"> Every <code>link</code> has descriptive text (no &quot;click here&quot;).</li>
+<li><input disabled="" type="checkbox"> Every <code>formField</code> has a <code>label</code>.</li>
+<li><input disabled="" type="checkbox"> Sample passes veraPDF for the chosen PDF/A variant.</li>
+<li><input disabled="" type="checkbox"> Sample reads in the correct order in NVDA/VoiceOver.</li>
+<li><input disabled="" type="checkbox"> If the document is multi-language, the dominant language is set in the document title.</li>
+</ul>
+<h2 id="further-reading">Further reading<a class="heading-anchor" href="#further-reading" aria-label="Link to this section">#</a></h2>
+<ul>
+<li><a href="https://www.iso.org/standard/64599.html" target="_blank" rel="noopener">ISO 14289-1 (PDF/UA-1)</a> — full PDF/UA specification.</li>
+<li><a href="https://www.pdfa.org/resource/the-matterhorn-protocol/" target="_blank" rel="noopener">Matterhorn Protocol 1.1</a> — ~136 verifiable PDF/UA failure conditions.</li>
+<li><a href="https://docs.verapdf.org/" target="_blank" rel="noopener">veraPDF documentation</a> — running validation in CI.</li>
+<li><a href="https://webaim.org/techniques/acrobat/" target="_blank" rel="noopener">WebAIM PDF accessibility</a> — accessibility primer.</li>
+</ul>
+<!-- guide:render:end -->
   </article>
 </main>
 
diff --git a/docs/guides/accessibility.md b/docs/guides/accessibility.md
index 6de79fd..c3b43a0 100644
--- a/docs/guides/accessibility.md
+++ b/docs/guides/accessibility.md
@@ -1,5 +1,7 @@
 # Accessibility
 
+> **Tagged PDF, PDF/UA and screen-reader-friendly output.** Pass `layout: { tagged: true }` (or a PDF/A level) and pdfnative emits the structure tree, `/ActualText` and metadata that assistive technology needs — then check the result with the read-only `validatePdfUA()`.
+
 pdfnative produces **tagged, accessible PDFs** out of the box. This guide covers PDF/UA, PDF/A, the structure tree, and best practices for screen-reader-friendly output.
 
 ## Why tagged PDF matters
@@ -110,6 +112,15 @@ For a real-world test, open your PDF with **NVDA** (Windows, free), **VoiceOver*
 
 Contributions to address these are welcome — see the [Roadmap](https://github.com/Nizoka/pdfnative/blob/main/ROADMAP.md).
 
+> **PDF/A declaration guards** _(v1.7.0)_. Tagged documents that also claim
+> PDF/A are now checked at build time: configurations that would break the
+> declared level (base-14 text without embedded fonts, form fields under a
+> claim, DeviceCMYK images against the sRGB OutputIntent) surface a diagnostic
+> — `console.warn` by default, a custom `onDiagnostic` sink, or a thrown error
+> under `strict: true`. Base-14 dictionaries under tagged mode also gain full
+> `/ToUnicode` coverage, which changes output bytes versus 1.6.0. Details in
+> the [PDF/A guide](pdfa.html).
+
 ## Testing your PDFs are accessible
 
 A pragmatic checklist for solo developers:
diff --git a/docs/guides/agentic-workflows.html b/docs/guides/agentic-workflows.html
index 0417724..bc7c23f 100644
--- a/docs/guides/agentic-workflows.html
+++ b/docs/guides/agentic-workflows.html
@@ -1,86 +1,261 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>Agentic workflows — pdfnative</title>
-  <meta name="description" content="How AI agents compose with pdfnative: extend the engine at runtime by registering fonts without a release (registerFont + parseFontData/compileFontData), and embed agent-generated images via the image block and the embed_image MCP tool.">
-  <link rel="canonical" href="https://pdfnative.dev/guides/agentic-workflows.html">
-  <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/agentic-workflows.html">
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Agentic workflows — pdfnative</title>
+  <meta name="description" content="How AI agents compose with pdfnative: extend the engine at runtime by registering fonts without a release (registerFont + parseFontData/compileFontData), and embed agent-generated images via the image block and the embed_image MCP tool.">
+  <link rel="canonical" href="https://pdfnative.dev/guides/agentic-workflows.html">
+  <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/agentic-workflows.html">
   <link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/agentic-workflows.html">
-  <link rel="alternate" type="text/markdown" href="agentic-workflows.md">
-  <meta property="og:type" content="article">
-  <meta property="og:site_name" content="pdfnative">
+  <link rel="alternate" type="text/markdown" href="agentic-workflows.md">
+  <link rel="alternate" type="text/plain" href="../llms.txt" title="llms.txt — machine-readable documentation index">
+  <meta property="og:type" content="article">
+  <meta property="og:site_name" content="pdfnative">
   <meta property="og:locale" content="en_US">
-  <meta property="og:url" content="https://pdfnative.dev/guides/agentic-workflows.html">
-  <meta property="og:title" content="Agentic workflows — pdfnative">
-  <meta property="og:description" content="Agents extend pdfnative at runtime — register fonts without a release, and pipe agent-generated images straight into the PDF. Built on public, validated APIs; the engine stays zero-dependency.">
-  <meta property="og:image" content="https://pdfnative.dev/assets/og-image.png">
-  <meta property="og:image:width" content="1200">
-  <meta property="og:image:height" content="630">
-  <meta name="twitter:card" content="summary_large_image">
-  <meta name="twitter:title" content="Agentic workflows — pdfnative">
-  <meta name="twitter:description" content="Runtime font extension + agent-generated images. Two factual patterns for driving pdfnative from AI agents, under a human-in-the-loop contract.">
-  <meta name="twitter:image" content="https://pdfnative.dev/assets/og-image.png">
-  <link rel="icon" type="image/svg+xml" href="../favicon.svg">
-  <link rel="stylesheet" href="../style.css">
-  <link rel="stylesheet" href="guide.css">
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
-</head>
-<body>
-
-<a class="skip-link" href="#main-content">Skip to main content</a>
-
-<nav class="nav" role="navigation" aria-label="Main navigation">
-  <div class="nav-inner">
-    <a class="nav-brand" href="../">
-      <img src="../assets/logo.svg" alt="" width="28" height="28">
-      pdfnative
-    </a>
-    <button class="nav-hamburger" aria-label="Toggle menu" aria-expanded="false">☰</button>
-    <ul class="nav-links" role="list">
-      <li><a href="../#features">Features</a></li>
-      <li><a href="../#examples">Examples</a></li>
-      <li><a href="../#demo">Demo</a></li>
-      <li><a href="../#mcp">MCP</a></li>
-      <li><a href="../#cli">CLI</a></li>
-      <li><a href="../#react">React</a></li>
-      <li><a href="../learn/">Learn</a></li>
-      <li><a href="./">Guides</a></li>
-      <li><a href="../playgrounds/">Playgrounds</a></li>
-      <li><a href="../responsibility.html">Responsibility</a></li>
-      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
-      <li><button class="theme-toggle" aria-label="Toggle dark mode">🌙</button></li>
-    </ul>
-  </div>
-</nav>
-
-<main class="guide-shell" id="main-content" tabindex="-1">
-  <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; Agentic workflows</p>
-  <article id="guide-content" class="guide-content" data-md="agentic-workflows.md">
-    <p class="guide-loading">Loading…</p>
-    <noscript><p>This guide is written in Markdown: <a href="agentic-workflows.md">read agentic-workflows.md</a>.</p></noscript>
-  </article>
-</main>
-
-<footer class="footer">
-  <div class="footer-inner">
-    <span>MIT License · © 2026 Nizoka</span>
-    <ul class="footer-links" role="list">
-      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
-      <li><a href="https://www.npmjs.com/package/pdfnative" target="_blank" rel="noopener">npm</a></li>
-      <li><a href="https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md" target="_blank" rel="noopener">Changelog</a></li>
-      <li><a href="./">All guides</a></li>
-    </ul>
-  </div>
-</footer>
-
-<script src="https://cdn.jsdelivr.net/npm/marked@12.0.2/marked.min.js" integrity="sha384-/TQbtLCAerC3jgaim+N78RZSDYV7ryeoBCVqTuzRrFec2akfBkHS7ACQ3PQhvMVi" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/dompurify@3.1.5/dist/purify.min.js" integrity="sha384-nszIONF2FGC59kn+pPFaRa6WUNGwsZgXZiJxJwQbym+TzcH7smolUviLgpPbNx7V" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/prism.min.js" integrity="sha384-BGaNxfftg+9+TtC098wxawPFVEUpKYvaiCgbB0iqAMjK/4jDdmUY+oGxrPNvnXEf" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-typescript.min.js" integrity="sha384-PeOqKNW/piETaCg8rqKFy+Pm6KEk7e36/5YZE5XO/OaFdO+/Aw3O8qZ9qDPKVUgx" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-bash.min.js" integrity="sha384-9WmlN8ABpoFSSHvBGGjhvB3E/D8UkNB9HpLJjBQFC2VSQsM1odiQDv4NbEo+7l15" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-json.min.js" integrity="sha384-RhrmFFMb0ZCHImjFMpR/UE3VEtIVTCtNrtKQqXCzqXZNJala02N3UbVhi+qzw3CY" crossorigin="anonymous" defer></script>
-<script src="guide.js" defer></script>
-</body>
-</html>
+  <meta property="og:url" content="https://pdfnative.dev/guides/agentic-workflows.html">
+  <meta property="og:title" content="Agentic workflows — pdfnative">
+  <meta property="og:description" content="Agents extend pdfnative at runtime — register fonts without a release, and pipe agent-generated images straight into the PDF. Built on public, validated APIs; the engine stays zero-dependency.">
+  <meta property="og:image" content="https://pdfnative.dev/assets/og-image.png">
+  <meta property="og:image:width" content="1200">
+  <meta property="og:image:height" content="630">
+  <meta name="twitter:card" content="summary_large_image">
+  <meta name="twitter:title" content="Agentic workflows — pdfnative">
+  <meta name="twitter:description" content="Runtime font extension + agent-generated images. Two factual patterns for driving pdfnative from AI agents, under a human-in-the-loop contract.">
+  <meta name="twitter:image" content="https://pdfnative.dev/assets/og-image.png">
+  <link rel="icon" type="image/svg+xml" href="../favicon.svg">
+  <link rel="stylesheet" href="../style.css">
+  <link rel="stylesheet" href="guide.css">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
+  <!-- guide:ld:start -->
+  <script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://pdfnative.dev/"},{"@type":"ListItem","position":2,"name":"Guides","item":"https://pdfnative.dev/guides/"},{"@type":"ListItem","position":3,"name":"Agentic workflows","item":"https://pdfnative.dev/guides/agentic-workflows.html"}]},{"@type":"TechArticle","headline":"Agentic workflows","description":"How AI agents compose with pdfnative: extend the engine at runtime by registering fonts without a release (registerFont + parseFontData/compileFontData), and embed agent-generated images via the image block and the embed_image MCP tool.","inLanguage":"en","author":{"@type":"Organization","name":"Nizoka","url":"https://github.com/Nizoka"},"publisher":{"@type":"Organization","name":"pdfnative","url":"https://pdfnative.dev","logo":{"@type":"ImageObject","url":"https://pdfnative.dev/assets/logo.svg"}},"mainEntityOfPage":{"@type":"WebPage","@id":"https://pdfnative.dev/guides/agentic-workflows.html"},"isPartOf":{"@type":"WebSite","name":"pdfnative","url":"https://pdfnative.dev"}}]}</script>
+  <!-- guide:ld:end -->
+</head>
+<body>
+
+<a class="skip-link" href="#main-content">Skip to main content</a>
+
+<nav class="nav" role="navigation" aria-label="Main navigation">
+  <div class="nav-inner">
+    <a class="nav-brand" href="../">
+      <img src="../assets/logo.svg" alt="" width="28" height="28">
+      pdfnative
+    </a>
+    <button class="nav-hamburger" aria-label="Toggle menu" aria-expanded="false">☰</button>
+    <ul class="nav-links" role="list">
+      <li><a href="../#features">Features</a></li>
+      <li><a href="../#examples">Examples</a></li>
+      <li><a href="../#demo">Demo</a></li>
+      <li><a href="../#mcp">MCP</a></li>
+      <li><a href="../#cli">CLI</a></li>
+      <li><a href="../#react">React</a></li>
+      <li><a href="../learn/">Learn</a></li>
+      <li><a href="./">Guides</a></li>
+      <li><a href="../playgrounds/">Playgrounds</a></li>
+      <li><a href="../responsibility.html">Responsibility</a></li>
+      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
+      <li><button class="theme-toggle" aria-label="Toggle dark mode">🌙</button></li>
+    </ul>
+  </div>
+</nav>
+
+<main class="guide-shell" id="main-content" tabindex="-1">
+  <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; Agentic workflows</p>
+  <article id="guide-content" class="guide-content" data-md="agentic-workflows.md" data-prerendered="true">
+<!-- guide:render:start -->
+<h1 id="agentic-workflows">Agentic workflows</h1>
+<blockquote>
+<p><strong>How AI agents compose with pdfnative.</strong> pdfnative is designed so an autonomous
+agent can do more than <em>call</em> the engine — it can <strong>extend</strong> it at runtime and
+<strong>feed it content it generated itself</strong>, all without waiting for a library
+release. This guide documents two concrete, factual patterns and the exact
+public APIs they rely on.</p>
+</blockquote>
+<p>Both patterns are built entirely on already-shipped, public API surfaces:</p>
+<ul>
+<li>The library&#39;s <code>registerFont()</code> / <code>loadFontData()</code> font registry, the
+<code>pdfnative/tools</code> sub-path (<code>parseFontData</code> / <code>compileFontData</code>, since v1.5.0),
+and the bundled <code>pdfnative-build-font</code> CLI.</li>
+<li>The image entry points: the <code>image</code> document block (library + CLI) and the
+<code>embed_image</code> MCP tool.</li>
+</ul>
+<p>There is <strong>no new API</strong> here — the point is that the existing surfaces were
+shaped so agents can use them autonomously, under the project&#39;s
+<a href="ai-governance.md">AI-governance / human-in-the-loop contract</a>.</p>
+<hr>
+<h2 id="pattern-1--extend-the-engine-at-runtime-without-a-release">Pattern 1 — extend the engine at runtime, without a release<a class="heading-anchor" href="#pattern-1--extend-the-engine-at-runtime-without-a-release" aria-label="Link to this section">#</a></h2>
+<p>pdfnative ships 26 bundled font-data modules (22 scripts plus Latin, math, and monochrome + colour emoji). But its font
+system is <strong>open</strong>: any TrueType/OpenType font becomes a first-class,
+CIDFont-embedded, subset-on-use font once it is <em>registered</em>. Registration is a
+runtime call — it does not require rebuilding or republishing pdfnative.</p>
+<p>This is what lets an agent add a capability the moment a document needs it. In a
+previous iteration of this project, an agent using the MCP server needed
+mathematical symbols before the bundled <strong>Noto Sans Math</strong> font existed as a
+release. Because the font registry is a public runtime API, the agent was able to
+compile the font data and register it on the spot; the same font later shipped as
+<code>registerFont(&#39;math&#39;, …)</code> in pdfnative 1.5.0. <!-- verify-docs:allow version-token (historical) --> The library did not need to change
+for the document to render — the release simply promoted an already-working
+runtime pattern into a bundled default.</p>
+<h3 id="the-three-building-blocks">The three building blocks<a class="heading-anchor" href="#the-three-building-blocks" aria-label="Link to this section">#</a></h3>
+<table>
+<thead>
+<tr>
+<th>API</th>
+<th>Sub-path</th>
+<th>What it does</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>registerFont(lang, loader)</code> / <code>registerFonts({ … })</code></td>
+<td><code>pdfnative</code></td>
+<td>Register a lazy font-data loader under a <code>lang</code> code. <code>loadFontData(lang)</code> resolves it on first use.</td>
+</tr>
+<tr>
+<td><code>parseFontData(bytes)</code> → <code>FontDataObject</code></td>
+<td><code>pdfnative/tools</code></td>
+<td>Parse a TTF/OTF <strong>in memory</strong> into a registerable font-data object (metrics, cmap, widths, GSUB/GPOS, <code>/W</code> array). Pure — no <code>fs</code>, no <code>child_process</code>, works in browsers / Deno / edge.</td>
+</tr>
+<tr>
+<td><code>compileFontData(bytes, { fontName })</code> → <code>string</code></td>
+<td><code>pdfnative/tools</code></td>
+<td>Emit the ES/CJS module <strong>source</strong> for a font-data file — byte-identical to the <code>pdfnative-build-font</code> CLI. Useful when the agent wants to persist a reusable <code>*-data.js</code>.</td>
+</tr>
+</tbody></table>
+<h3 id="an-agent-registers-a-font-at-runtime">An agent registers a font at runtime<a class="heading-anchor" href="#an-agent-registers-a-font-at-runtime" aria-label="Link to this section">#</a></h3>
+<pre><code class="language-ts">import { buildDocumentPDFBytes, registerFont, loadFontData } from &#39;pdfnative&#39;;
+import { parseFontData } from &#39;pdfnative/tools&#39;;
+
+// The agent obtained the TTF bytes however it likes — a bundled asset,
+// a user upload, or a fetch it performed itself.
+const ttfBytes: Uint8Array = await getFontBytes();
+
+// Parse in memory → a registerable font-data object.
+const fontData = parseFontData(ttfBytes);
+
+// Register it under a lang code. No release, no rebuild.
+registerFont(&#39;custom&#39;, () =&gt; Promise.resolve(fontData));
+
+// The registry is only consulted through loadFontData + fontEntries —
+// load the data and pass it explicitly (fontRef must be a PDF name; /F1 and /F2 are reserved):
+const custom = await loadFontData(&#39;custom&#39;);
+if (!custom) throw new Error(&#39;custom font failed to load&#39;);
+
+// It is now a first-class font: pdfnative subsets and embeds it on use.
+const pdf = buildDocumentPDFBytes({
+  title: &#39;Runtime font&#39;,
+  blocks: [{ type: &#39;paragraph&#39;, text: &#39;Rendered with an agent-registered font.&#39; }],
+  fontEntries: [{ fontData: custom, fontRef: &#39;/F3&#39;, lang: &#39;custom&#39; }],
+});
+</code></pre>
+<h3 id="persisting-a-reusable-data-module">Persisting a reusable data module<a class="heading-anchor" href="#persisting-a-reusable-data-module" aria-label="Link to this section">#</a></h3>
+<p>When an agent wants the font to be reusable across runs — or to hand a ready-made
+module to a human — it can emit the module source instead:</p>
+<pre><code class="language-ts">import { compileFontData } from &#39;pdfnative/tools&#39;;
+
+const source = compileFontData(ttfBytes, { fontName: &#39;My Font&#39; });
+// `source` is byte-identical to what `pdfnative-build-font` writes to disk.
+// A human (or a sandboxed file tool) can save it as `my-font-data.js`.
+</code></pre>
+<p>The equivalent one-liner for a human at a terminal is the bundled CLI:</p>
+<pre><code class="language-bash">npx pdfnative-build-font fonts/ttf/MyFont.ttf fonts/my-font-data.js
+</code></pre>
+<blockquote>
+<p><strong>Why this matters.</strong> The engine&#39;s coverage is not frozen at release time. An
+agent can close a glyph gap — a new script, a symbol set, a brand font — the
+instant a document requires it, then optionally graduate that work into a
+committed data module for the whole team. This is <em>runtime extensibility</em>, not
+autonomous modification of the published package: the agent extends its own
+in-process pdfnative instance; the repository is only ever changed by a human
+under the <a href="ai-governance.md">governance contract</a>.</p>
+</blockquote>
+<hr>
+<h2 id="pattern-2--agent-generated-images-in-the-pdf">Pattern 2 — agent-generated images in the PDF<a class="heading-anchor" href="#pattern-2--agent-generated-images-in-the-pdf" aria-label="Link to this section">#</a></h2>
+<p>Modern agents can <em>generate</em> raster content — charts, diagrams, illustrations,
+photos. Image-generating agents (for example Antigravity, ChatGPT, and other
+multimodal assistants) can pipe that output straight into a pdfnative document.
+pdfnative treats a generated PNG/JPEG exactly like any other image: it parses it
+natively and embeds it as an Image XObject (<code>/DCTDecode</code> for JPEG,
+<code>/FlateDecode</code> for PNG) — no rasterization, no headless browser.</p>
+<h3 id="via-the-mcp-server--embed_image">Via the MCP server — <code>embed_image</code><a class="heading-anchor" href="#via-the-mcp-server--embed_image" aria-label="Link to this section">#</a></h3>
+<p>An agent that produced an image returns it as base64 and calls <code>embed_image</code>:</p>
+<pre><code class="language-jsonc">{
+  &quot;tool&quot;: &quot;embed_image&quot;,
+  &quot;input&quot;: {
+    &quot;title&quot;: &quot;Quarterly trend&quot;,
+    &quot;imageBase64&quot;: &quot;&lt;base64 PNG/JPEG the agent just generated&gt;&quot;,
+    &quot;mimeType&quot;: &quot;image/png&quot;,
+    &quot;outputMode&quot;: &quot;base64&quot;
+  }
+}
+</code></pre>
+<p>For a richer layout, the same base64 payload can be dropped into an <code>image</code>
+block on <code>generate_basic_pdf</code>, alongside headings, tables, and barcodes the agent
+assembles in the same call.</p>
+<h3 id="via-the-library-or-cli--the-image-block">Via the library or CLI — the <code>image</code> block<a class="heading-anchor" href="#via-the-library-or-cli--the-image-block" aria-label="Link to this section">#</a></h3>
+<p>In code, a generated image is just another block:</p>
+<pre><code class="language-ts">import { buildDocumentPDFBytes } from &#39;pdfnative&#39;;
+
+const pdf = buildDocumentPDFBytes({
+  title: &#39;Report with a generated figure&#39;,
+  blocks: [
+    { type: &#39;heading&#39;, text: &#39;Findings&#39;, level: 1 },
+    { type: &#39;paragraph&#39;, text: &#39;The figure below was generated on-device by the agent.&#39; },
+    { type: &#39;image&#39;, data: generatedPngBytes, width: 480 },
+  ],
+});
+</code></pre>
+<p>From the shell, an agent driving <code>pdfnative-cli render</code> supplies the same block
+in its JSON document (image bytes are provided as a block field or an asset path,
+subject to the CLI&#39;s path-validation rules).</p>
+<blockquote>
+<p><strong>Safety.</strong> pdfnative validates image inputs at the boundary — it parses the
+JPEG/PNG structure natively and rejects malformed or unsupported payloads
+(e.g. raw RGBA). The agent supplies pixels; pdfnative decides whether they are
+a well-formed image before embedding.</p>
+</blockquote>
+<hr>
+<h2 id="how-the-two-patterns-fit-together">How the two patterns fit together<a class="heading-anchor" href="#how-the-two-patterns-fit-together" aria-label="Link to this section">#</a></h2>
+<p>A single agent turn can combine both: register a brand font, generate a cover
+image, and assemble a signed, archive-grade PDF — in one MCP conversation or one
+CLI pipeline, without a pdfnative release in the loop.</p>
+<p><img src="../assets/agentic-workflows.svg" alt="Agentic workflows: an AI agent generates images (embedded via the image block / embed_image) and compiles fonts (registered at runtime via registerFont + parseFontData), both feeding the pdfnative public API to produce an ISO 32000-1 PDF. Repository changes stay human-gated under the AI-governance / HITL contract."></p>
+<p>The engine stays zero-dependency and unchanged; the agent supplies fonts and
+images through public, validated entry points. Anything that would modify the
+<strong>repository</strong> — a new bundled font, a code change — still goes through a human
+under the <a href="ai-governance.md">AI-governance / human-in-the-loop contract</a>.</p>
+<hr>
+<h2 id="see-also">See also<a class="heading-anchor" href="#see-also" aria-label="Link to this section">#</a></h2>
+<ul>
+<li><a href="ai-governance.md">AI governance &amp; human-in-the-loop</a> — the contract that keeps
+repository changes human-gated.</li>
+<li><a href="mcp.md">MCP integration</a> — the 28 MCP tools, including <code>embed_image</code> and
+<code>draft_governance_issue</code>.</li>
+<li><a href="cli.md">CLI guide</a> — driving pdfnative from the shell.</li>
+<li><a href="font-validation.md">Font validation</a> — <code>validateFontData()</code> for sanity-checking
+a font module before registering it.</li>
+</ul>
+<!-- guide:render:end -->
+  </article>
+</main>
+
+<footer class="footer">
+  <div class="footer-inner">
+    <span>MIT License · © 2026 Nizoka</span>
+    <ul class="footer-links" role="list">
+      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
+      <li><a href="https://www.npmjs.com/package/pdfnative" target="_blank" rel="noopener">npm</a></li>
+      <li><a href="https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md" target="_blank" rel="noopener">Changelog</a></li>
+      <li><a href="./">All guides</a></li>
+    </ul>
+  </div>
+</footer>
+
+<script src="https://cdn.jsdelivr.net/npm/marked@12.0.2/marked.min.js" integrity="sha384-/TQbtLCAerC3jgaim+N78RZSDYV7ryeoBCVqTuzRrFec2akfBkHS7ACQ3PQhvMVi" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/dompurify@3.1.5/dist/purify.min.js" integrity="sha384-nszIONF2FGC59kn+pPFaRa6WUNGwsZgXZiJxJwQbym+TzcH7smolUviLgpPbNx7V" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/prism.min.js" integrity="sha384-BGaNxfftg+9+TtC098wxawPFVEUpKYvaiCgbB0iqAMjK/4jDdmUY+oGxrPNvnXEf" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-typescript.min.js" integrity="sha384-PeOqKNW/piETaCg8rqKFy+Pm6KEk7e36/5YZE5XO/OaFdO+/Aw3O8qZ9qDPKVUgx" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-bash.min.js" integrity="sha384-9WmlN8ABpoFSSHvBGGjhvB3E/D8UkNB9HpLJjBQFC2VSQsM1odiQDv4NbEo+7l15" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-json.min.js" integrity="sha384-RhrmFFMb0ZCHImjFMpR/UE3VEtIVTCtNrtKQqXCzqXZNJala02N3UbVhi+qzw3CY" crossorigin="anonymous" defer></script>
+<script src="guide.js" defer></script>
+</body>
+</html>
diff --git a/docs/guides/agentic-workflows.md b/docs/guides/agentic-workflows.md
index 65edaf1..c891d24 100644
--- a/docs/guides/agentic-workflows.md
+++ b/docs/guides/agentic-workflows.md
@@ -178,7 +178,7 @@ under the [AI-governance / human-in-the-loop contract](ai-governance.md).
 
 - [AI governance & human-in-the-loop](ai-governance.md) — the contract that keeps
   repository changes human-gated.
-- [MCP integration](mcp.md) — the 24 MCP tools, including `embed_image` and
+- [MCP integration](mcp.md) — the 28 MCP tools, including `embed_image` and
   `draft_governance_issue`.
 - [CLI guide](cli.md) — driving pdfnative from the shell.
 - [Font validation](font-validation.md) — `validateFontData()` for sanity-checking
diff --git a/docs/guides/ai-governance.html b/docs/guides/ai-governance.html
index b3ddb0e..cdebf43 100644
--- a/docs/guides/ai-governance.html
+++ b/docs/guides/ai-governance.html
@@ -1,86 +1,256 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>AI governance & human-in-the-loop — pdfnative</title>
-  <meta name="description" content="How pdfnative governs AI coding agents: a machine-readable contract (ai-governance.json) and a human-in-the-loop protocol that keep agents as draftsmen. Humans review, approve, and submit everything. Shipped in v1.5.0.">
-  <link rel="canonical" href="https://pdfnative.dev/guides/ai-governance.html">
-  <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/ai-governance.html">
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>AI governance & human-in-the-loop — pdfnative</title>
+  <meta name="description" content="How pdfnative governs AI coding agents: a machine-readable contract (ai-governance.json) and a human-in-the-loop protocol that keep agents as draftsmen. Humans review, approve, and submit everything. Shipped in v1.5.0.">
+  <link rel="canonical" href="https://pdfnative.dev/guides/ai-governance.html">
+  <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/ai-governance.html">
   <link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/ai-governance.html">
-  <link rel="alternate" type="text/markdown" href="ai-governance.md">
-  <meta property="og:type" content="article">
-  <meta property="og:site_name" content="pdfnative">
+  <link rel="alternate" type="text/markdown" href="ai-governance.md">
+  <link rel="alternate" type="text/plain" href="../llms.txt" title="llms.txt — machine-readable documentation index">
+  <meta property="og:type" content="article">
+  <meta property="og:site_name" content="pdfnative">
   <meta property="og:locale" content="en_US">
-  <meta property="og:url" content="https://pdfnative.dev/guides/ai-governance.html">
-  <meta property="og:title" content="AI governance & human-in-the-loop — pdfnative">
-  <meta property="og:description" content="Agents draft, humans decide. A machine-readable governance contract + HITL protocol that keeps AI agents advisory. Nothing reaches GitHub autonomously.">
-  <meta property="og:image" content="https://pdfnative.dev/assets/og-image.png">
-  <meta property="og:image:width" content="1200">
-  <meta property="og:image:height" content="630">
-  <meta name="twitter:card" content="summary_large_image">
-  <meta name="twitter:title" content="AI governance & human-in-the-loop — pdfnative">
-  <meta name="twitter:description" content="Transparent AI-agent governance for pdfnative: draftsman role, compliance report, human sign-off gate.">
-  <meta name="twitter:image" content="https://pdfnative.dev/assets/og-image.png">
-  <link rel="icon" type="image/svg+xml" href="../favicon.svg">
-  <link rel="stylesheet" href="../style.css">
-  <link rel="stylesheet" href="guide.css">
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
-</head>
-<body>
-
-<a class="skip-link" href="#main-content">Skip to main content</a>
-
-<nav class="nav" role="navigation" aria-label="Main navigation">
-  <div class="nav-inner">
-    <a class="nav-brand" href="../">
-      <img src="../assets/logo.svg" alt="" width="28" height="28">
-      pdfnative
-    </a>
-    <button class="nav-hamburger" aria-label="Toggle menu" aria-expanded="false">☰</button>
-    <ul class="nav-links" role="list">
-      <li><a href="../#features">Features</a></li>
-      <li><a href="../#examples">Examples</a></li>
-      <li><a href="../#demo">Demo</a></li>
-      <li><a href="../#mcp">MCP</a></li>
-      <li><a href="../#cli">CLI</a></li>
-      <li><a href="../#react">React</a></li>
-      <li><a href="../learn/">Learn</a></li>
-      <li><a href="./">Guides</a></li>
-      <li><a href="../playgrounds/">Playgrounds</a></li>
-      <li><a href="../responsibility.html">Responsibility</a></li>
-      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
-      <li><button class="theme-toggle" aria-label="Toggle dark mode">🌙</button></li>
-    </ul>
-  </div>
-</nav>
-
-<main class="guide-shell" id="main-content" tabindex="-1">
-  <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; AI governance</p>
-  <article id="guide-content" class="guide-content" data-md="ai-governance.md">
-    <p class="guide-loading">Loading…</p>
-    <noscript><p>This guide is written in Markdown: <a href="ai-governance.md">read ai-governance.md</a>.</p></noscript>
-  </article>
-</main>
-
-<footer class="footer">
-  <div class="footer-inner">
-    <span>MIT License · © 2026 Nizoka</span>
-    <ul class="footer-links" role="list">
-      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
-      <li><a href="https://www.npmjs.com/package/pdfnative" target="_blank" rel="noopener">npm</a></li>
-      <li><a href="https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md" target="_blank" rel="noopener">Changelog</a></li>
-      <li><a href="./">All guides</a></li>
-    </ul>
-  </div>
-</footer>
-
-<script src="https://cdn.jsdelivr.net/npm/marked@12.0.2/marked.min.js" integrity="sha384-/TQbtLCAerC3jgaim+N78RZSDYV7ryeoBCVqTuzRrFec2akfBkHS7ACQ3PQhvMVi" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/dompurify@3.1.5/dist/purify.min.js" integrity="sha384-nszIONF2FGC59kn+pPFaRa6WUNGwsZgXZiJxJwQbym+TzcH7smolUviLgpPbNx7V" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/prism.min.js" integrity="sha384-BGaNxfftg+9+TtC098wxawPFVEUpKYvaiCgbB0iqAMjK/4jDdmUY+oGxrPNvnXEf" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-typescript.min.js" integrity="sha384-PeOqKNW/piETaCg8rqKFy+Pm6KEk7e36/5YZE5XO/OaFdO+/Aw3O8qZ9qDPKVUgx" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-bash.min.js" integrity="sha384-9WmlN8ABpoFSSHvBGGjhvB3E/D8UkNB9HpLJjBQFC2VSQsM1odiQDv4NbEo+7l15" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-json.min.js" integrity="sha384-RhrmFFMb0ZCHImjFMpR/UE3VEtIVTCtNrtKQqXCzqXZNJala02N3UbVhi+qzw3CY" crossorigin="anonymous" defer></script>
-<script src="guide.js" defer></script>
-</body>
-</html>
+  <meta property="og:url" content="https://pdfnative.dev/guides/ai-governance.html">
+  <meta property="og:title" content="AI governance & human-in-the-loop — pdfnative">
+  <meta property="og:description" content="Agents draft, humans decide. A machine-readable governance contract + HITL protocol that keeps AI agents advisory. Nothing reaches GitHub autonomously.">
+  <meta property="og:image" content="https://pdfnative.dev/assets/og-image.png">
+  <meta property="og:image:width" content="1200">
+  <meta property="og:image:height" content="630">
+  <meta name="twitter:card" content="summary_large_image">
+  <meta name="twitter:title" content="AI governance & human-in-the-loop — pdfnative">
+  <meta name="twitter:description" content="Transparent AI-agent governance for pdfnative: draftsman role, compliance report, human sign-off gate.">
+  <meta name="twitter:image" content="https://pdfnative.dev/assets/og-image.png">
+  <link rel="icon" type="image/svg+xml" href="../favicon.svg">
+  <link rel="stylesheet" href="../style.css">
+  <link rel="stylesheet" href="guide.css">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
+  <!-- guide:ld:start -->
+  <script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://pdfnative.dev/"},{"@type":"ListItem","position":2,"name":"Guides","item":"https://pdfnative.dev/guides/"},{"@type":"ListItem","position":3,"name":"AI governance & human-in-the-loop","item":"https://pdfnative.dev/guides/ai-governance.html"}]},{"@type":"TechArticle","headline":"AI governance & human-in-the-loop","description":"How pdfnative governs AI coding agents: a machine-readable contract (ai-governance.json) and a human-in-the-loop protocol that keep agents as draftsmen. Humans review, approve, and submit everything. Shipped in v1.5.0.","inLanguage":"en","author":{"@type":"Organization","name":"Nizoka","url":"https://github.com/Nizoka"},"publisher":{"@type":"Organization","name":"pdfnative","url":"https://pdfnative.dev","logo":{"@type":"ImageObject","url":"https://pdfnative.dev/assets/logo.svg"}},"mainEntityOfPage":{"@type":"WebPage","@id":"https://pdfnative.dev/guides/ai-governance.html"},"isPartOf":{"@type":"WebSite","name":"pdfnative","url":"https://pdfnative.dev"}}]}</script>
+  <!-- guide:ld:end -->
+</head>
+<body>
+
+<a class="skip-link" href="#main-content">Skip to main content</a>
+
+<nav class="nav" role="navigation" aria-label="Main navigation">
+  <div class="nav-inner">
+    <a class="nav-brand" href="../">
+      <img src="../assets/logo.svg" alt="" width="28" height="28">
+      pdfnative
+    </a>
+    <button class="nav-hamburger" aria-label="Toggle menu" aria-expanded="false">☰</button>
+    <ul class="nav-links" role="list">
+      <li><a href="../#features">Features</a></li>
+      <li><a href="../#examples">Examples</a></li>
+      <li><a href="../#demo">Demo</a></li>
+      <li><a href="../#mcp">MCP</a></li>
+      <li><a href="../#cli">CLI</a></li>
+      <li><a href="../#react">React</a></li>
+      <li><a href="../learn/">Learn</a></li>
+      <li><a href="./">Guides</a></li>
+      <li><a href="../playgrounds/">Playgrounds</a></li>
+      <li><a href="../responsibility.html">Responsibility</a></li>
+      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
+      <li><button class="theme-toggle" aria-label="Toggle dark mode">🌙</button></li>
+    </ul>
+  </div>
+</nav>
+
+<main class="guide-shell" id="main-content" tabindex="-1">
+  <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; AI governance</p>
+  <article id="guide-content" class="guide-content" data-md="ai-governance.md" data-prerendered="true">
+<!-- guide:render:start -->
+<h1 id="ai-governance--human-in-the-loop">AI governance &amp; human-in-the-loop</h1>
+<blockquote>
+<p><strong>Shipped in v1.5.0.</strong> pdfnative is developed with the help of AI coding
+agents — and it governs them. This repository ships a <strong>machine-readable
+governance contract</strong> and a <strong>human-in-the-loop (HITL) protocol</strong> that keep
+AI agents in an advisory role: they may <em>draft</em> proposals, but a human always
+reviews, approves, and submits. Nothing reaches GitHub autonomously.</p>
+</blockquote>
+<p>This page exists for <strong>transparency</strong>. If you evaluate pdfnative for production,
+you should be able to see exactly how AI participates in its maintenance — and
+where the hard limits are.</p>
+<p><img src="../assets/ai-governance.svg" alt="AI governance and human-in-the-loop flow — an agent drafts across four steps (detect, reproduce, self-check, draft into .github/drafts/), automated checks run verify-issue.mjs and produce a compliance report, then a human review and sign-off gate is the only path to a submission published under the human&#39;s own GitHub identity. A red callout lists what agents must never do."></p>
+<h2 id="why-this-exists">Why this exists<a class="heading-anchor" href="#why-this-exists" aria-label="Link to this section">#</a></h2>
+<p>Modern open-source projects increasingly receive AI-generated issues and pull
+requests. Unbounded, that creates noise, low-signal duplicates, and — worst of
+all — a diffusion of responsibility: <em>who actually stands behind this change?</em></p>
+<p>pdfnative&#39;s answer is a written, enforceable contract:</p>
+<ul>
+<li><strong>Agents are draftsmen, never submitters.</strong> Their authority ends at producing
+a local markdown draft plus a compliance report.</li>
+<li><strong>A human is always in the loop.</strong> A person explicitly reviews, approves, and
+triggers every issue, comment, pull request, and release.</li>
+<li><strong>Identity integrity.</strong> Anything submitted is published under the human&#39;s own
+GitHub identity — so a human always shares responsibility for the content.</li>
+</ul>
+<p>The two source-of-truth files live in the repository and are loaded by any agent
+that scans project configuration on start-up:</p>
+<ul>
+<li><a href="https://github.com/Nizoka/pdfnative/blob/main/.github/AGENT_RULES.md" target="_blank" rel="noopener">.github/AGENT_RULES.md</a>
+— the human-and-agent-readable protocol.</li>
+<li><a href="https://github.com/Nizoka/pdfnative/blob/main/.github/ai-governance.json" target="_blank" rel="noopener">.github/ai-governance.json</a>
+— the machine-readable contract.</li>
+</ul>
+<h2 id="the-six-mandatory-rules">The six mandatory rules<a class="heading-anchor" href="#the-six-mandatory-rules" aria-label="Link to this section">#</a></h2>
+<p>Every agent (Copilot, Cursor, Claude, Antigravity, Aider, Cline, Windsurf,
+Gemini CLI, …) must satisfy all six before proposing anything:</p>
+<ol>
+<li><strong>Zero runtime dependencies.</strong> Never suggest, add, or import an external npm
+package for a runtime feature. This is a non-negotiable blocker.</li>
+<li><strong>No duplicates.</strong> Search open <em>and</em> closed issues/PRs first. Surface a
+matching one instead of opening a new report.</li>
+<li><strong>Local validation &amp; reproduction.</strong> Create and <em>execute</em> a minimal
+reproduction. If it does not fail or show a measurable regression, do not
+propose an issue.</li>
+<li><strong>Byte-identity awareness.</strong> For changes touching the builders, confirm the
+change is additive and existing output stays byte-identical — or report any
+intentional byte change.</li>
+<li><strong>Human-in-the-loop gate (ethics).</strong> Agents are strictly forbidden from
+creating, editing, or submitting issues, comments, PRs, or releases via any
+tool or API. They produce a local draft in
+<a href="https://github.com/Nizoka/pdfnative/tree/main/.github" target="_blank" rel="noopener">.github/drafts/</a> and
+present it with a compliance report.</li>
+<li><strong>Identity integrity.</strong> The agent reminds the user that anything submitted is
+published under their GitHub identity and that they share responsibility.</li>
+</ol>
+<h2 id="the-human-in-the-loop-workflow">The human-in-the-loop workflow<a class="heading-anchor" href="#the-human-in-the-loop-workflow" aria-label="Link to this section">#</a></h2>
+<pre><code>[Agent detects bug/improvement]
+            │
+            ▼
+ [Local validation &amp; reproduction]
+            │
+            ▼
+[Verify zero-dependency constraint]
+            │
+            ▼
+ [Generate draft markdown in .github/drafts/]
+            │
+            ▼
+[Present draft + compliance report to user]
+            │
+            ▼
+ [User explicitly reviews &amp; signs off]   ◄─── CRITICAL ETHICAL GATE
+            │
+            ▼
+ [User manually submits or approves the API call]
+</code></pre>
+<p>The agent&#39;s job ends at the draft. The <strong>human gate</strong> is the only path from a
+proposal to a published issue, PR, or release.</p>
+<h2 id="the-compliance-report">The compliance report<a class="heading-anchor" href="#the-compliance-report" aria-label="Link to this section">#</a></h2>
+<p>Every draft must be accompanied by a structured compliance report so the human
+can review with full context. At minimum it contains:</p>
+<table>
+<thead>
+<tr>
+<th>Field</th>
+<th>What it confirms</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><strong>Zero-dependency confirmed</strong></td>
+<td>no new runtime dependency introduced</td>
+</tr>
+<tr>
+<td><strong>Reproduction command</strong></td>
+<td>the exact command the agent ran</td>
+</tr>
+<tr>
+<td><strong>Reproduction result</strong></td>
+<td>the observed failure or regression</td>
+</tr>
+<tr>
+<td><strong>Duplicate search</strong></td>
+<td>what was searched and what was found</td>
+</tr>
+<tr>
+<td><strong>Affected packages</strong></td>
+<td>which monorepo packages are impacted</td>
+</tr>
+<tr>
+<td><strong>Identity reminder shown</strong></td>
+<td>the user was told it publishes under their name</td>
+</tr>
+</tbody></table>
+<h2 id="validate-a-draft-before-presenting-it">Validate a draft before presenting it<a class="heading-anchor" href="#validate-a-draft-before-presenting-it" aria-label="Link to this section">#</a></h2>
+<p>A small, dependency-free verifier checks a draft mechanically:</p>
+<pre><code class="language-bash">node scripts/verify-issue.mjs .github/drafts/my-issue.md
+# or via the npm script
+npm run verify:issue .github/drafts/my-issue.md
+</code></pre>
+<p>It fails when the draft proposes an external dependency or omits a reproduction
+code block. A passing check is <strong>necessary but not sufficient</strong> — the human
+review gate above always applies. The verifier is advisory in CI and exposes a
+pure <code>validateIssueMarkdown(content)</code> function so its logic is unit-tested.</p>
+<h2 id="the-machine-readable-contract">The machine-readable contract<a class="heading-anchor" href="#the-machine-readable-contract" aria-label="Link to this section">#</a></h2>
+<p><a href="https://github.com/Nizoka/pdfnative/blob/main/.github/ai-governance.json" target="_blank" rel="noopener">.github/ai-governance.json</a>
+encodes the policy so agents that scan repository configuration can honour it
+without parsing prose. Key fields:</p>
+<pre><code class="language-jsonc">{
+  &quot;policy&quot;: {
+    &quot;automatic_issue_reporting&quot;: false,
+    &quot;runtime_dependencies_allowed&quot;: false,
+    &quot;human_in_the_loop_mandatory&quot;: true,
+    &quot;autonomous_github_writes_allowed&quot;: false,
+    &quot;required_issue_fields&quot;: [
+      &quot;minimal_reproduction&quot;, &quot;environment&quot;, &quot;expected_behavior&quot;
+    ]
+  },
+  &quot;human_in_the_loop&quot;: {
+    &quot;role_of_agent&quot;: &quot;draftsman&quot;,
+    &quot;gate&quot;: &quot;A human MUST explicitly review, sign off on, and trigger any GitHub issue, comment, PR, or release.&quot;,
+    &quot;draft_location&quot;: &quot;.github/drafts/&quot;
+  }
+}
+</code></pre>
+<p>The contract <code>applies_to</code> the whole ecosystem — <code>pdfnative</code>, <code>pdfnative-cli</code>,
+<code>pdfnative-mcp</code>, and <code>pdfnative-react</code>.</p>
+<p>Since pdfnative-mcp 1.6.0, that package&#39;s mirror of the charter also states
+the <strong>single permitted egress class</strong>: the server makes no outbound request by
+default, and the only network calls it can ever perform go to the TSA / OCSP /
+CRL endpoints the <em>operator</em> configures for the PAdES tools — never to a URL
+taken from a tool argument, and never to GitHub. &quot;No GitHub write path&quot; and
+&quot;no telemetry&quot; remain absolute.</p>
+<h2 id="what-agents-must-never-do">What agents must never do<a class="heading-anchor" href="#what-agents-must-never-do" aria-label="Link to this section">#</a></h2>
+<ul>
+<li>Add a runtime dependency.</li>
+<li>Open, edit, label, close, or comment on issues/PRs autonomously.</li>
+<li>Submit anything under the user&#39;s identity without explicit, per-submission
+human approval.</li>
+<li>Bypass local validation or duplicate checks.</li>
+</ul>
+<h2 id="in-short">In short<a class="heading-anchor" href="#in-short" aria-label="Link to this section">#</a></h2>
+<p>pdfnative treats AI as a <strong>force multiplier for humans, not a replacement for
+human judgement</strong>. Agents accelerate the tedious parts — reproduction, drafting,
+compliance checking — while every externally visible action stays under
+deliberate human control. That is the standard we hold ourselves to, and we
+publish it so you can hold us to it too.</p>
+<!-- guide:render:end -->
+  </article>
+</main>
+
+<footer class="footer">
+  <div class="footer-inner">
+    <span>MIT License · © 2026 Nizoka</span>
+    <ul class="footer-links" role="list">
+      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
+      <li><a href="https://www.npmjs.com/package/pdfnative" target="_blank" rel="noopener">npm</a></li>
+      <li><a href="https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md" target="_blank" rel="noopener">Changelog</a></li>
+      <li><a href="./">All guides</a></li>
+    </ul>
+  </div>
+</footer>
+
+<script src="https://cdn.jsdelivr.net/npm/marked@12.0.2/marked.min.js" integrity="sha384-/TQbtLCAerC3jgaim+N78RZSDYV7ryeoBCVqTuzRrFec2akfBkHS7ACQ3PQhvMVi" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/dompurify@3.1.5/dist/purify.min.js" integrity="sha384-nszIONF2FGC59kn+pPFaRa6WUNGwsZgXZiJxJwQbym+TzcH7smolUviLgpPbNx7V" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/prism.min.js" integrity="sha384-BGaNxfftg+9+TtC098wxawPFVEUpKYvaiCgbB0iqAMjK/4jDdmUY+oGxrPNvnXEf" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-typescript.min.js" integrity="sha384-PeOqKNW/piETaCg8rqKFy+Pm6KEk7e36/5YZE5XO/OaFdO+/Aw3O8qZ9qDPKVUgx" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-bash.min.js" integrity="sha384-9WmlN8ABpoFSSHvBGGjhvB3E/D8UkNB9HpLJjBQFC2VSQsM1odiQDv4NbEo+7l15" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-json.min.js" integrity="sha384-RhrmFFMb0ZCHImjFMpR/UE3VEtIVTCtNrtKQqXCzqXZNJala02N3UbVhi+qzw3CY" crossorigin="anonymous" defer></script>
+<script src="guide.js" defer></script>
+</body>
+</html>
diff --git a/docs/guides/ai-governance.md b/docs/guides/ai-governance.md
index 8f0d810..a26485e 100644
--- a/docs/guides/ai-governance.md
+++ b/docs/guides/ai-governance.md
@@ -142,6 +142,13 @@ without parsing prose. Key fields:
 The contract `applies_to` the whole ecosystem — `pdfnative`, `pdfnative-cli`,
 `pdfnative-mcp`, and `pdfnative-react`.
 
+Since pdfnative-mcp 1.6.0, that package's mirror of the charter also states
+the **single permitted egress class**: the server makes no outbound request by
+default, and the only network calls it can ever perform go to the TSA / OCSP /
+CRL endpoints the *operator* configures for the PAdES tools — never to a URL
+taken from a tool argument, and never to GitHub. "No GitHub write path" and
+"no telemetry" remain absolute.
+
 ## What agents must never do
 
 - Add a runtime dependency.
diff --git a/docs/guides/annotations.html b/docs/guides/annotations.html
index 7418378..34f07fa 100644
--- a/docs/guides/annotations.html
+++ b/docs/guides/annotations.html
@@ -1,85 +1,226 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>Annotations (read & write) — pdfnative</title>
-  <meta name="description" content="Typed markup annotations in pdfnative — text, highlight, underline, strikeout, squiggly, square, circle, line, freetext — with buildAnnotation(), getAnnotations() to read existing PDFs, and addAnnotation() incremental write. New in v1.5.0.">
-  <link rel="canonical" href="https://pdfnative.dev/guides/annotations.html">
-  <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/annotations.html">
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Annotations (read & write) — pdfnative</title>
+  <meta name="description" content="Typed markup annotations in pdfnative — text, highlight, underline, strikeout, squiggly, square, circle, line, freetext — with buildAnnotation(), getAnnotations() to read existing PDFs, and addAnnotation() incremental write. New in v1.5.0.">
+  <link rel="canonical" href="https://pdfnative.dev/guides/annotations.html">
+  <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/annotations.html">
   <link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/annotations.html">
-  <link rel="alternate" type="text/markdown" href="annotations.md">
-  <meta property="og:type" content="article">
-  <meta property="og:site_name" content="pdfnative">
+  <link rel="alternate" type="text/markdown" href="annotations.md">
+  <link rel="alternate" type="text/plain" href="../llms.txt" title="llms.txt — machine-readable documentation index">
+  <meta property="og:type" content="article">
+  <meta property="og:site_name" content="pdfnative">
   <meta property="og:locale" content="en_US">
-  <meta property="og:url" content="https://pdfnative.dev/guides/annotations.html">
-  <meta property="og:title" content="Annotations (read & write) — pdfnative">
-  <meta property="og:description" content="Typed markup-annotation model with round-trip read/write: buildAnnotation, getAnnotations, addAnnotation. Zero dependency, ISO 32000-1 §12.5. New in v1.5.0.">
-  <meta property="og:image" content="https://pdfnative.dev/assets/og-image.png">
-  <meta property="og:image:width" content="1200">
-  <meta property="og:image:height" content="630">
-  <meta name="twitter:card" content="summary_large_image">
-  <meta name="twitter:title" content="Annotations (read & write) — pdfnative">
-  <meta name="twitter:description" content="Build, read, and inject PDF markup annotations with pdfnative.">
-  <meta name="twitter:image" content="https://pdfnative.dev/assets/og-image.png">
-  <link rel="icon" type="image/svg+xml" href="../favicon.svg">
-  <link rel="stylesheet" href="../style.css">
-  <link rel="stylesheet" href="guide.css">
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
-</head>
-<body>
-
-<a class="skip-link" href="#main-content">Skip to main content</a>
-
-<nav class="nav" role="navigation" aria-label="Main navigation">
-  <div class="nav-inner">
-    <a class="nav-brand" href="../">
-      <img src="../assets/logo.svg" alt="" width="28" height="28">
-      pdfnative
-    </a>
-    <button class="nav-hamburger" aria-label="Toggle menu" aria-expanded="false">☰</button>
-    <ul class="nav-links" role="list">
-      <li><a href="../#features">Features</a></li>
-      <li><a href="../#examples">Examples</a></li>
-      <li><a href="../#demo">Demo</a></li>
-      <li><a href="../#mcp">MCP</a></li>
-      <li><a href="../#cli">CLI</a></li>
-      <li><a href="../#react">React</a></li>
-      <li><a href="../learn/">Learn</a></li>
-      <li><a href="./">Guides</a></li>
-      <li><a href="../playgrounds/">Playgrounds</a></li>
-      <li><a href="../responsibility.html">Responsibility</a></li>
-      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
-      <li><button class="theme-toggle" aria-label="Toggle dark mode">🌙</button></li>
-    </ul>
-  </div>
-</nav>
-
-<main class="guide-shell" id="main-content" tabindex="-1">
-  <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; Annotations</p>
-  <article id="guide-content" class="guide-content" data-md="annotations.md">
-    <p class="guide-loading">Loading…</p>
-    <noscript><p>This guide is written in Markdown: <a href="annotations.md">read annotations.md</a>.</p></noscript>
-  </article>
-</main>
-
-<footer class="footer">
-  <div class="footer-inner">
-    <span>MIT License · © 2026 Nizoka</span>
-    <ul class="footer-links" role="list">
-      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
-      <li><a href="https://www.npmjs.com/package/pdfnative" target="_blank" rel="noopener">npm</a></li>
-      <li><a href="https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md" target="_blank" rel="noopener">Changelog</a></li>
-      <li><a href="./">All guides</a></li>
-    </ul>
-  </div>
-</footer>
-
-<script src="https://cdn.jsdelivr.net/npm/marked@12.0.2/marked.min.js" integrity="sha384-/TQbtLCAerC3jgaim+N78RZSDYV7ryeoBCVqTuzRrFec2akfBkHS7ACQ3PQhvMVi" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/dompurify@3.1.5/dist/purify.min.js" integrity="sha384-nszIONF2FGC59kn+pPFaRa6WUNGwsZgXZiJxJwQbym+TzcH7smolUviLgpPbNx7V" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/prism.min.js" integrity="sha384-BGaNxfftg+9+TtC098wxawPFVEUpKYvaiCgbB0iqAMjK/4jDdmUY+oGxrPNvnXEf" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-typescript.min.js" integrity="sha384-PeOqKNW/piETaCg8rqKFy+Pm6KEk7e36/5YZE5XO/OaFdO+/Aw3O8qZ9qDPKVUgx" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-bash.min.js" integrity="sha384-9WmlN8ABpoFSSHvBGGjhvB3E/D8UkNB9HpLJjBQFC2VSQsM1odiQDv4NbEo+7l15" crossorigin="anonymous" defer></script>
-<script src="guide.js" defer></script>
-</body>
-</html>
+  <meta property="og:url" content="https://pdfnative.dev/guides/annotations.html">
+  <meta property="og:title" content="Annotations (read & write) — pdfnative">
+  <meta property="og:description" content="Typed markup-annotation model with round-trip read/write: buildAnnotation, getAnnotations, addAnnotation. Zero dependency, ISO 32000-1 §12.5. New in v1.5.0.">
+  <meta property="og:image" content="https://pdfnative.dev/assets/og-image.png">
+  <meta property="og:image:width" content="1200">
+  <meta property="og:image:height" content="630">
+  <meta name="twitter:card" content="summary_large_image">
+  <meta name="twitter:title" content="Annotations (read & write) — pdfnative">
+  <meta name="twitter:description" content="Build, read, and inject PDF markup annotations with pdfnative.">
+  <meta name="twitter:image" content="https://pdfnative.dev/assets/og-image.png">
+  <link rel="icon" type="image/svg+xml" href="../favicon.svg">
+  <link rel="stylesheet" href="../style.css">
+  <link rel="stylesheet" href="guide.css">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
+  <!-- guide:ld:start -->
+  <script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://pdfnative.dev/"},{"@type":"ListItem","position":2,"name":"Guides","item":"https://pdfnative.dev/guides/"},{"@type":"ListItem","position":3,"name":"Annotations (read & write)","item":"https://pdfnative.dev/guides/annotations.html"}]},{"@type":"TechArticle","headline":"Annotations (read & write)","description":"Typed markup annotations in pdfnative — text, highlight, underline, strikeout, squiggly, square, circle, line, freetext — with buildAnnotation(), getAnnotations() to read existing PDFs, and addAnnotation() incremental write. New in v1.5.0.","inLanguage":"en","author":{"@type":"Organization","name":"Nizoka","url":"https://github.com/Nizoka"},"publisher":{"@type":"Organization","name":"pdfnative","url":"https://pdfnative.dev","logo":{"@type":"ImageObject","url":"https://pdfnative.dev/assets/logo.svg"}},"mainEntityOfPage":{"@type":"WebPage","@id":"https://pdfnative.dev/guides/annotations.html"},"isPartOf":{"@type":"WebSite","name":"pdfnative","url":"https://pdfnative.dev"}}]}</script>
+  <!-- guide:ld:end -->
+</head>
+<body>
+
+<a class="skip-link" href="#main-content">Skip to main content</a>
+
+<nav class="nav" role="navigation" aria-label="Main navigation">
+  <div class="nav-inner">
+    <a class="nav-brand" href="../">
+      <img src="../assets/logo.svg" alt="" width="28" height="28">
+      pdfnative
+    </a>
+    <button class="nav-hamburger" aria-label="Toggle menu" aria-expanded="false">☰</button>
+    <ul class="nav-links" role="list">
+      <li><a href="../#features">Features</a></li>
+      <li><a href="../#examples">Examples</a></li>
+      <li><a href="../#demo">Demo</a></li>
+      <li><a href="../#mcp">MCP</a></li>
+      <li><a href="../#cli">CLI</a></li>
+      <li><a href="../#react">React</a></li>
+      <li><a href="../learn/">Learn</a></li>
+      <li><a href="./">Guides</a></li>
+      <li><a href="../playgrounds/">Playgrounds</a></li>
+      <li><a href="../responsibility.html">Responsibility</a></li>
+      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
+      <li><button class="theme-toggle" aria-label="Toggle dark mode">🌙</button></li>
+    </ul>
+  </div>
+</nav>
+
+<main class="guide-shell" id="main-content" tabindex="-1">
+  <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; Annotations</p>
+  <article id="guide-content" class="guide-content" data-md="annotations.md" data-prerendered="true">
+<!-- guide:render:start -->
+<h1 id="annotations-read--write">Annotations (read &amp; write)</h1>
+<blockquote>
+<p><strong>New in v1.5.0.</strong> pdfnative now has a typed <strong>markup-annotation</strong> model plus
+round-trip <strong>read</strong> and <strong>write</strong> support. Build annotations for a new
+document, read the annotations out of an existing PDF, or inject new ones into
+an existing PDF via incremental update — all zero-dependency, all
+ISO 32000-1 §12.5.</p>
+</blockquote>
+<h2 id="supported-annotation-types">Supported annotation types<a class="heading-anchor" href="#supported-annotation-types" aria-label="Link to this section">#</a></h2>
+<table>
+<thead>
+<tr>
+<th><code>type</code></th>
+<th>PDF <code>/Subtype</code></th>
+<th>Use</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>text</code></td>
+<td><code>/Text</code></td>
+<td>Sticky-note comment with an icon</td>
+</tr>
+<tr>
+<td><code>highlight</code></td>
+<td><code>/Highlight</code></td>
+<td>Highlight a text region</td>
+</tr>
+<tr>
+<td><code>underline</code></td>
+<td><code>/Underline</code></td>
+<td>Underline a text region</td>
+</tr>
+<tr>
+<td><code>strikeout</code></td>
+<td><code>/StrikeOut</code></td>
+<td>Strike through a text region</td>
+</tr>
+<tr>
+<td><code>squiggly</code></td>
+<td><code>/Squiggly</code></td>
+<td>Squiggly (spellcheck-style) underline</td>
+</tr>
+<tr>
+<td><code>square</code></td>
+<td><code>/Square</code></td>
+<td>Rectangle</td>
+</tr>
+<tr>
+<td><code>circle</code></td>
+<td><code>/Circle</code></td>
+<td>Ellipse</td>
+</tr>
+<tr>
+<td><code>line</code></td>
+<td><code>/Line</code></td>
+<td>Straight line</td>
+</tr>
+<tr>
+<td><code>freetext</code></td>
+<td><code>/FreeText</code></td>
+<td>Typewriter / callout text</td>
+</tr>
+</tbody></table>
+<p>Every type shares <code>AnnotationBase</code>: <code>rect</code>, and optional <code>contents</code>, <code>color</code>,
+<code>opacity</code>, <code>title</code>, <code>modified</code>, <code>flags</code>.</p>
+<h2 id="building-annotations">Building annotations<a class="heading-anchor" href="#building-annotations" aria-label="Link to this section">#</a></h2>
+<pre><code class="language-ts">import { buildAnnotation } from &#39;pdfnative&#39;;
+import type { MarkupAnnotation } from &#39;pdfnative&#39;;
+
+const note: MarkupAnnotation = {
+  type: &#39;text&#39;,
+  rect: [72, 700, 96, 724],
+  contents: &#39;Please double-check this figure.&#39;,
+  title: &#39;Reviewer&#39;,
+  icon: &#39;Comment&#39;,
+};
+
+// Full indirect object, ready to concatenate into a PDF you assemble yourself:
+const obj = buildAnnotation(note, /* objNum */ 42);
+</code></pre>
+<ul>
+<li><code>buildAnnotation(annot, objNum)</code> returns a complete <code>N 0 obj … endobj</code> string.</li>
+<li><code>buildAnnotationBody(annot)</code> returns just the dictionary body — used by the
+modifier when injecting into an existing file.</li>
+</ul>
+<p><code>/Contents</code> and <code>/T</code> are safely encoded (UTF-16BE when needed), <code>/C</code> / <code>/IC</code>
+run through <code>parseColor</code>, <code>/QuadPoints</code> are auto-derived from <code>rect</code> for the
+text-markup types, and <code>/F</code> defaults to <code>4</code> (Print).</p>
+<h2 id="reading-annotations-from-an-existing-pdf">Reading annotations from an existing PDF<a class="heading-anchor" href="#reading-annotations-from-an-existing-pdf" aria-label="Link to this section">#</a></h2>
+<pre><code class="language-ts">import { openPdf } from &#39;pdfnative&#39;;
+
+const reader = openPdf(existingBytes);
+const annots = reader.getAnnotations(0); // page index 0
+
+for (const a of annots) {
+  console.log(a.subtype, a.rect, a.contents, a.url);
+}
+</code></pre>
+<p><code>getAnnotations(pageIndex)</code> returns <code>ParsedAnnotation[]</code> with <code>subtype</code>, <code>rect</code>,
+and optional <code>contents</code> (UTF-16BE decoded), <code>title</code>, <code>color</code>, <code>quadPoints</code>, and
+<code>url</code> (for URI-action links). <code>getPageRef(pageIndex)</code> returns the page&#39;s
+indirect reference when you need it.</p>
+<h2 id="writing-annotations-into-an-existing-pdf">Writing annotations into an existing PDF<a class="heading-anchor" href="#writing-annotations-into-an-existing-pdf" aria-label="Link to this section">#</a></h2>
+<p>Add a new annotation to an existing document with a non-destructive incremental
+update:</p>
+<pre><code class="language-ts">import { openPdf, createModifier, buildAnnotationBody } from &#39;pdfnative&#39;;
+
+const reader = openPdf(existingBytes);
+const modifier = createModifier(reader);
+
+const body = buildAnnotationBody({
+  type: &#39;highlight&#39;,
+  rect: [72, 640, 300, 656],
+  color: &#39;#ffe14d&#39;,
+  contents: &#39;Key clause&#39;,
+});
+
+modifier.addAnnotation(0, body); // inject on page 0
+const updated = modifier.save();  // appended incremental section, original preserved
+</code></pre>
+<p><code>addAnnotation()</code> appends the annotation object and rewrites the page&#39;s
+<code>/Annots</code> array in an incremental update section — the original bytes are never
+mutated, so any existing signature&#39;s byte range upstream of the appended section
+stays intact.</p>
+<p><strong>Encrypted documents</strong> are supported since v1.6.0: open with
+<code>openPdf(bytes, { password })</code> and annotate as usual — the appended
+annotation objects are encrypted under the document&#39;s existing scheme
+(RC4, AES-128 and AES-256 sources), so the annotation text never appears
+in cleartext in the file.</p>
+<pre><code class="language-ts">const modifier = createModifier(openPdf(encryptedBytes, { password: &#39;secret&#39; }));
+modifier.addAnnotation(0, body);
+const updated = modifier.save(); // annotation stored encrypted
+</code></pre>
+<h2 id="sample">Sample<a class="heading-anchor" href="#sample" aria-label="Link to this section">#</a></h2>
+<p><a href="https://github.com/Nizoka/pdfnative/blob/main/scripts/generators/annotations-showcase.ts" target="_blank" rel="noopener">annotations-showcase.ts</a>
+builds a document with every annotation type, reads them back out, and injects a
+highlight into an existing PDF.</p>
+<!-- guide:render:end -->
+  </article>
+</main>
+
+<footer class="footer">
+  <div class="footer-inner">
+    <span>MIT License · © 2026 Nizoka</span>
+    <ul class="footer-links" role="list">
+      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
+      <li><a href="https://www.npmjs.com/package/pdfnative" target="_blank" rel="noopener">npm</a></li>
+      <li><a href="https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md" target="_blank" rel="noopener">Changelog</a></li>
+      <li><a href="./">All guides</a></li>
+    </ul>
+  </div>
+</footer>
+
+<script src="https://cdn.jsdelivr.net/npm/marked@12.0.2/marked.min.js" integrity="sha384-/TQbtLCAerC3jgaim+N78RZSDYV7ryeoBCVqTuzRrFec2akfBkHS7ACQ3PQhvMVi" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/dompurify@3.1.5/dist/purify.min.js" integrity="sha384-nszIONF2FGC59kn+pPFaRa6WUNGwsZgXZiJxJwQbym+TzcH7smolUviLgpPbNx7V" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/prism.min.js" integrity="sha384-BGaNxfftg+9+TtC098wxawPFVEUpKYvaiCgbB0iqAMjK/4jDdmUY+oGxrPNvnXEf" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-typescript.min.js" integrity="sha384-PeOqKNW/piETaCg8rqKFy+Pm6KEk7e36/5YZE5XO/OaFdO+/Aw3O8qZ9qDPKVUgx" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-bash.min.js" integrity="sha384-9WmlN8ABpoFSSHvBGGjhvB3E/D8UkNB9HpLJjBQFC2VSQsM1odiQDv4NbEo+7l15" crossorigin="anonymous" defer></script>
+<script src="guide.js" defer></script>
+</body>
+</html>
diff --git a/docs/guides/architecture.html b/docs/guides/architecture.html
index e58f537..076aeb1 100644
--- a/docs/guides/architecture.html
+++ b/docs/guides/architecture.html
@@ -9,6 +9,7 @@
   <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/architecture.html">
   <link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/architecture.html">
   <link rel="alternate" type="text/markdown" href="architecture.md">
+  <link rel="alternate" type="text/plain" href="../llms.txt" title="llms.txt — machine-readable documentation index">
   <meta property="og:type" content="article">
   <meta property="og:site_name" content="pdfnative">
   <meta property="og:locale" content="en_US">
@@ -26,6 +27,9 @@
   <link rel="stylesheet" href="../style.css">
   <link rel="stylesheet" href="guide.css">
   <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
+  <!-- guide:ld:start -->
+  <script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://pdfnative.dev/"},{"@type":"ListItem","position":2,"name":"Guides","item":"https://pdfnative.dev/guides/"},{"@type":"ListItem","position":3,"name":"Architecture Guide","item":"https://pdfnative.dev/guides/architecture.html"}]},{"@type":"TechArticle","headline":"Architecture Guide","description":"Architecture of pdfnative — the two builders (buildPDF table-centric and buildDocument free-form), the module map, and the strict zero-dependency, unidirectional dependency flow.","inLanguage":"en","author":{"@type":"Organization","name":"Nizoka","url":"https://github.com/Nizoka"},"publisher":{"@type":"Organization","name":"pdfnative","url":"https://pdfnative.dev","logo":{"@type":"ImageObject","url":"https://pdfnative.dev/assets/logo.svg"}},"mainEntityOfPage":{"@type":"WebPage","@id":"https://pdfnative.dev/guides/architecture.html"},"isPartOf":{"@type":"WebSite","name":"pdfnative","url":"https://pdfnative.dev"}}]}</script>
+  <!-- guide:ld:end -->
 </head>
 <body>
 
@@ -57,9 +61,176 @@
 
 <main class="guide-shell" id="main-content" tabindex="-1">
   <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; Architecture</p>
-  <article id="guide-content" class="guide-content" data-md="architecture.md">
-    <p class="guide-loading">Loading…</p>
-    <noscript><p>This guide is written in Markdown: <a href="architecture.md">read architecture.md</a>.</p></noscript>
+  <article id="guide-content" class="guide-content" data-md="architecture.md" data-prerendered="true">
+<!-- guide:render:start -->
+<h1 id="architecture-guide">Architecture Guide</h1>
+<blockquote>
+<p><strong>Two builders, one strict dependency flow.</strong> <code>buildPDFBytes</code> is the table-centric builder, <code>buildDocumentPDFBytes</code> the free-form document builder; beneath them the modules flow types → core ← fonts ← shaping ← worker, with standalone crypto and parser modules — no circular imports anywhere.</p>
+</blockquote>
+<h2 id="two-builders">Two Builders<a class="heading-anchor" href="#two-builders" aria-label="Link to this section">#</a></h2>
+<p>pdfnative provides two PDF builders for different use cases:</p>
+<h3 id="buildpdf--buildpdfbytes--table-centric"><code>buildPDF()</code> / <code>buildPDFBytes()</code> — Table-Centric<a class="heading-anchor" href="#buildpdf--buildpdfbytes--table-centric" aria-label="Link to this section">#</a></h3>
+<p>Best for: financial statements, reports, tabular data.</p>
+<pre><code class="language-typescript">import { buildPDFBytes } from &#39;pdfnative&#39;;
+
+const pdf = buildPDFBytes({
+  title: &#39;Monthly Report&#39;,
+  headers: [&#39;Date&#39;, &#39;Description&#39;, &#39;Amount&#39;],
+  rows: [
+    { cells: [&#39;01/15&#39;, &#39;Grocery&#39;, &#39;-$45.00&#39;], type: &#39;debit&#39;, pointed: false },
+  ],
+  // ... infoItems, balanceText, countText, footerText
+});
+</code></pre>
+<p>Produces a structured table layout with title, info items, balance line, column headers, data rows, and footer. Supports pagination, tagged PDF, encryption, compression.</p>
+<h3 id="builddocumentpdf--builddocumentpdfbytes--free-form"><code>buildDocumentPDF()</code> / <code>buildDocumentPDFBytes()</code> — Free-Form<a class="heading-anchor" href="#builddocumentpdf--builddocumentpdfbytes--free-form" aria-label="Link to this section">#</a></h3>
+<p>Best for: reports, manuals, invoices, any document with mixed content.</p>
+<pre><code class="language-typescript">import { buildDocumentPDFBytes } from &#39;pdfnative&#39;;
+
+const pdf = buildDocumentPDFBytes({
+  title: &#39;Project Report&#39;,
+  blocks: [
+    { type: &#39;heading&#39;, text: &#39;Introduction&#39;, level: 1 },
+    { type: &#39;paragraph&#39;, text: &#39;This report covers...&#39; },
+    { type: &#39;table&#39;, headers: [&#39;Q&#39;, &#39;Revenue&#39;], rows: [...] },
+    { type: &#39;image&#39;, data: pngBytes, width: 300 },
+    { type: &#39;barcode&#39;, format: &#39;qr&#39;, data: &#39;https://example.com&#39; },
+  ],
+});
+</code></pre>
+<p>Supports 13 block types: heading, paragraph, list, table, image, link, spacer, pageBreak, toc, barcode, svg, formField, chart.</p>
+<h2 id="generation-pipeline">Generation Pipeline<a class="heading-anchor" href="#generation-pipeline" aria-label="Link to this section">#</a></h2>
+<pre><code>Input (params + options)
+  │
+  ├─ resolveLayout()         → page dimensions, margins, column positions
+  ├─ normalizeColors()       → validate &amp; normalize color values
+  ├─ createEncodingContext()  → font encoding (WinAnsi + CIDFont)
+  │
+  ├─ Content Loop ─────────────────────────────────
+  │   ├─ Text rendering      → BT/ET operators, font selection
+  │   ├─ Image embedding     → XObject + Do operator
+  │   ├─ Barcode rendering   → PDF path operators (re f)
+  │   ├─ SVG rendering       → PDF path operators (m l c)
+  │   └─ Page breaks         → new page object
+  │
+  ├─ Font subsetting         → TTF subset per used font
+  ├─ Tagged PDF (optional)   → structure tree, /ActualText, MCID
+  ├─ PDF/A (optional)        → XMP metadata, ICC OutputIntent
+  ├─ Encryption (optional)   → AES-128/256, key derivation
+  ├─ Compression (optional)  → FlateDecode on content streams
+  │
+  └─ Assembly ─────────────────────────────────────
+      ├─ createPdfWriter()   → binary writer with offset tracking
+      ├─ Object emission     → N 0 obj ... endobj
+      └─ writeXrefTrailer()  → xref table + trailer + startxref
+</code></pre>
+<h2 id="module-dependency-flow">Module Dependency Flow<a class="heading-anchor" href="#module-dependency-flow" aria-label="Link to this section">#</a></h2>
+<pre><code>types/ → core/ ← fonts/ ← shaping/ ← worker/
+              ↑
+          crypto/ (near-standalone, imports core/pdf-encrypt for sha256)
+          parser/ (imports core/pdf-compress, pdf-encrypt, pdf-tags)
+</code></pre>
+<ul>
+<li><strong>No circular dependencies</strong> — strict unidirectional flow, with <strong>one
+sanctioned, documented reverse edge</strong>: the signature-workflow core modules
+(<code>pdf-dss</code>, <code>pdf-sig-utils</code>, <code>pdf-doc-timestamp</code>, <code>pdf-sig-placeholder</code>,
+<code>pdf-form-fill</code>) import the parser to read existing documents before
+appending incremental revisions</li>
+<li><strong>crypto/</strong> is near-standalone — its only cross-module import is <code>sha256</code> from <code>core/pdf-encrypt.ts</code> (re-exported by <code>crypto/sha.ts</code>)</li>
+<li><strong>parser/</strong> imports from <code>core/pdf-compress.ts</code> (FlateDecode), <code>core/pdf-encrypt.ts</code> (decryption, incremental <code>/ID</code>) and <code>core/pdf-tags.ts</code> (XMP resync in <code>updateMetadata</code>)</li>
+<li><strong>fonts/</strong> imports from <code>shaping/</code> for script detection</li>
+<li><strong>shaping/</strong> imports from <code>fonts/</code> encoding context (via <code>core/encoding-context.ts</code> to break cycle)</li>
+</ul>
+<h2 id="key-design-decisions">Key Design Decisions<a class="heading-anchor" href="#key-design-decisions" aria-label="Link to this section">#</a></h2>
+<table>
+<thead>
+<tr>
+<th>Decision</th>
+<th>Rationale</th>
+</tr>
+</thead>
+<tbody><tr>
+<td>No classes</td>
+<td>Pure functions — easier to test, tree-shake, and reason about</td>
+</tr>
+<tr>
+<td>String-based PDF operators</td>
+<td>Direct control over output, no AST overhead</td>
+</tr>
+<tr>
+<td>Lazy font loading</td>
+<td><code>registerFonts()</code> + <code>loadFontData()</code> — load only needed scripts</td>
+</tr>
+<tr>
+<td>Shared assembler</td>
+<td><code>pdf-assembler.ts</code> eliminates xref/trailer duplication between builders</td>
+</tr>
+<tr>
+<td>Extracted renderers</td>
+<td><code>pdf-renderers.ts</code> — block renderers, text wrapping, constants extracted from <code>pdf-document.ts</code> for maintainability. <code>planTable()</code> and <code>TableSlice</code> provide planner-driven multi-page table rendering — <code>_paginateBlocks()</code> measures once then slices at row boundaries, keeping <code>renderTable()</code> page-lifecycle-free. See <a href="tables.md">Smart tables guide</a>.</td>
+</tr>
+<tr>
+<td>Encoding context in core/</td>
+<td>Dependency inversion — breaks fonts/ → shaping/ cycle</td>
+</tr>
+</tbody></table>
+<h2 id="ecosystem">Ecosystem<a class="heading-anchor" href="#ecosystem" aria-label="Link to this section">#</a></h2>
+<p>The architecture diagram above shows the <strong>internal library modules</strong>. External consumers sit above the library and import from <code>pdfnative</code> like any npm package. Three official companion packages — a CLI, an MCP server, and a React renderer — cover the most common non-library workflows. All live in separate repositories, version independently, and depend on <code>pdfnative</code> only through its public API, so the core engine stays zero-dependency.</p>
+<pre><code>                         ┌─────────────────────────────────────────────┐
+   [shell / CI / Docker] │  pdfnative-cli (npm) — 17 commands          │
+                         └─────────────────────────────────────────────┘
+                         ┌─────────────────────────────────────────────┐
+    [Claude / Cursor / …] │  pdfnative-mcp (npm) — 28 AI tools          │
+                         └───────────────────────────────────────────┘
+                         ┌─────────────────────────────────────────────┐
+   [React / Next.js app] │  pdfnative-react (npm) — declarative JSX    │
+                         └─────────────────────────────────────────────┘
+                            │  import { … } from &#39;pdfnative&#39;  (public API only)
+                         ┌─────────────────────────────────────────────┐
+                         │  pdfnative (npm) — zero-dependency engine   │  ← this repo
+                         └─────────────────────────────────────────────┘
+</code></pre>
+<h3 id="pdfnative-cli">pdfnative-cli<a class="heading-anchor" href="#pdfnative-cli" aria-label="Link to this section">#</a></h3>
+<p><a href="https://github.com/Nizoka/pdfnative-cli" target="_blank" rel="noopener">pdfnative-cli</a> is the <strong>official command-line interface</strong>. It exposes seventeen commands — <code>render</code>, <code>fill</code>, <code>annotate</code>, <code>merge</code>, <code>split</code>, <code>extract</code>, <code>sign</code>, <code>verify</code>, <code>encrypt</code>, <code>decrypt</code>, <code>inspect</code>, <code>extract-text</code>, <code>batch</code>, <code>doctor</code>, <code>schema</code>, <code>completion</code>, <code>govern</code> — that map directly to public <code>pdfnative</code> APIs, with an agent-native <code>--json</code>/<code>E_*</code>/<code>--dry-run</code> automation contract:</p>
+<pre><code>[shell / Makefile / GitHub Actions / Docker]
+              │ argv + stdin/stdout
+     ┌──────────────────────────┐
+     │  pdfnative-cli (npm)     │  ← dispatch layer, 17 commands + agent contract
+     └──────────────────────────┘
+              │ import { buildDocumentPDFBytes, signPdfBytes, openPdf, validatePdfUA } from &#39;pdfnative&#39;
+     ┌──────────────────────────┐
+     │      pdfnative (npm)     │  ← core library (this repo)
+     └──────────────────────────┘
+</code></pre>
+<p>Like <code>pdfnative-mcp</code> and <code>pdfnative-react</code>, the CLI lives in a separate repository and depends on <code>pdfnative</code> only via the public API surface. See the <a href="cli.html">CLI Guide</a> for usage and the security model.</p>
+<h3 id="pdfnative-mcp">pdfnative-mcp<a class="heading-anchor" href="#pdfnative-mcp" aria-label="Link to this section">#</a></h3>
+<p><a href="https://github.com/Nizoka/pdfnative-mcp" target="_blank" rel="noopener">pdfnative-mcp</a> is a <strong>Model Context Protocol server</strong> that wraps the pdfnative public API and exposes it as 28 structured tools to any MCP-compatible AI client (Claude Desktop, Cursor, Continue, Zed, ChatGPT, …). It commits to API stability via a per-tool <code>_meta.apiVersion</code> field.</p>
+<pre><code>[Claude Desktop / Cursor / Continue / Zed]
+              │ MCP stdio protocol
+     ┌──────────────────────────┐
+      │  pdfnative-mcp (npm)     │  ← MCP server, 28 tools
+     └──────────────────────────┘
+              │ import { buildDocumentPDFBytes, … } from &#39;pdfnative&#39;
+     ┌──────────────────────────┐
+     │      pdfnative (npm)     │  ← core library (this repo)
+     └──────────────────────────┘
+</code></pre>
+<p>pdfnative-mcp is <strong>not an internal module</strong> — it is a separate npm package with its own repository, versioning, and release cadence. It references <code>pdfnative</code> only through the public API.</p>
+<p>For setup instructions, tool reference, and per-client configuration, see the <a href="mcp.html">MCP Integration Guide</a>.</p>
+<h3 id="pdfnative-react">pdfnative-react<a class="heading-anchor" href="#pdfnative-react" aria-label="Link to this section">#</a></h3>
+<p><a href="https://github.com/Nizoka/pdfnative-react" target="_blank" rel="noopener">pdfnative-react</a> v1.1.0 is the <strong>declarative React renderer</strong>. A custom React reconciler compiles a JSX component tree — synchronously, with no DOM — into the pdfnative <code>DocumentParams</code> model, which the engine renders to bytes:</p>
+<pre><code>[React / Next.js / Remix component tree]
+              │ custom react-reconciler (no DOM, no headless browser)
+     ┌──────────────────────────┐
+     │  pdfnative-react (npm)   │  ← &lt;Document&gt;/&lt;Table&gt;/&lt;Barcode&gt; → pdfnative blocks
+     └──────────────────────────┘
+              │ import { buildDocumentPDFBytes, … } from &#39;pdfnative&#39;
+     ┌──────────────────────────┐
+     │      pdfnative (npm)     │  ← core library (this repo)
+     └──────────────────────────┘
+</code></pre>
+<p><strong>React 19 is a peer dependency of <code>pdfnative-react</code> only</strong> — the core <code>pdfnative</code> engine remains zero-dependency. Components map 1:1 onto pdfnative blocks, and the token-frugal <code>DocSpec</code> lets AI agents author the same documents with a fraction of the tokens. See the <a href="react.html">React Guide</a> for the component reference and the <a href="../playgrounds/react.html">React playground</a> to try it in your browser.</p>
+<!-- guide:render:end -->
   </article>
 </main>
 
diff --git a/docs/guides/architecture.md b/docs/guides/architecture.md
index 5452f73..26a4a4c 100644
--- a/docs/guides/architecture.md
+++ b/docs/guides/architecture.md
@@ -1,4 +1,6 @@
 # Architecture Guide
+
+> **Two builders, one strict dependency flow.** `buildPDFBytes` is the table-centric builder, `buildDocumentPDFBytes` the free-form document builder; beneath them the modules flow types → core ← fonts ← shaping ← worker, with standalone crypto and parser modules — no circular imports anywhere.
 
 ## Two Builders
 
@@ -111,7 +113,7 @@ The architecture diagram above shows the **internal library modules**. External
    [shell / CI / Docker] │  pdfnative-cli (npm) — 17 commands          │
                          └─────────────────────────────────────────────┘
                          ┌─────────────────────────────────────────────┐
-    [Claude / Cursor / …] │  pdfnative-mcp (npm) — 24 AI tools          │
+    [Claude / Cursor / …] │  pdfnative-mcp (npm) — 28 AI tools          │
                          └───────────────────────────────────────────┘
                          ┌─────────────────────────────────────────────┐
    [React / Next.js app] │  pdfnative-react (npm) — declarative JSX    │
@@ -142,13 +144,13 @@ Like `pdfnative-mcp` and `pdfnative-react`, the CLI lives in a separate reposito
 
 ### pdfnative-mcp
 
-[pdfnative-mcp](https://github.com/Nizoka/pdfnative-mcp) is a **Model Context Protocol server** that wraps the pdfnative public API and exposes it as 24 structured tools to any MCP-compatible AI client (Claude Desktop, Cursor, Continue, Zed, ChatGPT, …). It commits to API stability via a per-tool `_meta.apiVersion` field.
+[pdfnative-mcp](https://github.com/Nizoka/pdfnative-mcp) is a **Model Context Protocol server** that wraps the pdfnative public API and exposes it as 28 structured tools to any MCP-compatible AI client (Claude Desktop, Cursor, Continue, Zed, ChatGPT, …). It commits to API stability via a per-tool `_meta.apiVersion` field.
 
 ```
 [Claude Desktop / Cursor / Continue / Zed]
               │ MCP stdio protocol
      ┌──────────────────────────┐
-      │  pdfnative-mcp (npm)     │  ← MCP server, 24 tools
+      │  pdfnative-mcp (npm)     │  ← MCP server, 28 tools
      └──────────────────────────┘
               │ import { buildDocumentPDFBytes, … } from 'pdfnative'
      ┌──────────────────────────┐
diff --git a/docs/guides/charts.html b/docs/guides/charts.html
index edd6dd6..af093be 100644
--- a/docs/guides/charts.html
+++ b/docs/guides/charts.html
@@ -4,17 +4,18 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>Charts (native vector) — pdfnative</title>
-  <meta name="description" content="Native vector charts in pdfnative — bar, horizontal-bar, line, pie, and donut chart blocks rendered as pure PDF path operators. Zero dependencies, no rasterisation, tagged /Figure alt text. New in v1.6.0.">
+  <meta name="description" content="Native vector charts in pdfnative — nine chart kinds (bar, horizontal-bar, stacked bars, line, area, scatter, pie, donut) rendered as pure PDF path operators, with a secondary axis, log &amp; time scales and data labels since v1.7.0. Zero dependencies, no rasterisation, tagged /Figure alt text.">
   <link rel="canonical" href="https://pdfnative.dev/guides/charts.html">
   <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/charts.html">
   <link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/charts.html">
   <link rel="alternate" type="text/markdown" href="charts.md">
+  <link rel="alternate" type="text/plain" href="../llms.txt" title="llms.txt — machine-readable documentation index">
   <meta property="og:type" content="article">
   <meta property="og:site_name" content="pdfnative">
   <meta property="og:locale" content="en_US">
   <meta property="og:url" content="https://pdfnative.dev/guides/charts.html">
   <meta property="og:title" content="Charts (native vector) — pdfnative">
-  <meta property="og:description" content="Bar, line, pie, and donut charts as pure PDF path operators — zero dependencies, PDF/A-safe. New in v1.6.0.">
+  <meta property="og:description" content="Nine chart kinds as pure PDF path operators — charts since v1.6.0, charts v2 (stacked, area, scatter, dual axis, log &amp; time scales) in v1.7.0. Zero dependencies, PDF/A-safe.">
   <meta property="og:image" content="https://pdfnative.dev/assets/og-image.png">
   <meta property="og:image:width" content="1200">
   <meta property="og:image:height" content="630">
@@ -26,6 +27,9 @@
   <link rel="stylesheet" href="../style.css">
   <link rel="stylesheet" href="guide.css">
   <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
+  <!-- guide:ld:start -->
+  <script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://pdfnative.dev/"},{"@type":"ListItem","position":2,"name":"Guides","item":"https://pdfnative.dev/guides/"},{"@type":"ListItem","position":3,"name":"Charts (native vector)","item":"https://pdfnative.dev/guides/charts.html"}]},{"@type":"TechArticle","headline":"Charts (native vector)","description":"Native vector charts in pdfnative — nine chart kinds (bar, horizontal-bar, stacked bars, line, area, scatter, pie, donut) rendered as pure PDF path operators, with a secondary axis, log & time scales and data labels since v1.7.0. Zero dependencies, no rasterisation, tagged /Figure alt text.","inLanguage":"en","author":{"@type":"Organization","name":"Nizoka","url":"https://github.com/Nizoka"},"publisher":{"@type":"Organization","name":"pdfnative","url":"https://pdfnative.dev","logo":{"@type":"ImageObject","url":"https://pdfnative.dev/assets/logo.svg"}},"mainEntityOfPage":{"@type":"WebPage","@id":"https://pdfnative.dev/guides/charts.html"},"isPartOf":{"@type":"WebSite","name":"pdfnative","url":"https://pdfnative.dev"}}]}</script>
+  <!-- guide:ld:end -->
 </head>
 <body>
 
@@ -57,9 +61,267 @@
 
 <main class="guide-shell" id="main-content" tabindex="-1">
   <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; Charts</p>
-  <article id="guide-content" class="guide-content" data-md="charts.md">
-    <p class="guide-loading">Loading…</p>
-    <noscript><p>This guide is written in Markdown: <a href="charts.md">read charts.md</a>.</p></noscript>
+  <article id="guide-content" class="guide-content" data-md="charts.md" data-prerendered="true">
+<!-- guide:render:start -->
+<h1 id="charts-native-vector">Charts (native vector)</h1>
+<blockquote>
+<p><strong>New in v1.6.0, extended in v1.7.0.</strong> Render bar, horizontal-bar, stacked-bar,
+line, area, scatter, pie, and donut charts as <strong>pure PDF path operators</strong> —
+rectangles, line segments, and cubic-Bézier arcs. Zero dependencies, no
+rasterisation, no image embedding. Charts are crisp at any zoom, searchable
+(labels are real text), and PDF/A-safe.</p>
+</blockquote>
+<h2 id="tldr">TL;DR<a class="heading-anchor" href="#tldr" aria-label="Link to this section">#</a></h2>
+<pre><code class="language-ts">import { buildDocumentPDFBytes } from &#39;pdfnative&#39;;
+
+const pdf = buildDocumentPDFBytes({
+  title: &#39;Report&#39;,
+  blocks: [
+    {
+      type: &#39;chart&#39;,
+      chartType: &#39;bar&#39;,
+      title: &#39;Quarterly revenue vs cost&#39;,
+      categories: [&#39;Q1&#39;, &#39;Q2&#39;, &#39;Q3&#39;, &#39;Q4&#39;],
+      series: [
+        { label: &#39;Revenue&#39;, values: [120, 150, 170, 140] },
+        { label: &#39;Cost&#39;,    values: [80, 90, 100, 95] },
+      ],
+    },
+  ],
+});
+</code></pre>
+<p>Add a <code>chart</code> block anywhere in a document&#39;s <code>blocks</code> array, like a heading,
+paragraph, or table.</p>
+<h2 id="chart-types">Chart types<a class="heading-anchor" href="#chart-types" aria-label="Link to this section">#</a></h2>
+<table>
+<thead>
+<tr>
+<th><code>chartType</code></th>
+<th>Shape</th>
+<th>Series</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>&#39;bar&#39;</code></td>
+<td>Vertical grouped bars</td>
+<td>1+</td>
+</tr>
+<tr>
+<td><code>&#39;barH&#39;</code></td>
+<td>Horizontal grouped bars</td>
+<td>1+</td>
+</tr>
+<tr>
+<td><code>&#39;line&#39;</code></td>
+<td>Multi-series line, optional markers</td>
+<td>1+</td>
+</tr>
+<tr>
+<td><code>&#39;pie&#39;</code></td>
+<td>Pie</td>
+<td>exactly 1</td>
+</tr>
+<tr>
+<td><code>&#39;donut&#39;</code></td>
+<td>Donut (pie with a hole)</td>
+<td>exactly 1</td>
+</tr>
+<tr>
+<td><code>&#39;stackedBar&#39;</code> (v1.7.0)</td>
+<td>Vertical stacked bars (positive and negative running totals stack separately)</td>
+<td>1+</td>
+</tr>
+<tr>
+<td><code>&#39;stackedBarH&#39;</code> (v1.7.0)</td>
+<td>Horizontal stacked bars</td>
+<td>1+</td>
+</tr>
+<tr>
+<td><code>&#39;area&#39;</code> (v1.7.0)</td>
+<td>Line closed to the zero baseline, opaque tinted fill</td>
+<td>1+</td>
+</tr>
+<tr>
+<td><code>&#39;scatter&#39;</code> (v1.7.0)</td>
+<td>X/Y point markers positioned by <code>xValues</code></td>
+<td>1+</td>
+</tr>
+</tbody></table>
+<h2 id="the-chartblock">The <code>ChartBlock</code><a class="heading-anchor" href="#the-chartblock" aria-label="Link to this section">#</a></h2>
+<pre><code class="language-ts">interface ChartBlock {
+  type: &#39;chart&#39;;
+  chartType: &#39;bar&#39; | &#39;barH&#39; | &#39;line&#39; | &#39;pie&#39; | &#39;donut&#39;
+    | &#39;stackedBar&#39; | &#39;stackedBarH&#39; | &#39;area&#39; | &#39;scatter&#39;;    // last four: v1.7.0
+  series: {
+    label: string;
+    values: number[];
+    color?: PdfColor;
+    xValues?: (number | string)[]; // x positions for scatter / linear / time x-axes (v1.7.0)
+    yAxis?: &#39;left&#39; | &#39;right&#39;;      // bind the series to the secondary right axis (v1.7.0)
+  }[];
+  categories?: string[];        // x-axis / slice labels; defaults to 1-based indices
+  width?: number;               // plot width in pt (clamped to content width). Default 460
+  height?: number;              // plot-area height in pt. Default 240
+  title?: string;
+  legend?: &#39;bottom&#39; | &#39;none&#39;;   // default: shown for multi-series / pie
+  axis?: { yMin?: number; yMax?: number; ticks?: number; grid?: boolean;
+           scale?: &#39;linear&#39; | &#39;log&#39; };                      // scale: v1.7.0
+  axis2?: { yMin?: number; yMax?: number; ticks?: number;
+            scale?: &#39;linear&#39; | &#39;log&#39; };                     // right value axis (v1.7.0)
+  xAxis?: { type?: &#39;category&#39; | &#39;linear&#39; | &#39;time&#39;;          // v1.7.0
+            min?: number | string; max?: number | string;
+            ticks?: number; grid?: boolean };
+  dataLabels?: boolean                                      // v1.7.0
+    | { decimals?: number; prefix?: string; suffix?: string };
+  labelStride?: number;         // draw every Nth category label. Default: auto (v1.7.0)
+  labelRotation?: number;       // rotate category labels 0–90 degrees (v1.7.0)
+  markers?: boolean;            // line only. Default false
+  colors?: PdfColor[];          // palette override (per series / per slice)
+  align?: &#39;left&#39; | &#39;center&#39; | &#39;right&#39;;
+  altText?: string;             // tagged-PDF /Figure /Alt (auto-generated if omitted)
+}
+</code></pre>
+<p>Colours accept the same forms as the rest of pdfnative — <code>&#39;#4e79a7&#39;</code>,
+<code>[78, 121, 167]</code>, or a PDF RGB string — and are validated (injection-safe). When
+omitted, a built-in 8-colour categorical palette is used deterministically.</p>
+<h2 id="examples">Examples<a class="heading-anchor" href="#examples" aria-label="Link to this section">#</a></h2>
+<h3 id="multi-series-line-with-markers">Multi-series line with markers<a class="heading-anchor" href="#multi-series-line-with-markers" aria-label="Link to this section">#</a></h3>
+<pre><code class="language-ts">{
+  type: &#39;chart&#39;, chartType: &#39;line&#39;, markers: true,
+  categories: [&#39;Jan&#39;, &#39;Feb&#39;, &#39;Mar&#39;, &#39;Apr&#39;],
+  series: [
+    { label: &#39;Free&#39;, values: [10, 25, 22, 40] },
+    { label: &#39;Paid&#39;, values: [3, 8, 12, 18] },
+  ],
+}
+</code></pre>
+<h3 id="donut-with-a-custom-palette">Donut with a custom palette<a class="heading-anchor" href="#donut-with-a-custom-palette" aria-label="Link to this section">#</a></h3>
+<pre><code class="language-ts">{
+  type: &#39;chart&#39;, chartType: &#39;donut&#39;, title: &#39;Traffic sources&#39;,
+  categories: [&#39;Organic&#39;, &#39;Referral&#39;, &#39;Direct&#39;, &#39;Social&#39;],
+  colors: [&#39;#59a14f&#39;, &#39;#4e79a7&#39;, &#39;#f28e2b&#39;, &#39;#e15759&#39;],
+  series: [{ label: &#39;Share&#39;, values: [55, 20, 15, 10] }],
+}
+</code></pre>
+<h3 id="negative-values">Negative values<a class="heading-anchor" href="#negative-values" aria-label="Link to this section">#</a></h3>
+<p>Bar and line charts anchor at a zero baseline, so negative values render below
+the axis automatically:</p>
+<pre><code class="language-ts">{ type: &#39;chart&#39;, chartType: &#39;bar&#39;, categories: [&#39;Jan&#39;, &#39;Feb&#39;, &#39;Mar&#39;],
+  series: [{ label: &#39;Net flow&#39;, values: [30, -15, 20] }] }
+</code></pre>
+<h3 id="stacked-bars-v170">Stacked bars (v1.7.0)<a class="heading-anchor" href="#stacked-bars-v170" aria-label="Link to this section">#</a></h3>
+<p>Positive and negative values stack in separate running totals per category, so
+mixed-sign data reads correctly:</p>
+<pre><code class="language-ts">{
+  type: &#39;chart&#39;, chartType: &#39;stackedBar&#39;,
+  categories: [&#39;Q1&#39;, &#39;Q2&#39;, &#39;Q3&#39;, &#39;Q4&#39;],
+  series: [
+    { label: &#39;EMEA&#39;, values: [40, 55, 60, 52] },
+    { label: &#39;APAC&#39;, values: [25, 30, 35, 41] },
+    { label: &#39;AMER&#39;, values: [50, 48, 62, 70] },
+  ],
+}
+</code></pre>
+<h3 id="area-with-data-labels-v170">Area with data labels (v1.7.0)<a class="heading-anchor" href="#area-with-data-labels-v170" aria-label="Link to this section">#</a></h3>
+<p>The area fill is the series colour mixed 35 % toward white — an <strong>opaque
+tint</strong>, not transparency, so area charts remain PDF/A-safe (PDF/A-1b forbids
+<code>/ExtGState</code> alpha):</p>
+<pre><code class="language-ts">{
+  type: &#39;chart&#39;, chartType: &#39;area&#39;,
+  categories: [&#39;Jan&#39;, &#39;Feb&#39;, &#39;Mar&#39;, &#39;Apr&#39;],
+  dataLabels: { suffix: &#39; k€&#39;, decimals: 1 },
+  series: [{ label: &#39;ARR&#39;, values: [10.4, 12.1, 13.8, 16.2] }],
+}
+</code></pre>
+<p><code>dataLabels: true</code> reuses the axis tick formatter; the object form controls
+<code>decimals</code> and adds a <code>prefix</code>/<code>suffix</code>.</p>
+<h3 id="scatter-on-a-time-axis-v170">Scatter on a time axis (v1.7.0)<a class="heading-anchor" href="#scatter-on-a-time-axis-v170" aria-label="Link to this section">#</a></h3>
+<p><code>scatter</code> positions each point by <code>xValues</code> (required). On <code>xAxis.type: &#39;time&#39;</code>,
+<code>xValues</code> accepts ISO-8601 strings or epoch milliseconds; tick positions and
+labels are computed with <strong>UTC getters only</strong> — never <code>Intl</code> or the host time
+zone — so output bytes are identical on every machine:</p>
+<pre><code class="language-ts">{
+  type: &#39;chart&#39;, chartType: &#39;scatter&#39;,
+  xAxis: { type: &#39;time&#39;, grid: true },
+  series: [{
+    label: &#39;Deploys&#39;,
+    xValues: [&#39;2026-01-05&#39;, &#39;2026-02-14&#39;, &#39;2026-03-02&#39;, &#39;2026-04-20&#39;],
+    values: [3, 7, 5, 11],
+  }],
+}
+</code></pre>
+<p><code>line</code> and <code>area</code> charts may also opt into a <code>&#39;linear&#39;</code> or <code>&#39;time&#39;</code> x-axis;
+<code>bar</code> variants stay categorical.</p>
+<h3 id="dual-value-axes--log-scale-v170">Dual value axes &amp; log scale (v1.7.0)<a class="heading-anchor" href="#dual-value-axes--log-scale-v170" aria-label="Link to this section">#</a></h3>
+<p>Bind a series to a secondary right axis with <code>yAxis: &#39;right&#39;</code> and configure its
+range with <code>axis2</code>. The right axis (and its gutter) appears only when at least
+one series binds to it. Either axis can switch to <code>scale: &#39;log&#39;</code> (decade
+ticks); log scales require strictly positive values and cannot be combined
+with stacked charts:</p>
+<pre><code class="language-ts">{
+  type: &#39;chart&#39;, chartType: &#39;line&#39;, markers: true,
+  categories: [&#39;2023&#39;, &#39;2024&#39;, &#39;2025&#39;, &#39;2026&#39;],
+  axis2: { scale: &#39;log&#39; },
+  series: [
+    { label: &#39;Revenue (k€)&#39;, values: [120, 150, 170, 140] },
+    { label: &#39;Requests/day&#39;, values: [900, 8000, 65000, 400000], yAxis: &#39;right&#39; },
+  ],
+}
+</code></pre>
+<h3 id="crowded-category-labels-v170">Crowded category labels (v1.7.0)<a class="heading-anchor" href="#crowded-category-labels-v170" aria-label="Link to this section">#</a></h3>
+<p>Long or numerous x-labels no longer collide (issue #67). By default the engine
+measures every label and draws every <em>N</em>th one — the smallest stride at which
+labels no longer overlap (<code>1</code> when everything fits, so existing charts are
+unchanged). Override with <code>labelStride</code> (<code>1</code> forces every label), or rotate
+instead:</p>
+<pre><code class="language-ts">{
+  type: &#39;chart&#39;, chartType: &#39;bar&#39;,
+  categories: [&#39;January&#39;, &#39;February&#39;, &#39;March&#39;, &#39;April&#39;, &#39;May&#39;, &#39;June&#39;],
+  labelRotation: 45,   // 0–90° counter-clockwise, right-aligned to the tick
+  series: [{ label: &#39;Signups&#39;, values: [12, 18, 14, 22, 19, 27] }],
+}
+</code></pre>
+<p>Rotated labels read upward toward their tick; setting <code>labelRotation</code> disables
+the automatic stride (rotation defeats horizontal overlap on its own) unless
+<code>labelStride</code> is also set. Both options apply to category axes only —
+<code>scatter</code> charts reject them.</p>
+<h2 id="accessibility-tagged-pdf">Accessibility (tagged PDF)<a class="heading-anchor" href="#accessibility-tagged-pdf" aria-label="Link to this section">#</a></h2>
+<p>In tagged mode (<code>{ tagged: true }</code> or a PDF/A profile), each chart is emitted as
+a <code>/Figure</code> structure element with an <code>/Alt</code> description. Provide <code>altText</code> for a
+meaningful summary; otherwise a deterministic one is generated
+(<code>&quot;bar chart: 2 series, 4 categories&quot;</code>). Charts use solid fills only — no
+transparency — so they are <strong>PDF/A-safe</strong>. That includes area charts: the fill
+is an opaque tint (series colour mixed toward white), never <code>/ExtGState</code> alpha.</p>
+<h2 id="internationalised-labels">Internationalised labels<a class="heading-anchor" href="#internationalised-labels" aria-label="Link to this section">#</a></h2>
+<p>All chart text (title, axis ticks, category labels, legend, slice percentages)
+flows through pdfnative&#39;s standard text pipeline, so CJK, Arabic/RTL, and emoji
+labels shape correctly when the matching font is registered — no extra work.</p>
+<h2 id="limits--scope-v170">Limits &amp; scope (v1.7.0)<a class="heading-anchor" href="#limits--scope-v170" aria-label="Link to this section">#</a></h2>
+<ul>
+<li><strong>In:</strong> bar, horizontal bar, stacked bar (both orientations), multi-series
+line (straight segments + optional markers), area, scatter, pie, donut;
+linear and log value axes with &quot;nice&quot;/decade ticks; secondary right value
+axis; category, linear, and time (UTC-deterministic) x-axes; gridlines;
+legend; negative values; per-point data labels; automatic label stride and
+0–90° label rotation.</li>
+<li><strong>Out (planned):</strong> curved (spline) line interpolation, error bars, bubble
+sizing, combined chart types in one plot.</li>
+<li>A hard guard rejects charts with more than <strong>10,000</strong> total data points.</li>
+<li>Validation is strict and throws before any bytes are produced: log scales
+reject non-positive values (and stacked charts), <code>scatter</code> requires
+<code>xValues</code> on every series, <code>xValues</code> lengths must match <code>values</code>,
+<code>&#39;linear&#39;</code>/<code>&#39;time&#39;</code> x-axes apply only to line/area/scatter, date strings in
+<code>xValues</code> require <code>xAxis.type: &#39;time&#39;</code>, <code>yAxis: &#39;right&#39;</code> is cartesian-only,
+and <code>labelStride</code>/<code>labelRotation</code> apply to category axes only.</li>
+</ul>
+<h2 id="see-also">See also<a class="heading-anchor" href="#see-also" aria-label="Link to this section">#</a></h2>
+<ul>
+<li><a href="tables.html">Tables</a> — tabular data blocks</li>
+<li><a href="../guides/architecture.html">SVG rendering</a> — arbitrary vector paths</li>
+<li><a href="accessibility.html">Accessibility</a> — tagged PDF / PDF-UA</li>
+<li><a href="https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md" target="_blank" rel="noopener">CHANGELOG</a></li>
+</ul>
+<!-- guide:render:end -->
   </article>
 </main>
 
diff --git a/docs/guides/choose.html b/docs/guides/choose.html
new file mode 100644
index 0000000..823eb95
--- /dev/null
+++ b/docs/guides/choose.html
@@ -0,0 +1,267 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Choosing your surface — pdfnative</title>
+  <meta name="description" content="Library, CLI, MCP or React? The pdfnative decision tree plus a verified capability × surface matrix — generate, tables, charts, signatures, LTV, encryption, forms, text extraction, page-tree editing, annotations, layout inspection and PDF/UA validation on each surface.">
+  <link rel="canonical" href="https://pdfnative.dev/guides/choose.html">
+  <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/choose.html">
+  <link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/choose.html">
+  <link rel="alternate" type="text/markdown" href="choose.md">
+  <link rel="alternate" type="text/plain" href="../llms.txt" title="llms.txt — machine-readable documentation index">
+  <meta property="og:type" content="article">
+  <meta property="og:site_name" content="pdfnative">
+  <meta property="og:locale" content="en_US">
+  <meta property="og:url" content="https://pdfnative.dev/guides/choose.html">
+  <meta property="og:title" content="Choosing your surface — pdfnative">
+  <meta property="og:description" content="Application code → library, shell/CI → CLI, AI assistant → MCP, React 19 app → React renderer — same engine, same bytes, with a verified capability matrix.">
+  <meta property="og:image" content="https://pdfnative.dev/assets/og-image.png">
+  <meta property="og:image:width" content="1200">
+  <meta property="og:image:height" content="630">
+  <meta name="twitter:card" content="summary_large_image">
+  <meta name="twitter:title" content="Choosing your surface — pdfnative">
+  <meta name="twitter:description" content="Library vs CLI vs MCP vs React — the decision tree and the capability × surface matrix, verified against the sources.">
+  <meta name="twitter:image" content="https://pdfnative.dev/assets/og-image.png">
+  <link rel="icon" type="image/svg+xml" href="../favicon.svg">
+  <link rel="stylesheet" href="../style.css">
+  <link rel="stylesheet" href="guide.css">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
+  <!-- guide:ld:start -->
+  <script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://pdfnative.dev/"},{"@type":"ListItem","position":2,"name":"Guides","item":"https://pdfnative.dev/guides/"},{"@type":"ListItem","position":3,"name":"Choosing your surface","item":"https://pdfnative.dev/guides/choose.html"}]},{"@type":"TechArticle","headline":"Choosing your surface","description":"Library, CLI, MCP or React? The pdfnative decision tree plus a verified capability × surface matrix — generate, tables, charts, signatures, LTV, encryption, forms, text extraction, page-tree editing, annotations, layout inspection and PDF/UA validation on each surface.","inLanguage":"en","author":{"@type":"Organization","name":"Nizoka","url":"https://github.com/Nizoka"},"publisher":{"@type":"Organization","name":"pdfnative","url":"https://pdfnative.dev","logo":{"@type":"ImageObject","url":"https://pdfnative.dev/assets/logo.svg"}},"mainEntityOfPage":{"@type":"WebPage","@id":"https://pdfnative.dev/guides/choose.html"},"isPartOf":{"@type":"WebSite","name":"pdfnative","url":"https://pdfnative.dev"}}]}</script>
+  <!-- guide:ld:end -->
+</head>
+<body>
+
+<a class="skip-link" href="#main-content">Skip to main content</a>
+
+<nav class="nav" role="navigation" aria-label="Main navigation">
+  <div class="nav-inner">
+    <a class="nav-brand" href="../">
+      <img src="../assets/logo.svg" alt="" width="28" height="28">
+      pdfnative
+    </a>
+    <button class="nav-hamburger" aria-label="Toggle menu" aria-expanded="false">☰</button>
+    <ul class="nav-links" role="list">
+      <li><a href="../#features">Features</a></li>
+      <li><a href="../#examples">Examples</a></li>
+      <li><a href="../#demo">Demo</a></li>
+      <li><a href="../#mcp">MCP</a></li>
+      <li><a href="../#cli">CLI</a></li>
+      <li><a href="../#react">React</a></li>
+      <li><a href="../learn/">Learn</a></li>
+      <li><a href="./">Guides</a></li>
+      <li><a href="../playgrounds/">Playgrounds</a></li>
+      <li><a href="../responsibility.html">Responsibility</a></li>
+      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
+      <li><button class="theme-toggle" aria-label="Toggle dark mode">🌙</button></li>
+    </ul>
+  </div>
+</nav>
+
+<main class="guide-shell" id="main-content" tabindex="-1">
+  <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; Choosing your surface</p>
+  <article id="guide-content" class="guide-content" data-md="choose.md" data-prerendered="true">
+<!-- guide:render:start -->
+<h1 id="choosing-your-surface">Choosing your surface</h1>
+<blockquote>
+<p><strong>Write application code → the library. Drive a shell, Makefile or CI job →
+<code>pdfnative-cli</code>. Give a conversational AI assistant tool access →
+<code>pdfnative-mcp</code>. Author documents inside a React 19 app →
+<code>pdfnative-react</code>.</strong> All four surfaces sit on the same zero-dependency
+engine and produce the same ISO 32000-1 / PDF/A-conformant bytes, so the
+choice is about <em>who is calling</em>, not about what comes out — and you can
+switch later without re-authoring your documents.</p>
+</blockquote>
+<h2 id="the-decision-in-prose">The decision, in prose<a class="heading-anchor" href="#the-decision-in-prose" aria-label="Link to this section">#</a></h2>
+<p><strong>You are writing application code</strong> — a Node.js, Deno, Bun or browser
+service, a worker, a script with logic around the PDF. Use the <strong>library</strong>
+(<code>npm install pdfnative</code>). It is the full surface: synchronous builders, the
+parser, signatures with long-term validation, streaming, Web Worker support.
+Everything the other three surfaces do, they do by calling this package.</p>
+<p><strong>You are driving a shell, a CI pipeline, a container, or a build tool in
+another language.</strong> Use the <strong>CLI</strong> (<code>pdfnative-cli</code>, binary <code>pdfnative</code>) —
+17 commands over stdin/stdout pipelines, with an agent-native automation
+contract: a <code>--json</code> envelope, stable <code>E_*</code> error codes, <code>--dry-run</code>, and
+compact <code>--summary</code> / <code>--fields</code> output projection. No JavaScript required.</p>
+<p><strong>You are (or you are building) a conversational assistant with tool
+access</strong> — Claude Desktop, Cursor, Continue, Zed, or any Model Context
+Protocol client. Use the <strong>MCP server</strong> (<code>pdfnative-mcp</code>, <code>npx -y pdfnative-mcp</code>) — 28 tools with strict JSON Schemas, read-back tools for
+self-verification, and no outbound network access except the
+operator-configured TSA/OCSP/CRL endpoints.</p>
+<p><strong>Your host application is React 19.</strong> Use the <strong>React renderer</strong>
+(<code>pdfnative-react</code>) — declarative JSX compiled on-device to pdfnative blocks
+by a custom reconciler (no DOM, no headless browser), with live-preview hooks
+and the token-frugal <code>DocSpec</code> for agent authoring. React 19 is a peer
+dependency of this package only; the engine stays zero-dependency.</p>
+<h2 id="capability--surface">Capability × surface<a class="heading-anchor" href="#capability--surface" aria-label="Link to this section">#</a></h2>
+<p>The same facts in machine-readable form live in
+<a href="../data/surfaces.json"><code>docs/data/surfaces.json</code></a>; tool, command and export
+names are verified against
+<a href="../assets/ecosystem.json"><code>docs/assets/ecosystem.json</code></a> and the engine&#39;s
+export surface by the documentation CI. Version annotations name the release
+<em>of that surface&#39;s own package</em> which introduced the capability; an em-dash
+means the surface does not offer it.</p>
+<table>
+<thead>
+<tr>
+<th>Capability</th>
+<th>Library (<code>pdfnative</code>)</th>
+<th>CLI (<code>pdfnative-cli</code>)</th>
+<th>MCP (<code>pdfnative-mcp</code>)</th>
+<th>React (<code>pdfnative-react</code>)</th>
+</tr>
+</thead>
+<tbody><tr>
+<td>Generate documents</td>
+<td><code>buildDocumentPDFBytes</code> / <code>buildPDFBytes</code></td>
+<td><code>render</code></td>
+<td><code>generate_basic_pdf</code> (+ the dedicated document tools)</td>
+<td><code>renderToBytes</code> and friends, <code>&lt;Document&gt;</code> tree</td>
+</tr>
+<tr>
+<td>Smart tables</td>
+<td><code>table</code> block</td>
+<td><code>render</code> (<code>table</code> block, or <code>--variant table</code>)</td>
+<td><code>add_table</code></td>
+<td><code>&lt;Table&gt;</code></td>
+</tr>
+<tr>
+<td>Native vector charts</td>
+<td><code>chart</code> block <em>(v1.6.0)</em></td>
+<td><code>render</code> (<code>chart</code> block) <em>(v1.3.0)</em></td>
+<td><code>add_chart</code> <em>(v1.5.0)</em></td>
+<td><code>&lt;Chart&gt;</code> <em>(v1.1.0)</em></td>
+</tr>
+<tr>
+<td>Digital signatures (PAdES CMS)</td>
+<td><code>addSignaturePlaceholder</code> <em>(v1.2.0)</em> + <code>signPdfBytes</code></td>
+<td><code>sign</code></td>
+<td><code>sign_pdf</code> (+ <code>prepare_signature_placeholder</code>)</td>
+<td>—</td>
+</tr>
+<tr>
+<td>LTV ladder (B-T → B-LTA)</td>
+<td><code>signPdfBytesWithTimestamp</code>, <code>addValidationInfo</code>, <code>addDocumentTimestamp</code> <em>(v1.7.0)</em></td>
+<td>— (verification only: <code>verify --revocation</code>)</td>
+<td><code>add_ltv</code>, <code>timestamp_pdf</code> <em>(v1.6.0)</em></td>
+<td>—</td>
+</tr>
+<tr>
+<td>Encrypt / decrypt</td>
+<td>build-time <code>encryption</code> layout option; existing PDFs via the page-tree <code>encrypt</code> option and <code>openPdf</code> with a password</td>
+<td><code>encrypt</code> / <code>decrypt</code> <em>(v1.3.0)</em></td>
+<td><code>encrypt_pdf</code> / <code>decrypt_pdf</code> <em>(v1.5.0)</em></td>
+<td>build-time only, via the <code>layout</code> render option</td>
+</tr>
+<tr>
+<td>Fill / flatten forms</td>
+<td><code>readFormFields</code>, <code>fillForm</code>, <code>flattenForm</code> <em>(v1.6.0)</em></td>
+<td><code>fill</code> <em>(v1.3.0)</em></td>
+<td><code>read_form_fields</code>, <code>fill_form</code> <em>(v1.5.0)</em></td>
+<td>—</td>
+</tr>
+<tr>
+<td>Extract text</td>
+<td><code>extractText</code> <em>(v1.6.0)</em></td>
+<td><code>extract-text</code> <em>(v1.3.0)</em></td>
+<td><code>extract_text</code></td>
+<td>—</td>
+</tr>
+<tr>
+<td>Merge / split / extract pages</td>
+<td><code>mergePdfs</code>, <code>splitPdf</code>, <code>extractPages</code> <em>(v1.4.0)</em></td>
+<td><code>merge</code> / <code>split</code> / <code>extract</code> <em>(v1.2.0)</em></td>
+<td><code>merge_pdfs</code> / <code>split_pdf</code> / <code>extract_pages</code> <em>(v1.3.0)</em></td>
+<td>—</td>
+</tr>
+<tr>
+<td>Markup annotations</td>
+<td><code>buildAnnotation</code> + <code>PdfModifier.addAnnotation</code> <em>(v1.5.0)</em></td>
+<td><code>annotate</code> <em>(v1.2.0)</em></td>
+<td><code>annotate_pdf</code> <em>(v1.4.0)</em></td>
+<td>—</td>
+</tr>
+<tr>
+<td>Inspect layout (pagination dry run)</td>
+<td><code>inspectDocumentLayout</code> <em>(v1.5.0)</em></td>
+<td><code>render --inspect-layout</code> <em>(v1.2.0)</em></td>
+<td><code>inspect_layout</code> <em>(v1.6.0)</em></td>
+<td><code>inspectDocument</code></td>
+</tr>
+<tr>
+<td>Validate PDF/UA</td>
+<td><code>validatePdfUA</code> <em>(v1.3.0)</em></td>
+<td><code>inspect --pdfua</code> <em>(v1.1.0)</em></td>
+<td><code>validate_pdf</code> <em>(v1.1.0)</em></td>
+<td>— (<code>lintDocument</code> checks the authoring model before rendering, not the emitted PDF)</td>
+</tr>
+</tbody></table>
+<h2 id="honest-notes">Honest notes<a class="heading-anchor" href="#honest-notes" aria-label="Link to this section">#</a></h2>
+<ul>
+<li><strong>LTV differs by surface on purpose.</strong> The engine opens no socket: in the
+<strong>library</strong>, the RFC 3161 / OCSP / CRL transport is <em>injected by your code</em>
+(<code>setTimestampProvider</code> / <code>setRevocationProvider</code>). On <strong>MCP</strong>, the transport
+is <em>operator-configured</em> through environment variables
+(<code>PDFNATIVE_MCP_TSA_URL</code>, <code>PDFNATIVE_MCP_REVOCATION</code>, an allow-list) — never
+from tool arguments. The <strong>CLI</strong> currently <em>verifies</em> LTV material
+(<code>verify --revocation</code>, RFC 3161 timestamp validation) but does not create
+it — sign-side LTV is documented as out of scope there.</li>
+<li><strong>The engine ships no cryptographic signature verifier.</strong> <code>listSignatures</code>
+is an inventory; full verification (digest, CMS, chain, trust, timestamps,
+revocation) lives in <code>pdfnative-cli verify</code> and the MCP <code>verify_pdf</code> tool.</li>
+<li><strong>React is an authoring surface.</strong> It generates documents (including charts,
+barcodes, SVG, form <em>widgets</em> and build-time encryption via the <code>layout</code>
+render option) but does not operate on existing PDFs — no fill, extract,
+merge or signing. When a React app needs those, call the library directly:
+it is already installed as the renderer&#39;s peer dependency.</li>
+<li><strong>The MCP tool names, CLI commands and library exports in the table are the
+complete story for these capabilities</strong>, not a sample — where a cell is an
+em-dash, the surface genuinely lacks the capability today rather than
+hiding it under another name.</li>
+</ul>
+<h2 id="you-can-switch-later">You can switch later<a class="heading-anchor" href="#you-can-switch-later" aria-label="Link to this section">#</a></h2>
+<p>All four surfaces call the same engine, so the artefacts are interchangeable:
+a PDF rendered by the React reconciler can be signed by the CLI, inspected by
+an MCP tool, and have its text extracted by the library. Document <em>inputs</em>
+travel too — the CLI&#39;s <code>render</code> consumes the same <code>DocumentParams</code> JSON the
+library takes, the MCP <code>generate_basic_pdf</code> blocks mirror the engine&#39;s block
+kinds, and <code>pdfnative-react</code> compiles JSX (or a <code>DocSpec</code>) into that same
+model. Starting on the &quot;wrong&quot; surface costs a call-site migration, not a
+document rewrite.</p>
+<h2 id="further-reading">Further reading<a class="heading-anchor" href="#further-reading" aria-label="Link to this section">#</a></h2>
+<ul>
+<li><a href="onboarding.html">Onboarding</a> — the 90-second install-and-first-call for
+each surface.</li>
+<li><a href="self-verify.html">Self-verifying generation</a> — the generate → inspect →
+assert → correct loop on every surface.</li>
+<li><a href="architecture.html">Architecture</a> — how the four packages relate.</li>
+<li><a href="cli.html">CLI guide</a> · <a href="mcp.html">MCP guide</a> · <a href="react.html">React guide</a> —
+the complete per-surface references.</li>
+<li><a href="../agent-brief.md">Agent brief</a> — the same decision tree in
+paste-into-context form for AI agents.</li>
+</ul>
+<!-- guide:render:end -->
+  </article>
+</main>
+
+<footer class="footer">
+  <div class="footer-inner">
+    <span>MIT License · © 2026 Nizoka</span>
+    <ul class="footer-links" role="list">
+      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
+      <li><a href="https://www.npmjs.com/package/pdfnative" target="_blank" rel="noopener">npm</a></li>
+      <li><a href="https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md" target="_blank" rel="noopener">Changelog</a></li>
+      <li><a href="./">All guides</a></li>
+    </ul>
+  </div>
+</footer>
+
+<script src="https://cdn.jsdelivr.net/npm/marked@12.0.2/marked.min.js" integrity="sha384-/TQbtLCAerC3jgaim+N78RZSDYV7ryeoBCVqTuzRrFec2akfBkHS7ACQ3PQhvMVi" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/dompurify@3.1.5/dist/purify.min.js" integrity="sha384-nszIONF2FGC59kn+pPFaRa6WUNGwsZgXZiJxJwQbym+TzcH7smolUviLgpPbNx7V" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/prism.min.js" integrity="sha384-BGaNxfftg+9+TtC098wxawPFVEUpKYvaiCgbB0iqAMjK/4jDdmUY+oGxrPNvnXEf" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-typescript.min.js" integrity="sha384-PeOqKNW/piETaCg8rqKFy+Pm6KEk7e36/5YZE5XO/OaFdO+/Aw3O8qZ9qDPKVUgx" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-bash.min.js" integrity="sha384-9WmlN8ABpoFSSHvBGGjhvB3E/D8UkNB9HpLJjBQFC2VSQsM1odiQDv4NbEo+7l15" crossorigin="anonymous" defer></script>
+<script src="guide.js" defer></script>
+</body>
+</html>
diff --git a/docs/guides/choose.md b/docs/guides/choose.md
new file mode 100644
index 0000000..66f5c4c
--- /dev/null
+++ b/docs/guides/choose.md
@@ -0,0 +1,107 @@
+# Choosing your surface
+
+> **Write application code → the library. Drive a shell, Makefile or CI job →
+> `pdfnative-cli`. Give a conversational AI assistant tool access →
+> `pdfnative-mcp`. Author documents inside a React 19 app →
+> `pdfnative-react`.** All four surfaces sit on the same zero-dependency
+> engine and produce the same ISO 32000-1 / PDF/A-conformant bytes, so the
+> choice is about *who is calling*, not about what comes out — and you can
+> switch later without re-authoring your documents.
+
+## The decision, in prose
+
+**You are writing application code** — a Node.js, Deno, Bun or browser
+service, a worker, a script with logic around the PDF. Use the **library**
+(`npm install pdfnative`). It is the full surface: synchronous builders, the
+parser, signatures with long-term validation, streaming, Web Worker support.
+Everything the other three surfaces do, they do by calling this package.
+
+**You are driving a shell, a CI pipeline, a container, or a build tool in
+another language.** Use the **CLI** (`pdfnative-cli`, binary `pdfnative`) —
+17 commands over stdin/stdout pipelines, with an agent-native automation
+contract: a `--json` envelope, stable `E_*` error codes, `--dry-run`, and
+compact `--summary` / `--fields` output projection. No JavaScript required.
+
+**You are (or you are building) a conversational assistant with tool
+access** — Claude Desktop, Cursor, Continue, Zed, or any Model Context
+Protocol client. Use the **MCP server** (`pdfnative-mcp`, `npx -y
+pdfnative-mcp`) — 28 tools with strict JSON Schemas, read-back tools for
+self-verification, and no outbound network access except the
+operator-configured TSA/OCSP/CRL endpoints.
+
+**Your host application is React 19.** Use the **React renderer**
+(`pdfnative-react`) — declarative JSX compiled on-device to pdfnative blocks
+by a custom reconciler (no DOM, no headless browser), with live-preview hooks
+and the token-frugal `DocSpec` for agent authoring. React 19 is a peer
+dependency of this package only; the engine stays zero-dependency.
+
+## Capability × surface
+
+The same facts in machine-readable form live in
+[`docs/data/surfaces.json`](../data/surfaces.json); tool, command and export
+names are verified against
+[`docs/assets/ecosystem.json`](../assets/ecosystem.json) and the engine's
+export surface by the documentation CI. Version annotations name the release
+*of that surface's own package* which introduced the capability; an em-dash
+means the surface does not offer it.
+
+| Capability | Library (`pdfnative`) | CLI (`pdfnative-cli`) | MCP (`pdfnative-mcp`) | React (`pdfnative-react`) |
+|---|---|---|---|---|
+| Generate documents | `buildDocumentPDFBytes` / `buildPDFBytes` | `render` | `generate_basic_pdf` (+ the dedicated document tools) | `renderToBytes` and friends, `<Document>` tree |
+| Smart tables | `table` block | `render` (`table` block, or `--variant table`) | `add_table` | `<Table>` |
+| Native vector charts | `chart` block _(v1.6.0)_ | `render` (`chart` block) _(v1.3.0)_ | `add_chart` _(v1.5.0)_ | `<Chart>` _(v1.1.0)_ |
+| Digital signatures (PAdES CMS) | `addSignaturePlaceholder` _(v1.2.0)_ + `signPdfBytes` | `sign` | `sign_pdf` (+ `prepare_signature_placeholder`) | — |
+| LTV ladder (B-T → B-LTA) | `signPdfBytesWithTimestamp`, `addValidationInfo`, `addDocumentTimestamp` _(v1.7.0)_ | — (verification only: `verify --revocation`) | `add_ltv`, `timestamp_pdf` _(v1.6.0)_ | — |
+| Encrypt / decrypt | build-time `encryption` layout option; existing PDFs via the page-tree `encrypt` option and `openPdf` with a password | `encrypt` / `decrypt` _(v1.3.0)_ | `encrypt_pdf` / `decrypt_pdf` _(v1.5.0)_ | build-time only, via the `layout` render option |
+| Fill / flatten forms | `readFormFields`, `fillForm`, `flattenForm` _(v1.6.0)_ | `fill` _(v1.3.0)_ | `read_form_fields`, `fill_form` _(v1.5.0)_ | — |
+| Extract text | `extractText` _(v1.6.0)_ | `extract-text` _(v1.3.0)_ | `extract_text` | — |
+| Merge / split / extract pages | `mergePdfs`, `splitPdf`, `extractPages` _(v1.4.0)_ | `merge` / `split` / `extract` _(v1.2.0)_ | `merge_pdfs` / `split_pdf` / `extract_pages` _(v1.3.0)_ | — |
+| Markup annotations | `buildAnnotation` + `PdfModifier.addAnnotation` _(v1.5.0)_ | `annotate` _(v1.2.0)_ | `annotate_pdf` _(v1.4.0)_ | — |
+| Inspect layout (pagination dry run) | `inspectDocumentLayout` _(v1.5.0)_ | `render --inspect-layout` _(v1.2.0)_ | `inspect_layout` _(v1.6.0)_ | `inspectDocument` |
+| Validate PDF/UA | `validatePdfUA` _(v1.3.0)_ | `inspect --pdfua` _(v1.1.0)_ | `validate_pdf` _(v1.1.0)_ | — (`lintDocument` checks the authoring model before rendering, not the emitted PDF) |
+
+## Honest notes
+
+- **LTV differs by surface on purpose.** The engine opens no socket: in the
+  **library**, the RFC 3161 / OCSP / CRL transport is *injected by your code*
+  (`setTimestampProvider` / `setRevocationProvider`). On **MCP**, the transport
+  is *operator-configured* through environment variables
+  (`PDFNATIVE_MCP_TSA_URL`, `PDFNATIVE_MCP_REVOCATION`, an allow-list) — never
+  from tool arguments. The **CLI** currently *verifies* LTV material
+  (`verify --revocation`, RFC 3161 timestamp validation) but does not create
+  it — sign-side LTV is documented as out of scope there.
+- **The engine ships no cryptographic signature verifier.** `listSignatures`
+  is an inventory; full verification (digest, CMS, chain, trust, timestamps,
+  revocation) lives in `pdfnative-cli verify` and the MCP `verify_pdf` tool.
+- **React is an authoring surface.** It generates documents (including charts,
+  barcodes, SVG, form *widgets* and build-time encryption via the `layout`
+  render option) but does not operate on existing PDFs — no fill, extract,
+  merge or signing. When a React app needs those, call the library directly:
+  it is already installed as the renderer's peer dependency.
+- **The MCP tool names, CLI commands and library exports in the table are the
+  complete story for these capabilities**, not a sample — where a cell is an
+  em-dash, the surface genuinely lacks the capability today rather than
+  hiding it under another name.
+
+## You can switch later
+
+All four surfaces call the same engine, so the artefacts are interchangeable:
+a PDF rendered by the React reconciler can be signed by the CLI, inspected by
+an MCP tool, and have its text extracted by the library. Document *inputs*
+travel too — the CLI's `render` consumes the same `DocumentParams` JSON the
+library takes, the MCP `generate_basic_pdf` blocks mirror the engine's block
+kinds, and `pdfnative-react` compiles JSX (or a `DocSpec`) into that same
+model. Starting on the "wrong" surface costs a call-site migration, not a
+document rewrite.
+
+## Further reading
+
+- [Onboarding](onboarding.html) — the 90-second install-and-first-call for
+  each surface.
+- [Self-verifying generation](self-verify.html) — the generate → inspect →
+  assert → correct loop on every surface.
+- [Architecture](architecture.html) — how the four packages relate.
+- [CLI guide](cli.html) · [MCP guide](mcp.html) · [React guide](react.html) —
+  the complete per-surface references.
+- [Agent brief](../agent-brief.md) — the same decision tree in
+  paste-into-context form for AI agents.
diff --git a/docs/guides/cli.html b/docs/guides/cli.html
index 5898770..f21a552 100644
--- a/docs/guides/cli.html
+++ b/docs/guides/cli.html
@@ -1,86 +1,2058 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>pdfnative-cli — Command-Line Interface Guide</title>
-  <meta name="description" content="Official CLI for pdfnative — render JSON to PDF, sign with RSA or ECDSA-SHA256, inspect, and verify CMS/PKCS#7 signatures. Streaming, PDF/A, stdin/stdout.">
-  <meta name="robots" content="index, follow">
-  <link rel="canonical" href="https://pdfnative.dev/guides/cli.html">
-  <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/cli.html">
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>pdfnative-cli — Command-Line Interface Guide</title>
+  <meta name="description" content="Official CLI for pdfnative — 17 commands: render, fill, annotate, merge/split/extract, sign, verify (CMS + RFC 3161 timestamps + OCSP/CRL revocation), encrypt, decrypt, inspect, extract-text, batch, doctor, schema, completion, govern. Streaming, PDF/A, stdin/stdout.">
+  <meta name="robots" content="index, follow">
+  <link rel="canonical" href="https://pdfnative.dev/guides/cli.html">
+  <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/cli.html">
   <link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/cli.html">
-  <link rel="alternate" type="text/markdown" href="cli.md">
-  <meta property="og:type" content="article">
-  <meta property="og:site_name" content="pdfnative">
+  <link rel="alternate" type="text/markdown" href="cli.md">
+  <link rel="alternate" type="text/plain" href="../llms.txt" title="llms.txt — machine-readable documentation index">
+  <meta property="og:type" content="article">
+  <meta property="og:site_name" content="pdfnative">
   <meta property="og:locale" content="en_US">
-  <meta property="og:url" content="https://pdfnative.dev/guides/cli.html">
-  <meta property="og:title" content="pdfnative-cli — Command-Line Interface Guide">
-  <meta property="og:description" content="Official CLI for pdfnative — render JSON to PDF, sign with RSA or ECDSA-SHA256, inspect, and verify CMS/PKCS#7 signatures. Zero extra runtime dependencies, streaming, PDF/A, stdin/stdout pipelines.">
-  <meta property="og:image" content="https://pdfnative.dev/assets/og-image.png">
-  <meta property="og:image:width" content="1200">
-  <meta property="og:image:height" content="630">
-  <meta name="twitter:card" content="summary_large_image">
-  <meta name="twitter:title" content="pdfnative-cli — Command-Line Interface Guide">
-  <meta name="twitter:description" content="Render, sign, inspect, and verify PDFs from the terminal. Zero extra runtime dependencies, streaming, PDF/A, stdin/stdout pipelines.">
-  <meta name="twitter:image" content="https://pdfnative.dev/assets/og-image.png">
-  <link rel="icon" type="image/svg+xml" href="../favicon.svg">
-  <link rel="stylesheet" href="../style.css">
-  <link rel="stylesheet" href="guide.css">
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
-</head>
-<body>
-
-<a class="skip-link" href="#main-content">Skip to main content</a>
-
-<nav class="nav" role="navigation" aria-label="Main navigation">
-  <div class="nav-inner">
-    <a class="nav-brand" href="../">
-      <img src="../assets/logo.svg" alt="" width="28" height="28">
-      pdfnative
-    </a>
-    <button class="nav-hamburger" aria-label="Toggle menu" aria-expanded="false">☰</button>
-    <ul class="nav-links" role="list">
-      <li><a href="../#features">Features</a></li>
-      <li><a href="../#examples">Examples</a></li>
-      <li><a href="../#demo">Demo</a></li>
-      <li><a href="../#mcp">MCP</a></li>
-      <li><a href="../#cli">CLI</a></li>
-      <li><a href="../learn/">Learn</a></li>
-      <li><a href="./">Guides</a></li>
-      <li><a href="../playgrounds/">Playgrounds</a></li>
-      <li><a href="../responsibility.html">Responsibility</a></li>
-      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
-      <li><button class="theme-toggle" aria-label="Toggle dark mode">🌙</button></li>
-    </ul>
-  </div>
-</nav>
-
-<main class="guide-shell" id="main-content" tabindex="-1">
-  <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; CLI</p>
-  <article id="guide-content" class="guide-content" data-md="cli.md">
-    <p class="guide-loading">Loading…</p>
-    <noscript><p>This guide is written in Markdown: <a href="cli.md">read cli.md</a>.</p></noscript>
-  </article>
-</main>
-
-<footer class="footer">
-  <div class="footer-inner">
-    <span>MIT License · © 2026 Nizoka</span>
-    <ul class="footer-links" role="list">
-      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
-      <li><a href="https://www.npmjs.com/package/pdfnative" target="_blank" rel="noopener">npm</a></li>
-      <li><a href="https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md" target="_blank" rel="noopener">Changelog</a></li>
-      <li><a href="./">All guides</a></li>
-    </ul>
-  </div>
-</footer>
-
-<script src="https://cdn.jsdelivr.net/npm/marked@12.0.2/marked.min.js" integrity="sha384-/TQbtLCAerC3jgaim+N78RZSDYV7ryeoBCVqTuzRrFec2akfBkHS7ACQ3PQhvMVi" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/dompurify@3.1.5/dist/purify.min.js" integrity="sha384-nszIONF2FGC59kn+pPFaRa6WUNGwsZgXZiJxJwQbym+TzcH7smolUviLgpPbNx7V" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/prism.min.js" integrity="sha384-BGaNxfftg+9+TtC098wxawPFVEUpKYvaiCgbB0iqAMjK/4jDdmUY+oGxrPNvnXEf" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-typescript.min.js" integrity="sha384-PeOqKNW/piETaCg8rqKFy+Pm6KEk7e36/5YZE5XO/OaFdO+/Aw3O8qZ9qDPKVUgx" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-bash.min.js" integrity="sha384-9WmlN8ABpoFSSHvBGGjhvB3E/D8UkNB9HpLJjBQFC2VSQsM1odiQDv4NbEo+7l15" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-json.min.js" integrity="sha384-RhrmFFMb0ZCHImjFMpR/UE3VEtIVTCtNrtKQqXCzqXZNJala02N3UbVhi+qzw3CY" crossorigin="anonymous" defer></script>
-<script src="guide.js" defer></script>
-</body>
-</html>
+  <meta property="og:url" content="https://pdfnative.dev/guides/cli.html">
+  <meta property="og:title" content="pdfnative-cli — Command-Line Interface Guide">
+  <meta property="og:description" content="Official CLI for pdfnative — 17 commands covering the full document lifecycle, incl. fill, encrypt/decrypt, extract-text and doctor (v1.3.0), with verify doing CMS + RFC 3161 + OCSP/CRL. Zero extra runtime dependencies, streaming, PDF/A, stdin/stdout pipelines.">
+  <meta property="og:image" content="https://pdfnative.dev/assets/og-image.png">
+  <meta property="og:image:width" content="1200">
+  <meta property="og:image:height" content="630">
+  <meta name="twitter:card" content="summary_large_image">
+  <meta name="twitter:title" content="pdfnative-cli — Command-Line Interface Guide">
+  <meta name="twitter:description" content="Render, sign, inspect, and verify PDFs from the terminal. Zero extra runtime dependencies, streaming, PDF/A, stdin/stdout pipelines.">
+  <meta name="twitter:image" content="https://pdfnative.dev/assets/og-image.png">
+  <link rel="icon" type="image/svg+xml" href="../favicon.svg">
+  <link rel="stylesheet" href="../style.css">
+  <link rel="stylesheet" href="guide.css">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
+  <!-- guide:ld:start -->
+  <script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://pdfnative.dev/"},{"@type":"ListItem","position":2,"name":"Guides","item":"https://pdfnative.dev/guides/"},{"@type":"ListItem","position":3,"name":"pdfnative-cli — Command-Line Interface Guide","item":"https://pdfnative.dev/guides/cli.html"}]},{"@type":"TechArticle","headline":"pdfnative-cli — Command-Line Interface Guide","description":"Official CLI for pdfnative — 17 commands: render, fill, annotate, merge/split/extract, sign, verify (CMS + RFC 3161 timestamps + OCSP/CRL revocation), encrypt, decrypt, inspect, extract-text, batch, doctor, schema, completion, govern. Streaming, PDF/A, stdin/stdout.","inLanguage":"en","author":{"@type":"Organization","name":"Nizoka","url":"https://github.com/Nizoka"},"publisher":{"@type":"Organization","name":"pdfnative","url":"https://pdfnative.dev","logo":{"@type":"ImageObject","url":"https://pdfnative.dev/assets/logo.svg"}},"mainEntityOfPage":{"@type":"WebPage","@id":"https://pdfnative.dev/guides/cli.html"},"isPartOf":{"@type":"WebSite","name":"pdfnative","url":"https://pdfnative.dev"}}]}</script>
+  <!-- guide:ld:end -->
+</head>
+<body>
+
+<a class="skip-link" href="#main-content">Skip to main content</a>
+
+<nav class="nav" role="navigation" aria-label="Main navigation">
+  <div class="nav-inner">
+    <a class="nav-brand" href="../">
+      <img src="../assets/logo.svg" alt="" width="28" height="28">
+      pdfnative
+    </a>
+    <button class="nav-hamburger" aria-label="Toggle menu" aria-expanded="false">☰</button>
+    <ul class="nav-links" role="list">
+      <li><a href="../#features">Features</a></li>
+      <li><a href="../#examples">Examples</a></li>
+      <li><a href="../#demo">Demo</a></li>
+      <li><a href="../#mcp">MCP</a></li>
+      <li><a href="../#cli">CLI</a></li>
+      <li><a href="../learn/">Learn</a></li>
+      <li><a href="./">Guides</a></li>
+      <li><a href="../playgrounds/">Playgrounds</a></li>
+      <li><a href="../responsibility.html">Responsibility</a></li>
+      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
+      <li><button class="theme-toggle" aria-label="Toggle dark mode">🌙</button></li>
+    </ul>
+  </div>
+</nav>
+
+<main class="guide-shell" id="main-content" tabindex="-1">
+  <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; CLI</p>
+  <article id="guide-content" class="guide-content" data-md="cli.md" data-prerendered="true">
+<!-- guide:render:start -->
+<h1 id="pdfnative-cli--command-line-interface-guide">pdfnative-cli — Command-Line Interface Guide</h1>
+<blockquote>
+<p><strong>Tracks the latest published <code>pdfnative-cli</code></strong> (v1.3.0, built on the pdfnative 1.6 engine — pins <code>^1.6.0</code>, which semver-accepts 1.7.0). The CLI versions independently from the library. Live package versions — and the <code>pdfnative</code> version each one is built on — are shown at the top of the <a href="../index.html">documentation home</a>. Full history: <a href="https://github.com/Nizoka/pdfnative-cli/releases" target="_blank" rel="noopener">pdfnative-cli releases</a>.</p>
+</blockquote>
+<p><a href="https://github.com/Nizoka/pdfnative-cli" target="_blank" rel="noopener"><code>pdfnative-cli</code></a> is the <strong>official command-line interface</strong> for the <a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener"><code>pdfnative</code></a> library. It exposes 17 commands in five groups — create &amp; edit (<code>render</code>, <code>fill</code>, <code>annotate</code>), page tree (<code>merge</code>, <code>split</code>, <code>extract</code>), security (<code>sign</code>, <code>verify</code>, <code>encrypt</code>, <code>decrypt</code>), read &amp; extract (<code>inspect</code>, <code>extract-text</code>), and automation &amp; meta (<code>batch</code>, <code>doctor</code>, <code>schema</code>, <code>completion</code>, <code>govern</code>) — that together cover the full document lifecycle from JSON to a signed, verified, archive-grade PDF, plus page-tree editing, markup annotations, and an AI-governance gate, with an agent-native automation contract for autonomous AI and CI pipelines.</p>
+<blockquote>
+<p><strong>Why a CLI?</strong> Many real-world workflows live outside Node.js: shell scripts, CI pipelines, Docker containers, Makefiles, batch jobs, build tools written in other languages. The CLI lets all of them call <code>pdfnative</code> without writing JavaScript, and is fully composable through stdin/stdout pipelines.</p>
+</blockquote>
+<p>The CLI is a <strong>pure dispatch layer</strong> over <code>pdfnative</code>. No PDF logic lives in the CLI itself — every command forwards to a public <code>pdfnative</code> API:</p>
+<table>
+<thead>
+<tr>
+<th>CLI command</th>
+<th><code>pdfnative</code> API</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>render</code></td>
+<td><code>buildDocumentPDFBytes()</code> / <code>buildDocumentPDFStream()</code> / <code>buildDocumentPDFStreamTrue()</code> / <code>buildPDFBytes()</code> (table variant = <code>buildPDFBytes</code>, the table-centric builder; document variant = <code>buildDocumentPDFBytes</code>, the free-form block builder)</td>
+</tr>
+<tr>
+<td><code>fill</code></td>
+<td><code>readFormFields()</code> / <code>fillForm()</code> / <code>flattenForm()</code></td>
+</tr>
+<tr>
+<td><code>encrypt</code> / <code>decrypt</code></td>
+<td><code>openPdf(bytes, { password })</code> + <code>MergeOptions.encrypt</code></td>
+</tr>
+<tr>
+<td><code>extract-text</code></td>
+<td><code>extractText()</code></td>
+</tr>
+<tr>
+<td><code>doctor</code></td>
+<td>— (environment probe, no library equivalent)</td>
+</tr>
+<tr>
+<td><code>sign</code></td>
+<td><code>signPdfBytes()</code> / <code>addSignaturePlaceholder()</code> — the native constant-time provider is implemented in the CLI (<code>createNativeCryptoProvider</code> is a CLI utility, not a pdfnative API) and passed per call as <code>options.provider</code> (pdfnative also exposes a global <code>setCryptoProvider()</code>, which the CLI does not use)</td>
+</tr>
+<tr>
+<td><code>inspect</code></td>
+<td><code>openPdf()</code> / <code>getInfo()</code> / <code>pageCount</code> / <code>getPageLabels()</code> / <code>getAnnotations()</code> / <code>validatePdfUA()</code></td>
+</tr>
+<tr>
+<td><code>verify</code></td>
+<td><code>openPdf()</code> + <code>verifyCertSignature()</code> (X.509 certificate-signature checks); the CMS/PKCS#7, RFC 3161 timestamp and OCSP/CRL revocation verification is implemented in the CLI itself</td>
+</tr>
+<tr>
+<td><code>merge</code></td>
+<td><code>mergePdfs()</code></td>
+</tr>
+<tr>
+<td><code>split</code></td>
+<td><code>splitPdf()</code></td>
+</tr>
+<tr>
+<td><code>extract</code></td>
+<td><code>extractPages()</code></td>
+</tr>
+<tr>
+<td><code>annotate</code></td>
+<td><code>PdfModifier.addAnnotation()</code> / <code>buildAnnotationBody()</code></td>
+</tr>
+<tr>
+<td><code>govern</code></td>
+<td>AI-governance contract (<code>.github/ai-governance.json</code>, <code>AGENT_RULES.md</code>) — draft gating uses the CLI&#39;s own <code>validateGovernanceDraft()</code> (the core repo&#39;s equivalent check is a repo script, not a published API)</td>
+</tr>
+<tr>
+<td><code>batch</code></td>
+<td>the <code>render</code> pipeline, applied in parallel across a directory</td>
+</tr>
+<tr>
+<td><code>schema</code></td>
+<td>versioned JSON Schemas (Draft 2020-12) for every input/output shape</td>
+</tr>
+</tbody></table>
+<p>This means <strong>every feature of the library is one release away from the CLI</strong>, and any bug fix in <code>pdfnative</code> is automatically picked up by <code>pdfnative-cli</code> on its next dependency bump.</p>
+<hr>
+<h2 id="installation">Installation<a class="heading-anchor" href="#installation" aria-label="Link to this section">#</a></h2>
+<pre><code class="language-bash"># Run directly with npx — no global install required
+npx pdfnative-cli render --input document.json --output report.pdf
+
+# Or install globally
+npm install --global pdfnative-cli
+pdfnative render --input document.json --output report.pdf
+</code></pre>
+<p><strong>Requirements:</strong> Node.js ≥ 20 · Bun · Deno (<code>node dist/cli.cjs</code>).</p>
+<p>The CLI ships with <strong>NPM provenance</strong> — verify the published artifact with <code>npm audit signatures</code> or on <a href="https://www.npmjs.com/package/pdfnative-cli" target="_blank" rel="noopener">npmjs.com</a>.</p>
+<hr>
+<h2 id="when-to-use-the-cli-vs-the-library">When to use the CLI vs the library<a class="heading-anchor" href="#when-to-use-the-cli-vs-the-library" aria-label="Link to this section">#</a></h2>
+<table>
+<thead>
+<tr>
+<th>Use the <strong>CLI</strong> when…</th>
+<th>Use the <strong>library</strong> when…</th>
+</tr>
+</thead>
+<tbody><tr>
+<td>You write shell scripts, Makefiles, or Bash/PowerShell pipelines</td>
+<td>You build a Node.js / Bun / Deno service</td>
+</tr>
+<tr>
+<td>Your CI/CD job runs in Docker or GitHub Actions</td>
+<td>You need fine-grained streaming control or Web Worker offloading</td>
+</tr>
+<tr>
+<td>You want to compose with <code>cat</code>, <code>jq</code>, <code>tee</code>, <code>gzip</code>, etc.</td>
+<td>You target browsers, Web Workers, or Deno Deploy</td>
+</tr>
+<tr>
+<td>You sign, verify, or inspect PDFs ad-hoc from the terminal</td>
+<td>You bundle PDFs through a custom pipeline (custom font registry, hooks, etc.)</td>
+</tr>
+<tr>
+<td>You want a one-liner instead of a 30-line Node.js script</td>
+<td>You need 100 % programmatic control of the API surface</td>
+</tr>
+</tbody></table>
+<p>The two are <strong>complementary</strong>. A typical full-stack project uses the library at runtime and the CLI in CI scripts and operator workflows.</p>
+<hr>
+<h2 id="quick-start">Quick start<a class="heading-anchor" href="#quick-start" aria-label="Link to this section">#</a></h2>
+<h3 id="1-render-a-document">1. Render a document<a class="heading-anchor" href="#1-render-a-document" aria-label="Link to this section">#</a></h3>
+<p>Create <code>report.json</code>:</p>
+<pre><code class="language-json">{
+  &quot;title&quot;: &quot;April 2026 Report&quot;,
+  &quot;blocks&quot;: [
+    { &quot;type&quot;: &quot;heading&quot;, &quot;text&quot;: &quot;April 2026 Report&quot;, &quot;level&quot;: 1 },
+    { &quot;type&quot;: &quot;paragraph&quot;, &quot;text&quot;: &quot;Summary for the financial period ending 30 April 2026.&quot; },
+    { &quot;type&quot;: &quot;list&quot;, &quot;style&quot;: &quot;bullet&quot;, &quot;items&quot;: [
+      &quot;Revenue: +18% year-on-year&quot;,
+      &quot;Net Promoter Score: 72&quot;,
+      &quot;Active customers: 12,400&quot;
+    ]},
+    { &quot;type&quot;: &quot;table&quot;,
+      &quot;headers&quot;: [&quot;Quarter&quot;, &quot;Revenue&quot;, &quot;Profit&quot;],
+      &quot;rows&quot;: [
+        { &quot;cells&quot;: [&quot;Q1&quot;, &quot;$1.2M&quot;, &quot;$400K&quot;], &quot;type&quot;: &quot;credit&quot;, &quot;pointed&quot;: false },
+        { &quot;cells&quot;: [&quot;Q2&quot;, &quot;$1.5M&quot;, &quot;$600K&quot;], &quot;type&quot;: &quot;credit&quot;, &quot;pointed&quot;: true }
+      ]
+    }
+  ],
+  &quot;footerText&quot;: &quot;Confidential&quot;,
+  &quot;metadata&quot;: { &quot;author&quot;: &quot;Finance Team&quot;, &quot;subject&quot;: &quot;April 2026 Report&quot; }
+}
+</code></pre>
+<p>Render it:</p>
+<pre><code class="language-bash">pdfnative render --input report.json --output report.pdf
+</code></pre>
+<p>That&#39;s it — the file <code>report.pdf</code> is now a valid ISO 32000-1 PDF, ready to send.</p>
+<h3 id="2-sign-the-rendered-pdf-with-metadata">2. Sign the rendered PDF (with metadata)<a class="heading-anchor" href="#2-sign-the-rendered-pdf-with-metadata" aria-label="Link to this section">#</a></h3>
+<pre><code class="language-bash"># Set keys via environment variables (recommended for CI/CD — never logged)
+export PDFNATIVE_SIGN_KEY=&quot;$(cat private.pem)&quot;
+export PDFNATIVE_SIGN_CERT=&quot;$(cat cert.pem)&quot;
+
+pdfnative sign \
+  --input report.pdf \
+  --output report.signed.pdf \
+  --reason &quot;Approved by Finance&quot; \
+  --name &quot;Finance Team&quot; \
+  --location &quot;Paris, FR&quot; \
+  --signing-time 2026-04-28T10:00:00Z
+</code></pre>
+<p>The CLI accepts both <strong>RSA PKCS#1 v1.5</strong> and <strong>ECDSA P-256</strong> keys, both with SHA-256 digests. The signed PDF carries a CMS/PKCS#7 signature embedded as ISO 32000-1 §12.8 prescribes, validatable by Adobe Acrobat, MuPDF, and any other PAdES-compatible reader.</p>
+<h3 id="3-verify-embedded-signatures">3. Verify embedded signatures<a class="heading-anchor" href="#3-verify-embedded-signatures" aria-label="Link to this section">#</a></h3>
+<pre><code class="language-bash">pdfnative verify --input report.signed.pdf --strict --trust ca-root.pem
+</code></pre>
+<p>v0.3.0 performs <strong>real CMS/PKCS#7 verification</strong> — the CLI recomputes the byte-range digest, validates the signature value (RSA-SHA256 or ECDSA-SHA256), walks the certificate chain via <code>pdfnative</code>&#39;s <code>verifyCertSignature</code>, evaluates trust against <code>--trust</code> roots and self-signed acceptance, and reports the presence of an RFC 3161 timestamp token. Exit code is 0 on success, 1 on any failure under <code>--strict</code>.</p>
+<p>A sample JSON report:</p>
+<pre><code class="language-json">{
+  &quot;signatures&quot;: [
+    {
+      &quot;integrity&quot;: true,
+      &quot;signatureValid&quot;: true,
+      &quot;signatureAlgorithm&quot;: &quot;ecdsa-sha256&quot;,
+      &quot;chainValid&quot;: true,
+      &quot;trustedRoot&quot;: true,
+      &quot;timestampPresent&quot;: false,
+      &quot;signerSubject&quot;: &quot;CN=pdfnative-cli ECDSA Test, O=pdfnative-cli, C=FR&quot;,
+      &quot;signerIssuer&quot;: &quot;CN=pdfnative-cli ECDSA Test, O=pdfnative-cli, C=FR&quot;,
+      &quot;notes&quot;: [&quot;no --trust provided; accepted self-signed root&quot;]
+    }
+  ]
+}
+</code></pre>
+<!-- legacy anchor preserved for incoming external links -->
+<p><a id="pdfnative-verify-new-in-v020"></a></p>
+<h3 id="4-inspect-any-pdf">4. Inspect any PDF<a class="heading-anchor" href="#4-inspect-any-pdf" aria-label="Link to this section">#</a></h3>
+<pre><code class="language-bash">pdfnative inspect --input report.signed.pdf --format text
+</code></pre>
+<pre><code>Version:        1.7
+Pages:          2
+Encrypted:      no
+PDF/A:          none
+Signatures:     1
+Title:          April 2026 Report
+Author:         Finance Team
+Created:        2026-04-28T10:00:00+00:00
+Subject:        April 2026 Report
+Producer:       —
+</code></pre>
+<p>JSON output (default) is suited for piping into <code>jq</code> or storing as a CI artifact.</p>
+<hr>
+<h2 id="hybrid-layout-model">Hybrid layout model<a class="heading-anchor" href="#hybrid-layout-model" aria-label="Link to this section">#</a></h2>
+<p><code>render</code> adopts the same layout philosophy as <code>gh</code>, <code>kubectl</code>, and <code>docker</code>: high-frequency knobs are first-class flags, while the full <code>PdfLayoutOptions</code> shape is reachable via a JSON layout file.</p>
+<p><strong>Precedence:</strong> <code>CLI flags &gt; --layout file &gt; pdfnative defaults</code>.</p>
+<pre><code class="language-bash"># 1) Flags only — best for ad-hoc invocations
+pdfnative render --input doc.json --output report.pdf \
+  --page-size A4 --margin 50 --compress --tagged pdfa2b
+
+# 2) Layout file only — best for reproducible CI configs
+pdfnative render --input doc.json --output report.pdf \
+  --layout layout.json
+
+# 3) Hybrid — base config in a file, per-job overrides on the CLI
+pdfnative render --input doc.json --output report.pdf \
+  --layout layout.json \
+  --watermark-text &quot;DRAFT $(date +%Y-%m-%d)&quot;
+</code></pre>
+<p><code>layout.json</code> accepts any subset of <code>PdfLayoutOptions</code>:</p>
+<pre><code class="language-json">{
+  &quot;pageSize&quot;: { &quot;width&quot;: 595, &quot;height&quot;: 842 },
+  &quot;margin&quot;: { &quot;top&quot;: 60, &quot;right&quot;: 50, &quot;bottom&quot;: 60, &quot;left&quot;: 50 },
+  &quot;compress&quot;: true,
+  &quot;tagged&quot;: &quot;pdfa2b&quot;,
+  &quot;headerTemplate&quot;: { &quot;left&quot;: &quot;{title}&quot;, &quot;right&quot;: &quot;{date}&quot; },
+  &quot;footerTemplate&quot;: { &quot;center&quot;: &quot;Page {page} / {pages}&quot; }
+}
+</code></pre>
+<blockquote>
+<p><strong>Security:</strong> <code>--layout</code> paths are validated against directory traversal, and any <code>attachments[].data</code> field embedded in the JSON is <strong>stripped on load</strong>. Binary attachment payloads must come from <code>--attachment &lt;path&gt;</code> so the CLI can apply the same path-validation rules.</p>
+</blockquote>
+<hr>
+<h2 id="command-reference">Command reference<a class="heading-anchor" href="#command-reference" aria-label="Link to this section">#</a></h2>
+<h3 id="pdfnative-render"><code>pdfnative render</code><a class="heading-anchor" href="#pdfnative-render" aria-label="Link to this section">#</a></h3>
+<p>Renders a JSON document into a PDF. Supports both renderer variants exposed by <code>pdfnative</code>.</p>
+<h4 id="core-flags">Core flags<a class="heading-anchor" href="#core-flags" aria-label="Link to this section">#</a></h4>
+<table>
+<thead>
+<tr>
+<th>Flag</th>
+<th>Default</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>--input &lt;file&gt;</code></td>
+<td>stdin</td>
+<td>JSON file (<a href="https://pdfnative.dev/#api" target="_blank" rel="noopener"><code>DocumentParams</code></a> for <code>--variant document</code>, <code>PdfParams</code> for <code>--variant table</code>)</td>
+</tr>
+<tr>
+<td><code>--output &lt;file&gt;</code></td>
+<td>stdout</td>
+<td>Output PDF path</td>
+</tr>
+<tr>
+<td><code>--variant document|table</code></td>
+<td><code>document</code></td>
+<td>Selects <code>buildDocumentPDFBytes</code> (free-form) or <code>buildPDFBytes</code> (table-centric)</td>
+</tr>
+<tr>
+<td><code>--stream</code></td>
+<td>off</td>
+<td>Streaming output via <code>buildDocumentPDFStream</code> (<code>AsyncGenerator&lt;Uint8Array&gt;</code>) — recommended for &gt;100-page documents</td>
+</tr>
+<tr>
+<td><code>--stream-page-by-page</code></td>
+<td>off</td>
+<td>Streaming chunked at PDF object boundaries. Assembles the full document first, so TOC blocks and <code>{pages}</code> <strong>are</strong> supported. Mutually exclusive with <code>--stream</code></td>
+</tr>
+<tr>
+<td><code>--stream-true</code> <em>(v1.1.0)</em></td>
+<td>off</td>
+<td>Streaming via <code>buildDocumentPDFStreamTrue</code> / <code>buildPDFStreamTrue</code> — PDF parts are emitted and freed as they go, so the joined binary never materialises. Byte-identical to the buffered builders. Same constraints as <code>--stream</code> (no TOC, no <code>{pages}</code>); mutually exclusive with the other <code>--stream*</code> flags</td>
+</tr>
+<tr>
+<td><code>--max-blocks &lt;n&gt;</code> <em>(v1.1.0)</em></td>
+<td><code>100000</code></td>
+<td>Exposes <code>layout.maxBlocks</code> so very large multi-thousand-page reports no longer hit a spurious ceiling</td>
+</tr>
+<tr>
+<td><code>--layout &lt;file.json&gt;</code></td>
+<td>—</td>
+<td>Load any subset of <code>PdfLayoutOptions</code></td>
+</tr>
+</tbody></table>
+<h4 id="smart-tables-v130-document-variant">Smart tables <em>(v1.3.0, document variant)</em><a class="heading-anchor" href="#smart-tables-v130-document-variant" aria-label="Link to this section">#</a></h4>
+<p>These flags fill <code>TableBlock</code> fields left unset in the JSON (caption is per-table — set it in the JSON <code>TableBlock</code>):</p>
+<table>
+<thead>
+<tr>
+<th>Flag</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>--table-wrap &lt;mode&gt;</code></td>
+<td><code>auto</code> (default), <code>always</code>, or <code>never</code></td>
+</tr>
+<tr>
+<td><code>--repeat-header [true|false]</code></td>
+<td>Repeat the header row on continuation pages</td>
+</tr>
+<tr>
+<td><code>--zebra [true|false|&quot;R G B&quot;]</code></td>
+<td>Alternate-row striping</td>
+</tr>
+<tr>
+<td><code>--min-row-height &lt;pt&gt;</code></td>
+<td>Minimum row height in points</td>
+</tr>
+<tr>
+<td><code>--cell-padding &lt;pt&gt;</code></td>
+<td>Horizontal cell padding in points</td>
+</tr>
+</tbody></table>
+<h4 id="page-geometry">Page geometry<a class="heading-anchor" href="#page-geometry" aria-label="Link to this section">#</a></h4>
+<table>
+<thead>
+<tr>
+<th>Flag</th>
+<th>Default</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>--page-size &lt;name|WxH&gt;</code></td>
+<td><code>a4</code></td>
+<td>Named (<code>a4</code>, <code>letter</code>, <code>legal</code>, <code>a3</code>, <code>tabloid</code>, <code>a5</code>) or <code>WxH</code> in points</td>
+</tr>
+<tr>
+<td><code>--margin &lt;N&gt;</code> or <code>&lt;t,r,b,l&gt;</code></td>
+<td><code>50</code></td>
+<td>Uniform or per-side margin in points</td>
+</tr>
+<tr>
+<td><code>--compress</code></td>
+<td>off</td>
+<td>Apply <code>/Filter /FlateDecode</code> to all content streams</td>
+</tr>
+</tbody></table>
+<h4 id="pdfa-conformance">PDF/A conformance<a class="heading-anchor" href="#pdfa-conformance" aria-label="Link to this section">#</a></h4>
+<table>
+<thead>
+<tr>
+<th>Flag</th>
+<th>Default</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>--tagged &lt;level&gt;</code></td>
+<td><code>none</code></td>
+<td>Unified PDF/A flag: <code>none</code>, <code>pdfa1b</code>, <code>pdfa2b</code>, <code>pdfa2u</code>, <code>pdfa3b</code></td>
+</tr>
+<tr>
+<td><code>--conformance &lt;level&gt;</code></td>
+<td>—</td>
+<td><strong>Deprecated.</strong> Maps to <code>--tagged pdfa&lt;level&gt;</code> with a one-line stderr notice. Removed in v1.0.0</td>
+</tr>
+</tbody></table>
+<h4 id="watermarks">Watermarks<a class="heading-anchor" href="#watermarks" aria-label="Link to this section">#</a></h4>
+<table>
+<thead>
+<tr>
+<th>Flag</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>--watermark-text &lt;str&gt;</code></td>
+<td>Diagonal text watermark</td>
+</tr>
+<tr>
+<td><code>--watermark-image &lt;path&gt;</code></td>
+<td>Image watermark (PNG/JPEG, centered, aspect-preserved)</td>
+</tr>
+<tr>
+<td><code>--watermark-opacity &lt;0..1&gt;</code></td>
+<td>ExtGState <code>/ca</code> value</td>
+</tr>
+<tr>
+<td><code>--watermark-angle &lt;deg&gt;</code></td>
+<td>Rotation angle</td>
+</tr>
+<tr>
+<td><code>--watermark-color &lt;hex|R,G,B&gt;</code></td>
+<td>Fill color (text only)</td>
+</tr>
+<tr>
+<td><code>--watermark-font-size &lt;pt&gt;</code></td>
+<td>Font size (text only)</td>
+</tr>
+<tr>
+<td><code>--watermark-position background|foreground</code></td>
+<td>Drawing order vs. content</td>
+</tr>
+</tbody></table>
+<blockquote>
+<p>Watermarks with transparency are <strong>mutually exclusive</strong> with PDF/A-1b (ISO 19005-1 §6.4). The pdfnative core enforces this at render time — the run fails with the generic exit code 1 (<code>Watermark transparency is not allowed with PDF/A-1b</code>), not a CLI usage error.</p>
+</blockquote>
+<h4 id="headers--footers">Headers / footers<a class="heading-anchor" href="#headers--footers" aria-label="Link to this section">#</a></h4>
+<table>
+<thead>
+<tr>
+<th>Flag</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>--header-left &lt;str&gt;</code> / <code>--header-center</code> / <code>--header-right</code></td>
+<td>Page-template zones</td>
+</tr>
+<tr>
+<td><code>--footer-left &lt;str&gt;</code> / <code>--footer-center</code> / <code>--footer-right</code></td>
+<td>Page-template zones</td>
+</tr>
+</tbody></table>
+<p>Supported placeholders: <code>{page}</code>, <code>{pages}</code>, <code>{date}</code>, <code>{title}</code>. The <code>{pages}</code> placeholder is rejected with <code>--stream</code> because the total page count is only known after multi-pass pagination.</p>
+<h4 id="encryption">Encryption<a class="heading-anchor" href="#encryption" aria-label="Link to this section">#</a></h4>
+<p>Since v1.3.0, <code>render</code> speaks the same <strong>unified encryption vocabulary</strong> as <code>merge</code> / <code>split</code> / <code>extract</code>:</p>
+<table>
+<thead>
+<tr>
+<th>Flag</th>
+<th>Env var</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>--encrypt [aes-128|aes-256]</code></td>
+<td>—</td>
+<td>Enable encryption (bare <code>--encrypt</code> = <code>aes-128</code>)</td>
+</tr>
+<tr>
+<td><code>--owner-password &lt;pass&gt;</code></td>
+<td><code>PDFNATIVE_ENCRYPT_OWNER_PASS</code></td>
+<td><strong>Required</strong> whenever encryption is requested</td>
+</tr>
+<tr>
+<td><code>--user-password &lt;pass&gt;</code></td>
+<td><code>PDFNATIVE_ENCRYPT_USER_PASS</code></td>
+<td>Optional password needed to open the document</td>
+</tr>
+<tr>
+<td><code>--permissions &lt;list&gt;</code></td>
+<td>—</td>
+<td>Comma list: <code>print</code>, <code>copy</code>, <code>modify</code>, <code>extract</code></td>
+</tr>
+</tbody></table>
+<p>The legacy v0.2.0 flags — <code>--encrypt-algorithm</code>, <code>--encrypt-owner-pass</code>, <code>--encrypt-user-pass</code>, <code>--encrypt-permissions</code> — remain accepted as aliases; when both are given, the unified value wins.</p>
+<p>Env vars take precedence over flags, ensuring secrets never appear in shell history. Encryption is <strong>mutually exclusive</strong> with <code>--tagged pdfa*</code> per ISO 19005-1 §6.3.2 — rejected with exit 2.</p>
+<h4 id="pdfa-3-attachments">PDF/A-3 attachments<a class="heading-anchor" href="#pdfa-3-attachments" aria-label="Link to this section">#</a></h4>
+<table>
+<thead>
+<tr>
+<th>Flag</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>--attachment &lt;path&gt;[:mime[:rel[:desc]]]</code></td>
+<td>Embed a file as <code>/EmbeddedFile</code>. Repeatable</td>
+</tr>
+</tbody></table>
+<p>The Windows drive-letter colon (<code>D:\path</code>) is detected and not split — see <em>Troubleshooting</em>.</p>
+<h4 id="multilingual-fonts">Multilingual fonts<a class="heading-anchor" href="#multilingual-fonts" aria-label="Link to this section">#</a></h4>
+<table>
+<thead>
+<tr>
+<th>Flag</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>--lang &lt;code,code&gt;</code></td>
+<td>Activate font loaders for the listed languages (e.g. <code>th,ja,ar,te,si,km</code>)</td>
+</tr>
+<tr>
+<td><code>--font &lt;name&gt;</code> <em>(v1.1.0)</em></td>
+<td>Register a bundled pdfnative font shortcut. Repeatable. Allow-list covers every bundled font: <code>latin</code>, <code>emoji</code>, <code>color-emoji</code>, <code>math</code> <em>(v1.2.0)</em>, and the 22 script codes (<code>ar hy bn ru hi am ka el he ja km ko my pl zh si ta te th bo tr vi</code>). Each shortcut name doubles as its <code>--lang</code> code</td>
+</tr>
+</tbody></table>
+<p><code>--lang</code> activates a <em>programmatically registered</em> font loader via <code>loadFontData(code)</code>. Latin scripts are built-in. With v1.1.0, every bundled font is registrable directly through <code>--font</code> — no wrapper script needed for the 22 bundled scripts, colour emoji, or Latin. pdfnative routes each code point to the font whose cmap covers it. See <em>Recipes → Multilang fonts</em> only for fonts you ship yourself (those require calling the library directly).</p>
+<h4 id="bookmarks-math--layout-tooling-v120">Bookmarks, math &amp; layout tooling <em>(v1.2.0)</em><a class="heading-anchor" href="#bookmarks-math--layout-tooling-v120" aria-label="Link to this section">#</a></h4>
+<table>
+<thead>
+<tr>
+<th>Flag</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>--outline auto|&lt;tree.json&gt;</code></td>
+<td>Add a navigable PDF bookmark tree (<code>/Outlines</code>). <code>auto</code> derives it from the document&#39;s headings; a file supplies an explicit <code>OutlineItem[]</code> tree</td>
+</tr>
+<tr>
+<td><code>--font math</code></td>
+<td>Register the bundled <strong>Noto Sans Math</strong> font; pdfnative auto-routes math-operator and geometric-shape code points to it</td>
+</tr>
+<tr>
+<td><code>--inspect-layout</code></td>
+<td>Emit a <code>LayoutInspection</code> JSON report (per-page blocks, positions, sizes) instead of a PDF (document variant only)</td>
+</tr>
+<tr>
+<td><code>--debug-layout [margins,content,cells]</code></td>
+<td>Render a normal PDF with the opt-in layout-debug guides overlaid</td>
+</tr>
+</tbody></table>
+<pre><code class="language-bash"># Bookmarks derived from headings + math font
+pdfnative render --input paper.json --output paper.pdf --outline auto --font math
+
+# Layout introspection instead of a PDF
+pdfnative render --input report.json --inspect-layout &gt; layout.json
+</code></pre>
+<h4 id="iteration-helpers-v030">Iteration helpers <em>(v0.3.0)</em><a class="heading-anchor" href="#iteration-helpers-v030" aria-label="Link to this section">#</a></h4>
+<table>
+<thead>
+<tr>
+<th>Flag</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>--watch</code></td>
+<td>Re-render on input file change. 200 ms debounce, stderr-only logs. Requires <code>--input &lt;file&gt;</code> and a file <code>--output</code> (stdin / stdout pipelines are not supported — watch needs a stable on-disk source)</td>
+</tr>
+<tr>
+<td><code>--template &lt;file.json&gt;</code></td>
+<td>Deep-merge a base template under stdin / <code>--input</code>. Plain objects merge recursively; arrays and primitives are replaced (caller wins). Useful for centralising title / layout / headers in CI</td>
+</tr>
+</tbody></table>
+<pre><code class="language-bash"># Watch a file
+pdfnative render --input report.json --output report.pdf --watch
+
+# Template + override (template carries title/layout/headers, stdin overrides body)
+echo &#39;{&quot;blocks&quot;:[{&quot;type&quot;:&quot;paragraph&quot;,&quot;text&quot;:&quot;Today only.&quot;}]}&#39; \
+  | pdfnative render --template template.json -o today.pdf
+
+# Bundled fonts via flag (no wrapper)
+echo &#39;{&quot;blocks&quot;:[{&quot;type&quot;:&quot;paragraph&quot;,&quot;text&quot;:&quot;Hi \ud83d\ude80&quot;}]}&#39; \
+  | pdfnative render --font latin --font emoji --lang latin,emoji -o out.pdf
+</code></pre>
+<h3 id="pdfnative-sign"><code>pdfnative sign</code><a class="heading-anchor" href="#pdfnative-sign" aria-label="Link to this section">#</a></h3>
+<p>Applies a CMS/PKCS#7 digital signature to an existing PDF.</p>
+<table>
+<thead>
+<tr>
+<th>Flag</th>
+<th>Default</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>--input &lt;file&gt;</code></td>
+<td>stdin</td>
+<td>Input PDF</td>
+</tr>
+<tr>
+<td><code>--output &lt;file&gt;</code></td>
+<td>stdout</td>
+<td>Output signed PDF</td>
+</tr>
+<tr>
+<td><code>--key &lt;file&gt;</code></td>
+<td><code>PDFNATIVE_SIGN_KEY</code> env</td>
+<td>PEM-encoded private key (env var takes precedence)</td>
+</tr>
+<tr>
+<td><code>--cert &lt;file&gt;</code></td>
+<td><code>PDFNATIVE_SIGN_CERT</code> env</td>
+<td>PEM-encoded X.509 certificate (env var takes precedence)</td>
+</tr>
+<tr>
+<td><code>--cert-chain &lt;file&gt;</code></td>
+<td><code>PDFNATIVE_SIGN_CHAIN</code> env</td>
+<td>Intermediate-CA PEM (repeatable, concatenated into <code>certChain[]</code>)</td>
+</tr>
+<tr>
+<td><code>--algorithm &lt;algo&gt;</code></td>
+<td><code>rsa-sha256</code></td>
+<td><code>rsa-sha256</code> or <code>ecdsa-sha256</code> (both fully wired in v0.3.0; SEC1 / PKCS#8 P-256 keys accepted)</td>
+</tr>
+<tr>
+<td><code>--reason &lt;str&gt;</code></td>
+<td>—</td>
+<td><code>PdfSignOptions.reason</code></td>
+</tr>
+<tr>
+<td><code>--name &lt;str&gt;</code></td>
+<td>—</td>
+<td><code>PdfSignOptions.name</code></td>
+</tr>
+<tr>
+<td><code>--location &lt;str&gt;</code></td>
+<td>—</td>
+<td><code>PdfSignOptions.location</code></td>
+</tr>
+<tr>
+<td><code>--contact &lt;str&gt;</code></td>
+<td>—</td>
+<td><code>PdfSignOptions.contact</code></td>
+</tr>
+<tr>
+<td><code>--signing-time &lt;ISO 8601&gt;</code></td>
+<td>now</td>
+<td>Explicit timestamp; validated up-front before any credential I/O</td>
+</tr>
+<tr>
+<td><code>--pure-crypto</code> <em>(v1.2.0)</em></td>
+<td>off</td>
+<td>Force pdfnative&#39;s portable <strong>pure-JS</strong> bignum CMS path instead of the default native provider</td>
+</tr>
+</tbody></table>
+<blockquote>
+<p><strong>Native constant-time signing (v1.2.0).</strong> <code>sign</code> now routes CMS signing through Node&#39;s <code>node:crypto</code> by default (via <code>createNativeCryptoProvider</code>), for side-channel-resistant RSA/ECDSA. Pass <strong><code>--pure-crypto</code></strong> to select the portable pure-JS path (e.g. on a runtime without <code>node:crypto</code>).</p>
+</blockquote>
+<p>Signing keys are <strong>never logged</strong> — not in error output, not in debug traces, not in stack traces. The CLI redacts them at every code path that surfaces error context.</p>
+<h3 id="pdfnative-inspect"><code>pdfnative inspect</code><a class="heading-anchor" href="#pdfnative-inspect" aria-label="Link to this section">#</a></h3>
+<p>Inspects metadata and conformance of an existing PDF. Read-only — never modifies the input.</p>
+<table>
+<thead>
+<tr>
+<th>Flag</th>
+<th>Default</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>--input &lt;file&gt;</code></td>
+<td>stdin</td>
+<td>Input PDF</td>
+</tr>
+<tr>
+<td><code>--format &lt;fmt&gt;</code></td>
+<td><code>json</code></td>
+<td><code>json</code> or <code>text</code></td>
+</tr>
+<tr>
+<td><code>--verbose</code></td>
+<td>off</td>
+<td>Adds <code>verbose.{trailerKeys, catalogKeys, objectCount, xmpMetadata}</code>. Sanitised — no raw stream bytes</td>
+</tr>
+<tr>
+<td><code>--pages</code></td>
+<td>off</td>
+<td>Adds <code>pages: [{ index, width, height, rotation, annotations, formFields }]</code></td>
+</tr>
+<tr>
+<td><code>--pdfua</code> <em>(v1.1.0)</em></td>
+<td>off</td>
+<td>Adds a <code>pdfua: { valid, errors, warnings }</code> report from <code>validatePdfUA()</code> (ISO 14289-1 structural checks: MarkInfo, StructTree, ParentTree, Lang, per-page MCID uniqueness)</td>
+</tr>
+<tr>
+<td><code>--annotations</code> <em>(v1.2.0)</em></td>
+<td>off</td>
+<td>Lists markup + link annotations per page (from <code>getAnnotations()</code>). <code>/PageLabels</code> are reported automatically when present</td>
+</tr>
+<tr>
+<td><code>--form-fields</code> <em>(v1.3.0)</em></td>
+<td>off</td>
+<td>Lists AcroForm fields (name, type, value, required/read-only)</td>
+</tr>
+<tr>
+<td><code>--encryption</code> <em>(v1.3.0)</em></td>
+<td>off</td>
+<td>Reports the encryption scheme (algorithm, revision, opened-as)</td>
+</tr>
+<tr>
+<td><code>--password &lt;pass&gt;</code> <em>(v1.3.0)</em></td>
+<td>—</td>
+<td>Password for an encrypted PDF (env <code>PDFNATIVE_PASSWORD</code>)</td>
+</tr>
+<tr>
+<td><code>--check &lt;assertion&gt;</code></td>
+<td>—</td>
+<td>Repeatable; ANDed. Values: <code>pdfa</code>, <code>signed</code>, <code>encrypted</code>, <code>pdfua</code> <em>(v1.1.0)</em>. Sets exit 0 = pass, 1 = fail</td>
+</tr>
+<tr>
+<td><code>--summary</code> <em>(v1.1.0)</em></td>
+<td>off</td>
+<td>Under <code>--json</code>, emit a canonical minimal verdict (<code>{ pages, encrypted, signatures, pdfa }</code>)</td>
+</tr>
+<tr>
+<td><code>--fields &lt;a,b.c&gt;</code> <em>(v1.1.0)</em></td>
+<td>—</td>
+<td>Project the JSON result to named dot-paths (array segments map over elements; unknown paths omitted)</td>
+</tr>
+<tr>
+<td><code>--pretty</code></td>
+<td>off</td>
+<td>Force indented JSON even under the global <code>--json</code> (agent mode is compact)</td>
+</tr>
+</tbody></table>
+<p>Composable example:</p>
+<pre><code class="language-bash">pdfnative inspect --input dist/q1.pdf \
+  --check pdfa --check signed \
+  --format json &gt; dist/q1.report.json
+echo &quot;exit code: $?&quot;   # 0 if both assertions hold
+</code></pre>
+<h3 id="pdfnative-verify"><code>pdfnative verify</code><a class="heading-anchor" href="#pdfnative-verify" aria-label="Link to this section">#</a></h3>
+<p>Verifies CMS/PKCS#7 signatures embedded in a PDF.</p>
+<table>
+<thead>
+<tr>
+<th>Flag</th>
+<th>Default</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>--input &lt;file&gt;</code></td>
+<td>stdin</td>
+<td>Input PDF</td>
+</tr>
+<tr>
+<td><code>--format &lt;fmt&gt;</code></td>
+<td><code>json</code></td>
+<td><code>json</code> or <code>text</code></td>
+</tr>
+<tr>
+<td><code>--strict</code></td>
+<td>off</td>
+<td>Exit 1 on any failure or zero signatures</td>
+</tr>
+<tr>
+<td><code>--trust &lt;pem&gt;</code></td>
+<td>—</td>
+<td>Trust-anchor certificate (repeatable)</td>
+</tr>
+<tr>
+<td><code>--revocation &lt;mode&gt;</code></td>
+<td><code>offline</code></td>
+<td><code>offline</code> (embedded <code>/DSS</code> only), <code>online</code> (opt-in, SSRF-guarded OCSP/CRL fetch), or <code>disabled</code></td>
+</tr>
+<tr>
+<td><code>--revocation-policy &lt;p&gt;</code></td>
+<td><code>soft-fail</code></td>
+<td><code>soft-fail</code> or <code>strict</code></td>
+</tr>
+<tr>
+<td><code>--summary</code> <em>(v1.1.0)</em></td>
+<td>off</td>
+<td>Under <code>--json</code>, emit a minimal verdict (<code>{ valid, signatures, invalid }</code>)</td>
+</tr>
+<tr>
+<td><code>--fields &lt;a,b.c&gt;</code> <em>(v1.1.0)</em></td>
+<td>—</td>
+<td>Project the JSON result to named dot-paths</td>
+</tr>
+</tbody></table>
+<p><strong>Scope (since v1.0.0):</strong></p>
+<ul>
+<li>✅ Byte-range integrity (SHA-256 recomputed and compared with CMS <code>messageDigest</code> attribute)</li>
+<li>✅ Signature value verification — RSA-SHA256 and ECDSA-SHA256</li>
+<li>✅ Certificate chain verification via <code>pdfnative</code>&#39;s <code>verifyCertSignature</code></li>
+<li>✅ Trust evaluation against <code>--trust</code> roots, with self-signed acceptance for testing</li>
+<li>✅ <strong>RFC 3161 timestamp validation (PAdES-T)</strong> — TSA signature, <code>messageImprint</code> binding, chain, <code>genTime</code></li>
+<li>✅ <strong>OCSP (RFC 6960) + CRL (RFC 5280) revocation</strong> — embedded <code>/DSS</code> offline by default, opt-in SSRF-guarded online via AIA / CDP</li>
+</ul>
+<p><strong>Out of scope (upstream-blocked in pdfnative):</strong></p>
+<ul>
+<li>⚠️ Sign-side LTV (timestamp embedding / DSS) — <code>sign --timestamp</code> reserved</li>
+</ul>
+<h3 id="pdfnative-merge-v120"><code>pdfnative merge</code> <em>(v1.2.0)</em><a class="heading-anchor" href="#pdfnative-merge-v120" aria-label="Link to this section">#</a></h3>
+<p>Concatenates <strong>2–50</strong> PDFs into one document, in order, via <code>mergePdfs</code>.</p>
+<pre><code class="language-bash">pdfnative merge a.pdf b.pdf c.pdf --output combined.pdf
+</code></pre>
+<table>
+<thead>
+<tr>
+<th>Flag</th>
+<th>Default</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>&lt;paths…&gt;</code> / <code>--input &lt;file&gt;</code></td>
+<td>— <em>(required)</em></td>
+<td>Source PDFs — positional paths and/or repeatable <code>--input</code>. 2–50 total</td>
+</tr>
+<tr>
+<td><code>--output &lt;file&gt;</code></td>
+<td>stdout</td>
+<td>Output PDF</td>
+</tr>
+<tr>
+<td><code>--drop-annotations</code></td>
+<td>off</td>
+<td>Drop non-link annotations from the sources</td>
+</tr>
+<tr>
+<td><code>--max-output-size &lt;bytes&gt;</code></td>
+<td>256 MiB</td>
+<td>Reject an output larger than this ceiling</td>
+</tr>
+<tr>
+<td><code>--password &lt;pass&gt;</code> <em>(v1.3.0)</em></td>
+<td>—</td>
+<td>Password for encrypted sources (env <code>PDFNATIVE_PASSWORD</code>). One password is applied to every source; mixed passwords fail with <code>E_PASSWORD</code></td>
+</tr>
+<tr>
+<td><code>--encrypt [aes-128|aes-256]</code> <em>(v1.3.0)</em></td>
+<td>—</td>
+<td>Re-encrypt the output (bare = <code>aes-128</code>); needs <code>--owner-password</code></td>
+</tr>
+<tr>
+<td><code>--owner-password</code> / <code>--user-password</code> <em>(v1.3.0)</em></td>
+<td>—</td>
+<td>Passwords for <code>--encrypt</code> (env <code>PDFNATIVE_ENCRYPT_OWNER_PASS</code> / <code>_USER_PASS</code>)</td>
+</tr>
+<tr>
+<td><code>--permissions &lt;list&gt;</code> <em>(v1.3.0)</em></td>
+<td><code>print,extract</code></td>
+<td>Comma list: <code>print</code>, <code>copy</code>, <code>modify</code>, <code>extract</code> — without the flag, print and extract are allowed, copy and modify denied</td>
+</tr>
+<tr>
+<td><code>--stream</code> <em>(v1.3.0)</em></td>
+<td>off</td>
+<td>Constant-memory streaming output (<code>--chunk-size N</code>)</td>
+</tr>
+<tr>
+<td><code>--dry-run</code></td>
+<td>off</td>
+<td>Validate inputs without writing output</td>
+</tr>
+</tbody></table>
+<blockquote>
+<p>Encrypted sources are <strong>supported since v1.3.0</strong> via <code>--password</code> (a single password applied to every source), and the output can be re-encrypted via <code>--encrypt</code>. Signatures and <code>/AcroForm</code> are dropped (page edits invalidate <code>/ByteRange</code>); self-contained URI <code>/Link</code> annotations are preserved. Every path — positionals included — is validated against traversal.</p>
+</blockquote>
+<h3 id="pdfnative-split-v120"><code>pdfnative split</code> <em>(v1.2.0)</em><a class="heading-anchor" href="#pdfnative-split-v120" aria-label="Link to this section">#</a></h3>
+<p>Splits one PDF into many via <code>splitPdf</code> — one output per page (default) or one per comma-separated range.</p>
+<pre><code class="language-bash"># One output per page
+pdfnative split --input report.pdf --output-dir pages/ --prefix page
+
+# One output per range (1-based, inclusive)
+pdfnative split --input report.pdf --output-dir out/ --pages &quot;1-2,3-4&quot;
+</code></pre>
+<table>
+<thead>
+<tr>
+<th>Flag</th>
+<th>Default</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>--input &lt;file&gt;</code></td>
+<td>stdin</td>
+<td>Source PDF</td>
+</tr>
+<tr>
+<td><code>--output-dir &lt;dir&gt;</code></td>
+<td>— <em>(required)</em></td>
+<td>Destination directory; parts are written as <code>&lt;prefix&gt;-&lt;n&gt;.pdf</code> (zero-padded)</td>
+</tr>
+<tr>
+<td><code>--prefix &lt;str&gt;</code></td>
+<td>input basename (<code>part</code> on stdin)</td>
+<td>Output filename prefix</td>
+</tr>
+<tr>
+<td><code>--pages &lt;ranges&gt;</code></td>
+<td>per-page</td>
+<td>Comma-separated 1-based inclusive ranges (e.g. <code>1-2,3-4</code>)</td>
+</tr>
+<tr>
+<td><code>--max-output-size &lt;bytes&gt;</code></td>
+<td>256 MiB</td>
+<td>Per-part output ceiling</td>
+</tr>
+<tr>
+<td><code>--password &lt;pass&gt;</code> <em>(v1.3.0)</em></td>
+<td>—</td>
+<td>Password for an encrypted source (env <code>PDFNATIVE_PASSWORD</code>)</td>
+</tr>
+<tr>
+<td><code>--encrypt [aes-128|aes-256]</code> <em>(v1.3.0)</em></td>
+<td>—</td>
+<td>Re-encrypt each output (needs <code>--owner-password</code>; <code>--user-password</code> / <code>--permissions</code> as in <code>merge</code>)</td>
+</tr>
+<tr>
+<td><code>--stream</code> <em>(v1.3.0)</em></td>
+<td>off</td>
+<td>Constant-memory streaming output (<code>--chunk-size N</code>)</td>
+</tr>
+<tr>
+<td><code>--dry-run</code></td>
+<td>off</td>
+<td>Validate without writing</td>
+</tr>
+</tbody></table>
+<h3 id="pdfnative-extract-v120"><code>pdfnative extract</code> <em>(v1.2.0)</em><a class="heading-anchor" href="#pdfnative-extract-v120" aria-label="Link to this section">#</a></h3>
+<p>Pulls a selected, order-preserving subset of pages into a single PDF via <code>extractPages</code>.</p>
+<pre><code class="language-bash">pdfnative extract --input report.pdf --output cover.pdf --pages &quot;4,1-2&quot;
+</code></pre>
+<table>
+<thead>
+<tr>
+<th>Flag</th>
+<th>Default</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>--input &lt;file&gt;</code></td>
+<td>stdin</td>
+<td>Source PDF</td>
+</tr>
+<tr>
+<td><code>--output &lt;file&gt;</code></td>
+<td>stdout</td>
+<td>Output PDF</td>
+</tr>
+<tr>
+<td><code>--pages &lt;list&gt;</code></td>
+<td>— <em>(required)</em></td>
+<td>1-based page list/ranges; <strong>order is preserved and repeats are allowed</strong></td>
+</tr>
+<tr>
+<td><code>--max-output-size &lt;bytes&gt;</code></td>
+<td>256 MiB</td>
+<td>Output ceiling</td>
+</tr>
+<tr>
+<td><code>--password &lt;pass&gt;</code> <em>(v1.3.0)</em></td>
+<td>—</td>
+<td>Password for an encrypted source (env <code>PDFNATIVE_PASSWORD</code>)</td>
+</tr>
+<tr>
+<td><code>--encrypt [aes-128|aes-256]</code> <em>(v1.3.0)</em></td>
+<td>—</td>
+<td>Re-encrypt the output (needs <code>--owner-password</code>; <code>--user-password</code> / <code>--permissions</code> as in <code>merge</code>)</td>
+</tr>
+<tr>
+<td><code>--stream</code> <em>(v1.3.0)</em></td>
+<td>off</td>
+<td>Constant-memory streaming output (<code>--chunk-size N</code>)</td>
+</tr>
+<tr>
+<td><code>--dry-run</code></td>
+<td>off</td>
+<td>Validate without writing</td>
+</tr>
+</tbody></table>
+<h3 id="pdfnative-annotate-v120"><code>pdfnative annotate</code> <em>(v1.2.0)</em><a class="heading-anchor" href="#pdfnative-annotate-v120" aria-label="Link to this section">#</a></h3>
+<p>Attaches markup annotations to an existing PDF via an <strong>incremental save</strong>, so the original bytes — and any existing signature — stay intact.</p>
+<pre><code class="language-bash">pdfnative annotate --input report.pdf --output annotated.pdf \
+  --annotations notes.json
+</code></pre>
+<p><code>notes.json</code> is a JSON array (or <code>{ &quot;annotations&quot;: […] }</code>), each entry a markup annotation plus a 1-based <code>page</code>:</p>
+<pre><code class="language-json">[
+  { &quot;page&quot;: 1, &quot;type&quot;: &quot;highlight&quot;, &quot;rect&quot;: [72, 700, 520, 715], &quot;color&quot;: &quot;#ffe066&quot;, &quot;contents&quot;: &quot;Review this clause&quot; },
+  { &quot;page&quot;: 2, &quot;type&quot;: &quot;text&quot;, &quot;rect&quot;: [80, 640, 100, 660], &quot;contents&quot;: &quot;Sticky note&quot; }
+]
+</code></pre>
+<p>Supported types: <code>text</code>, <code>highlight</code>, <code>underline</code>, <code>strikeout</code>, <code>squiggly</code>, <code>square</code>, <code>circle</code>, <code>line</code>, <code>freetext</code>. Only known fields are forwarded (no dictionary injection). Read them back with <code>inspect --annotations</code>.</p>
+<blockquote>
+<p><strong>Overlay, not redaction.</strong> Annotations are a <em>visual review layer</em>; the underlying bytes remain. They do <strong>not</strong> remove or obscure content for security purposes.</p>
+</blockquote>
+<h3 id="pdfnative-govern-v120"><code>pdfnative govern</code> <em>(v1.2.0)</em><a class="heading-anchor" href="#pdfnative-govern-v120" aria-label="Link to this section">#</a></h3>
+<p>Surfaces pdfnative&#39;s <strong>AI-governance / Human-in-the-Loop (HITL)</strong> contract. Agents act as <strong>draftsmen</strong>: a human must always review and submit under their own GitHub identity.</p>
+<pre><code class="language-bash">pdfnative govern rules                  # human/agent protocol (AGENT_RULES)
+pdfnative govern policy --json          # machine-readable policy JSON
+pdfnative govern verify-issue draft.md  # gate a draft (exit 1 / E_POLICY)
+</code></pre>
+<table>
+<thead>
+<tr>
+<th>Subcommand</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>rules</code></td>
+<td>Print the human-and-agent protocol (mirrors <code>.github/AGENT_RULES.md</code>)</td>
+</tr>
+<tr>
+<td><code>policy [--json]</code></td>
+<td>Print the governance policy (mirrors <code>.github/ai-governance.json</code>)</td>
+</tr>
+<tr>
+<td><code>verify-issue &lt;draft.md&gt;</code></td>
+<td>Gate a local issue draft; exit <code>1</code> / <code>E_POLICY</code> on a violation (proposes a runtime dependency, omits a reproduction code block). Missing recommended fields surface as warnings</td>
+</tr>
+</tbody></table>
+<blockquote>
+<p><code>verify-issue</code> is a pure, <strong>fully offline</strong> validator — no GitHub or network access. A passing check is <em>necessary but not sufficient</em>: the human review gate always applies.</p>
+</blockquote>
+<h3 id="pdfnative-fill-v130"><code>pdfnative fill</code> <em>(v1.3.0)</em><a class="heading-anchor" href="#pdfnative-fill-v130" aria-label="Link to this section">#</a></h3>
+<p>Fill, flatten or export an AcroForm. The three modes compose into a round trip:
+export the current values, edit the JSON, feed it back.</p>
+<pre><code class="language-bash">pdfnative fill --input form.pdf --export --output values.json   # read
+pdfnative fill --input form.pdf --data values.json --output filled.pdf
+pdfnative fill --input filled.pdf --flatten --output flat.pdf   # freeze
+</code></pre>
+<table>
+<thead>
+<tr>
+<th>Flag</th>
+<th>Default</th>
+<th>Purpose</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>--data &lt;file&gt;</code></td>
+<td>—</td>
+<td>Values JSON. Required unless <code>--flatten</code> or <code>--export</code></td>
+</tr>
+<tr>
+<td><code>--flatten</code></td>
+<td>off</td>
+<td>Flatten after filling, or flatten the existing values</td>
+</tr>
+<tr>
+<td><code>--export</code></td>
+<td>off</td>
+<td>Read-only: emit current values in <code>--data</code> shape</td>
+</tr>
+<tr>
+<td><code>--force</code></td>
+<td>off</td>
+<td>Flatten even when a signed signature field is present</td>
+</tr>
+<tr>
+<td><code>--on-unknown &lt;mode&gt;</code></td>
+<td><code>throw</code></td>
+<td><code>throw</code> or <code>ignore</code> for unknown field names</td>
+</tr>
+<tr>
+<td><code>--need-appearances</code></td>
+<td>off</td>
+<td>Set <code>/NeedAppearances</code> to allow non-WinAnsi values</td>
+</tr>
+<tr>
+<td><code>--password &lt;pass&gt;</code></td>
+<td>—</td>
+<td>Open an encrypted form (env <code>PDFNATIVE_PASSWORD</code>)</td>
+</tr>
+<tr>
+<td><code>--dry-run</code></td>
+<td>off</td>
+<td>Validate and enumerate fields without writing</td>
+</tr>
+</tbody></table>
+<p>Flattening a signed document invalidates the signature, which is why <code>--force</code>
+exists rather than it being silent.</p>
+<h3 id="pdfnative-encrypt-v130"><code>pdfnative encrypt</code> <em>(v1.3.0)</em><a class="heading-anchor" href="#pdfnative-encrypt-v130" aria-label="Link to this section">#</a></h3>
+<p>Re-secure an existing PDF. <code>--owner-password</code> is required; without a
+<code>--user-password</code> the document <strong>opens with no prompt</strong> and the owner password
+only governs permissions.</p>
+<pre><code class="language-bash">pdfnative encrypt --input report.pdf --output secure.pdf \
+  --owner-password &quot;$OWNER&quot; --user-password &quot;$USER&quot; \
+  --algorithm aes-256 --permissions print,extract
+</code></pre>
+<table>
+<thead>
+<tr>
+<th>Flag</th>
+<th>Default</th>
+<th>Purpose</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>--owner-password &lt;pass&gt;</code></td>
+<td>—</td>
+<td><strong>Required.</strong> Env <code>PDFNATIVE_ENCRYPT_OWNER_PASS</code></td>
+</tr>
+<tr>
+<td><code>--user-password &lt;pass&gt;</code></td>
+<td>—</td>
+<td>Password needed to open. Env <code>PDFNATIVE_ENCRYPT_USER_PASS</code></td>
+</tr>
+<tr>
+<td><code>--algorithm &lt;alg&gt;</code></td>
+<td><code>aes-128</code></td>
+<td><code>aes-128</code> or <code>aes-256</code></td>
+</tr>
+<tr>
+<td><code>--permissions &lt;list&gt;</code></td>
+<td><code>print,extract</code></td>
+<td>Comma-separated: <code>print</code>, <code>copy</code>, <code>modify</code>, <code>extract</code> — without the flag, print and extract are allowed, copy and modify denied</td>
+</tr>
+<tr>
+<td><code>--password &lt;pass&gt;</code></td>
+<td>—</td>
+<td>Open an already-encrypted source (password rotation)</td>
+</tr>
+<tr>
+<td><code>--drop-annotations</code></td>
+<td>off</td>
+<td>Drop all annotations; the default keeps URI links</td>
+</tr>
+<tr>
+<td><code>--max-output-size &lt;n&gt;</code></td>
+<td>256 MiB</td>
+<td>Cap on the assembled size</td>
+</tr>
+<tr>
+<td><code>--stream</code></td>
+<td>off</td>
+<td>Stream the output (<code>--chunk-size N</code>)</td>
+</tr>
+</tbody></table>
+<h3 id="pdfnative-decrypt-v130"><code>pdfnative decrypt</code> <em>(v1.3.0)</em><a class="heading-anchor" href="#pdfnative-decrypt-v130" aria-label="Link to this section">#</a></h3>
+<p>Remove encryption, given the password. Reads RC4, AES-128 and AES-256 sources.</p>
+<pre><code class="language-bash">pdfnative decrypt --input secure.pdf --password &quot;$PASS&quot; --output plain.pdf
+</code></pre>
+<table>
+<thead>
+<tr>
+<th>Flag</th>
+<th>Default</th>
+<th>Purpose</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>--password &lt;pass&gt;</code></td>
+<td>—</td>
+<td>Document password. Env <code>PDFNATIVE_PASSWORD</code></td>
+</tr>
+<tr>
+<td><code>--drop-annotations</code></td>
+<td>off</td>
+<td>Drop all annotations; the default keeps URI links</td>
+</tr>
+<tr>
+<td><code>--max-output-size &lt;n&gt;</code></td>
+<td>256 MiB</td>
+<td>Cap on the assembled size</td>
+</tr>
+<tr>
+<td><code>--stream</code></td>
+<td>off</td>
+<td>Stream the output (<code>--chunk-size N</code>)</td>
+</tr>
+<tr>
+<td><code>--dry-run</code></td>
+<td>off</td>
+<td>Validate without writing</td>
+</tr>
+</tbody></table>
+<h3 id="pdfnative-extract-text-v130"><code>pdfnative extract-text</code> <em>(v1.3.0)</em><a class="heading-anchor" href="#pdfnative-extract-text-v130" aria-label="Link to this section">#</a></h3>
+<p>Reading-order Unicode text from an existing PDF. <code>ndjson</code> emits one JSON object
+per page, which makes it a natural feed for a RAG ingestion pipeline.</p>
+<pre><code class="language-bash">pdfnative extract-text --input paper.pdf --format ndjson --runs &gt; pages.ndjson
+pdfnative extract-text --input paper.pdf --pages 1,3,5-7 --format text
+</code></pre>
+<table>
+<thead>
+<tr>
+<th>Flag</th>
+<th>Default</th>
+<th>Purpose</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>--format, -f &lt;fmt&gt;</code></td>
+<td><code>text</code></td>
+<td><code>text</code>, <code>json</code>, or <code>ndjson</code> (one object per page)</td>
+</tr>
+<tr>
+<td><code>--pages &lt;selector&gt;</code></td>
+<td>all</td>
+<td>1-based selector, e.g. <code>1,3,5-7</code></td>
+</tr>
+<tr>
+<td><code>--runs</code></td>
+<td>off</td>
+<td>Include positioned runs <code>{ text, x, y, fontSize, fontName }</code></td>
+</tr>
+<tr>
+<td><code>--password &lt;pass&gt;</code></td>
+<td>—</td>
+<td>Extract from an encrypted PDF</td>
+</tr>
+<tr>
+<td><code>--max-length &lt;n&gt;</code></td>
+<td>16000000</td>
+<td>Hard cap on total characters; <code>0</code> disables</td>
+</tr>
+<tr>
+<td><code>--summary</code></td>
+<td>off</td>
+<td>(json) Emit only <code>{ pages, characters }</code></td>
+</tr>
+<tr>
+<td><code>--fields &lt;paths&gt;</code></td>
+<td>—</td>
+<td>(json) Comma-separated dot-paths to keep</td>
+</tr>
+</tbody></table>
+<p>Text comes from the <code>/ToUnicode</code> mapping, so it is real Unicode rather than
+glyph indices. A page whose content decodes entirely to U+FFFD is reported as
+not extractable rather than returning noise.</p>
+<h3 id="pdfnative-doctor-v130"><code>pdfnative doctor</code> <em>(v1.3.0)</em><a class="heading-anchor" href="#pdfnative-doctor-v130" aria-label="Link to this section">#</a></h3>
+<p>Environment and capability preflight. The first thing to run in a new
+environment, and the first thing an agent should call before planning work.</p>
+<pre><code class="language-bash">pdfnative doctor              # human-readable
+pdfnative doctor --format json --pretty
+</code></pre>
+<table>
+<thead>
+<tr>
+<th>Flag</th>
+<th>Default</th>
+<th>Purpose</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>--format, -f &lt;fmt&gt;</code></td>
+<td><code>text</code></td>
+<td><code>text</code> or <code>json</code></td>
+</tr>
+<tr>
+<td><code>--pretty</code></td>
+<td>off</td>
+<td>Indented JSON even under the global <code>--json</code></td>
+</tr>
+</tbody></table>
+<h3 id="pdfnative-batch"><code>pdfnative batch</code><a class="heading-anchor" href="#pdfnative-batch" aria-label="Link to this section">#</a></h3>
+<p>Renders every JSON file in a directory to PDF <strong>in parallel</strong>, reusing the full <code>render</code> pipeline.</p>
+<table>
+<thead>
+<tr>
+<th>Flag</th>
+<th>Default</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>--input-dir &lt;dir&gt;</code></td>
+<td>— <em>(required)</em></td>
+<td>Directory of <code>*.json</code> documents</td>
+</tr>
+<tr>
+<td><code>--output-dir &lt;dir&gt;</code></td>
+<td>— <em>(required)</em></td>
+<td>Destination directory for <code>*.pdf</code> (created if absent)</td>
+</tr>
+<tr>
+<td><code>--concurrency &lt;n&gt;</code></td>
+<td><code>4</code></td>
+<td>Bounded parallelism</td>
+</tr>
+<tr>
+<td><code>--fail-fast</code></td>
+<td>off</td>
+<td>Abort on the first failure</td>
+</tr>
+<tr>
+<td><code>--dry-run</code> <em>(v1.1.0)</em></td>
+<td>off</td>
+<td>Validate every input without writing output</td>
+</tr>
+<tr>
+<td><code>--json</code> / <code>--summary</code> <em>(v1.1.0)</em></td>
+<td>off</td>
+<td>Machine-readable per-file report; <code>--summary</code> emits <code>{ total, succeeded, failed }</code></td>
+</tr>
+</tbody></table>
+<pre><code class="language-bash">pdfnative batch --input-dir inputs/ --output-dir outputs/ --tagged pdfa2b --concurrency 4
+</code></pre>
+<h3 id="pdfnative-schema"><code>pdfnative schema</code><a class="heading-anchor" href="#pdfnative-schema" aria-label="Link to this section">#</a></h3>
+<p>Prints a versioned <strong>JSON Schema (Draft 2020-12)</strong> for a CLI input/output shape, so agents can self-validate before invoking a command. The <code>$id</code> embeds the CLI version.</p>
+<pre><code class="language-bash">pdfnative schema render            # input schema for `render`
+pdfnative schema inspect-summary   # compact inspect verdict shape
+pdfnative schema list              # enumerate every subject
+</code></pre>
+<p>Subjects: <code>render</code>, <code>inspect</code>, <code>verify</code>, <code>batch</code>, <code>annotate</code> <em>(v1.2.0)</em>, <code>govern-verify</code> <em>(v1.2.0)</em>, <code>extract-text</code>, <code>fill</code>, <code>form-export</code>, <code>status</code>, <code>manifest</code>, <code>doctor</code> <em>(all v1.3.0)</em>, and the compact <code>inspect-summary</code> / <code>verify-summary</code> / <code>batch-summary</code> shapes. <code>pdfnative schema list</code> enumerates them all.</p>
+<h3 id="pdfnative-completion"><code>pdfnative completion</code><a class="heading-anchor" href="#pdfnative-completion" aria-label="Link to this section">#</a></h3>
+<p>Emits a shell-completion script: <code>pdfnative completion bash|zsh|fish|powershell</code> <em>(PowerShell added in v1.3.0)</em>.</p>
+<hr>
+<h2 id="agent-native-automation-contract">Agent-native automation contract<a class="heading-anchor" href="#agent-native-automation-contract" aria-label="Link to this section">#</a></h2>
+<p>v1.1.0 makes the CLI deterministic to drive from autonomous AI agents and CI pipelines. The full contract is documented in <a href="https://github.com/Nizoka/pdfnative-cli/blob/main/AGENTS.md" target="_blank" rel="noopener">pdfnative-cli AGENTS.md</a>.</p>
+<ul>
+<li><strong>Global <code>--json</code> envelope.</strong> Any command run with <code>--json</code> emits a single machine-readable object on <strong>stderr</strong>: <code>{ ok: false, command, error: { code, message } }</code> on failure, and a <code>{ ok: true, … }</code> status line for <code>render</code> / <code>sign</code> / <code>batch</code> on success (since v1.3.0, every write command emits the success line). stdout stays reserved for the primary artifact (PDF, report, schema, script).</li>
+<li><strong>Stable <code>E_*</code> error codes</strong> on every failure: <code>E_USAGE</code>, <code>E_INPUT</code>, <code>E_PARSE</code>, <code>E_IO</code>, <code>E_SIGN</code>, <code>E_VERIFY_FAILED</code>, <code>E_CHECK_FAILED</code>, <code>E_POLICY</code> <em>(v1.2.0 — governance-gate failure)</em>, <code>E_UNSUPPORTED</code>, <code>E_PASSWORD</code> <em>(v1.3.0 — encrypted PDF: password missing or incorrect)</em>, <code>E_RUNTIME</code>. Numeric exit codes (0/1/2) are unchanged.</li>
+<li><strong><code>--dry-run</code></strong> for <code>render</code>, <code>sign</code>, <code>batch</code>, and — since v1.2.0 — <code>merge</code>, <code>split</code>, <code>extract</code>, and <code>annotate</code> (v1.3.0 extends it to <code>fill</code>, <code>encrypt</code> and <code>decrypt</code>) — fully validate inputs (and, for <code>sign</code>, parse credentials and prepare the PDF) without producing output.</li>
+<li><strong>Token-economy output projection</strong> (<code>inspect</code> / <code>verify</code> / <code>batch</code> / <code>extract-text</code>): stdout JSON is <strong>compact by default</strong> under <code>--json</code> (<code>--pretty</code> opts back into the human 2-space form), <strong><code>--summary</code></strong> emits a canonical minimal verdict, and <strong><code>--fields a,b.c</code></strong> projects the result to named dot-paths. Typically ~90 % fewer output tokens with no loss of the fields agents branch on. Non-<code>--json</code> human output is unchanged.</li>
+</ul>
+<pre><code class="language-bash"># Agent-friendly: compact verdict on stdout, structured status on stderr
+pdfnative inspect --input report.pdf --json --summary 2&gt;status.json
+
+# Branch on a stable error class
+pdfnative verify --input report.pdf --json --strict \
+  || echo &quot;failed: $(jq -r .error.code status.json)&quot;
+</code></pre>
+<hr>
+<h2 id="recipes">Recipes<a class="heading-anchor" href="#recipes" aria-label="Link to this section">#</a></h2>
+<h3 id="render--sign--verify--inspect-in-a-single-chain">Render → sign → verify → inspect, in a single chain<a class="heading-anchor" href="#render--sign--verify--inspect-in-a-single-chain" aria-label="Link to this section">#</a></h3>
+<pre><code class="language-bash">cat report.json \
+  | pdfnative render --tagged pdfa2b --compress \
+  | pdfnative sign --reason &quot;Approved&quot; \
+  | tee signed.pdf \
+  | pdfnative verify --strict --trust ca.pem
+pdfnative inspect --input signed.pdf --check pdfa --check signed
+</code></pre>
+<h3 id="encrypted-pdfa-3-hybrid-invoice-factur-x--zugferd">Encrypted PDF/A-3 hybrid invoice (Factur-X / ZUGFeRD)<a class="heading-anchor" href="#encrypted-pdfa-3-hybrid-invoice-factur-x--zugferd" aria-label="Link to this section">#</a></h3>
+<pre><code class="language-bash">pdfnative render \
+  --input invoice.json --output invoice.pdf \
+  --tagged pdfa3b \
+  --attachment factur-x.xml:application/xml:Source:&quot;Structured invoice data&quot; \
+  --footer-center &quot;Page {page} / {pages}&quot;
+</code></pre>
+<h3 id="encrypted-distribution-copy">Encrypted distribution copy<a class="heading-anchor" href="#encrypted-distribution-copy" aria-label="Link to this section">#</a></h3>
+<pre><code class="language-bash">pdfnative render \
+  --input contract.json --output contract.encrypted.pdf \
+  --encrypt-algorithm aes256 \
+  --encrypt-permissions print
+# PDFNATIVE_ENCRYPT_OWNER_PASS read from the env — never on the command line
+</code></pre>
+<h3 id="multilang-fonts">Multilang fonts<a class="heading-anchor" href="#multilang-fonts" aria-label="Link to this section">#</a></h3>
+<p>For the 22 bundled scripts (plus <code>latin</code>, <code>emoji</code>, <code>color-emoji</code>, <code>math</code>), no wrapper is needed — <code>--font</code> registers each bundled font inside the CLI process:</p>
+<pre><code class="language-bash">echo &#39;{&quot;blocks&quot;:[{&quot;type&quot;:&quot;paragraph&quot;,&quot;text&quot;:&quot;สวัสดี こんにちは&quot;}]}&#39; \
+  | pdfnative render --font th --font ja --lang th,ja -o out.pdf
+</code></pre>
+<p>For a font you ship yourself (not bundled), the CLI cannot use it: in-memory font registration does not cross a process boundary, so a wrapper that registers fonts and then <em>spawns</em> the CLI does not work. Call the library directly instead:</p>
+<pre><code class="language-javascript">// render-custom-font.mjs
+import { registerFont, loadFontData, buildDocumentPDFBytes } from &#39;pdfnative&#39;;
+import { writeFile } from &#39;node:fs/promises&#39;;
+
+registerFont(&#39;th&#39;, () =&gt; import(&#39;./fonts/my-thai-data.js&#39;));
+const th = await loadFontData(&#39;th&#39;);
+if (!th) throw new Error(&#39;Thai font failed to load&#39;);
+const bytes = buildDocumentPDFBytes({
+  title: &#39;Thai demo&#39;,
+  blocks: [{ type: &#39;paragraph&#39;, text: &#39;สวัสดี&#39; }],
+  fontEntries: [{ fontData: th, fontRef: &#39;/F3&#39;, lang: &#39;th&#39; }], // /F1 and /F2 are reserved
+});
+await writeFile(&#39;out.pdf&#39;, bytes);
+</code></pre>
+<h3 id="ci-assertion-github-actions">CI assertion (GitHub Actions)<a class="heading-anchor" href="#ci-assertion-github-actions" aria-label="Link to this section">#</a></h3>
+<pre><code class="language-yaml">- name: Render and assert PDF/A + signed
+  run: |
+    pdfnative render --input data/q1.json --output dist/q1.pdf --tagged pdfa2b
+    pdfnative sign  --input dist/q1.pdf  --output dist/q1.signed.pdf
+    pdfnative verify --input dist/q1.signed.pdf --strict
+    pdfnative inspect --input dist/q1.signed.pdf --check pdfa --check signed
+</code></pre>
+<h3 id="batch-render-a-directory-of-json-files">Batch-render a directory of JSON files<a class="heading-anchor" href="#batch-render-a-directory-of-json-files" aria-label="Link to this section">#</a></h3>
+<pre><code class="language-bash">for f in inputs/*.json; do
+  pdfnative render --input &quot;$f&quot; --output &quot;outputs/$(basename &quot;$f&quot; .json).pdf&quot; --tagged pdfa2b
+done
+</code></pre>
+<hr>
+<h2 id="security-model">Security model<a class="heading-anchor" href="#security-model" aria-label="Link to this section">#</a></h2>
+<p><code>pdfnative-cli</code> is built with the same zero-trust posture as the underlying library:</p>
+<ul>
+<li><strong>No <code>eval</code>, no <code>Function</code>, no dynamic code</strong> — input JSON is parsed via the standard <code>JSON.parse</code> with a 50 MB cap to prevent memory exhaustion.</li>
+<li><strong>Path traversal protection</strong> — all <code>--input</code> / <code>--output</code> / <code>--key</code> / <code>--cert</code> / <code>--cert-chain</code> / <code>--trust</code> / <code>--layout</code> / <code>--attachment</code> / <code>--watermark-image</code> paths are validated against <code>..</code> segments before any file system access.</li>
+<li><strong>Secrets never logged</strong> — <code>loadPem</code> / <code>loadPemChain</code> surface only generic error messages on parse failure; raw key material never appears in <code>CliError</code> messages or stderr. Encryption passwords are never echoed.</li>
+<li><strong>Layout-file injection blocked</strong> — <code>attachments[].data</code> fields embedded in <code>--layout</code> JSON are <strong>stripped on load</strong>. Binary attachment payloads must come from <code>--attachment &lt;path&gt;</code> so the CLI can apply path validation.</li>
+<li><strong>Env-var precedence for secrets</strong> — <code>PDFNATIVE_SIGN_KEY</code> / <code>PDFNATIVE_SIGN_CERT</code> / <code>PDFNATIVE_SIGN_CHAIN</code> / <code>PDFNATIVE_ENCRYPT_OWNER_PASS</code> / <code>PDFNATIVE_ENCRYPT_USER_PASS</code> are preferred over file-path flags so secrets never enter shell history.</li>
+<li><strong>Stdin/stdout safe</strong> — binary streams are passed through without interpretation; no shell-quoting issues.</li>
+<li><strong>NPM provenance</strong> — every published version is signed via GitHub Actions OIDC. Verify with <code>npm audit signatures</code>.</li>
+</ul>
+<p>The CLI <strong>does not</strong> open network connections, write to system directories outside the working directory, or load arbitrary code. It only reads the files you point it at.</p>
+<hr>
+<h2 id="comparison-with-the-library-api">Comparison with the library API<a class="heading-anchor" href="#comparison-with-the-library-api" aria-label="Link to this section">#</a></h2>
+<p>The CLI now covers nearly the full library surface; only Web Worker offloading remains library-only.</p>
+<table>
+<thead>
+<tr>
+<th>Feature</th>
+<th>CLI v1.3.0</th>
+<th>Library</th>
+</tr>
+</thead>
+<tbody><tr>
+<td>Document rendering (13 block types)</td>
+<td>✅</td>
+<td>✅</td>
+</tr>
+<tr>
+<td>Streaming output</td>
+<td>✅ <code>--stream</code> / <code>--stream-true</code></td>
+<td>✅ <code>buildDocumentPDFStream()</code> / <code>buildDocumentPDFStreamTrue()</code></td>
+</tr>
+<tr>
+<td>Configurable block cap</td>
+<td>✅ <code>--max-blocks</code></td>
+<td>✅ <code>layout.maxBlocks</code></td>
+</tr>
+<tr>
+<td>PDF/A conformance (1b, 2b, 2u, 3b)</td>
+<td>✅ <code>--tagged</code></td>
+<td>✅ <code>tagged: &#39;…&#39;</code></td>
+</tr>
+<tr>
+<td>Digital signatures (RSA-SHA256)</td>
+<td>✅</td>
+<td>✅ <code>signPdfBytes()</code></td>
+</tr>
+<tr>
+<td>Digital signatures (ECDSA-SHA256)</td>
+<td>✅ <code>--algorithm ecdsa-sha256</code></td>
+<td>✅ <code>signPdfBytes()</code></td>
+</tr>
+<tr>
+<td><strong>Native constant-time signing</strong></td>
+<td>✅ default (<code>--pure-crypto</code> opts out; the native provider is a CLI utility)</td>
+<td>✅ <code>setCryptoProvider()</code> (accepts any <code>CryptoProvider</code>)</td>
+</tr>
+<tr>
+<td>Inspection / metadata</td>
+<td>✅</td>
+<td>✅ <code>PdfReader</code></td>
+</tr>
+<tr>
+<td><strong>PDF/UA structural validation</strong></td>
+<td>✅ <code>inspect --pdfua</code></td>
+<td>✅ <code>validatePdfUA()</code></td>
+</tr>
+<tr>
+<td><strong>Annotation listing</strong></td>
+<td>✅ <code>inspect --annotations</code></td>
+<td>✅ <code>getAnnotations()</code></td>
+</tr>
+<tr>
+<td><strong>Signature verification (CMS/PKCS#7)</strong></td>
+<td>✅ <code>verify</code> (real CMS, RSA + ECDSA — implemented in the CLI)</td>
+<td>➖ <code>openPdf()</code> + <code>verifyCertSignature()</code> only (X.509 certificate-signature check, not CMS PDF-signature verification)</td>
+</tr>
+<tr>
+<td><strong>PAdES-T timestamp + OCSP/CRL revocation</strong></td>
+<td>✅ <code>verify --revocation</code> (implemented in the CLI)</td>
+<td>—</td>
+</tr>
+<tr>
+<td><strong>Encryption (AES-128/256)</strong></td>
+<td>✅ <code>--encrypt-*</code></td>
+<td>✅ <code>encryption: {…}</code></td>
+</tr>
+<tr>
+<td><strong>Watermarks</strong></td>
+<td>✅ <code>--watermark-*</code></td>
+<td>✅ <code>watermark: {…}</code></td>
+</tr>
+<tr>
+<td><strong>PDF/A-3 attachments</strong></td>
+<td>✅ <code>--attachment</code></td>
+<td>✅ <code>attachments: [...]</code></td>
+</tr>
+<tr>
+<td><strong>22 scripts + COLRv1 emoji + math</strong></td>
+<td>✅ <code>--font</code> / <code>--lang</code></td>
+<td>✅ <code>registerFont()</code> / <code>loadFontData()</code></td>
+</tr>
+<tr>
+<td><strong>Page-tree editing (merge / split / extract)</strong></td>
+<td>✅ <code>merge</code> / <code>split</code> / <code>extract</code></td>
+<td>✅ <code>mergePdfs()</code> / <code>splitPdf()</code> / <code>extractPages()</code></td>
+</tr>
+<tr>
+<td><strong>Markup annotations</strong></td>
+<td>✅ <code>annotate</code></td>
+<td>✅ <code>PdfModifier.addAnnotation()</code> / <code>buildAnnotationBody()</code></td>
+</tr>
+<tr>
+<td><strong>Bookmarks / outline</strong></td>
+<td>✅ <code>render --outline</code></td>
+<td>✅ <code>outline: &#39;…&#39;</code></td>
+</tr>
+<tr>
+<td><strong>Layout introspection / debug</strong></td>
+<td>✅ <code>render --inspect-layout</code> / <code>--debug-layout</code></td>
+<td>✅ <code>inspectDocumentLayout()</code> / <code>layout.debug</code></td>
+</tr>
+<tr>
+<td><strong>AI-governance / HITL gate</strong></td>
+<td>✅ <code>govern</code> (draft validation via the CLI&#39;s <code>validateGovernanceDraft()</code>)</td>
+<td>— (contract files in the repo; the core&#39;s check is a repo script, not a published API)</td>
+</tr>
+<tr>
+<td><strong>Parallel batch render</strong></td>
+<td>✅ <code>batch</code></td>
+<td>— (compose <code>render</code>)</td>
+</tr>
+<tr>
+<td><strong>JSON Schema export</strong></td>
+<td>✅ <code>schema</code></td>
+<td>— N/A</td>
+</tr>
+<tr>
+<td><strong>Agent-native <code>--json</code>/<code>E_*</code>/<code>--dry-run</code></strong></td>
+<td>✅</td>
+<td>— N/A</td>
+</tr>
+<tr>
+<td><strong>Table-centric variant</strong></td>
+<td>✅ <code>--variant table</code></td>
+<td>✅ <code>buildPDFBytes()</code></td>
+</tr>
+<tr>
+<td><strong>Full <code>PdfLayoutOptions</code></strong></td>
+<td>✅ <code>--layout file.json</code></td>
+<td>✅</td>
+</tr>
+<tr>
+<td><strong>Web Worker offloading</strong></td>
+<td>❌ N/A</td>
+<td>✅ <code>pdfWorker.ts</code></td>
+</tr>
+</tbody></table>
+<hr>
+<h2 id="examples--ready-to-run">Examples — ready-to-run<a class="heading-anchor" href="#examples--ready-to-run" aria-label="Link to this section">#</a></h2>
+<p>The <a href="https://github.com/Nizoka/pdfnative-cli/tree/main/samples" target="_blank" rel="noopener"><code>samples/</code></a> directory in the CLI repository ships <strong>40+ ready-to-run examples</strong> organized by feature:</p>
+<table>
+<thead>
+<tr>
+<th>Category</th>
+<th>What it shows</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>render/document/</code></td>
+<td>Minimal document, all blocks reference, invoice, technical spec, multi-page report</td>
+</tr>
+<tr>
+<td><code>render/table/</code></td>
+<td>Project status, financial summary</td>
+</tr>
+<tr>
+<td><code>render/table-variant/</code></td>
+<td><code>PdfParams</code>-shaped financial ledger via <code>--variant table</code></td>
+</tr>
+<tr>
+<td><code>render/barcode/</code></td>
+<td>QR code, Code 128, EAN-13</td>
+</tr>
+<tr>
+<td><code>render/form/</code></td>
+<td>Contact form, survey</td>
+</tr>
+<tr>
+<td><code>render/toc/</code></td>
+<td>Auto-generated table of contents with <code>/GoTo</code> links</td>
+</tr>
+<tr>
+<td><code>render/link/</code></td>
+<td>Resource directory with hyperlinks</td>
+</tr>
+<tr>
+<td><code>render/watermark/</code></td>
+<td>Draft / Confidential watermarks</td>
+</tr>
+<tr>
+<td><code>render/layout/</code></td>
+<td>US Letter, A5 portrait, A4 landscape</td>
+</tr>
+<tr>
+<td><code>render/pdfa/</code></td>
+<td>PDF/A-1b, 2b, 3b archival conformance</td>
+</tr>
+<tr>
+<td><code>render/encryption/</code></td>
+<td>AES-128 password-protected PDF</td>
+</tr>
+<tr>
+<td><code>render/headers-footers/</code></td>
+<td>Page templates with <code>{page}/{pages}/{date}/{title}</code></td>
+</tr>
+<tr>
+<td><code>render/attachments/</code></td>
+<td>PDF/A-3 hybrid invoice with embedded XML (Factur-X / ZUGFeRD)</td>
+</tr>
+<tr>
+<td><code>render/multilang/</code></td>
+<td>Multilang rendering via the bundled <code>--font</code> shortcuts</td>
+</tr>
+<tr>
+<td><code>render/chart/</code></td>
+<td>Native vector charts (bar, line, pie, donut) <em>(v1.3.0)</em></td>
+</tr>
+<tr>
+<td><code>render/math/</code></td>
+<td>Noto Sans Math font routing <em>(v1.2.0)</em></td>
+</tr>
+<tr>
+<td><code>render/outline/</code></td>
+<td><code>/Outlines</code> bookmark trees (<code>--outline auto</code> and explicit JSON) <em>(v1.2.0)</em></td>
+</tr>
+<tr>
+<td><code>render/table-smart/</code></td>
+<td>Smart-table flags (<code>--table-wrap</code>, <code>--zebra</code>, …) <em>(v1.3.0)</em></td>
+</tr>
+<tr>
+<td><code>render/font/</code>, <code>render/template/</code>, <code>render/watch/</code>, <code>render/inspect-layout/</code></td>
+<td>Font shortcuts, templates, watch mode, layout introspection</td>
+</tr>
+<tr>
+<td><code>fill/</code></td>
+<td>AcroForm fill / flatten / export round trip <em>(v1.3.0)</em></td>
+</tr>
+<tr>
+<td><code>encrypt/</code></td>
+<td>Encrypt / decrypt an existing PDF <em>(v1.3.0)</em></td>
+</tr>
+<tr>
+<td><code>extract-text/</code></td>
+<td>Reading-order text extraction (<code>text</code> / <code>json</code> / <code>ndjson</code>) <em>(v1.3.0)</em></td>
+</tr>
+<tr>
+<td><code>merge/</code>, <code>split/</code>, <code>extract/</code>, <code>annotate/</code></td>
+<td>Page-tree editing and markup annotations <em>(v1.2.0)</em></td>
+</tr>
+<tr>
+<td><code>sign/</code></td>
+<td>Bash + PowerShell signing scripts (basic + with metadata)</td>
+</tr>
+<tr>
+<td><code>inspect/</code></td>
+<td>JSON &amp; text inspection, <code>--verbose --pages</code>, <code>--check pdfa</code></td>
+</tr>
+<tr>
+<td><code>verify/</code></td>
+<td>Self-signed verification, strict-mode CI gating</td>
+</tr>
+<tr>
+<td><code>batch/</code>, <code>doctor/</code>, <code>govern/</code>, <code>completion/</code>, <code>agent/</code>, <code>config/</code></td>
+<td>Automation, preflight, governance, shell completion, agent patterns</td>
+</tr>
+<tr>
+<td><code>streaming/</code></td>
+<td>200-section document via streaming render</td>
+</tr>
+</tbody></table>
+<p>Render them all at once:</p>
+<pre><code class="language-bash">git clone https://github.com/Nizoka/pdfnative-cli
+cd pdfnative-cli
+node samples/run-all.js
+</code></pre>
+<hr>
+<h2 id="release-history">Release history<a class="heading-anchor" href="#release-history" aria-label="Link to this section">#</a></h2>
+<h3 id="whats-new-in-v130">What&#39;s new in v1.3.0<a class="heading-anchor" href="#whats-new-in-v130" aria-label="Link to this section">#</a></h3>
+<p>v1.3.0 is built on the <strong>pdfnative 1.6 engine</strong> (pin <code>^1.6.0</code>) and surfaces its engine additions as five new commands (<code>extract-text</code>, <code>fill</code>, <code>encrypt</code>, <code>decrypt</code>, <code>doctor</code>), native vector charts in <code>render</code>, and password / re-encryption / constant-memory streaming on the page-tree commands. Fixes a silent <code>render --encrypt</code> no-op. <strong>100 % backward-compatible</strong> with v1.2.0.</p>
+<table>
+<thead>
+<tr>
+<th>Area</th>
+<th>v1.2.0</th>
+<th>v1.3.0</th>
+</tr>
+</thead>
+<tbody><tr>
+<td>Commands</td>
+<td>12 commands <!-- verify-docs:allow stale-token (v1.2.0-era count) --></td>
+<td>adds <strong><code>fill</code></strong> (fill / flatten / <strong>export</strong> AcroForms via an incremental save), <strong><code>encrypt</code></strong>, <strong><code>decrypt</code></strong>, <strong><code>extract-text</code></strong> (reading-order Unicode text: <code>text</code> | <code>json</code> | <code>ndjson</code>), and <strong><code>doctor</code></strong> (offline environment / capability preflight)</td>
+</tr>
+<tr>
+<td>Charts</td>
+<td>—</td>
+<td>the engine&#39;s <code>chart</code> document block (bar, barH, line, pie, donut — the pdfnative 1.6 set) renders as pure vector path operators through <code>render</code></td>
+</tr>
+<tr>
+<td>Encryption vocabulary</td>
+<td><code>--encrypt-*</code> flags on <code>render</code> only</td>
+<td><strong>unified vocabulary</strong> — <code>--encrypt [aes-128|aes-256]</code>, <code>--owner-password</code>, <code>--user-password</code>, <code>--permissions print,copy,modify,extract</code> — shared by <code>render</code>, <code>merge</code>, <code>split</code> and <code>extract</code> (legacy <code>--encrypt-*</code> flags kept as aliases)</td>
+</tr>
+<tr>
+<td>Page-tree commands</td>
+<td>plaintext sources only</td>
+<td><strong><code>--password</code></strong> reads encrypted sources; <strong><code>--encrypt</code></strong> re-encrypts the output; <strong><code>--stream</code></strong> (+ <code>--chunk-size</code>) streams the output with constant memory</td>
+</tr>
+<tr>
+<td>Inspection</td>
+<td>metadata, PDF/UA, annotations</td>
+<td>adds <code>inspect --form-fields</code>, <code>--encryption</code> and <code>--password</code></td>
+</tr>
+<tr>
+<td>Shell completion</td>
+<td>bash, zsh, fish</td>
+<td>adds <strong>powershell</strong></td>
+</tr>
+<tr>
+<td>Agent contract</td>
+<td><code>--json</code> / <code>E_*</code> / <code>--dry-run</code> / schemas</td>
+<td>adds the stable <strong><code>E_PASSWORD</code></strong> code and an agent capability manifest (<code>schema manifest</code> + <code>llms.txt</code>)</td>
+</tr>
+<tr>
+<td>Compatibility</td>
+<td><code>pdfnative ^1.5.0</code></td>
+<td><code>pdfnative ^1.6.0</code></td>
+</tr>
+</tbody></table>
+<p>Full changelog: <a href="https://github.com/Nizoka/pdfnative-cli/releases/tag/v1.3.0" target="_blank" rel="noopener">pdfnative-cli release notes v1.3.0</a>.</p>
+<h3 id="whats-new-in-v120">What&#39;s new in v1.2.0<a class="heading-anchor" href="#whats-new-in-v120" aria-label="Link to this section">#</a></h3>
+<!-- verify-docs:allow version-token (historical release entry) -->
+<p>v1.2.0 lands the <strong>pdfnative 1.5.0</strong> engine&#39;s page-tree and annotation APIs on the CLI as five new commands, adds document bookmarks, a math font, layout introspection, native constant-time signing, and — for autonomous agents — surfaces pdfnative&#39;s <strong>AI-governance / Human-in-the-Loop (HITL)</strong> contract. <strong>100 % backward-compatible</strong> with v1.1.0.</p>
+<table>
+<thead>
+<tr>
+<th>Area</th>
+<th>v1.1.0</th>
+<th>v1.2.0</th>
+</tr>
+</thead>
+<tbody><tr>
+<td>Commands</td>
+<td>render, sign, inspect, verify, batch, schema</td>
+<td>adds <strong><code>merge</code></strong>, <strong><code>split</code></strong>, <strong><code>extract</code></strong> (page-tree), <strong><code>annotate</code></strong> (markup), and <strong><code>govern</code></strong> (<code>rules</code> / <code>policy</code> / <code>verify-issue</code>)</td>
+</tr>
+<tr>
+<td>Bookmarks</td>
+<td>—</td>
+<td><strong><code>render --outline auto</code></strong> derives a <code>/Outlines</code> bookmark tree from headings; <code>--outline &lt;tree.json&gt;</code> supplies an explicit <code>OutlineItem[]</code></td>
+</tr>
+<tr>
+<td>Math font</td>
+<td>—</td>
+<td><strong><code>render --font math</code></strong> registers the bundled Noto Sans Math font; pdfnative auto-routes math-operator / geometric-shape code points to it</td>
+</tr>
+<tr>
+<td>Layout tooling</td>
+<td>—</td>
+<td><strong><code>render --inspect-layout</code></strong> emits a <code>LayoutInspection</code> JSON report; <strong><code>--debug-layout [margins,content,cells]</code></strong> overlays layout guides on a normal PDF</td>
+</tr>
+<tr>
+<td>Signing</td>
+<td>pure-JS bignum CMS</td>
+<td><strong>native <code>node:crypto</code> by default</strong> (constant-time, side-channel-resistant RSA/ECDSA); <strong><code>--pure-crypto</code></strong> opts back into the portable pure-JS path</td>
+</tr>
+<tr>
+<td>Inspection</td>
+<td>metadata, PDF/UA</td>
+<td><strong><code>inspect --annotations</code></strong> lists markup + link annotations; <code>/PageLabels</code> are reported automatically when present</td>
+</tr>
+<tr>
+<td>Agent / governance</td>
+<td><code>--json</code>/<code>E_*</code>/<code>--dry-run</code></td>
+<td>adds the stable <strong><code>E_POLICY</code></strong> code; <code>schema</code> gains <code>annotate</code> + <code>govern-verify</code> subjects; <code>--dry-run</code> now also covers <code>merge</code> / <code>split</code> / <code>extract</code> / <code>annotate</code></td>
+</tr>
+<tr>
+<td>Compatibility</td>
+<td><code>pdfnative ^1.3.0</code></td>
+<td><code>pdfnative ^1.5.0</code></td>
+</tr>
+</tbody></table>
+<p>Full changelog: <a href="https://github.com/Nizoka/pdfnative-cli/releases/tag/v1.2.0" target="_blank" rel="noopener">pdfnative-cli release notes v1.2.0</a>. <!-- verify-docs:allow version-token (historical link) --></p>
+<h3 id="previously-in-v110">Previously in v1.1.0<a class="heading-anchor" href="#previously-in-v110" aria-label="Link to this section">#</a></h3>
+<!-- verify-docs:allow version-token (historical release entry) -->
+<p>v1.1.0 is built on <strong>pdfnative 1.3.0</strong> and surfaces its new engine capabilities through the CLI, plus a full agent-native automation contract. <strong>100 % backward-compatible</strong> with v0.3.0.</p>
+<table>
+<thead>
+<tr>
+<th>Area</th>
+<th>v0.3.0</th>
+<th>v1.1.0</th>
+</tr>
+</thead>
+<tbody><tr>
+<td>Fonts</td>
+<td><code>--font {latin,emoji}</code></td>
+<td><strong>22 Unicode scripts + COLRv1 colour emoji</strong> — <code>--font</code>/<code>--lang</code> allow-list covers every bundled font (<code>latin</code>, <code>emoji</code>, <code>color-emoji</code>, and the 22 script codes incl. Telugu <code>te</code>, Sinhala <code>si</code>, Tibetan <code>bo</code>, Khmer <code>km</code>, Myanmar <code>my</code>, Amharic <code>am</code>)</td>
+</tr>
+<tr>
+<td>Streaming</td>
+<td><code>--stream</code> (single-pass), page-by-page</td>
+<td>adds <strong><code>--stream-true</code></strong> — true constant-memory streaming via <code>buildDocumentPDFStreamTrue</code> / <code>buildPDFStreamTrue</code>; the joined binary never materialises</td>
+</tr>
+<tr>
+<td>Block cap</td>
+<td>hard-coded ceiling</td>
+<td><strong><code>--max-blocks &lt;n&gt;</code></strong> exposes <code>layout.maxBlocks</code> (default 100 000) for very large reports</td>
+</tr>
+<tr>
+<td>Accessibility</td>
+<td>—</td>
+<td><strong>PDF/UA (ISO 14289-1) structural validator</strong> — <code>inspect --pdfua</code> and <code>--check pdfua</code> as a CI accessibility gate</td>
+</tr>
+<tr>
+<td>Agent contract</td>
+<td>—</td>
+<td>global <strong><code>--json</code></strong> status/error envelope on stderr, stable <strong><code>E_*</code> error codes</strong>, <strong><code>--dry-run</code></strong>, token-economy <strong><code>--summary</code></strong> / <strong><code>--fields</code></strong> projection, compact JSON by default</td>
+</tr>
+<tr>
+<td>Commands</td>
+<td>render, sign, inspect, verify</td>
+<td>adds <strong><code>batch</code></strong> (parallel directory render) and <strong><code>schema</code></strong> (JSON Schema export)</td>
+</tr>
+<tr>
+<td>Supply chain</td>
+<td>provenance</td>
+<td>adds a CycloneDX <strong>SBOM</strong> (<code>sbom.cdx.json</code>) attached to every release + OpenSSF Scorecard badge</td>
+</tr>
+<tr>
+<td>Compatibility</td>
+<td><code>pdfnative ^1.1.0</code></td>
+<td><code>pdfnative ^1.3.0</code></td>
+</tr>
+</tbody></table>
+<p>Full changelog: <a href="https://github.com/Nizoka/pdfnative-cli/releases/tag/v1.1.0" target="_blank" rel="noopener">pdfnative-cli release notes v1.1.0</a>. <!-- verify-docs:allow version-token (historical link) --></p>
+<h3 id="previously-in-v030">Previously in v0.3.0<a class="heading-anchor" href="#previously-in-v030" aria-label="Link to this section">#</a></h3>
+<p>v0.3.0 finished the digital-signature story and added three iteration-friendly <code>render</code> flags. <strong>100 % backward-compatible</strong> with v0.2.0.</p>
+<table>
+<thead>
+<tr>
+<th>Area</th>
+<th>v0.2.0</th>
+<th>v0.3.0</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>sign</code> algorithm</td>
+<td>RSA-SHA256 only (ECDSA stub)</td>
+<td>RSA-SHA256 <strong>and</strong> ECDSA-SHA256 — fully wired via <code>parseEcPrivateKey</code> (SEC1 / PKCS#8 P-256)</td>
+</tr>
+<tr>
+<td><code>sign</code> placeholder</td>
+<td>Required a prior <code>prepare_signature_placeholder</code> call</td>
+<td><strong>Auto-injection</strong> — CLI detects PDFs with no AcroForm signature field and adds <code>/Sig</code> via a single incremental update</td>
+</tr>
+<tr>
+<td><code>verify</code> scope</td>
+<td>Byte-range integrity + cert chain</td>
+<td>Real CMS/PKCS#7 verification — signature value (RSA + ECDSA), message digest, certificate chain, trust roots, RFC 3161 timestamp detection</td>
+</tr>
+<tr>
+<td><code>render --watch</code></td>
+<td>—</td>
+<td>Re-render on input change (200 ms debounce, stderr-only logs)</td>
+</tr>
+<tr>
+<td><code>render --template &lt;file.json&gt;</code></td>
+<td>—</td>
+<td>Deep-merge a base template under stdin / <code>--input</code></td>
+</tr>
+<tr>
+<td><code>render --font &lt;name&gt;</code></td>
+<td>—</td>
+<td>Bundled font shortcut (<code>latin</code>, <code>emoji</code>)</td>
+</tr>
+<tr>
+<td>Compatibility</td>
+<td><code>pdfnative ^1.0.5</code></td>
+<td><code>pdfnative ^1.1.0</code></td>
+</tr>
+</tbody></table>
+<h3 id="previously-in-v020">Previously in v0.2.0<a class="heading-anchor" href="#previously-in-v020" aria-label="Link to this section">#</a></h3>
+<p>The v0.2.0 release expanded the CLI from ~10 flags to a near-complete projection of the <code>pdfnative</code> v1.0.5 surface, while remaining 100 % backward-compatible with v0.1.0.</p>
+<table>
+<thead>
+<tr>
+<th>Area</th>
+<th>v0.1.0</th>
+<th>v0.2.0</th>
+</tr>
+</thead>
+<tbody><tr>
+<td>Layout</td>
+<td><code>--conformance</code> only</td>
+<td>Hybrid model — high-frequency knobs as flags, full <code>PdfLayoutOptions</code> via <code>--layout file.json</code></td>
+</tr>
+<tr>
+<td>PDF/A</td>
+<td><code>--conformance 1b|2b|3b</code></td>
+<td><code>--tagged none|pdfa1b|pdfa2b|pdfa2u|pdfa3b</code> (<code>--conformance</code> deprecated)</td>
+</tr>
+<tr>
+<td>Encryption</td>
+<td>—</td>
+<td><code>--encrypt-owner-pass</code>, <code>--encrypt-user-pass</code>, <code>--encrypt-algorithm</code>, <code>--encrypt-permissions</code> (env-var precedence)</td>
+</tr>
+<tr>
+<td>Watermarks</td>
+<td>—</td>
+<td><code>--watermark-text</code>/<code>-image</code>/<code>-opacity</code>/<code>-angle</code>/<code>-color</code>/<code>-font-size</code>/<code>-position</code></td>
+</tr>
+<tr>
+<td>Headers / footers</td>
+<td>—</td>
+<td><code>--header-{l,c,r}</code>, <code>--footer-{l,c,r}</code> with <code>{page}/{pages}/{date}/{title}</code> placeholders</td>
+</tr>
+<tr>
+<td>PDF/A-3 attachments</td>
+<td>—</td>
+<td><code>--attachment &lt;path&gt;[:mime[:rel[:desc]]]</code> (repeatable)</td>
+</tr>
+<tr>
+<td>Multilingual fonts</td>
+<td>—</td>
+<td><code>--lang th,ja,ar</code> (at the time, required a wrapper registering fonts via <code>registerFont()</code>; superseded by <code>--font</code> in v1.1.0)</td>
+</tr>
+<tr>
+<td><code>verify</code> command</td>
+<td>n/a</td>
+<td>byte-range integrity + cert chain + <code>--trust</code> roots</td>
+</tr>
+</tbody></table>
+<hr>
+<h2 id="migration-v030--v110">Migration v0.3.0 → v1.1.0<a class="heading-anchor" href="#migration-v030--v110" aria-label="Link to this section">#</a></h2>
+<p><strong>100 % backward-compatible.</strong> Every v0.3.0 invocation continues to produce a byte-equivalent PDF. New, optional opportunities:</p>
+<pre><code class="language-diff"># 1. True constant-memory streaming for very large reports
+- pdfnative render --input big.json --output big.pdf --stream
++ pdfnative render --input big.json --output big.pdf --stream-true
+
+# 2. CI accessibility gate (PDF/UA)
++ pdfnative inspect --input report.pdf --check pdfua
+
+# 3. Agent-native, token-frugal output
++ pdfnative inspect --input report.pdf --json --summary
+
+# 4. Parallel directory render
++ pdfnative batch --input-dir inputs/ --output-dir outputs/ --concurrency 4
+</code></pre>
+<h2 id="migration-v020--v030">Migration v0.2.0 → v0.3.0<a class="heading-anchor" href="#migration-v020--v030" aria-label="Link to this section">#</a></h2>
+<p><strong>100 % backward-compatible.</strong> Three forward-looking opportunities:</p>
+<pre><code class="language-diff"># 1. ECDSA signing now works without a workaround
+- pdfnative sign -i in.pdf -o out.pdf --algorithm rsa-sha256 ...
++ pdfnative sign -i in.pdf -o out.pdf --algorithm ecdsa-sha256 \
++   --key ec-key.pem --cert ec-cert.pem
+
+# 2. Sign without a prior placeholder step
+- pdfnative sign -i with-placeholder.pdf -o signed.pdf ...
++ pdfnative sign -i any-pdf.pdf -o signed.pdf ...   # placeholder auto-injected
+</code></pre>
+<h2 id="migration-v010--v020">Migration v0.1.0 → v0.2.0<a class="heading-anchor" href="#migration-v010--v020" aria-label="Link to this section">#</a></h2>
+<p><strong>100 % backward-compatible</strong> — every v0.1.0 invocation continues to produce a byte-equivalent PDF, modulo a one-line stderr notice for <code>--conformance</code>. All v0.1.0 exit codes and JSON shapes are preserved; new <code>inspect</code> JSON fields are additive only.</p>
+<p>The only soft change you should plan for:</p>
+<pre><code class="language-diff">- pdfnative render --input doc.json --output report.pdf --conformance 2b
++ pdfnative render --input doc.json --output report.pdf --tagged pdfa2b
+</code></pre>
+<p><code>--conformance</code> will be <strong>removed in v1.0.0</strong> of the CLI.</p>
+<hr>
+<h2 id="troubleshooting">Troubleshooting<a class="heading-anchor" href="#troubleshooting" aria-label="Link to this section">#</a></h2>
+<h3 id="command-not-found-pdfnative"><code>command not found: pdfnative</code><a class="heading-anchor" href="#command-not-found-pdfnative" aria-label="Link to this section">#</a></h3>
+<p>You installed via <code>npx</code> (one-shot) and not globally. Either prepend <code>npx</code> to every invocation, or run <code>npm install --global pdfnative-cli</code>.</p>
+<h3 id="json-parse-error-input-too-large"><code>JSON parse error: input too large</code><a class="heading-anchor" href="#json-parse-error-input-too-large" aria-label="Link to this section">#</a></h3>
+<p>The CLI caps input JSON at 50 MB to prevent memory exhaustion. For very large documents, either split the document into multiple PDFs or use the library directly with the streaming API.</p>
+<h3 id="error-invalid-private-key"><code>Error: invalid private key</code><a class="heading-anchor" href="#error-invalid-private-key" aria-label="Link to this section">#</a></h3>
+<p>Both RSA PKCS#1 and ECDSA P-256 keys are accepted, but they must be <strong>PEM-encoded</strong>. Convert DER to PEM with <code>openssl pkcs8 -topk8 -in key.der -out key.pem -nocrypt</code>. As of v0.3.0, ECDSA support in <code>sign</code> is fully wired (SEC1 / PKCS#8 P-256 via <code>parseEcPrivateKey</code>).</p>
+<h3 id="encryption-requires-an-owner-password-provide---owner-password-pass-or-pdfnative_encrypt_owner_pass"><code>Encryption requires an owner password. Provide --owner-password &lt;pass&gt; or $PDFNATIVE_ENCRYPT_OWNER_PASS.</code><a class="heading-anchor" href="#encryption-requires-an-owner-password-provide---owner-password-pass-or-pdfnative_encrypt_owner_pass" aria-label="Link to this section">#</a></h3>
+<p>Any encryption flag was set without an owner password. Provide it via <code>--owner-password &lt;pass&gt;</code> (legacy alias: <code>--encrypt-owner-pass</code>) or — recommended — the <code>PDFNATIVE_ENCRYPT_OWNER_PASS</code> env var so it never enters shell history.</p>
+<h3 id="error---tagged-pdfa-and---encrypt--are-mutually-exclusive"><code>Error: --tagged pdfa* and --encrypt-* are mutually exclusive</code><a class="heading-anchor" href="#error---tagged-pdfa-and---encrypt--are-mutually-exclusive" aria-label="Link to this section">#</a></h3>
+<p>ISO 19005-1 §6.3.2 forbids encryption in PDF/A. Pick one — either an archival PDF/A document, or an encrypted distribution copy, but not both.</p>
+<h3 id="enoent-no-such-file-or-directory-d--windows"><code>ENOENT: no such file or directory, &#39;D\&#39;</code>  (Windows)<a class="heading-anchor" href="#enoent-no-such-file-or-directory-d--windows" aria-label="Link to this section">#</a></h3>
+<p>This was a v0.1.0 / pre-v0.2.0 regression: <code>--attachment D:\file.xml</code> was split at the drive-letter colon. Fixed in v0.2.0 — make sure you&#39;re on <code>pdfnative-cli@^0.2.0</code>.</p>
+<h3 id="layout-file-is-ignored-when-i-also-pass-cli-flags">Layout file is ignored when I also pass CLI flags<a class="heading-anchor" href="#layout-file-is-ignored-when-i-also-pass-cli-flags" aria-label="Link to this section">#</a></h3>
+<p>That is the <strong>intended precedence</strong>: <code>CLI flags &gt; --layout file &gt; pdfnative defaults</code>. To merge nested objects (e.g. a watermark in the layout file plus a <code>--watermark-text</code> on the CLI), the CLI now correctly merges <code>params.layout</code> with CLI-derived flags as of v0.2.0 (previously the JSON-embedded layout could be silently dropped — fixed).</p>
+<h3 id="--lang-th-does-not-produce-thai-glyphs"><code>--lang th</code> does not produce Thai glyphs<a class="heading-anchor" href="#--lang-th-does-not-produce-thai-glyphs" aria-label="Link to this section">#</a></h3>
+<p><code>--lang</code> only <em>activates</em> fonts that are registered in the CLI process — pass <code>--font th</code> as well so the bundled Noto Thai module is registered (<code>--font</code> covers all 22 bundled scripts, <code>latin</code>, <code>emoji</code>, <code>color-emoji</code>, <code>math</code>). A wrapper script that registers fonts and then spawns the CLI does <strong>not</strong> work: in-memory registration does not cross a process boundary. For a non-bundled font you ship yourself, call the library directly — see <em>Recipes → Multilang fonts</em>.</p>
+<h3 id="signed-pdf-fails-adobe-verification">Signed PDF fails Adobe verification<a class="heading-anchor" href="#signed-pdf-fails-adobe-verification" aria-label="Link to this section">#</a></h3>
+<p>Ensure your certificate&#39;s signing-key usage extension includes <code>digitalSignature</code> (key usage 0). Self-signed certificates work for testing but require the validator to trust the issuer — pass <code>--trust ca-root.pem</code> to <code>verify</code> for self-signed setups.</p>
+<hr>
+<h2 id="resources">Resources<a class="heading-anchor" href="#resources" aria-label="Link to this section">#</a></h2>
+<ul>
+<li>📦 <strong>npm:</strong> <a href="https://www.npmjs.com/package/pdfnative-cli" target="_blank" rel="noopener">pdfnative-cli</a></li>
+<li>🏛️ <strong>Repo:</strong> <a href="https://github.com/Nizoka/pdfnative-cli" target="_blank" rel="noopener">Nizoka/pdfnative-cli</a></li>
+<li>📚 <strong>Knowledge base:</strong> <a href="https://github.com/Nizoka/pdfnative-cli/blob/main/docs/KNOWLEDGE_BASE.md" target="_blank" rel="noopener">pdfnative-cli/docs/KNOWLEDGE_BASE.md</a> — full architecture, integration patterns, FAQ</li>
+<li>📁 <strong>Samples:</strong> <a href="https://github.com/Nizoka/pdfnative-cli/tree/main/samples" target="_blank" rel="noopener">pdfnative-cli/samples</a></li>
+<li>🧪 <strong>Try it interactively:</strong> <a href="../playgrounds/cli.html">CLI playground</a> — build commands without leaving the browser</li>
+<li>🔧 <strong>Underlying library:</strong> <a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener"><code>pdfnative</code></a></li>
+<li>🤖 <strong>AI integration:</strong> <a href="mcp.html">pdfnative-mcp guide</a> — same library exposed as a Model Context Protocol server</li>
+<li>🐛 <strong>Report a bug:</strong> <a href="https://github.com/Nizoka/pdfnative-cli/issues" target="_blank" rel="noopener">Nizoka/pdfnative-cli/issues</a></li>
+<li>💬 <strong>Discuss:</strong> <a href="https://github.com/Nizoka/pdfnative-cli/discussions" target="_blank" rel="noopener">Nizoka/pdfnative-cli/discussions</a></li>
+</ul>
+<hr>
+<h2 id="citation">Citation<a class="heading-anchor" href="#citation" aria-label="Link to this section">#</a></h2>
+<p>If you use the CLI in research or academic pipelines, cite both repositories:</p>
+<pre><code class="language-bibtex">@software{pdfnative_cli_2026,
+  title  = {pdfnative-cli: Official CLI for the pdfnative PDF generation library},
+  author = {Nizoka},
+  year   = {2026},
+  url    = {https://github.com/Nizoka/pdfnative-cli},
+  license = {MIT}
+}
+</code></pre>
+<!-- guide:render:end -->
+  </article>
+</main>
+
+<footer class="footer">
+  <div class="footer-inner">
+    <span>MIT License · © 2026 Nizoka</span>
+    <ul class="footer-links" role="list">
+      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
+      <li><a href="https://www.npmjs.com/package/pdfnative" target="_blank" rel="noopener">npm</a></li>
+      <li><a href="https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md" target="_blank" rel="noopener">Changelog</a></li>
+      <li><a href="./">All guides</a></li>
+    </ul>
+  </div>
+</footer>
+
+<script src="https://cdn.jsdelivr.net/npm/marked@12.0.2/marked.min.js" integrity="sha384-/TQbtLCAerC3jgaim+N78RZSDYV7ryeoBCVqTuzRrFec2akfBkHS7ACQ3PQhvMVi" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/dompurify@3.1.5/dist/purify.min.js" integrity="sha384-nszIONF2FGC59kn+pPFaRa6WUNGwsZgXZiJxJwQbym+TzcH7smolUviLgpPbNx7V" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/prism.min.js" integrity="sha384-BGaNxfftg+9+TtC098wxawPFVEUpKYvaiCgbB0iqAMjK/4jDdmUY+oGxrPNvnXEf" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-typescript.min.js" integrity="sha384-PeOqKNW/piETaCg8rqKFy+Pm6KEk7e36/5YZE5XO/OaFdO+/Aw3O8qZ9qDPKVUgx" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-bash.min.js" integrity="sha384-9WmlN8ABpoFSSHvBGGjhvB3E/D8UkNB9HpLJjBQFC2VSQsM1odiQDv4NbEo+7l15" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-json.min.js" integrity="sha384-RhrmFFMb0ZCHImjFMpR/UE3VEtIVTCtNrtKQqXCzqXZNJala02N3UbVhi+qzw3CY" crossorigin="anonymous" defer></script>
+<script src="guide.js" defer></script>
+</body>
+</html>
diff --git a/docs/guides/cli.md b/docs/guides/cli.md
index e9708b2..c2effa0 100644
--- a/docs/guides/cli.md
+++ b/docs/guides/cli.md
@@ -1,6 +1,6 @@
 # pdfnative-cli — Command-Line Interface Guide
 
-> **Tracks the latest published `pdfnative-cli`** (v1.3.0, built on pdfnative 1.7.0). The CLI versions independently from the library. Live package versions — and the `pdfnative` version each one is built on — are shown at the top of the [documentation home](../index.html). Full history: [pdfnative-cli releases](https://github.com/Nizoka/pdfnative-cli/releases).
+> **Tracks the latest published `pdfnative-cli`** (v1.3.0, built on the pdfnative 1.6 engine — pins `^1.6.0`, which semver-accepts 1.7.0). The CLI versions independently from the library. Live package versions — and the `pdfnative` version each one is built on — are shown at the top of the [documentation home](../index.html). Full history: [pdfnative-cli releases](https://github.com/Nizoka/pdfnative-cli/releases).
 
 [`pdfnative-cli`](https://github.com/Nizoka/pdfnative-cli) is the **official command-line interface** for the [`pdfnative`](https://github.com/Nizoka/pdfnative) library. It exposes 17 commands in five groups — create & edit (`render`, `fill`, `annotate`), page tree (`merge`, `split`, `extract`), security (`sign`, `verify`, `encrypt`, `decrypt`), read & extract (`inspect`, `extract-text`), and automation & meta (`batch`, `doctor`, `schema`, `completion`, `govern`) — that together cover the full document lifecycle from JSON to a signed, verified, archive-grade PDF, plus page-tree editing, markup annotations, and an AI-governance gate, with an agent-native automation contract for autonomous AI and CI pipelines.
 
@@ -873,12 +873,12 @@ node samples/run-all.js
 
 ### What's new in v1.3.0
 
-v1.3.0 is built on **pdfnative 1.7.0** and surfaces its engine additions as five new commands (`extract-text`, `fill`, `encrypt`, `decrypt`, `doctor`), native vector charts in `render`, and password / re-encryption / constant-memory streaming on the page-tree commands. Fixes a silent `render --encrypt` no-op. **100 % backward-compatible** with v1.2.0.
+v1.3.0 is built on the **pdfnative 1.6 engine** (pin `^1.6.0`) and surfaces its engine additions as five new commands (`extract-text`, `fill`, `encrypt`, `decrypt`, `doctor`), native vector charts in `render`, and password / re-encryption / constant-memory streaming on the page-tree commands. Fixes a silent `render --encrypt` no-op. **100 % backward-compatible** with v1.2.0.
 
 | Area | v1.2.0 | v1.3.0 |
 |---|---|---|
 | Commands | 12 commands <!-- verify-docs:allow stale-token (v1.2.0-era count) --> | adds **`fill`** (fill / flatten / **export** AcroForms via an incremental save), **`encrypt`**, **`decrypt`**, **`extract-text`** (reading-order Unicode text: `text` \| `json` \| `ndjson`), and **`doctor`** (offline environment / capability preflight) |
-| Charts | — | the pdfnative 1.7.0 `chart` document block (bar, barH, line, pie, donut) renders as pure vector path operators through `render` |
+| Charts | — | the engine's `chart` document block (bar, barH, line, pie, donut — the pdfnative 1.6 set) renders as pure vector path operators through `render` |
 | Encryption vocabulary | `--encrypt-*` flags on `render` only | **unified vocabulary** — `--encrypt [aes-128\|aes-256]`, `--owner-password`, `--user-password`, `--permissions print,copy,modify,extract` — shared by `render`, `merge`, `split` and `extract` (legacy `--encrypt-*` flags kept as aliases) |
 | Page-tree commands | plaintext sources only | **`--password`** reads encrypted sources; **`--encrypt`** re-encrypts the output; **`--stream`** (+ `--chunk-size`) streams the output with constant memory |
 | Inspection | metadata, PDF/UA, annotations | adds `inspect --form-fields`, `--encryption` and `--password` |
diff --git a/docs/guides/colour-emoji-cli.html b/docs/guides/colour-emoji-cli.html
index cdc943c..01d1adc 100644
--- a/docs/guides/colour-emoji-cli.html
+++ b/docs/guides/colour-emoji-cli.html
@@ -1,85 +1,285 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>Colour-emoji font CLI — pdfnative</title>
-  <meta name="description" content="Generate a colour-emoji data module with exactly the glyphs you need using pdfnative's bundled pdfnative-build-emoji-font CLI — from a few codepoints to the full ~3,600-glyph Noto Color Emoji set. New in v1.4.0.">
-  <link rel="canonical" href="https://pdfnative.dev/guides/colour-emoji-cli.html">
-  <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/colour-emoji-cli.html">
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Colour-emoji font CLI — pdfnative</title>
+  <meta name="description" content="Generate a colour-emoji data module with exactly the glyphs you need using pdfnative's bundled pdfnative-build-emoji-font CLI — from a few codepoints to the full ~3,600-glyph Noto Color Emoji set. New in v1.4.0.">
+  <link rel="canonical" href="https://pdfnative.dev/guides/colour-emoji-cli.html">
+  <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/colour-emoji-cli.html">
   <link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/colour-emoji-cli.html">
-  <link rel="alternate" type="text/markdown" href="colour-emoji-cli.md">
-  <meta property="og:type" content="article">
-  <meta property="og:site_name" content="pdfnative">
+  <link rel="alternate" type="text/markdown" href="colour-emoji-cli.md">
+  <link rel="alternate" type="text/plain" href="../llms.txt" title="llms.txt — machine-readable documentation index">
+  <meta property="og:type" content="article">
+  <meta property="og:site_name" content="pdfnative">
   <meta property="og:locale" content="en_US">
-  <meta property="og:url" content="https://pdfnative.dev/guides/colour-emoji-cli.html">
-  <meta property="og:title" content="Colour-emoji font CLI — pdfnative">
-  <meta property="og:description" content="pdfnative-build-emoji-font generates a colour-emoji data module with exactly the glyphs you need — up to the full Noto Color Emoji set. New in v1.4.0.">
-  <meta property="og:image" content="https://pdfnative.dev/assets/og-image.png">
-  <meta property="og:image:width" content="1200">
-  <meta property="og:image:height" content="630">
-  <meta name="twitter:card" content="summary_large_image">
-  <meta name="twitter:title" content="Colour-emoji font CLI — pdfnative">
-  <meta name="twitter:description" content="Generate a colour-emoji data module with exactly the glyphs you need — from a few codepoints to the full Noto Color Emoji set.">
-  <meta name="twitter:image" content="https://pdfnative.dev/assets/og-image.png">
-  <link rel="icon" type="image/svg+xml" href="../favicon.svg">
-  <link rel="stylesheet" href="../style.css">
-  <link rel="stylesheet" href="guide.css">
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
-</head>
-<body>
-
-<a class="skip-link" href="#main-content">Skip to main content</a>
-
-<nav class="nav" role="navigation" aria-label="Main navigation">
-  <div class="nav-inner">
-    <a class="nav-brand" href="../">
-      <img src="../assets/logo.svg" alt="" width="28" height="28">
-      pdfnative
-    </a>
-    <button class="nav-hamburger" aria-label="Toggle menu" aria-expanded="false">☰</button>
-    <ul class="nav-links" role="list">
-      <li><a href="../#features">Features</a></li>
-      <li><a href="../#examples">Examples</a></li>
-      <li><a href="../#demo">Demo</a></li>
-      <li><a href="../#mcp">MCP</a></li>
-      <li><a href="../#cli">CLI</a></li>
-      <li><a href="../#react">React</a></li>
-      <li><a href="../learn/">Learn</a></li>
-      <li><a href="./">Guides</a></li>
-      <li><a href="../playgrounds/">Playgrounds</a></li>
-      <li><a href="../responsibility.html">Responsibility</a></li>
-      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
-      <li><button class="theme-toggle" aria-label="Toggle dark mode">🌙</button></li>
-    </ul>
-  </div>
-</nav>
-
-<main class="guide-shell" id="main-content" tabindex="-1">
-  <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; Colour-emoji font CLI</p>
-  <article id="guide-content" class="guide-content" data-md="colour-emoji-cli.md">
-    <p class="guide-loading">Loading…</p>
-    <noscript><p>This guide is written in Markdown: <a href="colour-emoji-cli.md">read colour-emoji-cli.md</a>.</p></noscript>
-  </article>
-</main>
-
-<footer class="footer">
-  <div class="footer-inner">
-    <span>MIT License · © 2026 Nizoka</span>
-    <ul class="footer-links" role="list">
-      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
-      <li><a href="https://www.npmjs.com/package/pdfnative" target="_blank" rel="noopener">npm</a></li>
-      <li><a href="https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md" target="_blank" rel="noopener">Changelog</a></li>
-      <li><a href="./">All guides</a></li>
-    </ul>
-  </div>
-</footer>
-
-<script src="https://cdn.jsdelivr.net/npm/marked@12.0.2/marked.min.js" integrity="sha384-/TQbtLCAerC3jgaim+N78RZSDYV7ryeoBCVqTuzRrFec2akfBkHS7ACQ3PQhvMVi" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/dompurify@3.1.5/dist/purify.min.js" integrity="sha384-nszIONF2FGC59kn+pPFaRa6WUNGwsZgXZiJxJwQbym+TzcH7smolUviLgpPbNx7V" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/prism.min.js" integrity="sha384-BGaNxfftg+9+TtC098wxawPFVEUpKYvaiCgbB0iqAMjK/4jDdmUY+oGxrPNvnXEf" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-typescript.min.js" integrity="sha384-PeOqKNW/piETaCg8rqKFy+Pm6KEk7e36/5YZE5XO/OaFdO+/Aw3O8qZ9qDPKVUgx" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-bash.min.js" integrity="sha384-9WmlN8ABpoFSSHvBGGjhvB3E/D8UkNB9HpLJjBQFC2VSQsM1odiQDv4NbEo+7l15" crossorigin="anonymous" defer></script>
-<script src="guide.js" defer></script>
-</body>
-</html>
+  <meta property="og:url" content="https://pdfnative.dev/guides/colour-emoji-cli.html">
+  <meta property="og:title" content="Colour-emoji font CLI — pdfnative">
+  <meta property="og:description" content="pdfnative-build-emoji-font generates a colour-emoji data module with exactly the glyphs you need — up to the full Noto Color Emoji set. New in v1.4.0.">
+  <meta property="og:image" content="https://pdfnative.dev/assets/og-image.png">
+  <meta property="og:image:width" content="1200">
+  <meta property="og:image:height" content="630">
+  <meta name="twitter:card" content="summary_large_image">
+  <meta name="twitter:title" content="Colour-emoji font CLI — pdfnative">
+  <meta name="twitter:description" content="Generate a colour-emoji data module with exactly the glyphs you need — from a few codepoints to the full Noto Color Emoji set.">
+  <meta name="twitter:image" content="https://pdfnative.dev/assets/og-image.png">
+  <link rel="icon" type="image/svg+xml" href="../favicon.svg">
+  <link rel="stylesheet" href="../style.css">
+  <link rel="stylesheet" href="guide.css">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
+  <!-- guide:ld:start -->
+  <script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://pdfnative.dev/"},{"@type":"ListItem","position":2,"name":"Guides","item":"https://pdfnative.dev/guides/"},{"@type":"ListItem","position":3,"name":"Colour-emoji font CLI (pdfnative-build-emoji-font)","item":"https://pdfnative.dev/guides/colour-emoji-cli.html"}]},{"@type":"TechArticle","headline":"Colour-emoji font CLI (pdfnative-build-emoji-font)","description":"Generate a colour-emoji data module with exactly the glyphs you need using pdfnative's bundled pdfnative-build-emoji-font CLI — from a few codepoints to the full ~3,600-glyph Noto Color Emoji set. New in v1.4.0.","inLanguage":"en","author":{"@type":"Organization","name":"Nizoka","url":"https://github.com/Nizoka"},"publisher":{"@type":"Organization","name":"pdfnative","url":"https://pdfnative.dev","logo":{"@type":"ImageObject","url":"https://pdfnative.dev/assets/logo.svg"}},"mainEntityOfPage":{"@type":"WebPage","@id":"https://pdfnative.dev/guides/colour-emoji-cli.html"},"isPartOf":{"@type":"WebSite","name":"pdfnative","url":"https://pdfnative.dev"}}]}</script>
+  <!-- guide:ld:end -->
+</head>
+<body>
+
+<a class="skip-link" href="#main-content">Skip to main content</a>
+
+<nav class="nav" role="navigation" aria-label="Main navigation">
+  <div class="nav-inner">
+    <a class="nav-brand" href="../">
+      <img src="../assets/logo.svg" alt="" width="28" height="28">
+      pdfnative
+    </a>
+    <button class="nav-hamburger" aria-label="Toggle menu" aria-expanded="false">☰</button>
+    <ul class="nav-links" role="list">
+      <li><a href="../#features">Features</a></li>
+      <li><a href="../#examples">Examples</a></li>
+      <li><a href="../#demo">Demo</a></li>
+      <li><a href="../#mcp">MCP</a></li>
+      <li><a href="../#cli">CLI</a></li>
+      <li><a href="../#react">React</a></li>
+      <li><a href="../learn/">Learn</a></li>
+      <li><a href="./">Guides</a></li>
+      <li><a href="../playgrounds/">Playgrounds</a></li>
+      <li><a href="../responsibility.html">Responsibility</a></li>
+      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
+      <li><button class="theme-toggle" aria-label="Toggle dark mode">🌙</button></li>
+    </ul>
+  </div>
+</nav>
+
+<main class="guide-shell" id="main-content" tabindex="-1">
+  <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; Colour-emoji font CLI</p>
+  <article id="guide-content" class="guide-content" data-md="colour-emoji-cli.md" data-prerendered="true">
+<!-- guide:render:start -->
+<h1 id="colour-emoji-font-cli-pdfnative-build-emoji-font">Colour-emoji font CLI (<code>pdfnative-build-emoji-font</code>)</h1>
+<blockquote>
+<p><strong>New in v1.4.0, expanded in v1.6.0 and v1.7.0.</strong> pdfnative ships a curated
+1167-glyph colour-emoji module by default (plus 73 flag/ZWJ sequences since
+v1.7.0). When you need <strong>more emoji — up to the full ~3 600-glyph set, or
+skin-tone sequence variants</strong> — the
+<code>pdfnative-build-emoji-font</code> CLI generates a data module containing exactly the
+glyphs and sequences you choose. It&#39;s bundled with the <code>pdfnative</code> package, so
+any user can run it with <code>npx</code> — no extra install, no editing library source.</p>
+</blockquote>
+<h2 id="why-a-cli-instead-of-bundling-everything">Why a CLI instead of bundling everything?<a class="heading-anchor" href="#why-a-cli-instead-of-bundling-everything" aria-label="Link to this section">#</a></h2>
+<p>The complete Noto Color Emoji font is ~24 MB and resolves to a ~32 MB data
+module. Bundling that into the npm package would penalise <strong>every</strong> install,
+including the vast majority of users who only ever need a handful of emoji. The
+lean curated subset stays the default; the CLI lets you opt into precisely the
+coverage you need, when you need it. This is the same deterministic build core
+that produces the bundled module — you get identical, reproducible output.</p>
+<h2 id="tldr">TL;DR<a class="heading-anchor" href="#tldr" aria-label="Link to this section">#</a></h2>
+<pre><code class="language-bash"># Full coverage — download + checksum-verify the font, then build every glyph:
+npx pdfnative-build-emoji-font --download --all --out ./emoji-full.js
+
+# Exactly the emoji you need (hex scalars and/or inclusive ranges):
+npx pdfnative-build-emoji-font --download \
+  --ranges 1F600-1F64F,2600-27BF --codepoints 2764,1F680 --out ./emoji.js
+
+# Offline: point at a font you already have on disk:
+npx pdfnative-build-emoji-font --ttf ./NotoColorEmoji-Regular.ttf --all
+
+# Flag/ZWJ sequences (v1.7.0) — the curated sets plus any skin-tone form you need:
+npx pdfnative-build-emoji-font --download --sequences all \
+  --sequence-list 1F468-1F3FB-200D-1F4BB,1F469-1F3FD-200D-2695-FE0F --out ./emoji.js
+</code></pre>
+<p>Then register the module you generated, load it, and pass it via <code>fontEntries</code>:</p>
+<pre><code class="language-ts">import { registerFont, loadFontData, buildDocumentPDFBytes } from &#39;pdfnative&#39;;
+
+registerFont(&#39;emoji&#39;, () =&gt; import(&#39;./emoji-full.js&#39;));
+const emoji = await loadFontData(&#39;emoji&#39;);
+if (!emoji) throw new Error(&#39;emoji font failed to load&#39;);
+
+const bytes = buildDocumentPDFBytes({
+  title: &#39;Emoji&#39;,
+  blocks: [{ type: &#39;paragraph&#39;, text: &#39;Ship it 🚀🎉🥳🦄🌈&#39; }],
+  fontEntries: [{ fontData: emoji, fontRef: &#39;/F3&#39;, lang: &#39;emoji&#39; }], // /F1 and /F2 are reserved
+});
+</code></pre>
+<h2 id="getting-the-source-font">Getting the source font<a class="heading-anchor" href="#getting-the-source-font" aria-label="Link to this section">#</a></h2>
+<p>The CLI needs a COLRv1/CPAL colour font — the canonical one is
+<strong>NotoColorEmoji-Regular.ttf</strong> (OFL-1.1). Two ways to provide it:</p>
+<ul>
+<li><strong><code>--download</code></strong> fetches it from the official Google Fonts repository and
+verifies its SHA-256 against the build pdfnative was tested with. A mismatch is
+a transparent <strong>warning</strong> (Google periodically ships newer Unicode revisions),
+not a hard failure — the download is still used.</li>
+<li><strong><code>--ttf &lt;path&gt;</code></strong> uses a font already on disk (fully offline, no network).</li>
+</ul>
+<blockquote>
+<p>Only the pinned official Google Fonts URL is ever contacted; the CLI never
+fetches arbitrary user-supplied URLs.</p>
+</blockquote>
+<h2 id="selecting-glyphs">Selecting glyphs<a class="heading-anchor" href="#selecting-glyphs" aria-label="Link to this section">#</a></h2>
+<p>Combine these freely; selections are merged, de-duplicated and sorted. If you
+pass none, the curated set is used.</p>
+<table>
+<thead>
+<tr>
+<th>Flag</th>
+<th>Meaning</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>--all</code></td>
+<td>Every colour glyph in the font (large module).</td>
+</tr>
+<tr>
+<td><code>--preset curated</code></td>
+<td>pdfnative&#39;s lean 1167-glyph default set.</td>
+</tr>
+<tr>
+<td><code>--preset all</code></td>
+<td>Same as <code>--all</code>.</td>
+</tr>
+<tr>
+<td><code>--codepoints &lt;list&gt;</code></td>
+<td>Comma-separated hex scalars: <code>1F600,1F680,2764</code>. <code>U+</code>, <code>0x</code>, <code>#</code> prefixes are tolerated.</td>
+</tr>
+<tr>
+<td><code>--ranges &lt;list&gt;</code></td>
+<td>Comma-separated <strong>inclusive</strong> hex ranges: <code>1F600-1F64F,2600-27BF</code>.</td>
+</tr>
+</tbody></table>
+<h2 id="selecting-sequences-v170">Selecting sequences (v1.7.0)<a class="heading-anchor" href="#selecting-sequences-v170" aria-label="Link to this section">#</a></h2>
+<p>Multi-codepoint emoji — flags (regional-indicator pairs) and ZWJ sequences —
+are selected separately from single glyphs. Each requested sequence is
+resolved through the font&#39;s GSUB ligature lookups to a <strong>single colour glyph</strong>
+and emitted in the module&#39;s <code>sequences</code> table; both the VS-16 and the
+VS-16-free spelling register to the same glyph. Default: <strong>none</strong> (the
+pre-1.7 output shape, plus an inert <code>sequences = null</code> export).</p>
+<table>
+<thead>
+<tr>
+<th>Flag</th>
+<th>Meaning</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>--sequences &lt;preset&gt;</code></td>
+<td><code>flags</code> (the curated 51-flag set), <code>zwj</code> (the curated 22-sequence ZWJ set), <code>all</code> (both), or <code>none</code>.</td>
+</tr>
+<tr>
+<td><code>--sequence-list &lt;list&gt;</code></td>
+<td>Comma-separated entries: a 2-letter country code (<code>FR</code>, <code>DE</code>) and/or hyphen-joined hex scalars (<code>1F468-200D-1F680</code>, <code>1F469-1F3FD-200D-2695-FE0F</code>). Skin-tone forms welcome.</td>
+</tr>
+</tbody></table>
+<p>Selections merge and de-duplicate, so <code>--sequences flags --sequence-list 1F469-1F3FB-200D-2695-FE0F</code> is valid. The bundled npm module already carries
+the curated 51 + 22 set — reach for the CLI when you need skin-tone variants
+or sequences beyond it. Note that flags render <strong>flat</strong> (Noto&#39;s wave-shading
+overlay uses a COLRv1 compositing mask with no PDF equivalent — see the
+<a href="colour-emoji.html">colour-emoji guide</a>).</p>
+<h2 id="output-options">Output options<a class="heading-anchor" href="#output-options" aria-label="Link to this section">#</a></h2>
+<table>
+<thead>
+<tr>
+<th>Flag</th>
+<th>Default</th>
+<th>Meaning</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>--out &lt;path&gt;</code></td>
+<td><code>./noto-color-emoji-data.js</code></td>
+<td>Output <code>.js</code> path. A sibling <code>.d.ts</code> is written next to it.</td>
+</tr>
+<tr>
+<td><code>--font-name &lt;name&gt;</code></td>
+<td><code>NotoColorEmoji-Regular</code></td>
+<td>Embedded PostScript font name.</td>
+</tr>
+<tr>
+<td><code>--types &lt;path&gt;</code></td>
+<td><code>pdfnative</code></td>
+<td>The type import used in the generated <code>.d.ts</code> (e.g. <code>&#39;pdfnative&#39;</code> or a relative path).</td>
+</tr>
+</tbody></table>
+<p>The generated module exports the same shape as the bundled one
+(<code>metrics</code>, <code>cmap</code>, <code>widths</code>, <code>pdfWidthArray</code>, <code>colorGlyphs</code>, <code>sequences</code>,
+<code>ttfBase64</code>, …), so it drops straight into
+<code>registerFont(&#39;emoji&#39;, () =&gt; import(&#39;…&#39;))</code>.</p>
+<h2 id="verifying-the-result">Verifying the result<a class="heading-anchor" href="#verifying-the-result" aria-label="Link to this section">#</a></h2>
+<p>Pair the CLI with <a href="font-validation.html"><code>validateFontData()</code></a> to sanity-check a
+freshly generated module before shipping it:</p>
+<pre><code class="language-ts">import { validateFontData } from &#39;pdfnative&#39;;
+import * as emoji from &#39;./emoji-full.js&#39;;
+
+const report = validateFontData(emoji);
+if (!report.valid) console.error(report.errors);
+</code></pre>
+<h2 id="full-option-reference">Full option reference<a class="heading-anchor" href="#full-option-reference" aria-label="Link to this section">#</a></h2>
+<pre><code class="language-text">pdfnative-build-emoji-font — colour-emoji font data module generator
+
+Source font (one of):
+  --ttf &lt;path&gt;            Path to a COLRv1/CPAL colour font.
+  --download              Fetch the official Noto Color Emoji (OFL-1.1) and verify checksum.
+
+Glyph selection (combine freely; default: --preset curated):
+  --all                   Every colour glyph in the font.
+  --preset &lt;curated|all&gt;  Named selection.
+  --codepoints &lt;list&gt;     Comma-separated hex scalars, e.g. 1F600,1F680,2764.
+  --ranges &lt;list&gt;         Comma-separated inclusive hex ranges, e.g. 1F600-1F64F.
+
+Sequence selection (v1.7.0; default: none):
+  --sequences &lt;preset&gt;    flags | zwj | all | none — bundle the curated flag
+                          and/or ZWJ sequence sets (GSUB-resolved ligatures).
+  --sequence-list &lt;list&gt;  Comma-separated country codes and/or hyphen-joined
+                          hex sequences, e.g. FR,DE,1F468-200D-1F680,
+                          1F469-1F3FD-200D-2695-FE0F (skin tones welcome).
+
+Output:
+  --out &lt;path&gt;            Output .js path (a sibling .d.ts is written).
+  --font-name &lt;name&gt;      Embedded PostScript font name.
+  --types &lt;path&gt;          Type import used in the generated .d.ts.
+
+Other:
+  -h, --help              Show this help.
+</code></pre>
+<h2 id="licensing">Licensing<a class="heading-anchor" href="#licensing" aria-label="Link to this section">#</a></h2>
+<p>Noto Color Emoji is licensed under the <strong>SIL Open Font License 1.1 (OFL-1.1)</strong>.
+Generated modules embed a subset of that font; keep the OFL notice with any
+redistributed module, exactly as you would for any other Noto data module that
+pdfnative ships.</p>
+<h2 id="see-also">See also<a class="heading-anchor" href="#see-also" aria-label="Link to this section">#</a></h2>
+<ul>
+<li><a href="colour-emoji.html">Colour emoji (COLRv1)</a> — how colour glyphs render to PDF</li>
+<li><a href="font-validation.html">Font-data validation</a> — <code>validateFontData()</code></li>
+<li><a href="../playgrounds/toolkit.html">PDF Toolkit playground</a></li>
+<li><a href="https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md" target="_blank" rel="noopener">CHANGELOG</a></li>
+</ul>
+<!-- guide:render:end -->
+  </article>
+</main>
+
+<footer class="footer">
+  <div class="footer-inner">
+    <span>MIT License · © 2026 Nizoka</span>
+    <ul class="footer-links" role="list">
+      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
+      <li><a href="https://www.npmjs.com/package/pdfnative" target="_blank" rel="noopener">npm</a></li>
+      <li><a href="https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md" target="_blank" rel="noopener">Changelog</a></li>
+      <li><a href="./">All guides</a></li>
+    </ul>
+  </div>
+</footer>
+
+<script src="https://cdn.jsdelivr.net/npm/marked@12.0.2/marked.min.js" integrity="sha384-/TQbtLCAerC3jgaim+N78RZSDYV7ryeoBCVqTuzRrFec2akfBkHS7ACQ3PQhvMVi" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/dompurify@3.1.5/dist/purify.min.js" integrity="sha384-nszIONF2FGC59kn+pPFaRa6WUNGwsZgXZiJxJwQbym+TzcH7smolUviLgpPbNx7V" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/prism.min.js" integrity="sha384-BGaNxfftg+9+TtC098wxawPFVEUpKYvaiCgbB0iqAMjK/4jDdmUY+oGxrPNvnXEf" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-typescript.min.js" integrity="sha384-PeOqKNW/piETaCg8rqKFy+Pm6KEk7e36/5YZE5XO/OaFdO+/Aw3O8qZ9qDPKVUgx" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-bash.min.js" integrity="sha384-9WmlN8ABpoFSSHvBGGjhvB3E/D8UkNB9HpLJjBQFC2VSQsM1odiQDv4NbEo+7l15" crossorigin="anonymous" defer></script>
+<script src="guide.js" defer></script>
+</body>
+</html>
diff --git a/docs/guides/colour-emoji.html b/docs/guides/colour-emoji.html
index 69be57e..7c1f440 100644
--- a/docs/guides/colour-emoji.html
+++ b/docs/guides/colour-emoji.html
@@ -1,85 +1,314 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>Colour emoji (COLRv1) — pdfnative</title>
-  <meta name="description" content="Render colour emoji natively in pdfnative — COLR/CPAL glyph layers become PDF Form XObjects with solid fills and axial/radial gradients. Opt-in Noto Color Emoji subset, monochrome fallback. New in v1.3.0.">
-  <link rel="canonical" href="https://pdfnative.dev/guides/colour-emoji.html">
-  <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/colour-emoji.html">
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Colour emoji (COLRv1) — pdfnative</title>
+  <meta name="description" content="Render colour emoji natively in pdfnative — COLR/CPAL glyph layers become PDF Form XObjects with solid fills, axial/radial/sweep gradients and blend modes. 73 flag and ZWJ sequences as colour ligatures since v1.7.0. Opt-in Noto Color Emoji subset, monochrome fallback.">
+  <link rel="canonical" href="https://pdfnative.dev/guides/colour-emoji.html">
+  <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/colour-emoji.html">
   <link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/colour-emoji.html">
-  <link rel="alternate" type="text/markdown" href="colour-emoji.md">
-  <meta property="og:type" content="article">
-  <meta property="og:site_name" content="pdfnative">
+  <link rel="alternate" type="text/markdown" href="colour-emoji.md">
+  <link rel="alternate" type="text/plain" href="../llms.txt" title="llms.txt — machine-readable documentation index">
+  <meta property="og:type" content="article">
+  <meta property="og:site_name" content="pdfnative">
   <meta property="og:locale" content="en_US">
-  <meta property="og:url" content="https://pdfnative.dev/guides/colour-emoji.html">
-  <meta property="og:title" content="Colour emoji (COLRv1) — pdfnative">
-  <meta property="og:description" content="Render colour emoji natively in pdfnative — COLR/CPAL glyph layers become PDF Form XObjects with solid fills and axial/radial gradients. Opt-in Noto Color Emoji subset, monochrome fallback. New in v1.3.0.">
-  <meta property="og:image" content="https://pdfnative.dev/assets/og-image.png">
-  <meta property="og:image:width" content="1200">
-  <meta property="og:image:height" content="630">
-  <meta name="twitter:card" content="summary_large_image">
-  <meta name="twitter:title" content="Colour emoji (COLRv1) — pdfnative">
-  <meta name="twitter:description" content="COLR/CPAL glyph layers become PDF Form XObjects with gradients. Opt-in Noto Color Emoji subset, monochrome fallback. New in v1.3.0.">
-  <meta name="twitter:image" content="https://pdfnative.dev/assets/og-image.png">
-  <link rel="icon" type="image/svg+xml" href="../favicon.svg">
-  <link rel="stylesheet" href="../style.css">
-  <link rel="stylesheet" href="guide.css">
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
-</head>
-<body>
-
-<a class="skip-link" href="#main-content">Skip to main content</a>
-
-<nav class="nav" role="navigation" aria-label="Main navigation">
-  <div class="nav-inner">
-    <a class="nav-brand" href="../">
-      <img src="../assets/logo.svg" alt="" width="28" height="28">
-      pdfnative
-    </a>
-    <button class="nav-hamburger" aria-label="Toggle menu" aria-expanded="false">☰</button>
-    <ul class="nav-links" role="list">
-      <li><a href="../#features">Features</a></li>
-      <li><a href="../#examples">Examples</a></li>
-      <li><a href="../#demo">Demo</a></li>
-      <li><a href="../#mcp">MCP</a></li>
-      <li><a href="../#cli">CLI</a></li>
-      <li><a href="../#react">React</a></li>
-      <li><a href="../learn/">Learn</a></li>
-      <li><a href="./">Guides</a></li>
-      <li><a href="../playgrounds/">Playgrounds</a></li>
-      <li><a href="../responsibility.html">Responsibility</a></li>
-      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
-      <li><button class="theme-toggle" aria-label="Toggle dark mode">🌙</button></li>
-    </ul>
-  </div>
-</nav>
-
-<main class="guide-shell" id="main-content" tabindex="-1">
-  <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; Colour emoji</p>
-  <article id="guide-content" class="guide-content" data-md="colour-emoji.md">
-    <p class="guide-loading">Loading…</p>
-    <noscript><p>This guide is written in Markdown: <a href="colour-emoji.md">read colour-emoji.md</a>.</p></noscript>
-  </article>
-</main>
-
-<footer class="footer">
-  <div class="footer-inner">
-    <span>MIT License · © 2026 Nizoka</span>
-    <ul class="footer-links" role="list">
-      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
-      <li><a href="https://www.npmjs.com/package/pdfnative" target="_blank" rel="noopener">npm</a></li>
-      <li><a href="https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md" target="_blank" rel="noopener">Changelog</a></li>
-      <li><a href="./">All guides</a></li>
-    </ul>
-  </div>
-</footer>
-
-<script src="https://cdn.jsdelivr.net/npm/marked@12.0.2/marked.min.js" integrity="sha384-/TQbtLCAerC3jgaim+N78RZSDYV7ryeoBCVqTuzRrFec2akfBkHS7ACQ3PQhvMVi" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/dompurify@3.1.5/dist/purify.min.js" integrity="sha384-nszIONF2FGC59kn+pPFaRa6WUNGwsZgXZiJxJwQbym+TzcH7smolUviLgpPbNx7V" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/prism.min.js" integrity="sha384-BGaNxfftg+9+TtC098wxawPFVEUpKYvaiCgbB0iqAMjK/4jDdmUY+oGxrPNvnXEf" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-typescript.min.js" integrity="sha384-PeOqKNW/piETaCg8rqKFy+Pm6KEk7e36/5YZE5XO/OaFdO+/Aw3O8qZ9qDPKVUgx" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-bash.min.js" integrity="sha384-9WmlN8ABpoFSSHvBGGjhvB3E/D8UkNB9HpLJjBQFC2VSQsM1odiQDv4NbEo+7l15" crossorigin="anonymous" defer></script>
-<script src="guide.js" defer></script>
-</body>
-</html>
+  <meta property="og:url" content="https://pdfnative.dev/guides/colour-emoji.html">
+  <meta property="og:title" content="Colour emoji (COLRv1) — pdfnative">
+  <meta property="og:description" content="Render colour emoji natively in pdfnative — COLR/CPAL glyph layers become PDF Form XObjects with solid fills, axial/radial/sweep gradients and blend modes. 73 flag and ZWJ sequences as colour ligatures since v1.7.0. Opt-in Noto Color Emoji subset, monochrome fallback.">
+  <meta property="og:image" content="https://pdfnative.dev/assets/og-image.png">
+  <meta property="og:image:width" content="1200">
+  <meta property="og:image:height" content="630">
+  <meta name="twitter:card" content="summary_large_image">
+  <meta name="twitter:title" content="Colour emoji (COLRv1) — pdfnative">
+  <meta name="twitter:description" content="COLR/CPAL glyph layers become PDF Form XObjects with gradients; 73 flag and ZWJ sequences since v1.7.0. Opt-in Noto Color Emoji subset, monochrome fallback.">
+  <meta name="twitter:image" content="https://pdfnative.dev/assets/og-image.png">
+  <link rel="icon" type="image/svg+xml" href="../favicon.svg">
+  <link rel="stylesheet" href="../style.css">
+  <link rel="stylesheet" href="guide.css">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
+  <!-- guide:ld:start -->
+  <script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://pdfnative.dev/"},{"@type":"ListItem","position":2,"name":"Guides","item":"https://pdfnative.dev/guides/"},{"@type":"ListItem","position":3,"name":"Colour emoji (COLRv1)","item":"https://pdfnative.dev/guides/colour-emoji.html"}]},{"@type":"TechArticle","headline":"Colour emoji (COLRv1)","description":"Render colour emoji natively in pdfnative — COLR/CPAL glyph layers become PDF Form XObjects with solid fills, axial/radial/sweep gradients and blend modes. 73 flag and ZWJ sequences as colour ligatures since v1.7.0. Opt-in Noto Color Emoji subset, monochrome fallback.","inLanguage":"en","author":{"@type":"Organization","name":"Nizoka","url":"https://github.com/Nizoka"},"publisher":{"@type":"Organization","name":"pdfnative","url":"https://pdfnative.dev","logo":{"@type":"ImageObject","url":"https://pdfnative.dev/assets/logo.svg"}},"mainEntityOfPage":{"@type":"WebPage","@id":"https://pdfnative.dev/guides/colour-emoji.html"},"isPartOf":{"@type":"WebSite","name":"pdfnative","url":"https://pdfnative.dev"}}]}</script>
+  <!-- guide:ld:end -->
+</head>
+<body>
+
+<a class="skip-link" href="#main-content">Skip to main content</a>
+
+<nav class="nav" role="navigation" aria-label="Main navigation">
+  <div class="nav-inner">
+    <a class="nav-brand" href="../">
+      <img src="../assets/logo.svg" alt="" width="28" height="28">
+      pdfnative
+    </a>
+    <button class="nav-hamburger" aria-label="Toggle menu" aria-expanded="false">☰</button>
+    <ul class="nav-links" role="list">
+      <li><a href="../#features">Features</a></li>
+      <li><a href="../#examples">Examples</a></li>
+      <li><a href="../#demo">Demo</a></li>
+      <li><a href="../#mcp">MCP</a></li>
+      <li><a href="../#cli">CLI</a></li>
+      <li><a href="../#react">React</a></li>
+      <li><a href="../learn/">Learn</a></li>
+      <li><a href="./">Guides</a></li>
+      <li><a href="../playgrounds/">Playgrounds</a></li>
+      <li><a href="../responsibility.html">Responsibility</a></li>
+      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
+      <li><button class="theme-toggle" aria-label="Toggle dark mode">🌙</button></li>
+    </ul>
+  </div>
+</nav>
+
+<main class="guide-shell" id="main-content" tabindex="-1">
+  <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; Colour emoji</p>
+  <article id="guide-content" class="guide-content" data-md="colour-emoji.md" data-prerendered="true">
+<!-- guide:render:start -->
+<h1 id="colour-emoji-colrv1">Colour emoji (COLRv1)</h1>
+<blockquote>
+<p><strong>New in v1.3.0.</strong> pdfnative renders colour emoji natively — no rasterisation, no external dependency. Glyph colour layers become PDF Form XObjects with solid fills and axial/radial gradients. The monochrome emoji font is unchanged and remains the default.</p>
+</blockquote>
+<h2 id="tldr">TL;DR<a class="heading-anchor" href="#tldr" aria-label="Link to this section">#</a></h2>
+<pre><code class="language-ts">import { registerFont, loadFontData, buildDocumentPDFBytes } from &#39;pdfnative&#39;;
+
+// Opt in to the curated colour-emoji subset (1167 glyphs + 73 sequences, ~4.5 MB).
+registerFont(&#39;emoji&#39;, () =&gt; import(&#39;pdfnative/fonts/noto-color-emoji-data.js&#39;));
+
+const emoji = await loadFontData(&#39;emoji&#39;);
+if (!emoji) throw new Error(&#39;emoji font failed to load&#39;);
+
+const bytes = buildDocumentPDFBytes({
+  title: &#39;Colour emoji&#39;,
+  blocks: [
+    { type: &#39;paragraph&#39;, text: &#39;Status: 🟢 online · 🔴 offline · 🎉 launch day!&#39; },
+  ],
+  fontEntries: [{ fontData: emoji, fontRef: &#39;/F3&#39;, lang: &#39;emoji&#39; }], // /F1 and /F2 are reserved
+});
+</code></pre>
+<p>The <code>registerFont(&#39;emoji&#39;, …)</code> call swaps the monochrome Noto Emoji font for
+the COLR/CPAL colour build — but registration alone embeds nothing: you must
+<code>await loadFontData(&#39;emoji&#39;)</code> and pass the result in <code>fontEntries</code> (as above)
+or the emoji render as tofu. With the entry in place, everything else —
+detection, multi-font run splitting, line breaking — is automatic.</p>
+<h2 id="how-it-works">How it works<a class="heading-anchor" href="#how-it-works" aria-label="Link to this section">#</a></h2>
+<p>Noto Color Emoji is an OpenType <strong>COLR/CPAL</strong> font: each emoji codepoint maps
+to a base glyph plus a <em>colour glyph</em> describing ordered paint layers. pdfnative
+parses these tables with self-written, zero-dependency readers
+(<a href="https://github.com/Nizoka/pdfnative/blob/main/src/fonts/colr-parser.ts" target="_blank" rel="noopener"><code>src/fonts/colr-parser.ts</code></a>,
+<a href="https://github.com/Nizoka/pdfnative/blob/main/src/fonts/glyf-outline.ts" target="_blank" rel="noopener"><code>src/fonts/glyf-outline.ts</code></a>)
+and renders each colour glyph as a <strong>PDF Form XObject</strong>:</p>
+<table>
+<thead>
+<tr>
+<th>COLR feature</th>
+<th>PDF mapping</th>
+</tr>
+</thead>
+<tbody><tr>
+<td>Solid layer (COLR v0 / <code>PaintSolid</code>)</td>
+<td><code>rg</code> fill of the layer&#39;s <code>glyf</code> outline, clipped with <code>W n</code></td>
+</tr>
+<tr>
+<td>Linear gradient (<code>PaintLinearGradient</code>)</td>
+<td><code>/ShadingType 2</code> axial shading + <code>/ExtGState</code> constant alpha</td>
+</tr>
+<tr>
+<td>Radial gradient (<code>PaintRadialGradient</code>)</td>
+<td><code>/ShadingType 3</code> radial shading</td>
+</tr>
+<tr>
+<td>Sweep gradient (<code>PaintSweepGradient</code>)</td>
+<td>flat-colour triangular wedges fanned around the centre (<strong>v1.4.0</strong>)</td>
+</tr>
+<tr>
+<td>Compositing (<code>PaintComposite</code>)</td>
+<td>separable blend modes mapped to PDF <code>/BM</code> (Multiply, Screen, Overlay, Darken, Lighten, …) (<strong>v1.4.0</strong>)</td>
+</tr>
+<tr>
+<td>CPAL palette</td>
+<td>per-stop RGB(A) colours</td>
+</tr>
+</tbody></table>
+<p>Each unique emoji produces <strong>one indirect Form XObject</strong>, deduplicated and
+forward-referenced into every page&#39;s <code>/XObject</code> resource dictionary. The text
+run emits <code>q s 0 0 s x y cm /CEm0 Do Q</code> to place the glyph.</p>
+<blockquote>
+<p><strong>Advanced compositing (v1.4.0).</strong> COLRv1 <strong>sweep (conic) gradients</strong> render as
+native flat-shaded wedges, and <code>PaintComposite</code> <strong>separable blend modes</strong> map to
+PDF <code>/BM</code> ExtGState operators. Structural Porter-Duff modes (Clear / Src / Dest /
+Xor / …) and <code>PaintMask</code> fall back to the documented monochrome path — except
+that since <strong>v1.7.0</strong>, a composite whose <em>source</em> subtree alone is unsupported
+keeps its backdrop layers (this is what makes flags render flat instead of
+monochrome).</p>
+</blockquote>
+<h2 id="opt-in-not-default">Opt-in, not default<a class="heading-anchor" href="#opt-in-not-default" aria-label="Link to this section">#</a></h2>
+<p>Colour emoji is <strong>opt-in</strong> for two reasons:</p>
+<ol>
+<li><strong>Module size.</strong> The curated subset is ~4.5 MB (expanded to 1167 glyphs in
+v1.6.0, plus 73 flag/ZWJ sequences in v1.7.0); bundling it by default would
+bloat every consumer. Register it only when you need colour.</li>
+<li><strong>Byte stability.</strong> When no colour-emoji font is registered, documents are
+  byte-identical to the pre-colour-emoji path — the colour path is fully gated.</li>
+</ol>
+<p>To keep monochrome emoji instead, register the monochrome font:</p>
+<pre><code class="language-ts">registerFont(&#39;emoji&#39;, () =&gt; import(&#39;pdfnative/fonts/noto-emoji-data.js&#39;));
+</code></pre>
+<h2 id="coverage--limits">Coverage &amp; limits<a class="heading-anchor" href="#coverage--limits" aria-label="Link to this section">#</a></h2>
+<p>The bundled module is a <strong>curated subset</strong> of <strong>1167 common single-codepoint
+emoji</strong> (expanded from 221 in v1.6.0): the complete Emoticons and Supplemental
+Symbols &amp; Pictographs blocks, Miscellaneous Symbols &amp; Pictographs through
+U+1F53D (nature, food, objects, hearts, office, av/ui symbols) plus clocks and
+the emoji-presentation stragglers, and the <strong>complete assigned Transport &amp; Map
+block</strong> (U+1F680–1F6FF). Since v1.7.0 it also carries <strong>73 multi-codepoint
+sequences</strong> — 51 flags and 22 ZWJ sequences (see the next section). Symbols &amp;
+Pictographs Extended-A (U+1FA70–1FAFF) is
+not bundled — use the CLI below. It ships pre-built because every file under the package
+<code>files</code> allowlist is included in the npm tarball regardless of tree-shaking — the
+full Noto Color Emoji build (thousands of glyphs, ~32 MB) would weigh down
+<em>every</em> <code>npm install</code>, even for consumers who never touch emoji. The subset keeps
+the install within a 5120 KB budget (actual: ~4.5 MB) while the lazy
+<code>() =&gt; import(...)</code> keeps it out of bundles that don&#39;t reference it.</p>
+<blockquote>
+<p><strong>Out of scope for the bundled subset:</strong> skin-tone-modified forms
+(<code>👍🏽</code>, <code>👩🏻‍🚀</code>, …) and any flag or ZWJ sequence beyond the curated 73. The
+combinatorial skin-tone set is deliberately CLI territory — build a module
+with <code>--sequences</code> / <code>--sequence-list</code> below to cover exactly the forms you
+need. An uncovered sequence degrades to the per-codepoint behaviour
+described further down (base emoji render, joiners drop) — never worse.</p>
+</blockquote>
+<p>To cover the <strong>full</strong> Noto Color Emoji set — or any custom selection — pdfnative
+ships an official generator CLI, <code>pdfnative-build-emoji-font</code>, so you never have
+to edit library source:</p>
+<pre><code class="language-bash"># Every colour glyph (~3 600), fetched + checksum-verified from Google Fonts:
+npx pdfnative-build-emoji-font --download --all --out ./emoji-full.js
+
+# Or exactly the emoji you need (hex scalars and/or inclusive ranges):
+npx pdfnative-build-emoji-font --download \
+  --ranges 1F600-1F64F,2600-27BF --codepoints 2764,1F680 --out ./emoji.js
+</code></pre>
+<p>Then register the module you generated:</p>
+<pre><code class="language-ts">registerFont(&#39;emoji&#39;, () =&gt; import(&#39;./emoji-full.js&#39;));
+</code></pre>
+<p>See the <a href="colour-emoji-cli.html">colour-emoji CLI guide</a> for every flag, offline
+usage with <code>--ttf</code>, and the checksum/licensing details.</p>
+<h2 id="flag--zwj-sequences-v170">Flag &amp; ZWJ sequences (v1.7.0)<a class="heading-anchor" href="#flag--zwj-sequences-v170" aria-label="Link to this section">#</a></h2>
+<p>Multi-codepoint emoji now render as <strong>single colour glyphs</strong>. The bundled
+module resolves the font&#39;s GSUB ligature lookups at build time into a
+<code>sequences</code> table (first codepoint → resolved ligature glyph), and the text
+pipeline runs a longest-match pre-pass over it, so a flag pair or a ZWJ
+sequence produces exactly one COLR Form XObject:</p>
+<ul>
+<li><strong>51 flags</strong> — 🇪🇺 EU, 🇺🇳 UN, the G20 members, and other widely used
+locales (regional-indicator pairs).</li>
+<li><strong>22 ZWJ sequences</strong> — families (<code>👨‍👩‍👧</code>), professions (<code>👩‍🚀</code>, <code>👨‍💻</code>),
+<code>❤️‍🔥</code>, <code>🏳️‍🌈</code>, <code>🏳️‍⚧️</code>, <code>🏴‍☠️</code>, <code>🐻‍❄️</code>, <code>😮‍💨</code>, and friends —
+in their skin-tone-free RGI forms.</li>
+</ul>
+<p>No API change is required: register the bundled colour-emoji module as usual
+and write the sequences in your text. Three behaviours worth knowing:</p>
+<ul>
+<li><strong>VS-16 tolerance.</strong> Both the VS-16 spelling and the VS-16-free spelling of
+a sequence match the same glyph — real-world text is inconsistent about
+presentation selectors, so <code>❤️‍🔥</code> works with or without the invisible
+U+FE0F.</li>
+<li><strong>Fallback is never worse.</strong> A sequence absent from the table degrades to
+exactly the historical per-codepoint behaviour: unmatched joiners,
+variation selectors, and skin-tone modifiers are dropped, and unmatched
+regional indicators pass through the normal cmap lookup. A module without a
+<code>sequences</code> table renders byte-identically to v1.6.0.</li>
+<li><strong>Flags render flat.</strong> Noto&#39;s flag glyphs stack a wave-shading overlay on
+the flat artwork via a COLRv1 <code>PaintComposite</code> SRC_IN mask that has no PDF
+equivalent. pdfnative degrades the composite to its supported backdrop, so
+every flag renders as its flat (unwaved) artwork rather than falling back
+to monochrome.</li>
+</ul>
+<p>Skin-tone-modified sequences stay CLI-only — generate a module with
+<code>--sequences</code> / <code>--sequence-list</code> (see the <a href="colour-emoji-cli.html">CLI guide</a>).</p>
+<h2 id="advanced-compositing-v140">Advanced compositing (v1.4.0)<a class="heading-anchor" href="#advanced-compositing-v140" aria-label="Link to this section">#</a></h2>
+<p>COLRv1 includes two paint types beyond solid + axial/radial gradients, and
+pdfnative now maps both where a faithful PDF translation exists:</p>
+<table>
+<thead>
+<tr>
+<th>COLRv1 feature</th>
+<th>PDF mapping (v1.4.0)</th>
+</tr>
+</thead>
+<tbody><tr>
+<td>Sweep / conic gradient (<code>PaintSweepGradient</code>, format 8)</td>
+<td>Flat-shaded triangular <strong>wedges</strong> fanned around the centre — no <code>/Shading</code> resource, pure path fills. Matrix rotation is folded into the start/end angles via <code>Math.atan2</code>.</td>
+</tr>
+<tr>
+<td>Composite (<code>PaintComposite</code>, format 32) — <em>separable</em> blend modes</td>
+<td>Backdrop + source layers, with the source tagged via a <code>/BM</code> (blend mode) <code>/ExtGState</code>: Normal, Multiply, Screen, Overlay, Darken, Lighten, ColorDodge, ColorBurn, HardLight, SoftLight, Difference, Exclusion, Hue, Saturation, Color, Luminosity.</td>
+</tr>
+<tr>
+<td>Composite — <em>structural</em> Porter-Duff modes (<code>SrcOver</code>, <code>DestIn</code>, clipping masks, …)</td>
+<td>No exact PDF equivalent → the glyph falls back to the <strong>monochrome</strong> outline. Since v1.7.0, when only the composite&#39;s <em>source</em> subtree is unsupported, its partial layers roll back and the <strong>backdrop renders alone</strong> (best-effort) — Noto&#39;s flags degrade to their flat artwork this way.</td>
+</tr>
+</tbody></table>
+<p>Sweep wedges approximate the smooth conic sweep with a fan of flat-colour
+triangles whose count scales with the angular span — close enough for emoji at
+text sizes while staying within plain PDF path operators. Separable blend modes
+are exactly the set PDF defines in ISO 32000-1 §11.3.5, so they round-trip
+faithfully in any conformant viewer.</p>
+<blockquote>
+<p><strong>PDF/A note:</strong> blend modes and constant-alpha <code>/ExtGState</code> are transparency
+features that PDF/A-1b forbids. Use solid-layer emoji for archival documents.</p>
+</blockquote>
+<h2 id="limitations">Limitations<a class="heading-anchor" href="#limitations" aria-label="Link to this section">#</a></h2>
+<ul>
+<li><strong><code>PaintMask</code></strong> and COLRv1 variable (animated) paints are not yet rendered;
+glyphs using them fall back gracefully — to the backdrop layers when the
+unsupported paint sits inside a composite&#39;s source subtree (v1.7.0), to the
+monochrome outline otherwise. Tracked for a future release.</li>
+<li><strong>PDF/A:</strong> gradient transparency uses <code>/ExtGState</code> alpha, which PDF/A-1b
+forbids. Use solid-layer emoji or a non-PDF/A document for colour gradients.</li>
+</ul>
+<h2 id="variation-selectors--skin-tone-modifiers-v130">Variation selectors &amp; skin-tone modifiers (v1.3.0)<a class="heading-anchor" href="#variation-selectors--skin-tone-modifiers-v130" aria-label="Link to this section">#</a></h2>
+<p>Text such as <code>❤️</code> carries an invisible <strong>VS-16</strong> variation selector
+(U+FE0F), and <code>👍🏽</code> carries a <strong>Fitzpatrick</strong> skin-tone modifier
+(U+1F3FB–U+1F3FF); ZWJ sequences (<code>👨‍👩‍👧</code>) join several codepoints. Before
+v1.3.0 these zero-width formatting characters could route to the Latin font and
+render as <code>.notdef</code> tofu (the  box). As of v1.3.0 they are <strong>dropped during
+run-splitting</strong> when no registered font covers them, so the base emoji renders
+cleanly. (Internally this is the <code>isZeroWidthFormat(cp)</code> predicate in the
+shaping engine — it is not part of the published API surface.) Joiners are
+still preserved when an Indic shaper font maps them.</p>
+<p>Since <strong>v1.7.0</strong>, sequences covered by the registered font&#39;s <code>sequences</code> table
+take a different path entirely: the whole sequence — joiners, selectors and
+all — resolves to a single colour ligature glyph before run-splitting (see
+<a href="#flag--zwj-sequences-v170">Flag &amp; ZWJ sequences</a> above). The drop-during-run-splitting
+behaviour described here remains the fallback for uncovered sequences.</p>
+<p>Colour-glyph Form <code>/BBox</code> is also now computed from the glyph&#39;s transformed
+contour bounds (v1.3.0), so emoji that dip below the baseline are no longer
+clipped at the top or bottom.</p>
+<h2 id="see-also">See also<a class="heading-anchor" href="#see-also" aria-label="Link to this section">#</a></h2>
+<ul>
+<li><a href="quickstart.html">Quick start</a></li>
+<li><a href="troubleshooting.html">Troubleshooting</a> — missing glyphs / tofu</li>
+<li><a href="https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md" target="_blank" rel="noopener">CHANGELOG</a></li>
+</ul>
+<!-- guide:render:end -->
+  </article>
+</main>
+
+<footer class="footer">
+  <div class="footer-inner">
+    <span>MIT License · © 2026 Nizoka</span>
+    <ul class="footer-links" role="list">
+      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
+      <li><a href="https://www.npmjs.com/package/pdfnative" target="_blank" rel="noopener">npm</a></li>
+      <li><a href="https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md" target="_blank" rel="noopener">Changelog</a></li>
+      <li><a href="./">All guides</a></li>
+    </ul>
+  </div>
+</footer>
+
+<script src="https://cdn.jsdelivr.net/npm/marked@12.0.2/marked.min.js" integrity="sha384-/TQbtLCAerC3jgaim+N78RZSDYV7ryeoBCVqTuzRrFec2akfBkHS7ACQ3PQhvMVi" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/dompurify@3.1.5/dist/purify.min.js" integrity="sha384-nszIONF2FGC59kn+pPFaRa6WUNGwsZgXZiJxJwQbym+TzcH7smolUviLgpPbNx7V" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/prism.min.js" integrity="sha384-BGaNxfftg+9+TtC098wxawPFVEUpKYvaiCgbB0iqAMjK/4jDdmUY+oGxrPNvnXEf" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-typescript.min.js" integrity="sha384-PeOqKNW/piETaCg8rqKFy+Pm6KEk7e36/5YZE5XO/OaFdO+/Aw3O8qZ9qDPKVUgx" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-bash.min.js" integrity="sha384-9WmlN8ABpoFSSHvBGGjhvB3E/D8UkNB9HpLJjBQFC2VSQsM1odiQDv4NbEo+7l15" crossorigin="anonymous" defer></script>
+<script src="guide.js" defer></script>
+</body>
+</html>
diff --git a/docs/guides/debugging.html b/docs/guides/debugging.html
index fa5713e..6011669 100644
--- a/docs/guides/debugging.html
+++ b/docs/guides/debugging.html
@@ -1,85 +1,209 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>Layout debugging & inspection — pdfnative</title>
-  <meta name="description" content="Debug pdfnative document layout with an opt-in visual overlay (layout: { debug: true }) that draws margin / content / cell boxes, plus the inspectDocumentLayout() programmatic geometry API. New in v1.5.0.">
-  <link rel="canonical" href="https://pdfnative.dev/guides/debugging.html">
-  <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/debugging.html">
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Layout debugging & inspection — pdfnative</title>
+  <meta name="description" content="Debug pdfnative document layout with an opt-in visual overlay (layout: { debug: true }) that draws margin / content / cell boxes, plus the inspectDocumentLayout() programmatic geometry API. New in v1.5.0.">
+  <link rel="canonical" href="https://pdfnative.dev/guides/debugging.html">
+  <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/debugging.html">
   <link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/debugging.html">
-  <link rel="alternate" type="text/markdown" href="debugging.md">
-  <meta property="og:type" content="article">
-  <meta property="og:site_name" content="pdfnative">
+  <link rel="alternate" type="text/markdown" href="debugging.md">
+  <link rel="alternate" type="text/plain" href="../llms.txt" title="llms.txt — machine-readable documentation index">
+  <meta property="og:type" content="article">
+  <meta property="og:site_name" content="pdfnative">
   <meta property="og:locale" content="en_US">
-  <meta property="og:url" content="https://pdfnative.dev/guides/debugging.html">
-  <meta property="og:title" content="Layout debugging & inspection — pdfnative">
-  <meta property="og:description" content="Opt-in visual overlay (margin/content/cell boxes) and inspectDocumentLayout() per-page block geometry. Byte-identical when off. New in v1.5.0.">
-  <meta property="og:image" content="https://pdfnative.dev/assets/og-image.png">
-  <meta property="og:image:width" content="1200">
-  <meta property="og:image:height" content="630">
-  <meta name="twitter:card" content="summary_large_image">
-  <meta name="twitter:title" content="Layout debugging & inspection — pdfnative">
-  <meta name="twitter:description" content="Visual overlay + programmatic block geometry for pdfnative documents.">
-  <meta name="twitter:image" content="https://pdfnative.dev/assets/og-image.png">
-  <link rel="icon" type="image/svg+xml" href="../favicon.svg">
-  <link rel="stylesheet" href="../style.css">
-  <link rel="stylesheet" href="guide.css">
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
-</head>
-<body>
-
-<a class="skip-link" href="#main-content">Skip to main content</a>
-
-<nav class="nav" role="navigation" aria-label="Main navigation">
-  <div class="nav-inner">
-    <a class="nav-brand" href="../">
-      <img src="../assets/logo.svg" alt="" width="28" height="28">
-      pdfnative
-    </a>
-    <button class="nav-hamburger" aria-label="Toggle menu" aria-expanded="false">☰</button>
-    <ul class="nav-links" role="list">
-      <li><a href="../#features">Features</a></li>
-      <li><a href="../#examples">Examples</a></li>
-      <li><a href="../#demo">Demo</a></li>
-      <li><a href="../#mcp">MCP</a></li>
-      <li><a href="../#cli">CLI</a></li>
-      <li><a href="../#react">React</a></li>
-      <li><a href="../learn/">Learn</a></li>
-      <li><a href="./">Guides</a></li>
-      <li><a href="../playgrounds/">Playgrounds</a></li>
-      <li><a href="../responsibility.html">Responsibility</a></li>
-      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
-      <li><button class="theme-toggle" aria-label="Toggle dark mode">🌙</button></li>
-    </ul>
-  </div>
-</nav>
-
-<main class="guide-shell" id="main-content" tabindex="-1">
-  <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; Layout debugging</p>
-  <article id="guide-content" class="guide-content" data-md="debugging.md">
-    <p class="guide-loading">Loading…</p>
-    <noscript><p>This guide is written in Markdown: <a href="debugging.md">read debugging.md</a>.</p></noscript>
-  </article>
-</main>
-
-<footer class="footer">
-  <div class="footer-inner">
-    <span>MIT License · © 2026 Nizoka</span>
-    <ul class="footer-links" role="list">
-      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
-      <li><a href="https://www.npmjs.com/package/pdfnative" target="_blank" rel="noopener">npm</a></li>
-      <li><a href="https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md" target="_blank" rel="noopener">Changelog</a></li>
-      <li><a href="./">All guides</a></li>
-    </ul>
-  </div>
-</footer>
-
-<script src="https://cdn.jsdelivr.net/npm/marked@12.0.2/marked.min.js" integrity="sha384-/TQbtLCAerC3jgaim+N78RZSDYV7ryeoBCVqTuzRrFec2akfBkHS7ACQ3PQhvMVi" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/dompurify@3.1.5/dist/purify.min.js" integrity="sha384-nszIONF2FGC59kn+pPFaRa6WUNGwsZgXZiJxJwQbym+TzcH7smolUviLgpPbNx7V" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/prism.min.js" integrity="sha384-BGaNxfftg+9+TtC098wxawPFVEUpKYvaiCgbB0iqAMjK/4jDdmUY+oGxrPNvnXEf" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-typescript.min.js" integrity="sha384-PeOqKNW/piETaCg8rqKFy+Pm6KEk7e36/5YZE5XO/OaFdO+/Aw3O8qZ9qDPKVUgx" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-bash.min.js" integrity="sha384-9WmlN8ABpoFSSHvBGGjhvB3E/D8UkNB9HpLJjBQFC2VSQsM1odiQDv4NbEo+7l15" crossorigin="anonymous" defer></script>
-<script src="guide.js" defer></script>
-</body>
-</html>
+  <meta property="og:url" content="https://pdfnative.dev/guides/debugging.html">
+  <meta property="og:title" content="Layout debugging & inspection — pdfnative">
+  <meta property="og:description" content="Opt-in visual overlay (margin/content/cell boxes) and inspectDocumentLayout() per-page block geometry. Byte-identical when off. New in v1.5.0.">
+  <meta property="og:image" content="https://pdfnative.dev/assets/og-image.png">
+  <meta property="og:image:width" content="1200">
+  <meta property="og:image:height" content="630">
+  <meta name="twitter:card" content="summary_large_image">
+  <meta name="twitter:title" content="Layout debugging & inspection — pdfnative">
+  <meta name="twitter:description" content="Visual overlay + programmatic block geometry for pdfnative documents.">
+  <meta name="twitter:image" content="https://pdfnative.dev/assets/og-image.png">
+  <link rel="icon" type="image/svg+xml" href="../favicon.svg">
+  <link rel="stylesheet" href="../style.css">
+  <link rel="stylesheet" href="guide.css">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
+  <!-- guide:ld:start -->
+  <script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://pdfnative.dev/"},{"@type":"ListItem","position":2,"name":"Guides","item":"https://pdfnative.dev/guides/"},{"@type":"ListItem","position":3,"name":"Layout debugging & inspection","item":"https://pdfnative.dev/guides/debugging.html"}]},{"@type":"TechArticle","headline":"Layout debugging & inspection","description":"Debug pdfnative document layout with an opt-in visual overlay (layout: { debug: true }) that draws margin / content / cell boxes, plus the inspectDocumentLayout() programmatic geometry API. New in v1.5.0.","inLanguage":"en","author":{"@type":"Organization","name":"Nizoka","url":"https://github.com/Nizoka"},"publisher":{"@type":"Organization","name":"pdfnative","url":"https://pdfnative.dev","logo":{"@type":"ImageObject","url":"https://pdfnative.dev/assets/logo.svg"}},"mainEntityOfPage":{"@type":"WebPage","@id":"https://pdfnative.dev/guides/debugging.html"},"isPartOf":{"@type":"WebSite","name":"pdfnative","url":"https://pdfnative.dev"}}]}</script>
+  <!-- guide:ld:end -->
+</head>
+<body>
+
+<a class="skip-link" href="#main-content">Skip to main content</a>
+
+<nav class="nav" role="navigation" aria-label="Main navigation">
+  <div class="nav-inner">
+    <a class="nav-brand" href="../">
+      <img src="../assets/logo.svg" alt="" width="28" height="28">
+      pdfnative
+    </a>
+    <button class="nav-hamburger" aria-label="Toggle menu" aria-expanded="false">☰</button>
+    <ul class="nav-links" role="list">
+      <li><a href="../#features">Features</a></li>
+      <li><a href="../#examples">Examples</a></li>
+      <li><a href="../#demo">Demo</a></li>
+      <li><a href="../#mcp">MCP</a></li>
+      <li><a href="../#cli">CLI</a></li>
+      <li><a href="../#react">React</a></li>
+      <li><a href="../learn/">Learn</a></li>
+      <li><a href="./">Guides</a></li>
+      <li><a href="../playgrounds/">Playgrounds</a></li>
+      <li><a href="../responsibility.html">Responsibility</a></li>
+      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
+      <li><button class="theme-toggle" aria-label="Toggle dark mode">🌙</button></li>
+    </ul>
+  </div>
+</nav>
+
+<main class="guide-shell" id="main-content" tabindex="-1">
+  <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; Layout debugging</p>
+  <article id="guide-content" class="guide-content" data-md="debugging.md" data-prerendered="true">
+<!-- guide:render:start -->
+<h1 id="layout-debugging--inspection">Layout debugging &amp; inspection</h1>
+<blockquote>
+<p><strong>New in v1.5.0.</strong> Two complementary tools help you understand <em>where</em>
+pdfnative places every block on the page: an <strong>opt-in visual overlay</strong>
+(<code>layout: { debug: true }</code>) that draws margin / content / cell boxes straight
+onto the PDF, and a <strong>programmatic inspection</strong> API
+(<code>inspectDocumentLayout()</code>) that returns the per-page block geometry as plain
+data. Both are byte-neutral: when debug is off, output is <strong>byte-identical</strong>
+to previous releases.</p>
+</blockquote>
+<h2 id="tldr">TL;DR<a class="heading-anchor" href="#tldr" aria-label="Link to this section">#</a></h2>
+<pre><code class="language-ts">import { buildDocumentPDFBytes, inspectDocumentLayout } from &#39;pdfnative&#39;;
+
+const params = {
+  title: &#39;Invoice&#39;,
+  blocks: [
+    { type: &#39;heading&#39;, level: 1, text: &#39;Invoice #42&#39; },
+    { type: &#39;paragraph&#39;, text: &#39;Thanks for your business.&#39; },
+  ],
+};
+
+// 1. Visual overlay — margin / content / cell boxes drawn on the PDF
+const pdf = buildDocumentPDFBytes(params, { debug: true });
+
+// 2. Programmatic geometry — no rendering, just data
+const layout = inspectDocumentLayout(params);
+for (const page of layout.pages) {
+  for (const block of page.blocks) {
+    console.log(page.index, block.type, block.x, block.top, block.width, block.height);
+  }
+}
+</code></pre>
+<h2 id="visual-overlay">Visual overlay<a class="heading-anchor" href="#visual-overlay" aria-label="Link to this section">#</a></h2>
+<p>Pass <code>debug: true</code> (or a granular object) in the layout options:</p>
+<pre><code class="language-ts">buildDocumentPDFBytes(params, { debug: true });
+
+// or select exactly what you want to see:
+buildDocumentPDFBytes(params, {
+  debug: { showMargins: true, showContentBounds: true, showCells: false },
+});
+</code></pre>
+<table>
+<thead>
+<tr>
+<th>Option</th>
+<th>Colour</th>
+<th>Draws</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>showMargins</code></td>
+<td>blue</td>
+<td>the page margin box (content area boundary)</td>
+</tr>
+<tr>
+<td><code>showContentBounds</code></td>
+<td>red</td>
+<td>a rectangle around every rendered block</td>
+</tr>
+<tr>
+<td><code>showCells</code></td>
+<td>green</td>
+<td>per-cell rectangles for tables</td>
+</tr>
+</tbody></table>
+<p><code>debug: true</code> is shorthand for enabling all three. The overlay is drawn <strong>last</strong>,
+on top of the content, each shape wrapped in its own graphics state (<code>q … Q</code>) so
+it never leaks colour or line-width into your document. Turn it off (or omit it)
+and the bytes are exactly what you&#39;d get without the option.</p>
+<h2 id="programmatic-inspection">Programmatic inspection<a class="heading-anchor" href="#programmatic-inspection" aria-label="Link to this section">#</a></h2>
+<p><code>inspectDocumentLayout(params, layout?)</code> runs the <strong>same pagination engine</strong> as
+the builder but produces data instead of PDF bytes — no rendering, no font
+embedding:</p>
+<pre><code class="language-ts">import { inspectDocumentLayout } from &#39;pdfnative&#39;;
+import type { LayoutInspection } from &#39;pdfnative&#39;;
+
+const report: LayoutInspection = inspectDocumentLayout(params);
+
+report.pages.forEach((page) =&gt; {
+  console.log(`Page ${page.index + 1}: ${page.blocks.length} blocks`);
+  page.blocks.forEach((b) =&gt; {
+    console.log(`  ${b.type} @ (${b.x}, ${b.top}) ${b.width}×${b.height}`);
+  });
+});
+</code></pre>
+<h3 id="shape">Shape<a class="heading-anchor" href="#shape" aria-label="Link to this section">#</a></h3>
+<table>
+<thead>
+<tr>
+<th>Type</th>
+<th>Fields</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>LayoutInspection</code></td>
+<td><code>{ pageWidth, pageHeight, margins, totalPages, pages: InspectedPage[] }</code></td>
+</tr>
+<tr>
+<td><code>InspectedPage</code></td>
+<td><code>{ index, blocks: InspectedBlock[] }</code></td>
+</tr>
+<tr>
+<td><code>InspectedBlock</code></td>
+<td><code>{ type, page, x, top, width, height }</code> (PDF user-space points, origin bottom-left; <code>top</code> is the block&#39;s upper edge, <code>height</code> extends downward)</td>
+</tr>
+</tbody></table>
+<p>Because it shares the builder&#39;s <code>estimateBlockHeight</code> / <code>planTable</code> logic and
+constants, the reported geometry matches where the real renderer places each
+block — including table slicing across page breaks.</p>
+<h2 id="when-to-use-which">When to use which<a class="heading-anchor" href="#when-to-use-which" aria-label="Link to this section">#</a></h2>
+<ul>
+<li><strong>Overlay</strong> — eyeball a single document: &quot;why is this paragraph clipped?&quot;,
+&quot;is my table overflowing the margin?&quot; Open the PDF and <em>see</em> the boxes.</li>
+<li><strong>Inspection</strong> — automate it: assert block positions in a test, drive a
+layout linter, or feed geometry to another tool.</li>
+</ul>
+<h2 id="sample">Sample<a class="heading-anchor" href="#sample" aria-label="Link to this section">#</a></h2>
+<p><a href="https://github.com/Nizoka/pdfnative/blob/main/scripts/generators/layout-debug-overlay.ts" target="_blank" rel="noopener">layout-debug-overlay.ts</a>
+renders the same document twice — once clean, once with the overlay — and prints
+the <code>inspectDocumentLayout()</code> report.</p>
+<!-- guide:render:end -->
+  </article>
+</main>
+
+<footer class="footer">
+  <div class="footer-inner">
+    <span>MIT License · © 2026 Nizoka</span>
+    <ul class="footer-links" role="list">
+      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
+      <li><a href="https://www.npmjs.com/package/pdfnative" target="_blank" rel="noopener">npm</a></li>
+      <li><a href="https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md" target="_blank" rel="noopener">Changelog</a></li>
+      <li><a href="./">All guides</a></li>
+    </ul>
+  </div>
+</footer>
+
+<script src="https://cdn.jsdelivr.net/npm/marked@12.0.2/marked.min.js" integrity="sha384-/TQbtLCAerC3jgaim+N78RZSDYV7ryeoBCVqTuzRrFec2akfBkHS7ACQ3PQhvMVi" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/dompurify@3.1.5/dist/purify.min.js" integrity="sha384-nszIONF2FGC59kn+pPFaRa6WUNGwsZgXZiJxJwQbym+TzcH7smolUviLgpPbNx7V" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/prism.min.js" integrity="sha384-BGaNxfftg+9+TtC098wxawPFVEUpKYvaiCgbB0iqAMjK/4jDdmUY+oGxrPNvnXEf" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-typescript.min.js" integrity="sha384-PeOqKNW/piETaCg8rqKFy+Pm6KEk7e36/5YZE5XO/OaFdO+/Aw3O8qZ9qDPKVUgx" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-bash.min.js" integrity="sha384-9WmlN8ABpoFSSHvBGGjhvB3E/D8UkNB9HpLJjBQFC2VSQsM1odiQDv4NbEo+7l15" crossorigin="anonymous" defer></script>
+<script src="guide.js" defer></script>
+</body>
+</html>
diff --git a/docs/guides/faq.html b/docs/guides/faq.html
index 229d0a7..f7d7131 100644
--- a/docs/guides/faq.html
+++ b/docs/guides/faq.html
@@ -9,6 +9,7 @@
   <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/faq.html">
   <link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/faq.html">
   <link rel="alternate" type="text/markdown" href="faq.md">
+  <link rel="alternate" type="text/plain" href="../llms.txt" title="llms.txt — machine-readable documentation index">
   <meta property="og:type" content="article">
   <meta property="og:site_name" content="pdfnative">
   <meta property="og:locale" content="en_US">
@@ -26,6 +27,9 @@
   <link rel="stylesheet" href="../style.css">
   <link rel="stylesheet" href="guide.css">
   <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
+  <!-- guide:ld:start -->
+  <script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://pdfnative.dev/"},{"@type":"ListItem","position":2,"name":"Guides","item":"https://pdfnative.dev/guides/"},{"@type":"ListItem","position":3,"name":"FAQ","item":"https://pdfnative.dev/guides/faq.html"}]},{"@type":"TechArticle","headline":"FAQ","description":"Frequently asked questions about pdfnative — custom fonts, PDF/A, encryption, BiDi, browser usage, signatures, and more.","inLanguage":"en","author":{"@type":"Organization","name":"Nizoka","url":"https://github.com/Nizoka"},"publisher":{"@type":"Organization","name":"pdfnative","url":"https://pdfnative.dev","logo":{"@type":"ImageObject","url":"https://pdfnative.dev/assets/logo.svg"}},"mainEntityOfPage":{"@type":"WebPage","@id":"https://pdfnative.dev/guides/faq.html"},"isPartOf":{"@type":"WebSite","name":"pdfnative","url":"https://pdfnative.dev"}},{"@type":"FAQPage","mainEntity":[{"@type":"Question","name":"How do I generate my first PDF?","acceptedAnswer":{"@type":"Answer","text":"import { buildDocumentPDFBytes, downloadBlob } from 'pdfnative'; const pdf = buildDocumentPDFBytes({ title: 'Hello', blocks: [ { type: 'heading', text: 'Hello world', level: 1 }, { type: 'paragraph', text: 'My first PDF.' }, ], }); downloadBlob(pdf, 'hello.pdf'); // browser // or, in Node.js: // fs.writeFileSync('hello.pdf', pdf); See the Quick Start guide for Node.js, browser, and Web Worker walkthroughs."}},{"@type":"Question","name":"Which builder should I pick: `buildPDFBytes` or `buildDocumentPDFBytes`?","acceptedAnswer":{"@type":"Answer","text":"Builder — Best for — Key shape `buildPDFBytes` — Tabular reports, bank statements, invoices with a single table — `{ title, headers, rows, infoItems, balanceText, ... }` `buildDocumentPDFBytes` — Mixed-content documents (manuals, articles, multi-section reports) — `{ title, blocks: [...] }` with 13 block types Both return Uint8Array and accept the same layout / encryption / compression / tagged-PDF options."}},{"@type":"Question","name":"Does it work in the browser?","acceptedAnswer":{"@type":"Answer","text":"Yes — pdfnative is a dual ESM/CJS build with zero Node.js-specific APIs in the core: import { buildDocumentPDFBytes, downloadBlob } from 'pdfnative'; const pdf = buildDocumentPDFBytes({ title: 'Hello', blocks: [/* … */] }); downloadBlob(pdf, 'output.pdf'); For optimal compression in Node.js, call initNodeCompression() once at startup. In the browser, a stored-block fallback is used automatically."}},{"@type":"Question","name":"Does it work with Deno / Bun?","acceptedAnswer":{"@type":"Answer","text":"Yes. The library is standard ESM with no Node.js-specific imports in the core. Both Deno and Bun import it directly."}},{"@type":"Question","name":"Can I use custom fonts?","acceptedAnswer":{"@type":"Answer","text":"Yes. Build a font data module from any TTF file: npx pdfnative-build-font path/to/MyFont.ttf my-font-data.js Then register it: import { registerFonts, loadFontData, buildDocumentPDFBytes } from 'pdfnative'; registerFonts({ custom: () => import('./my-font-data.js'), }); const myFont = await loadFontData('custom'); const pdf = buildDocumentPDFBytes({ blocks: [{ type: 'paragraph', text: '…' }], fontEntries: [{ fontData: myFont!, fontRef: '/F3', lang: 'custom' }], }); Font subsetting is automatic — only the glyphs you actually used are embedded."}},{"@type":"Question","name":"How do I render Arabic / Hebrew / Thai / Devanagari?","acceptedAnswer":{"@type":"Answer","text":"Register the matching pre-built font module and pass it as a fontEntry : registerFonts({ ar: () => import('pdfnative/fonts/noto-arabic-data.js'), he: () => import('pdfnative/fonts/noto-hebrew-data.js'), th: () => import('pdfnative/fonts/noto-thai-data.js'), hi: () => import('pdfnative/fonts/noto-devanagari-data.js'), }); const langs = ['ar', 'he', 'th', 'hi']; const fontEntries = (await Promise.all(langs.map(loadFontData))) .map((fd, i) => (fd ? { fontData: fd, fontRef: `/F${3 + i}`, lang: langs[i] } : null)) .filter((e): e is NonNullable<typeof e> => e !== null); // .filter(Boolean) alone does not narrow the type const pdf = buildDocumentPDFBytes({ blocks: [ { type: 'paragraph', text: 'مرحبا — שלום — สวัสดี — नमस्ते' }, ], fontEntries, }); The lang property triggers BiDi resolution for RTL scripts and OpenType GSUB/GPOS shaping for Arabic, Devanagari, Bengali, Tamil, Telugu, Sinhala, Tibetan, Khmer, Myanmar, and Thai."}},{"@type":"Question","name":"Why does my Arabic text appear backwards?","acceptedAnswer":{"@type":"Answer","text":"The most common cause: missing lang: &#39;ar&#39; on the font entry. Without it, BiDi resolution and Arabic positional shaping are skipped. See Troubleshooting → RTL Text Backwards ."}},{"@type":"Question","name":"Which scripts are supported out of the box?","acceptedAnswer":{"@type":"Answer","text":"26 Noto font-data modules ship with the package: the 22 scripts — Amharic/Ethiopic, Arabic, Armenian, Bengali, Cyrillic, Devanagari, Georgian, Greek, Hebrew, Japanese, Khmer, Korean, Myanmar, Polish, Simplified Chinese, Sinhala, Tamil, Telugu, Thai, Tibetan, Turkish, Vietnamese — plus Latin (Noto Sans), math (Noto Sans Math), and monochrome + COLRv1 colour emoji."}},{"@type":"Question","name":"What PDF versions can pdfnative produce?","acceptedAnswer":{"@type":"Answer","text":"Mode — PDF version — Standard Default — 1.4 — ISO 32000-1 `tagged: true` — 1.7 — PDF/A-2b (default tagged mode, ISO 19005-2) `tagged: 'pdfa1b'` — 1.4 — PDF/A-1b (ISO 19005-1) `tagged: 'pdfa2u'` — 1.7 — PDF/A-2u (ISO 19005-2 with unicode) `tagged: 'pdfa3b'` — 1.7 — PDF/A-3b (ISO 19005-3, supports embedded files)"}},{"@type":"Question","name":"Which PDF/A variant should I pick?","acceptedAnswer":{"@type":"Answer","text":"PDF/A-1b — strictest, oldest. Pick only if your validator requires PDF 1.4 and you don&#39;t need transparency, JPEG2000, or layers. PDF/A-2b (recommended default) — PDF 1.7, supports transparency, layers, OpenType. Most modern archive systems target 2b. PDF/A-2u — same as 2b plus mandatory Unicode mapping for all text. Pick if downstream consumers need text extraction. PDF/A-3b — PDF/A-2b + ability to embed arbitrary attachments (e.g. source XML for invoicing standards like ZUGFeRD/Factur-X). Note: not all archive policies allow A-3."}},{"@type":"Question","name":"Can I combine PDF/A and encryption?","acceptedAnswer":{"@type":"Answer","text":"No. ISO 19005-1 §6.3.2 forbids encryption inside PDF/A documents. pdfnative validates this at the buildPDF() boundary and throws an error if both are requested. Pick one or the other."}},{"@type":"Question","name":"Is the output tagged for accessibility (PDF/UA)?","acceptedAnswer":{"@type":"Answer","text":"Yes — when you set tagged: true (or any PDF/A mode), pdfnative emits a structure tree with /Document → /Table → /TR → /TH|TD , /H1 – /H3 , /P , /L / /LI , /Figure , /Link , /Form , /TOC / /TOCI , and uses /ActualText for shaped Unicode. See the Accessibility guide ."}},{"@type":"Question","name":"How do I encrypt a PDF?","acceptedAnswer":{"@type":"Answer","text":"const pdf = buildPDFBytes(params, { encryption: { algorithm: 'aes256', // or 'aes128' userPassword: 'reader', ownerPassword: 'editor', permissions: { print: true, // default: true copy: false, // default: false modify: false, // default: false extractText: true, // accessibility text extraction — default: true }, }, }); aes256 (V5/R6) is recommended for new documents. Use aes128 (V4/R4) only when you need compatibility with very old viewers."}},{"@type":"Question","name":"How do I sign a PDF digitally?","acceptedAnswer":{"@type":"Answer","text":"import { addSignaturePlaceholder, signPdfBytes, parseCertificate, parseRsaPrivateKey } from 'pdfnative'; // 1. The PDF must contain a /Sig placeholder — add one if it doesn't // (skipping this throws \"No /Contents placeholder found\"): const prepared = addSignaturePlaceholder(pdfBytes); // 2. Sign it const signed = signPdfBytes(prepared, { signerCert: parseCertificate(certDer), // DER-encoded X.509 certificate rsaKey: parseRsaPrivateKey(keyDer), // DER-encoded RSA key (or `ecKey` for ECDSA P-256) algorithm: 'rsa-sha256', // or 'ecdsa-sha256' reason: 'Approved', name: 'Jane Doe', }); pdfnative implements ISO 32000-1 §12.8 — CMS/PKCS#7 SignedData with RSA (PKCS#1 v1.5) or ECDSA (P-256); RSA also offers SHA-384/512 since v1.7.0. The crypto stack is implemented in pure TypeScript inside src/crypto/ — no native modules, no node:crypto (an optional constant-time native provider can be plugged in via setCryptoProvider )."}},{"@type":"Question","name":"How do I make a signature \"LTV enabled\" (valid for years)?","acceptedAnswer":{"@type":"Answer","text":"Since v1.7.0 pdfnative covers the full PAdES baseline (ETSI EN 319 142-1): sign with profile: &#39;pades&#39; , add an RFC 3161 timestamp with signPdfBytesWithTimestamp , embed revocation material with addValidationInfo ( /DSS + /VRI ), and cap with addDocumentTimestamp . The engine never opens sockets — you inject the TSA/OCSP/CRL transport via setTimestampProvider / setRevocationProvider . Full pipeline in the LTV guide ."}},{"@type":"Question","name":"Can a PDF carry several signatures?","acceptedAnswer":{"@type":"Answer","text":"Yes (v1.7.0): create each placeholder with allowMultiple: true and target it by fieldName when signing. Each signature is appended as a non-destructive incremental revision, so earlier signatures remain valid; inspect any file with listSignatures(bytes) . See signatures — multiple signatures ."}},{"@type":"Question","name":"Is the build supply-chain safe?","acceptedAnswer":{"@type":"Answer","text":"Zero runtime dependencies — npm install pdfnative brings in nothing transitive at runtime. NPM provenance — every release is signed via GitHub Actions OIDC (SLSA L3-equivalent). OpenSSF Scorecard scanned weekly; CodeQL on every push. Pinned dev dependencies managed via Dependabot."}},{"@type":"Question","name":"Can I read or modify existing PDFs?","acceptedAnswer":{"@type":"Answer","text":"Yes. pdfnative includes a tokenizer, object parser, xref/stream parser, and a non-destructive incremental modifier: import { openPdf, createModifier } from 'pdfnative'; const reader = openPdf(new Uint8Array(fs.readFileSync('input.pdf'))); console.log(`Pages: ${reader.pageCount}`); console.log(`Title: ${reader.getInfo()?.get('Title')}`); const mod = createModifier(reader); mod.setMetadata('Title', 'Updated Title'); const updated = mod.save(); // appends a new xref/trailer with /Prev chain"}},{"@type":"Question","name":"What's the maximum document size?","acceptedAnswer":{"@type":"Answer","text":"buildPDFBytes enforces a 100 000 row limit on tables. buildDocumentPDFBytes paginates automatically, with a default cap of 100 000 blocks ( DEFAULT_MAX_BLOCKS ) that you can raise via layout.maxBlocks ; past that, the practical ceiling is your available memory. For very large documents, see the streaming question below."}},{"@type":"Question","name":"How do I avoid loading the whole PDF into memory?","acceptedAnswer":{"@type":"Answer","text":"Use the streaming API — it returns an AsyncGenerator&lt;Uint8Array&gt; that yields chunks as they&#39;re produced: import { buildDocumentPDFStream } from 'pdfnative'; for await (const chunk of buildDocumentPDFStream(params, {}, { chunkSize: 65536 })) { await writeStream.write(chunk); }"}},{"@type":"Question","name":"How can I make the PDF smaller?","acceptedAnswer":{"@type":"Answer","text":"Enable compression : compress: true (FlateDecode, 50–90 % size reduction). Initialize native zlib in Node.js : await initNodeCompression() once at startup. Use JPEG for photos — JPEG (DCTDecode) is already compressed; PNG is FlateDecode-compressed. Font subsetting is automatic — but each script you embed adds one subset."}},{"@type":"Question","name":"Can I generate PDFs in a Web Worker?","acceptedAnswer":{"@type":"Answer","text":"Yes. For large datasets pdfnative ships a built-in worker pipeline — use createPDF , which routes to a worker or the main thread for you: import { createPDF } from 'pdfnative'; const pdf = await createPDF(params, { workerUrl: new URL('./pdf-worker.js', import.meta.url), threshold: 500, // default WORKER_THRESHOLD = 500 rows }); Tables above the threshold run off the main thread (with an automatic main-thread fallback); smaller ones render synchronously. The lower-level generatePDFInWorker(workerUrl, params, { timeout, onProgress }) drives a worker directly — the worker URL is its first argument, and it has no threshold logic."}},{"@type":"Question","name":"How does it compare to jsPDF / pdfkit / pdf-lib / pdfmake?","acceptedAnswer":{"@type":"Answer","text":"See the feature comparison table in the README. Key differentiators: Zero runtime dependencies (others ship 3–6). 22 Unicode scripts with built-in BiDi and OpenType GSUB/GPOS shaping. PDF/A (1b, 2b, 2u, 3b) — none of the others support this directly. Built-in digital signatures (RSA + ECDSA) without external crypto modules. 5 native barcode formats (Code 128, EAN-13, QR, Data Matrix, PDF417) as PDF vector paths."}},{"@type":"Question","name":"Does it convert HTML to PDF?","acceptedAnswer":{"@type":"Answer","text":"No, and it never will. HTML→PDF is a different problem domain (browser engine, CSS, layout) better solved by tools like puppeteer or weasyprint . pdfnative is a structured-data → PDF library — you describe blocks, it emits ISO-compliant PDF."}},{"@type":"Question","name":"Why no classes / no inheritance?","acceptedAnswer":{"@type":"Answer","text":"pdfnative is built from pure functions. State is passed explicitly. This makes the library trivially tree-shakeable, easy to test, and easy to reason about. See the Architecture guide ."}}]}]}</script>
+  <!-- guide:ld:end -->
 </head>
 <body>
 
@@ -57,9 +61,307 @@
 
 <main class="guide-shell" id="main-content" tabindex="-1">
   <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; FAQ</p>
-  <article id="guide-content" class="guide-content" data-md="faq.md">
-    <p class="guide-loading">Loading…</p>
-    <noscript><p>This guide is written in Markdown: <a href="faq.md">read faq.md</a>.</p></noscript>
+  <article id="guide-content" class="guide-content" data-md="faq.md" data-prerendered="true">
+<!-- guide:render:start -->
+<h1 id="faq">FAQ</h1>
+<blockquote>
+<p>Frequently asked questions about pdfnative. Can&#39;t find your answer? Open a <a href="https://github.com/Nizoka/pdfnative/discussions" target="_blank" rel="noopener">discussion</a> or read the <a href="troubleshooting.html">Troubleshooting guide</a>.</p>
+</blockquote>
+<h2 id="getting-started">Getting started<a class="heading-anchor" href="#getting-started" aria-label="Link to this section">#</a></h2>
+<h3 id="how-do-i-generate-my-first-pdf">How do I generate my first PDF?<a class="heading-anchor" href="#how-do-i-generate-my-first-pdf" aria-label="Link to this section">#</a></h3>
+<pre><code class="language-typescript">import { buildDocumentPDFBytes, downloadBlob } from &#39;pdfnative&#39;;
+
+const pdf = buildDocumentPDFBytes({
+  title: &#39;Hello&#39;,
+  blocks: [
+    { type: &#39;heading&#39;,   text: &#39;Hello world&#39;, level: 1 },
+    { type: &#39;paragraph&#39;, text: &#39;My first PDF.&#39; },
+  ],
+});
+
+downloadBlob(pdf, &#39;hello.pdf&#39;);     // browser
+// or, in Node.js:
+// fs.writeFileSync(&#39;hello.pdf&#39;, pdf);
+</code></pre>
+<p>See the <a href="quickstart.html">Quick Start guide</a> for Node.js, browser, and Web Worker walkthroughs.</p>
+<h3 id="which-builder-should-i-pick-buildpdfbytes-or-builddocumentpdfbytes">Which builder should I pick: <code>buildPDFBytes</code> or <code>buildDocumentPDFBytes</code>?<a class="heading-anchor" href="#which-builder-should-i-pick-buildpdfbytes-or-builddocumentpdfbytes" aria-label="Link to this section">#</a></h3>
+<table>
+<thead>
+<tr>
+<th>Builder</th>
+<th>Best for</th>
+<th>Key shape</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>buildPDFBytes</code></td>
+<td>Tabular reports, bank statements, invoices with a single table</td>
+<td><code>{ title, headers, rows, infoItems, balanceText, ... }</code></td>
+</tr>
+<tr>
+<td><code>buildDocumentPDFBytes</code></td>
+<td>Mixed-content documents (manuals, articles, multi-section reports)</td>
+<td><code>{ title, blocks: [...] }</code> with 13 block types</td>
+</tr>
+</tbody></table>
+<p>Both return <code>Uint8Array</code> and accept the same layout / encryption / compression / tagged-PDF options.</p>
+<h3 id="does-it-work-in-the-browser">Does it work in the browser?<a class="heading-anchor" href="#does-it-work-in-the-browser" aria-label="Link to this section">#</a></h3>
+<p>Yes — pdfnative is a dual ESM/CJS build with zero Node.js-specific APIs in the core:</p>
+<pre><code class="language-typescript">import { buildDocumentPDFBytes, downloadBlob } from &#39;pdfnative&#39;;
+
+const pdf = buildDocumentPDFBytes({ title: &#39;Hello&#39;, blocks: [/* … */] });
+downloadBlob(pdf, &#39;output.pdf&#39;);
+</code></pre>
+<p>For optimal compression in Node.js, call <code>initNodeCompression()</code> once at startup. In the browser, a stored-block fallback is used automatically.</p>
+<h3 id="does-it-work-with-deno--bun">Does it work with Deno / Bun?<a class="heading-anchor" href="#does-it-work-with-deno--bun" aria-label="Link to this section">#</a></h3>
+<p>Yes. The library is standard ESM with no Node.js-specific imports in the core. Both Deno and Bun import it directly.</p>
+<hr>
+<h2 id="fonts-and-unicode">Fonts and Unicode<a class="heading-anchor" href="#fonts-and-unicode" aria-label="Link to this section">#</a></h2>
+<h3 id="can-i-use-custom-fonts">Can I use custom fonts?<a class="heading-anchor" href="#can-i-use-custom-fonts" aria-label="Link to this section">#</a></h3>
+<p>Yes. Build a font data module from any TTF file:</p>
+<pre><code class="language-bash">npx pdfnative-build-font path/to/MyFont.ttf my-font-data.js
+</code></pre>
+<p>Then register it:</p>
+<pre><code class="language-typescript">import { registerFonts, loadFontData, buildDocumentPDFBytes } from &#39;pdfnative&#39;;
+
+registerFonts({
+  custom: () =&gt; import(&#39;./my-font-data.js&#39;),
+});
+
+const myFont = await loadFontData(&#39;custom&#39;);
+const pdf = buildDocumentPDFBytes({
+  blocks: [{ type: &#39;paragraph&#39;, text: &#39;…&#39; }],
+  fontEntries: [{ fontData: myFont!, fontRef: &#39;/F3&#39;, lang: &#39;custom&#39; }],
+});
+</code></pre>
+<p>Font subsetting is automatic — only the glyphs you actually used are embedded.</p>
+<h3 id="how-do-i-render-arabic--hebrew--thai--devanagari">How do I render Arabic / Hebrew / Thai / Devanagari?<a class="heading-anchor" href="#how-do-i-render-arabic--hebrew--thai--devanagari" aria-label="Link to this section">#</a></h3>
+<p>Register the matching pre-built font module and pass it as a <code>fontEntry</code>:</p>
+<pre><code class="language-typescript">registerFonts({
+  ar: () =&gt; import(&#39;pdfnative/fonts/noto-arabic-data.js&#39;),
+  he: () =&gt; import(&#39;pdfnative/fonts/noto-hebrew-data.js&#39;),
+  th: () =&gt; import(&#39;pdfnative/fonts/noto-thai-data.js&#39;),
+  hi: () =&gt; import(&#39;pdfnative/fonts/noto-devanagari-data.js&#39;),
+});
+
+const langs = [&#39;ar&#39;, &#39;he&#39;, &#39;th&#39;, &#39;hi&#39;];
+const fontEntries = (await Promise.all(langs.map(loadFontData)))
+  .map((fd, i) =&gt; (fd ? { fontData: fd, fontRef: `/F${3 + i}`, lang: langs[i] } : null))
+  .filter((e): e is NonNullable&lt;typeof e&gt; =&gt; e !== null); // .filter(Boolean) alone does not narrow the type
+
+const pdf = buildDocumentPDFBytes({
+  blocks: [
+    { type: &#39;paragraph&#39;, text: &#39;مرحبا — שלום — สวัสดี — नमस्ते&#39; },
+  ],
+  fontEntries,
+});
+</code></pre>
+<p>The <code>lang</code> property triggers BiDi resolution for RTL scripts and OpenType GSUB/GPOS shaping for Arabic, Devanagari, Bengali, Tamil, Telugu, Sinhala, Tibetan, Khmer, Myanmar, and Thai.</p>
+<h3 id="why-does-my-arabic-text-appear-backwards">Why does my Arabic text appear backwards?<a class="heading-anchor" href="#why-does-my-arabic-text-appear-backwards" aria-label="Link to this section">#</a></h3>
+<p>The most common cause: missing <code>lang: &#39;ar&#39;</code> on the font entry. Without it, BiDi resolution and Arabic positional shaping are skipped. See <a href="troubleshooting.html">Troubleshooting → RTL Text Backwards</a>.</p>
+<h3 id="which-scripts-are-supported-out-of-the-box">Which scripts are supported out of the box?<a class="heading-anchor" href="#which-scripts-are-supported-out-of-the-box" aria-label="Link to this section">#</a></h3>
+<p>26 Noto font-data modules ship with the package: the 22 scripts — Amharic/Ethiopic, Arabic, Armenian, Bengali, Cyrillic, Devanagari, Georgian, Greek, Hebrew, Japanese, Khmer, Korean, Myanmar, Polish, Simplified Chinese, Sinhala, Tamil, Telugu, Thai, Tibetan, Turkish, Vietnamese — plus Latin (Noto Sans), math (Noto Sans Math), and monochrome + COLRv1 colour emoji.</p>
+<hr>
+<h2 id="standards-and-compliance">Standards and compliance<a class="heading-anchor" href="#standards-and-compliance" aria-label="Link to this section">#</a></h2>
+<h3 id="what-pdf-versions-can-pdfnative-produce">What PDF versions can pdfnative produce?<a class="heading-anchor" href="#what-pdf-versions-can-pdfnative-produce" aria-label="Link to this section">#</a></h3>
+<table>
+<thead>
+<tr>
+<th>Mode</th>
+<th>PDF version</th>
+<th>Standard</th>
+</tr>
+</thead>
+<tbody><tr>
+<td>Default</td>
+<td>1.4</td>
+<td>ISO 32000-1</td>
+</tr>
+<tr>
+<td><code>tagged: true</code></td>
+<td>1.7</td>
+<td>PDF/A-2b (default tagged mode, ISO 19005-2)</td>
+</tr>
+<tr>
+<td><code>tagged: &#39;pdfa1b&#39;</code></td>
+<td>1.4</td>
+<td>PDF/A-1b (ISO 19005-1)</td>
+</tr>
+<tr>
+<td><code>tagged: &#39;pdfa2u&#39;</code></td>
+<td>1.7</td>
+<td>PDF/A-2u (ISO 19005-2 with unicode)</td>
+</tr>
+<tr>
+<td><code>tagged: &#39;pdfa3b&#39;</code></td>
+<td>1.7</td>
+<td>PDF/A-3b (ISO 19005-3, supports embedded files)</td>
+</tr>
+</tbody></table>
+<h3 id="which-pdfa-variant-should-i-pick">Which PDF/A variant should I pick?<a class="heading-anchor" href="#which-pdfa-variant-should-i-pick" aria-label="Link to this section">#</a></h3>
+<ul>
+<li><strong>PDF/A-1b</strong> — strictest, oldest. Pick only if your validator requires PDF 1.4 and you don&#39;t need transparency, JPEG2000, or layers.</li>
+<li><strong>PDF/A-2b</strong> <em>(recommended default)</em> — PDF 1.7, supports transparency, layers, OpenType. Most modern archive systems target 2b.</li>
+<li><strong>PDF/A-2u</strong> — same as 2b plus mandatory Unicode mapping for all text. Pick if downstream consumers need text extraction.</li>
+<li><strong>PDF/A-3b</strong> — PDF/A-2b + ability to embed arbitrary attachments (e.g. source XML for invoicing standards like ZUGFeRD/Factur-X). Note: not all archive policies allow A-3.</li>
+</ul>
+<h3 id="can-i-combine-pdfa-and-encryption">Can I combine PDF/A and encryption?<a class="heading-anchor" href="#can-i-combine-pdfa-and-encryption" aria-label="Link to this section">#</a></h3>
+<p>No. ISO 19005-1 §6.3.2 forbids encryption inside PDF/A documents. pdfnative validates this at the <code>buildPDF()</code> boundary and throws an error if both are requested. Pick one or the other.</p>
+<h3 id="is-the-output-tagged-for-accessibility-pdfua">Is the output tagged for accessibility (PDF/UA)?<a class="heading-anchor" href="#is-the-output-tagged-for-accessibility-pdfua" aria-label="Link to this section">#</a></h3>
+<p>Yes — when you set <code>tagged: true</code> (or any PDF/A mode), pdfnative emits a structure tree with <code>/Document → /Table → /TR → /TH|TD</code>, <code>/H1</code>–<code>/H3</code>, <code>/P</code>, <code>/L</code>/<code>/LI</code>, <code>/Figure</code>, <code>/Link</code>, <code>/Form</code>, <code>/TOC</code>/<code>/TOCI</code>, and uses <code>/ActualText</code> for shaped Unicode. See the <a href="accessibility.html">Accessibility guide</a>.</p>
+<hr>
+<h2 id="security">Security<a class="heading-anchor" href="#security" aria-label="Link to this section">#</a></h2>
+<h3 id="how-do-i-encrypt-a-pdf">How do I encrypt a PDF?<a class="heading-anchor" href="#how-do-i-encrypt-a-pdf" aria-label="Link to this section">#</a></h3>
+<pre><code class="language-typescript">const pdf = buildPDFBytes(params, {
+  encryption: {
+    algorithm: &#39;aes256&#39;,           // or &#39;aes128&#39;
+    userPassword: &#39;reader&#39;,
+    ownerPassword: &#39;editor&#39;,
+    permissions: {
+      print: true,        // default: true
+      copy: false,        // default: false
+      modify: false,      // default: false
+      extractText: true,  // accessibility text extraction — default: true
+    },
+  },
+});
+</code></pre>
+<p><code>aes256</code> (V5/R6) is recommended for new documents. Use <code>aes128</code> (V4/R4) only when you need compatibility with very old viewers.</p>
+<h3 id="how-do-i-sign-a-pdf-digitally">How do I sign a PDF digitally?<a class="heading-anchor" href="#how-do-i-sign-a-pdf-digitally" aria-label="Link to this section">#</a></h3>
+<pre><code class="language-typescript">import { addSignaturePlaceholder, signPdfBytes, parseCertificate, parseRsaPrivateKey } from &#39;pdfnative&#39;;
+
+// 1. The PDF must contain a /Sig placeholder — add one if it doesn&#39;t
+//    (skipping this throws &quot;No /Contents placeholder found&quot;):
+const prepared = addSignaturePlaceholder(pdfBytes);
+
+// 2. Sign it
+const signed = signPdfBytes(prepared, {
+  signerCert: parseCertificate(certDer),   // DER-encoded X.509 certificate
+  rsaKey: parseRsaPrivateKey(keyDer),      // DER-encoded RSA key (or `ecKey` for ECDSA P-256)
+  algorithm: &#39;rsa-sha256&#39;,                 // or &#39;ecdsa-sha256&#39;
+  reason: &#39;Approved&#39;,
+  name: &#39;Jane Doe&#39;,
+});
+</code></pre>
+<p>pdfnative implements ISO 32000-1 §12.8 — CMS/PKCS#7 SignedData with RSA (PKCS#1 v1.5) or ECDSA (P-256); RSA also offers SHA-384/512 since v1.7.0. The crypto stack is implemented in pure TypeScript inside <code>src/crypto/</code> — no native modules, no <code>node:crypto</code> (an optional constant-time native provider can be plugged in via <code>setCryptoProvider</code>).</p>
+<h3 id="how-do-i-make-a-signature-ltv-enabled-valid-for-years">How do I make a signature &quot;LTV enabled&quot; (valid for years)?<a class="heading-anchor" href="#how-do-i-make-a-signature-ltv-enabled-valid-for-years" aria-label="Link to this section">#</a></h3>
+<p>Since v1.7.0 pdfnative covers the full PAdES baseline (ETSI EN 319 142-1):
+sign with <code>profile: &#39;pades&#39;</code>, add an RFC 3161 timestamp with
+<code>signPdfBytesWithTimestamp</code>, embed revocation material with
+<code>addValidationInfo</code> (<code>/DSS</code> + <code>/VRI</code>), and cap with <code>addDocumentTimestamp</code>.
+The engine never opens sockets — you inject the TSA/OCSP/CRL transport via
+<code>setTimestampProvider</code> / <code>setRevocationProvider</code>. Full pipeline in the
+<a href="ltv.html">LTV guide</a>.</p>
+<h3 id="can-a-pdf-carry-several-signatures">Can a PDF carry several signatures?<a class="heading-anchor" href="#can-a-pdf-carry-several-signatures" aria-label="Link to this section">#</a></h3>
+<p>Yes (v1.7.0): create each placeholder with <code>allowMultiple: true</code> and target
+it by <code>fieldName</code> when signing. Each signature is appended as a
+non-destructive incremental revision, so earlier signatures remain valid;
+inspect any file with <code>listSignatures(bytes)</code>. See
+<a href="signatures.html">signatures — multiple signatures</a>.</p>
+<h3 id="is-the-build-supply-chain-safe">Is the build supply-chain safe?<a class="heading-anchor" href="#is-the-build-supply-chain-safe" aria-label="Link to this section">#</a></h3>
+<ul>
+<li><strong>Zero runtime dependencies</strong> — <code>npm install pdfnative</code> brings in nothing transitive at runtime.</li>
+<li><strong>NPM provenance</strong> — every release is signed via GitHub Actions OIDC (SLSA L3-equivalent).</li>
+<li><strong>OpenSSF Scorecard</strong> scanned weekly; CodeQL on every push.</li>
+<li><strong>Pinned dev dependencies</strong> managed via Dependabot.</li>
+</ul>
+<hr>
+<h2 id="modifying-existing-pdfs">Modifying existing PDFs<a class="heading-anchor" href="#modifying-existing-pdfs" aria-label="Link to this section">#</a></h2>
+<h3 id="can-i-read-or-modify-existing-pdfs">Can I read or modify existing PDFs?<a class="heading-anchor" href="#can-i-read-or-modify-existing-pdfs" aria-label="Link to this section">#</a></h3>
+<p>Yes. pdfnative includes a tokenizer, object parser, xref/stream parser, and a non-destructive incremental modifier:</p>
+<pre><code class="language-typescript">import { openPdf, createModifier } from &#39;pdfnative&#39;;
+
+const reader = openPdf(new Uint8Array(fs.readFileSync(&#39;input.pdf&#39;)));
+
+console.log(`Pages: ${reader.pageCount}`);
+console.log(`Title: ${reader.getInfo()?.get(&#39;Title&#39;)}`);
+
+const mod = createModifier(reader);
+mod.setMetadata(&#39;Title&#39;, &#39;Updated Title&#39;);
+const updated = mod.save();   // appends a new xref/trailer with /Prev chain
+</code></pre>
+<h3 id="whats-the-maximum-document-size">What&#39;s the maximum document size?<a class="heading-anchor" href="#whats-the-maximum-document-size" aria-label="Link to this section">#</a></h3>
+<p><code>buildPDFBytes</code> enforces a 100 000 row limit on tables. <code>buildDocumentPDFBytes</code> paginates automatically, with a default cap of <strong>100 000 blocks</strong> (<code>DEFAULT_MAX_BLOCKS</code>) that you can raise via <code>layout.maxBlocks</code>; past that, the practical ceiling is your available memory. For very large documents, see the streaming question below.</p>
+<h3 id="how-do-i-avoid-loading-the-whole-pdf-into-memory">How do I avoid loading the whole PDF into memory?<a class="heading-anchor" href="#how-do-i-avoid-loading-the-whole-pdf-into-memory" aria-label="Link to this section">#</a></h3>
+<p>Use the streaming API — it returns an <code>AsyncGenerator&lt;Uint8Array&gt;</code> that yields chunks as they&#39;re produced:</p>
+<pre><code class="language-typescript">import { buildDocumentPDFStream } from &#39;pdfnative&#39;;
+
+for await (const chunk of buildDocumentPDFStream(params, {}, { chunkSize: 65536 })) {
+  await writeStream.write(chunk);
+}
+</code></pre>
+<hr>
+<h2 id="performance">Performance<a class="heading-anchor" href="#performance" aria-label="Link to this section">#</a></h2>
+<h3 id="how-can-i-make-the-pdf-smaller">How can I make the PDF smaller?<a class="heading-anchor" href="#how-can-i-make-the-pdf-smaller" aria-label="Link to this section">#</a></h3>
+<ol>
+<li><strong>Enable compression</strong>: <code>compress: true</code> (FlateDecode, 50–90 % size reduction).</li>
+<li><strong>Initialize native zlib in Node.js</strong>: <code>await initNodeCompression()</code> once at startup.</li>
+<li><strong>Use JPEG for photos</strong> — JPEG (DCTDecode) is already compressed; PNG is FlateDecode-compressed.</li>
+<li><strong>Font subsetting is automatic</strong> — but each script you embed adds one subset.</li>
+</ol>
+<h3 id="can-i-generate-pdfs-in-a-web-worker">Can I generate PDFs in a Web Worker?<a class="heading-anchor" href="#can-i-generate-pdfs-in-a-web-worker" aria-label="Link to this section">#</a></h3>
+<p>Yes. For large datasets pdfnative ships a built-in worker pipeline — use <code>createPDF</code>, which routes to a worker or the main thread for you:</p>
+<pre><code class="language-typescript">import { createPDF } from &#39;pdfnative&#39;;
+
+const pdf = await createPDF(params, {
+  workerUrl: new URL(&#39;./pdf-worker.js&#39;, import.meta.url),
+  threshold: 500, // default WORKER_THRESHOLD = 500 rows
+});
+</code></pre>
+<p>Tables above the threshold run off the main thread (with an automatic main-thread fallback); smaller ones render synchronously. The lower-level <code>generatePDFInWorker(workerUrl, params, { timeout, onProgress })</code> drives a worker directly — the worker URL is its first argument, and it has no threshold logic.</p>
+<hr>
+<h2 id="why-pdfnative">Why pdfnative?<a class="heading-anchor" href="#why-pdfnative" aria-label="Link to this section">#</a></h2>
+<h3 id="how-does-it-compare-to-jspdf--pdfkit--pdf-lib--pdfmake">How does it compare to jsPDF / pdfkit / pdf-lib / pdfmake?<a class="heading-anchor" href="#how-does-it-compare-to-jspdf--pdfkit--pdf-lib--pdfmake" aria-label="Link to this section">#</a></h3>
+<p>See the <a href="https://github.com/Nizoka/pdfnative#why-pdfnative" target="_blank" rel="noopener">feature comparison table</a> in the README. Key differentiators:</p>
+<ul>
+<li><strong>Zero runtime dependencies</strong> (others ship 3–6).</li>
+<li><strong>22 Unicode scripts</strong> with built-in BiDi and OpenType GSUB/GPOS shaping.</li>
+<li><strong>PDF/A</strong> (1b, 2b, 2u, 3b) — none of the others support this directly.</li>
+<li><strong>Built-in digital signatures</strong> (RSA + ECDSA) without external crypto modules.</li>
+<li><strong>5 native barcode formats</strong> (Code 128, EAN-13, QR, Data Matrix, PDF417) as PDF vector paths.</li>
+</ul>
+<h3 id="does-it-convert-html-to-pdf">Does it convert HTML to PDF?<a class="heading-anchor" href="#does-it-convert-html-to-pdf" aria-label="Link to this section">#</a></h3>
+<p>No, and it never will. HTML→PDF is a different problem domain (browser engine, CSS, layout) better solved by tools like <code>puppeteer</code> or <code>weasyprint</code>. pdfnative is a <strong>structured-data → PDF</strong> library — you describe blocks, it emits ISO-compliant PDF.</p>
+<h3 id="why-no-classes--no-inheritance">Why no classes / no inheritance?<a class="heading-anchor" href="#why-no-classes--no-inheritance" aria-label="Link to this section">#</a></h3>
+<p>pdfnative is built from pure functions. State is passed explicitly. This makes the library trivially tree-shakeable, easy to test, and easy to reason about. See the <a href="architecture.html">Architecture guide</a>.</p>
+<hr>
+<h2 id="common-errors">Common errors<a class="heading-anchor" href="#common-errors" aria-label="Link to this section">#</a></h2>
+<table>
+<thead>
+<tr>
+<th>Error</th>
+<th>Likely cause</th>
+<th>Fix</th>
+</tr>
+</thead>
+<tbody><tr>
+<td>Blank / missing glyphs for a script (no error is thrown)</td>
+<td><code>loadFontData(&#39;xx&#39;)</code> resolved to <code>null</code> because no loader was registered for that code — it returns <code>null</code> rather than throwing</td>
+<td>Call <code>registerFonts({ xx: … })</code> (or <code>registerFont</code>) first, then check the <code>loadFontData</code> result for <code>null</code> before building <code>fontEntries</code></td>
+</tr>
+<tr>
+<td><code>PDF/A and encryption are mutually exclusive</code></td>
+<td><code>tagged: &#39;pdfa…&#39;</code> combined with <code>encryption: …</code></td>
+<td>Pick one</td>
+</tr>
+<tr>
+<td><code>Invalid color format: …</code> / <code>Invalid color tuple …</code></td>
+<td>Unrecognized color value passed to a layout option</td>
+<td>Use <code>#rrggbb</code>, an <code>[r, g, b]</code> tuple with channels <strong>0–255</strong>, or a PDF RGB string <code>&#39;r g b&#39;</code> with channels 0.0–1.0</td>
+</tr>
+<tr>
+<td>Boxes / blank glyphs</td>
+<td>Font for that script is not loaded</td>
+<td>See <a href="troubleshooting.html">Troubleshooting → Missing glyphs</a></td>
+</tr>
+<tr>
+<td>Parser throws on external PDF</td>
+<td>Encrypted PDF opened without a password, or non-standard structure</td>
+<td>Pass <code>openPdf(bytes, { password })</code> — the parser decrypts RC4, AES-128 and AES-256 since v1.6.0. A missing or wrong password throws <code>PdfPasswordError</code></td>
+</tr>
+</tbody></table>
+<p>For more cases, see the <a href="troubleshooting.html">Troubleshooting guide</a>.</p>
+<!-- guide:render:end -->
   </article>
 </main>
 
diff --git a/docs/guides/font-validation.html b/docs/guides/font-validation.html
index 8a55426..4776d1a 100644
--- a/docs/guides/font-validation.html
+++ b/docs/guides/font-validation.html
@@ -1,85 +1,156 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>Font-data validation — pdfnative</title>
-  <meta name="description" content="Validate custom font-data modules before rendering with pdfnative's opt-in validateFontData() — SFNT magic, base64 integrity, cmap coverage, glyph-id range, width array, finite metrics. New in v1.4.0.">
-  <link rel="canonical" href="https://pdfnative.dev/guides/font-validation.html">
-  <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/font-validation.html">
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Font-data validation — pdfnative</title>
+  <meta name="description" content="Validate custom font-data modules before rendering with pdfnative's opt-in validateFontData() — SFNT magic, base64 integrity, cmap coverage, glyph-id range, width array, finite metrics. New in v1.4.0.">
+  <link rel="canonical" href="https://pdfnative.dev/guides/font-validation.html">
+  <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/font-validation.html">
   <link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/font-validation.html">
-  <link rel="alternate" type="text/markdown" href="font-validation.md">
-  <meta property="og:type" content="article">
-  <meta property="og:site_name" content="pdfnative">
+  <link rel="alternate" type="text/markdown" href="font-validation.md">
+  <link rel="alternate" type="text/plain" href="../llms.txt" title="llms.txt — machine-readable documentation index">
+  <meta property="og:type" content="article">
+  <meta property="og:site_name" content="pdfnative">
   <meta property="og:locale" content="en_US">
-  <meta property="og:url" content="https://pdfnative.dev/guides/font-validation.html">
-  <meta property="og:title" content="Font-data validation — pdfnative">
-  <meta property="og:description" content="Opt-in validateFontData() structurally checks custom font modules and returns { valid, errors, warnings }. New in v1.4.0.">
-  <meta property="og:image" content="https://pdfnative.dev/assets/og-image.png">
-  <meta property="og:image:width" content="1200">
-  <meta property="og:image:height" content="630">
-  <meta name="twitter:card" content="summary_large_image">
-  <meta name="twitter:title" content="Font-data validation — pdfnative">
-  <meta name="twitter:description" content="Structurally check custom font modules — SFNT magic, cmap coverage, glyph-id range, finite metrics.">
-  <meta name="twitter:image" content="https://pdfnative.dev/assets/og-image.png">
-  <link rel="icon" type="image/svg+xml" href="../favicon.svg">
-  <link rel="stylesheet" href="../style.css">
-  <link rel="stylesheet" href="guide.css">
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
-</head>
-<body>
-
-<a class="skip-link" href="#main-content">Skip to main content</a>
-
-<nav class="nav" role="navigation" aria-label="Main navigation">
-  <div class="nav-inner">
-    <a class="nav-brand" href="../">
-      <img src="../assets/logo.svg" alt="" width="28" height="28">
-      pdfnative
-    </a>
-    <button class="nav-hamburger" aria-label="Toggle menu" aria-expanded="false">☰</button>
-    <ul class="nav-links" role="list">
-      <li><a href="../#features">Features</a></li>
-      <li><a href="../#examples">Examples</a></li>
-      <li><a href="../#demo">Demo</a></li>
-      <li><a href="../#mcp">MCP</a></li>
-      <li><a href="../#cli">CLI</a></li>
-      <li><a href="../#react">React</a></li>
-      <li><a href="../learn/">Learn</a></li>
-      <li><a href="./">Guides</a></li>
-      <li><a href="../playgrounds/">Playgrounds</a></li>
-      <li><a href="../responsibility.html">Responsibility</a></li>
-      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
-      <li><button class="theme-toggle" aria-label="Toggle dark mode">🌙</button></li>
-    </ul>
-  </div>
-</nav>
-
-<main class="guide-shell" id="main-content" tabindex="-1">
-  <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; Font-data validation</p>
-  <article id="guide-content" class="guide-content" data-md="font-validation.md">
-    <p class="guide-loading">Loading…</p>
-    <noscript><p>This guide is written in Markdown: <a href="font-validation.md">read font-validation.md</a>.</p></noscript>
-  </article>
-</main>
-
-<footer class="footer">
-  <div class="footer-inner">
-    <span>MIT License · © 2026 Nizoka</span>
-    <ul class="footer-links" role="list">
-      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
-      <li><a href="https://www.npmjs.com/package/pdfnative" target="_blank" rel="noopener">npm</a></li>
-      <li><a href="https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md" target="_blank" rel="noopener">Changelog</a></li>
-      <li><a href="./">All guides</a></li>
-    </ul>
-  </div>
-</footer>
-
-<script src="https://cdn.jsdelivr.net/npm/marked@12.0.2/marked.min.js" integrity="sha384-/TQbtLCAerC3jgaim+N78RZSDYV7ryeoBCVqTuzRrFec2akfBkHS7ACQ3PQhvMVi" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/dompurify@3.1.5/dist/purify.min.js" integrity="sha384-nszIONF2FGC59kn+pPFaRa6WUNGwsZgXZiJxJwQbym+TzcH7smolUviLgpPbNx7V" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/prism.min.js" integrity="sha384-BGaNxfftg+9+TtC098wxawPFVEUpKYvaiCgbB0iqAMjK/4jDdmUY+oGxrPNvnXEf" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-typescript.min.js" integrity="sha384-PeOqKNW/piETaCg8rqKFy+Pm6KEk7e36/5YZE5XO/OaFdO+/Aw3O8qZ9qDPKVUgx" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-bash.min.js" integrity="sha384-9WmlN8ABpoFSSHvBGGjhvB3E/D8UkNB9HpLJjBQFC2VSQsM1odiQDv4NbEo+7l15" crossorigin="anonymous" defer></script>
-<script src="guide.js" defer></script>
-</body>
-</html>
+  <meta property="og:url" content="https://pdfnative.dev/guides/font-validation.html">
+  <meta property="og:title" content="Font-data validation — pdfnative">
+  <meta property="og:description" content="Opt-in validateFontData() structurally checks custom font modules and returns { valid, errors, warnings }. New in v1.4.0.">
+  <meta property="og:image" content="https://pdfnative.dev/assets/og-image.png">
+  <meta property="og:image:width" content="1200">
+  <meta property="og:image:height" content="630">
+  <meta name="twitter:card" content="summary_large_image">
+  <meta name="twitter:title" content="Font-data validation — pdfnative">
+  <meta name="twitter:description" content="Structurally check custom font modules — SFNT magic, cmap coverage, glyph-id range, finite metrics.">
+  <meta name="twitter:image" content="https://pdfnative.dev/assets/og-image.png">
+  <link rel="icon" type="image/svg+xml" href="../favicon.svg">
+  <link rel="stylesheet" href="../style.css">
+  <link rel="stylesheet" href="guide.css">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
+  <!-- guide:ld:start -->
+  <script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://pdfnative.dev/"},{"@type":"ListItem","position":2,"name":"Guides","item":"https://pdfnative.dev/guides/"},{"@type":"ListItem","position":3,"name":"Font-data validation","item":"https://pdfnative.dev/guides/font-validation.html"}]},{"@type":"TechArticle","headline":"Font-data validation","description":"Validate custom font-data modules before rendering with pdfnative's opt-in validateFontData() — SFNT magic, base64 integrity, cmap coverage, glyph-id range, width array, finite metrics. New in v1.4.0.","inLanguage":"en","author":{"@type":"Organization","name":"Nizoka","url":"https://github.com/Nizoka"},"publisher":{"@type":"Organization","name":"pdfnative","url":"https://pdfnative.dev","logo":{"@type":"ImageObject","url":"https://pdfnative.dev/assets/logo.svg"}},"mainEntityOfPage":{"@type":"WebPage","@id":"https://pdfnative.dev/guides/font-validation.html"},"isPartOf":{"@type":"WebSite","name":"pdfnative","url":"https://pdfnative.dev"}}]}</script>
+  <!-- guide:ld:end -->
+</head>
+<body>
+
+<a class="skip-link" href="#main-content">Skip to main content</a>
+
+<nav class="nav" role="navigation" aria-label="Main navigation">
+  <div class="nav-inner">
+    <a class="nav-brand" href="../">
+      <img src="../assets/logo.svg" alt="" width="28" height="28">
+      pdfnative
+    </a>
+    <button class="nav-hamburger" aria-label="Toggle menu" aria-expanded="false">☰</button>
+    <ul class="nav-links" role="list">
+      <li><a href="../#features">Features</a></li>
+      <li><a href="../#examples">Examples</a></li>
+      <li><a href="../#demo">Demo</a></li>
+      <li><a href="../#mcp">MCP</a></li>
+      <li><a href="../#cli">CLI</a></li>
+      <li><a href="../#react">React</a></li>
+      <li><a href="../learn/">Learn</a></li>
+      <li><a href="./">Guides</a></li>
+      <li><a href="../playgrounds/">Playgrounds</a></li>
+      <li><a href="../responsibility.html">Responsibility</a></li>
+      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
+      <li><button class="theme-toggle" aria-label="Toggle dark mode">🌙</button></li>
+    </ul>
+  </div>
+</nav>
+
+<main class="guide-shell" id="main-content" tabindex="-1">
+  <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; Font-data validation</p>
+  <article id="guide-content" class="guide-content" data-md="font-validation.md" data-prerendered="true">
+<!-- guide:render:start -->
+<h1 id="font-data-validation">Font-data validation</h1>
+<blockquote>
+<p><strong>New in v1.4.0.</strong> <code>validateFontData()</code> is an opt-in, read-only structural
+sanity check for <strong>custom</strong> font-data modules built from an untrusted or
+unfamiliar TTF/OTF. It catches the common failure modes early and returns
+<code>{ valid, errors, warnings }</code> instead of letting a cryptic <code>.notdef</code>/<code>NaN</code>
+surface deep inside the encoding/subsetting pipeline. The bundled
+<code>pdfnative/fonts/*</code> modules are already trusted — this is for fonts <strong>you</strong>
+build via <code>tools/build-font-data.cjs</code> or by hand.</p>
+</blockquote>
+<h2 id="tldr">TL;DR<a class="heading-anchor" href="#tldr" aria-label="Link to this section">#</a></h2>
+<pre><code class="language-ts">import { validateFontData } from &#39;pdfnative&#39;;
+import type { FontValidationResult } from &#39;pdfnative&#39;;
+
+const result: FontValidationResult = validateFontData(myFontData);
+if (!result.valid) {
+  console.error(&#39;Font rejected:&#39;, result.errors);
+}
+for (const w of result.warnings) console.warn(&#39;Font warning:&#39;, w);
+</code></pre>
+<h2 id="what-it-checks">What it checks<a class="heading-anchor" href="#what-it-checks" aria-label="Link to this section">#</a></h2>
+<table>
+<thead>
+<tr>
+<th>Area</th>
+<th>Rule</th>
+</tr>
+</thead>
+<tbody><tr>
+<td>Metrics</td>
+<td><code>unitsPerEm &gt; 0</code>, finite; <code>bbox</code> is 4 finite numbers</td>
+</tr>
+<tr>
+<td>Identity</td>
+<td><code>fontName</code> non-empty</td>
+</tr>
+<tr>
+<td>Coverage</td>
+<td><code>cmap</code> non-empty; every glyph id is an integer in <code>[0, numGlyphs)</code></td>
+</tr>
+<tr>
+<td>Widths</td>
+<td><code>widths</code> present (missing → <strong>warning</strong>); <code>pdfWidthArray</code> non-empty</td>
+</tr>
+<tr>
+<td>Binary</td>
+<td><code>ttfBase64</code> decodes as valid base64 and begins with an SFNT magic (<code>0x00010000</code>, <code>OTTO</code>, <code>true</code>, <code>ttcf</code>)</td>
+</tr>
+</tbody></table>
+<p>Blocking problems land in <code>errors</code>; suspicious-but-survivable ones land in
+<code>warnings</code>. It <strong>never throws</strong> — even on completely malformed input.</p>
+<h2 id="it-is-opt-in-by-design">It is opt-in by design<a class="heading-anchor" href="#it-is-opt-in-by-design" aria-label="Link to this section">#</a></h2>
+<p><code>validateFontData()</code> is <strong>not</strong> invoked automatically by <code>registerFont()</code>:
+running it on every load would add cost and risk false-rejecting edge-valid
+fonts. Call it yourself once when ingesting third-party font data, e.g. in a
+build step or a test:</p>
+<pre><code class="language-ts">import { validateFontData, registerFont } from &#39;pdfnative&#39;;
+import myFont from &#39;./my-font-data.js&#39;;
+
+const { valid, errors } = validateFontData(myFont);
+if (!valid) throw new Error(`Bad font data: ${errors.join(&#39;; &#39;)}`);
+registerFont(&#39;mylang&#39;, () =&gt; Promise.resolve(myFont));
+</code></pre>
+<h2 id="sample">Sample<a class="heading-anchor" href="#sample" aria-label="Link to this section">#</a></h2>
+<p><a href="https://github.com/Nizoka/pdfnative/blob/main/scripts/generators/font-validation-showcase.ts" target="_blank" rel="noopener">font-validation-showcase.ts</a>
+validates a bundled font plus deliberately broken payloads and renders the
+verdicts into a report PDF.</p>
+<!-- guide:render:end -->
+  </article>
+</main>
+
+<footer class="footer">
+  <div class="footer-inner">
+    <span>MIT License · © 2026 Nizoka</span>
+    <ul class="footer-links" role="list">
+      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
+      <li><a href="https://www.npmjs.com/package/pdfnative" target="_blank" rel="noopener">npm</a></li>
+      <li><a href="https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md" target="_blank" rel="noopener">Changelog</a></li>
+      <li><a href="./">All guides</a></li>
+    </ul>
+  </div>
+</footer>
+
+<script src="https://cdn.jsdelivr.net/npm/marked@12.0.2/marked.min.js" integrity="sha384-/TQbtLCAerC3jgaim+N78RZSDYV7ryeoBCVqTuzRrFec2akfBkHS7ACQ3PQhvMVi" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/dompurify@3.1.5/dist/purify.min.js" integrity="sha384-nszIONF2FGC59kn+pPFaRa6WUNGwsZgXZiJxJwQbym+TzcH7smolUviLgpPbNx7V" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/prism.min.js" integrity="sha384-BGaNxfftg+9+TtC098wxawPFVEUpKYvaiCgbB0iqAMjK/4jDdmUY+oGxrPNvnXEf" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-typescript.min.js" integrity="sha384-PeOqKNW/piETaCg8rqKFy+Pm6KEk7e36/5YZE5XO/OaFdO+/Aw3O8qZ9qDPKVUgx" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-bash.min.js" integrity="sha384-9WmlN8ABpoFSSHvBGGjhvB3E/D8UkNB9HpLJjBQFC2VSQsM1odiQDv4NbEo+7l15" crossorigin="anonymous" defer></script>
+<script src="guide.js" defer></script>
+</body>
+</html>
diff --git a/docs/guides/form-filling.html b/docs/guides/form-filling.html
index 7e5f23f..3e39840 100644
--- a/docs/guides/form-filling.html
+++ b/docs/guides/form-filling.html
@@ -9,6 +9,7 @@
   <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/form-filling.html">
   <link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/form-filling.html">
   <link rel="alternate" type="text/markdown" href="form-filling.md">
+  <link rel="alternate" type="text/plain" href="../llms.txt" title="llms.txt — machine-readable documentation index">
   <meta property="og:type" content="article">
   <meta property="og:site_name" content="pdfnative">
   <meta property="og:locale" content="en_US">
@@ -26,6 +27,9 @@
   <link rel="stylesheet" href="../style.css">
   <link rel="stylesheet" href="guide.css">
   <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
+  <!-- guide:ld:start -->
+  <script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://pdfnative.dev/"},{"@type":"ListItem","position":2,"name":"Guides","item":"https://pdfnative.dev/guides/"},{"@type":"ListItem","position":3,"name":"Form filling & flattening","item":"https://pdfnative.dev/guides/form-filling.html"}]},{"@type":"TechArticle","headline":"Form filling & flattening","description":"Read, fill, and flatten existing AcroForm PDFs with pdfnative — readFormFields(), fillForm() (regenerated appearances), flattenForm() — via non-destructive incremental update that preserves prior signatures. New in v1.6.0.","inLanguage":"en","author":{"@type":"Organization","name":"Nizoka","url":"https://github.com/Nizoka"},"publisher":{"@type":"Organization","name":"pdfnative","url":"https://pdfnative.dev","logo":{"@type":"ImageObject","url":"https://pdfnative.dev/assets/logo.svg"}},"mainEntityOfPage":{"@type":"WebPage","@id":"https://pdfnative.dev/guides/form-filling.html"},"isPartOf":{"@type":"WebSite","name":"pdfnative","url":"https://pdfnative.dev"}}]}</script>
+  <!-- guide:ld:end -->
 </head>
 <body>
 
@@ -57,9 +61,159 @@
 
 <main class="guide-shell" id="main-content" tabindex="-1">
   <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; Form filling</p>
-  <article id="guide-content" class="guide-content" data-md="form-filling.md">
-    <p class="guide-loading">Loading…</p>
-    <noscript><p>This guide is written in Markdown: <a href="form-filling.md">read form-filling.md</a>.</p></noscript>
+  <article id="guide-content" class="guide-content" data-md="form-filling.md" data-prerendered="true">
+<!-- guide:render:start -->
+<h1 id="form-filling--flattening">Form filling &amp; flattening</h1>
+<blockquote>
+<p><strong>New in v1.6.0.</strong> Read, fill, and flatten the <strong>interactive AcroForm fields
+of existing PDFs</strong> — whether authored by pdfnative or a third party — via
+non-destructive incremental update. Complements the form <em>builder</em> (which
+creates fields from scratch).</p>
+</blockquote>
+<h2 id="tldr">TL;DR<a class="heading-anchor" href="#tldr" aria-label="Link to this section">#</a></h2>
+<pre><code class="language-ts">import { readFormFields, fillForm, flattenForm } from &#39;pdfnative&#39;;
+import { readFileSync, writeFileSync } from &#39;node:fs&#39;;
+
+const src = readFileSync(&#39;application.pdf&#39;);
+
+// 1. Discover the fields
+for (const f of readFormFields(src)) {
+  console.log(f.name, f.type, f.value);
+}
+
+// 2. Fill by field name
+const filled = fillForm(src, {
+  fullName: &#39;Ada Lovelace&#39;,
+  agree: true,               // checkbox
+  country: &#39;France&#39;,         // dropdown option
+});
+writeFileSync(&#39;filled.pdf&#39;, filled);
+
+// 3. Optionally flatten (make it non-editable)
+writeFileSync(&#39;flat.pdf&#39;, flattenForm(filled));
+</code></pre>
+<h2 id="readformfieldsbytes-options"><code>readFormFields(bytes, options?)</code><a class="heading-anchor" href="#readformfieldsbytes-options" aria-label="Link to this section">#</a></h2>
+<p>Returns a <code>ParsedFormField[]</code> describing every terminal field:</p>
+<pre><code class="language-ts">interface ParsedFormField {
+  name: string;                               // fully-qualified (dotted) name
+  type: &#39;text&#39; | &#39;checkbox&#39; | &#39;radio&#39; | &#39;dropdown&#39; | &#39;listbox&#39;
+      | &#39;button&#39; | &#39;signature&#39; | &#39;unknown&#39;;
+  value: string | string[] | boolean | null;
+  readOnly: boolean;
+  required: boolean;
+  multiline: boolean;
+  options?: { export: string; label: string }[]; // choice fields
+  maxLen?: number;
+  onState?: string;                           // checkbox/radio &quot;on&quot; state name
+  widgets: { pageIndex: number; rect: [number, number, number, number] }[];
+  ref: number;                                // terminal field object number
+}
+</code></pre>
+<p>Inherited attributes (<code>/FT</code>, <code>/Ff</code>, <code>/DA</code>, <code>/Opt</code>, <code>/MaxLen</code>) are resolved up the
+<code>/Parent</code> chain, and UTF-16BE names/values are decoded.</p>
+<h2 id="fillformbytes-values-options"><code>fillForm(bytes, values, options?)</code><a class="heading-anchor" href="#fillformbytes-values-options" aria-label="Link to this section">#</a></h2>
+<p><code>values</code> maps <strong>fully-qualified field name → value</strong>:</p>
+<table>
+<thead>
+<tr>
+<th>Field type</th>
+<th>Value</th>
+</tr>
+</thead>
+<tbody><tr>
+<td>text / multiline</td>
+<td><code>string</code></td>
+</tr>
+<tr>
+<td>dropdown</td>
+<td><code>string</code> (one option&#39;s export/label)</td>
+</tr>
+<tr>
+<td>listbox</td>
+<td><code>string</code> or <code>string[]</code> (multi-select)</td>
+</tr>
+<tr>
+<td>checkbox / radio</td>
+<td><code>boolean</code>, or the export-state <code>string</code></td>
+</tr>
+</tbody></table>
+<pre><code class="language-ts">interface FillFormOptions {
+  flatten?: boolean;                          // fill then flatten in one call
+  onUnknownField?: &#39;throw&#39; | &#39;ignore&#39;;        // default &#39;throw&#39;
+  nonWinAnsi?: &#39;throw&#39; | &#39;needAppearances&#39;;   // default &#39;throw&#39;
+  password?: string;                          // for encrypted documents (see below)
+}
+</code></pre>
+<ul>
+<li>Text/choice fields get a freshly generated, <strong>self-contained</strong> Helvetica
+appearance stream (its own <code>/Resources /Helv</code>), so filling never depends on the
+document&#39;s <code>/DR</code>.</li>
+<li>Checkbox/radio set <code>/V</code> and <code>/AS</code> from the widget&#39;s <strong>own</strong> <code>/AP</code> on/off states,
+preserving the document&#39;s original look.</li>
+<li>Non-WinAnsi text (e.g. CJK) can&#39;t be drawn with the built-in Helvetica
+appearance; pass <code>nonWinAnsi: &#39;needAppearances&#39;</code> to write the value and let the
+viewer regenerate the appearance, or the call throws by default.</li>
+</ul>
+<p>Errors: <code>FormFieldNotFoundError</code>, <code>FormValueTypeError</code>, <code>FormUnsupportedError</code>.</p>
+<h2 id="flattenformbytes-options"><code>flattenForm(bytes, options?)</code><a class="heading-anchor" href="#flattenformbytes-options" aria-label="Link to this section">#</a></h2>
+<p>Stamps each widget&#39;s appearance into its page content and removes the
+interactive layer (<code>/AcroForm</code>, widget <code>/Annots</code>):</p>
+<pre><code class="language-ts">interface FlattenFormOptions {
+  force?: boolean;      // flatten even over a signed signature field
+  password?: string;    // for encrypted documents
+}
+</code></pre>
+<p>Flattening a document with a <strong>signed signature field</strong> throws by default
+(flattening is destructive to what was signed); pass <code>{ force: true }</code> to
+override.</p>
+<h2 id="encrypted--signed-documents">Encrypted &amp; signed documents<a class="heading-anchor" href="#encrypted--signed-documents" aria-label="Link to this section">#</a></h2>
+<ul>
+<li><p><strong>Encrypted documents are supported</strong> (v1.6.0): pass the password —</p>
+<pre><code class="language-ts">const filled = fillForm(encryptedPdf, { fullName: &#39;Grace Hopper&#39; }, { password: &#39;secret&#39; });
+const flat = flattenForm(filled, { password: &#39;secret&#39; });
+</code></pre>
+<p>The appended objects — field values, regenerated appearance streams,
+flatten overlays — are <strong>encrypted under the document&#39;s existing scheme</strong>
+(same <code>/Encrypt</code> dictionary, same file key; RC4, AES-128 and AES-256
+sources all work), so no plaintext ever leaks into an encrypted file and
+no downgrade or upgrade of the scheme is possible. A wrong or missing
+password throws <code>PdfPasswordError</code>. Note: the <code>/P</code> permission bits are
+<strong>not enforced</strong> — the update proceeds if the password authenticates;
+honouring the modify bit is the caller&#39;s responsibility
+(<code>openPdf(bytes, { password }).encryption.authenticatedAs</code> tells you
+which password opened the file).</p>
+</li>
+<li><p><strong>Signed documents:</strong> filling <em>non-signature</em> fields is allowed and preserves
+the signed revision byte-for-byte (incremental update only appends). Viewers
+will report &quot;document modified after signing&quot; for the added revision — expected,
+since the fill is a new, unsigned revision layered on top. Adding a <em>new</em>
+signature placeholder to an <strong>encrypted</strong> document is not supported
+(<code>addSignaturePlaceholder</code> needs a verbatim byte layout that cannot be
+transparently encrypted — it fails fast with a clear error).</p>
+</li>
+</ul>
+<h2 id="how-it-works">How it works<a class="heading-anchor" href="#how-it-works" aria-label="Link to this section">#</a></h2>
+<p>Both operations use the incremental modifier
+(<a href="architecture.html"><code>createModifier</code></a>), so the original bytes are never
+rewritten — the update is appended after the existing body with a new xref and a
+<code>/Prev</code> chain. That is why signatures on earlier revisions stay valid.</p>
+<blockquote>
+<p><strong>Searchable form text</strong> <em>(v1.7.0)</em>. The AcroForm <code>/Helv</code> font dictionary now
+carries a <code>/ToUnicode</code> CMap in every mode, so text typed into form fields is
+searchable and extractable (see the <a href="text-extraction.html">text extraction guide</a>).
+Because of that CMap, <strong>every form-carrying document changes bytes</strong> compared
+to v1.6.0 output (about 20 bytes) — a deliberate correctness fix, recorded in
+the v1.7.0 release notes. Under a PDF/A claim, a form field also raises the
+<code>PDFA_UNEMBEDDED_FORM_FONT</code> diagnostic (see the <a href="pdfa.html">PDF/A guide</a>).</p>
+</blockquote>
+<h2 id="see-also">See also<a class="heading-anchor" href="#see-also" aria-label="Link to this section">#</a></h2>
+<ul>
+<li><a href="signatures.html">Signatures</a> — CMS/PKCS#7 signing</li>
+<li><a href="pdf-manipulation.html">PDF manipulation</a> — merge/split/extract, decryption</li>
+<li><a href="accessibility.html">Accessibility</a></li>
+<li><a href="https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md" target="_blank" rel="noopener">CHANGELOG</a></li>
+</ul>
+<!-- guide:render:end -->
   </article>
 </main>
 
diff --git a/docs/guides/form-filling.md b/docs/guides/form-filling.md
index abc28ce..53ad48b 100644
--- a/docs/guides/form-filling.md
+++ b/docs/guides/form-filling.md
@@ -135,6 +135,14 @@ Both operations use the incremental modifier
 rewritten — the update is appended after the existing body with a new xref and a
 `/Prev` chain. That is why signatures on earlier revisions stay valid.
 
+> **Searchable form text** _(v1.7.0)_. The AcroForm `/Helv` font dictionary now
+> carries a `/ToUnicode` CMap in every mode, so text typed into form fields is
+> searchable and extractable (see the [text extraction guide](text-extraction.html)).
+> Because of that CMap, **every form-carrying document changes bytes** compared
+> to v1.6.0 output (about 20 bytes) — a deliberate correctness fix, recorded in
+> the v1.7.0 release notes. Under a PDF/A claim, a form field also raises the
+> `PDFA_UNEMBEDDED_FORM_FONT` diagnostic (see the [PDF/A guide](pdfa.html)).
+
 ## See also
 
 - [Signatures](signatures.html) — CMS/PKCS#7 signing
diff --git a/docs/guides/guide.css b/docs/guides/guide.css
index f9f18a0..4923df0 100644
--- a/docs/guides/guide.css
+++ b/docs/guides/guide.css
@@ -189,3 +189,89 @@
   font-weight: 400;
   color: var(--c-text-dim);
 }
+
+/* ── Pre-rendered guide enhancements (build-guides.ts + guide.js) ── */
+
+.heading-anchor {
+  margin-left: 8px;
+  font-size: 0.75em;
+  font-weight: 400;
+  color: var(--c-text-muted);
+  opacity: 0;
+  transition: opacity 0.15s;
+  text-decoration: none;
+}
+
+.guide-content h2:hover .heading-anchor,
+.guide-content h3:hover .heading-anchor,
+.guide-content h4:hover .heading-anchor,
+.heading-anchor:focus-visible {
+  opacity: 1;
+}
+
+.pre-wrap { position: relative; }
+
+.pre-wrap .copy-btn {
+  user-select: none;
+  position: absolute;
+  top: 8px;
+  right: 8px;
+  padding: 4px 10px;
+  font-size: 12px;
+  font-weight: 600;
+  border: 1px solid var(--c-border);
+  border-radius: 4px;
+  background: var(--c-surface);
+  color: var(--c-text);
+  cursor: pointer;
+  opacity: 0;
+  transition: opacity 0.15s;
+}
+
+.pre-wrap:hover .copy-btn,
+.pre-wrap .copy-btn:focus-visible {
+  opacity: 1;
+}
+
+.guide-source-bar {
+  display: flex;
+  gap: 14px;
+  align-items: center;
+  margin: 0 0 18px;
+  font-size: 13px;
+}
+
+.guide-source-btn {
+  padding: 5px 12px;
+  font-size: 13px;
+  font-weight: 600;
+  border: 1px solid var(--c-border);
+  border-radius: 6px;
+  background: var(--c-surface);
+  color: var(--c-text);
+  cursor: pointer;
+}
+
+.guide-source-btn:hover { border-color: var(--c-primary); }
+
+.guide-source-link { color: var(--c-text-dim); }
+
+/* Touch devices have no reliable :hover — the copy buttons and heading
+   anchors must be visible there, with WCAG 2.5.8-sized targets. */
+@media (hover: none), (pointer: coarse) {
+  .pre-wrap .copy-btn,
+  .heading-anchor {
+    opacity: 1;
+  }
+  .heading-anchor {
+    min-width: 24px;
+    min-height: 24px;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+  }
+}
+
+@media (max-width: 600px) {
+  .guide-shell { padding: 48px 14px; }
+}
diff --git a/docs/guides/guide.js b/docs/guides/guide.js
index d244cc8..6e9e130 100644
--- a/docs/guides/guide.js
+++ b/docs/guides/guide.js
@@ -44,8 +44,100 @@
   var container = document.getElementById('guide-content');
   if (!container) return;
 
-  var src = container.getAttribute('data-md');
-  if (!src) return;
+  // The Markdown source name is DERIVED from the page's own URL (every guide
+  // pairs name.html with name.md) — never from DOM text. CodeQL's
+  // js/xss-through-dom tracks getAttribute() values into href/fetch sinks
+  // regardless of regex guards, so the attribute is demoted to an opt-in
+  // marker: it must agree with the derived name, but the value that reaches
+  // fetch(), the source-bar href and the GitHub fallback URLs comes from
+  // location, filtered to a plain same-directory Markdown filename.
+  var page = (location.pathname.split('/').pop() || '').replace(/\.html$/, '');
+  var src = page + '.md';
+  var declared = container.getAttribute('data-md');
+  if (!declared || declared !== src || !/^[A-Za-z0-9][A-Za-z0-9_-]*\.md$/.test(src)) return;
+
+  // ── Progressive enhancements shared by both paths ─────────
+  // (pre-rendered shells and the runtime-rendered fallback)
+
+  function addCopyButtons(scope) {
+    scope.querySelectorAll('pre').forEach(function (pre) {
+      // The button lives in a positioned wrapper OUTSIDE the scrollable
+      // <pre>: as a child it would scroll away with wide code and its label
+      // would pollute manual text selection.
+      if (pre.parentNode.classList && pre.parentNode.classList.contains('pre-wrap')) return;
+      var wrap = document.createElement('div');
+      wrap.className = 'pre-wrap';
+      pre.parentNode.insertBefore(wrap, pre);
+      wrap.appendChild(pre);
+      var btn = document.createElement('button');
+      btn.className = 'copy-btn';
+      btn.type = 'button';
+      btn.textContent = 'Copy';
+      btn.addEventListener('click', function () {
+        var code = pre.querySelector('code');
+        navigator.clipboard.writeText(code ? code.textContent : pre.textContent).then(function () {
+          btn.textContent = 'Copied!';
+          setTimeout(function () { btn.textContent = 'Copy'; }, 1500);
+        }, function () { btn.textContent = 'Failed'; });
+      });
+      wrap.appendChild(btn);
+    });
+  }
+
+  function addSourceBar(scope) {
+    if (document.querySelector('.guide-source-bar')) return;
+    var bar = document.createElement('div');
+    bar.className = 'guide-source-bar';
+    var copyMd = document.createElement('button');
+    copyMd.type = 'button';
+    copyMd.className = 'guide-source-btn';
+    copyMd.textContent = 'Copy page as Markdown';
+    copyMd.addEventListener('click', function () {
+      fetch(src, { cache: 'no-cache' })
+        .then(function (r) { if (!r.ok) throw new Error('HTTP ' + r.status); return r.text(); })
+        .then(function (md) { return navigator.clipboard.writeText(md); })
+        .then(function () {
+          copyMd.textContent = 'Copied!';
+          setTimeout(function () { copyMd.textContent = 'Copy page as Markdown'; }, 1500);
+        })
+        .catch(function () { copyMd.textContent = 'Copy failed'; });
+    });
+    var view = document.createElement('a');
+    view.className = 'guide-source-link';
+    view.href = src;
+    view.textContent = 'View Markdown source';
+    bar.appendChild(copyMd);
+    bar.appendChild(view);
+    scope.parentNode.insertBefore(bar, scope);
+  }
+
+  function enhance(scope) {
+    addSourceBar(scope);
+    addCopyButtons(scope);
+    if (window.Prism && typeof window.Prism.highlightAllUnder === 'function') {
+      window.Prism.highlightAllUnder(scope);
+    }
+  }
+
+  // ── Pre-rendered path ─────────────────────────────────────
+  // build-guides.ts bakes the rendered article and its JSON-LD into the
+  // shell (rule guide-render-sync keeps it fresh). Nothing to fetch. The
+  // layout-affecting enhancements (source bar, copy buttons) run at once —
+  // deferring them behind the Prism wait used to shift the whole article
+  // down up to 2s after render. Only the highlighting waits for Prism.
+  if (container.getAttribute('data-prerendered') === 'true') {
+    addSourceBar(container);
+    addCopyButtons(container);
+    var tries = 20;
+    (function highlightWhenReady() {
+      if (window.Prism && typeof window.Prism.highlightAllUnder === 'function') {
+        window.Prism.highlightAllUnder(container);
+        return;
+      }
+      if (tries-- > 0) setTimeout(highlightWhenReady, 100);
+    })();
+    return;
+  }
 
   function showError(msg) {
     container.innerHTML = '<div class="guide-error">' +
@@ -123,10 +215,8 @@
           if (el) el.scrollIntoView();
         }
 
-        // Trigger Prism if loaded
-        if (window.Prism && typeof window.Prism.highlightAllUnder === 'function') {
-          window.Prism.highlightAllUnder(container);
-        }
+        // Copy buttons, source bar, Prism
+        enhance(container);
 
         // Update document title from first <h1>
         var h1 = container.querySelector('h1');
diff --git a/docs/guides/index.html b/docs/guides/index.html
index 506ad17..f9dcbf1 100644
--- a/docs/guides/index.html
+++ b/docs/guides/index.html
@@ -8,6 +8,7 @@
   <link rel="canonical" href="https://pdfnative.dev/guides/">
   <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/">
   <link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/">
+  <link rel="alternate" type="text/plain" href="../llms.txt" title="llms.txt — machine-readable documentation index">
   <meta property="og:type" content="website">
   <meta property="og:site_name" content="pdfnative">
   <meta property="og:locale" content="en_US">
@@ -33,7 +34,7 @@
         "inLanguage": "en",
         "@id": "https://pdfnative.dev/guides/#collection",
         "name": "pdfnative documentation guides",
-        "description": "All 28 reference guides for the pdfnative ecosystem.",
+        "description": "All 30 reference guides for the pdfnative ecosystem.",
         "url": "https://pdfnative.dev/guides/",
         "isPartOf": {
           "@type": "WebSite",
@@ -42,7 +43,7 @@
         },
         "mainEntity": {
           "@type": "ItemList",
-          "numberOfItems": 28,
+          "numberOfItems": 30,
           "itemListOrder": "https://schema.org/ItemListUnordered",
           "itemListElement": [
             {
@@ -84,132 +85,144 @@
             {
               "@type": "ListItem",
               "position": 7,
+              "name": "Choosing your surface",
+              "url": "https://pdfnative.dev/guides/choose.html"
+            },
+            {
+              "@type": "ListItem",
+              "position": 8,
               "name": "pdfnative-cli",
               "url": "https://pdfnative.dev/guides/cli.html"
             },
             {
               "@type": "ListItem",
-              "position": 8,
+              "position": 9,
               "name": "Colour-emoji font CLI",
               "url": "https://pdfnative.dev/guides/colour-emoji-cli.html"
             },
             {
               "@type": "ListItem",
-              "position": 9,
+              "position": 10,
               "name": "Colour emoji (COLRv1)",
               "url": "https://pdfnative.dev/guides/colour-emoji.html"
             },
             {
               "@type": "ListItem",
-              "position": 10,
+              "position": 11,
               "name": "Layout debugging",
               "url": "https://pdfnative.dev/guides/debugging.html"
             },
             {
               "@type": "ListItem",
-              "position": 11,
+              "position": 12,
               "name": "FAQ",
               "url": "https://pdfnative.dev/guides/faq.html"
             },
             {
               "@type": "ListItem",
-              "position": 12,
+              "position": 13,
               "name": "Font validation",
               "url": "https://pdfnative.dev/guides/font-validation.html"
             },
             {
               "@type": "ListItem",
-              "position": 13,
+              "position": 14,
               "name": "Fill and flatten AcroForms",
               "url": "https://pdfnative.dev/guides/form-filling.html"
             },
             {
               "@type": "ListItem",
-              "position": 14,
+              "position": 15,
               "name": "pdfnative-mcp",
               "url": "https://pdfnative.dev/guides/mcp.html"
             },
             {
               "@type": "ListItem",
-              "position": 15,
+              "position": 16,
               "name": "Onboarding — the pdfnative ecosystem",
               "url": "https://pdfnative.dev/guides/onboarding.html"
             },
             {
               "@type": "ListItem",
-              "position": 16,
+              "position": 17,
               "name": "Outlines and page labels",
               "url": "https://pdfnative.dev/guides/outlines.html"
             },
             {
               "@type": "ListItem",
-              "position": 17,
+              "position": 18,
               "name": "PDF manipulation — merge, split, decrypt",
               "url": "https://pdfnative.dev/guides/pdf-manipulation.html"
             },
             {
               "@type": "ListItem",
-              "position": 18,
+              "position": 19,
               "name": "PDF/A conformance",
               "url": "https://pdfnative.dev/guides/pdfa.html"
             },
             {
               "@type": "ListItem",
-              "position": 19,
+              "position": 20,
               "name": "Print production",
               "url": "https://pdfnative.dev/guides/print.html"
             },
             {
               "@type": "ListItem",
-              "position": 20,
+              "position": 21,
               "name": "Quick start — your first PDF",
               "url": "https://pdfnative.dev/guides/quickstart.html"
             },
             {
               "@type": "ListItem",
-              "position": 21,
+              "position": 22,
               "name": "pdfnative-react",
               "url": "https://pdfnative.dev/guides/react.html"
             },
             {
               "@type": "ListItem",
-              "position": 22,
+              "position": 23,
+              "name": "Self-verifying generation",
+              "url": "https://pdfnative.dev/guides/self-verify.html"
+            },
+            {
+              "@type": "ListItem",
+              "position": 24,
               "name": "Digital signatures",
               "url": "https://pdfnative.dev/guides/signatures.html"
             },
             {
               "@type": "ListItem",
-              "position": 23,
+              "position": 25,
               "name": "Long-term validation (LTV)",
               "url": "https://pdfnative.dev/guides/ltv.html"
             },
             {
               "@type": "ListItem",
-              "position": 24,
+              "position": 26,
               "name": "Streaming output",
               "url": "https://pdfnative.dev/guides/streaming.html"
             },
             {
               "@type": "ListItem",
-              "position": 25,
+              "position": 27,
               "name": "Smart tables",
               "url": "https://pdfnative.dev/guides/tables.html"
             },
             {
               "@type": "ListItem",
-              "position": 26,
+              "position": 28,
               "name": "Text extraction",
               "url": "https://pdfnative.dev/guides/text-extraction.html"
             },
             {
               "@type": "ListItem",
-              "position": 27,
+              "position": 29,
               "name": "Troubleshooting",
               "url": "https://pdfnative.dev/guides/troubleshooting.html"
             },
             {
               "@type": "ListItem",
-              "position": 28,
+              "position": 30,
               "name": "Viewer preferences",
               "url": "https://pdfnative.dev/guides/viewer-preferences.html"
             }
@@ -285,6 +298,10 @@ <h1>Documentation Guides</h1>
         <a href="onboarding.html">Onboarding →</a>
         <span class="guide-toc-desc">90-second start for the full ecosystem — the library, pdfnative-cli, pdfnative-mcp, and pdfnative-react. Install + first call for each.</span>
       </li>
+      <li>
+        <a href="choose.html">Choosing your surface →</a>
+        <span class="guide-toc-desc">Library, CLI, MCP or React? The decision tree in prose plus a verified capability × surface matrix — every export, command and tool name checked against the sources, with an honest em-dash where a surface lacks a capability. Machine-readable twin in <code>docs/data/surfaces.json</code>.</span>
+      </li>
       <li>
         <a href="quickstart.html">Quick Start →</a>
         <span class="guide-toc-desc">Install pdfnative and generate your first PDF in Node.js or the browser in under a minute.</span>
@@ -315,7 +332,7 @@ <h1>Documentation Guides</h1>
       </li>
       <li>
         <a href="pdfa.html">PDF/A conformance →</a>
-        <span class="guide-toc-desc">PDF/A-1b, 2b, 2u, 3b — validated against the veraPDF reference validator in CI on every commit.</span>
+        <span class="guide-toc-desc">PDF/A-1b, 2b, 2u, 3b — validated against the veraPDF reference validator in CI on every commit. v1.7.0 adds declaration guards: <code>strict</code>, <code>onDiagnostic</code>, and the <code>PDFA_*</code> diagnostic codes for configurations that would break the claimed level.</span>
       </li>
       <li>
         <a href="print.html">Print production →</a>
@@ -323,7 +340,7 @@ <h1>Documentation Guides</h1>
       </li>
       <li>
         <a href="signatures.html">Digital signatures →</a>
-        <span class="guide-toc-desc">CMS/PKCS#7 detached signatures — RSA + ECDSA P-256, one-call <code>addSignaturePlaceholder()</code> workflow, Adobe Reader / openssl-cms validation.</span>
+        <span class="guide-toc-desc">CMS/PKCS#7 detached signatures — RSA SHA-256/384/512 + ECDSA P-256, one-call <code>addSignaturePlaceholder()</code> workflow, Adobe Reader / openssl-cms validation. v1.7.0 adds the PAdES baseline profile (<code>profile: 'pades'</code>), multiple signatures (<code>allowMultiple</code> + <code>fieldName</code>), <code>listSignatures()</code>, and the <a href="ltv.html">LTV ladder</a> to B-LTA.</span>
       </li>
       <li>
         <a href="ltv.html">Long-term validation (LTV) →</a>
@@ -335,11 +352,11 @@ <h1>Documentation Guides</h1>
       </li>
       <li>
         <a href="colour-emoji.html">Colour emoji →</a>
-        <span class="guide-toc-desc">v1.3.0 COLRv1 colour emoji — opt-in Noto Color Emoji subset, solid + linear + radial gradient layers rendered as native PDF Form XObjects. Monochrome fallback when not registered.</span>
+        <span class="guide-toc-desc">v1.3.0 COLRv1 colour emoji — opt-in Noto Color Emoji subset, solid + linear + radial gradient layers (plus v1.4.0 sweep gradients and blend modes) rendered as native PDF Form XObjects. v1.7.0 adds 73 flag &amp; ZWJ sequences (51 flags + 22 ZWJ) resolved as single colour ligature glyphs. Monochrome fallback when not registered.</span>
       </li>
       <li>
         <a href="colour-emoji-cli.html">Colour-emoji font CLI →</a>
-        <span class="guide-toc-desc">v1.4.0 <code>pdfnative-build-emoji-font</code> — bundled CLI that generates a colour-emoji data module with exactly the glyphs you need, from a few codepoints to the full ~3,600-glyph set. <code>--download</code> + checksum, <code>--ttf</code>, <code>--all</code>, <code>--ranges</code>.</span>
+        <span class="guide-toc-desc">v1.4.0 <code>pdfnative-build-emoji-font</code> — bundled CLI that generates a colour-emoji data module with exactly the glyphs you need, from a few codepoints to the full ~3,600-glyph set. <code>--download</code> + checksum, <code>--ttf</code>, <code>--all</code>, <code>--ranges</code>, and v1.7.0 <code>--sequences flags|zwj|all|none</code> / <code>--sequence-list</code> for flag &amp; ZWJ ligatures.</span>
       </li>
       <li>
         <a href="streaming.html">Streaming output →</a>
@@ -359,7 +376,7 @@ <h1>Documentation Guides</h1>
       </li>
       <li>
         <a href="charts.html">Charts (native vector) →</a>
-        <span class="guide-toc-desc">v1.6.0 bar, horizontal-bar, line, pie, and donut <code>chart</code> blocks rendered as pure PDF path operators — zero dependencies, multi-series, "nice" axis ticks, negative values, tagged <code>/Figure</code> + alt text, PDF/A-safe.</span>
+        <span class="guide-toc-desc">Nine <code>chart</code> kinds rendered as pure PDF path operators — bar, horizontal-bar, line, pie, donut (v1.6.0), plus stacked bars, area, and scatter with a secondary axis, log &amp; time scales, and data labels (charts v2, v1.7.0). Zero dependencies, multi-series, negative values, tagged <code>/Figure</code> + alt text, PDF/A-safe.</span>
       </li>
       <li>
         <a href="text-extraction.html">Text extraction →</a>
@@ -377,13 +394,17 @@ <h1>Documentation Guides</h1>
         <a href="debugging.html">Layout debugging →</a>
         <span class="guide-toc-desc">v1.5.0 opt-in visual overlay (<code>layout: { debug: true }</code>) drawing margin / content / cell boxes, plus <code>inspectDocumentLayout()</code> for programmatic per-page block geometry. Byte-identical when off.</span>
       </li>
+      <li>
+        <a href="self-verify.html">Self-verifying generation →</a>
+        <span class="guide-toc-desc">The generate → inspect → assert → correct loop as a first-class pattern: plan with <code>inspectDocumentLayout()</code>, then verify the emitted bytes with <code>extractText()</code>, <code>validatePdfUA()</code> and <code>listSignatures()</code> / <code>openPdf()</code> — and the same loop via CLI <code>inspect --check</code> exit codes and the MCP <code>inspect_pdf</code> assertions, ready for CI and agent loops.</span>
+      </li>
       <li>
         <a href="annotations.html">Annotations →</a>
         <span class="guide-toc-desc">v1.5.0 typed markup annotations — text, highlight, underline, strikeout, squiggly, square, circle, line, freetext — with <code>buildAnnotation()</code>, <code>getAnnotations()</code> to read existing PDFs, and <code>addAnnotation()</code> incremental write.</span>
       </li>
       <li>
         <a href="mcp.html">MCP Integration →</a>
-        <span class="guide-toc-desc">Use pdfnative from Claude Desktop, Cursor, Continue, and Zed via pdfnative-mcp — 24 tools (incl. page-tree <code>merge_pdfs</code>, <code>split_pdf</code>, <code>extract_pages</code>, markup <code>annotate_pdf</code>, the network-free <code>draft_governance_issue</code>, plus <code>validate_pdf</code>, <code>verify_pdf</code>, <code>extract_attachments</code>), <code>pdfA</code> flag, multi-script <code>lang</code>, and a signed-document workflow.</span>
+        <span class="guide-toc-desc">Use pdfnative from Claude Desktop, Cursor, Continue, and Zed via pdfnative-mcp — 28 tools (incl. the PAdES ladder <code>sign_pdf</code> / <code>add_ltv</code> / <code>timestamp_pdf</code>, <code>update_metadata</code>, the read-only <code>inspect_layout</code> preview, page-tree <code>merge_pdfs</code> / <code>split_pdf</code> / <code>extract_pages</code>, markup <code>annotate_pdf</code>, the network-free <code>draft_governance_issue</code>), <code>pdfA</code> flag, multi-script <code>lang</code>, and a signed-document workflow.</span>
       </li>
       <li>
         <a href="cli.html">CLI →</a>
@@ -430,7 +451,7 @@ <h2>Interactive playgrounds</h2>
       </li>
       <li>
         <a href="../playgrounds/mcp.html">MCP tool explorer →</a>
-        <span class="guide-toc-desc">Browse the pdfnative-mcp toolset (24 tools), copy a ready-to-paste config snippet for Claude / Cursor / Continue / Zed, and generate the same PDFs an AI assistant would receive — all in your browser.</span>
+        <span class="guide-toc-desc">Browse the pdfnative-mcp toolset (28 tools), copy a ready-to-paste config snippet for Claude / Cursor / Continue / Zed, and generate the same PDFs an AI assistant would receive — all in your browser.</span>
       </li>
       <li>
         <a href="../playgrounds/react.html">React renderer →</a>
diff --git a/docs/guides/ltv.html b/docs/guides/ltv.html
index 2824f78..d307f10 100644
--- a/docs/guides/ltv.html
+++ b/docs/guides/ltv.html
@@ -9,6 +9,7 @@
   <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/ltv.html">
   <link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/ltv.html">
   <link rel="alternate" type="text/markdown" href="ltv.md">
+  <link rel="alternate" type="text/plain" href="../llms.txt" title="llms.txt — machine-readable documentation index">
   <meta property="og:type" content="article">
   <meta property="og:site_name" content="pdfnative">
   <meta property="og:locale" content="en_US">
@@ -26,6 +27,9 @@
   <link rel="stylesheet" href="../style.css">
   <link rel="stylesheet" href="guide.css">
   <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
+  <!-- guide:ld:start -->
+  <script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://pdfnative.dev/"},{"@type":"ListItem","position":2,"name":"Guides","item":"https://pdfnative.dev/guides/"},{"@type":"ListItem","position":3,"name":"Long-term validation (LTV) — PAdES B-B to B-LTA","item":"https://pdfnative.dev/guides/ltv.html"}]},{"@type":"TechArticle","headline":"Long-term validation (LTV) — PAdES B-B to B-LTA","description":"PAdES B-B to B-LTA in pdfnative — RFC 3161 signature timestamps, /DSS + /VRI validation material, document timestamps, injected providers, zero network in the engine.","inLanguage":"en","author":{"@type":"Organization","name":"Nizoka","url":"https://github.com/Nizoka"},"publisher":{"@type":"Organization","name":"pdfnative","url":"https://pdfnative.dev","logo":{"@type":"ImageObject","url":"https://pdfnative.dev/assets/logo.svg"}},"mainEntityOfPage":{"@type":"WebPage","@id":"https://pdfnative.dev/guides/ltv.html"},"isPartOf":{"@type":"WebSite","name":"pdfnative","url":"https://pdfnative.dev"}}]}</script>
+  <!-- guide:ld:end -->
 </head>
 <body>
 
@@ -57,9 +61,150 @@
 
 <main class="guide-shell" id="main-content" tabindex="-1">
   <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; Long-term validation</p>
-  <article id="guide-content" class="guide-content" data-md="ltv.md">
-    <p class="guide-loading">Loading…</p>
-    <noscript><p>This guide is written in Markdown: <a href="ltv.md">read ltv.md</a>.</p></noscript>
+  <article id="guide-content" class="guide-content" data-md="ltv.md" data-prerendered="true">
+<!-- guide:render:start -->
+<h1 id="long-term-validation-ltv--pades-b-b-to-b-lta">Long-term validation (LTV) — PAdES B-B to B-LTA</h1>
+<blockquote>
+<p><strong>New in v1.7.0.</strong> pdfnative signs PDFs that stay verifiable for decades: PAdES baseline signatures (ETSI EN 319 142-1), RFC 3161 signature timestamps, embedded revocation material (<code>/DSS</code> + <code>/VRI</code>), and document timestamps — all with <strong>zero runtime dependencies</strong> and <strong>zero network access in the engine</strong>. Transport is injected by your code.</p>
+</blockquote>
+<h2 id="tldr">TL;DR<a class="heading-anchor" href="#tldr" aria-label="Link to this section">#</a></h2>
+<pre><code class="language-ts">import {
+  buildDocumentPDFBytes, addSignaturePlaceholder, estimateContentsSize,
+  signPdfBytesWithTimestamp, addValidationInfo, addDocumentTimestamp,
+  setTimestampProvider, setRevocationProvider,
+} from &#39;pdfnative&#39;;
+
+// 1. Your transports (the engine never fetches on its own).
+setTimestampProvider({
+  async getTimestamp(request) {           // DER TimeStampReq in…
+    const res = await fetch(&#39;https://freetsa.org/tsr&#39;, {
+      method: &#39;POST&#39;,
+      headers: { &#39;Content-Type&#39;: &#39;application/timestamp-query&#39; },
+      body: request.slice(),
+    });
+    return new Uint8Array(await res.arrayBuffer());  // …DER TimeStampResp out
+  },
+});
+setRevocationProvider({
+  async fetchOcsp(url, request) {
+    const res = await fetch(url, {
+      method: &#39;POST&#39;,
+      headers: { &#39;Content-Type&#39;: &#39;application/ocsp-request&#39; },
+      body: request.slice(),
+    });
+    return new Uint8Array(await res.arrayBuffer());
+  },
+  async fetchCrl(url) {
+    const res = await fetch(url);
+    return new Uint8Array(await res.arrayBuffer());
+  },
+});
+
+// 2. Build → placeholder → sign+timestamp → embed validation → archive.
+const unsigned = addSignaturePlaceholder(buildDocumentPDFBytes(params), {
+  metadata: { subFilter: &#39;ETSI.CAdES.detached&#39;, reason: &#39;Contract v2&#39; },
+  placeholderBytes: estimateContentsSize([certDer.length], &#39;rsa-sha256&#39;, { timestamp: true }),
+});
+const signed  = await signPdfBytesWithTimestamp(unsigned, {
+  signerCert, certChain: [intermediateCert], rsaKey,
+  profile: &#39;pades&#39;,                       // ESS signing-certificate-v2, no CMS signing-time
+});
+const ltv     = await addValidationInfo(signed);       // /DSS + /VRI (B-LT)
+const archive = await addDocumentTimestamp(ltv);       // DocTimeStamp (B-LTA)
+</code></pre>
+<p>Every step appends a non-destructive incremental revision — earlier bytes are never modified, so prior signatures stay intact.</p>
+<h2 id="why-ltv">Why LTV<a class="heading-anchor" href="#why-ltv" aria-label="Link to this section">#</a></h2>
+<p>A plain signature proves <em>who</em> signed, but its verifiability decays: certificates expire, CAs go offline, revocation servers disappear. The PAdES baseline levels fix each failure mode in turn:</p>
+<table>
+<thead>
+<tr>
+<th>Level</th>
+<th>Adds</th>
+<th>Protects against</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><strong>B-B</strong></td>
+<td>CAdES signature with the ESS <code>signing-certificate-v2</code> attribute</td>
+<td>Certificate substitution</td>
+</tr>
+<tr>
+<td><strong>B-T</strong></td>
+<td>RFC 3161 signature timestamp (<code>id-aa-signatureTimeStampToken</code>)</td>
+<td>&quot;Was the signature made while the certificate was valid?&quot;</td>
+</tr>
+<tr>
+<td><strong>B-LT</strong></td>
+<td><code>/DSS</code>: embedded certificates + OCSP/CRL responses, per-signature <code>/VRI</code></td>
+<td>Revocation servers disappearing</td>
+</tr>
+<tr>
+<td><strong>B-LTA</strong></td>
+<td><code>/DocTimeStamp</code> covering the whole document</td>
+<td>Algorithm/key aging — re-timestamp before the TSA certificate expires to extend the chain</td>
+</tr>
+</tbody></table>
+<p>Adobe Reader shows a B-LT/B-LTA document as <strong>&quot;LTV enabled&quot;</strong> (with the chain&#39;s root trusted).</p>
+<h2 id="the-provider-architecture">The provider architecture<a class="heading-anchor" href="#the-provider-architecture" aria-label="Link to this section">#</a></h2>
+<p>pdfnative <strong>never opens a socket</strong>. Two small interfaces move bytes; you own transport, proxies, retries and trust decisions:</p>
+<pre><code class="language-ts">interface TimestampProvider {
+  getTimestamp(request: Uint8Array): Promise&lt;Uint8Array&gt;;   // TimeStampReq → TimeStampResp
+}
+interface RevocationProvider {
+  fetchOcsp?(url: string, request: Uint8Array): Promise&lt;Uint8Array&gt;; // OCSPRequest → OCSPResponse
+  fetchCrl?(url: string): Promise&lt;Uint8Array&gt;;                      // → CertificateList
+}
+</code></pre>
+<p>Install globally (<code>setTimestampProvider</code> / <code>setRevocationProvider</code>) or pass per call (<code>timestampProvider:</code> / <code>revocationProvider:</code> options — per-call wins). pdfnative builds and parses every RFC 3161 / RFC 6960 / RFC 5280 structure itself, verifies the token&#39;s message imprint and nonce echo, and <strong>refuses to embed</strong> a rejected or tampered response.</p>
+<h2 id="step-by-step">Step by step<a class="heading-anchor" href="#step-by-step" aria-label="Link to this section">#</a></h2>
+<h3 id="b-b--a-pades-baseline-signature">B-B — a PAdES baseline signature<a class="heading-anchor" href="#b-b--a-pades-baseline-signature" aria-label="Link to this section">#</a></h3>
+<pre><code class="language-ts">const signed = signPdfBytes(placeheld, {
+  signerCert, certChain, rsaKey,
+  profile: &#39;pades&#39;,          // adds ESS signing-certificate-v2 (RFC 5035)
+});
+</code></pre>
+<p>Pair <code>profile: &#39;pades&#39;</code> with the placeholder&#39;s <code>metadata: { subFilter: &#39;ETSI.CAdES.detached&#39; }</code> so the <code>/Sig</code> dictionary declares the PAdES SubFilter. The legacy default (<code>adbe.pkcs7.detached</code>, <code>profile: &#39;pkcs7&#39;</code>) is unchanged. <code>digestAlgorithm: &#39;sha384&#39; | &#39;sha512&#39;</code> upgrades the whole CMS digest chain.</p>
+<h3 id="b-t--the-signature-timestamp">B-T — the signature timestamp<a class="heading-anchor" href="#b-t--the-signature-timestamp" aria-label="Link to this section">#</a></h3>
+<p><code>signPdfBytesWithTimestamp</code> (async) signs, hashes the CMS signature value, asks your <code>TimestampProvider</code> for a token, verifies it, and attaches it as an unsigned attribute — the signed bytes are untouched, so the signature stays valid. Reserve room for the token when creating the placeholder:</p>
+<pre><code class="language-ts">placeholderBytes: estimateContentsSize(certSizes, &#39;rsa-sha256&#39;, { timestamp: true })  // +8 KiB
+</code></pre>
+<h3 id="b-lt--the-document-security-store">B-LT — the Document Security Store<a class="heading-anchor" href="#b-lt--the-document-security-store" aria-label="Link to this section">#</a></h3>
+<pre><code class="language-ts">const data = await collectValidationInfo(signed);   // async: chains + OCSP/CRL via provider
+const ltv  = embedValidationInfo(signed, data);     // sync, offline, deterministic
+// …or in one call: await addValidationInfo(signed)
+</code></pre>
+<p><code>collectValidationInfo</code> walks every signed signature (and the TSA certificates inside embedded timestamp tokens), deduplicates the certificate pool, and requests OCSP (preferred) or CRL data for every certificate that advertises a source via its AIA / CRL-distribution-point extensions — skipping self-signed roots and <code>id-pkix-ocsp-nocheck</code> responders. Missing intermediates can be supplied with <code>extraCertificates</code>.</p>
+<p><code>embedValidationInfo</code> writes the <code>/DSS</code> dictionary — <code>/Certs</code>, <code>/OCSPs</code>, <code>/CRLs</code> stream arrays plus a <code>/VRI</code> entry per signature keyed by the uppercase-hex SHA-1 of its full <code>/Contents</code> value (the Adobe convention; <code>vriKeyForContents</code> exposes the computation). An existing <code>/DSS</code> is merged, never replaced. The split matters: collect once online, embed deterministically offline (or in tests).</p>
+<h3 id="b-lta--the-document-timestamp">B-LTA — the document timestamp<a class="heading-anchor" href="#b-lta--the-document-timestamp" aria-label="Link to this section">#</a></h3>
+<pre><code class="language-ts">const archive = await addDocumentTimestamp(ltv);
+</code></pre>
+<p>Appends a signature field whose dictionary is <code>/Type /DocTimeStamp /SubFilter /ETSI.RFC3161</code> with a <strong>bare</strong> TimeStampToken as <code>/Contents</code> (ISO 32000-2 §12.8.5 — no <code>/M</code>: the token&#39;s genTime is the time assertion). Field names auto-suffix (<code>DocTimeStamp1</code>, <code>DocTimeStamp2</code>, …) so periodic re-timestamping chains naturally.</p>
+<h2 id="multiple-signatures">Multiple signatures<a class="heading-anchor" href="#multiple-signatures" aria-label="Link to this section">#</a></h2>
+<pre><code class="language-ts">const a = signPdfBytes(addSignaturePlaceholder(pdf, { fieldName: &#39;Author&#39; }), opts);
+const b = signPdfBytes(
+  addSignaturePlaceholder(a, { fieldName: &#39;Reviewer&#39;, allowMultiple: true }),
+  { ...opts, fieldName: &#39;Reviewer&#39; },
+);
+</code></pre>
+<p><code>allowMultiple: true</code> opts out of the historical one-signature short-circuit; the <code>fieldName</code> selector on <code>signPdfBytes</code> targets the right placeholder. Signed signatures are located by their real ByteRange values and can never be overwritten. Inspect any document with <code>listSignatures(bytes)</code>.</p>
+<h2 id="testing-without-a-real-tsa-or-ca">Testing without a real TSA or CA<a class="heading-anchor" href="#testing-without-a-real-tsa-or-ca" aria-label="Link to this section">#</a></h2>
+<p>The repository ships a deterministic offline mock PKI (<code>scripts/helpers/mock-pki.ts</code>): a root CA, a signer with AIA/CRL-DP extensions, a TSA with the critical <code>id-kp-timeStamping</code> EKU and an OCSP responder with <code>ocsp-nocheck</code> — plus providers that produce <strong>real, signed</strong> TimeStampTokens, BasicOCSPResponses and CRLs. The <code>signature/signature-pades-*.pdf</code> samples and the <code>ltv-pipeline</code> integration suite run the full B-LTA chain with zero network. Public TSAs for manual testing include <code>https://freetsa.org/tsr</code>.</p>
+<h2 id="verification-checklist">Verification checklist<a class="heading-anchor" href="#verification-checklist" aria-label="Link to this section">#</a></h2>
+<ul>
+<li><code>listSignatures(bytes)</code> — every entry, its SubFilter, ByteRange, placeholder/timestamp status.</li>
+<li>Adobe Reader: <em>Signature Panel → Certificate Details</em> — trust the mock/company root, then look for <strong>&quot;LTV enabled&quot;</strong> on B-LT documents and a valid document timestamp on B-LTA.</li>
+<li><code>openssl ts -reply -in token.der -text</code> inspects extracted timestamp tokens.</li>
+<li>pdfnative itself ships <strong>no signature verifier</strong> — validation belongs to dedicated tooling (veraPDF for PDF/A, Adobe/DSS for signatures, <code>pdfnative-cli verify</code> for full cryptographic verification: CMS signature values, certificate chain and trust, RFC 3161 timestamps, OCSP/CRL revocation).</li>
+</ul>
+<h2 id="limits--scope-v170">Limits &amp; scope (v1.7.0)<a class="heading-anchor" href="#limits--scope-v170" aria-label="Link to this section">#</a></h2>
+<ul>
+<li>ECDSA stays P-256 with SHA-256; RSA supports SHA-256/384/512.</li>
+<li>Chain building uses exact issuer-name matching over the embedded pool; cross-certification and bridge PKIs are out of scope.</li>
+<li><code>collectValidationInfo</code> fetches from the <strong>first</strong> advertised OCSP/CRL URL; provider-side failover is your transport&#39;s business.</li>
+<li>Encrypted documents cannot take signature placeholders (unchanged from v1.2).</li>
+<li>PDF 2.0 <code>/Extensions</code> declarations are not emitted; the ISO 32000-2 constructs used here are accepted by all mainstream validators.</li>
+</ul>
+<!-- guide:render:end -->
   </article>
 </main>
 
diff --git a/docs/guides/ltv.md b/docs/guides/ltv.md
index 1aff024..aff3a21 100644
--- a/docs/guides/ltv.md
+++ b/docs/guides/ltv.md
@@ -143,7 +143,7 @@ The repository ships a deterministic offline mock PKI (`scripts/helpers/mock-pki
 - `listSignatures(bytes)` — every entry, its SubFilter, ByteRange, placeholder/timestamp status.
 - Adobe Reader: *Signature Panel → Certificate Details* — trust the mock/company root, then look for **"LTV enabled"** on B-LT documents and a valid document timestamp on B-LTA.
 - `openssl ts -reply -in token.der -text` inspects extracted timestamp tokens.
-- pdfnative itself ships **no signature verifier** — validation belongs to dedicated tooling (veraPDF for PDF/A, Adobe/DSS for signatures, `pdfnative-cli verify` for structural checks).
+- pdfnative itself ships **no signature verifier** — validation belongs to dedicated tooling (veraPDF for PDF/A, Adobe/DSS for signatures, `pdfnative-cli verify` for full cryptographic verification: CMS signature values, certificate chain and trust, RFC 3161 timestamps, OCSP/CRL revocation).
 
 ## Limits & scope (v1.7.0)
 
diff --git a/docs/guides/mcp.html b/docs/guides/mcp.html
index 394ec72..a738f99 100644
--- a/docs/guides/mcp.html
+++ b/docs/guides/mcp.html
@@ -4,29 +4,33 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>pdfnative-mcp — MCP Integration Guide</title>
-  <meta name="description" content="Use pdfnative from any AI client (Claude, Cursor, Continue, Zed) via pdfnative-mcp — 24 MCP tools: render, sign, validate, verify, attach, extract, merge, split, and extract pages.">
+  <meta name="description" content="Use pdfnative from any AI client (Claude, Cursor, Continue, Zed) via pdfnative-mcp — 28 MCP tools: render, sign with the full PAdES ladder (LTV, timestamps), validate, verify, attach, extract, merge, split, extract pages, update metadata, and preview pagination.">
   <meta name="robots" content="index, follow">
   <link rel="canonical" href="https://pdfnative.dev/guides/mcp.html">
   <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/mcp.html">
   <link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/mcp.html">
   <link rel="alternate" type="text/markdown" href="mcp.md">
+  <link rel="alternate" type="text/plain" href="../llms.txt" title="llms.txt — machine-readable documentation index">
   <meta property="og:type" content="article">
   <meta property="og:site_name" content="pdfnative">
   <meta property="og:locale" content="en_US">
   <meta property="og:url" content="https://pdfnative.dev/guides/mcp.html">
   <meta property="og:title" content="pdfnative-mcp — MCP Integration Guide">
-  <meta property="og:description" content="Use pdfnative from any AI client (Claude, Cursor, Continue, Zed) via pdfnative-mcp — 24 MCP tools: render, sign, validate, verify, attach, extract, merge, split, and extract pages.">
+  <meta property="og:description" content="Use pdfnative from any AI client (Claude, Cursor, Continue, Zed) via pdfnative-mcp — 28 MCP tools: render, sign with the full PAdES ladder (LTV, timestamps), validate, verify, attach, extract, merge, split, extract pages, update metadata, and preview pagination.">
   <meta property="og:image" content="https://pdfnative.dev/assets/og-image.png">
   <meta property="og:image:width" content="1200">
   <meta property="og:image:height" content="630">
   <meta name="twitter:card" content="summary_large_image">
   <meta name="twitter:title" content="pdfnative-mcp — MCP Integration Guide">
-  <meta name="twitter:description" content="Use pdfnative from Claude Desktop, Cursor, Continue, and Zed — 24 MCP tools, pdfA flag, multi-script lang, per-tool apiVersion.">
+  <meta name="twitter:description" content="Use pdfnative from Claude Desktop, Cursor, Continue, and Zed — 28 MCP tools, PAdES LTV ladder, pdfA flag, multi-script lang, MCP 2026-07-28.">
   <meta name="twitter:image" content="https://pdfnative.dev/assets/og-image.png">
   <link rel="icon" type="image/svg+xml" href="../favicon.svg">
   <link rel="stylesheet" href="../style.css">
   <link rel="stylesheet" href="guide.css">
   <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
+  <!-- guide:ld:start -->
+  <script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://pdfnative.dev/"},{"@type":"ListItem","position":2,"name":"Guides","item":"https://pdfnative.dev/guides/"},{"@type":"ListItem","position":3,"name":"pdfnative-mcp — AI Client Integration Guide","item":"https://pdfnative.dev/guides/mcp.html"}]},{"@type":"TechArticle","headline":"pdfnative-mcp — AI Client Integration Guide","description":"Use pdfnative from any AI client (Claude, Cursor, Continue, Zed) via pdfnative-mcp — 28 MCP tools: render, sign with the full PAdES ladder (LTV, timestamps), validate, verify, attach, extract, merge, split, extract pages, update metadata, and preview pagination.","inLanguage":"en","author":{"@type":"Organization","name":"Nizoka","url":"https://github.com/Nizoka"},"publisher":{"@type":"Organization","name":"pdfnative","url":"https://pdfnative.dev","logo":{"@type":"ImageObject","url":"https://pdfnative.dev/assets/logo.svg"}},"mainEntityOfPage":{"@type":"WebPage","@id":"https://pdfnative.dev/guides/mcp.html"},"isPartOf":{"@type":"WebSite","name":"pdfnative","url":"https://pdfnative.dev"}}]}</script>
+  <!-- guide:ld:end -->
 </head>
 <body>
 
@@ -58,9 +62,1007 @@
 
 <main class="guide-shell" id="main-content" tabindex="-1">
   <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; MCP Integration</p>
-  <article id="guide-content" class="guide-content" data-md="mcp.md">
-    <p class="guide-loading">Loading…</p>
-    <noscript><p>This guide is written in Markdown: <a href="mcp.md">read mcp.md</a>.</p></noscript>
+  <article id="guide-content" class="guide-content" data-md="mcp.md" data-prerendered="true">
+<!-- guide:render:start -->
+<h1 id="pdfnative-mcp--ai-client-integration-guide">pdfnative-mcp — AI Client Integration Guide</h1>
+<blockquote>
+<p><strong>Tracks the latest published <code>pdfnative-mcp</code></strong> (v1.6.0, built on pdfnative 1.7.0). Full release notes: <a href="https://github.com/Nizoka/pdfnative-mcp/releases" target="_blank" rel="noopener">pdfnative-mcp releases</a>. Live package versions — and the <code>pdfnative</code> version each one is built on — are shown at the top of the <a href="../index.html">documentation home</a>.</p>
+</blockquote>
+<p><a href="https://github.com/Nizoka/pdfnative-mcp" target="_blank" rel="noopener">pdfnative-mcp</a> is an <strong>MCP server</strong> that exposes the full pdfnative library to any AI client supporting the <a href="https://modelcontextprotocol.io" target="_blank" rel="noopener">Model Context Protocol</a> — Claude Desktop, Cursor, Continue, Zed, ChatGPT, and more.</p>
+<blockquote>
+<p><strong>What is MCP?</strong> The Model Context Protocol is an open standard (originally developed by Anthropic) that lets AI assistants call external tools in a structured, safe way. An MCP server declares a set of tools with typed inputs and outputs; the AI client invokes those tools on your behalf during a conversation.</p>
+</blockquote>
+<p>With <code>pdfnative-mcp</code> installed, you can say to your AI assistant:</p>
+<blockquote>
+<p><em>&quot;Generate a Q1 2026 financial report as PDF/A-2b with a QR code pointing to our dashboard, then inspect the result to confirm it&#39;s archive-grade.&quot;</em></p>
+</blockquote>
+<p>…and the AI will call the right combination of <code>generate_basic_pdf</code>, <code>add_barcode</code>, <code>add_table</code>, and <code>inspect_pdf</code> tools, returning a ready-to-download PDF.</p>
+<hr>
+<h2 id="installation">Installation<a class="heading-anchor" href="#installation" aria-label="Link to this section">#</a></h2>
+<pre><code class="language-bash"># Run directly with npx — no global install required (recommended)
+npx -y pdfnative-mcp
+
+# Or install globally
+npm install -g pdfnative-mcp
+pdfnative-mcp
+</code></pre>
+<p><strong>Requirements:</strong> Node.js ≥ 22.</p>
+<hr>
+<h2 id="configuration-by-client">Configuration by client<a class="heading-anchor" href="#configuration-by-client" aria-label="Link to this section">#</a></h2>
+<h3 id="claude-desktop">Claude Desktop<a class="heading-anchor" href="#claude-desktop" aria-label="Link to this section">#</a></h3>
+<p>Edit the config file for your OS:</p>
+<ul>
+<li><strong>macOS:</strong> <code>~/Library/Application Support/Claude/claude_desktop_config.json</code></li>
+<li><strong>Windows:</strong> <code>%APPDATA%\Claude\claude_desktop_config.json</code></li>
+</ul>
+<pre><code class="language-json">{
+  &quot;mcpServers&quot;: {
+    &quot;pdfnative&quot;: {
+      &quot;command&quot;: &quot;npx&quot;,
+      &quot;args&quot;: [&quot;-y&quot;, &quot;pdfnative-mcp&quot;],
+      &quot;env&quot;: {
+        &quot;PDFNATIVE_MCP_OUTPUT_DIR&quot;: &quot;/Users/you/Documents/mcp-pdfs&quot;
+      }
+    }
+  }
+}
+</code></pre>
+<p>Restart Claude Desktop after saving. The <code>pdfnative</code> server will appear in the tools panel.</p>
+<h3 id="cursor">Cursor<a class="heading-anchor" href="#cursor" aria-label="Link to this section">#</a></h3>
+<p>In your project <code>.cursor/mcp.json</code> (or global <code>~/.cursor/mcp.json</code>):</p>
+<pre><code class="language-json">{
+  &quot;mcpServers&quot;: {
+    &quot;pdfnative&quot;: {
+      &quot;command&quot;: &quot;npx&quot;,
+      &quot;args&quot;: [&quot;-y&quot;, &quot;pdfnative-mcp&quot;],
+      &quot;env&quot;: {
+        &quot;PDFNATIVE_MCP_OUTPUT_DIR&quot;: &quot;/path/to/pdf-output&quot;
+      }
+    }
+  }
+}
+</code></pre>
+<h3 id="continue">Continue<a class="heading-anchor" href="#continue" aria-label="Link to this section">#</a></h3>
+<p>In your <code>~/.continue/config.json</code>:</p>
+<pre><code class="language-json">{
+  &quot;mcpServers&quot;: [
+    {
+      &quot;name&quot;: &quot;pdfnative&quot;,
+      &quot;command&quot;: &quot;npx&quot;,
+      &quot;args&quot;: [&quot;-y&quot;, &quot;pdfnative-mcp&quot;],
+      &quot;env&quot;: {
+        &quot;PDFNATIVE_MCP_OUTPUT_DIR&quot;: &quot;/path/to/pdf-output&quot;
+      }
+    }
+  ]
+}
+</code></pre>
+<h3 id="zed">Zed<a class="heading-anchor" href="#zed" aria-label="Link to this section">#</a></h3>
+<p>In your Zed <code>settings.json</code>:</p>
+<pre><code class="language-json">{
+  &quot;context_servers&quot;: {
+    &quot;pdfnative&quot;: {
+      &quot;command&quot;: {
+        &quot;path&quot;: &quot;npx&quot;,
+        &quot;args&quot;: [&quot;-y&quot;, &quot;pdfnative-mcp&quot;],
+        &quot;env&quot;: {
+          &quot;PDFNATIVE_MCP_OUTPUT_DIR&quot;: &quot;/path/to/pdf-output&quot;
+        }
+      }
+    }
+  }
+}
+</code></pre>
+<hr>
+<h2 id="environment-variables">Environment variables<a class="heading-anchor" href="#environment-variables" aria-label="Link to this section">#</a></h2>
+<table>
+<thead>
+<tr>
+<th>Variable</th>
+<th>Purpose</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>PDFNATIVE_MCP_OUTPUT_DIR</code></td>
+<td>Absolute path to the sandbox directory. <strong>Required to enable <code>outputMode: &quot;file&quot;</code></strong>. When unset, only <code>base64</code> output is available. (The misspelt <code>PDFNATIVE_MPC_OUTPUT_DIR</code> still works as a deprecated alias.)</td>
+</tr>
+<tr>
+<td><code>PDFNATIVE_MCP_CACHE_DIR</code></td>
+<td>Absolute path to enable the persistent SHA-256-keyed result cache (1 h TTL, 256 MiB LRU). When unset, the cache is disabled.</td>
+</tr>
+<tr>
+<td><code>PDFNATIVE_MCP_PORT</code></td>
+<td>When set to a valid port (1–65535), starts an HTTP server on <code>http://127.0.0.1:&lt;port&gt;/mcp</code> instead of stdio.</td>
+</tr>
+<tr>
+<td><code>PDFNATIVE_MCP_HTTP_TOKEN</code> <em>(v1.6.0)</em></td>
+<td>Opt-in bearer token for the HTTP transport (≥ 16 characters, no whitespace — a weaker value aborts startup). When set, <code>/mcp</code> requires <code>Authorization: Bearer &lt;token&gt;</code>; otherwise requests get <code>401</code> + <code>WWW-Authenticate</code>. Without it the loopback endpoint has <strong>no authentication</strong>. Never logged.</td>
+</tr>
+<tr>
+<td><code>PDFNATIVE_MCP_MAX_INFLATE_BYTES</code> <em>(v1.6.0)</em></td>
+<td>Operator override of the engine&#39;s 100 MiB per-stream decompression cap (integer ≥ 1024, read once at startup; an invalid value refuses to start with one clean <code>fatal:</code> line).</td>
+</tr>
+<tr>
+<td><code>PDFNATIVE_MCP_TSA_URL</code> <em>(v1.6.0)</em></td>
+<td>RFC 3161 timestamp authority endpoint. Required by <code>sign_pdf timestamp: true</code> and <code>timestamp_pdf</code> (<code>TSA_NOT_CONFIGURED</code> otherwise).</td>
+</tr>
+<tr>
+<td><code>PDFNATIVE_MCP_TSA_AUTH</code> <em>(v1.6.0)</em></td>
+<td>Optional <code>Authorization</code> header value sent to the TSA. Treated as a secret; never logged.</td>
+</tr>
+<tr>
+<td><code>PDFNATIVE_MCP_REVOCATION</code> <em>(v1.6.0)</em></td>
+<td>Revocation sources for <code>add_ltv mode: &#39;online&#39;</code> — <code>ocsp</code>, <code>crl</code>, or <code>ocsp,crl</code> (<code>REVOCATION_NOT_CONFIGURED</code> otherwise).</td>
+</tr>
+<tr>
+<td><code>PDFNATIVE_MCP_NETWORK_ALLOWED_HOSTS</code> <em>(v1.6.0)</em></td>
+<td>Mandatory allow-list of hosts the OCSP/CRL fetcher may contact. A certificate-supplied URL outside the list fails with <code>NETWORK_HOST_NOT_ALLOWED</code>.</td>
+</tr>
+<tr>
+<td><code>PDFNATIVE_MCP_NETWORK_TIMEOUT_MS</code> <em>(v1.6.0)</em></td>
+<td>Network timeout for TSA/OCSP/CRL requests (1000–120000 ms, default 10000).</td>
+</tr>
+</tbody></table>
+<blockquote>
+<p><strong>Network charter</strong> <em>(v1.6.0)</em>. The server still makes <strong>no outbound request by default</strong>. The only egress it can ever perform goes to the TSA / OCSP / CRL endpoints the <strong>operator</strong> configures via the variables above — URLs never come from tool arguments, and certificate-supplied OCSP/CRL URLs pass an SSRF guard (allow-list, http(s) only, no credentials, no redirects, internal address literals rejected, size caps, timeouts).</p>
+</blockquote>
+<hr>
+<h2 id="tool-reference">Tool reference<a class="heading-anchor" href="#tool-reference" aria-label="Link to this section">#</a></h2>
+<p><code>pdfnative-mcp</code> exposes <strong>28 tools</strong>:</p>
+<table>
+<thead>
+<tr>
+<th>Tool</th>
+<th>Purpose</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>generate_basic_pdf</code></td>
+<td>Multi-page documents from structured blocks — all <strong>13 block kinds</strong> since v1.6.0 (headings, paragraphs, lists, tables, images, links, TOC, barcodes, SVG, form fields, charts, page breaks, spacers). Accepts optional <code>pdfA</code>, layout options, build-time <code>encrypt</code>, and print-production fields.</td>
+</tr>
+<tr>
+<td><code>add_table</code></td>
+<td>Tabular PDF reports from column headers and data rows. Optional <code>autoFitColumns</code> and <code>clipCells</code>. Accepts <code>pdfA</code>.</td>
+</tr>
+<tr>
+<td><code>add_barcode</code></td>
+<td>QR Code, Code 128, EAN-13, Data Matrix, PDF417 — embedded in a single-page PDF. Accepts <code>pdfA</code>.</td>
+</tr>
+<tr>
+<td><code>add_international_text</code></td>
+<td>25 <code>lang</code> font codes — the 22 writing systems plus <code>latin</code>, <code>emoji</code> and the explicit <code>math</code> script (Noto Sans Math, on-demand) — with BiDi &amp; OpenType shaping. <code>lang</code> accepts <code>string</code>, <code>string[]</code>, or comma-separated.</td>
+</tr>
+<tr>
+<td><code>add_form</code></td>
+<td>Interactive AcroForm PDFs with text fields, text areas, checkboxes, radio buttons, dropdowns, and list boxes <em>(v1.6.0)</em>. Accepts <code>pdfA</code>.</td>
+</tr>
+<tr>
+<td><code>embed_image</code></td>
+<td>Embed a JPEG or PNG image (base64-encoded) into a titled PDF document, with <code>align</code> and <code>alt</code> <em>(v1.6.0)</em>. Accepts <code>pdfA</code>.</td>
+</tr>
+<tr>
+<td><code>prepare_signature_placeholder</code></td>
+<td>Create a PDF with a <code>/Sig</code> AcroForm placeholder ready to be signed; <code>subFilter</code>, <code>reserveTimestamp</code> and frozen signer metadata <em>(v1.6.0)</em>. Accepts <code>pdfA</code>.</td>
+</tr>
+<tr>
+<td><code>sign_pdf</code></td>
+<td>PAdES CMS digital signatures — RSA-SHA256/384/512 and ECDSA-SHA256 P-256, <code>profile: &#39;pades&#39;</code>, RFC 3161 <code>timestamp</code> (B-T), certificate chains, named fields and multiple signatures <em>(v1.6.0)</em>.</td>
+</tr>
+<tr>
+<td><code>add_ltv</code> <em>(v1.6.0)</em></td>
+<td>Embed long-term-validation material (<code>/DSS</code> + <code>/VRI</code>) into a signed PDF — PAdES <strong>B-LT</strong> — online through the operator-configured revocation provider or offline from caller-supplied material.</td>
+</tr>
+<tr>
+<td><code>timestamp_pdf</code> <em>(v1.6.0)</em></td>
+<td>Append a <code>/DocTimeStamp</code> (ETSI.RFC3161) through the operator TSA — PAdES <strong>B-LTA</strong> — with auto-suffixed field names for periodic re-timestamping.</td>
+</tr>
+<tr>
+<td><code>inspect_pdf</code></td>
+<td>Read-only inspection. Returns <code>version</code>, <code>pageCount</code>, <code>encryption</code>, <code>pdfA</code>, <code>signatureCount</code>, <code>info</code>, optional <code>perPage</code>, optional <code>pageLabels[]</code>, and — <em>(v1.6.0)</em> — an optional <code>signatures[]</code> inventory, <code>annotations[]</code>, page boxes + <code>userUnit</code>, <code>dss</code> / <code>docTimestampCount</code> / <code>trapped</code>, plus <code>checks</code> + <code>checksPassed</code>.</td>
+</tr>
+<tr>
+<td><code>inspect_layout</code> <em>(v1.6.0)</em></td>
+<td>Read-only pagination <strong>dry run</strong> — page count, page geometry and each block&#39;s position for a prospective document, with no PDF produced.</td>
+</tr>
+<tr>
+<td><code>validate_pdf</code></td>
+<td>Read-only PDF/UA structural validation (<code>valid</code>, <code>errors</code>, <code>warnings</code>).</td>
+</tr>
+<tr>
+<td><code>verify_pdf</code></td>
+<td>Real CMS/PKCS#7 signature verification — RSA &amp; ECDSA, message digest, certificate chain. Since v1.6.0, <code>/DocTimeStamp</code> entries are verified as RFC 3161 tokens and <code>ltv: true</code> reports the achieved PAdES level (B-B → B-LTA).</td>
+</tr>
+<tr>
+<td><code>add_attachment</code></td>
+<td>Embed files (e.g. Factur-X / ZUGFeRD e-invoice XML) into PDF/A-3b output.</td>
+</tr>
+<tr>
+<td><code>extract_attachments</code></td>
+<td>Extract embedded files from an existing PDF (optionally metadata-only).</td>
+</tr>
+<tr>
+<td><code>extract_text</code></td>
+<td>Extract text content from an existing PDF via the native parser.</td>
+</tr>
+<tr>
+<td><code>merge_pdfs</code></td>
+<td>Concatenate 2–50 PDFs into one document via the page-tree API (drops signatures/<code>/AcroForm</code>, keeps URI links).</td>
+</tr>
+<tr>
+<td><code>split_pdf</code></td>
+<td>Split one PDF into one document per page range — multi-output <code>{ mode, count, totalBytes, parts[] }</code>. In-memory assembly is capped by <code>maxOutputSizeBytes</code>, default <strong>256 MiB</strong>; each emitted PDF is separately capped at 50 MiB.</td>
+</tr>
+<tr>
+<td><code>extract_pages</code></td>
+<td>Pull an arbitrary, order-preserving page subset (max 5000) into a single PDF.</td>
+</tr>
+<tr>
+<td><code>annotate_pdf</code></td>
+<td>Overlay markup annotations (text / highlight / underline / strikeout / squiggly / square / circle / line / freetext) on an existing PDF via incremental update. A visual review layer, <strong>not</strong> a redaction.</td>
+</tr>
+<tr>
+<td><code>draft_governance_issue</code></td>
+<td>Assemble a governance-compliant GitHub-issue draft plus a structured <code>compliance</code> report <strong>locally</strong> — network-free by construction; never submits.</td>
+</tr>
+<tr>
+<td><code>add_chart</code> <em>(v1.5.0)</em></td>
+<td>Render a chart as <strong>native PDF vector paths</strong> — nine types since v1.6.0 (<code>bar</code>, <code>barH</code>, <code>stackedBar</code>, <code>stackedBarH</code>, <code>line</code>, <code>area</code>, <code>scatter</code>, <code>pie</code>, <code>donut</code>), with a secondary axis, log and time scales, and data labels. Tagged as <code>/Figure</code> with alt text when <code>pdfA</code> is set.</td>
+</tr>
+<tr>
+<td><code>read_form_fields</code> <em>(v1.5.0)</em></td>
+<td>List an existing AcroForm&#39;s fields with their types, current values and available options — the read half of the fill round-trip. Accepts <code>password</code>.</td>
+</tr>
+<tr>
+<td><code>fill_form</code> <em>(v1.5.0)</em></td>
+<td>Fill AcroForm field values and optionally <code>flatten</code> them into static page content. Works on encrypted PDFs via incremental update.</td>
+</tr>
+<tr>
+<td><code>encrypt_pdf</code> <em>(v1.5.0)</em></td>
+<td>Re-secure an existing PDF with AES-128 or AES-256 — owner/user passwords and an explicit permission set.</td>
+</tr>
+<tr>
+<td><code>decrypt_pdf</code> <em>(v1.5.0)</em></td>
+<td>Remove encryption from a password-protected PDF <strong>in-server</strong> — RC4, AES-128 and AES-256 sources.</td>
+</tr>
+<tr>
+<td><code>update_metadata</code> <em>(v1.6.0)</em></td>
+<td>Rewrite an existing PDF&#39;s <code>/Info</code> dictionary (+ XMP) — title, author, subject, keywords, pinned <code>modDate</code> — as a non-destructive incremental update.</td>
+</tr>
+</tbody></table>
+<p>Every tool publishes an <code>outputSchema</code> advertised in <code>tools/list</code>. Since v1.6.0 the server speaks the <a href="https://modelcontextprotocol.io/specification/2026-07-28" target="_blank" rel="noopener">MCP 2026-07-28 spec</a> (stateless envelope, <code>server/discover</code>, <code>resultType</code>, cache hints) on SDK v2, while 2025-era clients (2025-11-25 / 2025-06-18 / 2025-03-26) keep working through the automatic legacy fallback.</p>
+<hr>
+<h3 id="generate_basic_pdf"><code>generate_basic_pdf</code><a class="heading-anchor" href="#generate_basic_pdf" aria-label="Link to this section">#</a></h3>
+<p>Produces a multi-page document from a list of content blocks.</p>
+<pre><code class="language-jsonc">{
+  &quot;title&quot;: &quot;Q1 2026 Report&quot;,
+  &quot;blocks&quot;: [
+    { &quot;type&quot;: &quot;heading&quot;,   &quot;text&quot;: &quot;Executive Summary&quot;, &quot;level&quot;: 1 },
+    { &quot;type&quot;: &quot;paragraph&quot;, &quot;text&quot;: &quot;Revenue grew 24 % year over year.&quot; },
+    { &quot;type&quot;: &quot;list&quot;,      &quot;style&quot;: &quot;bullet&quot;, &quot;items&quot;: [&quot;Strong APAC&quot;, &quot;Stable EU&quot;, &quot;Soft NA&quot;] },
+    { &quot;type&quot;: &quot;pageBreak&quot; },
+    { &quot;type&quot;: &quot;heading&quot;,   &quot;text&quot;: &quot;Details&quot;, &quot;level&quot;: 2 }
+  ],
+  &quot;footerText&quot;: &quot;Confidential — Internal use only&quot;,
+  &quot;outputMode&quot;: &quot;base64&quot;
+}
+</code></pre>
+<p><strong>Block types supported:</strong> all <strong>13 engine block kinds</strong> since v1.6.0 — <code>heading</code> (levels 1–3), <code>paragraph</code>, <code>list</code> (<code>bullet</code> / <code>numbered</code>, nested items to depth 6), <code>table</code>, <code>image</code>, <code>link</code> (<code>http:</code> / <code>https:</code> / <code>mailto:</code> only), <code>toc</code> (a contents page with internal <code>/GoTo</code> links, pairs with <code>outline: &#39;auto&#39;</code>), <code>barcode</code>, <code>svg</code> (a safe subset: paths, shapes and text — no XML parser, no external reference ever fetched), <code>formField</code>, <code>chart</code> (same body as <code>add_chart</code>), <code>pageBreak</code>, and <code>spacer</code> (<code>height</code> in points). The <code>table</code> / <code>image</code> / <code>barcode</code> / <code>formField</code> blocks share their body with the dedicated tools, so a standalone artefact and an inline block validate and render identically.</p>
+<p><strong>Layout options</strong> <em>(v1.6.0)</em>, available on all nine document tools: <code>pageSize</code> (<code>A4</code> default, <code>Letter</code>, <code>Legal</code>, <code>A3</code>, <code>Tabloid</code>), <code>margins</code> (all four sides, 0–200 pt), running <code>headerTemplate</code> / <code>footerTemplate</code> (<code>left</code> / <code>center</code> / <code>right</code> zones with <code>{page}</code> <code>{pages}</code> <code>{title}</code> <code>{date}</code> placeholders — a <code>footerTemplate</code> replaces the default footer, so <code>footerText</code> is then ignored), <code>compress</code>, and <code>debug</code>.</p>
+<p><strong>Build-time <code>encrypt</code></strong> <em>(v1.6.0)</em>, on <code>generate_basic_pdf</code>, <code>add_table</code>, <code>add_form</code>, <code>add_international_text</code>, <code>embed_image</code>, <code>add_barcode</code> and <code>add_chart</code>: AES-128 (default) or AES-256 with owner/user passwords and permissions — and unlike <code>encrypt_pdf</code>, it <strong>keeps the AcroForm</strong>, making encrypted fillable forms reachable. Exclusive with <code>pdfA</code> (ISO 19005-1 §6.3.2); never cached.</p>
+<p><strong>Print production</strong> <em>(v1.6.0)</em>, on the nine document tools: <code>print</code> (TrimBox / BleedBox / ArtBox / CropBox, a <code>bleed</code> shorthand, crop + registration <code>marks</code>, <code>/UserUnit</code>), <code>metadata</code> (<code>/Author</code>, <code>/Subject</code>, <code>/Keywords</code>, <code>/Trapped</code> with XMP parity), and <code>outputIntent</code> (custom RGB ICC profile). <code>viewerPreferences</code> gains <code>duplex</code>, <code>pickTrayByPDFSize</code>, <code>printPageRange</code> (1-based), <code>numCopies</code>. Boxes survive <code>merge_pdfs</code> / <code>split_pdf</code> / <code>extract_pages</code> and are reported by <code>inspect_pdf</code>.</p>
+<p><strong>Honest PDF/A</strong> <em>(v1.6.0)</em>: text rendered through the viewer&#39;s base-14 Helvetica is not embedded, so a PDF/A claim on such a file is rejected by veraPDF. <code>embedFonts: true</code> embeds Noto Sans Latin for a valid claim; <code>strict: true</code> fails instead of producing a non-conformant file; <code>includeDiagnostics: true</code> echoes the engine&#39;s diagnostics (<code>PDFA_NO_FONT_ENTRIES</code>, <code>PDFA_UNEMBEDDED_FORM_FONT</code>, <code>PDFA_DEVICE_CMYK_IMAGE</code>).</p>
+<p><strong>Reproducible output</strong> <em>(v1.6.0)</em>: <code>creationDate</code> (ISO-8601) on all nine document tools pins <code>/Info /CreationDate</code>, the XMP dates and therefore the trailer <code>/ID</code> — byte-identical output on the same host time zone.</p>
+<hr>
+<h3 id="add_table"><code>add_table</code><a class="heading-anchor" href="#add_table" aria-label="Link to this section">#</a></h3>
+<p>Generates a tabular report from column headers and rows.</p>
+<pre><code class="language-jsonc">{
+  &quot;title&quot;: &quot;Monthly Sales&quot;,
+  &quot;headers&quot;: [&quot;Region&quot;, &quot;Units&quot;, &quot;Revenue&quot;],
+  &quot;rows&quot;: [
+    [&quot;APAC&quot;, &quot;1 200&quot;, &quot;$240,000&quot;],
+    [&quot;EMEA&quot;, &quot;800&quot;,   &quot;$160,000&quot;]
+  ],
+  &quot;infoItems&quot;:      [{ &quot;label&quot;: &quot;Period&quot;, &quot;value&quot;: &quot;January 2026&quot; }],
+  &quot;footerText&quot;:     &quot;Internal use only&quot;,
+  &quot;autoFitColumns&quot;: true,
+  &quot;clipCells&quot;:      true,
+  &quot;pdfA&quot;:           &quot;pdfa2b&quot;,
+  &quot;outputMode&quot;:     &quot;base64&quot;
+}
+</code></pre>
+<p><code>autoFitColumns</code> and <code>clipCells</code> transparently switch to the document-block backend so cell content fits its column or is clipped at the boundary, leveraging pdfnative&#39;s <code>TableBlock</code> props. Optional <code>pdfA</code> produces an archive-grade variant.</p>
+<blockquote>
+<p><strong>Smart-table fields (v1.0.0).</strong> <code>add_table</code> exposes the six pdfnative 1.2 <code>TableBlock</code> fields: <code>wrap</code> (<code>&#39;auto&#39;</code> | <code>&#39;always&#39;</code> | <code>&#39;never&#39;</code>, default <code>&#39;auto&#39;</code>), <code>repeatHeader</code> (default <code>true</code>), <code>zebra</code>, <code>caption</code>, <code>minRowHeight</code>, <code>cellPadding</code>. Multi-page tables reprint headers and wrap on overflow by default — agent-driven invoice/report workflows get multi-page-safe output out of the box. See the <a href="tables.md">Smart tables guide</a> for full semantics.</p>
+</blockquote>
+<hr>
+<h3 id="add_barcode"><code>add_barcode</code><a class="heading-anchor" href="#add_barcode" aria-label="Link to this section">#</a></h3>
+<pre><code class="language-jsonc">{
+  &quot;format&quot;:     &quot;qr&quot;,
+  &quot;data&quot;:       &quot;https://pdfnative.dev&quot;,
+  &quot;caption&quot;:    &quot;Scan to learn more&quot;,
+  &quot;ecLevel&quot;:    &quot;H&quot;,
+  &quot;outputMode&quot;: &quot;file&quot;,
+  &quot;outputPath&quot;: &quot;tickets/event-42.pdf&quot;
+}
+</code></pre>
+<p><strong>Supported formats:</strong> <code>qr</code>, <code>code128</code>, <code>ean13</code>, <code>datamatrix</code>, <code>pdf417</code>.<br><strong>Error correction levels</strong> (QR only): <code>L</code>, <code>M</code>, <code>Q</code>, <code>H</code>.</p>
+<hr>
+<h3 id="add_international_text"><code>add_international_text</code><a class="heading-anchor" href="#add_international_text" aria-label="Link to this section">#</a></h3>
+<pre><code class="language-jsonc">{
+  &quot;title&quot;:      &quot;مرحبا بالعالم 👋&quot;,
+  &quot;lang&quot;:       [&quot;ar&quot;, &quot;emoji&quot;],
+  &quot;paragraphs&quot;: [
+    &quot;هذا اختبار للنص العربي مع تشكيل OpenType ومحارف ثنائية الاتجاه.&quot;,
+    &quot;Mixed content: العربية + English + emoji 🚀 ✓&quot;
+  ]
+}
+</code></pre>
+<p><strong>Supported <code>lang</code> codes:</strong> <code>ar</code> (Arabic), <code>he</code> (Hebrew), <code>th</code> (Thai), <code>ja</code> (Japanese), <code>zh</code> (Chinese Simplified), <code>ko</code> (Korean), <code>el</code> (Greek), <code>hi</code> (Devanagari/Hindi), <code>bn</code> (Bengali), <code>ta</code> (Tamil), <code>te</code> (Telugu), <code>si</code> (Sinhala), <code>bo</code> (Tibetan), <code>km</code> (Khmer), <code>my</code> (Myanmar), <code>am</code> (Ethiopic), <code>ru</code> (Cyrillic/Russian), <code>ka</code> (Georgian), <code>hy</code> (Armenian), <code>tr</code> (Turkish), <code>vi</code> (Vietnamese), <code>pl</code> (Polish), plus <strong><code>latin</code></strong> (Noto Sans VF), <strong><code>emoji</code></strong> (Noto Emoji/COLRv1) and the explicit <strong><code>math</code></strong> symbols font <em>(v1.4.0)</em>.</p>
+<p><code>lang</code> accepts <code>string</code>, <code>string[]</code>, or a comma-separated value — e.g. <code>&quot;ar,emoji&quot;</code> or <code>[&quot;ar&quot;, &quot;emoji&quot;]</code>. When <code>pdfA</code> is set on this tool, the <code>latin</code> font is auto-registered so curly quotes, em-dashes, and ellipses validate cleanly under PDF/A.</p>
+<hr>
+<h3 id="add_form"><code>add_form</code><a class="heading-anchor" href="#add_form" aria-label="Link to this section">#</a></h3>
+<p>Creates an interactive AcroForm PDF.</p>
+<pre><code class="language-jsonc">{
+  &quot;title&quot;: &quot;Employee Onboarding&quot;,
+  &quot;fields&quot;: [
+    { &quot;fieldType&quot;: &quot;text&quot;,     &quot;name&quot;: &quot;fullName&quot;, &quot;label&quot;: &quot;Full Name&quot;,   &quot;required&quot;: true },
+    { &quot;fieldType&quot;: &quot;dropdown&quot;, &quot;name&quot;: &quot;dept&quot;,     &quot;label&quot;: &quot;Department&quot;,  &quot;options&quot;: [&quot;Engineering&quot;, &quot;Sales&quot;, &quot;HR&quot;] },
+    { &quot;fieldType&quot;: &quot;checkbox&quot;, &quot;name&quot;: &quot;agree&quot;,    &quot;label&quot;: &quot;I agree to the terms&quot;, &quot;checked&quot;: false }
+  ],
+  &quot;outputMode&quot;: &quot;base64&quot;
+}
+</code></pre>
+<p><strong>Field types:</strong> <code>text</code>, <code>textarea</code>, <code>checkbox</code>, <code>radio</code>, <code>dropdown</code>, and <code>listbox</code> <em>(v1.6.0)</em>. Text fields accept an optional <code>placeholder</code> <em>(v1.6.0)</em>. Since v1.6.0, <code>textarea</code> maps to the engine&#39;s true multi-line field (<code>/Ff 4096</code>) — in v1.5.0 it rendered as a single-line widget.</p>
+<hr>
+<h3 id="embed_image"><code>embed_image</code><a class="heading-anchor" href="#embed_image" aria-label="Link to this section">#</a></h3>
+<pre><code class="language-jsonc">{
+  &quot;title&quot;:       &quot;Product Photo&quot;,
+  &quot;imageBase64&quot;: &quot;&lt;base64-encoded JPEG bytes&gt;&quot;,
+  &quot;mimeType&quot;:    &quot;image/jpeg&quot;,
+  &quot;caption&quot;:     &quot;Front view of Model X&quot;,
+  &quot;width&quot;:       400,
+  &quot;outputMode&quot;:  &quot;base64&quot;
+}
+</code></pre>
+<blockquote>
+<p><strong>Note:</strong> Alpha-channel PNGs (color type 6) are not supported. Pre-process such images to remove the alpha channel before embedding.</p>
+</blockquote>
+<p>Since v1.6.0 the tool also accepts <code>align</code> (horizontal placement) and <code>alt</code> (accessibility text written as <code>/Figure /Alt</code> in tagged output).</p>
+<hr>
+<h3 id="prepare_signature_placeholder"><code>prepare_signature_placeholder</code><a class="heading-anchor" href="#prepare_signature_placeholder" aria-label="Link to this section">#</a></h3>
+<p>Creates a PDF pre-wired with an AcroForm <code>/Sig</code> field, ready to be signed by <code>sign_pdf</code>.</p>
+<pre><code class="language-jsonc">{
+  &quot;title&quot;:      &quot;Service Agreement&quot;,
+  &quot;signerName&quot;: &quot;Alice Dupont&quot;,
+  &quot;reason&quot;:     &quot;Approved&quot;,
+  &quot;location&quot;:   &quot;Paris, FR&quot;,
+  &quot;blocks&quot;: [
+    { &quot;type&quot;: &quot;paragraph&quot;, &quot;text&quot;: &quot;By signing below, I accept the terms and conditions.&quot; }
+  ],
+  &quot;outputMode&quot;: &quot;base64&quot;
+}
+</code></pre>
+<p>Since v1.6.0 the placeholder also takes <code>subFilter</code>, <code>reserveTimestamp</code> (extra <code>/Contents</code> room for a later RFC 3161 token), <code>placeholderBytes</code>, and <code>signingTime</code> — and the signer metadata (<code>signerName</code>, <code>reason</code>, <code>location</code>, <code>contactInfo</code>, <code>signingTime</code>) is <strong>baked into the <code>/Sig</code> dictionary at placeholder time</strong>, fixing a pre-1.7 engine bug where those values never reached the signed document.</p>
+<hr>
+<h3 id="sign_pdf"><code>sign_pdf</code><a class="heading-anchor" href="#sign_pdf" aria-label="Link to this section">#</a></h3>
+<p>Signs any PDF. When the input already contains a <code>/Sig</code> placeholder (e.g. produced by <code>prepare_signature_placeholder</code>) it is signed in place; otherwise the placeholder is auto-injected first (<code>autoInjectPlaceholder</code> defaults to <code>true</code>; set it to <code>false</code> to require an existing placeholder).</p>
+<pre><code class="language-jsonc">{
+  &quot;pdfBase64&quot;:           &quot;&lt;base64 PDF bytes&gt;&quot;,
+  &quot;algorithm&quot;:           &quot;rsa-sha256&quot;,
+  &quot;certDerBase64&quot;:       &quot;&lt;base64 X.509 certificate in DER format&gt;&quot;,
+  &quot;rsaKeyPkcs1DerBase64&quot;:&quot;&lt;base64 PKCS#1 RSAPrivateKey in DER format&gt;&quot;,
+  &quot;signerName&quot;:          &quot;Alice&quot;,
+  &quot;reason&quot;:              &quot;Approval&quot;,
+  &quot;location&quot;:            &quot;Paris, FR&quot;,
+  &quot;signingTime&quot;:         &quot;2026-01-15T10:30:00Z&quot;
+}
+</code></pre>
+<p>For ECDSA P-256: use <code>&quot;algorithm&quot;: &quot;ecdsa-sha256&quot;</code> and supply either <code>ecPrivateScalarHex</code> (64 hex chars, raw scalar <code>d</code>) or <code>ecPrivateKeyDerBase64</code> (SEC1 / PKCS#8 DER, base64 — signed through the constant-time <code>node:crypto</code> path) instead of <code>rsaKeyPkcs1DerBase64</code>. The two EC inputs are mutually exclusive.</p>
+<p><strong>PAdES and timestamps</strong> <em>(v1.6.0)</em>:</p>
+<ul>
+<li><code>algorithm</code> also accepts <code>rsa-sha384</code> and <code>rsa-sha512</code>.</li>
+<li><code>profile: &#39;pades&#39;</code> produces an ETSI.CAdES.detached signature (PAdES <strong>B-B</strong>).</li>
+<li><code>timestamp: true</code> requests an RFC 3161 timestamp from the operator-configured TSA (<code>PDFNATIVE_MCP_TSA_URL</code>) and embeds it in the CMS — PAdES <strong>B-T</strong>. Fails with <code>TSA_NOT_CONFIGURED</code> when no TSA is set, <code>TSA_REJECTED</code> when the authority declines.</li>
+<li><code>certChainDerBase64</code> embeds intermediate certificates alongside the signer certificate.</li>
+<li><code>fieldName</code> targets a specific <code>/Sig</code> field (<code>SIGNATURE_FIELD_NOT_FOUND</code> when absent, <code>PLACEHOLDER_AMBIGUOUS</code> when several placeholders exist and none is named); <code>allowMultiple: true</code> adds a signature next to existing ones instead of rejecting.</li>
+<li>The default placeholder reservation is now <code>max(16384, estimated CMS size)</code> — plus 8192 bytes when <code>timestamp: true</code> — instead of a flat 16384 bytes. To pin it exactly, build the placeholder with <code>prepare_signature_placeholder</code> and its <code>placeholderBytes</code> input.</li>
+</ul>
+<p>To climb the rest of the PAdES ladder, follow with <a href="#add_ltv-v160"><code>add_ltv</code></a> (B-LT) and <a href="#timestamp_pdf-v160"><code>timestamp_pdf</code></a> (B-LTA), then check the achieved level with <code>verify_pdf ltv: true</code>. The server&#39;s <code>pades_ladder</code> prompt walks through the full recipe.</p>
+<hr>
+<h3 id="inspect_pdf"><code>inspect_pdf</code><a class="heading-anchor" href="#inspect_pdf" aria-label="Link to this section">#</a></h3>
+<p>Read-only PDF inspection over <code>openPdf()</code>. Never modifies the input.</p>
+<pre><code class="language-jsonc">{
+  &quot;pdfBase64&quot;: &quot;&lt;base64 PDF bytes&gt;&quot;,
+  &quot;pages&quot;:     true,
+  &quot;check&quot;:     [&quot;pdfa&quot;, &quot;signed&quot;]
+}
+</code></pre>
+<p><strong>Inputs:</strong></p>
+<ul>
+<li><code>pdfBase64</code> — base64 PDF bytes (required).</li>
+<li><code>password</code> — password for an encrypted PDF <em>(v1.5.0)</em>.</li>
+<li><code>pages</code> — when <code>true</code>, includes per-page <code>index</code>, <code>width</code>, <code>height</code> — and, since v1.6.0, the declared page boxes and <code>userUnit</code>.</li>
+<li><code>signatures</code> <em>(v1.6.0)</em> — when <code>true</code>, a per-signature inventory: <code>subFilter</code>, <code>isDocTimestamp</code>, <code>isPlaceholder</code>, <code>byteRange</code>, <code>vriKey</code>.</li>
+<li><code>annotations</code> <em>(v1.6.0)</em> — when <code>true</code>, an <code>annotations[]</code> list (0-based <code>page</code>, <code>subtype</code>, <code>rect</code>, and when present <code>contents</code>, <code>title</code>, <code>color</code>, <code>quadPoints</code>, link <code>url</code>) plus <code>annotationCount</code>.</li>
+<li><code>check</code> — array of CI assertions. Allowed values: <code>pdfa</code>, <code>signed</code>, <code>encrypted</code>, <code>placeholder</code>, <code>attachments</code>, and — <em>(v1.6.0)</em> — <code>dss</code>, <code>docTimestamp</code>, <code>trapped</code>, <code>annotations</code>. The response includes <code>checks</code> (per-assertion result) and <code>checksPassed</code> (boolean AND). Since v1.6.0, <code>checks</code> contains <strong>only the requested keys</strong>.</li>
+<li><code>verbosity</code> — <code>&#39;full&#39;</code> (default) or <code>&#39;summary&#39;</code> (token-frugal scalar subset).</li>
+<li><code>fields</code> — optional dot-path projection of the result.</li>
+</ul>
+<p><strong>Outputs:</strong> <code>version</code>, <code>pageCount</code>, <code>encryption</code> (<code>&#39;none&#39;</code> / <code>&#39;aes-128&#39;</code> / <code>&#39;aes-256&#39;</code> / <code>&#39;rc4&#39;</code> / <code>&#39;unknown&#39;</code>), optional <code>encryptionInfo</code> (<code>{ algorithm, revision, authenticatedAs }</code>, present when the document is encrypted and opened successfully), <code>pdfA</code> (<code>null</code> or the detected claim string), <code>signatureCount</code>, <code>hasSignaturePlaceholder</code>, <code>attachments[]</code> (embedded-file summaries), <code>info</code> (decoded <code>/Info</code> entries), optional <code>perPage[]</code>, optional <code>pageLabels[]</code> (when <code>/PageLabels</code> is declared), optional <code>checks</code> + <code>checksPassed</code> — plus, presence-gated since v1.6.0, <code>dss</code>, <code>docTimestampCount</code> and <code>trapped</code>.</p>
+<p>Useful in CI as a final assertion step before publishing a PDF artifact:</p>
+<pre><code class="language-jsonc">{ &quot;tool&quot;: &quot;inspect_pdf&quot;,
+  &quot;input&quot;: { &quot;pdfBase64&quot;: &quot;&lt;...&gt;&quot;, &quot;check&quot;: [&quot;pdfa&quot;, &quot;signed&quot;] } }
+// → { ..., &quot;checks&quot;: { &quot;pdfa&quot;: true, &quot;signed&quot;: true }, &quot;checksPassed&quot;: true }
+</code></pre>
+<hr>
+<h3 id="merge_pdfs"><code>merge_pdfs</code><a class="heading-anchor" href="#merge_pdfs" aria-label="Link to this section">#</a></h3>
+<p>Concatenates <strong>2–50</strong> PDFs into a single document via pdfnative&#39;s page-tree API. Encrypted sources are supported since v1.5.0 via <code>password</code> (a single password applied to every encrypted source), and the output can be re-encrypted via <code>encrypt</code>. Signatures and <code>/AcroForm</code> are dropped because page edits invalidate <code>/ByteRange</code>; self-contained URI <code>/Link</code> annotations are kept.</p>
+<pre><code class="language-jsonc">{
+  &quot;pdfsBase64&quot;: [&quot;&lt;base64 PDF 1&gt;&quot;, &quot;&lt;base64 PDF 2&gt;&quot;, &quot;&lt;base64 PDF 3&gt;&quot;],
+  &quot;outputMode&quot;: &quot;base64&quot;
+}
+</code></pre>
+<p><strong>Errors:</strong> <code>PASSWORD_REQUIRED</code> / <code>PASSWORD_INVALID</code> (encrypted source without / with the wrong <code>password</code>), <code>OUTPUT_TOO_LARGE</code> (50 MiB per emitted PDF; assembly capped by <code>maxOutputSizeBytes</code>, default 256 MiB), <code>PDF_PARSE_FAILED</code>.</p>
+<hr>
+<h3 id="split_pdf"><code>split_pdf</code><a class="heading-anchor" href="#split_pdf" aria-label="Link to this section">#</a></h3>
+<p>Splits one PDF into one document per page range, returning a <strong>multi-output</strong> shape. Ranges are <strong>0-based and inclusive</strong>; <code>end</code> defaults to <code>start</code> (a single page).</p>
+<pre><code class="language-jsonc">{
+  &quot;pdfBase64&quot;: &quot;&lt;base64 PDF bytes&gt;&quot;,
+  &quot;ranges&quot;: [{ &quot;start&quot;: 0, &quot;end&quot;: 2 }, { &quot;start&quot;: 3, &quot;end&quot;: 9 }],
+  &quot;outputMode&quot;: &quot;base64&quot;
+}
+// → { &quot;mode&quot;: &quot;base64&quot;, &quot;count&quot;: 2, &quot;totalBytes&quot;: 123456, &quot;parts&quot;: [ { &quot;index&quot;: 0, &quot;sizeBytes&quot;: 61000, &quot;base64&quot;: &quot;...&quot; }, ... ] }
+</code></pre>
+<p>Each part is capped at <strong>50 MiB</strong>; the aggregate output is capped at <strong>200 MiB</strong>.</p>
+<hr>
+<h3 id="extract_pages"><code>extract_pages</code><a class="heading-anchor" href="#extract_pages" aria-label="Link to this section">#</a></h3>
+<p>Pulls an arbitrary, order-preserving page subset (<strong>max 5000</strong> pages) into a single PDF.</p>
+<pre><code class="language-jsonc">{
+  &quot;pdfBase64&quot;: &quot;&lt;base64 PDF bytes&gt;&quot;,
+  &quot;pages&quot;: [0, 2, 4, 1],
+  &quot;outputMode&quot;: &quot;base64&quot;
+}
+</code></pre>
+<p>Page indices are <strong>0-based</strong>; the output preserves the order you request.</p>
+<h3 id="annotate_pdf"><code>annotate_pdf</code><a class="heading-anchor" href="#annotate_pdf" aria-label="Link to this section">#</a></h3>
+<p>Overlays markup annotations on an existing PDF via <strong>incremental update</strong>, so the original bytes — and any existing signature — stay intact.</p>
+<pre><code class="language-jsonc">{
+  &quot;pdfBase64&quot;: &quot;&lt;base64 PDF bytes&gt;&quot;,
+  &quot;annotations&quot;: [
+    { &quot;type&quot;: &quot;highlight&quot;, &quot;page&quot;: 0, &quot;rect&quot;: [72, 700, 520, 715], &quot;color&quot;: &quot;#ffe066&quot;, &quot;contents&quot;: &quot;Review this clause&quot; },
+    { &quot;type&quot;: &quot;text&quot;,      &quot;page&quot;: 1, &quot;rect&quot;: [80, 640, 100, 660], &quot;contents&quot;: &quot;Sticky note&quot; }
+  ],
+  &quot;outputMode&quot;: &quot;base64&quot;
+}
+</code></pre>
+<p>Types: <code>text</code>, <code>highlight</code>, <code>underline</code>, <code>strikeout</code>, <code>squiggly</code>, <code>square</code>, <code>circle</code>, <code>line</code>, <code>freetext</code>. Each takes a <strong>0-based</strong> <code>page</code>, a <code>rect: [x1, y1, x2, y2]</code>, and optional <code>color</code> / <code>contents</code>. Encrypted sources → <code>ENCRYPTED_SOURCE</code>; an out-of-range <code>page</code> → a validation error.</p>
+<blockquote>
+<p><strong>Overlay, not redaction.</strong> <code>annotate_pdf</code> is a <em>visual review layer</em>; the underlying bytes remain. It does <strong>not</strong> remove or obscure content — see the deferred <code>redact_pdf</code> note under <em>What&#39;s new in v1.4.0</em>.</p>
+</blockquote>
+<h3 id="draft_governance_issue"><code>draft_governance_issue</code><a class="heading-anchor" href="#draft_governance_issue" aria-label="Link to this section">#</a></h3>
+<p>Assembles a governance-compliant GitHub-issue draft plus a structured <code>compliance</code> report <strong>locally</strong> and returns them. It <strong>never submits</strong> and makes <strong>no</strong> network call — there is no HTTP client, no GitHub SDK, and no <code>fetch</code> anywhere in the server.</p>
+<pre><code class="language-jsonc">{
+  &quot;title&quot;: &quot;SVG &lt;text&gt; word-wrap not supported&quot;,
+  &quot;issueType&quot;: &quot;feature&quot;,
+  &quot;summary&quot;: &quot;renderSvg() emits &lt;text&gt; on a single line with no automatic wrapping.&quot;,
+  &quot;reproduction&quot;: {
+    &quot;command&quot;: &quot;node repro.mjs&quot;,
+    &quot;result&quot;: &quot;Long &lt;text&gt; overflows the viewport instead of wrapping.&quot;
+  },
+  &quot;expectedBehavior&quot;: &quot;Optional word-wrap for SVG &lt;text&gt;.&quot;,
+  &quot;targetRepo&quot;: &quot;pdfnative&quot;,
+  &quot;affectedPackages&quot;: [&quot;pdfnative&quot;],
+  &quot;duplicateSearchPerformed&quot;: true,
+  &quot;outputMode&quot;: &quot;inline&quot;
+}
+</code></pre>
+<p><code>duplicateSearchPerformed</code> <strong>must be <code>true</code></strong>. A draft that proposes a runtime dependency, omits a reproduction, or sets it to <code>false</code> is rejected with <code>GOVERNANCE_VIOLATION</code>. Present the returned <code>draftMarkdown</code> + <code>compliance</code> to the user; a <strong>human</strong> submits it. Read the <code>governance_contract</code> / <code>draft_issue_workflow</code> prompts first.</p>
+<h3 id="add_chart-v150"><code>add_chart</code> <em>(v1.5.0)</em><a class="heading-anchor" href="#add_chart-v150" aria-label="Link to this section">#</a></h3>
+<p>Renders a chart as <strong>native PDF vector paths</strong> — no rasterisation, no image round-trip. Multi-series bar/line, legends, gridlines and negative values are supported; the chart is tagged <code>/Figure</code> with <code>/Alt</code> (auto-generated when <code>altText</code> is omitted).</p>
+<pre><code class="language-jsonc">{
+  &quot;chartType&quot;: &quot;bar&quot;,
+  &quot;title&quot;: &quot;Revenue by quarter&quot;,
+  &quot;series&quot;: [{ &quot;label&quot;: &quot;2026&quot;, &quot;values&quot;: [1.2, 1.5, 1.4, 1.9] }],
+  &quot;intro&quot;: &quot;Quarterly revenue in $M.&quot;,
+  &quot;pdfA&quot;: &quot;pdfa2b&quot;,
+  &quot;outputMode&quot;: &quot;base64&quot;
+}
+</code></pre>
+<p><strong>Inputs:</strong> <code>chartType</code> (<code>bar</code> / <code>barH</code> / <code>line</code> / <code>pie</code> / <code>donut</code>, plus — <em>(v1.6.0)</em> — <code>stackedBar</code> / <code>stackedBarH</code> / <code>area</code> / <code>scatter</code>) and <code>series</code> (required; pie/donut take exactly one series), plus <code>title</code>, <code>legend</code> (<code>&#39;bottom&#39;</code> / <code>&#39;none&#39;</code>), <code>markers</code> (line series), <code>colors</code> (hex palette override), <code>altText</code>, <code>intro</code> (paragraph above the chart), <code>pdfA</code>, <code>outputMode</code> / <code>outputPath</code>. For a chart amongst headings/paragraphs/tables, use a <code>chart</code> block inside <code>generate_basic_pdf</code> — both build identical pdfnative blocks.</p>
+<p><strong>Charts v2</strong> <em>(v1.6.0)</em>: per-series <code>xValues</code> with <code>xAxis.type: &#39;linear&#39; | &#39;time&#39;</code> (UTC-deterministic time axes), a secondary right axis (<code>axis2</code>), <code>axis.scale: &#39;log&#39;</code>, <code>dataLabels</code>, and <code>labelStride</code> / <code>labelRotation</code> for crowded x labels. Engine cross-field rules surface as <code>CHART_ERROR</code> with a remedy.</p>
+<h3 id="read_form_fields-v150"><code>read_form_fields</code> <em>(v1.5.0)</em><a class="heading-anchor" href="#read_form_fields-v150" aria-label="Link to this section">#</a></h3>
+<p>Read-only enumeration of an existing PDF&#39;s AcroForm — the discovery half of the fill round-trip.</p>
+<pre><code class="language-jsonc">{ &quot;pdfBase64&quot;: &quot;&lt;base64 PDF bytes&gt;&quot;, &quot;verbosity&quot;: &quot;full&quot; }
+</code></pre>
+<p><strong>Inputs:</strong> <code>pdfBase64</code> (required), <code>password</code> (encrypted sources), <code>verbosity</code> (<code>&#39;full&#39;</code> default / <code>&#39;summary&#39;</code> = <code>{ fieldCount }</code> only), <code>fields</code> (dot-path projection).<br><strong>Outputs:</strong> <code>fieldCount</code> and <code>fields[]</code> — each with <code>name</code> (fully-qualified), <code>type</code> (<code>text</code> / <code>checkbox</code> / <code>radio</code> / <code>dropdown</code> / <code>listbox</code> / <code>button</code> / <code>signature</code> / <code>unknown</code>), current <code>value</code>, <code>readOnly</code> / <code>required</code> / <code>multiline</code> flags, <code>options[]</code> (<code>{ export, label }</code> for choice fields), <code>maxLen</code>, <code>onState</code>, and <code>widgets[]</code> (0-based page + rect).</p>
+<h3 id="fill_form-v150"><code>fill_form</code> <em>(v1.5.0)</em><a class="heading-anchor" href="#fill_form-v150" aria-label="Link to this section">#</a></h3>
+<p>Fills (and optionally flattens) the AcroForm of an <em>existing</em> PDF via a non-destructive <strong>incremental update</strong>, so a prior signature stays valid for its revision. Works on encrypted documents via <code>password</code> (appended objects are encrypted under the document&#39;s existing scheme).</p>
+<pre><code class="language-jsonc">{
+  &quot;pdfBase64&quot;: &quot;&lt;base64 PDF bytes&gt;&quot;,
+  &quot;values&quot;: { &quot;fullName&quot;: &quot;Alice Dupont&quot;, &quot;agree&quot;: true },
+  &quot;flatten&quot;: false,
+  &quot;outputMode&quot;: &quot;base64&quot;
+}
+</code></pre>
+<p><strong>Inputs:</strong> <code>pdfBase64</code> (required), <code>values</code> (name → string | boolean | string[]; omit with <code>flatten: true</code> for a pure flatten), <code>flatten</code> (default <code>false</code>), <code>onUnknownField</code> (<code>&#39;throw&#39;</code> default / <code>&#39;ignore&#39;</code>), <code>nonWinAnsi</code> (<code>&#39;throw&#39;</code> default / <code>&#39;needAppearances&#39;</code>), <code>password</code>, <code>outputMode</code> / <code>outputPath</code>.<br><strong>Errors:</strong> <code>FORM_FIELD_NOT_FOUND</code>, <code>FORM_VALUE_TYPE_ERROR</code>, <code>FORM_UNSUPPORTED</code> (signature fields cannot be filled/flattened), <code>PASSWORD_REQUIRED</code> / <code>PASSWORD_INVALID</code>.</p>
+<h3 id="encrypt_pdf-v150"><code>encrypt_pdf</code> <em>(v1.5.0)</em><a class="heading-anchor" href="#encrypt_pdf-v150" aria-label="Link to this section">#</a></h3>
+<p>Re-secures an existing PDF with AES-128 (default, widest compatibility) or AES-256 via the page-tree re-encryption path. An already-encrypted source can be rotated to a new password by supplying its current <code>password</code>.</p>
+<pre><code class="language-jsonc">{
+  &quot;pdfBase64&quot;: &quot;&lt;base64 PDF bytes&gt;&quot;,
+  &quot;ownerPassword&quot;: &quot;s3cret-owner&quot;,
+  &quot;userPassword&quot;: &quot;open-me&quot;,
+  &quot;algorithm&quot;: &quot;aes256&quot;,
+  &quot;permissions&quot;: { &quot;print&quot;: true, &quot;copy&quot;: false, &quot;modify&quot;: false, &quot;extractText&quot;: false },
+  &quot;outputMode&quot;: &quot;base64&quot;
+}
+</code></pre>
+<p><strong>Inputs:</strong> <code>pdfBase64</code> and <code>ownerPassword</code> (required), <code>userPassword</code> (omitted/empty = opens without a prompt), <code>algorithm</code> (<code>&#39;aes128&#39;</code> default / <code>&#39;aes256&#39;</code>), <code>permissions</code> (<code>{ print?, copy?, modify?, extractText? }</code>, each allowed when omitted), <code>password</code> (current password of an encrypted source), <code>outputMode</code> / <code>outputPath</code>.</p>
+<blockquote>
+<p>Like merge/split/extract, encryption rebuilds the page tree: existing signatures and <code>/AcroForm</code> are <strong>dropped</strong>, and only self-contained URI link annotations are kept. Encrypt <strong>before</strong> signing, not after. Excluded from the response cache.</p>
+</blockquote>
+<h3 id="decrypt_pdf-v150"><code>decrypt_pdf</code> <em>(v1.5.0)</em><a class="heading-anchor" href="#decrypt_pdf-v150" aria-label="Link to this section">#</a></h3>
+<p>Opens an encrypted PDF (RC4, AES-128 or AES-256) and emits an unencrypted copy <strong>in-server</strong> — no external tool needed.</p>
+<pre><code class="language-jsonc">{ &quot;pdfBase64&quot;: &quot;&lt;base64 encrypted PDF&gt;&quot;, &quot;password&quot;: &quot;open-me&quot;, &quot;outputMode&quot;: &quot;base64&quot; }
+</code></pre>
+<p><strong>Inputs:</strong> <code>pdfBase64</code> (required), <code>password</code> (user or owner; omit only for documents with an empty user password), <code>outputMode</code> / <code>outputPath</code>.</p>
+<blockquote>
+<p>The rebuild drops signatures and <code>/AcroForm</code>. To <em>read</em> an encrypted PDF without rebuilding it, pass <code>password</code> to <code>inspect_pdf</code> / <code>extract_text</code> / <code>extract_attachments</code> instead. Excluded from the response cache.</p>
+</blockquote>
+<h3 id="add_ltv-v160"><code>add_ltv</code> <em>(v1.6.0)</em><a class="heading-anchor" href="#add_ltv-v160" aria-label="Link to this section">#</a></h3>
+<p>Embeds long-term-validation material — a <code>/DSS</code> (Document Security Store) with <code>/VRI</code> entries — into an already-signed PDF via incremental update, taking a PAdES B-T document to <strong>B-LT</strong>.</p>
+<pre><code class="language-jsonc">{
+  &quot;pdfBase64&quot;: &quot;&lt;base64 signed PDF&gt;&quot;,
+  &quot;mode&quot;: &quot;online&quot;,
+  &quot;preferOcsp&quot;: true,
+  &quot;outputMode&quot;: &quot;base64&quot;
+}
+</code></pre>
+<p><strong>Inputs:</strong> <code>pdfBase64</code> (required), <code>mode</code> (<code>&#39;online&#39;</code> default — fetches OCSP responses / CRLs through the operator-configured revocation provider; <code>&#39;offline&#39;</code> — embeds parse-validated caller-supplied material), <code>preferOcsp</code>, <code>certificatesDerBase64[]</code> / <code>ocspResponsesDerBase64[]</code> / <code>crlsDerBase64[]</code> (offline material), <code>outputMode</code> / <code>outputPath</code>. The structured result includes a <code>summary</code> of what was embedded.</p>
+<p><strong>Errors:</strong> <code>LTV_NO_SIGNATURE</code> (nothing to validate), <code>LTV_EMPTY</code> (no material gathered), <code>LTV_MATERIAL_INVALID</code>, <code>LTV_ERROR</code>, <code>REVOCATION_NOT_CONFIGURED</code> (online mode without <code>PDFNATIVE_MCP_REVOCATION</code>), <code>NETWORK_HOST_NOT_ALLOWED</code>, <code>NETWORK_ERROR</code>, <code>ENCRYPTED_SOURCE</code> (decrypting would destroy the signatures — sign before encrypting).</p>
+<blockquote>
+<p>Online mode is the <strong>only</strong> network-touching path in the server besides the TSA, and it only ever contacts operator-allow-listed hosts. See <em>Environment variables</em> above.</p>
+</blockquote>
+<h3 id="timestamp_pdf-v160"><code>timestamp_pdf</code> <em>(v1.6.0)</em><a class="heading-anchor" href="#timestamp_pdf-v160" aria-label="Link to this section">#</a></h3>
+<p>Appends a <code>/DocTimeStamp</code> signature field (ETSI.RFC3161) through the operator-configured TSA, taking a B-LT document to <strong>B-LTA</strong>. The token&#39;s status, message imprint and nonce are checked before embedding; its own CMS signature is verified by <code>verify_pdf</code>.</p>
+<pre><code class="language-jsonc">{
+  &quot;pdfBase64&quot;: &quot;&lt;base64 signed PDF&gt;&quot;,
+  &quot;outputMode&quot;: &quot;base64&quot;
+}
+</code></pre>
+<p><strong>Inputs:</strong> <code>pdfBase64</code> (required), <code>fieldName</code> (auto-suffixed <code>DocTimeStamp1</code>, <code>DocTimeStamp2</code>, … when omitted — supporting periodic re-timestamping), <code>placeholderBytes</code> (4096–65536), <code>outputMode</code> / <code>outputPath</code>.</p>
+<p><strong>Errors:</strong> <code>TSA_NOT_CONFIGURED</code>, <code>TSA_REJECTED</code>, <code>NETWORK_ERROR</code>, <code>ENCRYPTED_SOURCE</code>.</p>
+<h3 id="update_metadata-v160"><code>update_metadata</code> <em>(v1.6.0)</em><a class="heading-anchor" href="#update_metadata-v160" aria-label="Link to this section">#</a></h3>
+<p>Rewrites an existing PDF&#39;s <code>/Info</code> dictionary — and its XMP packet when present — via a non-destructive <strong>incremental update</strong>, so earlier revisions stay a byte-exact prefix.</p>
+<pre><code class="language-jsonc">{
+  &quot;pdfBase64&quot;: &quot;&lt;base64 PDF bytes&gt;&quot;,
+  &quot;title&quot;: &quot;Quarterly Report — Final&quot;,
+  &quot;author&quot;: &quot;Finance Team&quot;,
+  &quot;keywords&quot;: &quot;finance, Q1, 2026&quot;,
+  &quot;modDate&quot;: &quot;2026-08-25T09:00:00+02:00&quot;,
+  &quot;outputMode&quot;: &quot;base64&quot;
+}
+</code></pre>
+<p><strong>Inputs:</strong> <code>pdfBase64</code> (required), <code>title</code>, <code>author</code>, <code>subject</code>, <code>keywords</code> (≤ 1000 characters), <code>modDate</code> (ISO-8601 with offset — pinned for reproducible bytes), <code>outputMode</code> / <code>outputPath</code>.</p>
+<p><strong>Errors:</strong> <code>ENCRYPTED_SOURCE</code> (use <code>decrypt_pdf</code> → <code>update_metadata</code> → <code>encrypt_pdf</code>), <code>METADATA_ERROR</code>, <code>PDF_PARSE_FAILED</code>.</p>
+<h3 id="inspect_layout-v160"><code>inspect_layout</code> <em>(v1.6.0)</em><a class="heading-anchor" href="#inspect_layout-v160" aria-label="Link to this section">#</a></h3>
+<p>A read-only pagination <strong>dry run</strong>: measures how a prospective document would paginate — without producing a PDF and without consuming output tokens on base64 bytes. The seventh read tool with <code>verbosity</code> / <code>fields</code>.</p>
+<pre><code class="language-jsonc">{
+  &quot;title&quot;: &quot;Q1 2026 Report&quot;,
+  &quot;blocks&quot;: [
+    { &quot;type&quot;: &quot;heading&quot;, &quot;text&quot;: &quot;Executive Summary&quot;, &quot;level&quot;: 1 },
+    { &quot;type&quot;: &quot;paragraph&quot;, &quot;text&quot;: &quot;Revenue grew 24 % year over year.&quot; }
+  ],
+  &quot;verbosity&quot;: &quot;summary&quot;
+}
+// → { &quot;pageWidth&quot;: 595.28, &quot;pageHeight&quot;: 841.89, &quot;totalPages&quot;: 1, &quot;blockCount&quot;: 2 }
+</code></pre>
+<p><strong>Inputs:</strong> <code>title</code> and <code>blocks</code> (required), plus every input that moves a block — <code>footerText</code>, <code>pdfA</code>, <code>normalize</code>, <code>embedFonts</code>, <code>pageSize</code>, <code>margins</code>, <code>headerTemplate</code>, <code>footerTemplate</code> — and <code>verbosity</code> / <code>fields</code>.</p>
+<p><strong>Outputs (full):</strong> <code>pageWidth</code>, <code>pageHeight</code>, <code>margins</code>, <code>totalPages</code>, and <code>pages[].blocks[]</code> with each block&#39;s <code>type</code>, <code>page</code>, <code>x</code>, <code>top</code>, <code>width</code>, <code>height</code> (2-decimal points).</p>
+<blockquote>
+<p><strong>Known engine gap:</strong> a <code>toc</code> block is measured as 0 pt, so a document with a printed contents page may paginate one page later than previewed.</p>
+</blockquote>
+<hr>
+<h2 id="mcp-prompts">MCP prompts<a class="heading-anchor" href="#mcp-prompts" aria-label="Link to this section">#</a></h2>
+<p>Since v1.4.0 the server advertises the MCP <strong><code>prompts</code></strong> capability; v1.6.0 grows it to <strong>six prompts</strong> — the two governance prompts plus four recipe prompts:</p>
+<table>
+<thead>
+<tr>
+<th>Prompt</th>
+<th>Purpose</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>governance_contract</code></td>
+<td>The full AI-governance / Human-in-the-Loop contract.</td>
+</tr>
+<tr>
+<td><code>draft_issue_workflow</code></td>
+<td>The step-by-step recipe for producing a compliant issue draft with <code>draft_governance_issue</code>.</td>
+</tr>
+<tr>
+<td><code>pades_ladder</code> <em>(v1.6.0)</em></td>
+<td>The B-B → B-T → B-LT → B-LTA recipe: <code>sign_pdf</code> → <code>add_ltv</code> → <code>timestamp_pdf</code>, verified with <code>verify_pdf ltv: true</code>.</td>
+</tr>
+<tr>
+<td><code>print_ready</code> <em>(v1.6.0)</em></td>
+<td>Producing press-ready output: bleed, printer&#39;s marks, custom OutputIntent.</td>
+</tr>
+<tr>
+<td><code>reproducible_output</code> <em>(v1.6.0)</em></td>
+<td>Byte-stable output via pinned <code>creationDate</code> / <code>signingTime</code> / <code>modDate</code>.</td>
+</tr>
+<tr>
+<td><code>pdfa_valid</code> <em>(v1.6.0)</em></td>
+<td>Producing a PDF/A file that veraPDF actually accepts (<code>embedFonts</code>, <code>strict</code>, diagnostics).</td>
+</tr>
+</tbody></table>
+<h2 id="error-codes">Error codes<a class="heading-anchor" href="#error-codes" aria-label="Link to this section">#</a></h2>
+<table>
+<thead>
+<tr>
+<th><code>code</code></th>
+<th>Raised by</th>
+<th>Meaning / fix</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>ENCRYPTED_SOURCE</code></td>
+<td><code>annotate_pdf</code>, <code>update_metadata</code>, <code>add_ltv</code>, <code>timestamp_pdf</code></td>
+<td>The source PDF is encrypted and the tool has no <code>password</code> parameter. Remedies are tool-specific since v1.6.0: for <code>annotate_pdf</code> / <code>update_metadata</code>, <code>decrypt_pdf</code> → edit → <code>encrypt_pdf</code>; for <code>add_ltv</code> / <code>timestamp_pdf</code>, decrypting would destroy the signatures — sign before encrypting.</td>
+</tr>
+<tr>
+<td><code>PASSWORD_REQUIRED</code> <em>(v1.5.0)</em></td>
+<td>password-aware tools (<code>inspect_pdf</code>, <code>verify_pdf</code>, <code>extract_text</code>, <code>extract_attachments</code>, <code>read_form_fields</code>, <code>fill_form</code>, page-tree trio, <code>encrypt_pdf</code>, <code>decrypt_pdf</code>)</td>
+<td>The source is encrypted and no <code>password</code> was supplied.</td>
+</tr>
+<tr>
+<td><code>PASSWORD_INVALID</code> <em>(v1.5.0)</em></td>
+<td>password-aware tools</td>
+<td>The supplied <code>password</code> does not open the document.</td>
+</tr>
+<tr>
+<td><code>ENCRYPTION_UNSUPPORTED</code> <em>(v1.5.0)</em></td>
+<td>password-aware tools</td>
+<td>The document uses an encryption scheme the reader does not support.</td>
+</tr>
+<tr>
+<td><code>FORM_FIELD_NOT_FOUND</code> <em>(v1.5.0)</em></td>
+<td><code>fill_form</code></td>
+<td>A <code>values</code> key matches no field (with <code>onUnknownField: &#39;throw&#39;</code>, the default).</td>
+</tr>
+<tr>
+<td><code>FORM_VALUE_TYPE_ERROR</code> <em>(v1.5.0)</em></td>
+<td><code>fill_form</code></td>
+<td>A value&#39;s type does not match the field (e.g. a boolean for a text field).</td>
+</tr>
+<tr>
+<td><code>FORM_UNSUPPORTED</code> <em>(v1.5.0)</em></td>
+<td><code>fill_form</code></td>
+<td>The field cannot be filled/flattened (e.g. a signature field).</td>
+</tr>
+<tr>
+<td><code>OUTPUT_TOO_LARGE</code></td>
+<td>PDF-emitting tools</td>
+<td>An emitted PDF exceeds 50 MiB (for <code>split_pdf</code>, also the 200 MiB aggregate), or assembly exceeds <code>maxOutputSizeBytes</code> (default 256 MiB).</td>
+</tr>
+<tr>
+<td><code>PDF_PARSE_FAILED</code></td>
+<td>page-tree tools</td>
+<td>The source bytes are not a parseable PDF.</td>
+</tr>
+<tr>
+<td><code>GOVERNANCE_VIOLATION</code></td>
+<td><code>draft_governance_issue</code></td>
+<td>The draft breaks the AI-governance contract (proposes a runtime dependency, omits a reproduction, or <code>duplicateSearchPerformed: false</code>). Fix the draft and retry.</td>
+</tr>
+<tr>
+<td><code>TSA_NOT_CONFIGURED</code> <em>(v1.6.0)</em></td>
+<td><code>sign_pdf</code> (<code>timestamp: true</code>), <code>timestamp_pdf</code></td>
+<td>No <code>PDFNATIVE_MCP_TSA_URL</code> is set. Configure the TSA in the server environment.</td>
+</tr>
+<tr>
+<td><code>TSA_REJECTED</code> <em>(v1.6.0)</em></td>
+<td><code>sign_pdf</code>, <code>timestamp_pdf</code></td>
+<td>The timestamp authority declined the request.</td>
+</tr>
+<tr>
+<td><code>REVOCATION_NOT_CONFIGURED</code> <em>(v1.6.0)</em></td>
+<td><code>add_ltv</code> (<code>mode: &#39;online&#39;</code>)</td>
+<td>No <code>PDFNATIVE_MCP_REVOCATION</code> sources are set. Configure them, or use <code>mode: &#39;offline&#39;</code> with caller-supplied material.</td>
+</tr>
+<tr>
+<td><code>NETWORK_HOST_NOT_ALLOWED</code> <em>(v1.6.0)</em></td>
+<td><code>add_ltv</code></td>
+<td>A certificate-supplied OCSP/CRL URL points outside <code>PDFNATIVE_MCP_NETWORK_ALLOWED_HOSTS</code>.</td>
+</tr>
+<tr>
+<td><code>NETWORK_ERROR</code> <em>(v1.6.0)</em></td>
+<td>TSA/LTV tools</td>
+<td>The TSA/OCSP/CRL request failed (timeout, refusal, size cap).</td>
+</tr>
+<tr>
+<td><code>LTV_NO_SIGNATURE</code> / <code>LTV_EMPTY</code> / <code>LTV_MATERIAL_INVALID</code> / <code>LTV_ERROR</code> <em>(v1.6.0)</em></td>
+<td><code>add_ltv</code></td>
+<td>No signature to validate / no material gathered / supplied DER material does not parse / embedding failed.</td>
+</tr>
+<tr>
+<td><code>METADATA_ERROR</code> <em>(v1.6.0)</em></td>
+<td><code>update_metadata</code></td>
+<td>The incremental <code>/Info</code> + XMP rewrite failed.</td>
+</tr>
+<tr>
+<td><code>PRINT_ERROR</code> <em>(v1.6.0)</em></td>
+<td>document tools with <code>print</code></td>
+<td>The requested page boxes are inconsistent (e.g. do not fit <code>pageSize</code>).</td>
+</tr>
+<tr>
+<td><code>CHART_ERROR</code> <em>(v1.6.0)</em></td>
+<td><code>add_chart</code>, <code>chart</code> blocks</td>
+<td>An engine cross-field chart rule failed (the message carries the remedy).</td>
+</tr>
+<tr>
+<td><code>PLACEHOLDER_AMBIGUOUS</code> <em>(v1.6.0)</em></td>
+<td><code>sign_pdf</code></td>
+<td>Several unsigned placeholders exist and no <code>fieldName</code> was given.</td>
+</tr>
+<tr>
+<td><code>SIGNATURE_FIELD_NOT_FOUND</code> <em>(v1.6.0)</em></td>
+<td><code>sign_pdf</code></td>
+<td>The named <code>fieldName</code> does not exist.</td>
+</tr>
+<tr>
+<td><code>CMS_PARSE_FAILED</code> <em>(v1.6.0)</em></td>
+<td><code>verify_pdf</code></td>
+<td>A CMS structure is shorter or more malformed than the parser expects.</td>
+</tr>
+</tbody></table>
+<blockquote>
+<p><strong>Protocol errors</strong> <em>(v1.6.0)</em>: calling an unknown tool or prompt name is now a JSON-RPC <code>-32602</code> error (<code>[UNKNOWN_TOOL]</code> / <code>[UNKNOWN_PROMPT]</code>), not an <code>isError</code> result. Likewise, an unknown or misspelt input key — top-level or nested — fails with <code>VALIDATION_ERROR</code> (&quot;Unrecognized key&quot;) instead of being silently stripped.</p>
+</blockquote>
+<hr>
+<h2 id="the-pdfa-flag">The <code>pdfA</code> flag<a class="heading-anchor" href="#the-pdfa-flag" aria-label="Link to this section">#</a></h2>
+<p>Every document tool (<code>generate_basic_pdf</code>, <code>add_table</code>, <code>add_form</code>, <code>embed_image</code>, <code>add_barcode</code>, <code>prepare_signature_placeholder</code>, <code>add_international_text</code>, <code>add_chart</code> <em>(v1.5.0)</em>) accepts an optional <code>pdfA</code> field. <code>add_attachment</code> is the special case: it always produces <strong>PDF/A-3b</strong> (the only conformance level that allows arbitrary embedded files), so it has no <code>pdfA</code> input.</p>
+<table>
+<thead>
+<tr>
+<th><code>pdfA</code> value</th>
+<th>PDF version</th>
+<th>Notes</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>&quot;pdfa1b&quot;</code></td>
+<td>1.4</td>
+<td>Most conservative — no transparency, no AES</td>
+</tr>
+<tr>
+<td><code>&quot;pdfa2b&quot;</code></td>
+<td>1.7</td>
+<td>Default archive target</td>
+</tr>
+<tr>
+<td><code>&quot;pdfa2u&quot;</code></td>
+<td>1.7</td>
+<td>2b + Unicode mapping for every glyph</td>
+</tr>
+<tr>
+<td><code>&quot;pdfa3b&quot;</code></td>
+<td>1.7</td>
+<td>2b + arbitrary <code>/EmbeddedFile</code> attachments</td>
+</tr>
+</tbody></table>
+<p>When set on <code>add_international_text</code>, the <code>latin</code> font auto-registers so non-WinAnsi Latin characters validate cleanly. Mutually exclusive with the underlying pdfnative encryption layer (ISO 19005-1 §6.3.2).</p>
+<hr>
+<h2 id="output-modes">Output modes<a class="heading-anchor" href="#output-modes" aria-label="Link to this section">#</a></h2>
+<p>Every document-producing tool accepts an <code>outputMode</code> field. The seven read-only
+tools (<code>inspect_pdf</code>, <code>inspect_layout</code>, <code>validate_pdf</code>, <code>verify_pdf</code>, <code>extract_text</code>,
+<code>extract_attachments</code>, <code>read_form_fields</code>) return JSON only and have no
+<code>outputMode</code>:</p>
+<table>
+<thead>
+<tr>
+<th>Mode</th>
+<th>Behaviour</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>&quot;base64&quot;</code> <em>(default)</em></td>
+<td>The PDF bytes are returned inline in the MCP response as a base64 string. Suitable for pipelines that immediately consume or display the bytes.</td>
+</tr>
+<tr>
+<td><code>&quot;file&quot;</code></td>
+<td>The PDF is written to the sandbox directory configured via <code>PDFNATIVE_MCP_OUTPUT_DIR</code>. An <code>outputPath</code> (relative, <code>.pdf</code> extension) is required. <strong>Disabled unless the environment variable is set.</strong></td>
+</tr>
+</tbody></table>
+<blockquote>
+<p><strong>Exception:</strong> <code>draft_governance_issue</code> uses <code>outputMode: &quot;inline&quot; | &quot;file&quot;</code> (not <code>base64</code>) and writes a <strong><code>.md</code></strong> draft — not a PDF — when <code>file</code> mode is selected.</p>
+</blockquote>
+<hr>
+<h2 id="end-to-end-example-signed-document">End-to-end example: signed document<a class="heading-anchor" href="#end-to-end-example-signed-document" aria-label="Link to this section">#</a></h2>
+<p>This workflow uses two tools in sequence:</p>
+<pre><code class="language-jsonc">// Step 1 — create the placeholder
+{
+  &quot;tool&quot;: &quot;prepare_signature_placeholder&quot;,
+  &quot;input&quot;: {
+    &quot;title&quot;:      &quot;Purchase Order #42&quot;,
+    &quot;signerName&quot;: &quot;Jane Smith&quot;,
+    &quot;reason&quot;:     &quot;CFO approval&quot;,
+    &quot;location&quot;:   &quot;London, UK&quot;,
+    &quot;blocks&quot;: [
+      { &quot;type&quot;: &quot;paragraph&quot;, &quot;text&quot;: &quot;Total amount: $128,000&quot; }
+    ],
+    &quot;outputMode&quot;: &quot;base64&quot;
+  }
+}
+
+// Step 2 — sign the returned PDF
+{
+  &quot;tool&quot;: &quot;sign_pdf&quot;,
+  &quot;input&quot;: {
+    &quot;pdfBase64&quot;:            &quot;&lt;result from step 1&gt;&quot;,
+    &quot;algorithm&quot;:            &quot;rsa-sha256&quot;,
+    &quot;certDerBase64&quot;:        &quot;&lt;your DER certificate&gt;&quot;,
+    &quot;rsaKeyPkcs1DerBase64&quot;: &quot;&lt;your PKCS#1 private key&gt;&quot;,
+    &quot;signerName&quot;:           &quot;Jane Smith&quot;,
+    &quot;reason&quot;:               &quot;CFO approval&quot;,
+    &quot;location&quot;:             &quot;London, UK&quot;,
+    &quot;signingTime&quot;:          &quot;2026-04-26T09:00:00Z&quot;,
+    &quot;outputMode&quot;:           &quot;base64&quot;
+  }
+}
+</code></pre>
+<hr>
+<h2 id="security-model">Security model<a class="heading-anchor" href="#security-model" aria-label="Link to this section">#</a></h2>
+<p><code>pdfnative-mcp</code> is designed to run safely inside your AI client:</p>
+<ul>
+<li><strong>No network access by default</strong> — the server opens no outbound connection unless the <strong>operator</strong> configures TSA/OCSP/CRL endpoints for the PAdES tools (see the network charter under <em>Environment variables</em>). URLs never come from tool arguments, and certificate-supplied OCSP/CRL URLs pass an SSRF guard.</li>
+<li><strong>Sandboxed file writes</strong> — <code>file</code> output mode is gated by <code>PDFNATIVE_MCP_OUTPUT_DIR</code>. When unset, file writes are rejected with a <code>SecurityError</code>.</li>
+<li><strong>Path traversal protection</strong> — absolute paths, <code>..</code> sequences, NUL bytes, and non-<code>.pdf</code> extensions are all rejected.</li>
+<li><strong>Output size cap</strong> — PDF output is capped at <strong>50 MiB</strong> per call. <code>split_pdf</code> additionally enforces <strong>50 MiB per part</strong> and a <strong>200 MiB aggregate</strong> ceiling across its parts, returning <code>OUTPUT_TOO_LARGE</code> when exceeded.</li>
+<li><strong>HTTP transport hardening</strong> — when bound to <code>PDFNATIVE_MCP_PORT</code>, the HTTP transport is loopback-only and rejects foreign <code>Host</code> / <code>Origin</code> headers with <strong>403</strong> (DNS-rebinding protection). An opt-in bearer token (<code>PDFNATIVE_MCP_HTTP_TOKEN</code>) adds authentication <em>(v1.6.0)</em> — without it, the loopback endpoint has none.</li>
+<li><strong>Input validation</strong> — every tool validates inputs against strict JSON Schemas and Zod runtime checks at the boundary. Since v1.6.0 every schema is <code>.strict()</code> at every nesting level, so an unknown or misspelt key is a <code>VALIDATION_ERROR</code> instead of being silently stripped, and PEM armour where DER base64 is expected fails with the exact <code>openssl … -outform DER</code> remedy.</li>
+<li><strong>Decompression cap</strong> — the engine&#39;s 100 MiB per-stream inflate cap is operator-tunable via <code>PDFNATIVE_MCP_MAX_INFLATE_BYTES</code> <em>(v1.6.0)</em>.</li>
+</ul>
+<p>See <a href="https://github.com/Nizoka/pdfnative-mcp/blob/main/SECURITY.md" target="_blank" rel="noopener">SECURITY.md</a> for responsible disclosure.</p>
+<hr>
+<h2 id="troubleshooting">Troubleshooting<a class="heading-anchor" href="#troubleshooting" aria-label="Link to this section">#</a></h2>
+<p><strong>The server does not appear in my AI client.</strong><br>Verify that Node.js ≥ 22 is installed (<code>node --version</code>) and that the config file path is correct for your OS. Restart the client after any config change.</p>
+<p><strong><code>file</code> output mode returns a SecurityError.</strong><br>Set the <code>PDFNATIVE_MCP_OUTPUT_DIR</code> environment variable to an existing absolute path in the client config.</p>
+<p><strong><code>add_international_text</code> produces blank text.</strong><br>The Noto fonts ship bundled with <code>pdfnative</code> — no network access is needed. Blank text usually means an unsupported <code>lang</code> code or a corrupted install; check the <code>lang</code> value against the supported list and reinstall <code>pdfnative</code> if needed.</p>
+<p><strong><code>sign_pdf</code> fails with &quot;invalid placeholder&quot;.</strong><br>By default <code>sign_pdf</code> auto-injects a <code>/Sig</code> placeholder when the input has none (<code>autoInjectPlaceholder: true</code>), so this error normally only appears when <code>autoInjectPlaceholder</code> was set to <code>false</code> — either drop that flag or call <code>prepare_signature_placeholder</code> first, and make sure the placeholder PDF was not modified between creation and signing.</p>
+<p><strong>Output PDF exceeds 50 MB.</strong><br>Split the content across multiple tool calls or reduce image/barcode count.</p>
+<hr>
+<h2 id="release-history">Release history<a class="heading-anchor" href="#release-history" aria-label="Link to this section">#</a></h2>
+<p>The current release is <strong>v1.6.0</strong> (28 tools, built on pdfnative 1.7.0 — see the header note). Per-release notes, oldest first:</p>
+<h3 id="whats-new-in-v100">What&#39;s new in v1.0.0<a class="heading-anchor" href="#whats-new-in-v100" aria-label="Link to this section">#</a></h3>
+<p>v1.0.0 is the <strong>first stable release</strong>, built on <code>pdfnative</code> 1.2.0, and commits to API stability via a per-tool <code>_meta.apiVersion</code> field. New fields are optional and backward-compatible — omitting them produces byte-identical output. Tool count: <strong>12</strong> (was 9).</p>
+<ul>
+<li><strong>Three new tools:</strong><ul>
+<li><strong><code>verify_pdf</code></strong> — read-only verification of every PAdES Baseline / <code>adbe.pkcs7.detached</code> signature: recomputes the <code>ByteRange</code> SHA-256, validates the CMS <code>messageDigest</code>, and verifies the <code>signatureValue</code> with the embedded signer certificate (RSA-SHA256 + ECDSA-SHA256 P-256). Optional <code>trustedRootsDerBase64</code> enables chain trust.</li>
+<li><strong><code>add_attachment</code></strong> — generate a <strong>PDF/A-3 (ISO 19005-3)</strong> document with one or more embedded files. Primary use case: <strong>Factur-X / ZUGFeRD</strong> electronic invoices (XML payload with <code>relationship: &#39;Source&#39;</code>). 8 MiB per-file cap.</li>
+<li><strong><code>extract_text</code></strong> — best-effort plain-text extraction from a non-encrypted PDF (operands of <code>Tj</code> / <code>&#39;</code> / <code>&quot;</code> / <code>TJ</code>). Reports <code>extractable: false</code> when a page yields no text; encrypted PDFs are rejected.</li>
+</ul>
+</li>
+<li><strong>Smart-table fields on <code>add_table</code></strong> — <code>wrap</code>, <code>repeatHeader</code>, <code>zebra</code>, <code>caption</code>, <code>minRowHeight</code>, <code>cellPadding</code> (pdfnative 1.2 <code>TableBlock</code> props). Multi-page tables reprint headers and wrap on overflow by default.</li>
+<li><strong>Signing ergonomics</strong> — <code>sign_pdf</code> accepts ECDSA SEC1 / PKCS#8 DER keys and <code>autoInjectPlaceholder: true</code> (default) transparently calls <code>addSignaturePlaceholder()</code> when the input lacks a <code>/Sig</code> widget (one-call signing of any PDF).</li>
+<li><strong><code>inspect_pdf</code></strong> now reports <code>hasSignaturePlaceholder</code> and an <code>attachments[]</code> summary; two new <code>check</code> values: <code>placeholder</code>, <code>attachments</code>. The <code>signed</code> check is now <code>signatureCount &gt; 0 &amp;&amp; !hasSignaturePlaceholder</code>.</li>
+<li><strong>Opt-in result cache</strong> (<code>PDFNATIVE_MCP_CACHE_DIR</code>) — SHA-256 keyed over canonical JSON of <code>{tool, apiVersion, input}</code>, 1 h TTL, 256 MiB LRU. Skips <code>outputMode: &#39;file&#39;</code> calls.</li>
+<li><strong><code>_meta.apiVersion = &#39;1.0.0&#39;</code></strong> and per-tool <strong><code>_meta.examples</code></strong> on every tool listing for AI-agent discovery — anchored to <a href="https://github.com/Nizoka/pdfnative-mcp/blob/main/docs/API_STABILITY.md" target="_blank" rel="noopener"><code>docs/API_STABILITY.md</code></a>.</li>
+<li><strong><code>pdfA</code> flag on every document tool</strong> — values <code>pdfa1b</code>, <code>pdfa2b</code>, <code>pdfa2u</code>, <code>pdfa3b</code>, mapping to pdfnative&#39;s <code>tagged</code> option (spread straight from pdfnative&#39;s exported <code>PDF_A_CONFORMANCE_TARGETS</code>).</li>
+<li><strong>Env-var rename:</strong> the canonical name is <code>PDFNATIVE_MCP_OUTPUT_DIR</code> (was the misspelt <code>PDFNATIVE_MPC_OUTPUT_DIR</code>, which still works as a deprecated alias with a one-shot stderr warning, scheduled for removal in v2.0.0).</li>
+</ul>
+<p><strong>Deferred to v1.1:</strong> <code>merge_pdfs</code>, <code>split_pdf</code>, <code>redact_pdf</code> — require pdfnative page-tree primitives not yet exported.</p>
+<h3 id="whats-new-in-v110">What&#39;s new in v1.1.0<a class="heading-anchor" href="#whats-new-in-v110" aria-label="Link to this section">#</a></h3>
+<p>v1.1.0 upgrades the server to the <code>pdfnative</code> 1.3.0 engine and adds accessibility-first read tooling:</p>
+<ul>
+<li><strong>New tool: <code>validate_pdf</code></strong> — read-only PDF/UA structural conformance checks (ISO 14289-1).</li>
+<li><strong>Six additional scripts</strong> in <code>add_international_text</code>: Telugu (<code>te</code>), Sinhala (<code>si</code>), Tibetan (<code>bo</code>), Khmer (<code>km</code>), Myanmar (<code>my</code>), Ethiopic (<code>am</code>).</li>
+<li><strong>COLRv1 colour emoji support</strong> through the upgraded engine.</li>
+<li><strong>Paragraph newline sanitization</strong> to avoid malformed text blocks when callers send embedded <code>\n</code>.</li>
+</ul>
+<h3 id="whats-new-in-v120">What&#39;s new in v1.2.0<a class="heading-anchor" href="#whats-new-in-v120" aria-label="Link to this section">#</a></h3>
+<p>v1.2.0 keeps full backward compatibility and extends MCP ergonomics for AI workflows:</p>
+<ul>
+<li><strong>New tool: <code>extract_attachments</code></strong> — read embedded files from PDF/A-3 documents (Factur-X / ZUGFeRD round-trip).</li>
+<li><strong>Watermark support</strong> on <code>generate_basic_pdf</code> and <code>add_table</code> (text, opacity, angle, color, position).</li>
+<li><strong>Opt-in Unicode normalization</strong> (<code>normalize</code>: <code>NFC</code> / <code>NFD</code> / <code>NFKC</code> / <code>NFKD</code>) on international/document flows.</li>
+<li><strong>Token-frugal read modes</strong> on read-only tools via <code>verbosity: &#39;summary&#39;</code> and selective <code>fields</code> projection.</li>
+<li><strong>Base64 payload deduplication</strong>: generated bytes are returned once via <code>resource</code> in base64 mode.</li>
+</ul>
+<h3 id="whats-new-in-v130">What&#39;s new in v1.3.0<a class="heading-anchor" href="#whats-new-in-v130" aria-label="Link to this section">#</a></h3>
+<!-- verify-docs:allow version-token (historical release entry) -->
+<p>v1.3.0 upgrades the engine to <strong>pdfnative 1.4.0</strong>, adds a page-tree tool trio, and stays fully backward-compatible — tool count rises to <strong>17</strong>:</p>
+<ul>
+<li><strong>Three new page-tree tools:</strong><ul>
+<li><strong><code>merge_pdfs</code></strong> — concatenate <strong>2–50</strong> source PDFs into one document via pdfnative&#39;s page-tree API. Encrypted sources are rejected; signatures and <code>/AcroForm</code> are dropped (page edits invalidate <code>/ByteRange</code>); self-contained URI <code>/Link</code> annotations are preserved.</li>
+<li><strong><code>split_pdf</code></strong> — split one PDF into one document per page range, returning a <strong>multi-output</strong> shape <code>{ mode, count, totalBytes, parts[] }</code>. Caps: <strong>50 MiB per part</strong>, <strong>200 MiB aggregate</strong>.</li>
+<li><strong><code>extract_pages</code></strong> — pull an arbitrary, order-preserving page subset (<strong>max 5000</strong> pages) into a single PDF.</li>
+</ul>
+</li>
+<li><strong>Enriched authoring options</strong> (from pdfnative 1.4.0): <!-- verify-docs:allow version-token (historical) --><ul>
+<li><code>generate_basic_pdf</code> gains <code>outline</code> (<code>&#39;auto&#39;</code> or an explicit nested tree), <code>pageLabels</code>, <strong>nested <code>list</code> items</strong> (max depth 6), and <code>viewerPreferences</code>.</li>
+<li><code>add_table</code> gains <code>cellBorders</code> (top/right/bottom/left, color, width, style), <code>cellVAlign</code> (<code>&#39;top&#39;</code> / <code>&#39;middle&#39;</code> / <code>&#39;bottom&#39;</code>), and <code>viewerPreferences</code>.</li>
+<li><code>add_international_text</code> gains <code>viewerPreferences</code>.</li>
+</ul>
+</li>
+<li><strong>Constant-time signing</strong> — <code>sign_pdf</code> now signs RSA and EC-DER keys through a per-call <code>node:crypto</code> provider (constant-time) with a transparent pure-JS fallback; pure-scalar <code>ecPrivateScalarHex</code> remains pure-JS.</li>
+<li><strong>HTTP transport hardening</strong> — the <code>PDFNATIVE_MCP_PORT</code> Streamable HTTP transport now rejects foreign <code>Host</code> / <code>Origin</code> headers with <strong>403</strong> (DNS-rebinding protection). <code>serverInfo</code> advertises a human-readable <code>title</code> + <code>description</code> (MCP 2025-11-25 alignment).</li>
+<li><strong>New error codes</strong> on the page-tree tools: <code>ENCRYPTED_SOURCE</code>, <code>OUTPUT_TOO_LARGE</code>, <code>PDF_PARSE_FAILED</code>.</li>
+<li><strong>Spec alignment</strong> — MCP SDK <code>^1.29</code> (2025-11-25 revision), JSON Schema 2020-12, and <code>_meta.apiVersion</code> bumped to <code>1.3.0</code> on every tool.</li>
+</ul>
+<hr>
+<h3 id="whats-new-in-v140">What&#39;s new in v1.4.0<a class="heading-anchor" href="#whats-new-in-v140" aria-label="Link to this section">#</a></h3>
+<p>v1.4.0 upgrades the engine to <strong>pdfnative 1.5.0</strong>, brings the pdfnative <strong>AI-governance / Human-in-the-Loop (HITL)</strong> system to the MCP surface, and adds markup annotations — taking the catalogue to <strong>19 tools</strong> at that release.<!-- verify-docs:allow stale-token (historical: v1.4.0 total) --> Fully backward-compatible: every v1.3.0 call works unchanged and default responses are byte-identical.</p>
+<ul>
+<li><strong>Two new tools:</strong><ul>
+<li><strong><code>draft_governance_issue</code></strong> — an agent drafts a fully compliant GitHub issue <strong>locally</strong> (a draft <code>.md</code> plus a machine-readable <code>compliance</code> report) and stops. The agent is a <strong>draftsman, never an autonomous submitter</strong>: a human is the only gate, and — by construction, not just policy — the server makes <strong>zero</strong> GitHub writes and <strong>no</strong> outbound network call. A draft that proposes a runtime dependency, omits a reproduction, or sets <code>duplicateSearchPerformed: false</code> is rejected with the new <code>GOVERNANCE_VIOLATION</code> error.</li>
+<li><strong><code>annotate_pdf</code></strong> — overlay <code>text</code>, <code>highlight</code>, <code>underline</code>, <code>strikeout</code>, <code>squiggly</code>, <code>square</code>, <code>circle</code>, <code>line</code>, and <code>freetext</code> annotations on an existing PDF via incremental update. A <strong>visual review layer, not a redaction</strong> — the underlying bytes remain. Encrypted sources → <code>ENCRYPTED_SOURCE</code>.</li>
+</ul>
+</li>
+<li><strong>MCP <code>prompts</code> capability</strong> — the server now advertises two prompts: <code>governance_contract</code> (the full HITL contract) and <code>draft_issue_workflow</code> (the step-by-step recipe).</li>
+<li><strong>Page labels in <code>inspect_pdf</code></strong> — read-only surfacing of <code>/PageLabels</code> ranges via a new optional <code>pageLabels[]</code> output field (present only when the PDF declares them).</li>
+<li><strong>Math / scientific script</strong> — <code>add_international_text</code> accepts the explicit <code>math</code> lang (Noto Sans Math), embedded on demand only (e.g. <code>lang: [&#39;latin&#39;, &#39;math&#39;]</code>); there is <strong>no</strong> global auto-routing.</li>
+<li><strong>Engine upgrade</strong> — pdfnative <code>^1.4.0</code> → <code>^1.5.0</code> (additive, no breaking changes); <code>_meta.apiVersion</code> bumped to <code>1.4.0</code> on every tool.</li>
+</ul>
+<blockquote>
+<p><strong><code>redact_pdf</code> is deferred by design.</strong> pdfnative&#39;s annotation writer can only <em>overlay</em> content; an overlay-only “redaction” would leave the original bytes intact and create <strong>false security</strong>. It is intentionally <strong>not</strong> shipped and is tracked as an upstream true content-removal request — a fitting first use of <code>draft_governance_issue</code>.</p>
+</blockquote>
+<h3 id="whats-new-in-v150">What&#39;s new in v1.5.0<a class="heading-anchor" href="#whats-new-in-v150" aria-label="Link to this section">#</a></h3>
+<p>v1.5.0 upgrades the engine to <strong>pdfnative 1.6.0</strong> and takes the catalogue to <strong>24 tools</strong> at that release,<!-- verify-docs:allow stale-token (historical: v1.5.0 total) --> closing the read/modify loop on documents the assistant did not create.</p>
+<ul>
+<li><strong>Five new tools:</strong><ul>
+<li><code>add_chart</code> — bar, horizontal-bar, line, pie and donut charts drawn as <strong>native PDF vector paths</strong>. No rasterisation and no image round-trip, so the output stays sharp at any zoom and tags as <code>/Figure</code> with alt text. If you were previously asking an agent to render a chart to PNG and push it through <code>embed_image</code>, stop — this replaces that.</li>
+<li><code>read_form_fields</code> — list an AcroForm&#39;s fields with types, current values and options.</li>
+<li><code>fill_form</code> — fill values and optionally <code>flatten</code> them into static page content. Works on encrypted documents via incremental update.</li>
+<li><code>encrypt_pdf</code> — re-secure with AES-128 or AES-256, setting owner/user passwords and a permission set.</li>
+<li><code>decrypt_pdf</code> — remove encryption <strong>in-server</strong>, for RC4, AES-128 and AES-256 sources.</li>
+</ul>
+</li>
+<li><strong>Passwords on the read tools.</strong> <code>inspect_pdf</code>, <code>verify_pdf</code>, <code>extract_text</code> and <code>extract_attachments</code> accept a <code>password</code>, as do the page-tree trio. Encrypted sources are no longer rejected outright.</li>
+<li><strong>New error codes:</strong> <code>PASSWORD_REQUIRED</code>, <code>PASSWORD_INVALID</code>, <code>ENCRYPTION_UNSUPPORTED</code>, <code>FORM_FIELD_NOT_FOUND</code>, <code>FORM_VALUE_TYPE_ERROR</code>, <code>FORM_UNSUPPORTED</code>.</li>
+<li><strong>Generated PDFs are exposed as MCP resources</strong> (<code>pdfnative://output/{path}</code>), so a client can list and re-read them without a second tool call. File-mode results carry a <code>resource_link</code>.</li>
+<li><strong>Tool annotations</strong> (<code>readOnlyHint</code>, <code>destructiveHint</code>, <code>idempotentHint</code>, <code>openWorldHint</code>) are published in <code>tools/list</code>, letting a client reason about which calls are safe to retry.</li>
+<li>The encryption tools are deliberately <strong>excluded from the response cache</strong>.</li>
+</ul>
+<h3 id="whats-new-in-v160">What&#39;s new in v1.6.0<a class="heading-anchor" href="#whats-new-in-v160" aria-label="Link to this section">#</a></h3>
+<p>v1.6.0 aligns the server with the <strong>MCP 2026-07-28</strong> specification and grows the catalogue to <strong>28 tools</strong>, exposing the engine&#39;s full document model and completing the PAdES baseline ladder. No breaking changes: every v1.5.0 call keeps its inputs, error codes and response shape, and a superset gate against the published 1.5.0 catalogue proves it.</p>
+<ul>
+<li><strong>Four new tools:</strong><ul>
+<li><code>add_ltv</code> — embed <code>/DSS</code> + <code>/VRI</code> long-term-validation material (PAdES <strong>B-LT</strong>), online through the operator-configured revocation provider or offline from caller-supplied material.</li>
+<li><code>timestamp_pdf</code> — append a <code>/DocTimeStamp</code> through the operator TSA (PAdES <strong>B-LTA</strong>), with auto-suffixed field names for periodic re-timestamping.</li>
+<li><code>update_metadata</code> — rewrite <code>/Info</code> (+ XMP) of an existing PDF as an incremental update.</li>
+<li><code>inspect_layout</code> — a read-only pagination dry run: page count and block positions with no PDF produced.</li>
+</ul>
+</li>
+<li><strong>Full engine coverage</strong> — <code>generate_basic_pdf</code> composes all <strong>13 block kinds</strong> (<code>table</code>, <code>image</code>, <code>link</code>, <code>toc</code>, <code>barcode</code>, <code>svg</code>, <code>formField</code> join the six existing ones); <code>pageSize</code>, <code>margins</code>, running <code>headerTemplate</code> / <code>footerTemplate</code>, <code>compress</code> and <code>debug</code> on the nine document tools; build-time <code>encrypt</code> that <strong>keeps the AcroForm</strong>; image watermarks with <code>position</code>.</li>
+<li><strong>PAdES signing</strong> — <code>sign_pdf</code> gains <code>profile: &#39;pades&#39;</code>, <code>timestamp: true</code> (RFC 3161, B-T), RSA-SHA384/512, <code>certChainDerBase64</code>, <code>fieldName</code> / <code>allowMultiple</code>; <code>verify_pdf ltv: true</code> reports profile, timestamp, embedded revocation status and the achieved level; <code>prepare_signature_placeholder</code> gains <code>subFilter</code> / <code>reserveTimestamp</code> and freezes signer metadata into the <code>/Sig</code> dictionary (fixing a pre-1.7 engine bug where those values were silently dropped).</li>
+<li><strong>Network charter</strong> — still <strong>no outbound request by default</strong>; the single permitted egress class is the operator-configured TSA / OCSP / CRL endpoints, never a URL from a tool argument, behind an SSRF guard. Seven new environment variables configure the HTTP bearer token, the inflate cap and the network providers.</li>
+<li><strong>Print production</strong> — <code>print</code> page boxes, <code>bleed</code>, printer&#39;s <code>marks</code>, <code>/UserUnit</code>, <code>metadata</code> with <code>/Trapped</code>, custom <code>outputIntent</code>; boxes survive the page-tree tools and are reported by <code>inspect_pdf</code>.</li>
+<li><strong>Charts v2</strong> — <code>stackedBar</code> / <code>stackedBarH</code> / <code>area</code> / <code>scatter</code>, per-series <code>xValues</code> with linear or time axes, secondary <code>axis2</code>, <code>axis.scale: &#39;log&#39;</code>, <code>dataLabels</code>, <code>labelStride</code> / <code>labelRotation</code>.</li>
+<li><strong>Honest PDF/A</strong> — <code>embedFonts: true</code> (embed Noto Sans Latin for a claim veraPDF accepts), <code>strict: true</code> (fail instead of emitting a non-conformant file), <code>includeDiagnostics: true</code>; two new diagnostics; an advisory veraPDF corpus runs locally and in CI.</li>
+<li><strong>MCP 2026-07-28 transport</strong> — SDK v2 (<code>@modelcontextprotocol/server</code>), <code>server/discover</code>, <code>resultType</code>, cache hints, per-result <code>serverInfo</code>, deterministic <code>tools/list</code>; 2025-era clients keep working via the automatic legacy fallback.</li>
+<li><strong>Four new recipe prompts</strong> — <code>pades_ladder</code>, <code>print_ready</code>, <code>reproducible_output</code>, <code>pdfa_valid</code> — taking the prompt catalogue to six.</li>
+<li><strong>Reproducible output</strong> — <code>creationDate</code> on all nine document tools, <code>signingTime</code> on the placeholder, <code>modDate</code> on <code>update_metadata</code>.</li>
+</ul>
+<p><strong>Migrating from v1.5.0</strong> — six behaviour changes, all on error paths or on inputs the published schema already declared invalid:</p>
+<ol>
+<li><strong>Stray keys fail.</strong> An unknown or misspelt key, top-level or nested, is now <code>VALIDATION_ERROR</code> (&quot;Unrecognized key&quot;) instead of being silently stripped — the schemas always declared <code>additionalProperties: false</code>.</li>
+<li><strong>Page-index mistakes are <code>VALIDATION_ERROR</code>.</strong> Out-of-range pages / ranges on <code>merge_pdfs</code> / <code>split_pdf</code> / <code>extract_pages</code> were <code>PDF_PARSE_FAILED</code>; the message now carries a 0-based hint.</li>
+<li><strong><code>validate_pdf</code> on unparsable bytes is an error, not a verdict.</strong> v1.5.0 returned <code>{ valid: false }</code>; v1.6.0 returns <code>isError: true</code> <code>[PDF_PARSE_FAILED]</code> — a parse failure is not a PDF/UA verdict.</li>
+<li><strong>Unknown tool or prompt names are protocol errors</strong> — JSON-RPC <code>-32602</code> (<code>[UNKNOWN_TOOL]</code> / <code>[UNKNOWN_PROMPT]</code>), no <code>isError</code> result.</li>
+<li><strong><code>inspect_pdf.checks</code> holds only the keys you asked for</strong> — read <code>checksPassed</code> or the requested key, never an absent one.</li>
+<li><strong><code>add_form</code> text areas change bytes.</strong> <code>fieldType: &#39;textarea&#39;</code> now produces a real multi-line field (<code>/Ff 4096</code>).</li>
+</ol>
+<hr>
+<h2 id="further-reading">Further reading<a class="heading-anchor" href="#further-reading" aria-label="Link to this section">#</a></h2>
+<ul>
+<li><a href="https://github.com/Nizoka/pdfnative-mcp" target="_blank" rel="noopener">pdfnative-mcp on GitHub</a> — source, issues, CHANGELOG</li>
+<li><a href="https://www.npmjs.com/package/pdfnative-mcp" target="_blank" rel="noopener">pdfnative-mcp on npm</a> — version history, install stats</li>
+<li><a href="quickstart.html">pdfnative Quick Start</a> — pdfnative library directly in Node.js / browser</li>
+<li><a href="architecture.html">Architecture guide</a> — how pdfnative-mcp sits in the ecosystem</li>
+<li><a href="https://modelcontextprotocol.io" target="_blank" rel="noopener">Model Context Protocol specification</a> — MCP standard reference</li>
+</ul>
+<!-- guide:render:end -->
   </article>
 </main>
 
diff --git a/docs/guides/mcp.md b/docs/guides/mcp.md
index e068c39..a1d2fb8 100644
--- a/docs/guides/mcp.md
+++ b/docs/guides/mcp.md
@@ -1,6 +1,6 @@
 # pdfnative-mcp — AI Client Integration Guide
 
-> **Tracks the latest published `pdfnative-mcp`** (v1.5.0, built on pdfnative 1.7.0). Full release notes: [pdfnative-mcp releases](https://github.com/Nizoka/pdfnative-mcp/releases). Live package versions — and the `pdfnative` version each one is built on — are shown at the top of the [documentation home](../index.html).
+> **Tracks the latest published `pdfnative-mcp`** (v1.6.0, built on pdfnative 1.7.0). Full release notes: [pdfnative-mcp releases](https://github.com/Nizoka/pdfnative-mcp/releases). Live package versions — and the `pdfnative` version each one is built on — are shown at the top of the [documentation home](../index.html).
 
 [pdfnative-mcp](https://github.com/Nizoka/pdfnative-mcp) is an **MCP server** that exposes the full pdfnative library to any AI client supporting the [Model Context Protocol](https://modelcontextprotocol.io) — Claude Desktop, Cursor, Continue, Zed, ChatGPT, and more.
 
@@ -120,26 +120,38 @@ In your Zed `settings.json`:
 | `PDFNATIVE_MCP_OUTPUT_DIR` | Absolute path to the sandbox directory. **Required to enable `outputMode: "file"`**. When unset, only `base64` output is available. (The misspelt `PDFNATIVE_MPC_OUTPUT_DIR` still works as a deprecated alias.) |
 | `PDFNATIVE_MCP_CACHE_DIR` | Absolute path to enable the persistent SHA-256-keyed result cache (1 h TTL, 256 MiB LRU). When unset, the cache is disabled. |
 | `PDFNATIVE_MCP_PORT` | When set to a valid port (1–65535), starts an HTTP server on `http://127.0.0.1:<port>/mcp` instead of stdio. |
+| `PDFNATIVE_MCP_HTTP_TOKEN` _(v1.6.0)_ | Opt-in bearer token for the HTTP transport (≥ 16 characters, no whitespace — a weaker value aborts startup). When set, `/mcp` requires `Authorization: Bearer <token>`; otherwise requests get `401` + `WWW-Authenticate`. Without it the loopback endpoint has **no authentication**. Never logged. |
+| `PDFNATIVE_MCP_MAX_INFLATE_BYTES` _(v1.6.0)_ | Operator override of the engine's 100 MiB per-stream decompression cap (integer ≥ 1024, read once at startup; an invalid value refuses to start with one clean `fatal:` line). |
+| `PDFNATIVE_MCP_TSA_URL` _(v1.6.0)_ | RFC 3161 timestamp authority endpoint. Required by `sign_pdf timestamp: true` and `timestamp_pdf` (`TSA_NOT_CONFIGURED` otherwise). |
+| `PDFNATIVE_MCP_TSA_AUTH` _(v1.6.0)_ | Optional `Authorization` header value sent to the TSA. Treated as a secret; never logged. |
+| `PDFNATIVE_MCP_REVOCATION` _(v1.6.0)_ | Revocation sources for `add_ltv mode: 'online'` — `ocsp`, `crl`, or `ocsp,crl` (`REVOCATION_NOT_CONFIGURED` otherwise). |
+| `PDFNATIVE_MCP_NETWORK_ALLOWED_HOSTS` _(v1.6.0)_ | Mandatory allow-list of hosts the OCSP/CRL fetcher may contact. A certificate-supplied URL outside the list fails with `NETWORK_HOST_NOT_ALLOWED`. |
+| `PDFNATIVE_MCP_NETWORK_TIMEOUT_MS` _(v1.6.0)_ | Network timeout for TSA/OCSP/CRL requests (1000–120000 ms, default 10000). |
+
+> **Network charter** _(v1.6.0)_. The server still makes **no outbound request by default**. The only egress it can ever perform goes to the TSA / OCSP / CRL endpoints the **operator** configures via the variables above — URLs never come from tool arguments, and certificate-supplied OCSP/CRL URLs pass an SSRF guard (allow-list, http(s) only, no credentials, no redirects, internal address literals rejected, size caps, timeouts).
 
 ---
 
 ## Tool reference
 
-`pdfnative-mcp` exposes **24 tools**:
+`pdfnative-mcp` exposes **28 tools**:
 
 | Tool | Purpose |
 |---|---|
-| `generate_basic_pdf` | Multi-page A4 documents from structured blocks (headings, paragraphs, lists, spacers, charts, page breaks). Accepts optional `pdfA`. |
+| `generate_basic_pdf` | Multi-page documents from structured blocks — all **13 block kinds** since v1.6.0 (headings, paragraphs, lists, tables, images, links, TOC, barcodes, SVG, form fields, charts, page breaks, spacers). Accepts optional `pdfA`, layout options, build-time `encrypt`, and print-production fields. |
 | `add_table` | Tabular PDF reports from column headers and data rows. Optional `autoFitColumns` and `clipCells`. Accepts `pdfA`. |
 | `add_barcode` | QR Code, Code 128, EAN-13, Data Matrix, PDF417 — embedded in a single-page PDF. Accepts `pdfA`. |
-| `add_international_text` | 24 `lang` font codes — the 22 writing systems plus `latin` and `emoji` — with BiDi & OpenType shaping, plus the explicit `math` script (Noto Sans Math, on-demand). `lang` accepts `string`, `string[]`, or comma-separated. |
-| `add_form` | Interactive AcroForm PDFs with text fields, checkboxes, radio buttons, and dropdowns. Accepts `pdfA`. |
-| `embed_image` | Embed a JPEG or PNG image (base64-encoded) into a titled PDF document. Accepts `pdfA`. |
-| `prepare_signature_placeholder` | Create a PDF with a `/Sig` AcroForm placeholder ready to be signed. Accepts `pdfA`. |
-| `sign_pdf` | PAdES-style CMS digital signatures (RSA-SHA256 / ECDSA-SHA256 P-256). |
-| `inspect_pdf` | Read-only inspection. Returns `version`, `pageCount`, `encryption`, `pdfA`, `signatureCount`, `info`, optional `perPage`, optional `pageLabels[]` (when `/PageLabels` is declared), optional `checks` + `checksPassed`. |
+| `add_international_text` | 25 `lang` font codes — the 22 writing systems plus `latin`, `emoji` and the explicit `math` script (Noto Sans Math, on-demand) — with BiDi & OpenType shaping. `lang` accepts `string`, `string[]`, or comma-separated. |
+| `add_form` | Interactive AcroForm PDFs with text fields, text areas, checkboxes, radio buttons, dropdowns, and list boxes _(v1.6.0)_. Accepts `pdfA`. |
+| `embed_image` | Embed a JPEG or PNG image (base64-encoded) into a titled PDF document, with `align` and `alt` _(v1.6.0)_. Accepts `pdfA`. |
+| `prepare_signature_placeholder` | Create a PDF with a `/Sig` AcroForm placeholder ready to be signed; `subFilter`, `reserveTimestamp` and frozen signer metadata _(v1.6.0)_. Accepts `pdfA`. |
+| `sign_pdf` | PAdES CMS digital signatures — RSA-SHA256/384/512 and ECDSA-SHA256 P-256, `profile: 'pades'`, RFC 3161 `timestamp` (B-T), certificate chains, named fields and multiple signatures _(v1.6.0)_. |
+| `add_ltv` _(v1.6.0)_ | Embed long-term-validation material (`/DSS` + `/VRI`) into a signed PDF — PAdES **B-LT** — online through the operator-configured revocation provider or offline from caller-supplied material. |
+| `timestamp_pdf` _(v1.6.0)_ | Append a `/DocTimeStamp` (ETSI.RFC3161) through the operator TSA — PAdES **B-LTA** — with auto-suffixed field names for periodic re-timestamping. |
+| `inspect_pdf` | Read-only inspection. Returns `version`, `pageCount`, `encryption`, `pdfA`, `signatureCount`, `info`, optional `perPage`, optional `pageLabels[]`, and — _(v1.6.0)_ — an optional `signatures[]` inventory, `annotations[]`, page boxes + `userUnit`, `dss` / `docTimestampCount` / `trapped`, plus `checks` + `checksPassed`. |
+| `inspect_layout` _(v1.6.0)_ | Read-only pagination **dry run** — page count, page geometry and each block's position for a prospective document, with no PDF produced. |
 | `validate_pdf` | Read-only PDF/UA structural validation (`valid`, `errors`, `warnings`). |
-| `verify_pdf` | Real CMS/PKCS#7 signature verification — RSA & ECDSA, message digest, certificate chain. (RFC 3161 timestamp validation is a `pdfnative-cli verify` feature, not part of this server.) |
+| `verify_pdf` | Real CMS/PKCS#7 signature verification — RSA & ECDSA, message digest, certificate chain. Since v1.6.0, `/DocTimeStamp` entries are verified as RFC 3161 tokens and `ltv: true` reports the achieved PAdES level (B-B → B-LTA). |
 | `add_attachment` | Embed files (e.g. Factur-X / ZUGFeRD e-invoice XML) into PDF/A-3b output. |
 | `extract_attachments` | Extract embedded files from an existing PDF (optionally metadata-only). |
 | `extract_text` | Extract text content from an existing PDF via the native parser. |
@@ -148,13 +160,14 @@ In your Zed `settings.json`:
 | `extract_pages` | Pull an arbitrary, order-preserving page subset (max 5000) into a single PDF. |
 | `annotate_pdf` | Overlay markup annotations (text / highlight / underline / strikeout / squiggly / square / circle / line / freetext) on an existing PDF via incremental update. A visual review layer, **not** a redaction. |
 | `draft_governance_issue` | Assemble a governance-compliant GitHub-issue draft plus a structured `compliance` report **locally** — network-free by construction; never submits. |
-| `add_chart` _(v1.5.0)_ | Render a bar, horizontal-bar, line, pie or donut chart as **native PDF vector paths** — no rasterisation and no image round-trip. Tagged as `/Figure` with alt text when `pdfA` is set. |
+| `add_chart` _(v1.5.0)_ | Render a chart as **native PDF vector paths** — nine types since v1.6.0 (`bar`, `barH`, `stackedBar`, `stackedBarH`, `line`, `area`, `scatter`, `pie`, `donut`), with a secondary axis, log and time scales, and data labels. Tagged as `/Figure` with alt text when `pdfA` is set. |
 | `read_form_fields` _(v1.5.0)_ | List an existing AcroForm's fields with their types, current values and available options — the read half of the fill round-trip. Accepts `password`. |
 | `fill_form` _(v1.5.0)_ | Fill AcroForm field values and optionally `flatten` them into static page content. Works on encrypted PDFs via incremental update. |
 | `encrypt_pdf` _(v1.5.0)_ | Re-secure an existing PDF with AES-128 or AES-256 — owner/user passwords and an explicit permission set. |
 | `decrypt_pdf` _(v1.5.0)_ | Remove encryption from a password-protected PDF **in-server** — RC4, AES-128 and AES-256 sources. |
+| `update_metadata` _(v1.6.0)_ | Rewrite an existing PDF's `/Info` dictionary (+ XMP) — title, author, subject, keywords, pinned `modDate` — as a non-destructive incremental update. |
 
-Every tool now publishes an `outputSchema` advertised in `tools/list` per the [MCP 2025-06-18 spec](https://modelcontextprotocol.io/specification/2025-06-18), enabling clients to statically validate responses.
+Every tool publishes an `outputSchema` advertised in `tools/list`. Since v1.6.0 the server speaks the [MCP 2026-07-28 spec](https://modelcontextprotocol.io/specification/2026-07-28) (stateless envelope, `server/discover`, `resultType`, cache hints) on SDK v2, while 2025-era clients (2025-11-25 / 2025-06-18 / 2025-03-26) keep working through the automatic legacy fallback.
 
 ---
 
@@ -177,7 +190,17 @@ Produces a multi-page document from a list of content blocks.
 }
 ```
 
-**Block types supported:** `heading` (levels 1–3), `paragraph`, `list` (`bullet` / `numbered`, nested items to depth 6), `pageBreak`, `spacer` (`height` in points), and `chart` (same body as `add_chart`).
+**Block types supported:** all **13 engine block kinds** since v1.6.0 — `heading` (levels 1–3), `paragraph`, `list` (`bullet` / `numbered`, nested items to depth 6), `table`, `image`, `link` (`http:` / `https:` / `mailto:` only), `toc` (a contents page with internal `/GoTo` links, pairs with `outline: 'auto'`), `barcode`, `svg` (a safe subset: paths, shapes and text — no XML parser, no external reference ever fetched), `formField`, `chart` (same body as `add_chart`), `pageBreak`, and `spacer` (`height` in points). The `table` / `image` / `barcode` / `formField` blocks share their body with the dedicated tools, so a standalone artefact and an inline block validate and render identically.
+
+**Layout options** _(v1.6.0)_, available on all nine document tools: `pageSize` (`A4` default, `Letter`, `Legal`, `A3`, `Tabloid`), `margins` (all four sides, 0–200 pt), running `headerTemplate` / `footerTemplate` (`left` / `center` / `right` zones with `{page}` `{pages}` `{title}` `{date}` placeholders — a `footerTemplate` replaces the default footer, so `footerText` is then ignored), `compress`, and `debug`.
+
+**Build-time `encrypt`** _(v1.6.0)_, on `generate_basic_pdf`, `add_table`, `add_form`, `add_international_text`, `embed_image`, `add_barcode` and `add_chart`: AES-128 (default) or AES-256 with owner/user passwords and permissions — and unlike `encrypt_pdf`, it **keeps the AcroForm**, making encrypted fillable forms reachable. Exclusive with `pdfA` (ISO 19005-1 §6.3.2); never cached.
+
+**Print production** _(v1.6.0)_, on the nine document tools: `print` (TrimBox / BleedBox / ArtBox / CropBox, a `bleed` shorthand, crop + registration `marks`, `/UserUnit`), `metadata` (`/Author`, `/Subject`, `/Keywords`, `/Trapped` with XMP parity), and `outputIntent` (custom RGB ICC profile). `viewerPreferences` gains `duplex`, `pickTrayByPDFSize`, `printPageRange` (1-based), `numCopies`. Boxes survive `merge_pdfs` / `split_pdf` / `extract_pages` and are reported by `inspect_pdf`.
+
+**Honest PDF/A** _(v1.6.0)_: text rendered through the viewer's base-14 Helvetica is not embedded, so a PDF/A claim on such a file is rejected by veraPDF. `embedFonts: true` embeds Noto Sans Latin for a valid claim; `strict: true` fails instead of producing a non-conformant file; `includeDiagnostics: true` echoes the engine's diagnostics (`PDFA_NO_FONT_ENTRIES`, `PDFA_UNEMBEDDED_FORM_FONT`, `PDFA_DEVICE_CMYK_IMAGE`).
+
+**Reproducible output** _(v1.6.0)_: `creationDate` (ISO-8601) on all nine document tools pins `/Info /CreationDate`, the XMP dates and therefore the trailer `/ID` — byte-identical output on the same host time zone.
 
 ---
 
@@ -261,7 +284,7 @@ Creates an interactive AcroForm PDF.
 }
 ```
 
-**Field types:** `text`, `textarea`, `checkbox`, `radio`, `dropdown`.
+**Field types:** `text`, `textarea`, `checkbox`, `radio`, `dropdown`, and `listbox` _(v1.6.0)_. Text fields accept an optional `placeholder` _(v1.6.0)_. Since v1.6.0, `textarea` maps to the engine's true multi-line field (`/Ff 4096`) — in v1.5.0 it rendered as a single-line widget.
 
 ---
 
@@ -280,6 +303,8 @@ Creates an interactive AcroForm PDF.
 
 > **Note:** Alpha-channel PNGs (color type 6) are not supported. Pre-process such images to remove the alpha channel before embedding.
 
+Since v1.6.0 the tool also accepts `align` (horizontal placement) and `alt` (accessibility text written as `/Figure /Alt` in tagged output).
+
 ---
 
 ### `prepare_signature_placeholder`
@@ -299,6 +324,8 @@ Creates a PDF pre-wired with an AcroForm `/Sig` field, ready to be signed by `si
 }
 ```
 
+Since v1.6.0 the placeholder also takes `subFilter`, `reserveTimestamp` (extra `/Contents` room for a later RFC 3161 token), `placeholderBytes`, and `signingTime` — and the signer metadata (`signerName`, `reason`, `location`, `contactInfo`, `signingTime`) is **baked into the `/Sig` dictionary at placeholder time**, fixing a pre-1.7 engine bug where those values never reached the signed document.
+
 ---
 
 ### `sign_pdf`
@@ -320,6 +347,17 @@ Signs any PDF. When the input already contains a `/Sig` placeholder (e.g. produc
 
 For ECDSA P-256: use `"algorithm": "ecdsa-sha256"` and supply either `ecPrivateScalarHex` (64 hex chars, raw scalar `d`) or `ecPrivateKeyDerBase64` (SEC1 / PKCS#8 DER, base64 — signed through the constant-time `node:crypto` path) instead of `rsaKeyPkcs1DerBase64`. The two EC inputs are mutually exclusive.
 
+**PAdES and timestamps** _(v1.6.0)_:
+
+- `algorithm` also accepts `rsa-sha384` and `rsa-sha512`.
+- `profile: 'pades'` produces an ETSI.CAdES.detached signature (PAdES **B-B**).
+- `timestamp: true` requests an RFC 3161 timestamp from the operator-configured TSA (`PDFNATIVE_MCP_TSA_URL`) and embeds it in the CMS — PAdES **B-T**. Fails with `TSA_NOT_CONFIGURED` when no TSA is set, `TSA_REJECTED` when the authority declines.
+- `certChainDerBase64` embeds intermediate certificates alongside the signer certificate.
+- `fieldName` targets a specific `/Sig` field (`SIGNATURE_FIELD_NOT_FOUND` when absent, `PLACEHOLDER_AMBIGUOUS` when several placeholders exist and none is named); `allowMultiple: true` adds a signature next to existing ones instead of rejecting.
+- The default placeholder reservation is now `max(16384, estimated CMS size)` — plus 8192 bytes when `timestamp: true` — instead of a flat 16384 bytes. To pin it exactly, build the placeholder with `prepare_signature_placeholder` and its `placeholderBytes` input.
+
+To climb the rest of the PAdES ladder, follow with [`add_ltv`](#add_ltv-v160) (B-LT) and [`timestamp_pdf`](#timestamp_pdf-v160) (B-LTA), then check the achieved level with `verify_pdf ltv: true`. The server's `pades_ladder` prompt walks through the full recipe.
+
 ---
 
 ### `inspect_pdf`
@@ -337,12 +375,14 @@ Read-only PDF inspection over `openPdf()`. Never modifies the input.
 **Inputs:**
 - `pdfBase64` — base64 PDF bytes (required).
 - `password` — password for an encrypted PDF *(v1.5.0)*.
-- `pages` — when `true`, includes per-page `index`, `width`, `height`.
-- `check` — array of CI assertions. Allowed values: `pdfa`, `signed`, `encrypted`, `placeholder`, `attachments`. The response includes `checks` (per-assertion result) and `checksPassed` (boolean AND).
+- `pages` — when `true`, includes per-page `index`, `width`, `height` — and, since v1.6.0, the declared page boxes and `userUnit`.
+- `signatures` *(v1.6.0)* — when `true`, a per-signature inventory: `subFilter`, `isDocTimestamp`, `isPlaceholder`, `byteRange`, `vriKey`.
+- `annotations` *(v1.6.0)* — when `true`, an `annotations[]` list (0-based `page`, `subtype`, `rect`, and when present `contents`, `title`, `color`, `quadPoints`, link `url`) plus `annotationCount`.
+- `check` — array of CI assertions. Allowed values: `pdfa`, `signed`, `encrypted`, `placeholder`, `attachments`, and — *(v1.6.0)* — `dss`, `docTimestamp`, `trapped`, `annotations`. The response includes `checks` (per-assertion result) and `checksPassed` (boolean AND). Since v1.6.0, `checks` contains **only the requested keys**.
 - `verbosity` — `'full'` (default) or `'summary'` (token-frugal scalar subset).
 - `fields` — optional dot-path projection of the result.
 
-**Outputs:** `version`, `pageCount`, `encryption` (`'none'` / `'aes-128'` / `'aes-256'` / `'rc4'` / `'unknown'`), optional `encryptionInfo` (`{ algorithm, revision, authenticatedAs }`, present when the document is encrypted and opened successfully), `pdfA` (`null` or the detected claim string), `signatureCount`, `hasSignaturePlaceholder`, `attachments[]` (embedded-file summaries), `info` (decoded `/Info` entries), optional `perPage[]`, optional `pageLabels[]` (when `/PageLabels` is declared), optional `checks` + `checksPassed`.
+**Outputs:** `version`, `pageCount`, `encryption` (`'none'` / `'aes-128'` / `'aes-256'` / `'rc4'` / `'unknown'`), optional `encryptionInfo` (`{ algorithm, revision, authenticatedAs }`, present when the document is encrypted and opened successfully), `pdfA` (`null` or the detected claim string), `signatureCount`, `hasSignaturePlaceholder`, `attachments[]` (embedded-file summaries), `info` (decoded `/Info` entries), optional `perPage[]`, optional `pageLabels[]` (when `/PageLabels` is declared), optional `checks` + `checksPassed` — plus, presence-gated since v1.6.0, `dss`, `docTimestampCount` and `trapped`.
 
 Useful in CI as a final assertion step before publishing a PDF artifact:
 
@@ -444,7 +484,7 @@ Assembles a governance-compliant GitHub-issue draft plus a structured `complianc
 
 ### `add_chart` _(v1.5.0)_
 
-Renders a bar, horizontal-bar, line, pie or donut chart as **native PDF vector paths** — no rasterisation, no image round-trip. Multi-series bar/line, legends, gridlines and negative values are supported; the chart is tagged `/Figure` with `/Alt` (auto-generated when `altText` is omitted).
+Renders a chart as **native PDF vector paths** — no rasterisation, no image round-trip. Multi-series bar/line, legends, gridlines and negative values are supported; the chart is tagged `/Figure` with `/Alt` (auto-generated when `altText` is omitted).
 
 ```jsonc
 {
@@ -457,7 +497,9 @@ Renders a bar, horizontal-bar, line, pie or donut chart as **native PDF vector p
 }
 ```
 
-**Inputs:** `chartType` (`bar` / `barH` / `line` / `pie` / `donut`) and `series` (required; pie/donut take exactly one series), plus `title`, `legend` (`'bottom'` / `'none'`), `markers` (line series), `colors` (hex palette override), `altText`, `intro` (paragraph above the chart), `pdfA`, `outputMode` / `outputPath`. For a chart amongst headings/paragraphs/tables, use a `chart` block inside `generate_basic_pdf` — both build identical pdfnative blocks.
+**Inputs:** `chartType` (`bar` / `barH` / `line` / `pie` / `donut`, plus — _(v1.6.0)_ — `stackedBar` / `stackedBarH` / `area` / `scatter`) and `series` (required; pie/donut take exactly one series), plus `title`, `legend` (`'bottom'` / `'none'`), `markers` (line series), `colors` (hex palette override), `altText`, `intro` (paragraph above the chart), `pdfA`, `outputMode` / `outputPath`. For a chart amongst headings/paragraphs/tables, use a `chart` block inside `generate_basic_pdf` — both build identical pdfnative blocks.
+
+**Charts v2** _(v1.6.0)_: per-series `xValues` with `xAxis.type: 'linear' | 'time'` (UTC-deterministic time axes), a secondary right axis (`axis2`), `axis.scale: 'log'`, `dataLabels`, and `labelStride` / `labelRotation` for crowded x labels. Engine cross-field rules surface as `CHART_ERROR` with a remedy.
 
 ### `read_form_fields` _(v1.5.0)_
 
@@ -517,22 +559,101 @@ Opens an encrypted PDF (RC4, AES-128 or AES-256) and emits an unencrypted copy *
 
 > The rebuild drops signatures and `/AcroForm`. To *read* an encrypted PDF without rebuilding it, pass `password` to `inspect_pdf` / `extract_text` / `extract_attachments` instead. Excluded from the response cache.
 
+### `add_ltv` _(v1.6.0)_
+
+Embeds long-term-validation material — a `/DSS` (Document Security Store) with `/VRI` entries — into an already-signed PDF via incremental update, taking a PAdES B-T document to **B-LT**.
+
+```jsonc
+{
+  "pdfBase64": "<base64 signed PDF>",
+  "mode": "online",
+  "preferOcsp": true,
+  "outputMode": "base64"
+}
+```
+
+**Inputs:** `pdfBase64` (required), `mode` (`'online'` default — fetches OCSP responses / CRLs through the operator-configured revocation provider; `'offline'` — embeds parse-validated caller-supplied material), `preferOcsp`, `certificatesDerBase64[]` / `ocspResponsesDerBase64[]` / `crlsDerBase64[]` (offline material), `outputMode` / `outputPath`. The structured result includes a `summary` of what was embedded.
+
+**Errors:** `LTV_NO_SIGNATURE` (nothing to validate), `LTV_EMPTY` (no material gathered), `LTV_MATERIAL_INVALID`, `LTV_ERROR`, `REVOCATION_NOT_CONFIGURED` (online mode without `PDFNATIVE_MCP_REVOCATION`), `NETWORK_HOST_NOT_ALLOWED`, `NETWORK_ERROR`, `ENCRYPTED_SOURCE` (decrypting would destroy the signatures — sign before encrypting).
+
+> Online mode is the **only** network-touching path in the server besides the TSA, and it only ever contacts operator-allow-listed hosts. See *Environment variables* above.
+
+### `timestamp_pdf` _(v1.6.0)_
+
+Appends a `/DocTimeStamp` signature field (ETSI.RFC3161) through the operator-configured TSA, taking a B-LT document to **B-LTA**. The token's status, message imprint and nonce are checked before embedding; its own CMS signature is verified by `verify_pdf`.
+
+```jsonc
+{
+  "pdfBase64": "<base64 signed PDF>",
+  "outputMode": "base64"
+}
+```
+
+**Inputs:** `pdfBase64` (required), `fieldName` (auto-suffixed `DocTimeStamp1`, `DocTimeStamp2`, … when omitted — supporting periodic re-timestamping), `placeholderBytes` (4096–65536), `outputMode` / `outputPath`.
+
+**Errors:** `TSA_NOT_CONFIGURED`, `TSA_REJECTED`, `NETWORK_ERROR`, `ENCRYPTED_SOURCE`.
+
+### `update_metadata` _(v1.6.0)_
+
+Rewrites an existing PDF's `/Info` dictionary — and its XMP packet when present — via a non-destructive **incremental update**, so earlier revisions stay a byte-exact prefix.
+
+```jsonc
+{
+  "pdfBase64": "<base64 PDF bytes>",
+  "title": "Quarterly Report — Final",
+  "author": "Finance Team",
+  "keywords": "finance, Q1, 2026",
+  "modDate": "2026-08-25T09:00:00+02:00",
+  "outputMode": "base64"
+}
+```
+
+**Inputs:** `pdfBase64` (required), `title`, `author`, `subject`, `keywords` (≤ 1000 characters), `modDate` (ISO-8601 with offset — pinned for reproducible bytes), `outputMode` / `outputPath`.
+
+**Errors:** `ENCRYPTED_SOURCE` (use `decrypt_pdf` → `update_metadata` → `encrypt_pdf`), `METADATA_ERROR`, `PDF_PARSE_FAILED`.
+
+### `inspect_layout` _(v1.6.0)_
+
+A read-only pagination **dry run**: measures how a prospective document would paginate — without producing a PDF and without consuming output tokens on base64 bytes. The seventh read tool with `verbosity` / `fields`.
+
+```jsonc
+{
+  "title": "Q1 2026 Report",
+  "blocks": [
+    { "type": "heading", "text": "Executive Summary", "level": 1 },
+    { "type": "paragraph", "text": "Revenue grew 24 % year over year." }
+  ],
+  "verbosity": "summary"
+}
+// → { "pageWidth": 595.28, "pageHeight": 841.89, "totalPages": 1, "blockCount": 2 }
+```
+
+**Inputs:** `title` and `blocks` (required), plus every input that moves a block — `footerText`, `pdfA`, `normalize`, `embedFonts`, `pageSize`, `margins`, `headerTemplate`, `footerTemplate` — and `verbosity` / `fields`.
+
+**Outputs (full):** `pageWidth`, `pageHeight`, `margins`, `totalPages`, and `pages[].blocks[]` with each block's `type`, `page`, `x`, `top`, `width`, `height` (2-decimal points).
+
+> **Known engine gap:** a `toc` block is measured as 0 pt, so a document with a printed contents page may paginate one page later than previewed.
+
 ---
 
 ## MCP prompts
 
-Since v1.4.0 the server advertises the MCP **`prompts`** capability with two prompts, sourced from the same governance contract the tools enforce:
+Since v1.4.0 the server advertises the MCP **`prompts`** capability; v1.6.0 grows it to **six prompts** — the two governance prompts plus four recipe prompts:
 
 | Prompt | Purpose |
 |---|---|
 | `governance_contract` | The full AI-governance / Human-in-the-Loop contract. |
 | `draft_issue_workflow` | The step-by-step recipe for producing a compliant issue draft with `draft_governance_issue`. |
+| `pades_ladder` _(v1.6.0)_ | The B-B → B-T → B-LT → B-LTA recipe: `sign_pdf` → `add_ltv` → `timestamp_pdf`, verified with `verify_pdf ltv: true`. |
+| `print_ready` _(v1.6.0)_ | Producing press-ready output: bleed, printer's marks, custom OutputIntent. |
+| `reproducible_output` _(v1.6.0)_ | Byte-stable output via pinned `creationDate` / `signingTime` / `modDate`. |
+| `pdfa_valid` _(v1.6.0)_ | Producing a PDF/A file that veraPDF actually accepts (`embedFonts`, `strict`, diagnostics). |
 
 ## Error codes
 
 | `code` | Raised by | Meaning / fix |
 |---|---|---|
-| `ENCRYPTED_SOURCE` | `annotate_pdf` | The source PDF is encrypted; `annotate_pdf` has no `password` parameter (nor do `sign_pdf` and `validate_pdf`). Use `decrypt_pdf` first (note: that rebuild drops signatures/forms), or pass `password` to the tools that accept it. |
+| `ENCRYPTED_SOURCE` | `annotate_pdf`, `update_metadata`, `add_ltv`, `timestamp_pdf` | The source PDF is encrypted and the tool has no `password` parameter. Remedies are tool-specific since v1.6.0: for `annotate_pdf` / `update_metadata`, `decrypt_pdf` → edit → `encrypt_pdf`; for `add_ltv` / `timestamp_pdf`, decrypting would destroy the signatures — sign before encrypting. |
 | `PASSWORD_REQUIRED` *(v1.5.0)* | password-aware tools (`inspect_pdf`, `verify_pdf`, `extract_text`, `extract_attachments`, `read_form_fields`, `fill_form`, page-tree trio, `encrypt_pdf`, `decrypt_pdf`) | The source is encrypted and no `password` was supplied. |
 | `PASSWORD_INVALID` *(v1.5.0)* | password-aware tools | The supplied `password` does not open the document. |
 | `ENCRYPTION_UNSUPPORTED` *(v1.5.0)* | password-aware tools | The document uses an encryption scheme the reader does not support. |
@@ -542,6 +663,20 @@ Since v1.4.0 the server advertises the MCP **`prompts`** capability with two pro
 | `OUTPUT_TOO_LARGE` | PDF-emitting tools | An emitted PDF exceeds 50 MiB (for `split_pdf`, also the 200 MiB aggregate), or assembly exceeds `maxOutputSizeBytes` (default 256 MiB). |
 | `PDF_PARSE_FAILED` | page-tree tools | The source bytes are not a parseable PDF. |
 | `GOVERNANCE_VIOLATION` | `draft_governance_issue` | The draft breaks the AI-governance contract (proposes a runtime dependency, omits a reproduction, or `duplicateSearchPerformed: false`). Fix the draft and retry. |
+| `TSA_NOT_CONFIGURED` *(v1.6.0)* | `sign_pdf` (`timestamp: true`), `timestamp_pdf` | No `PDFNATIVE_MCP_TSA_URL` is set. Configure the TSA in the server environment. |
+| `TSA_REJECTED` *(v1.6.0)* | `sign_pdf`, `timestamp_pdf` | The timestamp authority declined the request. |
+| `REVOCATION_NOT_CONFIGURED` *(v1.6.0)* | `add_ltv` (`mode: 'online'`) | No `PDFNATIVE_MCP_REVOCATION` sources are set. Configure them, or use `mode: 'offline'` with caller-supplied material. |
+| `NETWORK_HOST_NOT_ALLOWED` *(v1.6.0)* | `add_ltv` | A certificate-supplied OCSP/CRL URL points outside `PDFNATIVE_MCP_NETWORK_ALLOWED_HOSTS`. |
+| `NETWORK_ERROR` *(v1.6.0)* | TSA/LTV tools | The TSA/OCSP/CRL request failed (timeout, refusal, size cap). |
+| `LTV_NO_SIGNATURE` / `LTV_EMPTY` / `LTV_MATERIAL_INVALID` / `LTV_ERROR` *(v1.6.0)* | `add_ltv` | No signature to validate / no material gathered / supplied DER material does not parse / embedding failed. |
+| `METADATA_ERROR` *(v1.6.0)* | `update_metadata` | The incremental `/Info` + XMP rewrite failed. |
+| `PRINT_ERROR` *(v1.6.0)* | document tools with `print` | The requested page boxes are inconsistent (e.g. do not fit `pageSize`). |
+| `CHART_ERROR` *(v1.6.0)* | `add_chart`, `chart` blocks | An engine cross-field chart rule failed (the message carries the remedy). |
+| `PLACEHOLDER_AMBIGUOUS` *(v1.6.0)* | `sign_pdf` | Several unsigned placeholders exist and no `fieldName` was given. |
+| `SIGNATURE_FIELD_NOT_FOUND` *(v1.6.0)* | `sign_pdf` | The named `fieldName` does not exist. |
+| `CMS_PARSE_FAILED` *(v1.6.0)* | `verify_pdf` | A CMS structure is shorter or more malformed than the parser expects. |
+
+> **Protocol errors** *(v1.6.0)*: calling an unknown tool or prompt name is now a JSON-RPC `-32602` error (`[UNKNOWN_TOOL]` / `[UNKNOWN_PROMPT]`), not an `isError` result. Likewise, an unknown or misspelt input key — top-level or nested — fails with `VALIDATION_ERROR` ("Unrecognized key") instead of being silently stripped.
 
 ---
 
@@ -562,8 +697,8 @@ When set on `add_international_text`, the `latin` font auto-registers so non-Win
 
 ## Output modes
 
-Every document-producing tool accepts an `outputMode` field. The read-only
-tools (`inspect_pdf`, `validate_pdf`, `verify_pdf`, `extract_text`,
+Every document-producing tool accepts an `outputMode` field. The seven read-only
+tools (`inspect_pdf`, `inspect_layout`, `validate_pdf`, `verify_pdf`, `extract_text`,
 `extract_attachments`, `read_form_fields`) return JSON only and have no
 `outputMode`:
 
@@ -619,12 +754,13 @@ This workflow uses two tools in sequence:
 
 `pdfnative-mcp` is designed to run safely inside your AI client:
 
-- **No network access** — the server does not open outbound connections.
+- **No network access by default** — the server opens no outbound connection unless the **operator** configures TSA/OCSP/CRL endpoints for the PAdES tools (see the network charter under *Environment variables*). URLs never come from tool arguments, and certificate-supplied OCSP/CRL URLs pass an SSRF guard.
 - **Sandboxed file writes** — `file` output mode is gated by `PDFNATIVE_MCP_OUTPUT_DIR`. When unset, file writes are rejected with a `SecurityError`.
 - **Path traversal protection** — absolute paths, `..` sequences, NUL bytes, and non-`.pdf` extensions are all rejected.
 - **Output size cap** — PDF output is capped at **50 MiB** per call. `split_pdf` additionally enforces **50 MiB per part** and a **200 MiB aggregate** ceiling across its parts, returning `OUTPUT_TOO_LARGE` when exceeded.
-- **HTTP transport hardening** — when bound to `PDFNATIVE_MCP_PORT`, the Streamable HTTP transport is loopback-only and rejects foreign `Host` / `Origin` headers with **403** (DNS-rebinding protection).
-- **Input validation** — every tool validates inputs against strict JSON Schemas and Zod runtime checks at the boundary.
+- **HTTP transport hardening** — when bound to `PDFNATIVE_MCP_PORT`, the HTTP transport is loopback-only and rejects foreign `Host` / `Origin` headers with **403** (DNS-rebinding protection). An opt-in bearer token (`PDFNATIVE_MCP_HTTP_TOKEN`) adds authentication _(v1.6.0)_ — without it, the loopback endpoint has none.
+- **Input validation** — every tool validates inputs against strict JSON Schemas and Zod runtime checks at the boundary. Since v1.6.0 every schema is `.strict()` at every nesting level, so an unknown or misspelt key is a `VALIDATION_ERROR` instead of being silently stripped, and PEM armour where DER base64 is expected fails with the exact `openssl … -outform DER` remedy.
+- **Decompression cap** — the engine's 100 MiB per-stream inflate cap is operator-tunable via `PDFNATIVE_MCP_MAX_INFLATE_BYTES` _(v1.6.0)_.
 
 See [SECURITY.md](https://github.com/Nizoka/pdfnative-mcp/blob/main/SECURITY.md) for responsible disclosure.
 
@@ -651,7 +787,7 @@ Split the content across multiple tool calls or reduce image/barcode count.
 
 ## Release history
 
-The current release is **v1.5.0** (24 tools, built on pdfnative 1.7.0 — see the header note). Per-release notes, oldest first:
+The current release is **v1.6.0** (28 tools, built on pdfnative 1.7.0 — see the header note). Per-release notes, oldest first:
 
 ### What's new in v1.0.0
 
@@ -726,7 +862,7 @@ v1.4.0 upgrades the engine to **pdfnative 1.5.0**, brings the pdfnative **AI-gov
 
 ### What's new in v1.5.0
 
-v1.5.0 upgrades the engine to **pdfnative 1.7.0** and takes the catalogue to **24 tools**, closing the read/modify loop on documents the assistant did not create.
+v1.5.0 upgrades the engine to **pdfnative 1.6.0** and takes the catalogue to **24 tools** at that release,<!-- verify-docs:allow stale-token (historical: v1.5.0 total) --> closing the read/modify loop on documents the assistant did not create.
 
 - **Five new tools:**
   - `add_chart` — bar, horizontal-bar, line, pie and donut charts drawn as **native PDF vector paths**. No rasterisation and no image round-trip, so the output stays sharp at any zoom and tags as `/Figure` with alt text. If you were previously asking an agent to render a chart to PNG and push it through `embed_image`, stop — this replaces that.
@@ -740,6 +876,34 @@ v1.5.0 upgrades the engine to **pdfnative 1.7.0** and takes the catalogue to **2
 - **Tool annotations** (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) are published in `tools/list`, letting a client reason about which calls are safe to retry.
 - The encryption tools are deliberately **excluded from the response cache**.
 
+### What's new in v1.6.0
+
+v1.6.0 aligns the server with the **MCP 2026-07-28** specification and grows the catalogue to **28 tools**, exposing the engine's full document model and completing the PAdES baseline ladder. No breaking changes: every v1.5.0 call keeps its inputs, error codes and response shape, and a superset gate against the published 1.5.0 catalogue proves it.
+
+- **Four new tools:**
+  - `add_ltv` — embed `/DSS` + `/VRI` long-term-validation material (PAdES **B-LT**), online through the operator-configured revocation provider or offline from caller-supplied material.
+  - `timestamp_pdf` — append a `/DocTimeStamp` through the operator TSA (PAdES **B-LTA**), with auto-suffixed field names for periodic re-timestamping.
+  - `update_metadata` — rewrite `/Info` (+ XMP) of an existing PDF as an incremental update.
+  - `inspect_layout` — a read-only pagination dry run: page count and block positions with no PDF produced.
+- **Full engine coverage** — `generate_basic_pdf` composes all **13 block kinds** (`table`, `image`, `link`, `toc`, `barcode`, `svg`, `formField` join the six existing ones); `pageSize`, `margins`, running `headerTemplate` / `footerTemplate`, `compress` and `debug` on the nine document tools; build-time `encrypt` that **keeps the AcroForm**; image watermarks with `position`.
+- **PAdES signing** — `sign_pdf` gains `profile: 'pades'`, `timestamp: true` (RFC 3161, B-T), RSA-SHA384/512, `certChainDerBase64`, `fieldName` / `allowMultiple`; `verify_pdf ltv: true` reports profile, timestamp, embedded revocation status and the achieved level; `prepare_signature_placeholder` gains `subFilter` / `reserveTimestamp` and freezes signer metadata into the `/Sig` dictionary (fixing a pre-1.7 engine bug where those values were silently dropped).
+- **Network charter** — still **no outbound request by default**; the single permitted egress class is the operator-configured TSA / OCSP / CRL endpoints, never a URL from a tool argument, behind an SSRF guard. Seven new environment variables configure the HTTP bearer token, the inflate cap and the network providers.
+- **Print production** — `print` page boxes, `bleed`, printer's `marks`, `/UserUnit`, `metadata` with `/Trapped`, custom `outputIntent`; boxes survive the page-tree tools and are reported by `inspect_pdf`.
+- **Charts v2** — `stackedBar` / `stackedBarH` / `area` / `scatter`, per-series `xValues` with linear or time axes, secondary `axis2`, `axis.scale: 'log'`, `dataLabels`, `labelStride` / `labelRotation`.
+- **Honest PDF/A** — `embedFonts: true` (embed Noto Sans Latin for a claim veraPDF accepts), `strict: true` (fail instead of emitting a non-conformant file), `includeDiagnostics: true`; two new diagnostics; an advisory veraPDF corpus runs locally and in CI.
+- **MCP 2026-07-28 transport** — SDK v2 (`@modelcontextprotocol/server`), `server/discover`, `resultType`, cache hints, per-result `serverInfo`, deterministic `tools/list`; 2025-era clients keep working via the automatic legacy fallback.
+- **Four new recipe prompts** — `pades_ladder`, `print_ready`, `reproducible_output`, `pdfa_valid` — taking the prompt catalogue to six.
+- **Reproducible output** — `creationDate` on all nine document tools, `signingTime` on the placeholder, `modDate` on `update_metadata`.
+
+**Migrating from v1.5.0** — six behaviour changes, all on error paths or on inputs the published schema already declared invalid:
+
+1. **Stray keys fail.** An unknown or misspelt key, top-level or nested, is now `VALIDATION_ERROR` ("Unrecognized key") instead of being silently stripped — the schemas always declared `additionalProperties: false`.
+2. **Page-index mistakes are `VALIDATION_ERROR`.** Out-of-range pages / ranges on `merge_pdfs` / `split_pdf` / `extract_pages` were `PDF_PARSE_FAILED`; the message now carries a 0-based hint.
+3. **`validate_pdf` on unparsable bytes is an error, not a verdict.** v1.5.0 returned `{ valid: false }`; v1.6.0 returns `isError: true` `[PDF_PARSE_FAILED]` — a parse failure is not a PDF/UA verdict.
+4. **Unknown tool or prompt names are protocol errors** — JSON-RPC `-32602` (`[UNKNOWN_TOOL]` / `[UNKNOWN_PROMPT]`), no `isError` result.
+5. **`inspect_pdf.checks` holds only the keys you asked for** — read `checksPassed` or the requested key, never an absent one.
+6. **`add_form` text areas change bytes.** `fieldType: 'textarea'` now produces a real multi-line field (`/Ff 4096`).
+
 ---
 
 ## Further reading
diff --git a/docs/guides/onboarding.html b/docs/guides/onboarding.html
index d09060d..64427cd 100644
--- a/docs/guides/onboarding.html
+++ b/docs/guides/onboarding.html
@@ -1,87 +1,198 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>Onboarding — pdfnative, CLI, MCP &amp; React</title>
-  <meta name="description" content="30-second start for the full pdfnative ecosystem — the library, pdfnative-cli, pdfnative-mcp, and pdfnative-react. Install, first call, and where to go next.">
-  <meta name="robots" content="index, follow">
-  <link rel="canonical" href="https://pdfnative.dev/guides/onboarding.html">
-  <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/onboarding.html">
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Onboarding — pdfnative, CLI, MCP &amp; React</title>
+  <meta name="description" content="30-second start for the full pdfnative ecosystem — the library, pdfnative-cli, pdfnative-mcp, and pdfnative-react. Install, first call, and where to go next.">
+  <meta name="robots" content="index, follow">
+  <link rel="canonical" href="https://pdfnative.dev/guides/onboarding.html">
+  <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/onboarding.html">
   <link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/onboarding.html">
-  <link rel="alternate" type="text/markdown" href="onboarding.md">
-  <meta property="og:type" content="article">
-  <meta property="og:site_name" content="pdfnative">
+  <link rel="alternate" type="text/markdown" href="onboarding.md">
+  <link rel="alternate" type="text/plain" href="../llms.txt" title="llms.txt — machine-readable documentation index">
+  <meta property="og:type" content="article">
+  <meta property="og:site_name" content="pdfnative">
   <meta property="og:locale" content="en_US">
-  <meta property="og:url" content="https://pdfnative.dev/guides/onboarding.html">
-  <meta property="og:title" content="Onboarding — pdfnative, CLI, MCP &amp; React">
-  <meta property="og:description" content="30-second start for the full pdfnative ecosystem — the library, pdfnative-cli, pdfnative-mcp, and pdfnative-react. Install, first call, and where to go next.">
-  <meta property="og:image" content="https://pdfnative.dev/assets/og-image.png">
-  <meta property="og:image:width" content="1200">
-  <meta property="og:image:height" content="630">
-  <meta name="twitter:card" content="summary_large_image">
-  <meta name="twitter:title" content="Onboarding — pdfnative, CLI, MCP &amp; React">
-  <meta name="twitter:description" content="30-second start for the full pdfnative ecosystem — library, CLI, MCP, and React. Install, first call, and where to go next.">
-  <meta name="twitter:image" content="https://pdfnative.dev/assets/og-image.png">
-  <link rel="icon" type="image/svg+xml" href="../favicon.svg">
-  <link rel="stylesheet" href="../style.css">
-  <link rel="stylesheet" href="guide.css">
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
-</head>
-<body>
-
-<a class="skip-link" href="#main-content">Skip to main content</a>
-
-<nav class="nav" role="navigation" aria-label="Main navigation">
-  <div class="nav-inner">
-    <a class="nav-brand" href="../">
-      <img src="../assets/logo.svg" alt="" width="28" height="28">
-      pdfnative
-    </a>
-    <button class="nav-hamburger" aria-label="Toggle menu" aria-expanded="false">☰</button>
-    <ul class="nav-links" role="list">
-      <li><a href="../#features">Features</a></li>
-      <li><a href="../#examples">Examples</a></li>
-      <li><a href="../#demo">Demo</a></li>
-      <li><a href="../#mcp">MCP</a></li>
-      <li><a href="../#cli">CLI</a></li>
-      <li><a href="../#react">React</a></li>
-      <li><a href="../learn/">Learn</a></li>
-      <li><a href="./">Guides</a></li>
-      <li><a href="../playgrounds/">Playgrounds</a></li>
-      <li><a href="../responsibility.html">Responsibility</a></li>
-      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
-      <li><button class="theme-toggle" aria-label="Toggle dark mode">🌙</button></li>
-    </ul>
-  </div>
-</nav>
-
-<main class="guide-shell" id="main-content" tabindex="-1">
-  <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; Onboarding</p>
-  <article id="guide-content" class="guide-content" data-md="onboarding.md">
-    <p class="guide-loading">Loading…</p>
-    <noscript><p>This guide is written in Markdown: <a href="onboarding.md">read onboarding.md</a>.</p></noscript>
-  </article>
-</main>
-
-<footer class="footer">
-  <div class="footer-inner">
-    <span>MIT License · © 2026 Nizoka</span>
-    <ul class="footer-links" role="list">
-      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
-      <li><a href="https://www.npmjs.com/package/pdfnative" target="_blank" rel="noopener">npm</a></li>
-      <li><a href="https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md" target="_blank" rel="noopener">Changelog</a></li>
-      <li><a href="./">All guides</a></li>
-    </ul>
-  </div>
-</footer>
-
-<script src="https://cdn.jsdelivr.net/npm/marked@12.0.2/marked.min.js" integrity="sha384-/TQbtLCAerC3jgaim+N78RZSDYV7ryeoBCVqTuzRrFec2akfBkHS7ACQ3PQhvMVi" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/dompurify@3.1.5/dist/purify.min.js" integrity="sha384-nszIONF2FGC59kn+pPFaRa6WUNGwsZgXZiJxJwQbym+TzcH7smolUviLgpPbNx7V" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/prism.min.js" integrity="sha384-BGaNxfftg+9+TtC098wxawPFVEUpKYvaiCgbB0iqAMjK/4jDdmUY+oGxrPNvnXEf" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-typescript.min.js" integrity="sha384-PeOqKNW/piETaCg8rqKFy+Pm6KEk7e36/5YZE5XO/OaFdO+/Aw3O8qZ9qDPKVUgx" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-bash.min.js" integrity="sha384-9WmlN8ABpoFSSHvBGGjhvB3E/D8UkNB9HpLJjBQFC2VSQsM1odiQDv4NbEo+7l15" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-json.min.js" integrity="sha384-RhrmFFMb0ZCHImjFMpR/UE3VEtIVTCtNrtKQqXCzqXZNJala02N3UbVhi+qzw3CY" crossorigin="anonymous" defer></script>
-<script src="guide.js" defer></script>
-</body>
-</html>
+  <meta property="og:url" content="https://pdfnative.dev/guides/onboarding.html">
+  <meta property="og:title" content="Onboarding — pdfnative, CLI, MCP &amp; React">
+  <meta property="og:description" content="30-second start for the full pdfnative ecosystem — the library, pdfnative-cli, pdfnative-mcp, and pdfnative-react. Install, first call, and where to go next.">
+  <meta property="og:image" content="https://pdfnative.dev/assets/og-image.png">
+  <meta property="og:image:width" content="1200">
+  <meta property="og:image:height" content="630">
+  <meta name="twitter:card" content="summary_large_image">
+  <meta name="twitter:title" content="Onboarding — pdfnative, CLI, MCP &amp; React">
+  <meta name="twitter:description" content="30-second start for the full pdfnative ecosystem — library, CLI, MCP, and React. Install, first call, and where to go next.">
+  <meta name="twitter:image" content="https://pdfnative.dev/assets/og-image.png">
+  <link rel="icon" type="image/svg+xml" href="../favicon.svg">
+  <link rel="stylesheet" href="../style.css">
+  <link rel="stylesheet" href="guide.css">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
+  <!-- guide:ld:start -->
+  <script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://pdfnative.dev/"},{"@type":"ListItem","position":2,"name":"Guides","item":"https://pdfnative.dev/guides/"},{"@type":"ListItem","position":3,"name":"Onboarding — the pdfnative ecosystem in 90 seconds","item":"https://pdfnative.dev/guides/onboarding.html"}]},{"@type":"TechArticle","headline":"Onboarding — the pdfnative ecosystem in 90 seconds","description":"30-second start for the full pdfnative ecosystem — the library, pdfnative-cli, pdfnative-mcp, and pdfnative-react. Install, first call, and where to go next.","inLanguage":"en","author":{"@type":"Organization","name":"Nizoka","url":"https://github.com/Nizoka"},"publisher":{"@type":"Organization","name":"pdfnative","url":"https://pdfnative.dev","logo":{"@type":"ImageObject","url":"https://pdfnative.dev/assets/logo.svg"}},"mainEntityOfPage":{"@type":"WebPage","@id":"https://pdfnative.dev/guides/onboarding.html"},"isPartOf":{"@type":"WebSite","name":"pdfnative","url":"https://pdfnative.dev"}}]}</script>
+  <!-- guide:ld:end -->
+</head>
+<body>
+
+<a class="skip-link" href="#main-content">Skip to main content</a>
+
+<nav class="nav" role="navigation" aria-label="Main navigation">
+  <div class="nav-inner">
+    <a class="nav-brand" href="../">
+      <img src="../assets/logo.svg" alt="" width="28" height="28">
+      pdfnative
+    </a>
+    <button class="nav-hamburger" aria-label="Toggle menu" aria-expanded="false">☰</button>
+    <ul class="nav-links" role="list">
+      <li><a href="../#features">Features</a></li>
+      <li><a href="../#examples">Examples</a></li>
+      <li><a href="../#demo">Demo</a></li>
+      <li><a href="../#mcp">MCP</a></li>
+      <li><a href="../#cli">CLI</a></li>
+      <li><a href="../#react">React</a></li>
+      <li><a href="../learn/">Learn</a></li>
+      <li><a href="./">Guides</a></li>
+      <li><a href="../playgrounds/">Playgrounds</a></li>
+      <li><a href="../responsibility.html">Responsibility</a></li>
+      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
+      <li><button class="theme-toggle" aria-label="Toggle dark mode">🌙</button></li>
+    </ul>
+  </div>
+</nav>
+
+<main class="guide-shell" id="main-content" tabindex="-1">
+  <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; Onboarding</p>
+  <article id="guide-content" class="guide-content" data-md="onboarding.md" data-prerendered="true">
+<!-- guide:render:start -->
+<h1 id="onboarding--the-pdfnative-ecosystem-in-90-seconds">Onboarding — the pdfnative ecosystem in 90 seconds</h1>
+<blockquote>
+<p><strong>Pick your entry point:</strong> the library for code, the CLI for shell scripts, MCP for AI assistants, and React for declarative JSX. They all produce the same ISO 32000-1 / PDF/A-conformant PDFs from the same zero-dependency engine. Live versions for every package are shown at the top of the <a href="../index.html">documentation home</a>.</p>
+</blockquote>
+<hr>
+<h2 id="1-library-node-browser-deno-bun--30-seconds">1. Library (Node, browser, Deno, Bun) — 30 seconds<a class="heading-anchor" href="#1-library-node-browser-deno-bun--30-seconds" aria-label="Link to this section">#</a></h2>
+<pre><code class="language-bash">npm install pdfnative
+</code></pre>
+<pre><code class="language-ts">import { buildDocumentPDFBytes, registerFont, loadFontData } from &#39;pdfnative&#39;;
+
+// Optional: enable a non-Latin script — register under the script code (&#39;ar&#39;),
+// then load the data and pass it via fontEntries (registration alone is a no-op):
+registerFont(&#39;ar&#39;, () =&gt; import(&#39;pdfnative/fonts/noto-arabic-data.js&#39;));
+const ar = await loadFontData(&#39;ar&#39;);
+if (!ar) throw new Error(&#39;Arabic font failed to load&#39;);
+
+// Synchronous — returns a Uint8Array, not a Promise.
+const bytes = buildDocumentPDFBytes({
+  title: &#39;Hello pdfnative&#39;,              // top-level, not inside metadata
+  metadata: { author: &#39;Me&#39; },            // author / subject / keywords only
+  blocks: [
+    { type: &#39;heading&#39;, text: &#39;Hello pdfnative&#39;, level: 1 },
+    { type: &#39;paragraph&#39;, text: &#39;Pure native PDF, zero runtime dependencies.&#39; },
+  ],
+  fontEntries: [{ fontData: ar, fontRef: &#39;/F3&#39;, lang: &#39;ar&#39; }], // /F1 and /F2 are reserved
+  layout: { tagged: &#39;pdfa2b&#39; },          // optional PDF/A-2b
+});
+
+// In Node: await fs.writeFile(&#39;out.pdf&#39;, bytes);
+// In browser: new Blob([bytes], { type: &#39;application/pdf&#39; });
+</code></pre>
+<p>Next: <a href="quickstart.html">Quick Start →</a> · <a href="architecture.html">Architecture →</a> · <a href="pdfa.html">PDF/A conformance →</a></p>
+<hr>
+<h2 id="2-cli--30-seconds">2. CLI — 30 seconds<a class="heading-anchor" href="#2-cli--30-seconds" aria-label="Link to this section">#</a></h2>
+<pre><code class="language-bash">npm install -g pdfnative-cli   # or: npx pdfnative-cli ...
+</code></pre>
+<blockquote>
+<p>The package is named <code>pdfnative-cli</code>, but the binary it puts on your PATH is
+<strong><code>pdfnative</code></strong>. Under <code>npx</code>, either name works.</p>
+</blockquote>
+<pre><code class="language-bash"># Check the environment first — the fastest way to confirm the install worked
+pdfnative doctor
+
+# Render a JSON document → PDF. Input and output are flags, not positionals;
+# with neither, render reads stdin and writes stdout.
+pdfnative render --input doc.json --output out.pdf --tagged pdfa2b
+
+# Sign it (auto-injects a signature placeholder if needed)
+pdfnative sign --input out.pdf --output signed.pdf \
+  --key signer.key --cert signer.crt --algorithm rsa-sha256
+
+# Verify the embedded CMS signature
+pdfnative verify --input signed.pdf --json
+</code></pre>
+<p>Iteration helpers: <code>--watch</code> re-renders on save, <code>--template</code> injects variables, <code>--font</code> enables any of the 22 bundled scripts + colour emoji + the math font. v1.1.0 added <code>--stream-true</code>, <code>inspect --pdfua</code> (accessibility gate), and an agent-native <code>--json</code>/<code>E_*</code>/<code>--dry-run</code> contract; v1.2.0 added page-tree <code>merge</code> / <code>split</code> / <code>extract</code>, markup <code>annotate</code>, an AI-governance <code>govern</code> gate, and <code>render --outline</code> / <code>--font math</code> / <code>--inspect-layout</code>; <strong>v1.3.0</strong> adds <code>fill</code>, <code>encrypt</code>, <code>decrypt</code>, <code>extract-text</code> and <code>doctor</code>, native <code>chart</code> blocks in <code>render</code>, passwords on the page-tree commands, and PowerShell completion.</p>
+<blockquote>
+<p><strong>Upgrading from v1.2.0?</strong> <code>render --encrypt</code> was a silent no-op in that
+release — documents you thought were encrypted were written in the clear.
+v1.3.0 fixes it and unifies the flags under <code>--encrypt</code> / <code>--owner-password</code> /
+<code>--user-password</code> / <code>--permissions</code>. Re-run any affected job.</p>
+</blockquote>
+<p>Next: <a href="cli.html">CLI guide →</a> · <a href="../playgrounds/cli.html">CLI playground →</a></p>
+<hr>
+<h2 id="3-mcp-claude-desktop-cursor-continue-zed--30-seconds">3. MCP (Claude Desktop, Cursor, Continue, Zed) — 30 seconds<a class="heading-anchor" href="#3-mcp-claude-desktop-cursor-continue-zed--30-seconds" aria-label="Link to this section">#</a></h2>
+<pre><code class="language-bash">npm install -g pdfnative-mcp
+</code></pre>
+<p>Add the server to your client config — Claude Desktop example (<code>~/Library/Application Support/Claude/claude_desktop_config.json</code> on macOS):</p>
+<pre><code class="language-json">{
+  &quot;mcpServers&quot;: {
+    &quot;pdfnative&quot;: {
+      &quot;command&quot;: &quot;npx&quot;,
+      &quot;args&quot;: [&quot;-y&quot;, &quot;pdfnative-mcp&quot;]
+    }
+  }
+}
+</code></pre>
+<p>Then prompt your assistant:</p>
+<blockquote>
+<p><em>Create a PDF/A-2b invoice for ACME Inc, add a multilingual paragraph in Arabic, and sign it with my key.</em></p>
+</blockquote>
+<p>The assistant calls <code>generate_basic_pdf</code> (with <code>pdfA: &quot;pdfa2b&quot;</code>), then <code>add_international_text</code> (with <code>lang: [&quot;ar&quot;, &quot;emoji&quot;]</code>), <code>add_table</code>, <code>sign_pdf</code>, and finally <code>inspect_pdf</code> — confirming the result. v1.6.0 ships <strong>28 tools</strong>, including the complete PAdES ladder (<code>sign_pdf</code> with RFC 3161 timestamps, <code>add_ltv</code>, <code>timestamp_pdf</code>), the page-tree trio <code>merge_pdfs</code>, <code>split_pdf</code>, <code>extract_pages</code>, markup <code>annotate_pdf</code>, <code>update_metadata</code>, the read-only <code>inspect_layout</code> pagination preview, the network-free <code>draft_governance_issue</code>, plus <code>validate_pdf</code>, <code>verify_pdf</code>, <code>add_attachment</code>, <code>extract_attachments</code>, and <code>extract_text</code>.</p>
+<p>Next: <a href="mcp.html">MCP guide →</a> · <a href="../playgrounds/mcp.html">MCP playground →</a></p>
+<hr>
+<h2 id="4-react-nextjs-remix-any-react-19-app--30-seconds">4. React (Next.js, Remix, any React 19 app) — 30 seconds<a class="heading-anchor" href="#4-react-nextjs-remix-any-react-19-app--30-seconds" aria-label="Link to this section">#</a></h2>
+<pre><code class="language-bash">npm install pdfnative-react pdfnative react
+</code></pre>
+<pre><code class="language-tsx">import { Document, Heading, Text, Table, renderToBytes } from &#39;pdfnative-react&#39;;
+
+const bytes = renderToBytes(
+  &lt;Document title=&quot;Invoice #1024&quot; footerText=&quot;Acme Inc&quot;&gt;
+    &lt;Heading level={1}&gt;Invoice #1024&lt;/Heading&gt;
+    &lt;Text&gt;Thank you for your business.&lt;/Text&gt;
+    &lt;Table headers={[&#39;Item&#39;, &#39;Total&#39;]} rows={[{ cells: [&#39;Pro plan&#39;, &#39;$49.00&#39;], type: &#39;default&#39;, pointed: false }]} zebra /&gt;
+  &lt;/Document&gt;,
+); // → Uint8Array, a valid PDF
+</code></pre>
+<p>A custom React reconciler compiles your JSX to pdfnative blocks on-device — no DOM, no headless browser. Preview live with the <code>usePdf</code> hook / <code>PDFViewer</code>, or let AI agents author with the token-frugal <code>DocSpec</code>. <strong>React 19 is a peer dependency of <code>pdfnative-react</code> only</strong> — the engine stays zero-dependency.</p>
+<p>Next: <a href="react.html">React guide →</a> · <a href="../playgrounds/react.html">React playground →</a></p>
+<hr>
+<h2 id="what-to-read-next">What to read next<a class="heading-anchor" href="#what-to-read-next" aria-label="Link to this section">#</a></h2>
+<ul>
+<li>New to PDFs in code? Start with <a href="quickstart.html">Quick Start</a> and <a href="architecture.html">Architecture</a>.</li>
+<li>Need accessible / archive-grade output? Read <a href="accessibility.html">Accessibility</a> and <a href="pdfa.html">PDF/A conformance</a>.</li>
+<li>Hit a snag? See <a href="troubleshooting.html">Troubleshooting</a> and the <a href="faq.html">FAQ</a>.</li>
+<li>Curious about the trade-offs? The <a href="faq.html">FAQ</a> compares pdfnative with pdfkit, jsPDF, and pdf-lib.</li>
+</ul>
+<p>If pdfnative saved you time, a ⭐ on <a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a> helps others find it. Thanks!</p>
+<!-- guide:render:end -->
+  </article>
+</main>
+
+<footer class="footer">
+  <div class="footer-inner">
+    <span>MIT License · © 2026 Nizoka</span>
+    <ul class="footer-links" role="list">
+      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
+      <li><a href="https://www.npmjs.com/package/pdfnative" target="_blank" rel="noopener">npm</a></li>
+      <li><a href="https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md" target="_blank" rel="noopener">Changelog</a></li>
+      <li><a href="./">All guides</a></li>
+    </ul>
+  </div>
+</footer>
+
+<script src="https://cdn.jsdelivr.net/npm/marked@12.0.2/marked.min.js" integrity="sha384-/TQbtLCAerC3jgaim+N78RZSDYV7ryeoBCVqTuzRrFec2akfBkHS7ACQ3PQhvMVi" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/dompurify@3.1.5/dist/purify.min.js" integrity="sha384-nszIONF2FGC59kn+pPFaRa6WUNGwsZgXZiJxJwQbym+TzcH7smolUviLgpPbNx7V" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/prism.min.js" integrity="sha384-BGaNxfftg+9+TtC098wxawPFVEUpKYvaiCgbB0iqAMjK/4jDdmUY+oGxrPNvnXEf" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-typescript.min.js" integrity="sha384-PeOqKNW/piETaCg8rqKFy+Pm6KEk7e36/5YZE5XO/OaFdO+/Aw3O8qZ9qDPKVUgx" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-bash.min.js" integrity="sha384-9WmlN8ABpoFSSHvBGGjhvB3E/D8UkNB9HpLJjBQFC2VSQsM1odiQDv4NbEo+7l15" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-json.min.js" integrity="sha384-RhrmFFMb0ZCHImjFMpR/UE3VEtIVTCtNrtKQqXCzqXZNJala02N3UbVhi+qzw3CY" crossorigin="anonymous" defer></script>
+<script src="guide.js" defer></script>
+</body>
+</html>
diff --git a/docs/guides/onboarding.md b/docs/guides/onboarding.md
index 7c906ba..9332cd3 100644
--- a/docs/guides/onboarding.md
+++ b/docs/guides/onboarding.md
@@ -98,7 +98,7 @@ Then prompt your assistant:
 
 > *Create a PDF/A-2b invoice for ACME Inc, add a multilingual paragraph in Arabic, and sign it with my key.*
 
-The assistant calls `generate_basic_pdf` (with `pdfA: "pdfa2b"`), then `add_international_text` (with `lang: ["ar", "emoji"]`), `add_table`, `sign_pdf`, and finally `inspect_pdf` — confirming the result. v1.4.0 ships **24 tools**, including the page-tree trio `merge_pdfs`, `split_pdf`, `extract_pages`, markup `annotate_pdf`, the network-free `draft_governance_issue`, plus `validate_pdf`, `verify_pdf`, `add_attachment`, `extract_attachments`, and `extract_text`.
+The assistant calls `generate_basic_pdf` (with `pdfA: "pdfa2b"`), then `add_international_text` (with `lang: ["ar", "emoji"]`), `add_table`, `sign_pdf`, and finally `inspect_pdf` — confirming the result. v1.6.0 ships **28 tools**, including the complete PAdES ladder (`sign_pdf` with RFC 3161 timestamps, `add_ltv`, `timestamp_pdf`), the page-tree trio `merge_pdfs`, `split_pdf`, `extract_pages`, markup `annotate_pdf`, `update_metadata`, the read-only `inspect_layout` pagination preview, the network-free `draft_governance_issue`, plus `validate_pdf`, `verify_pdf`, `add_attachment`, `extract_attachments`, and `extract_text`.
 
 Next: [MCP guide →](mcp.html) · [MCP playground →](../playgrounds/mcp.html)
 
diff --git a/docs/guides/outlines.html b/docs/guides/outlines.html
index 911858e..c6d32ac 100644
--- a/docs/guides/outlines.html
+++ b/docs/guides/outlines.html
@@ -1,85 +1,286 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>Outlines & page labels — pdfnative</title>
-  <meta name="description" content="Add a navigable bookmark tree (/Outlines) and logical page numbering (/PageLabels) to PDFs with pdfnative — auto outline from headings, roman front matter, prefixed appendices. New in v1.4.0.">
-  <link rel="canonical" href="https://pdfnative.dev/guides/outlines.html">
-  <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/outlines.html">
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Outlines & page labels — pdfnative</title>
+  <meta name="description" content="Add a navigable bookmark tree (/Outlines) and logical page numbering (/PageLabels) to PDFs with pdfnative — auto outline from headings, roman front matter, prefixed appendices. New in v1.4.0.">
+  <link rel="canonical" href="https://pdfnative.dev/guides/outlines.html">
+  <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/outlines.html">
   <link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/outlines.html">
-  <link rel="alternate" type="text/markdown" href="outlines.md">
-  <meta property="og:type" content="article">
-  <meta property="og:site_name" content="pdfnative">
+  <link rel="alternate" type="text/markdown" href="outlines.md">
+  <link rel="alternate" type="text/plain" href="../llms.txt" title="llms.txt — machine-readable documentation index">
+  <meta property="og:type" content="article">
+  <meta property="og:site_name" content="pdfnative">
   <meta property="og:locale" content="en_US">
-  <meta property="og:url" content="https://pdfnative.dev/guides/outlines.html">
-  <meta property="og:title" content="Outlines & page labels — pdfnative">
-  <meta property="og:description" content="Add a navigable bookmark tree (/Outlines) and logical page numbering (/PageLabels) to PDFs with pdfnative. New in v1.4.0.">
-  <meta property="og:image" content="https://pdfnative.dev/assets/og-image.png">
-  <meta property="og:image:width" content="1200">
-  <meta property="og:image:height" content="630">
-  <meta name="twitter:card" content="summary_large_image">
-  <meta name="twitter:title" content="Outlines & page labels — pdfnative">
-  <meta name="twitter:description" content="Bookmark tree (/Outlines) and logical page numbering (/PageLabels) — auto outline from headings, roman front matter, prefixed appendices.">
-  <meta name="twitter:image" content="https://pdfnative.dev/assets/og-image.png">
-  <link rel="icon" type="image/svg+xml" href="../favicon.svg">
-  <link rel="stylesheet" href="../style.css">
-  <link rel="stylesheet" href="guide.css">
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
-</head>
-<body>
-
-<a class="skip-link" href="#main-content">Skip to main content</a>
-
-<nav class="nav" role="navigation" aria-label="Main navigation">
-  <div class="nav-inner">
-    <a class="nav-brand" href="../">
-      <img src="../assets/logo.svg" alt="" width="28" height="28">
-      pdfnative
-    </a>
-    <button class="nav-hamburger" aria-label="Toggle menu" aria-expanded="false">☰</button>
-    <ul class="nav-links" role="list">
-      <li><a href="../#features">Features</a></li>
-      <li><a href="../#examples">Examples</a></li>
-      <li><a href="../#demo">Demo</a></li>
-      <li><a href="../#mcp">MCP</a></li>
-      <li><a href="../#cli">CLI</a></li>
-      <li><a href="../#react">React</a></li>
-      <li><a href="../learn/">Learn</a></li>
-      <li><a href="./">Guides</a></li>
-      <li><a href="../playgrounds/">Playgrounds</a></li>
-      <li><a href="../responsibility.html">Responsibility</a></li>
-      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
-      <li><button class="theme-toggle" aria-label="Toggle dark mode">🌙</button></li>
-    </ul>
-  </div>
-</nav>
-
-<main class="guide-shell" id="main-content" tabindex="-1">
-  <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; Outlines & page labels</p>
-  <article id="guide-content" class="guide-content" data-md="outlines.md">
-    <p class="guide-loading">Loading…</p>
-    <noscript><p>This guide is written in Markdown: <a href="outlines.md">read outlines.md</a>.</p></noscript>
-  </article>
-</main>
-
-<footer class="footer">
-  <div class="footer-inner">
-    <span>MIT License · © 2026 Nizoka</span>
-    <ul class="footer-links" role="list">
-      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
-      <li><a href="https://www.npmjs.com/package/pdfnative" target="_blank" rel="noopener">npm</a></li>
-      <li><a href="https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md" target="_blank" rel="noopener">Changelog</a></li>
-      <li><a href="./">All guides</a></li>
-    </ul>
-  </div>
-</footer>
-
-<script src="https://cdn.jsdelivr.net/npm/marked@12.0.2/marked.min.js" integrity="sha384-/TQbtLCAerC3jgaim+N78RZSDYV7ryeoBCVqTuzRrFec2akfBkHS7ACQ3PQhvMVi" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/dompurify@3.1.5/dist/purify.min.js" integrity="sha384-nszIONF2FGC59kn+pPFaRa6WUNGwsZgXZiJxJwQbym+TzcH7smolUviLgpPbNx7V" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/prism.min.js" integrity="sha384-BGaNxfftg+9+TtC098wxawPFVEUpKYvaiCgbB0iqAMjK/4jDdmUY+oGxrPNvnXEf" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-typescript.min.js" integrity="sha384-PeOqKNW/piETaCg8rqKFy+Pm6KEk7e36/5YZE5XO/OaFdO+/Aw3O8qZ9qDPKVUgx" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-bash.min.js" integrity="sha384-9WmlN8ABpoFSSHvBGGjhvB3E/D8UkNB9HpLJjBQFC2VSQsM1odiQDv4NbEo+7l15" crossorigin="anonymous" defer></script>
-<script src="guide.js" defer></script>
-</body>
-</html>
+  <meta property="og:url" content="https://pdfnative.dev/guides/outlines.html">
+  <meta property="og:title" content="Outlines & page labels — pdfnative">
+  <meta property="og:description" content="Add a navigable bookmark tree (/Outlines) and logical page numbering (/PageLabels) to PDFs with pdfnative. New in v1.4.0.">
+  <meta property="og:image" content="https://pdfnative.dev/assets/og-image.png">
+  <meta property="og:image:width" content="1200">
+  <meta property="og:image:height" content="630">
+  <meta name="twitter:card" content="summary_large_image">
+  <meta name="twitter:title" content="Outlines & page labels — pdfnative">
+  <meta name="twitter:description" content="Bookmark tree (/Outlines) and logical page numbering (/PageLabels) — auto outline from headings, roman front matter, prefixed appendices.">
+  <meta name="twitter:image" content="https://pdfnative.dev/assets/og-image.png">
+  <link rel="icon" type="image/svg+xml" href="../favicon.svg">
+  <link rel="stylesheet" href="../style.css">
+  <link rel="stylesheet" href="guide.css">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
+  <!-- guide:ld:start -->
+  <script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://pdfnative.dev/"},{"@type":"ListItem","position":2,"name":"Guides","item":"https://pdfnative.dev/guides/"},{"@type":"ListItem","position":3,"name":"Outlines & page labels","item":"https://pdfnative.dev/guides/outlines.html"}]},{"@type":"TechArticle","headline":"Outlines & page labels","description":"Add a navigable bookmark tree (/Outlines) and logical page numbering (/PageLabels) to PDFs with pdfnative — auto outline from headings, roman front matter, prefixed appendices. New in v1.4.0.","inLanguage":"en","author":{"@type":"Organization","name":"Nizoka","url":"https://github.com/Nizoka"},"publisher":{"@type":"Organization","name":"pdfnative","url":"https://pdfnative.dev","logo":{"@type":"ImageObject","url":"https://pdfnative.dev/assets/logo.svg"}},"mainEntityOfPage":{"@type":"WebPage","@id":"https://pdfnative.dev/guides/outlines.html"},"isPartOf":{"@type":"WebSite","name":"pdfnative","url":"https://pdfnative.dev"}}]}</script>
+  <!-- guide:ld:end -->
+</head>
+<body>
+
+<a class="skip-link" href="#main-content">Skip to main content</a>
+
+<nav class="nav" role="navigation" aria-label="Main navigation">
+  <div class="nav-inner">
+    <a class="nav-brand" href="../">
+      <img src="../assets/logo.svg" alt="" width="28" height="28">
+      pdfnative
+    </a>
+    <button class="nav-hamburger" aria-label="Toggle menu" aria-expanded="false">☰</button>
+    <ul class="nav-links" role="list">
+      <li><a href="../#features">Features</a></li>
+      <li><a href="../#examples">Examples</a></li>
+      <li><a href="../#demo">Demo</a></li>
+      <li><a href="../#mcp">MCP</a></li>
+      <li><a href="../#cli">CLI</a></li>
+      <li><a href="../#react">React</a></li>
+      <li><a href="../learn/">Learn</a></li>
+      <li><a href="./">Guides</a></li>
+      <li><a href="../playgrounds/">Playgrounds</a></li>
+      <li><a href="../responsibility.html">Responsibility</a></li>
+      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
+      <li><button class="theme-toggle" aria-label="Toggle dark mode">🌙</button></li>
+    </ul>
+  </div>
+</nav>
+
+<main class="guide-shell" id="main-content" tabindex="-1">
+  <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; Outlines & page labels</p>
+  <article id="guide-content" class="guide-content" data-md="outlines.md" data-prerendered="true">
+<!-- guide:render:start -->
+<h1 id="outlines--page-labels">Outlines &amp; page labels</h1>
+<blockquote>
+<p><strong>New in v1.4.0.</strong> Give long documents a navigable <strong>bookmark tree</strong>
+(<code>/Outlines</code>) and <strong>logical page numbering</strong> (<code>/PageLabels</code>) — roman-numbered
+front matter, prefixed appendices, custom starting numbers. Both are opt-in
+<code>DocumentParams</code> fields and add zero overhead when unused.</p>
+</blockquote>
+<h2 id="tldr">TL;DR<a class="heading-anchor" href="#tldr" aria-label="Link to this section">#</a></h2>
+<pre><code class="language-ts">import { buildDocumentPDFBytes } from &#39;pdfnative&#39;;
+
+const bytes = buildDocumentPDFBytes({
+  title: &#39;Annual Report&#39;,
+  outline: &#39;auto&#39;,                       // bookmarks derived from headings
+  pageLabels: [
+    { startPage: 0, style: &#39;roman&#39; },    // startPage is 0-based — i, ii, iii … (front matter)
+    { startPage: 3, style: &#39;decimal&#39; },  // 1, 2, 3 … (body, from the 4th page)
+  ],
+  blocks: [
+    { type: &#39;heading&#39;, level: 1, text: &#39;Overview&#39; },
+    { type: &#39;paragraph&#39;, text: &#39;…&#39; },
+    { type: &#39;heading&#39;, level: 2, text: &#39;Highlights&#39; },
+    { type: &#39;paragraph&#39;, text: &#39;…&#39; },
+  ],
+});
+</code></pre>
+<h2 id="document-outline-bookmarks">Document outline (bookmarks)<a class="heading-anchor" href="#document-outline-bookmarks" aria-label="Link to this section">#</a></h2>
+<p>The outline appears in the viewer&#39;s sidebar / bookmarks panel and lets readers
+jump straight to a section. Set <code>DocumentParams.outline</code> to either <code>&#39;auto&#39;</code> or
+an explicit nested tree.</p>
+<h3 id="automatic-outline-from-headings">Automatic outline from headings<a class="heading-anchor" href="#automatic-outline-from-headings" aria-label="Link to this section">#</a></h3>
+<pre><code class="language-ts">outline: &#39;auto&#39;
+</code></pre>
+<p>pdfnative walks your <code>HeadingBlock</code>s and builds a nested tree by heading level
+(<code>level: 1</code> → top level, <code>level: 2</code> → child, …), each bookmark linking to the
+page the heading lands on. This is the zero-effort option for structured
+reports.</p>
+<h3 id="explicit-outline">Explicit outline<a class="heading-anchor" href="#explicit-outline" aria-label="Link to this section">#</a></h3>
+<p>For full control over titles, nesting, ordering, styling, and destinations,
+pass an array of <code>OutlineItem</code>:</p>
+<pre><code class="language-ts">import type { OutlineItem } from &#39;pdfnative&#39;;
+
+const outline: OutlineItem[] = [
+  {
+    title: &#39;Part I — Introduction&#39;,
+    pageIndex: 0,       // 0-based page index
+    bold: true,
+    children: [
+      { title: &#39;Background&#39;, pageIndex: 0 },
+      { title: &#39;Scope&#39;,      pageIndex: 1 },
+    ],
+  },
+  {
+    title: &#39;Part II — Results&#39;,
+    pageIndex: 2,
+    color: [0.1, 0.3, 0.9], // RGB 0–1; also accepts &#39;#1a4fd6&#39;
+    children: [
+      { title: &#39;Findings&#39;, pageIndex: 2, italic: true },
+    ],
+  },
+];
+</code></pre>
+<table>
+<thead>
+<tr>
+<th><code>OutlineItem</code> field</th>
+<th>Type</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>title</code></td>
+<td><code>string</code></td>
+<td>Bookmark label (encoded as PDF text, UTF-16BE when needed)</td>
+</tr>
+<tr>
+<td><code>pageIndex</code></td>
+<td><code>number</code></td>
+<td>0-based page index to jump to</td>
+</tr>
+<tr>
+<td><code>y</code></td>
+<td><code>number?</code></td>
+<td>Optional vertical destination (PDF user units from the bottom); defaults to the top of the page</td>
+</tr>
+<tr>
+<td><code>bold</code></td>
+<td><code>boolean?</code></td>
+<td>Render the label bold (<code>/F</code> flag 2)</td>
+</tr>
+<tr>
+<td><code>italic</code></td>
+<td><code>boolean?</code></td>
+<td>Render the label italic (<code>/F</code> flag 1)</td>
+</tr>
+<tr>
+<td><code>color</code></td>
+<td><code>PdfColor?</code></td>
+<td>Label colour (<code>/C</code>) — <code>[r,g,b]</code> 0–1 or a hex string</td>
+</tr>
+<tr>
+<td><code>open</code></td>
+<td><code>boolean?</code></td>
+<td>Initial expansion state. <code>true</code> (default) renders the bookmark expanded; <code>false</code> renders it <strong>collapsed</strong> (negative <code>/Count</code>), hiding its children until the reader expands it. Only meaningful with <code>children</code>.</td>
+</tr>
+<tr>
+<td><code>children</code></td>
+<td><code>OutlineItem[]?</code></td>
+<td>Nested bookmarks</td>
+</tr>
+</tbody></table>
+<p>Destinations use <code>/XYZ</code> with the page&#39;s top-left as the default anchor, so the
+viewer scrolls the target page into view at 100 % zoom.</p>
+<h3 id="collapsed-bookmarks">Collapsed bookmarks<a class="heading-anchor" href="#collapsed-bookmarks" aria-label="Link to this section">#</a></h3>
+<p>Deep hierarchies read better when some branches start collapsed. Set
+<code>open: false</code> on any item with children:</p>
+<pre><code class="language-ts">const outline: OutlineItem[] = [
+  { title: &#39;Front matter&#39;, pageIndex: 0 },
+  {
+    title: &#39;Appendices&#39;,
+    pageIndex: 12,
+    open: false,            // collapsed on open — children hidden until expanded
+    children: [
+      { title: &#39;Appendix A&#39;, pageIndex: 12 },
+      { title: &#39;Appendix B&#39;, pageIndex: 18 },
+    ],
+  },
+];
+</code></pre>
+<p>pdfnative emits the spec-correct signed <code>/Count</code> (ISO 32000-1 §12.3.3): a
+positive count for open items, a negative count for collapsed ones, and a
+collapsed node contributes only itself — not its hidden descendants — to its
+ancestors&#39; visible counts.</p>
+<h2 id="page-labels">Page labels<a class="heading-anchor" href="#page-labels" aria-label="Link to this section">#</a></h2>
+<p>By default a viewer numbers pages <code>1, 2, 3 …</code>. <code>/PageLabels</code> overrides that with
+<em>logical</em> numbering — front matter in lowercase roman, the body in decimal,
+appendices with an <code>A-</code> prefix, and so on. The labels show in the viewer&#39;s page
+thumbnail / &quot;go to page&quot; box and in printed page references.</p>
+<pre><code class="language-ts">import type { PageLabelRange } from &#39;pdfnative&#39;;
+
+const pageLabels: PageLabelRange[] = [
+  { startPage: 0, style: &#39;roman&#39; },                 // i, ii, iii
+  { startPage: 3, style: &#39;decimal&#39; },               // 1, 2, 3
+  { startPage: 20, style: &#39;decimal&#39;, prefix: &#39;A-&#39;, start: 1 }, // A-1, A-2
+];
+</code></pre>
+<table>
+<thead>
+<tr>
+<th><code>PageLabelRange</code> field</th>
+<th>Type</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>startPage</code></td>
+<td><code>number</code></td>
+<td>0-based page index where this range begins</td>
+</tr>
+<tr>
+<td><code>style</code></td>
+<td><code>PageLabelStyle?</code></td>
+<td><code>&#39;decimal&#39;</code> · <code>&#39;roman&#39;</code> (i, ii) · <code>&#39;Roman&#39;</code> (I, II) · <code>&#39;alpha&#39;</code> (a, b) · <code>&#39;Alpha&#39;</code> (A, B) · <code>&#39;none&#39;</code> (label is the prefix only)</td>
+</tr>
+<tr>
+<td><code>prefix</code></td>
+<td><code>string?</code></td>
+<td>Text prepended to each label (e.g. <code>&#39;A-&#39;</code>)</td>
+</tr>
+<tr>
+<td><code>start</code></td>
+<td><code>number?</code></td>
+<td>First number in the range (default <code>1</code>)</td>
+</tr>
+</tbody></table>
+<p>Ranges must be ordered by <code>startPage</code> and stay within the document&#39;s page
+count — both are validated at the boundary with a descriptive error.</p>
+<h2 id="how-it-works">How it works<a class="heading-anchor" href="#how-it-works" aria-label="Link to this section">#</a></h2>
+<ul>
+<li><strong>Outline</strong> — <code>buildOutlineObjects()</code>
+(<a href="https://github.com/Nizoka/pdfnative/blob/main/src/core/pdf-outline.ts" target="_blank" rel="noopener"><code>src/core/pdf-outline.ts</code></a>)
+emits the <code>/Outlines</code> dictionary plus one indirect object per bookmark, wired
+with <code>/First /Last /Next /Prev /Parent /Count</code>. The objects are appended as
+trailing indirect objects and the catalog gains <code>/Outlines N 0 R</code>.</li>
+<li><strong>Page labels</strong> — <code>buildPageLabelsDict()</code>
+(<a href="https://github.com/Nizoka/pdfnative/blob/main/src/core/pdf-page-labels.ts" target="_blank" rel="noopener"><code>src/core/pdf-page-labels.ts</code></a>)
+emits an inline <code>/PageLabels &lt;&lt; /Nums [...] &gt;&gt;</code> number tree in the catalog, so
+it adds no indirect objects.</li>
+</ul>
+<p>Both features are fully additive: a document with neither field is <strong>byte-identical</strong>
+to the pre-v1.4.0 output.</p>
+<h2 id="see-also">See also<a class="heading-anchor" href="#see-also" aria-label="Link to this section">#</a></h2>
+<ul>
+<li><a href="quickstart.html">Quick start</a></li>
+<li><a href="pdf-manipulation.html">PDF manipulation</a> — merge/split/extract</li>
+<li><a href="accessibility.html">Accessibility</a> — tagged structure &amp; TOC</li>
+<li><a href="https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md" target="_blank" rel="noopener">CHANGELOG</a></li>
+</ul>
+<!-- guide:render:end -->
+  </article>
+</main>
+
+<footer class="footer">
+  <div class="footer-inner">
+    <span>MIT License · © 2026 Nizoka</span>
+    <ul class="footer-links" role="list">
+      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
+      <li><a href="https://www.npmjs.com/package/pdfnative" target="_blank" rel="noopener">npm</a></li>
+      <li><a href="https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md" target="_blank" rel="noopener">Changelog</a></li>
+      <li><a href="./">All guides</a></li>
+    </ul>
+  </div>
+</footer>
+
+<script src="https://cdn.jsdelivr.net/npm/marked@12.0.2/marked.min.js" integrity="sha384-/TQbtLCAerC3jgaim+N78RZSDYV7ryeoBCVqTuzRrFec2akfBkHS7ACQ3PQhvMVi" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/dompurify@3.1.5/dist/purify.min.js" integrity="sha384-nszIONF2FGC59kn+pPFaRa6WUNGwsZgXZiJxJwQbym+TzcH7smolUviLgpPbNx7V" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/prism.min.js" integrity="sha384-BGaNxfftg+9+TtC098wxawPFVEUpKYvaiCgbB0iqAMjK/4jDdmUY+oGxrPNvnXEf" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-typescript.min.js" integrity="sha384-PeOqKNW/piETaCg8rqKFy+Pm6KEk7e36/5YZE5XO/OaFdO+/Aw3O8qZ9qDPKVUgx" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-bash.min.js" integrity="sha384-9WmlN8ABpoFSSHvBGGjhvB3E/D8UkNB9HpLJjBQFC2VSQsM1odiQDv4NbEo+7l15" crossorigin="anonymous" defer></script>
+<script src="guide.js" defer></script>
+</body>
+</html>
diff --git a/docs/guides/pdf-manipulation.html b/docs/guides/pdf-manipulation.html
index f6463a1..180317b 100644
--- a/docs/guides/pdf-manipulation.html
+++ b/docs/guides/pdf-manipulation.html
@@ -1,85 +1,345 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>PDF manipulation — pdfnative</title>
-  <meta name="description" content="Merge, split, and extract pages from existing PDFs with pdfnative's production-safe page-tree API — clean object-graph rebuild, resolved inherited attributes, optional signature/annotation stripping. New in v1.4.0.">
-  <link rel="canonical" href="https://pdfnative.dev/guides/pdf-manipulation.html">
-  <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/pdf-manipulation.html">
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>PDF manipulation — pdfnative</title>
+  <meta name="description" content="Merge, split, and extract pages from existing PDFs with pdfnative's production-safe page-tree API — clean object-graph rebuild, resolved inherited attributes, optional signature/annotation stripping. New in v1.4.0.">
+  <link rel="canonical" href="https://pdfnative.dev/guides/pdf-manipulation.html">
+  <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/pdf-manipulation.html">
   <link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/pdf-manipulation.html">
-  <link rel="alternate" type="text/markdown" href="pdf-manipulation.md">
-  <meta property="og:type" content="article">
-  <meta property="og:site_name" content="pdfnative">
+  <link rel="alternate" type="text/markdown" href="pdf-manipulation.md">
+  <link rel="alternate" type="text/plain" href="../llms.txt" title="llms.txt — machine-readable documentation index">
+  <meta property="og:type" content="article">
+  <meta property="og:site_name" content="pdfnative">
   <meta property="og:locale" content="en_US">
-  <meta property="og:url" content="https://pdfnative.dev/guides/pdf-manipulation.html">
-  <meta property="og:title" content="PDF manipulation — pdfnative">
-  <meta property="og:description" content="Merge, split, and extract pages from existing PDFs with pdfnative's production-safe page-tree API. New in v1.4.0.">
-  <meta property="og:image" content="https://pdfnative.dev/assets/og-image.png">
-  <meta property="og:image:width" content="1200">
-  <meta property="og:image:height" content="630">
-  <meta name="twitter:card" content="summary_large_image">
-  <meta name="twitter:title" content="PDF manipulation — pdfnative">
-  <meta name="twitter:description" content="Merge, split, and extract pages from existing PDFs — clean object-graph rebuild, resolved inherited attributes.">
-  <meta name="twitter:image" content="https://pdfnative.dev/assets/og-image.png">
-  <link rel="icon" type="image/svg+xml" href="../favicon.svg">
-  <link rel="stylesheet" href="../style.css">
-  <link rel="stylesheet" href="guide.css">
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
-</head>
-<body>
-
-<a class="skip-link" href="#main-content">Skip to main content</a>
-
-<nav class="nav" role="navigation" aria-label="Main navigation">
-  <div class="nav-inner">
-    <a class="nav-brand" href="../">
-      <img src="../assets/logo.svg" alt="" width="28" height="28">
-      pdfnative
-    </a>
-    <button class="nav-hamburger" aria-label="Toggle menu" aria-expanded="false">☰</button>
-    <ul class="nav-links" role="list">
-      <li><a href="../#features">Features</a></li>
-      <li><a href="../#examples">Examples</a></li>
-      <li><a href="../#demo">Demo</a></li>
-      <li><a href="../#mcp">MCP</a></li>
-      <li><a href="../#cli">CLI</a></li>
-      <li><a href="../#react">React</a></li>
-      <li><a href="../learn/">Learn</a></li>
-      <li><a href="./">Guides</a></li>
-      <li><a href="../playgrounds/">Playgrounds</a></li>
-      <li><a href="../responsibility.html">Responsibility</a></li>
-      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
-      <li><button class="theme-toggle" aria-label="Toggle dark mode">🌙</button></li>
-    </ul>
-  </div>
-</nav>
-
-<main class="guide-shell" id="main-content" tabindex="-1">
-  <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; PDF manipulation</p>
-  <article id="guide-content" class="guide-content" data-md="pdf-manipulation.md">
-    <p class="guide-loading">Loading…</p>
-    <noscript><p>This guide is written in Markdown: <a href="pdf-manipulation.md">read pdf-manipulation.md</a>.</p></noscript>
-  </article>
-</main>
-
-<footer class="footer">
-  <div class="footer-inner">
-    <span>MIT License · © 2026 Nizoka</span>
-    <ul class="footer-links" role="list">
-      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
-      <li><a href="https://www.npmjs.com/package/pdfnative" target="_blank" rel="noopener">npm</a></li>
-      <li><a href="https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md" target="_blank" rel="noopener">Changelog</a></li>
-      <li><a href="./">All guides</a></li>
-    </ul>
-  </div>
-</footer>
-
-<script src="https://cdn.jsdelivr.net/npm/marked@12.0.2/marked.min.js" integrity="sha384-/TQbtLCAerC3jgaim+N78RZSDYV7ryeoBCVqTuzRrFec2akfBkHS7ACQ3PQhvMVi" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/dompurify@3.1.5/dist/purify.min.js" integrity="sha384-nszIONF2FGC59kn+pPFaRa6WUNGwsZgXZiJxJwQbym+TzcH7smolUviLgpPbNx7V" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/prism.min.js" integrity="sha384-BGaNxfftg+9+TtC098wxawPFVEUpKYvaiCgbB0iqAMjK/4jDdmUY+oGxrPNvnXEf" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-typescript.min.js" integrity="sha384-PeOqKNW/piETaCg8rqKFy+Pm6KEk7e36/5YZE5XO/OaFdO+/Aw3O8qZ9qDPKVUgx" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-bash.min.js" integrity="sha384-9WmlN8ABpoFSSHvBGGjhvB3E/D8UkNB9HpLJjBQFC2VSQsM1odiQDv4NbEo+7l15" crossorigin="anonymous" defer></script>
-<script src="guide.js" defer></script>
-</body>
-</html>
+  <meta property="og:url" content="https://pdfnative.dev/guides/pdf-manipulation.html">
+  <meta property="og:title" content="PDF manipulation — pdfnative">
+  <meta property="og:description" content="Merge, split, and extract pages from existing PDFs with pdfnative's production-safe page-tree API. New in v1.4.0.">
+  <meta property="og:image" content="https://pdfnative.dev/assets/og-image.png">
+  <meta property="og:image:width" content="1200">
+  <meta property="og:image:height" content="630">
+  <meta name="twitter:card" content="summary_large_image">
+  <meta name="twitter:title" content="PDF manipulation — pdfnative">
+  <meta name="twitter:description" content="Merge, split, and extract pages from existing PDFs — clean object-graph rebuild, resolved inherited attributes.">
+  <meta name="twitter:image" content="https://pdfnative.dev/assets/og-image.png">
+  <link rel="icon" type="image/svg+xml" href="../favicon.svg">
+  <link rel="stylesheet" href="../style.css">
+  <link rel="stylesheet" href="guide.css">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
+  <!-- guide:ld:start -->
+  <script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://pdfnative.dev/"},{"@type":"ListItem","position":2,"name":"Guides","item":"https://pdfnative.dev/guides/"},{"@type":"ListItem","position":3,"name":"PDF manipulation (merge / split / extract)","item":"https://pdfnative.dev/guides/pdf-manipulation.html"}]},{"@type":"TechArticle","headline":"PDF manipulation (merge / split / extract)","description":"Merge, split, and extract pages from existing PDFs with pdfnative's production-safe page-tree API — clean object-graph rebuild, resolved inherited attributes, optional signature/annotation stripping. New in v1.4.0.","inLanguage":"en","author":{"@type":"Organization","name":"Nizoka","url":"https://github.com/Nizoka"},"publisher":{"@type":"Organization","name":"pdfnative","url":"https://pdfnative.dev","logo":{"@type":"ImageObject","url":"https://pdfnative.dev/assets/logo.svg"}},"mainEntityOfPage":{"@type":"WebPage","@id":"https://pdfnative.dev/guides/pdf-manipulation.html"},"isPartOf":{"@type":"WebSite","name":"pdfnative","url":"https://pdfnative.dev"}}]}</script>
+  <!-- guide:ld:end -->
+</head>
+<body>
+
+<a class="skip-link" href="#main-content">Skip to main content</a>
+
+<nav class="nav" role="navigation" aria-label="Main navigation">
+  <div class="nav-inner">
+    <a class="nav-brand" href="../">
+      <img src="../assets/logo.svg" alt="" width="28" height="28">
+      pdfnative
+    </a>
+    <button class="nav-hamburger" aria-label="Toggle menu" aria-expanded="false">☰</button>
+    <ul class="nav-links" role="list">
+      <li><a href="../#features">Features</a></li>
+      <li><a href="../#examples">Examples</a></li>
+      <li><a href="../#demo">Demo</a></li>
+      <li><a href="../#mcp">MCP</a></li>
+      <li><a href="../#cli">CLI</a></li>
+      <li><a href="../#react">React</a></li>
+      <li><a href="../learn/">Learn</a></li>
+      <li><a href="./">Guides</a></li>
+      <li><a href="../playgrounds/">Playgrounds</a></li>
+      <li><a href="../responsibility.html">Responsibility</a></li>
+      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
+      <li><button class="theme-toggle" aria-label="Toggle dark mode">🌙</button></li>
+    </ul>
+  </div>
+</nav>
+
+<main class="guide-shell" id="main-content" tabindex="-1">
+  <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; PDF manipulation</p>
+  <article id="guide-content" class="guide-content" data-md="pdf-manipulation.md" data-prerendered="true">
+<!-- guide:render:start -->
+<h1 id="pdf-manipulation-merge--split--extract">PDF manipulation (merge / split / extract)</h1>
+<blockquote>
+<p><strong>New in v1.4.0.</strong> Combine, slice, and reorder existing PDFs with a
+production-safe page-tree API. Each operation <strong>rebuilds a clean object graph</strong>
+rather than patching bytes in place — inherited page attributes are resolved,
+dangling references are pruned, and the result is a fresh, well-formed PDF.</p>
+</blockquote>
+<h2 id="tldr">TL;DR<a class="heading-anchor" href="#tldr" aria-label="Link to this section">#</a></h2>
+<pre><code class="language-ts">import { mergePdfs, splitPdf, extractPages } from &#39;pdfnative&#39;;
+import { readFileSync, writeFileSync } from &#39;node:fs&#39;;
+
+const a = readFileSync(&#39;cover.pdf&#39;);
+const b = readFileSync(&#39;body.pdf&#39;);
+
+// Merge
+writeFileSync(&#39;combined.pdf&#39;, mergePdfs([a, b]));
+
+// Split into page ranges (0-based, end inclusive; end defaults to start)
+const [intro, rest] = splitPdf(b, [
+  { start: 0, end: 1 },   // pages 0–1
+  { start: 2, end: 9 },   // pages 2–9
+]);
+
+// Extract specific pages (0-based)
+writeFileSync(&#39;selected.pdf&#39;, extractPages(b, [0, 3, 7]));
+</code></pre>
+<p>All three accept and return <code>Uint8Array</code> PDF bytes.</p>
+<blockquote>
+<p><strong>New in v1.6.0.</strong> Encrypted sources are now <strong>decrypted on ingest</strong> — pass a
+password (see <a href="#encrypted-sources">Encrypted sources</a>) — the rebuilt output
+can be <strong>re-encrypted</strong> with <code>encrypt</code> (see
+<a href="#re-encrypting-the-output">Re-encrypting the output</a>), and there are
+constant-memory <strong>streaming</strong> variants (<code>streamMergedPdfs</code> / <code>streamSplitPdf</code> /
+<code>streamExtractPages</code>, see <a href="#streaming-merge--split">Streaming merge &amp; split</a>).</p>
+</blockquote>
+<h2 id="mergepdfssources-options"><code>mergePdfs(sources, options?)</code><a class="heading-anchor" href="#mergepdfssources-options" aria-label="Link to this section">#</a></h2>
+<p>Concatenates multiple PDFs into one, in order.</p>
+<pre><code class="language-ts">function mergePdfs(
+  sources: readonly PdfSourceInput[],
+  options?: MergeOptions,
+): Uint8Array;
+
+// Raw bytes, or bytes + password for an encrypted source (v1.6.0):
+type PdfSourceInput = Uint8Array | { bytes: Uint8Array; password?: string };
+
+interface MergeOptions {
+  /** Strip digital-signature widgets/fields from the result. Default false. */
+  dropSignatures?: boolean;
+  /** Strip all annotations (links, comments, …) from the result. Default false. */
+  dropAnnotations?: boolean;
+  /** Password used to decrypt encrypted sources (default for every source). v1.6.0 */
+  password?: string;
+  /**
+   * Maximum size, in bytes, of the assembled output. The operation throws as
+   * soon as the copied object graph would exceed this limit — even mid-copy,
+   * before an oversized stream is materialised — so a malicious or accidentally
+   * huge source cannot exhaust process memory. Defaults to **256 MiB**; pass
+   * `Infinity` to disable (not recommended for untrusted input).
+   */
+  maxOutputSize?: number;
+}
+</code></pre>
+<ul>
+<li>Up to <strong>50 source documents</strong> per call (<code>MAX_MERGE_SOURCES</code>).</li>
+<li>Output is hard-capped at <strong>256 MiB</strong> by default (<code>maxOutputSize</code>) so a hostile
+source cannot OOM the process; raise it for legitimately large merges.</li>
+<li>Page resources (<code>/Font</code>, <code>/XObject</code>, …) are deep-copied into a fresh
+object-number space, so there are no collisions between sources.</li>
+<li>Inherited attributes (<code>/MediaBox</code>, <code>/CropBox</code>, <code>/Rotate</code>, <code>/Resources</code>) are
+resolved from each page&#39;s ancestors and folded onto the page, so pages keep
+their geometry even when the original relied on inheritance.</li>
+</ul>
+<blockquote>
+<p>Merging a signed PDF invalidates its signature (the bytes change). Pass
+<code>dropSignatures: true</code> to remove the now-meaningless signature fields.</p>
+</blockquote>
+<h2 id="splitpdfsource-ranges"><code>splitPdf(source, ranges)</code><a class="heading-anchor" href="#splitpdfsource-ranges" aria-label="Link to this section">#</a></h2>
+<p>Splits one PDF into several, one output per range.</p>
+<pre><code class="language-ts">function splitPdf(
+  source: Uint8Array,
+  ranges: readonly PageRange[],
+  options?: MergeOptions,
+): Uint8Array[];
+
+interface PageRange {
+  /** 0-based first page (inclusive). */
+  start: number;
+  /** 0-based last page (inclusive). Defaults to `start` (single page). */
+  end?: number;
+}
+</code></pre>
+<p>Ranges may overlap and need not be contiguous. Each output is an independent,
+fully-formed PDF. <code>options</code> (including <code>maxOutputSize</code>) applies to every emitted
+document.</p>
+<h2 id="extractpagessource-indices"><code>extractPages(source, indices)</code><a class="heading-anchor" href="#extractpagessource-indices" aria-label="Link to this section">#</a></h2>
+<p>Builds a new PDF from an explicit list of <strong>0-based</strong> page indices, in the order
+given — handy for reordering or cherry-picking.</p>
+<pre><code class="language-ts">function extractPages(
+  source: Uint8Array,
+  indices: readonly number[],
+  options?: MergeOptions,
+): Uint8Array;
+
+extractPages(pdf, [4, 0, 1]); // page 5 first, then 1, then 2
+</code></pre>
+<p><code>options</code> (including <code>maxOutputSize</code> and <code>dropAnnotations</code>) is honoured here too.</p>
+<h2 id="encrypted-sources">Encrypted sources<a class="heading-anchor" href="#encrypted-sources" aria-label="Link to this section">#</a></h2>
+<p>Since <strong>v1.6.0</strong>, <code>mergePdfs</code> / <code>splitPdf</code> / <code>extractPages</code> decrypt encrypted
+sources transparently (Standard Security Handler — RC4, AES-128, AES-256). Give
+the password either per-source or as a shared default:</p>
+<pre><code class="language-ts">// Per-source password (only that source is encrypted):
+mergePdfs([cover, { bytes: encryptedBody, password: &#39;secret&#39; }]);
+
+// Shared password for every source, via options:
+mergePdfs([a, b], { password: &#39;secret&#39; });
+
+// splitPdf / extractPages take the password on options:
+splitPdf(encrypted, [{ start: 0, end: 2 }], { password: &#39;secret&#39; });
+</code></pre>
+<p>A wrong or missing password throws <code>PdfPasswordError</code>; an unsupported handler
+(e.g. public-key) throws <code>PdfEncryptionUnsupportedError</code>. The rebuilt output is
+unencrypted <strong>unless you set <code>encrypt</code></strong> (below). See the
+<a href="../guides/architecture.html">reader guide</a> for <code>openPdf(bytes, { password })</code>.</p>
+<h2 id="re-encrypting-the-output">Re-encrypting the output<a class="heading-anchor" href="#re-encrypting-the-output" aria-label="Link to this section">#</a></h2>
+<p>Since <strong>v1.6.0</strong>, <code>MergeOptions.encrypt</code> re-encrypts the rebuilt document —
+closing the round trip: <em>open encrypted → edit → re-secure</em>. It takes the same
+shape as the document builder&#39;s <code>encryption</code> option:</p>
+<pre><code class="language-ts">import { mergePdfs, splitPdf } from &#39;pdfnative&#39;;
+
+// Merge, then protect the result (AES-256):
+const secured = mergePdfs([a, b], {
+  encrypt: {
+    ownerPassword: &#39;owner-secret&#39;,      // required, non-empty
+    userPassword: &#39;user-secret&#39;,        // optional (empty = opens freely)
+    algorithm: &#39;aes256&#39;,                // &#39;aes128&#39; (V4/R4, default) | &#39;aes256&#39; (V5/R6)
+    permissions: { print: true, copy: false, modify: false },
+  },
+});
+
+// Change a document&#39;s password: decrypt on ingest, re-encrypt on output.
+const rekeyed = mergePdfs(
+  [{ bytes: oldPdf, password: &#39;old-password&#39; }],
+  { encrypt: { ownerPassword: &#39;new-password&#39;, algorithm: &#39;aes256&#39; } },
+);
+
+// Works identically on splitPdf / extractPages and the streaming variants.
+splitPdf(src, [{ start: 0, end: 4 }], { encrypt: { ownerPassword: &#39;o&#39; } });
+</code></pre>
+<p>Notes:</p>
+<ul>
+<li><strong>AES only</strong> — new output is never RC4-encrypted (legacy RC4 is read-only).</li>
+<li><strong>CSPRNG required</strong> — a missing Web Crypto secure random source throws
+before any copying starts (encryption keys are never derived from
+<code>Math.random()</code>).</li>
+<li><strong>Fresh keys</strong> — no key material, permissions, or passwords from any source
+document are reused; the caller states the new protection explicitly.</li>
+<li><strong>Non-deterministic output</strong> — random IVs/salts and a random document <code>/ID</code>
+mean encrypted output is not byte-reproducible (the unencrypted path keeps
+its content-addressed deterministic <code>/ID</code>).</li>
+</ul>
+<h2 id="streaming-merge--split">Streaming merge &amp; split<a class="heading-anchor" href="#streaming-merge--split" aria-label="Link to this section">#</a></h2>
+<p>For large documents, the streaming variants emit the result as fixed-size
+chunks while holding only the cross-reference offsets and small object dicts in
+memory — stream payloads flow straight from the (in-memory) source bytes, so the
+fully-joined document is never materialised. Each is <strong>byte-identical</strong> to its
+buffered counterpart (except with <code>encrypt</code>, where fresh random IVs make each
+invocation structurally — not byte — identical) and composes with
+<a href="streaming.html"><code>streamToFile</code></a>:</p>
+<pre><code class="language-ts">import { streamMergedPdfs, streamSplitPdf, streamToFile } from &#39;pdfnative&#39;;
+
+// Constant-memory merge straight to disk:
+await streamToFile(streamMergedPdfs([a, b]), &#39;combined.pdf&#39;);
+
+// Split: one output stream per range (drain each fully before advancing):
+for await (const part of streamSplitPdf(body, [{ start: 0, end: 1 }, { start: 2, end: 9 }])) {
+  await streamToFile(part.pdf, `part-${part.index}.pdf`);
+}
+</code></pre>
+<p><code>StreamMergeOptions</code> adds <code>chunkSize</code> (1 KiB–16 MiB, default 64 KiB) on top of
+<code>MergeOptions</code>. For multi-gigabyte merges pass <code>maxOutputSize: Infinity</code> — safe
+with streaming because output bytes are never buffered (the sources themselves
+are still in-memory <code>Uint8Array</code>s).</p>
+<p>For freshly <em>built</em> (not merged) documents, combine the true streaming builders
+with <a href="streaming.html"><code>streamToFile</code></a> so the binary never fully materialises:</p>
+<pre><code class="language-ts">import { buildDocumentPDFStreamTrue, streamToFile } from &#39;pdfnative&#39;;
+
+await streamToFile(buildDocumentPDFStreamTrue(params), &#39;report.pdf&#39;);
+</code></pre>
+<h2 id="updating-metadata-in-place">Updating metadata in place<a class="heading-anchor" href="#updating-metadata-in-place" aria-label="Link to this section">#</a></h2>
+<blockquote>
+<p><strong>New in v1.7.0.</strong> <code>PdfModifier.updateMetadata()</code> rewrites a document&#39;s
+metadata as a non-destructive incremental revision — no re-serialisation,
+existing signatures over earlier revisions stay intact.</p>
+</blockquote>
+<pre><code class="language-ts">import { openPdf, createModifier } from &#39;pdfnative&#39;;
+
+const modifier = createModifier(openPdf(bytes));
+modifier.updateMetadata({
+  title: &#39;Q3 report (final)&#39;,
+  author: &#39;Finance&#39;,
+  keywords: &#39;quarterly, revenue&#39;,
+  // modDate: new Date(&#39;2026-08-21T00:00:00Z&#39;),  // pin for reproducible bytes
+});
+const updated = modifier.save();
+</code></pre>
+<p>Only the fields you pass change; the rest of <code>/Info</code> is preserved. <code>/ModDate</code>
+is always refreshed (pass <code>modDate</code> to pin it). When the document carries an
+XMP packet, it is resynchronised in the same revision — <code>dc:title</code>,
+<code>dc:creator</code>, <code>dc:description</code>, <code>pdf:Keywords</code>, <code>xmp:ModifyDate</code> and
+<code>xmp:MetadataDate</code> — while <code>xmp:CreateDate</code> and any <code>pdfaid:*</code> conformance
+claim are preserved, so Info↔XMP parity holds for PDF/A documents.</p>
+<h2 id="safety--limits">Safety &amp; limits<a class="heading-anchor" href="#safety--limits" aria-label="Link to this section">#</a></h2>
+<ul>
+<li><strong>Encrypted input is decrypted on ingest</strong> (v1.6.0) when a valid password is
+supplied; a wrong/missing password throws <code>PdfPasswordError</code>. Output is
+unencrypted unless <code>encrypt</code> re-protects it (AES-128/AES-256, CSPRNG
+required, fresh keys only).</li>
+<li><strong>Annotations are filtered to URI <code>/Link</code> only</strong> during the rebuild (plus the
+full strip when <code>dropAnnotations</code> is set), so interactive form/JS annotations
+don&#39;t leak across documents.</li>
+<li><strong>Bounded-depth copy.</strong> The object-graph copy is capped at a fixed recursion
+depth, so a pathologically nested or adversarial source can never overflow the
+stack — it throws a descriptive error instead.</li>
+<li><strong>Bounded output size.</strong> Cumulative output is capped at <strong>256 MiB</strong> by default
+(<code>maxOutputSize</code>), checked <em>before</em> each stream is materialised, so a source
+full of multi-gigabyte objects is rejected rather than allowed to exhaust
+memory. Tune or disable (<code>Infinity</code>) per call.</li>
+<li><strong>Deterministic output.</strong> Every unencrypted result carries a
+content-addressed trailer <code>/ID</code> (ISO 32000-1 §7.5.5) derived from the
+assembled bytes, so the same inputs always produce a byte-identical PDF —
+friendly to caching, diffing, and reproducible builds. (With <code>encrypt</code>, the
+<code>/ID</code> is the encryption state&#39;s random document ID, as the file key is bound
+to it.)</li>
+<li><strong>Full rebuild, not in-place surgery.</strong> The clean-graph approach trades a
+little speed for correctness and is safe to run on third-party PDFs.</li>
+<li><strong>Page boxes survive</strong> <em>(v1.7.0)</em>. Declared <code>/TrimBox</code>, <code>/BleedBox</code>,
+<code>/ArtBox</code>, <code>/CropBox</code> and <code>/UserUnit</code> entries are preserved through
+<code>mergePdfs</code> / <code>splitPdf</code> / <code>extractPages</code> (they were dropped by the rebuild
+before 1.7.0) — so print-ready sources keep their geometry. See the
+<a href="print.html">print production guide</a>.</li>
+</ul>
+<h2 id="how-it-works">How it works<a class="heading-anchor" href="#how-it-works" aria-label="Link to this section">#</a></h2>
+<p><a href="https://github.com/Nizoka/pdfnative/blob/main/src/parser/pdf-pagetree.ts" target="_blank" rel="noopener"><code>src/parser/pdf-pagetree.ts</code></a>
+opens each source with the built-in <a href="architecture.html">PDF reader</a>, walks the
+page tree, and deep-copies every kept page plus its transitive object graph into
+a new document (<code>obj 1</code> = Catalog, <code>obj 2</code> = Pages root, <code>obj 3+</code> = the copied
+graph). The copy is <strong>memoised per reader</strong> and <strong>cycle-safe</strong>, and all values
+are serialised binary-safe (Latin-1) so embedded fonts and image streams survive
+intact.</p>
+<h2 id="see-also">See also<a class="heading-anchor" href="#see-also" aria-label="Link to this section">#</a></h2>
+<ul>
+<li><a href="architecture.html">Architecture</a> — the parser/reader internals</li>
+<li><a href="streaming.html">Streaming output</a> — <code>streamToFile</code></li>
+<li><a href="outlines.html">Outlines &amp; page labels</a></li>
+<li><a href="https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md" target="_blank" rel="noopener">CHANGELOG</a></li>
+</ul>
+<!-- guide:render:end -->
+  </article>
+</main>
+
+<footer class="footer">
+  <div class="footer-inner">
+    <span>MIT License · © 2026 Nizoka</span>
+    <ul class="footer-links" role="list">
+      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
+      <li><a href="https://www.npmjs.com/package/pdfnative" target="_blank" rel="noopener">npm</a></li>
+      <li><a href="https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md" target="_blank" rel="noopener">Changelog</a></li>
+      <li><a href="./">All guides</a></li>
+    </ul>
+  </div>
+</footer>
+
+<script src="https://cdn.jsdelivr.net/npm/marked@12.0.2/marked.min.js" integrity="sha384-/TQbtLCAerC3jgaim+N78RZSDYV7ryeoBCVqTuzRrFec2akfBkHS7ACQ3PQhvMVi" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/dompurify@3.1.5/dist/purify.min.js" integrity="sha384-nszIONF2FGC59kn+pPFaRa6WUNGwsZgXZiJxJwQbym+TzcH7smolUviLgpPbNx7V" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/prism.min.js" integrity="sha384-BGaNxfftg+9+TtC098wxawPFVEUpKYvaiCgbB0iqAMjK/4jDdmUY+oGxrPNvnXEf" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-typescript.min.js" integrity="sha384-PeOqKNW/piETaCg8rqKFy+Pm6KEk7e36/5YZE5XO/OaFdO+/Aw3O8qZ9qDPKVUgx" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-bash.min.js" integrity="sha384-9WmlN8ABpoFSSHvBGGjhvB3E/D8UkNB9HpLJjBQFC2VSQsM1odiQDv4NbEo+7l15" crossorigin="anonymous" defer></script>
+<script src="guide.js" defer></script>
+</body>
+</html>
diff --git a/docs/guides/pdf-manipulation.md b/docs/guides/pdf-manipulation.md
index 644a764..104663d 100644
--- a/docs/guides/pdf-manipulation.md
+++ b/docs/guides/pdf-manipulation.md
@@ -268,6 +268,11 @@ claim are preserved, so Info↔XMP parity holds for PDF/A documents.
   to it.)
 - **Full rebuild, not in-place surgery.** The clean-graph approach trades a
   little speed for correctness and is safe to run on third-party PDFs.
+- **Page boxes survive** _(v1.7.0)_. Declared `/TrimBox`, `/BleedBox`,
+  `/ArtBox`, `/CropBox` and `/UserUnit` entries are preserved through
+  `mergePdfs` / `splitPdf` / `extractPages` (they were dropped by the rebuild
+  before 1.7.0) — so print-ready sources keep their geometry. See the
+  [print production guide](print.html).
 
 ## How it works
 
diff --git a/docs/guides/pdfa.html b/docs/guides/pdfa.html
index 84d3951..f79fefc 100644
--- a/docs/guides/pdfa.html
+++ b/docs/guides/pdfa.html
@@ -4,28 +4,32 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>PDF/A conformance — pdfnative</title>
-  <meta name="description" content="How pdfnative implements PDF/A-1b, 2b, 2u, and 3b — full veraPDF conformance with v1.1.0 Latin font embedding and XMP parity.">
+  <meta name="description" content="How pdfnative implements PDF/A-1b, 2b, 2u, and 3b — full veraPDF conformance with Latin font embedding, XMP parity, and the v1.7.0 declaration guards (strict, onDiagnostic, PDFA_* diagnostic codes).">
   <link rel="canonical" href="https://pdfnative.dev/guides/pdfa.html">
   <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/pdfa.html">
   <link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/pdfa.html">
   <link rel="alternate" type="text/markdown" href="pdfa.md">
+  <link rel="alternate" type="text/plain" href="../llms.txt" title="llms.txt — machine-readable documentation index">
   <meta property="og:type" content="article">
   <meta property="og:site_name" content="pdfnative">
   <meta property="og:locale" content="en_US">
   <meta property="og:url" content="https://pdfnative.dev/guides/pdfa.html">
   <meta property="og:title" content="PDF/A conformance — pdfnative">
-  <meta property="og:description" content="How pdfnative implements PDF/A-1b, 2b, 2u, and 3b — full veraPDF conformance with Latin font embedding and XMP parity.">
+  <meta property="og:description" content="How pdfnative implements PDF/A-1b, 2b, 2u, and 3b — full veraPDF conformance with Latin font embedding, XMP parity, and the v1.7.0 declaration guards.">
   <meta property="og:image" content="https://pdfnative.dev/assets/og-image.png">
   <meta property="og:image:width" content="1200">
   <meta property="og:image:height" content="630">
   <meta name="twitter:card" content="summary_large_image">
   <meta name="twitter:title" content="PDF/A conformance — pdfnative">
-  <meta name="twitter:description" content="PDF/A-1b, 2b, 2u, and 3b — full veraPDF conformance with Latin font embedding and XMP parity.">
+  <meta name="twitter:description" content="PDF/A-1b, 2b, 2u, and 3b — full veraPDF conformance, Latin font embedding, and v1.7.0 declaration guards.">
   <meta name="twitter:image" content="https://pdfnative.dev/assets/og-image.png">
   <link rel="icon" type="image/svg+xml" href="../favicon.svg">
   <link rel="stylesheet" href="../style.css">
   <link rel="stylesheet" href="guide.css">
   <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
+  <!-- guide:ld:start -->
+  <script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://pdfnative.dev/"},{"@type":"ListItem","position":2,"name":"Guides","item":"https://pdfnative.dev/guides/"},{"@type":"ListItem","position":3,"name":"PDF/A conformance in pdfnative","item":"https://pdfnative.dev/guides/pdfa.html"}]},{"@type":"TechArticle","headline":"PDF/A conformance in pdfnative","description":"How pdfnative implements PDF/A-1b, 2b, 2u, and 3b — full veraPDF conformance with Latin font embedding, XMP parity, and the v1.7.0 declaration guards (strict, onDiagnostic, PDFA_* diagnostic codes).","inLanguage":"en","author":{"@type":"Organization","name":"Nizoka","url":"https://github.com/Nizoka"},"publisher":{"@type":"Organization","name":"pdfnative","url":"https://pdfnative.dev","logo":{"@type":"ImageObject","url":"https://pdfnative.dev/assets/logo.svg"}},"mainEntityOfPage":{"@type":"WebPage","@id":"https://pdfnative.dev/guides/pdfa.html"},"isPartOf":{"@type":"WebSite","name":"pdfnative","url":"https://pdfnative.dev"}}]}</script>
+  <!-- guide:ld:end -->
 </head>
 <body>
 
@@ -57,9 +61,384 @@
 
 <main class="guide-shell" id="main-content" tabindex="-1">
   <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; PDF/A</p>
-  <article id="guide-content" class="guide-content" data-md="pdfa.md">
-    <p class="guide-loading">Loading…</p>
-    <noscript><p>This guide is written in Markdown: <a href="pdfa.md">read pdfa.md</a>.</p></noscript>
+  <article id="guide-content" class="guide-content" data-md="pdfa.md" data-prerendered="true">
+<!-- guide:render:start -->
+<h1 id="pdfa-conformance-in-pdfnative">PDF/A conformance in pdfnative</h1>
+<blockquote>
+<p><strong>PDF/A-1b, 2b, 2u and 3b via <code>layout: { tagged: … }</code>, validated against the veraPDF reference validator in CI.</strong> Since v1.7.0, a configuration that would break the declared level surfaces a diagnostic — <code>console.warn</code> by default, a custom <code>onDiagnostic</code> sink, or a thrown error under <code>strict: true</code>.</p>
+</blockquote>
+<p>PDF/A is the ISO archival profile for PDF (ISO 19005). pdfnative supports
+PDF/A-1b, 2b, 2u, and 3b via the <code>tagged</code> build option. This guide
+explains what works today, what&#39;s still in flight, and how to validate
+your output against the official reference validator.</p>
+<h2 id="tldr">TL;DR<a class="heading-anchor" href="#tldr" aria-label="Link to this section">#</a></h2>
+<pre><code class="language-ts">import { buildPDFBytes } from &#39;pdfnative&#39;;
+
+const pdf = buildPDFBytes(params, { tagged: true });        // PDF/A-2b (default)
+const pdf1b = buildPDFBytes(params, { tagged: &#39;pdfa1b&#39; });  // PDF/A-1b
+const pdf2u = buildPDFBytes(params, { tagged: &#39;pdfa2u&#39; });  // PDF/A-2u
+const pdf3b = buildPDFBytes(params, { tagged: &#39;pdfa3b&#39; });  // PDF/A-3b + attachments
+</code></pre>
+<blockquote>
+<h3 id="tagged-alone-is-not-enough-embed-a-font"><code>tagged</code> alone is not enough: embed a font<a class="heading-anchor" href="#tagged-alone-is-not-enough-embed-a-font" aria-label="Link to this section">#</a></h3>
+<p>ISO 19005 requires <strong>every</strong> font in the file to be embedded. <code>tagged</code> writes the
+XMP conformance declaration, the structure tree and the output intent — but it does
+not embed a font for you. If your document uses only the viewer&#39;s built-in fonts
+(which is what happens when you pass no <code>fontEntries</code>), pdfnative writes a file that
+<em>claims</em> PDF/A while referencing non-embedded Helvetica, and veraPDF will reject it.</p>
+<p>Pass at least a Latin font whenever you set <code>tagged</code>:</p>
+<pre><code class="language-ts">import { buildDocumentPDFBytes, registerFonts, loadFontData } from &#39;pdfnative&#39;;
+
+registerFonts({ latin: () =&gt; import(&#39;pdfnative/fonts/noto-sans-data.js&#39;) });
+const fontData = await loadFontData(&#39;latin&#39;);
+
+// fontRef becomes a PDF resource name, so it needs the leading slash.
+// /F1 and /F2 are reserved by the engine — start at /F3.
+
+const pdf = buildDocumentPDFBytes(
+  { title: &#39;Archival&#39;, blocks, fontEntries: [{ fontData, fontRef: &#39;/F3&#39;, lang: &#39;latin&#39; }] },
+  { tagged: &#39;pdfa2b&#39; },
+);
+</code></pre>
+<p>Since <strong>v1.7.0</strong> the builders guard this declaration themselves: requesting any
+<code>&#39;pdfa*&#39;</code> level (or <code>tagged: true</code>) with no <code>fontEntries</code> emits the
+<code>PDFA_NO_FONT_ENTRIES</code> diagnostic — a <code>console.warn</code> by default, or a thrown
+<code>Error</code> under <code>strict: true</code>, before any output bytes are produced. See
+<em>Conformance diagnostics</em> below.</p>
+<p>The sample generators in <code>scripts/generators/</code> all do this, which is why the veraPDF
+CI job passes. If you author through <code>pdfnative-react</code>, its <code>lintDocument()</code> rule
+<code>L_TAGGED_NO_FONTS</code> still catches the same trap earlier, at the document-model
+level — a complementary check to the core diagnostic.</p>
+</blockquote>
+<p>Every output written with <code>tagged</code> set ships:</p>
+<ul>
+<li>A full structure tree (<code>/Document → /Table → /TR → /TH|/TD</code>, <code>/H1–H3</code>,
+<code>/P</code>, <code>/L → /LI</code>, <code>/Figure</code>, <code>/Link</code>).</li>
+<li><code>/ActualText</code> UTF-16BE on every marked content <code>/Span</code>.</li>
+<li>An XMP metadata stream with <code>pdfaid:part</code> and <code>pdfaid:conformance</code>.</li>
+<li>An sRGB ICC <code>OutputIntent</code> (<code>GTS_PDFA1</code>).</li>
+<li><code>/MarkInfo &lt;&lt; /Marked true &gt;&gt;</code> on the catalog.</li>
+<li>A trailer <code>/ID</code> derived deterministically from the document title and
+creation timestamp.</li>
+<li><code>/Info CreationDate</code> byte-equivalent to <code>xmp:CreateDate</code>, both with
+timezone offsets.</li>
+</ul>
+<h2 id="conformance-diagnostics-v170">Conformance diagnostics (v1.7.0)<a class="heading-anchor" href="#conformance-diagnostics-v170" aria-label="Link to this section">#</a></h2>
+<p>Configurations that produce a PDF/A claim veraPDF would reject no longer fail
+silently. Both builders (<code>buildPDFBytes</code> and <code>buildDocumentPDFBytes</code>) surface
+them through a single diagnostics channel:</p>
+<table>
+<thead>
+<tr>
+<th>Code</th>
+<th>Trigger</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>PDFA_NO_FONT_ENTRIES</code></td>
+<td>A <code>&#39;pdfa*&#39;</code> level (or <code>tagged: true</code>) requested with no <code>fontEntries</code> — the file would claim PDF/A while referencing unembedded standard-14 Helvetica (ISO 19005 §6.2.11.4.1).</td>
+</tr>
+<tr>
+<td><code>PDFA_DEVICE_CMYK_IMAGE</code></td>
+<td>A DeviceCMYK image embedded under a PDF/A claim with an sRGB <code>OutputIntent</code> (ISO 19005-2 §6.2.4.3).</td>
+</tr>
+<tr>
+<td><code>PDFA_UNEMBEDDED_FORM_FONT</code></td>
+<td>AcroForm fields under a PDF/A claim — form appearances render through an unembedded base-14 <code>/Helv</code> font (same §6.2.11.4.1 rule). Flatten the form or drop the level.</td>
+</tr>
+</tbody></table>
+<p>By default each diagnostic is a <code>console.warn</code>, deduplicated <strong>once per code
+per build</strong>. Two layout options change that:</p>
+<pre><code class="language-ts">import { buildPDFBytes, type PdfDiagnostic } from &#39;pdfnative&#39;;
+
+// CI / tests: escalate to a thrown Error, before any bytes are produced.
+buildPDFBytes(params, { tagged: &#39;pdfa2b&#39;, strict: true });
+
+// Custom sink — receives every diagnostic (no deduplication).
+// Pass () =&gt; {} to silence entirely.
+const diagnostics: PdfDiagnostic[] = [];
+const pdf = buildPDFBytes(params, {
+  tagged: &#39;pdfa2b&#39;,
+  onDiagnostic: (d) =&gt; diagnostics.push(d),
+});
+</code></pre>
+<p>Each <code>PdfDiagnostic</code> carries a machine-readable <code>code</code>, a <code>severity</code>
+(<code>&#39;warning&#39;</code>), and an actionable <code>message</code> that includes the remedy.
+<code>onDiagnostic</code> is ignored when <code>strict</code> is set — diagnostics throw instead.
+The code list is a stable, additions-only union (<code>PdfDiagnosticCode</code>), so a
+sink written today keeps compiling as future codes are added.</p>
+<blockquote>
+<p><strong>On the MCP surface</strong> <em>(pdfnative-mcp 1.6.0)</em>, the same honesty is exposed
+as three opt-in inputs on every document tool: <code>embedFonts: true</code> embeds
+Noto Sans Latin so a PDF/A claim on base-14 text is actually accepted by
+veraPDF, <code>strict: true</code> fails instead of producing a non-conformant file,
+and <code>includeDiagnostics: true</code> echoes the engine&#39;s diagnostics
+(<code>PDFA_NO_FONT_ENTRIES</code>, <code>PDFA_UNEMBEDDED_FORM_FONT</code>,
+<code>PDFA_DEVICE_CMYK_IMAGE</code>) in the tool result. Known engine limitation:
+<code>add_form</code> (or a <code>formField</code> block) under a PDF/A claim still fails
+veraPDF even with <code>embedFonts</code> — the AcroForm <code>/DR /Helv</code> font is an
+unembedded Type1 (ISO 19005-2 §6.2.11.4.1).</p>
+</blockquote>
+<h2 id="v110-status--fully-validated">v1.1.0 status — fully validated<a class="heading-anchor" href="#v110-status--fully-validated" aria-label="Link to this section">#</a></h2>
+<p>v1.1.0 ships full PDF/A-1b / 2b / 2u / 3b conformance against the
+official veraPDF reference validator. The validator runs as a
+<strong>blocking</strong> check on every PR (see
+<a href="https://github.com/Nizoka/pdfnative/blob/main/.github/workflows/verapdf.yml" target="_blank" rel="noopener">.github/workflows/verapdf.yml</a>).</p>
+<table>
+<thead>
+<tr>
+<th>Rule</th>
+<th>Status</th>
+<th>Fixed in</th>
+</tr>
+</thead>
+<tbody><tr>
+<td>ISO 19005-1 §6.1.3 — trailer <code>/ID</code> always present</td>
+<td>✅</td>
+<td>v1.0.4</td>
+</tr>
+<tr>
+<td>veraPDF 6.7.3 t1 — <code>CreationDate</code> ↔ <code>xmp:CreateDate</code> parity</td>
+<td>✅</td>
+<td>v1.0.4</td>
+</tr>
+<tr>
+<td>veraPDF 6.7.3 t1 — <code>dc:title</code> ↔ <code>/Info /Title</code> parity</td>
+<td>✅</td>
+<td>v1.1.0</td>
+</tr>
+<tr>
+<td>veraPDF 6.7.3 t4 — <code>dc:description</code> ↔ <code>/Info /Subject</code> parity</td>
+<td>✅</td>
+<td>v1.1.0</td>
+</tr>
+<tr>
+<td>veraPDF 6.7.3 t5 — <code>pdf:Keywords</code> ↔ <code>/Info /Keywords</code> parity</td>
+<td>✅</td>
+<td>v1.1.0</td>
+</tr>
+<tr>
+<td>veraPDF 6.7.3 — <code>dc:creator</code> ↔ <code>/Info /Author</code> parity</td>
+<td>✅</td>
+<td>v1.0.4</td>
+</tr>
+<tr>
+<td>ISO 19005-1 §6.3.4 — Latin font embedding</td>
+<td>✅</td>
+<td>v1.1.0</td>
+</tr>
+<tr>
+<td>ISO 19005-2 §6.2.11.4.1 — Type0 font references</td>
+<td>✅</td>
+<td>v1.1.0</td>
+</tr>
+<tr>
+<td>veraPDF 6.2.3.3 — DeviceRGB OutputIntent</td>
+<td>✅</td>
+<td>v1.0.4</td>
+</tr>
+</tbody></table>
+<p>To produce a strictly veraPDF-compliant PDF/A document, register the Latin
+font module <strong>and resolve it</strong>. Registering alone is not enough: the builders
+are synchronous and cannot await a loader, so the font never reaches the
+document and you get an unembedded Helvetica reference — verified: 0 embedded
+fonts.</p>
+<pre><code class="language-ts">import { registerFonts, loadFontData, buildPDFBytes } from &#39;pdfnative&#39;;
+
+registerFonts({ latin: () =&gt; import(&#39;pdfnative/fonts/noto-sans-data.js&#39;) });
+const fontData = await loadFontData(&#39;latin&#39;);
+
+const pdf = buildPDFBytes(
+  { ...params, fontEntries: [{ fontData, fontRef: &#39;/F3&#39;, lang: &#39;latin&#39; }] },
+  { tagged: true },
+);
+</code></pre>
+<p>Without the <code>&#39;latin&#39;</code> font registered, pdfnative falls back to the
+unembedded Helvetica standard-14 references for byte-stable v1.0.x
+output — convenient for non-archival rendering but invalid under
+PDF/A.</p>
+<h2 id="validating-your-output">Validating your output<a class="heading-anchor" href="#validating-your-output" aria-label="Link to this section">#</a></h2>
+<p>pdfnative ships a thin wrapper around the official veraPDF CLI:</p>
+<pre><code class="language-bash"># 1. Generate the sample suite (writes test-output/)
+npm run test:generate
+
+# 2. Run veraPDF against every PDF/A-claiming sample
+npm run validate:pdfa
+</code></pre>
+<p>The script auto-detects veraPDF on <code>$PATH</code> or via the <code>VERAPDF_HOME</code>
+env var. If veraPDF is not installed it exits 0 with install
+instructions — local development never blocks. CI installs veraPDF
+deterministically (pinned to 1.30.2) and runs the same script on every
+engine PR — see <a href="https://github.com/Nizoka/pdfnative/blob/main/.github/workflows/verapdf.yml" target="_blank" rel="noopener">.github/workflows/verapdf.yml</a> —
+and again as a blocking gate before every npm publish.</p>
+<p>Detection is automatic and guarded: every sample declaring
+<code>pdfaid:part</code> — currently the 18 PDF/A-claiming samples — is validated
+without any registration, and a <strong>coverage canary</strong> fails the run if the
+detected count drifts from <code>declared.pdfaSamples</code> in
+<code>docs/assets/ecosystem.json</code> (bump it when adding or removing a
+claiming sample; a mismatch with no sample change means detection or
+generation regressed).</p>
+<blockquote>
+<p><strong>Which samples are subject to PDF/A validation?</strong> Only files that
+<em>declare</em> a conformance level in their XMP (<code>pdfaid:part</code>) — the ones
+built with <code>tagged: &#39;pdfa…&#39;</code>, e.g. the <code>pdfa/</code> and <code>pdfa-latin/</code> sample
+categories. The script skips everything else. Most showcase samples
+(<code>bidi/</code>, <code>alphabet/</code>, <code>charts/</code>, …) intentionally make <strong>no</strong> PDF/A
+claim: they have no XMP packet at all, so force-validating one against a
+PDF/A profile in the veraPDF GUI fails by construction (missing
+<code>/Metadata</code>, uncalibrated DeviceRGB, …) — that is expected and not a
+defect.</p>
+</blockquote>
+<p>veraPDF is invoked as an <strong>external</strong> Java tool. pdfnative remains a
+zero-runtime-dependency library; veraPDF is never bundled, linked, or
+required by consumers of the npm package.</p>
+<h3 id="installing-verapdf-locally">Installing veraPDF locally<a class="heading-anchor" href="#installing-verapdf-locally" aria-label="Link to this section">#</a></h3>
+<p>veraPDF is a Java application. Pick whichever path matches your OS.
+After install, either expose <code>verapdf</code> on <code>$PATH</code> or set the
+<code>VERAPDF_HOME</code> environment variable to the install directory.</p>
+<p><strong>macOS</strong> — Homebrew cask:</p>
+<pre><code class="language-bash">brew install --cask verapdf
+verapdf --version
+</code></pre>
+<p><strong>Linux</strong> — official installer (headless):</p>
+<pre><code class="language-bash">curl -fsSL -o verapdf-installer.zip https://software.verapdf.org/rel/verapdf-installer.zip
+unzip verapdf-installer.zip
+java -jar verapdf-izpack-installer-*.jar -console
+# follow the prompts; defaults are sane
+export VERAPDF_HOME=&quot;$HOME/verapdf&quot;
+export PATH=&quot;$VERAPDF_HOME:$PATH&quot;
+</code></pre>
+<p><strong>Windows</strong> — official GUI installer from
+<a href="https://docs.verapdf.org/install/" target="_blank" rel="noopener">https://docs.verapdf.org/install/</a>, or the same headless install CI
+uses (download the pinned zip, run
+<code>java -jar verapdf-izpack-installer-*.jar auto-install.xml</code> — the
+descriptor is shown in <a href="https://github.com/Nizoka/pdfnative/blob/main/CONTRIBUTING.md" target="_blank" rel="noopener">CONTRIBUTING</a>).
+After install, either add the install directory to <code>PATH</code> or:</p>
+<pre><code class="language-powershell">$env:VERAPDF_HOME = &quot;C:\Program Files\verapdf&quot;
+$env:Path += &quot;;$env:VERAPDF_HOME&quot;
+verapdf.bat --version
+</code></pre>
+<p>The <code>.bat</code> launcher is fully supported by <code>npm run validate:pdfa</code>
+since v1.7.0 (it is spawned through a shell, as recent Node versions
+require for batch files).</p>
+<p><strong>No install at all?</strong> Drop the file into the official online demo
+at <a href="https://demo.verapdf.org" target="_blank" rel="noopener">https://demo.verapdf.org</a>. It validates against the same engine,
+which is convenient for ad-hoc checks but does not scale to a CI
+suite.</p>
+<h3 id="troubleshooting">Troubleshooting<a class="heading-anchor" href="#troubleshooting" aria-label="Link to this section">#</a></h3>
+<p><strong>&quot;My PDF fails veraPDF for missing XMP / DeviceRGB / unembedded
+font, but I never asked for PDF/A.&quot;</strong></p>
+<p>If the file was generated <strong>without</strong> <code>tagged: true</code>, it is a plain
+ISO 32000-1 document and should not be validated against any PDF/A
+profile. The veraPDF online demo lets you pick a profile manually,
+which will then surface failures by design — every PDF/A rule about
+metadata, output intents, font embedding, transparency, and color
+spaces will fire because the file never claimed any of those things.</p>
+<p>The <code>npm run validate:pdfa</code> wrapper avoids this trap: it scans each
+PDF for a <code>pdfaid:part</code> declaration in the XMP packet and skips
+files that don&#39;t claim PDF/A. The summary line reports how many were
+skipped:</p>
+<pre><code>Scanned 242 PDF(s); 18 claim PDF/A, 224 skipped (not PDF/A).
+</code></pre>
+<p>If you want a file to be validated, generate it with <code>tagged: true</code>
+(or any <code>&#39;pdfa*&#39;</code> value).</p>
+<p><strong>&quot;My tagged file still fails rule 6.3.4 (font embedding).&quot;</strong></p>
+<p>Register the Latin font module <strong>and pass the resolved data as <code>fontEntries</code></strong>
+(see the TL;DR above). Registration on its own does nothing for the synchronous
+builders. Without it, pdfnative emits Helvetica as an unembedded standard-14
+reference for byte-stable v1.0.x output. With it, every glyph used
+in the document is embedded as <code>CIDFontType2</code> / <code>FontFile2</code> — see
+the v1.1.0 status table above. Since v1.7.0 this configuration also emits the
+<code>PDFA_NO_FONT_ENTRIES</code> diagnostic at build time (a thrown error under
+<code>strict: true</code>), so the failure surfaces before veraPDF ever runs.</p>
+<h3 id="output-bytes-change-in-v104">Output bytes change in v1.0.4<a class="heading-anchor" href="#output-bytes-change-in-v104" aria-label="Link to this section">#</a></h3>
+<p>v1.0.4 has no public API break, but PDF outputs differ byte-for-byte
+from v1.0.3:</p>
+<ul>
+<li>Trailer <code>/ID</code> array is now always present.</li>
+<li><code>/Info CreationDate</code> and <code>xmp:CreateDate</code> carry timezone offsets.</li>
+<li><code>dc:creator</code> is emitted only when an author is provided.</li>
+</ul>
+<p>If your test fixtures snapshot full PDF bytes, regenerate them.</p>
+<h2 id="pdfa-vs-encryption">PDF/A vs encryption<a class="heading-anchor" href="#pdfa-vs-encryption" aria-label="Link to this section">#</a></h2>
+<p>ISO 19005-1 §6.3.2 forbids combining PDF/A with PDF encryption.
+pdfnative validates this at the build boundary — passing both
+<code>tagged: …</code> and <code>encryption: …</code> in the same call throws.</p>
+<h2 id="choosing-a-flavour">Choosing a flavour<a class="heading-anchor" href="#choosing-a-flavour" aria-label="Link to this section">#</a></h2>
+<table>
+<thead>
+<tr>
+<th>Flavour</th>
+<th>Base PDF</th>
+<th>Notes</th>
+</tr>
+</thead>
+<tbody><tr>
+<td>PDF/A-1b (<code>&#39;pdfa1b&#39;</code>)</td>
+<td>PDF 1.4</td>
+<td>Most conservative — required by some legacy archival systems. No transparency, no JPEG2000, no AES.</td>
+</tr>
+<tr>
+<td>PDF/A-2b (<code>true</code> / <code>&#39;pdfa2b&#39;</code>)</td>
+<td>PDF 1.7</td>
+<td>Default. Allows transparency, layers, embedded TrueType.</td>
+</tr>
+<tr>
+<td>PDF/A-2u (<code>&#39;pdfa2u&#39;</code>)</td>
+<td>PDF 1.7</td>
+<td>2b + Unicode mapping for every glyph. Required when <code>/ActualText</code> and ToUnicode CMap completeness matter (recommended for accessibility).</td>
+</tr>
+<tr>
+<td>PDF/A-3b (<code>&#39;pdfa3b&#39;</code>)</td>
+<td>PDF 1.7</td>
+<td>2b + arbitrary <code>/EmbeddedFile</code> attachments (XML, source data, etc.).</td>
+</tr>
+</tbody></table>
+<p>All four flavours share the same XMP / OutputIntent / structure-tree
+infrastructure — pdfnative only varies the PDF version, the
+<code>pdfaid:part</code>, and the <code>pdfaid:conformance</code> value.</p>
+<h3 id="canonical-list-for-tooling">Canonical list for tooling<a class="heading-anchor" href="#canonical-list-for-tooling" aria-label="Link to this section">#</a></h3>
+<p>The four legal <code>tagged</code> strings are also exposed as a
+typed constant for tooling that needs to populate a JSON-schema
+<code>enum:</code> (<code>pdfnative-mcp</code> does this for its MCP tool descriptions so
+Gemini-CLI and other agents can autocomplete the right value):</p>
+<pre><code class="language-ts">import { PDF_A_CONFORMANCE_TARGETS, type PdfAConformanceTarget } from &#39;pdfnative&#39;;
+
+PDF_A_CONFORMANCE_TARGETS;
+// → readonly [&#39;pdfa1b&#39;, &#39;pdfa2b&#39;, &#39;pdfa2u&#39;, &#39;pdfa3b&#39;]
+
+function isValidTarget(s: string): s is PdfAConformanceTarget {
+  return (PDF_A_CONFORMANCE_TARGETS as readonly string[]).includes(s);
+}
+</code></pre>
+<p>The constant is the single source of truth — adding a new target in a
+future minor release will surface automatically in every downstream
+consumer that imports it.</p>
+<h2 id="hard-invariants-for-contributors">Hard invariants for contributors<a class="heading-anchor" href="#hard-invariants-for-contributors" aria-label="Link to this section">#</a></h2>
+<p>These rules are documented in the contributor instruction file
+<a href="https://github.com/Nizoka/pdfnative/blob/main/.github/instructions/pdfa-conformance.instructions.md" target="_blank" rel="noopener">.github/instructions/pdfa-conformance.instructions.md</a>:</p>
+<ul>
+<li><code>/Info CreationDate</code> and <code>xmp:CreateDate</code> come from the <strong>same</strong>
+<code>buildPdfMetadata()</code> call. Never inline <code>new Date()</code> in the builders.</li>
+<li>The unencrypted trailer <code>/ID</code> is derived deterministically from
+<code>MD5(title + creationDate + objectCount)</code>. Never randomize — it
+breaks <code>buildPDFBytes(params)</code> byte-equality tests.</li>
+<li><code>dc:creator</code> is emitted only when an author is provided and is
+XML-escaped.</li>
+<li>XMP metadata streams are never compressed.</li>
+<li>Compression always happens <strong>before</strong> encryption (ISO 32000-1
+§7.3.8).</li>
+</ul>
+<h2 id="see-also">See also<a class="heading-anchor" href="#see-also" aria-label="Link to this section">#</a></h2>
+<ul>
+<li><a href="https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md" target="_blank" rel="noopener">CHANGELOG.md</a>
+— full v1.0.4 release notes.</li>
+<li><a href="https://verapdf.org" target="_blank" rel="noopener">veraPDF</a> — the official reference validator.</li>
+<li><a href="https://www.iso.org/standard/38920.html" target="_blank" rel="noopener">ISO 19005-1</a> /
+<a href="https://www.iso.org/standard/50655.html" target="_blank" rel="noopener">ISO 19005-2</a> /
+<a href="https://www.iso.org/standard/57229.html" target="_blank" rel="noopener">ISO 19005-3</a>.</li>
+</ul>
+<!-- guide:render:end -->
   </article>
 </main>
 
diff --git a/docs/guides/pdfa.md b/docs/guides/pdfa.md
index 87e8a40..af06ee0 100644
--- a/docs/guides/pdfa.md
+++ b/docs/guides/pdfa.md
@@ -1,5 +1,7 @@
 # PDF/A conformance in pdfnative
 
+> **PDF/A-1b, 2b, 2u and 3b via `layout: { tagged: … }`, validated against the veraPDF reference validator in CI.** Since v1.7.0, a configuration that would break the declared level surfaces a diagnostic — `console.warn` by default, a custom `onDiagnostic` sink, or a thrown error under `strict: true`.
+
 PDF/A is the ISO archival profile for PDF (ISO 19005). pdfnative supports
 PDF/A-1b, 2b, 2u, and 3b via the `tagged` build option. This guide
 explains what works today, what's still in flight, and how to validate
@@ -101,6 +103,17 @@ Each `PdfDiagnostic` carries a machine-readable `code`, a `severity`
 The code list is a stable, additions-only union (`PdfDiagnosticCode`), so a
 sink written today keeps compiling as future codes are added.
 
+> **On the MCP surface** _(pdfnative-mcp 1.6.0)_, the same honesty is exposed
+> as three opt-in inputs on every document tool: `embedFonts: true` embeds
+> Noto Sans Latin so a PDF/A claim on base-14 text is actually accepted by
+> veraPDF, `strict: true` fails instead of producing a non-conformant file,
+> and `includeDiagnostics: true` echoes the engine's diagnostics
+> (`PDFA_NO_FONT_ENTRIES`, `PDFA_UNEMBEDDED_FORM_FONT`,
+> `PDFA_DEVICE_CMYK_IMAGE`) in the tool result. Known engine limitation:
+> `add_form` (or a `formField` block) under a PDF/A claim still fails
+> veraPDF even with `embedFonts` — the AcroForm `/DR /Helv` font is an
+> unembedded Type1 (ISO 19005-2 §6.2.11.4.1).
+
 ## v1.1.0 status — fully validated
 
 v1.1.0 ships full PDF/A-1b / 2b / 2u / 3b conformance against the
diff --git a/docs/guides/print.html b/docs/guides/print.html
index d326a3d..16ae92e 100644
--- a/docs/guides/print.html
+++ b/docs/guides/print.html
@@ -9,6 +9,7 @@
   <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/print.html">
   <link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/print.html">
   <link rel="alternate" type="text/markdown" href="print.md">
+  <link rel="alternate" type="text/plain" href="../llms.txt" title="llms.txt — machine-readable documentation index">
   <meta property="og:type" content="article">
   <meta property="og:site_name" content="pdfnative">
   <meta property="og:locale" content="en_US">
@@ -26,6 +27,9 @@
   <link rel="stylesheet" href="../style.css">
   <link rel="stylesheet" href="guide.css">
   <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
+  <!-- guide:ld:start -->
+  <script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://pdfnative.dev/"},{"@type":"ListItem","position":2,"name":"Guides","item":"https://pdfnative.dev/guides/"},{"@type":"ListItem","position":3,"name":"Print production — bleed, trim & printer's marks","item":"https://pdfnative.dev/guides/print.html"}]},{"@type":"TechArticle","headline":"Print production — bleed, trim & printer's marks","description":"Print-ready PDFs in pdfnative — bleed, trim, art and crop boxes, crop and registration marks, /Trapped, duplex print defaults, custom OutputIntent ICC, and large-format /UserUnit.","inLanguage":"en","author":{"@type":"Organization","name":"Nizoka","url":"https://github.com/Nizoka"},"publisher":{"@type":"Organization","name":"pdfnative","url":"https://pdfnative.dev","logo":{"@type":"ImageObject","url":"https://pdfnative.dev/assets/logo.svg"}},"mainEntityOfPage":{"@type":"WebPage","@id":"https://pdfnative.dev/guides/print.html"},"isPartOf":{"@type":"WebSite","name":"pdfnative","url":"https://pdfnative.dev"}}]}</script>
+  <!-- guide:ld:end -->
 </head>
 <body>
 
@@ -57,9 +61,148 @@
 
 <main class="guide-shell" id="main-content" tabindex="-1">
   <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; Print production</p>
-  <article id="guide-content" class="guide-content" data-md="print.md">
-    <p class="guide-loading">Loading…</p>
-    <noscript><p>This guide is written in Markdown: <a href="print.md">read print.md</a>.</p></noscript>
+  <article id="guide-content" class="guide-content" data-md="print.md" data-prerendered="true">
+<!-- guide:render:start -->
+<h1 id="print-production--bleed-trim--printers-marks">Print production — bleed, trim &amp; printer&#39;s marks</h1>
+<blockquote>
+<p><strong>New in v1.7.0.</strong> Print-ready PDFs with zero dependencies: page geometry boxes (<code>/TrimBox</code>, <code>/BleedBox</code>, <code>/ArtBox</code>, <code>/CropBox</code>), crop and registration marks drawn as pure vector operators, <code>/Trapped</code> metadata with XMP parity, print-dialog defaults (duplex, tray, page range, copies), a caller-supplied OutputIntent ICC profile, and large-format <code>/UserUnit</code>. Everything is opt-in — output is byte-identical when unused.</p>
+</blockquote>
+<h2 id="tldr">TL;DR<a class="heading-anchor" href="#tldr" aria-label="Link to this section">#</a></h2>
+<pre><code class="language-ts">import { buildDocumentPDFBytes, PAGE_SIZES } from &#39;pdfnative&#39;;
+
+const BLEED = 8.5; // 3 mm in points
+
+const pdf = buildDocumentPDFBytes(params, {
+  // Design the page at trim size + bleed on every side…
+  pageWidth:  PAGE_SIZES.A4.width  + 2 * BLEED,
+  pageHeight: PAGE_SIZES.A4.height + 2 * BLEED,
+  margins: { t: 36 + BLEED, r: 36 + BLEED, b: 36 + BLEED, l: 36 + BLEED },
+  // …declare the geometry and draw the marks:
+  print: { bleed: BLEED, marks: true },
+  viewerPreferences: { duplex: &#39;duplexFlipLongEdge&#39;, pickTrayByPDFSize: true },
+});
+</code></pre>
+<p>Open the result in Acrobat with <em>Preferences → Page Display → Show art, trim &amp; bleed boxes</em> to see the geometry.</p>
+<h2 id="the-box-model-iso-32000-1-14112">The box model (ISO 32000-1 §14.11.2)<a class="heading-anchor" href="#the-box-model-iso-32000-1-14112" aria-label="Link to this section">#</a></h2>
+<pre><code>┌─────────────────────────────┐  MediaBox — the physical page (sheet)
+│  ┌───────────────────────┐  │  BleedBox — content clipped in production
+│  │ ┌───────────────────┐ │  │  TrimBox — the finished page after cutting
+│  │ │      ArtBox       │ │  │  ArtBox — meaningful-content extent
+│  │ └───────────────────┘ │  │
+│  │  backgrounds run here │  │  ← bleed zone: extend backgrounds into it
+│  └───────────────────────┘  │
+└─────────────────────────────┘
+</code></pre>
+<table>
+<thead>
+<tr>
+<th>Option</th>
+<th>PDF key</th>
+<th>Meaning</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>print.bleed</code></td>
+<td>derives both</td>
+<td>Shorthand: <code>TrimBox</code> = MediaBox inset by the bleed, <code>BleedBox</code> = MediaBox</td>
+</tr>
+<tr>
+<td><code>print.trimBox</code></td>
+<td><code>/TrimBox</code></td>
+<td>Finished page size after cutting</td>
+</tr>
+<tr>
+<td><code>print.bleedBox</code></td>
+<td><code>/BleedBox</code></td>
+<td>Clipping extent in production</td>
+</tr>
+<tr>
+<td><code>print.artBox</code></td>
+<td><code>/ArtBox</code></td>
+<td>Meaningful-content extent</td>
+</tr>
+<tr>
+<td><code>print.cropBox</code></td>
+<td><code>/CropBox</code></td>
+<td>Region viewers display/print</td>
+</tr>
+</tbody></table>
+<p>Boxes are validated (within the MediaBox, trim within bleed) and are pure page-dictionary metadata — the layout engine is untouched, so design the page at <em>trim + 2×bleed</em> and enlarge the margins by the bleed, letting backgrounds run to the page edge.</p>
+<p><code>mergePdfs</code> / <code>splitPdf</code> / <code>extractPages</code> preserve all four boxes (and <code>/UserUnit</code>).</p>
+<h2 id="printers-marks-14113">Printer&#39;s marks (§14.11.3)<a class="heading-anchor" href="#printers-marks-14113" aria-label="Link to this section">#</a></h2>
+<p><code>print.marks: true</code> draws, on every page, strictly <strong>outside</strong> the TrimBox:</p>
+<ul>
+<li><strong>Crop marks</strong> — 8 corner hairlines (default 0.25 pt, 14 pt long, 5 pt clear of the trim edge) showing where to cut.</li>
+<li><strong>Registration targets</strong> — circle-and-cross targets on the four edge midpoints, used to align separations.</li>
+</ul>
+<p>Fine-tune with an object: <code>marks: { crop, registration, length, offset, weight }</code>.</p>
+<blockquote>
+<p>Marks are stroked in RGB black. A true all-separation <em>registration colour</em> requires CMYK content support, which is on the roadmap together with PDF/X — see below.</p>
+</blockquote>
+<h2 id="trapped-and-prepress-metadata">/Trapped and prepress metadata<a class="heading-anchor" href="#trapped-and-prepress-metadata" aria-label="Link to this section">#</a></h2>
+<pre><code class="language-ts">buildDocumentPDFBytes({ ...params, metadata: { trapped: &#39;False&#39; } }, { tagged: &#39;pdfa2b&#39; });
+</code></pre>
+<p>Writes <code>/Info /Trapped /False</code> and mirrors it as <code>pdf:Trapped</code> in the XMP packet, telling the RIP whether trapping has been applied. Because <code>pdf:Trapped</code> is not part of the XMP-2005 Adobe PDF schema that PDF/A pins, pdfnative also emits the required PDF/A extension schema declaring the property (ISO 19005 §6.6.2.3.2) — the document stays veraPDF-compliant. Per ISO 32000-1 Table 317, <code>trapped: &#39;Unknown&#39;</code> is written to <code>/Info</code> only: unknown maps to the <em>absence</em> of <code>pdf:Trapped</code> in XMP.</p>
+<h2 id="print-dialog-defaults-viewerpreferences">Print-dialog defaults (<code>viewerPreferences</code>)<a class="heading-anchor" href="#print-dialog-defaults-viewerpreferences" aria-label="Link to this section">#</a></h2>
+<table>
+<thead>
+<tr>
+<th>Option</th>
+<th>PDF key</th>
+<th>Values</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>duplex</code></td>
+<td><code>/Duplex</code></td>
+<td><code>&#39;simplex&#39;</code>, <code>&#39;duplexFlipShortEdge&#39;</code>, <code>&#39;duplexFlipLongEdge&#39;</code></td>
+</tr>
+<tr>
+<td><code>pickTrayByPDFSize</code></td>
+<td><code>/PickTrayByPDFSize</code></td>
+<td>boolean (Windows viewers)</td>
+</tr>
+<tr>
+<td><code>printPageRange</code></td>
+<td><code>/PrintPageRange</code></td>
+<td>1-based <code>[first, last]</code> pairs, e.g. <code>[[1, 4], [7, 7]]</code></td>
+</tr>
+<tr>
+<td><code>numCopies</code></td>
+<td><code>/NumCopies</code></td>
+<td>positive integer</td>
+</tr>
+</tbody></table>
+<p>These join the existing v1.4.0 viewer preferences and remain PDF/A-safe metadata.</p>
+<h2 id="custom-outputintent-taggedpdf-a">Custom OutputIntent (tagged/PDF-A)<a class="heading-anchor" href="#custom-outputintent-taggedpdf-a" aria-label="Link to this section">#</a></h2>
+<p>Replace the built-in minimal sRGB profile with a real ICC profile:</p>
+<pre><code class="language-ts">import { readFileSync } from &#39;node:fs&#39;;
+
+buildDocumentPDFBytes(params, {
+  tagged: &#39;pdfa2b&#39;,
+  outputIntent: {
+    iccProfile: new Uint8Array(readFileSync(&#39;sRGB-IEC61966-2.1.icc&#39;)),
+    outputConditionIdentifier: &#39;sRGB IEC61966-2.1&#39;,
+    outputCondition: &#39;sRGB display&#39;,
+    info: &#39;IEC 61966-2.1 reference profile&#39;,
+  },
+});
+</code></pre>
+<p>RGB profiles only — pdfnative emits RGB content, and a mismatched intent fails PDF/A validation (a CMYK profile throws with an actionable message). Omitted, the historical built-in profile is used byte-identically.</p>
+<h2 id="large-formats--userunit">Large formats — <code>/UserUnit</code><a class="heading-anchor" href="#large-formats--userunit" aria-label="Link to this section">#</a></h2>
+<p>PDF user space caps pages at 14 400 units (200 in). For banners and plans, <code>print.userUnit</code> scales the unit (1 unit = <code>userUnit</code>/72 inch, up to 75 000):</p>
+<pre><code class="language-ts">// A 5 m × 1 m banner: 1417 × 283 units at 10/72 inch per unit.
+buildDocumentPDFBytes(params, { pageWidth: 1417, pageHeight: 283, print: { userUnit: 10 } });
+</code></pre>
+<p><code>/UserUnit</code> needs PDF 1.6+, so the header is raised to <code>%PDF-1.7</code> when the option is set — and it is rejected under <code>tagged: &#39;pdfa1b&#39;</code> (PDF/A-1 is PDF 1.4; use <code>pdfa2b</code> or later).</p>
+<h2 id="limits--scope-v170">Limits &amp; scope (v1.7.0)<a class="heading-anchor" href="#limits--scope-v170" aria-label="Link to this section">#</a></h2>
+<ul>
+<li>Marks are RGB black; <strong>no CMYK content</strong>, spot colours, colour bars or <strong>PDF/X</strong> conformance claims yet — all on the roadmap as one coherent CMYK workstream.</li>
+<li>One geometry per document (pages share the same boxes), matching the single-page-size layout model.</li>
+<li>The OutputIntent (custom or built-in) is emitted under <code>tagged</code> modes only.</li>
+</ul>
+<p>See the <a href="https://github.com/Nizoka/pdfnative/blob/main/scripts/generators/print-showcase.ts" target="_blank" rel="noopener">print samples</a>: <code>print/print-bleed-marks.pdf</code>, <code>print/print-explicit-boxes.pdf</code>, <code>print/print-large-format.pdf</code>.</p>
+<!-- guide:render:end -->
   </article>
 </main>
 
diff --git a/docs/guides/quickstart.html b/docs/guides/quickstart.html
index d8d9b14..9b562c1 100644
--- a/docs/guides/quickstart.html
+++ b/docs/guides/quickstart.html
@@ -9,6 +9,7 @@
   <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/quickstart.html">
   <link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/quickstart.html">
   <link rel="alternate" type="text/markdown" href="quickstart.md">
+  <link rel="alternate" type="text/plain" href="../llms.txt" title="llms.txt — machine-readable documentation index">
   <meta property="og:type" content="article">
   <meta property="og:site_name" content="pdfnative">
   <meta property="og:locale" content="en_US">
@@ -26,6 +27,9 @@
   <link rel="stylesheet" href="../style.css">
   <link rel="stylesheet" href="guide.css">
   <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
+  <!-- guide:ld:start -->
+  <script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://pdfnative.dev/"},{"@type":"ListItem","position":2,"name":"Guides","item":"https://pdfnative.dev/guides/"},{"@type":"ListItem","position":3,"name":"Quick Start","item":"https://pdfnative.dev/guides/quickstart.html"}]},{"@type":"TechArticle","headline":"Quick Start","description":"Generate your first PDF with pdfnative in under a minute — install, render a document, and export bytes. Node.js ≥ 22, browsers, Deno, and Bun. Zero runtime dependencies.","inLanguage":"en","author":{"@type":"Organization","name":"Nizoka","url":"https://github.com/Nizoka"},"publisher":{"@type":"Organization","name":"pdfnative","url":"https://pdfnative.dev","logo":{"@type":"ImageObject","url":"https://pdfnative.dev/assets/logo.svg"}},"mainEntityOfPage":{"@type":"WebPage","@id":"https://pdfnative.dev/guides/quickstart.html"},"isPartOf":{"@type":"WebSite","name":"pdfnative","url":"https://pdfnative.dev"}}]}</script>
+  <!-- guide:ld:end -->
 </head>
 <body>
 
@@ -57,9 +61,191 @@
 
 <main class="guide-shell" id="main-content" tabindex="-1">
   <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; Quick Start</p>
-  <article id="guide-content" class="guide-content" data-md="quickstart.md">
-    <p class="guide-loading">Loading…</p>
-    <noscript><p>This guide is written in Markdown: <a href="quickstart.md">read quickstart.md</a>.</p></noscript>
+  <article id="guide-content" class="guide-content" data-md="quickstart.md" data-prerendered="true">
+<!-- guide:render:start -->
+<h1 id="quick-start">Quick Start</h1>
+<blockquote>
+<p><strong>One install, one function.</strong> <code>npm install pdfnative</code>, then <code>buildDocumentPDFBytes({ title, blocks })</code> returns a <code>Uint8Array</code> — synchronously, in Node, browsers, Deno and Bun. No config, no build step, no service.</p>
+</blockquote>
+<p>Generate your first PDF in under a minute.</p>
+<h2 id="install">Install<a class="heading-anchor" href="#install" aria-label="Link to this section">#</a></h2>
+<pre><code class="language-bash">npm install pdfnative
+</code></pre>
+<blockquote>
+<p><strong>Requirements:</strong> Node.js ≥ 22 · modern browsers · Deno · Bun.
+Zero runtime dependencies are installed.</p>
+</blockquote>
+<h2 id="nodejs">Node.js<a class="heading-anchor" href="#nodejs" aria-label="Link to this section">#</a></h2>
+<pre><code class="language-typescript">import { writeFileSync } from &#39;node:fs&#39;;
+import { buildDocumentPDFBytes } from &#39;pdfnative&#39;;
+
+const pdf = buildDocumentPDFBytes({
+  title: &#39;Hello&#39;,
+  blocks: [
+    { type: &#39;heading&#39;,   text: &#39;Hello, pdfnative&#39;, level: 1 },
+    { type: &#39;paragraph&#39;, text: &#39;Pure native PDF — zero dependencies, ISO 32000-1.&#39; },
+  ],
+});
+
+writeFileSync(&#39;hello.pdf&#39;, pdf);
+</code></pre>
+<p>For optimal compression on Node.js, enable native zlib once at startup:</p>
+<pre><code class="language-typescript">import { initNodeCompression, buildDocumentPDFBytes } from &#39;pdfnative&#39;;
+
+await initNodeCompression();
+
+const pdf = buildDocumentPDFBytes(params, { compress: true });
+</code></pre>
+<h2 id="browser">Browser<a class="heading-anchor" href="#browser" aria-label="Link to this section">#</a></h2>
+<pre><code class="language-html">&lt;script type=&quot;module&quot;&gt;
+  import { buildDocumentPDFBytes, downloadBlob } from &#39;https://esm.sh/pdfnative@1.7.0&#39;;
+
+  document.getElementById(&#39;go&#39;).addEventListener(&#39;click&#39;, () =&gt; {
+    const pdf = buildDocumentPDFBytes({
+      title: &#39;Hello&#39;,
+      blocks: [
+        { type: &#39;heading&#39;, text: &#39;Hello from the browser&#39;, level: 1 },
+      ],
+    });
+    downloadBlob(pdf, &#39;hello.pdf&#39;);
+  });
+&lt;/script&gt;
+</code></pre>
+<p>A stored-block compression fallback works automatically — no native zlib needed in the browser.</p>
+<h2 id="tabular-reports--buildpdfbytes">Tabular reports — <code>buildPDFBytes</code><a class="heading-anchor" href="#tabular-reports--buildpdfbytes" aria-label="Link to this section">#</a></h2>
+<p>For bank statements, invoices, and any single-table report:</p>
+<pre><code class="language-typescript">import { buildPDFBytes } from &#39;pdfnative&#39;;
+
+const pdf = buildPDFBytes({
+  title: &#39;Monthly Report&#39;,
+  infoItems: [
+    { label: &#39;Period&#39;,  value: &#39;January 2026&#39; },
+    { label: &#39;Account&#39;, value: &#39;Main&#39; },
+  ],
+  balanceText: &#39;Balance: $1,234.56&#39;,
+  countText: &#39;42 transactions&#39;,
+  headers: [&#39;Date&#39;, &#39;Description&#39;, &#39;Amount&#39;],
+  rows: [
+    { cells: [&#39;01/15&#39;, &#39;Grocery&#39;, &#39;-$45.00&#39;],   type: &#39;debit&#39;,  pointed: false },
+    { cells: [&#39;01/16&#39;, &#39;Salary&#39;,  &#39;+$3,000.00&#39;], type: &#39;credit&#39;, pointed: true  },
+  ],
+  footerText: &#39;Generated by MyApp&#39;,
+});
+</code></pre>
+<h2 id="free-form-documents--builddocumentpdfbytes">Free-form documents — <code>buildDocumentPDFBytes</code><a class="heading-anchor" href="#free-form-documents--builddocumentpdfbytes" aria-label="Link to this section">#</a></h2>
+<p>For mixed content (manuals, articles, multi-section reports):</p>
+<pre><code class="language-typescript">const pdf = buildDocumentPDFBytes({
+  title: &#39;Project Report&#39;,
+  blocks: [
+    { type: &#39;toc&#39; },
+    { type: &#39;heading&#39;,   text: &#39;Executive Summary&#39;, level: 1 },
+    { type: &#39;paragraph&#39;, text: &#39;This quarter saw strong growth.&#39; },
+    { type: &#39;list&#39;, style: &#39;bullet&#39;, items: [&#39;Revenue +15%&#39;, &#39;Costs −8%&#39;] },
+    { type: &#39;image&#39;, data: chartBytes, width: 400, alt: &#39;Revenue chart&#39; },
+    { type: &#39;barcode&#39;, format: &#39;qr&#39;, data: &#39;https://example.com&#39;, width: 80 },
+    { type: &#39;pageBreak&#39; },
+    { type: &#39;heading&#39;,   text: &#39;Details&#39;, level: 1 },
+    { type: &#39;table&#39;, headers: [&#39;Q&#39;, &#39;Revenue&#39;], rows: [
+      { cells: [&#39;Q1&#39;, &#39;$1.2M&#39;], type: &#39;&#39;, pointed: false },
+      { cells: [&#39;Q2&#39;, &#39;$1.4M&#39;], type: &#39;&#39;, pointed: false },
+    ] },
+  ],
+  footerText: &#39;Confidential&#39;,
+});
+</code></pre>
+<p>13 block types are available: <code>heading</code>, <code>paragraph</code>, <code>list</code>, <code>table</code>, <code>image</code>, <code>link</code>, <code>spacer</code>, <code>pageBreak</code>, <code>toc</code>, <code>barcode</code>, <code>svg</code>, <code>formField</code>, <code>chart</code>.</p>
+<h2 id="multi-language">Multi-language<a class="heading-anchor" href="#multi-language" aria-label="Link to this section">#</a></h2>
+<pre><code class="language-typescript">import { registerFonts, loadFontData, buildDocumentPDFBytes } from &#39;pdfnative&#39;;
+
+registerFonts({
+  th: () =&gt; import(&#39;pdfnative/fonts/noto-thai-data.js&#39;),
+  ar: () =&gt; import(&#39;pdfnative/fonts/noto-arabic-data.js&#39;),
+});
+
+const fontEntries = await Promise.all([
+  loadFontData(&#39;th&#39;).then(fd =&gt; ({ fontData: fd!, fontRef: &#39;/F3&#39;, lang: &#39;th&#39; })),
+  loadFontData(&#39;ar&#39;).then(fd =&gt; ({ fontData: fd!, fontRef: &#39;/F4&#39;, lang: &#39;ar&#39; })),
+]);
+
+const pdf = buildDocumentPDFBytes({
+  blocks: [{ type: &#39;paragraph&#39;, text: &#39;สวัสดี — مرحبا&#39; }],
+  fontEntries,
+});
+</code></pre>
+<p>Note that <code>lang</code> is a property of each <strong>font entry</strong>, not of a block: pdfnative detects the script per character and routes to the matching font, so a single paragraph can mix Thai, Arabic and Latin. BiDi resolution and OpenType shaping follow from that routing. See the <a href="faq.html#fonts-and-unicode">FAQ → Fonts and Unicode</a> for the full list of codes.</p>
+<h2 id="web-worker">Web Worker<a class="heading-anchor" href="#web-worker" aria-label="Link to this section">#</a></h2>
+<p><code>createPDF</code> is the recommended entry point — it decides between the main thread and a worker for you:</p>
+<pre><code class="language-typescript">import { createPDF } from &#39;pdfnative&#39;;
+
+const pdf = await createPDF(params, {
+  workerUrl: new URL(&#39;./pdf-worker.js&#39;, import.meta.url), // your worker script
+  threshold: 500,   // rows above this go to the worker (default WORKER_THRESHOLD = 500)
+  onProgress: (p) =&gt; console.log(`${p}%`),
+});
+</code></pre>
+<p>At or below the <code>threshold</code> (or when <code>Worker</code> / <code>workerUrl</code> is unavailable) the PDF is generated on the main thread; above it, the worker at <code>workerUrl</code> is spawned, with an automatic main-thread fallback if the worker fails.</p>
+<p>To drive a worker directly, use <code>generatePDFInWorker(workerUrl, params, { timeout, onProgress })</code> — note the worker URL is the <strong>first</strong> argument, and the options are <code>timeout</code> (ms, default 60 000) and <code>onProgress</code> (there is no threshold at this level).</p>
+<h2 id="streaming">Streaming<a class="heading-anchor" href="#streaming" aria-label="Link to this section">#</a></h2>
+<pre><code class="language-typescript">import { buildDocumentPDFStream, concatChunks } from &#39;pdfnative&#39;;
+
+// buildDocumentPDFStream(params, layoutOptions?, streamOptions?)
+// chunkSize lives in the 3rd argument (StreamOptions)
+const chunks: Uint8Array[] = [];
+
+for await (const chunk of buildDocumentPDFStream(
+  params,
+  {},                        // layoutOptions
+  { chunkSize: 65536 },      // streamOptions
+)) {
+  chunks.push(chunk);
+}
+
+const pdf = concatChunks(chunks);
+</code></pre>
+<p>The async iterable yields <code>Uint8Array</code> chunks as the PDF is produced — no full-document buffering. The three-argument API (<code>params</code>, <code>layoutOptions</code>, <code>streamOptions</code>) keeps layout concerns (tagged, compress, watermark) and streaming concerns (chunk size) separate.</p>
+<h2 id="playgrounds">Playgrounds<a class="heading-anchor" href="#playgrounds" aria-label="Link to this section">#</a></h2>
+<p>The interactive playgrounds on <a href="https://pdfnative.dev" target="_blank" rel="noopener">pdfnative.dev</a> run entirely in the browser:</p>
+<ul>
+<li><a href="../playgrounds/extreme-scripts.html">Extreme scripts</a> — live BiDi, Tamil, Bengali + Devanagari, Arabic harakat</li>
+<li><a href="../playgrounds/scale.html">Scale</a> — 1,000 to 100,000 pages, Web Worker + true streaming</li>
+</ul>
+<blockquote>
+<p><strong>Local testing:</strong> opening the playgrounds as <code>file://</code> disables the Web Worker
+(browsers block cross-origin Worker imports from <code>file:</code> origins).
+Serve the docs directory instead:</p>
+<pre><code class="language-bash">npm run docs:serve   # → http://localhost:5000
+</code></pre>
+</blockquote>
+<h2 id="command-line--pdfnative-cli">Command line — pdfnative-cli<a class="heading-anchor" href="#command-line--pdfnative-cli" aria-label="Link to this section">#</a></h2>
+<p>Prefer the terminal? <a href="https://github.com/Nizoka/pdfnative-cli" target="_blank" rel="noopener"><code>pdfnative-cli</code></a> wraps the same library with 17 commands — including <code>render</code>, <code>fill</code>, <code>sign</code>, <code>verify</code>, <code>encrypt</code>, <code>decrypt</code>, <code>merge</code>, <code>split</code>, <code>extract</code> and <code>extract-text</code>:</p>
+<pre><code class="language-bash"># Install once
+npm install --global pdfnative-cli
+
+# Render a JSON document to a PDF
+pdfnative render --input report.json --output report.pdf
+
+# Sign with an RSA key (loaded from env var, never logged)
+export PDFNATIVE_SIGN_KEY=&quot;$(cat private.pem)&quot;
+export PDFNATIVE_SIGN_CERT=&quot;$(cat cert.pem)&quot;
+pdfnative sign --input report.pdf --output report.signed.pdf
+
+# Inspect any PDF (encryption, signatures, PDF/A, metadata)
+pdfnative inspect --input report.signed.pdf --format text
+</code></pre>
+<p>Stdin/stdout makes it composable in shell pipelines:</p>
+<pre><code class="language-bash">cat report.json | pdfnative render | pdfnative sign | pdfnative inspect --format text
+</code></pre>
+<p>See the dedicated <a href="cli.html">CLI guide</a> for the full command reference, security model, and CI/CD recipes.</p>
+<h2 id="next-steps">Next steps<a class="heading-anchor" href="#next-steps" aria-label="Link to this section">#</a></h2>
+<ul>
+<li><a href="architecture.html">Architecture</a> — modules, builders, generation pipeline.</li>
+<li><a href="cli.html">CLI</a> — pdfnative-cli command-line interface.</li>
+<li><a href="accessibility.html">Accessibility</a> — tagged PDF, PDF/UA, PDF/A.</li>
+<li><a href="faq.html">FAQ</a> — fonts, encryption, signatures, comparisons.</li>
+<li><a href="troubleshooting.html">Troubleshooting</a> — common pitfalls and fixes.</li>
+<li><a href="https://github.com/Nizoka/pdfnative/tree/main/scripts/generators" target="_blank" rel="noopener">Sample generators</a> — 242 PDFs across 37 categories (48 generators).</li>
+</ul>
+<!-- guide:render:end -->
   </article>
 </main>
 
diff --git a/docs/guides/quickstart.md b/docs/guides/quickstart.md
index be0b5df..a4216a8 100644
--- a/docs/guides/quickstart.md
+++ b/docs/guides/quickstart.md
@@ -1,5 +1,7 @@
 # Quick Start
 
+> **One install, one function.** `npm install pdfnative`, then `buildDocumentPDFBytes({ title, blocks })` returns a `Uint8Array` — synchronously, in Node, browsers, Deno and Bun. No config, no build step, no service.
+
 Generate your first PDF in under a minute.
 
 ## Install
diff --git a/docs/guides/react.html b/docs/guides/react.html
index 6e0f116..ef5a98b 100644
--- a/docs/guides/react.html
+++ b/docs/guides/react.html
@@ -10,6 +10,7 @@
   <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/react.html">
   <link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/react.html">
   <link rel="alternate" type="text/markdown" href="react.md">
+  <link rel="alternate" type="text/plain" href="../llms.txt" title="llms.txt — machine-readable documentation index">
   <meta property="og:type" content="article">
   <meta property="og:site_name" content="pdfnative">
   <meta property="og:locale" content="en_US">
@@ -27,6 +28,9 @@
   <link rel="stylesheet" href="../style.css">
   <link rel="stylesheet" href="guide.css">
   <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
+  <!-- guide:ld:start -->
+  <script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://pdfnative.dev/"},{"@type":"ListItem","position":2,"name":"Guides","item":"https://pdfnative.dev/guides/"},{"@type":"ListItem","position":3,"name":"pdfnative-react — Declarative JSX Renderer Guide","item":"https://pdfnative.dev/guides/react.html"}]},{"@type":"TechArticle","headline":"pdfnative-react — Declarative JSX Renderer Guide","description":"Render PDFs from declarative JSX with pdfnative-react — Document/Page/Table/Barcode components compiled on-device, live preview hooks, 22 Unicode scripts. React 19.","inLanguage":"en","author":{"@type":"Organization","name":"Nizoka","url":"https://github.com/Nizoka"},"publisher":{"@type":"Organization","name":"pdfnative","url":"https://pdfnative.dev","logo":{"@type":"ImageObject","url":"https://pdfnative.dev/assets/logo.svg"}},"mainEntityOfPage":{"@type":"WebPage","@id":"https://pdfnative.dev/guides/react.html"},"isPartOf":{"@type":"WebSite","name":"pdfnative","url":"https://pdfnative.dev"}}]}</script>
+  <!-- guide:ld:end -->
 </head>
 <body>
 
@@ -58,9 +62,380 @@
 
 <main class="guide-shell" id="main-content" tabindex="-1">
   <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; React</p>
-  <article id="guide-content" class="guide-content" data-md="react.md">
-    <p class="guide-loading">Loading…</p>
-    <noscript><p>This guide is written in Markdown: <a href="react.md">read react.md</a>.</p></noscript>
+  <article id="guide-content" class="guide-content" data-md="react.md" data-prerendered="true">
+<!-- guide:render:start -->
+<h1 id="pdfnative-react--declarative-jsx-renderer-guide">pdfnative-react — Declarative JSX Renderer Guide</h1>
+<blockquote>
+<p><strong>Tracks the latest published <code>pdfnative-react</code></strong> (v1.1.0, built on the pdfnative 1.6 engine), with <strong>React 19</strong> and <code>pdfnative</code> ^1.6.0 as peer dependencies (semver-accepts 1.7.0). Live package versions — and the <code>pdfnative</code> version each one is built on — are shown at the top of the <a href="../index.html">documentation home</a>. Full history: <a href="https://github.com/Nizoka/pdfnative-react/releases" target="_blank" rel="noopener">pdfnative-react releases</a>.</p>
+</blockquote>
+<p><a href="https://github.com/Nizoka/pdfnative-react" target="_blank" rel="noopener"><code>pdfnative-react</code></a> turns declarative <strong>JSX</strong> into real, on-device PDFs powered by the zero-dependency <a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener"><code>pdfnative</code></a> engine — no DOM, no headless browser, no SaaS round-trips. Your documents never leave the process.</p>
+<blockquote>
+<p><strong>Why a React renderer?</strong> Front-end teams already think in components. <code>pdfnative-react</code> lets you author a PDF the same way you author a UI — with familiar <code>@react-pdf/renderer</code>-style ergonomics (<code>Document</code>, <code>Page</code>, <code>Text</code>, <code>usePdf</code>, <code>PDFViewer</code>) — while the actual bytes are produced locally by pdfnative. It is the <strong>frontend gateway</strong> to the pdfnative ecosystem.</p>
+</blockquote>
+<pre><code class="language-tsx">import { Document, Heading, Text, Table, renderToBytes } from &#39;pdfnative-react&#39;;
+
+const bytes = renderToBytes(
+  &lt;Document title=&quot;Invoice #1024&quot; footerText=&quot;Acme Inc&quot;&gt;
+    &lt;Heading level={1}&gt;Invoice #1024&lt;/Heading&gt;
+    &lt;Text&gt;Thank you for your business.&lt;/Text&gt;
+    &lt;Table
+      headers={[&#39;Item&#39;, &#39;Qty&#39;, &#39;Total&#39;]}
+      rows={[{ cells: [&#39;Pro plan&#39;, &#39;1&#39;, &#39;$49.00&#39;], type: &#39;default&#39;, pointed: false }]}
+      zebra
+    /&gt;
+  &lt;/Document&gt;,
+); // → Uint8Array, a valid PDF (%PDF-… …%%EOF)
+</code></pre>
+<hr>
+<h2 id="how-it-works">How it works<a class="heading-anchor" href="#how-it-works" aria-label="Link to this section">#</a></h2>
+<p>A custom <strong>React reconciler</strong> compiles your component tree — synchronously, with no DOM — into the <code>pdfnative</code> <code>DocumentParams</code> model, which the engine then renders to bytes. There is <strong>no CSS/flexbox engine</strong> and no <code>&lt;View&gt;</code>: it is an honest, declarative <strong>block flow</strong> where every component maps 1:1 onto a pdfnative block.</p>
+<pre><code>[your JSX tree]
+      │ custom react-reconciler (synchronous, no DOM)
+┌──────────────────────────┐
+│   pdfnative-react (npm)  │  ← components compile to pdfnative blocks
+└──────────────────────────┘
+      │ import { buildDocumentPDFBytes, … } from &#39;pdfnative&#39;
+┌──────────────────────────┐
+│      pdfnative (npm)     │  ← zero-dependency PDF engine
+└──────────────────────────┘
+</code></pre>
+<blockquote>
+<p><strong>Zero-dependency invariant preserved.</strong> React 19 is a <strong>peer dependency of <code>pdfnative-react</code> only</strong>. The core <code>pdfnative</code> library remains zero-dependency — adding the React renderer to your app never adds a dependency to the engine itself.</p>
+</blockquote>
+<hr>
+<h2 id="installation">Installation<a class="heading-anchor" href="#installation" aria-label="Link to this section">#</a></h2>
+<pre><code class="language-bash">npm install pdfnative-react pdfnative react
+</code></pre>
+<p><strong>Requirements:</strong> <strong>React 19</strong> and <strong>pdfnative ^1.6.0</strong> (both peer dependencies) · <strong>Node.js ≥ 22</strong>. The package adds one runtime dependency of its own, <code>react-reconciler</code>. Works in Node, browsers and SSR frameworks.</p>
+<blockquote>
+<p><strong>Next.js and other React Server Component setups.</strong> The root barrel is deliberately <em>not</em> marked <code>&#39;use client&#39;</code>, and importing it from a Server Component or a <code>&#39;use server&#39;</code> file <strong>fails</strong> — the reconciler needs <code>createContext</code>, which is unavailable under React&#39;s <code>react-server</code> condition. Render from a <strong>Route Handler</strong> instead (see <a href="#server-rendering">Server rendering</a> below). The hooks and viewer components carry the directive and are published separately at <code>pdfnative-react/client</code>; import them from there in an app that mixes server and client components, because the directive does not survive bundling in the root barrel.</p>
+</blockquote>
+<p>The package ships <strong>NPM provenance</strong> — verify the published artifact with <code>npm audit signatures</code> or on <a href="https://www.npmjs.com/package/pdfnative-react" target="_blank" rel="noopener">npmjs.com</a>.</p>
+<hr>
+<h2 id="when-to-use-the-react-renderer">When to use the React renderer<a class="heading-anchor" href="#when-to-use-the-react-renderer" aria-label="Link to this section">#</a></h2>
+<table>
+<thead>
+<tr>
+<th>Use <strong>pdfnative-react</strong> when…</th>
+<th>Use the <strong>library</strong> / <strong>CLI</strong> when…</th>
+</tr>
+</thead>
+<tbody><tr>
+<td>You already build UIs in React and want PDFs the same way</td>
+<td>You write a non-React Node service → use <code>pdfnative</code> directly</td>
+</tr>
+<tr>
+<td>You want a live <code>&lt;iframe&gt;</code> preview in the browser (<code>usePdf</code> / <code>PDFViewer</code>)</td>
+<td>You operate from shell scripts or CI → use <a href="cli.html"><code>pdfnative-cli</code></a></td>
+</tr>
+<tr>
+<td>You are migrating from <code>@react-pdf/renderer</code></td>
+<td>You drive PDFs from an AI assistant → use <a href="mcp.html"><code>pdfnative-mcp</code></a></td>
+</tr>
+<tr>
+<td>You want AI agents to author with the token-frugal <code>DocSpec</code></td>
+<td>You need Web Worker offloading or 100 % programmatic control</td>
+</tr>
+</tbody></table>
+<p>The packages are <strong>complementary</strong> and all sit on the same engine, so a PDF authored in any of them is byte-compatible with the others.</p>
+<hr>
+<h2 id="components">Components<a class="heading-anchor" href="#components" aria-label="Link to this section">#</a></h2>
+<p>Every component maps 1:1 onto a pdfnative block (<code>Section</code> being the one intentional composite).</p>
+<table>
+<thead>
+<tr>
+<th>Component</th>
+<th>Renders</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>Document</code></td>
+<td>The required root (<code>title</code>, <code>footerText</code>, <code>metadata</code>, <code>fontEntries</code>, <code>layout</code>).</td>
+</tr>
+<tr>
+<td><code>Page</code></td>
+<td>An explicit page boundary (content auto-paginates otherwise).</td>
+</tr>
+<tr>
+<td><code>Heading</code></td>
+<td>A section heading (<code>level</code> 1–3); feeds the auto <code>TableOfContents</code>.</td>
+</tr>
+<tr>
+<td><code>Paragraph</code> / <code>Text</code></td>
+<td>A wrapping paragraph (<code>fontSize</code>, <code>lineHeight</code>, <code>align</code>, <code>indent</code>, <code>color</code>).</td>
+</tr>
+<tr>
+<td><code>List</code> / <code>Item</code></td>
+<td>A bullet or numbered (<code>ordered</code>) list.</td>
+</tr>
+<tr>
+<td><code>Table</code> / <code>Row</code> / <code>Cell</code></td>
+<td>A data table (data-driven <code>headers</code>/<code>rows</code>, or JSX <code>&lt;Row&gt;</code>/<code>&lt;Cell&gt;</code>).</td>
+</tr>
+<tr>
+<td><code>Image</code></td>
+<td>An embedded JPEG/PNG (<code>data: Uint8Array</code>).</td>
+</tr>
+<tr>
+<td><code>Link</code></td>
+<td>A clickable hyperlink (<code>url</code>/<code>href</code>).</td>
+</tr>
+<tr>
+<td><code>Spacer</code></td>
+<td>Vertical whitespace (<code>height</code>).</td>
+</tr>
+<tr>
+<td><code>PageBreak</code></td>
+<td>A hard page break.</td>
+</tr>
+<tr>
+<td><code>TableOfContents</code> / <code>Toc</code></td>
+<td>An auto-generated TOC built from headings.</td>
+</tr>
+<tr>
+<td><code>Barcode</code></td>
+<td>QR, Code 128, EAN-13, PDF417, Data Matrix (<code>format</code>, <code>data</code>).</td>
+</tr>
+<tr>
+<td><code>Svg</code></td>
+<td>Inline vector graphics (path data or markup).</td>
+</tr>
+<tr>
+<td><code>FormField</code></td>
+<td>Interactive AcroForm widgets (<code>fieldType</code>, <code>name</code>).</td>
+</tr>
+<tr>
+<td><code>Chart</code></td>
+<td>A native vector chart (<code>chartType</code>, <code>series</code>, <code>categories</code>, <code>altText</code>, …) — see <a href="#charts">Charts</a>.</td>
+</tr>
+<tr>
+<td><code>Section</code></td>
+<td><em>Composite</em> (the one exception to the 1:1 mapping): expands to an optional <code>PageBreak</code> + a <code>Heading</code> + its children before the reconciler runs. Props: <code>title</code>, <code>level</code> (default <code>2</code>), <code>color</code>, <code>break</code>.</td>
+</tr>
+</tbody></table>
+<hr>
+<h2 id="server-rendering">Server rendering<a class="heading-anchor" href="#server-rendering" aria-label="Link to this section">#</a></h2>
+<p><code>renderToResponse</code> returns a web-standard <code>Response</code>, so the same call works in a
+Next.js Route Handler, a Remix loader, Deno, Bun, Cloudflare Workers and any
+other runtime with the Fetch API. This is the supported way to render from a
+server framework.</p>
+<pre><code class="language-tsx">// app/invoice/route.tsx — Next.js Route Handler
+import { renderToResponse } from &#39;pdfnative-react&#39;;
+
+export async function GET() {
+  return renderToResponse(&lt;Invoice /&gt;, {
+    fileName: &#39;invoice.pdf&#39;,
+  });
+}
+</code></pre>
+<p><code>renderSpecToResponse</code> does the same from a <code>DocSpec</code> object rather than JSX,
+which is the shape an AI agent is most likely to produce.</p>
+<h2 id="charts">Charts<a class="heading-anchor" href="#charts" aria-label="Link to this section">#</a></h2>
+<p><code>&lt;Chart&gt;</code> compiles to the engine&#39;s native <code>chart</code> block — vector path operators,
+no rasterisation, and <code>/Figure</code> tagging with alt text.</p>
+<pre><code class="language-tsx">&lt;Chart
+  chartType=&quot;bar&quot;            // bar | barH | line | pie | donut
+  title=&quot;Quarterly revenue&quot;
+  categories={[&#39;Q1&#39;, &#39;Q2&#39;, &#39;Q3&#39;, &#39;Q4&#39;]}
+  series={[{ label: &#39;Revenue&#39;, values: [50, 62, 70, 81] }]}
+  altText=&quot;Bar chart of quarterly revenue, rising each quarter&quot;
+/&gt;
+</code></pre>
+<p>This is why the <code>pdfnative</code> peer floor is <code>^1.6.0</code>: a 1.5 engine receives an
+unknown block and drops it silently.</p>
+<h2 id="linting">Linting<a class="heading-anchor" href="#linting" aria-label="Link to this section">#</a></h2>
+<p><code>lintDocument</code> runs 18 deterministic rules over a compiled tree — no I/O, so it
+is safe in a test or a CI step. It catches the classes of mistake a type system
+cannot, including <code>L_TAGGED_NO_FONTS</code>: declaring PDF/A without embedding a font,
+which produces a file that claims conformance it does not have.</p>
+<pre><code class="language-ts">import { lintDocument, LINT_RULES } from &#39;pdfnative-react&#39;;
+
+const report = lintDocument(&lt;Invoice /&gt;);
+if (!report.ok) {
+  const first = report.findings.find((f) =&gt; f.severity === &#39;error&#39;);
+  throw new Error(first?.message ?? &#39;lint failed&#39;);
+}
+</code></pre>
+<h2 id="agent-surface">Agent surface<a class="heading-anchor" href="#agent-surface" aria-label="Link to this section">#</a></h2>
+<p><code>capabilityManifest()</code> and <code>doctor()</code> return plain JSON describing what the
+package can do and whether the environment supports it — the discovery pair an
+autonomous agent should call before planning work. <code>validateSpec</code>, <code>schema(subject?)</code>
+and <code>SCHEMA_SUBJECTS</code> cover DocSpec validation; <code>aiGovernancePolicy()</code>,
+<code>agentRulesText()</code> and <code>validateIssueDraft()</code> expose the human-in-the-loop contract.</p>
+<h2 id="rendering">Rendering<a class="heading-anchor" href="#rendering" aria-label="Link to this section">#</a></h2>
+<pre><code class="language-ts">import {
+  renderToBytes,   // (node, options?) =&gt; Uint8Array
+  renderToBlob,    // (node, options?) =&gt; Blob (application/pdf)
+  renderToStream,  // (node, options?) =&gt; AsyncGenerator&lt;Uint8Array&gt;
+  renderToFile,    // (node, path, options?) =&gt; Promise&lt;void&gt; (Node only)
+  renderToResponse,// (node, options?) =&gt; Promise&lt;Response&gt; (web standard)
+  renderToFileStream, // (node, path, options?) =&gt; Promise&lt;StreamToFileResult&gt; — { bytesWritten, path } (Node only)
+  inspectDocument, // (node) =&gt; layout diagnostics, no render
+  compileDocument, // (node) =&gt; DocumentParams (inspect the model, no render)
+} from &#39;pdfnative-react&#39;;
+</code></pre>
+<p><code>options</code> is <code>{ layout?: Partial&lt;PdfLayoutOptions&gt;; fontEntries?: FontEntry[]; fonts?: FontsMap }</code> and merges on top of anything set on <code>&lt;Document&gt;</code> — page size, margins, colors, PDF/A mode, encryption, and non-Latin fonts. Note that <code>fonts</code> is only honored by the <strong>async</strong> entry points (<code>renderToFile</code>, <code>renderToFileStream</code>, <code>renderToResponse</code>, <code>usePdf</code>, <code>usePdfStream</code>) — font loading is asynchronous, so the synchronous entries (<code>renderToBytes</code>, <code>renderToBlob</code>, <code>renderToStream</code>) ignore it; resolve manually first (<code>fontEntries: await resolveFonts(fonts)</code> — but see the <code>fontRef</code> caveat below).</p>
+<blockquote>
+<h3 id="build-fontentries-yourself--resolvefonts-produces-an-invalid-fontref">Build <code>fontEntries</code> yourself — <code>resolveFonts</code> produces an invalid <code>fontRef</code><a class="heading-anchor" href="#build-fontentries-yourself--resolvefonts-produces-an-invalid-fontref" aria-label="Link to this section">#</a></h3>
+<p><code>resolveFonts</code> (and the <code>fonts</code> option, which calls it) sets each entry&#39;s
+<code>fontRef</code> to the bare language code. <code>fontRef</code> is written straight into the PDF
+as a resource name, so it must be a <strong>PDF name starting with <code>/</code></strong> — and <code>/F1</code>
+and <code>/F2</code> are reserved by the engine. A bare code yields <code>latin 12 Tf</code> and a
+<code>/Font</code> key of <code>latin 5 0 R</code>, neither of which is valid syntax: Acrobat refuses
+the file with &quot;an error occurred while reading this document (14)&quot;, and Chrome
+falls back to a default encoding and draws raw glyph indices — <em>Multilingual</em>
+renders as <em>0XOWLOLQJXDO</em>.</p>
+<p>Until that is fixed upstream, resolve the fonts by hand:</p>
+<pre><code class="language-ts">import { registerFonts, loadFontData } from &#39;pdfnative&#39;;
+
+registerFonts({
+  latin: () =&gt; import(&#39;pdfnative/fonts/noto-sans-data.js&#39;),
+  ar:    () =&gt; import(&#39;pdfnative/fonts/noto-arabic-data.js&#39;),
+});
+
+const langs = [&#39;latin&#39;, &#39;ar&#39;];
+const fontEntries = await Promise.all(
+  langs.map(async (lang, i) =&gt; {
+    const fontData = await loadFontData(lang);
+    // loadFontData resolves to null (it does not throw) when the code has no
+    // registered loader — fail loudly instead of embedding nothing:
+    if (!fontData) throw new Error(`font &quot;${lang}&quot; failed to load — did you call registerFonts first?`);
+    return { fontData, fontRef: `/F${3 + i}`, lang };   // /F3, /F4, …
+  }),
+);
+
+const bytes = renderToBytes(&lt;Doc /&gt;, { fontEntries });
+</code></pre>
+<p>Rendering is synchronous, so registering without awaiting <code>loadFontData</code> embeds
+nothing at all and every non-Latin glyph comes out blank.</p>
+</blockquote>
+<pre><code class="language-ts">const bytes = renderToBytes(&lt;Invoice /&gt;, {
+  layout: { tagged: &#39;pdfa2b&#39;, compress: true },
+});
+</code></pre>
+<hr>
+<h2 id="hooks--client-components">Hooks &amp; client components<a class="heading-anchor" href="#hooks--client-components" aria-label="Link to this section">#</a></h2>
+<p>The published root bundle does <strong>not</strong> carry <code>&#39;use client&#39;</code> (a directive in an internal module does not survive single-file bundling); import hooks and viewer components from <code>pdfnative-react/client</code> in a React Server Components app, or add the directive to your own file as below.</p>
+<pre><code class="language-tsx">&#39;use client&#39;;
+import { usePdf } from &#39;pdfnative-react&#39;;
+
+function Preview({ doc }: { doc: React.ReactElement }) {
+  const { url, loading } = usePdf(doc);
+  return loading ? &lt;p&gt;Rendering…&lt;/p&gt; : &lt;iframe title=&quot;preview&quot; src={url} /&gt;;
+}
+</code></pre>
+<ul>
+<li><code>usePdf(element, options?)</code> → <code>{ url, blob, bytes, loading, error, update }</code></li>
+<li><code>usePdfStream(element, options?)</code> → <code>{ getStream() }</code></li>
+<li><code>PDFViewer</code> — live <code>&lt;iframe&gt;</code> preview.</li>
+<li><code>PDFDownloadLink</code> — one-click download (supports a render-prop child).</li>
+<li><code>BlobProvider</code> — render-prop access to the raw <code>Blob</code>.</li>
+</ul>
+<blockquote>
+<p>Try it live in the <a href="../playgrounds/react.html">React playground</a> — edit JSX or a <code>DocSpec</code> and see the PDF render in your browser.</p>
+</blockquote>
+<hr>
+<h2 id="agent-authoring--the-token-frugal-docspec">Agent authoring — the token-frugal <code>DocSpec</code><a class="heading-anchor" href="#agent-authoring--the-token-frugal-docspec" aria-label="Link to this section">#</a></h2>
+<p><code>pdfnative-react</code> is a <em>library</em>, so the place LLM agents spend tokens is <strong>authoring</strong> documents. The compact <code>DocSpec</code> expresses the same document as terse, JSON-serializable tuples — and compiles to the <strong>exact same</strong> PDF as the JSX, because it is built on the very same components.</p>
+<pre><code class="language-ts">import { renderSpecToBytes, type DocSpec } from &#39;pdfnative-react&#39;;
+
+const spec: DocSpec = {
+  title: &#39;Invoice #1024&#39;,
+  footerText: &#39;Acme Inc&#39;,
+  blocks: [
+    [&#39;h1&#39;, &#39;Invoice #1024&#39;],
+    [&#39;p&#39;, &#39;Thank you for your business.&#39;, { align: &#39;right&#39; }],
+    [&#39;table&#39;, { h: [&#39;Item&#39;, &#39;Total&#39;], r: [[&#39;Pro plan&#39;, &#39;$49.00&#39;]], zebra: true }],
+    [&#39;qr&#39;, &#39;https://acme.example/pay/1024&#39;, { align: &#39;right&#39; }],
+  ],
+};
+
+const bytes = renderSpecToBytes(spec);
+</code></pre>
+<p>The equivalent JSX is several times more tokens for a typical document, because every block carries opening/closing tags and prop names. Same bytes out, far fewer tokens in.</p>
+<ul>
+<li><code>compileSpec(spec)</code> → <code>DocumentParams</code> · <code>specToElement(spec)</code> → <code>&lt;Document&gt;</code> element</li>
+<li><code>renderSpecToBytes</code> / <code>renderSpecToBlob</code> / <code>renderSpecToStream</code> / <code>renderSpecToFile</code></li>
+<li><code>docSpecSchema()</code> → a Draft 2020-12 JSON Schema whose <code>$id</code> embeds the package version, so agents can self-validate a spec before rendering; <code>docSpecSchemaId()</code> returns the <code>$id</code>.</li>
+</ul>
+<p><strong>Block tuples:</strong> <code>[&#39;h1&#39;|&#39;h2&#39;|&#39;h3&#39;, text, opts?]</code>, <code>[&#39;p&#39;, text, opts?]</code>, <code>[&#39;ul&#39;|&#39;ol&#39;, items, opts?]</code>, <code>[&#39;table&#39;, { h?, r }]</code>, <code>[&#39;img&#39;, { data }]</code>, <code>[&#39;link&#39;, text, { url }]</code>, <code>[&#39;sp&#39;, height?]</code>, <code>[&#39;br&#39;]</code>, <code>[&#39;page&#39;, blocks]</code>, <code>[&#39;toc&#39;, opts?]</code>, <code>[&#39;qr&#39;|&#39;code128&#39;|&#39;ean13&#39;|&#39;pdf417&#39;|&#39;datamatrix&#39;, data, opts?]</code>, <code>[&#39;svg&#39;, data, opts?]</code>, <code>[&#39;chart&#39;, { chartType, series, … }]</code>, <code>[&#39;field&#39;, { fieldType, name, … }]</code>.</p>
+<hr>
+<h2 id="fonts--environment">Fonts &amp; environment<a class="heading-anchor" href="#fonts--environment" aria-label="Link to this section">#</a></h2>
+<p>Re-exported from the engine: <code>registerFonts</code>, <code>registerFont</code>, <code>loadFontData</code>, <code>validateFontData</code>, <code>downloadBlob</code> (browser), <code>initNodeCompression</code> (Node). (<code>loadFontData</code> is a pure dynamic import — it works in the browser too.) Pass non-Latin fonts via the <code>fontEntries</code> render option (or on <code>&lt;Document fontEntries={…}&gt;</code>), unlocking all 22 bundled Unicode scripts and COLRv1 colour emoji exactly as in the core library.</p>
+<pre><code class="language-tsx">import { Document, Text, renderToBytes, registerFont, loadFontData } from &#39;pdfnative-react&#39;;
+
+registerFont(&#39;th&#39;, () =&gt; import(&#39;pdfnative/fonts/noto-thai-data.js&#39;));
+const th = await loadFontData(&#39;th&#39;);
+if (!th) throw new Error(&#39;Thai font failed to load&#39;);
+const bytes = renderToBytes(
+  &lt;Document
+    title=&quot;สวัสดี&quot;
+    fontEntries={[{ fontData: th, fontRef: &#39;/F3&#39;, lang: &#39;th&#39; }]} // /F1 and /F2 are reserved
+  &gt;
+    &lt;Text&gt;สวัสดีชาวโลก&lt;/Text&gt;
+  &lt;/Document&gt;,
+);
+</code></pre>
+<hr>
+<h2 id="migrating-from-react-pdfrenderer">Migrating from <code>@react-pdf/renderer</code><a class="heading-anchor" href="#migrating-from-react-pdfrenderer" aria-label="Link to this section">#</a></h2>
+<table>
+<thead>
+<tr>
+<th><code>@react-pdf/renderer</code></th>
+<th>pdfnative-react</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>&lt;Document&gt;</code> / <code>&lt;Page&gt;</code></td>
+<td><code>&lt;Document&gt;</code> / <code>&lt;Page&gt;</code></td>
+</tr>
+<tr>
+<td><code>&lt;Text&gt;</code></td>
+<td><code>&lt;Text&gt;</code> (alias of <code>&lt;Paragraph&gt;</code>)</td>
+</tr>
+<tr>
+<td><code>&lt;View&gt;</code> + flexbox styles</td>
+<td><em>(none — declarative block flow; use blocks + <code>&lt;Spacer&gt;</code>)</em></td>
+</tr>
+<tr>
+<td><code>StyleSheet</code></td>
+<td>per-component props (<code>align</code>, <code>color</code>, <code>fontSize</code>, …)</td>
+</tr>
+<tr>
+<td><code>&lt;PDFViewer&gt;</code> / <code>&lt;PDFDownloadLink&gt;</code> / <code>&lt;BlobProvider&gt;</code></td>
+<td>same names, same shape</td>
+</tr>
+<tr>
+<td><!-- verify-docs:allow api-exists (left column names the @react-pdf/renderer API being migrated from) --> <code>usePDF()</code></td>
+<td><code>usePdf()</code></td>
+</tr>
+</tbody></table>
+<p>The biggest mental shift: there is <strong>no flexbox layout engine</strong>. Documents are a top-to-bottom block flow. Use <code>&lt;Spacer&gt;</code>, <code>&lt;PageBreak&gt;</code>, tables, and per-component alignment props instead of <code>&lt;View&gt;</code> containers.</p>
+<hr>
+<h2 id="diagnostics">Diagnostics<a class="heading-anchor" href="#diagnostics" aria-label="Link to this section">#</a></h2>
+<p><code>PdfStructureError</code> is thrown with an actionable message when a tree cannot be mapped onto the document model (for example, a <code>&lt;Cell&gt;</code> outside a <code>&lt;Row&gt;</code>, or an unsupported child of <code>&lt;Document&gt;</code>). Catch it to surface authoring mistakes early:</p>
+<pre><code class="language-ts">import { PdfStructureError, renderToBytes } from &#39;pdfnative-react&#39;;
+
+try {
+  const bytes = renderToBytes(&lt;MyDoc /&gt;);
+} catch (e) {
+  if (e instanceof PdfStructureError) console.error(&#39;Invalid document tree:&#39;, e.message);
+  else throw e;
+}
+</code></pre>
+<hr>
+<h2 id="resources">Resources<a class="heading-anchor" href="#resources" aria-label="Link to this section">#</a></h2>
+<ul>
+<li>📦 <strong>npm:</strong> <a href="https://www.npmjs.com/package/pdfnative-react" target="_blank" rel="noopener">pdfnative-react</a></li>
+<li>🏛️ <strong>Repo:</strong> <a href="https://github.com/Nizoka/pdfnative-react" target="_blank" rel="noopener">Nizoka/pdfnative-react</a></li>
+<li>📚 <strong>Knowledge base:</strong> <a href="https://github.com/Nizoka/pdfnative-react/blob/main/docs/KNOWLEDGE_BASE.md" target="_blank" rel="noopener">pdfnative-react/docs/KNOWLEDGE_BASE.md</a> — the compile pipeline, the react-reconciler version contract, and the agent authoring contract</li>
+<li>📁 <strong>Samples:</strong> <a href="https://github.com/Nizoka/pdfnative-react/tree/main/samples" target="_blank" rel="noopener">pdfnative-react/samples</a></li>
+<li>🧪 <strong>Try it interactively:</strong> <a href="../playgrounds/react.html">React playground</a> — render JSX to PDF in your browser</li>
+<li>🔧 <strong>Underlying library:</strong> <a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener"><code>pdfnative</code></a></li>
+<li>🤖 <strong>AI integration:</strong> <a href="mcp.html">pdfnative-mcp guide</a> · 💻 <strong>Terminal:</strong> <a href="cli.html">pdfnative-cli guide</a></li>
+<li>🐛 <strong>Report a bug:</strong> <a href="https://github.com/Nizoka/pdfnative-react/issues" target="_blank" rel="noopener">Nizoka/pdfnative-react/issues</a></li>
+</ul>
+<!-- guide:render:end -->
   </article>
 </main>
 
diff --git a/docs/guides/react.md b/docs/guides/react.md
index 51708fb..339847c 100644
--- a/docs/guides/react.md
+++ b/docs/guides/react.md
@@ -1,6 +1,6 @@
 # pdfnative-react — Declarative JSX Renderer Guide
 
-> **Tracks the latest published `pdfnative-react`** (v1.1.0, built on pdfnative 1.7.0), with **React 19** and `pdfnative` ^1.6.0 as peer dependencies. Live package versions — and the `pdfnative` version each one is built on — are shown at the top of the [documentation home](../index.html). Full history: [pdfnative-react releases](https://github.com/Nizoka/pdfnative-react/releases).
+> **Tracks the latest published `pdfnative-react`** (v1.1.0, built on the pdfnative 1.6 engine), with **React 19** and `pdfnative` ^1.6.0 as peer dependencies (semver-accepts 1.7.0). Live package versions — and the `pdfnative` version each one is built on — are shown at the top of the [documentation home](../index.html). Full history: [pdfnative-react releases](https://github.com/Nizoka/pdfnative-react/releases).
 
 [`pdfnative-react`](https://github.com/Nizoka/pdfnative-react) turns declarative **JSX** into real, on-device PDFs powered by the zero-dependency [`pdfnative`](https://github.com/Nizoka/pdfnative) engine — no DOM, no headless browser, no SaaS round-trips. Your documents never leave the process.
 
@@ -309,7 +309,7 @@ const bytes = renderToBytes(
 | `<View>` + flexbox styles | *(none — declarative block flow; use blocks + `<Spacer>`)* |
 | `StyleSheet` | per-component props (`align`, `color`, `fontSize`, …) |
 | `<PDFViewer>` / `<PDFDownloadLink>` / `<BlobProvider>` | same names, same shape |
-| `usePDF()` | `usePdf()` |
+| <!-- verify-docs:allow api-exists (left column names the @react-pdf/renderer API being migrated from) --> `usePDF()` | `usePdf()` |
 
 The biggest mental shift: there is **no flexbox layout engine**. Documents are a top-to-bottom block flow. Use `<Spacer>`, `<PageBreak>`, tables, and per-component alignment props instead of `<View>` containers.
 
diff --git a/docs/guides/self-verify.html b/docs/guides/self-verify.html
new file mode 100644
index 0000000..63dbaa4
--- /dev/null
+++ b/docs/guides/self-verify.html
@@ -0,0 +1,369 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Self-verifying generation — pdfnative</title>
+  <meta name="description" content="Close the loop on PDF generation: plan with inspectDocumentLayout(), then verify the emitted bytes with extractText(), validatePdfUA() and listSignatures()/openPdf() — the same generate → inspect → assert → correct pattern on the library, CLI (inspect --check) and MCP (inspect_pdf).">
+  <link rel="canonical" href="https://pdfnative.dev/guides/self-verify.html">
+  <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/self-verify.html">
+  <link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/self-verify.html">
+  <link rel="alternate" type="text/markdown" href="self-verify.md">
+  <link rel="alternate" type="text/plain" href="../llms.txt" title="llms.txt — machine-readable documentation index">
+  <meta property="og:type" content="article">
+  <meta property="og:site_name" content="pdfnative">
+  <meta property="og:locale" content="en_US">
+  <meta property="og:url" content="https://pdfnative.dev/guides/self-verify.html">
+  <meta property="og:title" content="Self-verifying generation — pdfnative">
+  <meta property="og:description" content="Generate → inspect → assert → correct: verify a generated PDF in-process with pdfnative's own parser, on the library, the CLI and MCP.">
+  <meta property="og:image" content="https://pdfnative.dev/assets/og-image.png">
+  <meta property="og:image:width" content="1200">
+  <meta property="og:image:height" content="630">
+  <meta name="twitter:card" content="summary_large_image">
+  <meta name="twitter:title" content="Self-verifying generation — pdfnative">
+  <meta name="twitter:description" content="Verify a generated PDF in-process: layout, text, PDF/UA structure and signatures, across all four pdfnative surfaces.">
+  <meta name="twitter:image" content="https://pdfnative.dev/assets/og-image.png">
+  <link rel="icon" type="image/svg+xml" href="../favicon.svg">
+  <link rel="stylesheet" href="../style.css">
+  <link rel="stylesheet" href="guide.css">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
+  <!-- guide:ld:start -->
+  <script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://pdfnative.dev/"},{"@type":"ListItem","position":2,"name":"Guides","item":"https://pdfnative.dev/guides/"},{"@type":"ListItem","position":3,"name":"Self-verifying generation","item":"https://pdfnative.dev/guides/self-verify.html"}]},{"@type":"TechArticle","headline":"Self-verifying generation","description":"Close the loop on PDF generation: plan with inspectDocumentLayout(), then verify the emitted bytes with extractText(), validatePdfUA() and listSignatures()/openPdf() — the same generate → inspect → assert → correct pattern on the library, CLI (inspect --check) and MCP (inspect_pdf).","inLanguage":"en","author":{"@type":"Organization","name":"Nizoka","url":"https://github.com/Nizoka"},"publisher":{"@type":"Organization","name":"pdfnative","url":"https://pdfnative.dev","logo":{"@type":"ImageObject","url":"https://pdfnative.dev/assets/logo.svg"}},"mainEntityOfPage":{"@type":"WebPage","@id":"https://pdfnative.dev/guides/self-verify.html"},"isPartOf":{"@type":"WebSite","name":"pdfnative","url":"https://pdfnative.dev"}}]}</script>
+  <!-- guide:ld:end -->
+</head>
+<body>
+
+<a class="skip-link" href="#main-content">Skip to main content</a>
+
+<nav class="nav" role="navigation" aria-label="Main navigation">
+  <div class="nav-inner">
+    <a class="nav-brand" href="../">
+      <img src="../assets/logo.svg" alt="" width="28" height="28">
+      pdfnative
+    </a>
+    <button class="nav-hamburger" aria-label="Toggle menu" aria-expanded="false">☰</button>
+    <ul class="nav-links" role="list">
+      <li><a href="../#features">Features</a></li>
+      <li><a href="../#examples">Examples</a></li>
+      <li><a href="../#demo">Demo</a></li>
+      <li><a href="../#mcp">MCP</a></li>
+      <li><a href="../#cli">CLI</a></li>
+      <li><a href="../#react">React</a></li>
+      <li><a href="../learn/">Learn</a></li>
+      <li><a href="./">Guides</a></li>
+      <li><a href="../playgrounds/">Playgrounds</a></li>
+      <li><a href="../responsibility.html">Responsibility</a></li>
+      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
+      <li><button class="theme-toggle" aria-label="Toggle dark mode">🌙</button></li>
+    </ul>
+  </div>
+</nav>
+
+<main class="guide-shell" id="main-content" tabindex="-1">
+  <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; Self-verifying generation</p>
+  <article id="guide-content" class="guide-content" data-md="self-verify.md" data-prerendered="true">
+<!-- guide:render:start -->
+<h1 id="self-verifying-generation">Self-verifying generation</h1>
+<blockquote>
+<p><strong>pdfnative can read what it writes, so a generated PDF never has to ship
+unchecked.</strong> Plan pagination with <code>inspectDocumentLayout()</code> <em>before</em> building,
+then run <code>extractText()</code>, <code>validatePdfUA()</code> and <code>listSignatures()</code> /
+<code>openPdf()</code> against the emitted bytes, assert what matters, and correct the
+input until every assertion holds. The same generate → inspect → assert →
+correct loop runs on all four surfaces: in the library, on the CLI
+(<code>inspect --check</code>, stable exit codes and <code>E_*</code> error classes), and on MCP
+(<code>inspect_pdf</code> check assertions) — so a test suite, a CI job or an AI agent
+can close the loop without a human ever opening a viewer.</p>
+</blockquote>
+<h2 id="why-a-pdf-is-normally-a-blind-artefact">Why a PDF is normally a blind artefact<a class="heading-anchor" href="#why-a-pdf-is-normally-a-blind-artefact" aria-label="Link to this section">#</a></h2>
+<p>Most PDF generators are write-only: the library that produced the file cannot
+parse it back. The only verification available is a human opening the result in
+a viewer — which no pipeline, test suite or autonomous agent can do. So defects
+ship silently: a table that slipped onto a second page, a template placeholder
+that was never substituted, a PDF/A claim the file cannot honour, a signature
+placeholder that was never actually signed.</p>
+<p>pdfnative bundles a parser next to the writer, in the same zero-dependency
+package. The read side (<code>openPdf()</code>, <code>extractText()</code>, <code>validatePdfUA()</code>,
+<code>listSignatures()</code>) consumes exactly what the write side emits — and any other
+PDF — which turns generation into a closed loop:</p>
+<ol>
+<li><strong>Plan</strong> — measure pagination with <code>inspectDocumentLayout()</code> before a single
+byte is produced.</li>
+<li><strong>Generate</strong> — build the document.</li>
+<li><strong>Inspect</strong> — read the emitted bytes back with the parser.</li>
+<li><strong>Assert &amp; correct</strong> — check the facts you care about; on failure, fix the
+<em>input</em> and regenerate. Never patch the output bytes.</li>
+</ol>
+<p>The rest of this guide walks the four verifiers with realistic
+failure → fix examples, then shows the identical loop on the CLI and on MCP.</p>
+<h2 id="verifier-1--inspectdocumentlayout-geometry-before-generating">Verifier 1 — <code>inspectDocumentLayout()</code>: geometry, before generating<a class="heading-anchor" href="#verifier-1--inspectdocumentlayout-geometry-before-generating" aria-label="Link to this section">#</a></h2>
+<p><em>(v1.5.0)</em> A pagination dry run: the same planning logic as the builder, but it
+returns data instead of PDF bytes — no rendering, no font embedding.</p>
+<pre><code class="language-ts">import { buildDocumentPDFBytes, inspectDocumentLayout } from &#39;pdfnative&#39;;
+
+const params = {
+  title: &#39;Invoice #2026-041&#39;,
+  blocks: [
+    { type: &#39;heading&#39;, level: 1, text: &#39;Invoice #2026-041&#39; },
+    { type: &#39;paragraph&#39;, text: intro },
+    { type: &#39;table&#39;, headers: [&#39;Item&#39;, &#39;Qty&#39;, &#39;Total&#39;], rows },
+  ],
+};
+
+// Plan — no PDF is produced.
+const layout = inspectDocumentLayout(params);
+
+// Assert: a one-page invoice.
+if (layout.totalPages !== 1) {
+  throw new Error(`expected 1 page, planned ${layout.totalPages}`);
+}
+
+// Assert: the table starts on page 1, not after a stray break.
+const table = layout.pages[0].blocks.find((b) =&gt; b.type === &#39;table&#39;);
+if (!table) throw new Error(&#39;table was pushed off page 1&#39;);
+
+// Only now generate.
+const bytes = buildDocumentPDFBytes(params);
+</code></pre>
+<p><strong>Failure → fix.</strong> <code>totalPages</code> comes back as <code>2</code> because this month&#39;s <code>rows</code>
+grew by three entries. Fixes live in the input: shorten <code>intro</code>, reduce the
+margins in the layout options, or accept the second page and change the
+assertion — the table planner repeats headers on continuation pages by default,
+so a deliberate two-pager stays readable. Re-run the inspection until the
+assertion holds, then build.</p>
+<blockquote>
+<p><strong>Honest caveat.</strong> <code>inspectDocumentLayout()</code> shares the builder&#39;s measurement
+code (<code>estimateBlockHeight</code> / <code>planTable</code> and its constants) — that is
+precisely why its geometry matches where the renderer places each block,
+including table slicing across page breaks. But it is a <em>prediction from the
+shared engine</em>, not an independent re-parse of the emitted bytes. For
+verification of the actual output, pair it with <code>extractText()</code> below. See
+<a href="debugging.html">Layout debugging &amp; inspection</a> for the full data shape and
+the visual overlay variant.</p>
+</blockquote>
+<h2 id="verifier-2--extracttext-is-the-content-actually-in-the-file">Verifier 2 — <code>extractText()</code>: is the content actually in the file?<a class="heading-anchor" href="#verifier-2--extracttext-is-the-content-actually-in-the-file" aria-label="Link to this section">#</a></h2>
+<p><em>(v1.6.0)</em> Reading-order Unicode text per page, decoded from the content
+streams of the emitted bytes — pdfnative-generated documents round-trip
+losslessly, including CJK, Arabic and emoji.</p>
+<pre><code class="language-ts">import { buildDocumentPDFBytes, extractText } from &#39;pdfnative&#39;;
+
+const bytes = buildDocumentPDFBytes(params);
+
+const pages = extractText(bytes);               // ExtractedPageText[]
+// Each entry: { pageIndex: number, text: string, runs?: ExtractedTextRun[] }
+const flat = pages.map((p) =&gt; p.text).join(&#39;\n&#39;);
+
+for (const required of [&#39;Invoice #2026-041&#39;, &#39;Total&#39;, &#39;1 240,00 €&#39;]) {
+  if (!flat.includes(required)) {
+    throw new Error(`missing from the emitted PDF: &quot;${required}&quot;`);
+  }
+}
+if (flat.includes(&#39;{{&#39;)) {
+  throw new Error(&#39;an unresolved template placeholder reached the PDF&#39;);
+}
+</code></pre>
+<p><strong>Failure → fix.</strong> The total is missing: the value never entered <code>blocks</code> —
+typically a renamed data field, or a templating step that ran after the build
+instead of before it. The <code>{{</code> guard catches the classic half-rendered
+template. Fix the data flow and regenerate. Positioned runs
+(<code>{ includeRuns: true }</code>) additionally give each string&#39;s <code>x</code> / <code>y</code> /
+<code>fontSize</code> when you need to assert <em>where</em> something landed, not just that it
+exists.</p>
+<p>Extraction has documented limits (no OCR on image content, lossy conjuncts in
+shaped Indic scripts) — see <a href="text-extraction.html">Text extraction</a> before
+asserting on those cases.</p>
+<h2 id="verifier-3--validatepdfua-structural-pdfua">Verifier 3 — <code>validatePdfUA()</code>: structural PDF/UA<a class="heading-anchor" href="#verifier-3--validatepdfua-structural-pdfua" aria-label="Link to this section">#</a></h2>
+<p>Read-only ISO 14289-1 structural checks over the emitted bytes: <code>/MarkInfo</code>,
+the structure tree, the parent tree, a document <code>/Lang</code>, per-page MCID
+uniqueness.</p>
+<pre><code class="language-ts">import { buildDocumentPDFBytes, validatePdfUA } from &#39;pdfnative&#39;;
+
+const bytes = buildDocumentPDFBytes(params, { tagged: true });
+
+const report = validatePdfUA(bytes);   // { valid, errors, warnings }
+if (!report.valid) {
+  throw new Error(`PDF/UA structure: ${report.errors.join(&#39;; &#39;)}`);
+}
+</code></pre>
+<p><strong>Failure → fix.</strong> The most common failure is building without <code>tagged</code> — the
+document then has no structure tree at all, and every structural check fires.
+Set <code>layout: { tagged: true }</code> (or a <code>&#39;pdfa*&#39;</code> level) and regenerate. Warnings
+are non-blocking best-practice notes; decide explicitly whether your pipeline
+tolerates them.</p>
+<blockquote>
+<p><strong>Honest caveat.</strong> This is a <em>structural</em> validation, not an accessibility
+audit. A passing report means the machine-checkable structure is present and
+consistent — it cannot judge whether the reading order makes sense to a
+human, whether alt text is meaningful, or whether colour contrast is
+adequate. And it is not a PDF/A validator: for archival conformance, run
+veraPDF as described in <a href="pdfa.html">PDF/A conformance</a>.</p>
+</blockquote>
+<h2 id="verifier-4--listsignatures--openpdf-signatures-encryption-metadata">Verifier 4 — <code>listSignatures()</code> + <code>openPdf()</code>: signatures, encryption, metadata<a class="heading-anchor" href="#verifier-4--listsignatures--openpdf-signatures-encryption-metadata" aria-label="Link to this section">#</a></h2>
+<p><code>listSignatures()</code> <em>(v1.7.0)</em> inventories every signature field in the
+document; <code>openPdf()</code> (available since v1.0.0) exposes page count, encryption
+state and the <code>/Info</code> dictionary.</p>
+<pre><code class="language-ts">import { openPdf, listSignatures } from &#39;pdfnative&#39;;
+
+const sigs = listSignatures(signedBytes);
+if (sigs.length === 0) throw new Error(&#39;no signature field found&#39;);
+if (sigs.some((s) =&gt; s.isPlaceholder)) {
+  throw new Error(&#39;a /Sig field is still an unsigned placeholder&#39;);
+}
+// Per entry: fieldName?, subFilter, byteRange, isDocTimestamp, isPlaceholder.
+const pades = sigs.filter((s) =&gt; s.subFilter === &#39;ETSI.CAdES.detached&#39;);
+
+const reader = openPdf(signedBytes);
+if (reader.encryption !== null) throw new Error(&#39;expected an unencrypted document&#39;);
+if (reader.pageCount &lt; 2) throw new Error(&#39;terms page missing&#39;);
+const info = reader.getInfo();
+</code></pre>
+<p><strong>Failure → fix.</strong> <code>isPlaceholder: true</code> means <code>addSignaturePlaceholder()</code> ran
+but <code>signPdfBytes()</code> never filled that field — usually a skipped signing step,
+or a <code>fieldName</code> selector that targeted a different placeholder. Sign the
+document (or the right field) and re-check. <code>isDocTimestamp</code> distinguishes
+<code>/DocTimeStamp</code> entries when you assert on the PAdES ladder.</p>
+<blockquote>
+<p><strong>Honest caveat.</strong> <code>listSignatures()</code> is an inventory, not a cryptographic
+verdict — the pdfnative engine deliberately ships no signature verifier.
+Full verification (byte-range digest, CMS signature value, certificate
+chain, trust, timestamps, revocation) lives in <code>pdfnative-cli verify</code> and in
+the MCP <code>verify_pdf</code> tool, below. See
+<a href="ltv.html">Long-term validation (LTV)</a>.</p>
+</blockquote>
+<h2 id="the-same-loop-on-the-cli">The same loop on the CLI<a class="heading-anchor" href="#the-same-loop-on-the-cli" aria-label="Link to this section">#</a></h2>
+<p><code>pdfnative-cli</code> turns the assertions into exit codes, which is what a shell or
+CI step branches on:</p>
+<pre><code class="language-bash"># Plan (pre-flight): pagination report instead of a PDF   (v1.2.0)
+pdfnative render --input invoice.json --inspect-layout &gt; layout.json
+
+# Generate, then assert — exit 0 when every --check holds, 1 otherwise
+pdfnative render  --input invoice.json --output invoice.pdf --tagged pdfa2b
+pdfnative inspect --input invoice.pdf --check pdfa --check pdfua --json --summary
+echo $?   # 0 = all assertions hold, 1 = at least one failed
+
+# Content presence, pipeline-style
+pdfnative extract-text --input invoice.pdf --format text | grep -q &#39;Invoice #2026-041&#39;
+</code></pre>
+<ul>
+<li><code>inspect --check</code> takes repeatable, ANDed assertions — <code>pdfa</code>, <code>signed</code>,
+<code>encrypted</code>, <code>pdfua</code> <em>(v1.1.0)</em> — and sets the exit code accordingly; under
+<code>--json</code>, a failed assertion also emits the stable error class
+<code>E_CHECK_FAILED</code> in the machine-readable envelope on stderr
+(<code>{ ok: false, command, error: { code, message } }</code>).</li>
+<li><code>--summary</code> <em>(v1.1.0)</em> shrinks the stdout verdict to
+<code>{ pages, encrypted, signatures, pdfa }</code>; <code>--fields a,b.c</code> projects arbitrary
+dot-paths — both exist so agents branch on facts without paying for the full
+report.</li>
+<li><code>pdfnative verify --strict</code> performs the cryptographic half: byte-range
+digest, CMS signature value (RSA and ECDSA), certificate chain and trust
+against <code>--trust</code> roots, RFC 3161 timestamps, OCSP/CRL revocation — exit 1
+and <code>E_VERIFY_FAILED</code> on any failure <em>or on zero signatures</em>.</li>
+</ul>
+<p>The full command reference, including every <code>--check</code> flag and the <code>E_*</code>
+catalogue, is in the <a href="cli.html">CLI guide</a>.</p>
+<h2 id="the-same-loop-on-mcp">The same loop on MCP<a class="heading-anchor" href="#the-same-loop-on-mcp" aria-label="Link to this section">#</a></h2>
+<p><code>pdfnative-mcp</code> gives a conversational agent the identical verifiers as
+read-only tools — the natural final step after any document tool call:</p>
+<table>
+<thead>
+<tr>
+<th>Tool</th>
+<th>Verifies</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>inspect_pdf</code></td>
+<td>Version, page count, encryption, PDF/A claim, signatures, attachments, <code>/Info</code> — plus <code>check</code> assertions with a boolean verdict.</td>
+</tr>
+<tr>
+<td><code>inspect_layout</code> <em>(v1.6.0)</em></td>
+<td>Pagination dry run for a prospective document — page count and block geometry, no PDF produced, no base64 output tokens spent.</td>
+</tr>
+<tr>
+<td><code>validate_pdf</code></td>
+<td>Structural PDF/UA — <code>{ valid, errors, warnings }</code>.</td>
+</tr>
+<tr>
+<td><code>verify_pdf</code></td>
+<td>Cryptographic signature verification; <code>ltv: true</code> <em>(v1.6.0)</em> reports the achieved PAdES level (B-B → B-LTA).</td>
+</tr>
+</tbody></table>
+<pre><code class="language-jsonc">{ &quot;tool&quot;: &quot;inspect_pdf&quot;,
+  &quot;input&quot;: { &quot;pdfBase64&quot;: &quot;&lt;...&gt;&quot;, &quot;check&quot;: [&quot;pdfa&quot;, &quot;signed&quot;] } }
+// → { ..., &quot;checks&quot;: { &quot;pdfa&quot;: true, &quot;signed&quot;: true }, &quot;checksPassed&quot;: true }
+</code></pre>
+<ul>
+<li><code>check</code> accepts <code>pdfa</code>, <code>signed</code>, <code>encrypted</code>, <code>placeholder</code>, <code>attachments</code>,
+and — <em>(v1.6.0)</em> — <code>dss</code>, <code>docTimestamp</code>, <code>trapped</code>, <code>annotations</code>.
+<code>checksPassed</code> is the AND of all requested assertions; since v1.6.0 <code>checks</code>
+contains <strong>only</strong> the requested keys, so branch on <code>checksPassed</code> or on a key
+you asked for, never on an absent one.</li>
+<li><code>inspect_layout</code> accepts the same <code>title</code> / <code>blocks</code> (plus every input that
+moves a block) as <code>generate_basic_pdf</code>, so an agent can iterate on pagination
+before spending output tokens on real bytes. Known engine gap: a <code>toc</code> block
+is measured as 0 pt, so a document with a printed contents page may paginate
+one page later than previewed.</li>
+<li><code>validate_pdf</code> on unparsable bytes is an error (<code>PDF_PARSE_FAILED</code>), not a
+<code>{ valid: false }</code> verdict, since v1.6.0 — a parse failure is not a PDF/UA
+result.</li>
+</ul>
+<p>Tool-by-tool inputs and error codes are in the <a href="mcp.html">MCP guide</a>.</p>
+<h2 id="wire-it-into-ci-and-agent-loops">Wire it into CI and agent loops<a class="heading-anchor" href="#wire-it-into-ci-and-agent-loops" aria-label="Link to this section">#</a></h2>
+<p><strong>CI.</strong> Chain the loop with <code>set -e</code> so any failed assertion fails the job —
+no PDF-viewing human in the path:</p>
+<pre><code class="language-bash">set -e
+pdfnative render  --input report.json --output report.pdf --tagged pdfa2b
+pdfnative sign    --input report.pdf  --output signed.pdf --key k.pem --cert c.pem
+pdfnative inspect --input signed.pdf  --check pdfa --check signed --json --summary
+pdfnative verify  --input signed.pdf  --strict --trust ca-root.pem
+</code></pre>
+<p><code>--dry-run</code> on the write commands validates inputs without producing output,
+which makes a cheap first CI stage; <code>--summary</code> / <code>--fields</code> keep logs and
+agent context small.</p>
+<p><strong>Agent loops.</strong> Treat every generation as unfinished until a read tool
+confirms it: after <code>generate_basic_pdf</code> (or any document tool), call
+<code>inspect_pdf</code> with the <code>check</code> list that encodes the user&#39;s requirements and
+branch on <code>checksPassed</code>; on failure, correct the tool input and regenerate
+rather than apologising with an unverified file. Use <code>inspect_layout</code> before
+generating and <code>verbosity: &quot;summary&quot;</code> on the read tools to keep token spend
+proportional. The <a href="../agent-brief.md">agent brief</a> condenses this contract
+into a paste-into-context form.</p>
+<h2 id="further-reading">Further reading<a class="heading-anchor" href="#further-reading" aria-label="Link to this section">#</a></h2>
+<ul>
+<li><a href="../agent-brief.md">Agent brief</a> — the compact form of this loop for AI
+agents, verified by the documentation CI.</li>
+<li><a href="debugging.html">Layout debugging &amp; inspection</a> — the visual overlay and the
+full <code>LayoutInspection</code> data shape.</li>
+<li><a href="text-extraction.html">Text extraction</a> — decoding rules, positioned runs,
+documented limits.</li>
+<li><a href="pdfa.html">PDF/A conformance</a> — validating archival claims with veraPDF,
+and the build-time <code>PDFA_*</code> diagnostics.</li>
+<li><a href="ltv.html">Long-term validation (LTV)</a> — the PAdES ladder the signature
+assertions climb.</li>
+<li><a href="cli.html">CLI guide</a> · <a href="mcp.html">MCP guide</a> — the complete surface
+references.</li>
+</ul>
+<!-- guide:render:end -->
+  </article>
+</main>
+
+<footer class="footer">
+  <div class="footer-inner">
+    <span>MIT License · © 2026 Nizoka</span>
+    <ul class="footer-links" role="list">
+      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
+      <li><a href="https://www.npmjs.com/package/pdfnative" target="_blank" rel="noopener">npm</a></li>
+      <li><a href="https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md" target="_blank" rel="noopener">Changelog</a></li>
+      <li><a href="./">All guides</a></li>
+    </ul>
+  </div>
+</footer>
+
+<script src="https://cdn.jsdelivr.net/npm/marked@12.0.2/marked.min.js" integrity="sha384-/TQbtLCAerC3jgaim+N78RZSDYV7ryeoBCVqTuzRrFec2akfBkHS7ACQ3PQhvMVi" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/dompurify@3.1.5/dist/purify.min.js" integrity="sha384-nszIONF2FGC59kn+pPFaRa6WUNGwsZgXZiJxJwQbym+TzcH7smolUviLgpPbNx7V" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/prism.min.js" integrity="sha384-BGaNxfftg+9+TtC098wxawPFVEUpKYvaiCgbB0iqAMjK/4jDdmUY+oGxrPNvnXEf" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-typescript.min.js" integrity="sha384-PeOqKNW/piETaCg8rqKFy+Pm6KEk7e36/5YZE5XO/OaFdO+/Aw3O8qZ9qDPKVUgx" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-bash.min.js" integrity="sha384-9WmlN8ABpoFSSHvBGGjhvB3E/D8UkNB9HpLJjBQFC2VSQsM1odiQDv4NbEo+7l15" crossorigin="anonymous" defer></script>
+<script src="guide.js" defer></script>
+</body>
+</html>
diff --git a/docs/guides/self-verify.md b/docs/guides/self-verify.md
new file mode 100644
index 0000000..27b1712
--- /dev/null
+++ b/docs/guides/self-verify.md
@@ -0,0 +1,297 @@
+# Self-verifying generation
+
+> **pdfnative can read what it writes, so a generated PDF never has to ship
+> unchecked.** Plan pagination with `inspectDocumentLayout()` *before* building,
+> then run `extractText()`, `validatePdfUA()` and `listSignatures()` /
+> `openPdf()` against the emitted bytes, assert what matters, and correct the
+> input until every assertion holds. The same generate → inspect → assert →
+> correct loop runs on all four surfaces: in the library, on the CLI
+> (`inspect --check`, stable exit codes and `E_*` error classes), and on MCP
+> (`inspect_pdf` check assertions) — so a test suite, a CI job or an AI agent
+> can close the loop without a human ever opening a viewer.
+
+## Why a PDF is normally a blind artefact
+
+Most PDF generators are write-only: the library that produced the file cannot
+parse it back. The only verification available is a human opening the result in
+a viewer — which no pipeline, test suite or autonomous agent can do. So defects
+ship silently: a table that slipped onto a second page, a template placeholder
+that was never substituted, a PDF/A claim the file cannot honour, a signature
+placeholder that was never actually signed.
+
+pdfnative bundles a parser next to the writer, in the same zero-dependency
+package. The read side (`openPdf()`, `extractText()`, `validatePdfUA()`,
+`listSignatures()`) consumes exactly what the write side emits — and any other
+PDF — which turns generation into a closed loop:
+
+1. **Plan** — measure pagination with `inspectDocumentLayout()` before a single
+   byte is produced.
+2. **Generate** — build the document.
+3. **Inspect** — read the emitted bytes back with the parser.
+4. **Assert & correct** — check the facts you care about; on failure, fix the
+   *input* and regenerate. Never patch the output bytes.
+
+The rest of this guide walks the four verifiers with realistic
+failure → fix examples, then shows the identical loop on the CLI and on MCP.
+
+## Verifier 1 — `inspectDocumentLayout()`: geometry, before generating
+
+_(v1.5.0)_ A pagination dry run: the same planning logic as the builder, but it
+returns data instead of PDF bytes — no rendering, no font embedding.
+
+```ts
+import { buildDocumentPDFBytes, inspectDocumentLayout } from 'pdfnative';
+
+const params = {
+  title: 'Invoice #2026-041',
+  blocks: [
+    { type: 'heading', level: 1, text: 'Invoice #2026-041' },
+    { type: 'paragraph', text: intro },
+    { type: 'table', headers: ['Item', 'Qty', 'Total'], rows },
+  ],
+};
+
+// Plan — no PDF is produced.
+const layout = inspectDocumentLayout(params);
+
+// Assert: a one-page invoice.
+if (layout.totalPages !== 1) {
+  throw new Error(`expected 1 page, planned ${layout.totalPages}`);
+}
+
+// Assert: the table starts on page 1, not after a stray break.
+const table = layout.pages[0].blocks.find((b) => b.type === 'table');
+if (!table) throw new Error('table was pushed off page 1');
+
+// Only now generate.
+const bytes = buildDocumentPDFBytes(params);
+```
+
+**Failure → fix.** `totalPages` comes back as `2` because this month's `rows`
+grew by three entries. Fixes live in the input: shorten `intro`, reduce the
+margins in the layout options, or accept the second page and change the
+assertion — the table planner repeats headers on continuation pages by default,
+so a deliberate two-pager stays readable. Re-run the inspection until the
+assertion holds, then build.
+
+> **Honest caveat.** `inspectDocumentLayout()` shares the builder's measurement
+> code (`estimateBlockHeight` / `planTable` and its constants) — that is
+> precisely why its geometry matches where the renderer places each block,
+> including table slicing across page breaks. But it is a *prediction from the
+> shared engine*, not an independent re-parse of the emitted bytes. For
+> verification of the actual output, pair it with `extractText()` below. See
+> [Layout debugging & inspection](debugging.html) for the full data shape and
+> the visual overlay variant.
+
+## Verifier 2 — `extractText()`: is the content actually in the file?
+
+_(v1.6.0)_ Reading-order Unicode text per page, decoded from the content
+streams of the emitted bytes — pdfnative-generated documents round-trip
+losslessly, including CJK, Arabic and emoji.
+
+```ts
+import { buildDocumentPDFBytes, extractText } from 'pdfnative';
+
+const bytes = buildDocumentPDFBytes(params);
+
+const pages = extractText(bytes);               // ExtractedPageText[]
+// Each entry: { pageIndex: number, text: string, runs?: ExtractedTextRun[] }
+const flat = pages.map((p) => p.text).join('\n');
+
+for (const required of ['Invoice #2026-041', 'Total', '1 240,00 €']) {
+  if (!flat.includes(required)) {
+    throw new Error(`missing from the emitted PDF: "${required}"`);
+  }
+}
+if (flat.includes('{{')) {
+  throw new Error('an unresolved template placeholder reached the PDF');
+}
+```
+
+**Failure → fix.** The total is missing: the value never entered `blocks` —
+typically a renamed data field, or a templating step that ran after the build
+instead of before it. The `{{` guard catches the classic half-rendered
+template. Fix the data flow and regenerate. Positioned runs
+(`{ includeRuns: true }`) additionally give each string's `x` / `y` /
+`fontSize` when you need to assert *where* something landed, not just that it
+exists.
+
+Extraction has documented limits (no OCR on image content, lossy conjuncts in
+shaped Indic scripts) — see [Text extraction](text-extraction.html) before
+asserting on those cases.
+
+## Verifier 3 — `validatePdfUA()`: structural PDF/UA
+
+Read-only ISO 14289-1 structural checks over the emitted bytes: `/MarkInfo`,
+the structure tree, the parent tree, a document `/Lang`, per-page MCID
+uniqueness.
+
+```ts
+import { buildDocumentPDFBytes, validatePdfUA } from 'pdfnative';
+
+const bytes = buildDocumentPDFBytes(params, { tagged: true });
+
+const report = validatePdfUA(bytes);   // { valid, errors, warnings }
+if (!report.valid) {
+  throw new Error(`PDF/UA structure: ${report.errors.join('; ')}`);
+}
+```
+
+**Failure → fix.** The most common failure is building without `tagged` — the
+document then has no structure tree at all, and every structural check fires.
+Set `layout: { tagged: true }` (or a `'pdfa*'` level) and regenerate. Warnings
+are non-blocking best-practice notes; decide explicitly whether your pipeline
+tolerates them.
+
+> **Honest caveat.** This is a *structural* validation, not an accessibility
+> audit. A passing report means the machine-checkable structure is present and
+> consistent — it cannot judge whether the reading order makes sense to a
+> human, whether alt text is meaningful, or whether colour contrast is
+> adequate. And it is not a PDF/A validator: for archival conformance, run
+> veraPDF as described in [PDF/A conformance](pdfa.html).
+
+## Verifier 4 — `listSignatures()` + `openPdf()`: signatures, encryption, metadata
+
+`listSignatures()` _(v1.7.0)_ inventories every signature field in the
+document; `openPdf()` (available since v1.0.0) exposes page count, encryption
+state and the `/Info` dictionary.
+
+```ts
+import { openPdf, listSignatures } from 'pdfnative';
+
+const sigs = listSignatures(signedBytes);
+if (sigs.length === 0) throw new Error('no signature field found');
+if (sigs.some((s) => s.isPlaceholder)) {
+  throw new Error('a /Sig field is still an unsigned placeholder');
+}
+// Per entry: fieldName?, subFilter, byteRange, isDocTimestamp, isPlaceholder.
+const pades = sigs.filter((s) => s.subFilter === 'ETSI.CAdES.detached');
+
+const reader = openPdf(signedBytes);
+if (reader.encryption !== null) throw new Error('expected an unencrypted document');
+if (reader.pageCount < 2) throw new Error('terms page missing');
+const info = reader.getInfo();
+```
+
+**Failure → fix.** `isPlaceholder: true` means `addSignaturePlaceholder()` ran
+but `signPdfBytes()` never filled that field — usually a skipped signing step,
+or a `fieldName` selector that targeted a different placeholder. Sign the
+document (or the right field) and re-check. `isDocTimestamp` distinguishes
+`/DocTimeStamp` entries when you assert on the PAdES ladder.
+
+> **Honest caveat.** `listSignatures()` is an inventory, not a cryptographic
+> verdict — the pdfnative engine deliberately ships no signature verifier.
+> Full verification (byte-range digest, CMS signature value, certificate
+> chain, trust, timestamps, revocation) lives in `pdfnative-cli verify` and in
+> the MCP `verify_pdf` tool, below. See
+> [Long-term validation (LTV)](ltv.html).
+
+## The same loop on the CLI
+
+`pdfnative-cli` turns the assertions into exit codes, which is what a shell or
+CI step branches on:
+
+```bash
+# Plan (pre-flight): pagination report instead of a PDF   (v1.2.0)
+pdfnative render --input invoice.json --inspect-layout > layout.json
+
+# Generate, then assert — exit 0 when every --check holds, 1 otherwise
+pdfnative render  --input invoice.json --output invoice.pdf --tagged pdfa2b
+pdfnative inspect --input invoice.pdf --check pdfa --check pdfua --json --summary
+echo $?   # 0 = all assertions hold, 1 = at least one failed
+
+# Content presence, pipeline-style
+pdfnative extract-text --input invoice.pdf --format text | grep -q 'Invoice #2026-041'
+```
+
+- `inspect --check` takes repeatable, ANDed assertions — `pdfa`, `signed`,
+  `encrypted`, `pdfua` _(v1.1.0)_ — and sets the exit code accordingly; under
+  `--json`, a failed assertion also emits the stable error class
+  `E_CHECK_FAILED` in the machine-readable envelope on stderr
+  (`{ ok: false, command, error: { code, message } }`).
+- `--summary` _(v1.1.0)_ shrinks the stdout verdict to
+  `{ pages, encrypted, signatures, pdfa }`; `--fields a,b.c` projects arbitrary
+  dot-paths — both exist so agents branch on facts without paying for the full
+  report.
+- `pdfnative verify --strict` performs the cryptographic half: byte-range
+  digest, CMS signature value (RSA and ECDSA), certificate chain and trust
+  against `--trust` roots, RFC 3161 timestamps, OCSP/CRL revocation — exit 1
+  and `E_VERIFY_FAILED` on any failure *or on zero signatures*.
+
+The full command reference, including every `--check` flag and the `E_*`
+catalogue, is in the [CLI guide](cli.html).
+
+## The same loop on MCP
+
+`pdfnative-mcp` gives a conversational agent the identical verifiers as
+read-only tools — the natural final step after any document tool call:
+
+| Tool | Verifies |
+|---|---|
+| `inspect_pdf` | Version, page count, encryption, PDF/A claim, signatures, attachments, `/Info` — plus `check` assertions with a boolean verdict. |
+| `inspect_layout` _(v1.6.0)_ | Pagination dry run for a prospective document — page count and block geometry, no PDF produced, no base64 output tokens spent. |
+| `validate_pdf` | Structural PDF/UA — `{ valid, errors, warnings }`. |
+| `verify_pdf` | Cryptographic signature verification; `ltv: true` _(v1.6.0)_ reports the achieved PAdES level (B-B → B-LTA). |
+
+```jsonc
+{ "tool": "inspect_pdf",
+  "input": { "pdfBase64": "<...>", "check": ["pdfa", "signed"] } }
+// → { ..., "checks": { "pdfa": true, "signed": true }, "checksPassed": true }
+```
+
+- `check` accepts `pdfa`, `signed`, `encrypted`, `placeholder`, `attachments`,
+  and — _(v1.6.0)_ — `dss`, `docTimestamp`, `trapped`, `annotations`.
+  `checksPassed` is the AND of all requested assertions; since v1.6.0 `checks`
+  contains **only** the requested keys, so branch on `checksPassed` or on a key
+  you asked for, never on an absent one.
+- `inspect_layout` accepts the same `title` / `blocks` (plus every input that
+  moves a block) as `generate_basic_pdf`, so an agent can iterate on pagination
+  before spending output tokens on real bytes. Known engine gap: a `toc` block
+  is measured as 0 pt, so a document with a printed contents page may paginate
+  one page later than previewed.
+- `validate_pdf` on unparsable bytes is an error (`PDF_PARSE_FAILED`), not a
+  `{ valid: false }` verdict, since v1.6.0 — a parse failure is not a PDF/UA
+  result.
+
+Tool-by-tool inputs and error codes are in the [MCP guide](mcp.html).
+
+## Wire it into CI and agent loops
+
+**CI.** Chain the loop with `set -e` so any failed assertion fails the job —
+no PDF-viewing human in the path:
+
+```bash
+set -e
+pdfnative render  --input report.json --output report.pdf --tagged pdfa2b
+pdfnative sign    --input report.pdf  --output signed.pdf --key k.pem --cert c.pem
+pdfnative inspect --input signed.pdf  --check pdfa --check signed --json --summary
+pdfnative verify  --input signed.pdf  --strict --trust ca-root.pem
+```
+
+`--dry-run` on the write commands validates inputs without producing output,
+which makes a cheap first CI stage; `--summary` / `--fields` keep logs and
+agent context small.
+
+**Agent loops.** Treat every generation as unfinished until a read tool
+confirms it: after `generate_basic_pdf` (or any document tool), call
+`inspect_pdf` with the `check` list that encodes the user's requirements and
+branch on `checksPassed`; on failure, correct the tool input and regenerate
+rather than apologising with an unverified file. Use `inspect_layout` before
+generating and `verbosity: "summary"` on the read tools to keep token spend
+proportional. The [agent brief](../agent-brief.md) condenses this contract
+into a paste-into-context form.
+
+## Further reading
+
+- [Agent brief](../agent-brief.md) — the compact form of this loop for AI
+  agents, verified by the documentation CI.
+- [Layout debugging & inspection](debugging.html) — the visual overlay and the
+  full `LayoutInspection` data shape.
+- [Text extraction](text-extraction.html) — decoding rules, positioned runs,
+  documented limits.
+- [PDF/A conformance](pdfa.html) — validating archival claims with veraPDF,
+  and the build-time `PDFA_*` diagnostics.
+- [Long-term validation (LTV)](ltv.html) — the PAdES ladder the signature
+  assertions climb.
+- [CLI guide](cli.html) · [MCP guide](mcp.html) — the complete surface
+  references.
diff --git a/docs/guides/signatures.html b/docs/guides/signatures.html
index ac3818e..f16892c 100644
--- a/docs/guides/signatures.html
+++ b/docs/guides/signatures.html
@@ -1,85 +1,491 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>Digital signatures — pdfnative</title>
-  <meta name="description" content="CMS/PKCS#7 detached signatures in pdfnative — RSA + ECDSA P-256, one-call addSignaturePlaceholder() workflow, Adobe Reader / openssl-cms validation.">
-  <link rel="canonical" href="https://pdfnative.dev/guides/signatures.html">
-  <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/signatures.html">
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Digital signatures — pdfnative</title>
+  <meta name="description" content="CMS/PKCS#7 detached signatures in pdfnative — RSA SHA-256/384/512 + ECDSA P-256, the PAdES baseline profile, multiple signatures and listSignatures() (v1.7.0), one-call addSignaturePlaceholder() workflow, Adobe Reader / openssl-cms validation.">
+  <link rel="canonical" href="https://pdfnative.dev/guides/signatures.html">
+  <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/signatures.html">
   <link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/signatures.html">
-  <link rel="alternate" type="text/markdown" href="signatures.md">
-  <meta property="og:type" content="article">
-  <meta property="og:site_name" content="pdfnative">
+  <link rel="alternate" type="text/markdown" href="signatures.md">
+  <link rel="alternate" type="text/plain" href="../llms.txt" title="llms.txt — machine-readable documentation index">
+  <meta property="og:type" content="article">
+  <meta property="og:site_name" content="pdfnative">
   <meta property="og:locale" content="en_US">
-  <meta property="og:url" content="https://pdfnative.dev/guides/signatures.html">
-  <meta property="og:title" content="Digital signatures — pdfnative">
-  <meta property="og:description" content="CMS/PKCS#7 detached signatures in pdfnative — RSA + ECDSA P-256, one-call addSignaturePlaceholder() workflow, Adobe Reader / openssl-cms validation.">
-  <meta property="og:image" content="https://pdfnative.dev/assets/og-image.png">
-  <meta property="og:image:width" content="1200">
-  <meta property="og:image:height" content="630">
-  <meta name="twitter:card" content="summary_large_image">
-  <meta name="twitter:title" content="Digital signatures — pdfnative">
-  <meta name="twitter:description" content="CMS/PKCS#7 detached signatures — RSA + ECDSA P-256, one-call addSignaturePlaceholder() workflow, Adobe Reader validation.">
-  <meta name="twitter:image" content="https://pdfnative.dev/assets/og-image.png">
-  <link rel="icon" type="image/svg+xml" href="../favicon.svg">
-  <link rel="stylesheet" href="../style.css">
-  <link rel="stylesheet" href="guide.css">
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
-</head>
-<body>
-
-<a class="skip-link" href="#main-content">Skip to main content</a>
-
-<nav class="nav" role="navigation" aria-label="Main navigation">
-  <div class="nav-inner">
-    <a class="nav-brand" href="../">
-      <img src="../assets/logo.svg" alt="" width="28" height="28">
-      pdfnative
-    </a>
-    <button class="nav-hamburger" aria-label="Toggle menu" aria-expanded="false">☰</button>
-    <ul class="nav-links" role="list">
-      <li><a href="../#features">Features</a></li>
-      <li><a href="../#examples">Examples</a></li>
-      <li><a href="../#demo">Demo</a></li>
-      <li><a href="../#mcp">MCP</a></li>
-      <li><a href="../#cli">CLI</a></li>
-      <li><a href="../#react">React</a></li>
-      <li><a href="../learn/">Learn</a></li>
-      <li><a href="./">Guides</a></li>
-      <li><a href="../playgrounds/">Playgrounds</a></li>
-      <li><a href="../responsibility.html">Responsibility</a></li>
-      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
-      <li><button class="theme-toggle" aria-label="Toggle dark mode">🌙</button></li>
-    </ul>
-  </div>
-</nav>
-
-<main class="guide-shell" id="main-content" tabindex="-1">
-  <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; Digital signatures</p>
-  <article id="guide-content" class="guide-content" data-md="signatures.md">
-    <p class="guide-loading">Loading…</p>
-    <noscript><p>This guide is written in Markdown: <a href="signatures.md">read signatures.md</a>.</p></noscript>
-  </article>
-</main>
-
-<footer class="footer">
-  <div class="footer-inner">
-    <span>MIT License · © 2026 Nizoka</span>
-    <ul class="footer-links" role="list">
-      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
-      <li><a href="https://www.npmjs.com/package/pdfnative" target="_blank" rel="noopener">npm</a></li>
-      <li><a href="https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md" target="_blank" rel="noopener">Changelog</a></li>
-      <li><a href="./">All guides</a></li>
-    </ul>
-  </div>
-</footer>
-
-<script src="https://cdn.jsdelivr.net/npm/marked@12.0.2/marked.min.js" integrity="sha384-/TQbtLCAerC3jgaim+N78RZSDYV7ryeoBCVqTuzRrFec2akfBkHS7ACQ3PQhvMVi" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/dompurify@3.1.5/dist/purify.min.js" integrity="sha384-nszIONF2FGC59kn+pPFaRa6WUNGwsZgXZiJxJwQbym+TzcH7smolUviLgpPbNx7V" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/prism.min.js" integrity="sha384-BGaNxfftg+9+TtC098wxawPFVEUpKYvaiCgbB0iqAMjK/4jDdmUY+oGxrPNvnXEf" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-typescript.min.js" integrity="sha384-PeOqKNW/piETaCg8rqKFy+Pm6KEk7e36/5YZE5XO/OaFdO+/Aw3O8qZ9qDPKVUgx" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-bash.min.js" integrity="sha384-9WmlN8ABpoFSSHvBGGjhvB3E/D8UkNB9HpLJjBQFC2VSQsM1odiQDv4NbEo+7l15" crossorigin="anonymous" defer></script>
-<script src="guide.js" defer></script>
-</body>
-</html>
+  <meta property="og:url" content="https://pdfnative.dev/guides/signatures.html">
+  <meta property="og:title" content="Digital signatures — pdfnative">
+  <meta property="og:description" content="CMS/PKCS#7 detached signatures in pdfnative — RSA SHA-256/384/512 + ECDSA P-256, the PAdES baseline profile, multiple signatures and listSignatures() (v1.7.0), one-call addSignaturePlaceholder() workflow, Adobe Reader / openssl-cms validation.">
+  <meta property="og:image" content="https://pdfnative.dev/assets/og-image.png">
+  <meta property="og:image:width" content="1200">
+  <meta property="og:image:height" content="630">
+  <meta name="twitter:card" content="summary_large_image">
+  <meta name="twitter:title" content="Digital signatures — pdfnative">
+  <meta name="twitter:description" content="CMS/PKCS#7 detached signatures — RSA SHA-256/384/512 + ECDSA P-256, PAdES profile and multiple signatures (v1.7.0), one-call addSignaturePlaceholder() workflow.">
+  <meta name="twitter:image" content="https://pdfnative.dev/assets/og-image.png">
+  <link rel="icon" type="image/svg+xml" href="../favicon.svg">
+  <link rel="stylesheet" href="../style.css">
+  <link rel="stylesheet" href="guide.css">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
+  <!-- guide:ld:start -->
+  <script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://pdfnative.dev/"},{"@type":"ListItem","position":2,"name":"Guides","item":"https://pdfnative.dev/guides/"},{"@type":"ListItem","position":3,"name":"Digital signatures in pdfnative","item":"https://pdfnative.dev/guides/signatures.html"}]},{"@type":"TechArticle","headline":"Digital signatures in pdfnative","description":"CMS/PKCS#7 detached signatures in pdfnative — RSA SHA-256/384/512 + ECDSA P-256, the PAdES baseline profile, multiple signatures and listSignatures() (v1.7.0), one-call addSignaturePlaceholder() workflow, Adobe Reader / openssl-cms validation.","inLanguage":"en","author":{"@type":"Organization","name":"Nizoka","url":"https://github.com/Nizoka"},"publisher":{"@type":"Organization","name":"pdfnative","url":"https://pdfnative.dev","logo":{"@type":"ImageObject","url":"https://pdfnative.dev/assets/logo.svg"}},"mainEntityOfPage":{"@type":"WebPage","@id":"https://pdfnative.dev/guides/signatures.html"},"isPartOf":{"@type":"WebSite","name":"pdfnative","url":"https://pdfnative.dev"}}]}</script>
+  <!-- guide:ld:end -->
+</head>
+<body>
+
+<a class="skip-link" href="#main-content">Skip to main content</a>
+
+<nav class="nav" role="navigation" aria-label="Main navigation">
+  <div class="nav-inner">
+    <a class="nav-brand" href="../">
+      <img src="../assets/logo.svg" alt="" width="28" height="28">
+      pdfnative
+    </a>
+    <button class="nav-hamburger" aria-label="Toggle menu" aria-expanded="false">☰</button>
+    <ul class="nav-links" role="list">
+      <li><a href="../#features">Features</a></li>
+      <li><a href="../#examples">Examples</a></li>
+      <li><a href="../#demo">Demo</a></li>
+      <li><a href="../#mcp">MCP</a></li>
+      <li><a href="../#cli">CLI</a></li>
+      <li><a href="../#react">React</a></li>
+      <li><a href="../learn/">Learn</a></li>
+      <li><a href="./">Guides</a></li>
+      <li><a href="../playgrounds/">Playgrounds</a></li>
+      <li><a href="../responsibility.html">Responsibility</a></li>
+      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
+      <li><button class="theme-toggle" aria-label="Toggle dark mode">🌙</button></li>
+    </ul>
+  </div>
+</nav>
+
+<main class="guide-shell" id="main-content" tabindex="-1">
+  <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; Digital signatures</p>
+  <article id="guide-content" class="guide-content" data-md="signatures.md" data-prerendered="true">
+<!-- guide:render:start -->
+<h1 id="digital-signatures-in-pdfnative">Digital signatures in pdfnative</h1>
+<blockquote>
+<p><strong>CMS/PKCS#7 detached signatures in pure TypeScript</strong> — RSA PKCS#1 v1.5 (SHA-256/384/512) and ECDSA P-256, the PAdES baseline profile and multiple signatures since v1.7.0, with a one-call <code>addSignaturePlaceholder()</code> workflow. For timestamps and B-T → B-LTA, see the <a href="ltv.html">LTV guide</a>.</p>
+</blockquote>
+<p>pdfnative ships a zero-dependency CMS/PKCS#7 detached signature
+implementation (ISO 32000-1 §12.8) with full crypto in pure TypeScript —
+RSA PKCS#1 v1.5 (SHA-256, plus SHA-384/512 since v1.7.0) and ECDSA P-256 (SHA-256), X.509 DER parsing,
+and ASN.1 DER encoding. No OpenSSL, no node-forge, no external crypto.</p>
+<h2 id="tldr--sign-any-pdf-in-3-lines">TL;DR — sign any PDF in 3 lines<a class="heading-anchor" href="#tldr--sign-any-pdf-in-3-lines" aria-label="Link to this section">#</a></h2>
+<pre><code class="language-ts">import {
+    buildDocumentPDFBytes,
+    addSignaturePlaceholder,
+    signPdfBytes,
+    parseCertificate,
+    parseRsaPrivateKey,
+} from &#39;pdfnative&#39;;
+
+const unsigned = buildDocumentPDFBytes(params);
+const placeheld = addSignaturePlaceholder(unsigned, { fieldName: &#39;Author&#39; });
+const signed = signPdfBytes(placeheld, {
+    signerCert: parseCertificate(certDer),  // X509Certificate (from DER bytes)
+    rsaKey: parseRsaPrivateKey(keyDer),     // RsaPrivateKey (from DER bytes)
+    algorithm: &#39;rsa-sha256&#39;,
+});
+</code></pre>
+<p>That&#39;s it. <code>addSignaturePlaceholder()</code> injects an
+AcroForm + invisible signature widget + <code>/Sig</code> dictionary into the
+existing PDF via an incremental update (ISO 32000-1 §7.5.6), then
+<code>signPdfBytes()</code> computes the <code>/ByteRange</code>, hashes the document, builds
+the CMS SignedData, and writes the result into the <code>/Contents</code>
+placeholder.</p>
+<h2 id="three-step-pipeline">Three-step pipeline<a class="heading-anchor" href="#three-step-pipeline" aria-label="Link to this section">#</a></h2>
+<pre><code>buildDocumentPDFBytes(params)
+        │
+        ▼
+   unsigned PDF
+        │
+        │  addSignaturePlaceholder()  ← injects AcroForm + /Sig dict
+        ▼
+   PDF with /ByteRange + /Contents placeholder
+        │
+        │  signPdfBytes()             ← hashes, signs, fills /Contents
+        ▼
+   signed PDF (Adobe Reader ✓ / openssl-cms ✓)
+</code></pre>
+<h3 id="1-addsignatureplaceholderpdfbytes-options">1. <code>addSignaturePlaceholder(pdfBytes, options?)</code><a class="heading-anchor" href="#1-addsignatureplaceholderpdfbytes-options" aria-label="Link to this section">#</a></h3>
+<p>Idempotent. If the input already contains an <code>/FT /Sig</code> widget,
+returns the input unchanged. Throws on encrypted input.</p>
+<p>Options:</p>
+<table>
+<thead>
+<tr>
+<th>Option</th>
+<th>Default</th>
+<th>Notes</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>placeholderBytes</code></td>
+<td><code>16384</code></td>
+<td>Size of the <code>/Contents</code> hex placeholder</td>
+</tr>
+<tr>
+<td><code>fieldName</code></td>
+<td><code>&#39;Signature1&#39;</code></td>
+<td>AcroForm field name</td>
+</tr>
+<tr>
+<td><code>pageIndex</code></td>
+<td><code>0</code></td>
+<td>Page to attach the (invisible) widget to</td>
+</tr>
+<tr>
+<td><code>rect</code></td>
+<td><code>[0, 0, 0, 0]</code></td>
+<td>Widget rectangle (invisible by default)</td>
+</tr>
+<tr>
+<td><code>allowMultiple</code></td>
+<td><code>false</code></td>
+<td>Append a placeholder even when signature fields already exist — the multi-signature flow (v1.7.0, see below)</td>
+</tr>
+</tbody></table>
+<p>To size <code>placeholderBytes</code> from your actual certificate chain instead of
+relying on the 16 KiB default, use <code>estimateContentsSize(certSizes, algorithm)</code>.
+Since v1.7.0 it takes an options object: <code>estimateContentsSize(certSizes, &#39;rsa-sha256&#39;, { timestamp: true })</code> reserves ~8 KiB of extra headroom for an
+RFC 3161 timestamp token (covering the TSA&#39;s own certificate chain) when an
+external signer will add one to the CMS.</p>
+<p>Signer metadata (<code>name</code>, <code>reason</code>, <code>location</code>, <code>contactInfo</code>, <code>signingTime</code>)
+is <strong>not</strong> set here — the placeholder writes an empty <code>/Sig</code> dictionary; pass
+the metadata to <code>signPdfBytes</code>, which writes it at signing time.</p>
+<h3 id="2-signpdfbytespdfbytes-options">2. <code>signPdfBytes(pdfBytes, options)</code><a class="heading-anchor" href="#2-signpdfbytespdfbytes-options" aria-label="Link to this section">#</a></h3>
+<p>Reads the <code>/ByteRange</code>, hashes the two byte ranges (everything except
+the <code>/Contents</code> slot), builds a CMS SignedData with the certificate
+chain and <code>signedAttrs</code> (content-type, message-digest, signing-time),
+signs the <code>signedAttrs</code> digest, and writes the DER-encoded CMS into
+<code>/Contents</code>.</p>
+<p>Options:</p>
+<ul>
+<li><code>signerCert</code> — <code>X509Certificate</code> (parse DER bytes with <code>parseCertificate</code>).</li>
+<li><code>rsaKey</code> <em>or</em> <code>ecKey</code> — the private key. Parse RSA keys from DER with
+<code>parseRsaPrivateKey</code>; for ECDSA there is no DER parser in the engine — supply
+the <code>EcPrivateKey</code> scalar directly, or install a crypto provider
+(<code>setCryptoProvider</code> / per-call <code>provider</code>) and omit the raw key entirely.</li>
+<li><code>algorithm</code> — <code>&#39;rsa-sha256&#39; | &#39;rsa-sha384&#39; | &#39;rsa-sha512&#39; | &#39;ecdsa-sha256&#39;</code>
+(default <code>&#39;rsa-sha256&#39;</code>; the SHA-384/512 RSA variants are new in v1.7.0).</li>
+<li><code>certChain?</code> — additional intermediate-CA certificates for the chain.</li>
+<li><code>signingTime?</code> — forwarded to <code>signedAttrs</code>.</li>
+<li><code>fieldName?</code> — with several unsigned placeholders in the file (the
+<code>allowMultiple</code> flow below), selects which one to sign by its AcroForm field
+name. With a single placeholder — the only case prior to v1.7.0 — the option
+is unnecessary and behaviour is unchanged. (v1.7.0)</li>
+</ul>
+<h3 id="3-verifying">3. Verifying<a class="heading-anchor" href="#3-verifying" aria-label="Link to this section">#</a></h3>
+<p>The library does <strong>not</strong> ship a PDF-signature verifier — its
+verification surface is limited to <code>openPdf()</code> plus
+<code>verifyCertSignature()</code> (an X.509 certificate-signature check). To
+verify a signed PDF end to end (byte-range digest, CMS signature value,
+chain, trust, timestamps, revocation), use
+<a href="cli.html#pdfnative-verify"><code>pdfnative-cli verify</code></a> or the
+<a href="mcp.html"><code>verify_pdf</code> MCP tool</a> — the CMS verification logic lives
+there. Since pdfnative-mcp 1.6.0, <code>verify_pdf</code> also validates
+<code>/DocTimeStamp</code> fields as RFC 3161 tokens and reports the achieved
+PAdES level (B-B → B-LTA) with <code>ltv: true</code>.</p>
+<h2 id="why-a-separate-placeholder-step">Why a separate placeholder step?<a class="heading-anchor" href="#why-a-separate-placeholder-step" aria-label="Link to this section">#</a></h2>
+<p>The PDF signature spec is unusual: the <code>/Contents</code> field of the <code>/Sig</code>
+dictionary must contain the CMS bytes, <strong>but the <code>/ByteRange</code> excludes
+exactly that slot</strong>. So the PDF is hashed <em>without</em> the bytes we&#39;re
+about to write, which means the file must already have the right
+layout — including the placeholder reserved bytes — before we sign.</p>
+<p><code>addSignaturePlaceholder()</code> is the canonical way to produce that
+layout. It replaces the ad-hoc reimplementations that downstream
+tooling (notably <code>pdfnative-cli</code>&#39;s <code>sign</code> command and <code>pdfnative-mcp</code>&#39;s
+<code>prepare_signature_placeholder</code> workaround) previously had to ship.</p>
+<h2 id="multiple-signatures-v170">Multiple signatures (v1.7.0)<a class="heading-anchor" href="#multiple-signatures-v170" aria-label="Link to this section">#</a></h2>
+<p>Simply repeating the placeholder + sign pass does <strong>not</strong> add a second
+signature: <code>addSignaturePlaceholder()</code> is idempotent by contract, so on a PDF
+that already carries any <code>/FT /Sig</code> field it returns the input unchanged. To
+add further signatures, opt in with <code>allowMultiple</code> and give each signature its
+own field name:</p>
+<pre><code class="language-ts">// First signer.
+let pdf = addSignaturePlaceholder(unsigned, { fieldName: &#39;Author&#39; });
+pdf = signPdfBytes(pdf, {
+    signerCert: authorCert, rsaKey: authorKey, algorithm: &#39;rsa-sha256&#39;,
+});
+
+// Second signer — appended as a fresh incremental update.
+pdf = addSignaturePlaceholder(pdf, { fieldName: &#39;Reviewer&#39;, allowMultiple: true });
+pdf = signPdfBytes(pdf, {
+    signerCert: reviewerCert, rsaKey: reviewerKey, algorithm: &#39;rsa-sha256&#39;,
+    fieldName: &#39;Reviewer&#39;, // selects which unsigned placeholder to fill
+});
+</code></pre>
+<p>The exact semantics:</p>
+<ul>
+<li><strong><code>allowMultiple: false</code></strong> (default) preserves the 1.x idempotent
+short-circuit: any existing signature field returns the input unchanged.</li>
+<li><strong><code>allowMultiple: true</code></strong> — an existing <em>unsigned</em> placeholder with the same
+<code>fieldName</code> returns the input unchanged (per-name idempotence); a <em>signed</em>
+field with the same name throws (pass a fresh <code>fieldName</code>); other signature
+fields are left alone and a new placeholder is appended via incremental
+update, so <code>/Prev</code> chains compose naturally.</li>
+<li><strong><code>signPdfBytes</code> with several unsigned placeholders</strong> requires the
+<code>fieldName</code> selector — without it, the call throws and lists the unsigned
+field names. Already-signed signatures are never modified.</li>
+</ul>
+<h2 id="inspecting-signatures--listsignatures-v170">Inspecting signatures — <code>listSignatures()</code> (v1.7.0)<a class="heading-anchor" href="#inspecting-signatures--listsignatures-v170" aria-label="Link to this section">#</a></h2>
+<p><code>listSignatures(pdfBytes)</code> enumerates every signature field in a PDF, in
+AcroForm <code>/Fields</code> order — signed signatures, document timestamps, and
+still-unsigned placeholders:</p>
+<pre><code class="language-ts">import { listSignatures } from &#39;pdfnative&#39;;
+
+for (const sig of listSignatures(signedPdf)) {
+    console.log(sig.fieldName, sig.subFilter, sig.isPlaceholder);
+}
+// → &#39;Author&#39;   &#39;adbe.pkcs7.detached&#39; false
+// → &#39;Reviewer&#39; &#39;adbe.pkcs7.detached&#39; false
+</code></pre>
+<p>Each entry is a <code>PdfSignatureInfo</code>:</p>
+<table>
+<thead>
+<tr>
+<th>Field</th>
+<th>Type</th>
+<th>Meaning</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>fieldName?</code></td>
+<td><code>string</code></td>
+<td>The widget&#39;s <code>/T</code> field name, when present</td>
+</tr>
+<tr>
+<td><code>subFilter</code></td>
+<td><code>string</code></td>
+<td><code>/SubFilter</code> — e.g. <code>&#39;adbe.pkcs7.detached&#39;</code>, <code>&#39;ETSI.CAdES.detached&#39;</code>, <code>&#39;ETSI.RFC3161&#39;</code> (<code>&#39;&#39;</code> when absent)</td>
+</tr>
+<tr>
+<td><code>byteRange</code></td>
+<td><code>readonly number[]</code></td>
+<td><code>/ByteRange</code> offsets</td>
+</tr>
+<tr>
+<td><code>contents</code></td>
+<td><code>Uint8Array</code></td>
+<td>The full decoded <code>/Contents</code> value, trailing zero padding included</td>
+</tr>
+<tr>
+<td><code>isDocTimestamp</code></td>
+<td><code>boolean</code></td>
+<td><code>true</code> for <code>/Type /DocTimeStamp</code> entries (ISO 32000-2 §12.8.5)</td>
+</tr>
+<tr>
+<td><code>isPlaceholder</code></td>
+<td><code>boolean</code></td>
+<td><code>true</code> for an unsigned placeholder (all-zero <code>/ByteRange</code>)</td>
+</tr>
+<tr>
+<td><code>sigObjNum</code></td>
+<td><code>number</code></td>
+<td>Object number of the <code>/Sig</code> dictionary</td>
+</tr>
+</tbody></table>
+<p><code>listSignatures()</code> is a read-only inspection API — it never <strong>verifies</strong>
+anything (see <em>Verifying</em> above for the verification story).</p>
+<p>Related v1.7.0 addition: <code>SigDictMetadata</code> — the metadata subset shared by
+<code>buildSigDict()</code> and the signing options — gains a <code>subFilter</code> field,
+<code>&#39;adbe.pkcs7.detached&#39;</code> (default, unchanged legacy behaviour) or
+<code>&#39;ETSI.CAdES.detached&#39;</code> to declare a PAdES (ETSI EN 319 142) signature.
+<code>buildSigDict()</code> writes it into the <code>/Sig</code> dictionary, and <code>listSignatures()</code>
+reports it back on each entry. When declaring <code>&#39;ETSI.CAdES.detached&#39;</code>, pair it
+with the <code>profile: &#39;pades&#39;</code> signing option so the CMS carries the matching
+ESS <code>signing-certificate-v2</code> attribute.</p>
+<h2 id="algorithms">Algorithms<a class="heading-anchor" href="#algorithms" aria-label="Link to this section">#</a></h2>
+<table>
+<thead>
+<tr>
+<th>Algorithm</th>
+<th>Hash</th>
+<th>Curve / Modulus</th>
+<th>Notes</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>rsa-sha256</code></td>
+<td>SHA-256</td>
+<td>2048 / 3072 / 4096</td>
+<td>PKCS#1 v1.5 (default)</td>
+</tr>
+<tr>
+<td><code>rsa-sha384</code></td>
+<td>SHA-384</td>
+<td>2048 / 3072 / 4096</td>
+<td>PKCS#1 v1.5 (v1.7.0)</td>
+</tr>
+<tr>
+<td><code>rsa-sha512</code></td>
+<td>SHA-512</td>
+<td>2048 / 3072 / 4096</td>
+<td>PKCS#1 v1.5 (v1.7.0)</td>
+</tr>
+<tr>
+<td><code>ecdsa-sha256</code></td>
+<td>SHA-256</td>
+<td>P-256 (secp256r1)</td>
+<td>DER-encoded ECDSA signature</td>
+</tr>
+</tbody></table>
+<p>That is the complete <code>SignatureAlgorithm</code> union — the RSA variants widened
+to SHA-384/512 in v1.7.0; ECDSA is offered with SHA-256 only.</p>
+<p>All primitives live under <a href="https://github.com/Nizoka/pdfnative/tree/main/src/crypto" target="_blank" rel="noopener">src/crypto/</a>:
+SHA-256/384/512 in <code>sha.ts</code>, ASN.1 DER in <code>asn1.ts</code>, RSA modular
+arithmetic in <code>rsa.ts</code>, ECDSA P-256 in <code>ecdsa.ts</code>, X.509 parsing in
+<code>x509.ts</code>, and the CMS SignedData builder in <code>cms.ts</code>.</p>
+<h2 id="validating-the-output">Validating the output<a class="heading-anchor" href="#validating-the-output" aria-label="Link to this section">#</a></h2>
+<pre><code class="language-bash"># openssl-cms — extract the CMS payload and verify against the certificate
+openssl pkcs7 -in signed.pdf -inform DER -print_certs
+
+# Adobe Reader — open signed.pdf; signatures panel shows the field name,
+# signing time, signer subject, and a green check if the chain validates.
+
+# pdfnative-cli — full CMS verification (the library itself has no PDF-signature verifier)
+npx pdfnative-cli verify --input signed.pdf --strict
+# → { &quot;signatures&quot;: [ { &quot;integrity&quot;: true, &quot;signatureValid&quot;: true, ... } ] }
+</code></pre>
+<h2 id="reading-the-validator-output">Reading the validator output<a class="heading-anchor" href="#reading-the-validator-output" aria-label="Link to this section">#</a></h2>
+<p>Two warnings commonly surface when testing the sample PDFs in Adobe Reader.
+Both are <strong>expected by spec</strong> — they are not pdfnative bugs.</p>
+<h3 id="validity-unknown--identité-du-signataire-inconnue">&quot;Validity unknown&quot; / &quot;Identité du signataire inconnue&quot;<a class="heading-anchor" href="#validity-unknown--identité-du-signataire-inconnue" aria-label="Link to this section">#</a></h3>
+<p>Adobe shows this whenever the signing certificate&#39;s issuer chain does
+not terminate in a root CA listed in Adobe&#39;s Approved Trust List (AATL)
+or in the user&#39;s locally configured Trusted Identities.</p>
+<ul>
+<li>The <code>scripts/generators/digital-signature.ts</code> sample uses a
+<strong>self-signed demo CA</strong> so it can ship deterministically. The
+cryptographic signature itself is valid (Adobe says so:
+<em>&quot;Le document n&#39;a pas été modifié depuis l&#39;apposition de la signature&quot;</em>);
+only the identity link to a public root is missing.</li>
+<li>To remove the warning in Adobe Reader: <strong>Preferences → Signatures →
+Identités → Identités autorisées → Ajouter</strong> and import the demo
+certificate as a trusted root.</li>
+<li>To verify the CMS independently of any trust store, use
+<code>openssl pkcs7 -in signed.pdf -inform DER -print_certs</code> and
+<code>openssl cms -verify -CAfile demo-ca.pem</code>.</li>
+<li>For production signatures, use a certificate issued by a CA in the
+Adobe Approved Trust List (Sectigo, DigiCert, GlobalSign…) or your
+organisation&#39;s enterprise CA distributed via group policy.</li>
+</ul>
+<h3 id="signature-non-valable-on-a-placeholder-pdf">&quot;Signature non valable&quot; on a placeholder PDF<a class="heading-anchor" href="#signature-non-valable-on-a-placeholder-pdf" aria-label="Link to this section">#</a></h3>
+<p>A PDF that has only been through <code>addSignaturePlaceholder()</code> (i.e. not
+yet <code>signPdfBytes()</code>) <strong>will</strong> read as invalid in Adobe — and that is
+correct behaviour. The <code>/Sig</code> dictionary&#39;s <code>/Contents</code> slot is
+zero-padded hex by design, reserved for the CMS SignedData that the
+external signer will produce. Adobe sees a malformed CMS and reports
+the signature as broken.</p>
+<p>The <code>scripts/generators/signature-placeholder.ts</code> sample produces
+exactly this shape on purpose, to demonstrate:</p>
+<ol>
+<li>The placeholder layout is byte-stable (the <code>-idempotent</code> companion
+PDF proves it — re-running the function produces identical bytes).</li>
+<li>Downstream tooling (HSMs, cloud KMS, smartcards) can fill in
+<code>/Contents</code> without touching the surrounding objects.</li>
+</ol>
+<p>To turn a placeholder into a valid signature, call <code>signPdfBytes()</code> on
+the placeholder bytes — that&#39;s the pipeline shown in the TL;DR above.</p>
+<h2 id="caveats">Caveats<a class="heading-anchor" href="#caveats" aria-label="Link to this section">#</a></h2>
+<ul>
+<li><strong>Encrypted PDFs.</strong> <code>addSignaturePlaceholder()</code> throws on encrypted
+input — sign before encrypting, or decrypt first.</li>
+<li><strong>Timestamping (RFC 3161).</strong> Supported since v1.7.0 —
+<code>signPdfBytesWithTimestamp()</code> embeds a verified TSA token as the
+<code>id-aa-signatureTimeStampToken</code> unsigned attribute, and
+<code>addDocumentTimestamp()</code> appends <code>/DocTimeStamp</code> revisions. See the
+<a href="ltv.html">Long-term validation guide</a> for the full PAdES B-B → B-LTA
+pipeline (timestamps, <code>/DSS</code> + <code>/VRI</code>, injected providers).</li>
+<li><strong>Multiple signatures.</strong> Supported since v1.7.0, but <strong>not</strong> by naively
+repeating the placeholder + sign pass — <code>addSignaturePlaceholder()</code> is
+idempotent and returns an already-signed PDF unchanged. Pass
+<code>allowMultiple: true</code> with a fresh <code>fieldName</code>, then select that field in
+<code>signPdfBytes</code> — see <a href="#multiple-signatures-v170">Multiple signatures</a>
+above.</li>
+<li><strong>PDF/A + signatures.</strong> PDF/A-2b/3b allow signatures; ISO 19005-2
+§6.3.5 forbids certain <code>/Sig</code> dictionary fields (<code>/Reference</code>,
+<code>/Changes</code>). pdfnative emits only the conformant subset.</li>
+<li><strong>Timing side-channels (pure-JS BigInt).</strong> The RSA/ECDSA math runs on
+JavaScript <code>BigInt</code>, which is <strong>not</strong> constant-time — the RSA modular
+exponentiation in particular is a secret-dependent square-and-multiply
+loop. Signing a PDF once per user action is not meaningfully
+exploitable, but a high-frequency server signing thousands of PDFs/s
+with the same key under adversarial timing observation could
+theoretically leak key material. For such pipelines, install a native
+constant-time signer via <code>setCryptoProvider()</code> (see below) — or compute the
+CMS/PKCS#7 blob with a constant-time native backend (Node.js
+<code>crypto.sign()</code> or WebCrypto <code>crypto.subtle.sign()</code>) and inject it via
+<code>signPdfBytes()</code>. See <a href="https://github.com/Nizoka/pdfnative/blob/main/SECURITY.md#cryptographic-implementation-scope--known-limitations" target="_blank" rel="noopener">SECURITY.md</a>
+for the full analysis.</li>
+</ul>
+<h2 id="native-crypto-provider-v140">Native crypto provider (v1.4.0)<a class="heading-anchor" href="#native-crypto-provider-v140" aria-label="Link to this section">#</a></h2>
+<p>For high-security, high-frequency server pipelines you can replace
+pdfnative&#39;s pure-JS RSA/ECDSA math with a native, <strong>constant-time</strong> signer
+without giving up the zero-dependency default. Install a provider globally
+with <code>setCryptoProvider(provider)</code>, or pass one per call via
+<code>PdfSignOptions.provider</code> (per-call wins over global). When a provider is set,
+<code>rsaKey</code> / <code>ecKey</code> are no longer required.</p>
+<pre><code class="language-ts">import { setCryptoProvider, signPdfBytes } from &#39;pdfnative&#39;;
+import { createSign, createPrivateKey } from &#39;node:crypto&#39;;
+
+const key = createPrivateKey(pemPrivateKey);
+
+setCryptoProvider({
+    // `tbs` is the DER-encoded CMS signed attributes. The provider hashes it
+    // with SHA-256 internally (node:crypto does this for you) and returns the
+    // raw signature value (RSA PKCS#1 v1.5, or a DER-encoded ECDSA-P256 sig).
+    sign(tbs, algorithm) {
+        return new Uint8Array(createSign(&#39;sha256&#39;).update(tbs).sign(key));
+    },
+});
+
+const signed = signPdfBytes(placeheld, {
+    signerCert: cert,
+    algorithm: &#39;rsa-sha256&#39;, // rsaKey/ecKey no longer needed
+});
+
+// Restore the pure-JS default at any time:
+setCryptoProvider(null);
+</code></pre>
+<p>This is the in-library escape hatch for the BigInt timing caveat above — the
+secret-dependent math runs in <code>node:crypto</code> / Web Crypto / an HSM while
+pdfnative&#39;s CMS/PKCS#7 assembly is reused unchanged.</p>
+<h2 id="full-example">Full example<a class="heading-anchor" href="#full-example" aria-label="Link to this section">#</a></h2>
+<p>See <a href="https://github.com/Nizoka/pdfnative/blob/main/scripts/generators/digital-signature.ts" target="_blank" rel="noopener">scripts/generators/digital-signature.ts</a>
+for a runnable RSA + ECDSA sample (key generation, certificate
+construction, sign, verify) and
+<a href="https://github.com/Nizoka/pdfnative/blob/main/scripts/generators/signature-placeholder.ts" target="_blank" rel="noopener">scripts/generators/signature-placeholder.ts</a>
+for the idempotency proof.</p>
+<h2 id="related-guides">Related guides<a class="heading-anchor" href="#related-guides" aria-label="Link to this section">#</a></h2>
+<ul>
+<li><a href="pdfa.html">PDF/A conformance →</a> — how signatures interact with PDF/A-2b/3b.</li>
+<li><a href="architecture.html">Architecture →</a> — where the crypto module sits in the dependency graph.</li>
+<li><a href="cli.html">CLI →</a> — <code>pdfnative-cli sign</code> wraps this exact pipeline.</li>
+<li><a href="mcp.html">MCP integration →</a> — <code>pdfnative-mcp</code> exposes signing as an AI tool, and since v1.6.0 the complete PAdES ladder: <code>sign_pdf</code> (<code>profile: &#39;pades&#39;</code>, RFC 3161 <code>timestamp</code>) → <code>add_ltv</code> (<code>/DSS</code> + <code>/VRI</code>, B-LT) → <code>timestamp_pdf</code> (<code>/DocTimeStamp</code>, B-LTA), verified with <code>verify_pdf ltv: true</code>.</li>
+</ul>
+<!-- guide:render:end -->
+  </article>
+</main>
+
+<footer class="footer">
+  <div class="footer-inner">
+    <span>MIT License · © 2026 Nizoka</span>
+    <ul class="footer-links" role="list">
+      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
+      <li><a href="https://www.npmjs.com/package/pdfnative" target="_blank" rel="noopener">npm</a></li>
+      <li><a href="https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md" target="_blank" rel="noopener">Changelog</a></li>
+      <li><a href="./">All guides</a></li>
+    </ul>
+  </div>
+</footer>
+
+<script src="https://cdn.jsdelivr.net/npm/marked@12.0.2/marked.min.js" integrity="sha384-/TQbtLCAerC3jgaim+N78RZSDYV7ryeoBCVqTuzRrFec2akfBkHS7ACQ3PQhvMVi" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/dompurify@3.1.5/dist/purify.min.js" integrity="sha384-nszIONF2FGC59kn+pPFaRa6WUNGwsZgXZiJxJwQbym+TzcH7smolUviLgpPbNx7V" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/prism.min.js" integrity="sha384-BGaNxfftg+9+TtC098wxawPFVEUpKYvaiCgbB0iqAMjK/4jDdmUY+oGxrPNvnXEf" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-typescript.min.js" integrity="sha384-PeOqKNW/piETaCg8rqKFy+Pm6KEk7e36/5YZE5XO/OaFdO+/Aw3O8qZ9qDPKVUgx" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-bash.min.js" integrity="sha384-9WmlN8ABpoFSSHvBGGjhvB3E/D8UkNB9HpLJjBQFC2VSQsM1odiQDv4NbEo+7l15" crossorigin="anonymous" defer></script>
+<script src="guide.js" defer></script>
+</body>
+</html>
diff --git a/docs/guides/signatures.md b/docs/guides/signatures.md
index 148dd03..351570a 100644
--- a/docs/guides/signatures.md
+++ b/docs/guides/signatures.md
@@ -1,8 +1,10 @@
 # Digital signatures in pdfnative
+
+> **CMS/PKCS#7 detached signatures in pure TypeScript** — RSA PKCS#1 v1.5 (SHA-256/384/512) and ECDSA P-256, the PAdES baseline profile and multiple signatures since v1.7.0, with a one-call `addSignaturePlaceholder()` workflow. For timestamps and B-T → B-LTA, see the [LTV guide](ltv.html).
 
 pdfnative ships a zero-dependency CMS/PKCS#7 detached signature
 implementation (ISO 32000-1 §12.8) with full crypto in pure TypeScript —
-RSA PKCS#1 v1.5 and ECDSA P-256, both with SHA-256, X.509 DER parsing,
+RSA PKCS#1 v1.5 (SHA-256, plus SHA-384/512 since v1.7.0) and ECDSA P-256 (SHA-256), X.509 DER parsing,
 and ASN.1 DER encoding. No OpenSSL, no node-forge, no external crypto.
 
 ## TL;DR — sign any PDF in 3 lines
@@ -108,7 +110,9 @@ verify a signed PDF end to end (byte-range digest, CMS signature value,
 chain, trust, timestamps, revocation), use
 [`pdfnative-cli verify`](cli.html#pdfnative-verify) or the
 [`verify_pdf` MCP tool](mcp.html) — the CMS verification logic lives
-there.
+there. Since pdfnative-mcp 1.6.0, `verify_pdf` also validates
+`/DocTimeStamp` fields as RFC 3161 tokens and reports the achieved
+PAdES level (B-B → B-LTA) with `ltv: true`.
 
 ## Why a separate placeholder step?
 
@@ -358,4 +362,4 @@ for the idempotency proof.
 - [PDF/A conformance →](pdfa.html) — how signatures interact with PDF/A-2b/3b.
 - [Architecture →](architecture.html) — where the crypto module sits in the dependency graph.
 - [CLI →](cli.html) — `pdfnative-cli sign` wraps this exact pipeline.
-- [MCP integration →](mcp.html) — `pdfnative-mcp` exposes signing as an AI tool.
+- [MCP integration →](mcp.html) — `pdfnative-mcp` exposes signing as an AI tool, and since v1.6.0 the complete PAdES ladder: `sign_pdf` (`profile: 'pades'`, RFC 3161 `timestamp`) → `add_ltv` (`/DSS` + `/VRI`, B-LT) → `timestamp_pdf` (`/DocTimeStamp`, B-LTA), verified with `verify_pdf ltv: true`.
diff --git a/docs/guides/streaming.html b/docs/guides/streaming.html
index 9f6eff7..6399b96 100644
--- a/docs/guides/streaming.html
+++ b/docs/guides/streaming.html
@@ -1,85 +1,252 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>Streaming output — pdfnative</title>
-  <meta name="description" content="Stream PDFs from pdfnative as AsyncGenerator&lt;Uint8Array&gt; — fixed-size, object-boundary, and true constant-memory modes. Pipe to disk, HTTP, or Web Streams.">
-  <link rel="canonical" href="https://pdfnative.dev/guides/streaming.html">
-  <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/streaming.html">
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Streaming output — pdfnative</title>
+  <meta name="description" content="Stream PDFs from pdfnative as AsyncGenerator&lt;Uint8Array&gt; — fixed-size, object-boundary, and true constant-memory modes. Pipe to disk, HTTP, or Web Streams.">
+  <link rel="canonical" href="https://pdfnative.dev/guides/streaming.html">
+  <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/streaming.html">
   <link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/streaming.html">
-  <link rel="alternate" type="text/markdown" href="streaming.md">
-  <meta property="og:type" content="article">
-  <meta property="og:site_name" content="pdfnative">
+  <link rel="alternate" type="text/markdown" href="streaming.md">
+  <link rel="alternate" type="text/plain" href="../llms.txt" title="llms.txt — machine-readable documentation index">
+  <meta property="og:type" content="article">
+  <meta property="og:site_name" content="pdfnative">
   <meta property="og:locale" content="en_US">
-  <meta property="og:url" content="https://pdfnative.dev/guides/streaming.html">
-  <meta property="og:title" content="Streaming output — pdfnative">
-  <meta property="og:description" content="Stream PDFs from pdfnative as AsyncGenerator&lt;Uint8Array&gt; — fixed-size, object-boundary, and true constant-memory modes. Pipe to disk, HTTP, or Web Streams. True streaming new in v1.3.0.">
-  <meta property="og:image" content="https://pdfnative.dev/assets/og-image.png">
-  <meta property="og:image:width" content="1200">
-  <meta property="og:image:height" content="630">
-  <meta name="twitter:card" content="summary_large_image">
-  <meta name="twitter:title" content="Streaming output — pdfnative">
-  <meta name="twitter:description" content="Stream PDFs as AsyncGenerator — fixed-size, object-boundary, and true constant-memory modes. Pipe to disk, HTTP, or Web Streams.">
-  <meta name="twitter:image" content="https://pdfnative.dev/assets/og-image.png">
-  <link rel="icon" type="image/svg+xml" href="../favicon.svg">
-  <link rel="stylesheet" href="../style.css">
-  <link rel="stylesheet" href="guide.css">
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
-</head>
-<body>
-
-<a class="skip-link" href="#main-content">Skip to main content</a>
-
-<nav class="nav" role="navigation" aria-label="Main navigation">
-  <div class="nav-inner">
-    <a class="nav-brand" href="../">
-      <img src="../assets/logo.svg" alt="" width="28" height="28">
-      pdfnative
-    </a>
-    <button class="nav-hamburger" aria-label="Toggle menu" aria-expanded="false">☰</button>
-    <ul class="nav-links" role="list">
-      <li><a href="../#features">Features</a></li>
-      <li><a href="../#examples">Examples</a></li>
-      <li><a href="../#demo">Demo</a></li>
-      <li><a href="../#mcp">MCP</a></li>
-      <li><a href="../#cli">CLI</a></li>
-      <li><a href="../#react">React</a></li>
-      <li><a href="../learn/">Learn</a></li>
-      <li><a href="./">Guides</a></li>
-      <li><a href="../playgrounds/">Playgrounds</a></li>
-      <li><a href="../responsibility.html">Responsibility</a></li>
-      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
-      <li><button class="theme-toggle" aria-label="Toggle dark mode">🌙</button></li>
-    </ul>
-  </div>
-</nav>
-
-<main class="guide-shell" id="main-content" tabindex="-1">
-  <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; Streaming output</p>
-  <article id="guide-content" class="guide-content" data-md="streaming.md">
-    <p class="guide-loading">Loading…</p>
-    <noscript><p>This guide is written in Markdown: <a href="streaming.md">read streaming.md</a>.</p></noscript>
-  </article>
-</main>
-
-<footer class="footer">
-  <div class="footer-inner">
-    <span>MIT License · © 2026 Nizoka</span>
-    <ul class="footer-links" role="list">
-      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
-      <li><a href="https://www.npmjs.com/package/pdfnative" target="_blank" rel="noopener">npm</a></li>
-      <li><a href="https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md" target="_blank" rel="noopener">Changelog</a></li>
-      <li><a href="./">All guides</a></li>
-    </ul>
-  </div>
-</footer>
-
-<script src="https://cdn.jsdelivr.net/npm/marked@12.0.2/marked.min.js" integrity="sha384-/TQbtLCAerC3jgaim+N78RZSDYV7ryeoBCVqTuzRrFec2akfBkHS7ACQ3PQhvMVi" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/dompurify@3.1.5/dist/purify.min.js" integrity="sha384-nszIONF2FGC59kn+pPFaRa6WUNGwsZgXZiJxJwQbym+TzcH7smolUviLgpPbNx7V" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/prism.min.js" integrity="sha384-BGaNxfftg+9+TtC098wxawPFVEUpKYvaiCgbB0iqAMjK/4jDdmUY+oGxrPNvnXEf" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-typescript.min.js" integrity="sha384-PeOqKNW/piETaCg8rqKFy+Pm6KEk7e36/5YZE5XO/OaFdO+/Aw3O8qZ9qDPKVUgx" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-bash.min.js" integrity="sha384-9WmlN8ABpoFSSHvBGGjhvB3E/D8UkNB9HpLJjBQFC2VSQsM1odiQDv4NbEo+7l15" crossorigin="anonymous" defer></script>
-<script src="guide.js" defer></script>
-</body>
-</html>
+  <meta property="og:url" content="https://pdfnative.dev/guides/streaming.html">
+  <meta property="og:title" content="Streaming output — pdfnative">
+  <meta property="og:description" content="Stream PDFs from pdfnative as AsyncGenerator&lt;Uint8Array&gt; — fixed-size, object-boundary, and true constant-memory modes. Pipe to disk, HTTP, or Web Streams. True streaming new in v1.3.0.">
+  <meta property="og:image" content="https://pdfnative.dev/assets/og-image.png">
+  <meta property="og:image:width" content="1200">
+  <meta property="og:image:height" content="630">
+  <meta name="twitter:card" content="summary_large_image">
+  <meta name="twitter:title" content="Streaming output — pdfnative">
+  <meta name="twitter:description" content="Stream PDFs as AsyncGenerator — fixed-size, object-boundary, and true constant-memory modes. Pipe to disk, HTTP, or Web Streams.">
+  <meta name="twitter:image" content="https://pdfnative.dev/assets/og-image.png">
+  <link rel="icon" type="image/svg+xml" href="../favicon.svg">
+  <link rel="stylesheet" href="../style.css">
+  <link rel="stylesheet" href="guide.css">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
+  <!-- guide:ld:start -->
+  <script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://pdfnative.dev/"},{"@type":"ListItem","position":2,"name":"Guides","item":"https://pdfnative.dev/guides/"},{"@type":"ListItem","position":3,"name":"Streaming output","item":"https://pdfnative.dev/guides/streaming.html"}]},{"@type":"TechArticle","headline":"Streaming output","description":"Stream PDFs from pdfnative as AsyncGenerator<Uint8Array> — fixed-size, object-boundary, and true constant-memory modes. Pipe to disk, HTTP, or Web Streams.","inLanguage":"en","author":{"@type":"Organization","name":"Nizoka","url":"https://github.com/Nizoka"},"publisher":{"@type":"Organization","name":"pdfnative","url":"https://pdfnative.dev","logo":{"@type":"ImageObject","url":"https://pdfnative.dev/assets/logo.svg"}},"mainEntityOfPage":{"@type":"WebPage","@id":"https://pdfnative.dev/guides/streaming.html"},"isPartOf":{"@type":"WebSite","name":"pdfnative","url":"https://pdfnative.dev"}}]}</script>
+  <!-- guide:ld:end -->
+</head>
+<body>
+
+<a class="skip-link" href="#main-content">Skip to main content</a>
+
+<nav class="nav" role="navigation" aria-label="Main navigation">
+  <div class="nav-inner">
+    <a class="nav-brand" href="../">
+      <img src="../assets/logo.svg" alt="" width="28" height="28">
+      pdfnative
+    </a>
+    <button class="nav-hamburger" aria-label="Toggle menu" aria-expanded="false">☰</button>
+    <ul class="nav-links" role="list">
+      <li><a href="../#features">Features</a></li>
+      <li><a href="../#examples">Examples</a></li>
+      <li><a href="../#demo">Demo</a></li>
+      <li><a href="../#mcp">MCP</a></li>
+      <li><a href="../#cli">CLI</a></li>
+      <li><a href="../#react">React</a></li>
+      <li><a href="../learn/">Learn</a></li>
+      <li><a href="./">Guides</a></li>
+      <li><a href="../playgrounds/">Playgrounds</a></li>
+      <li><a href="../responsibility.html">Responsibility</a></li>
+      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
+      <li><button class="theme-toggle" aria-label="Toggle dark mode">🌙</button></li>
+    </ul>
+  </div>
+</nav>
+
+<main class="guide-shell" id="main-content" tabindex="-1">
+  <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; Streaming output</p>
+  <article id="guide-content" class="guide-content" data-md="streaming.md" data-prerendered="true">
+<!-- guide:render:start -->
+<h1 id="streaming-output">Streaming output</h1>
+<blockquote>
+<p>pdfnative emits PDFs as <code>AsyncGenerator&lt;Uint8Array&gt;</code> so you can pipe them to disk, an HTTP response, or a Web Stream without buffering the whole document. <strong>New in v1.3.0:</strong> a mode in which the fully-joined PDF binary never exists in memory — see <a href="#what-this-does-and-does-not-buy-you">what this does and does not buy you</a> for the exact profile.</p>
+</blockquote>
+<h2 id="three-streaming-modes">Three streaming modes<a class="heading-anchor" href="#three-streaming-modes" aria-label="Link to this section">#</a></h2>
+<table>
+<thead>
+<tr>
+<th>Function</th>
+<th>Memory profile</th>
+<th>When to use</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>buildDocumentPDFStream</code> / <code>buildPDFStream</code></td>
+<td>Assembles full binary, then yields fixed-size chunks</td>
+<td>Simple back-pressure-friendly piping</td>
+</tr>
+<tr>
+<td><code>buildDocumentPDFStreamPageByPage</code> / <code>buildPDFStreamPageByPage</code></td>
+<td>Assembles full binary, yields one PDF object per chunk</td>
+<td>Object-granular persistence / diagnostics</td>
+</tr>
+<tr>
+<td><strong><code>buildDocumentPDFStreamTrue</code> / <code>buildPDFStreamTrue</code></strong></td>
+<td><strong>Never joins the binary — frees each part as it yields</strong></td>
+<td>Large documents, and anything over ~512 MB of output</td>
+</tr>
+</tbody></table>
+<p>All three produce <strong>byte-identical</strong> output to <code>buildDocumentPDFBytes()</code> /
+<code>buildPDFBytes()</code>.</p>
+<h2 id="streaming-without-joining-the-binary-v130">Streaming without joining the binary (v1.3.0)<a class="heading-anchor" href="#streaming-without-joining-the-binary-v130" aria-label="Link to this section">#</a></h2>
+<pre><code class="language-ts">import { createWriteStream } from &#39;node:fs&#39;;
+import { buildDocumentPDFStreamTrue } from &#39;pdfnative&#39;;
+
+const out = createWriteStream(&#39;report.pdf&#39;);
+for await (const chunk of buildDocumentPDFStreamTrue(params, layout, { chunkSize: 65536 })) {
+  out.write(chunk);
+}
+out.end();
+</code></pre>
+<p>Internally, the builder assembles the PDF into an array of raw parts (objects,
+xref, trailer) and the generator walks that array, encoding each part to bytes
+and <strong>freeing it (<code>parts[i] = &#39;&#39;</code>) as soon as it is emitted</strong>.</p>
+<h3 id="what-this-does-and-does-not-buy-you">What this does and does not buy you<a class="heading-anchor" href="#what-this-does-and-does-not-buy-you" aria-label="Link to this section">#</a></h3>
+<p>Being precise here matters, because the two claims are often conflated.</p>
+<p><strong>What it avoids.</strong> The joined PDF binary never exists. That removes a full
+second copy of the document, and it lifts the hard ceiling that
+<code>buildDocumentPDFStream</code> hits: that variant joins everything into one JavaScript
+string, and V8 caps a single string at roughly 512 MB. Past that point it throws
+regardless of how much RAM the machine has. <code>buildDocumentPDFStreamTrue</code> has no
+such ceiling.</p>
+<p><strong>What it does not avoid.</strong> <code>assembleDocumentParts()</code> runs to completion before
+the first chunk is yielded, so every part is resident at that moment. Peak memory
+is therefore still proportional to total output size — roughly 2 bytes per output
+character, since JavaScript strings are UTF-16. From the first yield onwards
+memory falls monotonically as parts are freed, but the peak has already happened.</p>
+<p>Two practical consequences:</p>
+<ul>
+<li>Budget for about twice your expected output size, not for a fixed ceiling.
+A 300 MB PDF wants roughly 600 MB of headroom.</li>
+<li><strong>There is no progress signal during assembly.</strong> Most of the wall-clock time is
+spent inside <code>assembleDocumentParts()</code>, which yields nothing, so a percentage
+bar covering that phase would be invented rather than measured. Report an
+indeterminate state until the first chunk arrives, then switch to a byte
+counter. The <a href="../playgrounds/scale.html">scale playground</a> does exactly this.</li>
+</ul>
+<p>True page-by-page assembly — where peak memory is bounded by one page rather than
+the whole document — is not implemented yet.</p>
+<h3 id="http-response-node">HTTP response (Node)<a class="heading-anchor" href="#http-response-node" aria-label="Link to this section">#</a></h3>
+<pre><code class="language-ts">import { buildDocumentPDFStreamTrue } from &#39;pdfnative&#39;;
+
+app.get(&#39;/report.pdf&#39;, async (req, res) =&gt; {
+  res.setHeader(&#39;Content-Type&#39;, &#39;application/pdf&#39;);
+  for await (const chunk of buildDocumentPDFStreamTrue(params)) {
+    res.write(chunk);
+  }
+  res.end();
+});
+</code></pre>
+<h3 id="web-streams-browser--deno--edge">Web Streams (browser / Deno / edge)<a class="heading-anchor" href="#web-streams-browser--deno--edge" aria-label="Link to this section">#</a></h3>
+<pre><code class="language-ts">const stream = new ReadableStream({
+  async pull(controller) {
+    for await (const chunk of buildDocumentPDFStreamTrue(params)) {
+      controller.enqueue(chunk);
+    }
+    controller.close();
+  },
+});
+return new Response(stream, { headers: { &#39;Content-Type&#39;: &#39;application/pdf&#39; } });
+</code></pre>
+<h2 id="options">Options<a class="heading-anchor" href="#options" aria-label="Link to this section">#</a></h2>
+<pre><code class="language-ts">interface StreamOptions {
+  /** Bytes per yielded chunk. Default 65536 (64 KB). Clamped to 1 KB–16 MB. */
+  chunkSize?: number;
+}
+</code></pre>
+<h2 id="draining-to-a-file-streamtofile-v140">Draining to a file: <code>streamToFile</code> (v1.4.0)<a class="heading-anchor" href="#draining-to-a-file-streamtofile-v140" aria-label="Link to this section">#</a></h2>
+<p><code>streamToFile()</code> drains <strong>any</strong> <code>AsyncGenerator&lt;Uint8Array&gt;</code> — including all
+three streaming modes above — straight to a file on disk in Node.js. It honours
+the OS write back-pressure (awaiting the <code>&#39;drain&#39;</code> event when the kernel buffer
+fills) and supports cancellation via an <code>AbortSignal</code>, so a single call covers
+the common &quot;generate a large PDF to disk without buffering it&quot; case.</p>
+<pre><code class="language-ts">import { buildDocumentPDFStreamTrue, streamToFile } from &#39;pdfnative&#39;;
+
+const { bytesWritten, path } = await streamToFile(
+  buildDocumentPDFStreamTrue(params),
+  &#39;report.pdf&#39;,
+);
+console.log(`Wrote ${bytesWritten} bytes to ${path}`);
+</code></pre>
+<h3 id="cancellation">Cancellation<a class="heading-anchor" href="#cancellation" aria-label="Link to this section">#</a></h3>
+<pre><code class="language-ts">const ac = new AbortController();
+setTimeout(() =&gt; ac.abort(), 5000); // give up after 5s
+
+await streamToFile(buildDocumentPDFStreamTrue(params), &#39;report.pdf&#39;, {
+  signal: ac.signal,
+}); // rejects with the abort reason; the partial file is closed
+</code></pre>
+<p>On abort — or on any write error — <code>streamToFile</code> releases the file descriptor
+and <strong>removes the partially-written file</strong> (best-effort), so a cancelled or
+failed run never leaves an orphaned half-written PDF on disk.</p>
+<p><code>streamToFile</code> is Node-only — it loads <code>node:fs</code> lazily via a dynamic import,
+so importing it in a browser or Deno bundle adds no static Node dependency. In
+non-Node runtimes, drive the generator yourself with the Web Streams snippet
+above.</p>
+<h2 id="streaming-merge--split-v160">Streaming merge &amp; split (v1.6.0)<a class="heading-anchor" href="#streaming-merge--split-v160" aria-label="Link to this section">#</a></h2>
+<p>The page-tree API has constant-memory variants —
+<code>streamMergedPdfs</code> / <code>streamSplitPdf</code> / <code>streamExtractPages</code> — that emit the
+assembled document as fixed-size chunks while holding only the cross-reference
+offsets in memory. Each is byte-identical to its buffered counterpart and
+composes with <code>streamToFile</code>. (Exception: with <code>MergeOptions.encrypt</code> the
+output is AES-encrypted with fresh random IVs/salts, so repeated invocations
+are structurally — not byte — identical.)</p>
+<pre><code class="language-ts">import { streamMergedPdfs, streamSplitPdf, streamToFile } from &#39;pdfnative&#39;;
+
+await streamToFile(streamMergedPdfs([a, b]), &#39;combined.pdf&#39;);
+
+for await (const part of streamSplitPdf(body, ranges)) {
+  await streamToFile(part.pdf, `part-${part.index}.pdf`);   // drain each fully, in order
+}
+</code></pre>
+<p>Note the honest memory profile: <strong>output</strong> bytes are never buffered, but the
+<strong>source</strong> PDFs are still in-memory <code>Uint8Array</code>s. See the
+<a href="pdf-manipulation.html#streaming-merge--split">PDF manipulation guide</a> for the
+full API.</p>
+<h2 id="constraints">Constraints<a class="heading-anchor" href="#constraints" aria-label="Link to this section">#</a></h2>
+<p>Streaming is incompatible with two features that need a second pass over the
+whole document. Both are validated at the boundary and throw a descriptive
+error:</p>
+<ul>
+<li><strong>TOC blocks</strong> — the table of contents requires multi-pass pagination to
+resolve page numbers.</li>
+<li><strong><code>{pages}</code> placeholder</strong> in header/footer templates — the total page count
+is unknown during progressive emission. Use <code>{page}</code> instead, or fall back to
+<code>buildDocumentPDFBytes()</code>.</li>
+</ul>
+<h2 id="see-also">See also<a class="heading-anchor" href="#see-also" aria-label="Link to this section">#</a></h2>
+<ul>
+<li><a href="quickstart.html">Quick start</a></li>
+<li><a href="architecture.html">Architecture</a></li>
+<li><a href="https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md" target="_blank" rel="noopener">CHANGELOG</a></li>
+</ul>
+<!-- guide:render:end -->
+  </article>
+</main>
+
+<footer class="footer">
+  <div class="footer-inner">
+    <span>MIT License · © 2026 Nizoka</span>
+    <ul class="footer-links" role="list">
+      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
+      <li><a href="https://www.npmjs.com/package/pdfnative" target="_blank" rel="noopener">npm</a></li>
+      <li><a href="https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md" target="_blank" rel="noopener">Changelog</a></li>
+      <li><a href="./">All guides</a></li>
+    </ul>
+  </div>
+</footer>
+
+<script src="https://cdn.jsdelivr.net/npm/marked@12.0.2/marked.min.js" integrity="sha384-/TQbtLCAerC3jgaim+N78RZSDYV7ryeoBCVqTuzRrFec2akfBkHS7ACQ3PQhvMVi" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/dompurify@3.1.5/dist/purify.min.js" integrity="sha384-nszIONF2FGC59kn+pPFaRa6WUNGwsZgXZiJxJwQbym+TzcH7smolUviLgpPbNx7V" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/prism.min.js" integrity="sha384-BGaNxfftg+9+TtC098wxawPFVEUpKYvaiCgbB0iqAMjK/4jDdmUY+oGxrPNvnXEf" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-typescript.min.js" integrity="sha384-PeOqKNW/piETaCg8rqKFy+Pm6KEk7e36/5YZE5XO/OaFdO+/Aw3O8qZ9qDPKVUgx" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-bash.min.js" integrity="sha384-9WmlN8ABpoFSSHvBGGjhvB3E/D8UkNB9HpLJjBQFC2VSQsM1odiQDv4NbEo+7l15" crossorigin="anonymous" defer></script>
+<script src="guide.js" defer></script>
+</body>
+</html>
diff --git a/docs/guides/tables.html b/docs/guides/tables.html
index 861ccf6..23a2c06 100644
--- a/docs/guides/tables.html
+++ b/docs/guides/tables.html
@@ -1,85 +1,410 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>Smart tables — pdfnative</title>
-  <meta name="description" content="Multi-page tables in pdfnative — auto-wrap on overflow, repeated headers, zebra striping, captions, smart auto-fit columns, and per-cell borders.">
-  <link rel="canonical" href="https://pdfnative.dev/guides/tables.html">
-  <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/tables.html">
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Smart tables — pdfnative</title>
+  <meta name="description" content="Multi-page tables in pdfnative — auto-wrap on overflow, repeated headers, zebra striping, captions, smart auto-fit columns, and per-cell borders.">
+  <link rel="canonical" href="https://pdfnative.dev/guides/tables.html">
+  <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/tables.html">
   <link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/tables.html">
-  <link rel="alternate" type="text/markdown" href="tables.md">
-  <meta property="og:type" content="article">
-  <meta property="og:site_name" content="pdfnative">
+  <link rel="alternate" type="text/markdown" href="tables.md">
+  <link rel="alternate" type="text/plain" href="../llms.txt" title="llms.txt — machine-readable documentation index">
+  <meta property="og:type" content="article">
+  <meta property="og:site_name" content="pdfnative">
   <meta property="og:locale" content="en_US">
-  <meta property="og:url" content="https://pdfnative.dev/guides/tables.html">
-  <meta property="og:title" content="Smart tables — pdfnative">
-  <meta property="og:description" content="Multi-page tables in pdfnative — auto-wrap on overflow, repeated headers across page breaks, zebra striping, captions, smart auto-fit columns. Planner-driven architecture.">
-  <meta property="og:image" content="https://pdfnative.dev/assets/og-image.png">
-  <meta property="og:image:width" content="1200">
-  <meta property="og:image:height" content="630">
-  <meta name="twitter:card" content="summary_large_image">
-  <meta name="twitter:title" content="Smart tables — pdfnative">
-  <meta name="twitter:description" content="Multi-page tables — auto-wrap, repeated headers, zebra striping, captions, smart auto-fit columns. Planner-driven architecture.">
-  <meta name="twitter:image" content="https://pdfnative.dev/assets/og-image.png">
-  <link rel="icon" type="image/svg+xml" href="../favicon.svg">
-  <link rel="stylesheet" href="../style.css">
-  <link rel="stylesheet" href="guide.css">
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
-</head>
-<body>
-
-<a class="skip-link" href="#main-content">Skip to main content</a>
-
-<nav class="nav" role="navigation" aria-label="Main navigation">
-  <div class="nav-inner">
-    <a class="nav-brand" href="../">
-      <img src="../assets/logo.svg" alt="" width="28" height="28">
-      pdfnative
-    </a>
-    <button class="nav-hamburger" aria-label="Toggle menu" aria-expanded="false">☰</button>
-    <ul class="nav-links" role="list">
-      <li><a href="../#features">Features</a></li>
-      <li><a href="../#examples">Examples</a></li>
-      <li><a href="../#demo">Demo</a></li>
-      <li><a href="../#mcp">MCP</a></li>
-      <li><a href="../#cli">CLI</a></li>
-      <li><a href="../#react">React</a></li>
-      <li><a href="../learn/">Learn</a></li>
-      <li><a href="./">Guides</a></li>
-      <li><a href="../playgrounds/">Playgrounds</a></li>
-      <li><a href="../responsibility.html">Responsibility</a></li>
-      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
-      <li><button class="theme-toggle" aria-label="Toggle dark mode">🌙</button></li>
-    </ul>
-  </div>
-</nav>
-
-<main class="guide-shell" id="main-content" tabindex="-1">
-  <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; Smart tables</p>
-  <article id="guide-content" class="guide-content" data-md="tables.md">
-    <p class="guide-loading">Loading…</p>
-    <noscript><p>This guide is written in Markdown: <a href="tables.md">read tables.md</a>.</p></noscript>
-  </article>
-</main>
-
-<footer class="footer">
-  <div class="footer-inner">
-    <span>MIT License · © 2026 Nizoka</span>
-    <ul class="footer-links" role="list">
-      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
-      <li><a href="https://www.npmjs.com/package/pdfnative" target="_blank" rel="noopener">npm</a></li>
-      <li><a href="https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md" target="_blank" rel="noopener">Changelog</a></li>
-      <li><a href="./">All guides</a></li>
-    </ul>
-  </div>
-</footer>
-
-<script src="https://cdn.jsdelivr.net/npm/marked@12.0.2/marked.min.js" integrity="sha384-/TQbtLCAerC3jgaim+N78RZSDYV7ryeoBCVqTuzRrFec2akfBkHS7ACQ3PQhvMVi" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/dompurify@3.1.5/dist/purify.min.js" integrity="sha384-nszIONF2FGC59kn+pPFaRa6WUNGwsZgXZiJxJwQbym+TzcH7smolUviLgpPbNx7V" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/prism.min.js" integrity="sha384-BGaNxfftg+9+TtC098wxawPFVEUpKYvaiCgbB0iqAMjK/4jDdmUY+oGxrPNvnXEf" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-typescript.min.js" integrity="sha384-PeOqKNW/piETaCg8rqKFy+Pm6KEk7e36/5YZE5XO/OaFdO+/Aw3O8qZ9qDPKVUgx" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-bash.min.js" integrity="sha384-9WmlN8ABpoFSSHvBGGjhvB3E/D8UkNB9HpLJjBQFC2VSQsM1odiQDv4NbEo+7l15" crossorigin="anonymous" defer></script>
-<script src="guide.js" defer></script>
-</body>
-</html>
+  <meta property="og:url" content="https://pdfnative.dev/guides/tables.html">
+  <meta property="og:title" content="Smart tables — pdfnative">
+  <meta property="og:description" content="Multi-page tables in pdfnative — auto-wrap on overflow, repeated headers across page breaks, zebra striping, captions, smart auto-fit columns. Planner-driven architecture.">
+  <meta property="og:image" content="https://pdfnative.dev/assets/og-image.png">
+  <meta property="og:image:width" content="1200">
+  <meta property="og:image:height" content="630">
+  <meta name="twitter:card" content="summary_large_image">
+  <meta name="twitter:title" content="Smart tables — pdfnative">
+  <meta name="twitter:description" content="Multi-page tables — auto-wrap, repeated headers, zebra striping, captions, smart auto-fit columns. Planner-driven architecture.">
+  <meta name="twitter:image" content="https://pdfnative.dev/assets/og-image.png">
+  <link rel="icon" type="image/svg+xml" href="../favicon.svg">
+  <link rel="stylesheet" href="../style.css">
+  <link rel="stylesheet" href="guide.css">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
+  <!-- guide:ld:start -->
+  <script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://pdfnative.dev/"},{"@type":"ListItem","position":2,"name":"Guides","item":"https://pdfnative.dev/guides/"},{"@type":"ListItem","position":3,"name":"Smart tables","item":"https://pdfnative.dev/guides/tables.html"}]},{"@type":"TechArticle","headline":"Smart tables","description":"Multi-page tables in pdfnative — auto-wrap on overflow, repeated headers, zebra striping, captions, smart auto-fit columns, and per-cell borders.","inLanguage":"en","author":{"@type":"Organization","name":"Nizoka","url":"https://github.com/Nizoka"},"publisher":{"@type":"Organization","name":"pdfnative","url":"https://pdfnative.dev","logo":{"@type":"ImageObject","url":"https://pdfnative.dev/assets/logo.svg"}},"mainEntityOfPage":{"@type":"WebPage","@id":"https://pdfnative.dev/guides/tables.html"},"isPartOf":{"@type":"WebSite","name":"pdfnative","url":"https://pdfnative.dev"}}]}</script>
+  <!-- guide:ld:end -->
+</head>
+<body>
+
+<a class="skip-link" href="#main-content">Skip to main content</a>
+
+<nav class="nav" role="navigation" aria-label="Main navigation">
+  <div class="nav-inner">
+    <a class="nav-brand" href="../">
+      <img src="../assets/logo.svg" alt="" width="28" height="28">
+      pdfnative
+    </a>
+    <button class="nav-hamburger" aria-label="Toggle menu" aria-expanded="false">☰</button>
+    <ul class="nav-links" role="list">
+      <li><a href="../#features">Features</a></li>
+      <li><a href="../#examples">Examples</a></li>
+      <li><a href="../#demo">Demo</a></li>
+      <li><a href="../#mcp">MCP</a></li>
+      <li><a href="../#cli">CLI</a></li>
+      <li><a href="../#react">React</a></li>
+      <li><a href="../learn/">Learn</a></li>
+      <li><a href="./">Guides</a></li>
+      <li><a href="../playgrounds/">Playgrounds</a></li>
+      <li><a href="../responsibility.html">Responsibility</a></li>
+      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
+      <li><button class="theme-toggle" aria-label="Toggle dark mode">🌙</button></li>
+    </ul>
+  </div>
+</nav>
+
+<main class="guide-shell" id="main-content" tabindex="-1">
+  <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; Smart tables</p>
+  <article id="guide-content" class="guide-content" data-md="tables.md" data-prerendered="true">
+<!-- guide:render:start -->
+<h1 id="smart-tables">Smart tables</h1>
+<blockquote>
+<p><em>Backward-compatible with v1.1.0 — existing single-page tables produce byte-identical output.</em></p>
+</blockquote>
+<p>pdfnative&#39;s table renderer is <strong>planner-driven</strong> and <strong>multi-page-safe</strong> by default. Long tables wrap on column overflow, slice cleanly across pages, and reprint their header on every continuation page — matching the behaviour readers expect from commercial PDF libraries.</p>
+<p>This guide documents the <code>TableBlock</code> fields, the planner architecture, the tagged-mode contract, and migration tips.</p>
+<hr>
+<h2 id="tldr">TL;DR<a class="heading-anchor" href="#tldr" aria-label="Link to this section">#</a></h2>
+<pre><code class="language-ts">import { buildDocumentPDFBytes } from &#39;pdfnative&#39;;
+
+const bytes = buildDocumentPDFBytes({
+    title: &#39;Invoice&#39;,
+    blocks: [
+        {
+            type: &#39;table&#39;,
+            headers: [&#39;Item&#39;, &#39;Qty&#39;, &#39;Price&#39;],
+            // PdfRow[]: e.g. { cells: [&#39;Pro plan&#39;, &#39;1&#39;, &#39;$49.00&#39;], type: &#39;default&#39;, pointed: false }
+            rows: bigInvoiceRows, // any length
+            columns: [            // optional ColumnDef[]: f = width fraction, a = align,
+                                  // mx / mxH = char caps (data / header), plus minWidth? / maxWidth?
+                { f: 0.6, a: &#39;l&#39;, mx: 40, mxH: 20 },
+                { f: 0.2, a: &#39;r&#39;, mx: 10, mxH: 8 },
+                { f: 0.2, a: &#39;r&#39;, mx: 10, mxH: 8 },
+            ],
+            autoFitColumns: true,  // content-aware widths (respects minWidth/maxWidth)
+            wrap: &#39;auto&#39;,          // ← new (default)
+            repeatHeader: true,    // ← new (default)
+            zebra: true,           // ← new (opt-in)
+            caption: &#39;Invoice line items&#39;,
+            minRowHeight: 14,
+            cellPadding: 5,
+        },
+    ],
+});
+</code></pre>
+<p>Existing v1.1.0 code with no new fields continues to work and produces <strong>byte-identical</strong> output on single-page tables.</p>
+<hr>
+<h2 id="tableblock-fields-all-optional"><code>TableBlock</code> fields (all optional)<a class="heading-anchor" href="#tableblock-fields-all-optional" aria-label="Link to this section">#</a></h2>
+<table>
+<thead>
+<tr>
+<th>Field</th>
+<th>Type</th>
+<th>Default</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>wrap</code></td>
+<td><code>&#39;auto&#39; | &#39;always&#39; | &#39;never&#39;</code></td>
+<td><code>&#39;auto&#39;</code></td>
+<td>Per-cell wrap policy.</td>
+</tr>
+<tr>
+<td><code>repeatHeader</code></td>
+<td><code>boolean</code></td>
+<td><code>true</code></td>
+<td>Reprint the header row at the top of each continuation page.</td>
+</tr>
+<tr>
+<td><code>zebra</code></td>
+<td><code>boolean | PdfColor</code></td>
+<td><code>false</code></td>
+<td>Alternating data-row fill. <code>true</code> uses <code>&#39;0.969 0.973 0.984&#39;</code>.</td>
+</tr>
+<tr>
+<td><code>caption</code></td>
+<td><code>string</code></td>
+<td><code>undefined</code></td>
+<td>Caption printed once above the first slice.</td>
+</tr>
+<tr>
+<td><code>minRowHeight</code></td>
+<td><code>number</code> (points)</td>
+<td><code>12</code></td>
+<td>Minimum visual row height.</td>
+</tr>
+<tr>
+<td><code>cellPadding</code></td>
+<td><code>number</code> (points)</td>
+<td><code>3</code></td>
+<td>Internal cell padding.</td>
+</tr>
+<tr>
+<td><code>cellBorders</code></td>
+<td><code>CellBorders</code></td>
+<td><code>undefined</code></td>
+<td>Per-cell vector borders (v1.4.0). Omit for byte-identical pre-1.4.0 output.</td>
+</tr>
+<tr>
+<td><code>cellVAlign</code></td>
+<td><code>&#39;top&#39; | &#39;middle&#39; | &#39;bottom&#39;</code></td>
+<td><code>undefined</code></td>
+<td>Vertical alignment of cell text within the row band (v1.4.0).</td>
+</tr>
+</tbody></table>
+<h3 id="wrap"><code>wrap</code><a class="heading-anchor" href="#wrap" aria-label="Link to this section">#</a></h3>
+<ul>
+<li><strong><code>&#39;auto&#39;</code></strong> (default) — single-line rendering when cell content fits within the column width; wraps on overflow only. This is the GAFAM-grade default — fast typical case, correct edge case.</li>
+<li><strong><code>&#39;always&#39;</code></strong> — every cell is run through the word-wrapper. Use when row heights need to be uniform regardless of content length.</li>
+<li><strong><code>&#39;never&#39;</code></strong> — v1.1.0 behaviour. Content is clipped at the column boundary. Use when output byte-stability against v1.1.0 is mandatory.</li>
+</ul>
+<h3 id="repeatheader"><code>repeatHeader</code><a class="heading-anchor" href="#repeatheader" aria-label="Link to this section">#</a></h3>
+<ul>
+<li><strong><code>true</code></strong> (default) — header row reprints at the top of every continuation page.</li>
+<li><strong><code>false</code></strong> — header appears only once. Set this alongside <code>wrap: &#39;never&#39;</code> to preserve the exact v1.1.0 multi-page rendering shape.</li>
+</ul>
+<h3 id="zebra"><code>zebra</code><a class="heading-anchor" href="#zebra" aria-label="Link to this section">#</a></h3>
+<ul>
+<li><strong><code>false</code></strong> (default) — no row fill.</li>
+<li><strong><code>true</code></strong> — alternating even data rows (1-indexed, so the second row, fourth row, …) are filled with <code>&#39;0.969 0.973 0.984&#39;</code> (a soft cool-grey tuned for accessibility contrast).</li>
+<li>A <a href="https://github.com/Nizoka/pdfnative#api-reference" target="_blank" rel="noopener"><code>PdfColor</code></a> — hex (<code>&#39;#f7f8fa&#39;</code>), tuple (<code>[247, 248, 250]</code>, channels <strong>0–255</strong>), or PDF-rgb string (<code>&#39;0.97 0.97 0.98&#39;</code>, channels 0.0–1.0) — overrides the default.</li>
+</ul>
+<h3 id="caption"><code>caption</code><a class="heading-anchor" href="#caption" aria-label="Link to this section">#</a></h3>
+<ul>
+<li>Printed once at the top of the table (above the first slice), using Helvetica 9pt.</li>
+<li>In tagged mode, emitted as a <code>/Caption</code> structure element child of <code>/Table</code> (ISO 14289-1 §7.10.6).</li>
+<li>Multi-line captions wrap to fit the table width.</li>
+</ul>
+<h3 id="minrowheight--cellpadding"><code>minRowHeight</code> / <code>cellPadding</code><a class="heading-anchor" href="#minrowheight--cellpadding" aria-label="Link to this section">#</a></h3>
+<ul>
+<li><code>minRowHeight</code> enforces a floor so rows look consistent even with short text.</li>
+<li><code>cellPadding</code> is the internal padding around each cell&#39;s text. Header padding inherits this but the baseline offset is a fixed v1.1.0-compatible constant (preserves byte-stability for the row body).</li>
+</ul>
+<h3 id="cellborders-v140"><code>cellBorders</code> (v1.4.0)<a class="heading-anchor" href="#cellborders-v140" aria-label="Link to this section">#</a></h3>
+<p>Draw per-cell vector borders. All sides are off by default — omitting <code>cellBorders</code> entirely keeps the table byte-identical to pre-1.4.0 (header underline + row separators only).</p>
+<pre><code class="language-ts">{
+    type: &#39;table&#39;,
+    headers: [&#39;Item&#39;, &#39;Qty&#39;],
+    rows: [/* … */],
+    cellBorders: {
+        all: true,            // shorthand for top+right+bottom+left
+        color: &#39;#cccccc&#39;,     // PdfColor — default &#39;0.8 0.8 0.8&#39;
+        width: 0.5,           // points — default 0.5
+        style: &#39;solid&#39;,       // &#39;solid&#39; | &#39;dashed&#39; | &#39;dotted&#39;
+    },
+}
+</code></pre>
+<table>
+<thead>
+<tr>
+<th>Field</th>
+<th>Type</th>
+<th>Default</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>top</code> / <code>right</code> / <code>bottom</code> / <code>left</code></td>
+<td><code>boolean</code></td>
+<td><code>false</code></td>
+<td>Enable individual edges.</td>
+</tr>
+<tr>
+<td><code>all</code></td>
+<td><code>boolean</code></td>
+<td><code>false</code></td>
+<td>Shorthand — enables all four edges.</td>
+</tr>
+<tr>
+<td><code>color</code></td>
+<td><code>PdfColor</code></td>
+<td><code>&#39;0.8 0.8 0.8&#39;</code></td>
+<td>Stroke colour (hex / tuple / PDF-rgb).</td>
+</tr>
+<tr>
+<td><code>width</code></td>
+<td><code>number</code> (points)</td>
+<td><code>0.5</code></td>
+<td>Stroke width.</td>
+</tr>
+<tr>
+<td><code>style</code></td>
+<td><code>&#39;solid&#39; | &#39;dashed&#39; | &#39;dotted&#39;</code></td>
+<td><code>&#39;solid&#39;</code></td>
+<td>Stroke style. The dash is reset after each cell so row separators stay solid.</td>
+</tr>
+</tbody></table>
+<p>Borders are pure vector strokes (<code>m … l S</code>), so output stays PDF/A-safe.</p>
+<h3 id="cellvalign-v140"><code>cellVAlign</code> (v1.4.0)<a class="heading-anchor" href="#cellvalign-v140" aria-label="Link to this section">#</a></h3>
+<p>Vertically align cell text within the row band. Useful when rows have a tall <code>minRowHeight</code> or wrapped cells of differing height. A per-column <a href="#tableblock-fields-all-optional"><code>ColumnDef.vAlign</code></a> overrides the table default.</p>
+<pre><code class="language-ts">{ type: &#39;table&#39;, headers: [/* … */], rows: [/* … */], minRowHeight: 30, cellVAlign: &#39;middle&#39; }
+</code></pre>
+<p><code>&#39;top&#39;</code> | <code>&#39;middle&#39;</code> | <code>&#39;bottom&#39;</code>. When omitted, the historic baseline placement is preserved exactly (byte-identical to pre-1.4.0).</p>
+<hr>
+<h2 id="columndefkind-field-optional"><code>ColumnDef.kind</code> field (optional)<a class="heading-anchor" href="#columndefkind-field-optional" aria-label="Link to this section">#</a></h2>
+<table>
+<thead>
+<tr>
+<th>Field</th>
+<th>Type</th>
+<th>Default</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>kind</code></td>
+<td><code>&#39;amount&#39;</code></td>
+<td><code>undefined</code></td>
+<td>Semantic hint. When set to <code>&#39;amount&#39;</code>, data cells in this column render in Helvetica-Bold with credit/debit colouring driven by <code>row.type</code>. Replaces the pre-1.2.0 hardcoded <code>i === 3</code> heuristic in <code>renderTable</code>.</td>
+</tr>
+</tbody></table>
+<pre><code class="language-ts">{
+  type: &#39;table&#39;,
+  headers: [&#39;Date&#39;, &#39;Description&#39;, &#39;Status&#39;, &#39;Amount&#39;],
+  columns: [
+    { f: 0.20, a: &#39;l&#39;, mx: 12, mxH: 12 },
+    { f: 0.45, a: &#39;l&#39;, mx: 60, mxH: 60 },
+    { f: 0.20, a: &#39;l&#39;, mx: 20, mxH: 20 },
+    { f: 0.15, a: &#39;r&#39;, mx: 18, mxH: 18, kind: &#39;amount&#39; }, // ← opt-in bold + credit/debit colour
+  ],
+  rows: [
+    { cells: [&#39;2026-05-01&#39;, &#39;Salary&#39;, &#39;Cleared&#39;, &#39;+3 000.00&#39;], type: &#39;credit&#39;, pointed: false },
+    { cells: [&#39;2026-05-03&#39;, &#39;Rent&#39;,   &#39;Pending&#39;, &#39;-1 250.00&#39;], type: &#39;debit&#39;,  pointed: false },
+  ],
+}
+</code></pre>
+<blockquote>
+<p><strong>Behaviour change for document-builder tables without <code>kind</code>.</strong> Previously the renderer applied Helvetica-Bold + credit/debit colour to whichever column happened to be at index 3. The current renderer removes that heuristic — opt in explicitly via <code>kind: &#39;amount&#39;</code>. The legacy <code>buildPDF()</code> (financial-statement) path keeps the historical heuristic for byte-identical v1.0/v1.1 output.</p>
+</blockquote>
+<hr>
+<h2 id="how-multi-page-tables-are-sliced">How multi-page tables are sliced<a class="heading-anchor" href="#how-multi-page-tables-are-sliced" aria-label="Link to this section">#</a></h2>
+<p>pdfnative uses a two-phase pipeline:</p>
+<ol>
+<li><strong>Plan phase</strong> — <code>planTable()</code> (<a href="https://github.com/Nizoka/pdfnative/blob/main/src/core/pdf-renderers.ts" target="_blank" rel="noopener">src/core/pdf-renderers.ts</a>) measures the entire table once: resolves columns (including <code>autoFit</code>), word-wraps each cell according to <code>wrap</code>, computes per-row heights, and produces a <code>TablePlan</code> containing every row&#39;s exact pixel height.</li>
+<li><strong>Slice phase</strong> — <code>_paginateBlocks()</code> in <a href="https://github.com/Nizoka/pdfnative/blob/main/src/core/pdf-document.ts" target="_blank" rel="noopener">src/core/pdf-document.ts</a> walks the plan greedily: it packs rows onto the current page until the next row would overflow, then emits a <code>TableSlice</code> ( <code>{ fromRow, toRow, drawCaption, drawHeader, isFinalSlice }</code>) and starts a new page. The caption is emitted once (on the first slice); the header is emitted on every slice when <code>repeatHeader: true</code>.</li>
+</ol>
+<p><code>renderTable()</code> is page-lifecycle-free — it accepts an optional <code>slice</code> parameter and renders exactly the rows the paginator asked for. There is no recursive &quot;if I overflow, start a new page&quot; inside the renderer; pagination decisions are deterministic and centralised.</p>
+<h3 id="edge-cases-handled">Edge cases handled<a class="heading-anchor" href="#edge-cases-handled" aria-label="Link to this section">#</a></h3>
+<ul>
+<li><strong>Empty <code>rows</code> array</strong> — emits a header-only slice with caption (if any). No crash, no zero-height row.</li>
+<li><strong>Single row taller than a fresh page</strong> — emitted as a one-row slice; <code>clipCells</code> (existing v1.1.0 behaviour) handles vertical overflow inside the cell.</li>
+<li><strong>No room on current page even after pushing the table to start</strong> — paginator forces a new page and retries.</li>
+</ul>
+<hr>
+<h2 id="tagged-mode--pdfua">Tagged-mode / PDF/UA<a class="heading-anchor" href="#tagged-mode--pdfua" aria-label="Link to this section">#</a></h2>
+<p>When the document is built with <code>tagged: true</code> (or any explicit PDF/A mode), the table emits the following structure tree:</p>
+<pre><code class="language-text">/Table
+├── /Caption       (only when caption is present)
+├── /TR  ← header
+│   ├── /TH
+│   ├── /TH
+│   └── /TH
+├── /TR  ← data row 1
+│   ├── /TD
+│   ├── /TD
+│   └── /TD
+└── /TR  ← data row N
+    └── …
+</code></pre>
+<p>The structure is <strong>single</strong> even when the table spans multiple pages. <code>_paginateBlocks()</code> shares a <code>tableStructAccum</code> array across all slices of the same table; the final slice commits it as <code>{ type: &#39;Table&#39;, children: tableStructAccum }</code>. Each <code>/TR</code> carries the correct <code>/StructParents</code> for its page so screen readers reconstruct the logical reading order correctly (ISO 14289-1 §7.10.6).</p>
+<p>Repeated headers in <code>repeatHeader: true</code> mode are <strong>not</strong> re-emitted in the structure tree — they are visual continuations only. The single <code>/TR</code> for the header sits at the top of the <code>/Table</code> element.</p>
+<hr>
+<h2 id="tagged-mode--zebra">Tagged-mode + zebra<a class="heading-anchor" href="#tagged-mode--zebra" aria-label="Link to this section">#</a></h2>
+<p>Zebra fills are decorative — they do not appear in the structure tree. PDF/UA conformance is preserved.</p>
+<blockquote>
+<p>⚠️ <strong>PDF/A-1b note.</strong> PDF/A-1b forbids transparency (ISO 19005-1 §6.4). Zebra fills are opaque solid rectangles, so they are safe under PDF/A-1b, but <strong>avoid combining zebra with <code>pdfa1b</code> watermarks</strong> that rely on <code>/ExtGState</code>. Default <code>tagged: true</code> (PDF/A-2b) has no such restriction.</p>
+</blockquote>
+<hr>
+<h2 id="migration-from-v110">Migration from v1.1.0<a class="heading-anchor" href="#migration-from-v110" aria-label="Link to this section">#</a></h2>
+<blockquote>
+<p><strong>One unconditional fix.</strong> Right- and centre-aligned <strong>bold header</strong> cells now use Helvetica-Bold metrics for width measurement (Adobe AFM), where pre-1.2.0 they were measured with Helvetica-Regular. This corrects a 2–5pt overshoot per cell that visually clipped the trailing glyph (e.g. the <code>t</code> in <code>Amount</code>). The fix shifts header glyph positioning by 2–5pt vs v1.1.0 — a genuine correctness improvement, not a regression. There is no opt-out.</p>
+</blockquote>
+<table>
+<thead>
+<tr>
+<th>You want…</th>
+<th>Setting</th>
+</tr>
+</thead>
+<tbody><tr>
+<td>Exact byte-identical v1.1.0 multi-page <em>body</em> output</td>
+<td><code>wrap: &#39;never&#39;, repeatHeader: false</code> (header positioning still corrected)</td>
+</tr>
+<tr>
+<td>Modern default (recommended)</td>
+<td>Omit all new fields — defaults are correct.</td>
+</tr>
+<tr>
+<td>Invoice / report parity with commercial libs</td>
+<td><code>wrap: &#39;auto&#39;, repeatHeader: true, zebra: true, caption: &#39;…&#39;</code></td>
+</tr>
+<tr>
+<td>Uniform row heights regardless of content</td>
+<td><code>wrap: &#39;always&#39;, minRowHeight: 18</code></td>
+</tr>
+<tr>
+<td>Maximum information density</td>
+<td><code>wrap: &#39;auto&#39;, cellPadding: 2, minRowHeight: 10</code></td>
+</tr>
+</tbody></table>
+<hr>
+<h2 id="samples-shipped">Samples shipped<a class="heading-anchor" href="#samples-shipped" aria-label="Link to this section">#</a></h2>
+<p>Run <code>npm run test:generate</code> to produce:</p>
+<ul>
+<li><code>test-output/document/table-wrap-auto.pdf</code> — wrap-on-overflow demo</li>
+<li><code>test-output/document/table-multipage-header-repeat.pdf</code> — 60-row table across 2+ pages with repeated header</li>
+<li><code>test-output/document/table-zebra-caption.pdf</code> — zebra + caption + min row height</li>
+<li><code>test-output/document/table-smart-autofit.pdf</code> — <code>autoFit</code> columns + wrap</li>
+</ul>
+<p>Generator: <a href="https://github.com/Nizoka/pdfnative/blob/main/scripts/generators/document-table-parity.ts" target="_blank" rel="noopener">scripts/generators/document-table-parity.ts</a>.</p>
+<hr>
+<h2 id="reference">Reference<a class="heading-anchor" href="#reference" aria-label="Link to this section">#</a></h2>
+<ul>
+<li>ISO 32000-1:2008 §9 — text rendering and positioning.</li>
+<li>ISO 14289-1:2014 §7.10.6 — tagged-PDF table structure (<code>/Table</code>, <code>/TR</code>, <code>/TH</code>, <code>/TD</code>, <code>/Caption</code>).</li>
+<li>ISO 19005-2:2011 — PDF/A-2b conformance.</li>
+</ul>
+<h3 id="internal-contracts-for-contributors">Internal contracts (for contributors)<a class="heading-anchor" href="#internal-contracts-for-contributors" aria-label="Link to this section">#</a></h3>
+<ul>
+<li><code>planTable()</code> and <code>TableSlice</code> live in <a href="https://github.com/Nizoka/pdfnative/blob/main/src/core/pdf-renderers.ts" target="_blank" rel="noopener">src/core/pdf-renderers.ts</a>. They are <strong>not</strong> re-exported from the package root. Treat them as internal — they may change without a major bump as long as the public <code>TableBlock</code> contract is preserved.</li>
+<li>Single-line row rendering uses <code>rowTop - rowH + 3</code> baseline for data and <code>rowTop - rowH + 4</code> for headers. These constants (<code>CELL_PAD_BOTTOM</code>, <code>HEADER_PAD_BOTTOM</code>) preserve byte-stability with v1.1.0 single-page output.</li>
+<li>The default <code>minRowHeight</code> (<code>12</code>) and default header height (<code>15</code>) match v1.1.0&#39;s <code>ROW_H</code> and <code>TH_H</code> constants exactly.</li>
+</ul>
+<hr>
+<h2 id="see-also">See also<a class="heading-anchor" href="#see-also" aria-label="Link to this section">#</a></h2>
+<ul>
+<li><a href="architecture.md">Architecture</a> — overall module layout.</li>
+<li><a href="pdfa.md">PDF/A conformance</a> — tagged-mode rules.</li>
+<li><a href="https://github.com/Nizoka/pdfnative/blob/main/README.md#api-reference" target="_blank" rel="noopener">API reference</a> — full <code>TableBlock</code> type.</li>
+</ul>
+<!-- guide:render:end -->
+  </article>
+</main>
+
+<footer class="footer">
+  <div class="footer-inner">
+    <span>MIT License · © 2026 Nizoka</span>
+    <ul class="footer-links" role="list">
+      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
+      <li><a href="https://www.npmjs.com/package/pdfnative" target="_blank" rel="noopener">npm</a></li>
+      <li><a href="https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md" target="_blank" rel="noopener">Changelog</a></li>
+      <li><a href="./">All guides</a></li>
+    </ul>
+  </div>
+</footer>
+
+<script src="https://cdn.jsdelivr.net/npm/marked@12.0.2/marked.min.js" integrity="sha384-/TQbtLCAerC3jgaim+N78RZSDYV7ryeoBCVqTuzRrFec2akfBkHS7ACQ3PQhvMVi" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/dompurify@3.1.5/dist/purify.min.js" integrity="sha384-nszIONF2FGC59kn+pPFaRa6WUNGwsZgXZiJxJwQbym+TzcH7smolUviLgpPbNx7V" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/prism.min.js" integrity="sha384-BGaNxfftg+9+TtC098wxawPFVEUpKYvaiCgbB0iqAMjK/4jDdmUY+oGxrPNvnXEf" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-typescript.min.js" integrity="sha384-PeOqKNW/piETaCg8rqKFy+Pm6KEk7e36/5YZE5XO/OaFdO+/Aw3O8qZ9qDPKVUgx" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-bash.min.js" integrity="sha384-9WmlN8ABpoFSSHvBGGjhvB3E/D8UkNB9HpLJjBQFC2VSQsM1odiQDv4NbEo+7l15" crossorigin="anonymous" defer></script>
+<script src="guide.js" defer></script>
+</body>
+</html>
diff --git a/docs/guides/tables.md b/docs/guides/tables.md
index 3115ef3..b907a14 100644
--- a/docs/guides/tables.md
+++ b/docs/guides/tables.md
@@ -114,7 +114,7 @@ Borders are pure vector strokes (`m … l S`), so output stays PDF/A-safe.
 
 ### `cellVAlign` (v1.4.0)
 
-Vertically align cell text within the row band. Useful when rows have a tall `minRowHeight` or wrapped cells of differing height. A per-column [`ColumnDef.vAlign`](#columndef-fields) overrides the table default.
+Vertically align cell text within the row band. Useful when rows have a tall `minRowHeight` or wrapped cells of differing height. A per-column [`ColumnDef.vAlign`](#tableblock-fields-all-optional) overrides the table default.
 
 ```ts
 { type: 'table', headers: [/* … */], rows: [/* … */], minRowHeight: 30, cellVAlign: 'middle' }
diff --git a/docs/guides/text-extraction.html b/docs/guides/text-extraction.html
index d621279..db63c33 100644
--- a/docs/guides/text-extraction.html
+++ b/docs/guides/text-extraction.html
@@ -9,6 +9,7 @@
   <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/text-extraction.html">
   <link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/text-extraction.html">
   <link rel="alternate" type="text/markdown" href="text-extraction.md">
+  <link rel="alternate" type="text/plain" href="../llms.txt" title="llms.txt — machine-readable documentation index">
   <meta property="og:type" content="article">
   <meta property="og:site_name" content="pdfnative">
   <meta property="og:locale" content="en_US">
@@ -26,6 +27,9 @@
   <link rel="stylesheet" href="../style.css">
   <link rel="stylesheet" href="guide.css">
   <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
+  <!-- guide:ld:start -->
+  <script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://pdfnative.dev/"},{"@type":"ListItem","position":2,"name":"Guides","item":"https://pdfnative.dev/guides/"},{"@type":"ListItem","position":3,"name":"Text extraction","item":"https://pdfnative.dev/guides/text-extraction.html"}]},{"@type":"TechArticle","headline":"Text extraction","description":"Extract Unicode text from any PDF with pdfnative's extractText() — per-page reading-order text, positioned runs, ToUnicode/encoding decoding, transparent decryption of encrypted documents. Zero dependencies. New in v1.6.0.","inLanguage":"en","author":{"@type":"Organization","name":"Nizoka","url":"https://github.com/Nizoka"},"publisher":{"@type":"Organization","name":"pdfnative","url":"https://pdfnative.dev","logo":{"@type":"ImageObject","url":"https://pdfnative.dev/assets/logo.svg"}},"mainEntityOfPage":{"@type":"WebPage","@id":"https://pdfnative.dev/guides/text-extraction.html"},"isPartOf":{"@type":"WebSite","name":"pdfnative","url":"https://pdfnative.dev"}}]}</script>
+  <!-- guide:ld:end -->
 </head>
 <body>
 
@@ -57,9 +61,164 @@
 
 <main class="guide-shell" id="main-content" tabindex="-1">
   <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; Text extraction</p>
-  <article id="guide-content" class="guide-content" data-md="text-extraction.md">
-    <p class="guide-loading">Loading…</p>
-    <noscript><p>This guide is written in Markdown: <a href="text-extraction.md">read text-extraction.md</a>.</p></noscript>
+  <article id="guide-content" class="guide-content" data-md="text-extraction.md" data-prerendered="true">
+<!-- guide:render:start -->
+<h1 id="text-extraction">Text extraction</h1>
+<blockquote>
+<p><strong>New in v1.6.0.</strong> Extract Unicode text from <strong>any PDF</strong> — including
+encrypted ones — with <code>extractText()</code>: per-page reading-order text plus
+optional positioned runs. Pure content-stream decoding, zero
+dependencies, no OCR engine, no rasterisation.</p>
+</blockquote>
+<h2 id="tldr">TL;DR<a class="heading-anchor" href="#tldr" aria-label="Link to this section">#</a></h2>
+<pre><code class="language-ts">import { extractText } from &#39;pdfnative&#39;;
+import { readFileSync } from &#39;node:fs&#39;;
+
+const bytes = readFileSync(&#39;report.pdf&#39;);
+
+for (const page of extractText(bytes)) {
+  console.log(`--- page ${page.pageIndex + 1} ---`);
+  console.log(page.text);
+}
+
+// Encrypted documents: pass the password (decryption is transparent).
+const secret = extractText(readFileSync(&#39;locked.pdf&#39;), { password: &#39;hunter2&#39; });
+
+// Positioned runs for layout-aware consumers (search hit boxes, RAG chunking).
+const [first] = extractText(bytes, { includeRuns: true, pages: [0] });
+for (const run of first.runs ?? []) {
+  console.log(run.text, `@ (${run.x.toFixed(1)}, ${run.y.toFixed(1)})`, run.fontSize);
+}
+</code></pre>
+<h2 id="extracttextbytes-options"><code>extractText(bytes, options?)</code><a class="heading-anchor" href="#extracttextbytes-options" aria-label="Link to this section">#</a></h2>
+<p>Returns one <code>ExtractedPageText</code> per requested page, in ascending page order:</p>
+<pre><code class="language-ts">interface ExtractTextOptions {
+  password?: string;        // for encrypted documents (delegated to openPdf)
+  pages?: number[];         // 0-based page indices; default: all pages
+  includeRuns?: boolean;    // also return positioned runs (default false)
+  maxTextLength?: number;   // hard cap on total characters (default 16 000 000)
+}
+
+interface ExtractedPageText {
+  pageIndex: number;        // 0-based index in the source document
+  text: string;             // reading-order text, &#39;\n&#39; between lines
+  runs?: ExtractedTextRun[];// content-stream order, when includeRuns is true
+}
+
+interface ExtractedTextRun {
+  text: string;             // decoded text of one show operation
+  x: number; y: number;     // device-space origin of the run (points)
+  fontSize: number;         // effective size (Tf size scaled by Tm × CTM)
+  fontName: string;         // font resource name, e.g. &#39;F1&#39;
+}
+</code></pre>
+<h2 id="how-text-is-decoded">How text is decoded<a class="heading-anchor" href="#how-text-is-decoded" aria-label="Link to this section">#</a></h2>
+<p>For every shown string, the extractor resolves each character code in
+this order:</p>
+<table>
+<thead>
+<tr>
+<th>Source</th>
+<th>Used for</th>
+<th>Notes</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>/ToUnicode</code> CMap</td>
+<td>any font that embeds one</td>
+<td><code>bfchar</code>, <code>bfrange</code> (both destination forms), surrogate pairs</td>
+</tr>
+<tr>
+<td><code>/Encoding /Differences</code></td>
+<td>simple fonts</td>
+<td>glyph names resolved through a compact AGL subset + <code>uniXXXX</code> / <code>uXXXX[XX]</code> patterns</td>
+</tr>
+<tr>
+<td>Base encoding</td>
+<td>simple fonts</td>
+<td><code>WinAnsiEncoding</code> (CP-1252) or <code>MacRomanEncoding</code> tables</td>
+</tr>
+<tr>
+<td>Fallback</td>
+<td>no <code>/Encoding</code> at all</td>
+<td>WinAnsi heuristic (covers pdfnative&#39;s own base-14 output and most western PDFs)</td>
+</tr>
+<tr>
+<td>No mapping anywhere</td>
+<td>—</td>
+<td>U+FFFD <code>�</code> per code</td>
+</tr>
+</tbody></table>
+<p>Type0 (CID) fonts are decoded as 2-byte codes (<code>Identity-H</code>/<code>Identity-V</code>),
+mapped through their <code>/ToUnicode</code> CMap — which pdfnative&#39;s own CIDFont
+output always embeds, so <strong>pdfnative-generated documents round-trip
+losslessly</strong>, including CJK, Arabic, and emoji.</p>
+<p>Since pdfnative <strong>1.7.0</strong> the <code>/ToUnicode</code> coverage is complete across both
+builders: base-14 font dictionaries are reached under tagged mode and the
+AcroForm <code>/Helv</code> dictionary carries a CMap in every mode — so base-14 text in
+tagged documents and <strong>text typed into form fields</strong> now extract cleanly too.</p>
+<h2 id="reading-order-and-runs">Reading order and runs<a class="heading-anchor" href="#reading-order-and-runs" aria-label="Link to this section">#</a></h2>
+<p><code>page.text</code> is assembled geometrically: runs are grouped into lines by
+baseline (tolerance scales with font size), lines are sorted top→bottom,
+runs within a line left→right, and a space is inserted where a visible
+horizontal gap separates two runs. Large negative <code>TJ</code> kerning
+adjustments (≤ −180/1000 em) are treated as word spaces.</p>
+<p><code>page.runs</code> (opt-in) preserves <strong>content-stream order</strong> — useful when you
+need the emitter&#39;s sequence rather than the geometric one. Positions are
+device-space points: <code>Tm × CTM</code> is tracked through <code>q</code>/<code>Q</code>/<code>cm</code>, so
+rotated and scaled content reports its true placement. Text inside Form
+XObjects is extracted too (<code>Do</code> recursion, depth-capped).</p>
+<h2 id="encrypted-documents">Encrypted documents<a class="heading-anchor" href="#encrypted-documents" aria-label="Link to this section">#</a></h2>
+<p><code>extractText</code> rides on <code>openPdf</code>: RC4, AES-128 and AES-256 documents
+decrypt transparently with <code>options.password</code>. A missing or wrong
+password throws <code>PdfPasswordError</code>; a document with an empty user
+password opens without one.</p>
+<h2 id="safety-bounds">Safety bounds<a class="heading-anchor" href="#safety-bounds" aria-label="Link to this section">#</a></h2>
+<p>Designed to be safe on untrusted input:</p>
+<ul>
+<li><code>maxTextLength</code> (default 16 M characters) hard-caps the total output —
+exceeding it throws rather than exhausting memory.</li>
+<li>Decompressed stream sizes are bounded by the parser&#39;s global inflate
+cap (<code>setMaxInflateOutputSize</code>).</li>
+<li>The interpreter is recursion-free with capped stacks (graphics state,
+operands, CMap entries, Form-XObject depth) and never throws on
+malformed content streams — unknown operators are skipped, unbalanced
+<code>BT</code>/<code>q</code> tolerated, inline images (<code>BI…EI</code>) byte-skipped.</li>
+</ul>
+<h2 id="limitations">Limitations<a class="heading-anchor" href="#limitations" aria-label="Link to this section">#</a></h2>
+<p>By design (documented, not bugs):</p>
+<ul>
+<li><strong>No OCR</strong> — image-only/scanned pages yield empty text.</li>
+<li>Type3 fonts are decoded via their encoding/<code>ToUnicode</code> only (glyph
+procedures are not interpreted).</li>
+<li>Non-Identity CMap <code>/Encoding</code>s (e.g. predefined UTF-16 CJK CMaps) are
+decoded best-effort as 2-byte codes through <code>/ToUnicode</code>.</li>
+<li>Vertical writing mode is treated as horizontal.</li>
+<li>The structure tree / <code>/ActualText</code> is not consulted — order is
+geometric, and ligature reversal is only as good as the embedded
+<code>/ToUnicode</code>. In practice this means <strong>shaped Indic scripts</strong>
+(Devanagari, Bengali, Tamil, Telugu, Sinhala, …) extract with U+FFFD
+for conjunct/ligature glyphs that have no single-codepoint mapping —
+the PDF <em>renders</em> correctly; only extraction of those clusters is
+lossy. Latin, CJK, Arabic and emoji round-trip cleanly.</li>
+</ul>
+<h2 id="samples">Samples<a class="heading-anchor" href="#samples" aria-label="Link to this section">#</a></h2>
+<p>Generated by <code>npm run test:generate</code>:</p>
+<ul>
+<li><code>parser/text-extract-source.pdf</code> — a rich source document.</li>
+<li><code>parser/text-extract-report.pdf</code> — its extraction rendered back to PDF
+(text + positioned-run table).</li>
+<li><code>parser/text-extract-encrypted-report.pdf</code> — AES-256 encrypted source,
+extracted with a password.</li>
+</ul>
+<h2 id="see-also">See also<a class="heading-anchor" href="#see-also" aria-label="Link to this section">#</a></h2>
+<ul>
+<li><a href="pdf-manipulation.html">PDF manipulation</a> — merge / split / extract pages.</li>
+<li><a href="form-filling.html">Form filling</a> — read and fill AcroForm fields.</li>
+<li><a href="debugging.html">Debugging &amp; layout inspection</a> — geometry the writer
+side reports.</li>
+</ul>
+<!-- guide:render:end -->
   </article>
 </main>
 
diff --git a/docs/guides/text-extraction.md b/docs/guides/text-extraction.md
index f6b2065..bda5568 100644
--- a/docs/guides/text-extraction.md
+++ b/docs/guides/text-extraction.md
@@ -72,6 +72,11 @@ mapped through their `/ToUnicode` CMap — which pdfnative's own CIDFont
 output always embeds, so **pdfnative-generated documents round-trip
 losslessly**, including CJK, Arabic, and emoji.
 
+Since pdfnative **1.7.0** the `/ToUnicode` coverage is complete across both
+builders: base-14 font dictionaries are reached under tagged mode and the
+AcroForm `/Helv` dictionary carries a CMap in every mode — so base-14 text in
+tagged documents and **text typed into form fields** now extract cleanly too.
+
 ## Reading order and runs
 
 `page.text` is assembled geometrically: runs are grouped into lines by
diff --git a/docs/guides/troubleshooting.html b/docs/guides/troubleshooting.html
index 7787f7b..b419eb2 100644
--- a/docs/guides/troubleshooting.html
+++ b/docs/guides/troubleshooting.html
@@ -9,6 +9,7 @@
   <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/troubleshooting.html">
   <link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/troubleshooting.html">
   <link rel="alternate" type="text/markdown" href="troubleshooting.md">
+  <link rel="alternate" type="text/plain" href="../llms.txt" title="llms.txt — machine-readable documentation index">
   <meta property="og:type" content="article">
   <meta property="og:site_name" content="pdfnative">
   <meta property="og:locale" content="en_US">
@@ -26,6 +27,9 @@
   <link rel="stylesheet" href="../style.css">
   <link rel="stylesheet" href="guide.css">
   <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
+  <!-- guide:ld:start -->
+  <script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://pdfnative.dev/"},{"@type":"ListItem","position":2,"name":"Guides","item":"https://pdfnative.dev/guides/"},{"@type":"ListItem","position":3,"name":"Troubleshooting","item":"https://pdfnative.dev/guides/troubleshooting.html"}]},{"@type":"TechArticle","headline":"Troubleshooting","description":"Common pdfnative issues and fixes — missing glyphs and font registration, PDF/A conformance, encryption, BiDi/RTL, browser usage, and signature validation.","inLanguage":"en","author":{"@type":"Organization","name":"Nizoka","url":"https://github.com/Nizoka"},"publisher":{"@type":"Organization","name":"pdfnative","url":"https://pdfnative.dev","logo":{"@type":"ImageObject","url":"https://pdfnative.dev/assets/logo.svg"}},"mainEntityOfPage":{"@type":"WebPage","@id":"https://pdfnative.dev/guides/troubleshooting.html"},"isPartOf":{"@type":"WebSite","name":"pdfnative","url":"https://pdfnative.dev"}}]}</script>
+  <!-- guide:ld:end -->
 </head>
 <body>
 
@@ -57,9 +61,117 @@
 
 <main class="guide-shell" id="main-content" tabindex="-1">
   <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; Troubleshooting</p>
-  <article id="guide-content" class="guide-content" data-md="troubleshooting.md">
-    <p class="guide-loading">Loading…</p>
-    <noscript><p>This guide is written in Markdown: <a href="troubleshooting.md">read troubleshooting.md</a>.</p></noscript>
+  <article id="guide-content" class="guide-content" data-md="troubleshooting.md" data-prerendered="true">
+<!-- guide:render:start -->
+<h1 id="troubleshooting">Troubleshooting</h1>
+<blockquote>
+<p><strong>Symptom-first fixes for the classic failures</strong> — tofu boxes (a font registered but never loaded), RTL text appearing backwards, oversized files, PDF/A validation errors, parser rejections — each with the check that identifies it and the change that fixes it.</p>
+</blockquote>
+<h2 id="font-not-rendering-boxes-or-blank">Font Not Rendering (Boxes or Blank)<a class="heading-anchor" href="#font-not-rendering-boxes-or-blank" aria-label="Link to this section">#</a></h2>
+<p><strong>Symptom:</strong> Non-Latin text shows as empty rectangles or missing glyphs.</p>
+<p><strong>Cause:</strong> The font for that script is not registered or not loaded.</p>
+<p><strong>Fix:</strong></p>
+<pre><code class="language-typescript">import { registerFonts, loadFontData } from &#39;pdfnative&#39;;
+
+// 1. Register font loaders (lazy — no data loaded yet)
+registerFonts({
+  th: () =&gt; import(&#39;pdfnative/fonts/noto-thai-data.js&#39;),
+  ar: () =&gt; import(&#39;pdfnative/fonts/noto-arabic-data.js&#39;),
+});
+
+// 2. Load font data when needed
+const thaiFont = await loadFontData(&#39;th&#39;);
+
+// 3. Pass fontEntries to your builder
+const pdf = buildDocumentPDFBytes({
+  blocks: [{ type: &#39;paragraph&#39;, text: &#39;สวัสดี&#39; }],
+  fontEntries: [{ fontData: thaiFont!, fontRef: &#39;/F3&#39;, lang: &#39;th&#39; }],
+});
+</code></pre>
+<h2 id="pdf-file-too-large">PDF File Too Large<a class="heading-anchor" href="#pdf-file-too-large" aria-label="Link to this section">#</a></h2>
+<p><strong>Symptom:</strong> Output PDF is unexpectedly large (&gt;1 MB for text content).</p>
+<p><strong>Causes &amp; fixes:</strong></p>
+<ol>
+<li><p><strong>Enable compression:</strong></p>
+<pre><code class="language-typescript">buildPDFBytes(params, { compress: true });
+</code></pre>
+<p>FlateDecode typically reduces size by 50–90%.</p>
+</li>
+<li><p><strong>Initialize native compression (Node.js):</strong></p>
+<pre><code class="language-typescript">import { initNodeCompression } from &#39;pdfnative&#39;;
+await initNodeCompression();
+</code></pre>
+<p>Without this, a stored-block fallback is used (minimal compression).</p>
+</li>
+<li><p><strong>Large images:</strong> JPEG is already compressed (DCTDecode). For PNG, the raw pixels are FlateDecode-compressed. Use JPEG for photos.</p>
+</li>
+<li><p><strong>Font subsetting:</strong> Automatic — only used glyphs are embedded. If you&#39;re embedding many scripts, each adds a font subset.</p>
+</li>
+</ol>
+<h2 id="rtl-text-backwards">RTL Text Backwards<a class="heading-anchor" href="#rtl-text-backwards" aria-label="Link to this section">#</a></h2>
+<p><strong>Symptom:</strong> Arabic or Hebrew text appears in logical order instead of visual (right-to-left) order.</p>
+<p><strong>Cause:</strong> Font entries must include the correct <code>lang</code> property for BiDi detection.</p>
+<p><strong>Fix:</strong></p>
+<pre><code class="language-typescript">const fontEntries = [
+  { fontData: arabicFont, fontRef: &#39;/F3&#39;, lang: &#39;ar&#39; },
+  { fontData: hebrewFont, fontRef: &#39;/F4&#39;, lang: &#39;he&#39; },
+];
+</code></pre>
+<p>The <code>lang</code> property triggers:</p>
+<ul>
+<li>BiDi run detection (<code>containsRTL()</code>)</li>
+<li>Arabic positional shaping (GSUB forms)</li>
+<li>Glyph mirroring for brackets and other paired delimiters (the full 428-pair
+Unicode BidiMirroring table since v1.7.0, per UAX #9 rule L4)</li>
+</ul>
+<p><strong>Reversed digits or backwards parentheses in RTL text?</strong> Fixed in v1.7.0 with
+no API change: digit runs now take even embedding levels (UAX #9 rules I1/I2),
+so a number like <code>1405</code> keeps its digit order instead of rendering <code>5041</code>, and
+rule L4 mirrors delimiters during reversal, so a logical <code>(X)</code> no longer
+renders <code>)X(</code>. If you see either symptom, upgrade pdfnative.</p>
+<h2 id="pdfa-validation-fails">PDF/A Validation Fails<a class="heading-anchor" href="#pdfa-validation-fails" aria-label="Link to this section">#</a></h2>
+<p><strong>Symptom:</strong> veraPDF reports non-conformance.</p>
+<p><strong>Common issues:</strong></p>
+<ol>
+<li><p><strong>Missing tagged mode:</strong></p>
+<pre><code class="language-typescript">buildPDFBytes(params, { tagged: true }); // PDF/A-2b
+// or
+buildPDFBytes(params, { tagged: &#39;pdfa1b&#39; }); // PDF/A-1b
+</code></pre>
+</li>
+<li><p><strong>PDF/A + encryption conflict:</strong> ISO 19005-1 §6.3.2 forbids encryption in PDF/A. Use one or the other.</p>
+</li>
+<li><p><strong>Transparency in PDF/A-1b:</strong> Watermarks with opacity &lt; 1.0 are blocked in PDF/A-1b (ISO 19005-1 §6.4). Use PDF/A-2b or remove transparency.</p>
+</li>
+</ol>
+<h2 id="document-has-too-many-blocks--very-large-documents">&quot;Document has too many blocks&quot; / Very Large Documents<a class="heading-anchor" href="#document-has-too-many-blocks--very-large-documents" aria-label="Link to this section">#</a></h2>
+<p><strong>Symptom:</strong> Generating a multi-thousand-page report throws a &quot;too many blocks&quot; error.</p>
+<p><strong>Cause:</strong> The document builder caps the number of content blocks as a safety rail. Before v1.3.0 this was a hard-coded 10 000. As of <strong>v1.3.0</strong> the default is <strong>100 000</strong> and is configurable.</p>
+<p><strong>Fix:</strong> raise the limit via the layout option:</p>
+<pre><code class="language-typescript">buildDocumentPDFBytes(params, { maxBlocks: 500000 });
+// also honoured by the streaming builders:
+buildDocumentPDFStream(params, { maxBlocks: 500000 }, { chunkSize: 65536 });
+</code></pre>
+<p>For very large outputs, prefer the streaming builders (<code>buildDocumentPDFStream</code>, or <code>buildDocumentPDFStreamTrue</code> for constant memory) so the full binary never has to sit in memory at once.</p>
+<h2 id="parser-fails-on-external-pdf">Parser Fails on External PDF<a class="heading-anchor" href="#parser-fails-on-external-pdf" aria-label="Link to this section">#</a></h2>
+<p><strong>Symptom:</strong> <code>openPdf()</code> throws on a PDF file not generated by pdfnative.</p>
+<p><strong>Common causes:</strong></p>
+<ol>
+<li><strong>Encrypted PDF opened without a password:</strong> Since v1.6.0 the parser decrypts the Standard Security Handler (RC4 V1-V4, AES-128, AES-256 R6) — but it needs the password. Call <code>openPdf(bytes, { password })</code>. Without one you get <code>PdfPasswordError</code>; with an algorithm the handler does not cover, <code>PdfEncryptionUnsupportedError</code>.</li>
+<li><strong>Linearized PDF:</strong> The parser follows standard xref/trailer. Linearized hint tables may cause offset issues.</li>
+<li><strong>Non-standard formatting:</strong> Some PDF generators produce non-compliant output. The parser follows ISO 32000-1 strictly.</li>
+</ol>
+<h2 id="build--import-issues">Build / Import Issues<a class="heading-anchor" href="#build--import-issues" aria-label="Link to this section">#</a></h2>
+<p><strong>ESM import paths:</strong></p>
+<pre><code class="language-typescript">// Bare package import — no extension involved
+import { buildPDFBytes } from &#39;pdfnative&#39;;
+
+// Font data modules — the .js extension IS required here (ESM subpath),
+// and the modules only have named exports, so use a namespace import:
+import * as thaiData from &#39;pdfnative/fonts/noto-thai-data.js&#39;;
+</code></pre>
+<p><strong>Browser vs Node.js:</strong> The library works in both environments. For compression in Node.js, call <code>initNodeCompression()</code> once at startup.</p>
+<!-- guide:render:end -->
   </article>
 </main>
 
diff --git a/docs/guides/troubleshooting.md b/docs/guides/troubleshooting.md
index c4df741..51a8867 100644
--- a/docs/guides/troubleshooting.md
+++ b/docs/guides/troubleshooting.md
@@ -1,4 +1,6 @@
 # Troubleshooting
+
+> **Symptom-first fixes for the classic failures** — tofu boxes (a font registered but never loaded), RTL text appearing backwards, oversized files, PDF/A validation errors, parser rejections — each with the check that identifies it and the change that fixes it.
 
 ## Font Not Rendering (Boxes or Blank)
 
diff --git a/docs/guides/viewer-preferences.html b/docs/guides/viewer-preferences.html
index c02203a..7ea0aa6 100644
--- a/docs/guides/viewer-preferences.html
+++ b/docs/guides/viewer-preferences.html
@@ -1,85 +1,256 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>Viewer preferences — pdfnative</title>
-  <meta name="description" content="Control how a PDF reader presents your document on open with pdfnative — initial page layout, page mode, full-screen kiosk, fit/centre window, reading direction, print scaling. New in v1.4.0.">
-  <link rel="canonical" href="https://pdfnative.dev/guides/viewer-preferences.html">
-  <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/viewer-preferences.html">
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Viewer preferences — pdfnative</title>
+  <meta name="description" content="Control how a PDF reader presents your document on open with pdfnative — initial page layout, page mode, full-screen kiosk, fit/centre window, reading direction, print scaling. New in v1.4.0.">
+  <link rel="canonical" href="https://pdfnative.dev/guides/viewer-preferences.html">
+  <link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/viewer-preferences.html">
   <link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/viewer-preferences.html">
-  <link rel="alternate" type="text/markdown" href="viewer-preferences.md">
-  <meta property="og:type" content="article">
-  <meta property="og:site_name" content="pdfnative">
+  <link rel="alternate" type="text/markdown" href="viewer-preferences.md">
+  <link rel="alternate" type="text/plain" href="../llms.txt" title="llms.txt — machine-readable documentation index">
+  <meta property="og:type" content="article">
+  <meta property="og:site_name" content="pdfnative">
   <meta property="og:locale" content="en_US">
-  <meta property="og:url" content="https://pdfnative.dev/guides/viewer-preferences.html">
-  <meta property="og:title" content="Viewer preferences — pdfnative">
-  <meta property="og:description" content="Control how a PDF reader presents your document on open — page layout, page mode, kiosk, window fit, reading direction. New in v1.4.0.">
-  <meta property="og:image" content="https://pdfnative.dev/assets/og-image.png">
-  <meta property="og:image:width" content="1200">
-  <meta property="og:image:height" content="630">
-  <meta name="twitter:card" content="summary_large_image">
-  <meta name="twitter:title" content="Viewer preferences — pdfnative">
-  <meta name="twitter:description" content="Initial page layout, page mode, full-screen kiosk, fit/centre window, reading direction, print scaling.">
-  <meta name="twitter:image" content="https://pdfnative.dev/assets/og-image.png">
-  <link rel="icon" type="image/svg+xml" href="../favicon.svg">
-  <link rel="stylesheet" href="../style.css">
-  <link rel="stylesheet" href="guide.css">
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
-</head>
-<body>
-
-<a class="skip-link" href="#main-content">Skip to main content</a>
-
-<nav class="nav" role="navigation" aria-label="Main navigation">
-  <div class="nav-inner">
-    <a class="nav-brand" href="../">
-      <img src="../assets/logo.svg" alt="" width="28" height="28">
-      pdfnative
-    </a>
-    <button class="nav-hamburger" aria-label="Toggle menu" aria-expanded="false">☰</button>
-    <ul class="nav-links" role="list">
-      <li><a href="../#features">Features</a></li>
-      <li><a href="../#examples">Examples</a></li>
-      <li><a href="../#demo">Demo</a></li>
-      <li><a href="../#mcp">MCP</a></li>
-      <li><a href="../#cli">CLI</a></li>
-      <li><a href="../#react">React</a></li>
-      <li><a href="../learn/">Learn</a></li>
-      <li><a href="./">Guides</a></li>
-      <li><a href="../playgrounds/">Playgrounds</a></li>
-      <li><a href="../responsibility.html">Responsibility</a></li>
-      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
-      <li><button class="theme-toggle" aria-label="Toggle dark mode">🌙</button></li>
-    </ul>
-  </div>
-</nav>
-
-<main class="guide-shell" id="main-content" tabindex="-1">
-  <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; Viewer preferences</p>
-  <article id="guide-content" class="guide-content" data-md="viewer-preferences.md">
-    <p class="guide-loading">Loading…</p>
-    <noscript><p>This guide is written in Markdown: <a href="viewer-preferences.md">read viewer-preferences.md</a>.</p></noscript>
-  </article>
-</main>
-
-<footer class="footer">
-  <div class="footer-inner">
-    <span>MIT License · © 2026 Nizoka</span>
-    <ul class="footer-links" role="list">
-      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
-      <li><a href="https://www.npmjs.com/package/pdfnative" target="_blank" rel="noopener">npm</a></li>
-      <li><a href="https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md" target="_blank" rel="noopener">Changelog</a></li>
-      <li><a href="./">All guides</a></li>
-    </ul>
-  </div>
-</footer>
-
-<script src="https://cdn.jsdelivr.net/npm/marked@12.0.2/marked.min.js" integrity="sha384-/TQbtLCAerC3jgaim+N78RZSDYV7ryeoBCVqTuzRrFec2akfBkHS7ACQ3PQhvMVi" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/dompurify@3.1.5/dist/purify.min.js" integrity="sha384-nszIONF2FGC59kn+pPFaRa6WUNGwsZgXZiJxJwQbym+TzcH7smolUviLgpPbNx7V" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/prism.min.js" integrity="sha384-BGaNxfftg+9+TtC098wxawPFVEUpKYvaiCgbB0iqAMjK/4jDdmUY+oGxrPNvnXEf" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-typescript.min.js" integrity="sha384-PeOqKNW/piETaCg8rqKFy+Pm6KEk7e36/5YZE5XO/OaFdO+/Aw3O8qZ9qDPKVUgx" crossorigin="anonymous" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-bash.min.js" integrity="sha384-9WmlN8ABpoFSSHvBGGjhvB3E/D8UkNB9HpLJjBQFC2VSQsM1odiQDv4NbEo+7l15" crossorigin="anonymous" defer></script>
-<script src="guide.js" defer></script>
-</body>
-</html>
+  <meta property="og:url" content="https://pdfnative.dev/guides/viewer-preferences.html">
+  <meta property="og:title" content="Viewer preferences — pdfnative">
+  <meta property="og:description" content="Control how a PDF reader presents your document on open — page layout, page mode, kiosk, window fit, reading direction. New in v1.4.0.">
+  <meta property="og:image" content="https://pdfnative.dev/assets/og-image.png">
+  <meta property="og:image:width" content="1200">
+  <meta property="og:image:height" content="630">
+  <meta name="twitter:card" content="summary_large_image">
+  <meta name="twitter:title" content="Viewer preferences — pdfnative">
+  <meta name="twitter:description" content="Initial page layout, page mode, full-screen kiosk, fit/centre window, reading direction, print scaling.">
+  <meta name="twitter:image" content="https://pdfnative.dev/assets/og-image.png">
+  <link rel="icon" type="image/svg+xml" href="../favicon.svg">
+  <link rel="stylesheet" href="../style.css">
+  <link rel="stylesheet" href="guide.css">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
+  <!-- guide:ld:start -->
+  <script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://pdfnative.dev/"},{"@type":"ListItem","position":2,"name":"Guides","item":"https://pdfnative.dev/guides/"},{"@type":"ListItem","position":3,"name":"Viewer preferences","item":"https://pdfnative.dev/guides/viewer-preferences.html"}]},{"@type":"TechArticle","headline":"Viewer preferences","description":"Control how a PDF reader presents your document on open with pdfnative — initial page layout, page mode, full-screen kiosk, fit/centre window, reading direction, print scaling. New in v1.4.0.","inLanguage":"en","author":{"@type":"Organization","name":"Nizoka","url":"https://github.com/Nizoka"},"publisher":{"@type":"Organization","name":"pdfnative","url":"https://pdfnative.dev","logo":{"@type":"ImageObject","url":"https://pdfnative.dev/assets/logo.svg"}},"mainEntityOfPage":{"@type":"WebPage","@id":"https://pdfnative.dev/guides/viewer-preferences.html"},"isPartOf":{"@type":"WebSite","name":"pdfnative","url":"https://pdfnative.dev"}}]}</script>
+  <!-- guide:ld:end -->
+</head>
+<body>
+
+<a class="skip-link" href="#main-content">Skip to main content</a>
+
+<nav class="nav" role="navigation" aria-label="Main navigation">
+  <div class="nav-inner">
+    <a class="nav-brand" href="../">
+      <img src="../assets/logo.svg" alt="" width="28" height="28">
+      pdfnative
+    </a>
+    <button class="nav-hamburger" aria-label="Toggle menu" aria-expanded="false">☰</button>
+    <ul class="nav-links" role="list">
+      <li><a href="../#features">Features</a></li>
+      <li><a href="../#examples">Examples</a></li>
+      <li><a href="../#demo">Demo</a></li>
+      <li><a href="../#mcp">MCP</a></li>
+      <li><a href="../#cli">CLI</a></li>
+      <li><a href="../#react">React</a></li>
+      <li><a href="../learn/">Learn</a></li>
+      <li><a href="./">Guides</a></li>
+      <li><a href="../playgrounds/">Playgrounds</a></li>
+      <li><a href="../responsibility.html">Responsibility</a></li>
+      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
+      <li><button class="theme-toggle" aria-label="Toggle dark mode">🌙</button></li>
+    </ul>
+  </div>
+</nav>
+
+<main class="guide-shell" id="main-content" tabindex="-1">
+  <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Guides</a> &nbsp;›&nbsp; Viewer preferences</p>
+  <article id="guide-content" class="guide-content" data-md="viewer-preferences.md" data-prerendered="true">
+<!-- guide:render:start -->
+<h1 id="viewer-preferences">Viewer preferences</h1>
+<blockquote>
+<p><strong>New in v1.4.0.</strong> Control how a conforming reader <strong>presents</strong> your PDF the
+moment it opens — initial page layout, the bookmark/thumbnail panel, full-screen
+kiosk mode, window fit/centering, UI-chrome visibility, reading direction, and
+print scaling. Set via <code>DocumentParams.layout.viewerPreferences</code>. Purely
+presentational, PDF/A-safe, and zero overhead when unused.</p>
+</blockquote>
+<h2 id="tldr">TL;DR<a class="heading-anchor" href="#tldr" aria-label="Link to this section">#</a></h2>
+<pre><code class="language-ts">import { buildDocumentPDFBytes } from &#39;pdfnative&#39;;
+import type { ViewerPreferences } from &#39;pdfnative&#39;;
+
+const viewerPreferences: ViewerPreferences = {
+  pageLayout: &#39;twoColumnLeft&#39;,  // continuous two-up, odd pages left
+  pageMode: &#39;useOutlines&#39;,      // open the bookmark panel
+  displayDocTitle: true,        // titlebar shows /Info /Title, not the filename
+  fitWindow: true,
+  centerWindow: true,
+};
+
+const bytes = buildDocumentPDFBytes({
+  title: &#39;Annual Report&#39;,
+  blocks: [/* … */],
+  outline: &#39;auto&#39;,
+  layout: { viewerPreferences },
+});
+</code></pre>
+<h2 id="page-layout-pagelayout">Page layout (<code>/PageLayout</code>)<a class="heading-anchor" href="#page-layout-pagelayout" aria-label="Link to this section">#</a></h2>
+<p>How pages are arranged in the viewport:</p>
+<table>
+<thead>
+<tr>
+<th>Value</th>
+<th>Behaviour</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>singlePage</code></td>
+<td>One page at a time</td>
+</tr>
+<tr>
+<td><code>oneColumn</code></td>
+<td>Continuous single column</td>
+</tr>
+<tr>
+<td><code>twoColumnLeft</code> / <code>twoColumnRight</code></td>
+<td>Continuous two columns; odd pages on the left / right</td>
+</tr>
+<tr>
+<td><code>twoPageLeft</code> / <code>twoPageRight</code></td>
+<td>Two pages at a time; odd pages on the left / right</td>
+</tr>
+</tbody></table>
+<h2 id="page-mode-pagemode">Page mode (<code>/PageMode</code>)<a class="heading-anchor" href="#page-mode-pagemode" aria-label="Link to this section">#</a></h2>
+<p>Which panel (if any) is open and whether the document opens full-screen:</p>
+<table>
+<thead>
+<tr>
+<th>Value</th>
+<th>Behaviour</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>useNone</code></td>
+<td>Neither bookmarks nor thumbnails</td>
+</tr>
+<tr>
+<td><code>useOutlines</code></td>
+<td>Bookmark panel open</td>
+</tr>
+<tr>
+<td><code>useThumbs</code></td>
+<td>Thumbnail panel open</td>
+</tr>
+<tr>
+<td><code>fullScreen</code></td>
+<td>Full-screen presentation, no menu/panel</td>
+</tr>
+<tr>
+<td><code>useOC</code></td>
+<td>Optional-content (layers) panel</td>
+</tr>
+<tr>
+<td><code>useAttachments</code></td>
+<td>Attachments panel</td>
+</tr>
+</tbody></table>
+<p>An explicit <code>pageMode</code> <strong>overrides</strong> the <code>/UseOutlines</code> default that a document
+automatically gets when it has an <code>outline</code>.</p>
+<h2 id="viewerpreferences-flags">ViewerPreferences flags<a class="heading-anchor" href="#viewerpreferences-flags" aria-label="Link to this section">#</a></h2>
+<table>
+<thead>
+<tr>
+<th>Field</th>
+<th>Effect</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>hideToolbar</code></td>
+<td>Hide the reader tool bars</td>
+</tr>
+<tr>
+<td><code>hideMenubar</code></td>
+<td>Hide the menu bar</td>
+</tr>
+<tr>
+<td><code>hideWindowUI</code></td>
+<td>Hide scrollbars / navigation, leaving only the page</td>
+</tr>
+<tr>
+<td><code>fitWindow</code></td>
+<td>Resize the window to the first page</td>
+</tr>
+<tr>
+<td><code>centerWindow</code></td>
+<td>Centre the window on screen</td>
+</tr>
+<tr>
+<td><code>displayDocTitle</code></td>
+<td>Show <code>/Info /Title</code> in the titlebar instead of the filename</td>
+</tr>
+<tr>
+<td><code>nonFullScreenPageMode</code></td>
+<td>Mode to use after exiting full-screen</td>
+</tr>
+<tr>
+<td><code>direction</code></td>
+<td><code>&#39;l2r&#39;</code> (default) or <code>&#39;r2l&#39;</code> reading order</td>
+</tr>
+<tr>
+<td><code>printScaling</code></td>
+<td><code>&#39;none&#39;</code> or <code>&#39;appDefault&#39;</code> print-dialog default</td>
+</tr>
+<tr>
+<td><code>duplex</code></td>
+<td><code>&#39;simplex&#39;</code>, <code>&#39;duplexFlipShortEdge&#39;</code> or <code>&#39;duplexFlipLongEdge&#39;</code> print-dialog default (v1.7.0)</td>
+</tr>
+<tr>
+<td><code>pickTrayByPDFSize</code></td>
+<td>Select the paper tray from the PDF page size (v1.7.0)</td>
+</tr>
+<tr>
+<td><code>printPageRange</code></td>
+<td>Default print range as 1-based <code>[from, to]</code> pairs (v1.7.0)</td>
+</tr>
+<tr>
+<td><code>numCopies</code></td>
+<td>Default copy count in the print dialog (v1.7.0)</td>
+</tr>
+</tbody></table>
+<p>The four print-dialog defaults ship with v1.7.0&#39;s print-production support —
+see the <a href="print.html">print production guide</a> for bleed/trim boxes, printer&#39;s
+marks and <code>/Trapped</code>.</p>
+<h2 id="full-screen-kiosk">Full-screen kiosk<a class="heading-anchor" href="#full-screen-kiosk" aria-label="Link to this section">#</a></h2>
+<pre><code class="language-ts">const viewerPreferences: ViewerPreferences = {
+  pageMode: &#39;fullScreen&#39;,
+  nonFullScreenPageMode: &#39;useThumbs&#39;,
+  hideToolbar: true,
+  hideMenubar: true,
+  direction: &#39;r2l&#39;,
+  printScaling: &#39;none&#39;,
+};
+</code></pre>
+<h2 id="pdfa-note">PDF/A note<a class="heading-anchor" href="#pdfa-note" aria-label="Link to this section">#</a></h2>
+<p>Viewer preferences are metadata only — no transparency, no scripting — so they
+are safe to combine with any PDF/A conformance level. Sample generators:
+<a href="https://github.com/Nizoka/pdfnative/blob/main/scripts/generators/viewer-prefs-showcase.ts" target="_blank" rel="noopener">viewer-prefs-showcase.ts</a>.</p>
+<!-- guide:render:end -->
+  </article>
+</main>
+
+<footer class="footer">
+  <div class="footer-inner">
+    <span>MIT License · © 2026 Nizoka</span>
+    <ul class="footer-links" role="list">
+      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
+      <li><a href="https://www.npmjs.com/package/pdfnative" target="_blank" rel="noopener">npm</a></li>
+      <li><a href="https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md" target="_blank" rel="noopener">Changelog</a></li>
+      <li><a href="./">All guides</a></li>
+    </ul>
+  </div>
+</footer>
+
+<script src="https://cdn.jsdelivr.net/npm/marked@12.0.2/marked.min.js" integrity="sha384-/TQbtLCAerC3jgaim+N78RZSDYV7ryeoBCVqTuzRrFec2akfBkHS7ACQ3PQhvMVi" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/dompurify@3.1.5/dist/purify.min.js" integrity="sha384-nszIONF2FGC59kn+pPFaRa6WUNGwsZgXZiJxJwQbym+TzcH7smolUviLgpPbNx7V" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/prism.min.js" integrity="sha384-BGaNxfftg+9+TtC098wxawPFVEUpKYvaiCgbB0iqAMjK/4jDdmUY+oGxrPNvnXEf" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-typescript.min.js" integrity="sha384-PeOqKNW/piETaCg8rqKFy+Pm6KEk7e36/5YZE5XO/OaFdO+/Aw3O8qZ9qDPKVUgx" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-bash.min.js" integrity="sha384-9WmlN8ABpoFSSHvBGGjhvB3E/D8UkNB9HpLJjBQFC2VSQsM1odiQDv4NbEo+7l15" crossorigin="anonymous" defer></script>
+<script src="guide.js" defer></script>
+</body>
+</html>
diff --git a/docs/index.html b/docs/index.html
index f9255bc..4ca85d2 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -5,7 +5,7 @@
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>pdfnative — Zero-dependency PDF generation for TypeScript</title>
   <meta name="description" content="Zero-dependency PDF library for TypeScript: generate, parse, extract text, fill forms, encrypt & decrypt. ISO 32000-1, PDF/A, AES-128/256, PAdES signatures with long-term validation (LTV, RSA + ECDSA), 22 Unicode scripts, BiDi, native charts, barcodes, SVG, streaming. CLI + MCP server included.">
-  <meta name="keywords" content="pdf, typescript, javascript, pdf generation, pdf parser, text extraction, extract text from pdf, fill pdf form, flatten pdf, decrypt pdf, encrypt pdf, pdf charts, zero dependencies, unicode, arabic, thai, hebrew, bidi, pdf-a, tagged-pdf, pades, acroform, accessibility, encryption, aes, rsa, ecdsa, cms, pkcs7, rfc-3161, digital-signatures, sign pdf, ltv, long-term validation, document timestamp, rtl, persian, barcodes, qr-code, svg, opentype, emoji, noto, cjk, mcp, model-context-protocol, claude, cursor, ai, llm, react, jsx, react-pdf, pdfnative-cli, pdfnative-mcp, pdfnative-react">
+  <meta name="keywords" content="pdf, typescript, javascript, pdf generation, pdf parser, text extraction, extract text from pdf, fill pdf form, flatten pdf, decrypt pdf, encrypt pdf, pdf charts, zero dependencies, unicode, arabic, thai, hebrew, bidi, pdf-a, tagged-pdf, pades, acroform, accessibility, encryption, aes, rsa, ecdsa, cms, pkcs7, rfc-3161, digital-signatures, sign pdf, ltv, long-term validation, document timestamp, ocsp, crl, rtl, persian, barcodes, qr-code, svg, opentype, emoji, noto, cjk, mcp, model-context-protocol, claude, cursor, ai, llm, react, jsx, react-pdf, pdfnative-cli, pdfnative-mcp, pdfnative-react">
   <meta name="author" content="Nizoka">
   <meta name="robots" content="index, follow, max-image-preview:large">
   <meta name="theme-color" content="#2563eb">
@@ -30,6 +30,7 @@
   <link rel="canonical" href="https://pdfnative.dev">
   <link rel="alternate" hreflang="en" href="https://pdfnative.dev">
   <link rel="alternate" hreflang="x-default" href="https://pdfnative.dev">
+  <link rel="alternate" type="text/plain" href="llms.txt" title="llms.txt — machine-readable documentation index">
   <link rel="icon" type="image/svg+xml" href="favicon.svg">
   <link rel="stylesheet" href="style.css">
 
@@ -72,7 +73,7 @@
         "@id": "https://pdfnative.dev/#library",
         "inLanguage": "en",
         "name": "pdfnative",
-        "description": "Pure native PDF library — no runtime dependencies in the engine, producing documents that conform to ISO 32000-1. Generate, parse, merge/split, extract text with positions, fill & flatten AcroForms, decrypt and re-encrypt (AES-128/256), PAdES digital signatures with long-term validation (LTV: RFC 3161 timestamps, /DSS, document timestamps), native vector charts (stacked, area, scatter, log & time axes).",
+        "description": "Pure native PDF library — no runtime dependencies in the engine, producing documents that conform to ISO 32000-1. Generate, parse, merge/split, extract text with positions, fill & flatten AcroForms, decrypt and re-encrypt (AES-128/256), PAdES digital signatures with long-term validation (LTV: RFC 3161 timestamps, /DSS, document timestamps), native vector charts (stacked, area, scatter, log & time axes), print production (page boxes, printer's marks, /Trapped, /UserUnit, custom OutputIntent).",
         "url": "https://pdfnative.dev",
         "codeRepository": "https://github.com/Nizoka/pdfnative",
         "programmingLanguage": "TypeScript",
@@ -103,9 +104,9 @@
         "@id": "https://pdfnative.dev/#mcp",
         "inLanguage": "en",
         "name": "pdfnative-mcp",
-        "description": "Model Context Protocol server exposing pdfnative to Claude Desktop, Cursor, Continue, Zed, and any stdio MCP client. 24 tools (incl. native vector add_chart, fill_form / read_form_fields, encrypt_pdf / decrypt_pdf, page-tree merge/split/extract, markup annotate_pdf, and the network-free draft_governance_issue), per-tool apiVersion, PDF/A flag.",
+        "description": "Model Context Protocol server exposing pdfnative to Claude Desktop, Cursor, Continue, Zed, and any MCP client. 28 tools (incl. the complete PAdES ladder sign_pdf / add_ltv / timestamp_pdf, update_metadata, the read-only inspect_layout preview, native vector add_chart, fill_form / read_form_fields, encrypt_pdf / decrypt_pdf, page-tree merge/split/extract, markup annotate_pdf, and the network-free draft_governance_issue), MCP 2026-07-28 spec, per-tool apiVersion, PDF/A flag.",
         "url": "https://github.com/Nizoka/pdfnative-mcp",
-        "softwareVersion": "1.5.0",
+        "softwareVersion": "1.6.0",
         "applicationCategory": "DeveloperApplication",
         "operatingSystem": "Cross-platform",
         "isAccessibleForFree": true,
@@ -211,7 +212,7 @@ <h1>Pure Native <span class="gradient">PDF Generation</span></h1>
 <!-- ═══════════════ Metrics Bar ═══════════════ -->
 <section class="metrics" aria-label="Key metrics">
   <div class="metric">
-    <div class="metric-value">2665+</div>
+    <div class="metric-value">2686+</div>
     <div class="metric-label">Tests</div>
   </div>
   <div class="metric">
@@ -252,7 +253,7 @@ <h3>Zero Dependencies</h3>
       <div class="feature-card">
         <div class="feature-icon fi-unicode"><svg width="28" height="28" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><line x1="2" y1="12" x2="22" y2="12"/><path d="M12 2a15.3 15.3 0 014 10 15.3 15.3 0 01-4 10 15.3 15.3 0 01-4-10 15.3 15.3 0 014-10z"/></svg></div>
         <h3>22 Unicode Scripts</h3>
-        <p>Thai, Arabic, Hebrew, Bengali, Tamil, Telugu, Sinhala, Tibetan, Khmer, Myanmar, Amharic, CJK, Cyrillic, Greek, Devanagari, and more. Full UAX #9 BiDi — isolates + explicit embeddings (LRE/RLE/LRO/RLO/PDF). OpenType GSUB/GPOS shaping for Thai, Arabic, Devanagari, Bengali, Tamil, Telugu, Sinhala, Tibetan, Khmer, and Myanmar.</p>
+        <p>Thai, Arabic, Hebrew, Bengali, Tamil, Telugu, Sinhala, Tibetan, Khmer, Myanmar, Amharic, CJK, Cyrillic, Greek, Devanagari, and more. Full UAX #9 BiDi — isolates + explicit embeddings (LRE/RLE/LRO/RLO/PDF). OpenType GSUB/GPOS shaping for Thai, Arabic, Devanagari, Bengali, Tamil, Telugu, Sinhala, Tibetan, Khmer, and Myanmar. Plus COLRv1 colour emoji — with 51 flag and 22 ZWJ sequences as single colour ligatures since v1.7.0. <a href="guides/colour-emoji.html">Emoji guide →</a></p>
       </div>
 
       <div class="feature-card">
@@ -270,19 +271,19 @@ <h3>Security Built-in</h3>
       <div class="feature-card">
         <div class="feature-icon fi-content"><svg width="28" height="28" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M14 2H6a2 2 0 00-2 2v16a2 2 0 002 2h12a2 2 0 002-2V8z"/><polyline points="14 2 14 8 20 8"/><line x1="16" y1="13" x2="8" y2="13"/><line x1="16" y1="17" x2="8" y2="17"/><polyline points="10 9 9 9 8 9"/></svg></div>
         <h3>Rich Content</h3>
-        <p>13 block types: tables, images, barcodes (5 ISO formats), native vector charts, SVG, AcroForm fields, TOC, watermarks, hyperlinks. Pure PDF vector ops — no rasterization. <strong>Smart tables</strong>: multi-page slicing with repeated headers, auto-wrap, zebra striping, captions, and per-cell borders. <strong>Document tools</strong>: bookmarks (<code>/Outlines</code>), page labels, viewer preferences, nested lists, and a <strong>merge / split / extract</strong> page-tree API. <a href="guides/tables.html">Tables guide →</a> &middot; <a href="guides/pdf-manipulation.html">Manipulation guide →</a></p>
+        <p>13 block types: tables, images, barcodes (5 ISO formats), native vector charts, SVG, AcroForm fields, TOC, watermarks, hyperlinks. Pure PDF vector ops — no rasterization. <strong>Smart tables</strong>: multi-page slicing with repeated headers, auto-wrap, zebra striping, captions, and per-cell borders. <strong>Document tools</strong>: bookmarks (<code>/Outlines</code>), page labels, viewer preferences, nested lists, and a <strong>merge / split / extract</strong> page-tree API. <strong>Print production</strong> (v1.7.0): bleed/trim/art/crop page boxes, crop &amp; registration marks, <code>/Trapped</code>, large-format <code>/UserUnit</code>, custom OutputIntent ICC. <a href="guides/tables.html">Tables guide →</a> &middot; <a href="guides/pdf-manipulation.html">Manipulation guide →</a> &middot; <a href="guides/print.html">Print guide →</a></p>
       </div>
 
       <div class="feature-card">
         <div class="feature-icon fi-production"><svg width="28" height="28" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polygon points="13 2 3 14 12 14 11 22 21 10 12 10 13 2"/></svg></div>
         <h3>Production Ready</h3>
-        <p>AsyncGenerator streaming (including object-boundary page-by-page), Web Worker off-thread generation, PDF parser &amp; modifier. 2665+ tests across 122 files, 95%+ statement coverage, SLSA provenance.</p>
+        <p>AsyncGenerator streaming (including object-boundary page-by-page), Web Worker off-thread generation, PDF parser &amp; modifier. 2686+ tests across 123 files, 95%+ statement coverage, SLSA provenance.</p>
       </div>
 
       <div class="feature-card">
         <div class="feature-icon fi-mcp"><svg width="28" height="28" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="2" y="3" width="20" height="14" rx="2"/><path d="M8 21h8M12 17v4"/><path d="M7 8h2M15 8h2M11 8h2"/></svg></div>
         <h3>AI Integration — MCP</h3>
-        <p>Use pdfnative from Claude Desktop, Cursor, Continue, Zed, and any other stdio MCP client (Cline, Windsurf, Goose, Gemini CLI…) via <a href="https://github.com/Nizoka/pdfnative-mcp" target="_blank" rel="noopener">pdfnative-mcp</a>. <strong>24 production tools</strong> incl. page-tree <code>merge_pdfs</code> / <code>split_pdf</code> / <code>extract_pages</code>, markup <code>annotate_pdf</code>, the network-free <code>draft_governance_issue</code>, <code>validate_pdf</code>, <code>verify_pdf</code>, <code>add_attachment</code> / <code>extract_attachments</code>, <code>extract_text</code>, <code>pdfA</code> flag everywhere, and token-frugal read modes. Zero configuration beyond <code>npx -y pdfnative-mcp</code>.</p>
+        <p>Use pdfnative from Claude Desktop, Cursor, Continue, Zed, and any other MCP client (Cline, Windsurf, Goose, Gemini CLI…) via <a href="https://github.com/Nizoka/pdfnative-mcp" target="_blank" rel="noopener">pdfnative-mcp</a>. <strong>28 production tools</strong> incl. the complete PAdES ladder <code>sign_pdf</code> / <code>add_ltv</code> / <code>timestamp_pdf</code>, <code>update_metadata</code>, the read-only <code>inspect_layout</code> preview, page-tree <code>merge_pdfs</code> / <code>split_pdf</code> / <code>extract_pages</code>, markup <code>annotate_pdf</code>, the network-free <code>draft_governance_issue</code>, <code>pdfA</code> flag everywhere, and token-frugal read modes. Zero configuration beyond <code>npx -y pdfnative-mcp</code>.</p>
       </div>
 
       <div class="feature-card">
@@ -425,21 +426,39 @@ <h2 class="section-title">Simple, Powerful API</h2>
 <section class="section" id="demo">
   <div class="container">
     <h2 class="section-title">Try It Live</h2>
-    <p class="section-subtitle">Pick an example, edit the code, then click "Generate PDF" — it runs entirely in your browser via the npm CDN.</p>
+    <p class="section-subtitle">Pick an example, edit the code, and watch the PDF render beside it — everything runs in your browser via the npm CDN. Nothing is uploaded anywhere.</p>
     <div class="demo-container">
       <div class="demo-toolbar">
+        <div class="demo-mode" role="group" aria-label="Editor mode">
+          <button class="demo-mode-btn active" id="demo-mode-code" aria-pressed="true" type="button">Code</button>
+          <button class="demo-mode-btn" id="demo-mode-json" aria-pressed="false" type="button">JSON</button>
+        </div>
         <label class="demo-picker-label" for="demo-picker">Example:</label>
         <select id="demo-picker" class="demo-picker" aria-label="Choose an example"></select>
         <a class="demo-source-link" id="demo-source-link" href="#" target="_blank" rel="noopener" aria-label="View this example's full generator on GitHub">View source ↗</a>
       </div>
       <p class="demo-description" id="demo-description"></p>
-      <textarea class="demo-editor" id="demo-code" spellcheck="false" aria-label="PDF generation code"></textarea>
-      <div class="demo-actions">
-        <button class="btn btn-primary" id="demo-run">▶ Generate PDF</button>
-        <button class="btn btn-secondary" id="demo-reset" type="button">↺ Reset</button>
-        <span class="demo-status" id="demo-status"></span>
+      <div class="pn-split">
+        <div class="pn-split-pane">
+          <textarea class="demo-editor" id="demo-code" spellcheck="false" aria-label="PDF generation code"></textarea>
+          <textarea class="demo-editor" id="demo-json" spellcheck="false" aria-label="Document JSON (DocumentParams)" hidden></textarea>
+          <div class="demo-actions">
+            <button class="btn btn-primary" id="demo-run">▶ Generate PDF</button>
+            <button class="btn btn-secondary" id="demo-reset" type="button">↺ Reset</button>
+            <button class="btn btn-secondary" id="demo-download" type="button" disabled>⬇ Download</button>
+            <button class="btn btn-secondary" id="demo-share" type="button">🔗 Copy link</button>
+            <button class="btn btn-secondary" id="demo-copy-cli" type="button" hidden>Copy as CLI command</button>
+            <button class="btn btn-secondary" id="demo-copy-mcp" type="button" hidden>Copy as MCP call</button>
+            <span class="demo-status" id="demo-status" role="status" aria-live="polite"></span>
+          </div>
+          <div class="demo-error" id="demo-error" role="alert"></div>
+          <p class="demo-note" id="demo-json-note" hidden>The JSON is a pdfnative <code>DocumentParams</code> object — the same document the library, <code>pdfnative-cli render</code> and the <code>generate_basic_pdf</code> MCP tool consume. Share links (<code>#doc=…</code>) encode this JSON, never code.</p>
+        </div>
+        <div class="pn-split-pane pn-preview-pane">
+          <iframe class="pn-preview-frame" id="demo-preview" title="Generated PDF preview"></iframe>
+          <p class="pn-preview-note" id="demo-preview-note" hidden>Your browser does not preview PDFs inline (most mobile browsers do not) — use <strong>Download</strong> to open the generated file.</p>
+        </div>
       </div>
-      <div class="demo-error" id="demo-error" role="alert"></div>
       <p class="demo-note">
         Need more? Browse all
         <a href="https://github.com/Nizoka/pdfnative/tree/main/scripts/generators" target="_blank" rel="noopener">48 generators (242 sample PDFs)</a>
@@ -456,7 +475,7 @@ <h2 class="section-title">30-Second Start</h2>
     <p class="section-subtitle">Four adoption paths — pick the one that fits your stack. All four are zero-config and zero-build.</p>
     <div class="onboarding-grid">
       <div class="onboarding-card">
-        <h3>Library <span class="ob-badge" data-pn-badge="pdfnative">v1.6.0</span></h3>
+        <h3>Library <span class="ob-badge" data-pn-badge="pdfnative">v1.7.0</span></h3>
         <p class="ob-tag">For TypeScript / JavaScript apps.</p>
 <pre><code class="language-bash">npm install pdfnative</code></pre>
 <pre><code class="language-typescript">import { buildDocumentPDFBytes, extractText } from 'pdfnative';
@@ -479,7 +498,7 @@ <h3>CLI <span class="ob-badge" data-pn-badge="pdfnative-cli">v1.3.0</span></h3>
         <a class="ob-link" href="guides/cli.html">CLI guide →</a>
       </div>
       <div class="onboarding-card">
-        <h3>MCP <span class="ob-badge" data-pn-badge="pdfnative-mcp">v1.5.0</span></h3>
+        <h3>MCP <span class="ob-badge" data-pn-badge="pdfnative-mcp">v1.6.0</span></h3>
         <p class="ob-tag">For Claude Desktop, Cursor, Continue, Zed, …</p>
 <pre><code class="language-json">{
   "mcpServers": {
@@ -514,6 +533,18 @@ <h3>React <span class="ob-badge" data-pn-badge="pdfnative-react">v1.1.0</span></
   <div class="container">
     <h2 class="section-title">How It Compares</h2>
     <p class="section-subtitle">Feature-by-feature comparison with popular PDF libraries.</p>
+    <div class="cmp-quiz" id="cmp-quiz">
+      <p class="cmp-quiz-label">What does your project need? Tick what applies — the matching rows light up and the verdict below is derived from the table, including the cases where another library is the better fit.</p>
+      <div class="cmp-quiz-options">
+        <label><input type="checkbox" data-quiz-cap="scripts,bidi"> Non-Latin scripts with correct shaping (Arabic, Thai, CJK…)</label>
+        <label><input type="checkbox" data-quiz-cap="sign"> Digital signatures</label>
+        <label><input type="checkbox" data-quiz-cap="pdfa"> PDF/A archival conformance</label>
+        <label><input type="checkbox" data-quiz-cap="parse"> Read or modify existing PDFs</label>
+        <label><input type="checkbox" data-quiz-cap="encrypt"> AES encryption</label>
+        <label><input type="checkbox" data-quiz-cap="barcodes"> Barcodes / QR codes</label>
+      </div>
+      <p class="cmp-quiz-verdict" id="cmp-quiz-verdict" aria-live="polite" hidden></p>
+    </div>
     <div class="table-wrap">
       <table class="cmp-table">
         <caption style="caption-side:bottom;text-align:left;font-size:12px;color:var(--c-text-dim);padding-top:12px;line-height:1.6;">
@@ -549,7 +580,7 @@ <h2 class="section-title">How It Compares</h2>
             <td>@types</td>
             <td class="cmp-check">✓</td>
           </tr>
-          <tr>
+          <tr data-cap="scripts">
             <td>Unicode scripts</td>
             <td><strong>22</strong></td>
             <td>Via fontkit</td>
@@ -557,7 +588,7 @@ <h2 class="section-title">How It Compares</h2>
             <td>Via pdfkit</td>
             <td>Via @pdf-lib/fontkit</td>
           </tr>
-          <tr>
+          <tr data-cap="bidi">
             <td>BiDi (Arabic / Hebrew)</td>
             <td class="cmp-check">✓</td>
             <td class="cmp-cross">✗</td>
@@ -565,7 +596,7 @@ <h2 class="section-title">How It Compares</h2>
             <td class="cmp-cross">✗</td>
             <td class="cmp-cross">✗</td>
           </tr>
-          <tr>
+          <tr data-cap="pdfa">
             <td>PDF/A compliance</td>
             <td><strong>4 levels</strong></td>
             <td class="cmp-cross">✗</td>
@@ -573,7 +604,7 @@ <h2 class="section-title">How It Compares</h2>
             <td class="cmp-cross">✗</td>
             <td class="cmp-cross">✗</td>
           </tr>
-          <tr>
+          <tr data-cap="encrypt">
             <td>AES encryption</td>
             <td><strong>128 + 256</strong></td>
             <td class="cmp-check">✓</td>
@@ -581,7 +612,7 @@ <h2 class="section-title">How It Compares</h2>
             <td class="cmp-check">✓</td>
             <td class="cmp-cross">✗</td>
           </tr>
-          <tr>
+          <tr data-cap="sign">
             <td>Digital signatures</td>
             <td class="cmp-check"><strong>RSA + ECDSA</strong></td>
             <td class="cmp-cross">✗</td>
@@ -589,7 +620,7 @@ <h2 class="section-title">How It Compares</h2>
             <td class="cmp-cross">✗</td>
             <td class="cmp-cross">✗</td>
           </tr>
-          <tr>
+          <tr data-cap="barcodes">
             <td>Barcodes / QR codes</td>
             <td><strong>5 formats</strong></td>
             <td class="cmp-cross">✗</td>
@@ -621,7 +652,7 @@ <h2 class="section-title">How It Compares</h2>
             <td class="cmp-check">✓</td>
             <td class="cmp-cross">✗</td>
           </tr>
-          <tr>
+          <tr data-cap="parse">
             <td>PDF parser / modifier</td>
             <td class="cmp-check">✓</td>
             <td class="cmp-cross">✗</td>
@@ -700,6 +731,13 @@ <h2 class="section-title">Performance</h2>
       Faster hardware (Apple M-series, desktop i7/i9) typically runs 2–4× quicker. Results may vary.
       Run <code>npx vitest bench</code> to measure on your hardware.
     </p>
+    <div class="bench-live" id="bench-live">
+      <button class="btn btn-secondary" id="bench-live-run" type="button">▶ Run this benchmark in your browser</button>
+      <div class="bench-live-grid" id="bench-live-rows" hidden></div>
+      <p class="bench-note" id="bench-live-note" hidden>
+        Measured in this tab just now with <code>performance.now()</code> — one sample per size after a warm-up run, on whatever this device and browser happen to be doing. Indicative, not a benchmark: the CI reference above uses <code>vitest bench</code> with proper sampling. Browser engines typically run this workload slower than Node.
+      </p>
+    </div>
   </div>
 </section>
 
@@ -739,7 +777,7 @@ <h2 class="section-title">Architecture</h2>
     <p class="section-subtitle">Strict unidirectional dependency flow. No circular imports. Each module is independently testable.</p>
     <div class="arch-diagram">
       <a href="https://github.com/Nizoka/pdfnative/tree/main/src" target="_blank" rel="noopener">
-        <img src="assets/architecture.svg" alt="pdfnative 1.7.0 module architecture. A header badge notes the repository's AI-agent governance with a human-in-the-loop contribution gate. Top band: three ecosystem consumers install pdfnative from npm — pdfnative-cli (17 commands: render · fill · sign · encrypt · extract-text and more), pdfnative-mcp (MCP server, 24 tools, any stdio client), and pdfnative-react (on-device JSX-to-PDF). Bottom band: the zero-dependency library with a strict unidirectional flow — types → core (pdf-builder, pdf-document, pdf-encrypt, pdf-tags, outline, page labels, annotations, layout inspect) ← fonts (encoding, subset, CMap, math font, tools sub-path) ← shaping (GSUB · GPOS · BiDi · 22 scripts) ← worker — plus a standalone crypto module and a standalone parser that reads, decrypts, extracts text, modifies, annotates, merges, splits and re-encrypts PDFs. A legend explains the four edge types: imports, consumes via npm, standalone, and imports compress." width="960" height="600" loading="lazy">
+        <img src="assets/architecture.svg" alt="pdfnative 1.7.0 module architecture. A header badge notes the repository's AI-agent governance with a human-in-the-loop contribution gate. Top band: three ecosystem consumers install pdfnative from npm — pdfnative-cli (17 commands: render · fill · sign · encrypt · extract-text and more), pdfnative-mcp (MCP server, 28 tools, any MCP client), and pdfnative-react (on-device JSX-to-PDF). Bottom band: the zero-dependency library with a strict unidirectional flow — types → core (pdf-builder, pdf-document, pdf-encrypt, pdf-tags, outline, page labels, annotations, layout inspect) ← fonts (encoding, subset, CMap, math font, tools sub-path) ← shaping (GSUB · GPOS · BiDi · 22 scripts) ← worker — plus a standalone crypto module and a standalone parser that reads, decrypts, extracts text, modifies, annotates, merges, splits and re-encrypts PDFs. A legend explains the four edge types: imports, consumes via npm, standalone, and imports compress." width="960" height="600" loading="lazy">
       </a>
     </div>
   </div>
@@ -763,25 +801,28 @@ <h2 class="section-title">AI Governance &amp; Human-in-the-Loop</h2>
 <section class="section section-alt" id="mcp">
   <div class="container">
     <h2 class="section-title">Use pdfnative from Any AI Client</h2>
-    <p class="section-subtitle"><a href="https://github.com/Nizoka/pdfnative-mcp" target="_blank" rel="noopener">pdfnative-mcp</a> is a <strong>Model Context Protocol server</strong> that exposes the full pdfnative library to Claude Desktop, Cursor, Continue, Zed, and any other MCP-compatible AI client. One <code>npx</code> command, no code required. Now with page-tree <code>merge_pdfs</code> / <code>split_pdf</code> / <code>extract_pages</code>, markup <code>annotate_pdf</code>, the network-free <code>draft_governance_issue</code>, <code>validate_pdf</code>, <code>verify_pdf</code>, <code>add_attachment</code> / <code>extract_attachments</code>, <code>extract_text</code>, a <code>pdfA</code> flag on every document tool, multi-script <code>lang</code>, and token-frugal read modes.</p>
+    <p class="section-subtitle"><a href="https://github.com/Nizoka/pdfnative-mcp" target="_blank" rel="noopener">pdfnative-mcp</a> is a <strong>Model Context Protocol server</strong> that exposes the full pdfnative library to Claude Desktop, Cursor, Continue, Zed, and any other MCP-compatible AI client. One <code>npx</code> command, no code required. Now with the complete PAdES ladder (<code>sign_pdf</code> with RFC 3161 timestamps, <code>add_ltv</code>, <code>timestamp_pdf</code>), <code>update_metadata</code>, the read-only <code>inspect_layout</code> pagination preview, all 13 block kinds in <code>generate_basic_pdf</code>, print production, charts v2, page-tree <code>merge_pdfs</code> / <code>split_pdf</code> / <code>extract_pages</code>, markup <code>annotate_pdf</code>, the network-free <code>draft_governance_issue</code>, a <code>pdfA</code> flag on every document tool, and token-frugal read modes — on the MCP 2026-07-28 spec with automatic legacy fallback.</p>
     <div class="mcp-layout">
       <div class="mcp-tools">
-        <h3>24 Production Tools</h3>
+        <h3>28 Production Tools</h3>
         <div class="table-wrap">
         <table class="mcp-table">
           <thead><tr><th>Tool</th><th>Purpose</th></tr></thead>
           <tbody>
-            <tr><td><code>generate_basic_pdf</code></td><td>Multi-page documents (headings, paragraphs, lists). Optional <code>pdfA</code> flag.</td></tr>
+            <tr><td><code>generate_basic_pdf</code></td><td>Multi-page documents — all 13 block kinds since v1.6.0 (incl. tables, images, links, TOC, barcodes, SVG, form fields, charts). Optional <code>pdfA</code>, layout options, build-time <code>encrypt</code>, print production.</td></tr>
             <tr><td><code>add_table</code></td><td>Tabular reports — now with optional <code>autoFitColumns</code> and <code>clipCells</code> (pdfnative v1.2 <code>TableBlock</code>).</td></tr>
             <tr><td><code>add_barcode</code></td><td>QR Code, Code 128, EAN-13, Data Matrix, PDF417</td></tr>
-            <tr><td><code>add_international_text</code></td><td>22 scripts with BiDi &amp; OpenType shaping. <code>lang</code> now accepts <code>string</code>, <code>string[]</code>, or comma-separated — e.g. <code>["ar", "emoji"]</code>.</td></tr>
-            <tr><td><code>add_form</code></td><td>Interactive AcroForm fields</td></tr>
-            <tr><td><code>embed_image</code></td><td>JPEG / PNG image embedding</td></tr>
-            <tr><td><code>prepare_signature_placeholder</code></td><td>PDF with <code>/Sig</code> field ready to sign</td></tr>
-            <tr><td><code>sign_pdf</code></td><td>CMS/PKCS#7 signatures (RSA &amp; ECDSA)</td></tr>
-            <tr><td><code>inspect_pdf</code></td><td>Read-only inspection — version, page count, encryption, PDF/A claim, signatures, info dict; optional CI-style <code>check: ('pdfa'|'signed'|'encrypted'|'placeholder'|'attachments')[]</code>.</td></tr>
+            <tr><td><code>add_international_text</code></td><td>25 <code>lang</code> font codes (22 Unicode scripts + <code>latin</code> + <code>emoji</code> + explicit <code>math</code>) with BiDi &amp; OpenType shaping. <code>lang</code> accepts <code>string</code>, <code>string[]</code>, or comma-separated — e.g. <code>["ar", "emoji"]</code>.</td></tr>
+            <tr><td><code>add_form</code></td><td>Interactive AcroForm fields — <code>text</code>, <code>textarea</code>, <code>checkbox</code>, <code>radio</code>, <code>dropdown</code>, plus <code>listbox</code> and <code>placeholder</code> (v1.6.0)</td></tr>
+            <tr><td><code>embed_image</code></td><td>JPEG / PNG image embedding, with <code>align</code> / <code>alt</code> (v1.6.0)</td></tr>
+            <tr><td><code>prepare_signature_placeholder</code></td><td>PDF with <code>/Sig</code> field ready to sign; <code>subFilter</code> / <code>reserveTimestamp</code> (v1.6.0)</td></tr>
+            <tr><td><code>sign_pdf</code></td><td>PAdES CMS signatures (RSA-SHA256/384/512 &amp; ECDSA); <code>profile: 'pades'</code>, RFC 3161 <code>timestamp</code>, cert chains, multiple signatures (v1.6.0)</td></tr>
+            <tr><td><code>add_ltv</code></td><td>Embed <code>/DSS</code> + <code>/VRI</code> long-term-validation material — PAdES B-LT (v1.6.0).</td></tr>
+            <tr><td><code>timestamp_pdf</code></td><td>Append a <code>/DocTimeStamp</code> through the operator TSA — PAdES B-LTA (v1.6.0).</td></tr>
+            <tr><td><code>inspect_pdf</code></td><td>Read-only inspection — version, page count, encryption, PDF/A claim, signatures, info dict; signature / annotation inventories, page boxes, <code>dss</code> (v1.6.0); optional CI-style <code>check</code> assertions.</td></tr>
+            <tr><td><code>inspect_layout</code></td><td>Read-only pagination dry run — page count and block geometry, no PDF produced (v1.6.0).</td></tr>
             <tr><td><code>validate_pdf</code></td><td>Read-only PDF/UA structural validation (<code>valid</code>, <code>errors</code>, <code>warnings</code>).</td></tr>
-            <tr><td><code>verify_pdf</code></td><td>Real CMS/PKCS#7 signature verification — RSA &amp; ECDSA, digest, certificate chain (v1.0.0).</td></tr>
+            <tr><td><code>verify_pdf</code></td><td>Real CMS/PKCS#7 signature verification — RSA &amp; ECDSA, digest, certificate chain; <code>/DocTimeStamp</code> tokens and the <code>ltv: true</code> PAdES-level report (v1.6.0).</td></tr>
             <tr><td><code>add_attachment</code></td><td>Embed files (Factur-X / ZUGFeRD e-invoice XML) into PDF/A-3b output (v1.0.0).</td></tr>
             <tr><td><code>extract_attachments</code></td><td>Extract embedded files from existing PDFs (metadata-only mode available, v1.2.0).</td></tr>
             <tr><td><code>extract_text</code></td><td>Extract text content from an existing PDF via the native parser (v1.0.0).</td></tr>
@@ -790,11 +831,12 @@ <h3>24 Production Tools</h3>
             <tr><td><code>extract_pages</code></td><td>Pull an arbitrary, order-preserving page subset (max 5000) into a new PDF (v1.3.0).</td></tr>
             <tr><td><code>annotate_pdf</code></td><td>Overlay markup annotations (highlight / underline / note / shape) on an existing PDF via incremental update. A visual review layer, not a redaction (v1.4.0).</td></tr>
             <tr><td><code>draft_governance_issue</code></td><td>Assemble a governance-compliant GitHub-issue draft locally — network-free by construction; never submits (v1.4.0).</td></tr>
-            <tr><td><code>add_chart</code></td><td>Render bar / horizontal-bar / line / pie / donut charts as native PDF vector paths — no rasterisation, no image round-trip (v1.5.0).</td></tr>
+            <tr><td><code>add_chart</code></td><td>Render charts as native PDF vector paths — nine types since v1.6.0 (bar, horizontal bar, stacked bar, stacked horizontal bar, line, area, scatter, pie, donut), dual axis, log &amp; time scales; no rasterisation (v1.5.0).</td></tr>
             <tr><td><code>read_form_fields</code></td><td>List an existing AcroForm's fields with their types, current values and options — the read half of the fill round-trip (v1.5.0).</td></tr>
             <tr><td><code>fill_form</code></td><td>Fill AcroForm field values and optionally flatten them into static page content (v1.5.0).</td></tr>
             <tr><td><code>encrypt_pdf</code></td><td>Re-secure an existing PDF with AES-128 or AES-256, setting owner/user passwords and permissions (v1.5.0).</td></tr>
             <tr><td><code>decrypt_pdf</code></td><td>Remove encryption from a password-protected PDF, in-server — RC4, AES-128 and AES-256 sources (v1.5.0).</td></tr>
+            <tr><td><code>update_metadata</code></td><td>Rewrite <code>/Info</code> (+ XMP) of an existing PDF via incremental update (v1.6.0).</td></tr>
           </tbody>
         </table>
         </div>
@@ -811,6 +853,8 @@ <h3>Claude Desktop — 3-line setup</h3>
   }
 }</code></pre>
         <p>Supports Cursor, Continue, Zed, and any stdio MCP client. See the <a href="guides/mcp.html">MCP Integration Guide →</a> &middot; <a href="playgrounds/mcp.html">Try the MCP playground →</a></p>
+        <h3 style="margin-top:24px">Coding with an AI agent?</h3>
+        <p>Paste the <a href="agent-brief.md">agent brief</a> into your assistant's context: the core API, the verified pitfalls that produce wrong code, and the self-verification loop — in about a page. <button class="btn btn-secondary" type="button" data-copy-url="agent-brief.md" style="margin-left:6px">Copy as prompt</button></p>
       </div>
     </div>
   </div>
@@ -967,6 +1011,8 @@ <h4>Guides</h4>
           <li><a href="guides/annotations.html">Annotations</a></li>
           <li><a href="guides/outlines.html">Outlines &amp; page labels</a></li>
           <li><a href="guides/signatures.html">Signatures</a></li>
+          <li><a href="guides/ltv.html">Long-term validation</a></li>
+          <li><a href="guides/print.html">Print production</a></li>
           <li><a href="guides/colour-emoji.html">Colour emoji</a></li>
           <li><a href="guides/faq.html">FAQ</a></li>
           <li><a href="guides/troubleshooting.html">Troubleshooting</a></li>
@@ -980,6 +1026,7 @@ <h4>Playgrounds</h4>
           <li><a href="playgrounds/extreme-scripts.html">Extreme scripts</a></li>
           <li><a href="playgrounds/all-scripts.html">All 22 scripts</a></li>
           <li><a href="playgrounds/toolkit.html">PDF Toolkit</a></li>
+          <li><a href="playgrounds/inspect.html">Inspect &amp; verify</a></li>
           <li><a href="playgrounds/charts.html">Charts</a></li>
           <li><a href="playgrounds/authoring-plus.html">Authoring+</a></li>
           <li><a href="playgrounds/scale.html">Scale</a></li>
diff --git a/docs/learn/01-install.html b/docs/learn/01-install.html
index 7389cc4..7d4ecbb 100644
--- a/docs/learn/01-install.html
+++ b/docs/learn/01-install.html
@@ -25,21 +25,7 @@
   <link rel="icon" type="image/svg+xml" href="../favicon.svg">
   <link rel="stylesheet" href="../style.css">
   <link rel="stylesheet" href="../guides/guide.css">
-  <style>
-    .ln-pager { display: flex; align-items: center; justify-content: space-between; gap: 12px; flex-wrap: wrap; margin: 36px 0 0; padding-top: 20px; border-top: 1px solid var(--c-border); font-size: 14px; }
-    .ln-pager a { font-weight: 600; }
-    .ln-step { color: var(--c-text-dim); font-size: 13px; font-variant-numeric: tabular-nums; }
-    .ln-hint { color: var(--c-text-dim); font-size: 13px; }
-    .ln-kbd { font-size: 12px; color: var(--c-text-dim); margin: 28px 0 -12px; }
-    .ln-kbd kbd { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 11px; padding: 1px 5px; border: 1px solid var(--c-border); border-radius: 4px; background: var(--c-surface); }
-    .ln-prereq { font-size: 13px; color: var(--c-text-dim); margin: -8px 0 20px; }
-    .ln-check { margin: 28px 0 0; padding: 12px 16px; background: var(--c-surface); border-left: 3px solid var(--c-success); border-radius: 0 8px 8px 0; font-size: 14px; }
-    .ln-list { list-style: none; padding: 0; margin: 24px 0; display: grid; gap: 10px; }
-    .ln-list li { border: 1px solid var(--c-border); border-radius: 8px; padding: 14px 16px; }
-    .ln-list a { font-weight: 700; font-size: 15px; }
-    .ln-list p { margin: 4px 0 0; font-size: 13px; color: var(--c-text-dim); }
-    .ln-num { display: inline-block; min-width: 22px; color: var(--c-text-dim); font-variant-numeric: tabular-nums; }
-  </style>
+  <link rel="stylesheet" href="learn.css">
   <script type="application/ld+json">
   {
     "@context": "https://schema.org",
diff --git a/docs/learn/02-blocks.html b/docs/learn/02-blocks.html
index ca858e2..1336aa2 100644
--- a/docs/learn/02-blocks.html
+++ b/docs/learn/02-blocks.html
@@ -26,21 +26,7 @@
   <link rel="icon" type="image/svg+xml" href="../favicon.svg">
   <link rel="stylesheet" href="../style.css">
   <link rel="stylesheet" href="../guides/guide.css">
-  <style>
-    .ln-pager { display: flex; align-items: center; justify-content: space-between; gap: 12px; flex-wrap: wrap; margin: 36px 0 0; padding-top: 20px; border-top: 1px solid var(--c-border); font-size: 14px; }
-    .ln-pager a { font-weight: 600; }
-    .ln-step { color: var(--c-text-dim); font-size: 13px; font-variant-numeric: tabular-nums; }
-    .ln-hint { color: var(--c-text-dim); font-size: 13px; }
-    .ln-kbd { font-size: 12px; color: var(--c-text-dim); margin: 28px 0 -12px; }
-    .ln-kbd kbd { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 11px; padding: 1px 5px; border: 1px solid var(--c-border); border-radius: 4px; background: var(--c-surface); }
-    .ln-prereq { font-size: 13px; color: var(--c-text-dim); margin: -8px 0 20px; }
-    .ln-check { margin: 28px 0 0; padding: 12px 16px; background: var(--c-surface); border-left: 3px solid var(--c-success); border-radius: 0 8px 8px 0; font-size: 14px; }
-    .ln-list { list-style: none; padding: 0; margin: 24px 0; display: grid; gap: 10px; }
-    .ln-list li { border: 1px solid var(--c-border); border-radius: 8px; padding: 14px 16px; }
-    .ln-list a { font-weight: 700; font-size: 15px; }
-    .ln-list p { margin: 4px 0 0; font-size: 13px; color: var(--c-text-dim); }
-    .ln-num { display: inline-block; min-width: 22px; color: var(--c-text-dim); font-variant-numeric: tabular-nums; }
-  </style>
+  <link rel="stylesheet" href="learn.css">
   <script type="application/ld+json">
   {
     "@context": "https://schema.org",
diff --git a/docs/learn/03-tables.html b/docs/learn/03-tables.html
index cd18150..a3ffa05 100644
--- a/docs/learn/03-tables.html
+++ b/docs/learn/03-tables.html
@@ -26,21 +26,7 @@
   <link rel="icon" type="image/svg+xml" href="../favicon.svg">
   <link rel="stylesheet" href="../style.css">
   <link rel="stylesheet" href="../guides/guide.css">
-  <style>
-    .ln-pager { display: flex; align-items: center; justify-content: space-between; gap: 12px; flex-wrap: wrap; margin: 36px 0 0; padding-top: 20px; border-top: 1px solid var(--c-border); font-size: 14px; }
-    .ln-pager a { font-weight: 600; }
-    .ln-step { color: var(--c-text-dim); font-size: 13px; font-variant-numeric: tabular-nums; }
-    .ln-hint { color: var(--c-text-dim); font-size: 13px; }
-    .ln-kbd { font-size: 12px; color: var(--c-text-dim); margin: 28px 0 -12px; }
-    .ln-kbd kbd { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 11px; padding: 1px 5px; border: 1px solid var(--c-border); border-radius: 4px; background: var(--c-surface); }
-    .ln-prereq { font-size: 13px; color: var(--c-text-dim); margin: -8px 0 20px; }
-    .ln-check { margin: 28px 0 0; padding: 12px 16px; background: var(--c-surface); border-left: 3px solid var(--c-success); border-radius: 0 8px 8px 0; font-size: 14px; }
-    .ln-list { list-style: none; padding: 0; margin: 24px 0; display: grid; gap: 10px; }
-    .ln-list li { border: 1px solid var(--c-border); border-radius: 8px; padding: 14px 16px; }
-    .ln-list a { font-weight: 700; font-size: 15px; }
-    .ln-list p { margin: 4px 0 0; font-size: 13px; color: var(--c-text-dim); }
-    .ln-num { display: inline-block; min-width: 22px; color: var(--c-text-dim); font-variant-numeric: tabular-nums; }
-  </style>
+  <link rel="stylesheet" href="learn.css">
   <script type="application/ld+json">
   {
     "@context": "https://schema.org",
diff --git a/docs/learn/04-page-furniture.html b/docs/learn/04-page-furniture.html
index d66df2a..264e61d 100644
--- a/docs/learn/04-page-furniture.html
+++ b/docs/learn/04-page-furniture.html
@@ -26,21 +26,7 @@
   <link rel="icon" type="image/svg+xml" href="../favicon.svg">
   <link rel="stylesheet" href="../style.css">
   <link rel="stylesheet" href="../guides/guide.css">
-  <style>
-    .ln-pager { display: flex; align-items: center; justify-content: space-between; gap: 12px; flex-wrap: wrap; margin: 36px 0 0; padding-top: 20px; border-top: 1px solid var(--c-border); font-size: 14px; }
-    .ln-pager a { font-weight: 600; }
-    .ln-step { color: var(--c-text-dim); font-size: 13px; font-variant-numeric: tabular-nums; }
-    .ln-hint { color: var(--c-text-dim); font-size: 13px; }
-    .ln-kbd { font-size: 12px; color: var(--c-text-dim); margin: 28px 0 -12px; }
-    .ln-kbd kbd { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 11px; padding: 1px 5px; border: 1px solid var(--c-border); border-radius: 4px; background: var(--c-surface); }
-    .ln-prereq { font-size: 13px; color: var(--c-text-dim); margin: -8px 0 20px; }
-    .ln-check { margin: 28px 0 0; padding: 12px 16px; background: var(--c-surface); border-left: 3px solid var(--c-success); border-radius: 0 8px 8px 0; font-size: 14px; }
-    .ln-list { list-style: none; padding: 0; margin: 24px 0; display: grid; gap: 10px; }
-    .ln-list li { border: 1px solid var(--c-border); border-radius: 8px; padding: 14px 16px; }
-    .ln-list a { font-weight: 700; font-size: 15px; }
-    .ln-list p { margin: 4px 0 0; font-size: 13px; color: var(--c-text-dim); }
-    .ln-num { display: inline-block; min-width: 22px; color: var(--c-text-dim); font-variant-numeric: tabular-nums; }
-  </style>
+  <link rel="stylesheet" href="learn.css">
   <script type="application/ld+json">
   {
     "@context": "https://schema.org",
diff --git a/docs/learn/05-fonts-and-scripts.html b/docs/learn/05-fonts-and-scripts.html
index c08bf60..0c9a412 100644
--- a/docs/learn/05-fonts-and-scripts.html
+++ b/docs/learn/05-fonts-and-scripts.html
@@ -26,21 +26,7 @@
   <link rel="icon" type="image/svg+xml" href="../favicon.svg">
   <link rel="stylesheet" href="../style.css">
   <link rel="stylesheet" href="../guides/guide.css">
-  <style>
-    .ln-pager { display: flex; align-items: center; justify-content: space-between; gap: 12px; flex-wrap: wrap; margin: 36px 0 0; padding-top: 20px; border-top: 1px solid var(--c-border); font-size: 14px; }
-    .ln-pager a { font-weight: 600; }
-    .ln-step { color: var(--c-text-dim); font-size: 13px; font-variant-numeric: tabular-nums; }
-    .ln-hint { color: var(--c-text-dim); font-size: 13px; }
-    .ln-kbd { font-size: 12px; color: var(--c-text-dim); margin: 28px 0 -12px; }
-    .ln-kbd kbd { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 11px; padding: 1px 5px; border: 1px solid var(--c-border); border-radius: 4px; background: var(--c-surface); }
-    .ln-prereq { font-size: 13px; color: var(--c-text-dim); margin: -8px 0 20px; }
-    .ln-check { margin: 28px 0 0; padding: 12px 16px; background: var(--c-surface); border-left: 3px solid var(--c-success); border-radius: 0 8px 8px 0; font-size: 14px; }
-    .ln-list { list-style: none; padding: 0; margin: 24px 0; display: grid; gap: 10px; }
-    .ln-list li { border: 1px solid var(--c-border); border-radius: 8px; padding: 14px 16px; }
-    .ln-list a { font-weight: 700; font-size: 15px; }
-    .ln-list p { margin: 4px 0 0; font-size: 13px; color: var(--c-text-dim); }
-    .ln-num { display: inline-block; min-width: 22px; color: var(--c-text-dim); font-variant-numeric: tabular-nums; }
-  </style>
+  <link rel="stylesheet" href="learn.css">
   <script type="application/ld+json">
   {
     "@context": "https://schema.org",
diff --git a/docs/learn/06-browser.html b/docs/learn/06-browser.html
index a7c3271..89c1d9c 100644
--- a/docs/learn/06-browser.html
+++ b/docs/learn/06-browser.html
@@ -26,21 +26,7 @@
   <link rel="icon" type="image/svg+xml" href="../favicon.svg">
   <link rel="stylesheet" href="../style.css">
   <link rel="stylesheet" href="../guides/guide.css">
-  <style>
-    .ln-pager { display: flex; align-items: center; justify-content: space-between; gap: 12px; flex-wrap: wrap; margin: 36px 0 0; padding-top: 20px; border-top: 1px solid var(--c-border); font-size: 14px; }
-    .ln-pager a { font-weight: 600; }
-    .ln-step { color: var(--c-text-dim); font-size: 13px; font-variant-numeric: tabular-nums; }
-    .ln-hint { color: var(--c-text-dim); font-size: 13px; }
-    .ln-kbd { font-size: 12px; color: var(--c-text-dim); margin: 28px 0 -12px; }
-    .ln-kbd kbd { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 11px; padding: 1px 5px; border: 1px solid var(--c-border); border-radius: 4px; background: var(--c-surface); }
-    .ln-prereq { font-size: 13px; color: var(--c-text-dim); margin: -8px 0 20px; }
-    .ln-check { margin: 28px 0 0; padding: 12px 16px; background: var(--c-surface); border-left: 3px solid var(--c-success); border-radius: 0 8px 8px 0; font-size: 14px; }
-    .ln-list { list-style: none; padding: 0; margin: 24px 0; display: grid; gap: 10px; }
-    .ln-list li { border: 1px solid var(--c-border); border-radius: 8px; padding: 14px 16px; }
-    .ln-list a { font-weight: 700; font-size: 15px; }
-    .ln-list p { margin: 4px 0 0; font-size: 13px; color: var(--c-text-dim); }
-    .ln-num { display: inline-block; min-width: 22px; color: var(--c-text-dim); font-variant-numeric: tabular-nums; }
-  </style>
+  <link rel="stylesheet" href="learn.css">
   <script type="application/ld+json">
   {
     "@context": "https://schema.org",
diff --git a/docs/learn/07-going-big.html b/docs/learn/07-going-big.html
index ffeedd5..f7785dd 100644
--- a/docs/learn/07-going-big.html
+++ b/docs/learn/07-going-big.html
@@ -26,21 +26,7 @@
   <link rel="icon" type="image/svg+xml" href="../favicon.svg">
   <link rel="stylesheet" href="../style.css">
   <link rel="stylesheet" href="../guides/guide.css">
-  <style>
-    .ln-pager { display: flex; align-items: center; justify-content: space-between; gap: 12px; flex-wrap: wrap; margin: 36px 0 0; padding-top: 20px; border-top: 1px solid var(--c-border); font-size: 14px; }
-    .ln-pager a { font-weight: 600; }
-    .ln-step { color: var(--c-text-dim); font-size: 13px; font-variant-numeric: tabular-nums; }
-    .ln-hint { color: var(--c-text-dim); font-size: 13px; }
-    .ln-kbd { font-size: 12px; color: var(--c-text-dim); margin: 28px 0 -12px; }
-    .ln-kbd kbd { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 11px; padding: 1px 5px; border: 1px solid var(--c-border); border-radius: 4px; background: var(--c-surface); }
-    .ln-prereq { font-size: 13px; color: var(--c-text-dim); margin: -8px 0 20px; }
-    .ln-check { margin: 28px 0 0; padding: 12px 16px; background: var(--c-surface); border-left: 3px solid var(--c-success); border-radius: 0 8px 8px 0; font-size: 14px; }
-    .ln-list { list-style: none; padding: 0; margin: 24px 0; display: grid; gap: 10px; }
-    .ln-list li { border: 1px solid var(--c-border); border-radius: 8px; padding: 14px 16px; }
-    .ln-list a { font-weight: 700; font-size: 15px; }
-    .ln-list p { margin: 4px 0 0; font-size: 13px; color: var(--c-text-dim); }
-    .ln-num { display: inline-block; min-width: 22px; color: var(--c-text-dim); font-variant-numeric: tabular-nums; }
-  </style>
+  <link rel="stylesheet" href="learn.css">
   <script type="application/ld+json">
   {
     "@context": "https://schema.org",
diff --git a/docs/learn/08-next-steps.html b/docs/learn/08-next-steps.html
index 54a8e97..31bcc64 100644
--- a/docs/learn/08-next-steps.html
+++ b/docs/learn/08-next-steps.html
@@ -25,21 +25,7 @@
   <link rel="icon" type="image/svg+xml" href="../favicon.svg">
   <link rel="stylesheet" href="../style.css">
   <link rel="stylesheet" href="../guides/guide.css">
-  <style>
-    .ln-pager { display: flex; align-items: center; justify-content: space-between; gap: 12px; flex-wrap: wrap; margin: 36px 0 0; padding-top: 20px; border-top: 1px solid var(--c-border); font-size: 14px; }
-    .ln-pager a { font-weight: 600; }
-    .ln-step { color: var(--c-text-dim); font-size: 13px; font-variant-numeric: tabular-nums; }
-    .ln-hint { color: var(--c-text-dim); font-size: 13px; }
-    .ln-kbd { font-size: 12px; color: var(--c-text-dim); margin: 28px 0 -12px; }
-    .ln-kbd kbd { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 11px; padding: 1px 5px; border: 1px solid var(--c-border); border-radius: 4px; background: var(--c-surface); }
-    .ln-prereq { font-size: 13px; color: var(--c-text-dim); margin: -8px 0 20px; }
-    .ln-check { margin: 28px 0 0; padding: 12px 16px; background: var(--c-surface); border-left: 3px solid var(--c-success); border-radius: 0 8px 8px 0; font-size: 14px; }
-    .ln-list { list-style: none; padding: 0; margin: 24px 0; display: grid; gap: 10px; }
-    .ln-list li { border: 1px solid var(--c-border); border-radius: 8px; padding: 14px 16px; }
-    .ln-list a { font-weight: 700; font-size: 15px; }
-    .ln-list p { margin: 4px 0 0; font-size: 13px; color: var(--c-text-dim); }
-    .ln-num { display: inline-block; min-width: 22px; color: var(--c-text-dim); font-variant-numeric: tabular-nums; }
-  </style>
+  <link rel="stylesheet" href="learn.css">
   <script type="application/ld+json">
   {
     "@context": "https://schema.org",
@@ -124,7 +110,7 @@ <h2>Pick the surface that fits your work</h2>
     <ul>
       <li><strong>The library</strong> — what you have been using. Full control, any runtime.</li>
       <li><strong><a href="../guides/cli.html">pdfnative-cli</a></strong> — 17 commands for shell scripts, CI and Makefiles. Render, sign, encrypt, extract text, fill forms, merge and split, all from JSON on stdin.</li>
-      <li><strong><a href="../guides/mcp.html">pdfnative-mcp</a></strong> — 24 tools that let an AI assistant (Claude, Cursor, Zed, any stdio MCP client) produce and inspect PDFs on your behalf, with no code.</li>
+      <li><strong><a href="../guides/mcp.html">pdfnative-mcp</a></strong> — 28 tools that let an AI assistant (Claude, Cursor, Zed, any MCP client) produce, sign and inspect PDFs on your behalf, with no code.</li>
       <li><strong><a href="../guides/react.html">pdfnative-react</a></strong> — the same engine driven by JSX components, if your app is already React.</li>
     </ul>
 
@@ -139,9 +125,9 @@ <h2>Common next requirements</h2>
     </ul>
 
     <h2>Try things without installing anything</h2>
-    <p>Nine <a href="../playgrounds/">playgrounds</a> run in your browser: 22 writing systems in one document, native charts, the full toolkit, a CLI command builder, an MCP tool explorer, the React renderer, and 100,000 pages.</p>
+    <p>Ten <a href="../playgrounds/">playgrounds</a> run in your browser: 22 writing systems in one document, native charts, the full toolkit, an inspect-and-verify report on any PDF you drop in, a CLI command builder, an MCP tool explorer, the React renderer, and 100,000 pages.</p>
 
-    <p>All 26 <a href="../guides/">reference guides</a> are one click away. If something in them does not hold up, <a href="https://github.com/Nizoka/pdfnative/issues/new" target="_blank" rel="noopener">say so</a> — a claim we cannot defend is a bug.</p>
+    <p>All 30 <a href="../guides/">reference guides</a> are one click away. If something in them does not hold up, <a href="https://github.com/Nizoka/pdfnative/issues/new" target="_blank" rel="noopener">say so</a> — a claim we cannot defend is a bug.</p>
 
     <div class="ln-check">
       <strong>You are done.</strong> You know the model, the delivery paths and where the reference material lives.
diff --git a/docs/learn/index.html b/docs/learn/index.html
index 606a97e..1a7d157 100644
--- a/docs/learn/index.html
+++ b/docs/learn/index.html
@@ -8,6 +8,7 @@
   <link rel="canonical" href="https://pdfnative.dev/learn/">
   <link rel="alternate" hreflang="en" href="https://pdfnative.dev/learn/">
   <link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/learn/">
+  <link rel="alternate" type="text/plain" href="../llms.txt" title="llms.txt — machine-readable documentation index">
   <link rel="next" href="01-install.html">
   <meta property="og:type" content="article">
   <meta property="og:site_name" content="pdfnative">
@@ -25,19 +26,7 @@
   <link rel="icon" type="image/svg+xml" href="../favicon.svg">
   <link rel="stylesheet" href="../style.css">
   <link rel="stylesheet" href="../guides/guide.css">
-  <style>
-    .ln-pager { display: flex; align-items: center; justify-content: space-between; gap: 12px; flex-wrap: wrap; margin: 36px 0 0; padding-top: 20px; border-top: 1px solid var(--c-border); font-size: 14px; }
-    .ln-pager a { font-weight: 600; }
-    .ln-step { color: var(--c-text-dim); font-size: 13px; font-variant-numeric: tabular-nums; }
-    .ln-hint { color: var(--c-text-dim); font-size: 13px; }
-    .ln-prereq { font-size: 13px; color: var(--c-text-dim); margin: -8px 0 20px; }
-    .ln-check { margin: 28px 0 0; padding: 12px 16px; background: var(--c-surface); border-left: 3px solid var(--c-success); border-radius: 0 8px 8px 0; font-size: 14px; }
-    .ln-list { list-style: none; padding: 0; margin: 24px 0; display: grid; gap: 10px; }
-    .ln-list li { border: 1px solid var(--c-border); border-radius: 8px; padding: 14px 16px; }
-    .ln-list a { font-weight: 700; font-size: 15px; }
-    .ln-list p { margin: 4px 0 0; font-size: 13px; color: var(--c-text-dim); }
-    .ln-num { display: inline-block; min-width: 22px; color: var(--c-text-dim); font-variant-numeric: tabular-nums; }
-  </style>
+  <link rel="stylesheet" href="learn.css">
   <script type="application/ld+json">
   {
     "@context": "https://schema.org",
@@ -162,7 +151,7 @@ <h1>Learn pdfnative</h1>
     <p>Eight short steps, in order, from installing the package to shipping a hundred-thousand-page document. Each one introduces exactly one idea and says what you should be able to do at the end of it.</p>
     <p>About thirty minutes, start to finish. You need <strong>Node.js 22 or newer</strong> and nothing else — no account, no key, no service.</p>
 
-    <p class="ln-prereq">Already know what you want? The <a href="../guides/">26 reference guides</a> are the shelf; this is the path.</p>
+    <p class="ln-prereq">Already know what you want? The <a href="../guides/">30 reference guides</a> are the shelf; this is the path.</p>
 
     <ol class="ln-list">
       <li><span class="ln-num">1.</span> <a href="01-install.html">Install pdfnative and make one PDF</a><p>Ten lines, one file on disk. Nothing else.</p></li>
@@ -179,7 +168,7 @@ <h2>Never generated a PDF from code before?</h2>
     <p>Then start at step 1 and do not skip. The single thing that makes pdfnative click is in <a href="02-blocks.html">step 2</a>: a document is an ordered array of blocks, and the library handles page geometry. Everything else follows from that.</p>
 
     <h2>Want to see output before you install anything?</h2>
-    <p>The <a href="../#demo">live editor on the homepage</a> generates real PDFs in your browser, and the <a href="../playgrounds/">nine playgrounds</a> cover charts, 22 writing systems, the full toolkit and more. Nothing is uploaded in any of them.</p>
+    <p>The <a href="../#demo">live editor on the homepage</a> generates real PDFs in your browser, and the <a href="../playgrounds/">ten playgrounds</a> cover charts, 22 writing systems, the full toolkit and more. Nothing is uploaded in any of them.</p>
 
     <div class="ln-pager">
       <span></span>
diff --git a/docs/learn/learn.css b/docs/learn/learn.css
new file mode 100644
index 0000000..e6f9904
--- /dev/null
+++ b/docs/learn/learn.css
@@ -0,0 +1,19 @@
+/* ═══════════════════════════════════════════════════════════════
+   pdfnative.dev — Learn path components (.ln-*)
+   Shared by learn/index.html and the eight steps; extracted from the
+   per-page inline styles they used to duplicate. Inherits style.css tokens.
+   ═══════════════════════════════════════════════════════════════ */
+
+.ln-pager { display: flex; align-items: center; justify-content: space-between; gap: 12px; flex-wrap: wrap; margin: 36px 0 0; padding-top: 20px; border-top: 1px solid var(--c-border); font-size: 14px; }
+.ln-pager a { font-weight: 600; }
+.ln-step { color: var(--c-text-dim); font-size: 13px; font-variant-numeric: tabular-nums; }
+.ln-hint { color: var(--c-text-dim); font-size: 13px; }
+.ln-kbd { font-size: 12px; color: var(--c-text-dim); margin: 28px 0 -12px; }
+.ln-kbd kbd { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 11px; padding: 1px 5px; border: 1px solid var(--c-border); border-radius: 4px; background: var(--c-surface); }
+.ln-prereq { font-size: 13px; color: var(--c-text-dim); margin: -8px 0 20px; }
+.ln-check { margin: 28px 0 0; padding: 12px 16px; background: var(--c-surface); border-left: 3px solid var(--c-success); border-radius: 0 8px 8px 0; font-size: 14px; }
+.ln-list { list-style: none; padding: 0; margin: 24px 0; display: grid; gap: 10px; }
+.ln-list li { border: 1px solid var(--c-border); border-radius: 8px; padding: 14px 16px; }
+.ln-list a { font-weight: 700; font-size: 15px; }
+.ln-list p { margin: 4px 0 0; font-size: 13px; color: var(--c-text-dim); }
+.ln-num { display: inline-block; min-width: 22px; color: var(--c-text-dim); font-variant-numeric: tabular-nums; }
diff --git a/docs/llms-full.txt b/docs/llms-full.txt
index a1f88cb..0b1e112 100644
--- a/docs/llms-full.txt
+++ b/docs/llms-full.txt
@@ -5,7 +5,7 @@
 ## Docs
 
 - [README](https://github.com/Nizoka/pdfnative/blob/main/README.md): Full feature list, install, quick start, API surface, examples.
-- [ROADMAP](https://github.com/Nizoka/pdfnative/blob/main/ROADMAP.md): Shipped milestones (v1.0 → v1.7; v1.5: math/technical-symbols font, `pdfnative/tools` font compiler/parser, SVG `<text>`, page-labels reader, layout debug overlay + `inspectDocumentLayout`, markup annotation read/write, AI-agent governance; v1.4: document outline/bookmarks, page labels, page-tree manipulation (merge/split/extract), streamToFile, COLRv1 advanced compositing; v1.3: COLRv1 colour emoji, USE-lite shaper integration, true constant-memory streaming, UAX #9 X4–X5 overrides, Telugu + Amharic/Sinhala/Tibetan/Khmer/Myanmar scripts, validatePdfUA) + long-term (WASM, full USE).
+- [ROADMAP](https://github.com/Nizoka/pdfnative/blob/main/ROADMAP.md): Shipped milestones (v1.0 → v1.7; v1.7: PAdES LTV B-B → B-LTA, charts v2, colour-emoji flag/ZWJ sequences, UAX #9 conformance, print production, PDF/A declaration guards, `updateMetadata`; v1.6: parser-side decryptor, streaming merge/split/extract, fill & flatten AcroForms, native vector charts, `extractText`, re-encrypt output; v1.5: math/technical-symbols font, `pdfnative/tools` font compiler/parser, SVG `<text>`, page-labels reader, layout debug overlay + `inspectDocumentLayout`, markup annotation read/write, AI-agent governance; v1.4: document outline/bookmarks, page labels, page-tree manipulation (merge/split/extract), streamToFile, COLRv1 advanced compositing; v1.3: COLRv1 colour emoji, USE-lite shaper integration, true constant-memory streaming, UAX #9 X4–X5 overrides, Telugu + Amharic/Sinhala/Tibetan/Khmer/Myanmar scripts, validatePdfUA) + long-term (WASM, full USE).
 - [CHANGELOG](https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md): Per-version changes.
 - [Release notes v1.7.0](https://github.com/Nizoka/pdfnative/blob/main/release-notes/v1.7.0.md): PAdES LTV signing B-B → B-LTA (`signPdfBytesWithTimestamp` RFC 3161 timestamps, `addValidationInfo` `/DSS` + `/VRI` OCSP/CRL material, `addDocumentTimestamp`, `listSignatures`, multi-signature via `addSignaturePlaceholder({ allowMultiple })` — network transport injected through `setTimestampProvider`/`setRevocationProvider`, the engine never opens a socket), charts v2 (stackedBar/stackedBarH/area/scatter, secondary right axis, log + UTC time scales, data labels, x-label collision handling), colour-emoji flag & ZWJ sequences (51 flags + 22 ZWJ as COLR ligatures), UAX #9 conformance fixes (RTL digit order, glyph mirroring, ALEF joining, Persian presentation forms), PDF/A declaration guards (`strict`/`onDiagnostic`), incremental writer/xref hardening, `PdfModifier.updateMetadata()`.
 - [Release notes v1.6.0](https://github.com/Nizoka/pdfnative/blob/main/release-notes/v1.6.0.md): Standard Security Handler reader/decryptor (`openPdf(bytes, { password })`, RC4/AES-128/AES-256; `PdfSourceInput`/`MergeOptions.password` for encrypted merge/split sources), streaming page-tree manipulation (`streamMergedPdfs`/`streamSplitPdf`/`streamExtractPages`), fill & flatten existing AcroForm PDFs (`readFormFields`/`fillForm`/`flattenForm`) — encrypted documents included (encrypted incremental update), native vector charts (`chart` block: bar/barH/line/pie/donut), text extraction (`extractText`: per-page reading-order text + positioned runs, encrypted PDFs supported), re-encrypt merge/split output (`MergeOptions.encrypt`, AES-128/256), expanded colour-emoji subset (221 → 1167 incl. complete Transport & Map). Fixes: spec-compliant R6 hash + all-strings encryption on the writer; incremental trailer carries `/Encrypt` forward.
@@ -25,7 +25,7 @@
 - [FAQ](https://pdfnative.dev/guides/faq.html): Custom fonts, encryption, BiDi, workers, vs other libs.
 - [Troubleshooting](https://pdfnative.dev/guides/troubleshooting.html): Missing glyphs, RTL appearing backwards, oversized PDFs, parser errors.
 - [Colour-emoji CLI](https://pdfnative.dev/guides/colour-emoji-cli.html): `npx pdfnative-build-emoji-font` — generate a colour-emoji data module covering any glyph subset up to the full ~3,600-glyph Noto Color Emoji set, plus flag & ZWJ sequences via `--sequences` / `--sequence-list`; pinned download + SHA-256 verification.
-- [Charts](https://pdfnative.dev/guides/charts.html): Native vector `chart` blocks — 9 kinds (bar, horizontal bar, stacked bars, line, area, scatter, pie, donut) with secondary right axis, log and time scales, data labels, x-label collision handling. Path operators, no rasterisation; `/Figure` tagging with alt text.
+- [Charts](https://pdfnative.dev/guides/charts.html): Native vector `chart` blocks — 9 kinds (bar, horizontal bar, stacked bar, stacked horizontal bar, line, area, scatter, pie, donut) with secondary right axis, log and time scales, data labels, x-label collision handling. Path operators, no rasterisation; `/Figure` tagging with alt text.
 - [Text extraction](https://pdfnative.dev/guides/text-extraction.html): `extractText()` — reading-order Unicode via `/ToUnicode`, optional positioned runs, works on encrypted PDFs with a password. The RAG / agent-ingestion entry point.
 - [Form filling](https://pdfnative.dev/guides/form-filling.html): `readFormFields()` / `fillForm()` / `flattenForm()` on existing AcroForms, including encrypted PDFs via incremental update.
 - [PDF manipulation](https://pdfnative.dev/guides/pdf-manipulation.html): `openPdf()` (with `{ password }`), merge / split / extract pages, re-encrypt on output, and their streaming variants.
@@ -48,26 +48,1522 @@
 
 - [Copilot instructions](https://github.com/Nizoka/pdfnative/blob/main/.github/copilot-instructions.md): Canonical project conventions — architecture, code style, build/test, PDF-specific invariants.
 - [AGENTS.md](https://github.com/Nizoka/pdfnative/blob/main/AGENTS.md): Editor-agnostic agent guidance (Cursor / Aider / Claude Code / Continue).
-- [MCP integration](https://pdfnative.dev/guides/mcp.html): `pdfnative-mcp` v1.5.0 — use pdfnative from Claude Desktop, Cursor, Continue, Zed via 24 tools — native vector `add_chart`, `read_form_fields` / `fill_form`, `encrypt_pdf` / `decrypt_pdf`, markup `annotate_pdf`, the network-free `draft_governance_issue`, and the page-tree trio `merge_pdfs` / `split_pdf` / `extract_pages`. Built on pdfnative 1.7.0.
-- [CLI](https://pdfnative.dev/guides/cli.html): `pdfnative-cli` v1.3.0 — 17 commands from the terminal — render, fill, annotate, merge / split / extract, sign, verify, encrypt, decrypt, inspect, extract-text, batch, doctor, schema, completion, govern; agent-native `--json`/`E_*`/`--dry-run` contract. Built on pdfnative 1.7.0.
+- [MCP integration](https://pdfnative.dev/guides/mcp.html): `pdfnative-mcp` v1.6.0 — use pdfnative from Claude Desktop, Cursor, Continue, Zed via 28 tools — the complete PAdES ladder B-B → B-LTA (`sign_pdf` with RFC 3161 timestamps, `add_ltv`, `timestamp_pdf`), `update_metadata`, the read-only `inspect_layout` pagination preview, all 13 block kinds in `generate_basic_pdf`, print production, charts v2, native vector `add_chart`, `read_form_fields` / `fill_form`, `encrypt_pdf` / `decrypt_pdf`, markup `annotate_pdf`, the network-free `draft_governance_issue`, and the page-tree trio `merge_pdfs` / `split_pdf` / `extract_pages`. MCP 2026-07-28 spec with legacy fallback. Built on pdfnative 1.7.0.
+- [CLI](https://pdfnative.dev/guides/cli.html): `pdfnative-cli` v1.3.0 — 17 commands from the terminal — render, fill, annotate, merge / split / extract, sign, verify, encrypt, decrypt, inspect, extract-text, batch, doctor, schema, completion, govern; agent-native `--json`/`E_*`/`--dry-run` contract. Built on the pdfnative 1.6 engine (pins `^1.6.0`, semver-accepts 1.7.0).
 - [React](https://pdfnative.dev/guides/react.html): `pdfnative-react` v1.1.0 — declarative JSX components compiled on-device to pdfnative blocks; render functions, client hooks, token-frugal DocSpec.
 
 ## Source
 
 - [src/](https://github.com/Nizoka/pdfnative/tree/main/src): Library source (core, crypto, fonts, parser, shaping, types, worker).
 - [scripts/generators/](https://github.com/Nizoka/pdfnative/tree/main/scripts/generators): 48 sample generators producing 242 reference PDFs.
-- [tests/](https://github.com/Nizoka/pdfnative/tree/main/tests): 2665+ tests across 122 files. 95%+ statements measured at v1.6.0; CI enforces ≥88%.
+- [tests/](https://github.com/Nizoka/pdfnative/tree/main/tests): 2686+ tests across 123 files. 95%+ statements measured at v1.6.0; CI enforces ≥88%.
+
+## Machine-readable artefacts
+
+- [agent-brief.md](https://pdfnative.dev/agent-brief.md): A compact briefing for AI agents writing code with pdfnative — the core API, the verified pitfalls that produce wrong code, the surface decision tree, and the self-verification loop. Designed to be pasted into a coding agent's context.
+- [llms-full.txt](https://pdfnative.dev/llms-full.txt): This index plus the README and the full Markdown source of every guide, in one request.
+- [llms-recipes.txt](https://pdfnative.dev/llms-recipes.txt): The executable recipe corpus — standalone TypeScript files importing from `pdfnative`, each executed in CI with its `@expect` assertions verified, so the code you copy is proven to compile and to produce exactly the artefact its header describes.
+- [api.json](https://pdfnative.dev/assets/api.json): The public API surface, derived mechanically from the export statements of `src/index.ts` — name, kind, source module, signature and TSDoc summary where extractable. The substitute for the unpublished `index.d.ts`.
+- [surfaces.json](https://pdfnative.dev/data/surfaces.json): The capability × surface matrix (library / CLI / MCP / React) behind the [Choosing your surface](https://pdfnative.dev/guides/choose.md) guide.
+- [llms-index.json](https://pdfnative.dev/llms-index.json): Per-page machine index — HTML and raw-Markdown URL, title, summary, section anchors, and exact byte / approximate token sizes for every artefact, so you can decide what to fetch before spending the tokens.
+- Every guide serves its raw Markdown at the same URL with `.md` instead of `.html`, declared via `<link rel="alternate" type="text/markdown">` in each page head. All of these URLs are listed in the sitemap.
+
+## Ecosystem
+
+- [pdfnative-cli](https://github.com/Nizoka/pdfnative-cli): CLI wrapper for pdfnative (v1.3.0, built on the pdfnative 1.6 engine — pins `^1.6.0`, semver-accepts 1.7.0) — render, fill, annotate, merge, split, extract, sign, verify, encrypt, decrypt, inspect, extract-text, batch, doctor, schema, completion, govern.
+- [pdfnative-mcp](https://github.com/Nizoka/pdfnative-mcp): Model Context Protocol server exposing pdfnative as 28 AI tools (v1.6.0, built on pdfnative 1.7.0).
+- [pdfnative-react](https://github.com/Nizoka/pdfnative-react): React renderer — declarative JSX components compiled on-device to pdfnative blocks (v1.1.0, React 19 + pdfnative ^1.6.0 peers).
+
+---
+<!-- source: README.md -->
+# pdfnative
+
+[![CI](https://github.com/Nizoka/pdfnative/actions/workflows/ci.yml/badge.svg)](https://github.com/Nizoka/pdfnative/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/Nizoka/pdfnative/actions/workflows/codeql.yml/badge.svg)](https://github.com/Nizoka/pdfnative/actions/workflows/codeql.yml)
+[![npm version](https://img.shields.io/npm/v/pdfnative)](https://www.npmjs.com/package/pdfnative)
+[![npm downloads](https://img.shields.io/npm/dm/pdfnative)](https://www.npmjs.com/package/pdfnative)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/pdfnative)](https://bundlephobia.com/package/pdfnative)
+[![zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](https://www.npmjs.com/package/pdfnative)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![npm provenance](https://img.shields.io/badge/provenance-signed-blueviolet)](https://docs.npmjs.com/generating-provenance-statements)
+[![website](https://img.shields.io/badge/pdfnative.dev-0066FF?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0id2hpdGUiPjxyZWN0IHg9IjMiIHk9IjIiIHdpZHRoPSIxNCIgaGVpZ2h0PSIxOCIgcng9IjIiIGZpbGw9Im5vbmUiIHN0cm9rZT0id2hpdGUiIHN0cm9rZS13aWR0aD0iMS41Ii8+PHBhdGggZD0iTTcgN2g2TTcgMTFoOE03IDE1aDQiIHN0cm9rZT0id2hpdGUiIHN0cm9rZS13aWR0aD0iMS41IiBzdHJva2UtbGluZWNhcD0icm91bmQiLz48L3N2Zz4=)](https://pdfnative.dev)
+[![pdfnative-mcp](https://img.shields.io/npm/v/pdfnative-mcp?label=pdfnative-mcp&color=6366f1)](https://www.npmjs.com/package/pdfnative-mcp)
+[![pdfnative-cli](https://img.shields.io/npm/v/pdfnative-cli?label=pdfnative-cli&color=0e7490)](https://www.npmjs.com/package/pdfnative-cli)
+[![pdfnative-react](https://img.shields.io/npm/v/pdfnative-react?label=pdfnative-react&color=06b6d4)](https://www.npmjs.com/package/pdfnative-react)
+
+Pure native PDF generation library — zero vendor dependencies. Conforms to ISO 32000-1 (PDF 1.7).
+
+## Ecosystem
+
+pdfnative ships as four coordinated packages — pick whichever entry point fits your workflow:
+
+| Package | Latest | Use it for |
+|---|:---:|---|
+| [`pdfnative`](https://www.npmjs.com/package/pdfnative) | **v1.7.0** | The library itself — call from Node, browsers, Workers, Deno, Bun. |
+| [`pdfnative-cli`](https://www.npmjs.com/package/pdfnative-cli) | **v1.3.0** | Render JSON → PDF, sign (RSA + ECDSA-SHA256, native constant-time crypto by default), inspect, verify (PAdES-T + OCSP/CRL), **merge / split / extract** pages, **annotate** (markup annotations), **govern** (AI-governance / HITL gate), batch, and emit JSON Schemas from the shell. Pins pdfnative `^1.6.0` (semver-accepts 1.7.0): 22 scripts + COLRv1 emoji, `--font math`, PDF bookmarks (`--outline`), layout introspection (`--inspect-layout` / `--debug-layout`), and an agent-native `--json`/`E_*`/`--dry-run`/`--summary` contract. |
+| [`pdfnative-mcp`](https://www.npmjs.com/package/pdfnative-mcp) | **v1.6.0** | Use pdfnative from Claude Desktop, Cursor, Continue, Zed (or any MCP client, stdio or HTTP) — **28 production tools** spanning the engine's full document model: all 13 block kinds in `generate_basic_pdf`, layout options, build-time `encrypt` that keeps the AcroForm, image watermarks, print production (page boxes, bleed, marks, `/UserUnit`, OutputIntent), charts v2 (stacked / area / scatter, dual axis, log & time scales), the complete PAdES ladder B-B → B-LTA (`sign_pdf` with RFC 3161 timestamps, `add_ltv`, `timestamp_pdf`, `verify_pdf ltv: true`), `update_metadata`, the read-only `inspect_layout` pagination preview, honest PDF/A (`embedFonts` / `strict` / diagnostics), six MCP prompts, token-frugal read modes (`verbosity` / `fields`), the network-free `draft_governance_issue` (AI-governance / HITL), and the MCP **2026-07-28** spec with automatic legacy fallback. No outbound request by default — the only permitted egress is operator-configured TSA / OCSP / CRL. Pins pdfnative `^1.7.0`. |
+| [`pdfnative-react`](https://www.npmjs.com/package/pdfnative-react) | **v1.1.0** | Write PDFs as declarative JSX — `<Document>`, `<Page>`, `<Table>`, `<Barcode>`, `<Svg>`, `<FormField>`… compiled on-device to pdfnative blocks by a custom React 19 reconciler. Render functions (`renderToBytes` / `renderToStream` / `renderToFile`), client hooks & components (`usePdf`, `PDFViewer`, `PDFDownloadLink`), and a versioned `DocSpec` grammar (`docSpecSchema()`) for AI agents. Peer: pdfnative ^1.6.0, React ^19.0.0, Node ≥22. (A 1.5 engine would silently drop the new `<Chart>` block.) |
+
+```bash
+npm install pdfnative                 # library
+npm install pdfnative pdfnative-react react   # React renderer (pdfnative + React 19 peers)
+npm install -g pdfnative-cli          # CLI
+npm install -g pdfnative-mcp          # MCP server
+```
+
+Detailed docs: [CLI guide](docs/guides/cli.md) · [MCP guide](docs/guides/mcp.md) · [React guide](docs/guides/react.md) · [Onboarding cheatsheet](docs/guides/onboarding.md).
+
+## Highlights
+
+- **Zero dependencies** — built from scratch in pure TypeScript. Zero runtime dependencies, tree-shakeable, auditable
+- **Conforms to ISO 32000-1** — valid xref tables, /Info metadata, proper font embedding
+- **22 Unicode scripts** — Thai, Japanese, Chinese (SC), Korean, Greek, Devanagari, Telugu, Turkish, Vietnamese, Polish, Arabic, Hebrew, Cyrillic, Georgian, Armenian, Bengali, Tamil, Sinhala, Tibetan, Khmer, Myanmar, Ethiopic
+- **Thai OpenType shaping** — GSUB substitution + GPOS mark-to-base + mark-to-mark positioning
+- **Arabic positional shaping** — GSUB isolated/initial/medial/final forms + lam-alef ligatures
+- **BiDi text layout** — Unicode Bidirectional Algorithm (UAX #9) with isolates (LRI/RLI/FSI/PDI) and explicit embeddings (LRE/RLE/LRO/RLO/PDF) including character-level X4–X5 overrides (v1.3.0). **v1.7.0** implements I1/I2 even embedding levels so digit runs (European, Arabic-Indic, Extended Arabic-Indic) keep logical order in RTL text, and full rule-L4 glyph mirroring through the complete 428-pair `BidiMirroring.txt` table
+- **USE-lite shaping** — `classifyUseCategory` / `classifyClusters` drive joiner classification across the Devanagari, Bengali, and Tamil shapers, fixing nukta+virama, half-form, eyelash-ra, and ya-phalaa edge cases (v1.3.0)
+- **Colour emoji (COLRv1)** — opt-in Noto Color Emoji subset (**expanded to 1167 glyphs in v1.6.0**, ~4.5 MB with the v1.7.0 sequence ligatures, incl. the complete Transport & Map block); solid + linear + radial gradient layers rendered as native PDF Form XObjects; monochrome fallback when not registered (v1.3.0). Variation selectors, ZWJ/ZWNJ, and skin-tone modifiers no longer leave tofu, and glyph `/BBox` is computed from contour bounds so emoji are never clipped (v1.3.0). **Advanced compositing** (v1.4.0): COLRv1 sweep (conic) gradients render as native flat-shaded wedges, and `PaintComposite` separable blend modes (Multiply, Screen, Overlay, Darken, Lighten, …) map to PDF `/BM` ExtGState; structural Porter-Duff modes fall back to monochrome. **Flag & ZWJ sequences** (v1.7.0): 51 flags + 22 ZWJ sequences (families, professions, rainbow/pirate flags, …) resolve through the source font's GSUB into single colour ligature glyphs with a longest-match pre-pass — both VS-16 spellings match, uncovered sequences degrade to the historical per-codepoint rendering, and the CLI bundles any custom set (`--sequences`, `--sequence-list`, skin tones included). [Guide →](docs/guides/colour-emoji.md)
+- **Multi-font fallback** — automatic cross-script font switching with continuation bias
+- **TTF subsetting** — only used glyphs embedded (dramatic file size reduction)
+- **Tagged PDF / PDF/A** — structure tree, /ActualText, XMP metadata, sRGB OutputIntent (PDF/A-1b, 2b, 2u, 3b with embedded file attachments). **Conformance guards** (v1.7.0): configurations that would break the declared PDF/A level (no embedded fonts, DeviceCMYK images) surface a diagnostic — `console.warn` by default, a custom `onDiagnostic` sink, or a thrown error under `strict: true`. [Guide →](docs/guides/pdfa.md)
+- **PDF Encryption (round-trip)** — **write** AES-128 (V4/R4) and AES-256 (V5/R6) encrypted PDFs (RC4 is never emitted), and **read** all of AES-128, AES-256, and legacy RC4 (V1–V4); owner + user passwords, granular permissions. **v1.6.0** adds a Standard Security Handler **decryptor** — `openPdf(bytes, { password })` decrypts transparently, the merge/split API ingests encrypted sources **and re-encrypts its output** (`MergeOptions.encrypt`, AES only, fresh keys) — closing the full *open → edit → re-secure* round trip. [Guide →](docs/guides/pdf-manipulation.md)
+- **Native vector charts** (v1.6.0, **charts v2 in v1.7.0**) — bar, horizontal-bar, line, pie, donut, **stacked bars, area, and scatter** `chart` blocks rendered as pure PDF path operators (zero deps, no rasterisation); multi-series, legends, "nice" axis ticks, negative values, tagged `/Figure` + alt text. v1.7.0 adds a **secondary right axis**, **log and UTC-deterministic time scales**, **per-point data labels**, and x-label collision handling (automatic stride + `labelStride` / `labelRotation`). [Guide →](docs/guides/charts.md)
+- **Text extraction** (v1.6.0) — `extractText()` decodes page content streams into per-page reading-order Unicode text plus optional positioned runs; `/ToUnicode` CMap, `/Encoding /Differences`, and WinAnsi/MacRoman decoding; works on encrypted documents (`{ password }`); hard `maxTextLength` memory cap for untrusted input. [Guide →](docs/guides/text-extraction.md)
+- **Free-form document builder** — headings, paragraphs, lists (incl. **nested / hierarchical** bullet & numbered lists, v1.4.0), tables, images, barcodes, SVG paths, form fields, spacers, page breaks, table of contents. Configurable block limit via `layout.maxBlocks` (default 100 000) for very large reports (v1.3.0)
+- **Smart tables** — multi-page slicing with repeated headers, auto-wrap on column overflow, zebra striping, captions, and smart auto-fit columns (v1.2.0), plus per-cell **borders** (`cellBorders`) and **vertical alignment** (`cellVAlign` / `ColumnDef.vAlign`, v1.4.0). [Guide →](docs/guides/tables.md)
+- **Barcode & QR code generation** — Code 128, EAN-13, QR Code, Data Matrix, PDF417 — pure PDF path operators (no images)
+- **SVG rendering** — path, rect, circle, ellipse, line, polyline, polygon as native PDF operators, plus `<text>` elements rendered as upright PDF text with `x`/`y` positioning and `text-anchor` (start/middle/end) support (v1.5.0)
+- **AcroForm fields** — text, multiline, checkbox, radio, dropdown, listbox with appearance streams (ISO 32000-1 §12.7). **v1.6.0** adds **fill & flatten of existing forms**: `readFormFields()`, `fillForm()` (regenerates appearances), and `flattenForm()` — non-destructive incremental update that preserves prior signatures, **including on encrypted documents** (appended objects are encrypted under the document's existing scheme). [Guide →](docs/guides/form-filling.md)
+- **Digital signatures** — CMS/PKCS#7 detached signatures with RSA (SHA-256/384/512, v1.7.0) + ECDSA-SHA256 (P-256) and X.509 parsing (ISO 32000-1 §12.8). One-call placeholder injection via `addSignaturePlaceholder()` (v1.2.0). Pluggable **native crypto provider** (`setCryptoProvider()` / `PdfSignOptions.provider`, v1.4.0) for constant-time, hardware-backed signing (`node:crypto` / Web Crypto / HSM). **v1.7.0**: PAdES baseline profile (`profile: 'pades'` — ESS signing-certificate-v2, `ETSI.CAdES.detached`), **multiple signatures** (`allowMultiple` + `fieldName` selector), and `listSignatures()` inspection. [Guide →](docs/guides/signatures.md)
+- **Print production** (v1.7.0) — bleed/trim/art/crop **page boxes** (`layout.print`, with a one-line `bleed` shorthand), **crop & registration marks** drawn as pure vector operators outside the TrimBox, `/Trapped` metadata with XMP parity, print-dialog defaults (**duplex**, tray pick, page range, copies), caller-supplied **OutputIntent ICC profile** (tagged mode), and large-format `/UserUnit` (banners, plans). Boxes survive `mergePdfs`/`splitPdf`. Byte-identical output when unused. [Guide →](docs/guides/print.md)
+- **Long-term validation (LTV, PAdES B-B → B-LTA)** (v1.7.0) — RFC 3161 **signature timestamps** (`signPdfBytesWithTimestamp()`), embedded revocation material in `/DSS` + per-signature `/VRI` (`addValidationInfo()` — OCSP RFC 6960 + CRL RFC 5280), and **document timestamps** (`addDocumentTimestamp()`). Network transport is injected (`TimestampProvider` / `RevocationProvider`) — the engine stays offline and zero-dependency; rejected or tampered TSA tokens are never embedded. [Guide →](docs/guides/ltv.md)
+- **Streaming output** — AsyncGenerator-based progressive PDF emission with configurable chunk size, object-boundary page-by-page streaming, and **true constant-memory streaming** (`buildDocumentPDFStreamTrue()`, v1.3.0) where the full PDF binary never materialises. One-call `streamToFile()` drains any stream to disk with back-pressure and `AbortSignal` support (v1.4.0). [Guide →](docs/guides/streaming.md)
+- **Document outline & page labels** — nested bookmarks (`/Outlines` tree, with bold/italic/colour, collapsible nodes via `open: false`, explicit or `outline: 'auto'` from headings) and logical page numbering (`/PageLabels`: decimal, roman, alpha, prefixes, custom start) (v1.4.0). [Guide →](docs/guides/outlines.md)
+- **Viewer preferences** — `PdfLayoutOptions.viewerPreferences` controls initial `/PageLayout` & `/PageMode` plus the `/ViewerPreferences` dict (hide toolbar/menubar, fit/center window, display doc title, non-full-screen mode, reading direction, print scaling) — PDF/A-safe (v1.4.0). **v1.7.0** adds the print-dialog defaults: `duplex`, `pickTrayByPDFSize`, `printPageRange`, `numCopies`. [Guide →](docs/guides/viewer-preferences.md)
+- **Font-data validator** — opt-in `validateFontData()` structurally checks custom font modules (SFNT magic, base64 integrity, cmap coverage, glyph-id range, width array, finite metrics) and returns `{ valid, errors, warnings }` (v1.4.0). [Guide →](docs/guides/font-validation.md)
+- **PDF parser & modifier** — read existing PDFs (tokenizer, xref, object parser, FlateDecode inflate) + incremental modification. Read-only PDF/UA structural checker `validatePdfUA()` (ISO 14289-1: MarkInfo, StructTree, ParentTree, Lang, per-page MCID uniqueness) (v1.3.0). **Page-tree manipulation** (v1.4.0): `mergePdfs()`, `splitPdf()`, `extractPages()` rebuild a clean object graph (inherited attributes resolved, annotations/signatures optionally dropped, deterministic trailer `/ID`, bounded-depth copy, 256 MiB output cap via `maxOutputSize`). **Round-trip readers** (v1.5.0): `getPageLabels()` parses `/PageLabels` back into a typed `PageLabelRange[]`; `getAnnotations()` / `getPageRef()` read page annotations, and `PdfModifier.addAnnotation()` injects new ones incrementally. **v1.6.0**: a Standard Security Handler **decryptor** (`openPdf(bytes, { password })`, RC4/AES-128/AES-256) lets the reader and page-tree API ingest encrypted sources, and **constant-memory streaming** variants `streamMergedPdfs()` / `streamSplitPdf()` / `streamExtractPages()` emit merges/splits in fixed-size chunks (byte-identical to the buffered functions). [Guide →](docs/guides/pdf-manipulation.md)
+- **Markup annotations** — typed annotation model (text, highlight, underline, strikeout, squiggly, square, circle, line, freetext) via `buildAnnotation()` / `buildAnnotationBody()`, plus `PdfReader.getAnnotations()` and `PdfModifier.addAnnotation()` for round-trip read/write (v1.5.0); **v1.6.0** lets `addAnnotation()` operate on encrypted documents (RC4/AES sources, annotations stored encrypted). [Guide →](docs/guides/annotations.md)
+- **Layout debug & inspection** — opt-in `layout: { debug: true }` overlays margin / content / cell boxes for visual layout debugging; `inspectDocumentLayout()` returns a programmatic per-page block-geometry report. Byte-identical when debug is off (v1.5.0). [Guide →](docs/guides/debugging.md)
+- **Math & technical symbols** — bundleable math font under lang `'math'`; mathematical operators, Greek, arrows, and technical symbols route automatically via script detection (v1.5.0)
+- **Font-data tooling** — `pdfnative/tools` exposes `compileFontData()` / `parseFontData()` to build and introspect font-data modules programmatically (v1.5.0)
+- **Image embedding** — JPEG (DCTDecode) and PNG (FlateDecode) with auto-scaling and alignment
+- **Hyperlinks** — PDF link annotations (/URI) with URL validation, blue underlined text, tagged /Link
+- **Header/footer templates** — configurable `PageTemplate` with left/center/right zones and `{page}`/`{pages}`/`{date}`/`{title}` placeholders
+- **Watermarks** — text and image overlays with configurable opacity, rotation, and position (background/foreground)
+- **Table of contents** — auto-generated TOC with internal /GoTo links, dot leaders, and page numbers
+- **FlateDecode compression** — zlib stream compression (50–90% size reduction), zero-dependency, platform-native
+- **Web Worker support** — off-main-thread generation for large datasets
+- **Tree-shakeable** — ESM + CJS dual build with TypeScript declarations
+- **Heavily tested** — 2686+ tests across 123 files, fuzz suite, dual-mode visual-regression suite, performance benchmarks; 95.41% statement coverage measured at the v1.6.0 release, with CI enforcing ≥88% statements / 80% branches / 85% functions / 90% lines (vitest.config.ts)
+- **NPM provenance** — signed builds via GitHub Actions OIDC
+- **On-device generation** — runs in Node, browsers, Workers, Deno, Bun. No SaaS round-trip; documents never leave the calling process unless your application explicitly sends them
+- **No telemetry, no network calls** — verifiable in source. The library never opens a socket, fetches remote fonts, or phones home
+- **AI client integration** — use pdfnative from Claude Desktop, Cursor, Continue, and Zed via [`pdfnative-mcp`](https://github.com/Nizoka/pdfnative-mcp) — **28 production tools** (generate, tables, barcodes, forms, sign with the full PAdES ladder, verify, validate, attachments, extraction, inspect, metadata, layout preview, plus page-tree `merge_pdfs` / `split_pdf` / `extract_pages`)
+- **Command-line interface** — render, sign, verify, inspect, and batch-render PDFs from the shell with [`pdfnative-cli`](https://github.com/Nizoka/pdfnative-cli) — zero-config, scriptable, agent-native (`--json`/`E_*`/`--dry-run`), ideal for CI/CD pipelines
+- **React renderer** — author PDFs as declarative JSX with [`pdfnative-react`](https://github.com/Nizoka/pdfnative-react): `<Document>`/`<Table>`/`<Barcode>` components, `usePdf`/`PDFViewer` client hooks, on-device rendering with no DOM or headless browser
+
+## Installation
+
+```bash
+npm install pdfnative
+```
+
+**Requirements:** Node.js >= 22 | Modern browsers | Deno | Bun
+
+## Documentation
+
+- 🌐 **Website:** [pdfnative.dev](https://pdfnative.dev) — landing page, live in-browser demo with 12 examples, comparisons, benchmarks.
+- 📘 **Quick Start:** [docs/guides/quickstart.md](docs/guides/quickstart.md) — Node.js, browser, Web Worker, streaming.
+- 🏛️ **Architecture:** [docs/guides/architecture.md](docs/guides/architecture.md) — modules, builders, generation pipeline.
+- ♿ **Accessibility:** [docs/guides/accessibility.md](docs/guides/accessibility.md) — tagged PDF, PDF/UA, PDF/A.
+- ❓ **FAQ:** [docs/guides/faq.md](docs/guides/faq.md) — fonts, encryption, signatures, comparisons.
+- 🤖 **Agentic workflows:** [docs/guides/agentic-workflows.md](docs/guides/agentic-workflows.md) — extend the engine at runtime (register fonts without a release) and embed agent-generated images.
+- 🛠️ **Troubleshooting:** [docs/guides/troubleshooting.md](docs/guides/troubleshooting.md) — common pitfalls.
+- 🎮 **Playgrounds:** ten interactive demos at [docs/playgrounds/](docs/playgrounds/) — [extreme-scripts](docs/playgrounds/extreme-scripts.html) (live BiDi/Indic stress tests), [all-scripts](docs/playgrounds/all-scripts.html) (every Unicode script), [scale](docs/playgrounds/scale.html) (1k-100k pages, Web Worker + true streaming), [authoring-plus](docs/playgrounds/authoring-plus.html) (SVG text, layout overlay, annotations), [toolkit](docs/playgrounds/toolkit.html) (bookmarks, page labels, viewer prefs, merge/split/extract, and v1.6.0 form fill/flatten), [charts](docs/playgrounds/charts.html) (native vector charts — all 9 v1.7.0 types), [inspect](docs/playgrounds/inspect.html) (drop any PDF and read a full report, entirely client-side), plus [cli](docs/playgrounds/cli.html), [mcp](docs/playgrounds/mcp.html) and [react](docs/playgrounds/react.html) ecosystem explorers.
+- 🧪 **Sample PDFs:** [scripts/generators/](scripts/generators/) — 242 sample PDFs across 37 categories (48 generators) (see [Sample PDFs](#sample-pdfs) below).
+- 🎓 **Learn:** [docs/learn/](docs/learn/) — an eight-step guided path from installing the package to generating 100,000 pages, live at [pdfnative.dev/learn/](https://pdfnative.dev/learn/).
+- 🤖 **Machine-readable:** [llms.txt](llms.txt) (doc index for LLMs), [AGENTS.md](AGENTS.md) (agent guidance), and [docs/assets/ecosystem.json](docs/assets/ecosystem.json) — the canonical manifest of ecosystem versions and counts, enforced by `npm run verify:docs`.
+
+## Why pdfnative?
+
+pdfnative was designed for teams that need **ISO-compliant, production-grade PDF generation** with zero supply-chain risk. Here is how it compares to other popular JavaScript PDF libraries:
+
+| Feature | pdfnative | jsPDF | pdfkit | pdf-lib | pdfmake |
+|---------|:---------:|:-----:|:------:|:-------:|:------:|
+| Runtime dependencies | **0** | 3 | 6 | 4 | 3 |
+| TypeScript declarations | Built-in | Built-in | @types/* | Built-in | @types/* |
+| PDF/A (ISO 19005) | 1b, 2b, 2u, 3b | — | — | — | — |
+| Tagged PDF / PDF/UA | ✅ | — | ✅ | — | — |
+| Encryption (read + write) | AES-128/256 + RC4 read | write (RC4) | write | — | write |
+| Complex text shaping (GSUB/GPOS) | ✅ Thai, Arabic, Devanagari, Bengali, Tamil | — | Via fontkit | Via @pdf-lib/fontkit | Via pdfkit |
+| BiDi (RTL) layout | ✅ | — | — | — | — |
+| Modify existing PDFs | ✅ (incremental) | — | — | ✅ | — |
+| Forms (create + fill + flatten) | ✅ all three | create | create | create + fill | — |
+| Native charts (vector) | ✅ 9 kinds incl. stacked/area/scatter | — | — | — | — |
+| Digital signatures | ✅ (RSA + ECDSA, PAdES) | — | — | — | — |
+| LTV / timestamps (PAdES B-LTA) | ✅ RFC 3161 + /DSS | — | — | — | — |
+| Print production (bleed/trim boxes, marks) | ✅ | — | — | — | — |
+| Barcode / QR code (native) | ✅ 5 formats | — | — | — | QR |
+| SVG path rendering | ✅ | Plugin | ✅ | Paths only | ✅ |
+| Streaming output | ✅ | — | ✅ | — | ✅ |
+| PDF parser | ✅ | — | — | ✅ | — |
+| Tree-shakeable (ESM) | ✅ | — | — | ✅ | — |
+| NPM provenance (SLSA) | ✅ | — | — | — | ✅ |
+
+> **Data sources:** npm registry metadata and official README/documentation for each library, compared on **2026-07-28** (pdfkit 0.19.1, jsPDF 4.2.1, pdfmake 0.3.11, pdf-lib 1.17.1 — see [docs/data/comparison-2026-07-28.json](docs/data/comparison-2026-07-28.json)). Dependency counts reflect direct `dependencies` listed in each package's published manifest. "—" means the feature is not supported or not documented. Feature claims about third-party libraries are based on their public documentation and may not reflect the latest version — please verify against current releases. Sample PDFs validate with veraPDF (PDF/A) and Adobe Acrobat.
+
+**When to choose another library:** You need advanced vector graphics (complex gradients, arbitrary transforms), rich interactive form scripting (JavaScript actions), or mature ecosystem integrations with existing toolchains.
+
+**When to choose pdfnative:** You need zero-dependency PDF generation with ISO archival compliance (PDF/A), accessibility (tagged PDF), AES encryption, digital signatures, multi-script Unicode support — particularly Arabic/Hebrew BiDi and Thai GSUB/GPOS shaping — form fields, barcode generation, SVG rendering, or the ability to parse and incrementally modify existing PDFs.
+
+## Quick Start
+
+```typescript
+import { buildPDFBytes, downloadBlob } from 'pdfnative';
+
+const pdf = buildPDFBytes({
+  title: 'Monthly Report',
+  infoItems: [
+    { label: 'Period', value: 'January 2026' },
+    { label: 'Account', value: 'Main Account' },
+  ],
+  balanceText: 'Balance: $1,234.56',
+  countText: '42 transactions',
+  headers: ['Date', 'Description', 'Category', 'Amount', 'Status'],
+  rows: [
+    { cells: ['01/15', 'Grocery Store', 'Food', '-$45.00', ''], type: 'debit', pointed: false },
+    { cells: ['01/16', 'Salary', 'Income', '+$3,000.00', 'X'], type: 'credit', pointed: true },
+  ],
+  footerText: 'Generated by MyApp',
+});
+
+// Browser: trigger download
+downloadBlob(pdf, 'report.pdf');
+
+// Node.js: write to file
+import { writeFileSync } from 'fs';
+writeFileSync('report.pdf', pdf);
+```
+
+### Document Builder
+
+Build free-form documents with headings, paragraphs, lists, tables, images, barcodes, and more:
+
+```typescript
+import { buildDocumentPDFBytes } from 'pdfnative';
+
+const pdf = buildDocumentPDFBytes({
+  title: 'Project Report',
+  blocks: [
+    { type: 'toc' },
+    { type: 'heading', text: 'Executive Summary', level: 1 },
+    { type: 'paragraph', text: 'This quarter saw strong growth across all divisions...' },
+    { type: 'image', data: jpegBytes, width: 400, align: 'center', alt: 'Revenue chart' },
+    { type: 'list', items: ['Revenue up 15%', 'Costs down 8%', 'Net profit +23%'], style: 'bullet' },
+    { type: 'table', headers: ['Q1', 'Q2', 'Q3', 'Q4'], rows: [
+      { cells: ['$1.2M', '$1.4M', '$1.6M', '$1.8M'], type: 'credit', pointed: false },
+    ]},
+    { type: 'spacer', height: 20 },
+    { type: 'heading', text: 'Next Steps', level: 2 },
+    { type: 'paragraph', text: 'Focus areas for next quarter include...', align: 'left' },
+    { type: 'link', text: 'View full report online', url: 'https://example.com/report' },
+    { type: 'barcode', format: 'qr', data: 'https://example.com/report', align: 'center' },
+  ],
+  footerText: 'Confidential',
+}, {
+  headerTemplate: { center: 'Project Report', right: '{date}' },
+  footerTemplate: { left: 'Confidential', right: 'Page {page} of {pages}' },
+});
+```
+
+## Unicode Font Support
+
+For non-Latin scripts, register font data loaders (lazy-loaded on demand):
+
+```typescript
+import { registerFonts, loadFontData, buildPDFBytes } from 'pdfnative';
+
+registerFonts({
+  th: () => import('pdfnative/fonts/noto-thai-data.js'),
+  ja: () => import('pdfnative/fonts/noto-jp-data.js'),
+  zh: () => import('pdfnative/fonts/noto-sc-data.js'),
+  ko: () => import('pdfnative/fonts/noto-kr-data.js'),
+  el: () => import('pdfnative/fonts/noto-greek-data.js'),
+  hi: () => import('pdfnative/fonts/noto-devanagari-data.js'),
+  tr: () => import('pdfnative/fonts/noto-turkish-data.js'),
+  vi: () => import('pdfnative/fonts/noto-vietnamese-data.js'),
+  pl: () => import('pdfnative/fonts/noto-polish-data.js'),
+  ar: () => import('pdfnative/fonts/noto-arabic-data.js'),
+  he: () => import('pdfnative/fonts/noto-hebrew-data.js'),
+  ru: () => import('pdfnative/fonts/noto-cyrillic-data.js'),
+  ka: () => import('pdfnative/fonts/noto-georgian-data.js'),
+  hy: () => import('pdfnative/fonts/noto-armenian-data.js'),
+  bn: () => import('pdfnative/fonts/noto-bengali-data.js'),
+  ta: () => import('pdfnative/fonts/noto-tamil-data.js'),
+  te: () => import('pdfnative/fonts/noto-telugu-data.js'), // v1.3.0
+  si: () => import('pdfnative/fonts/noto-sinhala-data.js'), // v1.3.0
+  bo: () => import('pdfnative/fonts/noto-tibetan-data.js'), // v1.3.0
+  km: () => import('pdfnative/fonts/noto-khmer-data.js'), // v1.3.0
+  my: () => import('pdfnative/fonts/noto-myanmar-data.js'), // v1.3.0
+  am: () => import('pdfnative/fonts/noto-ethiopic-data.js'), // v1.3.0
+  // v1.1.0+ — optional Latin fallback for PDF/A documents with curly quotes,
+  // em-dash, ellipsis, etc. (activates automatically when needed):
+  latin: () => import('pdfnative/fonts/noto-sans-data.js'),
+  // v1.1.0+ — optional monochrome emoji:
+  emoji: () => import('pdfnative/fonts/noto-emoji-data.js'),
+});
+
+const thaiFont = await loadFontData('th');
+
+const pdf = buildPDFBytes({
+  title: 'รายงานประจำเดือน',
+  // ... other params
+  fontEntries: thaiFont ? [{ fontData: thaiFont, fontRef: '/F3', lang: 'th' }] : [],
+});
+```
+
+### Supported Languages
+
+| Language | Code | Font | Script |
+|----------|------|------|--------|
+| Thai | `th` | Noto Sans Thai | GSUB + GPOS shaping |
+| Japanese | `ja` | Noto Sans JP | CJK ideographs + kana |
+| Chinese (Simplified) | `zh` | Noto Sans SC | CJK ideographs |
+| Korean | `ko` | Noto Sans KR | Hangul syllables |
+| Greek | `el` | Noto Sans Greek | Greek alphabet |
+| Hindi (Devanagari) | `hi` | Noto Sans Devanagari | GSUB conjuncts + GPOS marks |
+| Turkish | `tr` | Noto Sans Turkish | Latin extended (İ/ı) |
+| Vietnamese | `vi` | Noto Sans Vietnamese | Latin + combining marks |
+| Polish | `pl` | Noto Sans Polish | Latin extended (Ł/ł) |
+| Arabic | `ar` | Noto Sans Arabic | GSUB positional shaping |
+| Hebrew | `he` | Noto Sans Hebrew | Right-to-left script |
+| Russian (Cyrillic) | `ru` | Noto Sans | Cyrillic alphabet |
+| Georgian | `ka` | Noto Sans Georgian | Mkhedruli script |
+| Armenian | `hy` | Noto Sans Armenian | Armenian alphabet |
+| Bengali | `bn` | Noto Sans Bengali | GSUB conjuncts + GPOS marks |
+| Tamil | `ta` | Noto Sans Tamil | GSUB ligatures + split vowels |
+| Latin (PDF/A) | `latin` | Noto Sans VF | WinAnsi-extended Latin (curly quotes, em-dash, ellipsis…) |
+| Emoji | `emoji` | Noto Emoji | Monochrome emoji (BMP/SMP, Fitzpatrick, ZWJ, VS-15/16) |
+
+## Multi-Font (Mixed Scripts)
+
+Generate PDFs with multiple scripts in the same document:
+
+```typescript
+const fonts = await Promise.all([
+  loadFontData('th'),
+  loadFontData('ja'),
+  loadFontData('zh'),
+]);
+
+const fontEntries = fonts
+  .filter(Boolean)
+  .map((fd, i) => ({ fontData: fd!, fontRef: `/F${3 + i}`, lang: ['th', 'ja', 'zh'][i] }));
+
+const pdf = buildPDFBytes({
+  title: 'Multi-Language Report',
+  headers: ['Date', 'Description', 'Category', 'Amount', 'Status'],
+  rows: [
+    { cells: ['01/01', 'English text', 'Test', '+100', 'OK'], type: 'credit', pointed: false },
+    { cells: ['01/02', 'ข้อความไทย', 'ทดสอบ', '-50', ''], type: 'debit', pointed: false },
+    { cells: ['01/03', '日本語テキスト', 'テスト', '+200', '済'], type: 'credit', pointed: true },
+  ],
+  // ... other params
+  fontEntries,
+});
+```
+
+## Web Worker (Large Datasets)
+
+```typescript
+import { createPDF } from 'pdfnative';
+
+const pdf = await createPDF(params, {
+  workerUrl: new URL('pdfnative/worker', import.meta.url),
+  threshold: 500, // use Worker above 500 rows
+  timeout: 30000, // Worker timeout in ms (default: 60000)
+  onProgress: (percent) => console.log(`${percent}%`),
+});
+```
+
+For lower-level control, use `generatePDFInWorker` directly with `WorkerGenerationOptions`:
+
+```typescript
+import { generatePDFInWorker } from 'pdfnative';
+import type { WorkerGenerationOptions } from 'pdfnative';
+
+const options: WorkerGenerationOptions = {
+  timeout: 15000,
+  onProgress: (percent) => console.log(`${percent}%`),
+};
+
+const pdf = await generatePDFInWorker(workerUrl, params, options);
+```
+
+## Layout Customization
+
+```typescript
+const pdf = buildPDFBytes(params, {
+  pageWidth: 595.28,   // A4 (default)
+  pageHeight: 841.89,  // A4 (default)
+  margins: { t: 45, r: 36, b: 35, l: 36 },
+  colors: {
+    title: '#2563EB',           // hex — primary format
+    credit: [15, 145, 121],     // RGB tuple [0–255]
+    debit: '0.863 0.149 0.149', // PDF operator string [0.0–1.0]
+    // ... see PdfColors type
+  },
+  columns: [
+    { f: 0.15, a: 'l', mx: 12, mxH: 12 },
+    { f: 0.35, a: 'l', mx: 50, mxH: 50 },
+    { f: 0.20, a: 'r', mx: 20, mxH: 20 },
+    { f: 0.30, a: 'r', mx: 30, mxH: 30 },
+  ],
+});
+```
+
+### Color Formats
+
+All color values accept three formats:
+
+| Format | Example | Description |
+|--------|---------|-------------|
+| Hex string | `'#2563EB'` or `'#26E'` | Primary format — `#RRGGBB` or `#RGB` |
+| RGB tuple | `[37, 99, 235]` | Array with values 0–255 |
+| PDF operator | `'0.145 0.388 0.922'` | Raw PDF RGB string (0.0–1.0) |
+
+```typescript
+import { parseColor } from 'pdfnative';
+
+parseColor('#2563EB');           // '0.145 0.388 0.922'
+parseColor([37, 99, 235]);       // '0.145 0.388 0.922'
+parseColor('0.145 0.388 0.922'); // '0.145 0.388 0.922'
+```
+
+All inputs are validated and normalized before interpolation into PDF content streams, preventing operator injection.
+
+### Font Sizes
+
+Customize font sizes for each zone (title, info bar, table header, table cells, footer):
+
+```typescript
+const pdf = buildPDFBytes(params, {
+  fontSizes: {
+    title: 20,   // Title text (default: 16)
+    info: 10,    // Info bar items (default: 9)
+    th: 9,       // Table header cells (default: 8)
+    td: 8,       // Table body cells (default: 7.5)
+    ft: 8,       // Footer text (default: 7)
+  },
+});
+```
+
+| Zone | Key | Default | Description |
+|------|-----|---------|-------------|
+| Title | `title` | 16 | PDF title text |
+| Info bar | `info` | 9 | Key-value pairs below title |
+| Table header | `th` | 8 | Column header row |
+| Table cells | `td` | 7.5 | Data row cells |
+| Footer | `ft` | 7 | Page footer text |
+
+All values are in PDF points (1pt = 1/72 inch). Partial overrides are supported — unspecified keys use defaults.
+
+## Building Custom Font Data
+
+### Obtaining TTF Files
+
+For Noto Sans fonts, download the raw `.ttf` file directly from the [noto-fonts GitHub repository](https://github.com/notofonts):
+
+1. Navigate to the font's GitHub repository (e.g., `github.com/notofonts/bengali`)
+2. Find the TTF file under `fonts/NotoSansBengali/unhinted/ttf/` (or similar path)
+3. Click the file, then click **"Download raw file"** (or use the raw URL)
+4. Save it to `fonts/ttf/`
+
+No zip download or extraction needed — each TTF is a standalone file you can download directly.
+
+### Building the Data Module
+
+Convert any TTF font into an importable data module:
+
+```bash
+npx pdfnative-build-font fonts/ttf/MyFont.ttf fonts/my-font-data.js
+```
+
+The tool extracts cmap, widths, metrics, GSUB, GPOS, and embeds the raw TTF as base64.
+
+### Full colour-emoji coverage (`pdfnative-build-emoji-font`)
+
+The bundled colour-emoji module (`pdfnative/fonts/noto-color-emoji-data.js`)
+ships a lean curated subset to keep the package small. When you need glyphs
+beyond that subset — up to the **full ~3,600-glyph** Noto Color Emoji set — a
+second bundled binary generates a custom data module on demand, so even
+**pdfnative-only** users get full coverage without the package ever carrying the
+~32 MB source font:
+
+```bash
+# Download the pinned Noto Color Emoji (SHA-256 verified) and emit every glyph
+npx pdfnative-build-emoji-font --download --all --out my-color-emoji-data.js
+
+# …or build from a local TTF, selecting only the glyphs you need
+npx pdfnative-build-emoji-font --ttf NotoColorEmoji-Regular.ttf \
+  --codepoints "1F600,1F680,2764" --out my-color-emoji-data.js
+```
+
+Select glyphs with `--all`, `--preset`, `--codepoints`, or `--ranges`, then
+register the generated module under lang `'emoji'`. See the
+[Colour-emoji CLI guide](docs/guides/colour-emoji-cli.md).
+
+## Agentic workflows
+
+pdfnative is shaped so an AI agent can do more than *call* the engine — it can
+**extend** it at runtime and **feed it content it generated itself**, without
+waiting for a library release. Both patterns use already-shipped, public APIs.
+
+**1. Extend the engine at runtime — no release required.** The font registry is a
+runtime API. An agent can compile a TTF/OTF in memory and register it on the spot,
+so a document renders the moment it needs a new script, symbol set, or brand font:
+
+```js
+import { registerFont, loadFontData, buildDocumentPDFBytes } from 'pdfnative';
+registerFont('th', () => import('pdfnative/fonts/noto-thai-data.js'));
+const th = await loadFontData('th');
+if (!th) throw new Error('Thai font failed to load');
+const bytes = buildDocumentPDFBytes({
+  title: 'Thai demo',
+  blocks: [{ type: 'paragraph', text: 'สวัสดีชาวโลก' }],
+  fontEntries: [{ fontData: th, fontRef: '/F3', lang: 'th' }], // /F1 and /F2 are reserved
+});
+```
+
+This is how the bundled **Noto Sans Math** font existed as a *working runtime
+pattern* before it shipped as a default in v1.5.0. Use `compileFontData()` to emit
+a reusable `*-data.js` module (byte-identical to `npx pdfnative-build-font`).
+
+**2. Embed agent-generated images.** Image-generating agents (e.g. Antigravity,
+ChatGPT, and other multimodal assistants) can pipe a generated PNG/JPEG straight
+into a document — via the `image` block (library / CLI) or the `embed_image` MCP
+tool. pdfnative parses and embeds it natively (no rasterization) and validates it
+at the boundary.
+
+Runtime extensibility is **not** autonomous modification of the published package:
+the agent extends its own in-process instance; the repository is only ever changed
+by a human under the [AI-governance / human-in-the-loop contract](docs/guides/ai-governance.md).
+See the [Agentic workflows guide](docs/guides/agentic-workflows.md) for the full walkthrough.
+
+## Visual PDF Inspection
+
+<a id="sample-pdfs"></a>
+
+Generate sample PDFs for all supported languages to visually verify output:
+
+```bash
+npm run test:generate
+```
+
+This creates **242 sample PDFs** in `test-output/` (git-ignored), organized in 37 categories produced by 48 generators (including `charts/` native vector charts, `bidi/` Persian and mirroring showcases, `signatures/` LTV pipelines, and `print/` prepress output added in v1.7.0).
+See [scripts/README.md](scripts/README.md) for the modular generator architecture.
+
+### Financial Statements (per language)
+
+| File | Content |
+|------|---------|
+| `sample-latin.pdf` | English / Helvetica |
+| `sample-th.pdf` | Thai with GSUB + GPOS shaping |
+| `sample-ja.pdf` | Japanese (CJK ideographs) |
+| `sample-zh.pdf` | Chinese Simplified |
+| `sample-ko.pdf` | Korean (Hangul) |
+| `sample-el.pdf` | Greek |
+| `sample-hi.pdf` | Hindi (Devanagari) |
+| `sample-tr.pdf` | Turkish (İ/ı special casing) |
+| `sample-vi.pdf` | Vietnamese (combining marks) |
+| `sample-pl.pdf` | Polish (Ł/ł) |
+| `sample-ar.pdf` | Arabic (RTL, positional shaping) |
+| `sample-he.pdf` | Hebrew (RTL) |
+| `sample-ru.pdf` | Russian (Cyrillic) |
+| `sample-ka.pdf` | Georgian (Mkhedruli) |
+| `sample-hy.pdf` | Armenian |
+| `sample-bn.pdf` | Bengali (GSUB conjuncts + GPOS marks) |
+| `sample-ta.pdf` | Tamil (GSUB + split vowel decomposition) |
+| `sample-multi.pdf` | Mixed: all 22 scripts in one PDF |
+| `sample-pagination.pdf` | 200 rows, multi-page layout |
+
+### Diverse Use Cases (non-financial)
+
+| File | Content |
+|------|---------|
+| `diverse-student-transcript.pdf` | University academic transcript (Latin) |
+| `diverse-recipe-th.pdf` | Thai recipe — Tom Yum Goong ingredients (Thai) |
+| `diverse-server-ja.pdf` | Server monitoring dashboard (Japanese) |
+| `diverse-inventory-zh.pdf` | Warehouse product inventory (Chinese) |
+| `diverse-sports-ko.pdf` | K-League football standings (Korean) |
+| `diverse-library-el.pdf` | Classical Greek library catalog (Greek) |
+| `diverse-medical-hi.pdf` | Blood test lab results (Hindi) |
+| `diverse-menu-tr.pdf` | Turkish restaurant dinner menu (Turkish) |
+| `diverse-weather-vi.pdf` | Weekly weather forecast — Hanoi (Vietnamese) |
+| `diverse-train-pl.pdf` | Train schedule — Warsaw (Polish) |
+| `diverse-marketplace-ar.pdf` | Gold marketplace catalog — Dubai (Arabic) |
+| `diverse-museum-he.pdf` | Museum exhibition catalog — Jerusalem (Hebrew) |
+
+### Alphabet / Character Coverage
+
+| File | Content |
+|------|---------|
+| `alphabet-thai.pdf` | 44 consonants, vowels, tone marks, digits |
+| `alphabet-japanese.pdf` | Hiragana, Katakana, Kanji numerals & common |
+| `alphabet-chinese.pdf` | 121 characters by category (HSK frequency) |
+| `alphabet-korean.pdf` | Hangul jamo, syllables, complex clusters |
+| `alphabet-greek.pdf` | Full uppercase/lowercase, accented, archaic |
+| `alphabet-devanagari.pdf` | Vowels, consonants, matras, conjuncts, digits |
+| `alphabet-turkish.pdf` | 29 letters, İ/ı dotted-I distinction test |
+| `alphabet-vietnamese.pdf` | 7 base vowels × 6 tones, all diacritics |
+| `alphabet-polish.pdf` | 32 letters, digraphs, pangram |
+| `alphabet-arabic.pdf` | 28 letters, harakat, numerals, ligatures |
+| `alphabet-hebrew.pdf` | 22 letters, final forms, vowel points |
+| `alphabet-cyrillic.pdf` | 33 Russian letters, Ukrainian/Serbian extended |
+| `alphabet-georgian.pdf` | 33 Mkhedruli letters, Asomtavruli |
+| `alphabet-armenian.pdf` | 38 letters, ligatures |
+| `alphabet-bengali.pdf` | Vowels, consonants, conjuncts, digits |
+| `alphabet-tamil.pdf` | Vowels, consonants, compound characters, digits |
+
+### PDF/A Conformance Variants
+
+| File | Content |
+|------|---------|
+| `tagged-pdfa2b-default.pdf` | PDF/A-2b (tagged=true, default) |
+| `tagged-pdfa2b-explicit.pdf` | PDF/A-2b (tagged='pdfa2b', explicit) |
+| `tagged-pdfa1b.pdf` | PDF/A-1b (tagged='pdfa1b', legacy) |
+| `tagged-pdfa2u.pdf` | PDF/A-2u (tagged='pdfa2u', Unicode) |
+| `tagged-pdfa3b.pdf` | PDF/A-3b (tagged='pdfa3b', embedded file attachments) |
+
+### Encrypted PDFs
+
+| File | Content |
+|------|---------|
+| `encrypted-aes128.pdf` | AES-128 (V4/R4) owner-only |
+| `encrypted-aes256.pdf` | AES-256 (V5/R6) owner-only |
+| `encrypted-aes128-user.pdf` | AES-128 with user+owner passwords |
+| `encrypted-aes256-user.pdf` | AES-256 with user+owner passwords |
+| `encrypted-readonly.pdf` | AES-128 read-only (no copy/modify) |
+| `encrypted-noprint.pdf` | AES-128 fully restricted |
+
+**Sample passwords** (for testing only — all documented in `scripts/generate-samples.ts`):
+
+| File | Owner Password | User Password |
+|------|---------------|---------------|
+| `encrypted-aes128.pdf` | `owner123` | _(none — opens freely)_ |
+| `encrypted-aes256.pdf` | `owner256` | _(none — opens freely)_ |
+| `encrypted-aes128-user.pdf` | `owner123` | `user456` |
+| `encrypted-aes256-user.pdf` | `owner256` | `user789` |
+| `encrypted-readonly.pdf` | `owner-ro` | _(none — opens freely)_ |
+| `encrypted-noprint.pdf` | `owner-np` | _(none — opens freely)_ |
+| `doc-encrypted-aes128.pdf` | `docowner` | `docuser` |
+| `doc-encrypted-aes256.pdf` | `strongowner256` | _(none — opens freely)_ |
+
+### Document Builder Samples
+
+| File | Content |
+|------|---------|
+| `doc-headings-paragraphs.pdf` | H1/H2/H3 + paragraphs with text wrapping |
+| `doc-lists.pdf` | Bullet + numbered lists |
+| `doc-links.pdf` | External hyperlink annotations |
+| `doc-table.pdf` | Embedded table in document |
+| `doc-spacer-pagebreak.pdf` | Spacers + forced page breaks (3 pages) |
+| `doc-encrypted-aes128.pdf` | Document builder + AES-128 encryption |
+| `doc-encrypted-aes256.pdf` | Document builder + AES-256 encryption |
+| `doc-image.pdf` | Image embedding (JPEG, centered) |
+| `doc-custom-colors.pdf` | Color formats (hex, tuple, PDF operator) |
+| `doc-japanese.pdf` | Japanese Unicode document (headings, lists, table) |
+| `doc-arabic.pdf` | Arabic RTL document (headings, lists, table, BiDi) |
+| `doc-hebrew.pdf` | Hebrew RTL document (headings, lists, table, BiDi) |
+| `doc-thai.pdf` | Thai user manual (GSUB+GPOS shaping, pricing table) |
+| `doc-bengali.pdf` | Bengali document (GSUB conjuncts + GPOS marks) |
+| `doc-tamil.pdf` | Tamil document (GSUB substitution + split vowels) |
+| `doc-devanagari.pdf` | Hindi (Devanagari) document — GSUB conjuncts, reph reordering, matra reordering, split vowels |
+| `doc-telugu.pdf` | Telugu document (virama conjuncts + GPOS marks, no reph) |
+| `doc-sinhala.pdf` | Sinhala document (virama conjuncts + pre-base kombuva reordering) |
+| `doc-tibetan.pdf` | Tibetan document (vertical subjoined-consonant stacking) |
+| `doc-khmer.pdf` | Khmer document (USE-lite: coeng subscripts, pre-base vowels) |
+| `doc-myanmar.pdf` | Myanmar document (USE-lite: medials, pre-base reordering) |
+| `doc-amharic.pdf` | Amharic/Ethiopic document (syllabic abugida, no reordering) |
+| `doc-chinese-catalog.pdf` | Chinese product catalog (tables, ordering info) |
+| `doc-multi-language.pdf` | Multi-language showcase: all 22 Unicode scripts in one PDF |
+| `doc-invoice.pdf` | Invoice template (line items, totals, payment link) |
+| `doc-report-multipage.pdf` | 3-page technical report (7 sections, 4 tables) |
+| `doc-contract-bilingual.pdf` | Bilingual EN/AR contract (legal sections, signatures) |
+| `doc-showcase-all-blocks.pdf` | All 13 block types in one PDF |
+
+### Compressed PDFs (FlateDecode)
+
+| File | Content |
+|------|---------|
+| `compressed-latin-100rows.pdf` | 100-row Latin table (87% smaller) |
+| `uncompressed-latin-100rows.pdf` | Same 100-row table without compression (baseline) |
+| `compressed-japanese.pdf` | Japanese CIDFont + TTF subset (62% smaller) |
+| `compressed-arabic.pdf` | Arabic RTL + GSUB shaping (compressed) |
+| `compressed-thai.pdf` | Thai GSUB+GPOS shaping (compressed) |
+| `compressed-tagged-pdfa2b.pdf` | FlateDecode + Tagged PDF/A-2b (XMP uncompressed) |
+| `compressed-encrypted-aes128.pdf` | FlateDecode + AES-128 encryption |
+| `doc-compressed.pdf` | Document builder with FlateDecode |
+
+### Stress Test PDFs
+
+| File | Content |
+|------|---------|  
+| `stress-test-10k-rows.pdf` | 10,000-row table (167 pages, 4.3MB) |
+| `doc-extreme-bidi-wrapping.pdf` | Extreme BiDi mixed-script text wrapping |
+| `table-heavy-text-overflow.pdf` | Dense table with heavy text overflow |
+| `media-rich-document.pdf` | Media-rich document with multiple images |
+| `tagged-accessibility-complex.pdf` | Complex tagged PDF/A accessibility tree |
+| `layout-extreme-customization.pdf` | Extreme layout customization (margins, columns, colors) |
+
+### Edge-Case Stress Tests
+
+| File | Content |
+|------|---------|  
+| `doc-unbreakable-text.pdf` | 1000-char words with no spaces (DNA, URL, Base64) |
+| `table-micro-columns.pdf` | Extreme column fractions (f=0.025, mx=1) |
+| `doc-link-annotation-bomb.pdf` | 500 link annotations across 10 pages |
+| `zero-content-empty-table.pdf` | Table with headers but 0 rows |
+| `zero-content-empty-doc.pdf` | Document with no blocks |
+| `zero-content-empty-strings.pdf` | Empty headings, paragraphs, and list items |
+| `doc-heavy-buffer-5mb.pdf` | 5 MB synthetic JPEG embedded (memory stress) |
+
+### Barcode & QR Code Samples
+
+| File | Content |
+|------|---------|
+| `barcode-showcase.pdf` | All 5 formats: Code 128, EAN-13, QR Code, Data Matrix, PDF417 |
+| `barcode-alignment-sizing.pdf` | Alignment (left/center/right) and custom size variations |
+| `barcode-tagged-pdfa.pdf` | Barcodes in tagged PDF/A-2b mode (/Figure structure elements) |
+
+### SVG Path Rendering Samples
+
+| File | Content |
+|------|---------|
+| `svg-basic-shapes.pdf` | Rect, circle, ellipse, line, polyline, polygon |
+| `svg-complex-paths.pdf` | Cubic/quadratic Bézier curves, arcs, combined paths |
+| `svg-tagged-pdfa.pdf` | SVG elements in tagged PDF/A-2b mode |
+
+### Form Field Samples
+
+| File | Content |
+|------|---------|
+| `form-fields.pdf` | All field types: text, multiline, checkbox, radio, dropdown, listbox |
+| `form-contact.pdf` | Contact form with name, email, message, and submit fields |
+
+### Digital Signature Samples
+
+| File | Content |
+|------|---------|
+| `sig-rsa-self-signed.pdf` | RSA PKCS#1 v1.5 self-signed signature |
+| `sig-ecdsa-p256.pdf` | ECDSA P-256 digital signature |
+| `sig-multi-field.pdf` | PDF with multiple signature fields |
+
+### Streaming Output Samples
+
+| File | Content |
+|------|---------|
+| `streaming-document.pdf` | Document streamed via `buildDocumentPDFStream()` |
+| `streaming-table.pdf` | Table streamed via `buildPDFStream()` |
+
+### PDF Parser & Modifier Samples
+
+| File | Content |
+|------|---------|
+| `parser-original.pdf` | Generated → parsed → verified round-trip |
+| `parser-modified.pdf` | Generated → parsed → modified → incremental save |
+| `parser-document.pdf` | Document builder → parser round-trip verification |
+
+### Outline & Page Label Samples (v1.4.0)
+
+| File | Content |
+|------|---------|
+| `outline/outline-explicit.pdf` | Nested bookmarks (`/Outlines`) + roman/decimal page labels |
+| `outline/outline-auto.pdf` | `outline: 'auto'` — bookmarks derived from headings |
+| `outline/page-labels.pdf` | Roman front matter + prefixed appendix page labels |
+
+### PDF Manipulation Samples (v1.4.0)
+
+| File | Content |
+|------|---------|
+| `manipulation/merged.pdf` | `mergePdfs()` — multiple documents combined |
+| `manipulation/split-report.pdf` | `splitPdf()` — first page range |
+| `manipulation/split-invoice.pdf` | `splitPdf()` — second page range |
+| `manipulation/extract-reordered.pdf` | `extractPages()` — selected pages, reordered |
+| `manipulation/streamed.pdf` | `streamToFile()` — document streamed straight to disk |
+
+## API Reference
+
+### Core
+
+| Function | Description |
+|----------|-------------|
+| `buildPDF(params, layout?)` | Build table-centric PDF as binary string |
+| `buildPDFBytes(params, layout?)` | Build table-centric PDF as `Uint8Array` |
+| `buildDocumentPDF(params, layout?)` | Build free-form document PDF as binary string |
+| `buildDocumentPDFBytes(params, layout?)` | Build free-form document PDF as `Uint8Array` |
+| `wrapText(text, maxWidth, fontSize, enc)` | Word-wrap text into lines |
+| `createPDF(params, options?)` | Smart dispatch (Worker or main thread) |
+| `initNodeCompression()` | Initialize native zlib for ESM (call once before `compress: true`) |
+| `downloadBlob(bytes, filename)` | Trigger browser download |
+| `toBytes(str)` | Convert binary string to `Uint8Array` |
+| `slugify(str)` | Sanitize string for filename |
+
+### Image Support
+
+| Function | Description |
+|----------|-------------|
+| `parseImage(bytes)` | Auto-detect and parse JPEG or PNG |
+| `parseJPEG(bytes)` | Parse JPEG image (DCTDecode) |
+| `parsePNG(bytes)` | Parse PNG image (FlateDecode) |
+| `detectImageFormat(bytes)` | Detect JPEG or PNG from magic bytes |
+| `buildImageXObject(img, smaskObj?)` | Build PDF Image XObject dictionary |
+| `buildImageOperators(ref, x, y, w, h)` | Build `q cm Do Q` content stream operators |
+
+### Link Annotations
+
+| Function | Description |
+|----------|-------------|
+| `validateURL(url)` | Validate URL scheme (http/https/mailto only) |
+| `buildLinkAnnotation(annot)` | Build PDF /Link annotation with /URI action |
+| `buildInternalLinkAnnotation(link)` | Build PDF /Link with /GoTo action |
+| `isLinkAnnotation(annot)` | Type guard for LinkAnnotation |
+
+### BiDi & Arabic/Hebrew Shaping
+
+| Function | Description |
+|----------|-------------|
+| `resolveBidiRuns(text)` | Resolve text into BiDi runs with levels |
+| `containsRTL(text)` | Check if text contains RTL characters |
+| `shapeArabicText(str, fontData)` | Arabic GSUB positional shaping |
+| `containsArabic(text)` | Check for Arabic characters |
+| `containsHebrew(text)` | Check for Hebrew characters |
+
+### Barcode & QR Code
+
+| Function | Description |
+|----------|-------------|
+| `renderBarcode(format, data, x, y, opts?)` | Unified barcode renderer (dispatches to format-specific function) |
+| `encodeCode128(data)` | Encode data into Code 128 barcode pattern (ISO 15417) |
+| `renderCode128(data, x, y, w, h)` | Render Code 128 barcode as PDF path operators |
+| `ean13CheckDigit(digits)` | Compute EAN-13 check digit (ISO 15420) |
+| `renderEAN13(data, x, y, w, h)` | Render EAN-13 barcode with guard bars and digits |
+| `generateQR(data, ecLevel?)` | Generate QR Code matrix (ISO 18004) |
+| `renderQR(data, x, y, size, ecLevel?)` | Render QR Code as PDF path operators |
+| `generateDataMatrix(data)` | Generate Data Matrix ECC 200 matrix (ISO 16022) |
+| `renderDataMatrix(data, x, y, size)` | Render Data Matrix as PDF path operators |
+| `encodePDF417(data, ecLevel?)` | Encode data into PDF417 codewords (ISO 15438) |
+| `renderPDF417(data, x, y, w, h, ecLevel?)` | Render PDF417 barcode as PDF path operators |
+
+### SVG Rendering
+
+| Function | Description |
+|----------|-------------|
+| `parseSvgPath(d)` | Parse SVG path `d` attribute into segments |
+| `renderSvg(segments, options?)` | Render SVG segments (paths + `<text>`) as PDF operators |
+
+### Markup Annotations
+
+| Function | Description |
+|----------|-------------|
+| `buildAnnotation(annot, objNum)` | Build a full markup annotation indirect object (v1.5.0) |
+| `buildAnnotationBody(annot)` | Build a markup annotation dictionary body (for the modifier) (v1.5.0) |
+
+Supported `MarkupAnnotation` types: `text`, `highlight`, `underline`, `strikeout`, `squiggly`, `square`, `circle`, `line`, `freetext`.
+
+### Layout Debug & Inspection
+
+| Function | Description |
+|----------|-------------|
+| `inspectDocumentLayout(params, layout?)` | Return a programmatic per-page block-geometry `LayoutInspection` (v1.5.0) |
+
+Enable the visual overlay via `layout: { debug: true }` or a granular `LayoutDebugOptions` (`showMargins` / `showContentBounds` / `showCells`). Byte-identical when debug is off.
+
+### Font-Data Tools (`pdfnative/tools`)
+
+| Function | Description |
+|----------|-------------|
+| `compileFontData(buffer, opts?)` | Compile a TTF/OTF `Uint8Array` into a font-data module source string (v1.5.0) |
+| `parseFontData(buffer, opts?)` | Parse a TTF/OTF `Uint8Array` into a `FontDataObject` (metrics, cmap, widths, glyph coverage) (v1.5.0) |
+
+### AcroForm Fields
+
+| Function | Description |
+|----------|-------------|
+| `buildFormWidget(field, objNum, pageRef)` | Build form field widget annotation + appearance stream |
+| `buildAcroFormDict(fieldRefs)` | Build `/AcroForm` dictionary for catalog |
+| `buildRadioGroupParent(group)` | Build radio button group parent object |
+| `buildAppearanceStreamDict(width, height)` | Build appearance stream dictionary |
+| `defaultFieldHeight(type)` | Default height by field type |
+
+### Digital Signatures
+
+| Function | Description |
+|----------|-------------|
+| `buildSigDict(options)` | Build `/Sig` dictionary with ByteRange/Contents placeholders (`subFilter: 'ETSI.CAdES.detached'` for PAdES, v1.7.0) |
+| `buildDocTimeStampDict(contentsSize?)` | Build a `/DocTimeStamp` dictionary variant (ISO 32000-2 §12.8.5, v1.7.0) |
+| `signPdfBytes(pdf, options)` | Sign a PDF with CMS/PKCS#7 detached signature (`profile: 'pades'`, `digestAlgorithm`, multi-signature `fieldName` selector, v1.7.0) |
+| `signPdfBytesWithTimestamp(pdf, options)` | Sign + embed a verified RFC 3161 signature timestamp (PAdES B-T, v1.7.0) |
+| `listSignatures(pdf)` | Enumerate signature fields — SubFilter, ByteRange, /Contents, placeholder/timestamp flags (v1.7.0) |
+| `collectValidationInfo(pdf, opts?)` | Gather certificates + OCSP/CRL material for every signature via the injected `RevocationProvider` (v1.7.0) |
+| `embedValidationInfo(pdf, data)` | Write pre-collected LTV material as `/DSS` + `/VRI` — sync, offline, deterministic (v1.7.0) |
+| `addValidationInfo(pdf, opts?)` | Collect + embed in one call (PAdES B-LT, v1.7.0) |
+| `addDocumentTimestamp(pdf, opts?)` | Append a `/DocTimeStamp` revision (PAdES B-LTA, v1.7.0) |
+| `estimateContentsSize(certSizes, algorithm?, opts?)` | Estimate `/Contents` size (`{ timestamp: true }` adds RFC 3161 headroom, v1.7.0) |
+| `setCryptoProvider(provider)` | Install (or clear with `null`) a global native signature provider (v1.4.0) |
+| `getCryptoProvider()` | Return the current global `CryptoProvider`, or `null` (v1.4.0) |
+| `setTimestampProvider(provider)` / `getTimestampProvider()` | Global RFC 3161 transport — TimeStampReq bytes in, TimeStampResp bytes out (v1.7.0) |
+| `setRevocationProvider(provider)` / `getRevocationProvider()` | Global OCSP/CRL transport (v1.7.0) |
+
+### Streaming Output
+
+| Function | Description |
+|----------|-------------|
+| `buildDocumentPDFStream(params, layout?, streamOpts?)` | Stream document PDF as `AsyncGenerator<Uint8Array>` |
+| `buildPDFStream(params, layout?, streamOpts?)` | Stream table PDF as `AsyncGenerator<Uint8Array>` |
+| `buildDocumentPDFStreamTrue(params, layout?, streamOpts?)` | **True constant-memory** document streaming — frees each part as it yields (v1.3.0) |
+| `buildPDFStreamTrue(params, layout?, streamOpts?)` | **True constant-memory** table streaming (v1.3.0) |
+| `buildDocumentPDFStreamPageByPage(params, layout?)` | Stream document PDF chunked at PDF object boundaries |
+| `buildPDFStreamPageByPage(params, layout?)` | Stream table PDF chunked at PDF object boundaries |
+| `validateDocumentStreamable(params, layout?)` | Validate document is compatible with streaming (no TOC, no `{pages}`) |
+| `validateTableStreamable(params, layout?)` | Validate table is compatible with streaming |
+| `chunkBinaryString(str, chunkSize)` | Split binary string into `Uint8Array` chunks |
+| `concatChunks(chunks)` | Concatenate `Uint8Array` chunks into one |
+| `streamByteLength(stream)` | Count total bytes from an async stream |
+| `streamToFile(stream, filePath, opts?)` | Drain an `AsyncGenerator<Uint8Array>` to disk with back-pressure + `AbortSignal` (Node) — returns `{ bytesWritten, path }` (v1.4.0) |
+
+### Crypto (Hashing, ASN.1, RSA, ECDSA, X.509, CMS)
+
+| Function | Description |
+|----------|-------------|
+| `sha1(data)` | SHA-1 — `/VRI` keying and OCSP CertID identification only, never a security digest (v1.7.0) |
+| `sha384(data)` / `sha512(data)` | SHA-384 / SHA-512 hash (FIPS 180-4) |
+| `hmacSha256(key, data)` | HMAC-SHA-256 (RFC 2104) |
+| `derDecode(data)` | Decode DER-encoded ASN.1 |
+| `derSetOf(...values)` / `derGeneralizedTime(date)` | Canonical DER SET OF (X.690 §11.6) / GeneralizedTime encoder (v1.7.0) |
+| `rsaSign(msg, key, digest?)` / `rsaVerify(msg, sig, key, digest?)` | RSA PKCS#1 v1.5 sign/verify — SHA-256/384/512 (digest param v1.7.0) |
+| `ecdsaSign(hash, key)` / `ecdsaVerify(hash, sig, key)` | ECDSA P-256 sign/verify |
+| `parseCertificate(der)` | Parse X.509 DER certificate — incl. SKI/AKI, EKU, AIA (OCSP/caIssuers URLs), CRL distribution points (v1.7.0) |
+| `certHasEku(cert, oid)` | Check an extended-key-usage OID (v1.7.0) |
+| `buildCmsSignedData(options)` | Build CMS SignedData — PKCS#7 or PAdES profile, SHA-256/384/512 (v1.7.0) |
+| `parseCmsSignedData(der)` / `addUnsignedAttribute(cms, attr)` / `buildAttribute(oid, ...v)` | CMS inspection + unsigned-attribute surgery, signed bytes untouched (v1.7.0) |
+| `buildTimestampRequest(imprint, opts?)` / `parseTimestampResponse(der)` / `parseTimestampToken(der)` / `verifyTimestampImprint(info, hash)` | RFC 3161 timestamp protocol (v1.7.0) |
+| `buildOcspRequest(cert, issuer, opts?)` / `parseOcspResponse(der)` | OCSP RFC 6960 (v1.7.0) |
+| `parseCrl(der)` / `isSerialRevoked(crl, serial)` | CRL RFC 5280 (v1.7.0) |
+| `initCrypto()` | Initialize crypto module (lazy load) |
+
+### PDF Parser & Modifier
+
+| Function | Description |
+|----------|-------------|
+| `openPdf(bytes, opts?)` | Parse a PDF `Uint8Array` and return a `PdfReader`. Pass `{ password }` to open an encrypted document (RC4, AES-128, AES-256) |
+| `createModifier(reader)` | Create an incremental `PdfModifier` from a `PdfReader` |
+| `createTokenizer(data, offset?)` | Create a low-level PDF tokenizer |
+| `parseValue(tok)` | Parse a single PDF value from token stream |
+| `parseIndirectObject(tok)` | Parse an indirect object (`N M obj ... endobj`) |
+| `findStartxref(data)` | Find `startxref` offset in PDF bytes |
+| `parseXrefTable(data, offset)` | Parse xref table/stream at given offset |
+| `isRef(v)` / `isDict(v)` / `isArray(v)` / `isStream(v)` | Type guards for parsed PDF values |
+| `dictGet(dict, key)` / `dictGetName(dict, key)` | Dictionary value accessors |
+| `inflateSync(data)` | Decompress FlateDecode data (zlib inflate) |
+| `validatePdfUA(bytes)` | Read-only PDF/UA structural checker — returns `{ valid, errors, warnings }` (v1.3.0) |
+| `mergePdfs(sources, opts?)` | Merge multiple PDFs into one, rebuilding a clean object graph; `opts.maxOutputSize` caps output at 256 MiB by default (v1.4.0); `opts.encrypt` re-encrypts the output (AES-128/AES-256, v1.6.0) |
+| `splitPdf(src, ranges, opts?)` | Split a PDF into multiple documents by inclusive 0-based page ranges (v1.4.0) |
+| `extractPages(src, indices, opts?)` | Extract specific pages (0-based) into a new PDF (v1.4.0) |
+| `reader.getPageLabels()` | Parse an existing `/PageLabels` number tree into `PageLabelRange[]` or `null` (v1.5.0) |
+| `reader.getAnnotations(pageIndex)` | Read a page's annotations into `ParsedAnnotation[]` (v1.5.0) |
+| `reader.getPageRef(pageIndex)` | Get the indirect `PdfRef` for a page (v1.5.0) |
+| `modifier.addAnnotation(pageIndex, body)` | Inject a new annotation on a page via incremental update (v1.5.0) |
+| `extractText(bytes, opts?)` | Extract per-page reading-order Unicode text (+ optional positioned runs) from any PDF, incl. encrypted (`opts.password`); `ToUnicode`/`Differences`/WinAnsi/MacRoman decoding, hard `maxTextLength` memory cap (v1.6.0) |
+
+### Document Block Types
+
+| Type | Description |
+|------|-------------|
+| `HeadingBlock` | H1/H2/H3 with color, auto-wrapped |
+| `ParagraphBlock` | Text with fontSize, lineHeight, align, indent, color |
+| `TableBlock` | Headers + rows using PdfRow/ColumnDef |
+| `ListBlock` | Bullet or numbered items; entries may be plain strings or nested `ListItem` `{ text, items }` for hierarchical lists (v1.4.0) |
+| `ImageBlock` | JPEG/PNG with optional width, height, align, alt text |
+| `LinkBlock` | Hyperlink with URL, blue underline, tagged /Link |
+| `SpacerBlock` | Vertical whitespace |
+| `PageBreakBlock` | Force new page |
+| `TocBlock` | Auto-generated table of contents with /GoTo links |
+| `BarcodeBlock` | Barcode / QR code rendered via PDF path operators |
+| `SvgBlock` | SVG path/shape rendering as native PDF path operators |
+| `FormFieldBlock` | AcroForm interactive fields (text, checkbox, radio, dropdown, listbox) |
+
+### Tagged PDF & PDF/A
+
+| Function | Description |
+|----------|-------------|
+| `resolvePdfAConfig(tagged)` | Resolve tagged option → PDF/A config (version, part, conformance) |
+| `encodePdfTextString(str)` | Encode string as PDF text (PDFDocEncoding or UTF-16BE hex) |
+
+### Encryption
+
+Encryption is configured via the `encryption` option in layout options. Since v1.6.0 the reader side is public too — `openPdf(bytes, { password })` plus the `PdfPasswordError`, `PdfEncryptionUnsupportedError` and `PdfEncryptionInfo` exports.
+
+```typescript
+const pdf = buildPDFBytes(params, {
+  encryption: { userPassword: 'secret', ownerPassword: 'admin', permissions: { print: true } }
+});
+```
+
+### Color Utilities
+
+| Function | Description |
+|----------|-------------|
+| `parseColor(input)` | Parse hex / tuple / PDF string → validated PDF RGB string |
+| `isValidPdfRgb(str)` | Check if string is valid `"R G B"` format (0.0–1.0) |
+| `normalizeColors(colors)` | Validate and normalize all fields in a PdfColors object |
+
+### Compression
+
+| Function | Description |
+|----------|-------------|
+| `initNodeCompression()` | Initialize native zlib (async, call once in ESM before `compress: true`) |
+| `setDeflateImpl(fn)` | Inject custom DEFLATE function (e.g. for browser polyfill) |
+
+**Browser compression** — In browser environments without native zlib, inject a third-party DEFLATE via `setDeflateImpl`:
+
+```typescript
+import { setDeflateImpl, buildPDFBytes } from 'pdfnative';
+import { deflateSync } from 'fflate'; // or pako
+
+setDeflateImpl(deflateSync);
+
+const pdf = buildPDFBytes(params, { compress: true });
+```
+
+### Fonts
+
+| Function | Description |
+|----------|-------------|
+| `registerFont(lang, loader)` | Register a font data loader |
+| `registerFonts(map)` | Register multiple font loaders |
+| `loadFontData(lang)` | Lazy-load font data (cached) |
+| `hasFontLoader(lang)` | Check if loader is registered |
+| `getRegisteredLangs()` | List registered language codes |
+| `createEncodingContext(fontEntries)` | Create encoding context |
+| `validateFontData(data)` | Opt-in structural validation of custom font data — returns `{ valid, errors, warnings }` (v1.4.0) |
+
+### Shaping
+
+| Function | Description |
+|----------|-------------|
+| `shapeThaiText(str, fontData)` | Thai OpenType shaping (GSUB + GPOS) |
+| `shapeBengaliText(str, fontData)` | Bengali GSUB conjuncts + GPOS marks |
+| `shapeTamilText(str, fontData)` | Tamil GSUB + split vowel decomposition |
+| `shapeDevanagariText(str, fontData)` | Devanagari cluster shaping + GSUB/GPOS |
+| `shapeTeluguText(str, fontData)` | Telugu GSUB conjuncts + GPOS marks (v1.3.0) |
+| `shapeSinhalaText(str, fontData)` | Sinhala conjuncts + pre-base reorder + GSUB/GPOS (v1.3.0) |
+| `shapeTibetanText(str, fontData)` | Tibetan vertical subjoined stacking (v1.3.0) |
+| `shapeKhmerText(str, fontData)` | Khmer USE-lite — coeng subscripts + pre-base vowels (v1.3.0) |
+| `shapeMyanmarText(str, fontData)` | Myanmar USE-lite — medials + virama stacking (v1.3.0) |
+| `detectFallbackLangs(texts, primaryLang)` | Detect needed fallback fonts |
+| `detectCharLang(codePoint)` | Map codepoint to preferred font language |
+| `splitTextByFont(str, fontEntries)` | Multi-font text run splitting |
+| `needsUnicodeFont(str)` | Check if text needs CIDFont |
+| `containsThai(str)` | Check for Thai characters |
+| `resolveBidiRuns(text)` | Resolve BiDi runs (UAX #9) |
+| `containsRTL(text)` | Detect RTL content |
+| `shapeArabicText(str, fontData)` | Arabic GSUB positional shaping |
+| `containsArabic(text)` | Detect Arabic content |
+| `containsHebrew(text)` | Detect Hebrew content |
+| `containsTelugu(text)` | Detect Telugu content (v1.3.0) |
+| `isTeluguCodepoint(cp)` | Telugu codepoint predicate (v1.3.0) |
+| `containsSinhala(text)` / `containsTibetan(text)` / `containsKhmer(text)` / `containsMyanmar(text)` / `containsEthiopic(text)` | Detect script content (v1.3.0) |
+| `isSinhalaCodepoint(cp)` / `isTibetanCodepoint(cp)` / `isKhmerCodepoint(cp)` / `isMyanmarCodepoint(cp)` / `isEthiopicCodepoint(cp)` | Codepoint predicates (v1.3.0) |
+| `containsMath(text)` / `isMathCodepoint(cp)` | Detect / test mathematical symbols → lang `'math'` (v1.5.0) |
+
+### Layout Constants
+
+| Constant | Description |
+|----------|-------------|
+| `PG_W` / `PG_H` | A4 page dimensions (points) |
+| `DEFAULT_MARGINS` | Default margins `{ t, r, b, l }` |
+| `DEFAULT_COLORS` | Default color palette |
+| `DEFAULT_COLUMNS` | Default 5-column layout |
+| `ROW_H` / `TH_H` | Row / header heights |
+| `HEADER_H` | Header zone height (15pt) |
+| `PAGE_SIZES` | Preset page dimensions (A4, Letter, Legal, A3, Tabloid) |
+| `resolveTemplate(tpl, page, pages, title, date)` | Resolve header/footer template placeholders |
 
 ## Ecosystem
 
-- [pdfnative-cli](https://github.com/Nizoka/pdfnative-cli): CLI wrapper for pdfnative (v1.3.0, built on pdfnative 1.7.0) — render, fill, annotate, merge, split, extract, sign, verify, encrypt, decrypt, inspect, extract-text, batch, doctor, schema, completion, govern.
-- [pdfnative-mcp](https://github.com/Nizoka/pdfnative-mcp): Model Context Protocol server exposing pdfnative as 24 AI tools (v1.5.0, built on pdfnative 1.7.0).
-- [pdfnative-react](https://github.com/Nizoka/pdfnative-react): React renderer — declarative JSX components compiled on-device to pdfnative blocks (v1.1.0, React 19 + pdfnative ^1.6.0 peers).
+pdfnative ships as a library, but three official companion packages cover the most common non-library use cases — a CLI, an MCP server, and a React renderer. All live in separate repositories and depend on `pdfnative` only through the public API, so the core library stays zero-dependency.
+
+### pdfnative-cli — command-line interface
+
+[`pdfnative-cli`](https://github.com/Nizoka/pdfnative-cli) v1.3.0 is the **official CLI**, built on `pdfnative` v1.6.0. It exposes 17 commands in five groups — create & edit (`render`, `fill`, `annotate`), page tree (`merge`, `split`, `extract`), security (`sign`, `verify`, `encrypt`, `decrypt`), read & extract (`inspect`, `extract-text`), and automation & meta (`batch`, `doctor`, `schema`, `completion`, `govern`) — for use in shell scripts, Makefiles, GitHub Actions, and Docker images. Zero extra runtime dependencies, npm-provenance-signed, with a CycloneDX SBOM attached to every release.
+
+**New in v1.1.0:** **22 Unicode scripts + COLRv1 colour emoji** through the `--font`/`--lang` shortcuts, **true constant-memory streaming** (`--stream-true`), a `--max-blocks` cap for very large documents, and a **PDF/UA (ISO 14289-1) structural validator** (`inspect --pdfua` / `--check pdfua`). It also adds an **agent-native contract** — a global `--json` status/error envelope, stable `E_*` error codes, a `--dry-run` validation mode, the new **`schema`** command (Draft 2020-12), and token-economy output projection (`--summary` / `--fields` + compact JSON) that cuts agent output ~90 %. **100 % backward-compatible.**
+
+<!-- verify-docs:allow version-token (historical: CLI v1.2.0 shipped on the pdfnative 1.5.0 engine) -->
+**New in v1.2.0:** five new commands — **`merge`**, **`split`**, **`extract`** (page-tree manipulation via pdfnative 1.5.0), **`annotate`** (markup annotations via incremental save, so existing signatures stay intact), and **`govern`** (the AI-governance / Human-in-the-Loop contract: `govern rules` / `govern policy` / `govern verify-issue`, with a stable `E_POLICY` error code). Plus PDF bookmarks (`--outline auto` or an explicit tree), the bundled math font (`--font math`), layout introspection (`--inspect-layout` / `--debug-layout`), and native constant-time crypto by default in `sign` (opt out with `--pure-crypto`).
+
+**New in v1.3.0:** five more commands on the pdfnative 1.6 engine — **`fill`** (fill, flatten, and export existing AcroForms via incremental save, encrypted PDFs included), **`encrypt`** / **`decrypt`** (AES-128/256 re-securing and password removal; RC4 never emitted), **`extract-text`** (reading-order Unicode text as text/JSON/NDJSON, `--runs`, `--password`), and **`doctor`** (offline environment preflight). Also native vector charts in `render`, `--password` + `--encrypt` re-encryption on merge/split/extract, an agent capability manifest (`schema manifest` + `llms.txt`), and PowerShell completion.
+
+```bash
+# render with full layout coverage (encryption + watermark + PDF/A-2b)
+npx pdfnative-cli render --input doc.json --output report.pdf \
+  --tagged pdfa2b --compress \
+  --watermark-text "DRAFT" --watermark-opacity 0.15
+
+# sign with metadata and intermediate cert chain
+npx pdfnative-cli sign --input report.pdf --output signed.pdf \
+  --reason "Approved" --name "Finance Team" \
+  --signing-time 2026-04-28T10:00:00Z \
+  --cert-chain intermediate.pem
+
+# verify embedded signatures (byte-range + chain + trust + revocation)
+npx pdfnative-cli verify --input signed.pdf --strict --trust ca-root.pem
+
+# inspect with CI assertions, incl. PDF/UA accessibility gate (exit 1 on failure)
+npx pdfnative-cli inspect --input signed.pdf \
+  --check pdfa --check signed --check pdfua --json --summary
+```
+
+<!-- verify-docs:allow version-token (pdfnative-cli's own current version, not the engine) -->
+See the [CLI Guide](https://pdfnative.dev/guides/cli.html) for the full v1.3.0 reference, agent contract, security model, and recipes. Try the [interactive CLI playground](https://pdfnative.dev/playgrounds/cli.html) to build commands without leaving the browser.
+
+### pdfnative-mcp — Model Context Protocol server
+
+[`pdfnative-mcp`](https://github.com/Nizoka/pdfnative-mcp) v1.6.0 is a **Model Context Protocol server** that bridges pdfnative to any MCP-compatible AI client. Once configured, your AI assistant can generate PDFs and native vector charts, embed barcodes, create, read, fill and flatten forms, sign documents through the complete PAdES ladder (B-B → B-LTA with RFC 3161 timestamps and embedded revocation material), verify signatures and document timestamps, encrypt and decrypt PDFs, validate PDF/UA structure, embed and extract attachments, extract Unicode text, render international text, merge, split and extract pages, annotate existing PDFs, rewrite document metadata, preview pagination without producing a PDF, draft governance-compliant GitHub issues (human-in-the-loop), and inspect existing PDFs — all without writing code.
+
+<!-- verify-docs:allow stale-token (historical: MCP v1.0.0 shipped 12 tools) -->
+**v1.0.0:** first stable MCP release with 12 tools, `verify_pdf`, `add_attachment` (Factur-X / ZUGFeRD PDF/A-3), `extract_text`, smart-table options, auto-placeholder signing, and `_meta.apiVersion`.
+
+**v1.1.0:** adds `validate_pdf`, six additional scripts (Telugu, Sinhala, Tibetan, Khmer, Myanmar, Ethiopic), and COLRv1 colour-emoji support via the pdfnative 1.3.0 engine. <!-- verify-docs:allow version-token (historical engine reference) -->
+
+**v1.2.0:** adds `extract_attachments`, watermark options on document tools, Unicode `normalize` (NFC/NFD/NFKC/NFKD), token-frugal read modes (`verbosity`/`fields`), and returns base64 PDF bytes once via a `resource` block.
+
+**v1.3.0:** adds the page-tree trio `merge_pdfs` / `split_pdf` / `extract_pages` (**17 tools** total)<!-- verify-docs:allow stale-token (historical: MCP v1.3.0 total) -->, enriched authoring options (`outline`, `pageLabels`, nested lists, `viewerPreferences`, `cellBorders`, `cellVAlign`), a constant-time `node:crypto` signing provider, and DNS-rebinding protection on the HTTP transport — all via the pdfnative 1.4.0 engine.
+
+**v1.4.0:** adds `annotate_pdf` (markup via incremental update) and the network-free `draft_governance_issue` (**19 tools**)<!-- verify-docs:allow stale-token (historical: MCP v1.4.0 total, on the pdfnative 1.5.0 engine) -->, the MCP `prompts` capability (`governance_contract`, `draft_issue_workflow`), `pageLabels[]` in `inspect_pdf`, and the explicit `math` script — via the pdfnative 1.5.0 engine.
+
+**v1.5.0:** adds `add_chart`, `read_form_fields`, `fill_form`, `encrypt_pdf`, `decrypt_pdf` (**24 tools**)<!-- verify-docs:allow stale-token (historical: MCP v1.5.0 total) -->, `password` support on the read-only and page-tree tools, MCP resources (`pdfnative://output/…`), and tool annotations — via the pdfnative 1.6.0 engine.
+
+**v1.6.0:** adds `add_ltv`, `timestamp_pdf`, `update_metadata`, `inspect_layout` (**28 tools**), all 13 block kinds in `generate_basic_pdf`, layout options and build-time `encrypt` on the document tools, image watermarks, print production, charts v2, honest PDF/A (`embedFonts` / `strict` / diagnostics), PAdES timestamps on `sign_pdf`, four new recipe prompts, and the MCP 2026-07-28 spec — via the pdfnative 1.7.0 engine.
+
+```bash
+npx -y pdfnative-mcp
+```
+
+### Available tools
+
+| Tool | Purpose |
+|------|---------|
+| `generate_basic_pdf` | Multi-page documents from structured blocks — all 13 block kinds since v1.6.0 (incl. tables, images, links, TOC, barcodes, SVG, form fields); optional `outline`, `pageLabels`, `pdfA`, layout options, build-time `encrypt`, print production |
+| `add_table` | Smart tables (`wrap`, `repeatHeader`, `zebra`, `caption`, `minRowHeight`, `cellPadding`, `cellBorders`, `cellVAlign`) |
+| `add_barcode` | QR Code, Code 128, EAN-13, Data Matrix, PDF417 |
+| `add_international_text` | 25 `lang` font codes (22 Unicode scripts + `latin` + `emoji` + explicit `math`) with BiDi and OpenType shaping |
+| `add_form` | Interactive AcroForm PDFs (`text`, `textarea`, `checkbox`, `radio`, `dropdown`, `listbox` since v1.6.0) |
+| `embed_image` | Embed a JPEG or PNG image (base64), with `align` / `alt` since v1.6.0 |
+| `prepare_signature_placeholder` | PDF with a `/Sig` field ready to be signed (optional — `sign_pdf` auto-injects one); `subFilter` / `reserveTimestamp` since v1.6.0 |
+| `sign_pdf` | PAdES CMS signatures (RSA-SHA256/384/512 / ECDSA-SHA256 P-256); `profile: 'pades'`, RFC 3161 `timestamp`, cert chains, multiple signatures since v1.6.0 |
+| `add_ltv` | Embed `/DSS` + `/VRI` long-term-validation material — PAdES B-LT (v1.6.0) |
+| `timestamp_pdf` | Append a `/DocTimeStamp` through the operator TSA — PAdES B-LTA (v1.6.0) |
+| `validate_pdf` | Read-only PDF/UA structural validation |
+| `verify_pdf` | Verify every PAdES signature and `/DocTimeStamp` (integrity + value + optional chain trust; `ltv: true` reports the achieved PAdES level since v1.6.0) |
+| `add_attachment` | PDF/A-3 with embedded files (Factur-X / ZUGFeRD) |
+| `extract_attachments` | Extract embedded files (optionally metadata-only) |
+| `extract_text` | Unicode text extraction (positioned runs; `password` since v1.5.0) |
+| `merge_pdfs` | Concatenate 2–50 PDFs (encrypted sources via `password`; re-encrypt since v1.5.0) |
+| `split_pdf` | Split one PDF into one document per page range |
+| `extract_pages` | Pull an arbitrary, order-preserving page subset into a new PDF |
+| `annotate_pdf` | Overlay markup annotations (9 types) via incremental update; not a redaction |
+| `draft_governance_issue` | Governance-compliant GitHub-issue draft, network-free, never submits (HITL) |
+| `add_chart` | Native vector charts, zero rasterisation — nine types since v1.6.0 (bar, horizontal bar, stacked bar, stacked horizontal bar, line, area, scatter, pie, donut), dual axis, log & time scales |
+| `read_form_fields` | List an existing AcroForm's fields (types, values, options) |
+| `fill_form` | Fill and optionally flatten an existing AcroForm (encrypted PDFs supported) |
+| `encrypt_pdf` | Re-secure with AES-128/AES-256, owner/user passwords + permissions |
+| `decrypt_pdf` | Remove encryption in-server (RC4 / AES-128 / AES-256 sources) |
+| `update_metadata` | Rewrite `/Info` (+ XMP) of an existing PDF via incremental update (v1.6.0) |
+| `inspect_pdf` | Structured report (metadata, pages, signatures, PDF/A, attachments, `encryptionInfo`, `pageLabels`; annotation and signature inventories, `dss`, page boxes since v1.6.0) |
+| `inspect_layout` | Read-only pagination dry run — page count and block geometry, no PDF produced (v1.6.0) |
+
+### Claude Desktop configuration
+
+```json
+{
+  "mcpServers": {
+    "pdfnative": {
+      "command": "npx",
+      "args": ["-y", "pdfnative-mcp"],
+      "env": {
+        "PDFNATIVE_MCP_OUTPUT_DIR": "/Users/you/Documents/mcp-pdfs"
+      }
+    }
+  }
+}
+```
+
+See the [MCP Integration Guide](https://pdfnative.dev/guides/mcp.html) and the [pdfnative-mcp repository](https://github.com/Nizoka/pdfnative-mcp) for configuration on Cursor, Continue, Zed, and more.
+
+### pdfnative-react — declarative JSX renderer
+
+[`pdfnative-react`](https://github.com/Nizoka/pdfnative-react) v1.1.0 turns declarative **JSX** into real, on-device PDFs powered by the zero-dependency pdfnative engine — no DOM, no headless browser, no SaaS round-trips. A custom React reconciler compiles your component tree synchronously into the pdfnative block model. Requires **React 19**, **pdfnative ^1.6.0** and **Node.js ≥ 22**. React and pdfnative are peer dependencies; the package itself adds one runtime dependency, `react-reconciler`. The pdfnative engine remains dependency-free.
+
+```tsx
+import { Document, Heading, Text, Table, renderToBytes } from 'pdfnative-react';
+
+const bytes = renderToBytes(
+  <Document title="Invoice #1024" footerText="Acme Inc">
+    <Heading level={1}>Invoice #1024</Heading>
+    <Text>Thank you for your business.</Text>
+    <Table
+      headers={['Item', 'Qty', 'Total']}
+      rows={[{ cells: ['Pro plan', '1', '$49.00'], type: 'default', pointed: false }]}
+      zebra
+    />
+  </Document>,
+); // → Uint8Array, a valid PDF
+```
+
+Every component (`Document`, `Page`, `Section`, `Heading`, `Paragraph`/`Text`, `List`/`Item`, `Table`/`Row`/`Cell`, `Image`, `Link`, `Spacer`, `PageBreak`, `TableOfContents` (alias `Toc`), `Barcode`, `Svg`, `Chart`, `FormField`) maps 1:1 onto a pdfnative block. Render with `renderToBytes` / `renderToBlob` / `renderToStream` / `renderToFile` / `renderToFileStream` / `renderToResponse`, introspect with `inspectDocument` / `lintDocument`, preview live with the `usePdf` / `usePdfStream` hooks and `PDFViewer` / `PDFDownloadLink` / `BlobProvider` client components, or let AI agents author documents with the token-frugal `DocSpec` (terse JSON tuples that compile to the *same* PDF, validated by a versioned JSON Schema).
+
+See the [React Guide](https://pdfnative.dev/guides/react.html) for the full component reference, and try the [interactive React playground](https://pdfnative.dev/playgrounds/react.html) to render JSX to PDF in your browser.
+
+## Architecture
+
+```
+src/
+├── index.ts              # Public API — single entry point
+├── types/
+│   ├── pdf-types.ts      # Core TypeScript type definitions
+│   └── pdf-document-types.ts  # Document builder type definitions (blocks, params)
+├── core/
+│   ├── pdf-builder.ts    # Table-centric PDF assembly + /Info metadata + tagged PDF
+│   ├── pdf-document.ts   # Free-form document builder (headings, paragraphs, lists, tables, images)
+│   ├── pdf-assembler.ts  # Shared PDF binary assembly primitives (xref, trailer, writer)
+│   ├── encoding-context.ts # Encoding context factory (dependency inversion from fonts/)
+│   ├── pdf-image.ts      # JPEG/PNG parsing + PDF Image XObject builder
+│   ├── pdf-text.ts       # Text rendering (Latin + CIDFont + shaped + tagged)
+│   ├── pdf-stream.ts     # Binary utilities + download
+│   ├── pdf-stream-writer.ts # AsyncGenerator streaming output
+│   ├── pdf-layout.ts     # Layout constants & computation
+│   ├── pdf-tags.ts       # Tagged PDF: structure tree, XMP metadata, ICC profile
+│   ├── pdf-annot.ts      # Link annotations: /URI, /GoTo, URL validation + control-char hardening
+│   ├── pdf-color.ts      # Color parsing, validation, normalization
+│   ├── pdf-compress.ts   # FlateDecode stream compression (zlib, stored-block fallback)
+│   ├── pdf-watermark.ts  # Text/image watermarks with ExtGState transparency
+│   ├── pdf-barcode.ts    # Barcode/QR code encoders + PDF path rendering (5 formats)
+│   ├── pdf-svg.ts        # SVG path/shape rendering as native PDF operators
+│   ├── pdf-form.ts       # AcroForm interactive fields with appearance streams
+│   ├── pdf-signature.ts  # CMS/PKCS#7 digital signatures (RSA + ECDSA)
+│   └── pdf-encrypt.ts    # AES-128/256 encryption, MD5, SHA-256, key derivation
+├── crypto/
+│   ├── sha.ts            # SHA-384, SHA-512, HMAC-SHA-256
+│   ├── asn1.ts           # ASN.1 DER encoding/decoding
+│   ├── rsa.ts            # RSA PKCS#1 v1.5 sign/verify
+│   ├── ecdsa.ts          # ECDSA P-256 sign/verify
+│   ├── x509.ts           # X.509 certificate parsing
+│   └── cms.ts            # CMS SignedData (PKCS#7) builder
+├── parser/
+│   ├── pdf-inflate.ts    # DEFLATE decompression (zlib inflate)
+│   ├── pdf-tokenizer.ts  # PDF lexical scanner (ISO 32000-1 §7.2)
+│   ├── pdf-object-parser.ts # PDF object parser with type guards
+│   ├── pdf-xref-parser.ts # Cross-reference table/stream parser
+│   ├── pdf-reader.ts     # High-level PDF reader (page tree, stream decode)
+│   └── pdf-modifier.ts   # Incremental modification (non-destructive save)
+├── fonts/
+│   ├── encoding.ts       # WinAnsi + CIDFont pure encoding functions (no shaping deps)
+│   ├── font-loader.ts    # Configurable font registry + cache
+│   ├── font-subsetter.ts # TTF subsetting engine (with buffer bounds checking)
+│   └── font-embedder.ts  # CMap builder + width arrays
+├── shaping/
+│   ├── script-registry.ts # Centralized Unicode range constants & script predicates
+│   ├── thai-shaper.ts    # Thai GSUB + GPOS shaping pipeline
+│   ├── bengali-shaper.ts # Bengali GSUB conjuncts + GPOS mark positioning
+│   ├── tamil-shaper.ts   # Tamil GSUB + split vowel decomposition
+│   ├── script-detect.ts  # Unicode script range detection (uses script-registry)
+│   ├── multi-font.ts     # Cross-script font run splitting
+│   ├── bidi.ts           # Unicode Bidirectional Algorithm (UAX #9)
+│   └── arabic-shaper.ts  # Arabic GSUB positional shaping (uses script-registry)
+└── worker/
+    ├── worker-api.ts     # Worker/main-thread dispatch
+    └── pdf-worker.ts     # Self-contained worker entry
+
+fonts/                    # Pre-built font data modules (22 scripts)
+tools/                    # CLI: build-font-data.cjs (TTF → JS module)
+scripts/                  # Modular sample PDF generation (48 generators, 242 PDFs)
+tests/                    # 2686+ tests (123 files: unit + integration + fuzz + parser + docs)
+bench/                    # Performance benchmarks (vitest bench)
+```
+
+## Development
+
+```bash
+git clone https://github.com/Nizoka/pdfnative.git
+cd pdfnative
+npm install
+
+npm run build            # tsup → dist/ (ESM + CJS + .d.ts)
+npm run test             # vitest run (2686+ tests)
+npm run test:coverage    # vitest with v8 coverage (95.41% statements at the v1.6.0 release; CI gates: 88/80/85/90)
+npm run test:generate       # Generate 242 sample PDFs → test-output/
+npm run lint                # ESLint 9 + typescript-eslint strict
+npm run typecheck           # tsc --noEmit (src/)
+npm run typecheck:tests     # tsc --project tsconfig.test.json
+npm run typecheck:scripts   # tsc --project tsconfig.scripts.json
+npm run typecheck:all       # Typecheck src/ + tests/ + scripts/
+npm run bench               # Performance benchmarks (vitest bench)
+```
+
+### Quality Metrics
+
+| Metric | Value |
+|--------|-------|
+| Tests | 2686+ (123 files) |
+| Statement coverage | 95.41% (measured at the v1.6.0 release; CI enforces ≥88%, vitest.config.ts) |
+| Branch coverage | 87.79% (measured at the v1.6.0 release; CI enforces ≥80%) |
+| Function coverage | 98.5% (measured at the v1.6.0 release; CI enforces ≥85%; lines gate: ≥90%) |
+| Fuzz tests | 89 tests in 5 files (`tests/fuzzing/`) |
+| Benchmarks | Latin 500 rows ~10ms, Unicode ~13ms (Apple M1, Node 22) |
+| Dependencies | 0 runtime |
+| CI | Node 22/24 matrix |
+| Provenance | npm signed builds |
+
+## Known Limitations — Visual vs. Semantic PDF
+
+pdfnative generates **visually pixel-perfect** PDFs for all 22 supported scripts. However, PDF is fundamentally a *visual* format (a digital printer), not a *semantic* one. This distinction matters for **text extraction** (copy-paste, `pdftotext`, screen readers):
+
+### Complex Text Layout (CTL) scripts
+
+For scripts with combining marks — **Thai**, **Devanagari**, **Vietnamese tones** — the shaper positions each mark in its own `BT…ET` block with precise GPOS offsets. PDF viewers **render** this correctly, but text extractors reconstruct content by spatial position rather than logical order. This can produce garbled output when copying text from the PDF.
+
+| Scenario | Visual rendering | Text extraction (Ctrl+C) |
+|----------|:---:|:---:|
+| Latin, Greek, Polish, Turkish | ✅ Perfect | ✅ Perfect |
+| CJK (Japanese, Chinese, Korean) | ✅ Perfect | ✅ Perfect |
+| Vietnamese (combining diacritics) | ✅ Perfect | ⚠️ May show Win-1252 fallback artifacts |
+| Thai (GSUB + GPOS shaping) | ✅ Perfect | ⚠️ Combining marks may be reordered |
+| Devanagari (matras, conjuncts) | ✅ Perfect | ⚠️ Combining marks may be reordered |
+| Bengali (conjuncts, GPOS marks) | ✅ Perfect | ⚠️ Combining marks may be reordered |
+| Tamil (split vowels, GSUB) | ✅ Perfect | ⚠️ Split vowel recomposition may fail |
+
+### Why this happens
+
+This is an inherent limitation of the PDF spec (ISO 32000-1), not a bug in pdfnative. The ToUnicode CMap correctly maps glyph IDs back to Unicode code points, but extractors that rely on spatial reconstruction rather than CMap lookup will produce artifacts. This behavior is shared by most PDF generators that don't use Tagged PDF.
+
+### Tagged PDF, /ActualText & PDF/A — Implemented ✅
+
+All three roadmap items are now implemented and available via the `tagged` layout option:
+
+```ts
+const pdf = buildPDFBytes(params, { tagged: true });       // PDF/A-2b (default)
+const pdf1b = buildPDFBytes(params, { tagged: 'pdfa1b' }); // PDF/A-1b (legacy)
+const pdf2u = buildPDFBytes(params, { tagged: 'pdfa2u' }); // PDF/A-2u (Unicode)
+```
+
+When `tagged` is set, the output includes:
+
+- **Tagged PDF (PDF/UA)** — full structure tree (`/Document → /Table → /TR → /TH|/TD`, `/H1-H3`, `/P`, `/L → /LI`, `/Figure`, `/Link`) with `/Span` marked content operators and `/StructParents` on every page
+- **/ActualText** — original Unicode string attached as UTF-16BE hex to every `/Span BDC...EMC` sequence, solving text extraction for GPOS-repositioned glyphs (Thai, Arabic, Devanagari)
+- **PDF/A-2b compliance** (default) — PDF 1.7, XMP metadata with `pdfaid:part=2` + `pdfaid:conformance=B`, sRGB ICC OutputIntent (`GTS_PDFA1`), `/MarkInfo << /Marked true >>` on Catalog
+- **PDF/A-1b compatibility** — explicit `tagged: 'pdfa1b'` uses PDF 1.4, `pdfaid:part=1`
+- **PDF/A-2u variant** — `tagged: 'pdfa2u'` uses PDF 1.7, `pdfaid:conformance=U`
+
+The `tagged` option is backward-compatible — omitting it or setting `false` produces the same output as before.
+
+> **PDF/A status (v1.1.0).** Every PDF/A-claiming sample now passes
+> the **veraPDF** reference validator (1b / 2b / 2u / 3b) when the
+> Latin font module is registered. Trailer `/ID` and
+> `/Info CreationDate` are byte-equivalent to `xmp:CreateDate`
+> (with timezone offset). `<dc:title>`, `<dc:description>`,
+> `<pdf:Keywords>` mirror `/Info /Title`, `/Subject`, `/Keywords`
+> byte-for-byte (ISO 19005-1 §6.7.3 t1 / t4 / t5). Object 3 / Object 4
+> are emitted as Type0 redirector dicts pointing to the embedded
+> CIDFontType2 chain — no more unembedded `Helvetica` references
+> (ISO 19005-1 §6.3.4 / ISO 19005-2 §6.2.11.4.1). To produce strict
+> PDF/A:
+>
+> ```ts
+> import { registerFont } from 'pdfnative';
+> registerFont('latin', () => import('pdfnative/fonts/noto-sans-data.js'));
+> ```
+>
+> Run `npm run validate:pdfa` locally (with veraPDF installed, see
+> [docs/guides/pdfa.html](docs/guides/pdfa.html)) to verify against
+> the reference validator. CI runs veraPDF as a blocking check.
+
+### PDF Encryption — Implemented ✅
+
+AES-128 and AES-256 encryption with owner/user passwords and granular permissions:
+
+```ts
+const pdf = buildPDFBytes(params, {
+  encryption: {
+    ownerPassword: 'owner123',       // Required — full access password
+    userPassword: 'user456',         // Optional — password to open the PDF
+    algorithm: 'aes128',             // 'aes128' (default) or 'aes256'
+    permissions: {
+      print: true,                   // Allow printing (default: true)
+      copy: false,                   // Allow copy/paste (default: false)
+      modify: false,                 // Allow modification (default: false)
+      extractText: true,             // Allow text extraction (default: true)
+    },
+  },
+});
+```
+
+| Algorithm | PDF Version | Revision | Key Length | CFM |
+|-----------|------------|----------|------------|-----|
+| `aes128` | 1.4 | R4 (V4) | 128-bit | /AESV2 |
+| `aes256` | 1.4 | R6 (V5) | 256-bit | /AESV3 |
+
+**Note:** PDF/A and encryption are mutually exclusive (ISO 19005-1 §6.3.2). Setting both `tagged` and `encryption` will throw an error.
+
+## Typography Convention: En-Dash Separator
+
+pdfnative uses **en-dash** `–` (U+2013) with surrounding spaces as the standard title and footer separator:
+
+```
+"Arabic Script Coverage – الأبجدية العربية"    ✅ recommended
+"Arabic Script Coverage — الأبجدية العربية"    ⚠️ works, but wider gap
+```
+
+**Why en-dash?**
+
+| Property | Em-dash `—` (U+2014) | En-dash `–` (U+2013) |
+|----------|:---:|:---:|
+| Helvetica width | 1000 units (1 em) | 556 units (0.56 em) |
+| Visual gap at 16pt | ~24pt with spaces | ~18pt with spaces |
+| WinAnsi encodable | ✅ (0x97) | ✅ (0x96) |
+| International standard | US English only | ISO / Europe / technical |
+| Cursive script rendering | Disproportionate gap | Balanced spacing |
+
+The en-dash is **44% narrower** than the em-dash and follows ISO/international typography standards. This eliminates disproportionate visual gaps in cursive scripts (Arabic, Thai) where compact shaped text amplifies the perceived space around wider separators.
+
+Both em-dash and en-dash are **fully supported** by the library (encoding, width metrics, BiDi classification) — this is a typographic recommendation for the best cross-script visual balance, not a restriction.
+
+## Stream Compression (FlateDecode)
+
+Enable FlateDecode compression for dramatically smaller PDFs:
+
+```typescript
+import { initNodeCompression, buildPDFBytes } from 'pdfnative';
+
+// Initialize native zlib (required once in ESM context)
+await initNodeCompression();
+
+const pdf = buildPDFBytes(params, { compress: true });
+```
+
+| Stream Type | Compressed? | Typical Reduction |
+|-------------|:-----------:|:-----------------:|
+| Page content (text operators) | ✅ | 80–90% |
+| FontFile2 (TTF subset) | ✅ | 60–80% |
+| ToUnicode CMap | ✅ | 80–90% |
+| ICC sRGB profile | ✅ | 40–60% |
+| XMP metadata | ❌ (tagged mode) | — |
+| JPEG image | ❌ (already DCTDecode) | — |
+| PNG image | ❌ (already FlateDecode) | — |
+
+### Compression + Encryption
+
+Both features compose correctly — compression is applied **before** encryption per ISO 32000-1 §7.3.8:
+
+```typescript
+const pdf = buildPDFBytes(params, {
+  compress: true,
+  encryption: {
+    ownerPassword: 'owner123',
+    algorithm: 'aes128',
+  },
+});
+```
+
+### Platform Support
+
+| Runtime | Compression Method | Performance |
+|---------|-------------------|-------------|
+| Node.js 22+ | `zlib.deflateSync()` (native C) | Optimal |
+| Browser | Stored-block fallback (valid FlateDecode) | No size reduction |
+| Deno / Bun | CJS require fallback | Depends on compat layer |
+
+For browser contexts with full compression, call `setDeflateImpl()` with a custom DEFLATE function.
+
+## Browser & Runtime Compatibility
+
+pdfnative targets ES2020 and works in any environment that supports `Uint8Array`, `TextEncoder`, and `crypto.getRandomValues()`.
+
+| Runtime | Version | Status | Notes |
+|---------|---------|:------:|-------|
+| Node.js | 22, 24+ | ✅ Tested in CI | Full support (ESM + CJS) |
+| Chrome | 80+ | ✅ | ESM via bundler or `<script type="module">` |
+| Firefox | 80+ | ✅ | ESM via bundler or `<script type="module">` |
+| Safari | 14+ | ✅ | ESM via bundler or `<script type="module">` |
+| Edge | 80+ | ✅ | Chromium-based |
+| Deno | 1.0+ | ✅ | Native ESM imports |
+| Bun | 1.0+ | ✅ | Native ESM imports |
+| Web Workers | — | ✅ | Via `pdfnative/worker` entry point |
+| React Native | — | ⚠️ | Requires `TextEncoder` polyfill |
+
+**Bundle format:** ESM (`dist/index.js`) + CJS (`dist/index.cjs`) + TypeScript declarations (`dist/index.d.ts`). Tree-shakeable with `sideEffects: false`.
+
+## Origin
+
+pdfnative was born inside [**plika.app**](https://plika.app) — a personal finance application where high-quality, multi-language PDF generation (bank statements, transaction reports) was a core requirement. Rather than depending on heavy third-party libraries, the PDF engine was built from scratch with zero dependencies, strict ISO compliance, and native support for 22 Unicode scripts.
+
+The decision was then made to extract the engine into an independent open-source library so that everyone can benefit from production-grade PDF generation — not just plika.app users.
+
+> **Where it all started** — the PDF engine that became pdfnative was originally built inside [plika.app](https://plika.app), a personal finance app generating multi-language bank statements and financial summaries across 16 scripts.<!-- verify-docs:allow stale-token (historical: origin story) -->
+
+## Security
+
+- No `eval()`, `Function()`, or dynamic code execution
+- Input validation at `buildPDF()` and `buildDocumentPDF()` entry: type checks, row/block limits
+- URL validation at `validateURL()`: blocks `javascript:`, `file:`, `data:` URI schemes + control characters (U+0000–U+001F, U+007F–U+009F)
+- RGBA PNG rejection: unsupported color types rejected at parse boundary with descriptive errors
+- PDF string escaping for `\`, `(`, `)` — prevents injection
+- CIDFont hex encoding — no string injection vector
+- TTF subsetting uses typed arrays with bounds checking + compound glyph iteration limits
+- XRef offset guard: validates byte offsets before writing cross-reference table
+- JPEG parser robustness: validates SOF markers and handles edge-case byte sequences
+- PDF encryption: AES-128/256 with per-object keys, random IVs — no ECB mode
+- No external crypto dependencies — pure TypeScript AES, MD5, SHA-256 implementations
+- NPM provenance — signed builds via GitHub Actions OIDC
+
+For more details, see [SECURITY.md](SECURITY.md).
+
+## Contributing
+
+We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for:
+
+- Development environment setup
+- Running tests, linting, and type checking
+- Code style requirements (strict TypeScript, pure functions, ESM-first)
+- Branch strategy and PR process
+
+## Citing pdfnative
+
+If you use pdfnative in academic, governmental, or compliance work, please cite it. Citation metadata is available in [CITATION.cff](CITATION.cff).
+
+```bibtex
+@software{pdfnative,
+  author  = {Nizoka},
+  title   = {pdfnative: Zero-dependency, ISO 32000-1 compliant PDF generation for TypeScript},
+  url     = {https://github.com/Nizoka/pdfnative},
+  year    = {2026}
+}
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+Font data files in `fonts/` are licensed under [SIL Open Font License 1.1](https://scripts.sil.org/OFL). Unicode Character Database source files in `scripts/data/` are © Unicode, Inc., used under the [Unicode License v3](https://www.unicode.org/license.txt). See [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md) for the aggregated notices.
 
 ---
 <!-- source: docs/guides/accessibility.md -->
 # Accessibility
 
+> **Tagged PDF, PDF/UA and screen-reader-friendly output.** Pass `layout: { tagged: true }` (or a PDF/A level) and pdfnative emits the structure tree, `/ActualText` and metadata that assistive technology needs — then check the result with the read-only `validatePdfUA()`.
+
 pdfnative produces **tagged, accessible PDFs** out of the box. This guide covers PDF/UA, PDF/A, the structure tree, and best practices for screen-reader-friendly output.
 
 ## Why tagged PDF matters
@@ -178,6 +1674,15 @@ For a real-world test, open your PDF with **NVDA** (Windows, free), **VoiceOver*
 
 Contributions to address these are welcome — see the [Roadmap](https://github.com/Nizoka/pdfnative/blob/main/ROADMAP.md).
 
+> **PDF/A declaration guards** _(v1.7.0)_. Tagged documents that also claim
+> PDF/A are now checked at build time: configurations that would break the
+> declared level (base-14 text without embedded fonts, form fields under a
+> claim, DeviceCMYK images against the sRGB OutputIntent) surface a diagnostic
+> — `console.warn` by default, a custom `onDiagnostic` sink, or a thrown error
+> under `strict: true`. Base-14 dictionaries under tagged mode also gain full
+> `/ToUnicode` coverage, which changes output bytes versus 1.6.0. Details in
+> the [PDF/A guide](pdfa.html).
+
 ## Testing your PDFs are accessible
 
 A pragmatic checklist for solo developers:
@@ -379,7 +1884,7 @@ under the [AI-governance / human-in-the-loop contract](ai-governance.md).
 
 - [AI governance & human-in-the-loop](ai-governance.md) — the contract that keeps
   repository changes human-gated.
-- [MCP integration](mcp.md) — the 24 MCP tools, including `embed_image` and
+- [MCP integration](mcp.md) — the 28 MCP tools, including `embed_image` and
   `draft_governance_issue`.
 - [CLI guide](cli.md) — driving pdfnative from the shell.
 - [Font validation](font-validation.md) — `validateFontData()` for sanity-checking
@@ -531,6 +2036,13 @@ without parsing prose. Key fields:
 The contract `applies_to` the whole ecosystem — `pdfnative`, `pdfnative-cli`,
 `pdfnative-mcp`, and `pdfnative-react`.
 
+Since pdfnative-mcp 1.6.0, that package's mirror of the charter also states
+the **single permitted egress class**: the server makes no outbound request by
+default, and the only network calls it can ever perform go to the TSA / OCSP /
+CRL endpoints the *operator* configures for the PAdES tools — never to a URL
+taken from a tool argument, and never to GitHub. "No GitHub write path" and
+"no telemetry" remain absolute.
+
 ## What agents must never do
 
 - Add a runtime dependency.
@@ -667,6 +2179,8 @@ highlight into an existing PDF.
 <!-- source: docs/guides/architecture.md -->
 # Architecture Guide
 
+> **Two builders, one strict dependency flow.** `buildPDFBytes` is the table-centric builder, `buildDocumentPDFBytes` the free-form document builder; beneath them the modules flow types → core ← fonts ← shaping ← worker, with standalone crypto and parser modules — no circular imports anywhere.
+
 ## Two Builders
 
 pdfnative provides two PDF builders for different use cases:
@@ -778,7 +2292,7 @@ The architecture diagram above shows the **internal library modules**. External
    [shell / CI / Docker] │  pdfnative-cli (npm) — 17 commands          │
                          └─────────────────────────────────────────────┘
                          ┌─────────────────────────────────────────────┐
-    [Claude / Cursor / …] │  pdfnative-mcp (npm) — 24 AI tools          │
+    [Claude / Cursor / …] │  pdfnative-mcp (npm) — 28 AI tools          │
                          └───────────────────────────────────────────┘
                          ┌─────────────────────────────────────────────┐
    [React / Next.js app] │  pdfnative-react (npm) — declarative JSX    │
@@ -809,13 +2323,13 @@ Like `pdfnative-mcp` and `pdfnative-react`, the CLI lives in a separate reposito
 
 ### pdfnative-mcp
 
-[pdfnative-mcp](https://github.com/Nizoka/pdfnative-mcp) is a **Model Context Protocol server** that wraps the pdfnative public API and exposes it as 24 structured tools to any MCP-compatible AI client (Claude Desktop, Cursor, Continue, Zed, ChatGPT, …). It commits to API stability via a per-tool `_meta.apiVersion` field.
+[pdfnative-mcp](https://github.com/Nizoka/pdfnative-mcp) is a **Model Context Protocol server** that wraps the pdfnative public API and exposes it as 28 structured tools to any MCP-compatible AI client (Claude Desktop, Cursor, Continue, Zed, ChatGPT, …). It commits to API stability via a per-tool `_meta.apiVersion` field.
 
 ```
 [Claude Desktop / Cursor / Continue / Zed]
               │ MCP stdio protocol
      ┌──────────────────────────┐
-      │  pdfnative-mcp (npm)     │  ← MCP server, 24 tools
+      │  pdfnative-mcp (npm)     │  ← MCP server, 28 tools
      └──────────────────────────┘
               │ import { buildDocumentPDFBytes, … } from 'pdfnative'
      ┌──────────────────────────┐
@@ -1110,11 +2624,121 @@ labels shape correctly when the matching font is registered — no extra work.
 - [Accessibility](accessibility.html) — tagged PDF / PDF-UA
 - [CHANGELOG](https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md)
 
+---
+<!-- source: docs/guides/choose.md -->
+# Choosing your surface
+
+> **Write application code → the library. Drive a shell, Makefile or CI job →
+> `pdfnative-cli`. Give a conversational AI assistant tool access →
+> `pdfnative-mcp`. Author documents inside a React 19 app →
+> `pdfnative-react`.** All four surfaces sit on the same zero-dependency
+> engine and produce the same ISO 32000-1 / PDF/A-conformant bytes, so the
+> choice is about *who is calling*, not about what comes out — and you can
+> switch later without re-authoring your documents.
+
+## The decision, in prose
+
+**You are writing application code** — a Node.js, Deno, Bun or browser
+service, a worker, a script with logic around the PDF. Use the **library**
+(`npm install pdfnative`). It is the full surface: synchronous builders, the
+parser, signatures with long-term validation, streaming, Web Worker support.
+Everything the other three surfaces do, they do by calling this package.
+
+**You are driving a shell, a CI pipeline, a container, or a build tool in
+another language.** Use the **CLI** (`pdfnative-cli`, binary `pdfnative`) —
+17 commands over stdin/stdout pipelines, with an agent-native automation
+contract: a `--json` envelope, stable `E_*` error codes, `--dry-run`, and
+compact `--summary` / `--fields` output projection. No JavaScript required.
+
+**You are (or you are building) a conversational assistant with tool
+access** — Claude Desktop, Cursor, Continue, Zed, or any Model Context
+Protocol client. Use the **MCP server** (`pdfnative-mcp`, `npx -y
+pdfnative-mcp`) — 28 tools with strict JSON Schemas, read-back tools for
+self-verification, and no outbound network access except the
+operator-configured TSA/OCSP/CRL endpoints.
+
+**Your host application is React 19.** Use the **React renderer**
+(`pdfnative-react`) — declarative JSX compiled on-device to pdfnative blocks
+by a custom reconciler (no DOM, no headless browser), with live-preview hooks
+and the token-frugal `DocSpec` for agent authoring. React 19 is a peer
+dependency of this package only; the engine stays zero-dependency.
+
+## Capability × surface
+
+The same facts in machine-readable form live in
+[`docs/data/surfaces.json`](../data/surfaces.json); tool, command and export
+names are verified against
+[`docs/assets/ecosystem.json`](../assets/ecosystem.json) and the engine's
+export surface by the documentation CI. Version annotations name the release
+*of that surface's own package* which introduced the capability; an em-dash
+means the surface does not offer it.
+
+| Capability | Library (`pdfnative`) | CLI (`pdfnative-cli`) | MCP (`pdfnative-mcp`) | React (`pdfnative-react`) |
+|---|---|---|---|---|
+| Generate documents | `buildDocumentPDFBytes` / `buildPDFBytes` | `render` | `generate_basic_pdf` (+ the dedicated document tools) | `renderToBytes` and friends, `<Document>` tree |
+| Smart tables | `table` block | `render` (`table` block, or `--variant table`) | `add_table` | `<Table>` |
+| Native vector charts | `chart` block _(v1.6.0)_ | `render` (`chart` block) _(v1.3.0)_ | `add_chart` _(v1.5.0)_ | `<Chart>` _(v1.1.0)_ |
+| Digital signatures (PAdES CMS) | `addSignaturePlaceholder` _(v1.2.0)_ + `signPdfBytes` | `sign` | `sign_pdf` (+ `prepare_signature_placeholder`) | — |
+| LTV ladder (B-T → B-LTA) | `signPdfBytesWithTimestamp`, `addValidationInfo`, `addDocumentTimestamp` _(v1.7.0)_ | — (verification only: `verify --revocation`) | `add_ltv`, `timestamp_pdf` _(v1.6.0)_ | — |
+| Encrypt / decrypt | build-time `encryption` layout option; existing PDFs via the page-tree `encrypt` option and `openPdf` with a password | `encrypt` / `decrypt` _(v1.3.0)_ | `encrypt_pdf` / `decrypt_pdf` _(v1.5.0)_ | build-time only, via the `layout` render option |
+| Fill / flatten forms | `readFormFields`, `fillForm`, `flattenForm` _(v1.6.0)_ | `fill` _(v1.3.0)_ | `read_form_fields`, `fill_form` _(v1.5.0)_ | — |
+| Extract text | `extractText` _(v1.6.0)_ | `extract-text` _(v1.3.0)_ | `extract_text` | — |
+| Merge / split / extract pages | `mergePdfs`, `splitPdf`, `extractPages` _(v1.4.0)_ | `merge` / `split` / `extract` _(v1.2.0)_ | `merge_pdfs` / `split_pdf` / `extract_pages` _(v1.3.0)_ | — |
+| Markup annotations | `buildAnnotation` + `PdfModifier.addAnnotation` _(v1.5.0)_ | `annotate` _(v1.2.0)_ | `annotate_pdf` _(v1.4.0)_ | — |
+| Inspect layout (pagination dry run) | `inspectDocumentLayout` _(v1.5.0)_ | `render --inspect-layout` _(v1.2.0)_ | `inspect_layout` _(v1.6.0)_ | `inspectDocument` |
+| Validate PDF/UA | `validatePdfUA` _(v1.3.0)_ | `inspect --pdfua` _(v1.1.0)_ | `validate_pdf` _(v1.1.0)_ | — (`lintDocument` checks the authoring model before rendering, not the emitted PDF) |
+
+## Honest notes
+
+- **LTV differs by surface on purpose.** The engine opens no socket: in the
+  **library**, the RFC 3161 / OCSP / CRL transport is *injected by your code*
+  (`setTimestampProvider` / `setRevocationProvider`). On **MCP**, the transport
+  is *operator-configured* through environment variables
+  (`PDFNATIVE_MCP_TSA_URL`, `PDFNATIVE_MCP_REVOCATION`, an allow-list) — never
+  from tool arguments. The **CLI** currently *verifies* LTV material
+  (`verify --revocation`, RFC 3161 timestamp validation) but does not create
+  it — sign-side LTV is documented as out of scope there.
+- **The engine ships no cryptographic signature verifier.** `listSignatures`
+  is an inventory; full verification (digest, CMS, chain, trust, timestamps,
+  revocation) lives in `pdfnative-cli verify` and the MCP `verify_pdf` tool.
+- **React is an authoring surface.** It generates documents (including charts,
+  barcodes, SVG, form *widgets* and build-time encryption via the `layout`
+  render option) but does not operate on existing PDFs — no fill, extract,
+  merge or signing. When a React app needs those, call the library directly:
+  it is already installed as the renderer's peer dependency.
+- **The MCP tool names, CLI commands and library exports in the table are the
+  complete story for these capabilities**, not a sample — where a cell is an
+  em-dash, the surface genuinely lacks the capability today rather than
+  hiding it under another name.
+
+## You can switch later
+
+All four surfaces call the same engine, so the artefacts are interchangeable:
+a PDF rendered by the React reconciler can be signed by the CLI, inspected by
+an MCP tool, and have its text extracted by the library. Document *inputs*
+travel too — the CLI's `render` consumes the same `DocumentParams` JSON the
+library takes, the MCP `generate_basic_pdf` blocks mirror the engine's block
+kinds, and `pdfnative-react` compiles JSX (or a `DocSpec`) into that same
+model. Starting on the "wrong" surface costs a call-site migration, not a
+document rewrite.
+
+## Further reading
+
+- [Onboarding](onboarding.html) — the 90-second install-and-first-call for
+  each surface.
+- [Self-verifying generation](self-verify.html) — the generate → inspect →
+  assert → correct loop on every surface.
+- [Architecture](architecture.html) — how the four packages relate.
+- [CLI guide](cli.html) · [MCP guide](mcp.html) · [React guide](react.html) —
+  the complete per-surface references.
+- [Agent brief](../agent-brief.md) — the same decision tree in
+  paste-into-context form for AI agents.
+
 ---
 <!-- source: docs/guides/cli.md -->
 # pdfnative-cli — Command-Line Interface Guide
 
-> **Tracks the latest published `pdfnative-cli`** (v1.3.0, built on pdfnative 1.7.0). The CLI versions independently from the library. Live package versions — and the `pdfnative` version each one is built on — are shown at the top of the [documentation home](../index.html). Full history: [pdfnative-cli releases](https://github.com/Nizoka/pdfnative-cli/releases).
+> **Tracks the latest published `pdfnative-cli`** (v1.3.0, built on the pdfnative 1.6 engine — pins `^1.6.0`, which semver-accepts 1.7.0). The CLI versions independently from the library. Live package versions — and the `pdfnative` version each one is built on — are shown at the top of the [documentation home](../index.html). Full history: [pdfnative-cli releases](https://github.com/Nizoka/pdfnative-cli/releases).
 
 [`pdfnative-cli`](https://github.com/Nizoka/pdfnative-cli) is the **official command-line interface** for the [`pdfnative`](https://github.com/Nizoka/pdfnative) library. It exposes 17 commands in five groups — create & edit (`render`, `fill`, `annotate`), page tree (`merge`, `split`, `extract`), security (`sign`, `verify`, `encrypt`, `decrypt`), read & extract (`inspect`, `extract-text`), and automation & meta (`batch`, `doctor`, `schema`, `completion`, `govern`) — that together cover the full document lifecycle from JSON to a signed, verified, archive-grade PDF, plus page-tree editing, markup annotations, and an AI-governance gate, with an agent-native automation contract for autonomous AI and CI pipelines.
 
@@ -1987,12 +3611,12 @@ node samples/run-all.js
 
 ### What's new in v1.3.0
 
-v1.3.0 is built on **pdfnative 1.7.0** and surfaces its engine additions as five new commands (`extract-text`, `fill`, `encrypt`, `decrypt`, `doctor`), native vector charts in `render`, and password / re-encryption / constant-memory streaming on the page-tree commands. Fixes a silent `render --encrypt` no-op. **100 % backward-compatible** with v1.2.0.
+v1.3.0 is built on the **pdfnative 1.6 engine** (pin `^1.6.0`) and surfaces its engine additions as five new commands (`extract-text`, `fill`, `encrypt`, `decrypt`, `doctor`), native vector charts in `render`, and password / re-encryption / constant-memory streaming on the page-tree commands. Fixes a silent `render --encrypt` no-op. **100 % backward-compatible** with v1.2.0.
 
 | Area | v1.2.0 | v1.3.0 |
 |---|---|---|
 | Commands | 12 commands <!-- verify-docs:allow stale-token (v1.2.0-era count) --> | adds **`fill`** (fill / flatten / **export** AcroForms via an incremental save), **`encrypt`**, **`decrypt`**, **`extract-text`** (reading-order Unicode text: `text` \| `json` \| `ndjson`), and **`doctor`** (offline environment / capability preflight) |
-| Charts | — | the pdfnative 1.7.0 `chart` document block (bar, barH, line, pie, donut) renders as pure vector path operators through `render` |
+| Charts | — | the engine's `chart` document block (bar, barH, line, pie, donut — the pdfnative 1.6 set) renders as pure vector path operators through `render` |
 | Encryption vocabulary | `--encrypt-*` flags on `render` only | **unified vocabulary** — `--encrypt [aes-128\|aes-256]`, `--owner-password`, `--user-password`, `--permissions print,copy,modify,extract` — shared by `render`, `merge`, `split` and `extract` (legacy `--encrypt-*` flags kept as aliases) |
 | Page-tree commands | plaintext sources only | **`--password`** reads encrypted sources; **`--encrypt`** re-encrypts the output; **`--stream`** (+ `--chunk-size`) streams the output with constant memory |
 | Inspection | metadata, PDF/UA, annotations | adds `inspect --form-fields`, `--encryption` and `--password` |
@@ -3189,6 +4813,14 @@ Both operations use the incremental modifier
 rewritten — the update is appended after the existing body with a new xref and a
 `/Prev` chain. That is why signatures on earlier revisions stay valid.
 
+> **Searchable form text** _(v1.7.0)_. The AcroForm `/Helv` font dictionary now
+> carries a `/ToUnicode` CMap in every mode, so text typed into form fields is
+> searchable and extractable (see the [text extraction guide](text-extraction.html)).
+> Because of that CMap, **every form-carrying document changes bytes** compared
+> to v1.6.0 output (about 20 bytes) — a deliberate correctness fix, recorded in
+> the v1.7.0 release notes. Under a PDF/A claim, a form field also raises the
+> `PDFA_UNEMBEDDED_FORM_FONT` diagnostic (see the [PDF/A guide](pdfa.html)).
+
 ## See also
 
 - [Signatures](signatures.html) — CMS/PKCS#7 signing
@@ -3343,7 +4975,7 @@ The repository ships a deterministic offline mock PKI (`scripts/helpers/mock-pki
 - `listSignatures(bytes)` — every entry, its SubFilter, ByteRange, placeholder/timestamp status.
 - Adobe Reader: *Signature Panel → Certificate Details* — trust the mock/company root, then look for **"LTV enabled"** on B-LT documents and a valid document timestamp on B-LTA.
 - `openssl ts -reply -in token.der -text` inspects extracted timestamp tokens.
-- pdfnative itself ships **no signature verifier** — validation belongs to dedicated tooling (veraPDF for PDF/A, Adobe/DSS for signatures, `pdfnative-cli verify` for structural checks).
+- pdfnative itself ships **no signature verifier** — validation belongs to dedicated tooling (veraPDF for PDF/A, Adobe/DSS for signatures, `pdfnative-cli verify` for full cryptographic verification: CMS signature values, certificate chain and trust, RFC 3161 timestamps, OCSP/CRL revocation).
 
 ## Limits & scope (v1.7.0)
 
@@ -3357,7 +4989,7 @@ The repository ships a deterministic offline mock PKI (`scripts/helpers/mock-pki
 <!-- source: docs/guides/mcp.md -->
 # pdfnative-mcp — AI Client Integration Guide
 
-> **Tracks the latest published `pdfnative-mcp`** (v1.5.0, built on pdfnative 1.7.0). Full release notes: [pdfnative-mcp releases](https://github.com/Nizoka/pdfnative-mcp/releases). Live package versions — and the `pdfnative` version each one is built on — are shown at the top of the [documentation home](../index.html).
+> **Tracks the latest published `pdfnative-mcp`** (v1.6.0, built on pdfnative 1.7.0). Full release notes: [pdfnative-mcp releases](https://github.com/Nizoka/pdfnative-mcp/releases). Live package versions — and the `pdfnative` version each one is built on — are shown at the top of the [documentation home](../index.html).
 
 [pdfnative-mcp](https://github.com/Nizoka/pdfnative-mcp) is an **MCP server** that exposes the full pdfnative library to any AI client supporting the [Model Context Protocol](https://modelcontextprotocol.io) — Claude Desktop, Cursor, Continue, Zed, ChatGPT, and more.
 
@@ -3477,26 +5109,38 @@ In your Zed `settings.json`:
 | `PDFNATIVE_MCP_OUTPUT_DIR` | Absolute path to the sandbox directory. **Required to enable `outputMode: "file"`**. When unset, only `base64` output is available. (The misspelt `PDFNATIVE_MPC_OUTPUT_DIR` still works as a deprecated alias.) |
 | `PDFNATIVE_MCP_CACHE_DIR` | Absolute path to enable the persistent SHA-256-keyed result cache (1 h TTL, 256 MiB LRU). When unset, the cache is disabled. |
 | `PDFNATIVE_MCP_PORT` | When set to a valid port (1–65535), starts an HTTP server on `http://127.0.0.1:<port>/mcp` instead of stdio. |
+| `PDFNATIVE_MCP_HTTP_TOKEN` _(v1.6.0)_ | Opt-in bearer token for the HTTP transport (≥ 16 characters, no whitespace — a weaker value aborts startup). When set, `/mcp` requires `Authorization: Bearer <token>`; otherwise requests get `401` + `WWW-Authenticate`. Without it the loopback endpoint has **no authentication**. Never logged. |
+| `PDFNATIVE_MCP_MAX_INFLATE_BYTES` _(v1.6.0)_ | Operator override of the engine's 100 MiB per-stream decompression cap (integer ≥ 1024, read once at startup; an invalid value refuses to start with one clean `fatal:` line). |
+| `PDFNATIVE_MCP_TSA_URL` _(v1.6.0)_ | RFC 3161 timestamp authority endpoint. Required by `sign_pdf timestamp: true` and `timestamp_pdf` (`TSA_NOT_CONFIGURED` otherwise). |
+| `PDFNATIVE_MCP_TSA_AUTH` _(v1.6.0)_ | Optional `Authorization` header value sent to the TSA. Treated as a secret; never logged. |
+| `PDFNATIVE_MCP_REVOCATION` _(v1.6.0)_ | Revocation sources for `add_ltv mode: 'online'` — `ocsp`, `crl`, or `ocsp,crl` (`REVOCATION_NOT_CONFIGURED` otherwise). |
+| `PDFNATIVE_MCP_NETWORK_ALLOWED_HOSTS` _(v1.6.0)_ | Mandatory allow-list of hosts the OCSP/CRL fetcher may contact. A certificate-supplied URL outside the list fails with `NETWORK_HOST_NOT_ALLOWED`. |
+| `PDFNATIVE_MCP_NETWORK_TIMEOUT_MS` _(v1.6.0)_ | Network timeout for TSA/OCSP/CRL requests (1000–120000 ms, default 10000). |
+
+> **Network charter** _(v1.6.0)_. The server still makes **no outbound request by default**. The only egress it can ever perform goes to the TSA / OCSP / CRL endpoints the **operator** configures via the variables above — URLs never come from tool arguments, and certificate-supplied OCSP/CRL URLs pass an SSRF guard (allow-list, http(s) only, no credentials, no redirects, internal address literals rejected, size caps, timeouts).
 
 ---
 
 ## Tool reference
 
-`pdfnative-mcp` exposes **24 tools**:
+`pdfnative-mcp` exposes **28 tools**:
 
 | Tool | Purpose |
 |---|---|
-| `generate_basic_pdf` | Multi-page A4 documents from structured blocks (headings, paragraphs, lists, spacers, charts, page breaks). Accepts optional `pdfA`. |
+| `generate_basic_pdf` | Multi-page documents from structured blocks — all **13 block kinds** since v1.6.0 (headings, paragraphs, lists, tables, images, links, TOC, barcodes, SVG, form fields, charts, page breaks, spacers). Accepts optional `pdfA`, layout options, build-time `encrypt`, and print-production fields. |
 | `add_table` | Tabular PDF reports from column headers and data rows. Optional `autoFitColumns` and `clipCells`. Accepts `pdfA`. |
 | `add_barcode` | QR Code, Code 128, EAN-13, Data Matrix, PDF417 — embedded in a single-page PDF. Accepts `pdfA`. |
-| `add_international_text` | 24 `lang` font codes — the 22 writing systems plus `latin` and `emoji` — with BiDi & OpenType shaping, plus the explicit `math` script (Noto Sans Math, on-demand). `lang` accepts `string`, `string[]`, or comma-separated. |
-| `add_form` | Interactive AcroForm PDFs with text fields, checkboxes, radio buttons, and dropdowns. Accepts `pdfA`. |
-| `embed_image` | Embed a JPEG or PNG image (base64-encoded) into a titled PDF document. Accepts `pdfA`. |
-| `prepare_signature_placeholder` | Create a PDF with a `/Sig` AcroForm placeholder ready to be signed. Accepts `pdfA`. |
-| `sign_pdf` | PAdES-style CMS digital signatures (RSA-SHA256 / ECDSA-SHA256 P-256). |
-| `inspect_pdf` | Read-only inspection. Returns `version`, `pageCount`, `encryption`, `pdfA`, `signatureCount`, `info`, optional `perPage`, optional `pageLabels[]` (when `/PageLabels` is declared), optional `checks` + `checksPassed`. |
+| `add_international_text` | 25 `lang` font codes — the 22 writing systems plus `latin`, `emoji` and the explicit `math` script (Noto Sans Math, on-demand) — with BiDi & OpenType shaping. `lang` accepts `string`, `string[]`, or comma-separated. |
+| `add_form` | Interactive AcroForm PDFs with text fields, text areas, checkboxes, radio buttons, dropdowns, and list boxes _(v1.6.0)_. Accepts `pdfA`. |
+| `embed_image` | Embed a JPEG or PNG image (base64-encoded) into a titled PDF document, with `align` and `alt` _(v1.6.0)_. Accepts `pdfA`. |
+| `prepare_signature_placeholder` | Create a PDF with a `/Sig` AcroForm placeholder ready to be signed; `subFilter`, `reserveTimestamp` and frozen signer metadata _(v1.6.0)_. Accepts `pdfA`. |
+| `sign_pdf` | PAdES CMS digital signatures — RSA-SHA256/384/512 and ECDSA-SHA256 P-256, `profile: 'pades'`, RFC 3161 `timestamp` (B-T), certificate chains, named fields and multiple signatures _(v1.6.0)_. |
+| `add_ltv` _(v1.6.0)_ | Embed long-term-validation material (`/DSS` + `/VRI`) into a signed PDF — PAdES **B-LT** — online through the operator-configured revocation provider or offline from caller-supplied material. |
+| `timestamp_pdf` _(v1.6.0)_ | Append a `/DocTimeStamp` (ETSI.RFC3161) through the operator TSA — PAdES **B-LTA** — with auto-suffixed field names for periodic re-timestamping. |
+| `inspect_pdf` | Read-only inspection. Returns `version`, `pageCount`, `encryption`, `pdfA`, `signatureCount`, `info`, optional `perPage`, optional `pageLabels[]`, and — _(v1.6.0)_ — an optional `signatures[]` inventory, `annotations[]`, page boxes + `userUnit`, `dss` / `docTimestampCount` / `trapped`, plus `checks` + `checksPassed`. |
+| `inspect_layout` _(v1.6.0)_ | Read-only pagination **dry run** — page count, page geometry and each block's position for a prospective document, with no PDF produced. |
 | `validate_pdf` | Read-only PDF/UA structural validation (`valid`, `errors`, `warnings`). |
-| `verify_pdf` | Real CMS/PKCS#7 signature verification — RSA & ECDSA, message digest, certificate chain. (RFC 3161 timestamp validation is a `pdfnative-cli verify` feature, not part of this server.) |
+| `verify_pdf` | Real CMS/PKCS#7 signature verification — RSA & ECDSA, message digest, certificate chain. Since v1.6.0, `/DocTimeStamp` entries are verified as RFC 3161 tokens and `ltv: true` reports the achieved PAdES level (B-B → B-LTA). |
 | `add_attachment` | Embed files (e.g. Factur-X / ZUGFeRD e-invoice XML) into PDF/A-3b output. |
 | `extract_attachments` | Extract embedded files from an existing PDF (optionally metadata-only). |
 | `extract_text` | Extract text content from an existing PDF via the native parser. |
@@ -3505,13 +5149,14 @@ In your Zed `settings.json`:
 | `extract_pages` | Pull an arbitrary, order-preserving page subset (max 5000) into a single PDF. |
 | `annotate_pdf` | Overlay markup annotations (text / highlight / underline / strikeout / squiggly / square / circle / line / freetext) on an existing PDF via incremental update. A visual review layer, **not** a redaction. |
 | `draft_governance_issue` | Assemble a governance-compliant GitHub-issue draft plus a structured `compliance` report **locally** — network-free by construction; never submits. |
-| `add_chart` _(v1.5.0)_ | Render a bar, horizontal-bar, line, pie or donut chart as **native PDF vector paths** — no rasterisation and no image round-trip. Tagged as `/Figure` with alt text when `pdfA` is set. |
+| `add_chart` _(v1.5.0)_ | Render a chart as **native PDF vector paths** — nine types since v1.6.0 (`bar`, `barH`, `stackedBar`, `stackedBarH`, `line`, `area`, `scatter`, `pie`, `donut`), with a secondary axis, log and time scales, and data labels. Tagged as `/Figure` with alt text when `pdfA` is set. |
 | `read_form_fields` _(v1.5.0)_ | List an existing AcroForm's fields with their types, current values and available options — the read half of the fill round-trip. Accepts `password`. |
 | `fill_form` _(v1.5.0)_ | Fill AcroForm field values and optionally `flatten` them into static page content. Works on encrypted PDFs via incremental update. |
 | `encrypt_pdf` _(v1.5.0)_ | Re-secure an existing PDF with AES-128 or AES-256 — owner/user passwords and an explicit permission set. |
 | `decrypt_pdf` _(v1.5.0)_ | Remove encryption from a password-protected PDF **in-server** — RC4, AES-128 and AES-256 sources. |
+| `update_metadata` _(v1.6.0)_ | Rewrite an existing PDF's `/Info` dictionary (+ XMP) — title, author, subject, keywords, pinned `modDate` — as a non-destructive incremental update. |
 
-Every tool now publishes an `outputSchema` advertised in `tools/list` per the [MCP 2025-06-18 spec](https://modelcontextprotocol.io/specification/2025-06-18), enabling clients to statically validate responses.
+Every tool publishes an `outputSchema` advertised in `tools/list`. Since v1.6.0 the server speaks the [MCP 2026-07-28 spec](https://modelcontextprotocol.io/specification/2026-07-28) (stateless envelope, `server/discover`, `resultType`, cache hints) on SDK v2, while 2025-era clients (2025-11-25 / 2025-06-18 / 2025-03-26) keep working through the automatic legacy fallback.
 
 ---
 
@@ -3534,7 +5179,17 @@ Produces a multi-page document from a list of content blocks.
 }
 ```
 
-**Block types supported:** `heading` (levels 1–3), `paragraph`, `list` (`bullet` / `numbered`, nested items to depth 6), `pageBreak`, `spacer` (`height` in points), and `chart` (same body as `add_chart`).
+**Block types supported:** all **13 engine block kinds** since v1.6.0 — `heading` (levels 1–3), `paragraph`, `list` (`bullet` / `numbered`, nested items to depth 6), `table`, `image`, `link` (`http:` / `https:` / `mailto:` only), `toc` (a contents page with internal `/GoTo` links, pairs with `outline: 'auto'`), `barcode`, `svg` (a safe subset: paths, shapes and text — no XML parser, no external reference ever fetched), `formField`, `chart` (same body as `add_chart`), `pageBreak`, and `spacer` (`height` in points). The `table` / `image` / `barcode` / `formField` blocks share their body with the dedicated tools, so a standalone artefact and an inline block validate and render identically.
+
+**Layout options** _(v1.6.0)_, available on all nine document tools: `pageSize` (`A4` default, `Letter`, `Legal`, `A3`, `Tabloid`), `margins` (all four sides, 0–200 pt), running `headerTemplate` / `footerTemplate` (`left` / `center` / `right` zones with `{page}` `{pages}` `{title}` `{date}` placeholders — a `footerTemplate` replaces the default footer, so `footerText` is then ignored), `compress`, and `debug`.
+
+**Build-time `encrypt`** _(v1.6.0)_, on `generate_basic_pdf`, `add_table`, `add_form`, `add_international_text`, `embed_image`, `add_barcode` and `add_chart`: AES-128 (default) or AES-256 with owner/user passwords and permissions — and unlike `encrypt_pdf`, it **keeps the AcroForm**, making encrypted fillable forms reachable. Exclusive with `pdfA` (ISO 19005-1 §6.3.2); never cached.
+
+**Print production** _(v1.6.0)_, on the nine document tools: `print` (TrimBox / BleedBox / ArtBox / CropBox, a `bleed` shorthand, crop + registration `marks`, `/UserUnit`), `metadata` (`/Author`, `/Subject`, `/Keywords`, `/Trapped` with XMP parity), and `outputIntent` (custom RGB ICC profile). `viewerPreferences` gains `duplex`, `pickTrayByPDFSize`, `printPageRange` (1-based), `numCopies`. Boxes survive `merge_pdfs` / `split_pdf` / `extract_pages` and are reported by `inspect_pdf`.
+
+**Honest PDF/A** _(v1.6.0)_: text rendered through the viewer's base-14 Helvetica is not embedded, so a PDF/A claim on such a file is rejected by veraPDF. `embedFonts: true` embeds Noto Sans Latin for a valid claim; `strict: true` fails instead of producing a non-conformant file; `includeDiagnostics: true` echoes the engine's diagnostics (`PDFA_NO_FONT_ENTRIES`, `PDFA_UNEMBEDDED_FORM_FONT`, `PDFA_DEVICE_CMYK_IMAGE`).
+
+**Reproducible output** _(v1.6.0)_: `creationDate` (ISO-8601) on all nine document tools pins `/Info /CreationDate`, the XMP dates and therefore the trailer `/ID` — byte-identical output on the same host time zone.
 
 ---
 
@@ -3618,7 +5273,7 @@ Creates an interactive AcroForm PDF.
 }
 ```
 
-**Field types:** `text`, `textarea`, `checkbox`, `radio`, `dropdown`.
+**Field types:** `text`, `textarea`, `checkbox`, `radio`, `dropdown`, and `listbox` _(v1.6.0)_. Text fields accept an optional `placeholder` _(v1.6.0)_. Since v1.6.0, `textarea` maps to the engine's true multi-line field (`/Ff 4096`) — in v1.5.0 it rendered as a single-line widget.
 
 ---
 
@@ -3637,6 +5292,8 @@ Creates an interactive AcroForm PDF.
 
 > **Note:** Alpha-channel PNGs (color type 6) are not supported. Pre-process such images to remove the alpha channel before embedding.
 
+Since v1.6.0 the tool also accepts `align` (horizontal placement) and `alt` (accessibility text written as `/Figure /Alt` in tagged output).
+
 ---
 
 ### `prepare_signature_placeholder`
@@ -3656,6 +5313,8 @@ Creates a PDF pre-wired with an AcroForm `/Sig` field, ready to be signed by `si
 }
 ```
 
+Since v1.6.0 the placeholder also takes `subFilter`, `reserveTimestamp` (extra `/Contents` room for a later RFC 3161 token), `placeholderBytes`, and `signingTime` — and the signer metadata (`signerName`, `reason`, `location`, `contactInfo`, `signingTime`) is **baked into the `/Sig` dictionary at placeholder time**, fixing a pre-1.7 engine bug where those values never reached the signed document.
+
 ---
 
 ### `sign_pdf`
@@ -3677,6 +5336,17 @@ Signs any PDF. When the input already contains a `/Sig` placeholder (e.g. produc
 
 For ECDSA P-256: use `"algorithm": "ecdsa-sha256"` and supply either `ecPrivateScalarHex` (64 hex chars, raw scalar `d`) or `ecPrivateKeyDerBase64` (SEC1 / PKCS#8 DER, base64 — signed through the constant-time `node:crypto` path) instead of `rsaKeyPkcs1DerBase64`. The two EC inputs are mutually exclusive.
 
+**PAdES and timestamps** _(v1.6.0)_:
+
+- `algorithm` also accepts `rsa-sha384` and `rsa-sha512`.
+- `profile: 'pades'` produces an ETSI.CAdES.detached signature (PAdES **B-B**).
+- `timestamp: true` requests an RFC 3161 timestamp from the operator-configured TSA (`PDFNATIVE_MCP_TSA_URL`) and embeds it in the CMS — PAdES **B-T**. Fails with `TSA_NOT_CONFIGURED` when no TSA is set, `TSA_REJECTED` when the authority declines.
+- `certChainDerBase64` embeds intermediate certificates alongside the signer certificate.
+- `fieldName` targets a specific `/Sig` field (`SIGNATURE_FIELD_NOT_FOUND` when absent, `PLACEHOLDER_AMBIGUOUS` when several placeholders exist and none is named); `allowMultiple: true` adds a signature next to existing ones instead of rejecting.
+- The default placeholder reservation is now `max(16384, estimated CMS size)` — plus 8192 bytes when `timestamp: true` — instead of a flat 16384 bytes. To pin it exactly, build the placeholder with `prepare_signature_placeholder` and its `placeholderBytes` input.
+
+To climb the rest of the PAdES ladder, follow with [`add_ltv`](#add_ltv-v160) (B-LT) and [`timestamp_pdf`](#timestamp_pdf-v160) (B-LTA), then check the achieved level with `verify_pdf ltv: true`. The server's `pades_ladder` prompt walks through the full recipe.
+
 ---
 
 ### `inspect_pdf`
@@ -3694,12 +5364,14 @@ Read-only PDF inspection over `openPdf()`. Never modifies the input.
 **Inputs:**
 - `pdfBase64` — base64 PDF bytes (required).
 - `password` — password for an encrypted PDF *(v1.5.0)*.
-- `pages` — when `true`, includes per-page `index`, `width`, `height`.
-- `check` — array of CI assertions. Allowed values: `pdfa`, `signed`, `encrypted`, `placeholder`, `attachments`. The response includes `checks` (per-assertion result) and `checksPassed` (boolean AND).
+- `pages` — when `true`, includes per-page `index`, `width`, `height` — and, since v1.6.0, the declared page boxes and `userUnit`.
+- `signatures` *(v1.6.0)* — when `true`, a per-signature inventory: `subFilter`, `isDocTimestamp`, `isPlaceholder`, `byteRange`, `vriKey`.
+- `annotations` *(v1.6.0)* — when `true`, an `annotations[]` list (0-based `page`, `subtype`, `rect`, and when present `contents`, `title`, `color`, `quadPoints`, link `url`) plus `annotationCount`.
+- `check` — array of CI assertions. Allowed values: `pdfa`, `signed`, `encrypted`, `placeholder`, `attachments`, and — *(v1.6.0)* — `dss`, `docTimestamp`, `trapped`, `annotations`. The response includes `checks` (per-assertion result) and `checksPassed` (boolean AND). Since v1.6.0, `checks` contains **only the requested keys**.
 - `verbosity` — `'full'` (default) or `'summary'` (token-frugal scalar subset).
 - `fields` — optional dot-path projection of the result.
 
-**Outputs:** `version`, `pageCount`, `encryption` (`'none'` / `'aes-128'` / `'aes-256'` / `'rc4'` / `'unknown'`), optional `encryptionInfo` (`{ algorithm, revision, authenticatedAs }`, present when the document is encrypted and opened successfully), `pdfA` (`null` or the detected claim string), `signatureCount`, `hasSignaturePlaceholder`, `attachments[]` (embedded-file summaries), `info` (decoded `/Info` entries), optional `perPage[]`, optional `pageLabels[]` (when `/PageLabels` is declared), optional `checks` + `checksPassed`.
+**Outputs:** `version`, `pageCount`, `encryption` (`'none'` / `'aes-128'` / `'aes-256'` / `'rc4'` / `'unknown'`), optional `encryptionInfo` (`{ algorithm, revision, authenticatedAs }`, present when the document is encrypted and opened successfully), `pdfA` (`null` or the detected claim string), `signatureCount`, `hasSignaturePlaceholder`, `attachments[]` (embedded-file summaries), `info` (decoded `/Info` entries), optional `perPage[]`, optional `pageLabels[]` (when `/PageLabels` is declared), optional `checks` + `checksPassed` — plus, presence-gated since v1.6.0, `dss`, `docTimestampCount` and `trapped`.
 
 Useful in CI as a final assertion step before publishing a PDF artifact:
 
@@ -3801,7 +5473,7 @@ Assembles a governance-compliant GitHub-issue draft plus a structured `complianc
 
 ### `add_chart` _(v1.5.0)_
 
-Renders a bar, horizontal-bar, line, pie or donut chart as **native PDF vector paths** — no rasterisation, no image round-trip. Multi-series bar/line, legends, gridlines and negative values are supported; the chart is tagged `/Figure` with `/Alt` (auto-generated when `altText` is omitted).
+Renders a chart as **native PDF vector paths** — no rasterisation, no image round-trip. Multi-series bar/line, legends, gridlines and negative values are supported; the chart is tagged `/Figure` with `/Alt` (auto-generated when `altText` is omitted).
 
 ```jsonc
 {
@@ -3814,7 +5486,9 @@ Renders a bar, horizontal-bar, line, pie or donut chart as **native PDF vector p
 }
 ```
 
-**Inputs:** `chartType` (`bar` / `barH` / `line` / `pie` / `donut`) and `series` (required; pie/donut take exactly one series), plus `title`, `legend` (`'bottom'` / `'none'`), `markers` (line series), `colors` (hex palette override), `altText`, `intro` (paragraph above the chart), `pdfA`, `outputMode` / `outputPath`. For a chart amongst headings/paragraphs/tables, use a `chart` block inside `generate_basic_pdf` — both build identical pdfnative blocks.
+**Inputs:** `chartType` (`bar` / `barH` / `line` / `pie` / `donut`, plus — _(v1.6.0)_ — `stackedBar` / `stackedBarH` / `area` / `scatter`) and `series` (required; pie/donut take exactly one series), plus `title`, `legend` (`'bottom'` / `'none'`), `markers` (line series), `colors` (hex palette override), `altText`, `intro` (paragraph above the chart), `pdfA`, `outputMode` / `outputPath`. For a chart amongst headings/paragraphs/tables, use a `chart` block inside `generate_basic_pdf` — both build identical pdfnative blocks.
+
+**Charts v2** _(v1.6.0)_: per-series `xValues` with `xAxis.type: 'linear' | 'time'` (UTC-deterministic time axes), a secondary right axis (`axis2`), `axis.scale: 'log'`, `dataLabels`, and `labelStride` / `labelRotation` for crowded x labels. Engine cross-field rules surface as `CHART_ERROR` with a remedy.
 
 ### `read_form_fields` _(v1.5.0)_
 
@@ -3874,22 +5548,101 @@ Opens an encrypted PDF (RC4, AES-128 or AES-256) and emits an unencrypted copy *
 
 > The rebuild drops signatures and `/AcroForm`. To *read* an encrypted PDF without rebuilding it, pass `password` to `inspect_pdf` / `extract_text` / `extract_attachments` instead. Excluded from the response cache.
 
+### `add_ltv` _(v1.6.0)_
+
+Embeds long-term-validation material — a `/DSS` (Document Security Store) with `/VRI` entries — into an already-signed PDF via incremental update, taking a PAdES B-T document to **B-LT**.
+
+```jsonc
+{
+  "pdfBase64": "<base64 signed PDF>",
+  "mode": "online",
+  "preferOcsp": true,
+  "outputMode": "base64"
+}
+```
+
+**Inputs:** `pdfBase64` (required), `mode` (`'online'` default — fetches OCSP responses / CRLs through the operator-configured revocation provider; `'offline'` — embeds parse-validated caller-supplied material), `preferOcsp`, `certificatesDerBase64[]` / `ocspResponsesDerBase64[]` / `crlsDerBase64[]` (offline material), `outputMode` / `outputPath`. The structured result includes a `summary` of what was embedded.
+
+**Errors:** `LTV_NO_SIGNATURE` (nothing to validate), `LTV_EMPTY` (no material gathered), `LTV_MATERIAL_INVALID`, `LTV_ERROR`, `REVOCATION_NOT_CONFIGURED` (online mode without `PDFNATIVE_MCP_REVOCATION`), `NETWORK_HOST_NOT_ALLOWED`, `NETWORK_ERROR`, `ENCRYPTED_SOURCE` (decrypting would destroy the signatures — sign before encrypting).
+
+> Online mode is the **only** network-touching path in the server besides the TSA, and it only ever contacts operator-allow-listed hosts. See *Environment variables* above.
+
+### `timestamp_pdf` _(v1.6.0)_
+
+Appends a `/DocTimeStamp` signature field (ETSI.RFC3161) through the operator-configured TSA, taking a B-LT document to **B-LTA**. The token's status, message imprint and nonce are checked before embedding; its own CMS signature is verified by `verify_pdf`.
+
+```jsonc
+{
+  "pdfBase64": "<base64 signed PDF>",
+  "outputMode": "base64"
+}
+```
+
+**Inputs:** `pdfBase64` (required), `fieldName` (auto-suffixed `DocTimeStamp1`, `DocTimeStamp2`, … when omitted — supporting periodic re-timestamping), `placeholderBytes` (4096–65536), `outputMode` / `outputPath`.
+
+**Errors:** `TSA_NOT_CONFIGURED`, `TSA_REJECTED`, `NETWORK_ERROR`, `ENCRYPTED_SOURCE`.
+
+### `update_metadata` _(v1.6.0)_
+
+Rewrites an existing PDF's `/Info` dictionary — and its XMP packet when present — via a non-destructive **incremental update**, so earlier revisions stay a byte-exact prefix.
+
+```jsonc
+{
+  "pdfBase64": "<base64 PDF bytes>",
+  "title": "Quarterly Report — Final",
+  "author": "Finance Team",
+  "keywords": "finance, Q1, 2026",
+  "modDate": "2026-08-25T09:00:00+02:00",
+  "outputMode": "base64"
+}
+```
+
+**Inputs:** `pdfBase64` (required), `title`, `author`, `subject`, `keywords` (≤ 1000 characters), `modDate` (ISO-8601 with offset — pinned for reproducible bytes), `outputMode` / `outputPath`.
+
+**Errors:** `ENCRYPTED_SOURCE` (use `decrypt_pdf` → `update_metadata` → `encrypt_pdf`), `METADATA_ERROR`, `PDF_PARSE_FAILED`.
+
+### `inspect_layout` _(v1.6.0)_
+
+A read-only pagination **dry run**: measures how a prospective document would paginate — without producing a PDF and without consuming output tokens on base64 bytes. The seventh read tool with `verbosity` / `fields`.
+
+```jsonc
+{
+  "title": "Q1 2026 Report",
+  "blocks": [
+    { "type": "heading", "text": "Executive Summary", "level": 1 },
+    { "type": "paragraph", "text": "Revenue grew 24 % year over year." }
+  ],
+  "verbosity": "summary"
+}
+// → { "pageWidth": 595.28, "pageHeight": 841.89, "totalPages": 1, "blockCount": 2 }
+```
+
+**Inputs:** `title` and `blocks` (required), plus every input that moves a block — `footerText`, `pdfA`, `normalize`, `embedFonts`, `pageSize`, `margins`, `headerTemplate`, `footerTemplate` — and `verbosity` / `fields`.
+
+**Outputs (full):** `pageWidth`, `pageHeight`, `margins`, `totalPages`, and `pages[].blocks[]` with each block's `type`, `page`, `x`, `top`, `width`, `height` (2-decimal points).
+
+> **Known engine gap:** a `toc` block is measured as 0 pt, so a document with a printed contents page may paginate one page later than previewed.
+
 ---
 
 ## MCP prompts
 
-Since v1.4.0 the server advertises the MCP **`prompts`** capability with two prompts, sourced from the same governance contract the tools enforce:
+Since v1.4.0 the server advertises the MCP **`prompts`** capability; v1.6.0 grows it to **six prompts** — the two governance prompts plus four recipe prompts:
 
 | Prompt | Purpose |
 |---|---|
 | `governance_contract` | The full AI-governance / Human-in-the-Loop contract. |
 | `draft_issue_workflow` | The step-by-step recipe for producing a compliant issue draft with `draft_governance_issue`. |
+| `pades_ladder` _(v1.6.0)_ | The B-B → B-T → B-LT → B-LTA recipe: `sign_pdf` → `add_ltv` → `timestamp_pdf`, verified with `verify_pdf ltv: true`. |
+| `print_ready` _(v1.6.0)_ | Producing press-ready output: bleed, printer's marks, custom OutputIntent. |
+| `reproducible_output` _(v1.6.0)_ | Byte-stable output via pinned `creationDate` / `signingTime` / `modDate`. |
+| `pdfa_valid` _(v1.6.0)_ | Producing a PDF/A file that veraPDF actually accepts (`embedFonts`, `strict`, diagnostics). |
 
 ## Error codes
 
 | `code` | Raised by | Meaning / fix |
 |---|---|---|
-| `ENCRYPTED_SOURCE` | `annotate_pdf` | The source PDF is encrypted; `annotate_pdf` has no `password` parameter (nor do `sign_pdf` and `validate_pdf`). Use `decrypt_pdf` first (note: that rebuild drops signatures/forms), or pass `password` to the tools that accept it. |
+| `ENCRYPTED_SOURCE` | `annotate_pdf`, `update_metadata`, `add_ltv`, `timestamp_pdf` | The source PDF is encrypted and the tool has no `password` parameter. Remedies are tool-specific since v1.6.0: for `annotate_pdf` / `update_metadata`, `decrypt_pdf` → edit → `encrypt_pdf`; for `add_ltv` / `timestamp_pdf`, decrypting would destroy the signatures — sign before encrypting. |
 | `PASSWORD_REQUIRED` *(v1.5.0)* | password-aware tools (`inspect_pdf`, `verify_pdf`, `extract_text`, `extract_attachments`, `read_form_fields`, `fill_form`, page-tree trio, `encrypt_pdf`, `decrypt_pdf`) | The source is encrypted and no `password` was supplied. |
 | `PASSWORD_INVALID` *(v1.5.0)* | password-aware tools | The supplied `password` does not open the document. |
 | `ENCRYPTION_UNSUPPORTED` *(v1.5.0)* | password-aware tools | The document uses an encryption scheme the reader does not support. |
@@ -3899,6 +5652,20 @@ Since v1.4.0 the server advertises the MCP **`prompts`** capability with two pro
 | `OUTPUT_TOO_LARGE` | PDF-emitting tools | An emitted PDF exceeds 50 MiB (for `split_pdf`, also the 200 MiB aggregate), or assembly exceeds `maxOutputSizeBytes` (default 256 MiB). |
 | `PDF_PARSE_FAILED` | page-tree tools | The source bytes are not a parseable PDF. |
 | `GOVERNANCE_VIOLATION` | `draft_governance_issue` | The draft breaks the AI-governance contract (proposes a runtime dependency, omits a reproduction, or `duplicateSearchPerformed: false`). Fix the draft and retry. |
+| `TSA_NOT_CONFIGURED` *(v1.6.0)* | `sign_pdf` (`timestamp: true`), `timestamp_pdf` | No `PDFNATIVE_MCP_TSA_URL` is set. Configure the TSA in the server environment. |
+| `TSA_REJECTED` *(v1.6.0)* | `sign_pdf`, `timestamp_pdf` | The timestamp authority declined the request. |
+| `REVOCATION_NOT_CONFIGURED` *(v1.6.0)* | `add_ltv` (`mode: 'online'`) | No `PDFNATIVE_MCP_REVOCATION` sources are set. Configure them, or use `mode: 'offline'` with caller-supplied material. |
+| `NETWORK_HOST_NOT_ALLOWED` *(v1.6.0)* | `add_ltv` | A certificate-supplied OCSP/CRL URL points outside `PDFNATIVE_MCP_NETWORK_ALLOWED_HOSTS`. |
+| `NETWORK_ERROR` *(v1.6.0)* | TSA/LTV tools | The TSA/OCSP/CRL request failed (timeout, refusal, size cap). |
+| `LTV_NO_SIGNATURE` / `LTV_EMPTY` / `LTV_MATERIAL_INVALID` / `LTV_ERROR` *(v1.6.0)* | `add_ltv` | No signature to validate / no material gathered / supplied DER material does not parse / embedding failed. |
+| `METADATA_ERROR` *(v1.6.0)* | `update_metadata` | The incremental `/Info` + XMP rewrite failed. |
+| `PRINT_ERROR` *(v1.6.0)* | document tools with `print` | The requested page boxes are inconsistent (e.g. do not fit `pageSize`). |
+| `CHART_ERROR` *(v1.6.0)* | `add_chart`, `chart` blocks | An engine cross-field chart rule failed (the message carries the remedy). |
+| `PLACEHOLDER_AMBIGUOUS` *(v1.6.0)* | `sign_pdf` | Several unsigned placeholders exist and no `fieldName` was given. |
+| `SIGNATURE_FIELD_NOT_FOUND` *(v1.6.0)* | `sign_pdf` | The named `fieldName` does not exist. |
+| `CMS_PARSE_FAILED` *(v1.6.0)* | `verify_pdf` | A CMS structure is shorter or more malformed than the parser expects. |
+
+> **Protocol errors** *(v1.6.0)*: calling an unknown tool or prompt name is now a JSON-RPC `-32602` error (`[UNKNOWN_TOOL]` / `[UNKNOWN_PROMPT]`), not an `isError` result. Likewise, an unknown or misspelt input key — top-level or nested — fails with `VALIDATION_ERROR` ("Unrecognized key") instead of being silently stripped.
 
 ---
 
@@ -3919,8 +5686,8 @@ When set on `add_international_text`, the `latin` font auto-registers so non-Win
 
 ## Output modes
 
-Every document-producing tool accepts an `outputMode` field. The read-only
-tools (`inspect_pdf`, `validate_pdf`, `verify_pdf`, `extract_text`,
+Every document-producing tool accepts an `outputMode` field. The seven read-only
+tools (`inspect_pdf`, `inspect_layout`, `validate_pdf`, `verify_pdf`, `extract_text`,
 `extract_attachments`, `read_form_fields`) return JSON only and have no
 `outputMode`:
 
@@ -3976,12 +5743,13 @@ This workflow uses two tools in sequence:
 
 `pdfnative-mcp` is designed to run safely inside your AI client:
 
-- **No network access** — the server does not open outbound connections.
+- **No network access by default** — the server opens no outbound connection unless the **operator** configures TSA/OCSP/CRL endpoints for the PAdES tools (see the network charter under *Environment variables*). URLs never come from tool arguments, and certificate-supplied OCSP/CRL URLs pass an SSRF guard.
 - **Sandboxed file writes** — `file` output mode is gated by `PDFNATIVE_MCP_OUTPUT_DIR`. When unset, file writes are rejected with a `SecurityError`.
 - **Path traversal protection** — absolute paths, `..` sequences, NUL bytes, and non-`.pdf` extensions are all rejected.
 - **Output size cap** — PDF output is capped at **50 MiB** per call. `split_pdf` additionally enforces **50 MiB per part** and a **200 MiB aggregate** ceiling across its parts, returning `OUTPUT_TOO_LARGE` when exceeded.
-- **HTTP transport hardening** — when bound to `PDFNATIVE_MCP_PORT`, the Streamable HTTP transport is loopback-only and rejects foreign `Host` / `Origin` headers with **403** (DNS-rebinding protection).
-- **Input validation** — every tool validates inputs against strict JSON Schemas and Zod runtime checks at the boundary.
+- **HTTP transport hardening** — when bound to `PDFNATIVE_MCP_PORT`, the HTTP transport is loopback-only and rejects foreign `Host` / `Origin` headers with **403** (DNS-rebinding protection). An opt-in bearer token (`PDFNATIVE_MCP_HTTP_TOKEN`) adds authentication _(v1.6.0)_ — without it, the loopback endpoint has none.
+- **Input validation** — every tool validates inputs against strict JSON Schemas and Zod runtime checks at the boundary. Since v1.6.0 every schema is `.strict()` at every nesting level, so an unknown or misspelt key is a `VALIDATION_ERROR` instead of being silently stripped, and PEM armour where DER base64 is expected fails with the exact `openssl … -outform DER` remedy.
+- **Decompression cap** — the engine's 100 MiB per-stream inflate cap is operator-tunable via `PDFNATIVE_MCP_MAX_INFLATE_BYTES` _(v1.6.0)_.
 
 See [SECURITY.md](https://github.com/Nizoka/pdfnative-mcp/blob/main/SECURITY.md) for responsible disclosure.
 
@@ -4008,7 +5776,7 @@ Split the content across multiple tool calls or reduce image/barcode count.
 
 ## Release history
 
-The current release is **v1.5.0** (24 tools, built on pdfnative 1.7.0 — see the header note). Per-release notes, oldest first:
+The current release is **v1.6.0** (28 tools, built on pdfnative 1.7.0 — see the header note). Per-release notes, oldest first:
 
 ### What's new in v1.0.0
 
@@ -4083,7 +5851,7 @@ v1.4.0 upgrades the engine to **pdfnative 1.5.0**, brings the pdfnative **AI-gov
 
 ### What's new in v1.5.0
 
-v1.5.0 upgrades the engine to **pdfnative 1.7.0** and takes the catalogue to **24 tools**, closing the read/modify loop on documents the assistant did not create.
+v1.5.0 upgrades the engine to **pdfnative 1.6.0** and takes the catalogue to **24 tools** at that release,<!-- verify-docs:allow stale-token (historical: v1.5.0 total) --> closing the read/modify loop on documents the assistant did not create.
 
 - **Five new tools:**
   - `add_chart` — bar, horizontal-bar, line, pie and donut charts drawn as **native PDF vector paths**. No rasterisation and no image round-trip, so the output stays sharp at any zoom and tags as `/Figure` with alt text. If you were previously asking an agent to render a chart to PNG and push it through `embed_image`, stop — this replaces that.
@@ -4097,6 +5865,34 @@ v1.5.0 upgrades the engine to **pdfnative 1.7.0** and takes the catalogue to **2
 - **Tool annotations** (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) are published in `tools/list`, letting a client reason about which calls are safe to retry.
 - The encryption tools are deliberately **excluded from the response cache**.
 
+### What's new in v1.6.0
+
+v1.6.0 aligns the server with the **MCP 2026-07-28** specification and grows the catalogue to **28 tools**, exposing the engine's full document model and completing the PAdES baseline ladder. No breaking changes: every v1.5.0 call keeps its inputs, error codes and response shape, and a superset gate against the published 1.5.0 catalogue proves it.
+
+- **Four new tools:**
+  - `add_ltv` — embed `/DSS` + `/VRI` long-term-validation material (PAdES **B-LT**), online through the operator-configured revocation provider or offline from caller-supplied material.
+  - `timestamp_pdf` — append a `/DocTimeStamp` through the operator TSA (PAdES **B-LTA**), with auto-suffixed field names for periodic re-timestamping.
+  - `update_metadata` — rewrite `/Info` (+ XMP) of an existing PDF as an incremental update.
+  - `inspect_layout` — a read-only pagination dry run: page count and block positions with no PDF produced.
+- **Full engine coverage** — `generate_basic_pdf` composes all **13 block kinds** (`table`, `image`, `link`, `toc`, `barcode`, `svg`, `formField` join the six existing ones); `pageSize`, `margins`, running `headerTemplate` / `footerTemplate`, `compress` and `debug` on the nine document tools; build-time `encrypt` that **keeps the AcroForm**; image watermarks with `position`.
+- **PAdES signing** — `sign_pdf` gains `profile: 'pades'`, `timestamp: true` (RFC 3161, B-T), RSA-SHA384/512, `certChainDerBase64`, `fieldName` / `allowMultiple`; `verify_pdf ltv: true` reports profile, timestamp, embedded revocation status and the achieved level; `prepare_signature_placeholder` gains `subFilter` / `reserveTimestamp` and freezes signer metadata into the `/Sig` dictionary (fixing a pre-1.7 engine bug where those values were silently dropped).
+- **Network charter** — still **no outbound request by default**; the single permitted egress class is the operator-configured TSA / OCSP / CRL endpoints, never a URL from a tool argument, behind an SSRF guard. Seven new environment variables configure the HTTP bearer token, the inflate cap and the network providers.
+- **Print production** — `print` page boxes, `bleed`, printer's `marks`, `/UserUnit`, `metadata` with `/Trapped`, custom `outputIntent`; boxes survive the page-tree tools and are reported by `inspect_pdf`.
+- **Charts v2** — `stackedBar` / `stackedBarH` / `area` / `scatter`, per-series `xValues` with linear or time axes, secondary `axis2`, `axis.scale: 'log'`, `dataLabels`, `labelStride` / `labelRotation`.
+- **Honest PDF/A** — `embedFonts: true` (embed Noto Sans Latin for a claim veraPDF accepts), `strict: true` (fail instead of emitting a non-conformant file), `includeDiagnostics: true`; two new diagnostics; an advisory veraPDF corpus runs locally and in CI.
+- **MCP 2026-07-28 transport** — SDK v2 (`@modelcontextprotocol/server`), `server/discover`, `resultType`, cache hints, per-result `serverInfo`, deterministic `tools/list`; 2025-era clients keep working via the automatic legacy fallback.
+- **Four new recipe prompts** — `pades_ladder`, `print_ready`, `reproducible_output`, `pdfa_valid` — taking the prompt catalogue to six.
+- **Reproducible output** — `creationDate` on all nine document tools, `signingTime` on the placeholder, `modDate` on `update_metadata`.
+
+**Migrating from v1.5.0** — six behaviour changes, all on error paths or on inputs the published schema already declared invalid:
+
+1. **Stray keys fail.** An unknown or misspelt key, top-level or nested, is now `VALIDATION_ERROR` ("Unrecognized key") instead of being silently stripped — the schemas always declared `additionalProperties: false`.
+2. **Page-index mistakes are `VALIDATION_ERROR`.** Out-of-range pages / ranges on `merge_pdfs` / `split_pdf` / `extract_pages` were `PDF_PARSE_FAILED`; the message now carries a 0-based hint.
+3. **`validate_pdf` on unparsable bytes is an error, not a verdict.** v1.5.0 returned `{ valid: false }`; v1.6.0 returns `isError: true` `[PDF_PARSE_FAILED]` — a parse failure is not a PDF/UA verdict.
+4. **Unknown tool or prompt names are protocol errors** — JSON-RPC `-32602` (`[UNKNOWN_TOOL]` / `[UNKNOWN_PROMPT]`), no `isError` result.
+5. **`inspect_pdf.checks` holds only the keys you asked for** — read `checksPassed` or the requested key, never an absent one.
+6. **`add_form` text areas change bytes.** `fieldType: 'textarea'` now produces a real multi-line field (`/Ff 4096`).
+
 ---
 
 ## Further reading
@@ -4209,7 +6005,7 @@ Then prompt your assistant:
 
 > *Create a PDF/A-2b invoice for ACME Inc, add a multilingual paragraph in Arabic, and sign it with my key.*
 
-The assistant calls `generate_basic_pdf` (with `pdfA: "pdfa2b"`), then `add_international_text` (with `lang: ["ar", "emoji"]`), `add_table`, `sign_pdf`, and finally `inspect_pdf` — confirming the result. v1.4.0 ships **24 tools**, including the page-tree trio `merge_pdfs`, `split_pdf`, `extract_pages`, markup `annotate_pdf`, the network-free `draft_governance_issue`, plus `validate_pdf`, `verify_pdf`, `add_attachment`, `extract_attachments`, and `extract_text`.
+The assistant calls `generate_basic_pdf` (with `pdfA: "pdfa2b"`), then `add_international_text` (with `lang: ["ar", "emoji"]`), `add_table`, `sign_pdf`, and finally `inspect_pdf` — confirming the result. v1.6.0 ships **28 tools**, including the complete PAdES ladder (`sign_pdf` with RFC 3161 timestamps, `add_ltv`, `timestamp_pdf`), the page-tree trio `merge_pdfs`, `split_pdf`, `extract_pages`, markup `annotate_pdf`, `update_metadata`, the read-only `inspect_layout` pagination preview, the network-free `draft_governance_issue`, plus `validate_pdf`, `verify_pdf`, `add_attachment`, `extract_attachments`, and `extract_text`.
 
 Next: [MCP guide →](mcp.html) · [MCP playground →](../playgrounds/mcp.html)
 
@@ -4684,6 +6480,11 @@ claim are preserved, so Info↔XMP parity holds for PDF/A documents.
   to it.)
 - **Full rebuild, not in-place surgery.** The clean-graph approach trades a
   little speed for correctness and is safe to run on third-party PDFs.
+- **Page boxes survive** _(v1.7.0)_. Declared `/TrimBox`, `/BleedBox`,
+  `/ArtBox`, `/CropBox` and `/UserUnit` entries are preserved through
+  `mergePdfs` / `splitPdf` / `extractPages` (they were dropped by the rebuild
+  before 1.7.0) — so print-ready sources keep their geometry. See the
+  [print production guide](print.html).
 
 ## How it works
 
@@ -4706,6 +6507,8 @@ intact.
 <!-- source: docs/guides/pdfa.md -->
 # PDF/A conformance in pdfnative
 
+> **PDF/A-1b, 2b, 2u and 3b via `layout: { tagged: … }`, validated against the veraPDF reference validator in CI.** Since v1.7.0, a configuration that would break the declared level surfaces a diagnostic — `console.warn` by default, a custom `onDiagnostic` sink, or a thrown error under `strict: true`.
+
 PDF/A is the ISO archival profile for PDF (ISO 19005). pdfnative supports
 PDF/A-1b, 2b, 2u, and 3b via the `tagged` build option. This guide
 explains what works today, what's still in flight, and how to validate
@@ -4807,6 +6610,17 @@ Each `PdfDiagnostic` carries a machine-readable `code`, a `severity`
 The code list is a stable, additions-only union (`PdfDiagnosticCode`), so a
 sink written today keeps compiling as future codes are added.
 
+> **On the MCP surface** _(pdfnative-mcp 1.6.0)_, the same honesty is exposed
+> as three opt-in inputs on every document tool: `embedFonts: true` embeds
+> Noto Sans Latin so a PDF/A claim on base-14 text is actually accepted by
+> veraPDF, `strict: true` fails instead of producing a non-conformant file,
+> and `includeDiagnostics: true` echoes the engine's diagnostics
+> (`PDFA_NO_FONT_ENTRIES`, `PDFA_UNEMBEDDED_FORM_FONT`,
+> `PDFA_DEVICE_CMYK_IMAGE`) in the tool result. Known engine limitation:
+> `add_form` (or a `formField` block) under a PDF/A claim still fails
+> veraPDF even with `embedFonts` — the AcroForm `/DR /Helv` font is an
+> unembedded Type1 (ISO 19005-2 §6.2.11.4.1).
+
 ## v1.1.0 status — fully validated
 
 v1.1.0 ships full PDF/A-1b / 2b / 2u / 3b conformance against the
@@ -5172,6 +6986,8 @@ See the [print samples](https://github.com/Nizoka/pdfnative/blob/main/scripts/ge
 <!-- source: docs/guides/quickstart.md -->
 # Quick Start
 
+> **One install, one function.** `npm install pdfnative`, then `buildDocumentPDFBytes({ title, blocks })` returns a `Uint8Array` — synchronously, in Node, browsers, Deno and Bun. No config, no build step, no service.
+
 Generate your first PDF in under a minute.
 
 ## Install
@@ -5399,7 +7215,7 @@ See the dedicated [CLI guide](cli.html) for the full command reference, security
 <!-- source: docs/guides/react.md -->
 # pdfnative-react — Declarative JSX Renderer Guide
 
-> **Tracks the latest published `pdfnative-react`** (v1.1.0, built on pdfnative 1.7.0), with **React 19** and `pdfnative` ^1.6.0 as peer dependencies. Live package versions — and the `pdfnative` version each one is built on — are shown at the top of the [documentation home](../index.html). Full history: [pdfnative-react releases](https://github.com/Nizoka/pdfnative-react/releases).
+> **Tracks the latest published `pdfnative-react`** (v1.1.0, built on the pdfnative 1.6 engine), with **React 19** and `pdfnative` ^1.6.0 as peer dependencies (semver-accepts 1.7.0). Live package versions — and the `pdfnative` version each one is built on — are shown at the top of the [documentation home](../index.html). Full history: [pdfnative-react releases](https://github.com/Nizoka/pdfnative-react/releases).
 
 [`pdfnative-react`](https://github.com/Nizoka/pdfnative-react) turns declarative **JSX** into real, on-device PDFs powered by the zero-dependency [`pdfnative`](https://github.com/Nizoka/pdfnative) engine — no DOM, no headless browser, no SaaS round-trips. Your documents never leave the process.
 
@@ -5708,7 +7524,7 @@ const bytes = renderToBytes(
 | `<View>` + flexbox styles | *(none — declarative block flow; use blocks + `<Spacer>`)* |
 | `StyleSheet` | per-component props (`align`, `color`, `fontSize`, …) |
 | `<PDFViewer>` / `<PDFDownloadLink>` / `<BlobProvider>` | same names, same shape |
-| `usePDF()` | `usePdf()` |
+| <!-- verify-docs:allow api-exists (left column names the @react-pdf/renderer API being migrated from) --> `usePDF()` | `usePdf()` |
 
 The biggest mental shift: there is **no flexbox layout engine**. Documents are a top-to-bottom block flow. Use `<Spacer>`, `<PageBreak>`, tables, and per-component alignment props instead of `<View>` containers.
 
@@ -5742,13 +7558,315 @@ try {
 - 🤖 **AI integration:** [pdfnative-mcp guide](mcp.html) · 💻 **Terminal:** [pdfnative-cli guide](cli.html)
 - 🐛 **Report a bug:** [Nizoka/pdfnative-react/issues](https://github.com/Nizoka/pdfnative-react/issues)
 
+---
+<!-- source: docs/guides/self-verify.md -->
+# Self-verifying generation
+
+> **pdfnative can read what it writes, so a generated PDF never has to ship
+> unchecked.** Plan pagination with `inspectDocumentLayout()` *before* building,
+> then run `extractText()`, `validatePdfUA()` and `listSignatures()` /
+> `openPdf()` against the emitted bytes, assert what matters, and correct the
+> input until every assertion holds. The same generate → inspect → assert →
+> correct loop runs on all four surfaces: in the library, on the CLI
+> (`inspect --check`, stable exit codes and `E_*` error classes), and on MCP
+> (`inspect_pdf` check assertions) — so a test suite, a CI job or an AI agent
+> can close the loop without a human ever opening a viewer.
+
+## Why a PDF is normally a blind artefact
+
+Most PDF generators are write-only: the library that produced the file cannot
+parse it back. The only verification available is a human opening the result in
+a viewer — which no pipeline, test suite or autonomous agent can do. So defects
+ship silently: a table that slipped onto a second page, a template placeholder
+that was never substituted, a PDF/A claim the file cannot honour, a signature
+placeholder that was never actually signed.
+
+pdfnative bundles a parser next to the writer, in the same zero-dependency
+package. The read side (`openPdf()`, `extractText()`, `validatePdfUA()`,
+`listSignatures()`) consumes exactly what the write side emits — and any other
+PDF — which turns generation into a closed loop:
+
+1. **Plan** — measure pagination with `inspectDocumentLayout()` before a single
+   byte is produced.
+2. **Generate** — build the document.
+3. **Inspect** — read the emitted bytes back with the parser.
+4. **Assert & correct** — check the facts you care about; on failure, fix the
+   *input* and regenerate. Never patch the output bytes.
+
+The rest of this guide walks the four verifiers with realistic
+failure → fix examples, then shows the identical loop on the CLI and on MCP.
+
+## Verifier 1 — `inspectDocumentLayout()`: geometry, before generating
+
+_(v1.5.0)_ A pagination dry run: the same planning logic as the builder, but it
+returns data instead of PDF bytes — no rendering, no font embedding.
+
+```ts
+import { buildDocumentPDFBytes, inspectDocumentLayout } from 'pdfnative';
+
+const params = {
+  title: 'Invoice #2026-041',
+  blocks: [
+    { type: 'heading', level: 1, text: 'Invoice #2026-041' },
+    { type: 'paragraph', text: intro },
+    { type: 'table', headers: ['Item', 'Qty', 'Total'], rows },
+  ],
+};
+
+// Plan — no PDF is produced.
+const layout = inspectDocumentLayout(params);
+
+// Assert: a one-page invoice.
+if (layout.totalPages !== 1) {
+  throw new Error(`expected 1 page, planned ${layout.totalPages}`);
+}
+
+// Assert: the table starts on page 1, not after a stray break.
+const table = layout.pages[0].blocks.find((b) => b.type === 'table');
+if (!table) throw new Error('table was pushed off page 1');
+
+// Only now generate.
+const bytes = buildDocumentPDFBytes(params);
+```
+
+**Failure → fix.** `totalPages` comes back as `2` because this month's `rows`
+grew by three entries. Fixes live in the input: shorten `intro`, reduce the
+margins in the layout options, or accept the second page and change the
+assertion — the table planner repeats headers on continuation pages by default,
+so a deliberate two-pager stays readable. Re-run the inspection until the
+assertion holds, then build.
+
+> **Honest caveat.** `inspectDocumentLayout()` shares the builder's measurement
+> code (`estimateBlockHeight` / `planTable` and its constants) — that is
+> precisely why its geometry matches where the renderer places each block,
+> including table slicing across page breaks. But it is a *prediction from the
+> shared engine*, not an independent re-parse of the emitted bytes. For
+> verification of the actual output, pair it with `extractText()` below. See
+> [Layout debugging & inspection](debugging.html) for the full data shape and
+> the visual overlay variant.
+
+## Verifier 2 — `extractText()`: is the content actually in the file?
+
+_(v1.6.0)_ Reading-order Unicode text per page, decoded from the content
+streams of the emitted bytes — pdfnative-generated documents round-trip
+losslessly, including CJK, Arabic and emoji.
+
+```ts
+import { buildDocumentPDFBytes, extractText } from 'pdfnative';
+
+const bytes = buildDocumentPDFBytes(params);
+
+const pages = extractText(bytes);               // ExtractedPageText[]
+// Each entry: { pageIndex: number, text: string, runs?: ExtractedTextRun[] }
+const flat = pages.map((p) => p.text).join('\n');
+
+for (const required of ['Invoice #2026-041', 'Total', '1 240,00 €']) {
+  if (!flat.includes(required)) {
+    throw new Error(`missing from the emitted PDF: "${required}"`);
+  }
+}
+if (flat.includes('{{')) {
+  throw new Error('an unresolved template placeholder reached the PDF');
+}
+```
+
+**Failure → fix.** The total is missing: the value never entered `blocks` —
+typically a renamed data field, or a templating step that ran after the build
+instead of before it. The `{{` guard catches the classic half-rendered
+template. Fix the data flow and regenerate. Positioned runs
+(`{ includeRuns: true }`) additionally give each string's `x` / `y` /
+`fontSize` when you need to assert *where* something landed, not just that it
+exists.
+
+Extraction has documented limits (no OCR on image content, lossy conjuncts in
+shaped Indic scripts) — see [Text extraction](text-extraction.html) before
+asserting on those cases.
+
+## Verifier 3 — `validatePdfUA()`: structural PDF/UA
+
+Read-only ISO 14289-1 structural checks over the emitted bytes: `/MarkInfo`,
+the structure tree, the parent tree, a document `/Lang`, per-page MCID
+uniqueness.
+
+```ts
+import { buildDocumentPDFBytes, validatePdfUA } from 'pdfnative';
+
+const bytes = buildDocumentPDFBytes(params, { tagged: true });
+
+const report = validatePdfUA(bytes);   // { valid, errors, warnings }
+if (!report.valid) {
+  throw new Error(`PDF/UA structure: ${report.errors.join('; ')}`);
+}
+```
+
+**Failure → fix.** The most common failure is building without `tagged` — the
+document then has no structure tree at all, and every structural check fires.
+Set `layout: { tagged: true }` (or a `'pdfa*'` level) and regenerate. Warnings
+are non-blocking best-practice notes; decide explicitly whether your pipeline
+tolerates them.
+
+> **Honest caveat.** This is a *structural* validation, not an accessibility
+> audit. A passing report means the machine-checkable structure is present and
+> consistent — it cannot judge whether the reading order makes sense to a
+> human, whether alt text is meaningful, or whether colour contrast is
+> adequate. And it is not a PDF/A validator: for archival conformance, run
+> veraPDF as described in [PDF/A conformance](pdfa.html).
+
+## Verifier 4 — `listSignatures()` + `openPdf()`: signatures, encryption, metadata
+
+`listSignatures()` _(v1.7.0)_ inventories every signature field in the
+document; `openPdf()` (available since v1.0.0) exposes page count, encryption
+state and the `/Info` dictionary.
+
+```ts
+import { openPdf, listSignatures } from 'pdfnative';
+
+const sigs = listSignatures(signedBytes);
+if (sigs.length === 0) throw new Error('no signature field found');
+if (sigs.some((s) => s.isPlaceholder)) {
+  throw new Error('a /Sig field is still an unsigned placeholder');
+}
+// Per entry: fieldName?, subFilter, byteRange, isDocTimestamp, isPlaceholder.
+const pades = sigs.filter((s) => s.subFilter === 'ETSI.CAdES.detached');
+
+const reader = openPdf(signedBytes);
+if (reader.encryption !== null) throw new Error('expected an unencrypted document');
+if (reader.pageCount < 2) throw new Error('terms page missing');
+const info = reader.getInfo();
+```
+
+**Failure → fix.** `isPlaceholder: true` means `addSignaturePlaceholder()` ran
+but `signPdfBytes()` never filled that field — usually a skipped signing step,
+or a `fieldName` selector that targeted a different placeholder. Sign the
+document (or the right field) and re-check. `isDocTimestamp` distinguishes
+`/DocTimeStamp` entries when you assert on the PAdES ladder.
+
+> **Honest caveat.** `listSignatures()` is an inventory, not a cryptographic
+> verdict — the pdfnative engine deliberately ships no signature verifier.
+> Full verification (byte-range digest, CMS signature value, certificate
+> chain, trust, timestamps, revocation) lives in `pdfnative-cli verify` and in
+> the MCP `verify_pdf` tool, below. See
+> [Long-term validation (LTV)](ltv.html).
+
+## The same loop on the CLI
+
+`pdfnative-cli` turns the assertions into exit codes, which is what a shell or
+CI step branches on:
+
+```bash
+# Plan (pre-flight): pagination report instead of a PDF   (v1.2.0)
+pdfnative render --input invoice.json --inspect-layout > layout.json
+
+# Generate, then assert — exit 0 when every --check holds, 1 otherwise
+pdfnative render  --input invoice.json --output invoice.pdf --tagged pdfa2b
+pdfnative inspect --input invoice.pdf --check pdfa --check pdfua --json --summary
+echo $?   # 0 = all assertions hold, 1 = at least one failed
+
+# Content presence, pipeline-style
+pdfnative extract-text --input invoice.pdf --format text | grep -q 'Invoice #2026-041'
+```
+
+- `inspect --check` takes repeatable, ANDed assertions — `pdfa`, `signed`,
+  `encrypted`, `pdfua` _(v1.1.0)_ — and sets the exit code accordingly; under
+  `--json`, a failed assertion also emits the stable error class
+  `E_CHECK_FAILED` in the machine-readable envelope on stderr
+  (`{ ok: false, command, error: { code, message } }`).
+- `--summary` _(v1.1.0)_ shrinks the stdout verdict to
+  `{ pages, encrypted, signatures, pdfa }`; `--fields a,b.c` projects arbitrary
+  dot-paths — both exist so agents branch on facts without paying for the full
+  report.
+- `pdfnative verify --strict` performs the cryptographic half: byte-range
+  digest, CMS signature value (RSA and ECDSA), certificate chain and trust
+  against `--trust` roots, RFC 3161 timestamps, OCSP/CRL revocation — exit 1
+  and `E_VERIFY_FAILED` on any failure *or on zero signatures*.
+
+The full command reference, including every `--check` flag and the `E_*`
+catalogue, is in the [CLI guide](cli.html).
+
+## The same loop on MCP
+
+`pdfnative-mcp` gives a conversational agent the identical verifiers as
+read-only tools — the natural final step after any document tool call:
+
+| Tool | Verifies |
+|---|---|
+| `inspect_pdf` | Version, page count, encryption, PDF/A claim, signatures, attachments, `/Info` — plus `check` assertions with a boolean verdict. |
+| `inspect_layout` _(v1.6.0)_ | Pagination dry run for a prospective document — page count and block geometry, no PDF produced, no base64 output tokens spent. |
+| `validate_pdf` | Structural PDF/UA — `{ valid, errors, warnings }`. |
+| `verify_pdf` | Cryptographic signature verification; `ltv: true` _(v1.6.0)_ reports the achieved PAdES level (B-B → B-LTA). |
+
+```jsonc
+{ "tool": "inspect_pdf",
+  "input": { "pdfBase64": "<...>", "check": ["pdfa", "signed"] } }
+// → { ..., "checks": { "pdfa": true, "signed": true }, "checksPassed": true }
+```
+
+- `check` accepts `pdfa`, `signed`, `encrypted`, `placeholder`, `attachments`,
+  and — _(v1.6.0)_ — `dss`, `docTimestamp`, `trapped`, `annotations`.
+  `checksPassed` is the AND of all requested assertions; since v1.6.0 `checks`
+  contains **only** the requested keys, so branch on `checksPassed` or on a key
+  you asked for, never on an absent one.
+- `inspect_layout` accepts the same `title` / `blocks` (plus every input that
+  moves a block) as `generate_basic_pdf`, so an agent can iterate on pagination
+  before spending output tokens on real bytes. Known engine gap: a `toc` block
+  is measured as 0 pt, so a document with a printed contents page may paginate
+  one page later than previewed.
+- `validate_pdf` on unparsable bytes is an error (`PDF_PARSE_FAILED`), not a
+  `{ valid: false }` verdict, since v1.6.0 — a parse failure is not a PDF/UA
+  result.
+
+Tool-by-tool inputs and error codes are in the [MCP guide](mcp.html).
+
+## Wire it into CI and agent loops
+
+**CI.** Chain the loop with `set -e` so any failed assertion fails the job —
+no PDF-viewing human in the path:
+
+```bash
+set -e
+pdfnative render  --input report.json --output report.pdf --tagged pdfa2b
+pdfnative sign    --input report.pdf  --output signed.pdf --key k.pem --cert c.pem
+pdfnative inspect --input signed.pdf  --check pdfa --check signed --json --summary
+pdfnative verify  --input signed.pdf  --strict --trust ca-root.pem
+```
+
+`--dry-run` on the write commands validates inputs without producing output,
+which makes a cheap first CI stage; `--summary` / `--fields` keep logs and
+agent context small.
+
+**Agent loops.** Treat every generation as unfinished until a read tool
+confirms it: after `generate_basic_pdf` (or any document tool), call
+`inspect_pdf` with the `check` list that encodes the user's requirements and
+branch on `checksPassed`; on failure, correct the tool input and regenerate
+rather than apologising with an unverified file. Use `inspect_layout` before
+generating and `verbosity: "summary"` on the read tools to keep token spend
+proportional. The [agent brief](../agent-brief.md) condenses this contract
+into a paste-into-context form.
+
+## Further reading
+
+- [Agent brief](../agent-brief.md) — the compact form of this loop for AI
+  agents, verified by the documentation CI.
+- [Layout debugging & inspection](debugging.html) — the visual overlay and the
+  full `LayoutInspection` data shape.
+- [Text extraction](text-extraction.html) — decoding rules, positioned runs,
+  documented limits.
+- [PDF/A conformance](pdfa.html) — validating archival claims with veraPDF,
+  and the build-time `PDFA_*` diagnostics.
+- [Long-term validation (LTV)](ltv.html) — the PAdES ladder the signature
+  assertions climb.
+- [CLI guide](cli.html) · [MCP guide](mcp.html) — the complete surface
+  references.
+
 ---
 <!-- source: docs/guides/signatures.md -->
 # Digital signatures in pdfnative
 
+> **CMS/PKCS#7 detached signatures in pure TypeScript** — RSA PKCS#1 v1.5 (SHA-256/384/512) and ECDSA P-256, the PAdES baseline profile and multiple signatures since v1.7.0, with a one-call `addSignaturePlaceholder()` workflow. For timestamps and B-T → B-LTA, see the [LTV guide](ltv.html).
+
 pdfnative ships a zero-dependency CMS/PKCS#7 detached signature
 implementation (ISO 32000-1 §12.8) with full crypto in pure TypeScript —
-RSA PKCS#1 v1.5 and ECDSA P-256, both with SHA-256, X.509 DER parsing,
+RSA PKCS#1 v1.5 (SHA-256, plus SHA-384/512 since v1.7.0) and ECDSA P-256 (SHA-256), X.509 DER parsing,
 and ASN.1 DER encoding. No OpenSSL, no node-forge, no external crypto.
 
 ## TL;DR — sign any PDF in 3 lines
@@ -5854,7 +7972,9 @@ verify a signed PDF end to end (byte-range digest, CMS signature value,
 chain, trust, timestamps, revocation), use
 [`pdfnative-cli verify`](cli.html#pdfnative-verify) or the
 [`verify_pdf` MCP tool](mcp.html) — the CMS verification logic lives
-there.
+there. Since pdfnative-mcp 1.6.0, `verify_pdf` also validates
+`/DocTimeStamp` fields as RFC 3161 tokens and reports the achieved
+PAdES level (B-B → B-LTA) with `ltv: true`.
 
 ## Why a separate placeholder step?
 
@@ -6104,7 +8224,7 @@ for the idempotency proof.
 - [PDF/A conformance →](pdfa.html) — how signatures interact with PDF/A-2b/3b.
 - [Architecture →](architecture.html) — where the crypto module sits in the dependency graph.
 - [CLI →](cli.html) — `pdfnative-cli sign` wraps this exact pipeline.
-- [MCP integration →](mcp.html) — `pdfnative-mcp` exposes signing as an AI tool.
+- [MCP integration →](mcp.html) — `pdfnative-mcp` exposes signing as an AI tool, and since v1.6.0 the complete PAdES ladder: `sign_pdf` (`profile: 'pades'`, RFC 3161 `timestamp`) → `add_ltv` (`/DSS` + `/VRI`, B-LT) → `timestamp_pdf` (`/DocTimeStamp`, B-LTA), verified with `verify_pdf ltv: true`.
 
 ---
 <!-- source: docs/guides/streaming.md -->
@@ -6406,7 +8526,7 @@ Borders are pure vector strokes (`m … l S`), so output stays PDF/A-safe.
 
 ### `cellVAlign` (v1.4.0)
 
-Vertically align cell text within the row band. Useful when rows have a tall `minRowHeight` or wrapped cells of differing height. A per-column [`ColumnDef.vAlign`](#columndef-fields) overrides the table default.
+Vertically align cell text within the row band. Useful when rows have a tall `minRowHeight` or wrapped cells of differing height. A per-column [`ColumnDef.vAlign`](#tableblock-fields-all-optional) overrides the table default.
 
 ```ts
 { type: 'table', headers: [/* … */], rows: [/* … */], minRowHeight: 30, cellVAlign: 'middle' }
@@ -6616,6 +8736,11 @@ mapped through their `/ToUnicode` CMap — which pdfnative's own CIDFont
 output always embeds, so **pdfnative-generated documents round-trip
 losslessly**, including CJK, Arabic, and emoji.
 
+Since pdfnative **1.7.0** the `/ToUnicode` coverage is complete across both
+builders: base-14 font dictionaries are reached under tagged mode and the
+AcroForm `/Helv` dictionary carries a CMap in every mode — so base-14 text in
+tagged documents and **text typed into form fields** now extract cleanly too.
+
 ## Reading order and runs
 
 `page.text` is assembled geometrically: runs are grouped into lines by
@@ -6689,6 +8814,8 @@ Generated by `npm run test:generate`:
 <!-- source: docs/guides/troubleshooting.md -->
 # Troubleshooting
 
+> **Symptom-first fixes for the classic failures** — tofu boxes (a font registered but never loaded), RTL text appearing backwards, oversized files, PDF/A validation errors, parser rejections — each with the check that identifies it and the change that fixes it.
+
 ## Font Not Rendering (Boxes or Blank)
 
 **Symptom:** Non-Latin text shows as empty rectangles or missing glyphs.
diff --git a/docs/llms-index.json b/docs/llms-index.json
new file mode 100644
index 0000000..e2c9f27
--- /dev/null
+++ b/docs/llms-index.json
@@ -0,0 +1,585 @@
+{
+  "$comment": "Machine index of the pdfnative documentation. Generated by scripts/build-llms-full.ts; verified by the llms-index-sync rule of scripts/verify-docs.ts. Token counts are approximate (bytes / 4).",
+  "site": "https://pdfnative.dev",
+  "artefacts": [
+    {
+      "url": "https://pdfnative.dev/llms.txt",
+      "description": "Documentation index (llmstxt.org convention).",
+      "bytes": 15130,
+      "approxTokens": 3783
+    },
+    {
+      "url": "https://pdfnative.dev/agent-brief.md",
+      "description": "Compact paste-into-context briefing for coding agents: core API, verified pitfalls, surface decision tree, self-verification loop.",
+      "bytes": 7114,
+      "approxTokens": 1779
+    },
+    {
+      "url": "https://pdfnative.dev/llms-full.txt",
+      "description": "Full corpus: index + README + every guide, one request.",
+      "bytes": 486009,
+      "approxTokens": 121502
+    },
+    {
+      "url": "https://pdfnative.dev/llms-recipes.txt",
+      "description": "Executable recipes: CI-verified, copy-ready code for the most common tasks.",
+      "bytes": 24611,
+      "approxTokens": 6153
+    },
+    {
+      "url": "https://github.com/Nizoka/pdfnative/blob/main/README.md",
+      "description": "Complete feature and API reference (also embedded in llms-full.txt).",
+      "bytes": 97646,
+      "approxTokens": 24412
+    }
+  ],
+  "guides": [
+    {
+      "title": "Accessibility",
+      "summary": "Tagged PDF, PDF/UA and screen-reader-friendly output. Pass `layout: { tagged: true }` (or a PDF/A level) and pdfnative emits the structure tree, `/ActualText` and metadata that assistive technology needs — then check the result with the read-only `validatePdfUA()`.",
+      "html": "https://pdfnative.dev/guides/accessibility.html",
+      "markdown": "https://pdfnative.dev/guides/accessibility.md",
+      "anchors": [
+        "why-tagged-pdf-matters",
+        "enabling-tagged-mode",
+        "what-pdfnative-emits",
+        "block-level-accessibility-hints",
+        "verifying-conformance",
+        "limitations-and-known-caveats",
+        "testing-your-pdfs-are-accessible",
+        "further-reading"
+      ],
+      "bytes": 7410,
+      "approxTokens": 1853
+    },
+    {
+      "title": "Agentic workflows",
+      "summary": "How AI agents compose with pdfnative. pdfnative is designed so an autonomous",
+      "html": "https://pdfnative.dev/guides/agentic-workflows.html",
+      "markdown": "https://pdfnative.dev/guides/agentic-workflows.md",
+      "anchors": [
+        "pattern-1--extend-the-engine-at-runtime-without-a-release",
+        "pattern-2--agent-generated-images-in-the-pdf",
+        "how-the-two-patterns-fit-together",
+        "see-also"
+      ],
+      "bytes": 8416,
+      "approxTokens": 2104
+    },
+    {
+      "title": "AI governance & human-in-the-loop",
+      "summary": "Shipped in v1.5.0. pdfnative is developed with the help of AI coding",
+      "html": "https://pdfnative.dev/guides/ai-governance.html",
+      "markdown": "https://pdfnative.dev/guides/ai-governance.md",
+      "anchors": [
+        "why-this-exists",
+        "the-six-mandatory-rules",
+        "the-human-in-the-loop-workflow",
+        "the-compliance-report",
+        "validate-a-draft-before-presenting-it",
+        "the-machine-readable-contract",
+        "what-agents-must-never-do",
+        "in-short"
+      ],
+      "bytes": 7268,
+      "approxTokens": 1817
+    },
+    {
+      "title": "Annotations (read & write)",
+      "summary": "New in v1.5.0. pdfnative now has a typed markup-annotation model plus",
+      "html": "https://pdfnative.dev/guides/annotations.html",
+      "markdown": "https://pdfnative.dev/guides/annotations.md",
+      "anchors": [
+        "supported-annotation-types",
+        "building-annotations",
+        "reading-annotations-from-an-existing-pdf",
+        "writing-annotations-into-an-existing-pdf",
+        "sample"
+      ],
+      "bytes": 3981,
+      "approxTokens": 995
+    },
+    {
+      "title": "Architecture Guide",
+      "summary": "Two builders, one strict dependency flow. `buildPDFBytes` is the table-centric builder, `buildDocumentPDFBytes` the free-form document builder; beneath them the modules flow types → core ← fonts ← shaping ← worker, with standalone crypto and parser modules — no circular imports anywhere.",
+      "html": "https://pdfnative.dev/guides/architecture.html",
+      "markdown": "https://pdfnative.dev/guides/architecture.md",
+      "anchors": [
+        "two-builders",
+        "generation-pipeline",
+        "module-dependency-flow",
+        "key-design-decisions",
+        "ecosystem"
+      ],
+      "bytes": 11392,
+      "approxTokens": 2848
+    },
+    {
+      "title": "Charts (native vector)",
+      "summary": "New in v1.6.0, extended in v1.7.0. Render bar, horizontal-bar, stacked-bar,",
+      "html": "https://pdfnative.dev/guides/charts.html",
+      "markdown": "https://pdfnative.dev/guides/charts.md",
+      "anchors": [
+        "tldr",
+        "chart-types",
+        "the-chartblock",
+        "examples",
+        "accessibility-tagged-pdf",
+        "internationalised-labels",
+        "limits--scope-v170",
+        "see-also"
+      ],
+      "bytes": 9748,
+      "approxTokens": 2437
+    },
+    {
+      "title": "Choosing your surface",
+      "summary": "Write application code → the library. Drive a shell, Makefile or CI job →",
+      "html": "https://pdfnative.dev/guides/choose.html",
+      "markdown": "https://pdfnative.dev/guides/choose.md",
+      "anchors": [
+        "the-decision-in-prose",
+        "capability--surface",
+        "honest-notes",
+        "you-can-switch-later",
+        "further-reading"
+      ],
+      "bytes": 7210,
+      "approxTokens": 1803
+    },
+    {
+      "title": "pdfnative-cli — Command-Line Interface Guide",
+      "summary": "Tracks the latest published `pdfnative-cli` (v1.3.0, built on the pdfnative 1.6 engine — pins `^1.6.0`, which semver-accepts 1.7.0). The CLI versions independently from the library. Live package versions — and the `pdfnative` version each one is built on — are shown at the top of the documentation h",
+      "html": "https://pdfnative.dev/guides/cli.html",
+      "markdown": "https://pdfnative.dev/guides/cli.md",
+      "anchors": [
+        "installation",
+        "when-to-use-the-cli-vs-the-library",
+        "quick-start",
+        "hybrid-layout-model",
+        "command-reference",
+        "agent-native-automation-contract",
+        "recipes",
+        "security-model",
+        "comparison-with-the-library-api",
+        "examples--ready-to-run",
+        "release-history",
+        "migration-v030--v110",
+        "migration-v020--v030",
+        "migration-v010--v020",
+        "troubleshooting",
+        "resources",
+        "citation"
+      ],
+      "bytes": 60044,
+      "approxTokens": 15011
+    },
+    {
+      "title": "Colour-emoji font CLI (pdfnative-build-emoji-font)",
+      "summary": "New in v1.4.0, expanded in v1.6.0 and v1.7.0. pdfnative ships a curated",
+      "html": "https://pdfnative.dev/guides/colour-emoji-cli.html",
+      "markdown": "https://pdfnative.dev/guides/colour-emoji-cli.md",
+      "anchors": [
+        "why-a-cli-instead-of-bundling-everything",
+        "tldr",
+        "getting-the-source-font",
+        "selecting-glyphs",
+        "selecting-sequences-v170",
+        "output-options",
+        "verifying-the-result",
+        "full-option-reference",
+        "licensing",
+        "see-also"
+      ],
+      "bytes": 7619,
+      "approxTokens": 1905
+    },
+    {
+      "title": "Colour emoji (COLRv1)",
+      "summary": "New in v1.3.0. pdfnative renders colour emoji natively — no rasterisation, no external dependency. Glyph colour layers become PDF Form XObjects with solid fills and axial/radial gradients. The monochrome emoji font is unchanged and remains the default.",
+      "html": "https://pdfnative.dev/guides/colour-emoji.html",
+      "markdown": "https://pdfnative.dev/guides/colour-emoji.md",
+      "anchors": [
+        "tldr",
+        "how-it-works",
+        "opt-in-not-default",
+        "coverage--limits",
+        "flag--zwj-sequences-v170",
+        "advanced-compositing-v140",
+        "limitations",
+        "variation-selectors--skin-tone-modifiers-v130",
+        "see-also"
+      ],
+      "bytes": 11715,
+      "approxTokens": 2929
+    },
+    {
+      "title": "Layout debugging & inspection",
+      "summary": "New in v1.5.0. Two complementary tools help you understand *where*",
+      "html": "https://pdfnative.dev/guides/debugging.html",
+      "markdown": "https://pdfnative.dev/guides/debugging.md",
+      "anchors": [
+        "tldr",
+        "visual-overlay",
+        "programmatic-inspection",
+        "when-to-use-which",
+        "sample"
+      ],
+      "bytes": 3746,
+      "approxTokens": 937
+    },
+    {
+      "title": "FAQ",
+      "summary": "const pdf = buildDocumentPDFBytes({ title: 'Hello', blocks: [ { type: 'heading', text: 'Hello world', level: 1 }, { type: 'paragraph', text: 'My first PDF.' }, ], });",
+      "html": "https://pdfnative.dev/guides/faq.html",
+      "markdown": "https://pdfnative.dev/guides/faq.md",
+      "anchors": [
+        "getting-started",
+        "fonts-and-unicode",
+        "standards-and-compliance",
+        "security",
+        "modifying-existing-pdfs",
+        "performance",
+        "why-pdfnative",
+        "common-errors"
+      ],
+      "bytes": 13596,
+      "approxTokens": 3399
+    },
+    {
+      "title": "Font-data validation",
+      "summary": "New in v1.4.0. `validateFontData()` is an opt-in, read-only structural",
+      "html": "https://pdfnative.dev/guides/font-validation.html",
+      "markdown": "https://pdfnative.dev/guides/font-validation.md",
+      "anchors": [
+        "tldr",
+        "what-it-checks",
+        "it-is-opt-in-by-design",
+        "sample"
+      ],
+      "bytes": 2243,
+      "approxTokens": 561
+    },
+    {
+      "title": "Form filling & flattening",
+      "summary": "New in v1.6.0. Read, fill, and flatten the interactive AcroForm fields",
+      "html": "https://pdfnative.dev/guides/form-filling.html",
+      "markdown": "https://pdfnative.dev/guides/form-filling.md",
+      "anchors": [
+        "tldr",
+        "readformfieldsbytes-options",
+        "fillformbytes-values-options",
+        "flattenformbytes-options",
+        "encrypted--signed-documents",
+        "how-it-works",
+        "see-also"
+      ],
+      "bytes": 6166,
+      "approxTokens": 1542
+    },
+    {
+      "title": "Long-term validation (LTV) — PAdES B-B to B-LTA",
+      "summary": "New in v1.7.0. pdfnative signs PDFs that stay verifiable for decades: PAdES baseline signatures (ETSI EN 319 142-1), RFC 3161 signature timestamps, embedded revocation material (`/DSS` + `/VRI`), and document timestamps — all with zero runtime dependencies and zero network access in the engine. Tran",
+      "html": "https://pdfnative.dev/guides/ltv.html",
+      "markdown": "https://pdfnative.dev/guides/ltv.md",
+      "anchors": [
+        "tldr",
+        "why-ltv",
+        "the-provider-architecture",
+        "step-by-step",
+        "multiple-signatures",
+        "testing-without-a-real-tsa-or-ca",
+        "verification-checklist",
+        "limits--scope-v170"
+      ],
+      "bytes": 8882,
+      "approxTokens": 2221
+    },
+    {
+      "title": "pdfnative-mcp — AI Client Integration Guide",
+      "summary": "Tracks the latest published `pdfnative-mcp` (v1.6.0, built on pdfnative 1.7.0). Full release notes: pdfnative-mcp releases. Live package versions — and the `pdfnative` version each one is built on — are shown at the top of the documentation home.",
+      "html": "https://pdfnative.dev/guides/mcp.html",
+      "markdown": "https://pdfnative.dev/guides/mcp.md",
+      "anchors": [
+        "installation",
+        "configuration-by-client",
+        "environment-variables",
+        "tool-reference",
+        "mcp-prompts",
+        "error-codes",
+        "the-pdfa-flag",
+        "output-modes",
+        "end-to-end-example-signed-document",
+        "security-model",
+        "troubleshooting",
+        "release-history",
+        "further-reading"
+      ],
+      "bytes": 61475,
+      "approxTokens": 15369
+    },
+    {
+      "title": "Onboarding — the pdfnative ecosystem in 90 seconds",
+      "summary": "Pick your entry point: the library for code, the CLI for shell scripts, MCP for AI assistants, and React for declarative JSX. They all produce the same ISO 32000-1 / PDF/A-conformant PDFs from the same zero-dependency engine. Live versions for every package are shown at the top of the documentation ",
+      "html": "https://pdfnative.dev/guides/onboarding.html",
+      "markdown": "https://pdfnative.dev/guides/onboarding.md",
+      "anchors": [
+        "1-library-node-browser-deno-bun--30-seconds",
+        "2-cli--30-seconds",
+        "3-mcp-claude-desktop-cursor-continue-zed--30-seconds",
+        "4-react-nextjs-remix-any-react-19-app--30-seconds",
+        "what-to-read-next"
+      ],
+      "bytes": 6270,
+      "approxTokens": 1568
+    },
+    {
+      "title": "Outlines & page labels",
+      "summary": "New in v1.4.0. Give long documents a navigable bookmark tree",
+      "html": "https://pdfnative.dev/guides/outlines.html",
+      "markdown": "https://pdfnative.dev/guides/outlines.md",
+      "anchors": [
+        "tldr",
+        "document-outline-bookmarks",
+        "page-labels",
+        "how-it-works",
+        "see-also"
+      ],
+      "bytes": 6051,
+      "approxTokens": 1513
+    },
+    {
+      "title": "PDF manipulation (merge / split / extract)",
+      "summary": "New in v1.4.0. Combine, slice, and reorder existing PDFs with a",
+      "html": "https://pdfnative.dev/guides/pdf-manipulation.html",
+      "markdown": "https://pdfnative.dev/guides/pdf-manipulation.md",
+      "anchors": [
+        "tldr",
+        "mergepdfssources-options",
+        "splitpdfsource-ranges",
+        "extractpagessource-indices",
+        "encrypted-sources",
+        "re-encrypting-the-output",
+        "streaming-merge--split",
+        "updating-metadata-in-place",
+        "safety--limits",
+        "how-it-works",
+        "see-also"
+      ],
+      "bytes": 12003,
+      "approxTokens": 3001
+    },
+    {
+      "title": "PDF/A conformance in pdfnative",
+      "summary": "PDF/A-1b, 2b, 2u and 3b via `layout: { tagged: … }`, validated against the veraPDF reference validator in CI. Since v1.7.0, a configuration that would break the declared level surfaces a diagnostic — `console.warn` by default, a custom `onDiagnostic` sink, or a thrown error under `strict: true`.",
+      "html": "https://pdfnative.dev/guides/pdfa.html",
+      "markdown": "https://pdfnative.dev/guides/pdfa.md",
+      "anchors": [
+        "tldr",
+        "conformance-diagnostics-v170",
+        "v110-status--fully-validated",
+        "validating-your-output",
+        "pdfa-vs-encryption",
+        "choosing-a-flavour",
+        "hard-invariants-for-contributors",
+        "see-also"
+      ],
+      "bytes": 15911,
+      "approxTokens": 3978
+    },
+    {
+      "title": "Print production — bleed, trim & printer's marks",
+      "summary": "New in v1.7.0. Print-ready PDFs with zero dependencies: page geometry boxes (`/TrimBox`, `/BleedBox`, `/ArtBox`, `/CropBox`), crop and registration marks drawn as pure vector operators, `/Trapped` metadata with XMP parity, print-dialog defaults (duplex, tray, page range, copies), a caller-supplied O",
+      "html": "https://pdfnative.dev/guides/print.html",
+      "markdown": "https://pdfnative.dev/guides/print.md",
+      "anchors": [
+        "tldr",
+        "the-box-model-iso-32000-1-14112",
+        "printers-marks-14113",
+        "trapped-and-prepress-metadata",
+        "print-dialog-defaults-viewerpreferences",
+        "custom-outputintent-taggedpdf-a",
+        "large-formats--userunit",
+        "limits--scope-v170"
+      ],
+      "bytes": 6287,
+      "approxTokens": 1572
+    },
+    {
+      "title": "Quick Start",
+      "summary": "One install, one function. `npm install pdfnative`, then `buildDocumentPDFBytes({ title, blocks })` returns a `Uint8Array` — synchronously, in Node, browsers, Deno and Bun. No config, no build step, no service.",
+      "html": "https://pdfnative.dev/guides/quickstart.html",
+      "markdown": "https://pdfnative.dev/guides/quickstart.md",
+      "anchors": [
+        "install",
+        "nodejs",
+        "browser",
+        "tabular-reports--buildpdfbytes",
+        "free-form-documents--builddocumentpdfbytes",
+        "multi-language",
+        "web-worker",
+        "streaming",
+        "playgrounds",
+        "command-line--pdfnative-cli",
+        "next-steps"
+      ],
+      "bytes": 8042,
+      "approxTokens": 2011
+    },
+    {
+      "title": "pdfnative-react — Declarative JSX Renderer Guide",
+      "summary": "Tracks the latest published `pdfnative-react` (v1.1.0, built on the pdfnative 1.6 engine), with React 19 and `pdfnative` ^1.6.0 as peer dependencies (semver-accepts 1.7.0). Live package versions — and the `pdfnative` version each one is built on — are shown at the top of the documentation home. Full",
+      "html": "https://pdfnative.dev/guides/react.html",
+      "markdown": "https://pdfnative.dev/guides/react.md",
+      "anchors": [
+        "how-it-works",
+        "installation",
+        "when-to-use-the-react-renderer",
+        "components",
+        "server-rendering",
+        "charts",
+        "linting",
+        "agent-surface",
+        "rendering",
+        "hooks--client-components",
+        "agent-authoring--the-token-frugal-docspec",
+        "fonts--environment",
+        "migrating-from-react-pdfrenderer",
+        "diagnostics",
+        "resources"
+      ],
+      "bytes": 17489,
+      "approxTokens": 4372
+    },
+    {
+      "title": "Self-verifying generation",
+      "summary": "pdfnative can read what it writes, so a generated PDF never has to ship",
+      "html": "https://pdfnative.dev/guides/self-verify.html",
+      "markdown": "https://pdfnative.dev/guides/self-verify.md",
+      "anchors": [
+        "why-a-pdf-is-normally-a-blind-artefact",
+        "verifier-1--inspectdocumentlayout-geometry-before-generating",
+        "verifier-2--extracttext-is-the-content-actually-in-the-file",
+        "verifier-3--validatepdfua-structural-pdfua",
+        "verifier-4--listsignatures--openpdf-signatures-encryption-metadata",
+        "the-same-loop-on-the-cli",
+        "the-same-loop-on-mcp",
+        "wire-it-into-ci-and-agent-loops",
+        "further-reading"
+      ],
+      "bytes": 13827,
+      "approxTokens": 3457
+    },
+    {
+      "title": "Digital signatures in pdfnative",
+      "summary": "CMS/PKCS#7 detached signatures in pure TypeScript — RSA PKCS#1 v1.5 (SHA-256/384/512) and ECDSA P-256, the PAdES baseline profile and multiple signatures since v1.7.0, with a one-call `addSignaturePlaceholder()` workflow. For timestamps and B-T → B-LTA, see the LTV guide.",
+      "html": "https://pdfnative.dev/guides/signatures.html",
+      "markdown": "https://pdfnative.dev/guides/signatures.md",
+      "anchors": [
+        "tldr--sign-any-pdf-in-3-lines",
+        "three-step-pipeline",
+        "why-a-separate-placeholder-step",
+        "multiple-signatures-v170",
+        "inspecting-signatures--listsignatures-v170",
+        "algorithms",
+        "validating-the-output",
+        "reading-the-validator-output",
+        "caveats",
+        "native-crypto-provider-v140",
+        "full-example",
+        "related-guides"
+      ],
+      "bytes": 17676,
+      "approxTokens": 4419
+    },
+    {
+      "title": "Streaming output",
+      "summary": "All three produce byte-identical output to `buildDocumentPDFBytes()` / `buildPDFBytes()`.",
+      "html": "https://pdfnative.dev/guides/streaming.html",
+      "markdown": "https://pdfnative.dev/guides/streaming.md",
+      "anchors": [
+        "three-streaming-modes",
+        "streaming-without-joining-the-binary-v130",
+        "options",
+        "draining-to-a-file-streamtofile-v140",
+        "streaming-merge--split-v160",
+        "constraints",
+        "see-also"
+      ],
+      "bytes": 7078,
+      "approxTokens": 1770
+    },
+    {
+      "title": "Smart tables",
+      "summary": "Behaviour change for document-builder tables without `kind`. Previously the renderer applied Helvetica-Bold + credit/debit colour to whichever column happened to be at index 3. The current renderer removes that heuristic — opt in explicitly via `kind: 'amount'`. The legacy `buildPDF()` (financial-st",
+      "html": "https://pdfnative.dev/guides/tables.html",
+      "markdown": "https://pdfnative.dev/guides/tables.md",
+      "anchors": [
+        "tldr",
+        "tableblock-fields-all-optional",
+        "columndefkind-field-optional",
+        "how-multi-page-tables-are-sliced",
+        "tagged-mode--pdfua",
+        "tagged-mode--zebra",
+        "migration-from-v110",
+        "samples-shipped",
+        "reference",
+        "see-also"
+      ],
+      "bytes": 15171,
+      "approxTokens": 3793
+    },
+    {
+      "title": "Text extraction",
+      "summary": "New in v1.6.0. Extract Unicode text from any PDF — including",
+      "html": "https://pdfnative.dev/guides/text-extraction.html",
+      "markdown": "https://pdfnative.dev/guides/text-extraction.md",
+      "anchors": [
+        "tldr",
+        "extracttextbytes-options",
+        "how-text-is-decoded",
+        "reading-order-and-runs",
+        "encrypted-documents",
+        "safety-bounds",
+        "limitations",
+        "samples",
+        "see-also"
+      ],
+      "bytes": 6230,
+      "approxTokens": 1558
+    },
+    {
+      "title": "Troubleshooting",
+      "summary": "Symptom-first fixes for the classic failures — tofu boxes (a font registered but never loaded), RTL text appearing backwards, oversized files, PDF/A validation errors, parser rejections — each with the check that identifies it and the change that fixes it.",
+      "html": "https://pdfnative.dev/guides/troubleshooting.html",
+      "markdown": "https://pdfnative.dev/guides/troubleshooting.md",
+      "anchors": [
+        "font-not-rendering-boxes-or-blank",
+        "pdf-file-too-large",
+        "rtl-text-backwards",
+        "pdfa-validation-fails",
+        "document-has-too-many-blocks--very-large-documents",
+        "parser-fails-on-external-pdf",
+        "build--import-issues"
+      ],
+      "bytes": 5303,
+      "approxTokens": 1326
+    },
+    {
+      "title": "Viewer preferences",
+      "summary": "New in v1.4.0. Control how a conforming reader presents your PDF the",
+      "html": "https://pdfnative.dev/guides/viewer-preferences.html",
+      "markdown": "https://pdfnative.dev/guides/viewer-preferences.md",
+      "anchors": [
+        "tldr",
+        "page-layout-pagelayout",
+        "page-mode-pagemode",
+        "viewerpreferences-flags",
+        "full-screen-kiosk",
+        "pdfa-note"
+      ],
+      "bytes": 3516,
+      "approxTokens": 879
+    }
+  ]
+}
diff --git a/docs/llms-recipes.txt b/docs/llms-recipes.txt
new file mode 100644
index 0000000..7a78d0b
--- /dev/null
+++ b/docs/llms-recipes.txt
@@ -0,0 +1,683 @@
+# pdfnative — executable recipes
+
+> Every file below lives in the repository as `recipes/<name>.ts`, imports only
+> from 'pdfnative', and is executed in CI with each `@expect` assertion checked
+> (tests/docs/recipes.test.ts). The machine index is recipes/index.json.
+
+---
+<!-- source: recipes/arabic-rtl.ts -->
+
+```ts
+/**
+ * Arabic text with positional shaping and right-to-left layout. The Noto
+ * Naskh Arabic data module is registered as a lazy loader, resolved with
+ * `loadFontData`, and passed through `fontEntries`; the engine embeds a
+ * subsetted CIDFont (Identity-H) and shapes the letterforms.
+ *
+ * @task Render shaped right-to-left Arabic text with an embedded Noto font
+ * @surface library
+ * @since 1.3.0
+ * @expect pages === 1
+ * @expect pdf contains '/FontFile2'
+ * @expect pdf contains '/Identity-H'
+ */
+import { buildDocumentPDFBytes, openPdf, registerFont, loadFontData } from 'pdfnative';
+import type { DocumentParams, FontEntry, FontLoader } from 'pdfnative';
+
+export async function run(): Promise<{ bytes: Uint8Array; pages: number }> {
+    // Registration lives inside run() so importing this module has no side
+    // effect on the global font registry; registerFont is idempotent for the
+    // same loader. The cast: the generated data modules predate the full
+    // FontData declaration — the runtime shape is complete.
+    registerFont('ar', (() => import('pdfnative/fonts/noto-arabic-data.js')) as unknown as FontLoader);
+    const arabic = await loadFontData('ar');
+    if (!arabic) throw new Error('Arabic font data failed to load');
+
+    const fontEntries: FontEntry[] = [{ fontData: arabic, fontRef: '/F3', lang: 'ar' }];
+    const params: DocumentParams = {
+        title: 'Arabic shaping',
+        blocks: [
+            { type: 'heading', text: 'Positional forms and ligatures', level: 1 },
+            { type: 'paragraph', text: 'السلام عليكم ورحمة الله وبركاته.' },
+            { type: 'paragraph', text: 'النص العربي يُعرض من اليمين إلى اليسار.' },
+        ],
+        footerText: 'Arabic recipe',
+        fontEntries,
+    };
+
+    const bytes = buildDocumentPDFBytes(params, { creationDate: new Date('2026-08-25T00:00:00Z') });
+    return { bytes, pages: openPdf(bytes).pageCount };
+}
+```
+
+---
+<!-- source: recipes/charts-v2.ts -->
+
+```ts
+/**
+ * Native vector charts (charts v2): a stacked bar chart of quarterly
+ * revenue and a scatter plot on a linear x-axis, one per page. Charts are
+ * pure PDF path operators — no rasterisation, no dependencies.
+ *
+ * @task Render stacked-bar and scatter charts as native vector graphics
+ * @surface library
+ * @since 1.7.0
+ * @expect pages === 2
+ */
+import { buildDocumentPDFBytes, openPdf } from 'pdfnative';
+import type { DocumentParams } from 'pdfnative';
+
+const params: DocumentParams = {
+    title: 'Quarterly figures',
+    blocks: [
+        {
+            type: 'chart',
+            chartType: 'stackedBar',
+            title: 'Revenue by region',
+            categories: ['Q1', 'Q2', 'Q3', 'Q4'],
+            series: [
+                { label: 'EMEA', values: [120, 135, 128, 150] },
+                { label: 'Americas', values: [90, 105, 118, 122] },
+                { label: 'APAC', values: [45, 52, 61, 70] },
+            ],
+            height: 220,
+            legend: 'bottom',
+        },
+        { type: 'pageBreak' },
+        {
+            type: 'chart',
+            chartType: 'scatter',
+            title: 'Latency against payload size',
+            xAxis: { type: 'linear', grid: true },
+            series: [
+                { label: 'Samples', values: [12, 18, 25, 31, 44], xValues: [10, 25, 50, 75, 100] },
+            ],
+            height: 220,
+            dataLabels: { decimals: 0, suffix: ' ms' },
+        },
+    ],
+    footerText: 'Quarterly figures',
+};
+
+export async function run(): Promise<{ bytes: Uint8Array; pages: number }> {
+    const bytes = buildDocumentPDFBytes(params, { creationDate: new Date('2026-08-25T00:00:00Z') });
+    return { bytes, pages: openPdf(bytes).pageCount };
+}
+```
+
+---
+<!-- source: recipes/form-fill-roundtrip.ts -->
+
+```ts
+/**
+ * AcroForm round trip: author a form, enumerate its fields, fill a value,
+ * and read it back. A second fill with `flatten: true` stamps the
+ * appearance into the page content, where plain text extraction finds it.
+ *
+ * @task Author an AcroForm, fill it, and read the value back
+ * @surface library
+ * @since 1.6.0
+ * @expect field 'fullName' value === 'Ada Lovelace'
+ * @expect text of page 0 of the flattened document contains 'Ada Lovelace'
+ */
+import { buildDocumentPDFBytes, readFormFields, fillForm, extractText } from 'pdfnative';
+import type { DocumentParams, ParsedFormField } from 'pdfnative';
+
+const params: DocumentParams = {
+    title: 'Application',
+    blocks: [
+        { type: 'heading', text: 'Application form', level: 1 },
+        { type: 'formField', fieldType: 'text', name: 'fullName', label: 'Full name' },
+        { type: 'formField', fieldType: 'checkbox', name: 'agree', label: 'I agree to the terms' },
+        { type: 'formField', fieldType: 'dropdown', name: 'country', label: 'Country', options: ['France', 'Germany', 'Spain'] },
+    ],
+    footerText: 'Application',
+};
+
+export async function run(): Promise<{
+    bytes: Uint8Array;
+    fields: readonly ParsedFormField[];
+    filledValue: string | readonly string[] | boolean | null;
+    flattenedText: string;
+}> {
+    const blank = buildDocumentPDFBytes(params, { creationDate: new Date('2026-08-25T00:00:00Z') });
+
+    // Enumerate the authored fields, then fill by fully-qualified name.
+    const values = { fullName: 'Ada Lovelace', agree: true, country: 'Germany' } as const;
+    const filled = fillForm(blank, values);
+    const fields = readFormFields(filled);
+    const filledValue = fields.find(f => f.name === 'fullName')?.value ?? null;
+
+    // Flattening replaces the widgets with static page content.
+    const flattened = fillForm(blank, values, { flatten: true });
+    const flattenedText = extractText(flattened, { pages: [0] })[0].text;
+
+    return { bytes: filled, fields, filledValue, flattenedText };
+}
+```
+
+---
+<!-- source: recipes/invoice-pdfa2b.ts -->
+
+```ts
+/**
+ * Invoice as tagged PDF/A-2b — an itemised table with an embedded Latin
+ * font, so the archival claim survives validation. The creation date is
+ * pinned to keep the output byte-identical across runs.
+ *
+ * @task Build a PDF/A-2b invoice with an itemised line-item table
+ * @surface library
+ * @since 1.6.0
+ * @expect pages === 1
+ * @expect text of page 0 contains 'Invoice'
+ * @expect pdfA claim === 'pdfa2b'
+ */
+import { buildDocumentPDFBytes, openPdf, extractText } from 'pdfnative';
+import type { DocumentParams, FontData, FontEntry } from 'pdfnative';
+import * as notoSans from 'pdfnative/fonts/noto-sans-data.js';
+
+// PDF/A requires every rendered glyph to come from an embedded font
+// (ISO 19005 §6.2.11.4.1); the bundled Noto Sans data module covers Latin.
+// /F1 and /F2 are reserved by the engine — custom fontRefs start at /F3.
+const latinFont: FontEntry = {
+    fontRef: '/F3',
+    lang: 'latin',
+    fontData: notoSans as unknown as FontData,
+};
+
+const params: DocumentParams = {
+    title: 'Invoice INV-2026-0042',
+    blocks: [
+        { type: 'paragraph', text: 'Billed to: Acme Widgets Ltd, 4 Foundry Lane, Sheffield' },
+        { type: 'spacer', height: 8 },
+        {
+            type: 'table',
+            caption: 'Line items',
+            headers: ['Item', 'Quantity', 'Unit price', 'Total'],
+            rows: [
+                { cells: ['Consultancy (June)', '3 days', '650.00', '1,950.00'], type: 'debit', pointed: false },
+                { cells: ['Managed hosting', '1 month', '120.00', '120.00'], type: 'debit', pointed: false },
+                { cells: ['Support retainer', '1 month', '250.00', '250.00'], type: 'debit', pointed: false },
+            ],
+        },
+        { type: 'spacer', height: 8 },
+        { type: 'paragraph', text: 'Total due: 2,320.00 GBP within 30 days.', align: 'right' },
+    ],
+    footerText: 'Registered in England no. 01234567',
+    fontEntries: [latinFont],
+    metadata: { author: 'Accounts', subject: 'Invoice INV-2026-0042' },
+};
+
+export async function run(): Promise<{ bytes: Uint8Array; pages: number; text: string }> {
+    const bytes = buildDocumentPDFBytes(params, {
+        tagged: 'pdfa2b',
+        creationDate: new Date('2026-08-25T00:00:00Z'),
+    });
+    const pages = openPdf(bytes).pageCount;
+    const text = extractText(bytes, { pages: [0] })[0].text;
+    return { bytes, pages, text };
+}
+```
+
+---
+<!-- source: recipes/layout-preview.ts -->
+
+```ts
+/**
+ * Dry-run layout inspection: `inspectDocumentLayout` reports how the
+ * builder will paginate and place each block — page index, x, top, width,
+ * height — without rendering a PDF. Useful for layout assertions and
+ * tooling.
+ *
+ * @task Preview pagination and block geometry without rendering a PDF
+ * @surface library
+ * @since 1.5.0
+ * @expect totalPages === 2
+ * @expect first block type === 'heading' on page 0 with width > 0
+ */
+import { inspectDocumentLayout } from 'pdfnative';
+import type { DocumentParams, LayoutInspection } from 'pdfnative';
+
+const params: DocumentParams = {
+    title: 'Layout probe',
+    blocks: [
+        { type: 'heading', text: 'Section one', level: 1 },
+        { type: 'paragraph', text: 'A paragraph measured, not rendered.' },
+        { type: 'pageBreak' },
+        { type: 'heading', text: 'Section two', level: 1 },
+        { type: 'paragraph', text: 'Placed on the second page.' },
+    ],
+    footerText: 'Layout probe',
+};
+
+export async function run(): Promise<{ inspection: LayoutInspection }> {
+    const inspection = inspectDocumentLayout(params);
+    return { inspection };
+}
+```
+
+---
+<!-- source: recipes/merge-encrypted.ts -->
+
+```ts
+/**
+ * Merge two documents and encrypt the result in the same call.
+ * `MergeOptions.encrypt` re-protects the assembled document (AES-128
+ * here); the reader then opens it with the user password and reports the
+ * scheme. Encryption uses random salts, so the bytes differ per run while
+ * the structure stays identical.
+ *
+ * @task Merge two PDFs and AES-encrypt the combined document
+ * @surface library
+ * @since 1.6.0
+ * @expect pages === 2
+ * @expect encryption.algorithm === 'aes128'
+ */
+import { buildDocumentPDFBytes, mergePdfs, openPdf } from 'pdfnative';
+import type { DocumentParams, PdfEncryptionInfo } from 'pdfnative';
+
+function chapter(title: string, body: string): DocumentParams {
+    return {
+        title,
+        blocks: [{ type: 'paragraph', text: body }],
+        footerText: title,
+    };
+}
+
+export async function run(): Promise<{ bytes: Uint8Array; pages: number; encryption: PdfEncryptionInfo | null }> {
+    const created = new Date('2026-08-25T00:00:00Z');
+    const first = buildDocumentPDFBytes(chapter('Part one', 'Opening chapter.'), { creationDate: created });
+    const second = buildDocumentPDFBytes(chapter('Part two', 'Closing chapter.'), { creationDate: created });
+
+    const bytes = mergePdfs([first, second], {
+        encrypt: {
+            ownerPassword: 'owner-secret',
+            userPassword: 'reader-secret',
+            algorithm: 'aes128',
+            permissions: { print: true, copy: false },
+        },
+    });
+
+    const reader = openPdf(bytes, { password: 'reader-secret' });
+    return { bytes, pages: reader.pageCount, encryption: reader.encryption };
+}
+```
+
+---
+<!-- source: recipes/multipage-table.ts -->
+
+```ts
+/**
+ * A table long enough to paginate. `repeatHeader` (the default, stated
+ * here explicitly) re-draws the header row on every continuation page,
+ * which the extracted text of page 1 confirms.
+ *
+ * @task Paginate a long table with the header row repeated on every page
+ * @surface library
+ * @since 1.6.0
+ * @expect pages === 2
+ * @expect text of page 1 contains 'Description'
+ */
+import { buildDocumentPDFBytes, openPdf, extractText } from 'pdfnative';
+import type { DocumentParams, PdfRow } from 'pdfnative';
+
+const rows: PdfRow[] = Array.from({ length: 70 }, (_, i) => ({
+    cells: [`2026-06-${String((i % 28) + 1).padStart(2, '0')}`, `Ledger entry ${i + 1}`, (100 + i).toFixed(2)],
+    type: i % 2 === 0 ? 'credit' : 'debit',
+    pointed: false,
+}));
+
+const params: DocumentParams = {
+    title: 'June ledger',
+    blocks: [
+        {
+            type: 'table',
+            headers: ['Date', 'Description', 'Amount'],
+            rows,
+            repeatHeader: true,
+        },
+    ],
+    footerText: 'June ledger',
+};
+
+export async function run(): Promise<{ bytes: Uint8Array; pages: number; page1Text: string }> {
+    const bytes = buildDocumentPDFBytes(params, { creationDate: new Date('2026-08-25T00:00:00Z') });
+    const pages = openPdf(bytes).pageCount;
+    const page1Text = extractText(bytes, { pages: [1] })[0].text;
+    return { bytes, pages, page1Text };
+}
+```
+
+---
+<!-- source: recipes/print-bleed.ts -->
+
+```ts
+/**
+ * Print production: the page is designed at trim size plus 3 mm bleed on
+ * every side (8.5 pt), `layout.print.bleed` derives the TrimBox and
+ * BleedBox, and `marks: true` draws crop and registration marks outside
+ * the trim area. The boxes are read back from the parsed page.
+ *
+ * @task Prepare a print-ready page with bleed, TrimBox and printer's marks
+ * @surface library
+ * @since 1.7.0
+ * @expect trimBox === [8.5, 8.5, 603.78, 850.39]
+ * @expect bleedBox === [0, 0, 612.28, 858.89]
+ */
+import { buildDocumentPDFBytes, openPdf, dictGetArray } from 'pdfnative';
+
+const BLEED = 8.5; // 3 mm in points
+const TRIM_W = 595.28; // A4 trim width
+const TRIM_H = 841.89; // A4 trim height
+
+export async function run(): Promise<{
+    bytes: Uint8Array;
+    trimBox: readonly number[];
+    bleedBox: readonly number[];
+}> {
+    const bytes = buildDocumentPDFBytes(
+        {
+            title: 'Poster',
+            blocks: [{ type: 'paragraph', text: 'Background art runs to the page edge; keep copy inside the trim.' }],
+            footerText: 'Poster',
+        },
+        {
+            // Page size = trim size + 2 × bleed; backgrounds may run to the edge.
+            pageWidth: TRIM_W + 2 * BLEED,
+            pageHeight: TRIM_H + 2 * BLEED,
+            print: { bleed: BLEED, marks: true },
+            creationDate: new Date('2026-08-25T00:00:00Z'),
+        },
+    );
+
+    const page = openPdf(bytes).getPage(0);
+    const asNumbers = (name: string): number[] =>
+        (dictGetArray(page, name) ?? []).filter((v): v is number => typeof v === 'number');
+
+    return { bytes, trimBox: asNumbers('TrimBox'), bleedBox: asNumbers('BleedBox') };
+}
+```
+
+---
+<!-- source: recipes/signed-pades.ts -->
+
+```ts
+/**
+ * PAdES B-B digital signature. The document is built, an invisible
+ * signature placeholder is injected (with the CAdES subFilter and the
+ * descriptive entries baked in — the /Sig dictionary's byte layout is
+ * frozen at placeholder time), then signed. The caller supplies the
+ * certificate and RSA key; pdfnative never generates key material.
+ *
+ * @task Sign a document with a PAdES B-B (ETSI.CAdES.detached) signature
+ * @surface library
+ * @since 1.7.0
+ * @expect signatures.length === 1
+ * @expect signatures[0].subFilter === 'ETSI.CAdES.detached'
+ * @expect signatures[0].isPlaceholder === false
+ */
+import { buildDocumentPDFBytes, addSignaturePlaceholder, signPdfBytes, listSignatures } from 'pdfnative';
+import type { DocumentParams, PdfSignatureInfo, RsaPrivateKey, X509Certificate } from 'pdfnative';
+
+/** Key material supplied by the caller (e.g. from a PKCS#12 store). */
+export interface SignerMaterial {
+    readonly cert: X509Certificate;
+    readonly key: RsaPrivateKey;
+    readonly chain?: readonly X509Certificate[];
+}
+
+const params: DocumentParams = {
+    title: 'Service agreement',
+    blocks: [
+        { type: 'heading', text: 'Agreement', level: 1 },
+        { type: 'paragraph', text: 'This agreement is executed by digital signature.' },
+    ],
+    footerText: 'Service agreement',
+};
+
+export async function run(signer: SignerMaterial): Promise<{ bytes: Uint8Array; signatures: readonly PdfSignatureInfo[] }> {
+    const unsigned = buildDocumentPDFBytes(params, { creationDate: new Date('2026-08-25T00:00:00Z') });
+
+    const placeheld = addSignaturePlaceholder(unsigned, {
+        fieldName: 'Author',
+        metadata: {
+            subFilter: 'ETSI.CAdES.detached',
+            reason: 'Approval',
+            location: 'London',
+            signingTime: new Date('2026-08-25T00:00:00Z'),
+        },
+    });
+
+    const bytes = signPdfBytes(placeheld, {
+        signerCert: signer.cert,
+        certChain: signer.chain,
+        rsaKey: signer.key,
+        algorithm: 'rsa-sha256',
+        profile: 'pades',
+        signingTime: new Date('2026-08-25T00:00:00Z'),
+    });
+
+    return { bytes, signatures: listSignatures(bytes) };
+}
+```
+
+---
+<!-- source: recipes/streaming-large.ts -->
+
+```ts
+/**
+ * True streaming output for a large document: `buildDocumentPDFStreamTrue`
+ * yields the PDF in chunks whose concatenation is byte-identical to the
+ * buffered builder's output for the same input (creation date pinned so
+ * both builds share it).
+ *
+ * @task Stream a 300-block document and match the buffered output byte for byte
+ * @surface library
+ * @since 1.3.0
+ * @expect identical === true
+ * @expect pages === 8
+ */
+import { buildDocumentPDFBytes, buildDocumentPDFStreamTrue, concatChunks, openPdf } from 'pdfnative';
+import type { DocumentParams, DocumentBlock } from 'pdfnative';
+
+const blocks: DocumentBlock[] = Array.from({ length: 300 }, (_, i) => ({
+    type: 'paragraph' as const,
+    text: `Row ${i + 1}: measurement recorded and archived.`,
+}));
+
+const params: DocumentParams = {
+    title: 'Measurement log',
+    blocks,
+    footerText: 'Measurement log',
+};
+
+export async function run(): Promise<{ bytes: Uint8Array; pages: number; identical: boolean }> {
+    const created = new Date('2026-08-25T00:00:00Z');
+
+    const chunks: Uint8Array[] = [];
+    for await (const chunk of buildDocumentPDFStreamTrue(params, { creationDate: created }, { chunkSize: 16 * 1024 })) {
+        chunks.push(chunk);
+    }
+    const bytes = concatChunks(chunks);
+
+    const buffered = buildDocumentPDFBytes(params, { creationDate: created });
+    const identical = bytes.length === buffered.length && bytes.every((b, i) => b === buffered[i]);
+
+    return { bytes, pages: openPdf(bytes).pageCount, identical };
+}
+```
+
+---
+<!-- source: recipes/text-extraction-rag.ts -->
+
+```ts
+/**
+ * Positioned text extraction for indexing pipelines (RAG, search). With
+ * `includeRuns` each text-showing operation is returned with its
+ * device-space origin and effective font size, alongside the
+ * reading-order text per page.
+ *
+ * @task Extract reading-order text plus positioned runs from a document
+ * @surface library
+ * @since 1.6.0
+ * @expect text of page 0 contains 'retrieval'
+ * @expect runs.length > 0
+ * @expect every run has numeric x, y and fontSize
+ */
+import { buildDocumentPDFBytes, extractText } from 'pdfnative';
+import type { DocumentParams, ExtractedPageText } from 'pdfnative';
+
+const params: DocumentParams = {
+    title: 'Corpus notes',
+    blocks: [
+        { type: 'heading', text: 'Chunking strategy', level: 1 },
+        { type: 'paragraph', text: 'Split documents into passages before retrieval; keep headings with their sections.' },
+        { type: 'paragraph', text: 'Store the run positions so citations can point back into the page.' },
+    ],
+    footerText: 'Corpus notes',
+};
+
+export async function run(): Promise<{ bytes: Uint8Array; pages: readonly ExtractedPageText[] }> {
+    const bytes = buildDocumentPDFBytes(params, { creationDate: new Date('2026-08-25T00:00:00Z') });
+    const pages = extractText(bytes, { includeRuns: true });
+    return { bytes, pages };
+}
+```
+
+---
+<!-- source: recipes/toc-outline.ts -->
+
+```ts
+/**
+ * Table of contents and bookmarks together: a `toc` block renders linked
+ * entries for every heading, while `outline: 'auto'` derives the viewer's
+ * bookmark panel from the same headings and adds /Outlines to the catalog.
+ *
+ * @task Generate a linked table of contents plus automatic bookmarks
+ * @surface library
+ * @since 1.6.0
+ * @expect pages === 3
+ * @expect catalog has /Outlines
+ * @expect text of page 0 contains 'Table of Contents'
+ */
+import { buildDocumentPDFBytes, openPdf, extractText } from 'pdfnative';
+import type { DocumentParams } from 'pdfnative';
+
+const params: DocumentParams = {
+    title: 'Operations handbook',
+    blocks: [
+        { type: 'toc', maxLevel: 2 },
+        { type: 'pageBreak' },
+        { type: 'heading', text: 'Onboarding', level: 1 },
+        { type: 'paragraph', text: 'Accounts, hardware and access requests.' },
+        { type: 'heading', text: 'First week', level: 2 },
+        { type: 'paragraph', text: 'Pairing schedule and reading list.' },
+        { type: 'pageBreak' },
+        { type: 'heading', text: 'Incident response', level: 1 },
+        { type: 'paragraph', text: 'Escalation ladder and post-incident review.' },
+    ],
+    footerText: 'Operations handbook',
+    outline: 'auto',
+};
+
+export async function run(): Promise<{ bytes: Uint8Array; pages: number; hasOutlines: boolean; tocText: string }> {
+    const bytes = buildDocumentPDFBytes(params, { creationDate: new Date('2026-08-25T00:00:00Z') });
+    const reader = openPdf(bytes);
+    const hasOutlines = reader.getCatalog().get('Outlines') !== undefined;
+    const tocText = extractText(bytes, { pages: [0] })[0].text;
+    return { bytes, pages: reader.pageCount, hasOutlines, tocText };
+}
+```
+
+---
+<!-- source: recipes/update-metadata.ts -->
+
+```ts
+/**
+ * Incremental metadata update: open an existing document, re-issue its
+ * /Info dictionary with a new title and a pinned modification date, and
+ * save. The original revision is preserved byte for byte; the reopened
+ * document reports the new title.
+ *
+ * @task Retitle an existing PDF via a non-destructive incremental update
+ * @surface library
+ * @since 1.7.0
+ * @expect title === 'Quarterly report (revised)'
+ */
+import { buildDocumentPDFBytes, openPdf, createModifier } from 'pdfnative';
+
+/** /Info strings may be UTF-16BE with a BOM; plain literals pass through. */
+function decodePdfText(raw: unknown): string {
+    if (typeof raw !== 'string') return '';
+    if (raw.length >= 2 && raw.charCodeAt(0) === 0xFE && raw.charCodeAt(1) === 0xFF) {
+        let out = '';
+        for (let i = 2; i + 1 < raw.length; i += 2) {
+            out += String.fromCharCode((raw.charCodeAt(i) << 8) | raw.charCodeAt(i + 1));
+        }
+        return out;
+    }
+    return raw;
+}
+
+export async function run(): Promise<{ bytes: Uint8Array; title: string }> {
+    const original = buildDocumentPDFBytes(
+        {
+            title: 'Quarterly report',
+            blocks: [{ type: 'paragraph', text: 'Figures under review.' }],
+            footerText: 'Quarterly report',
+        },
+        { creationDate: new Date('2026-08-25T00:00:00Z') },
+    );
+
+    const modifier = createModifier(openPdf(original));
+    modifier.updateMetadata({
+        title: 'Quarterly report (revised)',
+        modDate: new Date('2026-08-25T00:00:00Z'),
+    });
+    const bytes = modifier.save();
+
+    const info = openPdf(bytes).getInfo();
+    const title = decodePdfText(info?.get('Title'));
+    return { bytes, title };
+}
+```
+
+---
+<!-- source: recipes/watermark.ts -->
+
+```ts
+/**
+ * A rotated, semi-transparent text watermark behind the content of every
+ * page. The watermark never disturbs the body text: extraction still
+ * returns the paragraph, and the watermark string itself is present too.
+ *
+ * @task Stamp a rotated DRAFT watermark behind the page content
+ * @surface library
+ * @since 1.6.0
+ * @expect text of page 0 contains 'Confidential clause'
+ * @expect text of page 0 contains 'DRAFT'
+ */
+import { buildDocumentPDFBytes, extractText } from 'pdfnative';
+import type { DocumentParams } from 'pdfnative';
+
+const params: DocumentParams = {
+    title: 'Draft contract',
+    blocks: [
+        { type: 'heading', text: 'Terms', level: 1 },
+        { type: 'paragraph', text: 'Confidential clause: neither party discloses the commercial terms.' },
+    ],
+    footerText: 'Draft contract',
+};
+
+export async function run(): Promise<{ bytes: Uint8Array; text: string }> {
+    const bytes = buildDocumentPDFBytes(params, {
+        watermark: {
+            text: { text: 'DRAFT', fontSize: 60, opacity: 0.15, angle: -45 },
+            position: 'background',
+        },
+        creationDate: new Date('2026-08-25T00:00:00Z'),
+    });
+    const text = extractText(bytes, { pages: [0] })[0].text;
+    return { bytes, text };
+}
+```
diff --git a/docs/llms.txt b/docs/llms.txt
index 7907dee..fa255d5 100644
--- a/docs/llms.txt
+++ b/docs/llms.txt
@@ -5,7 +5,7 @@
 ## Docs
 
 - [README](https://github.com/Nizoka/pdfnative/blob/main/README.md): Full feature list, install, quick start, API surface, examples.
-- [ROADMAP](https://github.com/Nizoka/pdfnative/blob/main/ROADMAP.md): Shipped milestones (v1.0 → v1.7; v1.5: math/technical-symbols font, `pdfnative/tools` font compiler/parser, SVG `<text>`, page-labels reader, layout debug overlay + `inspectDocumentLayout`, markup annotation read/write, AI-agent governance; v1.4: document outline/bookmarks, page labels, page-tree manipulation (merge/split/extract), streamToFile, COLRv1 advanced compositing; v1.3: COLRv1 colour emoji, USE-lite shaper integration, true constant-memory streaming, UAX #9 X4–X5 overrides, Telugu + Amharic/Sinhala/Tibetan/Khmer/Myanmar scripts, validatePdfUA) + long-term (WASM, full USE).
+- [ROADMAP](https://github.com/Nizoka/pdfnative/blob/main/ROADMAP.md): Shipped milestones (v1.0 → v1.7; v1.7: PAdES LTV B-B → B-LTA, charts v2, colour-emoji flag/ZWJ sequences, UAX #9 conformance, print production, PDF/A declaration guards, `updateMetadata`; v1.6: parser-side decryptor, streaming merge/split/extract, fill & flatten AcroForms, native vector charts, `extractText`, re-encrypt output; v1.5: math/technical-symbols font, `pdfnative/tools` font compiler/parser, SVG `<text>`, page-labels reader, layout debug overlay + `inspectDocumentLayout`, markup annotation read/write, AI-agent governance; v1.4: document outline/bookmarks, page labels, page-tree manipulation (merge/split/extract), streamToFile, COLRv1 advanced compositing; v1.3: COLRv1 colour emoji, USE-lite shaper integration, true constant-memory streaming, UAX #9 X4–X5 overrides, Telugu + Amharic/Sinhala/Tibetan/Khmer/Myanmar scripts, validatePdfUA) + long-term (WASM, full USE).
 - [CHANGELOG](https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md): Per-version changes.
 - [Release notes v1.7.0](https://github.com/Nizoka/pdfnative/blob/main/release-notes/v1.7.0.md): PAdES LTV signing B-B → B-LTA (`signPdfBytesWithTimestamp` RFC 3161 timestamps, `addValidationInfo` `/DSS` + `/VRI` OCSP/CRL material, `addDocumentTimestamp`, `listSignatures`, multi-signature via `addSignaturePlaceholder({ allowMultiple })` — network transport injected through `setTimestampProvider`/`setRevocationProvider`, the engine never opens a socket), charts v2 (stackedBar/stackedBarH/area/scatter, secondary right axis, log + UTC time scales, data labels, x-label collision handling), colour-emoji flag & ZWJ sequences (51 flags + 22 ZWJ as COLR ligatures), UAX #9 conformance fixes (RTL digit order, glyph mirroring, ALEF joining, Persian presentation forms), PDF/A declaration guards (`strict`/`onDiagnostic`), incremental writer/xref hardening, `PdfModifier.updateMetadata()`.
 - [Release notes v1.6.0](https://github.com/Nizoka/pdfnative/blob/main/release-notes/v1.6.0.md): Standard Security Handler reader/decryptor (`openPdf(bytes, { password })`, RC4/AES-128/AES-256; `PdfSourceInput`/`MergeOptions.password` for encrypted merge/split sources), streaming page-tree manipulation (`streamMergedPdfs`/`streamSplitPdf`/`streamExtractPages`), fill & flatten existing AcroForm PDFs (`readFormFields`/`fillForm`/`flattenForm`) — encrypted documents included (encrypted incremental update), native vector charts (`chart` block: bar/barH/line/pie/donut), text extraction (`extractText`: per-page reading-order text + positioned runs, encrypted PDFs supported), re-encrypt merge/split output (`MergeOptions.encrypt`, AES-128/256), expanded colour-emoji subset (221 → 1167 incl. complete Transport & Map). Fixes: spec-compliant R6 hash + all-strings encryption on the writer; incremental trailer carries `/Encrypt` forward.
@@ -25,7 +25,7 @@
 - [FAQ](https://pdfnative.dev/guides/faq.html): Custom fonts, encryption, BiDi, workers, vs other libs.
 - [Troubleshooting](https://pdfnative.dev/guides/troubleshooting.html): Missing glyphs, RTL appearing backwards, oversized PDFs, parser errors.
 - [Colour-emoji CLI](https://pdfnative.dev/guides/colour-emoji-cli.html): `npx pdfnative-build-emoji-font` — generate a colour-emoji data module covering any glyph subset up to the full ~3,600-glyph Noto Color Emoji set, plus flag & ZWJ sequences via `--sequences` / `--sequence-list`; pinned download + SHA-256 verification.
-- [Charts](https://pdfnative.dev/guides/charts.html): Native vector `chart` blocks — 9 kinds (bar, horizontal bar, stacked bars, line, area, scatter, pie, donut) with secondary right axis, log and time scales, data labels, x-label collision handling. Path operators, no rasterisation; `/Figure` tagging with alt text.
+- [Charts](https://pdfnative.dev/guides/charts.html): Native vector `chart` blocks — 9 kinds (bar, horizontal bar, stacked bar, stacked horizontal bar, line, area, scatter, pie, donut) with secondary right axis, log and time scales, data labels, x-label collision handling. Path operators, no rasterisation; `/Figure` tagging with alt text.
 - [Text extraction](https://pdfnative.dev/guides/text-extraction.html): `extractText()` — reading-order Unicode via `/ToUnicode`, optional positioned runs, works on encrypted PDFs with a password. The RAG / agent-ingestion entry point.
 - [Form filling](https://pdfnative.dev/guides/form-filling.html): `readFormFields()` / `fillForm()` / `flattenForm()` on existing AcroForms, including encrypted PDFs via incremental update.
 - [PDF manipulation](https://pdfnative.dev/guides/pdf-manipulation.html): `openPdf()` (with `{ password }`), merge / split / extract pages, re-encrypt on output, and their streaming variants.
@@ -48,18 +48,28 @@
 
 - [Copilot instructions](https://github.com/Nizoka/pdfnative/blob/main/.github/copilot-instructions.md): Canonical project conventions — architecture, code style, build/test, PDF-specific invariants.
 - [AGENTS.md](https://github.com/Nizoka/pdfnative/blob/main/AGENTS.md): Editor-agnostic agent guidance (Cursor / Aider / Claude Code / Continue).
-- [MCP integration](https://pdfnative.dev/guides/mcp.html): `pdfnative-mcp` v1.5.0 — use pdfnative from Claude Desktop, Cursor, Continue, Zed via 24 tools — native vector `add_chart`, `read_form_fields` / `fill_form`, `encrypt_pdf` / `decrypt_pdf`, markup `annotate_pdf`, the network-free `draft_governance_issue`, and the page-tree trio `merge_pdfs` / `split_pdf` / `extract_pages`. Built on pdfnative 1.7.0.
-- [CLI](https://pdfnative.dev/guides/cli.html): `pdfnative-cli` v1.3.0 — 17 commands from the terminal — render, fill, annotate, merge / split / extract, sign, verify, encrypt, decrypt, inspect, extract-text, batch, doctor, schema, completion, govern; agent-native `--json`/`E_*`/`--dry-run` contract. Built on pdfnative 1.7.0.
+- [MCP integration](https://pdfnative.dev/guides/mcp.html): `pdfnative-mcp` v1.6.0 — use pdfnative from Claude Desktop, Cursor, Continue, Zed via 28 tools — the complete PAdES ladder B-B → B-LTA (`sign_pdf` with RFC 3161 timestamps, `add_ltv`, `timestamp_pdf`), `update_metadata`, the read-only `inspect_layout` pagination preview, all 13 block kinds in `generate_basic_pdf`, print production, charts v2, native vector `add_chart`, `read_form_fields` / `fill_form`, `encrypt_pdf` / `decrypt_pdf`, markup `annotate_pdf`, the network-free `draft_governance_issue`, and the page-tree trio `merge_pdfs` / `split_pdf` / `extract_pages`. MCP 2026-07-28 spec with legacy fallback. Built on pdfnative 1.7.0.
+- [CLI](https://pdfnative.dev/guides/cli.html): `pdfnative-cli` v1.3.0 — 17 commands from the terminal — render, fill, annotate, merge / split / extract, sign, verify, encrypt, decrypt, inspect, extract-text, batch, doctor, schema, completion, govern; agent-native `--json`/`E_*`/`--dry-run` contract. Built on the pdfnative 1.6 engine (pins `^1.6.0`, semver-accepts 1.7.0).
 - [React](https://pdfnative.dev/guides/react.html): `pdfnative-react` v1.1.0 — declarative JSX components compiled on-device to pdfnative blocks; render functions, client hooks, token-frugal DocSpec.
 
 ## Source
 
 - [src/](https://github.com/Nizoka/pdfnative/tree/main/src): Library source (core, crypto, fonts, parser, shaping, types, worker).
 - [scripts/generators/](https://github.com/Nizoka/pdfnative/tree/main/scripts/generators): 48 sample generators producing 242 reference PDFs.
-- [tests/](https://github.com/Nizoka/pdfnative/tree/main/tests): 2665+ tests across 122 files. 95%+ statements measured at v1.6.0; CI enforces ≥88%.
+- [tests/](https://github.com/Nizoka/pdfnative/tree/main/tests): 2686+ tests across 123 files. 95%+ statements measured at v1.6.0; CI enforces ≥88%.
+
+## Machine-readable artefacts
+
+- [agent-brief.md](https://pdfnative.dev/agent-brief.md): A compact briefing for AI agents writing code with pdfnative — the core API, the verified pitfalls that produce wrong code, the surface decision tree, and the self-verification loop. Designed to be pasted into a coding agent's context.
+- [llms-full.txt](https://pdfnative.dev/llms-full.txt): This index plus the README and the full Markdown source of every guide, in one request.
+- [llms-recipes.txt](https://pdfnative.dev/llms-recipes.txt): The executable recipe corpus — standalone TypeScript files importing from `pdfnative`, each executed in CI with its `@expect` assertions verified, so the code you copy is proven to compile and to produce exactly the artefact its header describes.
+- [api.json](https://pdfnative.dev/assets/api.json): The public API surface, derived mechanically from the export statements of `src/index.ts` — name, kind, source module, signature and TSDoc summary where extractable. The substitute for the unpublished `index.d.ts`.
+- [surfaces.json](https://pdfnative.dev/data/surfaces.json): The capability × surface matrix (library / CLI / MCP / React) behind the [Choosing your surface](https://pdfnative.dev/guides/choose.md) guide.
+- [llms-index.json](https://pdfnative.dev/llms-index.json): Per-page machine index — HTML and raw-Markdown URL, title, summary, section anchors, and exact byte / approximate token sizes for every artefact, so you can decide what to fetch before spending the tokens.
+- Every guide serves its raw Markdown at the same URL with `.md` instead of `.html`, declared via `<link rel="alternate" type="text/markdown">` in each page head. All of these URLs are listed in the sitemap.
 
 ## Ecosystem
 
-- [pdfnative-cli](https://github.com/Nizoka/pdfnative-cli): CLI wrapper for pdfnative (v1.3.0, built on pdfnative 1.7.0) — render, fill, annotate, merge, split, extract, sign, verify, encrypt, decrypt, inspect, extract-text, batch, doctor, schema, completion, govern.
-- [pdfnative-mcp](https://github.com/Nizoka/pdfnative-mcp): Model Context Protocol server exposing pdfnative as 24 AI tools (v1.5.0, built on pdfnative 1.7.0).
+- [pdfnative-cli](https://github.com/Nizoka/pdfnative-cli): CLI wrapper for pdfnative (v1.3.0, built on the pdfnative 1.6 engine — pins `^1.6.0`, semver-accepts 1.7.0) — render, fill, annotate, merge, split, extract, sign, verify, encrypt, decrypt, inspect, extract-text, batch, doctor, schema, completion, govern.
+- [pdfnative-mcp](https://github.com/Nizoka/pdfnative-mcp): Model Context Protocol server exposing pdfnative as 28 AI tools (v1.6.0, built on pdfnative 1.7.0).
 - [pdfnative-react](https://github.com/Nizoka/pdfnative-react): React renderer — declarative JSX components compiled on-device to pdfnative blocks (v1.1.0, React 19 + pdfnative ^1.6.0 peers).
diff --git a/docs/playgrounds/all-scripts.html b/docs/playgrounds/all-scripts.html
index 7eca4eb..10e0145 100644
--- a/docs/playgrounds/all-scripts.html
+++ b/docs/playgrounds/all-scripts.html
@@ -75,6 +75,7 @@
     <a href="./extreme-scripts.html">Extreme scripts</a>
     <a href="./all-scripts.html" aria-current="page">All 22 scripts</a>
     <a href="./toolkit.html">PDF Toolkit</a>
+    <a href="./inspect.html">Inspect &amp; verify</a>
     <a href="./charts.html">Charts</a>
     <a href="./authoring-plus.html">Authoring+</a>
     <a href="./scale.html">Scale</a>
diff --git a/docs/playgrounds/authoring-plus.html b/docs/playgrounds/authoring-plus.html
index f9c27f5..84c404f 100644
--- a/docs/playgrounds/authoring-plus.html
+++ b/docs/playgrounds/authoring-plus.html
@@ -7,10 +7,10 @@
   <meta name="description" content="Try pdfnative's 1.5.0 authoring features in your browser: SVG <text> labels, the layout debug overlay, and markup annotations (highlight, underline, sticky notes) — all client-side, zero install.">
   <link rel="canonical" href="https://pdfnative.dev/playgrounds/authoring-plus.html">
   <link rel="alternate" hreflang="en" href="https://pdfnative.dev/playgrounds/authoring-plus.html">
-  <link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/playgrounds/authoring-plus.html">
+  <link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/playgrounds/authoring-plus.html">
   <meta property="og:type" content="website">
   <meta property="og:site_name" content="pdfnative">
-  <meta property="og:locale" content="en_US">
+  <meta property="og:locale" content="en_US">
   <meta property="og:url" content="https://pdfnative.dev/playgrounds/authoring-plus.html">
   <meta property="og:title" content="Authoring+ Playground (v1.5.0) — pdfnative">
   <meta property="og:description" content="SVG text labels, layout debug overlay, and markup annotations — all in your browser.">
@@ -75,6 +75,7 @@
     <a href="./extreme-scripts.html">Extreme scripts</a>
     <a href="./all-scripts.html">All 22 scripts</a>
     <a href="./toolkit.html">PDF Toolkit</a>
+    <a href="./inspect.html">Inspect &amp; verify</a>
     <a href="./charts.html">Charts</a>
     <a href="./authoring-plus.html" aria-current="page">Authoring+</a>
     <a href="./scale.html">Scale</a>
diff --git a/docs/playgrounds/charts.html b/docs/playgrounds/charts.html
index 549a598..6209063 100644
--- a/docs/playgrounds/charts.html
+++ b/docs/playgrounds/charts.html
@@ -13,8 +13,10 @@
   <meta property="og:locale" content="en_US">
   <meta property="og:url" content="https://pdfnative.dev/playgrounds/charts.html">
   <meta property="og:title" content="Charts Playground — pdfnative">
-  <meta property="og:description" content="Nine chart types — bar, stacked, line, area, scatter, pie, donut — rendered as pure PDF path operators, zero install, right in your browser.">
+  <meta property="og:description" content="Nine chart types — bar, horizontal bar, stacked bar, stacked horizontal bar, line, area, scatter, pie, donut — rendered as pure PDF path operators, zero install, right in your browser.">
   <meta property="og:image" content="https://pdfnative.dev/assets/og-image.png">
+  <meta property="og:image:width" content="1200">
+  <meta property="og:image:height" content="630">
   <meta name="twitter:card" content="summary_large_image">
   <meta name="twitter:title" content="Charts Playground — pdfnative">
   <meta name="twitter:description" content="Native vector charts as pure PDF path operators. Zero install.">
@@ -105,12 +107,13 @@
 </nav>
 
 <main class="guide-shell" id="main-content" tabindex="-1">
-  <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Playgrounds</a> &nbsp;›&nbsp; Charts (v1.6.0)</p>
+  <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Playgrounds</a> &nbsp;›&nbsp; Charts (v1.6.0 → v1.7.0)</p>
   <nav class="playground-switcher" aria-label="Playground switcher">
     <span class="playground-switcher-label">Playgrounds:</span>
     <a href="./extreme-scripts.html">Extreme scripts</a>
     <a href="./all-scripts.html">All 22 scripts</a>
     <a href="./toolkit.html">PDF Toolkit</a>
+    <a href="./inspect.html">Inspect &amp; verify</a>
     <a href="./charts.html" aria-current="page">Charts</a>
     <a href="./authoring-plus.html">Authoring+</a>
     <a href="./scale.html">Scale</a>
@@ -120,7 +123,7 @@
     <a href="./" style="margin-left:auto;">All →</a>
   </nav>
   <article class="guide-content">
-    <h1>Native vector charts — new in 1.6.0</h1>
+    <h1>Native vector charts — since 1.6.0, charts v2 in 1.7.0</h1>
     <p>pdfnative's <code>chart</code> block renders <strong>bar, horizontal-bar, line, pie, and donut</strong> charts — and, since 1.7.0, <strong>stacked bars, area, and scatter</strong> — as <strong>pure PDF path operators</strong>: rectangles, line segments, and cubic-Bézier arcs. Zero dependencies, no rasterisation, crisp at any zoom, and PDF/A-safe. Pick a preset, generate, and open the downloaded PDF in any viewer.</p>
 
     <div id="status" style="display:none;padding:10px 14px;border-radius:6px;margin:16px 0;font-size:14px;"></div>
@@ -131,7 +134,7 @@ <h1>Native vector charts — new in 1.6.0</h1>
         <option value="bar">Grouped bar — revenue vs cost</option>
         <option value="line">Multi-series line with markers</option>
         <option value="pie">Pie — traffic sources</option>
-        <option value="donut">Donut — budget split (tagged + alt text)</option>
+        <option value="donut">Donut — budget split (PDF/A-2b tagged + alt text)</option>
         <option value="mixed">Dashboard — several charts on one page</option>
         <option value="v2">Charts v2 — stacked, area, scatter (1.7.0)</option>
       </select>
diff --git a/docs/playgrounds/cli.html b/docs/playgrounds/cli.html
index 7e85ca1..2f4ef63 100644
--- a/docs/playgrounds/cli.html
+++ b/docs/playgrounds/cli.html
@@ -8,10 +8,10 @@
   <meta name="robots" content="index, follow">
   <link rel="canonical" href="https://pdfnative.dev/playgrounds/cli.html">
   <link rel="alternate" hreflang="en" href="https://pdfnative.dev/playgrounds/cli.html">
-  <link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/playgrounds/cli.html">
+  <link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/playgrounds/cli.html">
   <meta property="og:type" content="website">
   <meta property="og:site_name" content="pdfnative">
-  <meta property="og:locale" content="en_US">
+  <meta property="og:locale" content="en_US">
   <meta property="og:url" content="https://pdfnative.dev/playgrounds/cli.html">
   <meta property="og:title" content="CLI Command Builder — pdfnative-cli playground">
   <meta property="og:description" content="Interactive command-builder for pdfnative-cli — assemble render, sign, inspect, verify, merge, split, extract, annotate and govern invocations with full flag coverage. Live shell preview, copy-to-clipboard, validation. Zero install.">
@@ -114,6 +114,7 @@
     <a href="./extreme-scripts.html">Extreme scripts</a>
     <a href="./all-scripts.html">All 22 scripts</a>
     <a href="./toolkit.html">PDF Toolkit</a>
+    <a href="./inspect.html">Inspect &amp; verify</a>
     <a href="./charts.html">Charts</a>
     <a href="./authoring-plus.html">Authoring+</a>
     <a href="./scale.html">Scale</a>
diff --git a/docs/playgrounds/extreme-scripts.html b/docs/playgrounds/extreme-scripts.html
index eb91684..ccd8f47 100644
--- a/docs/playgrounds/extreme-scripts.html
+++ b/docs/playgrounds/extreme-scripts.html
@@ -75,6 +75,7 @@
     <a href="./extreme-scripts.html" aria-current="page">Extreme scripts</a>
     <a href="./all-scripts.html">All 22 scripts</a>
     <a href="./toolkit.html">PDF Toolkit</a>
+    <a href="./inspect.html">Inspect &amp; verify</a>
     <a href="./charts.html">Charts</a>
     <a href="./authoring-plus.html">Authoring+</a>
     <a href="./scale.html">Scale</a>
@@ -186,7 +187,7 @@ <h2 style="margin-top:24px;">Body paragraphs <span style="font-weight:400;color:
       '',
       'Faces & gestures: 😀 😁 😂 🤣 😊 😍 😎 🤔 👍 👏 🙌 🎉',
       '',
-      'Symbols & objects: ❤️ 🔥 ⭐ ✅ 🚀 💡 📦 🔒 🌍 ☕ 🍕 🎯',
+      'Symbols & objects: ❤️ 🔥 ⭐ ✅ 🚀 💡 🎁 🔒 🌍 ☕ 🍕 🎯',
       '',
       'Mixed with text: Build a PDF 📄 with zero dependencies ⚡ and ship it 🚢.'
     ].join('\n')
diff --git a/docs/playgrounds/index.html b/docs/playgrounds/index.html
index 7798c0c..4dfbbe8 100644
--- a/docs/playgrounds/index.html
+++ b/docs/playgrounds/index.html
@@ -4,22 +4,23 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>Playgrounds — pdfnative</title>
-  <meta name="description" content="Nine zero-install pdfnative playgrounds: extreme scripts, all 22 scripts + emoji, a document toolkit, native charts, authoring+, a 100,000-page scale test, CLI, MCP, and React.">
+  <meta name="description" content="Ten zero-install pdfnative playgrounds: extreme scripts, all 22 scripts + emoji, a document toolkit, an inspect &amp; verify report, native charts, authoring+, a 100,000-page scale test, CLI, MCP, and React.">
   <link rel="canonical" href="https://pdfnative.dev/playgrounds/">
   <link rel="alternate" hreflang="en" href="https://pdfnative.dev/playgrounds/">
   <link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/playgrounds/">
+  <link rel="alternate" type="text/plain" href="../llms.txt" title="llms.txt — machine-readable documentation index">
   <meta property="og:type" content="website">
   <meta property="og:site_name" content="pdfnative">
   <meta property="og:locale" content="en_US">
   <meta property="og:url" content="https://pdfnative.dev/playgrounds/">
   <meta property="og:title" content="Playgrounds — pdfnative">
-  <meta property="og:description" content="Nine interactive playgrounds for pdfnative 1.7.0: extreme-script shaping, an all-22-scripts + colour-emoji showcase, a document toolkit (engine features from v1.4.0 through v1.6.0), native vector charts (new in v1.6.0), an authoring showcase (v1.5.0 features), a 100,000-page scale test, a CLI command builder, an MCP tool explorer, and a declarative React (JSX) renderer. All zero-install, in your browser.">
+  <meta property="og:description" content="Ten interactive playgrounds for pdfnative 1.7.0: extreme-script shaping, an all-22-scripts + colour-emoji showcase, a document toolkit (engine features from v1.4.0 through v1.6.0), an inspect &amp; verify drop-zone that reads a full report from any PDF, native vector charts (v1.6.0, charts v2 in v1.7.0), an authoring showcase (v1.5.0 features), a 100,000-page scale test, a CLI command builder, an MCP tool explorer, and a declarative React (JSX) renderer. All zero-install, in your browser.">
   <meta property="og:image" content="https://pdfnative.dev/assets/og-image.png">
   <meta property="og:image:width" content="1200">
   <meta property="og:image:height" content="630">
   <meta name="twitter:card" content="summary_large_image">
   <meta name="twitter:title" content="Playgrounds — pdfnative">
-  <meta name="twitter:description" content="Nine zero-install playgrounds: extreme scripts, all-22-scripts + emoji, document toolkit, native charts, authoring showcase, 100k-page scale test, CLI builder, MCP explorer, React renderer.">
+  <meta name="twitter:description" content="Ten zero-install playgrounds: extreme scripts, all-22-scripts + emoji, document toolkit, inspect &amp; verify, native charts, authoring showcase, 100k-page scale test, CLI builder, MCP explorer, React renderer.">
   <meta name="twitter:image" content="https://pdfnative.dev/assets/og-image.png">
   <link rel="icon" type="image/svg+xml" href="../favicon.svg">
   <link rel="stylesheet" href="../style.css">
@@ -51,7 +52,7 @@
         "inLanguage": "en",
         "@id": "https://pdfnative.dev/playgrounds/#collection",
         "name": "pdfnative interactive playgrounds",
-        "description": "9 zero-install playgrounds that generate real PDFs in your browser.",
+        "description": "10 zero-install playgrounds that generate and inspect real PDFs in your browser.",
         "url": "https://pdfnative.dev/playgrounds/",
         "isPartOf": {
           "@type": "WebSite",
@@ -60,7 +61,7 @@
         },
         "mainEntity": {
           "@type": "ItemList",
-          "numberOfItems": 9,
+          "numberOfItems": 10,
           "itemListElement": [
             {
               "@type": "ListItem",
@@ -95,24 +96,30 @@
             {
               "@type": "ListItem",
               "position": 6,
+              "name": "Inspect & verify — metadata, PDF/UA, signatures, form fields",
+              "url": "https://pdfnative.dev/playgrounds/inspect.html"
+            },
+            {
+              "@type": "ListItem",
+              "position": 7,
               "name": "MCP tool explorer",
               "url": "https://pdfnative.dev/playgrounds/mcp.html"
             },
             {
               "@type": "ListItem",
-              "position": 7,
+              "position": 8,
               "name": "React (JSX) renderer",
               "url": "https://pdfnative.dev/playgrounds/react.html"
             },
             {
               "@type": "ListItem",
-              "position": 8,
+              "position": 9,
               "name": "Scale — up to 100,000 pages",
               "url": "https://pdfnative.dev/playgrounds/scale.html"
             },
             {
               "@type": "ListItem",
-              "position": 9,
+              "position": 10,
               "name": "PDF toolkit — bookmarks, forms, encryption, extraction",
               "url": "https://pdfnative.dev/playgrounds/toolkit.html"
             }
@@ -171,7 +178,7 @@
   <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; Playgrounds</p>
   <article class="guide-content">
     <h1>Interactive playgrounds</h1>
-    <p>Nine hands-on environments that exercise the entire pdfnative ecosystem in your browser. No install, no API keys, no build step. Pick a card to dive in — every playground includes a switcher at the top so you can hop between them without coming back here.</p>
+    <p>Ten hands-on environments that exercise the entire pdfnative ecosystem in your browser — from generating documents to inspecting the ones you already have. No install, no API keys, no build step. Pick a card to dive in — every playground includes a switcher at the top so you can hop between them without coming back here.</p>
 
     <div class="pg-grid">
       <a class="pg-card" href="./extreme-scripts.html">
@@ -204,12 +211,22 @@ <h3>PDF Toolkit <span class="badge">Library</span> <span class="badge alt">engin
         <div class="pg-cta">Open PDF Toolkit playground →</div>
       </a>
 
+      <a class="pg-card" href="./inspect.html">
+        <div class="pg-icon" aria-hidden="true">🔍</div>
+        <h3>Inspect &amp; verify <span class="badge">Library</span></h3>
+        <p>Drop any PDF and read a full report — metadata, extracted text, PDF/UA structure, a signature inventory, and form fields — built by <code>openPdf</code>, <code>extractText</code>, <code>validatePdfUA</code>, <code>listSignatures</code> and <code>readFormFields</code>, entirely in your browser. Honest limits stated on the page: the PDF/UA check is structural, not an accessibility audit, and the signature card is an inventory, not cryptographic verification.</p>
+        <div class="pg-tags">
+          <span class="pg-tag">Metadata</span><span class="pg-tag">PDF/UA</span><span class="pg-tag">Signatures</span><span class="pg-tag">Form fields</span><span class="pg-tag">Nothing uploaded</span>
+        </div>
+        <div class="pg-cta">Open Inspect &amp; verify playground →</div>
+      </a>
+
       <a class="pg-card" href="./charts.html">
         <div class="pg-icon" aria-hidden="true">📈</div>
-        <h3>Charts <span class="badge">Library</span> <span class="badge alt">1.6.0</span></h3>
-        <p>New in 1.6.0: native <strong>vector charts</strong> — bar, horizontal-bar, line (with markers), pie, and donut — rendered as pure PDF path operators. Multi-series, legends, "nice" axis ticks, negative values, and tagged <code>/Figure</code> alt text. Each preset is a one-click downloadable PDF.</p>
+        <h3>Charts <span class="badge">Library</span> <span class="badge alt">1.6.0 → 1.7.0</span></h3>
+        <p>Native <strong>vector charts</strong> — nine kinds: bar, horizontal-bar, line (with markers), pie, donut (v1.6.0), plus stacked bars, area, and scatter with a secondary axis, log &amp; time scales, and data labels (charts v2, v1.7.0) — rendered as pure PDF path operators. Multi-series, legends, "nice" axis ticks, negative values, and tagged <code>/Figure</code> alt text. Each preset is a one-click downloadable PDF.</p>
         <div class="pg-tags">
-          <span class="pg-tag">Bar</span><span class="pg-tag">Line</span><span class="pg-tag">Pie/Donut</span><span class="pg-tag">Zero-dep</span>
+          <span class="pg-tag">Bar</span><span class="pg-tag">Line</span><span class="pg-tag">Pie/Donut</span><span class="pg-tag">Stacked/Area/Scatter</span><span class="pg-tag">Zero-dep</span>
         </div>
         <div class="pg-cta">Open Charts playground →</div>
       </a>
@@ -247,7 +264,7 @@ <h3>CLI builder <span class="badge alt">CLI</span></h3>
       <a class="pg-card" href="./mcp.html">
         <div class="pg-icon" aria-hidden="true">🤖</div>
         <h3>MCP tool explorer <span class="badge alt">MCP</span></h3>
-        <p>Browse the <strong>pdfnative-mcp</strong> v1.5.0 toolset (24 tools: incl. page-tree <code>merge_pdfs</code>, <code>split_pdf</code>, <code>extract_pages</code>, markup <code>annotate_pdf</code>, the network-free <code>draft_governance_issue</code>, plus <code>validate_pdf</code>, <code>verify_pdf</code>, <code>add_attachment</code>, <code>extract_attachments</code>), copy a ready-to-paste config snippet for Claude Desktop, Cursor, Continue, Zed (or any stdio MCP client), and generate the same PDFs an AI assistant would receive — directly in your browser.</p>
+        <p>Browse the <strong>pdfnative-mcp</strong> v1.6.0 toolset (28 tools: incl. the PAdES ladder <code>sign_pdf</code> / <code>add_ltv</code> / <code>timestamp_pdf</code>, <code>update_metadata</code>, the read-only <code>inspect_layout</code> preview, page-tree <code>merge_pdfs</code> / <code>split_pdf</code> / <code>extract_pages</code>, markup <code>annotate_pdf</code>, the network-free <code>draft_governance_issue</code>), copy a ready-to-paste config snippet for Claude Desktop, Cursor, Continue, Zed (or any MCP client), and generate the same PDFs an AI assistant would receive — directly in your browser.</p>
         <div class="pg-tags">
           <span class="pg-tag">stdio tools</span><span class="pg-tag">Claude</span><span class="pg-tag">Cursor</span><span class="pg-tag">Zed</span><span class="pg-tag">+ any stdio client</span>
         </div>
@@ -286,6 +303,7 @@ <h2>Resources</h2>
       <li><a href="./extreme-scripts.html">Extreme scripts</a></li>
       <li><a href="./all-scripts.html">All 22 scripts</a></li>
       <li><a href="./toolkit.html">PDF Toolkit</a></li>
+      <li><a href="./inspect.html">Inspect &amp; verify</a></li>
       <li><a href="./charts.html">Charts</a></li>
       <li><a href="./authoring-plus.html">Authoring+</a></li>
       <li><a href="./scale.html">Scale</a></li>
diff --git a/docs/playgrounds/inspect.html b/docs/playgrounds/inspect.html
new file mode 100644
index 0000000..cb7697d
--- /dev/null
+++ b/docs/playgrounds/inspect.html
@@ -0,0 +1,635 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Inspect &amp; Verify Playground — pdfnative</title>
+  <meta name="description" content="Drop a PDF and read a full report — metadata, text, PDF/UA structure, signatures, form fields — produced entirely in your browser. Nothing is uploaded.">
+  <meta name="keywords" content="inspect PDF, PDF metadata reader, PDF/UA validator, PDF signature inventory, AcroForm fields, extract PDF text, encrypted PDF, PDF report, browser PDF inspector, pdfnative">
+  <meta name="robots" content="index, follow">
+  <link rel="canonical" href="https://pdfnative.dev/playgrounds/inspect.html">
+  <link rel="alternate" hreflang="en" href="https://pdfnative.dev/playgrounds/inspect.html">
+  <link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/playgrounds/inspect.html">
+  <link rel="alternate" type="text/plain" href="../llms.txt" title="llms.txt — machine-readable documentation index">
+  <meta property="og:type" content="website">
+  <meta property="og:site_name" content="pdfnative">
+  <meta property="og:locale" content="en_US">
+  <meta property="og:url" content="https://pdfnative.dev/playgrounds/inspect.html">
+  <meta property="og:title" content="Inspect &amp; Verify Playground — pdfnative">
+  <meta property="og:description" content="Drop a PDF and read a full report — metadata, text, PDF/UA structure, signature inventory, form fields — produced entirely in your browser. Nothing is uploaded.">
+  <meta property="og:image" content="https://pdfnative.dev/assets/og-image.png">
+  <meta property="og:image:width" content="1200">
+  <meta property="og:image:height" content="630">
+  <meta name="twitter:card" content="summary_large_image">
+  <meta name="twitter:title" content="Inspect &amp; Verify Playground — pdfnative">
+  <meta name="twitter:description" content="Metadata, text, PDF/UA structure, signatures and form fields — read from your PDF entirely in your browser. Nothing is uploaded.">
+  <meta name="twitter:image" content="https://pdfnative.dev/assets/og-image.png">
+  <link rel="icon" type="image/svg+xml" href="../favicon.svg">
+  <link rel="stylesheet" href="../style.css">
+  <link rel="stylesheet" href="../guides/guide.css">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
+  <style>
+    .insp-drop { border: 2px dashed var(--c-border); border-radius: 12px; padding: 28px 24px; text-align: center; background: var(--c-bg-card); margin-top: 24px; transition: border-color 0.15s, background 0.15s; }
+    .insp-drop.dragover { border-color: var(--c-primary); background: var(--c-surface); }
+    .insp-drop p { margin: 0 0 12px; color: var(--c-text-dim); font-size: 14px; }
+    .insp-drop .insp-file-row { display: flex; gap: 12px; justify-content: center; align-items: center; flex-wrap: wrap; }
+    .insp-drop input[type="file"] { font-size: 13px; max-width: 100%; }
+    .insp-pwrow { margin-top: 16px; padding: 14px 16px; border: 1px solid var(--c-border); border-radius: 8px; background: var(--c-surface); }
+    .insp-pwrow label { font-weight: 600; margin-right: 8px; }
+    .insp-pwrow input { padding: 6px 10px; border-radius: 6px; border: 1px solid var(--c-border); font-size: 14px; }
+    .insp-pwrow button { margin-left: 8px; padding: 6px 14px; border-radius: 6px; border: none; background: var(--c-primary); color: #fff; font-weight: 600; cursor: pointer; }
+    .insp-pwrow .insp-pwnote { font-size: 12px; color: var(--c-text-dim); margin: 8px 0 0; }
+    .insp-card { border: 1px solid var(--c-border); border-radius: 10px; background: var(--c-bg-card); padding: 18px 20px 14px; margin-top: 20px; }
+    .insp-card h2 { font-size: 17px; margin: 0 0 10px; }
+    /* dt keys come from the dropped file's /Info — cap the column so a
+       hostile 300-character key cannot blow the grid apart. */
+    .insp-card dl { display: grid; grid-template-columns: minmax(120px, 28ch) 1fr; gap: 4px 16px; font-size: 14px; margin: 0; }
+    .insp-card dt { color: var(--c-text-dim); font-weight: 600; overflow-wrap: anywhere; }
+    .insp-card dd { margin: 0; overflow-wrap: anywhere; }
+    .insp-card ul { font-size: 14px; margin: 8px 0 0; padding-left: 20px; }
+    .insp-card pre { margin-top: 10px; max-height: 280px; overflow: auto; padding: 12px; border-radius: 8px; background: var(--c-code-bg); color: var(--c-code-text); font-size: 12px; line-height: 1.5; white-space: pre-wrap; }
+    .insp-caveat { font-size: 13px; color: var(--c-text-dim); border-left: 3px solid #d97706; padding: 6px 12px; margin: 10px 0 0; background: var(--c-surface); border-radius: 0 6px 6px 0; }
+    .insp-error { font-size: 14px; color: #b91c1c; margin: 0; }
+    [data-theme="dark"] .insp-error { color: #fca5a5; }
+    .insp-status-error   { background: #fee2e2; color: #991b1b; border: 1px solid #fca5a5; }
+    .insp-status-success { background: #d1fae5; color: #065f46; border: 1px solid #6ee7b7; }
+    .insp-status-info    { background: #dbeafe; color: #1e3a8a; border: 1px solid #93c5fd; }
+    [data-theme="dark"] .insp-status-error   { background: #450a0a; color: #fca5a5; border-color: #7f1d1d; }
+    [data-theme="dark"] .insp-status-success { background: #052e16; color: #86efac; border-color: #14532d; }
+    [data-theme="dark"] .insp-status-info    { background: #172554; color: #93c5fd; border-color: #1e3a8a; }
+    .insp-verdict { display: inline-block; font-size: 12px; font-weight: 700; padding: 2px 10px; border-radius: 999px; margin-left: 8px; vertical-align: middle; }
+    .insp-verdict.pass { background: #d1fae5; color: #065f46; }
+    .insp-verdict.fail { background: #fee2e2; color: #991b1b; }
+    .rs-verify { font-size: 13px; color: var(--c-text-dim); margin: 12px 0 0; }
+    .rs-verify a { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 12px; }
+    .insp-meta { font-size: 13px; color: var(--c-text-dim); margin-top: 16px; }
+  </style>
+  <script type="application/ld+json">
+  {
+    "@context": "https://schema.org",
+    "@type": "WebApplication",
+    "inLanguage": "en",
+    "name": "Inspect & Verify Playground",
+    "applicationCategory": "DeveloperApplication",
+    "operatingSystem": "Any (browser-based)",
+    "browserRequirements": "Requires JavaScript and HTML5",
+    "url": "https://pdfnative.dev/playgrounds/inspect.html",
+    "description": "Drop a PDF and read a full report — metadata, text, PDF/UA structure, signatures, form fields — produced entirely in your browser. Nothing is uploaded.",
+    "offers": { "@type": "Offer", "price": "0", "priceCurrency": "USD" },
+    "isPartOf": { "@type": "WebSite", "name": "pdfnative", "url": "https://pdfnative.dev" },
+    "author": { "@type": "Organization", "name": "Nizoka", "url": "https://github.com/Nizoka" }
+  }
+  </script>
+</head>
+<body>
+
+<a class="skip-link" href="#main-content">Skip to main content</a>
+
+<nav class="nav" role="navigation" aria-label="Main navigation">
+  <div class="nav-inner">
+    <a class="nav-brand" href="../">
+      <img src="../assets/logo.svg" alt="" width="28" height="28">
+      pdfnative
+    </a>
+    <button class="nav-hamburger" aria-label="Toggle menu" aria-expanded="false">☰</button>
+    <ul class="nav-links" role="list">
+      <li><a href="../#features">Features</a></li>
+      <li><a href="../#examples">Examples</a></li>
+      <li><a href="../#demo">Demo</a></li>
+      <li><a href="../#mcp">MCP</a></li>
+      <li><a href="../#cli">CLI</a></li>
+      <li><a href="../#react">React</a></li>
+      <li><a href="../guides/">Guides</a></li>
+      <li><a href="./">Playgrounds</a></li>
+      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
+      <li><button class="theme-toggle" aria-label="Toggle dark mode">🌙</button></li>
+    </ul>
+  </div>
+</nav>
+
+<main class="guide-shell" id="main-content" tabindex="-1">
+  <p class="guide-breadcrumb"><a href="../">Home</a> &nbsp;›&nbsp; <a href="./">Playgrounds</a> &nbsp;›&nbsp; Inspect &amp; verify</p>
+  <nav class="playground-switcher" aria-label="Playground switcher">
+    <span class="playground-switcher-label">Playgrounds:</span>
+    <a href="./extreme-scripts.html">Extreme scripts</a>
+    <a href="./all-scripts.html">All 22 scripts</a>
+    <a href="./toolkit.html">PDF Toolkit</a>
+    <a href="./inspect.html" aria-current="page">Inspect &amp; verify</a>
+    <a href="./charts.html">Charts</a>
+    <a href="./authoring-plus.html">Authoring+</a>
+    <a href="./scale.html">Scale</a>
+    <a href="./cli.html">CLI builder</a>
+    <a href="./mcp.html">MCP explorer</a>
+    <a href="./react.html">React renderer</a>
+    <a href="./" style="margin-left:auto;">All →</a>
+  </nav>
+  <article class="guide-content">
+    <h1>Inspect &amp; verify — drop a PDF, nothing leaves your machine</h1>
+    <p>Drop any PDF below and read a full report — document metadata, extracted text, PDF/UA structure, a signature inventory, and form fields — produced by the same pdfnative reader APIs that run in Node, Deno and Bun. Open your browser's Network panel before dropping a file: the only requests this page ever makes happen while it loads — its stylesheets, the Prism highlighter, and the pdfnative engine from the CDN — before you drop anything. The file is read with the standard FileReader API and never leaves this tab. Nothing is stored either: reload the page and the report is gone.</p>
+    <p style="font-size:14px;color:var(--c-text-dim);">In the spirit of the <a href="../responsibility.html">responsibility page</a>, every card below links the source file in the repository that produced it — the report is only as trustworthy as the code you can read.</p>
+
+    <p id="loader-status" role="status" aria-live="polite" style="font-size:13px;color:var(--c-text-dim);">Loading <code>pdfnative</code> from esm.sh… this happens once, at page load.</p>
+
+    <div id="dropzone" class="insp-drop">
+      <p><strong>Drop a PDF anywhere in this box</strong> — or pick one:</p>
+      <div class="insp-file-row">
+        <label for="file-input"><strong>Choose a PDF file</strong></label>
+        <input type="file" id="file-input" accept="application/pdf">
+        <span aria-hidden="true" style="color:var(--c-text-dim);">·</span>
+        <button id="sample-btn" class="btn btn-primary" type="button" style="padding:8px 18px;" disabled>Try a generated sample</button>
+      </div>
+      <p style="margin:12px 0 0;">The sample is a small two-page tagged document with form fields, built in this tab by <code>buildDocumentPDFBytes()</code> — so the page can demonstrate itself without needing a file of yours.</p>
+    </div>
+
+    <div id="password-row" class="insp-pwrow" hidden>
+      <label for="pdf-password">Password</label>
+      <input type="password" id="pdf-password" autocomplete="off">
+      <button id="password-apply" type="button">Unlock and inspect</button>
+      <p class="insp-pwnote">This document is encrypted. The password is handed to <code>openPdf()</code> in this tab only — it is never stored and never sent anywhere.</p>
+    </div>
+
+    <div id="status" role="status" aria-live="polite" style="display:none;padding:10px 14px;border-radius:6px;margin:16px 0 0;font-size:14px;"></div>
+    <p id="file-meta" class="insp-meta" hidden></p>
+
+    <div id="report" hidden>
+      <section class="insp-card" aria-labelledby="h-overview">
+        <h2 id="h-overview">Overview</h2>
+        <div id="overview-body"></div>
+        <p class="rs-verify">Read the source: <a href="https://github.com/Nizoka/pdfnative/blob/main/src/parser/pdf-reader.ts" target="_blank" rel="noopener">src/parser/pdf-reader.ts</a> · <a href="https://github.com/Nizoka/pdfnative/blob/main/src/parser/pdf-xref-parser.ts" target="_blank" rel="noopener">src/parser/pdf-xref-parser.ts</a></p>
+      </section>
+
+      <section class="insp-card" aria-labelledby="h-text">
+        <h2 id="h-text">Text</h2>
+        <div id="text-body"></div>
+        <p class="rs-verify">Read the source: <a href="https://github.com/Nizoka/pdfnative/blob/main/src/parser/pdf-text-extract.ts" target="_blank" rel="noopener">src/parser/pdf-text-extract.ts</a></p>
+      </section>
+
+      <section class="insp-card" aria-labelledby="h-ua">
+        <h2 id="h-ua">PDF/UA structure <span id="ua-verdict"></span></h2>
+        <div id="ua-body"></div>
+        <p class="insp-caveat">Structural checks only (ISO 14289-1) — a passing result is not an accessibility audit. Whether the reading order makes sense or the alt text is meaningful remains the author's judgement; no validator substitutes for it.</p>
+        <p class="rs-verify">Read the source: <a href="https://github.com/Nizoka/pdfnative/blob/main/src/parser/pdf-ua-validator.ts" target="_blank" rel="noopener">src/parser/pdf-ua-validator.ts</a></p>
+      </section>
+
+      <section class="insp-card" aria-labelledby="h-sigs">
+        <h2 id="h-sigs">Signatures</h2>
+        <div id="sigs-body"></div>
+        <p class="insp-caveat">This is an inventory, not cryptographic verification — nothing here checks the CMS signature, the certificate chain or the document digest. Use <code>pdfnative-cli verify</code> or the <code>verify_pdf</code> MCP tool for that.</p>
+        <p class="rs-verify">Read the source: <a href="https://github.com/Nizoka/pdfnative/blob/main/src/core/pdf-sig-utils.ts" target="_blank" rel="noopener">src/core/pdf-sig-utils.ts</a></p>
+      </section>
+
+      <section class="insp-card" aria-labelledby="h-forms">
+        <h2 id="h-forms">Form fields</h2>
+        <div id="forms-body"></div>
+        <p class="rs-verify">Read the source: <a href="https://github.com/Nizoka/pdfnative/blob/main/src/core/pdf-form-fill.ts" target="_blank" rel="noopener">src/core/pdf-form-fill.ts</a></p>
+      </section>
+    </div>
+  </article>
+</main>
+
+<footer class="footer">
+  <div class="footer-inner">
+    <span>MIT License · © 2026 Nizoka</span>
+    <ul class="footer-links" role="list">
+      <li><a href="https://github.com/Nizoka/pdfnative" target="_blank" rel="noopener">GitHub</a></li>
+      <li><a href="../guides/">All guides</a></li>
+      <li><a href="../responsibility.html">Responsibility</a></li>
+    </ul>
+  </div>
+</footer>
+
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/prism.min.js" integrity="sha384-BGaNxfftg+9+TtC098wxawPFVEUpKYvaiCgbB0iqAMjK/4jDdmUY+oGxrPNvnXEf" crossorigin="anonymous" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-json.min.js" integrity="sha384-RhrmFFMb0ZCHImjFMpR/UE3VEtIVTCtNrtKQqXCzqXZNJala02N3UbVhi+qzw3CY" crossorigin="anonymous" defer></script>
+<script type="module">
+const $ = (id) => document.getElementById(id);
+const statusBox = $('status');
+
+function setStatus(msg, kind) {
+  statusBox.style.display = 'block';
+  statusBox.textContent = msg;
+  // Theme-aware banners via classes (styles in the page <style> block).
+  statusBox.className = 'insp-status insp-status-' + (kind === 'error' ? 'error' : kind === 'success' ? 'success' : 'info');
+}
+
+// ── DOM helpers — every file-derived string goes through textContent, never innerHTML ──
+function el(tag, cls, text) {
+  const n = document.createElement(tag);
+  if (cls) n.className = cls;
+  if (text !== undefined) n.textContent = text;
+  return n;
+}
+function kv(dl, key, value) {
+  dl.appendChild(el('dt', '', key));
+  dl.appendChild(el('dd', '', value));
+}
+let sectionFailures = 0; // reset per inspection; feeds the honest final status
+function sectionError(bodyId, err) {
+  sectionFailures++;
+  const p = el('p', 'insp-error', 'Could not run on this file: ' + (err && err.message ? err.message : String(err)));
+  $(bodyId).replaceChildren(p);
+}
+function rawJsonDetails(obj) {
+  const details = document.createElement('details');
+  details.appendChild(el('summary', '', 'Raw JSON'));
+  const pre = document.createElement('pre');
+  const code = el('code', 'language-json', JSON.stringify(obj, (k, v) => {
+    if (v instanceof Uint8Array) return '<' + v.length + ' bytes>';
+    if (v instanceof Map) return Object.fromEntries(v);
+    return v;
+  }, 2));
+  pre.appendChild(code);
+  details.appendChild(pre);
+  details.addEventListener('toggle', () => { if (details.open && window.Prism) window.Prism.highlightElement(code); }, { once: true });
+  return details;
+}
+
+// PDF text strings are either PDFDocEncoding (close to Latin-1) or UTF-16BE
+// with a FE FF byte-order mark. The parser hands both over as byte strings.
+function decodePdfText(s) {
+  if (typeof s !== 'string') return String(s);
+  if (s.length >= 2 && s.charCodeAt(0) === 0xFE && s.charCodeAt(1) === 0xFF) {
+    let out = '';
+    for (let i = 2; i + 1 < s.length; i += 2) {
+      out += String.fromCharCode((s.charCodeAt(i) << 8) | s.charCodeAt(i + 1));
+    }
+    return out;
+  }
+  return s;
+}
+function displayValue(mod, reader, raw) {
+  const v = reader.resolveValue(raw);
+  if (v === null || v === undefined) return '';
+  if (typeof v === 'string') return decodePdfText(v);
+  if (typeof v === 'number' || typeof v === 'boolean') return String(v);
+  if (typeof v === 'object' && v.type === 'name') return '/' + v.value;
+  return '(non-scalar value)';
+}
+
+// ── pdfnative loader — eager, at page load, so no request follows a drop ──
+const CDN_URLS = ['https://esm.sh/pdfnative@1.7.0', 'https://unpkg.com/pdfnative@1.7.0?module'];
+let pdfnativeMod = null;
+let loadErr = null;
+
+(async () => {
+  for (const url of CDN_URLS) {
+    try {
+      const m = await import(url);
+      const mod = m.buildDocumentPDFBytes ? m : (m.default && m.default.buildDocumentPDFBytes ? m.default : m);
+      if (mod && typeof mod.buildDocumentPDFBytes === 'function') { pdfnativeMod = mod; break; }
+    } catch (e) { loadErr = e; }
+  }
+  const ls = $('loader-status');
+  if (pdfnativeMod) {
+    ls.textContent = 'pdfnative loaded — drop a PDF or try the generated sample. No further network request will be made.';
+    ls.style.color = 'var(--c-success)';
+    $('sample-btn').disabled = false;
+  } else {
+    ls.textContent = 'Failed to load pdfnative from CDN: ' + (loadErr && loadErr.message ? loadErr.message : 'unknown error');
+    ls.style.color = '#b91c1c';
+  }
+})();
+
+// ── Report sections — each runs independently: a PDF may fail one reader and pass another ──
+
+function renderOverview(mod, bytes, password) {
+  const body = $('overview-body');
+  body.replaceChildren();
+  const reader = mod.openPdf(bytes, password !== undefined ? { password } : undefined);
+
+  const dl = document.createElement('dl');
+  const head = new TextDecoder('latin1').decode(bytes.subarray(0, 1024));
+  const headerMatch = /%PDF-(\d+\.\d+)/.exec(head);
+  let version = headerMatch ? headerMatch[1] : '(no %PDF header found)';
+  try {
+    const catVersion = reader.resolveValue(reader.getCatalog().get('Version'));
+    if (catVersion && typeof catVersion === 'object' && catVersion.type === 'name') {
+      version += ' (raised to ' + catVersion.value + ' by the catalog /Version entry)';
+    }
+  } catch (e) { /* catalogue unreadable — the header value stands */ }
+  kv(dl, 'PDF version', version);
+  kv(dl, 'Pages', String(reader.pageCount));
+  kv(dl, 'File size', (bytes.length / 1024).toFixed(1) + ' KB (' + bytes.length + ' bytes)');
+
+  if (reader.encryption) {
+    kv(dl, 'Encryption', reader.encryption.algorithm + ' · security handler revision ' + reader.encryption.revision + ' · opened as ' + reader.encryption.authenticatedAs);
+  } else {
+    kv(dl, 'Encryption', 'Not encrypted');
+  }
+
+  try {
+    kv(dl, 'startxref', 'byte offset ' + mod.findStartxref(bytes));
+  } catch (e) {
+    kv(dl, 'startxref', 'not found: ' + (e && e.message ? e.message : e));
+  }
+  kv(dl, 'Xref entries', String(reader.xref.entries.size) + ' objects');
+
+  const info = reader.getInfo();
+  const infoOut = {};
+  if (info) {
+    for (const [key, raw] of info) {
+      const value = displayValue(mod, reader, raw);
+      if (value !== '') { kv(dl, '/' + key, value); infoOut[key] = value; }
+    }
+  } else {
+    kv(dl, '/Info', 'No document information dictionary');
+  }
+  body.appendChild(dl);
+  body.appendChild(rawJsonDetails({
+    version, pageCount: reader.pageCount, bytes: bytes.length,
+    encryption: reader.encryption, xrefEntries: reader.xref.entries.size, info: infoOut,
+  }));
+  return reader.encryption;
+}
+
+function renderText(mod, bytes, password) {
+  const body = $('text-body');
+  body.replaceChildren();
+  const opts = { includeRuns: true };
+  if (password !== undefined) opts.password = password;
+  const pages = mod.extractText(bytes, opts);
+  let totalChars = 0, runCount = 0;
+  for (const page of pages) {
+    totalChars += page.text.length;
+    runCount += (page.runs ? page.runs.length : 0);
+  }
+  const dl = document.createElement('dl');
+  kv(dl, 'Pages read', String(pages.length));
+  kv(dl, 'Characters', String(totalChars) + ' across all pages');
+  kv(dl, 'Positioned runs', String(runCount) + ' (includeRuns: true)');
+  body.appendChild(dl);
+  if (pages.length > 0 && pages[0].text.trim() !== '') {
+    const preview = pages[0].text.length > 1200 ? pages[0].text.slice(0, 1200) + '… (truncated)' : pages[0].text;
+    body.appendChild(el('p', '', 'First page, reading order:'));
+    const pre = document.createElement('pre');
+    pre.textContent = preview;
+    body.appendChild(pre);
+  } else {
+    body.appendChild(el('p', '', 'No text on the first page — the document may be image-only, or its text may live on later pages.'));
+  }
+}
+
+function renderUA(mod, bytes, encrypted) {
+  const body = $('ua-body');
+  const verdict = $('ua-verdict');
+  body.replaceChildren();
+  verdict.replaceChildren();
+  const res = mod.validatePdfUA(bytes);
+  const badge = el('span', 'insp-verdict ' + (res.valid ? 'pass' : 'fail'), res.valid ? 'structurally valid' : 'not valid');
+  verdict.appendChild(badge);
+  if (encrypted) {
+    body.appendChild(el('p', '', 'Note: validatePdfUA() opens the document without a password. On an encrypted file that needs one, the result below reflects that failure, not the document structure.'));
+  }
+  if (res.errors.length === 0 && res.warnings.length === 0) {
+    body.appendChild(el('p', '', 'No structural errors and no warnings: MarkInfo, StructTreeRoot, ParentTree, /Lang and per-page MCID uniqueness all check out.'));
+  }
+  if (res.errors.length > 0) {
+    body.appendChild(el('p', '', String(res.errors.length) + ' blocking error(s):'));
+    const ul = document.createElement('ul');
+    for (const err of res.errors) ul.appendChild(el('li', '', err));
+    body.appendChild(ul);
+  }
+  if (res.warnings.length > 0) {
+    body.appendChild(el('p', '', String(res.warnings.length) + ' warning(s):'));
+    const ul = document.createElement('ul');
+    for (const w of res.warnings) ul.appendChild(el('li', '', w));
+    body.appendChild(ul);
+  }
+  body.appendChild(rawJsonDetails(res));
+}
+
+function renderSignatures(mod, bytes) {
+  const body = $('sigs-body');
+  body.replaceChildren();
+  const sigs = mod.listSignatures(bytes);
+  if (sigs.length === 0) {
+    body.appendChild(el('p', '', 'No signature fields — no signed signatures, no document timestamps, no unsigned placeholders.'));
+    return;
+  }
+  body.appendChild(el('p', '', String(sigs.length) + ' signature field(s), in AcroForm order:'));
+  const ul = document.createElement('ul');
+  for (const s of sigs) {
+    const kind = s.isPlaceholder ? 'unsigned placeholder'
+      : s.isDocTimestamp ? 'document timestamp'
+      : 'signed signature';
+    const parts = [
+      (s.fieldName ? s.fieldName : '(unnamed field)'),
+      kind,
+      'subFilter: ' + (s.subFilter !== '' ? s.subFilter : '(none)'),
+      'ByteRange: ' + (s.byteRange.length > 0 ? '[' + s.byteRange.join(', ') + ']' : 'empty'),
+      '/Contents: ' + s.contents.length + ' bytes',
+    ];
+    ul.appendChild(el('li', '', parts.join(' · ')));
+  }
+  body.appendChild(ul);
+  body.appendChild(rawJsonDetails(sigs));
+}
+
+function renderForms(mod, bytes, password) {
+  const body = $('forms-body');
+  body.replaceChildren();
+  const opts = password !== undefined ? { password } : undefined;
+  const fields = mod.readFormFields(bytes, opts);
+  if (fields.length === 0) {
+    body.appendChild(el('p', '', 'No AcroForm fields in this document.'));
+    return;
+  }
+  body.appendChild(el('p', '', String(fields.length) + ' field(s):'));
+  const ul = document.createElement('ul');
+  for (const f of fields) {
+    const flags = [];
+    if (f.readOnly) flags.push('read-only');
+    if (f.required) flags.push('required');
+    if (f.multiline) flags.push('multiline');
+    let valueText;
+    if (f.value === null) valueText = 'empty';
+    else if (Array.isArray(f.value)) valueText = f.value.join(', ');
+    else valueText = String(f.value);
+    ul.appendChild(el('li', '', f.name + ' — ' + f.type + (flags.length ? ' (' + flags.join(', ') + ')' : '') + ' · value: ' + valueText));
+  }
+  body.appendChild(ul);
+  body.appendChild(rawJsonDetails(fields));
+}
+
+// ── Orchestration ──
+let current = null; // { bytes: Uint8Array, name: string } — held in memory only, never persisted
+
+function isPasswordError(mod, err) {
+  return (mod.PdfPasswordError && err instanceof mod.PdfPasswordError) || (err && err.name === 'PdfPasswordError');
+}
+
+async function inspect(password) {
+  const mod = pdfnativeMod;
+  if (!mod || !current) return;
+  const t0 = performance.now();
+  sectionFailures = 0;
+  // The five readers run synchronously on the main thread; yield between
+  // cards so a large file does not freeze the tab wholesale.
+  const tick = () => new Promise((r) => setTimeout(r, 0));
+
+  // Overview drives the password flow: a wrong or missing password surfaces here first.
+  let encryption = null;
+  try {
+    encryption = renderOverview(mod, current.bytes, password);
+    $('password-row').hidden = true;
+  } catch (err) {
+    if (isPasswordError(mod, err)) {
+      $('report').hidden = true;
+      $('password-row').hidden = false;
+      $('pdf-password').focus();
+      setStatus(password === undefined
+        ? 'This document is encrypted — enter its password to inspect it.'
+        : 'Wrong password — ' + (err.message || 'the document did not open.'), 'error');
+      return;
+    }
+    sectionError('overview-body', err);
+  }
+
+  const encryptedWithPassword = encryption !== null && password !== undefined && password !== '';
+
+  await tick();
+  try { renderText(mod, current.bytes, password); }
+  catch (err) { sectionError('text-body', err); }
+
+  await tick();
+  try { renderUA(mod, current.bytes, encryptedWithPassword); }
+  catch (err) { $('ua-verdict').replaceChildren(); sectionError('ua-body', err); }
+
+  await tick();
+  try { renderSignatures(mod, current.bytes); }
+  catch (err) {
+    if (isPasswordError(mod, err)) {
+      $('sigs-body').replaceChildren(el('p', 'insp-error',
+        'listSignatures() takes no password option, so it cannot open this encrypted file. That is a limit of the current API, not a property of your document — pdfnative-cli inspect reads it with --password.'));
+    } else { sectionError('sigs-body', err); }
+  }
+
+  await tick();
+  try { renderForms(mod, current.bytes, password); }
+  catch (err) { sectionError('forms-body', err); }
+
+  $('report').hidden = false;
+  const ms = (performance.now() - t0).toFixed(0);
+  const meta = $('file-meta');
+  meta.hidden = false;
+  meta.textContent = current.name + ' · ' + (current.bytes.length / 1024).toFixed(1) + ' KB · inspected in ' + ms + ' ms, entirely in this tab.';
+  // Honest tally: a green "ready" banner over five failed cards would lie.
+  if (sectionFailures === 0) {
+    setStatus('Report ready.', 'success');
+  } else {
+    setStatus('Report ready — ' + sectionFailures + ' of 5 sections could not run on this file (details in the cards below).', 'error');
+  }
+}
+
+function readFileBytes(file) {
+  return new Promise((resolve, reject) => {
+    const fr = new FileReader();
+    fr.onload = () => resolve(new Uint8Array(fr.result));
+    fr.onerror = () => reject(fr.error || new Error('File read failed'));
+    fr.readAsArrayBuffer(file);
+  });
+}
+
+async function acceptFile(file) {
+  if (!file) return;
+  if (!pdfnativeMod) {
+    setStatus('The engine has not finished loading yet — try again in a moment.', 'error');
+    return;
+  }
+  try {
+    setStatus('Reading ' + file.name + ' with FileReader…', 'info');
+    const bytes = await readFileBytes(file);
+    if (bytes.length > 25 * 1024 * 1024) {
+      setStatus('This file is ' + (bytes.length / 1024 / 1024).toFixed(0) +
+        ' MB — the five readers run in this tab and may be slow on a file this large. Proceeding…', 'info');
+    }
+    current = { bytes, name: file.name };
+    $('pdf-password').value = '';
+    inspect(undefined);
+  } catch (err) {
+    setStatus('Error: ' + (err && err.message ? err.message : err), 'error');
+    console.error(err);
+  }
+}
+
+// ── Drop zone: drag & drop plus a plain, keyboard-accessible file input ──
+// Document-level guards: a PDF dropped a few pixels outside the zone must
+// not navigate the tab away from the page.
+document.addEventListener('dragover', (e) => e.preventDefault());
+document.addEventListener('drop', (e) => e.preventDefault());
+const dropzone = $('dropzone');
+let dragDepth = 0; // dragleave fires when crossing child elements — count entries
+dropzone.addEventListener('dragenter', () => { dragDepth++; dropzone.classList.add('dragover'); });
+dropzone.addEventListener('dragover', (e) => { e.preventDefault(); dropzone.classList.add('dragover'); });
+dropzone.addEventListener('dragleave', () => { if (--dragDepth <= 0) { dragDepth = 0; dropzone.classList.remove('dragover'); } });
+dropzone.addEventListener('drop', (e) => {
+  e.preventDefault();
+  dragDepth = 0;
+  dropzone.classList.remove('dragover');
+  const file = e.dataTransfer && e.dataTransfer.files ? e.dataTransfer.files[0] : null;
+  acceptFile(file);
+});
+$('file-input').addEventListener('change', (e) => acceptFile(e.target.files[0]));
+
+$('password-apply').addEventListener('click', () => inspect($('pdf-password').value));
+$('pdf-password').addEventListener('keydown', (e) => { if (e.key === 'Enter') inspect($('pdf-password').value); });
+
+// ── Generated sample: the page demonstrates itself without a visitor's file ──
+$('sample-btn').addEventListener('click', () => {
+  const mod = pdfnativeMod;
+  if (!mod) return;
+  try {
+    setStatus('Building the sample document in this tab…', 'info');
+    const bytes = mod.buildDocumentPDFBytes({
+      title: 'Inspection sample',
+      metadata: { author: 'pdfnative playground', subject: 'A document generated in your browser for inspection' },
+      blocks: [
+        { type: 'heading', text: 'Inspection sample', level: 1 },
+        { type: 'paragraph', text: 'This two-page document was generated in your browser a moment ago. It is tagged, so the PDF/UA card has structure to check, and it carries two form fields for the form-field card. It has no signature fields — the signatures card should say exactly that. One honest note: its PDF/A-2b claim is deliberately NOT conformant — the text uses unembedded base-14 Helvetica and form fields sit under the claim, the two documented limitations the engine’s diagnostics guard against. Run it through veraPDF to see both; the PDF/A guide explains the conformant recipe (embedFonts, no form fields under a claim).' },
+        { type: 'list', style: 'bullet', items: [
+          'Overview reads the header, page tree, xref and /Info dictionary.',
+          'Text extraction returns reading-order text plus positioned runs.',
+          'Nothing about this file exists outside this tab.',
+        ]},
+        { type: 'pageBreak' },
+        { type: 'heading', text: 'Form fields', level: 1 },
+        { type: 'formField', fieldType: 'text', name: 'fullName', label: 'Full name' },
+        { type: 'formField', fieldType: 'checkbox', name: 'subscribe', label: 'Subscribe to the newsletter' },
+      ],
+    }, { tagged: true });
+    current = { bytes, name: 'generated-sample.pdf' };
+    $('pdf-password').value = '';
+    inspect(undefined);
+  } catch (err) {
+    setStatus('Error: ' + (err && err.message ? err.message : err), 'error');
+    console.error(err);
+  }
+});
+
+// ── Theme + hamburger parity with the rest of the site ──
+// Same semantics as app.js: the attribute is always explicit ('light' or
+// 'dark') and localStorage stores the same value — removing the attribute
+// would fall back to prefers-color-scheme, so "light" on a dark-OS machine
+// would do nothing, and an empty stored value breaks every other page.
+const themeBtn = document.querySelector('.theme-toggle');
+if (themeBtn) {
+  const stored = localStorage.getItem('theme');
+  const preferred = stored || (matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light');
+  const applyTheme = (theme) => {
+    document.documentElement.setAttribute('data-theme', theme);
+    localStorage.setItem('theme', theme);
+    themeBtn.textContent = theme === 'dark' ? '☀️' : '🌙';
+  };
+  applyTheme(preferred);
+  themeBtn.addEventListener('click', () => {
+    applyTheme(document.documentElement.getAttribute('data-theme') === 'dark' ? 'light' : 'dark');
+  });
+}
+const hb = document.querySelector('.nav-hamburger');
+if (hb) hb.addEventListener('click', () => {
+  const nav = document.querySelector('.nav-links');
+  if (nav) nav.classList.toggle('open');
+  hb.setAttribute('aria-expanded', String(nav && nav.classList.contains('open')));
+});
+</script>
+</body>
+</html>
diff --git a/docs/playgrounds/mcp.html b/docs/playgrounds/mcp.html
index cb068ef..4b1f633 100644
--- a/docs/playgrounds/mcp.html
+++ b/docs/playgrounds/mcp.html
@@ -4,8 +4,8 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>MCP Tool Explorer — pdfnative</title>
-  <meta name="description" content="Browse all 24 pdfnative-mcp tools, read example prompts and JSON payloads, and generate the exact PDFs an AI assistant receives — in your browser.">
-  <meta name="keywords" content="pdfnative-mcp, Model Context Protocol, MCP server, AI PDF generation, Claude Desktop, Cursor, PDF tools, generate PDF, merge PDF, split PDF, PDF/A, digital signature">
+  <meta name="description" content="Browse all 28 pdfnative-mcp tools, read example prompts and JSON payloads, and generate the exact PDFs an AI assistant receives — in your browser.">
+  <meta name="keywords" content="pdfnative-mcp, Model Context Protocol, MCP server, AI PDF generation, Claude Desktop, Cursor, PDF tools, generate PDF, merge PDF, split PDF, PDF/A, digital signature, PAdES, LTV, document timestamp, update PDF metadata, layout preview">
   <meta name="robots" content="index, follow">
   <link rel="canonical" href="https://pdfnative.dev/playgrounds/mcp.html">
   <link rel="alternate" hreflang="en" href="https://pdfnative.dev/playgrounds/mcp.html">
@@ -14,24 +14,24 @@
   <meta property="og:site_name" content="pdfnative">
   <meta property="og:locale" content="en_US">
   <meta property="og:url" content="https://pdfnative.dev/playgrounds/mcp.html">
-  <meta property="og:title" content="pdfnative-mcp Tool Explorer — 24 AI PDF tools">
-  <meta property="og:description" content="Browse the 24 pdfnative-mcp tool schemas, see example prompts, and generate the exact PDFs an AI assistant receives — directly in your browser. No keys, no install.">
+  <meta property="og:title" content="pdfnative-mcp Tool Explorer — 28 AI PDF tools">
+  <meta property="og:description" content="Browse the 28 pdfnative-mcp tool schemas, see example prompts, and generate the exact PDFs an AI assistant receives — directly in your browser. No keys, no install.">
   <meta property="og:image" content="https://pdfnative.dev/assets/og-image.png">
   <meta property="og:image:width" content="1200">
   <meta property="og:image:height" content="630">
   <meta name="twitter:card" content="summary_large_image">
-  <meta name="twitter:title" content="pdfnative-mcp Tool Explorer — 24 AI PDF tools">
-  <meta name="twitter:description" content="Browse the 24 pdfnative-mcp tool schemas, see example prompts, and generate real PDFs in your browser. No keys, no install, no LLM cost.">
+  <meta name="twitter:title" content="pdfnative-mcp Tool Explorer — 28 AI PDF tools">
+  <meta name="twitter:description" content="Browse the 28 pdfnative-mcp tool schemas, see example prompts, and generate real PDFs in your browser. No keys, no install, no LLM cost.">
   <meta name="twitter:image" content="https://pdfnative.dev/assets/og-image.png">
   <link rel="icon" type="image/svg+xml" href="../favicon.svg">
   <link rel="stylesheet" href="../style.css">
   <link rel="stylesheet" href="../guides/guide.css">
   <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" integrity="sha384-wFjoQjtV1y5jVHbt0p35Ui8aV8GVpEZkyF99OXWqP/eNJDU93D3Ugxkoyh6Y2I4A" crossorigin="anonymous">
   <style>
-    .mcp-cards { display: grid; grid-template-columns: repeat(auto-fit, minmax(360px, 1fr)); gap: 18px; margin-top: 24px; }
+    .mcp-cards { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(360px, 100%), 1fr)); gap: 18px; margin-top: 24px; }
     .mcp-card { border: 1px solid var(--c-border); border-radius: 10px; padding: 18px 20px 16px; background: var(--c-bg-card); display: flex; flex-direction: column; gap: 10px; }
-    .mcp-card h3 { font-size: 16px; font-weight: 700; margin: 0; color: var(--c-text); display: flex; align-items: center; gap: 8px; }
-    .mcp-card h3 code { background: var(--c-surface); padding: 2px 8px; border-radius: 4px; font-size: 13px; color: var(--c-primary); }
+    .mcp-card h3 { font-size: 16px; font-weight: 700; margin: 0; color: var(--c-text); display: flex; flex-wrap: wrap; align-items: center; gap: 8px; }
+    .mcp-card h3 code { background: var(--c-surface); padding: 2px 8px; border-radius: 4px; font-size: 13px; color: var(--c-primary); overflow-wrap: anywhere; }
     .mcp-card .purpose { font-size: 13px; color: var(--c-text-dim); line-height: 1.5; margin: 0; }
     .mcp-card details { font-size: 13px; }
     .mcp-card details summary { cursor: pointer; font-weight: 600; color: var(--c-text); padding: 4px 0; }
@@ -66,14 +66,14 @@
     "applicationCategory": "DeveloperApplication",
     "operatingSystem": "Any (browser-based)",
     "url": "https://pdfnative.dev/playgrounds/mcp.html",
-    "description": "Interactive explorer for the 24 pdfnative-mcp tools. Browse JSON schemas, see example prompts, and generate the exact PDFs an AI assistant receives — directly in the browser.",
+    "description": "Interactive explorer for the 28 pdfnative-mcp tools. Browse JSON schemas, see example prompts, and generate the exact PDFs an AI assistant receives — directly in the browser.",
     "offers": { "@type": "Offer", "price": "0", "priceCurrency": "USD" },
     "isPartOf": { "@type": "WebSite", "name": "pdfnative", "url": "https://pdfnative.dev" },
     "about": {
       "@type": "SoftwareApplication",
       "inLanguage": "en",
       "name": "pdfnative-mcp",
-      "softwareVersion": "1.5.0",
+      "softwareVersion": "1.6.0",
       "applicationCategory": "DeveloperApplication",
       "operatingSystem": "Node.js",
       "url": "https://github.com/Nizoka/pdfnative-mcp"
@@ -117,6 +117,7 @@
     <a href="./extreme-scripts.html">Extreme scripts</a>
     <a href="./all-scripts.html">All 22 scripts</a>
     <a href="./toolkit.html">PDF Toolkit</a>
+    <a href="./inspect.html">Inspect &amp; verify</a>
     <a href="./charts.html">Charts</a>
     <a href="./authoring-plus.html">Authoring+</a>
     <a href="./scale.html">Scale</a>
@@ -127,7 +128,7 @@
   </nav>
   <article class="guide-content">
     <h1>pdfnative-mcp tool explorer</h1>
-    <p>The tools an AI assistant gets when you wire <a href="https://github.com/Nizoka/pdfnative-mcp">pdfnative-mcp</a> into Claude Desktop, Cursor, Continue, Zed, or any other stdio MCP client (Cline, Windsurf, Goose, Gemini CLI…). The server exposes <strong>24 tools</strong> — including the v1.4.0 markup <code>annotate_pdf</code> and network-free <code>draft_governance_issue</code>, the v1.3.0 page-tree trio <code>merge_pdfs</code> / <code>split_pdf</code> / <code>extract_pages</code>, plus <code>validate_pdf</code>, <code>inspect_pdf</code>, <code>verify_pdf</code>, <code>add_attachment</code> / <code>extract_attachments</code> (Factur-X / ZUGFeRD PDF/A-3), and <code>extract_text</code> — a <code>pdfA</code> flag on every document tool, multi-script <code>lang</code> on <code>add_international_text</code>, token-frugal read modes (<code>verbosity</code> / <code>fields</code>), and a per-tool <code>_meta.apiVersion</code> stability contract. Each card below shows a real example prompt, the pdfnative library payload this browser demo executes (the MCP tool schemas differ — see the <a href="../guides/mcp.html">MCP guide</a> for the exact schemas), and a <strong>Generate PDF</strong> button that produces the very PDF the AI assistant would receive — running the underlying <a href="https://www.npmjs.com/package/pdfnative">pdfnative</a> library directly in your browser. No API keys, no install, no LLM cost.</p>
+    <p>The tools an AI assistant gets when you wire <a href="https://github.com/Nizoka/pdfnative-mcp">pdfnative-mcp</a> into Claude Desktop, Cursor, Continue, Zed, or any other MCP client (Cline, Windsurf, Goose, Gemini CLI…). The server exposes <strong>28 tools</strong> — including the v1.6.0 PAdES ladder <code>add_ltv</code> / <code>timestamp_pdf</code> (with RFC 3161 timestamps on <code>sign_pdf</code>), <code>update_metadata</code>, the read-only <code>inspect_layout</code> pagination preview, all 13 block kinds in <code>generate_basic_pdf</code>, print production and charts v2, the v1.5.0 <code>add_chart</code> / form / encryption tools, the v1.4.0 markup <code>annotate_pdf</code> and network-free <code>draft_governance_issue</code>, and the v1.3.0 page-tree trio <code>merge_pdfs</code> / <code>split_pdf</code> / <code>extract_pages</code> — a <code>pdfA</code> flag on every document tool, multi-script <code>lang</code> on <code>add_international_text</code>, token-frugal read modes (<code>verbosity</code> / <code>fields</code>), and a per-tool <code>_meta.apiVersion</code> stability contract. Each card below shows a real example prompt, the pdfnative library payload this browser demo executes (the MCP tool schemas differ — see the <a href="../guides/mcp.html">MCP guide</a> for the exact schemas), and a <strong>Generate PDF</strong> button that produces the very PDF the AI assistant would receive — running the underlying <a href="https://www.npmjs.com/package/pdfnative">pdfnative</a> library directly in your browser. No API keys, no install, no LLM cost.</p>
 
     <p style="font-size: 14px; color: var(--c-text-dim);">For the full integration story (config, security model, signed-document workflow), see the <a href="../guides/mcp.html">MCP guide</a>.</p>
 
@@ -146,7 +147,7 @@ <h2 style="font-size: 18px; margin-bottom: 8px;">1. Configure your client</h2>
 
     <h2 style="margin-top: 36px;">2. Try the tools</h2>
     <p id="loader-status" style="font-size: 13px; color: var(--c-text-dim);">Loading <code>pdfnative</code> from esm.sh… this happens once per page load.</p>
-    <p style="font-size: 13px; color: var(--c-text-dim);">The interactive cards below cover the core document-authoring tools, the v1.3.0 page-tree trio (<code>merge_pdfs</code>, <code>split_pdf</code>, <code>extract_pages</code>), and the v1.4.0 <code>annotate_pdf</code> — all of which build their own source PDFs in the browser and run the real pdfnative 1.7.0 API. <code>draft_governance_issue</code> produces no PDF (it validates a report locally, network-free) — use its <em>Copy args</em> button. Nine of the 24 tools have no card here, because they need a real PDF as input and run best from your own MCP client: <code>validate_pdf</code>, <code>verify_pdf</code>, <code>add_attachment</code>, <code>extract_attachments</code>, <code>extract_text</code>, <code>read_form_fields</code>, <code>fill_form</code>, <code>encrypt_pdf</code> and <code>decrypt_pdf</code>. See the <a href="../guides/mcp.html">MCP guide</a> for their full schemas.</p>
+    <p style="font-size: 13px; color: var(--c-text-dim);">The interactive cards below cover the core document-authoring tools, the v1.3.0 page-tree trio (<code>merge_pdfs</code>, <code>split_pdf</code>, <code>extract_pages</code>), the v1.4.0 <code>annotate_pdf</code>, and the v1.6.0 <code>update_metadata</code> — all of which build their own source PDFs in the browser and run the real pdfnative 1.7.0 API. Two cards produce no PDF by design: <code>inspect_layout</code> returns a pagination report (run it to see the JSON), and <code>draft_governance_issue</code> validates a report locally, network-free — use its <em>Copy args</em> button. Eleven of the 28 tools have no card here: nine need a real PDF as input and run best from your own MCP client (<code>validate_pdf</code>, <code>verify_pdf</code>, <code>add_attachment</code>, <code>extract_attachments</code>, <code>extract_text</code>, <code>read_form_fields</code>, <code>fill_form</code>, <code>encrypt_pdf</code>, <code>decrypt_pdf</code>), and two need the operator-configured network providers a browser page cannot supply (<code>add_ltv</code>, <code>timestamp_pdf</code> — TSA / OCSP / CRL endpoints set via environment variables). See the <a href="../guides/mcp.html">MCP guide</a> for their full schemas.</p>
 
     <div class="mcp-cards" id="cards"></div>
 
@@ -305,7 +306,7 @@ <h2>Resources</h2>
     },
     {
       id: 'add_chart',
-      purpose: 'Render a bar, horizontal-bar, line, pie or donut chart as native PDF vector paths — no rasterisation, no image round-trip.',
+      purpose: 'Render a chart as native PDF vector paths — nine types since v1.6.0 (bar, horizontal bar, stacked bar, stacked horizontal bar, line, area, scatter, pie, donut), dual axis, log and time scales; no rasterisation, no image round-trip.',
       prompt: 'Chart our Q1-Q4 revenue against cost as a bar chart, and tag it for accessibility.',
       args: {
         title: 'FY2026 performance',
@@ -326,7 +327,7 @@ <h2>Resources</h2>
     },
     {
       id: 'add_international_text',
-      purpose: 'Render text in any of 24 lang codes — 22 scripts plus latin and emoji, with explicit math on top — with BiDi & OpenType shaping. You can pass several in one call.',
+      purpose: 'Render text in any of 25 lang codes — 22 scripts plus latin, emoji and the explicit math font — with BiDi & OpenType shaping. You can pass several in one call.',
       prompt: 'Create a multilingual greeting card with English, Thai, Arabic, and a smiling-face emoji.',
       args: {
         title: 'Multilingual greeting',
@@ -360,7 +361,7 @@ <h2>Resources</h2>
     },
     {
       id: 'add_form',
-      purpose: 'Build an interactive AcroForm PDF (text, checkbox, radio, dropdown).',
+      purpose: 'Build an interactive AcroForm PDF (text, textarea, checkbox, radio, dropdown — plus listbox and placeholder since v1.6.0).',
       prompt: 'Create a contact form PDF with a name field, an email field, and a “subscribe to newsletter” checkbox.',
       args: {
         title: 'Contact us',
@@ -407,7 +408,7 @@ <h2>Resources</h2>
     },
     {
       id: 'sign_pdf',
-      purpose: 'Apply a CMS/PKCS#7 signature (RSA or ECDSA) to an existing PDF.',
+      purpose: 'Apply a PAdES CMS signature (RSA-SHA256/384/512 or ECDSA) to an existing PDF — with profile: "pades", an RFC 3161 timestamp, certificate chains and multiple signatures since v1.6.0.',
       prompt: 'Sign the prepared contract using our corporate certificate.',
       args: {
         algorithm: 'rsa-sha256',
@@ -453,6 +454,30 @@ <h2>Resources</h2>
         });
       },
     },
+    {
+      id: 'inspect_layout',
+      purpose: 'Dry-run pagination: page count, page geometry and the position of every block — with no PDF produced (new in v1.6.0).',
+      prompt: 'Before rendering, tell me how many pages this report will take and where the table lands.',
+      args: {
+        title: 'Layout preview',
+        blocks: [
+          { type: 'heading', text: 'Quarterly report', level: 1 },
+          { type: 'paragraph', text: 'A short summary paragraph that flows above the figures table.' },
+          { type: 'table',
+            headers: ['Quarter', 'Revenue'],
+            rows: [
+              { cells: ['Q1', '$1.2M'] },
+              { cells: ['Q2', '$1.5M'] },
+            ],
+          },
+        ],
+      },
+      noteHtml: 'The MCP tool wraps the same read-only <code>inspectDocumentLayout()</code> this button runs — token-frugal by design, because no base64 PDF bytes are produced or transferred. The button prints the real pagination report (page size, margins, and each block&rsquo;s page / x / top / width / height) below the card.',
+      runJson: (p, m) => {
+        requireFn(m, 'inspectDocumentLayout');
+        return m.inspectDocumentLayout(p);
+      },
+    },
     {
       id: 'merge_pdfs',
       purpose: 'Concatenate 2–50 PDFs into one document (page-tree API, new in v1.3.0).',
@@ -564,6 +589,40 @@ <h2>Resources</h2>
         return mod.save();
       },
     },
+    {
+      id: 'update_metadata',
+      purpose: 'Rewrite the /Info dictionary (+ XMP) of an existing PDF — title, author, subject, keywords, pinned modDate — via a non-destructive incremental update (new in v1.6.0).',
+      prompt: 'Set the title of this PDF to "Quarterly Report — Final" and the author to "Finance Team", without touching anything else.',
+      args: {
+        pdfBase64: '<base64 source PDF>',
+        title: 'Quarterly Report — Final',
+        author: 'Finance Team',
+        keywords: 'finance, quarterly, 2026',
+        modDate: '2026-08-25T09:00:00+02:00',
+        outputMode: 'base64',
+      },
+      noteHtml: 'In a real MCP call the AI assistant supplies the source as base64. This demo builds a small source PDF in the browser, then runs the <em>real</em> pdfnative 1.7.0 <code>openPdf()</code> → <code>createModifier()</code> → <code>updateMetadata()</code> → <code>save()</code> pipeline the tool calls — an incremental update, so the original bytes stay a byte-exact prefix. Pinning <code>modDate</code> keeps the output reproducible. <strong>Encrypted sources are rejected</strong> (<code>ENCRYPTED_SOURCE</code>), matching the tool contract.',
+      build: (p, m) => {
+        requireFn(m, 'openPdf');
+        requireFn(m, 'createModifier');
+        const src = m.buildDocumentPDFBytes({ title: 'Quarterly report (draft)', blocks: [
+          { type: 'heading', text: 'Quarterly report', level: 1 },
+          { type: 'paragraph', text: 'Source document handed to update_metadata — its /Info dictionary is rewritten as an appended revision.' },
+        ]});
+        const reader = m.openPdf(src);
+        const mod = m.createModifier(reader);
+        if (typeof mod.updateMetadata !== 'function') {
+          throw new Error('updateMetadata() requires pdfnative ≥ 1.7.0 — the CDN served an older build. Try reloading.');
+        }
+        mod.updateMetadata({
+          title: 'Quarterly Report — Final',
+          author: 'Finance Team',
+          keywords: 'finance, quarterly, 2026',
+          modDate: new Date('2026-08-25T09:00:00+02:00'),
+        });
+        return mod.save();
+      },
+    },
     {
       id: 'draft_governance_issue',
       purpose: 'Generate a policy-compliant GitHub issue report locally — fully network-free (new in v1.4.0).',
@@ -612,16 +671,18 @@ <h3><code>${t.id}</code></h3>
       <div class="prompt">${t.prompt}</div>
       ${t.noteHtml ? `<p class="purpose">${t.noteHtml}</p>` : ''}
       <details>
-        <summary>${t.build ? 'Payload (pdfnative library form)' : 'MCP tool-call payload (schema example)'}</summary>
+        <summary>${(t.build || t.runJson) ? 'Payload (pdfnative library form)' : 'MCP tool-call payload (schema example)'}</summary>
         <div>
-          ${t.build ? '<p class="purpose" style="margin:0 0 6px;">This is the pdfnative library payload the browser demo executes; the MCP tool schema differs — see the <a href="../guides/mcp.html">MCP guide</a>.</p>' : ''}
+          ${(t.build || t.runJson) ? '<p class="purpose" style="margin:0 0 6px;">This is the pdfnative library payload the browser demo executes; the MCP tool schema differs — see the <a href="../guides/mcp.html">MCP guide</a>.</p>' : ''}
           <pre><code class="language-json">${escapeHtml(JSON.stringify(t.args, null, 2))}</code></pre>
         </div>
       </details>
       <div class="actions">
         ${t.build ? `<button class="primary" data-action="run" data-tool="${idx}" disabled>Generate PDF</button>` : ''}
+        ${t.runJson ? `<button class="primary" data-action="run" data-tool="${idx}" disabled>Preview layout</button>` : ''}
         <button class="secondary" data-action="copy-args" data-tool="${idx}">Copy args</button>
       </div>
+      ${t.runJson ? '<pre data-result hidden></pre>' : ''}
       <div class="status" data-status></div>
     `;
     cards.appendChild(card);
@@ -677,14 +738,24 @@ <h3><code>${t.id}</code></h3>
     if (btn.dataset.action === 'run') {
       if (!pdfnativeMod) return;
       btn.disabled = true;
-      status.textContent = 'Generating…'; status.className = 'status';
+      status.textContent = tool.runJson ? 'Measuring…' : 'Generating…'; status.className = 'status';
       try {
         const t0 = performance.now();
-        const bytes = await tool.build(tool.args, pdfnativeMod);
-        const elapsed = (performance.now() - t0).toFixed(0);
-        downloadPdf(bytes, tool.id + '.pdf');
-        status.textContent = `Generated ${(bytes.length / 1024).toFixed(1)} KB in ${elapsed} ms.`;
-        status.className = 'status success';
+        if (tool.runJson) {
+          const report = await tool.runJson(tool.args, pdfnativeMod);
+          const elapsed = (performance.now() - t0).toFixed(0);
+          const out = card.querySelector('[data-result]');
+          out.textContent = JSON.stringify(report, null, 2);
+          out.hidden = false;
+          status.textContent = `Previewed ${report.totalPages} page(s) in ${elapsed} ms — no PDF produced.`;
+          status.className = 'status success';
+        } else {
+          const bytes = await tool.build(tool.args, pdfnativeMod);
+          const elapsed = (performance.now() - t0).toFixed(0);
+          downloadPdf(bytes, tool.id + '.pdf');
+          status.textContent = `Generated ${(bytes.length / 1024).toFixed(1)} KB in ${elapsed} ms.`;
+          status.className = 'status success';
+        }
       } catch (e) {
         status.textContent = 'Error: ' + (e && e.message ? e.message : e);
         status.className = 'status error';
diff --git a/docs/playgrounds/react.html b/docs/playgrounds/react.html
index 0bd5e18..6c69403 100644
--- a/docs/playgrounds/react.html
+++ b/docs/playgrounds/react.html
@@ -100,6 +100,7 @@
     <a href="./extreme-scripts.html">Extreme scripts</a>
     <a href="./all-scripts.html">All 22 scripts</a>
     <a href="./toolkit.html">PDF Toolkit</a>
+    <a href="./inspect.html">Inspect &amp; verify</a>
     <a href="./charts.html">Charts</a>
     <a href="./authoring-plus.html">Authoring+</a>
     <a href="./scale.html">Scale</a>
diff --git a/docs/playgrounds/scale.html b/docs/playgrounds/scale.html
index 9a0b642..12cac44 100644
--- a/docs/playgrounds/scale.html
+++ b/docs/playgrounds/scale.html
@@ -131,6 +131,7 @@
     <a href="./extreme-scripts.html">Extreme scripts</a>
     <a href="./all-scripts.html">All 22 scripts</a>
     <a href="./toolkit.html">PDF Toolkit</a>
+    <a href="./inspect.html">Inspect &amp; verify</a>
     <a href="./charts.html">Charts</a>
     <a href="./authoring-plus.html">Authoring+</a>
     <a href="./scale.html" aria-current="page">Scale</a>
diff --git a/docs/playgrounds/toolkit.html b/docs/playgrounds/toolkit.html
index 497d12e..a0d21d0 100644
--- a/docs/playgrounds/toolkit.html
+++ b/docs/playgrounds/toolkit.html
@@ -7,10 +7,10 @@
   <meta name="description" content="Try pdfnative's document toolkit in your browser: outline bookmarks, page labels, merge / split / extract, AES re-encryption, encrypted form filling, and text extraction with positions.">
   <link rel="canonical" href="https://pdfnative.dev/playgrounds/toolkit.html">
   <link rel="alternate" hreflang="en" href="https://pdfnative.dev/playgrounds/toolkit.html">
-  <link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/playgrounds/toolkit.html">
+  <link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/playgrounds/toolkit.html">
   <meta property="og:type" content="website">
   <meta property="og:site_name" content="pdfnative">
-  <meta property="og:locale" content="en_US">
+  <meta property="og:locale" content="en_US">
   <meta property="og:url" content="https://pdfnative.dev/playgrounds/toolkit.html">
   <meta property="og:title" content="PDF Toolkit Playground — pdfnative">
   <meta property="og:description" content="Outline bookmarks, page labels, merge / split / extract, AES-256 re-encryption, encrypted AcroForm fill &amp; flatten, and text extraction with positions — all in your browser.">
@@ -75,6 +75,7 @@
     <a href="./extreme-scripts.html">Extreme scripts</a>
     <a href="./all-scripts.html">All 22 scripts</a>
     <a href="./toolkit.html" aria-current="page">PDF Toolkit</a>
+    <a href="./inspect.html">Inspect &amp; verify</a>
     <a href="./charts.html">Charts</a>
     <a href="./authoring-plus.html">Authoring+</a>
     <a href="./scale.html">Scale</a>
diff --git a/docs/responsibility.html b/docs/responsibility.html
index f1069c5..58e41f1 100644
--- a/docs/responsibility.html
+++ b/docs/responsibility.html
@@ -8,6 +8,7 @@
   <link rel="canonical" href="https://pdfnative.dev/responsibility.html">
   <link rel="alternate" hreflang="en" href="https://pdfnative.dev/responsibility.html">
   <link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/responsibility.html">
+  <link rel="alternate" type="text/plain" href="llms.txt" title="llms.txt — machine-readable documentation index">
   <meta property="og:type" content="website">
   <meta property="og:site_name" content="pdfnative">
   <meta property="og:locale" content="en_US">
@@ -98,12 +99,12 @@ <h2 id="efficiency">Efficiency by architecture</h2>
 
     <div class="rs-claim">
       <p><strong>The engine has no runtime dependencies.</strong> <code>pdfnative</code> ships with no <code>dependencies</code> field at all: nothing transitive to install, audit, or patch.</p>
-      <p>Scoped honestly, because the ecosystem is not uniform: <code>pdfnative-cli</code> depends only on <code>pdfnative</code> itself. <code>pdfnative-react</code> adds one real runtime dependency, <code>react-reconciler</code>, with React and pdfnative as peers. <code>pdfnative-mcp</code> adds two, <code>@modelcontextprotocol/sdk</code> and <code>zod</code>. And this documentation site itself loads Prism, marked and DOMPurify from a CDN — pinned, with subresource-integrity hashes.</p>
+      <p>Scoped honestly, because the ecosystem is not uniform: <code>pdfnative-cli</code> depends only on <code>pdfnative</code> itself. <code>pdfnative-react</code> adds one real runtime dependency, <code>react-reconciler</code>, with React and pdfnative as peers. <code>pdfnative-mcp</code> adds two, <code>@modelcontextprotocol/server</code> and <code>zod</code>. And this documentation site itself loads Prism, marked and DOMPurify from a CDN — pinned, with subresource-integrity hashes.</p>
       <p class="rs-verify">Verify it: <a href="https://github.com/Nizoka/pdfnative/blob/main/package.json" target="_blank" rel="noopener">package.json</a> (no dependencies key) · <a href="https://github.com/Nizoka/pdfnative-react/blob/main/package.json" target="_blank" rel="noopener">pdfnative-react/package.json</a> · <a href="https://github.com/Nizoka/pdfnative-mcp/blob/main/package.json" target="_blank" rel="noopener">pdfnative-mcp/package.json</a></p>
     </div>
 
     <div class="rs-claim">
-      <p><strong>The library never opens a socket.</strong> No telemetry endpoint, no auto-update channel, no remote font fetch. Searching the engine source for any of the ways JavaScript can reach the network — <code>fetch</code>, <code>XMLHttpRequest</code>, <code>WebSocket</code>, <code>node:http</code>, <code>sendBeacon</code> — returns no matches at all.</p>
+      <p><strong>The library never opens a socket.</strong> No telemetry endpoint, no auto-update channel, no remote font fetch. Searching the engine source for any of the ways JavaScript can reach the network — <code>fetch</code>, <code>XMLHttpRequest</code>, <code>WebSocket</code>, <code>node:http</code>, <code>sendBeacon</code> — finds no call sites in executable code. The only matches are documentation comments: the <code>@example</code> blocks of the injectable <code>TimestampProvider</code> / <code>RevocationProvider</code> interfaces (v1.7.0), which show how <em>your</em> code can supply network transport for LTV — the engine itself never performs the request.</p>
       <p>One scoped exception, stated because it is real: <code>pdfnative-cli verify</code> can fetch OCSP and CRL responses when checking whether a signing certificate has been revoked. It does not do so by default — the default reads only the revocation data already embedded in the document, and network checks require <code>--revocation online</code>. RFC 3161 timestamps are <em>validated</em> from the embedded token; the CLI does not contact a timestamp authority, and <code>sign --timestamp</code> reports that it is not yet implemented.</p>
       <p class="rs-verify">Verify it: <code>grep -rE "fetch\(|XMLHttpRequest|WebSocket|node:http" src/</code> · <a href="https://github.com/Nizoka/pdfnative/blob/main/SECURITY.md" target="_blank" rel="noopener">SECURITY.md</a></p>
     </div>
@@ -179,7 +180,7 @@ <h2 id="not-claimed">What we deliberately do not claim</h2>
         <li><strong>"Lighter than <em>library X</em>" as an environmental argument.</strong> The <a href="./#comparison">feature comparison</a> compares capabilities. There is no committed benchmark comparing runtime or bundle size against other libraries, so there is no basis for an efficiency claim relative to them.</li>
         <li><strong>A single headline bundle size.</strong> The built artefacts in <code>dist/</code> are unminified and ship with sourcemaps, so quoting their raw byte count would overstate the cost as badly as quoting a gzipped figure would understate it. Measure it for your own bundle.</li>
         <li><strong>"Zero dependencies" across the ecosystem.</strong> True for the engine. Not true for <code>pdfnative-react</code> or <code>pdfnative-mcp</code>, as stated above.</li>
-        <li><strong>"Never touches the network" across the ecosystem.</strong> True for the engine. The CLI's <code>verify</code> command makes OCSP, CRL and timestamp requests by design.</li>
+        <li><strong>"Never touches the network" across the ecosystem.</strong> True for the engine. The CLI's <code>verify</code> command can make OCSP and CRL requests when <code>--revocation online</code> is passed, and pdfnative-mcp's PAdES tools reach only the operator-configured TSA / OCSP / CRL endpoints — by design in both cases.</li>
         <li><strong>Certification of any kind.</strong> PDF/A output is validated by the veraPDF reference validator in CI, which is meaningful evidence — but pdfnative is not an accredited conformance-tested product, and there is no ISO 14001, SOC 2, HIPAA or GDPR certification behind it. Software architecture is not a compliance certificate.</li>
         <li><strong>WCAG conformance of this website.</strong> The site has a skip link, visible focus indicators, reduced-motion support and contrast ratios checked in CI. It has not been through a formal accessibility audit, so we describe the measures rather than claim the outcome.</li>
       </ul>
diff --git a/docs/robots.txt b/docs/robots.txt
index bff4552..349888a 100644
--- a/docs/robots.txt
+++ b/docs/robots.txt
@@ -1,5 +1,10 @@
 # robots.txt for pdfnative.dev
 # Allow all well-behaved crawlers full access to the documentation site.
+#
+# Machine-readable documentation for AI agents and LLM pipelines:
+#   https://pdfnative.dev/llms.txt        — index (llmstxt.org convention)
+#   https://pdfnative.dev/llms-full.txt   — full documentation corpus
+# Every guide also serves its raw Markdown at the same path with .md.
 
 User-agent: *
 Allow: /
diff --git a/docs/sitemap.xml b/docs/sitemap.xml
index 837d73a..3086552 100644
--- a/docs/sitemap.xml
+++ b/docs/sitemap.xml
@@ -11,7 +11,7 @@
     <loc>https://pdfnative.dev/</loc>
     <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/"/>
     <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/"/>
-    <lastmod>2026-08-01</lastmod>
+    <lastmod>2026-08-25</lastmod>
     <changefreq>weekly</changefreq>
     <priority>1.0</priority>
   </url>
@@ -21,7 +21,7 @@
     <loc>https://pdfnative.dev/guides/</loc>
     <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/"/>
     <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/"/>
-    <lastmod>2026-08-01</lastmod>
+    <lastmod>2026-08-25</lastmod>
     <changefreq>weekly</changefreq>
     <priority>0.9</priority>
   </url>
@@ -29,7 +29,7 @@
     <loc>https://pdfnative.dev/guides/onboarding.html</loc>
     <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/onboarding.html"/>
     <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/onboarding.html"/>
-    <lastmod>2026-08-01</lastmod>
+    <lastmod>2026-08-25</lastmod>
     <changefreq>monthly</changefreq>
     <priority>0.8</priority>
   </url>
@@ -45,7 +45,7 @@
     <loc>https://pdfnative.dev/guides/architecture.html</loc>
     <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/architecture.html"/>
     <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/architecture.html"/>
-    <lastmod>2026-08-01</lastmod>
+    <lastmod>2026-08-25</lastmod>
     <changefreq>monthly</changefreq>
     <priority>0.7</priority>
   </url>
@@ -53,7 +53,7 @@
     <loc>https://pdfnative.dev/guides/ai-governance.html</loc>
     <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/ai-governance.html"/>
     <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/ai-governance.html"/>
-    <lastmod>2026-08-01</lastmod>
+    <lastmod>2026-08-25</lastmod>
     <changefreq>monthly</changefreq>
     <priority>0.7</priority>
   </url>
@@ -61,7 +61,7 @@
     <loc>https://pdfnative.dev/guides/agentic-workflows.html</loc>
     <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/agentic-workflows.html"/>
     <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/agentic-workflows.html"/>
-    <lastmod>2026-08-01</lastmod>
+    <lastmod>2026-08-25</lastmod>
     <changefreq>monthly</changefreq>
     <priority>0.7</priority>
   </url>
@@ -77,7 +77,7 @@
     <loc>https://pdfnative.dev/guides/pdfa.html</loc>
     <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/pdfa.html"/>
     <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/pdfa.html"/>
-    <lastmod>2026-08-21</lastmod>
+    <lastmod>2026-08-25</lastmod>
     <changefreq>monthly</changefreq>
     <priority>0.7</priority>
   </url>
@@ -85,7 +85,7 @@
     <loc>https://pdfnative.dev/guides/accessibility.html</loc>
     <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/accessibility.html"/>
     <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/accessibility.html"/>
-    <lastmod>2026-08-01</lastmod>
+    <lastmod>2026-08-25</lastmod>
     <changefreq>monthly</changefreq>
     <priority>0.7</priority>
   </url>
@@ -93,7 +93,7 @@
     <loc>https://pdfnative.dev/guides/signatures.html</loc>
     <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/signatures.html"/>
     <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/signatures.html"/>
-    <lastmod>2026-08-20</lastmod>
+    <lastmod>2026-08-25</lastmod>
     <changefreq>monthly</changefreq>
     <priority>0.7</priority>
   </url>
@@ -101,7 +101,7 @@
     <loc>https://pdfnative.dev/guides/ltv.html</loc>
     <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/ltv.html"/>
     <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/ltv.html"/>
-    <lastmod>2026-08-20</lastmod>
+    <lastmod>2026-08-25</lastmod>
     <changefreq>monthly</changefreq>
     <priority>0.7</priority>
   </url>
@@ -125,7 +125,7 @@
     <loc>https://pdfnative.dev/guides/colour-emoji.html</loc>
     <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/colour-emoji.html"/>
     <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/colour-emoji.html"/>
-    <lastmod>2026-08-21</lastmod>
+    <lastmod>2026-08-25</lastmod>
     <changefreq>monthly</changefreq>
     <priority>0.7</priority>
   </url>
@@ -149,7 +149,7 @@
     <loc>https://pdfnative.dev/guides/pdf-manipulation.html</loc>
     <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/pdf-manipulation.html"/>
     <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/pdf-manipulation.html"/>
-    <lastmod>2026-08-01</lastmod>
+    <lastmod>2026-08-25</lastmod>
     <changefreq>monthly</changefreq>
     <priority>0.7</priority>
   </url>
@@ -157,7 +157,7 @@
     <loc>https://pdfnative.dev/guides/form-filling.html</loc>
     <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/form-filling.html"/>
     <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/form-filling.html"/>
-    <lastmod>2026-08-01</lastmod>
+    <lastmod>2026-08-25</lastmod>
     <changefreq>monthly</changefreq>
     <priority>0.7</priority>
   </url>
@@ -165,7 +165,7 @@
     <loc>https://pdfnative.dev/guides/charts.html</loc>
     <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/charts.html"/>
     <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/charts.html"/>
-    <lastmod>2026-08-21</lastmod>
+    <lastmod>2026-08-25</lastmod>
     <changefreq>monthly</changefreq>
     <priority>0.7</priority>
   </url>
@@ -173,7 +173,7 @@
     <loc>https://pdfnative.dev/guides/text-extraction.html</loc>
     <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/text-extraction.html"/>
     <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/text-extraction.html"/>
-    <lastmod>2026-08-01</lastmod>
+    <lastmod>2026-08-25</lastmod>
     <changefreq>monthly</changefreq>
     <priority>0.7</priority>
   </url>
@@ -213,7 +213,7 @@
     <loc>https://pdfnative.dev/guides/cli.html</loc>
     <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/cli.html"/>
     <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/cli.html"/>
-    <lastmod>2026-08-01</lastmod>
+    <lastmod>2026-08-25</lastmod>
     <changefreq>monthly</changefreq>
     <priority>0.7</priority>
   </url>
@@ -221,7 +221,7 @@
     <loc>https://pdfnative.dev/guides/mcp.html</loc>
     <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/mcp.html"/>
     <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/mcp.html"/>
-    <lastmod>2026-08-01</lastmod>
+    <lastmod>2026-08-25</lastmod>
     <changefreq>monthly</changefreq>
     <priority>0.7</priority>
   </url>
@@ -229,7 +229,7 @@
     <loc>https://pdfnative.dev/guides/react.html</loc>
     <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/react.html"/>
     <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/react.html"/>
-    <lastmod>2026-08-01</lastmod>
+    <lastmod>2026-08-25</lastmod>
     <changefreq>monthly</changefreq>
     <priority>0.7</priority>
   </url>
@@ -255,7 +255,7 @@
     <loc>https://pdfnative.dev/playgrounds/</loc>
     <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/playgrounds/"/>
     <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/playgrounds/"/>
-    <lastmod>2026-08-01</lastmod>
+    <lastmod>2026-08-25</lastmod>
     <changefreq>monthly</changefreq>
     <priority>0.8</priority>
   </url>
@@ -279,7 +279,7 @@
     <loc>https://pdfnative.dev/playgrounds/charts.html</loc>
     <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/playgrounds/charts.html"/>
     <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/playgrounds/charts.html"/>
-    <lastmod>2026-08-01</lastmod>
+    <lastmod>2026-08-25</lastmod>
     <changefreq>monthly</changefreq>
     <priority>0.6</priority>
   </url>
@@ -303,7 +303,7 @@
     <loc>https://pdfnative.dev/learn/</loc>
     <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/learn/"/>
     <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/learn/"/>
-    <lastmod>2026-08-01</lastmod>
+    <lastmod>2026-08-25</lastmod>
     <changefreq>monthly</changefreq>
     <priority>0.9</priority>
   </url>
@@ -367,7 +367,7 @@
     <loc>https://pdfnative.dev/learn/08-next-steps.html</loc>
     <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/learn/08-next-steps.html"/>
     <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/learn/08-next-steps.html"/>
-    <lastmod>2026-08-01</lastmod>
+    <lastmod>2026-08-25</lastmod>
     <changefreq>monthly</changefreq>
     <priority>0.8</priority>
   </url>
@@ -375,7 +375,7 @@
     <loc>https://pdfnative.dev/responsibility.html</loc>
     <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/responsibility.html"/>
     <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/responsibility.html"/>
-    <lastmod>2026-08-01</lastmod>
+    <lastmod>2026-08-25</lastmod>
     <changefreq>monthly</changefreq>
     <priority>0.7</priority>
   </url>
@@ -399,7 +399,7 @@
     <loc>https://pdfnative.dev/playgrounds/mcp.html</loc>
     <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/playgrounds/mcp.html"/>
     <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/playgrounds/mcp.html"/>
-    <lastmod>2026-08-01</lastmod>
+    <lastmod>2026-08-25</lastmod>
     <changefreq>monthly</changefreq>
     <priority>0.6</priority>
   </url>
@@ -411,4 +411,304 @@
     <changefreq>monthly</changefreq>
     <priority>0.6</priority>
   </url>
+
+  <!-- Machine-readable sources: the llms.txt index, the full concatenation,
+       and the raw Markdown behind every guide (AI agents prefer these). -->
+  <url>
+    <loc>https://pdfnative.dev/llms.txt</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/llms.txt"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/llms.txt"/>
+    <lastmod>2026-08-25</lastmod>
+    <changefreq>monthly</changefreq>
+    <priority>0.3</priority>
+  </url>
+  <url>
+    <loc>https://pdfnative.dev/agent-brief.md</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/agent-brief.md"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/agent-brief.md"/>
+    <lastmod>2026-08-25</lastmod>
+    <changefreq>monthly</changefreq>
+    <priority>0.4</priority>
+  </url>
+  <url>
+    <loc>https://pdfnative.dev/llms-full.txt</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/llms-full.txt"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/llms-full.txt"/>
+    <lastmod>2026-08-25</lastmod>
+    <changefreq>monthly</changefreq>
+    <priority>0.3</priority>
+  </url>
+  <url>
+    <loc>https://pdfnative.dev/guides/accessibility.md</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/accessibility.md"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/accessibility.md"/>
+    <lastmod>2026-08-25</lastmod>
+    <changefreq>monthly</changefreq>
+    <priority>0.3</priority>
+  </url>
+  <url>
+    <loc>https://pdfnative.dev/guides/agentic-workflows.md</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/agentic-workflows.md"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/agentic-workflows.md"/>
+    <lastmod>2026-08-25</lastmod>
+    <changefreq>monthly</changefreq>
+    <priority>0.3</priority>
+  </url>
+  <url>
+    <loc>https://pdfnative.dev/guides/ai-governance.md</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/ai-governance.md"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/ai-governance.md"/>
+    <lastmod>2026-08-25</lastmod>
+    <changefreq>monthly</changefreq>
+    <priority>0.3</priority>
+  </url>
+  <url>
+    <loc>https://pdfnative.dev/guides/annotations.md</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/annotations.md"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/annotations.md"/>
+    <lastmod>2026-08-25</lastmod>
+    <changefreq>monthly</changefreq>
+    <priority>0.3</priority>
+  </url>
+  <url>
+    <loc>https://pdfnative.dev/guides/architecture.md</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/architecture.md"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/architecture.md"/>
+    <lastmod>2026-08-25</lastmod>
+    <changefreq>monthly</changefreq>
+    <priority>0.3</priority>
+  </url>
+  <url>
+    <loc>https://pdfnative.dev/guides/charts.md</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/charts.md"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/charts.md"/>
+    <lastmod>2026-08-25</lastmod>
+    <changefreq>monthly</changefreq>
+    <priority>0.3</priority>
+  </url>
+  <url>
+    <loc>https://pdfnative.dev/guides/cli.md</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/cli.md"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/cli.md"/>
+    <lastmod>2026-08-25</lastmod>
+    <changefreq>monthly</changefreq>
+    <priority>0.3</priority>
+  </url>
+  <url>
+    <loc>https://pdfnative.dev/guides/colour-emoji-cli.md</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/colour-emoji-cli.md"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/colour-emoji-cli.md"/>
+    <lastmod>2026-08-25</lastmod>
+    <changefreq>monthly</changefreq>
+    <priority>0.3</priority>
+  </url>
+  <url>
+    <loc>https://pdfnative.dev/guides/colour-emoji.md</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/colour-emoji.md"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/colour-emoji.md"/>
+    <lastmod>2026-08-25</lastmod>
+    <changefreq>monthly</changefreq>
+    <priority>0.3</priority>
+  </url>
+  <url>
+    <loc>https://pdfnative.dev/guides/debugging.md</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/debugging.md"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/debugging.md"/>
+    <lastmod>2026-08-25</lastmod>
+    <changefreq>monthly</changefreq>
+    <priority>0.3</priority>
+  </url>
+  <url>
+    <loc>https://pdfnative.dev/guides/faq.md</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/faq.md"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/faq.md"/>
+    <lastmod>2026-08-25</lastmod>
+    <changefreq>monthly</changefreq>
+    <priority>0.3</priority>
+  </url>
+  <url>
+    <loc>https://pdfnative.dev/guides/font-validation.md</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/font-validation.md"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/font-validation.md"/>
+    <lastmod>2026-08-25</lastmod>
+    <changefreq>monthly</changefreq>
+    <priority>0.3</priority>
+  </url>
+  <url>
+    <loc>https://pdfnative.dev/guides/form-filling.md</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/form-filling.md"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/form-filling.md"/>
+    <lastmod>2026-08-25</lastmod>
+    <changefreq>monthly</changefreq>
+    <priority>0.3</priority>
+  </url>
+  <url>
+    <loc>https://pdfnative.dev/guides/ltv.md</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/ltv.md"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/ltv.md"/>
+    <lastmod>2026-08-25</lastmod>
+    <changefreq>monthly</changefreq>
+    <priority>0.3</priority>
+  </url>
+  <url>
+    <loc>https://pdfnative.dev/guides/mcp.md</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/mcp.md"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/mcp.md"/>
+    <lastmod>2026-08-25</lastmod>
+    <changefreq>monthly</changefreq>
+    <priority>0.3</priority>
+  </url>
+  <url>
+    <loc>https://pdfnative.dev/guides/onboarding.md</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/onboarding.md"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/onboarding.md"/>
+    <lastmod>2026-08-25</lastmod>
+    <changefreq>monthly</changefreq>
+    <priority>0.3</priority>
+  </url>
+  <url>
+    <loc>https://pdfnative.dev/guides/outlines.md</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/outlines.md"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/outlines.md"/>
+    <lastmod>2026-08-25</lastmod>
+    <changefreq>monthly</changefreq>
+    <priority>0.3</priority>
+  </url>
+  <url>
+    <loc>https://pdfnative.dev/guides/pdf-manipulation.md</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/pdf-manipulation.md"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/pdf-manipulation.md"/>
+    <lastmod>2026-08-25</lastmod>
+    <changefreq>monthly</changefreq>
+    <priority>0.3</priority>
+  </url>
+  <url>
+    <loc>https://pdfnative.dev/guides/pdfa.md</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/pdfa.md"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/pdfa.md"/>
+    <lastmod>2026-08-25</lastmod>
+    <changefreq>monthly</changefreq>
+    <priority>0.3</priority>
+  </url>
+  <url>
+    <loc>https://pdfnative.dev/guides/print.md</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/print.md"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/print.md"/>
+    <lastmod>2026-08-25</lastmod>
+    <changefreq>monthly</changefreq>
+    <priority>0.3</priority>
+  </url>
+  <url>
+    <loc>https://pdfnative.dev/guides/quickstart.md</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/quickstart.md"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/quickstart.md"/>
+    <lastmod>2026-08-25</lastmod>
+    <changefreq>monthly</changefreq>
+    <priority>0.3</priority>
+  </url>
+  <url>
+    <loc>https://pdfnative.dev/guides/react.md</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/react.md"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/react.md"/>
+    <lastmod>2026-08-25</lastmod>
+    <changefreq>monthly</changefreq>
+    <priority>0.3</priority>
+  </url>
+  <url>
+    <loc>https://pdfnative.dev/guides/signatures.md</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/signatures.md"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/signatures.md"/>
+    <lastmod>2026-08-25</lastmod>
+    <changefreq>monthly</changefreq>
+    <priority>0.3</priority>
+  </url>
+  <url>
+    <loc>https://pdfnative.dev/guides/streaming.md</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/streaming.md"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/streaming.md"/>
+    <lastmod>2026-08-25</lastmod>
+    <changefreq>monthly</changefreq>
+    <priority>0.3</priority>
+  </url>
+  <url>
+    <loc>https://pdfnative.dev/guides/tables.md</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/tables.md"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/tables.md"/>
+    <lastmod>2026-08-25</lastmod>
+    <changefreq>monthly</changefreq>
+    <priority>0.3</priority>
+  </url>
+  <url>
+    <loc>https://pdfnative.dev/guides/text-extraction.md</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/text-extraction.md"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/text-extraction.md"/>
+    <lastmod>2026-08-25</lastmod>
+    <changefreq>monthly</changefreq>
+    <priority>0.3</priority>
+  </url>
+  <url>
+    <loc>https://pdfnative.dev/guides/troubleshooting.md</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/troubleshooting.md"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/troubleshooting.md"/>
+    <lastmod>2026-08-25</lastmod>
+    <changefreq>monthly</changefreq>
+    <priority>0.3</priority>
+  </url>
+  <url>
+    <loc>https://pdfnative.dev/guides/viewer-preferences.md</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/viewer-preferences.md"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/viewer-preferences.md"/>
+    <lastmod>2026-08-25</lastmod>
+    <changefreq>monthly</changefreq>
+    <priority>0.3</priority>
+  </url>
+  <url>
+    <loc>https://pdfnative.dev/guides/choose.html</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/choose.html"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/choose.html"/>
+    <lastmod>2026-08-25</lastmod>
+    <changefreq>monthly</changefreq>
+    <priority>0.7</priority>
+  </url>
+  <url>
+    <loc>https://pdfnative.dev/guides/self-verify.html</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/self-verify.html"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/self-verify.html"/>
+    <lastmod>2026-08-25</lastmod>
+    <changefreq>monthly</changefreq>
+    <priority>0.7</priority>
+  </url>
+  <url>
+    <loc>https://pdfnative.dev/guides/choose.md</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/choose.md"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/choose.md"/>
+    <lastmod>2026-08-25</lastmod>
+    <changefreq>monthly</changefreq>
+    <priority>0.3</priority>
+  </url>
+  <url>
+    <loc>https://pdfnative.dev/guides/self-verify.md</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/guides/self-verify.md"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/guides/self-verify.md"/>
+    <lastmod>2026-08-25</lastmod>
+    <changefreq>monthly</changefreq>
+    <priority>0.3</priority>
+  </url>
+  <url>
+    <loc>https://pdfnative.dev/llms-recipes.txt</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/llms-recipes.txt"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/llms-recipes.txt"/>
+    <lastmod>2026-08-25</lastmod>
+    <changefreq>monthly</changefreq>
+    <priority>0.4</priority>
+  </url>
+  <url>
+    <loc>https://pdfnative.dev/playgrounds/inspect.html</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://pdfnative.dev/playgrounds/inspect.html"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://pdfnative.dev/playgrounds/inspect.html"/>
+    <lastmod>2026-08-25</lastmod>
+    <changefreq>monthly</changefreq>
+    <priority>0.6</priority>
+  </url>
+
 </urlset>
diff --git a/docs/style.css b/docs/style.css
index aa00da5..1ef0671 100644
--- a/docs/style.css
+++ b/docs/style.css
@@ -88,6 +88,11 @@ a:hover { text-decoration: underline; }
 
 img, svg { max-width: 100%; height: auto; }
 
+/* The [hidden] attribute must always win: author display rules on the same
+   element (.btn { display: inline-flex }, .bench-live-grid { display: grid })
+   would otherwise beat the UA's `[hidden] { display: none }`. */
+[hidden] { display: none !important; }
+
 /* ── Navbar ────────────────────────────────────────────────── */
 .nav {
   position: sticky; top: 0; z-index: 100;
@@ -274,7 +279,9 @@ img, svg { max-width: 100%; height: auto; }
 
 /* ── Live Demo ─────────────────────────────────────────────── */
 .demo-container {
-  max-width: 780px; margin: 0 auto;
+  /* Wide enough for the editor + inline PDF preview split (≈552px/pane);
+     the split collapses to one column below 900px. */
+  max-width: 1120px; margin: 0 auto;
   display: grid; gap: 16px;
 }
 .demo-toolbar {
@@ -351,8 +358,8 @@ textarea:focus-visible,
   font-family: 'SF Mono', 'Fira Code', 'Cascadia Code', monospace;
   font-size: 13px; line-height: 1.5; tab-size: 2;
 }
-.demo-actions { display: flex; gap: 12px; align-items: center; }
-.demo-status { font-size: 13px; color: var(--c-text-muted); }
+.demo-actions { display: flex; flex-wrap: wrap; gap: 12px; align-items: center; }
+.demo-status { font-size: 13px; color: var(--c-text-muted); min-width: 0; flex: 1 1 100%; }
 .demo-error {
   background: #fef2f2; color: #991b1b;
   border: 1px solid #fecaca; border-radius: var(--radius-sm);
@@ -772,17 +779,102 @@ textarea:focus-visible,
   text-decoration: none;
 }
 .star-cta .star-icon { font-size: 13px; }
+
+/* ── Reduced motion ──────────────────────────────────────────────────
+   The site animates benchmark bars, smooth-scrolls anchor navigation and
+   carries ~10 transition rules. Honour the OS-level preference for users
+   who experience motion sickness or distraction from movement. */
+@media (prefers-reduced-motion: reduce) {
+  html { scroll-behavior: auto; }
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+
+/* ── Live-demo split view (editor + inline PDF preview) ──────────── */
+
+.pn-split {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
+  gap: 16px;
+  align-items: stretch;
+}
+
+.pn-split-pane { min-width: 0; display: flex; flex-direction: column; }
+
+/* min-height lives on the frame only: when the iframe is hidden (no inline
+   PDF viewer, e.g. most mobile browsers) the pane must collapse to its note
+   instead of leaving a 420px empty box. */
+
+.pn-preview-frame {
+  flex: 1;
+  width: 100%;
+  min-height: 420px;
+  border: 1px solid var(--c-border);
+  border-radius: 8px;
+  background: var(--c-surface);
+}
+
+.pn-preview-note {
+  font-size: 13px;
+  color: var(--c-text-dim);
+  margin: 8px 0 0;
+}
+
+@media (max-width: 900px) {
+  .pn-split { grid-template-columns: 1fr; }
+  .pn-preview-frame { min-height: 320px; }
+}
+
+.demo-mode { display: inline-flex; gap: 4px; margin-right: 10px; border: 1px solid var(--c-border); border-radius: 6px; padding: 2px; }
+.demo-mode-btn { padding: 4px 12px; font-size: 13px; border: none; background: transparent; border-radius: 4px; cursor: pointer; color: var(--c-text-dim); font-weight: 600; }
+.demo-mode-btn.active { background: var(--c-primary); color: var(--c-primary-fg); }
+
+.bench-live { margin-top: 18px; }
+.bench-live-grid { margin-top: 14px; display: grid; gap: 10px; }
+.bench-live-label { font-size: 13px; color: var(--c-text-dim); }
+.bench-live-value { font-size: 13px; font-weight: 600; color: var(--c-text); font-variant-numeric: tabular-nums; }
+.bench-live-bar { background: var(--c-success, #16a34a); }
+
+/* ── Comparison quiz ─────────────────────────────────────────────── */
+
+.cmp-quiz { margin: 0 auto 22px; max-width: 860px; padding: 16px 20px; border: 1px solid var(--c-border); border-radius: 10px; background: var(--c-bg-card); }
+.cmp-quiz-label { font-size: 14px; color: var(--c-text-dim); margin: 0 0 12px; }
+.cmp-quiz-options { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(280px, 100%), 1fr)); gap: 8px 18px; }
+.cmp-quiz-options label { font-size: 14px; color: var(--c-text); display: flex; gap: 8px; align-items: baseline; cursor: pointer; }
+.cmp-quiz-verdict { margin: 14px 0 0; font-size: 14px; color: var(--c-text); border-left: 3px solid var(--c-primary); background: var(--c-surface); padding: 10px 14px; border-radius: 0 8px 8px 0; }
+.cmp-table tr.cmp-hot td { background: color-mix(in srgb, var(--c-primary) 10%, transparent); }
+
+/* Dark theme: --c-primary lightens to #3b82f6 while --c-primary-fg stays
+   white (3.7:1 at 13px — below AA). Use a darker active background there. */
+[data-theme="dark"] .demo-mode-btn.active { background: #1d4ed8; }
 
-/* ── Reduced motion ──────────────────────────────────────────────────
-   The site animates benchmark bars, smooth-scrolls anchor navigation and
-   carries ~10 transition rules. Honour the OS-level preference for users
-   who experience motion sickness or distraction from movement. */
-@media (prefers-reduced-motion: reduce) {
-  html { scroll-behavior: auto; }
-  *, *::before, *::after {
-    animation-duration: 0.01ms !important;
-    animation-iteration-count: 1 !important;
-    transition-duration: 0.01ms !important;
-    scroll-behavior: auto !important;
+/* ── Print ───────────────────────────────────────────────────────── */
+
+@media print {
+  .nav,
+  .nav-hamburger,
+  .theme-toggle,
+  .playground-switcher,
+  .guide-source-bar,
+  .demo-actions,
+  .demo-mode,
+  .pn-preview-pane,
+  .pn-version-strip,
+  .footer-links,
+  .skip-link,
+  .copy-btn,
+  .bench-live,
+  .cmp-quiz {
+    display: none !important;
+  }
+  .guide-content a[href^="http"]::after {
+    content: " (" attr(href) ")";
+    font-size: 0.85em;
+    color: #475569;
   }
-}
+  body { background: #ffffff; color: #000000; }
+}
diff --git a/llms.txt b/llms.txt
index 7907dee..fa255d5 100644
--- a/llms.txt
+++ b/llms.txt
@@ -5,7 +5,7 @@
 ## Docs
 
 - [README](https://github.com/Nizoka/pdfnative/blob/main/README.md): Full feature list, install, quick start, API surface, examples.
-- [ROADMAP](https://github.com/Nizoka/pdfnative/blob/main/ROADMAP.md): Shipped milestones (v1.0 → v1.7; v1.5: math/technical-symbols font, `pdfnative/tools` font compiler/parser, SVG `<text>`, page-labels reader, layout debug overlay + `inspectDocumentLayout`, markup annotation read/write, AI-agent governance; v1.4: document outline/bookmarks, page labels, page-tree manipulation (merge/split/extract), streamToFile, COLRv1 advanced compositing; v1.3: COLRv1 colour emoji, USE-lite shaper integration, true constant-memory streaming, UAX #9 X4–X5 overrides, Telugu + Amharic/Sinhala/Tibetan/Khmer/Myanmar scripts, validatePdfUA) + long-term (WASM, full USE).
+- [ROADMAP](https://github.com/Nizoka/pdfnative/blob/main/ROADMAP.md): Shipped milestones (v1.0 → v1.7; v1.7: PAdES LTV B-B → B-LTA, charts v2, colour-emoji flag/ZWJ sequences, UAX #9 conformance, print production, PDF/A declaration guards, `updateMetadata`; v1.6: parser-side decryptor, streaming merge/split/extract, fill & flatten AcroForms, native vector charts, `extractText`, re-encrypt output; v1.5: math/technical-symbols font, `pdfnative/tools` font compiler/parser, SVG `<text>`, page-labels reader, layout debug overlay + `inspectDocumentLayout`, markup annotation read/write, AI-agent governance; v1.4: document outline/bookmarks, page labels, page-tree manipulation (merge/split/extract), streamToFile, COLRv1 advanced compositing; v1.3: COLRv1 colour emoji, USE-lite shaper integration, true constant-memory streaming, UAX #9 X4–X5 overrides, Telugu + Amharic/Sinhala/Tibetan/Khmer/Myanmar scripts, validatePdfUA) + long-term (WASM, full USE).
 - [CHANGELOG](https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md): Per-version changes.
 - [Release notes v1.7.0](https://github.com/Nizoka/pdfnative/blob/main/release-notes/v1.7.0.md): PAdES LTV signing B-B → B-LTA (`signPdfBytesWithTimestamp` RFC 3161 timestamps, `addValidationInfo` `/DSS` + `/VRI` OCSP/CRL material, `addDocumentTimestamp`, `listSignatures`, multi-signature via `addSignaturePlaceholder({ allowMultiple })` — network transport injected through `setTimestampProvider`/`setRevocationProvider`, the engine never opens a socket), charts v2 (stackedBar/stackedBarH/area/scatter, secondary right axis, log + UTC time scales, data labels, x-label collision handling), colour-emoji flag & ZWJ sequences (51 flags + 22 ZWJ as COLR ligatures), UAX #9 conformance fixes (RTL digit order, glyph mirroring, ALEF joining, Persian presentation forms), PDF/A declaration guards (`strict`/`onDiagnostic`), incremental writer/xref hardening, `PdfModifier.updateMetadata()`.
 - [Release notes v1.6.0](https://github.com/Nizoka/pdfnative/blob/main/release-notes/v1.6.0.md): Standard Security Handler reader/decryptor (`openPdf(bytes, { password })`, RC4/AES-128/AES-256; `PdfSourceInput`/`MergeOptions.password` for encrypted merge/split sources), streaming page-tree manipulation (`streamMergedPdfs`/`streamSplitPdf`/`streamExtractPages`), fill & flatten existing AcroForm PDFs (`readFormFields`/`fillForm`/`flattenForm`) — encrypted documents included (encrypted incremental update), native vector charts (`chart` block: bar/barH/line/pie/donut), text extraction (`extractText`: per-page reading-order text + positioned runs, encrypted PDFs supported), re-encrypt merge/split output (`MergeOptions.encrypt`, AES-128/256), expanded colour-emoji subset (221 → 1167 incl. complete Transport & Map). Fixes: spec-compliant R6 hash + all-strings encryption on the writer; incremental trailer carries `/Encrypt` forward.
@@ -25,7 +25,7 @@
 - [FAQ](https://pdfnative.dev/guides/faq.html): Custom fonts, encryption, BiDi, workers, vs other libs.
 - [Troubleshooting](https://pdfnative.dev/guides/troubleshooting.html): Missing glyphs, RTL appearing backwards, oversized PDFs, parser errors.
 - [Colour-emoji CLI](https://pdfnative.dev/guides/colour-emoji-cli.html): `npx pdfnative-build-emoji-font` — generate a colour-emoji data module covering any glyph subset up to the full ~3,600-glyph Noto Color Emoji set, plus flag & ZWJ sequences via `--sequences` / `--sequence-list`; pinned download + SHA-256 verification.
-- [Charts](https://pdfnative.dev/guides/charts.html): Native vector `chart` blocks — 9 kinds (bar, horizontal bar, stacked bars, line, area, scatter, pie, donut) with secondary right axis, log and time scales, data labels, x-label collision handling. Path operators, no rasterisation; `/Figure` tagging with alt text.
+- [Charts](https://pdfnative.dev/guides/charts.html): Native vector `chart` blocks — 9 kinds (bar, horizontal bar, stacked bar, stacked horizontal bar, line, area, scatter, pie, donut) with secondary right axis, log and time scales, data labels, x-label collision handling. Path operators, no rasterisation; `/Figure` tagging with alt text.
 - [Text extraction](https://pdfnative.dev/guides/text-extraction.html): `extractText()` — reading-order Unicode via `/ToUnicode`, optional positioned runs, works on encrypted PDFs with a password. The RAG / agent-ingestion entry point.
 - [Form filling](https://pdfnative.dev/guides/form-filling.html): `readFormFields()` / `fillForm()` / `flattenForm()` on existing AcroForms, including encrypted PDFs via incremental update.
 - [PDF manipulation](https://pdfnative.dev/guides/pdf-manipulation.html): `openPdf()` (with `{ password }`), merge / split / extract pages, re-encrypt on output, and their streaming variants.
@@ -48,18 +48,28 @@
 
 - [Copilot instructions](https://github.com/Nizoka/pdfnative/blob/main/.github/copilot-instructions.md): Canonical project conventions — architecture, code style, build/test, PDF-specific invariants.
 - [AGENTS.md](https://github.com/Nizoka/pdfnative/blob/main/AGENTS.md): Editor-agnostic agent guidance (Cursor / Aider / Claude Code / Continue).
-- [MCP integration](https://pdfnative.dev/guides/mcp.html): `pdfnative-mcp` v1.5.0 — use pdfnative from Claude Desktop, Cursor, Continue, Zed via 24 tools — native vector `add_chart`, `read_form_fields` / `fill_form`, `encrypt_pdf` / `decrypt_pdf`, markup `annotate_pdf`, the network-free `draft_governance_issue`, and the page-tree trio `merge_pdfs` / `split_pdf` / `extract_pages`. Built on pdfnative 1.7.0.
-- [CLI](https://pdfnative.dev/guides/cli.html): `pdfnative-cli` v1.3.0 — 17 commands from the terminal — render, fill, annotate, merge / split / extract, sign, verify, encrypt, decrypt, inspect, extract-text, batch, doctor, schema, completion, govern; agent-native `--json`/`E_*`/`--dry-run` contract. Built on pdfnative 1.7.0.
+- [MCP integration](https://pdfnative.dev/guides/mcp.html): `pdfnative-mcp` v1.6.0 — use pdfnative from Claude Desktop, Cursor, Continue, Zed via 28 tools — the complete PAdES ladder B-B → B-LTA (`sign_pdf` with RFC 3161 timestamps, `add_ltv`, `timestamp_pdf`), `update_metadata`, the read-only `inspect_layout` pagination preview, all 13 block kinds in `generate_basic_pdf`, print production, charts v2, native vector `add_chart`, `read_form_fields` / `fill_form`, `encrypt_pdf` / `decrypt_pdf`, markup `annotate_pdf`, the network-free `draft_governance_issue`, and the page-tree trio `merge_pdfs` / `split_pdf` / `extract_pages`. MCP 2026-07-28 spec with legacy fallback. Built on pdfnative 1.7.0.
+- [CLI](https://pdfnative.dev/guides/cli.html): `pdfnative-cli` v1.3.0 — 17 commands from the terminal — render, fill, annotate, merge / split / extract, sign, verify, encrypt, decrypt, inspect, extract-text, batch, doctor, schema, completion, govern; agent-native `--json`/`E_*`/`--dry-run` contract. Built on the pdfnative 1.6 engine (pins `^1.6.0`, semver-accepts 1.7.0).
 - [React](https://pdfnative.dev/guides/react.html): `pdfnative-react` v1.1.0 — declarative JSX components compiled on-device to pdfnative blocks; render functions, client hooks, token-frugal DocSpec.
 
 ## Source
 
 - [src/](https://github.com/Nizoka/pdfnative/tree/main/src): Library source (core, crypto, fonts, parser, shaping, types, worker).
 - [scripts/generators/](https://github.com/Nizoka/pdfnative/tree/main/scripts/generators): 48 sample generators producing 242 reference PDFs.
-- [tests/](https://github.com/Nizoka/pdfnative/tree/main/tests): 2665+ tests across 122 files. 95%+ statements measured at v1.6.0; CI enforces ≥88%.
+- [tests/](https://github.com/Nizoka/pdfnative/tree/main/tests): 2686+ tests across 123 files. 95%+ statements measured at v1.6.0; CI enforces ≥88%.
+
+## Machine-readable artefacts
+
+- [agent-brief.md](https://pdfnative.dev/agent-brief.md): A compact briefing for AI agents writing code with pdfnative — the core API, the verified pitfalls that produce wrong code, the surface decision tree, and the self-verification loop. Designed to be pasted into a coding agent's context.
+- [llms-full.txt](https://pdfnative.dev/llms-full.txt): This index plus the README and the full Markdown source of every guide, in one request.
+- [llms-recipes.txt](https://pdfnative.dev/llms-recipes.txt): The executable recipe corpus — standalone TypeScript files importing from `pdfnative`, each executed in CI with its `@expect` assertions verified, so the code you copy is proven to compile and to produce exactly the artefact its header describes.
+- [api.json](https://pdfnative.dev/assets/api.json): The public API surface, derived mechanically from the export statements of `src/index.ts` — name, kind, source module, signature and TSDoc summary where extractable. The substitute for the unpublished `index.d.ts`.
+- [surfaces.json](https://pdfnative.dev/data/surfaces.json): The capability × surface matrix (library / CLI / MCP / React) behind the [Choosing your surface](https://pdfnative.dev/guides/choose.md) guide.
+- [llms-index.json](https://pdfnative.dev/llms-index.json): Per-page machine index — HTML and raw-Markdown URL, title, summary, section anchors, and exact byte / approximate token sizes for every artefact, so you can decide what to fetch before spending the tokens.
+- Every guide serves its raw Markdown at the same URL with `.md` instead of `.html`, declared via `<link rel="alternate" type="text/markdown">` in each page head. All of these URLs are listed in the sitemap.
 
 ## Ecosystem
 
-- [pdfnative-cli](https://github.com/Nizoka/pdfnative-cli): CLI wrapper for pdfnative (v1.3.0, built on pdfnative 1.7.0) — render, fill, annotate, merge, split, extract, sign, verify, encrypt, decrypt, inspect, extract-text, batch, doctor, schema, completion, govern.
-- [pdfnative-mcp](https://github.com/Nizoka/pdfnative-mcp): Model Context Protocol server exposing pdfnative as 24 AI tools (v1.5.0, built on pdfnative 1.7.0).
+- [pdfnative-cli](https://github.com/Nizoka/pdfnative-cli): CLI wrapper for pdfnative (v1.3.0, built on the pdfnative 1.6 engine — pins `^1.6.0`, semver-accepts 1.7.0) — render, fill, annotate, merge, split, extract, sign, verify, encrypt, decrypt, inspect, extract-text, batch, doctor, schema, completion, govern.
+- [pdfnative-mcp](https://github.com/Nizoka/pdfnative-mcp): Model Context Protocol server exposing pdfnative as 28 AI tools (v1.6.0, built on pdfnative 1.7.0).
 - [pdfnative-react](https://github.com/Nizoka/pdfnative-react): React renderer — declarative JSX components compiled on-device to pdfnative blocks (v1.1.0, React 19 + pdfnative ^1.6.0 peers).
diff --git a/package-lock.json b/package-lock.json
index 6a47d66..a3c62a5 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -16,6 +16,7 @@
         "@types/node": "^22.0.0",
         "@vitest/coverage-v8": "^4.1.8",
         "eslint": "^9.0.0",
+        "marked": "12.0.2",
         "tsup": "^8.0.0",
         "tsx": "^4.22.4",
         "typescript": "^5.4.0",
@@ -3169,6 +3170,19 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/marked": {
+      "version": "12.0.2",
+      "resolved": "https://registry.npmjs.org/marked/-/marked-12.0.2.tgz",
+      "integrity": "sha512-qXUm7e/YKFoqFPYPa3Ukg9xlI5cyAtGmyEIzMfW//m6kXwCy2Ps9DYf5ioijFKQ8qyuscrHoY04iJGctu2Kg0Q==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "marked": "bin/marked.js"
+      },
+      "engines": {
+        "node": ">= 18"
+      }
+    },
     "node_modules/minimatch": {
       "version": "3.1.5",
       "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.5.tgz",
diff --git a/package.json b/package.json
index c841021..827cd4d 100644
--- a/package.json
+++ b/package.json
@@ -66,6 +66,8 @@
     "validate:pdfa": "npx tsx scripts/validate-pdfa.ts",
     "verify:docs": "npx tsx scripts/verify-docs.ts",
     "docs:llms": "npx tsx scripts/build-llms-full.ts",
+    "docs:guides": "npx tsx scripts/build-guides.ts",
+    "docs:api": "npx tsx scripts/build-api-json.ts",
     "fonts:download": "npx tsx scripts/download-fonts.ts",
     "verify:issue": "node scripts/verify-issue.mjs",
     "lint": "eslint src/",
@@ -192,6 +194,7 @@
     "@types/node": "^22.0.0",
     "@vitest/coverage-v8": "^4.1.8",
     "eslint": "^9.0.0",
+    "marked": "12.0.2",
     "tsup": "^8.0.0",
     "tsx": "^4.22.4",
     "typescript": "^5.4.0",
diff --git a/recipes/arabic-rtl.ts b/recipes/arabic-rtl.ts
new file mode 100644
index 0000000..d14bf66
--- /dev/null
+++ b/recipes/arabic-rtl.ts
@@ -0,0 +1,40 @@
+/**
+ * Arabic text with positional shaping and right-to-left layout. The Noto
+ * Naskh Arabic data module is registered as a lazy loader, resolved with
+ * `loadFontData`, and passed through `fontEntries`; the engine embeds a
+ * subsetted CIDFont (Identity-H) and shapes the letterforms.
+ *
+ * @task Render shaped right-to-left Arabic text with an embedded Noto font
+ * @surface library
+ * @since 1.3.0
+ * @expect pages === 1
+ * @expect pdf contains '/FontFile2'
+ * @expect pdf contains '/Identity-H'
+ */
+import { buildDocumentPDFBytes, openPdf, registerFont, loadFontData } from 'pdfnative';
+import type { DocumentParams, FontEntry, FontLoader } from 'pdfnative';
+
+export async function run(): Promise<{ bytes: Uint8Array; pages: number }> {
+    // Registration lives inside run() so importing this module has no side
+    // effect on the global font registry; registerFont is idempotent for the
+    // same loader. The cast: the generated data modules predate the full
+    // FontData declaration — the runtime shape is complete.
+    registerFont('ar', (() => import('pdfnative/fonts/noto-arabic-data.js')) as unknown as FontLoader);
+    const arabic = await loadFontData('ar');
+    if (!arabic) throw new Error('Arabic font data failed to load');
+
+    const fontEntries: FontEntry[] = [{ fontData: arabic, fontRef: '/F3', lang: 'ar' }];
+    const params: DocumentParams = {
+        title: 'Arabic shaping',
+        blocks: [
+            { type: 'heading', text: 'Positional forms and ligatures', level: 1 },
+            { type: 'paragraph', text: 'السلام عليكم ورحمة الله وبركاته.' },
+            { type: 'paragraph', text: 'النص العربي يُعرض من اليمين إلى اليسار.' },
+        ],
+        footerText: 'Arabic recipe',
+        fontEntries,
+    };
+
+    const bytes = buildDocumentPDFBytes(params, { creationDate: new Date('2026-08-25T00:00:00Z') });
+    return { bytes, pages: openPdf(bytes).pageCount };
+}
diff --git a/recipes/charts-v2.ts b/recipes/charts-v2.ts
new file mode 100644
index 0000000..777b9dc
--- /dev/null
+++ b/recipes/charts-v2.ts
@@ -0,0 +1,49 @@
+/**
+ * Native vector charts (charts v2): a stacked bar chart of quarterly
+ * revenue and a scatter plot on a linear x-axis, one per page. Charts are
+ * pure PDF path operators — no rasterisation, no dependencies.
+ *
+ * @task Render stacked-bar and scatter charts as native vector graphics
+ * @surface library
+ * @since 1.7.0
+ * @expect pages === 2
+ */
+import { buildDocumentPDFBytes, openPdf } from 'pdfnative';
+import type { DocumentParams } from 'pdfnative';
+
+const params: DocumentParams = {
+    title: 'Quarterly figures',
+    blocks: [
+        {
+            type: 'chart',
+            chartType: 'stackedBar',
+            title: 'Revenue by region',
+            categories: ['Q1', 'Q2', 'Q3', 'Q4'],
+            series: [
+                { label: 'EMEA', values: [120, 135, 128, 150] },
+                { label: 'Americas', values: [90, 105, 118, 122] },
+                { label: 'APAC', values: [45, 52, 61, 70] },
+            ],
+            height: 220,
+            legend: 'bottom',
+        },
+        { type: 'pageBreak' },
+        {
+            type: 'chart',
+            chartType: 'scatter',
+            title: 'Latency against payload size',
+            xAxis: { type: 'linear', grid: true },
+            series: [
+                { label: 'Samples', values: [12, 18, 25, 31, 44], xValues: [10, 25, 50, 75, 100] },
+            ],
+            height: 220,
+            dataLabels: { decimals: 0, suffix: ' ms' },
+        },
+    ],
+    footerText: 'Quarterly figures',
+};
+
+export async function run(): Promise<{ bytes: Uint8Array; pages: number }> {
+    const bytes = buildDocumentPDFBytes(params, { creationDate: new Date('2026-08-25T00:00:00Z') });
+    return { bytes, pages: openPdf(bytes).pageCount };
+}
diff --git a/recipes/form-fill-roundtrip.ts b/recipes/form-fill-roundtrip.ts
new file mode 100644
index 0000000..c6bda0d
--- /dev/null
+++ b/recipes/form-fill-roundtrip.ts
@@ -0,0 +1,45 @@
+/**
+ * AcroForm round trip: author a form, enumerate its fields, fill a value,
+ * and read it back. A second fill with `flatten: true` stamps the
+ * appearance into the page content, where plain text extraction finds it.
+ *
+ * @task Author an AcroForm, fill it, and read the value back
+ * @surface library
+ * @since 1.6.0
+ * @expect field 'fullName' value === 'Ada Lovelace'
+ * @expect text of page 0 of the flattened document contains 'Ada Lovelace'
+ */
+import { buildDocumentPDFBytes, readFormFields, fillForm, extractText } from 'pdfnative';
+import type { DocumentParams, ParsedFormField } from 'pdfnative';
+
+const params: DocumentParams = {
+    title: 'Application',
+    blocks: [
+        { type: 'heading', text: 'Application form', level: 1 },
+        { type: 'formField', fieldType: 'text', name: 'fullName', label: 'Full name' },
+        { type: 'formField', fieldType: 'checkbox', name: 'agree', label: 'I agree to the terms' },
+        { type: 'formField', fieldType: 'dropdown', name: 'country', label: 'Country', options: ['France', 'Germany', 'Spain'] },
+    ],
+    footerText: 'Application',
+};
+
+export async function run(): Promise<{
+    bytes: Uint8Array;
+    fields: readonly ParsedFormField[];
+    filledValue: string | readonly string[] | boolean | null;
+    flattenedText: string;
+}> {
+    const blank = buildDocumentPDFBytes(params, { creationDate: new Date('2026-08-25T00:00:00Z') });
+
+    // Enumerate the authored fields, then fill by fully-qualified name.
+    const values = { fullName: 'Ada Lovelace', agree: true, country: 'Germany' } as const;
+    const filled = fillForm(blank, values);
+    const fields = readFormFields(filled);
+    const filledValue = fields.find(f => f.name === 'fullName')?.value ?? null;
+
+    // Flattening replaces the widgets with static page content.
+    const flattened = fillForm(blank, values, { flatten: true });
+    const flattenedText = extractText(flattened, { pages: [0] })[0].text;
+
+    return { bytes: filled, fields, filledValue, flattenedText };
+}
diff --git a/recipes/index.json b/recipes/index.json
new file mode 100644
index 0000000..f7cd11b
--- /dev/null
+++ b/recipes/index.json
@@ -0,0 +1,145 @@
+[
+  {
+    "file": "arabic-rtl.ts",
+    "task": "Render shaped right-to-left Arabic text with an embedded Noto font",
+    "surface": "library",
+    "since": "1.3.0",
+    "expects": [
+      "pages === 1",
+      "pdf contains '/FontFile2'",
+      "pdf contains '/Identity-H'"
+    ]
+  },
+  {
+    "file": "charts-v2.ts",
+    "task": "Render stacked-bar and scatter charts as native vector graphics",
+    "surface": "library",
+    "since": "1.7.0",
+    "expects": [
+      "pages === 2"
+    ]
+  },
+  {
+    "file": "form-fill-roundtrip.ts",
+    "task": "Author an AcroForm, fill it, and read the value back",
+    "surface": "library",
+    "since": "1.6.0",
+    "expects": [
+      "field 'fullName' value === 'Ada Lovelace'",
+      "text of page 0 of the flattened document contains 'Ada Lovelace'"
+    ]
+  },
+  {
+    "file": "invoice-pdfa2b.ts",
+    "task": "Build a PDF/A-2b invoice with an itemised line-item table",
+    "surface": "library",
+    "since": "1.6.0",
+    "expects": [
+      "pages === 1",
+      "text of page 0 contains 'Invoice'",
+      "pdfA claim === 'pdfa2b'"
+    ]
+  },
+  {
+    "file": "layout-preview.ts",
+    "task": "Preview pagination and block geometry without rendering a PDF",
+    "surface": "library",
+    "since": "1.5.0",
+    "expects": [
+      "totalPages === 2",
+      "first block type === 'heading' on page 0 with width > 0"
+    ]
+  },
+  {
+    "file": "merge-encrypted.ts",
+    "task": "Merge two PDFs and AES-encrypt the combined document",
+    "surface": "library",
+    "since": "1.6.0",
+    "expects": [
+      "pages === 2",
+      "encryption.algorithm === 'aes128'"
+    ]
+  },
+  {
+    "file": "multipage-table.ts",
+    "task": "Paginate a long table with the header row repeated on every page",
+    "surface": "library",
+    "since": "1.6.0",
+    "expects": [
+      "pages === 2",
+      "text of page 1 contains 'Description'"
+    ]
+  },
+  {
+    "file": "print-bleed.ts",
+    "task": "Prepare a print-ready page with bleed, TrimBox and printer's marks",
+    "surface": "library",
+    "since": "1.7.0",
+    "expects": [
+      "trimBox === [8.5, 8.5, 603.78, 850.39]",
+      "bleedBox === [0, 0, 612.28, 858.89]"
+    ]
+  },
+  {
+    "file": "signed-pades.ts",
+    "task": "Sign a document with a PAdES B-B (ETSI.CAdES.detached) signature",
+    "surface": "library",
+    "since": "1.7.0",
+    "expects": [
+      "signatures.length === 1",
+      "signatures[0].subFilter === 'ETSI.CAdES.detached'",
+      "signatures[0].isPlaceholder === false"
+    ]
+  },
+  {
+    "file": "streaming-large.ts",
+    "task": "Stream a 300-block document and match the buffered output byte for byte",
+    "surface": "library",
+    "since": "1.3.0",
+    "expects": [
+      "identical === true",
+      "pages === 8"
+    ]
+  },
+  {
+    "file": "text-extraction-rag.ts",
+    "task": "Extract reading-order text plus positioned runs from a document",
+    "surface": "library",
+    "since": "1.6.0",
+    "expects": [
+      "text of page 0 contains 'retrieval'",
+      "runs.length > 0",
+      "every run has numeric x, y and fontSize"
+    ]
+  },
+  {
+    "file": "toc-outline.ts",
+    "task": "Generate a linked table of contents plus automatic bookmarks",
+    "surface": "library",
+    "since": "1.6.0",
+    "expects": [
+      "pages === 3",
+      "catalog has /Outlines",
+      "text of page 0 contains 'Table of Contents'"
+    ]
+  },
+  {
+    "file": "update-metadata.ts",
+    "task": "Retitle an existing PDF via a non-destructive incremental update",
+    "surface": "library",
+    "since": "1.7.0",
+    "expects": [
+      "title === 'Quarterly report (revised)'"
+    ]
+  },
+  {
+    "file": "watermark.ts",
+    "task": "Stamp a rotated DRAFT watermark behind the page content",
+    "surface": "library",
+    "since": "1.6.0",
+    "expects": [
+      "text of page 0 contains 'Confidential clause'",
+      "text of page 0 contains 'DRAFT'"
+    ]
+  }
+]
diff --git a/recipes/invoice-pdfa2b.ts b/recipes/invoice-pdfa2b.ts
new file mode 100644
index 0000000..c7e14a4
--- /dev/null
+++ b/recipes/invoice-pdfa2b.ts
@@ -0,0 +1,57 @@
+/**
+ * Invoice as tagged PDF/A-2b — an itemised table with an embedded Latin
+ * font, so the archival claim survives validation. The creation date is
+ * pinned to keep the output byte-identical across runs.
+ *
+ * @task Build a PDF/A-2b invoice with an itemised line-item table
+ * @surface library
+ * @since 1.6.0
+ * @expect pages === 1
+ * @expect text of page 0 contains 'Invoice'
+ * @expect pdfA claim === 'pdfa2b'
+ */
+import { buildDocumentPDFBytes, openPdf, extractText } from 'pdfnative';
+import type { DocumentParams, FontData, FontEntry } from 'pdfnative';
+import * as notoSans from 'pdfnative/fonts/noto-sans-data.js';
+
+// PDF/A requires every rendered glyph to come from an embedded font
+// (ISO 19005 §6.2.11.4.1); the bundled Noto Sans data module covers Latin.
+// /F1 and /F2 are reserved by the engine — custom fontRefs start at /F3.
+const latinFont: FontEntry = {
+    fontRef: '/F3',
+    lang: 'latin',
+    fontData: notoSans as unknown as FontData,
+};
+
+const params: DocumentParams = {
+    title: 'Invoice INV-2026-0042',
+    blocks: [
+        { type: 'paragraph', text: 'Billed to: Acme Widgets Ltd, 4 Foundry Lane, Sheffield' },
+        { type: 'spacer', height: 8 },
+        {
+            type: 'table',
+            caption: 'Line items',
+            headers: ['Item', 'Quantity', 'Unit price', 'Total'],
+            rows: [
+                { cells: ['Consultancy (June)', '3 days', '650.00', '1,950.00'], type: 'debit', pointed: false },
+                { cells: ['Managed hosting', '1 month', '120.00', '120.00'], type: 'debit', pointed: false },
+                { cells: ['Support retainer', '1 month', '250.00', '250.00'], type: 'debit', pointed: false },
+            ],
+        },
+        { type: 'spacer', height: 8 },
+        { type: 'paragraph', text: 'Total due: 2,320.00 GBP within 30 days.', align: 'right' },
+    ],
+    footerText: 'Registered in England no. 01234567',
+    fontEntries: [latinFont],
+    metadata: { author: 'Accounts', subject: 'Invoice INV-2026-0042' },
+};
+
+export async function run(): Promise<{ bytes: Uint8Array; pages: number; text: string }> {
+    const bytes = buildDocumentPDFBytes(params, {
+        tagged: 'pdfa2b',
+        creationDate: new Date('2026-08-25T00:00:00Z'),
+    });
+    const pages = openPdf(bytes).pageCount;
+    const text = extractText(bytes, { pages: [0] })[0].text;
+    return { bytes, pages, text };
+}
diff --git a/recipes/layout-preview.ts b/recipes/layout-preview.ts
new file mode 100644
index 0000000..6009d90
--- /dev/null
+++ b/recipes/layout-preview.ts
@@ -0,0 +1,31 @@
+/**
+ * Dry-run layout inspection: `inspectDocumentLayout` reports how the
+ * builder will paginate and place each block — page index, x, top, width,
+ * height — without rendering a PDF. Useful for layout assertions and
+ * tooling.
+ *
+ * @task Preview pagination and block geometry without rendering a PDF
+ * @surface library
+ * @since 1.5.0
+ * @expect totalPages === 2
+ * @expect first block type === 'heading' on page 0 with width > 0
+ */
+import { inspectDocumentLayout } from 'pdfnative';
+import type { DocumentParams, LayoutInspection } from 'pdfnative';
+
+const params: DocumentParams = {
+    title: 'Layout probe',
+    blocks: [
+        { type: 'heading', text: 'Section one', level: 1 },
+        { type: 'paragraph', text: 'A paragraph measured, not rendered.' },
+        { type: 'pageBreak' },
+        { type: 'heading', text: 'Section two', level: 1 },
+        { type: 'paragraph', text: 'Placed on the second page.' },
+    ],
+    footerText: 'Layout probe',
+};
+
+export async function run(): Promise<{ inspection: LayoutInspection }> {
+    const inspection = inspectDocumentLayout(params);
+    return { inspection };
+}
diff --git a/recipes/merge-encrypted.ts b/recipes/merge-encrypted.ts
new file mode 100644
index 0000000..f6143df
--- /dev/null
+++ b/recipes/merge-encrypted.ts
@@ -0,0 +1,41 @@
+/**
+ * Merge two documents and encrypt the result in the same call.
+ * `MergeOptions.encrypt` re-protects the assembled document (AES-128
+ * here); the reader then opens it with the user password and reports the
+ * scheme. Encryption uses random salts, so the bytes differ per run while
+ * the structure stays identical.
+ *
+ * @task Merge two PDFs and AES-encrypt the combined document
+ * @surface library
+ * @since 1.6.0
+ * @expect pages === 2
+ * @expect encryption.algorithm === 'aes128'
+ */
+import { buildDocumentPDFBytes, mergePdfs, openPdf } from 'pdfnative';
+import type { DocumentParams, PdfEncryptionInfo } from 'pdfnative';
+
+function chapter(title: string, body: string): DocumentParams {
+    return {
+        title,
+        blocks: [{ type: 'paragraph', text: body }],
+        footerText: title,
+    };
+}
+
+export async function run(): Promise<{ bytes: Uint8Array; pages: number; encryption: PdfEncryptionInfo | null }> {
+    const created = new Date('2026-08-25T00:00:00Z');
+    const first = buildDocumentPDFBytes(chapter('Part one', 'Opening chapter.'), { creationDate: created });
+    const second = buildDocumentPDFBytes(chapter('Part two', 'Closing chapter.'), { creationDate: created });
+
+    const bytes = mergePdfs([first, second], {
+        encrypt: {
+            ownerPassword: 'owner-secret',
+            userPassword: 'reader-secret',
+            algorithm: 'aes128',
+            permissions: { print: true, copy: false },
+        },
+    });
+
+    const reader = openPdf(bytes, { password: 'reader-secret' });
+    return { bytes, pages: reader.pageCount, encryption: reader.encryption };
+}
diff --git a/recipes/multipage-table.ts b/recipes/multipage-table.ts
new file mode 100644
index 0000000..4e24132
--- /dev/null
+++ b/recipes/multipage-table.ts
@@ -0,0 +1,39 @@
+/**
+ * A table long enough to paginate. `repeatHeader` (the default, stated
+ * here explicitly) re-draws the header row on every continuation page,
+ * which the extracted text of page 1 confirms.
+ *
+ * @task Paginate a long table with the header row repeated on every page
+ * @surface library
+ * @since 1.6.0
+ * @expect pages === 2
+ * @expect text of page 1 contains 'Description'
+ */
+import { buildDocumentPDFBytes, openPdf, extractText } from 'pdfnative';
+import type { DocumentParams, PdfRow } from 'pdfnative';
+
+const rows: PdfRow[] = Array.from({ length: 70 }, (_, i) => ({
+    cells: [`2026-06-${String((i % 28) + 1).padStart(2, '0')}`, `Ledger entry ${i + 1}`, (100 + i).toFixed(2)],
+    type: i % 2 === 0 ? 'credit' : 'debit',
+    pointed: false,
+}));
+
+const params: DocumentParams = {
+    title: 'June ledger',
+    blocks: [
+        {
+            type: 'table',
+            headers: ['Date', 'Description', 'Amount'],
+            rows,
+            repeatHeader: true,
+        },
+    ],
+    footerText: 'June ledger',
+};
+
+export async function run(): Promise<{ bytes: Uint8Array; pages: number; page1Text: string }> {
+    const bytes = buildDocumentPDFBytes(params, { creationDate: new Date('2026-08-25T00:00:00Z') });
+    const pages = openPdf(bytes).pageCount;
+    const page1Text = extractText(bytes, { pages: [1] })[0].text;
+    return { bytes, pages, page1Text };
+}
diff --git a/recipes/print-bleed.ts b/recipes/print-bleed.ts
new file mode 100644
index 0000000..d93a902
--- /dev/null
+++ b/recipes/print-bleed.ts
@@ -0,0 +1,44 @@
+/**
+ * Print production: the page is designed at trim size plus 3 mm bleed on
+ * every side (8.5 pt), `layout.print.bleed` derives the TrimBox and
+ * BleedBox, and `marks: true` draws crop and registration marks outside
+ * the trim area. The boxes are read back from the parsed page.
+ *
+ * @task Prepare a print-ready page with bleed, TrimBox and printer's marks
+ * @surface library
+ * @since 1.7.0
+ * @expect trimBox === [8.5, 8.5, 603.78, 850.39]
+ * @expect bleedBox === [0, 0, 612.28, 858.89]
+ */
+import { buildDocumentPDFBytes, openPdf, dictGetArray } from 'pdfnative';
+
+const BLEED = 8.5; // 3 mm in points
+const TRIM_W = 595.28; // A4 trim width
+const TRIM_H = 841.89; // A4 trim height
+
+export async function run(): Promise<{
+    bytes: Uint8Array;
+    trimBox: readonly number[];
+    bleedBox: readonly number[];
+}> {
+    const bytes = buildDocumentPDFBytes(
+        {
+            title: 'Poster',
+            blocks: [{ type: 'paragraph', text: 'Background art runs to the page edge; keep copy inside the trim.' }],
+            footerText: 'Poster',
+        },
+        {
+            // Page size = trim size + 2 × bleed; backgrounds may run to the edge.
+            pageWidth: TRIM_W + 2 * BLEED,
+            pageHeight: TRIM_H + 2 * BLEED,
+            print: { bleed: BLEED, marks: true },
+            creationDate: new Date('2026-08-25T00:00:00Z'),
+        },
+    );
+
+    const page = openPdf(bytes).getPage(0);
+    const asNumbers = (name: string): number[] =>
+        (dictGetArray(page, name) ?? []).filter((v): v is number => typeof v === 'number');
+
+    return { bytes, trimBox: asNumbers('TrimBox'), bleedBox: asNumbers('BleedBox') };
+}
diff --git a/recipes/signed-pades.ts b/recipes/signed-pades.ts
new file mode 100644
index 0000000..08c2c0e
--- /dev/null
+++ b/recipes/signed-pades.ts
@@ -0,0 +1,57 @@
+/**
+ * PAdES B-B digital signature. The document is built, an invisible
+ * signature placeholder is injected (with the CAdES subFilter and the
+ * descriptive entries baked in — the /Sig dictionary's byte layout is
+ * frozen at placeholder time), then signed. The caller supplies the
+ * certificate and RSA key; pdfnative never generates key material.
+ *
+ * @task Sign a document with a PAdES B-B (ETSI.CAdES.detached) signature
+ * @surface library
+ * @since 1.7.0
+ * @expect signatures.length === 1
+ * @expect signatures[0].subFilter === 'ETSI.CAdES.detached'
+ * @expect signatures[0].isPlaceholder === false
+ */
+import { buildDocumentPDFBytes, addSignaturePlaceholder, signPdfBytes, listSignatures } from 'pdfnative';
+import type { DocumentParams, PdfSignatureInfo, RsaPrivateKey, X509Certificate } from 'pdfnative';
+
+/** Key material supplied by the caller (e.g. from a PKCS#12 store). */
+export interface SignerMaterial {
+    readonly cert: X509Certificate;
+    readonly key: RsaPrivateKey;
+    readonly chain?: readonly X509Certificate[];
+}
+
+const params: DocumentParams = {
+    title: 'Service agreement',
+    blocks: [
+        { type: 'heading', text: 'Agreement', level: 1 },
+        { type: 'paragraph', text: 'This agreement is executed by digital signature.' },
+    ],
+    footerText: 'Service agreement',
+};
+
+export async function run(signer: SignerMaterial): Promise<{ bytes: Uint8Array; signatures: readonly PdfSignatureInfo[] }> {
+    const unsigned = buildDocumentPDFBytes(params, { creationDate: new Date('2026-08-25T00:00:00Z') });
+
+    const placeheld = addSignaturePlaceholder(unsigned, {
+        fieldName: 'Author',
+        metadata: {
+            subFilter: 'ETSI.CAdES.detached',
+            reason: 'Approval',
+            location: 'London',
+            signingTime: new Date('2026-08-25T00:00:00Z'),
+        },
+    });
+
+    const bytes = signPdfBytes(placeheld, {
+        signerCert: signer.cert,
+        certChain: signer.chain,
+        rsaKey: signer.key,
+        algorithm: 'rsa-sha256',
+        profile: 'pades',
+        signingTime: new Date('2026-08-25T00:00:00Z'),
+    });
+
+    return { bytes, signatures: listSignatures(bytes) };
+}
diff --git a/recipes/streaming-large.ts b/recipes/streaming-large.ts
new file mode 100644
index 0000000..8fa5c27
--- /dev/null
+++ b/recipes/streaming-large.ts
@@ -0,0 +1,40 @@
+/**
+ * True streaming output for a large document: `buildDocumentPDFStreamTrue`
+ * yields the PDF in chunks whose concatenation is byte-identical to the
+ * buffered builder's output for the same input (creation date pinned so
+ * both builds share it).
+ *
+ * @task Stream a 300-block document and match the buffered output byte for byte
+ * @surface library
+ * @since 1.3.0
+ * @expect identical === true
+ * @expect pages === 8
+ */
+import { buildDocumentPDFBytes, buildDocumentPDFStreamTrue, concatChunks, openPdf } from 'pdfnative';
+import type { DocumentParams, DocumentBlock } from 'pdfnative';
+
+const blocks: DocumentBlock[] = Array.from({ length: 300 }, (_, i) => ({
+    type: 'paragraph' as const,
+    text: `Row ${i + 1}: measurement recorded and archived.`,
+}));
+
+const params: DocumentParams = {
+    title: 'Measurement log',
+    blocks,
+    footerText: 'Measurement log',
+};
+
+export async function run(): Promise<{ bytes: Uint8Array; pages: number; identical: boolean }> {
+    const created = new Date('2026-08-25T00:00:00Z');
+
+    const chunks: Uint8Array[] = [];
+    for await (const chunk of buildDocumentPDFStreamTrue(params, { creationDate: created }, { chunkSize: 16 * 1024 })) {
+        chunks.push(chunk);
+    }
+    const bytes = concatChunks(chunks);
+
+    const buffered = buildDocumentPDFBytes(params, { creationDate: created });
+    const identical = bytes.length === buffered.length && bytes.every((b, i) => b === buffered[i]);
+
+    return { bytes, pages: openPdf(bytes).pageCount, identical };
+}
diff --git a/recipes/text-extraction-rag.ts b/recipes/text-extraction-rag.ts
new file mode 100644
index 0000000..e0c10c5
--- /dev/null
+++ b/recipes/text-extraction-rag.ts
@@ -0,0 +1,31 @@
+/**
+ * Positioned text extraction for indexing pipelines (RAG, search). With
+ * `includeRuns` each text-showing operation is returned with its
+ * device-space origin and effective font size, alongside the
+ * reading-order text per page.
+ *
+ * @task Extract reading-order text plus positioned runs from a document
+ * @surface library
+ * @since 1.6.0
+ * @expect text of page 0 contains 'retrieval'
+ * @expect runs.length > 0
+ * @expect every run has numeric x, y and fontSize
+ */
+import { buildDocumentPDFBytes, extractText } from 'pdfnative';
+import type { DocumentParams, ExtractedPageText } from 'pdfnative';
+
+const params: DocumentParams = {
+    title: 'Corpus notes',
+    blocks: [
+        { type: 'heading', text: 'Chunking strategy', level: 1 },
+        { type: 'paragraph', text: 'Split documents into passages before retrieval; keep headings with their sections.' },
+        { type: 'paragraph', text: 'Store the run positions so citations can point back into the page.' },
+    ],
+    footerText: 'Corpus notes',
+};
+
+export async function run(): Promise<{ bytes: Uint8Array; pages: readonly ExtractedPageText[] }> {
+    const bytes = buildDocumentPDFBytes(params, { creationDate: new Date('2026-08-25T00:00:00Z') });
+    const pages = extractText(bytes, { includeRuns: true });
+    return { bytes, pages };
+}
diff --git a/recipes/toc-outline.ts b/recipes/toc-outline.ts
new file mode 100644
index 0000000..4e6b2d4
--- /dev/null
+++ b/recipes/toc-outline.ts
@@ -0,0 +1,39 @@
+/**
+ * Table of contents and bookmarks together: a `toc` block renders linked
+ * entries for every heading, while `outline: 'auto'` derives the viewer's
+ * bookmark panel from the same headings and adds /Outlines to the catalog.
+ *
+ * @task Generate a linked table of contents plus automatic bookmarks
+ * @surface library
+ * @since 1.6.0
+ * @expect pages === 3
+ * @expect catalog has /Outlines
+ * @expect text of page 0 contains 'Table of Contents'
+ */
+import { buildDocumentPDFBytes, openPdf, extractText } from 'pdfnative';
+import type { DocumentParams } from 'pdfnative';
+
+const params: DocumentParams = {
+    title: 'Operations handbook',
+    blocks: [
+        { type: 'toc', maxLevel: 2 },
+        { type: 'pageBreak' },
+        { type: 'heading', text: 'Onboarding', level: 1 },
+        { type: 'paragraph', text: 'Accounts, hardware and access requests.' },
+        { type: 'heading', text: 'First week', level: 2 },
+        { type: 'paragraph', text: 'Pairing schedule and reading list.' },
+        { type: 'pageBreak' },
+        { type: 'heading', text: 'Incident response', level: 1 },
+        { type: 'paragraph', text: 'Escalation ladder and post-incident review.' },
+    ],
+    footerText: 'Operations handbook',
+    outline: 'auto',
+};
+
+export async function run(): Promise<{ bytes: Uint8Array; pages: number; hasOutlines: boolean; tocText: string }> {
+    const bytes = buildDocumentPDFBytes(params, { creationDate: new Date('2026-08-25T00:00:00Z') });
+    const reader = openPdf(bytes);
+    const hasOutlines = reader.getCatalog().get('Outlines') !== undefined;
+    const tocText = extractText(bytes, { pages: [0] })[0].text;
+    return { bytes, pages: reader.pageCount, hasOutlines, tocText };
+}
diff --git a/recipes/update-metadata.ts b/recipes/update-metadata.ts
new file mode 100644
index 0000000..9564390
--- /dev/null
+++ b/recipes/update-metadata.ts
@@ -0,0 +1,47 @@
+/**
+ * Incremental metadata update: open an existing document, re-issue its
+ * /Info dictionary with a new title and a pinned modification date, and
+ * save. The original revision is preserved byte for byte; the reopened
+ * document reports the new title.
+ *
+ * @task Retitle an existing PDF via a non-destructive incremental update
+ * @surface library
+ * @since 1.7.0
+ * @expect title === 'Quarterly report (revised)'
+ */
+import { buildDocumentPDFBytes, openPdf, createModifier } from 'pdfnative';
+
+/** /Info strings may be UTF-16BE with a BOM; plain literals pass through. */
+function decodePdfText(raw: unknown): string {
+    if (typeof raw !== 'string') return '';
+    if (raw.length >= 2 && raw.charCodeAt(0) === 0xFE && raw.charCodeAt(1) === 0xFF) {
+        let out = '';
+        for (let i = 2; i + 1 < raw.length; i += 2) {
+            out += String.fromCharCode((raw.charCodeAt(i) << 8) | raw.charCodeAt(i + 1));
+        }
+        return out;
+    }
+    return raw;
+}
+
+export async function run(): Promise<{ bytes: Uint8Array; title: string }> {
+    const original = buildDocumentPDFBytes(
+        {
+            title: 'Quarterly report',
+            blocks: [{ type: 'paragraph', text: 'Figures under review.' }],
+            footerText: 'Quarterly report',
+        },
+        { creationDate: new Date('2026-08-25T00:00:00Z') },
+    );
+
+    const modifier = createModifier(openPdf(original));
+    modifier.updateMetadata({
+        title: 'Quarterly report (revised)',
+        modDate: new Date('2026-08-25T00:00:00Z'),
+    });
+    const bytes = modifier.save();
+
+    const info = openPdf(bytes).getInfo();
+    const title = decodePdfText(info?.get('Title'));
+    return { bytes, title };
+}
diff --git a/recipes/watermark.ts b/recipes/watermark.ts
new file mode 100644
index 0000000..76dd73c
--- /dev/null
+++ b/recipes/watermark.ts
@@ -0,0 +1,34 @@
+/**
+ * A rotated, semi-transparent text watermark behind the content of every
+ * page. The watermark never disturbs the body text: extraction still
+ * returns the paragraph, and the watermark string itself is present too.
+ *
+ * @task Stamp a rotated DRAFT watermark behind the page content
+ * @surface library
+ * @since 1.6.0
+ * @expect text of page 0 contains 'Confidential clause'
+ * @expect text of page 0 contains 'DRAFT'
+ */
+import { buildDocumentPDFBytes, extractText } from 'pdfnative';
+import type { DocumentParams } from 'pdfnative';
+
+const params: DocumentParams = {
+    title: 'Draft contract',
+    blocks: [
+        { type: 'heading', text: 'Terms', level: 1 },
+        { type: 'paragraph', text: 'Confidential clause: neither party discloses the commercial terms.' },
+    ],
+    footerText: 'Draft contract',
+};
+
+export async function run(): Promise<{ bytes: Uint8Array; text: string }> {
+    const bytes = buildDocumentPDFBytes(params, {
+        watermark: {
+            text: { text: 'DRAFT', fontSize: 60, opacity: 0.15, angle: -45 },
+            position: 'background',
+        },
+        creationDate: new Date('2026-08-25T00:00:00Z'),
+    });
+    const text = extractText(bytes, { pages: [0] })[0].text;
+    return { bytes, text };
+}
diff --git a/scripts/build-api-json.ts b/scripts/build-api-json.ts
new file mode 100644
index 0000000..212b1e5
--- /dev/null
+++ b/scripts/build-api-json.ts
@@ -0,0 +1,144 @@
+#!/usr/bin/env tsx
+/**
+ * pdfnative — api.json generator
+ * ==============================
+ * Emits `docs/assets/api.json`: the public API surface of the engine, derived
+ * mechanically from the export statements of `src/index.ts` — name, kind
+ * (value or type), source module, and, when extractable, the declaration's
+ * signature line and the first sentence of its TSDoc.
+ *
+ * Why: `dist/index.d.ts` is gitignored and never served, so an agent that has
+ * not run `npm install` has no source of truth for what pdfnative exports or
+ * what a function's shape is — the root condition for hallucinated APIs. This
+ * file is committed, served at https://pdfnative.dev/assets/api.json, listed
+ * in llms.txt, and policed by the `api-json-sync` rule of verify-docs (same
+ * pattern as llms-full.txt): regenerate with `npm run docs:api`.
+ *
+ * Honesty rule: fields that cannot be extracted mechanically are `null`,
+ * never guessed. The signature text is the declaration as written in source
+ * (first line, normalised whitespace), not a reconstruction.
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+
+function lf(text: string): string {
+    return text.replace(/\r\n/g, '\n');
+}
+
+interface ApiEntry {
+    name: string;
+    kind: 'value' | 'type';
+    module: string;
+    signature: string | null;
+    summary: string | null;
+}
+
+/** First sentence of the JSDoc block immediately above `index` in `text`. */
+function docSummaryAbove(text: string, index: number): string | null {
+    const before = text.slice(0, index);
+    // Tempered body — cannot cross a `*/` — so this can only match the block
+    // IMMEDIATELY above the declaration; a lazy [\s\S]*? here would match from
+    // the file's banner comment and attribute it to every symbol.
+    const m = before.match(/\/\*\*((?:[^*]|\*(?!\/))*)\*\/\s*$/);
+    if (!m) return null;
+    const body = m[1]
+        .split('\n')
+        .map((l) => l.replace(/^\s*\*\s?/, '').trim())
+        .filter((l) => l && !l.startsWith('@') && !/^[=\-─═]{3,}$/.test(l))
+        .join(' ');
+    const sentence = body.match(/^(.*?[.!?])(\s|$)/);
+    const summary = (sentence ? sentence[1] : body).replace(/\{@link\s+([^}|]+)(?:\|[^}]*)?\}/g, '$1').trim();
+    return summary.length > 0 ? summary.slice(0, 240) : null;
+}
+
+/** Declaration line for `name` in `text`, normalised, or null. */
+function declarationOf(text: string, name: string): { signature: string | null; summary: string | null } {
+    const re = new RegExp(
+        `export\\s+(?:async\\s+)?(?:function\\*?|const|let|class|type|interface|enum)\\s+${name}\\b[^\\n]*`,
+    );
+    const m = re.exec(text);
+    if (!m) return { signature: null, summary: null };
+    let sig = m[0];
+    // Functions: extend to the closing paren of the parameter list (may span lines).
+    if (/export\s+(?:async\s+)?function/.test(sig) && !/\)/.test(sig)) {
+        const rest = text.slice(m.index + m[0].length);
+        const upTo = rest.slice(0, rest.indexOf(')') + 1 + (rest.slice(rest.indexOf(')') + 1).match(/^[^\n{;]*/)?.[0].length ?? 0));
+        sig += upTo;
+    }
+    sig = sig.replace(/\s+/g, ' ').replace(/\s*\{\s*$/, '').trim();
+    return { signature: sig.length > 300 ? sig.slice(0, 297) + '…' : sig, summary: docSummaryAbove(text, m.index) };
+}
+
+/** Build the api.json content for the repo rooted at `root`. */
+export function buildApiJson(root: string): string {
+    const indexPath = join(root, 'src', 'index.ts');
+    const index = lf(readFileSync(indexPath, 'utf8'));
+    const entries: ApiEntry[] = [];
+    const seen = new Set<string>();
+    const moduleCache = new Map<string, string>();
+
+    const readModule = (spec: string): string => {
+        if (moduleCache.has(spec)) return moduleCache.get(spec)!;
+        const path = join(dirname(indexPath), spec.replace(/\.js$/, '.ts'));
+        const text = existsSync(path) ? lf(readFileSync(path, 'utf8')) : '';
+        moduleCache.set(spec, text);
+        return text;
+    };
+
+    // `export { a, b as c } from './x.js'` and `export type { … } from './x.js'`
+    const RE_BLOCK = /export\s*(type\s*)?\{([^}]*)\}\s*from\s*['"]([^'"]+)['"]/g;
+    let m: RegExpExecArray | null;
+    while ((m = RE_BLOCK.exec(index)) !== null) {
+        const blockIsType = Boolean(m[1]);
+        const spec = m[3];
+        const moduleText = readModule(spec);
+        for (const raw of m[2].split(',')) {
+            const piece = raw.trim();
+            if (!piece) continue;
+            const isType = blockIsType || piece.startsWith('type ');
+            const name = piece.replace(/^type\s+/, '').split(/\s+as\s+/).pop()!.trim();
+            if (!name || seen.has(name)) continue;
+            seen.add(name);
+            const { signature, summary } = declarationOf(moduleText, name);
+            entries.push({
+                name,
+                kind: isType ? 'type' : 'value',
+                module: spec.replace(/^\.\//, 'src/').replace(/\.js$/, '.ts'),
+                signature,
+                summary,
+            });
+        }
+    }
+
+    // Direct declarations in index.ts itself (if any).
+    for (const d of index.matchAll(/export\s+(?:async\s+)?(function\*?|const|let|class|type|interface|enum)\s+([A-Za-z_]\w*)/g)) {
+        const name = d[2];
+        if (seen.has(name)) continue;
+        seen.add(name);
+        const isType = d[1] === 'type' || d[1] === 'interface';
+        const { signature, summary } = declarationOf(index, name);
+        entries.push({ name, kind: isType ? 'type' : 'value', module: 'src/index.ts', signature, summary });
+    }
+
+    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+
+    const out = {
+        $comment:
+            'Public API surface of pdfnative, derived mechanically from the export statements of src/index.ts by scripts/build-api-json.ts and policed by the api-json-sync rule of scripts/verify-docs.ts. Fields that cannot be extracted mechanically are null, never guessed. Regenerate with `npm run docs:api`.',
+        package: 'pdfnative',
+        source: 'src/index.ts',
+        exportCount: entries.length,
+        exports: entries,
+    };
+    return JSON.stringify(out, null, 2) + '\n';
+}
+
+const isMain = import.meta.filename === resolve(process.argv[1] ?? '');
+if (isMain) {
+    const root = resolve(import.meta.dirname, '..');
+    const out = join(root, 'docs', 'assets', 'api.json');
+    writeFileSync(out, buildApiJson(root));
+    const count = (JSON.parse(buildApiJson(root)) as { exportCount: number }).exportCount;
+    console.log(`build-api-json: wrote ${out} (${count} exports)`);
+}
diff --git a/scripts/build-guides.ts b/scripts/build-guides.ts
new file mode 100644
index 0000000..5761036
--- /dev/null
+++ b/scripts/build-guides.ts
@@ -0,0 +1,304 @@
+#!/usr/bin/env tsx
+/**
+ * pdfnative — guide pre-renderer
+ * ==============================
+ * Renders each `docs/guides/*.md` into its companion `.html` shell, between
+ * `<!-- guide:render:start -->` / `<!-- guide:render:end -->` markers, and
+ * injects the page's schema.org JSON-LD (TechArticle + BreadcrumbList, plus
+ * FAQPage for the FAQ) between `<!-- guide:ld:start -->` / `<!-- guide:ld:end -->`
+ * markers in the head.
+ *
+ * Why: the shells used to ship an empty `<article>` filled in by `guide.js` at
+ * runtime, so any fetcher that does not execute JavaScript (most AI crawlers,
+ * social scrapers, `curl`) received the word "Loading…" instead of the guide —
+ * and the client-injected JSON-LD was equally invisible. Pre-rendering makes
+ * every canonical URL serve its full content and markup; `guide.js` detects the
+ * pre-rendered content and skips the fetch, keeping its old behaviour as a
+ * fallback for shells that have not been generated.
+ *
+ * The served site stays fully static: this script runs at authoring time, its
+ * output is committed, and `scripts/verify-docs.ts` (rule `guide-render-sync`)
+ * rebuilds everything in memory and fails the build when a committed shell is
+ * stale — the exact pattern established by `build-llms-full.ts` + `llms-sync`.
+ *
+ * Rendering is deterministic: marked@12.0.2 pinned as an exact devDependency
+ * (the same version the pages load from the CDN), LF endings, and a
+ * GitHub-style heading slugger implemented here (marked ≥ 5 no longer emits
+ * heading ids itself). Content is first-party Markdown reviewed in the repo, so
+ * no sanitiser runs at build time; the client fallback path keeps DOMPurify.
+ *
+ * Usage:
+ *   npx tsx scripts/build-guides.ts          # rewrite all docs/guides/*.html
+ */
+
+import { readFileSync, readdirSync, writeFileSync, existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { marked } from 'marked';
+
+function lf(text: string): string {
+    return text.replace(/\r\n/g, '\n');
+}
+
+marked.use({ gfm: true, breaks: false });
+
+// ── Heading slugs (GitHub convention, deterministic) ────────────────
+
+function decodeEntities(s: string): string {
+    return s
+        .replace(/&amp;/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'");
+}
+
+function stripTags(html: string): string {
+    return html.replace(/<[^>]+>/g, '');
+}
+
+export function slugify(text: string): string {
+    // GitHub convention: strip punctuation, then EVERY whitespace character
+    // becomes its own hyphen ("Flag & ZWJ" → "flag--zwj", not "flag-zwj") —
+    // existing deep links across the guides were written against that shape.
+    return decodeEntities(stripTags(text))
+        .trim()
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}\s_-]/gu, '')
+        .replace(/\s/g, '-');
+}
+
+/**
+ * Add `id` attributes and a visible anchor link to every h1–h4 in rendered
+ * Markdown output. marked emits headings on a single line, so a line-scoped
+ * regex is reliable here (this is generator output, not arbitrary HTML).
+ */
+function addHeadingAnchors(html: string): string {
+    const seen = new Map<string, number>();
+    return html.replace(/<h([1-4])>([\s\S]*?)<\/h\1>/g, (_m, level: string, inner: string) => {
+        let slug = slugify(inner) || 'section';
+        const n = seen.get(slug) ?? 0;
+        seen.set(slug, n + 1);
+        if (n > 0) slug = `${slug}-${n}`;
+        const anchor =
+            level === '1'
+                ? ''
+                : `<a class="heading-anchor" href="#${slug}" aria-label="Link to this section">#</a>`;
+        return `<h${level} id="${slug}">${inner}${anchor}</h${level}>`;
+    });
+}
+
+/** Open external links in a new tab (mirrors the old guide.js behaviour). */
+function externaliseLinks(html: string): string {
+    return html.replace(/<a href="(https?:\/\/[^"]+)">/g, '<a href="$1" target="_blank" rel="noopener">');
+}
+
+// ── Rendering ───────────────────────────────────────────────────────
+
+/** Render one guide's Markdown into the article HTML committed in its shell. */
+export function renderGuideArticle(root: string, mdName: string): string {
+    const md = lf(readFileSync(join(root, 'docs', 'guides', mdName), 'utf8'));
+    const html = marked.parse(md) as string;
+    return externaliseLinks(addHeadingAnchors(html)).trimEnd() + '\n';
+}
+
+// ── Structured data ─────────────────────────────────────────────────
+
+interface JsonLdNode {
+    [key: string]: unknown;
+}
+
+function firstHeadline(articleHtml: string): string {
+    const m = articleHtml.match(/<h1[^>]*>([\s\S]*?)<\/h1>/);
+    return m ? decodeEntities(stripTags(m[1])).trim() : '';
+}
+
+function metaContent(shell: string, name: string): string {
+    const m = shell.match(new RegExp(`<meta name="${name}" content="([^"]*)"`));
+    return m ? decodeEntities(m[1]) : '';
+}
+
+function canonicalOf(shell: string): string {
+    const m = shell.match(/<link rel="canonical" href="([^"]+)"/);
+    return m ? m[1] : '';
+}
+
+/** Plain text of a marked token tree (for FAQPage answers). */
+function tokenText(tokens: Array<Record<string, unknown>> | undefined): string {
+    if (!tokens) return '';
+    const parts: string[] = [];
+    for (const t of tokens) {
+        if (t['type'] === 'table') {
+            // A table-only answer is still an answer: serialise header and
+            // body cells (each cell is { text, tokens }).
+            const header = t['header'] as Array<Record<string, unknown>> | undefined;
+            const rows = t['rows'] as Array<Array<Record<string, unknown>>> | undefined;
+            if (header) parts.push(header.map((c) => String(c['text'] ?? '')).join(' — '));
+            for (const row of rows ?? []) {
+                parts.push(row.map((c) => String(c['text'] ?? '')).join(' — '));
+            }
+        } else if (typeof t['text'] === 'string' && !t['tokens'] && !t['items']) {
+            parts.push(t['text'] as string);
+        } else if (Array.isArray(t['items'])) {
+            parts.push(tokenText(t['items'] as Array<Record<string, unknown>>));
+        } else if (Array.isArray(t['tokens'])) {
+            parts.push(tokenText(t['tokens'] as Array<Record<string, unknown>>));
+        } else if (typeof t['text'] === 'string') {
+            parts.push(t['text'] as string);
+        }
+    }
+    return parts.join(' ').replace(/\s+/g, ' ').trim();
+}
+
+/** FAQPage mainEntity derived from the FAQ's `###` questions, via the lexer. */
+function buildFaqEntities(md: string): JsonLdNode[] {
+    const tokens = marked.lexer(md) as unknown as Array<Record<string, unknown>>;
+    const entities: JsonLdNode[] = [];
+    let question: string | null = null;
+    let answerTokens: Array<Record<string, unknown>> = [];
+    const flush = () => {
+        if (question) {
+            const answer = tokenText(answerTokens);
+            if (answer) {
+                entities.push({
+                    '@type': 'Question',
+                    name: question,
+                    acceptedAnswer: { '@type': 'Answer', text: answer },
+                });
+            }
+        }
+        question = null;
+        answerTokens = [];
+    };
+    for (const t of tokens) {
+        if (t['type'] === 'heading' && (t['depth'] as number) <= 3) {
+            flush();
+            if ((t['depth'] as number) === 3) question = String(t['text'] ?? '').trim();
+        } else if (question) {
+            answerTokens.push(t);
+        }
+    }
+    flush();
+    return entities;
+}
+
+/** The JSON-LD graph for one guide, serialised for the committed shell. */
+export function buildGuideJsonLd(root: string, mdName: string, shell: string, articleHtml: string): string {
+    const canonical = canonicalOf(shell);
+    const headline = firstHeadline(articleHtml) || metaContent(shell, 'description');
+    const graph: JsonLdNode[] = [];
+
+    graph.push({
+        '@type': 'BreadcrumbList',
+        itemListElement: [
+            { '@type': 'ListItem', position: 1, name: 'Home', item: 'https://pdfnative.dev/' },
+            { '@type': 'ListItem', position: 2, name: 'Guides', item: 'https://pdfnative.dev/guides/' },
+            { '@type': 'ListItem', position: 3, name: headline, item: canonical },
+        ],
+    });
+
+    // No dateModified: schema.org defines it as the date the WORK was last
+    // modified, and the only honest per-guide source (git history) is not
+    // available to the CI verifier's shallow checkout. Stamping the manifest's
+    // verifiedOn here claimed a modification date for guides whose Markdown
+    // had not changed — a false date is worse than no date.
+    graph.push({
+        '@type': 'TechArticle',
+        headline,
+        description: metaContent(shell, 'description'),
+        inLanguage: 'en',
+        author: { '@type': 'Organization', name: 'Nizoka', url: 'https://github.com/Nizoka' },
+        publisher: {
+            '@type': 'Organization',
+            name: 'pdfnative',
+            url: 'https://pdfnative.dev',
+            logo: { '@type': 'ImageObject', url: 'https://pdfnative.dev/assets/logo.svg' },
+        },
+        mainEntityOfPage: { '@type': 'WebPage', '@id': canonical },
+        isPartOf: { '@type': 'WebSite', name: 'pdfnative', url: 'https://pdfnative.dev' },
+    });
+
+    if (mdName === 'faq.md') {
+        const md = lf(readFileSync(join(root, 'docs', 'guides', mdName), 'utf8'));
+        const mainEntity = buildFaqEntities(md);
+        if (mainEntity.length > 0) graph.push({ '@type': 'FAQPage', mainEntity });
+    }
+
+    return JSON.stringify({ '@context': 'https://schema.org', '@graph': graph });
+}
+
+// ── Shell surgery ───────────────────────────────────────────────────
+
+const ARTICLE_RE = /(<article id="guide-content"[^>]*>)([\s\S]*?)(<\/article>)/;
+const LD_BLOCK_RE = /[ \t]*<!-- guide:ld:start -->[\s\S]*?<!-- guide:ld:end -->\n?/;
+const MD_ALT_RE = /([ \t]*)(<link rel="alternate" type="text\/markdown"[^>]*>)/;
+
+/** Return the fully updated shell for one guide (deterministic). */
+export function applyGuideRender(root: string, htmlName: string): string {
+    const path = join(root, 'docs', 'guides', htmlName);
+    let shell = lf(readFileSync(path, 'utf8'));
+
+    const article = shell.match(ARTICLE_RE);
+    if (!article) return shell;
+    const mdAttr = article[1].match(/data-md="([^"]+)"/);
+    if (!mdAttr) return shell;
+    const mdName = mdAttr[1];
+    if (!existsSync(join(root, 'docs', 'guides', mdName))) return shell;
+
+    const rendered = renderGuideArticle(root, mdName);
+
+    // Article: replace inner content, mark as pre-rendered for guide.js.
+    let openTag = article[1];
+    if (!openTag.includes('data-prerendered')) {
+        openTag = openTag.replace(/>$/, ' data-prerendered="true">');
+    }
+    shell = shell.replace(
+        ARTICLE_RE,
+        () => `${openTag}\n<!-- guide:render:start -->\n${rendered}<!-- guide:render:end -->\n  ${article[3]}`,
+    );
+
+    // Head: llms.txt discovery link, right after the markdown alternate.
+    if (!shell.includes('href="../llms.txt"')) {
+        shell = shell.replace(
+            MD_ALT_RE,
+            '$1$2\n$1<link rel="alternate" type="text/plain" href="../llms.txt" title="llms.txt — machine-readable documentation index">',
+        );
+    }
+
+    // Head: server-side JSON-LD between markers (replace any previous block).
+    const ld = buildGuideJsonLd(root, mdName, shell, rendered);
+    const ldBlock = `  <!-- guide:ld:start -->\n  <script type="application/ld+json">${ld}</script>\n  <!-- guide:ld:end -->\n`;
+    shell = shell.replace(LD_BLOCK_RE, '');
+    // Function replacer: the JSON-LD may legitimately contain `$'`/`$&`
+    // sequences (e.g. a FAQ answer about regex replacement patterns), which a
+    // string replacement would expand into silent corruption.
+    shell = shell.replace(/<\/head>/, () => `${ldBlock}</head>`);
+
+    return shell;
+}
+
+/** All guide shells that pair with a Markdown source, alphabetical. */
+export function listGuideShells(root: string): string[] {
+    const dir = join(root, 'docs', 'guides');
+    return readdirSync(dir)
+        .filter((f) => f.endsWith('.html') && f !== 'index.html')
+        .filter((f) => existsSync(join(dir, f.replace(/\.html$/, '.md'))))
+        .sort();
+}
+
+// Exact-path check: a substring test would make any importer whose argv[1]
+// merely contains "build-guides" rewrite 30 shells as an import side effect.
+const isMain = import.meta.filename === resolve(process.argv[1] ?? '');
+if (isMain) {
+    const root = resolve(import.meta.dirname, '..');
+    let changed = 0;
+    for (const htmlName of listGuideShells(root)) {
+        const path = join(root, 'docs', 'guides', htmlName);
+        const before = readFileSync(path, 'utf8');
+        const after = applyGuideRender(root, htmlName);
+        if (before !== after) {
+            writeFileSync(path, after);
+            changed++;
+        }
+    }
+    console.log(`build-guides: ${changed} shell(s) updated, ${listGuideShells(root).length} total.`);
+}
diff --git a/scripts/build-llms-full.ts b/scripts/build-llms-full.ts
index e94fe51..2389287 100644
--- a/scripts/build-llms-full.ts
+++ b/scripts/build-llms-full.ts
@@ -1,17 +1,26 @@
 #!/usr/bin/env tsx
 /**
- * pdfnative — llms-full.txt generator
- * ====================================
- * Emits `docs/llms-full.txt`: the root `llms.txt` index followed by the full
- * Markdown source of every guide, so an agent can ingest the whole
- * documentation set in a single request (the llmstxt.org "full" convention).
+ * pdfnative — llms-full.txt + llms-index.json generator
+ * =====================================================
+ * Emits two machine-readable artefacts, both committed and both policed by
+ * `scripts/verify-docs.ts` (rules `llms-sync` and `llms-index-sync`):
+ *
+ * - `docs/llms-full.txt` — the root `llms.txt` index followed by the full
+ *   Markdown source of the README and of every guide, so an agent can ingest
+ *   the whole documentation set in a single request (the llmstxt.org "full"
+ *   convention).
+ * - `docs/llms-index.json` — a per-page machine index: HTML and raw-Markdown
+ *   URL, title, summary, section anchors, and exact byte / approximate token
+ *   sizes, so an agent can decide what to fetch before spending the tokens.
+ *   Sizes live here rather than in `llms.txt` itself so no artefact has to
+ *   embed its own size (which would be circular).
  *
  * The output is deterministic (alphabetical guide order, LF line endings), so
- * `scripts/verify-docs.ts` can rebuild it in memory and fail the build when the
- * committed copy is stale.
+ * the verifier can rebuild both in memory and fail the build when a committed
+ * copy is stale.
  *
  * Usage:
- *   npx tsx scripts/build-llms-full.ts          # rewrite docs/llms-full.txt
+ *   npx tsx scripts/build-llms-full.ts    # rewrite both artefacts
  */
 
 import { readFileSync, readdirSync, writeFileSync, existsSync } from 'node:fs';
@@ -28,6 +37,12 @@ export function buildLlmsFull(root: string): string {
     const index = join(root, 'llms.txt');
     if (existsSync(index)) parts.push(lf(readFileSync(index, 'utf8')).trimEnd());
 
+    const readme = join(root, 'README.md');
+    if (existsSync(readme)) {
+        parts.push('\n\n---\n<!-- source: README.md -->\n');
+        parts.push(lf(readFileSync(readme, 'utf8')).trimEnd());
+    }
+
     const guidesDir = join(root, 'docs', 'guides');
     const guides = existsSync(guidesDir)
         ? readdirSync(guidesDir).filter((f) => f.endsWith('.md')).sort()
@@ -40,10 +55,141 @@ export function buildLlmsFull(root: string): string {
     return parts.join('') + '\n';
 }
 
-const isMain = process.argv[1] && resolve(process.argv[1]).includes('build-llms-full');
+// ── llms-recipes.txt ────────────────────────────────────────────────
+
+/**
+ * Concatenation of the executable recipe corpus (`recipes/*.ts`) — every file
+ * is CI-executed with its `@expect` assertions verified, so an agent ingesting
+ * this artefact copies code that is proven to compile and produce exactly the
+ * artefact its header describes. The cheapest high-signal fetch for a coding
+ * agent.
+ */
+export function buildLlmsRecipes(root: string): string {
+    const dir = join(root, 'recipes');
+    const parts: string[] = [
+        '# pdfnative — executable recipes',
+        '',
+        '> Every file below lives in the repository as `recipes/<name>.ts`, imports only',
+        "> from 'pdfnative', and is executed in CI with each `@expect` assertion checked",
+        '> (tests/docs/recipes.test.ts). The machine index is recipes/index.json.',
+    ];
+    const files = existsSync(dir)
+        ? readdirSync(dir).filter((f) => f.endsWith('.ts')).sort()
+        : [];
+    for (const name of files) {
+        parts.push(`\n---\n<!-- source: recipes/${name} -->\n`);
+        parts.push('```ts');
+        parts.push(lf(readFileSync(join(dir, name), 'utf8')).trimEnd());
+        parts.push('```');
+    }
+    return parts.join('\n') + '\n';
+}
+
+// ── llms-index.json ─────────────────────────────────────────────────
+
+// The ONE slugger: the same implementation that assigns heading ids in the
+// pre-rendered shells, so the anchors this index publishes always resolve.
+// (Raw-Markdown headings get their inline backticks stripped first — the
+// equivalent of the tag-stripping the renderer does on the HTML side.)
+import { slugify as slugifyHeading } from './build-guides.ts';
+function slugify(text: string): string {
+    return slugifyHeading(text.replace(/`/g, ''));
+}
+
+function approxTokens(bytes: number): number {
+    // Rough English-text heuristic (~4 bytes per token); good enough for an
+    // agent's fetch-or-not decision, and labelled as approximate in the output.
+    return Math.round(bytes / 4);
+}
+
+interface IndexPage {
+    title: string;
+    summary: string;
+    html: string;
+    markdown: string;
+    anchors: string[];
+    bytes: number;
+    approxTokens: number;
+}
+
+interface LlmsIndex {
+    $comment: string;
+    site: string;
+    artefacts: Array<{ url: string; description: string; bytes: number; approxTokens: number }>;
+    guides: IndexPage[];
+}
+
+/** Build the machine index for the repo rooted at `root`. */
+export function buildLlmsIndex(root: string): string {
+    const site = 'https://pdfnative.dev';
+    const guidesDir = join(root, 'docs', 'guides');
+    const guides = readdirSync(guidesDir).filter((f) => f.endsWith('.md')).sort();
+
+    const pages: IndexPage[] = [];
+    for (const name of guides) {
+        const md = lf(readFileSync(join(guidesDir, name), 'utf8'));
+        const title = md.match(/^# (.+)$/m)?.[1].replace(/`/g, '').trim() ?? name;
+        const quote = md.match(/^> \*\*([\s\S]*?)$/m)?.[0] ?? '';
+        const firstPara = md.split(/\n\n+/).find((p) => /^[A-Za-z[]/.test(p.trim())) ?? '';
+        const summary = (quote || firstPara)
+            .replace(/^> /gm, '')
+            .replace(/\*\*/g, '')
+            .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
+            .replace(/\s+/g, ' ')
+            .trim()
+            .slice(0, 300);
+        const anchors = [...md.matchAll(/^## (.+)$/gm)].map((m) => slugify(m[1]));
+        const bytes = Buffer.byteLength(md, 'utf8');
+        pages.push({
+            title,
+            summary,
+            html: `${site}/guides/${name.replace(/\.md$/, '.html')}`,
+            markdown: `${site}/guides/${name}`,
+            anchors,
+            bytes,
+            approxTokens: approxTokens(bytes),
+        });
+    }
+
+    const artefactList: LlmsIndex['artefacts'] = [];
+    const artefactSources: Array<[string, string, string]> = [
+        [`${site}/llms.txt`, join(root, 'llms.txt'), 'Documentation index (llmstxt.org convention).'],
+        [`${site}/agent-brief.md`, join(root, 'docs', 'agent-brief.md'), 'Compact paste-into-context briefing for coding agents: core API, verified pitfalls, surface decision tree, self-verification loop.'],
+        [`${site}/llms-full.txt`, join(root, 'docs', 'llms-full.txt'), 'Full corpus: index + README + every guide, one request.'],
+        [`${site}/llms-recipes.txt`, join(root, 'docs', 'llms-recipes.txt'), 'Executable recipes: CI-verified, copy-ready code for the most common tasks.'],
+        ['https://github.com/Nizoka/pdfnative/blob/main/README.md', join(root, 'README.md'), 'Complete feature and API reference (also embedded in llms-full.txt).'],
+    ];
+    for (const [url, path, description] of artefactSources) {
+        if (!existsSync(path)) continue;
+        // Byte size of the LF-normalised content — the size of the committed
+        // blob GitHub Pages serves. statSync().size would measure the working
+        // tree, which is CRLF-inflated on autocrlf Windows clones and would
+        // make llms-index-sync fail on a pristine checkout.
+        const bytes = Buffer.byteLength(lf(readFileSync(path, 'utf8')), 'utf8');
+        artefactList.push({ url, description, bytes, approxTokens: approxTokens(bytes) });
+    }
+
+    const out: LlmsIndex = {
+        $comment:
+            'Machine index of the pdfnative documentation. Generated by scripts/build-llms-full.ts; verified by the llms-index-sync rule of scripts/verify-docs.ts. Token counts are approximate (bytes / 4).',
+        site,
+        artefacts: artefactList,
+        guides: pages,
+    };
+    return JSON.stringify(out, null, 2) + '\n';
+}
+
+const isMain = import.meta.filename === resolve(process.argv[1] ?? '');
 if (isMain) {
     const root = resolve(import.meta.dirname, '..');
     const out = join(root, 'docs', 'llms-full.txt');
     writeFileSync(out, buildLlmsFull(root));
     console.log(`build-llms-full: wrote ${out}`);
+    const rec = join(root, 'docs', 'llms-recipes.txt');
+    writeFileSync(rec, buildLlmsRecipes(root));
+    console.log(`build-llms-full: wrote ${rec}`);
+    // Index last: it reports the other artefacts' on-disk sizes.
+    const idx = join(root, 'docs', 'llms-index.json');
+    writeFileSync(idx, buildLlmsIndex(root));
+    console.log(`build-llms-full: wrote ${idx}`);
 }
diff --git a/scripts/verify-docs.ts b/scripts/verify-docs.ts
index 238c487..1019049 100644
--- a/scripts/verify-docs.ts
+++ b/scripts/verify-docs.ts
@@ -24,7 +24,7 @@
  */
 
 import { readFileSync, readdirSync, statSync, existsSync, writeFileSync, mkdtempSync, rmSync } from 'node:fs';
-import { join, relative, resolve, dirname, posix } from 'node:path';
+import { join, relative, resolve, dirname, posix, sep } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { tmpdir } from 'node:os';
 
@@ -143,11 +143,16 @@ const MANIFEST_REL = rel(MANIFEST_PATH);
 // ── The documentation corpus ────────────────────────────────────────
 
 const DOC_FILES: string[] = [
-    // llms-full.txt is generated from files already in the corpus; scanning the
-    // concatenation would double-report every finding at useless line numbers.
+    // llms-full.txt and llms-recipes.txt are generated from files already in
+    // the corpus; scanning a concatenation would double-report every finding
+    // at line numbers nobody can act on.
     ...walk(
         join(ROOT, 'docs'),
-        (p) => /\.(html|md|js|svg|xml|txt)$/.test(p) && !p.includes('ecosystem.json') && !p.endsWith('llms-full.txt'),
+        (p) =>
+            /\.(html|md|js|svg|xml|txt)$/.test(p) &&
+            !p.includes('ecosystem.json') &&
+            !p.endsWith('llms-full.txt') &&
+            !p.endsWith('llms-recipes.txt'),
     ),
     ...['README.md', 'ROADMAP.md', 'AGENTS.md', 'CONTRIBUTING.md', 'SECURITY.md', 'llms.txt']
         .map((f) => join(ROOT, f))
@@ -158,6 +163,10 @@ const DOC_FILES: string[] = [
     // were outside the corpus.
     ...walk(join(ROOT, '.github', 'instructions'), (p) => p.endsWith('.md')),
     ...walk(join(ROOT, '.github', 'prompts'), (p) => p.endsWith('.md')),
+    // The recipes ARE documentation — executable documentation is the whole
+    // point — so their source is scanned directly (the generated llms-recipes
+    // concatenation above is excluded in their favour).
+    ...walk(join(ROOT, 'recipes'), (p) => p.endsWith('.ts')),
 ];
 
 const HTML_FILES = walk(join(ROOT, 'docs'), (p) => p.endsWith('.html'));
@@ -211,8 +220,22 @@ const actualDerived: Record<string, number> = {
           ).length
         : 0,
     learnSteps: manifest.learnPath.length,
+    recipes: existsSync(join(ROOT, 'recipes'))
+        ? readdirSync(join(ROOT, 'recipes')).filter((f) => f.endsWith('.ts')).length
+        : 0,
 };
 
+// A misspelt derived key (e.g. "recipies") would silently drop both the typo
+// AND the real counter from verification — reject unknown keys outright.
+{
+    const KNOWN_DERIVED = new Set([...Object.keys(actualDerived), 'samplePdfs', '$comment']);
+    for (const key of Object.keys(manifest.derived)) {
+        if (!KNOWN_DERIVED.has(key)) {
+            fail(MANIFEST_REL, 1, 'manifest-shape', `derived.${key} is not computed by any rule — typo, or add it to derived-counts`);
+        }
+    }
+}
+
 // samplePdfs only counts when the samples have actually been generated;
 // test-output/ is git-ignored, so an empty tree is not a failure. A partially
 // generated tree is not one either — it is the normal local state after a
@@ -411,6 +434,98 @@ if (SRC_FILES.length > 0) {
             fail(rel(file), lineOf(text, m.index), 'api-exists', `"${id}" is not declared anywhere in src/`);
         }
     }
+
+    // Generalisation of the scan above: ANY identifier written call-shaped at
+    // the very start of an inline code span — `name(…)` in Markdown, or
+    // <code>name(…)</code> in rendered/authored HTML — must exist somewhere in
+    // src/. "Exists" is the same doctrine as the build*/stream* scan: docs may
+    // name internal helpers and interface methods, so the reference set is
+    // every call- or declaration-shaped identifier in the sources, not just
+    // the exports. Anchoring on the span opener keeps prose and member calls
+    // (`mod.updateMetadata(…)`) out of scope; fenced code blocks never start
+    // an identifier with a backtick, so they stay out too. Platform globals
+    // that docs legitimately call in spans are allow-listed here.
+    const callable = new Set<string>(exported);
+    const CALLABLE_FILES = [
+        ...SRC_FILES,
+        // Repo tooling the agent docs legitimately reference (verify-issue.mjs & co).
+        ...walk(join(ROOT, 'scripts'), (p) => p.endsWith('.ts') || p.endsWith('.mjs')),
+    ];
+    for (const srcFile of CALLABLE_FILES) {
+        for (const m of read(srcFile).matchAll(/\b([A-Za-z_]\w*)\s*\(/g)) {
+            callable.add(m[1]);
+        }
+    }
+    const SPAN_GLOBALS = new Set([
+        // Platform / runtime globals docs legitimately call in spans.
+        'fetch', 'import', 'require', 'atob', 'btoa', 'structuredClone',
+        // Test-framework globals (vitest) named by the testing instructions.
+        'describe', 'it', 'test', 'expect', 'bench', 'vi',
+        'beforeAll', 'beforeEach', 'afterAll', 'afterEach',
+        // Conventional-commit prefixes written call-shaped (`feat(scope):`).
+        'feat', 'fix', 'chore', 'refactor', 'perf', 'style', 'ci',
+        // Companion-package exports named in ecosystem prose outside the
+        // dedicated companion guides (their drift is a companion-repo concern,
+        // caught by the weekly --online npm-drift run, not this offline scan).
+        'validateGovernanceDraft', // pdfnative-cli
+        'docSpecSchema', // pdfnative-react (README ecosystem row)
+        'lintDocument', // pdfnative-react (cited by the PDF/A guide)
+    ]);
+    // Guides DEDICATED to a companion package document that package's API
+    // throughout — checking those names against this repo's src/ would be a
+    // category error, so they are out of this scan's scope entirely.
+    const SPAN_SKIP = /docs[\\/](?:guides|playgrounds)[\\/](react|cli|mcp)\.(md|html)$/;
+    // Companion-package exports are legitimate wherever the docs corpus shows
+    // them imported from that package (`import { usePdf } from
+    // 'pdfnative-react'`) — the import example is itself the documentation
+    // that the name exists there.
+    const companionImported = new Set<string>();
+    for (const file of DOC_FILES) {
+        for (const m of read(file).matchAll(/import\s*(?:type\s*)?\{([^}]*)\}\s*from\s*['"]pdfnative-[\w-]+['"]/g)) {
+            for (const raw of m[1].split(',')) {
+                const name = raw.replace(/^type\s+/, '').split(/\s+as\s+/)[0].trim();
+                if (name) companionImported.add(name);
+            }
+        }
+    }
+    // In Markdown a backtick opens a code span; in HTML a backtick is almost
+    // always a JS template literal inside an inline <script>, so only the
+    // literal <code> opener counts there.
+    const SPAN_CALL_MD = /(?:`|<code>)([A-Za-z_]\w*)\(/g;
+    const SPAN_CALL_HTML = /<code>([A-Za-z_]\w*)\(/g;
+    for (const file of DOC_FILES) {
+        if (SPAN_SKIP.test(file)) continue;
+        const SPAN_CALL = file.endsWith('.html') ? SPAN_CALL_HTML : SPAN_CALL_MD;
+        const text = read(file);
+        const lines = text.split(/\r?\n/);
+        SPAN_CALL.lastIndex = 0;
+        let m: RegExpExecArray | null;
+        while ((m = SPAN_CALL.exec(text)) !== null) {
+            const id = m[1];
+            if (callable.has(id) || SPAN_GLOBALS.has(id) || companionImported.has(id)) continue;
+            if (Object.prototype.hasOwnProperty.call(manifest.apiDenylist, id)) continue;
+            const line = lineOf(text, m.index);
+            if (isSuppressed(lines, line, 'api-exists')) continue;
+            fail(rel(file), line, 'api-exists', `"${id}()" is not declared anywhere in src/`);
+        }
+    }
+}
+
+// ── Rule: api-json-sync ─────────────────────────────────────────────
+
+/**
+ * `docs/assets/api.json` is the served, machine-readable export surface —
+ * the substitute for the gitignored `dist/index.d.ts` that agents cannot
+ * otherwise reach. A stale copy teaches last release's API, so it is policed
+ * like every other generated artefact: rebuilt in memory and compared.
+ */
+const { buildApiJson } = await import('./build-api-json.ts');
+
+const API_JSON = join(ROOT, 'docs', 'assets', 'api.json');
+if (!existsSync(API_JSON)) {
+    fail('docs/assets/api.json', 1, 'api-json-sync', 'missing — generate it with `npm run docs:api`');
+} else if (read(API_JSON).replace(/\r\n/g, '\n') !== buildApiJson(ROOT)) {
+    fail('docs/assets/api.json', 1, 'api-json-sync', 'stale — regenerate with `npm run docs:api`');
 }
 
 // ── Rule: jsonld-version ────────────────────────────────────────────
@@ -573,7 +688,9 @@ const SITEMAP = join(ROOT, 'docs', 'sitemap.xml');
 if (existsSync(SITEMAP)) {
     const xml = read(SITEMAP);
     const locs = [...xml.matchAll(/<loc>\s*([^<]+?)\s*<\/loc>/g)].map((m) => m[1]);
-    const today = new Date().toISOString().slice(0, 10);
+    // +1 day of tolerance: a contributor east of UTC editing after their
+    // local midnight writes a lastmod the UTC runner would call "future".
+    const today = new Date(Date.now() + 24 * 3600 * 1000).toISOString().slice(0, 10);
 
     for (const m of xml.matchAll(/<lastmod>\s*([^<]+?)\s*<\/lastmod>/g)) {
         const value = m[1];
@@ -931,6 +1048,152 @@ if (!existsSync(LLMS_FULL)) {
     fail('docs/llms-full.txt', 1, 'llms-sync', 'stale — regenerate with `npx tsx scripts/build-llms-full.ts`');
 }
 
+const { buildLlmsRecipes } = await import('./build-llms-full.ts');
+const LLMS_RECIPES = join(ROOT, 'docs', 'llms-recipes.txt');
+if (!existsSync(LLMS_RECIPES)) {
+    fail('docs/llms-recipes.txt', 1, 'llms-sync', 'missing — generate it with `npm run docs:llms`');
+} else if (read(LLMS_RECIPES).replace(/\r\n/g, '\n') !== buildLlmsRecipes(ROOT)) {
+    fail('docs/llms-recipes.txt', 1, 'llms-sync', 'stale — regenerate with `npm run docs:llms`');
+}
+
+// ── Rule: error-parity ──────────────────────────────────────────────
+
+/**
+ * `docs/data/errors.json` is the served registry of the engine's diagnostic
+ * codes. Two-way check against reality: every `PDFA_*` token the docs mention
+ * must exist both in the registry and in src/, and every registry entry must
+ * exist in src/ — a registry entry for a code the engine no longer emits
+ * teaches agents a ghost.
+ */
+{
+    const ERRORS_JSON = join(ROOT, 'docs', 'data', 'errors.json');
+    if (!existsSync(ERRORS_JSON)) {
+        fail('docs/data/errors.json', 1, 'error-parity', 'missing — the engine diagnostic registry must be served');
+    } else {
+        const registry = JSON.parse(read(ERRORS_JSON)) as { diagnostics: Array<{ code: string }> };
+        const registered = new Set(registry.diagnostics.map((d) => d.code));
+        const srcCodes = new Set<string>();
+        for (const f of walk(join(ROOT, 'src'), (p) => p.endsWith('.ts'))) {
+            for (const m of read(f).matchAll(/\bPDFA_[A-Z_]+\b/g)) srcCodes.add(m[0]);
+        }
+        for (const code of registered) {
+            if (!srcCodes.has(code)) {
+                fail('docs/data/errors.json', 1, 'error-parity', `registry lists "${code}" but src/ never emits it`);
+            }
+        }
+        // Third direction: a code the engine emits must be in the served
+        // registry, or agents learn an incomplete error surface.
+        for (const code of srcCodes) {
+            if (!registered.has(code)) {
+                fail('docs/data/errors.json', 1, 'error-parity', `src/ emits "${code}" but the served registry does not list it`);
+            }
+        }
+        for (const file of DOC_FILES) {
+            const text = read(file);
+            for (const m of text.matchAll(/\bPDFA_[A-Z_]+\b/g)) {
+                if (registered.has(m[0])) continue;
+                fail(rel(file), lineOf(text, m.index!), 'error-parity', `diagnostic "${m[0]}" is not in docs/data/errors.json`);
+            }
+        }
+    }
+}
+
+// ── Rule: anchor-parity ─────────────────────────────────────────────
+
+/**
+ * `internal-links` deliberately strips `#fragments` — so a deep link to a
+ * renamed section rots invisibly, which matters twice as much now that AI
+ * answers cite section-level URLs. With every guide pre-rendered, anchors are
+ * plain `id="…"` attributes in committed HTML: every internal link that
+ * carries a fragment must point at an id that exists in its target page.
+ * Links written against a `.md` target are checked against the paired `.html`
+ * (that is where the pre-rendered ids live).
+ */
+{
+    const anchorCache = new Map<string, Set<string> | null>();
+    const anchorsOf = (absPath: string): Set<string> | null => {
+        if (anchorCache.has(absPath)) return anchorCache.get(absPath)!;
+        if (!existsSync(absPath) || !absPath.endsWith('.html')) {
+            anchorCache.set(absPath, null);
+            return null;
+        }
+        const ids = new Set<string>();
+        for (const m of read(absPath).matchAll(/\bid=["']([^"']+)["']/g)) ids.add(m[1]);
+        anchorCache.set(absPath, ids);
+        return ids;
+    };
+    // Fragment may start with a digit: numbered headings ("## 1. Render…")
+    // slug to ids like "1-render-a-document".
+    const LINK_WITH_FRAG = /(?:\]\(|href=["'])([^)"'#\s]*)#([\p{L}\p{N}][\p{L}\p{N}_-]*)/gu;
+    for (const file of DOC_FILES) {
+        if (!file.endsWith('.md') && !file.endsWith('.html')) continue;
+        const text = read(file);
+        const lines = text.split(/\r?\n/);
+        LINK_WITH_FRAG.lastIndex = 0;
+        let m: RegExpExecArray | null;
+        while ((m = LINK_WITH_FRAG.exec(text)) !== null) {
+            let target = m[1];
+            const frag = m[2];
+            if (/^[a-z][a-z0-9+.-]*:/i.test(target)) continue; // external / mailto
+            if (target === '') target = rel(file).split('/').pop()!; // same-page link
+            let abs = resolve(dirname(file), target);
+            if (abs.endsWith(sep)) abs = join(abs, 'index.html');
+            if (abs.endsWith('.md')) abs = abs.slice(0, -3) + '.html';
+            const ids = anchorsOf(abs);
+            if (ids === null) continue; // non-HTML target or missing file: internal-links' turf
+            if (ids.has(frag)) continue;
+            const line = lineOf(text, m.index);
+            if (isSuppressed(lines, line, 'anchor-parity')) continue;
+            fail(rel(file), line, 'anchor-parity', `link fragment "#${frag}" has no matching id in ${rel(abs)}`);
+        }
+    }
+}
+
+// ── Rule: llms-index-sync ───────────────────────────────────────────
+
+/**
+ * `docs/llms-index.json` tells an agent what every page costs before it
+ * spends the tokens (URLs, anchors, exact bytes). A stale index quietly
+ * advertises last release's sizes and anchors, so it is policed exactly like
+ * `llms-full.txt`. Runs after llms-sync: the index reports the on-disk size
+ * of llms-full.txt, which the previous rule has just proven fresh.
+ */
+const { buildLlmsIndex } = await import('./build-llms-full.ts');
+
+const LLMS_INDEX = join(ROOT, 'docs', 'llms-index.json');
+if (!existsSync(LLMS_INDEX)) {
+    fail('docs/llms-index.json', 1, 'llms-index-sync', 'missing — generate it with `npm run docs:llms`');
+} else if (read(LLMS_INDEX).replace(/\r\n/g, '\n') !== buildLlmsIndex(ROOT)) {
+    fail('docs/llms-index.json', 1, 'llms-index-sync', 'stale — regenerate with `npm run docs:llms`');
+}
+
+// ── Rule: guide-render-sync ─────────────────────────────────────────
+
+/**
+ * Guide shells carry the pre-rendered HTML of their Markdown source (between
+ * `guide:render` markers) plus server-side JSON-LD, so crawlers that do not
+ * execute JavaScript — most AI fetchers — receive the full guide instead of
+ * "Loading…". The renderer is `scripts/build-guides.ts`; this rule rebuilds
+ * every shell in memory and fails when a committed copy is stale, exactly as
+ * `llms-sync` polices `llms-full.txt`. A shell whose article has never been
+ * generated (no marker) fails too: an empty article is the defect this whole
+ * mechanism exists to remove.
+ */
+const { applyGuideRender, listGuideShells } = await import('./build-guides.ts');
+
+for (const htmlName of listGuideShells(ROOT)) {
+    const relPath = `docs/guides/${htmlName}`;
+    const committed = read(join(ROOT, 'docs', 'guides', htmlName)).replace(/\r\n/g, '\n');
+    if (!committed.includes('<!-- guide:render:start -->')) {
+        fail(relPath, 1, 'guide-render-sync', 'article is not pre-rendered — run `npm run docs:guides`');
+        continue;
+    }
+    const expected = applyGuideRender(ROOT, htmlName);
+    if (committed !== expected) {
+        fail(relPath, 1, 'guide-render-sync', 'stale — the committed render differs from its Markdown source; run `npm run docs:guides`');
+    }
+}
+
 // ── Rule: playground-syntax ─────────────────────────────────────────
 
 /**
@@ -1049,6 +1312,11 @@ const OFFLINE_RULES = [
     'bench-parity',
     'contrast',
     'llms-sync',
+    'llms-index-sync',
+    'error-parity',
+    'anchor-parity',
+    'guide-render-sync',
+    'api-json-sync',
     'playground-syntax',
 ] as const;
 
diff --git a/tests/docs/recipes.test.ts b/tests/docs/recipes.test.ts
new file mode 100644
index 0000000..d698287
--- /dev/null
+++ b/tests/docs/recipes.test.ts
@@ -0,0 +1,247 @@
+/**
+ * Executable-documentation recipes (`recipes/`).
+ *
+ * Every recipe is a standalone consumer example importing only from
+ * 'pdfnative' (aliased to `src/index.ts` in vitest.config.ts). Each file
+ * declares its machine-checkable outcomes as `@expect` header lines; this
+ * suite runs every recipe and asserts each declared outcome with the
+ * library's own readers (openPdf / extractText / listSignatures / the
+ * layout inspector), so a recipe that drifts from the engine fails loudly
+ * rather than rotting as prose. A final test keeps `recipes/index.json`
+ * in lock-step with the headers on disk.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { createMockPki } from '../../scripts/helpers/mock-pki.js';
+
+// Dynamic node imports via string indirection (tests avoid @types/node).
+async function nodeFs(): Promise<{
+    readFileSync(p: string, enc: 'utf8'): string;
+    readdirSync(p: string): string[];
+}> {
+    return (await import('node:' + 'fs')) as never;
+}
+
+const RECIPES_DIR = `${import.meta.dirname}/../../recipes`;
+
+function latin1(bytes: Uint8Array): string {
+    let s = '';
+    for (let i = 0; i < bytes.length; i++) s += String.fromCharCode(bytes[i]);
+    return s;
+}
+
+// ── The recipes ──────────────────────────────────────────────────────
+
+describe('recipe: invoice-pdfa2b', () => {
+    // The bundled Noto Sans data module is large; its first import dominates
+    // the runtime and slows further under coverage instrumentation.
+    it('builds a one-page PDF/A-2b invoice whose text and claim check out', { timeout: 60_000 }, async () => {
+        const { run } = await import('../../recipes/invoice-pdfa2b.js');
+        const { bytes, pages, text } = await run();
+        expect(pages).toBe(1);
+        expect(text).toContain('Invoice');
+        const pdf = latin1(bytes);
+        expect(pdf).toContain('<pdfaid:part>2</pdfaid:part>');
+        expect(pdf).toContain('<pdfaid:conformance>B</pdfaid:conformance>');
+    });
+});
+
+describe('recipe: multipage-table', () => {
+    it('paginates to two pages and repeats the header row on page 1', async () => {
+        const { run } = await import('../../recipes/multipage-table.js');
+        const { pages, page1Text } = await run();
+        expect(pages).toBe(2);
+        expect(page1Text).toContain('Description');
+    });
+});
+
+describe('recipe: arabic-rtl', () => {
+    it('embeds a subsetted Identity-H Arabic font on a single page', { timeout: 60_000 }, async () => {
+        const { run } = await import('../../recipes/arabic-rtl.js');
+        const { bytes, pages } = await run();
+        expect(pages).toBe(1);
+        const pdf = latin1(bytes);
+        expect(pdf).toContain('/FontFile2');
+        expect(pdf).toContain('/Identity-H');
+    });
+});
+
+describe('recipe: signed-pades', () => {
+    it('produces exactly one signed ETSI.CAdES.detached signature', async () => {
+        const { run } = await import('../../recipes/signed-pades.js');
+        const pki = createMockPki();
+        const { signatures } = await run({
+            cert: pki.signerCert,
+            key: pki.signerKey,
+            chain: [pki.rootCert],
+        });
+        expect(signatures.length).toBe(1);
+        expect(signatures[0].subFilter).toBe('ETSI.CAdES.detached');
+        expect(signatures[0].isPlaceholder).toBe(false);
+    });
+});
+
+describe('recipe: form-fill-roundtrip', () => {
+    it('fills the text field and finds the value in the flattened page text', async () => {
+        const { run } = await import('../../recipes/form-fill-roundtrip.js');
+        const { fields, filledValue, flattenedText } = await run();
+        expect(fields.map(f => f.name)).toContain('fullName');
+        expect(filledValue).toBe('Ada Lovelace');
+        expect(flattenedText).toContain('Ada Lovelace');
+    });
+});
+
+describe('recipe: text-extraction-rag', () => {
+    it('returns reading-order text plus positioned runs', async () => {
+        const { run } = await import('../../recipes/text-extraction-rag.js');
+        const { pages } = await run();
+        expect(pages[0].text).toContain('retrieval');
+        const runs = pages[0].runs ?? [];
+        expect(runs.length).toBeGreaterThan(0);
+        for (const r of runs) {
+            expect(Number.isFinite(r.x)).toBe(true);
+            expect(Number.isFinite(r.y)).toBe(true);
+            expect(Number.isFinite(r.fontSize)).toBe(true);
+        }
+    });
+});
+
+describe('recipe: merge-encrypted', () => {
+    it('merges two documents into an AES-128 protected two-pager', { timeout: 60_000 }, async () => {
+        const { run } = await import('../../recipes/merge-encrypted.js');
+        const { pages, encryption } = await run();
+        expect(pages).toBe(2);
+        expect(encryption?.algorithm).toBe('aes128');
+    });
+});
+
+describe('recipe: charts-v2', () => {
+    it('renders the stacked-bar and scatter charts across two pages', async () => {
+        const { run } = await import('../../recipes/charts-v2.js');
+        const { pages } = await run();
+        expect(pages).toBe(2);
+    });
+});
+
+describe('recipe: print-bleed', () => {
+    it('derives TrimBox and BleedBox from the bleed shorthand', async () => {
+        const { run } = await import('../../recipes/print-bleed.js');
+        const { bytes, trimBox, bleedBox } = await run();
+        expect(trimBox).toEqual([8.5, 8.5, 603.78, 850.39]);
+        expect(bleedBox).toEqual([0, 0, 612.28, 858.89]);
+        expect(latin1(bytes)).toContain('/TrimBox');
+    });
+});
+
+describe('recipe: toc-outline', () => {
+    it('renders a linked TOC page and a catalog /Outlines tree', async () => {
+        const { run } = await import('../../recipes/toc-outline.js');
+        const { pages, hasOutlines, tocText } = await run();
+        expect(pages).toBe(3);
+        expect(hasOutlines).toBe(true);
+        expect(tocText).toContain('Table of Contents');
+    });
+});
+
+describe('recipe: watermark', () => {
+    it('keeps the body text extractable alongside the watermark', async () => {
+        const { run } = await import('../../recipes/watermark.js');
+        const { text } = await run();
+        expect(text).toContain('Confidential clause');
+        expect(text).toContain('DRAFT');
+    });
+});
+
+describe('recipe: streaming-large', () => {
+    it('streams chunks whose concatenation matches the buffered build', { timeout: 60_000 }, async () => {
+        const { run } = await import('../../recipes/streaming-large.js');
+        const { pages, identical } = await run();
+        expect(identical).toBe(true);
+        expect(pages).toBe(8);
+    });
+});
+
+describe('recipe: layout-preview', () => {
+    it('reports two pages and the first block geometry without rendering', async () => {
+        const { run } = await import('../../recipes/layout-preview.js');
+        const { inspection } = await run();
+        expect(inspection.totalPages).toBe(2);
+        const first = inspection.pages[0].blocks[0];
+        expect(first.type).toBe('heading');
+        expect(first.page).toBe(0);
+        expect(first.width).toBeGreaterThan(0);
+    });
+});
+
+describe('recipe: update-metadata', () => {
+    it('re-reads the incrementally updated title', async () => {
+        const { run } = await import('../../recipes/update-metadata.js');
+        const { title } = await run();
+        expect(title).toBe('Quarterly report (revised)');
+    });
+});
+
+// ── Index consistency ────────────────────────────────────────────────
+
+interface IndexEntry {
+    readonly file: string;
+    readonly task: string;
+    readonly surface: string;
+    readonly since: string;
+    readonly expects: readonly string[];
+}
+
+/** Parse the structured `@tag` lines out of a recipe's header comment. */
+function parseHeader(source: string): { task: string; surface: string; since: string; expects: string[] } {
+    const tags: { task?: string; surface?: string; since?: string; expects: string[] } = { expects: [] };
+    const re = /^\s*\*\s*@(task|surface|since|expect)\s+(.+?)\s*$/gm;
+    for (let m = re.exec(source); m !== null; m = re.exec(source)) {
+        const [, tag, value] = m;
+        if (tag === 'expect') tags.expects.push(value);
+        else tags[tag as 'task' | 'surface' | 'since'] = value;
+    }
+    expect(tags.task, 'header must carry @task').toBeDefined();
+    expect(tags.surface, 'header must carry @surface').toBeDefined();
+    expect(tags.since, 'header must carry @since').toBeDefined();
+    return { task: tags.task!, surface: tags.surface!, since: tags.since!, expects: tags.expects };
+}
+
+describe('recipes/index.json', () => {
+    it('mirrors the header tags of every recipe on disk, with none missing', async () => {
+        const fs = await nodeFs();
+        const index = JSON.parse(fs.readFileSync(`${RECIPES_DIR}/index.json`, 'utf8')) as IndexEntry[];
+
+        const onDisk = fs.readdirSync(RECIPES_DIR).filter(f => f.endsWith('.ts')).sort();
+        expect(index.map(e => e.file)).toEqual(onDisk);
+        // The count comes from the manifest, never a literal: derived.recipes
+        // is what verify-docs asserts against the tree.
+        const manifest = JSON.parse(
+            fs.readFileSync(`${RECIPES_DIR}/../docs/assets/ecosystem.json`, 'utf8'),
+        ) as { derived: { recipes: number } };
+        expect(index.length).toBe(manifest.derived.recipes);
+
+        for (const entry of index) {
+            const source = fs.readFileSync(`${RECIPES_DIR}/${entry.file}`, 'utf8');
+            const header = parseHeader(source);
+            expect(header.task, `${entry.file}: @task`).toBe(entry.task);
+            expect(header.surface, `${entry.file}: @surface`).toBe(entry.surface);
+            expect(header.since, `${entry.file}: @since`).toBe(entry.since);
+            expect(header.expects, `${entry.file}: @expect lines`).toEqual([...entry.expects]);
+        }
+    });
+
+    it('recipes import only from pdfnative — never from src or relative paths', async () => {
+        const fs = await nodeFs();
+        const files = fs.readdirSync(RECIPES_DIR).filter(f => f.endsWith('.ts'));
+        for (const file of files) {
+            const source = fs.readFileSync(`${RECIPES_DIR}/${file}`, 'utf8');
+            const re = /from\s+'([^']+)'/g;
+            for (let m = re.exec(source); m !== null; m = re.exec(source)) {
+                expect(
+                    m[1] === 'pdfnative' || m[1].startsWith('pdfnative/'),
+                    `${file} imports '${m[1]}'`,
+                ).toBe(true);
+            }
+        }
+    });
+});
diff --git a/tests/docs/verify-docs.test.ts b/tests/docs/verify-docs.test.ts
index 87b200c..9a75b74 100644
--- a/tests/docs/verify-docs.test.ts
+++ b/tests/docs/verify-docs.test.ts
@@ -1,6 +1,6 @@
 import { describe, it, expect } from 'vitest';
 import { execFileSync } from 'node:child_process';
-import { readFileSync, writeFileSync, mkdtempSync, rmSync, cpSync, existsSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdtempSync, rmSync, cpSync, existsSync, symlinkSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { tmpdir } from 'node:os';
 
@@ -30,7 +30,10 @@ interface Run {
 function runVerifier(root: string): Run {
     const script = root === ROOT ? SCRIPT : join(root, 'scripts', 'verify-docs.ts');
     try {
-        const output = execFileSync('npx', ['tsx', script], {
+        // shell:true (required for npx.cmd on Windows) does not quote args —
+        // a temp path with spaces or `&` would break the command line.
+        const scriptArg = process.platform === 'win32' ? JSON.stringify(script) : script;
+        const output = execFileSync('npx', ['tsx', scriptArg], {
             cwd: ROOT,
             encoding: 'utf8',
             stdio: ['ignore', 'pipe', 'pipe'],
@@ -49,7 +52,7 @@ function runVerifier(root: string): Run {
  */
 function makeSandbox(): string {
     const dir = mkdtempSync(join(tmpdir(), 'pdfnative-verify-'));
-    for (const entry of ['docs', 'src', 'tests', 'scripts', 'bench', '.github']) {
+    for (const entry of ['docs', 'src', 'tests', 'scripts', 'bench', 'recipes', '.github']) {
         const from = join(ROOT, entry);
         if (existsSync(from)) cpSync(from, join(dir, entry), { recursive: true });
     }
@@ -59,6 +62,9 @@ function makeSandbox(): string {
         const from = join(ROOT, file);
         if (existsSync(from)) cpSync(from, join(dir, file));
     }
+    // scripts/build-guides.ts imports `marked` from node_modules; link the real
+    // install into the sandbox (junction: no admin rights needed on Windows).
+    symlinkSync(join(ROOT, 'node_modules'), join(dir, 'node_modules'), 'junction');
     return dir;
 }
 
@@ -79,6 +85,19 @@ describe('verify-docs', () => {
     describe('each rule reports the defect it exists for', () => {
         let sandbox: string;
 
+        // The control every perturbation test depends on: a sandbox that has
+        // NOT been perturbed must be clean, otherwise the `status === 1`
+        // assertions below are satisfied by pre-existing noise instead of by
+        // the rule under test (which is exactly how a missing `recipes/` copy
+        // once made every negative test vacuous).
+        it('an unperturbed sandbox is clean', () => {
+            withSandbox((dir) => {
+                const run = runVerifier(dir);
+                expect(run.output).toContain('rules passed');
+                expect(run.status).toBe(0);
+            });
+        }, 120_000);
+
         function withSandbox(fn: (dir: string) => void): void {
             sandbox = makeSandbox();
             try {
@@ -91,10 +110,10 @@ describe('verify-docs', () => {
         it('stale-token compares counts for equality, not against a blocklist', () => {
             withSandbox((dir) => {
                 // A value that no blocklist would have enumerated.
-                patch(dir, 'docs/guides/mcp.md', '**24 tools**', '**25 tools**');
+                patch(dir, 'docs/guides/mcp.md', '**28 tools**', '**29 tools**');
                 const run = runVerifier(dir);
                 expect(run.output).toContain('stale-token');
-                expect(run.output).toContain('the manifest says 24');
+                expect(run.output).toContain('the manifest says 28');
                 expect(run.status).toBe(1);
             });
         }, 120_000);
@@ -125,6 +144,55 @@ describe('verify-docs', () => {
             });
         }, 120_000);
 
+        it('guide-render-sync catches a shell whose Markdown source moved on', () => {
+            withSandbox((dir) => {
+                // Edit the .md without regenerating the pre-rendered shell.
+                patch(dir, 'docs/guides/charts.md', '# Charts (native vector)', '# Charts (native vector, perturbed)');
+                const run = runVerifier(dir);
+                expect(run.output).toContain('guide-render-sync');
+                expect(run.output).toContain('docs/guides/charts.html');
+                expect(run.status).toBe(1);
+            });
+        }, 120_000);
+
+        it('error-parity rejects a diagnostic code the docs invent', () => {
+            withSandbox((dir) => {
+                patch(dir, 'docs/guides/pdfa.md', 'PDFA_NO_FONT_ENTRIES', 'PDFA_IMAGINARY_CODE');
+                const run = runVerifier(dir);
+                expect(run.output).toContain('error-parity');
+                expect(run.output).toContain('PDFA_IMAGINARY_CODE');
+                expect(run.status).toBe(1);
+            });
+        }, 120_000);
+
+        it('anchor-parity catches a deep link to a renamed section', () => {
+            withSandbox((dir) => {
+                patch(dir, 'docs/guides/streaming.md', '#streaming-merge--split', '#streaming-merge--split-renamed');
+                const run = runVerifier(dir);
+                expect(run.output).toContain('anchor-parity');
+                expect(run.output).toContain('streaming-merge--split-renamed');
+                expect(run.status).toBe(1);
+            });
+        }, 120_000);
+
+        it('api-json-sync catches a stale API surface', () => {
+            withSandbox((dir) => {
+                patch(dir, 'docs/assets/api.json', '"package": "pdfnative"', '"package": "perturbed"');
+                const run = runVerifier(dir);
+                expect(run.output).toContain('api-json-sync');
+                expect(run.status).toBe(1);
+            });
+        }, 120_000);
+
+        it('llms-index-sync catches a stale machine index', () => {
+            withSandbox((dir) => {
+                patch(dir, 'docs/llms-index.json', '"site": "https://pdfnative.dev"', '"site": "https://perturbed.example"');
+                const run = runVerifier(dir);
+                expect(run.output).toContain('llms-index-sync');
+                expect(run.status).toBe(1);
+            });
+        }, 120_000);
+
         it('bench-parity ties the homepage figures to bench/RESULTS.md', () => {
             withSandbox((dir) => {
                 patch(dir, 'docs/index.html', '<span class="bench-value">~98 ms</span>', '<span class="bench-value">~33 ms</span>');
diff --git a/tsconfig.test.json b/tsconfig.test.json
index 3096f7d..5e3b07d 100644
--- a/tsconfig.test.json
+++ b/tsconfig.test.json
@@ -19,8 +19,12 @@
     "noUnusedParameters": true,
     "noFallthroughCasesInSwitch": true,
     "noEmit": true,
-    "exactOptionalPropertyTypes": false
+    "exactOptionalPropertyTypes": false,
+    "paths": {
+      "pdfnative": ["./src/index.ts"],
+      "pdfnative/fonts/*": ["./fonts/*"]
+    }
   },
-  "include": ["src/**/*.ts", "tests/**/*.ts"],
+  "include": ["src/**/*.ts", "tests/**/*.ts", "recipes/**/*.ts"],
   "exclude": ["node_modules", "dist", "tools", "scripts"]
 }
diff --git a/vitest.config.ts b/vitest.config.ts
index c75f279..859d746 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -1,32 +1,49 @@
-import { defineConfig } from 'vitest/config';
-
-export default defineConfig({
-    test: {
-        include: ['tests/**/*.test.ts'],
-        environment: 'node',
-        globals: false,
-        coverage: {
-            provider: 'v8',
-            include: ['src/**/*.ts'],
-            exclude: [
-                'src/worker/pdf-worker.ts',
-                'src/index.ts',
-                'src/core/index.ts',
-                'src/crypto/index.ts',
-                'src/fonts/index.ts',
-                'src/shaping/index.ts',
-                'src/worker/index.ts',
-                'src/types/pdf-types.ts',
-                'src/parser/index.ts',
-                'src/types/pdf-document-types.ts',
-                'src/tools/index.ts',
-            ],
-            thresholds: {
-                statements: 88,
-                branches: 80,
-                functions: 85,
-                lines: 90,
-            },
-        },
-    },
-});
+import { defineConfig } from 'vitest/config';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * The executable-documentation recipes in `recipes/` import from 'pdfnative'
+ * exactly as a consumer would; these aliases point that specifier (and the
+ * `pdfnative/fonts/*` data-module subpaths) at the in-repo sources so the
+ * recipe suite always exercises the current tree. The fonts alias must be
+ * listed first — a bare 'pdfnative' entry would otherwise prefix-match the
+ * subpath imports.
+ */
+const rootUrl = (p: string): string => fileURLToPath(new URL(p, import.meta.url));
+
+export default defineConfig({
+    resolve: {
+        alias: [
+            { find: /^pdfnative\/fonts\/(.*)$/, replacement: `${rootUrl('./fonts')}/$1` },
+            { find: /^pdfnative$/, replacement: rootUrl('./src/index.ts') },
+        ],
+    },
+    test: {
+        include: ['tests/**/*.test.ts'],
+        environment: 'node',
+        globals: false,
+        coverage: {
+            provider: 'v8',
+            include: ['src/**/*.ts'],
+            exclude: [
+                'src/worker/pdf-worker.ts',
+                'src/index.ts',
+                'src/core/index.ts',
+                'src/crypto/index.ts',
+                'src/fonts/index.ts',
+                'src/shaping/index.ts',
+                'src/worker/index.ts',
+                'src/types/pdf-types.ts',
+                'src/parser/index.ts',
+                'src/types/pdf-document-types.ts',
+                'src/tools/index.ts',
+            ],
+            thresholds: {
+                statements: 88,
+                branches: 80,
+                functions: 85,
+                lines: 90,
+            },
+        },
+    },
+});