@damiangilgonzalez/harness 1.3.7

package/skills/document-processing/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: document-processing
+description: "Use when the deliverable is a document's bytes or its literal content — text/tables out of PDFs, AcroForm fill and flatten, page merge/split, PDF/DOCX from templates, OCR of image-only scans. NOT schema-typed fields pulled from text (that is structured-extraction), NOT signature routing (e-signature) or spreadsheet cells/formulas (spreadsheet-ops)."
+tags: [pdf, ocr, docx, forms, extraction, document-ai]
+recommends: [structured-extraction, e-signature, spreadsheet-ops, rag, data-scraper]
+origin: risco
+---
+
+# Document processing
+
+File in, content out — or data in, file out. You open a byte stream (PDF, DOCX, scan) and either pull the content out, or you build a new document from a template and a data dict. That is the whole job: the deliverable is **bytes of a document or the literal content of one**.
+
+The boundary test, apply it first:
+
+- Deliverable is **raw text / Markdown / table cells / a generated file** → you are in the right place.
+- Deliverable is **a typed object matching a schema** (`{parties: [...], total: 1234.50}`) → that is `structured-extraction`. This skill stops at "clean Markdown out of the file"; the schema-constrained extraction runs on that Markdown.
+
+Everything else routes too: signing with an audit trail → `e-signature`, spreadsheet grids/formulas/XLSX-as-data → `spreadsheet-ops`, indexing for cross-document Q&A → `rag` (this skill *produces* the text `rag` ingests, it does not index it), downloading the files off a site → `data-scraper`.
+
+## Step 0 — does the PDF have a text layer?
+
+The most expensive mistake in this skill is OCR'ing a PDF that already has a text layer. A digital PDF (exported from Word, a browser, a report tool) carries selectable text — extracting it is free, instant, and lossless. OCR is slow, costs money or GPU, and *introduces* errors. **Never OCR a PDF you can extract.**
+
+Check before you pick an engine:
+
+```python
+import pdfplumber
+
+with pdfplumber.open("doc.pdf") as pdf:
+    txt = pdf.pages[0].extract_text() or ""
+
+if len(txt.strip()) > 20:
+    print("text layer present -> extract directly (pdfplumber / pypdf)")
+else:
+    print("image-only or empty -> this is an OCR job")
+```
+
+If `extract_text()` returns empty (or near-empty) across the first few pages, it is a scan or image-only PDF and you go to the OCR branch. Symptom from the user's side: *"the text copies out as garbage / random symbols"* usually means a broken/embedded font, not a missing text layer — try `pypdf` extraction too before assuming OCR.
+
+## Engine selection
+
+| Goal | Use | Why |
+|---|---|---|
+| Extract text + tables with layout | **pdfplumber** | Layout-aware; `extract_tables()` returns rows/cols as Python lists → pandas/CSV. |
+| Raw text, merge, split, rotate, page ops | **pypdf** (6.12.2) | Pure-Python, no C deps, runs in Lambda/containers; the maintained core — import `pypdf`, never the dead `PyPDF2`, which was merged back into it. |
+| Fill an interactive PDF form | **pypdf** | `update_page_form_field_values` writes AcroForm fields; can flatten. |
+| Generate a Word/DOCX from a template | **docxtpl** (0.20.x) | A real `.docx` becomes a Jinja2 template; author in Word, tag, render. |
+| Generate a PDF from scratch | **ReportLab** | Canvas / Platypus flowables for laid-out PDFs. |
+| OCR a scan, local / no API budget | **Docling** (or Marker) | Layout + reading order + table structure, fully local, wraps Tesseract/RapidOCR. |
+| OCR messy scans / handwriting / hard tables, API ok | **Mistral OCR** | `mistral-ocr-2512` (OCR 3), ~$2 / 1,000 pages, tuned for forms + handwriting. |
+| Fastest extract / easiest page→PNG raster | **PyMuPDF** ⚠️ **AGPL** | Fast, but AGPL: shipping it imposes an open-source obligation or needs a paid license. Flag this before recommending. |
+
+## Extraction recipes
+
+Text + tables with `pdfplumber`, straight to CSV:
+
+```python
+import csv
+import pdfplumber
+
+rows = []
+with pdfplumber.open("invoice.pdf") as pdf:
+    for page in pdf.pages:
+        for table in page.extract_tables():
+            rows.extend(table)
+
+with open("out.csv", "w", newline="") as f:
+    csv.writer(f).writerows(rows)
+```
+
+Raw text, merge, split, rotate with `pypdf`:
+
+```python
+from pypdf import PdfReader, PdfWriter
+
+# raw text
+text = "\n".join(p.extract_text() or "" for p in PdfReader("doc.pdf").pages)
+
+# merge two files
+w = PdfWriter()
+for src in ("a.pdf", "b.pdf"):
+    w.append(src)
+with open("merged.pdf", "wb") as f:
+    w.write(f)
+
+# split first 3 pages + rotate one
+w2 = PdfWriter()
+reader = PdfReader("doc.pdf")
+for page in reader.pages[:3]:
+    w2.add_page(page)
+w2.pages[0].rotate(90)
+with open("first3.pdf", "wb") as f:
+    w2.write(f)
+```
+
+## Form filling (AcroForm)
+
+Dump the field names first — guessing them is the #1 reason a fill silently does nothing:
+
+```python
+from pypdf import PdfReader
+
+fields = PdfReader("form.pdf").get_fields() or {}
+for name, f in fields.items():
+    print(name, "->", f.get("/FT"))  # /Tx text, /Btn checkbox/radio, /Ch choice
+```
+
+Then write the values. Set `auto_regenerate=False` and bake with `flatten=True` if it must not be editable:
+
+```python
+from pypdf import PdfReader, PdfWriter
+
+reader = PdfReader("form.pdf")
+writer = PdfWriter()
+writer.append(reader)
+
+for page in writer.pages:
+    writer.update_page_form_field_values(
+        page,
+        {"applicant_name": "Eric Risco", "agree": "/Yes"},  # checkbox = its on-state
+        auto_regenerate=False,  # else a spurious "save changes?" prompt fires on open
+    )
+
+# flatten=True bakes the values and drops the editable widgets
+with open("filled.pdf", "wb") as f:
+    writer.write(f)
+```
+
+`auto_regenerate` defaults to `True` for legacy reasons, and you almost never want it. Checkbox/radio values are the field's `/V` on-state (often `/Yes`), not `True` — read the field to find it.
+
+## Generation
+
+DOCX from a Word template you authored and tagged with Jinja2 (`{{ client }}`, `{% tr for row in items %}` on a table row, `InlineImage` for pictures):
+
+```python
+from docxtpl import DocxTemplate
+
+doc = DocxTemplate("contract_template.docx")
+doc.render({
+    "client": "Acme SL",
+    "date": "2026-06-02",
+    "items": [{"desc": "Audit", "amount": "1.200,00 €"}],
+})
+doc.save("contract_2026-06-02.docx")
+```
+
+PDF from scratch with ReportLab Platypus:
+
+```python
+from reportlab.lib.pagesizes import A4
+from reportlab.platypus import SimpleDocTemplate, Paragraph, Spacer
+from reportlab.lib.styles import getSampleStyleSheet
+
+styles = getSampleStyleSheet()
+doc = SimpleDocTemplate("report.pdf", pagesize=A4)
+doc.build([
+    Paragraph("Quarterly Report", styles["Title"]),
+    Spacer(1, 12),
+    Paragraph("Generated automatically from the data dict.", styles["BodyText"]),
+])
+```
+
+## OCR
+
+Branch on cost and privacy. **Local, no API budget, or data must not leave the machine → Docling/Marker.** **Messy scans, handwriting, brutal tables, and an API budget is fine → Mistral OCR.**
+
+Local with Docling (wraps Tesseract / RapidOCR, exports Markdown preserving tables):
+
+```python
+from docling.document_converter import DocumentConverter
+
+result = DocumentConverter().convert("scan.pdf")
+markdown = result.document.export_to_markdown()
+open("scan.md", "w").write(markdown)
+```
+
+Hosted with Mistral OCR (~$2 / 1,000 pages, 50% off via Batch API; outputs interleaved text+images as Markdown):
+
+```python
+from mistralai import Mistral
+
+client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
+resp = client.ocr.process(
+    model="mistral-ocr-2512",
+    document={"type": "document_url", "document_url": signed_url},
+)
+markdown = "\n\n".join(p.markdown for p in resp.pages)
+```
+
+**Never trust OCR output blind.** OCR confuses `0/O`, `1/l/I`, and drops or shifts decimal points — a `1.234,50` can come back as `1234,50` or `1,234.50`. Always spot-check totals, dates, and ID numbers against the rendered page before you hand the text downstream. For clean scans with no budget, plain `pytesseract` is the zero-cost baseline, but it is weak on layout/tables versus the pipelines above.
+
+## Scale
+
+Batch jobs: parallelize per-file, cap concurrency on the hosted API (rate limits + cost), and use Mistral's Batch API for the 50% discount on large runs. Engine install matrix, exact version pins, the full licensing table, the Docling-vs-Marker-vs-Mistral feature/cost comparison, and troubleshooting (encrypted PDFs, mangled AcroForm field names, multi-column reading order, CJK/handwriting) live in `references/engines.md` — read it before a non-trivial install.
+
+## Anti-patterns
+
+| Anti-pattern | Why it is wrong | Do instead |
+|---|---|---|
+| Pipe every PDF straight to OCR | OCR'ing a digital PDF is slow, costs money, and *adds* errors to text you could extract losslessly | Step 0: check the text layer first; OCR only image-only PDFs |
+| `import PyPDF2` | Unmaintained; merged into `pypdf` years ago — a stale-code smell | `from pypdf import PdfReader, PdfWriter` |
+| Recommend PyMuPDF without a word about its license | PyMuPDF is **AGPL**; shipping it silently creates an open-source obligation | Flag AGPL; prefer pdfplumber/pypdf, or get a commercial license knowingly |
+| Leave `auto_regenerate=True` on a form fill | Marks the AcroForm dirty → a spurious "save changes?" prompt for every user | Pass `auto_regenerate=False` |
+| Trust OCR'd totals/numbers as-is | `0/O`, `1/l`, shifted decimals silently corrupt amounts | Spot-check totals/dates/IDs against the page image |
+| Hand-roll a regex to pull typed fields from the Markdown | Brittle, re-implements a sibling, breaks on layout drift | Output clean Markdown, hand it to `structured-extraction` |
+| Use Mistral OCR when the user said "no cloud / local only" | Sends documents off-machine, violating the privacy constraint | Use Docling/Marker + Tesseract/RapidOCR locally |

package/skills/document-processing/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — document-processing
+
+`cases.yaml` is a routing-and-capability fixture, not an automated runner. To use it, take each prompt under `should_trigger` and confirm a router/agent picks `document-processing` for the stated `why`; take each `should_not_trigger` prompt and confirm it routes instead to the named `route_to` sibling (`structured-extraction`, `e-signature`, `spreadsheet-ops`, `rag`, `data-scraper`) — a miss here is a boundary leak, the most common failure for this skill. For `capability`, give the model the `scenario` with only the SKILL.md loaded and grade the response against every line in `must_include` (it must detect the missing text layer, choose a *local* OCR pipeline because the user said no cloud, hand the Markdown to structured-extraction rather than regexing fields, add an OCR spot-check, and use current libs not PyPDF2). If the repo has a top-level eval harness, point it at this file; otherwise read the cases by hand.

package/skills/document-processing/evals/cases.yaml

@@ -0,0 +1,65 @@
+skill: document-processing
+
+# Prompts that MUST load `document-processing`. The skill owns the byte-level
+# work of turning documents into content and data into documents: extract
+# text/tables from PDFs, fill AcroForm fields, generate PDF/DOCX from
+# templates, and OCR image-only files into Markdown/JSON. The deliverable is
+# bytes of a document or the literal content of one.
+should_trigger:
+  - prompt: "Extract all the tables from this scanned invoice PDF into CSV."
+    why: "Table extraction is core; 'scanned' means it must first detect no text layer and OCR, then emit CSV cells — file-in/content-out."
+
+  - prompt: "Fill this PDF application form with these values and flatten it so it can't be edited."
+    why: "AcroForm fill via pypdf update_page_form_field_values + flatten — the canonical form-filling job this skill owns."
+
+  - prompt: "Generate a Word contract from this .docx template and a dict of client fields."
+    why: "docxtpl: author-in-Word template rendered with a context dict — data-in/file-out generation."
+
+  - prompt: "These PDFs copy out as garbled symbols — get me clean text."
+    why: "Non-obvious: the symptom describes a broken/embedded font or image-only PDF, not a feature request; the skill diagnoses the text-layer problem and OCRs or re-extracts."
+
+  - prompt: "Rellena este formulario PDF y luego fusiona los tres documentos en uno solo."
+    why: "Spanish: fill a PDF form then merge three documents into one — form fill + pypdf merge, both owned here."
+
+  - prompt: "Convert 200 scanned pages to Markdown keeping the table structure, locally, with no API."
+    why: "Local batch OCR with table structure preserved -> Docling/Marker; the 'no API / local' constraint forces the local pipeline, not a hosted one."
+
+  - prompt: "Merge these five PDFs, rotate page 2, and rasterize the cover to a PNG."
+    why: "Pure page-level byte ops (merge/rotate/raster) are squarely this skill's pypdf/PyMuPDF territory."
+
+# NEAR-MISS prompts that must NOT load `document-processing`. The recurring
+# trap: anything where the real deliverable is a typed object, a signature
+# workflow, a spreadsheet grid, a retrieval index, or the acquisition of files.
+should_not_trigger:
+  - prompt: "Parse this contract text into a typed JSON schema of parties, dates, and amounts."
+    route_to: "structured-extraction"
+    why: "Deliverable is a schema-typed object, not raw content; this skill produces the Markdown that structured-extraction then types."
+
+  - prompt: "Send this signed PDF to the client for signature with an audit trail."
+    route_to: "e-signature"
+    why: "Signer workflow, routing, and audit trail are e-signature; document-processing only produces or edits the bytes."
+
+  - prompt: "Read the values from B2:D40 of this spreadsheet and sum them."
+    route_to: "spreadsheet-ops"
+    why: "Cells, ranges, and formulas are a spreadsheet grid — spreadsheet-ops, not document bytes."
+
+  - prompt: "Index these PDFs so I can ask questions across all of them."
+    route_to: "rag"
+    why: "Retrieval/embeddings index for Q&A is rag; this skill produces the text rag ingests but does not index it."
+
+  - prompt: "Crawl this site and download every PDF it links to."
+    route_to: "data-scraper"
+    why: "Acquiring documents off the web is data-scraper; processing them once they are on disk is this skill."
+
+# Capability: graded against the must_include rubric.
+capability:
+  - scenario: >
+      The user has a folder of scanned, image-only invoice PDFs (a few pages
+      are handwritten) and wants the line items as CSV. Hard constraint: fully
+      local, no cloud API may be used. Outline the pipeline you would run.
+    must_include:
+      - "Detects or states the PDFs are image-only (no text layer), e.g. via pdfplumber extract_text() returning empty, so OCR is required."
+      - "Picks a LOCAL pipeline (Docling or Marker + Tesseract/RapidOCR), explicitly NOT a hosted API like Mistral OCR, honoring the 'no cloud' constraint."
+      - "Produces Markdown/tables from the OCR, then notes the handoff to structured-extraction for typed line-item fields rather than regexing them here."
+      - "Adds a verification step: spot-check OCR'd totals/numbers against the page image (0/O, 1/l, shifted decimals)."
+      - "Uses current libraries (pypdf / pdfplumber / docling), never PyPDF2."

package/skills/document-processing/references/engines.md

@@ -0,0 +1,67 @@
+# Engines: install, version pins, licensing, troubleshooting
+
+Offloaded depth for `document-processing`. Read before a non-trivial install or when a job hits a quirk.
+
+## Install matrix + version pins
+
+| Library | Install | Pin (current stable, 2026-06) | Notes |
+|---|---|---|---|
+| pypdf | `pip install pypdf` | `pypdf==6.12.2` | Pure-Python, no C deps. Runs in Lambda / slim containers. Core: read/write/merge/split/rotate/forms. |
+| pdfplumber | `pip install pdfplumber` | latest | Layout-aware text + `extract_tables()`. Built on pdfminer.six. |
+| docxtpl | `pip install docxtpl` | `docxtpl==0.20.*` | python-docx-template. Jinja2 over a real `.docx`. Pulls in python-docx + Jinja2. |
+| python-docx | `pip install python-docx` | latest | Programmatic DOCX when you build the doc from code, not from a template. |
+| reportlab | `pip install reportlab` | latest | PDF generation: low-level `canvas` and high-level Platypus flowables. |
+| docling | `pip install docling` | latest | IBM / LF AI local pipeline. First run downloads models. CPU works; GPU is faster. |
+| marker | `pip install marker-pdf` | latest | Datalab pipeline on the Surya engine. PDF/image → Markdown/JSON/HTML. GPU recommended. |
+| pytesseract | `pip install pytesseract` + system Tesseract | latest | Needs the Tesseract binary: macOS `brew install tesseract`, Debian `apt install tesseract-ocr`. Add `tesseract-ocr-<lang>` packs for non-English. |
+| mistralai | `pip install mistralai` | latest | Hosted OCR client. Needs `MISTRAL_API_KEY`. No local model download. |
+| PyMuPDF | `pip install pymupdf` | latest | ⚠️ **AGPL** — see licensing. Fastest extract + easiest page→PNG raster + annotations. |
+
+## Licensing — read before you ship
+
+| Library | License | Implication |
+|---|---|---|
+| pypdf | BSD-3 | Permissive. Ship freely. |
+| pdfplumber | MIT | Permissive. |
+| python-docx / docxtpl | MIT / LGPL-ish | Permissive enough for commercial use. |
+| reportlab | BSD (open-source edition) | Open edition is BSD; "ReportLab PLUS" is the paid product. The `reportlab` PyPI package is the open one. |
+| docling | MIT | Permissive, local, no per-page cost. |
+| marker / surya | check current repo license | Historically had usage-revenue conditions on Surya weights — verify before commercial deployment. |
+| **PyMuPDF** | **AGPL-3.0** | **Network/SaaS use can trigger source-disclosure obligations.** Either comply with AGPL (open your source) or buy Artifex's commercial license. Do not slip it into a closed product silently. |
+| Mistral OCR | Hosted, paid | ~$2 / 1,000 pages; 50% off via Batch API. No code license issue — it is an API. Data leaves the machine. |
+| Tesseract | Apache-2.0 | Permissive, free, local. |
+
+## Local OCR vs hosted: Docling vs Marker vs Mistral
+
+| Dimension | Docling | Marker | Mistral OCR |
+|---|---|---|---|
+| Runs | Local | Local | Hosted API |
+| Cost | Free (compute only) | Free (compute only) | ~$2 / 1k pages (50% off batch) |
+| Best at | Layout + reading order, table structure, many input formats (PDF/DOCX/PPTX/XLSX/HTML/images) | Clean Markdown from PDFs/images, equations, code blocks | Messy scans, handwriting, complex tables, forms |
+| OCR backend | Wraps Tesseract / EasyOCR / RapidOCR | Surya recognition engine | Proprietary (`mistral-ocr-2512`, OCR 3) |
+| Output | Markdown / JSON | Markdown / JSON / HTML | Markdown / JSON, interleaved text+images |
+| Pick when | Data must stay local; batch conversion; varied formats | Local + want deterministic layout parsing | Quality matters more than per-page cost; handwriting; API budget fine |
+
+Decision: **data must stay local → Docling (varied formats) or Marker (PDF→Markdown).** **Handwriting / messy / API budget fine → Mistral OCR.** **Clean scan, zero budget, simple layout → plain `pytesseract`.**
+
+## Troubleshooting
+
+**Encrypted / password PDFs.** `PdfReader` raises on encrypted files. Decrypt first:
+
+```python
+from pypdf import PdfReader
+
+reader = PdfReader("locked.pdf")
+if reader.is_encrypted:
+    reader.decrypt("the-password")  # empty string for owner-locked-but-readable PDFs
+```
+
+Some PDFs are owner-locked (printing/editing disabled) but openable with `reader.decrypt("")`.
+
+**AcroForm fields fill but show blank, or names look mangled.** Dump `get_fields()` and inspect `/FT` and the exact keys — field names are case-sensitive and often have a hierarchy (`section1.name`). For checkbox/radio, the value is the on-state from `/V` (commonly `/Yes`), not `True`. If a fill writes but the viewer renders nothing, the AcroForm may lack `/NeedAppearances`; setting `auto_regenerate=False` and flattening sidesteps appearance-stream issues.
+
+**Multi-column reading order is scrambled.** pdfplumber reads in PDF object order, which can interleave columns. For complex layouts (academic papers, newspapers) prefer Docling/Marker, which do explicit reading-order analysis, over raw pdfplumber text.
+
+**CJK / accented text comes out as boxes or mojibake.** For OCR, install the matching Tesseract language pack (`tesseract-ocr-jpn`, `-chi-sim`, `-cat`, ...) and pass `lang=`. For extraction, the font may lack a ToUnicode map — that is a broken text layer; fall back to OCR. Handwriting: Tesseract is poor; use Mistral OCR.
+
+**Lambda / container cold-start size.** pypdf + pdfplumber are small and pure-Python — fine in a slim image. Docling/Marker pull large model weights — bake them into the image or mount a cache; do not download on every cold start.

package/skills/document-processing/scripts/verify.sh

@@ -0,0 +1,172 @@
+#!/usr/bin/env bash
+#
+# verify.sh — static guardrail for document-processing skill content.
+#
+# WHAT IT DOES (read-only; never edits, moves, runs, or installs anything)
+#   Network-free, dependency-free static checks over a target file or
+#   directory of skill content (defaults to the SKILL.md next to this script).
+#   It does NOT execute any PDF/OCR library — it only greps the text:
+#     1. No dead `import PyPDF2` / `from PyPDF2` — must use the maintained
+#        `pypdf` import.                                            (FAIL)
+#     2. Every form-fill call (`update_page_form_field_values`) sits in a
+#        file that also sets `auto_regenerate=False`.               (FAIL)
+#     3. The OCR guidance names BOTH a local engine (docling/marker/
+#        tesseract) AND the hosted option (mistral).                (FAIL)
+#     4. Code fences are language-tagged (no bare ``` opening a block). (WARN)
+#     5. references/engines.md exists alongside the skill.          (WARN)
+#
+#   Checks 1-3 are hard failures. 4-5 are warnings (don't fail) unless
+#   --strict. An empty / content-free / non-skill target exits 0 — never a
+#   false failure on nothing.
+#
+# HOW TO RUN
+#   bash scripts/verify.sh                 # checks ../SKILL.md by default
+#   bash scripts/verify.sh path/to/SKILL.md
+#   bash scripts/verify.sh path/to/dir/    # checks every *.md under dir
+#   bash scripts/verify.sh --strict ...    # treat warnings as failures
+#
+# EXIT CODES
+#   0  clean, warnings only (without --strict), or empty/non-skill target
+#   1  a hard failure — or any warning under --strict
+#   2  bad usage (target does not exist)
+#
+# Runs on stock macOS bash 3.2: no mapfile, no associative arrays, no bc.
+
+set -u
+
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; NC=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; NC=''
+fi
+
+fail_count=0; warn_count=0
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN"  "$NC" "$*"; }
+warn() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; warn_count=$((warn_count + 1)); }
+fail() { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; fail_count=$((fail_count + 1)); }
+
+STRICT=0
+TARGET=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -h|--help) sed -n '2,46p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    --strict)  STRICT=1; shift ;;
+    -*) printf 'unknown option: %s\n' "$1" >&2; exit 2 ;;
+    *)  if [ -z "$TARGET" ]; then TARGET="$1"; fi; shift ;;
+  esac
+done
+
+# Default target: the SKILL.md beside this script's directory.
+if [ -z "$TARGET" ]; then
+  SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+  TARGET="$SCRIPT_DIR/../SKILL.md"
+fi
+
+if [ ! -e "$TARGET" ]; then
+  printf 'no such target: %s\n' "$TARGET" >&2
+  exit 2
+fi
+
+# Build the list of files to inspect.
+FILES=""
+if [ -d "$TARGET" ]; then
+  FILES="$(find "$TARGET" -name '*.md' -type f 2>/dev/null)"
+  DIR_ROOT="$TARGET"
+else
+  FILES="$TARGET"
+  DIR_ROOT="$(cd "$(dirname "$TARGET")" && pwd)"
+fi
+
+# Nothing with content -> exit 0, no false failure.
+HAS_CONTENT=0
+for f in $FILES; do
+  if [ -s "$f" ] && grep -q '[^[:space:]]' "$f"; then HAS_CONTENT=1; fi
+done
+if [ "$HAS_CONTENT" -eq 0 ]; then
+  ok "empty or content-free target: nothing to verify"
+  exit 0
+fi
+
+# --- 1. No dead PyPDF2 import ----------------------------------------------
+# Only flag a real import line in CODE: skip Markdown table rows (lines
+# starting with '|', where it may be cited as the bad example to AVOID) and
+# inline-code mentions wrapped in backticks within prose.
+PYPDF2_HITS="$(grep -REn 'import[[:space:]]+PyPDF2|from[[:space:]]+PyPDF2' $FILES 2>/dev/null \
+  | grep -vE ':[[:space:]]*\|' \
+  | grep -vE '`[^`]*PyPDF2' || true)"
+if [ -n "$PYPDF2_HITS" ]; then
+  fail "found a PyPDF2 import in code — use the maintained 'pypdf' instead"
+  printf '%s\n' "$PYPDF2_HITS" | sed 's/^/        /'
+else
+  ok "no dead PyPDF2 import in code"
+fi
+
+# --- 2. Form fills set auto_regenerate=False -------------------------------
+for f in $FILES; do
+  if grep -q 'update_page_form_field_values' "$f"; then
+    if grep -q 'auto_regenerate[[:space:]]*=[[:space:]]*False' "$f"; then
+      ok "form-fill in $(basename "$f") sets auto_regenerate=False"
+    else
+      fail "$(basename "$f") fills a form but never sets auto_regenerate=False (spurious 'save changes' prompt)"
+    fi
+  fi
+done
+
+# --- 3. OCR names a local AND a hosted engine ------------------------------
+ALLTEXT="$(cat $FILES 2>/dev/null)"
+if printf '%s' "$ALLTEXT" | grep -qiE 'ocr'; then
+  has_local=0; has_hosted=0
+  printf '%s' "$ALLTEXT" | grep -qiE 'docling|marker|tesseract' && has_local=1
+  printf '%s' "$ALLTEXT" | grep -qiE 'mistral' && has_hosted=1
+  if [ "$has_local" -eq 1 ] && [ "$has_hosted" -eq 1 ]; then
+    ok "OCR guidance names a local engine and the hosted Mistral option"
+  else
+    [ "$has_local" -eq 0 ] && fail "OCR section names no local engine (docling/marker/tesseract)"
+    [ "$has_hosted" -eq 0 ] && fail "OCR section names no hosted option (mistral)"
+  fi
+fi
+
+# --- 4. Code fences are language-tagged (warn) -----------------------------
+for f in $FILES; do
+  # Count fence lines; a bare ``` that OPENS a block (odd-indexed) is untagged.
+  # We approximate: any line that is exactly ``` may be a close OR a bad open.
+  # Flag files where a ``` opener has no language by tracking parity.
+  awk '
+    /^```/ {
+      if (inblock == 0) {
+        # opening fence: must have a language after the backticks
+        if ($0 ~ /^```[[:space:]]*$/) { bad++ }
+        inblock = 1
+      } else {
+        inblock = 0
+      }
+    }
+    END { exit (bad > 0 ? 1 : 0) }
+  ' "$f" || warn "$(basename "$f") has an untagged code fence (bare \`\`\`) — tag the language"
+done
+[ "$warn_count" -eq 0 ] && ok "code fences appear language-tagged"
+
+# --- 5. references/engines.md exists (warn) --------------------------------
+if [ -d "$TARGET" ]; then
+  REF_DIR="$TARGET/references"
+else
+  REF_DIR="$DIR_ROOT/references"
+fi
+if [ -f "$REF_DIR/engines.md" ]; then
+  ok "references/engines.md present"
+else
+  warn "references/engines.md not found at $REF_DIR — install/licensing depth is expected there"
+fi
+
+# --- Summary ---------------------------------------------------------------
+printf '\n'
+if [ "$fail_count" -gt 0 ]; then
+  printf '%s%d failure(s), %d warning(s)%s\n' "$RED" "$fail_count" "$warn_count" "$NC"
+  exit 1
+fi
+if [ "$STRICT" -eq 1 ] && [ "$warn_count" -gt 0 ]; then
+  printf '%s0 failures but %d warning(s) under --strict%s\n' "$YELLOW" "$warn_count" "$NC"
+  exit 1
+fi
+printf '%spassed: 0 failures, %d warning(s)%s\n' "$GREEN" "$warn_count" "$NC"
+exit 0

package/skills/domain-modeling/ADR-FORMAT.md

@@ -0,0 +1,47 @@
+# Formato de ADR
+
+Los ADRs viven en `docs/adr/` y usan numeración secuencial: `0001-slug.md`, `0002-slug.md`, etc.
+
+Crea el directorio `docs/adr/` de forma perezosa — solo cuando haga falta el primer ADR.
+
+## Plantilla
+
+```md
+# {Título corto de la decisión}
+
+{1-3 frases: cuál es el contexto, qué decidimos y por qué.}
+```
+
+Eso es todo. Un ADR puede ser un único párrafo. El valor está en registrar *que* se tomó una decisión y *por qué* — no en rellenar secciones.
+
+## Secciones opcionales
+
+Inclúyelas solo cuando aporten valor genuino. La mayoría de los ADRs no las necesitarán.
+
+- **Status** en el frontmatter (`proposed | accepted | deprecated | superseded by ADR-NNNN`) — útil cuando las decisiones se revisan
+- **Opciones consideradas** — solo cuando las alternativas rechazadas merezcan recordarse
+- **Consecuencias** — solo cuando haya efectos colaterales no obvios que merezca la pena señalar
+
+## Numeración
+
+Escanea `docs/adr/` para encontrar el número más alto existente e incrementa en uno.
+
+## Cuándo ofrecer un ADR
+
+Las tres condiciones deben ser ciertas:
+
+1. **Difícil de revertir** — el coste de cambiar de opinión más adelante es relevante
+2. **Sorprendente sin contexto** — un futuro lector mirará el código y se preguntará "¿por qué demonios lo hicieron así?"
+3. **Resultado de un trade-off real** — había alternativas genuinas y elegiste una por razones específicas
+
+Si una decisión es fácil de revertir, sáltala — simplemente la revertirás. Si no es sorprendente, nadie se preguntará por qué. Si no había una alternativa real, no hay nada que registrar más allá de "hicimos lo obvio".
+
+### Qué califica
+
+- **Forma arquitectónica.** "Usamos un monorepo." "El write model es event-sourced, el read model se proyecta en Postgres."
+- **Patrones de integración entre contextos.** "Ordering y Billing se comunican vía eventos de dominio, no HTTP síncrono."
+- **Elecciones tecnológicas que conllevan lock-in.** Base de datos, message bus, proveedor de auth, target de despliegue. No cada librería — solo las que costaría un trimestre cambiar.
+- **Decisiones de límites y alcance.** "Los datos del Cliente son propiedad del contexto Customer; otros contextos los referencian solo por ID." Los no-s explícitos son tan valiosos como los sí-s.
+- **Desviaciones deliberadas del camino obvio.** "Usamos SQL manual en lugar de un ORM porque X." Cualquier cosa donde un lector razonable asumiría lo contrario. Esto evita que el siguiente ingeniero "arregle" algo que era deliberado.
+- **Restricciones no visibles en el código.** "No podemos usar AWS por requisitos de compliance." "Los tiempos de respuesta deben estar por debajo de 200ms por el contrato de la API del partner."
+- **Alternativas rechazadas cuando el rechazo no es obvio.** Si consideraste GraphQL y elegiste REST por razones sutiles, regístralo — de lo contrario alguien volverá a sugerir GraphQL dentro de seis meses.

package/skills/domain-modeling/CONTEXT-FORMAT.md

@@ -0,0 +1,60 @@
+# Formato de CONTEXT.md
+
+## Estructura
+
+```md
+# {Nombre del Contexto}
+
+{Una o dos frases describiendo qué es este contexto y por qué existe.}
+
+## Lenguaje
+
+**Pedido**:
+{Una o dos frases describiendo el término}
+_Evitar_: Compra, transacción
+
+**Factura**:
+Una solicitud de pago enviada a un cliente tras la entrega.
+_Evitar_: Recibo, solicitud de cobro
+
+**Cliente**:
+Una persona u organización que realiza pedidos.
+_Evitar_: Comprador, usuario, cuenta
+```
+
+## Reglas
+
+- **Sé opinado.** Cuando existan varias palabras para el mismo concepto, elige la mejor y lista las demás bajo `_Evitar_`.
+- **Mantén las definiciones ajustadas.** Una o dos frases como máximo. Define lo que ES, no lo que hace.
+- **Incluye solo términos específicos del contexto de este proyecto.** Los conceptos generales de programación (timeouts, tipos de error, patrones de utilidad) no pertenecen aquí aunque el proyecto los use mucho. Antes de añadir un término pregúntate: ¿es un concepto propio de este contexto, o un concepto general de programación? Solo el primero pertenece.
+- **Agrupa términos bajo subtítulos** cuando emerjan clústeres naturales. Si todos los términos pertenecen a una sola área cohesionada, una lista plana está bien.
+
+## Repos de contexto único vs. múltiple
+
+**Contexto único (la mayoría de los repos):** Un solo `CONTEXT.md` en la raíz del repo.
+
+**Múltiples contextos:** Un `CONTEXT-MAP.md` en la raíz lista los contextos, dónde viven y cómo se relacionan entre sí:
+
+```md
+# Mapa de Contextos
+
+## Contextos
+
+- [Ordering](./src/ordering/CONTEXT.md) — recibe y rastrea los pedidos de clientes
+- [Billing](./src/billing/CONTEXT.md) — genera facturas y procesa pagos
+- [Fulfillment](./src/fulfillment/CONTEXT.md) — gestiona el picking y el envío en el almacén
+
+## Relaciones
+
+- **Ordering → Fulfillment**: Ordering emite eventos `OrderPlaced`; Fulfillment los consume para empezar el picking
+- **Fulfillment → Billing**: Fulfillment emite eventos `ShipmentDispatched`; Billing los consume para generar facturas
+- **Ordering ↔ Billing**: Tipos compartidos para `CustomerId` y `Money`
+```
+
+La skill infiere qué estructura aplica:
+
+- Si existe `CONTEXT-MAP.md`, léelo para encontrar los contextos
+- Si solo existe un `CONTEXT.md` en la raíz, es contexto único
+- Si no existe ninguno, crea un `CONTEXT.md` en la raíz de forma perezosa cuando se resuelva el primer término
+
+Cuando existen múltiples contextos, infiere a cuál corresponde el tema actual. Si no está claro, pregunta.