chore(deps): pin Playwright + jsonschema as dev dependencies (#95 / #94 follow-up) (#100)

* chore(deps): requirements-dev.txt pinning Playwright + jsonschema (#95 / #94)

Pins the two third-party Python packages that the repo's dev tooling
imports, so a fresh clone is reproducible without ambient pip state:

  - playwright>=1.54,<2.0 — tools/capture-gallery-hero.py (#67 / #94 hero PNG)
  - jsonschema>=4.0,<5.0  — verify-plugin.sh, verify-security.sh,
                            verify-seed-expectations.sh, mock-bootstrap.sh,
                            generate-spec-anchor-audit.py

Preview Forge is not a Python package, so no pyproject.toml — a plain
requirements-dev.txt matches the script-driven nature of the Python side.
The capture-gallery-hero.py docstring now references the new install
contract.

Verified:
  - python3 -m pip install -r requirements-dev.txt (fresh venv) — succeeds
  - bash scripts/verify-plugin.sh — Pass: 57 / Fail: 0
  - bash tests/fixtures/security/verify-security.sh — all defenses holding
  - bash tests/e2e/mock-bootstrap.sh {standard,pro,max} — PASS x3

* docs(contributing): Python dev setup section (#95 / #94)

Adds a "Python dev setup (optional, for tooling / verify-* scripts)"
subsection under "Local setup", documenting the requirements-dev.txt
contract added in the preceding commit (Playwright + jsonschema) and
the optional `playwright install` step for hero-screenshot regen.

Notes that Preview Forge is not a Python package (no pyproject.toml)
and that verify-plugin.sh degrades gracefully on missing jsonschema
locally but is fail-closed in CI.

Author: sgwannabe

CONTRIBUTING.md

@@ -60,6 +60,36 @@ claude --plugin-dir ./plugins/preview-forge
 
 Inside Claude Code, try `/pf:help` to see the 14 commands.
 
+### Python dev setup (optional, for tooling / verify-\* scripts)
+
+Preview Forge is primarily JavaScript / Markdown, but a handful of Python
+scripts and tools ship with the repo (hero screenshot helper, schema
+validators embedded in `verify-*` shell harnesses, hooks under
+`plugins/preview-forge/hooks/`). Two third-party packages are pinned in
+[`requirements-dev.txt`](./requirements-dev.txt):
+
+- **`playwright`** — used by `tools/capture-gallery-hero.py` to regenerate
+  `docs/assets/v1.6-gallery-hero.png` (#67 / #94).
+- **`jsonschema`** — used by `scripts/verify-plugin.sh`,
+  `tests/fixtures/security/verify-security.sh`,
+  `tests/fixtures/seed-expectations/verify-seed-expectations.sh`, and
+  `tests/e2e/mock-bootstrap.sh` for schema validation.
+
+Install (once, ideally in a venv):
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate   # optional but recommended
+python3 -m pip install -r requirements-dev.txt
+
+# Only if you need to regenerate the hero screenshot:
+python3 -m playwright install --with-deps firefox chromium
+```
+
+The repo is **not** a Python package — there is no `pyproject.toml` /
+`setup.py`. `requirements-dev.txt` documents the contract; nothing is
+installed by `bash scripts/verify-plugin.sh` itself (it degrades gracefully
+when `jsonschema` is missing, except in CI where it is fail-closed).
+
 ## Contribution types
 
 ### 1. 📚 LESSON (most welcome)

requirements-dev.txt

@@ -0,0 +1,30 @@
+# Dev-only Python dependencies for Preview Forge tooling.
+#
+# Install:
+#   python3 -m pip install -r requirements-dev.txt
+#
+# Browser binaries for Playwright (one-off, after the pip install above):
+#   python3 -m playwright install --with-deps firefox chromium
+#
+# Preview Forge is NOT a Python package (no installable source / __init__.py).
+# These pins exist so the handful of Python *scripts* and *tools* that the
+# repo ships are reproducible without ambient pip state. JS-side tooling
+# stays in package.json / pnpm-workspace.yaml.
+
+# ---------------------------------------------------------------------------
+# Hero screenshot helper
+#   tools/capture-gallery-hero.py — regenerates docs/assets/v1.6-gallery-hero.png
+#   (the README/SUBMISSION above-the-fold gallery hero, #67 / #94).
+# ---------------------------------------------------------------------------
+playwright>=1.54,<2.0
+
+# ---------------------------------------------------------------------------
+# JSON Schema validation (used by several verify-* shell harnesses that
+# embed `python3 -c "import jsonschema; ..."`):
+#   - scripts/verify-plugin.sh                       (profiles schema check)
+#   - tests/fixtures/security/verify-security.sh     (I-7 / S-3 defenses)
+#   - tests/fixtures/seed-expectations/verify-seed-expectations.sh
+#   - tests/e2e/mock-bootstrap.sh                    (previews schema, fail-closed in CI)
+#   - scripts/generate-spec-anchor-audit.py          (optional; degrades gracefully)
+# ---------------------------------------------------------------------------
+jsonschema>=4.0,<5.0

tools/capture-gallery-hero.py

@@ -16,6 +16,15 @@
 
 Determinism: fonts loaded, animations disabled, viewport pinned, file://
 URI. Re-running on the same gallery.html produces a byte-stable PNG.
+
+Setup (#95 / #94 follow-up — Playwright is now a pinned dev dependency):
+
+    python3 -m pip install -r requirements-dev.txt
+    python3 -m playwright install --with-deps firefox chromium
+
+See requirements-dev.txt and CONTRIBUTING.md ("Python dev setup") for the
+full contract. Previously this script relied on an ambient `playwright`
+install; the pin makes it reproducible on a fresh clone.
 """
 from __future__ import annotations