fix: update documentation and examples to improve clarity on @shell usage with zsh

Author: Akagi201

README.md

@@ -91,6 +91,7 @@ Shellflow also recognizes bounded block directives at the top of a block body:
 - `# @TIMEOUT <seconds>`
 - `# @RETRY <count>`
 - `# @EXPORT NAME=stdout|stderr|output|exit_code`
+- `# @SHELL <shell>` - Specify the shell to use (e.g., `zsh`, `bash`)
 
 `<ssh-host>` must match a `Host` entry in your SSH config. Shellflow then connects using that SSH host definition, which means the actual machine can be resolved through the configured `HostName`, `User`, `Port`, and `IdentityFile` values.
 
@@ -112,6 +113,22 @@ echo "remote output: $SHELLFLOW_LAST_OUTPUT"
 echo "version = $VERSION"
 ```
 
+Using `@SHELL` for remote servers with non-bash default shells:
+
+```bash
+#!/bin/bash
+
+# @REMOTE zsh-server
+# @SHELL zsh
+# zsh-specific commands work here
+reload
+compdef
+
+# @REMOTE bash-server
+# Default bash shell is used
+ls -la
+```
+
 ## SSH Configuration
 
 Example `~/.ssh/config` entry:

SKILL.md

@@ -167,6 +167,22 @@ You can use multiple exports in a single block:
 curl -s -w "%{http_code}" -o response.txt https://api.example.com
 ```
 
+### Shell Directive
+
+`# @SHELL <shell>` - Specify the shell to use for executing this block.
+
+Use this when targeting remote hosts that use a non-bash default shell (e.g., zsh).
+
+```bash
+# @REMOTE zsh-server
+# @SHELL zsh
+# zsh-specific commands now work
+reload
+compdef
+```
+
+Without `@SHELL`, Shellflow defaults to `bash` for all remote blocks.
+
 ## 5. Assume every block runs in a fresh shell
 
 Each block is isolated.
@@ -351,7 +367,7 @@ Shellflow returns distinct exit codes for different failure types:
 Before returning a Shellflow playbook, verify that:
 
 - The script is valid bash without custom DSL syntax.
-- Only `# @LOCAL`, `# @REMOTE <host>`, and block directives (`# @TIMEOUT`, `# @RETRY`, `# @EXPORT`) are used.
+- Only `# @LOCAL`, `# @REMOTE <host>`, and block directives (`# @TIMEOUT`, `# @RETRY`, `# @EXPORT`, `# @SHELL`) are used.
 - Block directives appear immediately after the block marker, before any commands.
 - Anything before the first marker is safe to repeat for every block.
 - Every block can run independently in a fresh shell.
@@ -399,6 +415,7 @@ log "build $BUILD_ID complete"
 - Using an undefined remote host alias.
 - Placing block directives after commands instead of immediately after the marker.
 - Using invalid export sources (not stdout, stderr, output, or exit_code).
+- Forgetting that `@SHELL` must be specified before any commands in the block.
 - Forgetting that `@RETRY 0` means no retry attempts.
 - Using `@TIMEOUT` with values too small for normal operation.
 - Printing extra debug output from a block whose output is consumed by the next block via `@EXPORT`.

examples/zsh_remote.sh

@@ -0,0 +1,14 @@
+#!/bin/bash
+# Example: Using @SHELL directive for remote servers with zsh
+
+# This script demonstrates how to use the @SHELL directive
+# to execute commands on remote servers that use zsh as their default shell.
+
+# @REMOTE zsh-server
+# @SHELL zsh
+# Now zsh-specific commands will work
+echo "Running in zsh on remote server"
+
+# @REMOTE another-server
+# Default bash shell will be used (no @SHELL directive)
+echo "Running in bash on another server"

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "shellflow"
-version = "0.2.0"
+version = "0.2.1"
 description = "A minimal shell script orchestrator with SSH support"
 readme = "README.md"
 license = "Apache-2.0"

src/shellflow.py

@@ -46,6 +46,7 @@ class Block:
     timeout_seconds: int | None = None
     retry_count: int = 0
     exports: dict[str, str] = field(default_factory=dict)
+    shell: str | None = None  # Shell to use for execution (e.g., "zsh", "bash")
 
     @property
     def is_local(self) -> bool:
@@ -501,6 +502,11 @@ def _apply_block_directive(block: Block, marker_name: str, marker_argument: str
         export_name, export_source = _parse_export_directive(marker_argument, line_no=line_no)
         block.exports[export_name] = export_source
         return
+    if marker_name == "SHELL":
+        if not marker_argument:
+            raise ParseError(f"Line {line_no}: @SHELL requires a shell name (e.g., zsh, bash)")
+        block.shell = marker_argument
+        return
     raise ParseError(f"Line {line_no}: Unknown marker @{marker_name}")
 
 
@@ -890,7 +896,8 @@ def execute_remote(
     if ssh_config_path.exists():
         ssh_args.extend(["-F", str(ssh_config_path)])
 
-    ssh_args.extend(["-o", "BatchMode=yes", host, "bash", "-se"])
+    shell = block.shell or "bash"
+    ssh_args.extend(["-o", "BatchMode=yes", host, shell, "-se"])
     remote_script = _build_executable_script(
         block.commands,
         context,