docs: enhance help messages and documentation for demo management commands

Improved user experience with detailed command descriptions and examples:

Command Help Messages:
- bin/new-demo: Added description explaining basic demo creation
- bin/scaffold-demo: Added description for advanced demo scaffolding
- bin/update-all-demos: Added description for bulk version updates
- All commands now show clear usage, examples, and available options

Documentation Updates:
- README.md: Reorganized demo management section with detailed examples for all three commands
- CONTRIBUTING.md: Updated with Ruby script recommendations and help flag usage
- CONTRIBUTING_SETUP.md: Added links to main README for detailed examples
- .gitignore: Added pr_description.md and commit_message.txt

Users can now run --help on any command to see:
- What the command does
- Usage syntax
- Example invocations
- All available options

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: justin808

.gitignore

@@ -51,4 +51,5 @@ vendor/bundle/
 
 # Ignore master key for decrypting credentials and more
 /demos/*/config/master.key
-/demos/*/config/credentials.yml.enc
+/demos/*/config/credentials.yml.encpr_description.md
+commit_message.txt

CONTRIBUTING.md

@@ -46,13 +46,22 @@ bin/dev
 
 ### Creating a New Demo
 
+Use the Ruby scripts for creating demos (fully tested and recommended):
+
 ```bash
-./scripts/new-demo.sh react_on_rails-demo-v16-your-feature
+# Create a basic demo
+bin/new-demo react_on_rails-demo-v16-your-feature
+
+# Create an advanced demo with scaffolding and integrations
+bin/scaffold-demo react_on_rails-demo-v16-your-feature
 
-# Or use the scaffold script with options:
-./scripts/scaffold-demo.sh react_on_rails-demo-v16-your-feature --typescript --tailwind
+# Show available options
+bin/new-demo --help
+bin/scaffold-demo --help
 ```
 
+See the [README](./README.md#create-a-new-demo) for detailed usage examples.
+
 ### Testing
 
 Run tests for all demos:

README.md

@@ -80,30 +80,78 @@ See [Development Setup](./docs/CONTRIBUTING_SETUP.md) for details.
 
 ### Create a New Demo
 
-Scripts are available in both Ruby (recommended) and Bash:
+Three commands are available for managing demos:
 
-```bash
-# Simple demo creation (Ruby)
-bin/new-demo react_on_rails-demo-v16-your-feature
+#### 1. `bin/new-demo` - Create Basic Demo
 
-# Or use bash script
-./scripts/new-demo.sh react_on_rails-demo-v16-your-feature
+Creates a new React on Rails demo with PostgreSQL, Shakapacker, and React on Rails pre-configured.
 
-# Scaffold with advanced options (Ruby)
-bin/scaffold-demo react_on_rails-demo-v16-your-feature --typescript --tailwind
+```bash
+# Basic usage (uses .demo-versions defaults)
+bin/new-demo react_on_rails-demo-v16-your-feature
 
-# Or bash version
-./scripts/scaffold-demo.sh react_on_rails-demo-v16-your-feature --typescript --tailwind
+# With custom versions
+bin/new-demo my-demo \
+  --shakapacker-version '~> 8.0' \
+  --react-on-rails-version '~> 16.1'
 
-# Specify custom gem versions
-bin/new-demo my-demo --shakapacker-version '~> 8.0' --react-on-rails-version '~> 16.0'
+# With custom Rails/generator arguments
+bin/new-demo my-demo \
+  --rails-args="--skip-test,--api" \
+  --react-on-rails-args="--redux,--node"
 
 # Preview commands without execution
 bin/new-demo my-demo --dry-run
+
+# Show help
+bin/new-demo --help
+```
+
+#### 2. `bin/scaffold-demo` - Create Advanced Demo
+
+Creates an advanced demo with scaffolding, example components, and optional integrations.
+
+```bash
+# Basic scaffolding
+bin/scaffold-demo react_on_rails-demo-v16-advanced
+
+# With TypeScript and Tailwind
+bin/scaffold-demo my-demo --typescript --tailwind
+
+# With Material-UI
+bin/scaffold-demo my-demo --mui
+
+# Skip database setup
+bin/scaffold-demo my-demo --skip-db
+
+# Show help
+bin/scaffold-demo --help
+```
+
+#### 3. `bin/update-all-demos` - Bulk Update Versions
+
+Updates React on Rails and/or Shakapacker versions across all existing demos.
+
+```bash
+# Update React on Rails across all demos
+bin/update-all-demos --react-on-rails-version '~> 16.1'
+
+# Update both gems
+bin/update-all-demos \
+  --react-on-rails-version '~> 16.1' \
+  --shakapacker-version '~> 8.1'
+
+# Preview without making changes
+bin/update-all-demos --react-on-rails-version '~> 16.1' --dry-run
+
+# Update specific demos only
+bin/update-all-demos --demos "demo-v16-*" --react-on-rails-version '~> 16.1'
+
+# Show help
+bin/update-all-demos --help
 ```
 
-**Ruby scripts** (in `bin/`) are fully tested and recommended for use.
-**Bash scripts** (in `scripts/`) are kept for compatibility.
+**Note:** Ruby scripts (in `bin/`) are fully tested and recommended. Bash scripts (in `scripts/`) are kept for compatibility.
 
 Default versions are configured in `.demo-versions`. Override with command-line flags.
 

bin/new-demo

@@ -16,6 +16,11 @@ options = {
 parser = OptionParser.new do |opts|
   opts.banner = 'Usage: bin/new-demo DEMO_NAME [options]'
   opts.separator ''
+  opts.separator 'Description:'
+  opts.separator '  Creates a new basic React on Rails demo application with PostgreSQL,'
+  opts.separator '  Shakapacker, and React on Rails pre-configured. Uses version defaults'
+  opts.separator '  from .demo-versions unless overridden.'
+  opts.separator ''
   opts.separator 'Example: bin/new-demo react_on_rails-demo-v16-typescript-setup'
   opts.separator ''
   opts.separator 'Options:'

bin/scaffold-demo

@@ -22,6 +22,11 @@ options = {
 parser = OptionParser.new do |opts|
   opts.banner = 'Usage: bin/scaffold-demo DEMO_NAME [options]'
   opts.separator ''
+  opts.separator 'Description:'
+  opts.separator '  Creates an advanced React on Rails demo with additional scaffolding,'
+  opts.separator '  example components, and optional integrations (TypeScript, Tailwind,'
+  opts.separator '  Bootstrap, Material-UI). Includes HelloWorld component and route setup.'
+  opts.separator ''
   opts.separator 'Example: bin/scaffold-demo react_on_rails-demo-v16-ssr-hmr'
   opts.separator ''
   opts.separator 'Options:'

bin/update-all-demos

@@ -16,7 +16,12 @@ options = {
 parser = OptionParser.new do |opts|
   opts.banner = 'Usage: bin/update-all-demos [options]'
   opts.separator ''
-  opts.separator 'Update React on Rails and/or Shakapacker versions across all demos.'
+  opts.separator 'Description:'
+  opts.separator '  Bulk updates React on Rails and/or Shakapacker versions across all'
+  opts.separator '  existing demos in the demos/ directory. Updates Gemfiles, runs bundle'
+  opts.separator '  install, optionally runs tests, and updates demo READMEs with new versions.'
+  opts.separator ''
+  opts.separator 'Example: bin/update-all-demos --react-on-rails-version "~> 16.1"'
   opts.separator ''
   opts.separator 'Options:'
 

docs/CONTRIBUTING_SETUP.md

@@ -127,13 +127,19 @@ bundle exec rubocop lib/demo_scripts/
 ### Adding a New Demo
 
 ```bash
-# Use the Ruby script
+# Create a basic demo
 bin/new-demo react_on_rails-demo-v16-my-feature
 
-# Or with options
-bin/scaffold-demo react_on_rails-demo-v16-my-feature --typescript --tailwind
+# Create an advanced demo with scaffolding
+bin/scaffold-demo react_on_rails-demo-v16-my-feature
+
+# See all available options
+bin/new-demo --help
+bin/scaffold-demo --help
 ```
 
+For detailed examples and all available commands, see the [main README](../README.md#create-a-new-demo).
+
 ## Troubleshooting
 
 ### Lefthook not working