Document canonical plugin architecture

examples/plugin_template/README.md

@@ -0,0 +1,44 @@
+# dns-sync plugin template
+
+This directory is a documentation/example package. dns-sync does not load it
+from this location.
+
+Copy it to one of these locations and rename it for the application:
+
+    dns_sync/plugins/adapters/<plugin_name>/
+
+for a built-in plugin, or:
+
+    $DNS_SYNC_PLUGIN_PATH/<plugin_name>/
+
+for an external plugin.
+
+The canonical package layout is:
+
+    <plugin_name>/
+    ├── __init__.py
+    └── client.py
+
+`__init__.py` is the dns-sync adapter boundary. It owns endpoint discovery,
+generic capabilities, native-to-normalized translation, apply, verify, and
+optional retirement behavior.
+
+`client.py` is private to the plugin. It owns authentication, transport,
+application-specific models, native request/response handling, and endpoint
+operations.
+
+## Before enabling a copied plugin
+
+1. Rename `example`, `ExampleClient`, and `ExampleRecord`.
+2. Implement `configured_endpoints(config)`.
+3. Implement the native client methods.
+4. Declare only capabilities the plugin really supports.
+5. Implement discovery for those object types.
+6. Translate normalized desired state into native state in `apply()`.
+7. Re-discover mutations and return the real endpoint-local key.
+8. Implement `verify()`.
+9. Add `retire()` only when retirement/deletion is safely supported.
+10. Add focused adapter/client tests.
+11. Validate using read-only reconciliation before enabling mutations.
+
+See the root `README.md` for the complete plugin contract and architecture.