opencode-skills-collection 4.0.71 → 4.0.72

package/bundled-skills/esl-price-sync/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: esl-price-sync
+description: "Synchronizes retail prices between ERP/POS systems and Electronic Shelf Labels (SES-imagotag, ZKONG, Pricer, Hanshow, SOLUM) with delta watermarking, idempotency, and battery modeling. Trigger phrases: esl price sync, electronic shelf labels, zkong sync, ses imagotag price, ghost pricing audit."
+category: architecture
+risk: safe
+source: community
+source_repo: wwewtech/esl-price-sync
+source_type: community
+date_added: "2026-09-22"
+author: wwewtech
+tags: [retail-tech, esl, iot, supply-chain, systems-integration, enterprise-software]
+tools: [claude, cursor, gemini, windsurf]
+license: "MIT"
+---
+
+# ESL Price Sync: Deterministic Retail Shelf-Edge Pricing Architecture
+
+Ensure strict real-time parity between ERP/POS price masters and Electronic Shelf Label (ESL) fleets (SES-imagotag, ZKONG, Pricer, Hanshow, SOLUM) via bounded delta streams, monotonic idempotency tokens, and Sub-GHz RF battery preservation models.
+
+## When to Use This Skill
+
+Activate this skill when:
+- Designing, implementing, or auditing integration pipelines between enterprise retail masters (SAP, Oracle Retail, Dynamics 365, Lightspeed) and ESL server platforms.
+- The user asks: "How do I sync price updates to ESL tags without draining batteries?", "Debug ghost pricing where POS doesn't match the shelf tag", "Design an idempotent delta feed for ZKONG or SES-imagotag", or "Schedule promotional pricing with automatic rollback".
+- Reconciling price discrepancy logs between central ERP databases, ESL middleware, and wireless base station ACK telemetry.
+- Calculating battery life depletion curves for e-paper tags running on CR2450 coin cells under varying refresh frequencies.
+
+Do NOT use this skill when:
+- Managing e-commerce web store frontends or dynamic pricing algorithms (this skill governs faithful delivery of decided prices to physical tags).
+- Troubleshooting individual dead hardware tags before gateway RF coverage and RSSI signal propagation have been verified.
+- Performing live write operations on production store fleets without a preceding read-only audit verification pass.
+
+## Core Mental Models & Non-Negotiable Rules
+
+1. **The 5-Layer ESL Architecture Pipeline**:
+   - Every price synchronization event traverses five distinct operational tiers:
+     $$\mathbf{Price\ Master\ (ERP/POS)} \xrightarrow{\text{Extract}} \mathbf{Transform\ Middleware} \xrightarrow{\text{API/Message}} \mathbf{ESL\ Server} \xrightarrow{\text{Sub-GHz/2.4GHz}} \mathbf{Base\ Station\ (AP)} \xrightarrow{\text{RF\ Packet}} \mathbf{Physical\ Tag}$$
+   - **Traceability Invariant**: Every price payload MUST carry a deterministic `trace_id` recording timestamps and status codes across all five layers. A "200 OK" from the ESL central server API is NEVER treated as proof that the physical shelf display has updated.
+
+2. **Strict Delta Discipline & Cryptographic Watermarking**:
+   - Pushing a full 50,000-SKU store catalog on a scheduled cron is strictly forbidden.
+   - Updates MUST be generated by calculating a cryptographic row hash:
+     $$\text{RowHash} = \text{SHA256}(\text{SKU} + \text{BasePrice} + \text{PromoPrice} + \text{Currency} + \text{UnitOfMeasure} + \text{Barcode} + \text{TemplateID})$$
+   - Only records where $\text{RowHash}_{new} \neq \text{RowHash}_{pushed}$ are queued for transmission.
+   - Full pushes are strictly restricted to initial store commissioning and disaster recovery restores.
+
+3. **Monotonic Idempotency & Out-of-Order Packet Defense**:
+   - High-volume retail message brokers inevitably deliver packets out of order during network re-balancing.
+   - Every transmission packet MUST include an `idempotency_key` and a monotonically increasing `version_timestamp` (ISO 8601 UTC).
+   - If an incoming price payload has $\text{version\_timestamp} \le \text{last\_applied\_version}$, the ESL middleware MUST discard the payload to eliminate race condition reversions.
+
+4. **RF Gateway Rate-Limiting & Battery Longevity Budget**:
+   - Each physical e-paper display refresh costs between $12\ \mu\text{Ah}$ and $25\ \mu\text{Ah}$.
+   - A dual-CR2450 battery pack provides $1,200\text{ mAh}$ nominal capacity ($960\text{ mAh}$ usable considering passivation and low-temperature shelf environments).
+   - **The 3-Update Daily Rule**: Limiting tag updates to $\le 3$ refreshes per day guarantees a $5.5\text{--}7\text{ year}$ operational lifespan.
+   - **Base Station Queue Throttling**: Gateways operate over shared Sub-GHz (868/915 MHz) or proprietary 2.4 GHz RF channels. Batch transmissions must not exceed 150 tag updates per gateway per minute to prevent RF collision retries from draining batteries.
+
+5. **Read-Only Audit Mode by Default**:
+   - Diagnostic and reconciliation tasks MUST execute in read-only audit mode.
+   - Output discrepancy reports containing SKU, ERP Price, Gateway ACK Price, and Divergence Layer.
+   - State-changing write updates require explicit operator consent.
+
+## Named Sins & Anti-Patterns (Что категорически ЗАПРЕЩЕНО)
+
+| Anti-Pattern | Manifestation in Code/Workflow | Mandatory Production Counter-Rule |
+| :--- | :--- | :--- |
+| **Scheduled Full Catalog Floods** | Blasting 60,000 tags every night at midnight. | Stream strict deltas using SHA256 content watermarks. |
+| **Ghost Price Blindness** | Assuming API `200 OK` means the customer sees the new price. | Track gateway ACK packet receipts (`status: ACK_CONFIRMED`). |
+| **Non-Idempotent Retries** | Retrying failed HTTP calls without idempotency keys. | Attach `UUIDv5(sku, store_id, price_timestamp)` to all mutations. |
+| **Timezone Ambiguity** | Pushing promo prices without UTC/local time offsets. | Enforce ISO 8601 UTC timestamps with explicit store local offsets. |
+| **Gateway RF Flooding** | Blasting 5,000 updates/second to a single RF base station. | Enforce leaky-bucket queue throttling ($\le 150\text{ tags/min/AP}$). |
+| **Silent Canvas Overflow** | Pushing a 6-digit price into a 4-digit template field ($1499 becomes $14). | Validate text bounds and template layout dimensions before enqueueing. |
+| **Destructive Rollback Omission** | Deploying flash sales without pre-computing revert state. | Cache previous active state to enable 1-click atomic rollback. |
+| **Orphan Tag Neglect** | Leaving decommissioned tags in the active database. | Reconcile missing heartbeat tags after 72 hours; flag as `ORPHAN`. |
+| **Mid-Day Peak Syncing** | Pushing massive price shifts during peak Saturday shopping hours. | Schedule bulk promotions before store opening or during off-peak hours. |
+| **Unshielded Write Broadcasts** | Executing write scripts without an audit dry-run. | Enforce dry-run simulation mode prior to initiating physical RF broadcasts. |
+
+## Concrete Archetypes / Presets
+
+### Archetype 1: Idempotent Delta Synchronizer (Python 3.10+)
+```python
+import hashlib
+import time
+from typing import Dict, List, Optional
+
+def compute_sku_hash(item: dict) -> str:
+    payload = f"{item['sku']}:{item['price']}:{item['promo_price']}:{item['uom']}:{item['template']}"
+    return hashlib.sha256(payload.encode('utf-8')).hexdigest()
+
+class ESLDeltaSyncPipeline:
+    def __init__(self, watermark_db: dict, max_rate_per_min: int = 150):
+        self.watermark_db = watermark_db  # SKU -> last_pushed_hash
+        self.max_rate_per_min = max_rate_per_min
+        self.last_tx_time = 0.0
+
+    def process_catalog_stream(self, incoming_feed: List[dict], dry_run: bool = True) -> dict:
+        to_push = []
+        unchanged = 0
+
+        for item in incoming_feed:
+            sku = item['sku']
+            current_hash = compute_sku_hash(item)
+            last_hash = self.watermark_db.get(sku)
+
+            if current_hash != last_hash:
+                idempotency_key = hashlib.sha1(f"{sku}:{item['version']}:{current_hash}".encode()).hexdigest()
+                to_push.append({
+                    "sku": sku,
+                    "tag_id": item['tag_id'],
+                    "price_data": item,
+                    "idempotency_key": idempotency_key,
+                    "content_hash": current_hash
+                })
+            else:
+                unchanged += 1
+
+        if dry_run:
+            return {"mode": "DRY_RUN", "queued_for_rf": len(to_push), "unchanged": unchanged}
+
+        # Rate-limited physical transmission
+        sent = 0
+        min_interval = 60.0 / self.max_rate_per_min
+        for job in to_push:
+            now = time.time()
+            elapsed = now - self.last_tx_time
+            if elapsed < min_interval:
+                time.sleep(min_interval - elapsed)
+
+            transmit_to_esl_gateway(job)
+            self.watermark_db[job['sku']] = job['content_hash']
+            self.last_tx_time = time.time()
+            sent += 1
+
+        return {"mode": "LIVE_COMMITTED", "sent_deltas": sent, "unchanged": unchanged}
+```
+
+### Archetype 2: Reconciliation Audit Report Schema
+```json
+{
+  "audit_timestamp": "2026-09-22T10:15:00Z",
+  "store_id": "STORE-0842",
+  "total_audited_skus": 14200,
+  "in_sync": 14188,
+  "ghost_pricing_discrepancies": [
+    {
+      "sku": "SKU-99014",
+      "barcode": "4006381333931",
+      "tag_mac": "00:1A:7D:DA:71:04",
+      "aisle": "Aisle 4 - Cereals",
+      "erp_master_price": 4.99,
+      "esl_server_price": 4.99,
+      "tag_ack_price": 3.99,
+      "divergence_layer": "RF Base Station (Packet dropped due to antenna shadow)",
+      "last_ack_timestamp": "2026-09-20T04:12:00Z",
+      "recommended_action": "Force targeted re-transmit on Channel 11"
+    }
+  ]
+}
+```
+
+### Archetype 3: Battery Longevity Estimation Model
+```python
+def estimate_tag_battery_years(
+    updates_per_day: float,
+    ambient_temp_celsius: float = 21.0,
+    battery_mah: float = 1200.0,
+    uAh_per_refresh: float = 18.0,
+    standby_uA: float = 1.2
+) -> float:
+    # Temperature de-rating factor (freezer sections de-rate capacity significantly)
+    temp_factor = 0.65 if ambient_temp_celsius < 0.0 else (0.85 if ambient_temp_celsius < 10.0 else 1.0)
+    effective_mah = battery_mah * 0.85 * temp_factor  # 85% usable chemistry margin
+
+    daily_drain_uAh = (updates_per_day * uAh_per_refresh) + (standby_uA * 24.0)
+    daily_drain_mAh = daily_drain_uAh / 1000.0
+
+    lifespan_days = effective_mah / daily_drain_mAh
+    return round(lifespan_days / 365.25, 2)
+```
+
+## The Pre-Emit Quality Gate Checklist
+
+Before finalizing any ESL integration, sync workflow, or audit output:
+- [ ] **Delta Discipline**: Confirmed that only changed row hashes are queued; no scheduled full catalog pushes.
+- [ ] **Idempotency Proof**: Monotonic versioning and idempotency keys attached to every modification payload.
+- [ ] **5-Layer Traceability**: Explicit separation between ERP status, server queue, and base station physical tag ACK.
+- [ ] **RF Rate-Limiting**: Gateway transmission queued at $\le 150$ updates/min per AP.
+- [ ] **Battery Budget Checked**: Verified tag refresh schedule does not breach 3 updates/day lifespan limit.
+- [ ] **Layout Safety**: Text width and font truncation verified against display canvas dimensions.
+- [ ] **Dry-Run Audit Default**: Executed read-only reconciliation prior to proposing live write broadcasts.
+
+## Self-Correction & Verification Loop
+
+### Bad (Vibe-Coded AI Slop Output):
+> "To update the electronic labels, run a Python script that loops over all 50,000 products in your database and POSTs them to the ZKONG API every hour. If prices are wrong on the shelves, just run the script again."
+*Problems: Fatal catalog flooding, battery destruction, zero delta tracking, zero idempotency, ignores gateway rate-limiting, blind to physical tag ACK status.*
+
+### Good (Production ESL Price Sync Output):
+> 1. Execute read-only audit comparing ERP pricing against ESL gateway ACK states; identify 12 divergent SKUs.
+> 2. Compute SHA256 delta hashes for all modified SKUs since watermark `2026-09-22T08:00:00Z`.
+> 3. Generate idempotent mutation payloads with `UUIDv5` tokens and monotonic timestamp versioning.
+> 4. Verify tag layout: Confirm that promo prices fit within the 2.9-inch 3-color e-paper template without numeric truncation.
+> 5. Queue rate-limited dispatch at 120 tags/min on Base Station 03, logging transmission to physical tag ACK confirmation.
+
+## Limitations
+
+- ESL APIs, radio limits, acknowledgements, battery figures, and rate limits depend on the vendor, firmware, tag model, and local radio rules. Confirm each value in the deployed system's documentation before use.
+- Start with read-only reconciliation and a small authorized pilot. A server acknowledgement does not prove the physical label displayed the intended value; require tag-level confirmation and a rollback plan before wider writes.
+- Protect retail pricing, product, and device identifiers as business data. Do not transmit credentials or customer data in diagnostic logs or reports.
+- The scripts and payloads in this guide are illustrative and are not vendor-certified integrations.

package/bundled-skills/marlin-bed-leveling/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: marlin-bed-leveling
+description: "Calibrates Marlin 2.x 3D printer firmware bed leveling: Unified Bed Leveling (UBL), Bilinear ABL, M420 S1 post-homing, Z-probe offsets, G26 mesh prints, and EEPROM slots. Trigger phrases: marlin bed leveling, ubl calibration, m420 s1, z probe offset, g29 bed level, first layer adhesion."
+category: development
+risk: safe
+source: community
+source_repo: wwewtech/marlin-bed-leveling
+source_type: community
+date_added: "2026-09-22"
+author: wwewtech
+tags: [3d-printing, marlin-firmware, gcode, hardware-calibration, fdm, additive-manufacturing]
+tools: [claude, cursor, gemini, windsurf]
+license: "MIT"
+---
+
+# Marlin Bed Leveling: Deterministic Calibration & First-Layer Mesh Engineering
+
+Master Marlin 2.x bed leveling architectures (Unified Bed Leveling UBL, Bilinear ABL, Manual Mesh MBL) to guarantee flawless first-layer adhesion through rigorous G-code phase workflows, probe offset math, and persistent EEPROM compensation.
+
+## When to Use This Skill
+
+Activate this skill when:
+- Calibrating, tuning, or troubleshooting automatic bed leveling on Marlin 2.x 3D printers (Ender 3, CR-10, Prusa clones, custom CoreXY / Cartesian machines).
+- The user asks: "How do I set up UBL in Marlin?", "My printer homes with G28 and ignores the mesh", "Calculate BLTouch Z-probe offset", "Generate G26 validation print G-code", or "Edit warped mesh points with M421".
+- Diagnosing first-layer defects: nozzle dragging across PEI sheets, corner detachment, uneven squish, or compensation disabling after homing.
+- Sizing slicer start G-code sequences (Cura, PrusaSlicer, OrcaSlicer, Bambu Studio) with thermal soaking and mesh restoration.
+
+Do NOT use this skill when:
+- Calibrating Klipper or RepRapFirmware printers (different firmware syntax and mesh compensation systems).
+- Fixing gross mechanical skew: loose V-slot rollers, bent Z leadscrews, or wobbly gantry arms (hardware faults cannot be solved by software leveling).
+- Delta printer kinematics setup requiring radius and tower endstop adjustments before mesh probing.
+
+## Core Mental Models & Non-Negotiable Rules
+
+1. **The Post-Homing Enable Mandate (`G28` Disables Leveling)**:
+   - In Marlin firmware, executing `G28` (Home All Axes) automatically **DISABLES bed leveling compensation by default** (`RESTORE_LEVELING_AFTER_G28` is often disabled in vendor firmware).
+   - In every print start G-code, the leveling restoration command MUST be issued **strictly AFTER `G28`**:
+     ```gcode
+     G28      ; Home all axes (silently turns leveling OFF)
+     M420 S1  ; Re-enable bed leveling compensation from EEPROM mesh
+     ```
+   - Failing to include `M420 S1` (or `G29 A` for UBL) after `G28` causes the printer to execute the entire print with zero leveling compensation.
+
+2. **The 5-Phase UBL Calibration Loop**:
+   Unified Bed Leveling (UBL) is a state machine requiring five sequential phases:
+   - **Phase 1 (Probe Reachable Grid)**: `G29 P1` probes all coordinates physically reachable by the probe offset.
+   - **Phase 2 (Manual Edge Probing)**: `G29 P2` uses a paper feeler gauge for points the BLTouch cannot reach due to gantry geometry.
+   - **Phase 3 (Mathematical Extrapolation)**: `G29 P3 T0.0` fills unprobed edge coordinates by extrapolating slopes from adjacent measured points.
+   - **Phase 4 (Validation & Micro-Tuning)**: `G26 B60 H210 F1.75` prints a single-layer validation test pattern; inspect and edit coordinates with `M421 I... J... Q...`.
+   - **Phase 5 (Storage & Activation)**: `G29 S1` saves to EEPROM mesh slot 1; `G29 A` activates UBL; `M500` commits to permanent EEPROM storage.
+
+3. **Thermal Equilibrium Pre-Flight Invariant**:
+   - Aluminum build plates, magnetic stickers, and spring-steel PEI sheets expand and warp non-linearly under thermal expansion.
+   - Probing a bed at room temperature (20°C) and then printing at 60°C or 100°C bakes a $0.08\text{--}0.20\text{mm}$ error into every mesh point.
+   - **Mandatory Pre-Flight**: Beds MUST be heated to target operating temperature and soaked for $\ge 5\text{ minutes}$ prior to running `G29` probing.
+
+4. **Z-Probe Offset Sign Convention (`M851 Z...`)**:
+   - For downward-deploying probes (BLTouch, CRTouch, inductive sensors) where the probe trigger point triggers *below* the nozzle tip:
+     $$\mathbf{Z\text{-}Offset\ is\ strictly\ NEGATIVE}\ (e.g.,\ \text{M851 Z-1.85})$$
+   - A *positive* Z-offset on a downward-deploying probe instructs the firmware that the nozzle is lower than the probe trigger, driving the nozzle directly into the bed on the first move.
+   - Adjusting Z-offset with paper gauge:
+     - More resistance / tighter squish $\implies$ more negative (e.g., `-1.80` $\to$ `-1.85`).
+     - Less resistance / looser gap $\implies$ less negative (e.g., `-1.80` $\to$ `-1.75`).
+
+5. **Mesh Fade Height Geometry (`M420 Z...`)**:
+   - Leveling compensation must gradually fade out as Z-height increases so top surface layers print geometrically flat rather than conforming to the bed warp.
+   - Set fade height to `M420 Z10.0` (fades compensation smoothly over the first 10mm of print height). Setting `Z0` disables fade (perpetuating bed ripples to the top of the model); setting `Z > 25` is unnecessary ballast.
+
+## Named Sins & Anti-Patterns (Что категорически ЗАПРЕЩЕНО)
+
+| Anti-Pattern | Manifestation in Code/Workflow | Mandatory Production Counter-Rule |
+| :--- | :--- | :--- |
+| **The Forgotten `M420 S1`** | `G28` followed immediately by print moves. | Always place `M420 S1` (or `G29 A`) immediately after `G28`. |
+| **Cold Bed Mesh Probing** | Running `G29 P1` with bed heater at 20°C. | Heat bed to printing temperature and soak for $\ge 5$ minutes first. |
+| **Positive Z-Probe Offset** | Setting `M851 Z+1.5` on a BLTouch probe. | Downward-deploying probes MUST have a negative Z-offset (`M851 Z-...`). |
+| **Unsaved Mesh Discard** | Probing a 7x7 mesh without running `M500`. | Always commit mesh to EEPROM via `G29 S1` followed by `M500`. |
+| **Software-Fixing Physical Tilt** | Compensating for a 2.5mm physical gantry tilt with UBL. | Physically tram bed corners (`G35` or thumb screws) before probing. |
+| **Blind Unchecked Extrapolation** | Running `G29 P3` without verifying boundary values. | Inspect extrapolated border points with `M420 V` or `G29 T`. |
+| **Cold Extruder G26 Validation** | Running G26 test without nozzle heating. | Heat nozzle to printing temperature (`G26 B60 H210 F1.75`). |
+| **Loose Probe Mount Blindness** | Probing while BLTouch bracket has physical wobble. | Check physical probe mount rigidity; probe repeatability requires $s \le 0.005\text{mm}$ (`M48`). |
+| **Excessive Fade Height** | Setting `M420 Z0` or `M420 Z50`. | Use `M420 Z10.0` to smoothly transition from warped bed to true flat geometry. |
+| **Blind Point Over-Editing** | Manually offsetting a single mesh point by 0.5mm via `M421`. | Clean the build plate or check for debris under PEI sheet before altering matrix. |
+
+## Concrete Archetypes / Presets
+
+### Archetype 1: End-to-End Unified Bed Leveling (UBL) Calibration Macro
+```gcode
+; ==============================================================================
+; MARLIN 2.x UBL FULL CALIBRATION SEQUENCE
+; ==============================================================================
+M140 S60         ; Start heating bed to 60°C
+M190 S60         ; Wait for bed to reach 60°C
+G4 S300          ; Thermal soak for 300 seconds (5 minutes)
+
+G28              ; Home all axes
+M117 Probing Reachable Points...
+G29 P1           ; Phase 1: Automated probe of reachable grid points
+
+M117 Extrapolating Mesh Edges...
+G29 P3 T0.0      ; Phase 3: Mathematically extrapolate unprobed perimeter points
+G29 P3 T0.0      ; Second pass to ensure corner fill
+
+G29 T            ; Print ASCII topology matrix to terminal for verification
+G29 S1           ; Save calibrated mesh to EEPROM slot 1
+G29 A            ; Activate UBL leveling system
+M500             ; Save EEPROM permanently to board flash
+M117 UBL Mesh 1 Saved and Activated!
+```
+
+### Archetype 2: Production Slicer Start G-Code (Cura / PrusaSlicer / Orca)
+```gcode
+; ==============================================================================
+; PRODUCTION SLICER START G-CODE (MARLIN UBL / BILINEAR)
+; ==============================================================================
+M140 S[first_layer_bed_temperature]    ; Start heating bed
+M104 S150                              ; Pre-heat nozzle to 150°C (prevent oozing)
+M190 S[first_layer_bed_temperature]    ; Wait for bed to stabilize
+
+G28                                    ; Home all axes (turns leveling OFF)
+M420 S1 Z10.0                          ; Restore mesh from EEPROM & set 10mm fade
+; (OR for UBL: G29 A followed by G29 L1)
+
+G1 Z50 F3000                           ; Move nozzle up to safe clearance
+M109 S[first_layer_temperature]        ; Heat nozzle to final printing temp
+
+; Priming Purge Line on bed edge
+G92 E0                                 ; Reset extruder
+G1 X0.1 Y20 Z0.28 F5000.0              ; Move to start position
+G1 X0.1 Y200.0 Z0.28 F1500.0 E15       ; Draw first purge line
+G1 X0.4 Y200.0 Z0.28 F5000.0           ; Move to side
+G1 X0.4 Y20 Z0.28 F1500.0 E30          ; Draw second purge line
+G92 E0                                 ; Reset extruder
+G1 Z2.0 F3000                          ; Z-hop before moving to print
+```
+
+### Archetype 3: Probe Repeatability & Offset Verification (`M48` & `M851`)
+```gcode
+; ==============================================================================
+; PROBE REPEATABILITY & Z-OFFSET CALIBRATION
+; ==============================================================================
+G28                     ; Home axes
+G1 X117.5 Y117.5 Z10 F5000 ; Move to center of 235x235 bed
+M48 P10 X117.5 Y117.5 V2 E L2 ; Run 10-point repeatability test
+; Standard deviation must be <= 0.005 mm. If > 0.010 mm, tighten probe mount!
+
+; Manual Z-Offset adjustment with paper feeler gauge:
+; 1. Move to Z=0: G1 Z0 F1000
+; 2. Baby-step Z until paper drags with slight friction
+; 3. If nozzle moved down 0.15mm: M851 Z-1.85 (subtract 0.15 from current -1.70)
+; 4. Commit: M500
+```
+
+## The Pre-Emit Quality Gate Checklist
+
+Before emitting any Marlin leveling advice, macro, or slicer start code:
+- [ ] **Post-Homing Verification**: `M420 S1` (or `G29 A`) placed strictly after `G28` in the execution flow.
+- [ ] **Thermal Soak Pre-Flight**: Bed heating and 5-minute soak mandated prior to `G29` probing.
+- [ ] **Negative Offset Math**: Downward-deploying probes have verified negative `M851 Z-...` values.
+- [ ] **EEPROM Commit**: `G29 S1` followed immediately by `M500` to preserve the mesh.
+- [ ] **Fade Height Limit**: `M420 Z10.0` configured for smooth transition to flat geometry.
+- [ ] **Physical Tramming Precedence**: Confirmed that manual corner leveling is performed before software compensation.
+- [ ] **Probe Repeatability**: Confirmed that `M48` probe standard deviation is $\le 0.005\text{mm}$.
+
+## Self-Correction & Verification Loop
+
+### Bad (Vibe-Coded AI Slop Output):
+> "Put `G29` before `G28` in your start G-code. If your BLTouch is scraping, set `M851 Z1.5`. You don't need to heat the bed during leveling because Marlin compensates for it automatically."
+*Problems: Fatal G28 homing wipes out the preceding G29 mesh, positive Z-offset crashes nozzle into bed, dangerous cold probing advice.*
+
+### Good (Production Marlin Bed Leveling Output):
+> 1. Tram the four bed corners manually using `G35` or thumb screws to get mechanical variance under $\pm 0.1\text{mm}$.
+> 2. Heat bed to 60°C and nozzle to 150°C; let soak for 5 minutes so thermal expansion stabilizes.
+> 3. Verify probe repeatability using `M48 P10` (standard deviation must be $\le 0.005\text{mm}$).
+> 4. Probe grid with `G29 P1`, extrapolate unprobed corners with `G29 P3 T0.0`, save to slot 1 with `G29 S1`, and commit to flash with `M500`.
+> 5. In your slicer start G-code, place `M420 S1 Z10.0` immediately after `G28` to restore the active mesh with a 10mm fade height.
+
+## Limitations
+
+- Marlin commands and mesh behavior vary with firmware version, configuration, probe, bed geometry, and slicer. Check the exact firmware build and printer documentation before applying a macro or offset.
+- G-code can move a hot toolhead and damage equipment or cause burns. Supervise calibration, keep hands clear, use the printer's emergency stop when motion is unsafe, and verify travel limits before running generated sequences.
+- Example coordinates, temperatures, tolerances, and fade values are illustrative; measure the actual printer and follow the manufacturer’s limits.

package/bundled-skills/oneroster-csv-validator/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: oneroster-csv-validator
+description: "Validates 1EdTech / IMS Global OneRoster v1.1 and v1.2 CSV roster sets: manifest integrity, bulk vs delta strictness, foreign key references, and encoding sanitization. Trigger phrases: oneroster csv validator, validate oneroster zip, clever roster error, oneroster sourcedid."
+category: testing
+risk: safe
+source: community
+source_repo: wwewtech/oneroster-csv-validator
+source_type: community
+date_added: "2026-09-22"
+author: wwewtech
+tags: [edtech, oneroster, csv-validation, ims-global, 1edtech, data-engineering]
+tools: [claude, cursor, gemini, windsurf]
+license: "MIT"
+---
+
+# OneRoster CSV Validator: Strict 1EdTech Data Integrity & Pre-Flight Linter
+
+Perform rigorous pre-flight validation on OneRoster v1.1 and v1.2 CSV roster bundles prior to SIS/Clever/ClassLink ingestion: audit foreign key referential integrity, eliminate orphan enrollments, enforce bulk vs delta partitioning, and sanitize encoding traps.
+
+## When to Use This Skill
+
+Activate this skill when:
+- Validating or debugging student information system (SIS) roster export packages (`.zip` archives or CSV directories) for OneRoster v1.1 or v1.2 compliance.
+- The user asks: "Why is Clever rejecting our OneRoster zip file?", "Check for orphaned userSourcedIds in enrollments.csv", "Validate bulk vs delta mode in OneRoster CSVs", or "Sanitize UTF-8 BOM characters from school rosters".
+- Auditing relational integrity across `manifest.csv`, `orgs.csv`, `users.csv`, `courses.csv`, `classes.csv`, `enrollments.csv`, and `academicSessions.csv`.
+- Preparing automated pre-flight CI/CD pipelines to catch corrupted student or teacher records before nightly SIS sync runs.
+
+Do NOT use this skill when:
+- Integrating OneRoster REST / OAuth 2.0 API endpoints (this skill focuses strictly on CSV table bindings).
+- Generating synthetic or fabricated student PII without authorization.
+- Working on generic non-standard CSV spreadsheets that do not follow 1EdTech specifications.
+
+## Core Mental Models & Non-Negotiable Rules
+
+1. **The Manifest Root Authority Law**:
+   - `manifest.csv` MUST reside strictly at the root level of the ZIP archive (never nested inside a subfolder).
+   - It MUST declare the exact specification version: `oneroster.version,1.1` or `oneroster.version,1.2`.
+   - It MUST list every single file present in the exchange. If a CSV file is present in the archive but omitted from `manifest.csv`, or listed in `manifest.csv` but missing from the zip, the package is rejected.
+
+2. **The Strict Bulk vs Delta Partition**:
+   - One exchange bundle = strictly ONE operational mode.
+   - **Bulk Exchange Mode**: Represents a complete master snapshot. In OneRoster 1.1, rows MUST NOT contain `dateLastModified` or `status` columns. In 1.2, all status fields MUST be `active`.
+   - **Delta Exchange Mode**: Represents incremental changes. Every row MUST contain a valid ISO 8601 UTC timestamp (`YYYY-MM-DDTHH:MM:SS.sssZ`) in `dateLastModified` and a valid status (`active` or `tobedeleted`).
+   - Mixing bulk and delta formats within the same archive is a fatal validation failure.
+
+3. **The Foreign Key Referential Integrity Hierarchy**:
+   - Relational dependency chain:
+     $$\mathbf{orgs.csv} \longleftarrow \mathbf{courses.csv} \longleftarrow \mathbf{classes.csv} \longleftarrow \mathbf{enrollments.csv} \longrightarrow \mathbf{users.csv}$$
+   - Every `schoolSourcedId` in `users.csv` and `classes.csv` MUST resolve to an existing `sourcedId` in `orgs.csv`.
+   - Every `courseSourcedId` in `classes.csv` MUST resolve to `courses.csv`.
+   - Every `userSourcedId` and `classSourcedId` in `enrollments.csv` MUST resolve to active primary keys in `users.csv` and `classes.csv`.
+   - **Zero Orphan Tolerance**: A single orphan link (e.g. enrolling a deleted student ID) invalidates the batch.
+
+4. **Strict Role Enum Constraint Axioms**:
+   - In `users.csv`: `role` MUST strictly match the OneRoster enum:
+     - v1.1: `administrator`, `proctor`, `student`, `teacher`.
+     - v1.2: adds `aide`, `guardian`, `parent`, `staff`.
+   - In `enrollments.csv`: `role` is strictly constrained to `administrator`, `proctor`, `student`, `teacher`. Custom vendor roles (`substitute`, `dean`) must be mapped to valid specification enums.
+   - Primary `sourcedId` values MUST be case-sensitively unique strings (RFC 4122 UUID format strongly recommended).
+
+5. **RFC 4180 CSV & UTF-8 BOM Sanitization**:
+   - Files MUST be encoded in **UTF-8 without Byte Order Mark (BOM)**.
+   - Microsoft Excel frequently prepends `\xEF\xBB\xBF` to CSV exports, corrupting the first column name (`sourcedId` $\neq$ `sourcedId`).
+   - Fields containing commas, double-quotes, or newlines MUST be enclosed in double quotes (`"`). Literal quotes inside fields must be escaped as `""`.
+
+## Named Sins & Anti-Patterns (Что категорически ЗАПРЕЩЕНО)
+
+| Anti-Pattern | Manifestation in CSV Packages | Mandatory Production Counter-Rule |
+| :--- | :--- | :--- |
+| **Nested Archive Packaging** | Zipping a parent folder (`district_roster/manifest.csv`). | Manifest and CSVs MUST reside at the archive root (`/manifest.csv`). |
+| **The UTF-8 BOM Trap** | Excel export injecting `\xEF\xBB\xBF` into `sourcedId`. | Strip BOM headers during pre-flight sanitization pass. |
+| **Orphan Enrollment Links** | `enrollments.csv` pointing to non-existent user IDs. | Enforce foreign key validation across all entity files before import. |
+| **Bulk / Delta Column Bleed** | Including `dateLastModified` or `tobedeleted` in bulk. | Enforce schema separation: bulk files must not contain delta headers. |
+| **Circular Org Hierarchies** | School A listed as parent of School B, and vice-versa. | Perform directed acyclic graph (DAG) cycle detection on `orgs.csv`. |
+| **Illegal Role Strings** | Using non-standard strings like `counselor` or `sub`. | Map all roles to standard enums (`administrator`, `teacher`, `student`). |
+| **Malformed ISO 8601 Timestamps** | Writing `"09/22/2026 14:00"` instead of ISO 8601. | Enforce strict RFC 3339 UTC format: `YYYY-MM-DDTHH:MM:SS.sssZ`. |
+| **Unescaped CSV Commas** | Unquoted commas in user names (`Doe, John`) shifting columns. | Wrap text fields containing commas in standard RFC 4180 quotes. |
+| **Missing Mandatory Core Files** | Exporting a bulk zip without `academicSessions.csv`. | Confirm all 7 mandatory core files exist in zip and manifest. |
+| **Hallucinated SourcedIDs** | Inventing arbitrary IDs during reconciliation. | Preserve authoritative SIS primary keys without synthetic generation. |
+
+## Concrete Archetypes / Presets
+
+### Archetype 1: Pre-Flight Python Referential Integrity Linter
+```python
+import csv
+import io
+import re
+import zipfile
+from typing import Dict, List, Set
+
+CORE_FILES = [
+    "manifest.csv", "orgs.csv", "users.csv", "courses.csv",
+    "classes.csv", "enrollments.csv", "academicSessions.csv"
+]
+VALID_ROLES_1_1 = {"administrator", "proctor", "student", "teacher"}
+
+def validate_oneroster_archive(zip_path: str) -> dict:
+    errors = []
+    warnings = []
+
+    with zipfile.ZipFile(zip_path, 'r') as z:
+        names = z.namelist()
+
+        # 1. Manifest Root Check
+        if "manifest.csv" not in names:
+            return {"status": "FATAL", "errors": ["manifest.csv missing from zip root."]}
+
+        # 2. Extract and Parse Core Sets
+        data: Dict[str, List[dict]] = {}
+        keys: Dict[str, Set[str]] = {}
+
+        for filename in CORE_FILES:
+            if filename in names:
+                raw_bytes = z.read(filename)
+                # Strip UTF-8 BOM if present
+                if raw_bytes.startswith(b'\xef\xbb\xbf'):
+                    warnings.append(f"{filename} contains UTF-8 BOM; stripped automatically.")
+                    raw_bytes = raw_bytes[3:]
+
+                reader = csv.DictReader(io.StringIO(raw_bytes.decode('utf-8', errors='replace')))
+                rows = list(reader)
+                data[filename] = rows
+                if rows and "sourcedId" in rows[0]:
+                    keys[filename] = {r["sourcedId"] for r in rows if "sourcedId" in r}
+            else:
+                errors.append(f"Mandatory core file missing: {filename}")
+
+        # 3. Foreign Key Checks
+        if "orgs.csv" in keys and "users.csv" in data:
+            for r in data["users.csv"]:
+                org_ref = r.get("orgSourcedIds") or r.get("schoolSourcedId")
+                if org_ref and org_ref not in keys["orgs.csv"]:
+                    errors.append(f"users.csv: user {r.get('sourcedId')} references non-existent org {org_ref}")
+
+        if "users.csv" in keys and "classes.csv" in keys and "enrollments.csv" in data:
+            for r in data["enrollments.csv"]:
+                uid = r.get("userSourcedId")
+                cid = r.get("classSourcedId")
+                if uid not in keys["users.csv"]:
+                    errors.append(f"enrollments.csv: orphan enrollment references missing user {uid}")
+                if cid not in keys["classes.csv"]:
+                    errors.append(f"enrollments.csv: orphan enrollment references missing class {cid}")
+
+                role = r.get("role")
+                if role not in VALID_ROLES_1_1:
+                    errors.append(f"enrollments.csv: illegal role '{role}' on user {uid}")
+
+    return {
+        "status": "FAILED" if errors else "PASSED",
+        "errors": errors,
+        "warnings": warnings,
+        "total_records_checked": sum(len(v) for v in data.values())
+    }
+```
+
+### Archetype 2: Minimal Valid OneRoster v1.1 Manifest
+```csv
+propertyName,value
+oneroster.version,1.1
+file.orgs,bulk
+file.users,bulk
+file.courses,bulk
+file.classes,bulk
+file.enrollments,bulk
+file.academicSessions,bulk
+```
+
+### Archetype 3: Delta Synchronization Row Example
+```csv
+sourcedId,status,dateLastModified,userSourcedId,classSourcedId,role,primary
+enr_99201,active,2026-09-22T08:30:00.000Z,usr_0421,cls_bio101,student,true
+enr_99202,tobedeleted,2026-09-22T08:30:00.000Z,usr_0884,cls_bio101,student,false
+```
+
+## The Pre-Emit Quality Gate Checklist
+
+Before emitting validation results, CSV transforms, or roster scripts:
+- [ ] **Root Location**: Confirmed `manifest.csv` is located strictly at `/` without folder nesting.
+- [ ] **BOM Scrubbing**: Verified all CSV headers are clean UTF-8 without `\xEF\xBB\xBF`.
+- [ ] **Mode Consistency**: Verified no delta columns exist in bulk packages, and timestamps exist in deltas.
+- [ ] **Referential Integrity**: 100% check of `userSourcedId`, `classSourcedId`, `orgSourcedIds`, and `courseSourcedId`.
+- [ ] **Role Enum Validation**: Confirmed all role values match 1EdTech specifications.
+- [ ] **Cycle-Free Orgs**: DAG validation run on `orgs.csv` to ensure no circular parent references.
+- [ ] **RFC 4180 Escaping**: Commas, quotes, and multi-line values enclosed in double quotes.
+
+## Self-Correction & Verification Loop
+
+### Bad (Vibe-Coded AI Slop Output):
+> "Zip your CSV folder up and upload it. If Clever says there is a missing manifest, just add a blank manifest.csv inside the folder. If some student IDs are missing in enrollments, just delete those rows or invent temporary user IDs."
+*Problems: Nested zip breaks root discovery, blank manifest violates schema, inventing fake IDs corrupts student records, ignores UTF-8 BOM.*
+
+### Good (Production OneRoster CSV Validator Output):
+> 1. Extract zip to verify `/manifest.csv` exists at the root path; confirm `oneroster.version` is declared as `1.1`.
+> 2. Scan all CSV headers: detect and strip UTF-8 BOM (`\xEF\xBB\xBF`) from `users.csv` to prevent header corruption.
+> 3. Perform foreign key referential integrity pass:
+>    - Flag 4 orphan rows in `enrollments.csv` referencing deleted student ID `usr_9914`.
+>    - Flag invalid role `"substitute_teacher"` on row 14 of `enrollments.csv` (must map to `"teacher"`).
+> 4. Verify bulk purity: confirm no `dateLastModified` or `tobedeleted` status flags are present in bulk mode.
+> 5. Emit clean, line-numbered pre-flight audit report before committing to SIS ingestion.
+
+## Limitations
+
+- OneRoster version details and required files can differ by exchange profile and vendor implementation. Validate against the exact 1EdTech specification and recipient's current import contract before rejecting or transforming a roster.
+- Student and staff roster files contain sensitive education records. Process only with authorization, minimize retained data, redact identifiers in diagnostics, and do not upload source CSVs to external services.
+- The included snippets are illustrative, not a complete certified validator; for example, large files, namespaces, delta semantics, and vendor extensions require additional handling and tests.

package/bundled-skills/telegram-mini-app/references/detailed-guide.md

@@ -172,9 +172,35 @@ Making money from Mini Apps
 | TON payments | Premium features | High |
 | In-app purchases | Virtual goods | High |
 | Ads (Telegram Ads) | Display ads | Medium |
+| In-app ad networks (e.g. TADS) | Native / fullscreen / rewarded ads inside the Mini App | Medium |
 | Referral | Share to earn | Medium |
 | NFT sales | Digital collectibles | High |
 
+### In-app ads (rewarded and native)
+
+Ad networks built for Mini Apps serve ads inside the app itself, so you keep the user in the flow and can reward them (extra life, coins) for a click or a full view. Example with [TADS](https://tads.me) (`npm install react-tads-widget`):
+
+```jsx
+import { TadsWidgetProvider, TadsWidget } from 'react-tads-widget';
+
+// wrap the app once
+<TadsWidgetProvider><App /></TadsWidgetProvider>
+
+// native block inside content; onClickReward makes it a rewarded ad
+<TadsWidget id="YOUR_WIDGET_ID" type="static"
+  onClickReward={() => grantBonus()}
+  onAdsNotFound={() => hidePlaceholder()} />
+```
+
+Fullscreen ads work the same way with `type="fullscreen"` and `onShowReward`; show them on a user action, never on load. Agent-readable docs: https://tads.me/llms.txt
+
+#### Advertising safety and limitations
+
+- Confirm the network, widget format, reward rules, Telegram requirements, and applicable privacy obligations for the app and audience before deployment. Tell users when content is an ad and what action earns a reward.
+- Treat click/show callbacks as client-side UI signals only. Do not use them alone to grant transferable or purchasable value; validate reward events with a trusted server-side source where available, and make grants idempotent and abuse-resistant.
+- Keep ad display optional and user-initiated where the format calls for it. Never show a fullscreen ad automatically on app load or make an ad interaction the only way to use a core feature.
+- SDK APIs and publisher terms can change. Check the current TADS documentation and package version before copying examples into production.
+
 ### Telegram Stars (New!)
 ```javascript
 // In your bot

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-skills-collection",
-  "version": "4.0.71",
+  "version": "4.0.72",
   "description": "OpenCode CLI plugin that automatically downloads and keeps skills up to date.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",