docs(readme): let Claude have a go at making a fancy README to describe the repo so far

README.md

@@ -1,3 +1,76 @@
-# genieACS-projects
+# genieACS Projects
 
-Collection of genieACS or TR069/TR369-related projects
+> A collection of extensions and provisioning scripts for [genieACS](https://genieacs.com/) — an open-source TR-069/TR-369 ACS (Auto Configuration Server) for managing CPE devices at scale.
+
+---
+
+## Overview
+
+This repository contains scripts that automate device configuration through the genieACS platform, targeting TP-Link ONU (Optical Network Unit) hardware. The scripts are structured around the two main genieACS script types: **extensions** (server-side helper functions) and **provisions** (device-lifecycle automation).
+
+---
+
+## Repository Structure
+
+```
+genieACS-projects/
+├── extensions/
+│   └── TPLink-ONU-VOIP-mapping.js      # API helper: resolves VOIP VLAN name by device ID
+└── provisions/
+    └── TPLink-ONU-VOIP-binding-fix.js  # Provision: binds VOIP VLAN interface on TP-Link ONUs
+```
+
+---
+
+## Scripts
+
+### `extensions/TPLink-ONU-VOIP-mapping.js`
+
+A genieACS **extension** that exposes a helper callable from any provision script.
+
+**What it does:**
+- Queries the genieACS NBI (Northbound Interface) REST API for a given device ID
+- Retrieves all `Device.Ethernet.VLANTermination.*` instances from the device's parameter tree
+- Finds the VLAN termination entry where `VLANID = 20` (the designated VOIP VLAN)
+- Returns the `Name` of that termination (e.g. `"veip0.20"`) for use downstream
+
+**Key config:**
+
+| Variable | Default | Description |
+|---|---|---|
+| `GENIEACS_URL` | `http://10.5.2.111:7557` | Base URL of the genieACS NBI |
+
+---
+
+### `provisions/TPLink-ONU-VOIP-binding-fix.js`
+
+A genieACS **provision** script that runs during the inform cycle of TP-Link XX230v ONU devices.
+
+**What it does:**
+1. Declares and caches the device's VLAN termination data (`VLANID` + `Name` properties)
+2. Calls the `TPLink-ONU-VOIP-mapping` extension to resolve the correct VOIP interface name
+3. Writes the resolved name to both VOIP binding parameters on the device:
+   - `Device.Services.VoiceService.1.X_TP_BoundIfName`
+   - `Device.X_TP_Services.X_TP_VoiceService.1.BoundIfName`
+
+This ensures VOIP traffic is always bound to the correct VLAN interface, even after resets or re-provisioning.
+
+---
+
+## Protocol Background
+
+| Term | Meaning |
+|---|---|
+| **TR-069** | Broadband Forum standard for CPE remote management over CWMP |
+| **genieACS** | Open-source ACS implementing TR-069; manages device parameters via provisions and extensions |
+| **ONU** | Optical Network Unit — the customer-side fiber termination device |
+| **VLAN** | Virtual LAN; used here to segment VOIP traffic onto a dedicated logical interface |
+| **NBI** | genieACS Northbound Interface — the REST API used by extensions to query device data |
+
+---
+
+## Requirements
+
+- A running [genieACS](https://github.com/genieacs/genieacs) instance
+- Axios available in the genieACS extension environment
+- TP-Link XX230v ONU devices managed by the ACS