diff --git a/docs/documentation/user-guide/process-engine/scripting.md b/docs/documentation/user-guide/process-engine/scripting.md
index fc89f27..d5412a4 100644
--- a/docs/documentation/user-guide/process-engine/scripting.md
+++ b/docs/documentation/user-guide/process-engine/scripting.md
@@ -531,7 +531,7 @@ the current context every time the element is executed.
- ```${sourceCode}
+ ${sourceCode}
@@ -578,6 +578,32 @@ script task.
```
+:::caution[Dynamic script-source detection]
+
+For languages other than JUEL, Operaton treats inline script content as an expression that
+resolves to source code when the content starts with `${` or `#{`. Leading whitespace is ignored
+for this check. The format name is compared case-insensitively, and a script task without a
+`scriptFormat` defaults to `juel`, so no detection takes place in that case. Detection applies to
+script tasks, listeners, conditions, and input/output parameters.
+
+Once the content matches, the whole content is parsed as a single composite expression. Every
+`${...}` and `#{...}` in it is resolved by the expression language and
+the remaining text is passed through literally. An unintended match can therefore:
+
+* replace placeholders that were meant for the script language, for example Groovy GString
+ interpolation such as `"${price}"`;
+* fail at runtime if a referenced variable does not exist;
+* fail the deployment if the content is not valid expression syntax, for example a Groovy
+ closure such as `${ x -> x }`.
+
+If the content legitimately starts with `${` or `#{`, prefix it with a comment recognized by that
+language, or load it from an external resource. The comment itself must not start with `${` or
+`#{`; in languages that use `#` for comments, such as Python or Ruby, write `# {...}` instead of
+`#{...}`. For external resources, detection applies to the resource path, not to the contents of
+the loaded file.
+
+:::
+
For more information, see the
[operaton:resource](../../reference/bpmn20/custom-extensions/extension-attributes.md#resource)
section of the [Custom Extensions](../../reference/bpmn20/custom-extensions/index.md) chapter.