printedparts stage 11: low-stock email alerts on threshold crossing

Contract 0.12.0: send_email/send_alert join the plugin surface (the
mailer was core-only), PLUGIN-HOOKS and status docs updated, manifest
pins the new floor. The alert fires inside _ledger_write only when a
decrement CROSSES the item's threshold - one alert per depletion,
rearmed by restocking above - and is best-effort after the commit so
mail trouble can never fail a take. Recipients come from
printedparts_alert_email, falling back to the site alert_recipients.
on_enable re-seeds settings idempotently so existing installs pick up
new keys. Crossing/rearm semantics proven by test.

docs/PLUGIN-HOOKS.md

@@ -9,7 +9,7 @@ The contract is locked in [ADR-001](../docs/adr/ADR-001-asset-as-platform-contra
 The framework declares its contract version in `shopdb/__init__.py`:
 
 ```python
-__contract_version__ = '0.11.0'
+__contract_version__ = '0.12.0'
 ```
 
 Each plugin's `manifest.json` declares the range of contract versions it supports:
@@ -479,6 +479,9 @@ What `shopdb.api` exposes:
 - Import mode: `apply_import_timestamps`, `import_mode_active`,
   `parse_import_datetime`
 - Legacy employee directory: `employee_connection`
+- Mailer (0.12.0): `send_email(to, subject, html, text=None)` and
+  `send_alert(subject, html, text=None)` - settings-first, no-op safe when
+  email is unconfigured; send_alert targets the site's alert_recipients
 
 ```python
 from shopdb.api import db, Asset, AssetType, success_response, paginate_query

docs/PLUGIN-LAB-PRINTEDPARTS.md

@@ -286,6 +286,26 @@ Done means: a colleague can clone the repo, enable the plugin, print a bin
 label, and take a part at the kiosk with their badge - without asking you
 anything.
 
+## Stage 11 (extension) - low-stock email alerts
+
+Per-item thresholds already exist; alerting on them is a worked example of a
+CONTRACT ADDITION, because the mailer was not on the plugin surface:
+1. Export `send_email`/`send_alert` from `shopdb/api/__init__.py`, bump
+   `__contract_version__` 0.11.0 -> 0.12.0, and update PLUGIN-HOOKS.md - the
+   docs-drift guard test fails until the doc's version example matches.
+   Manifest pins `core_version >=0.12.0` since the plugin now needs it.
+2. Fire the alert inside `_ledger_write` when a DECREMENT crosses the
+   threshold (before > threshold >= after). Crossing, not being-below, is the
+   natural debounce: one alert per depletion, restocking above rearms.
+   Best-effort try/except AFTER the commit - mail failure must never fail
+   the take.
+3. Recipients: Setting `printedparts_alert_email` (comma-separated), empty
+   falls back to the site's alert_recipients via `send_alert`. Seed the new
+   setting in on_enable too (idempotent) so already-installed sites get it.
+4. Test with a monkeypatched sender: no alert above threshold, one on the
+   crossing, no re-fire while below, rearm after restock (see
+   `test_lowstock_alert_fires_on_crossing_only`).
+
 ---
 
 ## Where each pattern lives (cheat sheet)

docs/ROADMAP.md

@@ -1,6 +1,6 @@
 # Roadmap
 
-shopdb-flask is at `__contract_version__ = '0.11.0'` (pre-1.0; product `__version__ 0.7.0`, tags through v0.7.0). This document captures what stands between today and a stable `1.0.0` release. Maintained as scope evolves; supersedes nothing in the ADRs.
+shopdb-flask is at `__contract_version__ = '0.12.0'` (pre-1.0; product `__version__ 0.7.0`, tags through v0.7.0). This document captures what stands between today and a stable `1.0.0` release. Maintained as scope evolves; supersedes nothing in the ADRs.
 
 ## Phase status