note validation options

TEMPLATES.md

@@ -666,12 +666,76 @@ echo "Installation of ${CONTAINER_NAME} complete"
 4. **Handle cleanup** properly in stop.sh and uninstall.sh using `docker compose down`
 5. **Use named volumes** for persistent data that matches Dropshell conventions
 
-## Testing Templates
+## Validating Templates
 
-After creating a template, validate it:
+Dropshell includes a comprehensive template validation command that checks for common issues:
 
 ```bash
-dropshell test-template /path/to/template
+dropshell validate <template-name>
 ```
 
-This checks all requirements and reports any issues.
+Aliases: `ds lint`, `ds check-template`
+
+### What Validate Checks
+
+1. **Structure Validation**
+   - Required files exist (`install.sh`, `uninstall.sh`, `config/service.env`, `config/.template_info.env`)
+   - Scripts are executable
+   - `TEMPLATE` variable matches directory name
+
+2. **Shell Script Linting (via Shellcheck)**
+   - Runs [shellcheck](https://www.shellcheck.net/) on all `.sh` files
+   - Catches common bash issues: quoting, syntax errors, unused variables, etc.
+   - Runs in a Docker container (`koalaman/shellcheck:stable`) - no host installation required
+
+3. **Dropshell-Specific Checks**
+   - Main scripts (`install.sh`, `uninstall.sh`, `start.sh`, `stop.sh`, `status.sh`) source `common.sh`
+
+### Example Output
+
+```
+$ ds validate my-template
+
+=== Structure Validation ===
+  ✓ Template structure is valid
+
+=== Shellcheck Linting ===
+  ✓ install.sh
+  ✓ uninstall.sh
+  ✓ start.sh
+    status.sh:14:33: warning: Double quote to prevent globbing. [SC2086]
+
+=== Dropshell: common.sh sourcing ===
+  ✓ Sources common.sh: install.sh
+  ✓ Sources common.sh: uninstall.sh
+  ⚠ Missing 'source "${AGENT_PATH}/common.sh"' in start.sh
+
+Validation Summary: Template 'my-template' has 2 warning(s)
+```
+
+### Pre-Install Validation
+
+The `install` command automatically runs basic syntax checking (`bash -n`) on all template scripts before deploying. If any script has a syntax error, the install fails with a clear message:
+
+```
+[ERR] Template shell scripts have syntax errors. Run 'ds validate my-template' for details.
+```
+
+### Suppressing Shellcheck Warnings
+
+If shellcheck reports a false positive, you can suppress it with a comment:
+
+```bash
+# shellcheck disable=SC2034  # Variable used by sourced script
+MY_VAR="value"
+```
+
+Place the disable comment on the line before the flagged code. See [shellcheck wiki](https://github.com/koalaman/shellcheck/wiki/Ignore) for more options.
+
+### Best Practices
+
+1. **Run validate before publishing** - Ensure your template passes all checks
+2. **Fix warnings, not just errors** - Warnings often indicate real issues
+3. **Source common.sh in all main scripts** - Provides `_die`, `_check_docker_installed`, etc.
+4. **Quote variables** - Especially in paths and test expressions
+5. **Add error handling** - Use `|| _die "message"` after commands that can fail

source/src/commands/help.cpp

@@ -153,6 +153,9 @@ int help_handler(const CommandContext& ctx) {
         info << std::endl;
         show_command("create-server");
         show_command("create-service");
+        show_command("create-template");
+        info << std::endl;
+        show_command("validate");
     }
     return 0;
 }