feat(fs-workflow): add --dry-run flag, crate README, improved error messages

- Add --dry-run flag to `rpa-fs run` — validates and displays workflow
  plan (watch paths, rules, actions) without executing
- Add crate README.md with usage, config examples, action/event reference
- Improve config loading errors: show file path, JSON line/column on parse failure
- --version already supported via clap derive

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

crates/rpa-fs-workflow/README.md

@@ -0,0 +1,120 @@
+<!-- SPDX-License-Identifier: PMPL-1.0-or-later -->
+# rpa-fs-workflow
+
+Filesystem workflow automation CLI for [RPA Elysium](../../README.adoc).
+
+## Overview
+
+`rpa-fs` watches directories for file system events (create, modify, delete, rename) and
+executes configured actions — copy, move, archive, delete, rename, or plugin-based operations.
+
+## Installation
+
+```bash
+cargo install --path .
+# or from workspace root:
+just install
+```
+
+## Usage
+
+```bash
+# Generate an example workflow config
+rpa-fs init workflow.json
+
+# Validate a config without running
+rpa-fs validate workflow.json
+
+# Run a workflow
+rpa-fs run workflow.json
+
+# Dry run — validate and display plan without executing
+rpa-fs run --dry-run workflow.json
+
+# Verbose output
+rpa-fs -v run workflow.json
+
+# Show version
+rpa-fs --version
+```
+
+## Configuration
+
+Workflow configs are JSON or [Nickel](https://nickel-lang.org/) files.
+
+### JSON Example
+
+```json
+{
+  "name": "backup-documents",
+  "description": "Auto-backup PDFs and spreadsheets",
+  "watch": [
+    { "path": "/home/user/Downloads", "recursive": true }
+  ],
+  "rules": [
+    {
+      "name": "backup-pdfs",
+      "patterns": ["*.pdf"],
+      "events": ["created"],
+      "actions": [
+        { "type": "copy", "destination": "/home/user/Backups/pdf" }
+      ]
+    },
+    {
+      "name": "archive-old-logs",
+      "patterns": ["*.log"],
+      "events": ["modified"],
+      "actions": [
+        { "type": "archive", "destination": "/home/user/Archives", "format": "tar_gz" }
+      ]
+    }
+  ]
+}
+```
+
+### Nickel Example
+
+See [`examples/workflow.ncl`](../../examples/workflow.ncl) for a Nickel configuration example.
+
+## Action Types
+
+| Action | Description |
+|--------|-------------|
+| `copy` | Copy file to destination (with optional overwrite and structure preservation) |
+| `move` | Move file to destination |
+| `archive` | Compress file to tar.gz or zip archive |
+| `delete` | Delete the file (with optional trash support) |
+| `rename` | Rename file using `{name}` and `{ext}` pattern substitution |
+| `plugin` | Execute a WASM plugin action (requires rpa-plugin integration) |
+
+## Event Types
+
+| Event | Triggers when |
+|-------|---------------|
+| `created` | A new file appears in the watched directory |
+| `modified` | An existing file is changed |
+| `deleted` | A file is removed |
+| `renamed` | A file is renamed or moved within the watch scope |
+
+## Architecture
+
+```
+rpa-fs-workflow/
+├── src/
+│   ├── main.rs       # CLI entry point (clap)
+│   ├── lib.rs         # Public API
+│   ├── config.rs      # JSON/Nickel config parsing
+│   ├── runner.rs      # Workflow execution engine
+│   ├── watcher.rs     # Filesystem event watcher (notify)
+│   └── actions/       # Action implementations
+│       ├── copy.rs
+│       ├── move_file.rs
+│       ├── archive.rs
+│       ├── delete.rs
+│       ├── rename.rs
+│       └── plugin.rs
+```
+
+## License
+
+PMPL-1.0-or-later

crates/rpa-fs-workflow/src/config.rs

@@ -170,8 +170,22 @@ impl WorkflowConfig {
     /// Load from JSON file
     fn load_json(path: &Path) -> Result<Self> {
         debug!("Loading JSON config from {}", path.display());
-        let content = std::fs::read_to_string(path)?;
-        let config: Self = serde_json::from_str(&content)?;
+        let content = std::fs::read_to_string(path).map_err(|e| {
+            Error::Config(format!(
+                "Cannot read config file '{}': {}",
+                path.display(),
+                e
+            ))
+        })?;
+        let config: Self = serde_json::from_str(&content).map_err(|e| {
+            Error::Config(format!(
+                "Invalid JSON in '{}': {} (line {}, column {})",
+                path.display(),
+                e,
+                e.line(),
+                e.column()
+            ))
+        })?;
         config.validate()?;
         Ok(config)
     }

crates/rpa-fs-workflow/src/main.rs

@@ -50,6 +50,10 @@ enum Commands {
     Run {
         /// Path to the workflow configuration file (.json or .ncl)
         config: PathBuf,
+
+        /// Validate and display the workflow without executing it
+        #[arg(long)]
+        dry_run: bool,
     },
 
     /// Generate an example configuration file
@@ -84,7 +88,13 @@ fn main() {
         .init();
 
     let result = match cli.command {
-        Commands::Run { config } => run_workflow(config),
+        Commands::Run { config, dry_run } => {
+            if dry_run {
+                dry_run_workflow(config)
+            } else {
+                run_workflow(config)
+            }
+        }
         Commands::Init { output } => init_workflow(output),
         Commands::Validate { config } => validate_workflow(config),
     };
@@ -95,6 +105,47 @@ fn main() {
     }
 }
 
+/// Validate and display workflow plan without executing
+fn dry_run_workflow(config_path: PathBuf) -> anyhow::Result<()> {
+    info!("Dry run — loading workflow from: {}", config_path.display());
+
+    let config = WorkflowConfig::load(&config_path)?;
+
+    info!("Workflow: {}", config.workflow.name);
+    if let Some(desc) = &config.workflow.description {
+        info!("  Description: {}", desc);
+    }
+    info!("  Version: {}", config.workflow.version);
+    info!("  Enabled: {}", config.workflow.enabled);
+
+    info!("Watch paths ({}):", config.watch.len());
+    for watch in &config.watch {
+        info!(
+            "  - {} (recursive: {})",
+            watch.path.display(),
+            watch.recursive
+        );
+        if !watch.path.exists() {
+            info!("    [WARNING] Path does not exist — will be created at runtime");
+        }
+    }
+
+    info!("Rules ({}):", config.rules.len());
+    for rule in &config.rules {
+        info!(
+            "  - {} (enabled: {}, events: {:?}, patterns: {:?}, actions: {})",
+            rule.name,
+            rule.enabled,
+            rule.events,
+            rule.patterns,
+            rule.actions.len()
+        );
+    }
+
+    info!("Dry run complete — configuration is valid, no actions were executed.");
+    Ok(())
+}
+
 fn run_workflow(config_path: PathBuf) -> anyhow::Result<()> {
     info!("Loading workflow from: {}", config_path.display());