feat(hub): split the OTel sampler for hub-api and trace workflow stages

opentelemetry.sampler now applies only to the services downstream of the Vault
(hub-workflows, pipe-*, workflow stages), which continue the Vault's trace and
should run parentbased_always_off; hub-api, which starts its own traces for
user requests, gets opentelemetry.apiSampler. Workflow stages (hub-stage.yaml)
had no OTEL_EXPORTER_OTLP_ENDPOINT, so their tracing ran in no-op mode; they
now get the endpoint and the downstream sampler when opentelemetry is enabled.

Defaults are empty, so the only rendered change is the stage endpoint.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

charts/hub/Chart.yaml

@@ -16,7 +16,7 @@ type: application
 # This is the chart version. This version number should be incremented each time you make changes
 # to the chart and its templates, including the app version.
 # Versions are expected to follow Semantic Versioning (https://semver.org/)
-version: 0.160.0
+version: 0.164.0
 
 # This is the version number of the application being deployed. This version number should be
 # incremented each time you make changes to the application. Versions are not expected to

charts/hub/README.md

@@ -268,8 +268,10 @@ kerberospipeline:
 | `opentelemetry.enabled` | Enable or disable OpenTelemetry instrumentation. | `false` |
 | `opentelemetry.routingEnabled` | Enable or disable OpenTelemetry routing/export behavior. | `false` |
 | `opentelemetry.collector.endpoint` | OpenTelemetry collector endpoint used for trace export. | `"http://otel-collector:4317"` |
-| `opentelemetry.sampler.type` | Trace sampler, exported as `OTEL_TRACES_SAMPLER` (e.g. `parentbased_traceidratio`). Empty keeps the SDK default (sample everything). | `""` |
-| `opentelemetry.sampler.arg` | Sampler argument, exported as `OTEL_TRACES_SAMPLER_ARG` (e.g. `"0.1"` for ~10% of traces). | `""` |
+| `opentelemetry.sampler.type` | Trace sampler for the services downstream of the Vault (hub-workflows, `pipe-*`, workflow stages), exported as `OTEL_TRACES_SAMPLER`. They continue the Vault's trace, so use `parentbased_always_off` and sample at the Vault. Empty keeps the SDK default (sample everything). | `""` |
+| `opentelemetry.sampler.arg` | Sampler argument for those services, exported as `OTEL_TRACES_SAMPLER_ARG`. | `""` |
+| `opentelemetry.apiSampler.type` | Trace sampler for hub-api, which starts its own traces for user requests (e.g. `parentbased_traceidratio`). Empty keeps the SDK default. | `""` |
+| `opentelemetry.apiSampler.arg` | Sampler argument for hub-api (e.g. `"0.1"` for ~10% of requests). | `""` |
 | `openai.enabled` | Enable or disable OpenAI-backed semantic features. | `false` |
 | `openai.apikey` | OpenAI API key used when OpenAI integration is enabled. | `"xxx"` |
 | `kerberosvault.uri` | The default Kerberos Vault uri (you can add multiple within the app), by default `'https://api.storage.yourdomain.com'` | `"https://api.vault.yourdomain.com"` |
@@ -377,6 +379,7 @@ kerberospipeline:
 | `kerberoshub.frontend.sentry.url` | No longer used. | `"https://xxx@sentry.io/xxx"` |
 | `kerberoshub.frontend.stripe.publicKey` | Public key for `kerberoshub.frontend.stripe`. | `""` |
 | `kerberoshub.frontend.googlemaps.apikey` | Within Kerberos Hub frontend a couple of maps are being used, the google maps is leveraged for that. | `"xxxx"` |
+| `kerberoshub.frontend.googlemaps.placesApi` | Google Places API used for address autocomplete with the same `apikey`: `"legacy"` (Places API) or `"new"` (Places API (New), required for keys that cannot enable the legacy Places API). | `"legacy"` |
 | `kerberoshub.frontend.zendesk.url` | No longer used. | `"yourdomain.zendesk.com"` |
 | `kerberoshub.frontend.posthog.key` | The API key retrieved from the Posthog instance. | `"xxx"` |
 | `kerberoshub.frontend.posthog.url` | Posthog's endpoint (http/https). | `"https://posthog.domain.com"` |
@@ -591,6 +594,7 @@ kerberospipeline:
 | `kerberospipeline.analysis.tag` | The Docker image tag/version. | `"v1.7.8"` |
 | `kerberospipeline.analysis.replicas` | Number of replicas for `kerberospipeline.analysis`. | `1` |
 | `kerberospipeline.analysis.logLevel` | Log verbosity level for `kerberospipeline.analysis`. | `"info"` |
+| `kerberospipeline.analysis.thumbnailRegeneration.enabled` | Regenerate thumbnails from the first frame of a classified moving object (`THUMBNAIL_REGENERATION_ENABLED`). Adds one thumbnail job per classified recording. Requires an analysis image that reads the flag. | `false` |
 | `kerberospipeline.analysis.dbCache.enabled` | Cache hot-path MongoDB lookups (site vault per device) in memory. Site changes apply after at most one TTL. | `false` |
 | `kerberospipeline.analysis.dbCache.ttl` | Lifetime of a cached lookup, as a Go duration (e.g. `"30s"`, `"5m"`). | `"5m"` |
 | `kerberospipeline.analysis.resources.requests.memory` | Memory request for `kerberospipeline.analysis`. | `"10Mi"` |
@@ -680,6 +684,87 @@ kerberospipeline:
 | `kerberoshub.frontend.ssoDomain` | The domain that's being used to activate SSO from the login page. | `""` |
 | `kerberoshub.frontend.stripe.apikey` | If using the public version, `stripe` can be used for automated billing and subscriptions. | `""` |
 
+### Email templates and variables
+
+Every email Hub sends is a template: an HTML file, plus a plain-text `.txt` version, containing `{{variable}}` placeholders that are filled in just before sending. This section lists which value each placeholder gets.
+
+#### Which template is used
+
+- `email.templates.<name>` sets the template name for each email (for example `email.templates.detection: "detection"`).
+- With `email.provider: smtp`, Hub reads `/mail/templates/<name>.html` and `/mail/templates/<name>.txt` from the container. If the files are not there, it uses its built-in template with that name. To use your own, mount a volume at `/mail` (see the commented `custom-email-templates` volume in `values.yaml`). The [`custom-layout/templates`](custom-layout/templates) folder holds a complete set to start from.
+- With `email.provider: mailgun`, `<name>` is a template stored in your Mailgun account. Mailgun receives `user`, `text`, `link`, `numberOfMedia`, `dataUsage` and the email-specific values below as template variables. The computed values (dates, camera, sites, groups, thumbnail) are only filled in with `smtp`.
+- Alert emails (`detection`) are only sent when `email.provider` is `smtp`.
+- A placeholder that has no value for that email stays in the email as literal text, so only use the placeholders listed for it. The bundled templates contain `{{tab1_href}}`, `{{tab1_title}}`, `{{tab2_href}}` and `{{tab2_title}}`; these are not filled in.
+
+#### Links
+
+- The **base URL** is `kerberoshub.frontend.schema` + `://` + `kerberoshub.frontend.url` (the `PUBLIC_URL` environment variable), for example `https://app.example.com`.
+- A **tenant URL** is the base URL with the first part of the host replaced by the recipient account's domain. With base URL `https://app.example.com` and account domain `acme`, the tenant URL is `https://acme.example.com`. Accounts without a domain use the base URL. Only the last two parts of the host are kept, so a base URL on `app.example.co.uk` becomes `acme.co.uk`.
+
+#### Alerts: `detection`
+
+Sent by the notification pipeline (`kerberospipeline.notify`) when a custom alert or the generic detection alert fires. The subject is `email.templates.alertTitle`; for a custom alert it is prefixed with the alert's name in brackets, for example `[Front door] Hub detected an event.`
+
+| Placeholder | Value |
+|---|---|
+| `{{user}}` | Name of the account that receives the alert: first and last name, or the username when both are empty. This is the account the camera belongs to, not the user who created the alert. |
+| `{{title}}` | The email subject. |
+| `{{text}}` | The alert message: what was detected, on which camera and when. |
+| `{{link}}` | **Custom alerts**: a signed link to the recording file. It stops working when the storage link expires. **Generic detection alert**: the recording's page in Hub, `<tenant URL>/media/<id>`. |
+| `{{medialink}}` | `https://app.kerberos.io/media/<id>`. Always this host; it does not follow `kerberoshub.frontend.url`. |
+| `{{thumbnail}}` | An `<img>` of the recording: embedded in the email for custom alerts, a signed thumbnail URL for the generic detection alert. |
+| `{{date}}`, `{{time}}`, `{{datetime}}` | Start of the recording, in the account's timezone. |
+| `{{eventdate}}`, `{{eventtime}}`, `{{eventdatetime}}` | When the alert was sent, in the account's timezone. |
+| `{{timezone}}` | The account's timezone. |
+| `{{devicename}}`, `{{deviceid}}` | Camera name and camera key. |
+| `{{sites}}`, `{{groups}}` | Comma-separated names of the sites and groups the camera belongs to. |
+| `{{classifications}}` | Comma-separated objects detected in the recording. |
+
+#### Camera status: `device`
+
+Sent by `hub-monitor-device` when a camera goes online, offline or idle. The subject is `email.templates.deviceTitle`.
+
+| Placeholder | Value |
+|---|---|
+| `{{user}}` | Username of the account the camera belongs to. |
+| `{{title}}` | The email subject. |
+| `{{text}}` | The status change, for example "`<camera>` is online, but the camera stream is not connected." |
+| `{{status}}` | `online`, `offline` or `idle`. |
+| `{{devicename}}`, `{{deviceid}}` | Camera name and camera key. |
+| `{{eventdate}}`, `{{eventtime}}`, `{{eventdatetime}}` | When the status changed, in the server's timezone (normally UTC), not the account's. |
+| `{{link}}` | Not set; replaced with an empty value. |
+
+#### Account and sharing emails
+
+Sent by the API (`kerberoshub.api`). The subject of each email is the matching `email.templates.<name>Title` value.
+
+| Email (`email.templates.*`) | Placeholder | Value |
+|---|---|---|
+| Registration (`welcome`) | `{{user}}` | New user's first and last name, or username. |
+| | `{{link}}` | Activation link: `<base URL>/login/activate/<token>`. |
+| | `{{token}}` | The activation token. |
+| Account activated (`activate`) | `{{user}}` | User's first and last name, or username. |
+| | `{{link}}` | `<base URL>/login`. |
+| Password reset (`forgot`) | `{{user}}` | User's first and last name, or username. |
+| | `{{password}}` | The newly generated password. |
+| | `{{ipaddress}}` | IP address the reset was requested from. |
+| Recording shared (`share`) | `{{user}}` | Sender's first and last name, or username. |
+| | `{{url}}` | Signed link to the recording file. |
+| | `{{title}}` | The email subject (`email.templates.shareTitle`). The share's own title is only used when that value is empty. |
+| | `{{body}}` | The notes the sender added to the share. |
+| Case shared (`share_case`) | `{{user}}` | Sender's first and last name, or email address. |
+| | `{{firstname}}`, `{{lastname}}` | Sender's first and last name. |
+| | `{{url}}` | `<base URL>/share/<token>`. |
+| | `{{expiry}}` | How long the share stays valid, for example "2 days" or "1 week". |
+| Case share code (`share_case_otp`) | `{{code}}` | One-time code to open the shared case. |
+| | `{{expiry}}` | How long the code stays valid. |
+| Task assigned (`assign_task`) | `{{assignee}}` | Assigned user's first and last name, or username. |
+| | `{{user}}` | Name of the user who assigned the task. |
+| | `{{task_name}}` | The task title. |
+| | `{{link}}` | `<tenant URL>/tasks/`, using the assigned user's domain. |
+
+The `newip`, `disable` and `highupload` templates are included, but no service currently sends them.
+
 ### Post installation
 
 After the installation you'll need to initialise the Mongodb with some objects. Have a look at the `mongodb/` folder, you'll find three files available:
@@ -718,19 +803,37 @@ Within the Kerberos Hub front-end you'll see the option to filter through classi
 The default shared classification list lives in
 [`templates/configMaps/catalogs/classifications.yaml`](templates/configMaps/catalogs/classifications.yaml),
 independently of workflow contracts. The chart uses this bundled definition
-unless a deployer provides a ConfigMap override. Each entry contains the stable classifier output
+unless a deployer defines the catalog inline or provides a ConfigMap override. Each entry contains the stable classifier output
 `key`, the user-facing `label`, and an `icon` key. Hub API exposes this catalog
 to alerts and filters. When the mounted catalog is unavailable, compatible Hub
 API versions fall back to the legacy `settings` document and then the built-in
 classification list. Set `classificationCatalogEnabled: false` to omit the
 ConfigMap and make Hub API use that fallback directly.
 
-Starting with chart **0.155.0**, the inline `classificationCatalog` values key is
-removed. Supplying it fails validation, including `null` and `[]`; it is never
-silently ignored or replaced with bundled defaults.
+The simplest way to customize the catalog is to define the complete list inline
+in your values (restored in chart **0.162.0** after its removal in 0.155.0):
 
-To customize the catalog, create a ConfigMap in the release namespace containing
-the complete JSON array, then use the per-file replacement interface:
+```yaml
+classificationCatalog:
+  - key: car
+    label: Car
+    icon: car
+  - key: forklift
+    label: Forklift
+```
+
+The list replaces the bundled defaults entirely (entries are not merged) and is
+rendered into the chart's `classification-catalog` ConfigMap, so Hub API and the
+bundled `catalogs/classifications.json` of workflow packaging use the same list
+and a change rolls the API pod. Each entry needs a `key` and `label`, `icon` is
+optional, and keys must be unique. Omitting the key (or `null`) keeps the bundled
+defaults; `[]` is rejected, so use `classificationCatalogEnabled: false` for the
+API fallback. An inline list cannot be combined with
+`classificationCatalogEnabled: false`, `classificationCatalogExistingConfigMap` or
+a per-file catalog replacement.
+
+Alternatively, create a ConfigMap in the release namespace containing the complete
+JSON array, then use the per-file replacement interface:
 
 ```yaml
 classificationCatalogEnabled: true
@@ -745,13 +848,8 @@ workflowConfiguration:
           replace: true
 ```
 
-To migrate, copy the existing list exactly (preserving keys, labels and icons)
-into the ConfigMap's JSON data, remove `classificationCatalog` from every values
-overlay and command-line override, and deploy the ConfigMap before the chart
-upgrade. A `null` value is not a migration: remove the key. The bundled list
-remains the default when no override is configured. If an old `[]` intentionally
-selected the API's runtime fallback, use `classificationCatalogEnabled: false`
-and configure workflow packaging without bundled defaults instead.
+Deploy that ConfigMap before the chart upgrade. The bundled list remains the
+default when no override is configured.
 
 The existing `classificationCatalogExistingConfigMap: hub-classification-catalog`
 option remains supported, including for deployments without workflow packaging.
@@ -1096,12 +1194,12 @@ not owned by workflows. A library may ship a catalog without implementing an API
 **effective** classification list under `/etc/kerberos/configuration`, using
 the directory layout above. The projected volume reuses the existing
 classification ConfigMap, including `classificationCatalogExistingConfigMap`
-overrides or explicit per-file replacements, rather
+overrides, an inline `classificationCatalog` or explicit per-file replacements, rather
 than storing another copy in the workflow ConfigMap.
 
 The default classification ConfigMap name, mount path, `CLASSIFICATION_CATALOG_FILE`
-and API endpoint remain unchanged. Inline `classificationCatalog` values,
-including `[]` and `null`, are rejected from chart 0.155.0 onward. The current API
+and API endpoint remain unchanged. An inline `classificationCatalog` list is
+rendered into that ConfigMap; `[]` is rejected. The current API
 still falls back to settings/built-in values for an empty/invalid mounted catalog. The preparatory
 bundle does not reproduce that runtime fallback and must not be treated as a
 resolved API catalog. The Start-specific loader shares the existing classification
@@ -1188,10 +1286,9 @@ A replacement for `catalogs/classifications.json` also supplies the standalone
 classification API. Both mounts use that ConfigMap and key, even when its key
 is not named `classifications.json`. The chart does not generate or checksum the
 replaced ConfigMap. To avoid two competing sources, do not combine this
-replacement with a nonempty `classificationCatalogExistingConfigMap`. That
-existing ConfigMap option remains supported when no per-file catalog replacement
-is configured. The retired inline `classificationCatalog` key is rejected
-regardless of the selected configuration.
+replacement with a nonempty `classificationCatalogExistingConfigMap` or an inline
+`classificationCatalog`. Those options remain supported when no per-file catalog
+replacement is configured.
 `classificationCatalogEnabled` must remain true when including defaults.
 
 This is whole-file replacement, not field-level YAML merging or catalog-entry

charts/hub/examples/workflow-configuration-overrides-values.yaml

@@ -1,7 +1,6 @@
 # Create these ConfigMaps in the release namespace before deploying the chart.
 # Keys contain complete contracts/catalogs; they are not merged with chart data.
-# Remove the retired classificationCatalog key from every values overlay.
-# Do not also set classificationCatalogExistingConfigMap.
+# Do not also set classificationCatalog or classificationCatalogExistingConfigMap.
 classificationCatalogEnabled: true
 workflowConfiguration:
   enabled: true

charts/hub/templates/_configuration.tpl

@@ -22,9 +22,6 @@
 
 {{/* Normalize both interfaces without changing the caller's values. */}}
 {{- define "hub.workflowConfiguration.settings" -}}
-{{- if hasKey .Values "classificationCatalog" -}}
-{{- fail "classificationCatalog is no longer supported; remove the values key and place the complete catalog in a ConfigMap, then use workflowConfiguration.configMaps with path: catalogs/classifications.json and replace: true" -}}
-{{- end -}}
 {{- $config := .Values.workflowConfiguration | default dict -}}
 {{- $unified := or (hasKey $config "includeDefaults") (hasKey $config "configMaps") -}}
 {{- $legacy := or (hasKey $config "existingConfigMap") (hasKey $config "items") (hasKey $config "extraConfigMaps") -}}
@@ -78,6 +75,17 @@
 {{- fail "a classifications.json replacement cannot be combined with classificationCatalogExistingConfigMap; choose one override mechanism" -}}
 {{- end -}}
 {{- end -}}
+{{- if not (kindIs "invalid" .Values.classificationCatalog) -}}
+{{- if not .Values.classificationCatalogEnabled -}}
+{{- fail "classificationCatalog requires classificationCatalogEnabled; remove the inline list to use the API fallback" -}}
+{{- end -}}
+{{- if .Values.classificationCatalogExistingConfigMap -}}
+{{- fail "classificationCatalog cannot be combined with classificationCatalogExistingConfigMap; choose one override mechanism" -}}
+{{- end -}}
+{{- if hasKey $replacements "catalogs/classifications.json" -}}
+{{- fail "classificationCatalog cannot be combined with a classifications.json replacement; choose one override mechanism" -}}
+{{- end -}}
+{{- end -}}
 {{- dict "enabled" $enabled "includeDefaults" $includeDefaults "configMaps" $normalizedSources "replacements" $replacements | toYaml -}}
 {{- end -}}
 

charts/hub/templates/_helpers.tpl

@@ -86,14 +86,27 @@ Usage: {{- include "hub.mongodb.appUriEnv" (dict "root" $ "app" "hub-api") | nin
 {{/*
 OpenTelemetry sampler env entries, rendered only when configured. The OTel SDKs
 read these natively; unset keeps the SDK default (parentbased_always_on).
+"hub.opentelemetry.samplerEnv" renders opentelemetry.sampler, the sampler of the
+services downstream of the Vault (pipeline, workflows engine and stages), which
+continue the Vault's trace; "hub.opentelemetry.apiSamplerEnv" renders
+opentelemetry.apiSampler for hub-api, which starts its own traces for user
+requests.
 Usage: {{- include "hub.opentelemetry.samplerEnv" $ | trim | nindent 8 }}
 */}}
 {{- define "hub.opentelemetry.samplerEnv" -}}
-{{- with .Values.opentelemetry.sampler.type }}
+{{- include "hub.opentelemetry.samplerEnvFrom" .Values.opentelemetry.sampler -}}
+{{- end -}}
+
+{{- define "hub.opentelemetry.apiSamplerEnv" -}}
+{{- include "hub.opentelemetry.samplerEnvFrom" (.Values.opentelemetry.apiSampler | default dict) -}}
+{{- end -}}
+
+{{- define "hub.opentelemetry.samplerEnvFrom" -}}
+{{- with .type }}
 - name: OTEL_TRACES_SAMPLER
   value: {{ . | quote }}
 {{- end }}
-{{- with .Values.opentelemetry.sampler.arg }}
+{{- with .arg }}
 - name: OTEL_TRACES_SAMPLER_ARG
   value: {{ . | quote }}
 {{- end }}

charts/hub/templates/configMaps/catalogs/classifications.yaml

@@ -11,6 +11,28 @@
   {"key": "cell phone", "label": "Cell phone", "icon": "cell phone"}
 ]
 {{- end -}}
+{{/*
+The effective chart-rendered catalog: the inline classificationCatalog values
+list when set, otherwise the bundled defaults above. values.schema.json
+validates each entry ({key, label, icon?}); keys must also be unique.
+*/}}
+{{- define "hub.classificationCatalog.json" -}}
+{{- if kindIs "invalid" .Values.classificationCatalog -}}
+{{- include "hub.classificationCatalog.defaults" . | mustFromJson | toJson -}}
+{{- else if and (kindIs "slice" .Values.classificationCatalog) .Values.classificationCatalog -}}
+{{- $seen := dict -}}
+{{- range $entry := .Values.classificationCatalog -}}
+{{- $key := toString $entry.key -}}
+{{- if hasKey $seen $key -}}
+{{- fail (printf "classificationCatalog: duplicate key %q" $key) -}}
+{{- end -}}
+{{- $_ := set $seen $key true -}}
+{{- end -}}
+{{- .Values.classificationCatalog | toJson -}}
+{{- else -}}
+{{- fail "classificationCatalog must be omitted (bundled defaults) or a nonempty list; to use the API fallback set classificationCatalogEnabled: false" -}}
+{{- end -}}
+{{- end -}}
 {{- $config := include "hub.workflowConfiguration.settings" . | fromYaml -}}
 {{- if and .Values.classificationCatalogEnabled (not .Values.classificationCatalogExistingConfigMap) (not (hasKey $config.replacements "catalogs/classifications.json")) }}
 apiVersion: v1
@@ -20,5 +42,5 @@ metadata:
   namespace: {{ .Release.Namespace }}
 data:
   classifications.json: |-
-    {{- include "hub.classificationCatalog.defaults" . | mustFromJson | toPrettyJson | nindent 4 }}
+    {{- include "hub.classificationCatalog.json" . | mustFromJson | toPrettyJson | nindent 4 }}
 {{- end -}}

charts/hub/templates/kerberos-hub/hub-api.yaml

@@ -597,6 +597,6 @@ spec:
               value: "{{ .Values.opentelemetry.routingEnabled }}"
             - name: OTEL_EXPORTER_OTLP_ENDPOINT
               value: "{{ .Values.opentelemetry.collector.endpoint }}"
-            {{- include "hub.opentelemetry.samplerEnv" $ | trim | nindent 12 }}
+            {{- include "hub.opentelemetry.apiSamplerEnv" $ | trim | nindent 12 }}
             {{- end }}
 {{- end }}

charts/hub/templates/kerberos-hub/hub-frontend-demo.yaml

@@ -192,6 +192,8 @@ spec:
         # Google maps for using and displaying cameras, sites on a map
         - name: GOOGLEMAPS_KEY
           value: "{{ .Values.kerberoshub.frontend.googlemaps.apikey }}"
+        - name: GOOGLEMAPS_PLACES_API
+          value: "{{ .Values.kerberoshub.frontend.googlemaps.placesApi }}"
 
         # features > chart
         - name: CHART_COLORS

charts/hub/templates/kerberos-hub/hub-frontend.yaml

@@ -275,6 +275,8 @@ spec:
         # Google maps for using and displaying cameras, sites on a map
         - name: GOOGLEMAPS_KEY
           value: "{{ .Values.kerberoshub.frontend.googlemaps.apikey }}"
+        - name: GOOGLEMAPS_PLACES_API
+          value: "{{ .Values.kerberoshub.frontend.googlemaps.placesApi }}"
 
         # Zendesk for support
         - name: ZENDESK_URL

charts/hub/templates/kerberos-pipeline/hub-stage.yaml

@@ -117,6 +117,14 @@ spec:
         - name: KERBEROS_STORAGE_PROVIDER
           value: {{ . | quote }}
         {{- end }}
+        {{- if $root.Values.opentelemetry.enabled }}
+
+        # OpenTelemetry tracing: the stage continues the engine's dispatch span
+        # (the run's traceparent) and follows its sampling decision.
+        - name: OTEL_EXPORTER_OTLP_ENDPOINT
+          value: "{{ $root.Values.opentelemetry.collector.endpoint }}"
+        {{- include "hub.opentelemetry.samplerEnv" $root | trim | nindent 8 }}
+        {{- end }}
 
         # Per-stage tuning knobs. Any key/value under services.<name>.env is
         # rendered verbatim as container env, so a worker can be tuned from

charts/hub/templates/kerberos-pipeline/pipe-analysis.yaml

@@ -126,6 +126,10 @@ spec:
         - name: DOMINANTCOLOR_ENABLED
           value: "{{ .Values.kerberospipeline.dominantColor.enabled }}"
 
+        # Thumbnail regeneration from classified frames (opt-in)
+        - name: THUMBNAIL_REGENERATION_ENABLED
+          value: {{ .Values.kerberospipeline.analysis.thumbnailRegeneration.enabled | default false | quote }}
+
         # In-memory cache for hot-path MongoDB lookups
         - name: DB_CACHE_ENABLED
           value: {{ .Values.kerberospipeline.analysis.dbCache.enabled | default false | quote }}

charts/hub/values.schema.json

@@ -8,8 +8,19 @@
       "pattern": "^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$"
     },
     "classificationCatalog": {
-      "not": {},
-      "description": "Removed in 0.155.0. Store the complete catalog in a ConfigMap and use workflowConfiguration.configMaps with replace: true at catalogs/classifications.json."
+      "type": ["array", "null"],
+      "minItems": 1,
+      "description": "Optional inline classification catalog in the Hub shared choice catalog format; replaces the bundled defaults in the chart's classification-catalog ConfigMap. Omit (or null) for the bundled defaults. Keys must be unique (checked when rendering).",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["key", "label"],
+        "properties": {
+          "key": {"type": "string", "minLength": 1},
+          "label": {"type": "string", "minLength": 1},
+          "icon": {"type": "string", "minLength": 1}
+        }
+      }
     },
     "deviceTags": {
       "type": "object",

charts/hub/values.yaml

@@ -82,8 +82,15 @@ classificationCatalogEnabled: true
 # When set, do not create a catalog ConfigMap; this replaces bundled defaults.
 classificationCatalogExistingConfigMap: ""
 # Defaults live in templates/configMaps/catalogs/classifications.yaml.
-# Inline classificationCatalog values are no longer accepted (including null/[]).
-# Use a ConfigMap item with path: catalogs/classifications.json and replace: true.
+# Optionally define the complete catalog inline instead; it replaces the
+# defaults in the chart's classification-catalog ConfigMap (and so the bundled
+# catalogs/classifications.json). Entries are {key, label, icon?} with unique
+# keys. Do not combine it with classificationCatalogExistingConfigMap or a
+# catalogs/classifications.json replacement in workflowConfiguration.
+# classificationCatalog:
+#   - key: car
+#     label: Car
+#     icon: car
 
 # Device tags, grouped by type. System tags are defined here and assigned by
 # owners (a multi-select on the device page); global workflows select devices
@@ -121,7 +128,7 @@ workflowConfiguration:
   # Replacement requires includeDefaults: true and a known bundled destination path.
   # Unmarked collisions and repeated custom destinations are rejected.
   # Replacing catalogs/classifications.json also supplies the classification API:
-  # do not combine it with classificationCatalogExistingConfigMap.
+  # do not combine it with classificationCatalogExistingConfigMap or classificationCatalog.
   # Legacy existingConfigMap/items/extraConfigMaps remain supported, but cannot
   # be mixed with includeDefaults/configMaps. Both interfaces are omitted here
   # so Helm's default merging does not introduce a false mixed configuration.
@@ -204,15 +211,26 @@ opentelemetry:
     endpoint: "http://otel-collector:4318"
   # Trace sampling, passed to the services as OTEL_TRACES_SAMPLER and
   # OTEL_TRACES_SAMPLER_ARG. Leave empty to keep the SDK default, which records
-  # every trace. Example: keep ~10% of traces, and follow the parent's decision
-  # for spans that continue an upstream trace:
-  #   type: "parentbased_traceidratio"
-  #   arg: "0.1"
+  # every trace.
   # Supported types: always_on, always_off, traceidratio, parentbased_always_on,
   # parentbased_always_off, parentbased_traceidratio.
+  #
+  # sampler applies to the services downstream of the Vault: hub-workflows, the
+  # pipe-* services and the workflow stages. They continue the trace the Vault
+  # starts for an upload, so head sampling belongs at the Vault
+  # (parentbased_traceidratio on the Vault deployment) and these follow its
+  # decision without starting traces of their own:
+  #   type: "parentbased_always_off"
   sampler:
     type: ""
     arg: ""
+  # apiSampler applies to hub-api, which starts its own traces for user
+  # requests. Example: keep ~10% of them:
+  #   type: "parentbased_traceidratio"
+  #   arg: "0.1"
+  apiSampler:
+    type: ""
+    arg: ""
 ############################################
 # OpenAI configuration (semantic search)
 #
@@ -702,6 +720,7 @@ kerberoshub:
       publicKey: ""
     googlemaps: # Google maps is used inside the application to visualise cameras and sites.
       apikey: "xxxx"
+      placesApi: "legacy" # Places API for address autocomplete: "legacy" (default) or "new" for keys with Places API (New) enabled. Uses the same apikey.
     zendesk: # We can use different support tools, for now we use Zendesk but others can be integrated
       url: "yourdomain.zendesk.com"
     posthog: # Posthog is used for auditing and user interaction logging
@@ -1269,6 +1288,12 @@ kerberospipeline:
     #  - name: extra
     #    mountPath: /data
     logLevel: "info" # possible values: trace, debug, info, warn, error
+    # Opt-in: after classification, re-enqueue the recording on the thumbnail
+    # queue to regenerate its thumbnail from the first frame of a tracked moving
+    # object (THUMBNAIL_REGENERATION_ENABLED). Adds one thumbnail job per
+    # classified recording; size pipe-thumbnail accordingly before enabling.
+    thumbnailRegeneration:
+      enabled: false
     # In-memory cache for hot-path MongoDB lookups (site vault per device).
     # Site changes apply after at most one TTL; each replica caches separately.
     dbCache: