docs(plugin-scripts): add how-to docs

plugin-script-bun/src/main/resources/doc/io.kestra.plugin.scripts.bun.md

@@ -0,0 +1,13 @@
+# How to use the Bun plugin
+
+Run TypeScript and JavaScript scripts with Bun's built-in runtime — no transpile step required.
+
+## Common properties
+
+`containerImage` defaults to `oven/bun`. Pin a specific version (e.g., `oven/bun:1`) for reproducibility. `taskRunner` defaults to Docker and can be overridden for other execution environments.
+
+## Tasks
+
+`Script` runs inline TypeScript or JavaScript defined in the `script` property — best for short, flow-specific logic. `Commands` runs shell commands (e.g., `bun run index.ts`) against script files; use it when your code lives in [namespace files](https://kestra.io/docs/concepts/namespace-files) shared across flows, or is cloned from a Git repository with a preceding `Clone` task.
+
+Install packages in `beforeCommands` with `bun add <package>`, or include a `bun.lockb` and `package.json` via namespace files and run `bun install` to restore dependencies before execution.

plugin-script-deno/src/main/resources/doc/io.kestra.plugin.scripts.deno.md

@@ -0,0 +1,13 @@
+# How to use the Deno plugin
+
+Run TypeScript and JavaScript with Deno's secure-by-default runtime — imports are URL-based, so no install step is needed for most dependencies.
+
+## Common properties
+
+`containerImage` defaults to `denoland/deno`. `taskRunner` defaults to Docker and can be overridden for other execution environments.
+
+## Tasks
+
+`Script` runs inline TypeScript or JavaScript defined in the `script` property — best for short, flow-specific logic. `Commands` runs Deno commands (e.g., `deno run --allow-net main.ts`) against script files; use it when your code lives in [namespace files](https://kestra.io/docs/concepts/namespace-files) shared across flows, or is cloned from a Git repository with a preceding `Clone` task.
+
+Deno resolves imports from URLs at runtime — no install step needed for URL-based imports. For local module graphs, include a `deno.json` import map via namespace files. Pass Deno permission flags (`--allow-net`, `--allow-read`, `--allow-env`, etc.) directly in `commands` to scope what the script can access.

plugin-script-go/src/main/resources/doc/io.kestra.plugin.scripts.go.md

@@ -0,0 +1,13 @@
+# How to use the Go plugin
+
+Compile and run Go programs as flow steps, with full module and dependency support.
+
+## Common properties
+
+`containerImage` defaults to a Go image. Pin a specific version (e.g., `golang:1.22`) for reproducibility. `taskRunner` defaults to Docker and can be overridden for other execution environments.
+
+## Tasks
+
+`Script` runs inline Go code defined in the `script` property (wrapped in a `main` package automatically) — best for short, flow-specific logic. `Commands` runs shell commands (e.g., `go run main.go`) against source files; use it when your code lives in [namespace files](https://kestra.io/docs/concepts/namespace-files) shared across flows, or is cloned from a Git repository with a preceding `Clone` task.
+
+For module-based projects, include a `go.mod` (and optionally `go.sum`) via namespace files and run `go mod download` in `beforeCommands` before executing your program.

plugin-script-groovy/src/main/resources/doc/io.kestra.plugin.scripts.groovy.md

@@ -0,0 +1,11 @@
+# How to use the Groovy plugin
+
+Execute Groovy code directly in the Kestra JVM — no container or task runner required.
+
+## Tasks
+
+`Eval` runs inline Groovy code and is the primary task for general scripting. `Script` runs a Groovy script file. Both execute in-process on the Kestra worker with access to the full JVM classpath — no `containerImage` or `taskRunner` is needed.
+
+`FileTransform` processes Kestra internal storage files (Ion, Avro, JSON) record by record, transforming or filtering rows without writing intermediate files to disk. It is the right choice when you need lightweight row-level data transformation between tasks.
+
+Add Maven dependencies inline using Grape annotations: `@Grab('group:artifact:version')` at the top of your script resolves the dependency from Maven Central at runtime.

plugin-script-jbang/src/main/resources/doc/io.kestra.plugin.scripts.jbang.md

@@ -0,0 +1,13 @@
+# How to use the JBang plugin
+
+Run Java source files directly without a build system — JBang compiles and executes them on the fly.
+
+## Common properties
+
+`containerImage` defaults to a JBang image. `taskRunner` defaults to Docker and can be overridden for other execution environments.
+
+## Tasks
+
+`Script` runs inline Java code defined in the `script` property — best for short, flow-specific logic. `Commands` runs JBang commands (e.g., `jbang main.java`) against source files; use it when your code lives in [namespace files](https://kestra.io/docs/concepts/namespace-files) shared across flows, or is cloned from a Git repository with a preceding `Clone` task.
+
+Declare Maven dependencies directly in the source file using JBang's `//DEPS` directive at the top: `//DEPS com.google.guava:guava:32.0.0-jre`. JBang resolves and caches them automatically at runtime — no `pom.xml` or `build.gradle` required.

plugin-script-julia/src/main/resources/doc/io.kestra.plugin.scripts.md

@@ -0,0 +1,13 @@
+# How to use the Julia plugin
+
+Run Julia scripts for numerical computing and data science inside a container as flow steps.
+
+## Common properties
+
+`containerImage` defaults to `julia:latest`. Pin a specific version (e.g., `julia:1.10`) for reproducibility. `taskRunner` defaults to Docker and can be overridden for other execution environments.
+
+## Tasks
+
+`Script` runs inline Julia code defined in the `script` property — best for short, flow-specific logic. `Commands` runs shell commands (e.g., `julia main.jl`) against script files; use it when your code lives in [namespace files](https://kestra.io/docs/concepts/namespace-files) shared across flows, or is cloned from a Git repository with a preceding `Clone` task.
+
+For package dependencies, install them in `beforeCommands` with `julia -e 'using Pkg; Pkg.add("DataFrames")'`. For larger environments, include a `Project.toml` and `Manifest.toml` via namespace files and run `julia --project -e 'using Pkg; Pkg.instantiate()'` in `beforeCommands` to restore the exact package state.

plugin-script-jython/src/main/resources/doc/io.kestra.plugin.scripts.jython.md

@@ -0,0 +1,9 @@
+# How to use the Jython plugin
+
+Execute Python 2.7 code on the JVM with direct access to Java classes — no container required.
+
+## Tasks
+
+`Eval` runs inline Python code directly in the Kestra JVM via the Jython interpreter — no `containerImage` or `taskRunner` is needed. `FileTransform` processes Kestra internal storage files (Ion, Avro, JSON) record by record, transforming or filtering rows without writing intermediate files to disk.
+
+Jython implements Python 2.7. For Python 3 compatibility or access to native C extensions (NumPy, pandas, etc.), use the [Python plugin](https://kestra.io/plugins/io.kestra.plugin.scripts.python) instead, which runs in a container with the full CPython runtime.

plugin-script-lua/src/main/resources/doc/io.kestra.plugin.scripts.lua.md

@@ -0,0 +1,13 @@
+# How to use the Lua plugin
+
+Run Lua scripts inside a container as flow steps.
+
+## Common properties
+
+`containerImage` defaults to a Lua image. `taskRunner` defaults to Docker and can be overridden for other execution environments.
+
+## Tasks
+
+`Script` runs inline Lua code defined in the `script` property — best for short, flow-specific logic. `Commands` runs shell commands (e.g., `lua main.lua`) against script files; use it when your code lives in [namespace files](https://kestra.io/docs/concepts/namespace-files) shared across flows, or is cloned from a Git repository with a preceding `Clone` task.
+
+Install LuaRocks packages in `beforeCommands` with `luarocks install <package>`, or use a custom `containerImage` pre-built with your dependencies.

plugin-script-nashorn/src/main/resources/doc/io.kestra.plugin.scripts.nashorn.md

@@ -0,0 +1,9 @@
+# How to use the Nashorn plugin
+
+Execute JavaScript in the Kestra JVM using the Nashorn engine — no container required, with direct access to Java classes.
+
+## Tasks
+
+`Eval` runs inline JavaScript directly in the Kestra JVM — no `containerImage` or `taskRunner` is needed. `FileTransform` processes Kestra internal storage files (Ion, Avro, JSON) record by record, transforming or filtering rows without writing intermediate files to disk.
+
+Nashorn runs on the Java 11 engine and supports ES5 with partial ES6 coverage. For modern JavaScript (ES6 modules, async/await, npm packages), use the [Node](https://kestra.io/plugins/io.kestra.plugin.scripts.node) or [Deno](https://kestra.io/plugins/io.kestra.plugin.scripts.deno) plugin instead.

plugin-script-node/src/main/resources/doc/io.kestra.plugin.scripts.node.md

@@ -0,0 +1,15 @@
+# How to use the Node.js plugin
+
+Run Node.js scripts and trigger flows from script output as flow steps.
+
+## Common properties
+
+`containerImage` defaults to a Node image. Pin a specific version (e.g., `node:20`) for reproducibility. `taskRunner` defaults to Docker and can be overridden for other execution environments.
+
+## Tasks
+
+`Script` runs inline JavaScript defined in the `script` property — best for short, flow-specific logic. `Commands` runs shell commands (e.g., `node index.js`) against script files; use it when your code lives in [namespace files](https://kestra.io/docs/concepts/namespace-files) shared across flows, or is cloned from a Git repository with a preceding `Clone` task.
+
+Install npm packages in `beforeCommands` with `npm install` (from a `package.json` in namespace files) or `npm install <package>` for ad hoc installs. Use `npm ci` with a committed `package-lock.json` for reproducible installs.
+
+`CommandsTrigger` and `ScriptTrigger` run Node.js commands on a schedule and start one execution per run — use them for polling scripts that produce structured output consumed as Kestra trigger outputs.

plugin-script-perl/src/main/resources/doc/io.kestra.plugin.scripts.perl.md

@@ -0,0 +1,13 @@
+# How to use the Perl plugin
+
+Run Perl scripts inside a container as flow steps.
+
+## Common properties
+
+`containerImage` defaults to a Perl image. `taskRunner` defaults to Docker and can be overridden for other execution environments.
+
+## Tasks
+
+`Script` runs inline Perl code defined in the `script` property — best for short, flow-specific logic. `Commands` runs shell commands (e.g., `perl main.pl`) against script files; use it when your code lives in [namespace files](https://kestra.io/docs/concepts/namespace-files) shared across flows, or is cloned from a Git repository with a preceding `Clone` task.
+
+Install CPAN modules in `beforeCommands` with `cpanm <Module::Name>` (App::cpanminus is included in the default image), or use a custom `containerImage` pre-built with your dependencies.

plugin-script-php/src/main/resources/doc/io.kestra.plugin.scripts.php.md

@@ -0,0 +1,13 @@
+# How to use the PHP plugin
+
+Run PHP scripts inside a container as flow steps.
+
+## Common properties
+
+`containerImage` defaults to a PHP image. `taskRunner` defaults to Docker and can be overridden for other execution environments.
+
+## Tasks
+
+`Script` runs inline PHP code defined in the `script` property — best for short, flow-specific logic. `Commands` runs shell commands (e.g., `php main.php`) against script files; use it when your code lives in [namespace files](https://kestra.io/docs/concepts/namespace-files) shared across flows, or is cloned from a Git repository with a preceding `Clone` task.
+
+Manage dependencies with Composer — include a `composer.json` via namespace files and run `composer install` in `beforeCommands`. For projects without Composer dependencies, a plain PHP image is sufficient.

plugin-script-powershell/src/main/resources/doc/io.kestra.plugin.scripts.powershell.md

@@ -0,0 +1,13 @@
+# How to use the PowerShell plugin
+
+Run PowerShell scripts for Windows automation, Azure management, and cross-platform scripting from Kestra flows.
+
+## Common properties
+
+`containerImage` defaults to `mcr.microsoft.com/powershell`. `taskRunner` defaults to Docker and can be overridden for other execution environments.
+
+## Tasks
+
+`Script` runs inline PowerShell code defined in the `script` property — best for short, flow-specific logic. `Commands` runs PowerShell commands against script files; use it when your scripts live in [namespace files](https://kestra.io/docs/concepts/namespace-files) shared across flows, or are cloned from a Git repository with a preceding `Clone` task.
+
+Install PowerShell modules in `beforeCommands` with `Install-Module -Name <Module> -Force -AllowClobber`. For Azure automation, `Az` module is the standard; for Microsoft Graph, use `Microsoft.Graph`. Use a custom `containerImage` pre-built with your modules to avoid long install times on each execution.

plugin-script-python/src/main/resources/doc/io.kestra.plugin.scripts.python.md

@@ -0,0 +1,15 @@
+# How to use the Python plugin
+
+Run Python code inline or from files, with full control over dependencies, the container image, and the execution environment.
+
+## Common properties
+
+`containerImage` sets the Python image used for execution — defaults to a Kestra-managed Python image. Use a custom image (e.g., `python:3.12-slim`) or one pre-built with your dependencies to avoid installing them at runtime.
+
+`taskRunner` controls where the script runs. The default is Docker (isolated container on the local worker). Set it to `Process` to run directly on the worker without a container, or to a [Kubernetes task runner](https://kestra.io/docs/workflow-components/task-runners) to run in a remote cluster.
+
+## Tasks
+
+`Script` runs inline Python code defined in the `script` property — best for short, flow-specific logic. `Commands` runs shell commands (e.g., `python main.py`) against script files; use it when your code lives in [namespace files](https://kestra.io/docs/concepts/namespace-files) shared across flows, or is cloned from a Git repository with a preceding `Clone` task.
+
+Install dependencies with `beforeCommands` (e.g., `["pip install pandas requests"]`) or bake them into a custom `containerImage`. For larger dependency sets, store a `requirements.txt` as a namespace file and run `pip install -r requirements.txt` in `beforeCommands`. The same `Commands`/`Script` pattern applies to all other language submodules in this plugin (Shell, Node, R, Go, and others).

plugin-script-r/src/main/resources/doc/io.kestra.plugin.scripts.r.md

@@ -0,0 +1,13 @@
+# How to use the R plugin
+
+Run R scripts for statistical computing and data analysis inside a container as flow steps.
+
+## Common properties
+
+`containerImage` defaults to an R image (e.g., `r-base`). For data science workflows, consider images from the Rocker project (e.g., `rocker/tidyverse`) which include common packages pre-installed. `taskRunner` defaults to Docker and can be overridden for other execution environments.
+
+## Tasks
+
+`Script` runs inline R code defined in the `script` property — best for short, flow-specific logic. `Commands` runs shell commands (e.g., `Rscript main.R`) against script files; use it when your code lives in [namespace files](https://kestra.io/docs/concepts/namespace-files) shared across flows, or is cloned from a Git repository with a preceding `Clone` task.
+
+Install CRAN packages in `beforeCommands` with `Rscript -e 'install.packages(c("dplyr", "ggplot2"), repos="https://cloud.r-project.org")'`. For reproducible environments, use a `renv.lock` file via namespace files and restore with `Rscript -e 'renv::restore()'` — or build a custom `containerImage` with packages pre-installed to avoid per-run install time.

plugin-script-ruby/src/main/resources/doc/io.kestra.plugin.scripts.ruby.md

@@ -0,0 +1,13 @@
+# How to use the Ruby plugin
+
+Run Ruby scripts inside a container as flow steps.
+
+## Common properties
+
+`containerImage` defaults to a Ruby image. Pin a specific version (e.g., `ruby:3.3`) for reproducibility. `taskRunner` defaults to Docker and can be overridden for other execution environments.
+
+## Tasks
+
+`Script` runs inline Ruby code defined in the `script` property — best for short, flow-specific logic. `Commands` runs shell commands (e.g., `ruby main.rb`) against script files; use it when your code lives in [namespace files](https://kestra.io/docs/concepts/namespace-files) shared across flows, or is cloned from a Git repository with a preceding `Clone` task.
+
+Install gems in `beforeCommands` with `gem install <gem-name>`. For Bundler-managed projects, include a `Gemfile` (and optionally `Gemfile.lock`) via namespace files and run `bundle install` in `beforeCommands`.

plugin-script-shell/src/main/resources/doc/io.kestra.plugin.scripts.shell.md

@@ -0,0 +1,15 @@
+# How to use the Shell plugin
+
+Run shell commands and scripts from Kestra flows — the most direct way to invoke system tools, CLIs, and POSIX utilities.
+
+## Common properties
+
+`containerImage` sets the base OS image (`ubuntu:latest`, `alpine:latest`, or any image that includes the tools you need). `taskRunner` defaults to Docker and can be overridden for other execution environments.
+
+## Tasks
+
+`Script` runs an inline shell script defined in the `script` property — best for short, flow-specific logic. `Commands` runs shell commands against script files; use it when your scripts live in [namespace files](https://kestra.io/docs/concepts/namespace-files) shared across flows, or are cloned from a Git repository with a preceding `Clone` task.
+
+Install OS packages in `beforeCommands` with `apt-get install -y <pkg>` (Debian/Ubuntu images) or `apk add <pkg>` (Alpine images), or use a custom `containerImage` that already includes your tooling.
+
+`CommandsTrigger` and `ScriptTrigger` run shell commands on a schedule and start one execution per run — use them for polling scripts that produce structured output consumed as Kestra trigger outputs.