feat(paperless-ngx)!: quote every operator scalar, pin the consume mover, drop oidcSecretRef

Three issues on one chart, bundled because they share values.yaml,
values.schema.json and the version line, and because the first half of #11
lives in the same template as #101.

Gitea #11, first half: the consume CronJob's schedule was rendered bare, so a
schedule in the commonest cron notation there is - a star, a slash, an interval
- aborted the render with a YAML parse error pointing at the template while the
operator's value appeared nowhere in the message. Quoting it in the values file
does not help; Helm passes the content through. Reproduced before the fix, at
the line the issue names, and fixed with | quote.

Gitea #11, second half: secrets.oidcSecretRef is removed, values and schema
both. No template ever read it, so no OnePasswordItem was created and nothing
reached the pod - the quiet kind of defect that looks like successful
configuration. It is not reimplemented, and the reason is in paperless: the
whole OIDC configuration travels in one json environment variable with no _FILE
variant, so a secretKeyRef cannot substitute a fragment into it. The
operational question is answered by #83 - Keycloak marks a client public per
client, so nothing forces a confidential one here.

In the same breath, oidc.provider.tokenAuthMethod is restricted to "none". Its
comment named client_secret_basic as the example, which asks the provider for
an authentication this chart cannot perform: it configures no client secret and
cannot. The two values read together looked like a working secret setup, and the
symptom was a login dying at the callback with invalid_client. No live release
sets it (measured against all three instances).

Gitea #112 asked for an extraEnv and the chart already had the standard
additive env block - the issue was measured against a deployed 12.2.0 and read
only the top-level keys. What was actually broken is the block itself: it
rendered its operand bare, so a "*"-leading value aborted the render and "true"
or "0755" arrived as a bool or an integer, which the API server rejects after a
green render. It is brought to the repository's documented quoted form
(template-chart carries the rule), which is what makes an arbitrary PAPERLESS_*
variable settable in practice. PAPERLESS_LOGGING_DIR is documented as the
worked example, with the cross-reference it needs: the root cause is the
NFS-exported RWX data volume in jk-cluster-config #360 and this does not fix it
- it only moves the log off that volume. The two Ingress upload-size
annotations had the same bare render and are quoted too.

Gitea #101: the consume mover now runs on the node of the StatefulSet pod, via
a required podAffinity on its label. It mounts the RWX consume volume, and
Longhorn's CSI driver refuses that mount unless it finds a workload pod in
Pending, so a mover on another node left the StatefulSet node's kubelet
retrying every two minutes - 291 events in 10 hours in both releases with SMB
on, none in the release without the CronJob. A static nodeSelector would be
wrong because the StatefulSet pod is not pinned either, and preferred would
reproduce the bug more rarely and harder to find.

The cost of a required term is handled rather than left open:
concurrencyPolicy: Forbid, a startingDeadlineSeconds that also keeps the
controller away from its 100-missed-schedules stop, and an activeDeadlineSeconds
that fails a job which cannot be placed instead of leaving one Pending pod per
schedule. scaleDown already suspends the CronJob; what remains is
paperless.replicas: 0 with SMB on, which now reports a bounded, visible failure.
successfulJobsHistoryLimit is deliberately untouched: Longhorn's check asks for
the existence of a Pending pod, not the absence of Succeeded ones, so those
three pods are the error message's evidence and not its cause.

Side defect fixed on the way: every read of smbConnection.cron dereferenced the
block directly, so an override that had erased it aborted with a nil-pointer
error naming an internal template path instead of falling back to the defaults
this chart promises everywhere else. Measured on origin/main; all reads now go
through a merged-defaults helper that preserves an explicit false.

Major: a value is removed and fails the strict schema afterwards, and runtime
placement changes.

Fixes #11
Fixes #101
Fixes #112

paperless-ngx/values.yaml

@@ -13,7 +13,26 @@ secrets:
   databaseSecretRef: null
   paperlessSecretRef: null
   smbConnectionSecretRef: null
-  oidcSecretRef: null
+  # REMOVED IN 13.0.0: secrets.oidcSecretRef (Gitea #11). It is gone from the
+  # schema too, so a release that still sets it now fails to render with
+  #     additional properties 'oidcSecretRef' not allowed
+  # instead of being ignored - DELETE THE KEY from your values, nothing else is
+  # needed. It never did anything: no template read it, no OnePasswordItem was
+  # created for it, and whatever the item held never reached the pod.
+  #
+  # It is not coming back as a feature, and the reason is in paperless itself:
+  # the whole OIDC configuration travels in ONE json environment variable
+  # (SOCIALACCOUNT_PROVIDERS = json.loads(os.getenv(
+  # "PAPERLESS_SOCIALACCOUNT_PROVIDERS", "{}"))), and there is no _FILE variant
+  # of it. A secretKeyRef cannot substitute a fragment INTO a json variable, so
+  # an honest implementation would have to either inline the secret in the pod
+  # spec or push the complete json into the vault by hand - and the second one
+  # makes every required() in the oidc block below dead wood.
+  #
+  # The operational question behind it is answered rather than dodged: this
+  # chart registers a PUBLIC client with PKCE, Keycloak (Gitea #83) can mark a
+  # client public per client, and so no provider constraint forces a
+  # confidential client here. See the oidc block below.
 
 ingress:
   # Set to false to omit the Ingress entirely. NEW in the chart version that
@@ -179,7 +198,38 @@ paperless:
     timeoutSeconds: 5
   # Extra environment variables, appended to the ones the chart always sets.
   # Values are rendered through tpl; value, secretKeyRef and configMapKeyRef
-  # forms are supported.
+  # forms are supported. paperless-ngx reads around 80 PAPERLESS_* variables and
+  # this chart maps a handful of them explicitly - everything else goes here.
+  #
+  #   env:
+  #     - name: PAPERLESS_LOGGING_DIR
+  #       value: /tmp/paperless-log
+  #
+  # ADDITIVE MEANS ADDITIVE, and the timing matters: an entry repeating a name
+  # the chart already sets reaches the pod twice, and at INSTALL the later one -
+  # yours - wins. On an EXISTING release the same entry is lost, because
+  # Kubernetes merges env by name and the pair collapses to the chart's own
+  # value, while helm upgrade still reports success. Read an override back off
+  # the StatefulSet, never off the upgrade's exit code.
+  #
+  # VALUES MUST BE STRINGS (the schema enforces it) and they are quoted on the
+  # way out since 13.0.0. Before that a value beginning with "*" aborted the
+  # render and "true" or "0755" arrived as a bool or an integer, which the API
+  # server rejects - see the comment at the render site in
+  # templates/paperless-server.sfs.yaml.
+  #
+  # THE WORKED EXAMPLE, PAPERLESS_LOGGING_DIR, AND WHAT IT DOES NOT FIX
+  # (jk-cluster-config #360): with the data directory on an RWX volume that
+  # Longhorn exports over NFS, paperless' concurrent_log_handler cannot hold its
+  # lock file there and fails with "RuntimeError: Cannot acquire lock after 20
+  # attempts" - measured at 45 % of the application log across all three
+  # installations. Pointing PAPERLESS_LOGGING_DIR at a path under the /tmp
+  # emptyDir this pod already mounts takes the log off the NFS share and the
+  # noise stops. It does NOT fix the RWX data volume, which is the actual root
+  # cause and a cluster-config decision (the PVC asks for ReadWriteOnce and was
+  # provisioned ReadWriteMany; taking RWX back means recreating the volume).
+  # A log under /tmp does not survive a pod restart - no loss here, paperless
+  # also writes to stdout, which is what kubectl logs reads.
   env: []
   resources:
     # Limits are optional: memory and ephemeral-storage limits default to
@@ -214,8 +264,58 @@ paperless:
 smbConnection:
   enabled: false
   server: null
+  # Cron schedule of the consume mover. Quote it or not as you like - the chart
+  # quotes it on the way into the manifest (since 13.0.0, Gitea #11), which is
+  # what a schedule beginning with "*" or "@" needs. Before that such a
+  # schedule aborted the render with a YAML error pointing at the template.
   cronJob: "0 0,12 * * *"
   cron:
+    # Run the mover on the node that carries the StatefulSet pod (Gitea #101).
+    #
+    # WHY IT DEFAULTS TO TRUE: this pod mounts the consume volume, which is RWX
+    # and comes from Longhorn, and Longhorn's CSI driver refuses to mount an RWX
+    # volume unless it finds a workload pod in Pending - a mover pod that ran on
+    # a different node leaves the kubelet of the StatefulSet's node retrying
+    # every two minutes with "no Pending workload pods for volume ... to be
+    # mounted" (291 events in 10 hours, in both releases with SMB on; the
+    # release without the CronJob produced none).
+    #
+    # It is a switch and not a free-form affinity block on purpose: the default
+    # has to name the StatefulSet pod's label, that label contains the RELEASE
+    # NAME, and a values.yaml is never templated - so the useful default cannot
+    # be expressed here at all (the same property that forces
+    # valkey.secrets.authSecretRef to be typed out twice, further down).
+    #
+    # WHAT IT COSTS, AND IT IS A REAL COST: the affinity is required, so with
+    # the StatefulSet pod absent the mover cannot be scheduled. The two ways
+    # that happens are handled rather than left open - scaleDown: true suspends
+    # this CronJob outright, and activeDeadlineSeconds below fails a job that
+    # cannot be placed instead of letting Pending pods pile up. What stays: with
+    # paperless.replicas: 0 and SMB on, the mover does not run and reports one
+    # failed job per schedule. Set this to false to get the old, unpinned
+    # behaviour back - including the mount errors.
+    pinToServerNode: true
+    # How late a missed run may still start. Also keeps the CronJob controller
+    # from reaching "too many missed start times (> 100)", after which it stops
+    # scheduling this job entirely and says so only in its own log - reachable
+    # by leaving scaleDown: true in place for months. The cost of a window: a
+    # run that could not start inside it is skipped, not queued. Must stay well
+    # above 10s, below which the controller may never schedule at all.
+    startingDeadlineSeconds: 600
+    # Hard stop for one mover run, counted from the job's start - so it also
+    # bounds a pod that never gets scheduled (see pinToServerNode). Exceeding it
+    # shows up as a job with reason DeadlineExceeded, which is the point: a
+    # loud, self-clearing failure instead of a Pending pod that nobody sees.
+    # Raise it if a run legitimately moves more than an hour's worth of files;
+    # the mover copies across filesystems, so large scans are not instant.
+    activeDeadlineSeconds: 3600
+    # Extra environment variables for the mover container, same form as
+    # paperless.env above. Deliberately empty: the container is a busybox
+    # running one mv, so this exists for the odd proxy or locale variable and
+    # for the convention that every workload container offers the block - not
+    # because the mover needs configuration. Note that the cron SCHEDULE's time
+    # zone is the controller's and cannot be changed with a TZ entry here.
+    env: []
     # The consume mover only shuffles files between the SMB share (mounted
     # with 0777 modes) and the consume PVC, so it runs as the same non-root
     # uid/gid as paperless itself with a fully hardened context.
@@ -251,9 +351,25 @@ oidc:
     name: null
     clientId: null
     discoveryUrl: null
-    # Optional: explicit token endpoint auth method (e.g. client_secret_basic).
-    # Some providers need this since the allauth update in paperless-ngx 3.0
-    # (login fails at the callback with invalid_client otherwise).
+    # Optional: explicit token endpoint auth method. "none" is the only accepted
+    # value, and the schema enforces that (Gitea #11).
+    #
+    # WHY IT IS RESTRICTED, since the previous comment here named
+    # client_secret_basic as the example and that was actively misleading: this
+    # chart registers a PUBLIC client and configures NO client secret - it
+    # renders OAUTH_PKCE_ENABLED and nothing else, and secrets.oidcSecretRef was
+    # removed in 13.0.0 because no secret can reach paperless through a json
+    # environment variable anyway. A method that authenticates WITH a client
+    # secret therefore cannot work here; asking for one produced a login that
+    # died at the callback with invalid_client, while the two values read
+    # together looked like a working secret setup.
+    #
+    # So: null omits the key and lets allauth decide, "none" states the public
+    # client explicitly - which is what some providers need spelled out since
+    # the allauth update in paperless-ngx 3.0, and the symptom when they do is
+    # that same invalid_client at the callback. If a future paperless release
+    # supports an auth method that needs no secret, widening the enum is a minor
+    # bump; allowing one that needs a secret is not on the table.
     tokenAuthMethod: null
 
 # ---------------------------------------------------------------------------