docs: correct and complete the documentation against the code

README.md

@@ -17,7 +17,7 @@ A Kubernetes Operator that maps [OpenVox Server](https://github.com/OpenVoxProje
 - 🔄 **Multi-Version Deployments** - Run different server versions side by side - canary deployments, rolling upgrades
 - 🔒 **Rootless & OpenShift Ready** - Random UID compatible, no root, no ezbake, no privilege escalation
 - 🪶 **Minimal Image** - UBI9-based, no agent Ruby, no ezbake packaging - smaller footprint, fewer updates
-- 🧠 **Auto-tuned JVM** - Heap size calculated from memory limits (90%) - no manual `-Xmx` tuning needed
+- 🧠 **JVM sizing** - Set `javaArgs` per Server or Database; see [Server](docs/reference/server.md) for the current default
 - 📦 **OCI Image Volumes** - Package Puppet code as OCI images, deploy immutably with automatic rollout (K8s 1.35+)
 - 🌐 **Gateway API** - SNI-based TLSRoute support - share a single LoadBalancer across environments via TLS passthrough
 - 🗄️ **Managed OpenVox DB** - Deploy OpenVox DB (PuppetDB) with external PostgreSQL - TLS, config, and credentials managed by the operator

docs/_snippets/features.md

@@ -6,7 +6,7 @@
 - 🔄 **Multi-Version Deployments** - Run different server versions side by side - canary deployments, rolling upgrades
 - 🔒 **Rootless & OpenShift Ready** - Random UID compatible, no root, no ezbake, no privilege escalation
 - 🪶 **Minimal Image** - UBI9-based, no agent Ruby, no ezbake packaging - smaller footprint, fewer updates
-- 🧠 **Auto-tuned JVM** - Heap size calculated from memory limits (90%) - no manual `-Xmx` tuning needed
+- 🧠 **JVM sizing** - Set `javaArgs` per Server or Database; see [Server](reference/server.md) for the current default
 - 📦 **OCI Image Volumes** - Package Puppet code as OCI images, deploy immutably with automatic rollout (K8s 1.35+)
 - 🌐 **Gateway API** - SNI-based TLSRoute support - share a single LoadBalancer across environments via TLS passthrough
 - 🗄️ **Managed OpenVox DB** - Deploy OpenVox DB (PuppetDB) with external PostgreSQL - TLS, config, and credentials managed by the operator

docs/concepts/certificate-signing.md

@@ -29,7 +29,7 @@ sequenceDiagram
     Operator->>K8s: Create PVC ({ca}-data)
     Operator->>K8s: Create Service ({ca}-internal)
     Operator->>K8s: Create ServiceAccount + RBAC
-    Operator->>K8s: Create Job ({ca}-setup)
+    Operator->>K8s: Create Job ({ca}-ca-setup)
     Job->>PVC: Run puppetserver ca setup
     Job->>K8s: Create Secret {ca}-ca (public cert)
     Job->>K8s: Create Secret {ca}-ca-key (private key)

docs/concepts/code-deployment.md

@@ -58,9 +58,9 @@ metadata:
 spec:
   image:
     repository: ghcr.io/slauger/openvox-server-8
-    tag: "8.12.1"
+    tag: "latest"
   code:
-    image: ghcr.io/example/puppet-code:v1.0.0
+    - image: ghcr.io/example/puppet-code:v1.0.0
 ```
 
 ### Pull Policy
@@ -70,8 +70,8 @@ Control when the image is pulled via `imagePullPolicy`. Defaults to `IfNotPresen
 ```yaml
 spec:
   code:
-    image: ghcr.io/example/puppet-code:v1.0.0
-    imagePullPolicy: Always
+    - image: ghcr.io/example/puppet-code:v1.0.0
+      imagePullPolicy: Always
 ```
 
 Supported values: `Always`, `IfNotPresent`, `Never`.
@@ -83,15 +83,15 @@ For immutable, reproducible deployments you can reference images by digest inste
 ```yaml
 spec:
   code:
-    image: ghcr.io/example/puppet-code@sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2
+    - image: ghcr.io/example/puppet-code@sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2
 ```
 
 A tag+digest combination also works:
 
 ```yaml
 spec:
   code:
-    image: ghcr.io/example/puppet-code:v1.0.0@sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2
+    - image: ghcr.io/example/puppet-code:v1.0.0@sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2
 ```
 
 ### Rolling Out Code Changes
@@ -101,7 +101,7 @@ Update the image reference to deploy new code. The operator detects the change a
 ```yaml
 spec:
   code:
-    image: ghcr.io/example/puppet-code:v1.1.0
+    - image: ghcr.io/example/puppet-code:v1.1.0
 ```
 
 ### Private Registries
@@ -111,8 +111,8 @@ For private registries, create a pull secret and reference it:
 ```yaml
 spec:
   code:
-    image: registry.example.com/puppet-code:v1.0.0
-    imagePullSecret: registry-credentials
+    - image: registry.example.com/puppet-code:v1.0.0
+      imagePullSecret: registry-credentials
 ```
 
 ### Rollout Visibility
@@ -163,7 +163,7 @@ spec:
   configRef: production
   certificateRef: canary-cert
   code:
-    image: ghcr.io/example/puppet-code:v2.0.0-rc1
+    - image: ghcr.io/example/puppet-code:v2.0.0-rc1
 ```
 
 ## PVC
@@ -181,9 +181,9 @@ metadata:
 spec:
   image:
     repository: ghcr.io/slauger/openvox-server-8
-    tag: "8.12.1"
+    tag: "latest"
   code:
-    claimName: puppet-code
+    - claimName: puppet-code
 ```
 
 Like the image volume, the PVC is mounted at the configured `environmentPath` (default `/etc/puppetlabs/code/environments`), so its root must contain the environment directories directly (`production/`, `staging/`, ...).

docs/concepts/database.md

@@ -71,10 +71,21 @@ spec:
   databaseRef: production-db   # operator reads Database.status.url
   image:
     repository: ghcr.io/slauger/openvox-server-8
-    tag: "8.12.1"
+    tag: "latest"
 ```
 
-The operator reads `Database.status.url` (e.g. `https://production-db.namespace.svc.cluster.local:8081`) and renders it into `puppetdb.conf`. When the Database is not yet `Running`, the Config controller waits.
+The operator reads `Database.status.url` (e.g. `https://production-db.namespace.svc.cluster.local:8081`) and renders it into `puppetdb.conf`.
+
+When the Database has no URL yet, the Config controller does **not** wait. It
+renders a `puppetdb.conf` without `server_urls` and carries on, so the servers
+start regardless. Combined with `soft_write_failure = true`, which the operator
+always sets, a server in that state compiles catalogs normally while reports
+and exported resources go nowhere and no error is raised.
+
+The Config is re-reconciled when the Database status changes, so this resolves
+by itself during bring-up. It becomes a problem only if the Database never
+reaches `Running`: the symptom is an empty PuppetDB with healthy-looking
+servers, not a failure.
 
 ### Via static `puppetdb.serverUrls`
 

docs/concepts/external-node-classification.md

@@ -136,7 +136,7 @@ spec:
   nodeClassifierRef: pe-classifier
   image:
     repository: ghcr.io/slauger/openvox-server-8
-    tag: "8.12.1"
+    tag: "latest"
 ```
 
 This generates the following puppet.conf entries in the `[server]` section:

docs/concepts/gateway-api.md

@@ -107,14 +107,17 @@ spec:
 
 The `openvox-stack` chart provides a `gateway` section for shared Gateway settings:
 
+A Pool does not name its servers. The relationship runs the other way: each
+entry under `servers` lists the pools it joins via `poolRefs`, and the Pool
+selects those pods through its Service.
+
 ```yaml
 gateway:
   name: puppet-gateway
   sectionName: tls
 
 pools:
   - name: puppet
-    serverRef: ca
     service:
       type: ClusterIP
       port: 8140

docs/concepts/report-processing.md

@@ -107,7 +107,7 @@ spec:
   authorityRef: production-ca
   image:
     repository: ghcr.io/slauger/openvox-server-8
-    tag: "8.12.1"
+    tag: "latest"
 ```
 
 ```yaml

docs/examples/index.md

@@ -13,7 +13,7 @@ spec:
   authorityRef: lab-ca
   image:
     repository: ghcr.io/slauger/openvox-server-8
-    tag: "8.12.1"
+    tag: "latest"
 ---
 apiVersion: openvox.voxpupuli.org/v1alpha1
 kind: CertificateAuthority
@@ -74,7 +74,7 @@ spec:
   databaseRef: production-db
   image:
     repository: ghcr.io/slauger/openvox-server-8
-    tag: "8.12.1"
+    tag: "latest"
   puppet:
     environmentTimeout: unlimited
     storeconfigs: true
@@ -232,7 +232,7 @@ spec:
   replicas: 3
   maxActiveInstances: 2
   code:
-    claimName: puppet-code
+    - claimName: puppet-code
   resources:
     requests:
       cpu: "1"
@@ -250,10 +250,10 @@ spec:
   certificateRef: canary-cert
   poolRefs: [puppet]
   image:
-    tag: "8.13.0"
+    tag: "latest"
   replicas: 1
   code:
-    claimName: puppet-code
+    - claimName: puppet-code
   resources:
     requests:
       cpu: "1"

docs/getting-started/quickstart.md

@@ -75,7 +75,7 @@ This guide sets up an OpenVox Server deployment. Choose between the Helm chart (
       authorityRef: lab-ca
       image:
         repository: ghcr.io/slauger/openvox-server-8
-        tag: "8.12.1"
+        tag: "latest"
     ---
     apiVersion: openvox.voxpupuli.org/v1alpha1
     kind: CertificateAuthority
@@ -162,6 +162,18 @@ NAME                                        TYPE        ENDPOINTS   AGE
 pool.openvox.voxpupuli.org/puppet           ClusterIP   1           2m
 ```
 
+!!! warning "Without a SigningPolicy nothing gets signed"
+
+    The operator points `autosign` at its own binary as soon as a
+    CertificateAuthority exists, and that binary denies every CSR it has no
+    matching policy for. An empty policy list therefore means deny-all, not
+    off.
+
+    Nothing surfaces this. The servers come up, the Config reports `Running`,
+    and every agent sits in `puppet agent --waitforcert` until it gives up.
+    Check with `kubectl get signingpolicy -n <namespace>`; if the list is
+    empty, see [SigningPolicy](../reference/signingpolicy.md).
+
 ## Next Steps
 
 See the [Examples](../examples/index.md) section for production setups with separate CA, server pools, canary deployments, and code deployment via OCI image volumes.

docs/guides/ca-import.md

@@ -28,7 +28,7 @@ If you have an existing CA and want the operator to manage it going forward, you
 
     ```bash
     # Find the PVC
-    kubectl get pvc -l openvox.voxpupuli.org/certificate-authority=production-ca
+    kubectl get pvc -l openvox.voxpupuli.org/certificateauthority=production-ca
 
     # Create a temporary pod to copy data
     kubectl run ca-import --image=busybox --restart=Never \