chore: update config docs

docs/configuration.md

@@ -1,6 +1,6 @@
 # Configuration
 
-The Reference Package is configured using the [application's Helm chart](https://github.com/uds-packages/reference-package/tree/main/.github/container-and-chart/helm/chart), alongside the `uds-reference-package` UDS config chart.
+The Reference Package is configured using the [application's Helm chart](https://github.com/uds-packages/reference-package/tree/main/.github/container-and-chart/helm/chart), alongside the `uds-reference-package-config` UDS config chart.
 
 ## Bundle Overrides
 
@@ -54,15 +54,61 @@ postgres:
   port: 5432
 ```
 
+#### Secrets creation
+
+The Zalando Postgres Operator uses a `{namespace}.{username}` format for the `users` key in its config. That namespace prefix determines **which namespace** the operator places the credentials secret in. Given the following bundle override on the `postgres-operator` package:
+
+```yaml
+overrides:
+  postgres-operator:
+    uds-postgres-config:
+      values:
+        - path: postgresql
+          value:
+            users:
+              reference-package.reference-package: []
+            databases:
+              reference: reference-package.reference-package
+```
+
+The operator creates a secret named `reference-package.reference-package.pg-cluster.credentials.postgresql.acid.zalan.do` in the `reference-package` namespace.
+
+`chart/templates/postgres-secret.yaml` then looks up that secret, extracts the credentials, and writes a `postgres://` connection string into `reference-package-postgres` in the same namespace. The application chart consumes it via the `database` bundle override:
+
+```yaml
+overrides:
+  reference-package:
+    reference-package:
+      values:
+        - path: database
+          value:
+            secretName: "reference-package-postgres"  # must match the secret created by the config chart
+            secretKey: "PASSWORD"
+```
+
+For external databases (non-operator), set `postgres.password` directly and provide the `host`, `dbName`, and connection details for your database service.
+
+> [!IMPORTANT]
+> You can learn more about configuring the databases and operator within the [Postgres Operator docs](https://github.com/zalando/postgres-operator/tree/master/docs).
+
 ### Single Sign-On
 
-Setting `sso.enabled: true` in the UDS config chart overrides tells the package to generate an SSO secret.
+Setting `sso.enabled: true` on the application chart registers the SSO client with Keycloak and wires the resulting credentials into the application.
+
+The UDS Operator reads the SSO configuration from the Package CR (`chart/templates/uds-package.yaml`) and creates a secret named `reference-package-sso` in the `reference-package` namespace. That secret contains:
+
+- `KEYCLOAK_URL`
+- `KEYCLOAK_CLIENT_ID`
+- `KEYCLOAK_CLIENT_SECRET`
+- `APP_CALLBACK_URL`
+
+The application mounts the entire secret as environment variables. The `sso.secretName` value in the bundle override must match the name declared in the Package CR — both default to `reference-package-sso`.
 
-This relies on the UDS Operator's built-in secret templating. You can read more about how this works in the [Register and customize SSO clients](https://docs.defenseunicorns.com/core/how-to-guides/identity--authorization/register-and-customize-sso-clients/) guide.
+You can read more about how UDS Operator SSO secret templating works in the [Register and customize SSO clients](https://docs.defenseunicorns.com/core/how-to-guides/identity--authorization/register-and-customize-sso-clients/) guide.
 
 ### Monitoring
 
-Setting `monitoring.enabled: true` configures the package to expose metrics to Prometheus. More information can be found in the [Capture application metrics](https://docs.defenseunicorns.com/core/how-to-guides/monitoring--observability/capture-application-metrics/) guide.
+Setting `monitoring.enabled: true` configures the package to expose metrics to Prometheus and creates a Grafana dashboard ConfigMap (`chart/templates/grafana-dashboard.yaml`) that Grafana auto-discovers via the `grafana_dashboard: "1"` label. More information can be found in the [Capture application metrics](https://docs.defenseunicorns.com/core/how-to-guides/monitoring--observability/capture-application-metrics/) guide.
 
 ## Package Custom Resources (CR)