Docs: document secrets refs runtime and migration

docs/gateway/configuration.md

@@ -492,6 +492,34 @@ Rules:
 
 </Accordion>
 
+<Accordion title="Secret refs (env and encrypted file)">
+  For fields that support SecretRef objects, you can use:
+
+```json5
+{
+  models: {
+    providers: {
+      openai: { apiKey: { source: "env", id: "OPENAI_API_KEY" } },
+    },
+  },
+  skills: {
+    entries: {
+      "nano-banana-pro": {
+        apiKey: { source: "file", id: "/skills/entries/nano-banana-pro/apiKey" },
+      },
+    },
+  },
+  channels: {
+    googlechat: {
+      serviceAccountRef: { source: "file", id: "/channels/googlechat/serviceAccount" },
+    },
+  },
+}
+```
+
+SecretRef details (including `secrets.sources.file` for `sops`) are in [Secrets Management](/gateway/secrets).
+</Accordion>
+
 See [Environment](/help/environment) for full precedence and sources.
 
 ## Full reference