diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml
new file mode 100644
index 0000000..cb621f8
--- /dev/null
+++ b/.github/workflows/validate.yml
@@ -0,0 +1,52 @@
+name: Validate
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+      - "codex/**"
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install YAML parser
+        run: python -m pip install --disable-pip-version-check pyyaml
+
+      - name: Validate repo structure
+        run: python tools/validate-repo.py
+
+      - name: Validate Codex metadata
+        run: |
+          python - <<'PY'
+          import pathlib
+          import yaml
+
+          path = pathlib.Path("nutrient-document-processing/agents/openai.yaml")
+          data = yaml.safe_load(path.read_text())
+          interface = data.get("interface", {})
+          required = ["display_name", "short_description", "default_prompt"]
+          missing = [key for key in required if key not in interface]
+          if missing:
+              raise SystemExit(f"openai.yaml missing interface keys: {missing}")
+          print("openai.yaml parsed successfully")
+          PY
+
+      - name: Compile Python scripts
+        run: |
+          python -m py_compile nutrient-document-processing/scripts/*.py nutrient-document-processing/scripts/lib/common.py
+
+      - name: Smoke test script help
+        run: |
+          for script in nutrient-document-processing/scripts/*.py; do
+            python "$script" --help > /dev/null
+          done
diff --git a/README.md b/README.md
index de4915e..ebcd555 100644
--- a/README.md
+++ b/README.md
@@ -2,13 +2,14 @@
 
 <p align="center">
   <a href="https://www.nutrient.io/api/"><img src="https://img.shields.io/badge/Nutrient-DWS%20API-blue" alt="Nutrient DWS API"></a>
-  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-green" alt="License"></a>
+  <a href="https://www.npmjs.com/package/@nutrient-sdk/dws-mcp-server"><img src="https://img.shields.io/npm/v/@nutrient-sdk/dws-mcp-server" alt="npm version"></a>
+  <a href="nutrient-document-processing/LICENSE.txt"><img src="https://img.shields.io/badge/license-Apache--2.0-green" alt="License"></a>
   <a href="https://agentskills.io"><img src="https://img.shields.io/badge/Agent%20Skills-compatible-purple" alt="Agent Skills"></a>
 </p>
 
 <p align="center">
   <strong>Give your AI agent PDF superpowers — in one command.</strong><br>
-  Convert, extract, OCR, redact, sign, and fill documents from any coding agent.
+  Generate, convert, extract, OCR, redact, sign, archive, and optimize documents from any coding agent.
 </p>
 
 <p align="center">
@@ -131,13 +132,17 @@ patient-records.pdf (contains PII)
 
 | Capability | Description | Example prompt |
 |------------|-------------|----------------|
+| ✨ **Generate** | Create PDFs from HTML templates, uploaded assets, or remote URLs | *"Generate a PDF proposal from this HTML template"* |
 | 📄 **Convert** | PDF ↔ DOCX/XLSX/PPTX, HTML → PDF, images → PDF | *"Convert report.docx to PDF"* |
+| 🧩 **Assemble** | Merge, split, reorder, rotate, and flatten PDF packets before delivery | *"Merge these PDFs, rotate the landscape pages, and keep only pages 1-5"* |
 | 📝 **Extract** | Text, tables, and key-value pairs from PDFs | *"Extract all tables from invoice.pdf as Excel"* |
 | 🔍 **OCR** | Multi-language OCR for scanned documents | *"OCR this German scan and extract the text"* |
 | 🔒 **Redact** | Pattern-based + AI-powered PII redaction | *"Redact all SSNs and emails from records.pdf"* |
 | 💧 **Watermark** | Text or image watermarks with full styling | *"Add a DRAFT watermark to proposal.pdf"* |
 | ✍️ **Sign** | CMS and CAdES digital signatures | *"Digitally sign contract.pdf"* |
 | 📋 **Fill Forms** | Programmatic PDF form filling | *"Fill the tax form with these values…"* |
+| 🗂️ **Compliance** | Convert PDFs for archival or accessibility targets like PDF/A and PDF/UA | *"Convert this PDF to PDF/A-2a"* |
+| ⚡ **Optimize** | Optimize and linearize PDFs for web delivery and download performance | *"Linearize this PDF for fast web viewing"* |
 | 📊 **Credits** | Monitor API usage and balance | *"How many API credits do I have left?"* |
 
 ---
@@ -188,15 +193,21 @@ cp -r nutrient-agent-skill/nutrient-document-processing ~/.claude/skills/
 ```
 nutrient-document-processing/
 ├── SKILL.md                          # Main instructions (loaded by agents)
+├── agents/
+│   └── openai.yaml                   # Optional Codex App metadata
+├── references/
+│   ├── REFERENCE.md                  # Reference index
+│   └── *.md                          # Focused cookbooks by workflow type
 ├── scripts/
 │   ├── *.py                          # Single-operation scripts
 │   └── lib/common.py                 # Shared utilities
 ├── assets/
+│   ├── nutrient.svg                  # Skill icon
 │   └── templates/
 │       └── custom-workflow-template.py  # Runtime pipeline template
 ├── tests/
 │   └── testing-guide.md
-└── LICENSE                           # Apache-2.0
+└── LICENSE.txt                       # Apache-2.0
 ```
 
 ### Script Model
@@ -204,12 +215,15 @@ nutrient-document-processing/
 - `scripts/*.py` are single-operation scripts only.
 - Multi-step workflows are generated at runtime in a temporary script from `assets/templates/custom-workflow-template.py`.
 - Do not commit runtime pipeline scripts.
+- Use `references/` for HTML/URL generation, compliance outputs, and other workflows that are easier to express as direct API payloads or temporary pipelines.
 
 ## Documentation
 
 - **[SKILL.md](nutrient-document-processing/SKILL.md)** — Agent instructions with setup and operation examples
+- **[Reference Index](nutrient-document-processing/references/REFERENCE.md)** — Modular cookbook for generation, conversion, extraction, security, compliance, and workflow sequencing
 - **[Testing Guide](nutrient-document-processing/tests/testing-guide.md)** — Manual test procedures
 - **[Custom Workflow Template](nutrient-document-processing/assets/templates/custom-workflow-template.py)** — Runtime pipeline starting point
+- **[Codex App Metadata](nutrient-document-processing/agents/openai.yaml)** — Optional manifest for Codex App packaging
 - **[API Playground](https://dashboard.nutrient.io/processor-api/playground/)** — Interactive API testing
 - **[Official API Docs](https://www.nutrient.io/guides/dws-processor/)** — Nutrient documentation
 
@@ -219,4 +233,4 @@ Built by [Nutrient](https://www.nutrient.io/) (formerly PSPDFKit) — document S
 
 ## License
 
-[Apache-2.0](nutrient-document-processing/LICENSE)
+[Apache-2.0](nutrient-document-processing/LICENSE.txt)
diff --git a/nutrient-document-processing/LICENSE b/nutrient-document-processing/LICENSE.txt
similarity index 100%
rename from nutrient-document-processing/LICENSE
rename to nutrient-document-processing/LICENSE.txt
diff --git a/nutrient-document-processing/SKILL.md b/nutrient-document-processing/SKILL.md
index 939b6c3..8bcd33f 100644
--- a/nutrient-document-processing/SKILL.md
+++ b/nutrient-document-processing/SKILL.md
@@ -1,83 +1,117 @@
 ---
 name: nutrient-document-processing
 description: >-
-  Process documents with the Nutrient DWS API. Use this skill when the user wants to convert documents
-  (PDF, DOCX, XLSX, PPTX, HTML, images), extract text or tables from PDFs, OCR scanned documents,
-  redact sensitive information (PII, SSN, emails, credit cards), add watermarks, digitally sign PDFs,
-  fill PDF forms, or check API credit usage. Activates on keywords: PDF, document, convert, extract,
-  OCR, redact, watermark, sign, merge, compress, form fill, document processing.
+  Process documents with Nutrient DWS. Use when the user wants to generate PDFs from HTML or URLs,
+  convert Office/images/PDFs, assemble or split packets, OCR scans, extract text/tables/key-value
+  pairs, redact PII, watermark, sign, fill forms, optimize PDFs, or produce compliance outputs like
+  PDF/A or PDF/UA. Triggers include convert to PDF, merge these PDFs, OCR this scan, extract tables,
+  redact PII, sign this PDF, make this PDF/A, or linearize for web delivery.
 license: Apache-2.0
 metadata:
   author: nutrient-sdk
   version: "1.0"
   homepage: "https://www.nutrient.io/api/"
   repository: "https://github.com/PSPDFKit-labs/nutrient-agent-skill"
-  compatibility: "Requires Node.js 18+ and internet. Works with Claude Code, Codex CLI, Gemini CLI, OpenCode, Cursor, Windsurf, GitHub Copilot, Amp, or any Agent Skills-compatible product."
+  compatibility: "Requires Python 3.10+, uv, and internet. Works with Claude Code, Codex CLI, Gemini CLI, OpenCode, Cursor, Windsurf, GitHub Copilot, Amp, or any Agent Skills-compatible product."
+  short-description: "Generate, convert, assemble, OCR, redact, sign, archive, and optimize documents"
 ---
 
 # Nutrient Document Processing
 
-Process, convert, extract, redact, sign, and manipulate documents using the [Nutrient DWS Processor API](https://www.nutrient.io/api/).
+Use Nutrient DWS for managed document workflows where fidelity, compliance, or multi-step processing matters more than local-tool convenience.
 
 ## Setup
-
-You need a Nutrient DWS API key. Get one free at <https://dashboard.nutrient.io/sign_up/?product=processor>.
-
-Export the API key before running scripts:
-
-```bash
-export NUTRIENT_API_KEY="nutr_sk_..."
-```
-
-Scripts live in `scripts/` relative to this SKILL.md. Use the directory containing this SKILL.md as the working directory when running scripts:
-
-```bash
-cd <directory containing this SKILL.md> && uv run scripts/<script>.py --help
-```
-
-Page ranges use `start:end` (0-based, end-exclusive). Negative indices count from the end. Use comma-separated ranges like `0:2,3:5,-2:-1`.
-
-## PDF Requirements
-
-Some operations require specific document characteristics:
-
-- **split.py**: Requires multi-page PDFs (2+ pages). Cannot extract a range from a single-page document.
-- **delete-pages.py**: Must retain at least one page. Cannot delete all pages in a document.
-- **sign.py**: Only accepts local file paths (not URLs).
-
-## Single-Operation Scripts
-
-- Convert format: `uv run scripts/convert.py --input doc.pdf --format docx --out doc.docx`
-- Merge files: `uv run scripts/merge.py --inputs a.pdf,b.pdf --out merged.pdf`
-- Split by ranges: `uv run scripts/split.py --input doc.pdf --ranges 0:2,2: --out-dir out --prefix part`
-- OCR: `uv run scripts/ocr.py --input scan.pdf --languages english --out scan-ocr.pdf`
-- Rotate pages: `uv run scripts/rotate.py --input doc.pdf --angle 90 --out rotated.pdf`
-- Optimize: `uv run scripts/optimize.py --input doc.pdf --out optimized.pdf`
-- Extract text: `uv run scripts/extract-text.py --input doc.pdf --out text.json`
-- Extract tables: `uv run scripts/extract-table.py --input doc.pdf --out tables.json`
-- Extract key-value pairs: `uv run scripts/extract-key-value-pairs.py --input doc.pdf --out kvp.json`
-- Add text watermark: `uv run scripts/watermark-text.py --input doc.pdf --text CONFIDENTIAL --out watermarked.pdf`
-- AI redact: `uv run scripts/redact-ai.py --input doc.pdf --criteria "Remove all SSNs" --mode apply --out redacted.pdf`
-- Sign: `uv run scripts/sign.py --input doc.pdf --out signed.pdf`
-- Password protect: `uv run scripts/password-protect.py --input doc.pdf --user-password upass --owner-password opass --out protected.pdf`
-- Add pages: `uv run scripts/add-pages.py --input doc.pdf --count 2 --out with-pages.pdf`
-- Delete pages: `uv run scripts/delete-pages.py --input doc.pdf --pages 0,2,-1 --out trimmed.pdf`
-- Duplicate/reorder pages: `uv run scripts/duplicate-pages.py --input doc.pdf --pages 2,0,1,1 --out reordered.pdf`
+- Get a Nutrient DWS API key at <https://dashboard.nutrient.io/sign_up/?product=processor>.
+- Direct API calls use `Authorization: Bearer $NUTRIENT_API_KEY`.
+  ```bash
+  export NUTRIENT_API_KEY="nutr_sk_..."
+  ```
+- MCP setups commonly use `@nutrient-sdk/dws-mcp-server` with `NUTRIENT_DWS_API_KEY`.
+- Scripts live in `scripts/` relative to this SKILL.md. Use the directory containing this SKILL.md as the working directory:
+  ```bash
+  cd <directory containing this SKILL.md> && uv run scripts/<script>.py --help
+  ```
+- Page ranges use `start:end` with 0-based indexes and end-exclusive semantics. Negative indexes count from the end.
+
+## When to use
+- Generate PDFs from HTML templates, uploaded assets, or remote URLs.
+- Convert Office, HTML, image, and PDF files between supported formats.
+- OCR scans and extract text, tables, or key-value pairs.
+- Redact PII, watermark, sign, fill forms, merge, split, rotate, flatten, or encrypt PDFs.
+- Produce delivery targets like PDF/A, PDF/UA, optimized PDFs, or linearized PDFs.
+- Check credits before large, batch, or AI-heavy runs.
+
+## Tool preference
+1. Prefer `scripts/*.py` for covered single-operation workflows.
+2. Use `assets/templates/custom-workflow-template.py` for multi-step jobs that should still run through the Python client.
+3. Use the modular `references/` docs and direct API payloads for capabilities that do not yet have a dedicated helper script, especially HTML/URL generation and compliance tuning.
+4. Use local PDF utilities only for lightweight inspection. Use Nutrient when output fidelity or compliance matters.
+
+## Single-operation scripts
+- `convert.py` -> convert between `pdf`, `pdfa`, `pdfua`, `docx`, `xlsx`, `pptx`, `png`, `jpeg`, `webp`, `html`, and `markdown`
+- `merge.py` -> merge multiple files into one PDF
+- `split.py` -> split one PDF into multiple PDFs by page ranges
+- `add-pages.py` -> append blank pages
+- `delete-pages.py` -> remove specific pages
+- `duplicate-pages.py` -> reorder or duplicate pages into a new PDF
+- `rotate.py` -> rotate selected pages
+- `ocr.py` -> OCR scanned PDFs or images
+- `extract-text.py` -> extract text to JSON
+- `extract-table.py` -> extract tables
+- `extract-key-value-pairs.py` -> extract key-value pairs
+- `watermark-text.py` -> apply a text watermark
+- `redact-ai.py` -> detect and apply AI-powered redactions
+- `sign.py` -> digitally sign a local PDF
+- `password-protect.py` -> write encrypted output PDFs
+- `optimize.py` -> apply optimization and linearization-style options via JSON
 
 ## Multi-Step Workflow Rule
-
 Do not add new committed pipeline scripts under `scripts/`.
 
 When the user asks for multiple operations in one run:
-
-1. Copy `assets/templates/custom-workflow-template.py` to a temporary location (for example `/tmp/ndp-workflow-<task>.py`).
+1. Copy `assets/templates/custom-workflow-template.py` to a temporary location such as `/tmp/ndp-workflow-<task>.py`.
 2. Implement the combined workflow in that temporary script.
 3. Run it with `uv run /tmp/ndp-workflow-<task>.py ...`.
 4. Return generated output files.
 5. Delete the temporary script unless the user explicitly asks to keep it.
 
-## Rules
+## PDF Requirements
+- `split.py` requires a multi-page PDF and cannot extract ranges from a single-page document.
+- `delete-pages.py` must retain at least one page and cannot delete the entire document.
+- `sign.py` only accepts local file paths for the main PDF.
+
+## Decision rules
+- Prefer a helper script when one already covers the requested operation cleanly.
+- If you control the source markup, prefer HTML generation over browser print workflows.
+- Use remote `file.url` inputs when the source already lives at a stable URL and you want to avoid local uploads.
+- Use `output.type` for conversion and finalization targets. Use `actions` for transformations when building direct API payloads.
+- OCR before text extraction, key-value extraction, or semantic redaction on scans.
+- Prefer preset or regex redaction when the target is explicit. Use AI redaction only for contextual or natural-language requests.
+- Use the PDF manipulation reference for merge, split, rotate, flatten, and page-range workflows instead of inferring those payloads from conversion examples.
+- Treat PDF/A and PDF/UA as compliance targets, not cosmetic export formats. Choose the target up front and validate final artifacts when requirements are contractual.
+- For PDF/UA, clean born-digital inputs and structured HTML usually tag better than rasterized or flattened source PDFs.
+- For delivery optimization, linearize or optimize unsigned output artifacts instead of mutating already signed files.
+- When the user asks for multiple steps, keep destructive or final steps late in the sequence. Use the workflow recipes when ordering is ambiguous.
+
+## Anti-patterns
+- Do not OCR born-digital PDFs just because the task mentions extraction. Extract first and OCR only if the text layer is missing.
+- Do not flatten forms or annotations until the user confirms the artifact no longer needs to stay editable.
+- Do not sign, archive, or linearize intermediate working files. Keep those as final-delivery steps.
+- Do not promise PDF/A or PDF/UA compliance without a validation step when the requirement is contractual.
+- Do not commit temporary workflow scripts under `scripts/`.
+
+## Reference map
+Read only what you need:
+
+- `references/request-basics.md` -> endpoint model, auth, multipart vs JSON, credits, limits, and errors
+- `references/generation-and-conversion.md` -> HTML/URL generation and format conversion
+- `references/pdf-manipulation.md` -> merge, split, page-range, rotate, and flatten workflows
+- `references/extraction-and-ocr.md` -> OCR, text extraction, tables, and key-value workflows
+- `references/security-signing-and-forms.md` -> redaction, watermarking, signatures, forms, and passwords
+- `references/compliance-and-optimization.md` -> PDF/A, PDF/UA, optimization, and linearization
+- `references/workflow-recipes.md` -> end-to-end sequencing patterns for common business document workflows
 
+## Rules
 - Fail fast when required arguments are missing.
 - Write outputs to explicit paths and print created files.
 - Do not log secrets.
diff --git a/nutrient-document-processing/agents/openai.yaml b/nutrient-document-processing/agents/openai.yaml
new file mode 100644
index 0000000..c1cf13d
--- /dev/null
+++ b/nutrient-document-processing/agents/openai.yaml
@@ -0,0 +1,6 @@
+interface:
+  display_name: "Nutrient Document Processing"
+  short_description: "Generate, convert, assemble, OCR, redact, sign, archive, and optimize documents"
+  icon_small: "./assets/nutrient.svg"
+  icon_large: "./assets/nutrient.svg"
+  default_prompt: "Use $nutrient-document-processing to generate, convert, assemble, OCR, extract, redact, sign, fill, archive, optimize, or linearize this document, then return the output files and a concise summary."
diff --git a/nutrient-document-processing/assets/nutrient.svg b/nutrient-document-processing/assets/nutrient.svg
new file mode 100644
index 0000000..3f0d8f5
--- /dev/null
+++ b/nutrient-document-processing/assets/nutrient.svg
@@ -0,0 +1,4 @@
+<svg width="48" height="48" viewBox="0 0 48 48" fill="none" xmlns="http://www.w3.org/2000/svg">
+<rect width="48" height="48" rx="8" fill="white"/>
+<path d="M9.83333 26.8471C8.26792 26.8471 7 25.5729 7 23.9998C7 22.4266 8.26792 21.1524 9.83333 21.1524C11.3987 21.1524 12.6667 22.4266 12.6667 23.9998C12.6667 25.5729 11.3987 26.8471 9.83333 26.8471ZM38.1667 21.1524C36.6012 21.1524 35.3333 22.4266 35.3333 23.9998C35.3333 25.5729 36.6012 26.8471 38.1667 26.8471C39.7321 26.8471 41 25.5729 41 23.9998C41 22.4266 39.7321 21.1524 38.1667 21.1524ZM11.3265 30.9701C10.128 31.9809 9.97075 33.7776 10.9766 34.982C11.9824 36.1865 13.7702 36.3445 14.9688 35.3337C16.1672 34.3229 16.3245 32.5262 15.3187 31.3217C14.3128 30.1173 12.525 29.9593 11.3265 30.9701ZM36.6735 17.0294C37.872 16.0186 38.0292 14.2219 37.0234 13.0175C36.0176 11.8131 34.2297 11.6551 33.0312 12.6659C31.8328 13.6767 31.6755 15.4734 32.6813 16.6778C33.6872 17.8822 35.475 18.0402 36.6735 17.0294ZM14.9688 12.6673C13.7702 11.6565 11.9824 11.8131 10.9766 13.0189C9.97075 14.2248 10.1266 16.02 11.3265 17.0309C12.5264 18.0417 14.3128 17.8851 15.3187 16.6792C16.3245 15.4734 16.1687 13.6781 14.9688 12.6673ZM36.6735 30.9701C35.475 29.9593 33.6872 30.1159 32.6813 31.3217C31.6755 32.5262 31.8313 34.3229 33.0312 35.3337C34.2297 36.3445 36.0176 36.1879 37.0234 34.982C38.0292 33.7776 37.8734 31.9809 36.6735 30.9701ZM29.4386 24.8682C28.2401 23.8574 26.4523 24.014 25.4464 25.2199C24.4406 26.4257 24.5964 28.221 25.7963 29.2318C26.9962 30.2426 28.7827 30.086 29.7885 28.8801C30.7943 27.6743 30.6385 25.879 29.4386 24.8682ZM22.2037 18.7677C21.0052 17.7569 19.2173 17.9135 18.2115 19.1194C17.2057 20.3253 17.3615 22.1205 18.5614 23.1313C19.7613 24.1421 21.5478 23.9855 22.5536 22.7797C23.5594 21.5738 23.4036 19.7786 22.2037 18.7677Z" fill="#1A1414"/>
+</svg>
diff --git a/nutrient-document-processing/references/REFERENCE.md b/nutrient-document-processing/references/REFERENCE.md
new file mode 100644
index 0000000..323f7b9
--- /dev/null
+++ b/nutrient-document-processing/references/REFERENCE.md
@@ -0,0 +1,33 @@
+# Nutrient DWS Reference Index
+
+Use this folder as a modular cookbook. Keep `SKILL.md` loaded as the router and open only the reference file that matches the task at hand.
+
+## Reference map
+
+- [request-basics.md](request-basics.md)
+  Endpoint model, authentication, multipart vs JSON requests, credits, limits, and common errors.
+
+- [generation-and-conversion.md](generation-and-conversion.md)
+  PDF generation from HTML or URLs, Office/image conversion, and output-format selection.
+
+- [pdf-manipulation.md](pdf-manipulation.md)
+  Merge, split, reorder, rotate, and flatten PDF workflows.
+
+- [extraction-and-ocr.md](extraction-and-ocr.md)
+  OCR, text extraction, table extraction, and key-value workflows.
+
+- [security-signing-and-forms.md](security-signing-and-forms.md)
+  Redaction, watermarking, signing, form fill, and password-protected PDFs.
+
+- [compliance-and-optimization.md](compliance-and-optimization.md)
+  PDF/A archival output, PDF/UA auto-tagging, PDF optimization, and linearization.
+
+- [workflow-recipes.md](workflow-recipes.md)
+  Sequencing guidance for common multi-step business document workflows.
+
+## Official docs
+
+- [Processor API overview](https://www.nutrient.io/api/processor-api/)
+- [General documentation](https://www.nutrient.io/api/documentation/)
+- [Tools and APIs](https://www.nutrient.io/api/documentation/tools-and-api/)
+- [API playground](https://dashboard.nutrient.io/processor-api/playground/)
diff --git a/nutrient-document-processing/references/compliance-and-optimization.md b/nutrient-document-processing/references/compliance-and-optimization.md
new file mode 100644
index 0000000..b11454d
--- /dev/null
+++ b/nutrient-document-processing/references/compliance-and-optimization.md
@@ -0,0 +1,128 @@
+# Compliance and Optimization
+
+Use these patterns when the required output is archival, accessible, or tuned for delivery performance.
+
+## PDF/A archival conversion
+
+```bash
+curl -X POST https://api.nutrient.io/build \
+  -H "Authorization: Bearer $NUTRIENT_API_KEY" \
+  -F document=@document.pdf \
+  -F 'instructions={
+    "parts": [
+      {
+        "file": "document"
+      }
+    ],
+    "output": {
+      "type": "pdfa",
+      "conformance": "pdfa-2a",
+      "vectorization": true,
+      "rasterization": true
+    }
+  }' \
+  -o result.pdf
+```
+
+Supported PDF/A targets include:
+
+- `pdfa-1a`, `pdfa-1b`
+- `pdfa-2a`, `pdfa-2u`, `pdfa-2b`
+- `pdfa-3a`, `pdfa-3u`, `pdfa-3b`
+- `pdfa-4`, `pdfa-4e`, `pdfa-4f`
+
+### PDF/A caveat
+
+To achieve conformance, conversion may vectorize or rasterize content. That can remove live text and font information, so later OCR may be needed.
+
+## PDF/UA auto-tagging
+
+Dedicated endpoint:
+
+```bash
+curl -X POST https://api.nutrient.io/processor/pdfua \
+  -H "Content-Type: application/pdf" \
+  -H "Authorization: Bearer $NUTRIENT_API_KEY" \
+  --data-binary @document.pdf \
+  -o result.pdf
+```
+
+Equivalent `/build` workflow:
+
+```bash
+curl -X POST https://api.nutrient.io/build \
+  -H "Authorization: Bearer $NUTRIENT_API_KEY" \
+  -F document=@document.pdf \
+  -F 'instructions={
+    "parts": [
+      {
+        "file": "document"
+      }
+    ],
+    "output": {
+      "type": "pdfua"
+    }
+  }' \
+  -o result.pdf
+```
+
+### PDF/UA rules
+
+- PDF/UA is an accessibility target, not just a format conversion.
+- Clean born-digital PDFs generally tag better than rasterized or flattened inputs.
+- Structured HTML sources also tend to produce better accessibility outcomes than image-only content.
+- Validate final outputs with your required checker when accessibility compliance is contractual.
+
+## PDF optimization and linearization
+
+Linearize a PDF for fast web viewing:
+
+```bash
+curl -X POST https://api.nutrient.io/build \
+  -H "Authorization: Bearer $NUTRIENT_API_KEY" \
+  -F document=@document.pdf \
+  -F 'instructions={
+    "parts": [
+      {
+        "file": "document"
+      }
+    ],
+    "output": {
+      "type": "pdf",
+      "optimize": {
+        "linearize": true
+      }
+    }
+  }' \
+  -o result.pdf
+```
+
+Optimization with compression controls:
+
+```json
+{
+  "parts": [{ "file": "document" }],
+  "output": {
+    "type": "pdf",
+    "optimize": {
+      "disableImages": false,
+      "mrcCompression": true,
+      "imageOptimizationQuality": 2,
+      "linearize": true
+    }
+  }
+}
+```
+
+### Optimization rules
+
+- Linearize only for delivery PDFs meant for network viewing.
+- Optimize before signatures when possible. Treat signed PDFs as immutable delivery artifacts.
+- Compression changes should be validated visually when image quality matters.
+
+## Official docs
+
+- [PDF to PDF/A API](https://www.nutrient.io/api/pdf-to-pdfa-api/)
+- [PDF/UA auto-tagging API](https://www.nutrient.io/api/pdfua-auto-tagging-api/)
+- [Optimization API](https://www.nutrient.io/api/document-optimization-api/)
+- [PDF linearization API](https://www.nutrient.io/api/pdf-linearization-api/)
diff --git a/nutrient-document-processing/references/extraction-and-ocr.md b/nutrient-document-processing/references/extraction-and-ocr.md
new file mode 100644
index 0000000..7dfed2f
--- /dev/null
+++ b/nutrient-document-processing/references/extraction-and-ocr.md
@@ -0,0 +1,100 @@
+# Extraction and OCR
+
+Use these patterns when the goal is to pull machine-readable data from PDFs or scans.
+
+## Extract plain text
+
+```bash
+curl -X POST https://api.nutrient.io/build \
+  -H "Authorization: Bearer $NUTRIENT_API_KEY" \
+  -F document.pdf=@document.pdf \
+  -F 'instructions={"parts":[{"file":"document.pdf"}],"output":{"type":"text"}}' \
+  -o extracted.txt
+```
+
+## Extract tables
+
+```bash
+curl -X POST https://api.nutrient.io/build \
+  -H "Authorization: Bearer $NUTRIENT_API_KEY" \
+  -F document.pdf=@document.pdf \
+  -F 'instructions={"parts":[{"file":"document.pdf"}],"actions":[{"type":"extraction","strategy":"tables"}],"output":{"type":"xlsx"}}' \
+  -o tables.xlsx
+```
+
+Common structured outputs: `xlsx`, `json`, `xml`, `csv`
+
+## Extract key-value pairs
+
+```bash
+curl -X POST https://api.nutrient.io/build \
+  -H "Authorization: Bearer $NUTRIENT_API_KEY" \
+  -F document.pdf=@document.pdf \
+  -F 'instructions={"parts":[{"file":"document.pdf"}],"actions":[{"type":"extraction","strategy":"key-values"}],"output":{"type":"json"}}' \
+  -o pairs.json
+```
+
+## Basic OCR
+
+```bash
+curl -X POST https://api.nutrient.io/build \
+  -H "Authorization: Bearer $NUTRIENT_API_KEY" \
+  -F scanned.pdf=@scanned.pdf \
+  -F 'instructions={"parts":[{"file":"scanned.pdf"}],"actions":[{"type":"ocr","language":"english"}]}' \
+  -o searchable.pdf
+```
+
+## Multi-language OCR
+
+```json
+{
+  "parts": [{ "file": "scanned.pdf" }],
+  "actions": [{ "type": "ocr", "language": ["english", "german", "french"] }]
+}
+```
+
+## OCR on images
+
+```bash
+curl -X POST https://api.nutrient.io/build \
+  -H "Authorization: Bearer $NUTRIENT_API_KEY" \
+  -F scan.jpg=@scan.jpg \
+  -F 'instructions={"parts":[{"file":"scan.jpg"}],"actions":[{"type":"ocr","language":"english"}]}' \
+  -o searchable.pdf
+```
+
+## OCR languages
+
+Common OCR languages include:
+
+- `english`
+- `german`
+- `french`
+- `spanish`
+- `italian`
+- `portuguese`
+- `dutch`
+- `swedish`
+- `polish`
+- `czech`
+- `turkish`
+- `japanese`
+- `korean`
+- `chinese-simplified`
+- `chinese-traditional`
+- `arabic`
+- `hebrew`
+- `hindi`
+- `russian`
+
+## OCR and extraction rules
+
+- OCR before extraction when text is image-only, unselectable, or suspiciously sparse.
+- Tables and key-values benefit from cleaner scans and correct page orientation.
+- For multilingual inputs, pass an array of languages rather than guessing a single language.
+- If OCR quality is poor, fix source orientation and scan quality before retrying.
+
+## Official docs
+
+- [Data extraction overview](https://www.nutrient.io/api/data-extraction-api/)
+- [Processor API overview](https://www.nutrient.io/api/processor-api/)
diff --git a/nutrient-document-processing/references/generation-and-conversion.md b/nutrient-document-processing/references/generation-and-conversion.md
new file mode 100644
index 0000000..b2419ea
--- /dev/null
+++ b/nutrient-document-processing/references/generation-and-conversion.md
@@ -0,0 +1,119 @@
+# Generation and Conversion
+
+Use these patterns when the main task is to generate a new document or convert an existing one into another format.
+
+## HTML to PDF generation
+
+Upload the HTML file and reference it through `parts[].html`.
+
+```bash
+curl -X POST https://api.nutrient.io/build \
+  -H "Authorization: Bearer $NUTRIENT_API_KEY" \
+  -F index.html=@index.html \
+  -F 'instructions={"parts":[{"html":"index.html"}]}' \
+  -o result.pdf
+```
+
+With layout options:
+
+```json
+{
+  "parts": [{ "html": "index.html" }],
+  "output": {
+    "type": "pdf",
+    "layout": {
+      "orientation": "landscape",
+      "size": "A4",
+      "margin": { "top": 20, "bottom": 20, "left": 15, "right": 15 }
+    }
+  }
+}
+```
+
+## Remote URL generation or conversion
+
+When the input already lives at a stable remote URL, send a JSON request and use `file.url`:
+
+```bash
+curl -X POST https://api.nutrient.io/build \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $NUTRIENT_API_KEY" \
+  -d '{
+    "parts": [
+      {
+        "file": {
+          "url": "https://www.nutrient.io/api/assets/downloads/samples/docx/document.docx"
+        }
+      }
+    ]
+  }' \
+  -o result.pdf
+```
+
+Use this pattern when you want server-side fetches and do not need to upload a local file first.
+
+## Office to PDF
+
+```bash
+curl -X POST https://api.nutrient.io/build \
+  -H "Authorization: Bearer $NUTRIENT_API_KEY" \
+  -F document.docx=@document.docx \
+  -F 'instructions={"parts":[{"file":"document.docx"}]}' \
+  -o result.pdf
+```
+
+Supported common inputs: `docx`, `xlsx`, `pptx`, `doc`, `xls`, `ppt`, `odt`, `ods`, `odp`, `rtf`
+
+## Image to PDF
+
+```bash
+curl -X POST https://api.nutrient.io/build \
+  -H "Authorization: Bearer $NUTRIENT_API_KEY" \
+  -F photo.jpg=@photo.jpg \
+  -F 'instructions={"parts":[{"file":"photo.jpg"}]}' \
+  -o result.pdf
+```
+
+Supported common images: `jpg`, `jpeg`, `png`, `gif`, `webp`, `tiff`, `bmp`
+
+## PDF to Office
+
+```bash
+curl -X POST https://api.nutrient.io/build \
+  -H "Authorization: Bearer $NUTRIENT_API_KEY" \
+  -F document.pdf=@document.pdf \
+  -F 'instructions={"parts":[{"file":"document.pdf"}],"output":{"type":"docx"}}' \
+  -o result.docx
+```
+
+Supported common outputs: `docx`, `xlsx`, `pptx`
+
+## PDF to image
+
+```bash
+curl -X POST https://api.nutrient.io/build \
+  -H "Authorization: Bearer $NUTRIENT_API_KEY" \
+  -F document.pdf=@document.pdf \
+  -F 'instructions={"parts":[{"file":"document.pdf","pages":{"start":0,"end":0}}],"output":{"type":"png","dpi":150}}' \
+  -o page.png
+```
+
+Useful output options:
+
+| Option | Meaning |
+|--------|---------|
+| `type` | `png`, `jpeg`, or `webp` |
+| `dpi` | Resolution target |
+| `width` / `height` | Explicit pixel size |
+
+## Generation and conversion rules
+
+- Use HTML generation when you control the markup and need stable, reproducible output.
+- Use remote URL requests when the source already exists online and you want to avoid local uploads.
+- Use `output.type` for direct conversions. Do not create unnecessary `actions` for simple format changes.
+- For paginated image output, render only the pages you need.
+
+## Official docs
+
+- [PDF generator / converter overview](https://www.nutrient.io/api/pdf-converter-api/)
+- [URL to PDF API](https://www.nutrient.io/api/url-to-pdf-api/)
diff --git a/nutrient-document-processing/references/pdf-manipulation.md b/nutrient-document-processing/references/pdf-manipulation.md
new file mode 100644
index 0000000..2c6486a
--- /dev/null
+++ b/nutrient-document-processing/references/pdf-manipulation.md
@@ -0,0 +1,96 @@
+# PDF Manipulation
+
+Use these patterns when the task is about assembling, slicing, or normalizing PDFs before final delivery operations.
+
+## Merge PDFs
+
+Part order controls merge order:
+
+```bash
+curl -X POST https://api.nutrient.io/build \
+  -H "Authorization: Bearer $NUTRIENT_API_KEY" \
+  -F cover=@cover.pdf \
+  -F body=@body.pdf \
+  -F appendix=@appendix.pdf \
+  -F 'instructions={
+    "parts": [
+      { "file": "cover" },
+      { "file": "body" },
+      { "file": "appendix" }
+    ]
+  }' \
+  -o packet.pdf
+```
+
+## Split or extract page ranges
+
+Use `pages` on a part to carve out a subset:
+
+```bash
+curl -X POST https://api.nutrient.io/build \
+  -H "Authorization: Bearer $NUTRIENT_API_KEY" \
+  -F document=@document.pdf \
+  -F 'instructions={
+    "parts": [
+      {
+        "file": "document",
+        "pages": { "start": 0, "end": 4 }
+      }
+    ]
+  }' \
+  -o first-five-pages.pdf
+```
+
+## Reorder or assemble a packet from ranges
+
+Reuse the same source part with different page ranges to build a new packet:
+
+```json
+{
+  "parts": [
+    { "file": "document", "pages": { "start": 5, "end": 9 } },
+    { "file": "document", "pages": { "start": 0, "end": 4 } }
+  ]
+}
+```
+
+## Rotate pages
+
+Use a rotation action when page orientation is wrong:
+
+```json
+{
+  "parts": [{ "file": "document.pdf" }],
+  "actions": [
+    {
+      "type": "rotate",
+      "rotation": 90,
+      "pages": [0, 1, 2]
+    }
+  ]
+}
+```
+
+## Flatten forms or annotations
+
+Flatten only when the output should stop being interactive:
+
+```json
+{
+  "parts": [{ "file": "document.pdf" }],
+  "actions": [{ "type": "flatten" }]
+}
+```
+
+## Rules
+
+- Page indexes are zero-based. `end: -1` means the last page.
+- Assemble the full packet before watermarking, signing, optimizing, or linearizing.
+- Rotate before rasterizing or signing if the source orientation is incorrect.
+- Flatten late. It removes editability from forms and many annotation workflows.
+- Keep passwords on the affected `part` when slicing or merging encrypted inputs.
+
+## Official docs
+
+- [Processor API overview](https://www.nutrient.io/api/processor-api/)
+- [Tools and APIs](https://www.nutrient.io/api/documentation/tools-and-api/)
diff --git a/nutrient-document-processing/references/request-basics.md b/nutrient-document-processing/references/request-basics.md
new file mode 100644
index 0000000..989fc84
--- /dev/null
+++ b/nutrient-document-processing/references/request-basics.md
@@ -0,0 +1,118 @@
+# Request Basics
+
+Most Nutrient DWS workflows use:
+
+```text
+POST https://api.nutrient.io/build
+Authorization: Bearer YOUR_API_KEY
+```
+
+Use multipart when you are uploading local files. Use JSON when every input is a remote URL.
+
+## Multipart pattern
+
+```bash
+curl -X POST https://api.nutrient.io/build \
+  -H "Authorization: Bearer $NUTRIENT_API_KEY" \
+  -F document=@document.pdf \
+  -F 'instructions={"parts":[{"file":"document"}]}' \
+  -o result.pdf
+```
+
+## JSON pattern for remote URLs
+
+```bash
+curl -X POST https://api.nutrient.io/build \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $NUTRIENT_API_KEY" \
+  -d '{
+    "parts": [
+      {
+        "file": {
+          "url": "https://www.nutrient.io/api/assets/downloads/samples/docx/document.docx"
+        }
+      }
+    ]
+  }' \
+  -o result.pdf
+```
+
+## Instructions model
+
+```json
+{
+  "parts": [
+    {
+      "file": "document.pdf",
+      "pages": { "start": 0, "end": -1 },
+      "password": "optional-password"
+    }
+  ],
+  "actions": [
+    { "type": "action_type" }
+  ],
+  "output": {
+    "type": "pdf"
+  }
+}
+```
+
+## Core rules
+
+- Multipart field names must match the filenames or symbolic names referenced in `parts`.
+- `parts` preserves order. Multiple parts become a merged output unless the selected output type says otherwise.
+- `actions` execute in order and mutate the in-flight document.
+- `output.type` selects the final artifact type such as `pdf`, `text`, `docx`, `xlsx`, `pptx`, `png`, `pdfa`, or `pdfua`.
+- Password-protected inputs need `password` on the relevant part.
+
+## Credits
+
+Check balance:
+
+```bash
+curl -X GET https://api.nutrient.io/credits \
+  -H "Authorization: Bearer $NUTRIENT_API_KEY"
+```
+
+Check usage:
+
+```bash
+curl -X GET "https://api.nutrient.io/credits/usage?period=month" \
+  -H "Authorization: Bearer $NUTRIENT_API_KEY"
+```
+
+## Limits and common errors
+
+### HTTP status codes
+
+| Code | Meaning |
+|------|---------|
+| `200` | Success |
+| `400` | Invalid instructions or missing required fields |
+| `401` | Invalid or missing API key |
+| `402` | Insufficient credits |
+| `413` | Payload too large |
+| `415` | Unsupported media type |
+| `422` | Valid request but unsupported or unprocessable content |
+| `429` | Rate limited |
+| `500` | Server error |
+
+### Common problems
+
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| `file_not_found` | The symbolic file name in `parts` does not match an uploaded field | Align multipart names and `parts` references |
+| Empty extraction | The file is scanned or rasterized | OCR first |
+| `password_required` | The PDF is encrypted | Add the password on the part |
+| `insufficient_credits` | Batch or AI-heavy workflow exceeded credits | Check balance before the run |
+
+### File limits
+
+- Maximum input file: 100 MB
+- Maximum total upload: 500 MB per request
+- For faster runs, prefer files below 50 MB when possible
+
+## Official docs
+
+- [API overview](https://www.nutrient.io/api/documentation/developer-guides/api-overview/)
+- [Processor API overview](https://www.nutrient.io/api/processor-api/)
diff --git a/nutrient-document-processing/references/security-signing-and-forms.md b/nutrient-document-processing/references/security-signing-and-forms.md
new file mode 100644
index 0000000..0fc7026
--- /dev/null
+++ b/nutrient-document-processing/references/security-signing-and-forms.md
@@ -0,0 +1,141 @@
+# Security, Signing, and Forms
+
+Use these patterns when the task is about redaction, watermarking, signatures, form fill, or document protection.
+
+## Preset redaction
+
+```bash
+curl -X POST https://api.nutrient.io/build \
+  -H "Authorization: Bearer $NUTRIENT_API_KEY" \
+  -F document.pdf=@document.pdf \
+  -F 'instructions={"parts":[{"file":"document.pdf"}],"actions":[{"type":"redaction","strategy":"preset","preset":"email-address"}]}' \
+  -o redacted.pdf
+```
+
+Common presets:
+
+- `social-security-number`
+- `credit-card-number`
+- `email-address`
+- `north-american-phone-number`
+- `international-phone-number`
+- `date`
+- `url`
+- `ipv4`
+- `ipv6`
+- `mac-address`
+- `us-zip-code`
+- `vin`
+- `time`
+
+## Regex redaction
+
+```bash
+curl -X POST https://api.nutrient.io/build \
+  -H "Authorization: Bearer $NUTRIENT_API_KEY" \
+  -F document.pdf=@document.pdf \
+  -F 'instructions={"parts":[{"file":"document.pdf"}],"actions":[{"type":"redaction","strategy":"regex","regex":"\\b\\d{3}-\\d{2}-\\d{4}\\b","caseSensitive":false}]}' \
+  -o redacted.pdf
+```
+
+## AI redaction
+
+```bash
+curl -X POST https://api.nutrient.io/build \
+  -H "Authorization: Bearer $NUTRIENT_API_KEY" \
+  -F document.pdf=@document.pdf \
+  -F 'instructions={"parts":[{"file":"document.pdf"}],"actions":[{"type":"ai_redaction","criteria":"All personally identifiable information"}]}' \
+  -o redacted.pdf
+```
+
+Use AI redaction for contextual asks. Use preset or regex redaction for explicit patterns.
+
+## Text watermark
+
+```bash
+curl -X POST https://api.nutrient.io/build \
+  -H "Authorization: Bearer $NUTRIENT_API_KEY" \
+  -F document.pdf=@document.pdf \
+  -F 'instructions={"parts":[{"file":"document.pdf"}],"actions":[{"type":"watermark","watermarkType":"text","text":"DRAFT","fontSize":72,"fontColor":"#FF0000","opacity":0.3,"rotation":45,"width":"50%","height":"50%"}]}' \
+  -o watermarked.pdf
+```
+
+## Image watermark
+
+```bash
+curl -X POST https://api.nutrient.io/build \
+  -H "Authorization: Bearer $NUTRIENT_API_KEY" \
+  -F document.pdf=@document.pdf \
+  -F logo.png=@logo.png \
+  -F 'instructions={"parts":[{"file":"document.pdf"}],"actions":[{"type":"watermark","watermarkType":"image","imagePath":"logo.png","width":"25%","height":"25%","opacity":0.5}]}' \
+  -o watermarked.pdf
+```
+
+## CMS signature
+
+```bash
+curl -X POST https://api.nutrient.io/build \
+  -H "Authorization: Bearer $NUTRIENT_API_KEY" \
+  -F document.pdf=@document.pdf \
+  -F 'instructions={"parts":[{"file":"document.pdf"}],"actions":[{"type":"sign","signatureType":"cms","signerName":"John Doe","reason":"Document approval","location":"San Francisco"}]}' \
+  -o signed.pdf
+```
+
+## CAdES signature
+
+```bash
+curl -X POST https://api.nutrient.io/build \
+  -H "Authorization: Bearer $NUTRIENT_API_KEY" \
+  -F document.pdf=@document.pdf \
+  -F 'instructions={"parts":[{"file":"document.pdf"}],"actions":[{"type":"sign","signatureType":"cades","cadesLevel":"b-lt","signerName":"Jane Smith"}]}' \
+  -o signed.pdf
+```
+
+## Fill form fields
+
+```json
+{
+  "parts": [{ "file": "form.pdf" }],
+  "actions": [{
+    "type": "fillForm",
+    "fields": [
+      { "name": "firstName", "value": "John" },
+      { "name": "lastName", "value": "Doe" },
+      { "name": "email", "value": "john@example.com" },
+      { "name": "agree", "value": true }
+    ]
+  }]
+}
+```
+
+## Encrypt output
+
+```json
+{
+  "parts": [{ "file": "document.pdf" }],
+  "output": {
+    "type": "pdf",
+    "owner_password": "owner123",
+    "user_password": "user456"
+  }
+}
+```
+
+## Open a password-protected input
+
+```json
+{
+  "parts": [{ "file": "protected.pdf", "password": "user456" }]
+}
+```
+
+## Rules
+
+- Redact before signing. Signed documents should be treated as final artifacts.
+- Deterministic redaction is easier to verify than AI redaction.
+- Confirm real signing requirements before promising a legally sufficient workflow.
+- Use real field names for form fill. Do not guess from visible labels.
+
+## Official docs
+
+- [Tools and APIs](https://www.nutrient.io/api/documentation/tools-and-api/)
diff --git a/nutrient-document-processing/references/workflow-recipes.md b/nutrient-document-processing/references/workflow-recipes.md
new file mode 100644
index 0000000..aab7780
--- /dev/null
+++ b/nutrient-document-processing/references/workflow-recipes.md
@@ -0,0 +1,98 @@
+# Workflow Recipes
+
+Use these patterns when the task spans more than one DWS feature and ordering matters.
+
+## 1. Scan to searchable text
+
+Goal: take an image-only PDF and produce both a searchable PDF and extracted text.
+
+Recommended sequence:
+
+1. OCR the source PDF into a searchable PDF.
+2. Extract text from the searchable result.
+
+Reasoning: OCR improves extraction quality and gives you a reusable intermediate artifact.
+
+## 2. Scan to redacted delivery PDF
+
+Goal: redact a scanned document and deliver a shareable PDF.
+
+Recommended sequence:
+
+1. OCR
+2. Preset or regex redaction
+3. Optional watermark
+4. Optional optimization or linearization
+5. Signature last, if required
+
+Reasoning: OCR enables reliable matching, and signatures should only happen after all content mutations are complete.
+
+## 3. HTML report to archival PDF
+
+Goal: generate a PDF from structured content and archive it.
+
+Recommended sequence:
+
+1. Generate PDF from HTML
+2. Convert the result to PDF/A
+3. Validate the archival output in your downstream compliance workflow if required
+
+Reasoning: HTML generation gives you better structure control than post-hoc browser printing, and PDF/A should be treated as a final archival artifact.
+
+## 4. Existing PDF to accessible PDF/UA
+
+Goal: turn a born-digital PDF into a screen-reader-ready artifact.
+
+Recommended sequence:
+
+1. Start from the cleanest available PDF
+2. Run PDF/UA auto-tagging
+3. Validate the result with your required accessibility checker
+
+Reasoning: flattened, rasterized, or noisy inputs reduce tagging quality.
+
+## 5. Form packet to signed output
+
+Goal: fill a form, remove interactivity if needed, and sign it.
+
+Recommended sequence:
+
+1. Fill form fields
+2. Optional flattening
+3. Signature last
+
+Reasoning: signing too early forces a second mutation pass and can invalidate the signed artifact.
+
+## 6. Web delivery PDF
+
+Goal: publish a PDF that streams quickly in viewers.
+
+Recommended sequence:
+
+1. Final content edits
+2. Optional compression
+3. Linearization
+4. Publish to a server that supports byte-range requests
+
+Reasoning: linearization is a delivery concern, not an authoring concern.
+
+## 7. Packet assembly before signing
+
+Goal: merge multiple PDFs, fix page orientation, and produce a final packet for signing or distribution.
+
+Recommended sequence:
+
+1. Merge or reorder the required parts
+2. Extract or omit page ranges as needed
+3. Optional page rotation
+4. Optional flattening
+5. Watermark, sign, optimize, or linearize last
+
+Reasoning: assembly and page normalization are still content mutations. Final-artifact operations should happen only after the packet shape is stable.
+
+## Recipe heuristics
+
+- Keep OCR early.
+- Keep compliance targets intentional.
+- Keep signatures last.
+- Treat optimization as a delivery-stage step unless the workflow explicitly needs it earlier.
diff --git a/tools/validate-repo.py b/tools/validate-repo.py
new file mode 100644
index 0000000..ad35dc2
--- /dev/null
+++ b/tools/validate-repo.py
@@ -0,0 +1,104 @@
+#!/usr/bin/env python3
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+SKILL_DIR = REPO_ROOT / "nutrient-document-processing"
+CONFLICT_MARKERS = ("<" * 7, "=" * 7, ">" * 7)
+TEXT_SUFFIXES = {".md", ".txt", ".py", ".yaml", ".yml", ".svg", ".gitignore"}
+
+
+def fail(message: str) -> None:
+    print(message, file=sys.stderr)
+    raise SystemExit(1)
+
+
+def check_required_paths() -> None:
+    required = [
+        REPO_ROOT / "README.md",
+        SKILL_DIR / "SKILL.md",
+        SKILL_DIR / "LICENSE.txt",
+        SKILL_DIR / "references" / "REFERENCE.md",
+        SKILL_DIR / "scripts" / "lib" / "common.py",
+        SKILL_DIR / "tests" / "testing-guide.md",
+    ]
+    missing = [str(path.relative_to(REPO_ROOT)) for path in required if not path.exists()]
+    if missing:
+        fail("Missing required files:\n- " + "\n- ".join(missing))
+
+
+def iter_text_files() -> list[Path]:
+    files: list[Path] = []
+    for path in REPO_ROOT.rglob("*"):
+        if not path.is_file():
+            continue
+        if ".git" in path.parts:
+            continue
+        if path.suffix in TEXT_SUFFIXES or path.name in TEXT_SUFFIXES:
+            files.append(path)
+    return files
+
+
+def check_conflict_markers() -> None:
+    offenders: list[str] = []
+    for path in iter_text_files():
+        try:
+            text = path.read_text(encoding="utf-8")
+        except UnicodeDecodeError:
+            continue
+        if any(marker in text for marker in CONFLICT_MARKERS):
+            offenders.append(str(path.relative_to(REPO_ROOT)))
+    if offenders:
+        fail("Unresolved merge markers found:\n- " + "\n- ".join(sorted(offenders)))
+
+
+def check_skill_frontmatter() -> None:
+    text = (SKILL_DIR / "SKILL.md").read_text(encoding="utf-8")
+    match = re.match(r"^---\n(.*?)\n---\n", text, flags=re.DOTALL)
+    if not match:
+        fail("SKILL.md is missing a frontmatter block.")
+    frontmatter = match.group(1)
+    for field in ("name:", "description:", "license:"):
+        if field not in frontmatter:
+            fail(f"SKILL.md frontmatter is missing `{field[:-1]}`.")
+
+
+def check_readme_links() -> None:
+    readme = (REPO_ROOT / "README.md").read_text(encoding="utf-8")
+    if 'href="nutrient-document-processing/LICENSE.txt"' not in readme:
+        fail("README.md does not point its license badge at nutrient-document-processing/LICENSE.txt.")
+    if "[Apache-2.0](nutrient-document-processing/LICENSE.txt)" not in readme:
+        fail("README.md does not point its license section at nutrient-document-processing/LICENSE.txt.")
+
+
+def check_reference_links() -> None:
+    reference_path = SKILL_DIR / "references" / "REFERENCE.md"
+    text = reference_path.read_text(encoding="utf-8")
+    links = re.findall(r"\(([^)]+)\)", text)
+    missing: list[str] = []
+    for link in links:
+        if "://" in link or link.startswith("#"):
+            continue
+        target = (reference_path.parent / link).resolve()
+        if not target.exists():
+            missing.append(link)
+    if missing:
+        fail("REFERENCE.md contains missing relative links:\n- " + "\n- ".join(sorted(missing)))
+
+
+def main() -> None:
+    check_required_paths()
+    check_conflict_markers()
+    check_skill_frontmatter()
+    check_readme_links()
+    check_reference_links()
+    print("Repository validation passed.")
+
+
+if __name__ == "__main__":
+    main()