@bpmnkit/camunda-docspack 0.0.0

package/.llms/chunks/components.concepts.secret-resolution-incidents.diagnose-the-cause-2.md

@@ -0,0 +1,14 @@
+# Troubleshoot secret resolution failures — Diagnose the cause (2)
+
+- **Secret name**: Confirm the reference name exactly matches the secret name in the store, including case. Store-managed names that the Camunda secret endpoints reject, such as names containing a period, can still resolve when you escape them with backticks in an input mapping expression.
+
+  Escaping applies only to expressions. Camunda scans references in [cluster variable](https://docs.camunda.io/docs/next/components/admin/cluster-variables) values as plain text rather than parsing them as FEEL. In this case, the name after the prefix must match `[\p{Alnum}_-]+` and cannot be escaped. A period, space, or other unsupported character prevents Camunda from detecting the reference.
+
+- **Reference format**: Confirm the reference is a FEEL expression rather than a static string. In an input mapping source or Connector property, use a path such as `=camunda.secrets.TOKEN`. Static values and quoted references such as `={"auth": "camunda.secrets.TOKEN"}` are rejected at deployment.
+
+- **Value size**: Confirm the resolved value and other job variables fit within `camunda.cluster.network.max-message-size`.
+
+The `SECRET` resource type in [authorizations](https://docs.camunda.io/docs/next/components/concepts/access-control/authorizations) applies to the secrets API, not broker-side secret resolution. Missing Camunda authorizations don't cause `SECRET_RESOLUTION_ERROR` incidents.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/secret-resolution-incidents

package/.llms/chunks/components.concepts.secret-resolution-incidents.diagnose-the-cause.md

@@ -0,0 +1,26 @@
+# Troubleshoot secret resolution failures — Diagnose the cause
+
+Start with the incident error type and message, then confirm the underlying cause in the broker log. Incident messages don't include the store's error category, so use the log to distinguish conditions such as a missing secret, denied access, or an unavailable store.
+
+1. Read the incident in Operate or search for incidents filtered by `errorType`. Note the secret reference, variable path, and job key from the message.
+2. For incidents whose message starts with `Failed to resolve secret`, search the broker log for the affected partition and reference name. Match the log entry to the table below.
+3. For injection failures, inspect the job variables at the reported path in Operate or through the element instance variables.
+
+| Broker log line                                                                                    | Cause                                                                                                | Fix                                                                                                     |
+| -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `Secret '<ref>' in secret store '<id>' failed permanently: NOT_FOUND — No secret store configured` | No secret store is configured for this physical tenant, so every reference fails as not found.       | Configure a secret store.                                                                               |
+| `Secret '<ref>' in secret store '<id>' failed permanently: NOT_FOUND — <message>`                  | The store does not contain a secret with that name.                                                  | Create the secret or correct the reference name in the process.                                         |
+| `Secret '<ref>' in secret store '<id>' failed permanently: ACCESS_DENIED — <message>`              | The credentials used by the broker don't have permission to read the secret.                         | Grant read access in the secret store. This is store-level access control, not a Camunda authorization. |
+| `Secret '<ref>' in secret store '<id>' failed permanently: INVALID_REF — <message>`                | The store rejects the reference name as invalid.                                                     | Rename the secret so the store and Camunda reference syntax both accept it.                             |
+| `Secret '<ref>' in secret store '<id>' failed permanently: UNREADABLE — <message>`                 | The store contains the secret, but its value cannot be read or decoded.                              | Repair the stored value.                                                                                |
+| `Secret store '<id>' unavailable (attempt <n>/<m>), retrying in <backoff>: <message>`              | The failure is transient. The broker is retrying the store with backoff, and no incident exists yet. | If the failure persists, restore the store's availability.                                              |
+| `Secret store '<id>' unavailable after <n>/<m> attempts — failing <n> pending refs: <message>`     | The store remained unavailable through `retry-max-attempts`, so its pending references failed.       | Restore the store's availability, then resolve the incidents.                                           |
+
+The separator in these log lines is an em dash, and `<message>` contains the store's own error text. Search for a distinctive fragment such as `failed permanently` rather than the entire line.
+
+Then verify the reference itself:
+
+- **Reference name**: Confirm the reference resolves to the intended secret name. In an input mapping, Camunda detects references from the parsed FEEL expression, so FEEL syntax determines where the name ends. For example, FEEL interprets `=camunda.secrets.db-password` as the reference `db` minus the variable `password`. Escape names that aren't valid bare FEEL identifiers with backticks, for example ``=camunda.secrets.`db-password` ``. If the incident names a shorter secret than expected, check whether FEEL interpreted part of the name as an operator.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/secret-resolution-incidents

package/.llms/chunks/components.concepts.secret-resolution-incidents.find-your-symptom.md

@@ -0,0 +1,17 @@
+# Troubleshoot secret resolution failures — Find your symptom
+
+| Symptom                                                                          | What happened                                                                                                | Section                                                                                           |
+| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
+| An incident message starts with `Failed to resolve secret`                       | The secret store could not return the value, either permanently or after exhausting all retries.             | [Resolve secret lookup failures](#resolve-secret-lookup-failures)                                 |
+| An incident message names a job key and variable path                            | The secret value was available, but Camunda could not inject it into the job variables.                      | [Resolve secret injection failures](#resolve-secret-injection-failures)                           |
+| An incident message reports growth in bytes and the configured message size      | The resolved values are too large to fit in an activation batch.                                             | [Reduce oversized secret values](#reduce-oversized-secret-values)                                 |
+| A job that references secrets is not activated, and no incident is raised        | The references have not resolved yet, or the store is in retry backoff.                                      | [Identify failures that raise no incident](#identify-failures-that-raise-no-incident)             |
+| Jobs activate later and in smaller batches than usual, and no incident is raised | The injected values did not fit in the current batch, so the broker deferred the jobs to a later activation. | [Identify failures that raise no incident](#identify-failures-that-raise-no-incident)             |
+| A job in a suspended process instance is not activated after its secret resolves | The process instance remains suspended, so secret resolution does not make the job activatable.              | [Resume a suspended job after secret resolution](#resume-a-suspended-job-after-secret-resolution) |
+
+These incidents are job incidents. You can view them in [Operate](https://docs.camunda.io/docs/next/components/operate/userguide/resolve-incidents-update-variables) or retrieve them through the [search incidents](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/search-incidents.api) endpoint. Filter by `errorType` for `SECRET_RESOLUTION_ERROR` or `MESSAGE_SIZE_EXCEEDED`.
+
+Incident messages never contain secret values. They may include the secret reference, variable path, job key, or message size, but not the resolved value.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/secret-resolution-incidents

package/.llms/chunks/components.concepts.secret-resolution-incidents.identify-failures-that-raise-no-incident.md

@@ -0,0 +1,31 @@
+# Troubleshoot secret resolution failures — Identify failures that raise no incident
+
+Some secret resolution outcomes do not raise incidents and do not require operator action. Their symptoms can still resemble incident conditions.
+
+### Job does not fit in the current batch
+
+If injecting a job's resolved values would exceed the remaining message size in the current activation batch, Camunda removes that job and every subsequent job from the batch and marks the batch as truncated.
+
+The removed jobs remain activatable and can be included in a later activation. The visible effect is smaller batches and slightly delayed activation rather than a stuck job.
+
+### Reference no longer has a placeholder
+
+Camunda activates the job without changing the value when there is no placeholder left to replace.
+
+This can happen in either of the following cases:
+
+- The recorded pointer no longer addresses a value, for example because the worker's `fetchVariables` list excludes that variable.
+- The value at the pointer no longer contains `camunda.secrets.<name>`, for example because a variable update replaced the placeholder with a literal value.
+
+In the second case, the worker receives the current literal value instead of the secret. Camunda raises an [injection incident](#resolve-secret-injection-failures) only when a secret placeholder is still present but cannot be replaced.
+
+### Job push does not check injected value size
+
+Long polling checks the growth caused by injected secret values against the remaining message size in the activation batch. If the job does not fit, Camunda removes it from the batch.
+
+Job push does not perform the same size check on the pushed job because the activation event contains no variables. As a result, the push path does not raise a `MESSAGE_SIZE_EXCEEDED` incident for oversized injected values.
+
+Job push does not bypass the transport message-size limit. If the pushed job exceeds the configured transport limit between the broker, gateway, and worker, delivery can fail without raising a `MESSAGE_SIZE_EXCEEDED` incident.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/secret-resolution-incidents

package/.llms/chunks/components.concepts.secret-resolution-incidents.md

@@ -0,0 +1,14 @@
+# Troubleshoot secret resolution failures
+
+Diagnose the incidents raised when a job's secret references cannot be resolved or their values cannot be injected, fix the cause, and know what happens next.
+
+When a job's [secret references](https://docs.camunda.io/docs/next/components/concepts/secret-resolution-and-job-activation) cannot be delivered, the cluster responds in one of three ways: it raises a `SECRET_RESOLUTION_ERROR` incident, raises a `MESSAGE_SIZE_EXCEEDED` incident, or defers the job and retries it without raising an incident.
+
+This page describes an alpha feature and may change in future releases. See [alpha features](https://docs.camunda.io/docs/next/components/early-access/alpha/alpha-features).
+
+Only the two incident cases require operator action.
+
+Use this page to diagnose an existing secret resolution or activation problem. To understand how secret resolution and job activation work, see [Secret resolution and job activation](https://docs.camunda.io/docs/next/components/concepts/secret-resolution-and-job-activation).
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/secret-resolution-incidents

package/.llms/chunks/components.concepts.secret-resolution-incidents.reduce-oversized-secret-values.md

@@ -0,0 +1,20 @@
+# Troubleshoot secret resolution failures — Reduce oversized secret values
+
+A `MESSAGE_SIZE_EXCEEDED` incident is raised when the resolved secret values make the job too large to fit within the configured activation message size.
+
+```text
+The job with key '2251799813685260' can not be activated, because injecting its secret values would grow the activation batch by 5.2MiB, more than any batch can grow without exceeding the configured message size (per default is 4 MB). Try to reduce the size of the secret values or of the job variables.
+```
+
+The applicable limit is `camunda.cluster.network.max-message-size`, which defaults to `4MB`. Secret values do not have a separate size limit.
+
+Camunda raises this incident only when the oversized job is first in the activation batch and still cannot fit within the available message size. If a job does not fit only because of other jobs already included in the batch, Camunda removes it from that batch without raising an incident and activates it later. See [Identify failures that raise no incident](#identify-failures-that-raise-no-incident).
+
+### Retry after reducing the size
+
+Resolve the incident only after reducing the size of the secret value or the job variables. Otherwise, the next activation attempt fails in the same way.
+
+To reduce the job variables included in activation, adjust the worker's `fetchVariables` list. Variables the worker does not fetch are excluded from the activation and do not count toward the message-size limit.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/secret-resolution-incidents

package/.llms/chunks/components.concepts.secret-resolution-incidents.related-resources.md

@@ -0,0 +1,8 @@
+# Troubleshoot secret resolution failures — Related resources
+
+- [Secret resolution and job activation](https://docs.camunda.io/docs/next/components/concepts/secret-resolution-and-job-activation) describes how Camunda resolves references and when a job becomes activatable, including the scheduler settings that control how quickly store failures become incidents.
+- [Incidents](https://docs.camunda.io/docs/next/components/concepts/incidents) explains how incidents work and how to resolve them.
+- [Resolve incidents and update variables](https://docs.camunda.io/docs/next/components/operate/userguide/resolve-incidents-update-variables) explains how to resolve incidents in Operate.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/secret-resolution-incidents

package/.llms/chunks/components.concepts.secret-resolution-incidents.resolve-secret-injection-failures.md

@@ -0,0 +1,41 @@
+# Troubleshoot secret resolution failures — Resolve secret injection failures
+
+A secret injection failure also raises a `SECRET_RESOLUTION_ERROR` incident, but for a different reason. In this case, the secret value was available, but Camunda could not inject it into the job variables.
+
+Each secret reference records the JSON pointer of the variable that contains the placeholder. During activation, Camunda replaces the placeholder at that pointer with the resolved value.
+
+Injection fails when both of the following conditions apply:
+
+- Camunda cannot replace the placeholder at the recorded pointer.
+- A `camunda.secrets.<name>` placeholder still remains at that path after all references for the path have been processed.
+
+For example, injection fails if the pointer now addresses a list or object that still contains a secret placeholder. If the value at the pointer no longer contains a placeholder, Camunda [continues without raising an incident](#identify-failures-that-raise-no-incident).
+
+```text
+The job with key '2251799813685260' can not be activated, because the secret reference 'camunda.secrets.API_TOKEN' could not be resolved at '/credentials/token'. Fix the variable's value or the input mapping that sets it, then resolve the incident, or use process instance modification to reactivate the element and create a fresh job.
+```
+
+If the failure does not identify a specific reference, for example because Camunda cannot read the job variables, the incident uses the following generic message:
+
+```text
+The job with key '2251799813685260' can not be activated, because injecting its secret values failed. Resolve the incident, or use process instance modification to reactivate the element and create a fresh job.
+```
+
+Long polling and job push use the same incident messages for injection failures.
+
+Typical causes include:
+
+- A variable merge overwrites the placeholder after the job is created.
+- An input mapping produces a list or context instead of a single text value.
+- A cluster variable changes between input mapping evaluation and job creation.
+
+While the incident is active, the job is not activatable, so the broker does not retry the same failed injection on every poll.
+
+### Retry secret injection
+
+Resolve the incident only after correcting the variable value or the input mapping that produced it. Resolving the incident makes the job activatable again, and Camunda retries injection against the current job variables.
+
+If you cannot restore the placeholder, use [process instance modification](https://docs.camunda.io/docs/next/components/concepts/process-instance-modification) to reactivate the element. This creates a new job and detects its secret references again.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/secret-resolution-incidents

package/.llms/chunks/components.concepts.secret-resolution-incidents.resolve-secret-lookup-failures.md

@@ -0,0 +1,26 @@
+# Troubleshoot secret resolution failures — Resolve secret lookup failures
+
+A secret lookup failure raises a `SECRET_RESOLUTION_ERROR` incident. This happens when the secret store returns a permanent failure or remains unavailable until all retry attempts are exhausted.
+
+The broker raises one incident per affected job. If a job already has an incident for another failed secret reference, the broker does not raise a second incident. As a result, a job waiting on multiple failed secrets shows only the first incident.
+
+```text
+Failed to resolve secret 'API_TOKEN' from the configured secret store. Ensure the secret exists and the store is available, then resolve the incident to retry.
+```
+
+For the default store, the incident message uses `the configured secret store`. For any other store, it uses `secret store '<storeId>'`.
+
+The `camunda.secrets.<name>` syntax does not currently identify a store, so every reference addresses the default store. As a result, incident messages currently use the default-store wording.
+
+The incident message does not identify the underlying store failure. Check the broker log and follow [Diagnose the cause](#diagnose-the-cause) to determine whether the secret is missing, access is denied, the store is unavailable, or another failure occurred.
+
+While the incident is active, the job is not activatable and no worker receives it. The broker does not raise another incident for the same failed reference.
+
+### Retry after resolving the incident
+
+Resolve the incident only after fixing the underlying cause. Resolving the incident makes the job activatable again. On the next activation attempt, the broker requests resolution again because the reference is still uncached.
+
+You don't need to redeploy or make client-side changes. Once the reference resolves successfully, the process instance continues from where it stopped.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/secret-resolution-incidents

package/.llms/chunks/components.concepts.secret-resolution-incidents.resume-a-suspended-job-after-secret-resolution.md

@@ -0,0 +1,12 @@
+# Troubleshoot secret resolution failures — Resume a suspended job after secret resolution
+
+A job waiting for an uncached secret is parked, as described in [activate a job that references secrets](https://docs.camunda.io/docs/next/components/concepts/secret-resolution-and-job-activation#activate-a-job-that-references-secrets). If you suspend its process instance, the job enters `SUSPENDED` instead.
+
+If the secret resolves while the process instance is suspended, the job remains suspended and does not become activatable automatically.
+
+Resume the process instance to make the job available again. On the next activation attempt, Camunda injects the resolved value if it is still cached. If the value is no longer cached, Camunda parks the job again and requests secret resolution.
+
+In either case, no additional operator action is required and no incident is raised.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/secret-resolution-incidents

package/.llms/chunks/components.concepts.secret-resolution-incidents.retry-after-fixing-the-cause.md

@@ -0,0 +1,18 @@
+# Troubleshoot secret resolution failures — Retry after fixing the cause
+
+Resolve the incident after correcting the underlying problem. Resolving the incident retries the failed operation and makes the job activatable again.
+
+| You fixed                                     | After you resolve the incident                                                        |
+| --------------------------------------------- | ------------------------------------------------------------------------------------- |
+| The secret in the store or store access       | The broker requests resolution again, and the job activates once the value is cached. |
+| The variable or input mapping                 | Camunda retries injection against the current job variables.                          |
+| The size of the secret value or job variables | The job activates once the resolved values fit within the message-size limit.         |
+
+You don't need to redeploy or make changes to workers, clients, or job worker libraries. Jobs blocked on a reference become activatable automatically once the reference resolves, whether resolution follows an incident or store recovery.
+
+<!-- The secret resolution and secret cache meters that show a store failing before it produces incidents are owned by camunda/camunda#60963. Link them here once they are in the metrics reference. -->
+
+<!-- The camunda.secrets.* secret store configuration is owned by camunda/camunda#60331. Link the store configuration reference from the diagnosis steps once it lands. -->
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/secret-resolution-incidents

package/.llms/chunks/components.concepts.secret-resolution.cache-behavior.md

@@ -0,0 +1,16 @@
+# Secret resolution — Cache behavior
+
+Resolving is cache-first on both paths: the broker's background scheduler and the gateway's resolve endpoint each serve a reference from the store's cache when the cache already holds it, and only read the backing store for a reference the cache doesn't hold yet.
+
+Listing is different by design. What a store's cache holds is the values it has resolved so far, not the tenant's full set of secrets. `/v2/secrets/list` always reads the configured stores directly rather than serving from the cache.
+
+
+## Not currently supported
+
+- More than one secret store per physical tenant. A reference always addresses the `default` store.
+- Pinning an AWS Secrets Manager secret to a version stage other than `AWSCURRENT`, or a GCP Secret Manager secret to a version other than `latest`.
+- Filtering or paginating a `POST /v2/secrets/list` response, see [Secrets](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-secrets#list-secrets).
+- The general limitations that apply to every alpha feature, see [alpha features](https://docs.camunda.io/docs/next/components/early-access/alpha/alpha-features).
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/secret-resolution

package/.llms/chunks/components.concepts.secret-resolution.md

@@ -0,0 +1,16 @@
+# Secret resolution
+
+Understand camunda.secrets.<name> references, the two paths that resolve them, and where resolution is scoped and cached.
+
+Secret resolution replaces a `camunda.secrets.<name>` reference, known as a Secret reference (Orchestration Cluster), with the value a configured secret store holds for it, without that value being written into a process model, a job variable literal, or a configuration file.
+
+This is a separate mechanism from the connector runtime's `{{secrets.<name>}}` syntax, now called Secret reference (legacy). The two forms are resolved independently and are never mixed: a reference written in one form is never satisfied by a store or provider configured for the other.
+
+The legacy form was the subject of [security notice 61](https://docs.camunda.io/docs/next/reference/notices#notice-61), where an unscoped reference could resolve outside the field it was written in. The secret filter that notice introduces applies only to the legacy form. `camunda.secrets.<name>` resolution isn't affected: the broker records each reference's position in the job variables and replaces only that position, so a reference can't resolve at a field where it wasn't written.
+
+This page describes an alpha feature and may change in future releases. See [alpha features](https://docs.camunda.io/docs/next/components/early-access/alpha/alpha-features).
+
+Secret resolution is available in both SaaS and Self-Managed. See [Availability](https://docs.camunda.io/docs/next/components/concepts/secret-resolution-and-job-activation#availability) for what each offering provides and what you configure.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/secret-resolution

package/.llms/chunks/components.concepts.secret-resolution.physical-tenant-scope.md

@@ -0,0 +1,8 @@
+# Secret resolution — Physical-tenant scope
+
+A reference names no store, so it always addresses the physical tenant's `default` secret store: `camunda.secrets.X` means `camunda.secrets.default.X`. Each physical tenant supports exactly one secret store, counted across every store type combined, and that store's ID must be `default`. Configuring a second store under a different ID is rejected at startup.
+
+Resolving and listing both read the secret stores of the caller's physical tenant only, never another tenant's stores. See [Validation and constraints](https://docs.camunda.io/docs/next/self-managed/concepts/physical-tenants/configuration-reference#validation-and-constraints) for how the one-store-per-tenant rule is validated, and [Secrets](https://docs.camunda.io/docs/next/self-managed/components/orchestration-cluster/core-settings/configuration/properties#secrets) for store configuration.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/secret-resolution

package/.llms/chunks/components.concepts.secret-resolution.reference-syntax.md

@@ -0,0 +1,29 @@
+# Secret resolution — Reference syntax
+
+A reference has the form `camunda.secrets.<name>`, where `<name>` is a single, non-empty token of ASCII letters, digits, `_`, and `-`.
+
+`camunda.secrets.<name>` is authored as a FEEL expression (`=camunda.secrets.<name>`), so a dashed name has to be backtick-escaped. A bare dash is FEEL's minus operator:
+
+```feel
+=camunda.secrets.`db-password`
+```
+
+An unescaped dashed name is not a reference. FEEL reads `=camunda.secrets.db-password` as the reference `db` minus the variable `password`.
+
+### Charset differs by surface
+
+The engine detects a reference by parsing the FEEL abstract syntax tree, not by matching characters against a fixed set. A name written in a model can therefore be anything a FEEL identifier allows, including unicode letters, `$`, and any name that is backtick-escaped, such as `` =camunda.secrets.`tls.crt` ``.
+
+The gateway API is stricter. `POST /v2/secrets/resolve` and `POST /v2/secrets/list` both reject any name outside `[\p{Alnum}_-]+`.
+
+| Name                                       | Resolves in a model | Usable with `/v2/secrets/resolve` or `/v2/secrets/list` |
+| :----------------------------------------- | :-----------------: | :-----------------------------------------------------: |
+| `API_TOKEN`                                |         Yes         |                           Yes                           |
+| `` `db-password` `` (backtick-escaped)     |         Yes         |                 Yes (as `db-password`)                  |
+| `` `tls.crt` `` (backtick-escaped)         |         Yes         |                   No: contains a `.`                    |
+| `` `résumé` `` (backtick-escaped, unicode) |         Yes         |              No: outside `[\p{Alnum}_-]+`               |
+
+A name a model can reference is not guaranteed to be creatable or manageable through the API. Use the API's charset for any name you intend to create, list, or grant permissions on through `/v2/secrets/*`.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/secret-resolution

package/.llms/chunks/components.concepts.secret-resolution.related-resources.md

@@ -0,0 +1,9 @@
+# Secret resolution — Related resources
+
+- [Secret resolution and job activation](https://docs.camunda.io/docs/next/components/concepts/secret-resolution-and-job-activation) covers the broker path in detail: the scheduler, retries, and both delivery paths.
+- [Troubleshoot secret resolution failures](https://docs.camunda.io/docs/next/components/concepts/secret-resolution-incidents) covers the incidents raised when a reference or its injection fails.
+- [Authorizations](https://docs.camunda.io/docs/next/components/concepts/access-control/authorizations) covers the `SECRET` resource's `READ` and `REVEAL` permissions.
+- [Secrets](https://docs.camunda.io/docs/next/apis-tools/java-client/secrets) covers the Java client's resolve and list commands, including how a per-reference failure is reported.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/secret-resolution

package/.llms/chunks/components.concepts.secret-resolution.two-resolution-paths.md

@@ -0,0 +1,14 @@
+# Secret resolution — Two resolution paths
+
+|          | Broker path                             | Gateway API path                                                                           |
+| :------- | :-------------------------------------- | :----------------------------------------------------------------------------------------- |
+| Used by  | Job workers, outbound connectors        | Inbound connectors (`POST /v2/secrets/resolve`), the Web Modeler (`POST /v2/secrets/list`) |
+| When     | Asynchronously, ahead of job activation | On demand, per request                                                                     |
+| Delivery | Long polling and job push               | The HTTP response                                                                          |
+
+The broker path resolves references in a job's variables in the background and injects the resolved values only when the job is activated. See [Secret resolution and job activation](https://docs.camunda.io/docs/next/components/concepts/secret-resolution-and-job-activation) for the scheduler, caching, and delivery mechanics, including why no resolved value reaches a record, runtime state, or log on this path.
+
+The gateway API path serves callers that have no job to wait on. An inbound connector resolves the references an expression evaluation used, in batches, through `POST /v2/secrets/resolve`. The Web Modeler calls `POST /v2/secrets/list` to offer known reference names while you author a model. Both endpoints share a request and response contract described in [Secrets](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-secrets); for the full request and response schema of each, see [Resolve secrets](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/resolve-secrets.api) and [List secrets](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/list-secrets.api).
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/secret-resolution

package/.llms/chunks/components.concepts.signals.md

@@ -0,0 +1,20 @@
+# Signals
+
+Learn about broadcasting signals, which can trigger all matching signal events with a single broadcast.
+
+Signals are a similar concept to [messages](https://docs.camunda.io/docs/next/components/concepts/messages). However, messages are correlated to a specific
+process instance, whereas signals can trigger _all_ the matching signal events with a single broadcast.
+Depending on the type of [signal catch events](https://docs.camunda.io/docs/next/components/modeler/bpmn/signal-events/signal-events), the process instance will
+respond accordingly.
+
+
+## Broadcasting signals
+
+You can broadcast signals in several ways:
+
+- Using a [signal throw event or signal end event](https://docs.camunda.io/docs/next/components/modeler/bpmn/signal-events/signal-events#signal-throw-events)
+- Using the [Orchestration Cluster REST API Broadcast signal](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/broadcast-signal.api) endpoint
+- Using Zeebe's [`BroadcastSignal` RPC](https://docs.camunda.io/docs/next/apis-tools/zeebe-api/gateway-service#broadcastsignal-rpc)
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/signals

package/.llms/chunks/components.concepts.signals.signal-subscriptions.md

@@ -0,0 +1,24 @@
+# Signals — Signal subscriptions
+
+When you broadcast a signal it triggers _all_ signal subscriptions that match the signal name.
+
+When a process instance encounters a signal catch event it creates a new signal subscription. This process instance waits until a signal with a matching name is broadcasted. You can define the signal name in the
+process definition.
+
+Deploying a process with a signal start event also creates a new signal subscription. In this case, the triggered
+subscription starts a new process instance.
+
+
+## Signal cardinality
+
+A broadcasted signal iterates over _all_ available subscriptions. As a result, a single broadcast triggers _all_ the
+signal catch events that match the signal name, and _all_ [partitions](https://docs.camunda.io/docs/next/components/zeebe/technical-concepts/partitions).
+
+**Caution**
+Signals can negatively impact the performance of Camunda 8. Performance is impacted in two ways:
+
+- Signals trigger _all_ available subscriptions that match the signal name, potentially resulting in the continued execution of many processes.
+- Signals are broadcasted to _all_ partitions, resulting in lots of network traffic. This scales linearly with the number of partitions.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/signals

package/.llms/chunks/components.concepts.user-task-listeners-guide.additional-resources-and-next-steps.md

@@ -0,0 +1,7 @@
+# Example user task listener — Additional resources and next steps
+
+- Learn more about Camunda 8 and what it can do by reading [What is Camunda 8](https://docs.camunda.io/docs/next/components/components-overview) or watching our [Overview video](https://bit.ly/3TjNEm7) in Camunda Academy.
+- Get your local environment ready for development with Camunda 8 by [setting up your first development project](https://docs.camunda.io/docs/next/guides/getting-started-example).
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/user-task-listeners-guide

package/.llms/chunks/components.concepts.user-task-listeners-guide.md

@@ -0,0 +1,19 @@
+# Example user task listener
+
+In Camunda 8, user task listeners allow you to run custom logic when a user task is created, assigned, or completed.
+
+Beginner
+Time estimate: 35 minutes
+
+In Camunda 8, **user task listeners** allow you to run custom logic in response to changes to a user task, such as when the `creating`, `assigning`, or `completing` event occurs.
+
+User task listeners facilitate the integration of custom logic into your workflows. For more details, refer to the [User Task Listeners concept](https://docs.camunda.io/docs/next/components/concepts/user-task-listeners).
+
+This guide walks you through:
+
+- Defining a task listener using **Camunda Hub**
+- Implementing a task listener as a job worker
+- Verifying the result in **Operate** and **Tasklist**
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/user-task-listeners-guide

package/.llms/chunks/components.concepts.user-task-listeners-guide.prerequisites.md

@@ -0,0 +1,50 @@
+# Example user task listener — Prerequisites
+
+You must have access to a Camunda 8 SaaS account.
+
+   Have you signed up for Camunda yet?
+
+---
+---
+
+
+## Sign Up
+
+Visit [signup.camunda.com/accounts](https://signup.camunda.com/accounts?utm_source=docs.camunda.io&utm_medium=referral) to sign up.
+
+### Create an account
+
+Fill out the form and click **Create account**.
+
+When you fill out the form, you'll receive a confirmation email. Click on the link to verify your email address.
+
+
+## Log in to your Camunda 8 account
+
+Log in with the email address and password you used in the previous form, or use the social login buttons. To access the login site directly, navigate to [camunda.io](https://weblogin.cloud.camunda.io/).
+
+![login](./../img/login.png)
+
+After login, select the square-shaped **Camunda components** icon in the upper-left corner, and select **Console** to view the Console overview page. This is the central place to manage the clusters, diagrams, and forms you want to deploy to Camunda 8.
+
+![overview-home](./../img/home.png)
+
+You must also know how to model a process with a user task.  
+If you haven't done this before, first follow the steps in our guide to [get started with human task orchestration](https://docs.camunda.io/docs/next/guides/getting-started-orchestrate-human-tasks).
+
+Additionally, you need the following:
+
+- Java ≥ 8
+- Maven
+- IDE (IntelliJ, VSCode, or similar)
+- Download and unzip or clone the [repository](https://github.com/camunda/camunda-8-tutorials), then navigate to:  
+  `camunda-8-tutorials/quick-start/task-listeners/worker-java`
+
+For all steps in this guide, refer to the following diagram:
+
+Diagram (BPMN): Task Listener Tutorial
+  start "Task assignment needed" → user task "Assigned by creating task listener" → end "Task completed"
+  note: This user task does not specify an assignee. However, on creating a listener is triggered. The listener can externally decide upon the assignee by completing the job with a correction of the assignee. This can be useful when the assignee depends on an external system.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/user-task-listeners-guide

package/.llms/chunks/components.concepts.user-task-listeners-guide.step-1-create-a-process-with-a-user-task-in-hub.md

@@ -0,0 +1,29 @@
+# Example user task listener — Step 1: Create a process with a user task in Hub
+
+1. Launch **Camunda Hub**.
+2. In your workspace, open or create a project.
+3. In your project, create a new BPMN file.
+4. Add a user task named `Assigned by creating task listener`.
+
+
+## Step 2: Select the user task
+
+1. Click the **user task**.
+2. In the right-hand **properties panel**, scroll to **Task listeners**.
+
+
+## Step 3: Define a task listener
+
+Add a new task listener to the user task and define its properties:
+
+1. Click the plus sign in the **Task listeners** section to add a new task listener.
+2. Under **Event type**, select **Creating**.
+3. Under **Listener type**, enter `assign_new_task`.
+
+![Creating listener is defined with type assign_new_task](./assets/user-task-listeners-guide/3-creating-listener-defined.png)
+
+**Info**
+You've now defined a **creating** task listener for this user task. When a process instance arrives at this user task, the `creating` event is triggered, and a job of type `assign_new_task` is created. A job worker can then activate this job to execute the external logic and complete it, approving the creation of the user task.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/user-task-listeners-guide

package/.llms/chunks/components.concepts.user-task-listeners-guide.step-4-create-a-cluster.md

@@ -0,0 +1,26 @@
+# Example user task listener — Step 4: Create a cluster
+
+---
+---
+
+To deploy and run your process, create a cluster in Camunda 8.
+
+1. In **Camunda Hub**, under **Console > Clusters**, click **Create cluster**.
+2. Name your cluster.
+3. Select a region and backup location.
+4. Select a cluster type and tag.
+5. Select a channel and generation. For the purpose of this guide, Camunda recommends using the **Stable** channel and the latest generation.
+6. Click **Create cluster**.
+
+It will take a few moments to create your cluster. Check the status on the **Clusters** page or by clicking into the cluster itself and looking at the **Components** section.
+
+**Tip**
+If **Create cluster** is disabled, consider these explanations:
+
+- Your organization is on a trial plan, and you have already created a cluster. In this case, you cannot create another cluster, because only one cluster is included in the trial plan.
+- Your billing reservations do not allow any more clusters. You must increase the [reservations](https://docs.camunda.io/docs/next/components/hub/organization/manage-organization-settings/manage-plan/update-billing-reservations) to create more clusters. If you do not have the necessary rights, contact an admin or the owner of the organization.
+
+If the cluster shows a status of at least **Creating**, you can start modeling. However, Zeebe must show a status of **Healthy** to properly deploy your model.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/user-task-listeners-guide

package/.llms/chunks/components.concepts.user-task-listeners-guide.step-5-deploy-and-run-the-process.md

@@ -0,0 +1,32 @@
+# Example user task listener — Step 5: Deploy and run the process
+
+1. In your diagram, click **Deploy & run**.
+2. Select your deployment stage.
+3. Add an `assignee` or `manager` variable as JSON data. For example, `{ "assignee": "john.doe@camunda.com" }`.
+4. Click **Deploy & run**.
+
+
+## Step 6: Understand what happens to the user task
+
+Now, we'll explore what happened to the user task. We'll see that the listener blocks the creation.
+
+1. Navigate to **Tasklist** and notice that there is no task in Tasklist yet.
+
+   ![No tasks found in Tasklist](./assets/user-task-listeners-guide/6.2-no-tasks-found.png)
+
+2. Navigate to **Operate** to see your process instance with a token waiting at the user task by clicking on the active process instance in the **Dashboard**.
+
+   ![Active process instances in Operate Dashboard](./assets/user-task-listeners-guide/6.3-active-process-instances.png)
+
+3. Click the **Process instance key** to [inspect the process instance](https://docs.camunda.io/docs/next/components/operate/userguide/basic-operate-navigation#inspect-a-process-instance).
+
+   ![Inspect process instance in Operate](./assets/user-task-listeners-guide/6.4-inspect-process-instance.png)
+
+4. Click the user task and then click the **Listeners** tab to see that the **Creating** listener is **Active**.
+
+   ![Inspect listeners for user task in Operate](./assets/user-task-listeners-guide/6.5-inspect-listeners.png)
+
+5. Take a moment to understand the properties of the listener, for example verify that the listener type is what you defined in the process model. This listener is a job that can be activated and handled by a job worker.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/user-task-listeners-guide

package/.llms/chunks/components.concepts.user-task-listeners-guide.step-7-implement-the-listener.md

@@ -0,0 +1,32 @@
+# Example user task listener — Step 7: Implement the listener
+
+Next, we'll run the listener application to execute our external logic, and complete the listener job to continue the user task's creation.
+
+### Create credentials for your Camunda client
+
+---
+---
+
+To interact with your Camunda 8 cluster, you'll use the Camunda client. First, you'll need to create credentials.
+
+1. In Camunda Hub, in the left navigation, under **Console**, click **Clusters**.
+2. Select a cluster.
+3. Click the **API** tab.
+4. Click **Create new client**.
+5. Provide a **Client Name** and **Scopes**.
+6. Click **Create**.
+7. Copy or download your client credentials.
+
+You will need your client ID and your client secret when creating a worker in the next section, so keep this window open. Once you close or navigate away from this screen, you will not be able to see them again.
+
+### Create a job worker to implement the task listener
+
+Next, we’ll create a worker that listens to the user task's events by associating it with the **Listener type** we specified on the task listener in the BPMN diagram.
+
+1. Open the downloaded or cloned project ([repo](https://github.com/camunda/camunda-8-tutorials), then `cd` into `camunda-8-tutorials/quick-start/task-listeners/worker-java`) in your IDE.
+2. Add your credentials to `application.properties`. Your client ID and client secret are available from the previous section in the credential text file you downloaded or copied. [Find your **Region ID** and **Cluster ID**](https://docs.camunda.io/docs/next/components/hub/organization/manage-clusters/manage-api-clients#view-connection-informationview-connection-information).
+3. In the `Listener.java` file, change the type to match what you specified in the BPMN diagram. If you followed the previous steps for this guide and entered “assign_new_task”, no action is required.
+4. After making these changes, perform a Maven install, then run the Listener.java `main` method via your favorite IDE. If you prefer using a terminal, run `mvn package exec:java`.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/user-task-listeners-guide