Merge origin/main into codex/nutrient-skill-router

Resolve the PR conflict by adopting the Python plugin structure merged in #3 while preserving the broader document-processing guidance, modular references, Codex metadata, and expanded capability coverage from this branch. Add a lightweight validation workflow so packaging drift and unresolved markers are caught automatically in future PRs.

Author: jdrhyne

.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

.gitignore

@@ -0,0 +1,3 @@
+__pycache__/
+*.pyc
+.recording-tmp/

README.md

@@ -20,26 +20,38 @@
   <a href="#30-second-quickstart">Quickstart</a> •
   <a href="#real-world-workflows">Workflows</a> •
   <a href="#features">Features</a> •
-  <a href="#supported-agents">40+ Agents</a> •
-  <a href="#alternative-integrations">MCP &amp; OpenClaw</a>
+  <a href="#supported-agents">40+ Agents</a>
 </p>
 
 ---
 
 ## 30-Second Quickstart
 
+**1. Get a free API key** → **<https://dashboard.nutrient.io/sign_up/?product=processor>**
+
+**2. Install & configure:**
+
 ```bash
-# 1. Install the skill (works with 40+ agents)
+# Install the skill (works with 40+ agents)
 npx skills add PSPDFKit-labs/nutrient-agent-skill
 
-# 2. Set your API key (free at https://dashboard.nutrient.io/sign_up/?product=processor)
+# Set your API key
 export NUTRIENT_API_KEY="pdf_live_..."
-
-# 3. Ask your agent
-> "Extract the text from invoice.pdf"
 ```
 
-That's it. Your agent now has full document processing capabilities — no MCP setup required.
+**3. Ask your agent:**
+
+> *"Extract the text from invoice.pdf"*
+
+That's it. Your agent now has full document processing capabilities.
+
+---
+
+## Requirements
+
+- Python 3.10+
+- `uv` installed: <https://docs.astral.sh/uv/>
+- Nutrient API key
 
 ---
 
@@ -176,62 +188,42 @@ cp -r nutrient-agent-skill/nutrient-document-processing ~/.claude/skills/
 
 ---
 
-## Alternative Integrations
-
-### MCP Server (For agents with MCP support)
-
-The **Nutrient DWS MCP Server** provides all operations as native agent tools with file I/O handling and sandboxing.
-
-```bash
-npx @nutrient-sdk/dws-mcp-server
-```
-
-Add to your MCP config (e.g., `claude_desktop_config.json`):
-
-```json
-{
-  "mcpServers": {
-    "nutrient-dws": {
-      "command": "npx",
-      "args": ["-y", "@nutrient-sdk/dws-mcp-server"],
-      "env": {
-        "NUTRIENT_DWS_API_KEY": "YOUR_API_KEY",
-        "SANDBOX_PATH": "/path/to/working/directory"
-      }
-    }
-  }
-}
-```
-
-📦 [npm](https://www.npmjs.com/package/@nutrient-sdk/dws-mcp-server) · [GitHub](https://github.com/PSPDFKit/nutrient-dws-mcp-server)
-
-### OpenClaw Plugin
-
-For [OpenClaw](https://openclaw.com) users:
-
-```bash
-openclaw plugins install @nutrient-sdk/nutrient-openclaw
-```
-
-📦 [npm](https://www.npmjs.com/package/@nutrient-sdk/nutrient-openclaw)
-
----
-
 ## Skill Structure
 
 ```
 nutrient-document-processing/
-├── SKILL.md              # Main instructions (loaded by agents)
+├── SKILL.md                          # Main instructions (loaded by agents)
+├── agents/
+│   └── openai.yaml                   # Optional Codex App metadata
 ├── references/
-│   └── REFERENCE.md      # Full API reference (loaded on demand)
-├── LICENSE               # Apache-2.0
-└── README.md
+│   ├── 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.txt                       # Apache-2.0
 ```
 
+### Script Model
+
+- `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.md](nutrient-document-processing/references/REFERENCE.md)** — Complete API reference with all endpoints, parameters, and error codes
+- **[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
 
@@ -241,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)

nutrient-document-processing/SKILL.md

@@ -1,18 +1,37 @@
 ---
 name: nutrient-document-processing
-description: Use when tasks involve generating PDFs from HTML or URLs, converting Office/images/PDFs, assembling or splitting PDFs, OCRing and extracting content, redacting, watermarking, signing, filling, or producing compliance outputs like PDF/A, PDF/UA, and linearized PDFs with Nutrient DWS. Triggers include convert to PDF, OCR this scan, extract tables, merge these PDFs, redact PII, sign this PDF, make this PDF/A, or linearize for web delivery. Prefer the Nutrient MCP server when it is already configured, otherwise call the API directly.
+description: >-
+  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:
-  short-description: Generate, convert, assemble, OCR, redact, sign, archive, and optimize documents
+  author: nutrient-sdk
+  version: "1.0"
+  homepage: "https://www.nutrient.io/api/"
+  repository: "https://github.com/PSPDFKit-labs/nutrient-agent-skill"
+  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
 
 Use Nutrient DWS for managed document workflows where fidelity, compliance, or multi-step processing matters more than local-tool convenience.
 
-## Setup assumptions
+## Setup
+- 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`.
-- Open `references/request-basics.md` first when authentication or payload shape is the blocker.
+- 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.
@@ -23,38 +42,49 @@ Use Nutrient DWS for managed document workflows where fidelity, compliance, or m
 - Check credits before large, batch, or AI-heavy runs.
 
 ## Tool preference
-1. Prefer the Nutrient MCP server when it is already configured. It handles file I/O and reduces multipart-request boilerplate.
-2. Fall back to direct API calls when MCP is unavailable or the workflow is easier to express as an explicit payload.
-3. Use local PDF utilities only for lightweight inspection. Use Nutrient when output fidelity or compliance matters.
+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.
 
-## Request model
-- Most workflows use `POST https://api.nutrient.io/build`.
-- Use multipart requests when uploading local files. Use JSON requests when all inputs are remote URLs.
-- `parts` describes source files, HTML inputs, remote URLs, page ranges, and passwords.
-- `actions` applies ordered transformations such as OCR, redaction, watermarking, signing, flattening, or rotation.
-- `output` selects the final format and delivery options such as `pdf`, `text`, `docx`, `png`, `pdfa`, `pdfua`, or optimized PDF output.
-- Dedicated endpoints also exist for some tools such as PDF/UA auto-tagging, but `/build` is the default mental model.
+## 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
 
-Minimal direct-call template:
+## Multi-Step Workflow Rule
+Do not add new committed pipeline scripts under `scripts/`.
 
-```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"}]}' \
-  -o result.pdf
-```
+When the user asks for multiple operations in one run:
+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.
 
-## Workflow
-1. Identify the source type and the required final artifact.
-2. Decide whether the job is generation, conversion, extraction, security/compliance, or a chained workflow.
-3. Express the full pipeline in one payload when the ordering is clear and the artifact should stay in-memory on the server.
-4. Save outputs with stable suffixes such as `-ocr`, `-redacted`, `-pdfa`, `-pdfua`, or `-linearized`.
+## 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.
+- 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.
@@ -68,6 +98,7 @@ curl -X POST https://api.nutrient.io/build \
 - 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:
@@ -80,9 +111,9 @@ Read only what you need:
 - `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
 
-## References
-- [Reference index](references/REFERENCE.md)
-- [API docs](https://www.nutrient.io/api/documentation/)
-- [Processor API overview](https://www.nutrient.io/api/processor-api/)
-- [API playground](https://dashboard.nutrient.io/processor-api/playground/)
-- [MCP server](https://github.com/PSPDFKit/nutrient-dws-mcp-server)
+## Rules
+- Fail fast when required arguments are missing.
+- Write outputs to explicit paths and print created files.
+- Do not log secrets.
+- All client methods are async and should run via `asyncio.run(main())`.
+- If import fails, install dependency with `uv add nutrient-dws`.

nutrient-document-processing/assets/templates/custom-workflow-template.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.10"
+# dependencies = ["nutrient-dws"]
+# ///
+
+import argparse
+import asyncio
+import sys
+from pathlib import Path
+
+from nutrient_dws.builder.constant import BuildActions
+
+sys.path.insert(0, str(Path(__file__).parent.parent.parent / "scripts"))
+from lib.common import create_client, write_workflow_output, handle_error
+
+
+async def main() -> None:
+    parser = argparse.ArgumentParser(description="Template for multi-step custom workflows.")
+    parser.add_argument("--input", required=True, help="Path or URL to the input document.")
+    parser.add_argument("--out", required=True, help="Output file path.")
+    args = parser.parse_args()
+
+    client = create_client()
+
+    # Customize this action list for the requested pipeline.
+    actions = [
+        BuildActions.ocr("english"),
+        BuildActions.watermark_text("DRAFT", {"opacity": 0.25, "rotation": 45}),
+    ]
+
+    result = await (
+        client.workflow()
+        .add_file_part(args.input, actions=actions)
+        .output_pdf()
+        .execute()
+    )
+    write_workflow_output(result, args.out)
+
+
+if __name__ == "__main__":
+    try:
+        asyncio.run(main())
+    except Exception as e:
+        handle_error(e)