Add native Olist composition sync

README.md

@@ -52,6 +52,21 @@ The scheduled endpoint is API-key protected and returns a summary:
 }
 ```
 
+### Native Olist V3 composition sync
+
+Graphs can connect directly to Olist V3 from `Cadastros`, import manufactured-product structures, and create/update the local catalog and consumption references. Configure these backend environment variables in Portainer before connecting:
+
+```text
+OLIST_CLIENT_ID
+OLIST_CLIENT_SECRET
+OLIST_REDIRECT_URI=https://<backend-host>/api/olist/oauth/callback
+OLIST_FRONTEND_URL=https://<frontend-host>
+OLIST_TOKEN_ENCRYPTION_KEY=<32-byte base64 key or 64-character hex key>
+OLIST_SYNC_ENABLED=true
+```
+
+`OLIST_TOKEN_ENCRYPTION_KEY` must be stable between deploys because Graphs uses it to encrypt OAuth tokens stored in PostgreSQL. The initial sync is full; later scheduled runs are incremental and use the product update date. Manual JSON import remains available as a fallback.
+
 ### Cutting Workbook Import
 
 Manual cutting/replenishment workbooks can be normalized into JSON before they