fix(skill): address CodeRabbit review — shell-safe examples, doc accuracy, F541

Objective: A public reviewer (CodeRabbit) flagged copy-paste examples that break
in a real shell plus a few doc/lint issues in the skill's reference files.

Approach: Fix the verified findings; decline two by repo convention.
- integration-examples.md: the remote-server example used <ANGLE_BRACKET>
  placeholders (a shell parses "<" as input redirection, so the "copy-pasteable"
  command failed before ODL ran) -> quoted env var; the JSON reader now uses a
  context manager; and a note documents that max_chars bounds size BETWEEN
  elements (a single element larger than max_chars is not split).
- options-matrix.md: qualify "a hybrid server is required" for --hybrid-fallback
  (the run then completes via local Java as fallback output, not hybrid); and note
  that formula/picture enrichment needs the hybrid SERVER's --enrich-* flags, not
  just the client's --hybrid-mode full (CodeRabbit's proposed client-flag fix was
  wrong -- those are server startup flags).
- sync-skill-refs.py: drop f-prefixes on placeholder-free strings (Ruff F541).
Declined: pinning actions to commit SHAs (repo convention is floating tags -- the
sibling workflows use actions/checkout@v7 / setup-python@v6 unpinned, so pinning
only these two would be inconsistent) and adding a concurrency group (CodeRabbit
itself marked it low value for these light jobs).

Evidence: ran the fixed code, did not just edit it.
- Extracted the fixed chunk_with_citations from the reference and ran it on real
  ODL JSON: the context-manager path works and chunks carry {page,bbox}; a
  5000-char element with max_chars=1000 becomes its own oversized chunk (matches
  the new note).
- Shell-safety before/after: old form -> "bash: PRIVATE_BIND_ADDRESS: No such
  file or directory"; fixed form resolves to --host 10.0.0.5.
- sync-skill-refs.py still runs (drift 31=31, exit 0); f-prefixes gone; py_compile OK.
- skill-gate PASS (fences, evals schema, cross-refs, compile, drift).

Author: hyunhee-jo

skills/odl-pdf/references/integration-examples.md

@@ -140,7 +140,8 @@ def iter_elements(node):
             yield from iter_elements(v)
 
 def chunk_with_citations(json_path, max_chars=1000):
-    doc = json.loads(open(json_path, encoding="utf-8").read())
+    with open(json_path, encoding="utf-8") as f:
+        doc = json.load(f)
     chunks, buf, buf_len = [], [], 0
     for el in iter_elements(doc):
         text = _text_of(el).strip()
@@ -160,6 +161,9 @@ def chunk_with_citations(json_path, max_chars=1000):
 
 # Each chunk carries the (page, bbox) of every element it contains, so a
 # retrieved chunk can cite the exact page and region it came from.
+# max_chars bounds size BETWEEN elements: a single element longer than max_chars
+# becomes its own chunk that exceeds the bound (elements are not split, to keep
+# each citation's (page, bbox) intact).
 ```
 
 ### LangChain
@@ -285,13 +289,15 @@ opendataloader-pdf input.pdf \
 For multi-machine deployments, run the server on a GPU host and point clients at it.
 
 ```bash
-# GPU host — bind an explicit private address; the server has NO built-in auth
-opendataloader-pdf-hybrid --host <PRIVATE_BIND_ADDRESS> --port 5002
+# GPU host — bind an explicit private address; the server has NO built-in auth.
+# Set this to the host's actual private address (quoted so it is not parsed as a shell redirect).
+HYBRID_HOST=10.0.0.5
+opendataloader-pdf-hybrid --host "$HYBRID_HOST" --port 5002
 
 # Client
 opendataloader-pdf input.pdf \
   --hybrid docling-fast \
-  --hybrid-url http://<gpu-host>:5002 \
+  --hybrid-url "http://$HYBRID_HOST:5002" \
   --hybrid-timeout 30000
 ```
 

skills/odl-pdf/references/options-matrix.md

@@ -111,8 +111,10 @@ from the output, check that `--hybrid-mode full` is set.
 
 **2. `--hybrid` requires a running server**
 
-Setting `--hybrid docling-fast` (or any non-`off` value) without a reachable hybrid server will
-cause requests to fail. Quick start:
+Setting `--hybrid docling-fast` (or any non-`off` value) without a reachable hybrid server makes
+requests fail — **unless `--hybrid-fallback` is set, in which case the run completes via the local
+Java path and returns fallback output (no hybrid OCR/enrichment), which is easy to mistake for a
+successful hybrid extraction** (VERIFY the enrichments actually landed). Quick start:
 
 ```bash
 pip install "opendataloader-pdf[hybrid]"
@@ -226,7 +228,7 @@ opendataloader-pdf input.pdf \
   --hybrid-url http://127.0.0.1:5002
 ```
 
-Do **not** add `--hybrid-fallback` here: this example's goal is enrichment, and on a backend error fallback would yield enrichment-less output that still "succeeds." Add it only when partial local output beats failure — and then verify the enrichments actually landed.
+This is the **client** command; the enrichments only run if the hybrid **server** was started with the matching flags (`--enrich-formula` and/or `--enrich-picture-description`) — `--hybrid-mode full` alone routes pages to the backend but enables neither (Gotcha 2). Do **not** add `--hybrid-fallback` here: this example's goal is enrichment, and on a backend error fallback would yield enrichment-less output that still "succeeds." Add it only when partial local output beats failure — and then verify the enrichments actually landed.
 
 ---
 

skills/odl-pdf/scripts/sync-skill-refs.py

@@ -175,12 +175,12 @@ def main(argv: list[str] | None = None) -> int:
 
     # Report drift
     if new_options:
-        print(f"\nNEW options (in options.json, not in skill):")
+        print("\nNEW options (in options.json, not in skill):")
         for name in new_options:
             print(f"  - {name}")
 
     if removed_options:
-        print(f"\nREMOVED options (in skill, not in options.json):")
+        print("\nREMOVED options (in skill, not in options.json):")
         for name in removed_options:
             print(f"  - {name}")