add README.md to each example directory with usage instructions

4 files changed, 105 insertions, 0 deletions

diff --git a/examples/cli/README.md b/examples/cli/README.md
new file mode 100644
index 0000000..d393a9c
--- /dev/null
+++ b/examples/cli/README.md
@@ -0,0 +1,26 @@
+# Example: Via CLI
+
+Uses RCM through the `rcm` command-line tool.
+
+## Usage
+
+```sh
+# Dry run — show what would change, make no changes
+rcm config.rb --dry
+
+# Verbose output
+rcm config.rb --debug
+
+# Limit execution to specific hosts
+rcm config.rb --hosts earth,mars
+
+# Apply configuration
+rcm config.rb
+```
+
+## What it does
+
+- Creates `/tmp/example/hello.txt` with static content (parent directory created automatically)
+- Creates `/tmp/example/info.txt` from an inline ERB template containing the hostname and current date
+
+Both operations only run when the current hostname is `earth`.
diff --git a/examples/gem/README.md b/examples/gem/README.md
new file mode 100644
index 0000000..c05b844
--- /dev/null
+++ b/examples/gem/README.md
@@ -0,0 +1,28 @@
+# Example: As a Gem
+
+Uses RCM as a Bundler-managed gem inside a Rake project.
+
+## Setup
+
+```sh
+bundle install
+```
+
+## Usage
+
+```sh
+# Dry run — show what would change, make no changes
+bundle exec rake setup -- --dry
+
+# Verbose output
+bundle exec rake setup -- --debug
+
+# Apply configuration
+bundle exec rake setup
+```
+
+## What it does
+
+- Creates `/tmp/example/wg0.conf` from an inline ERB template
+
+The task only runs when the current hostname is `earth`.
diff --git a/examples/plain_ruby/README.md b/examples/plain_ruby/README.md
new file mode 100644
index 0000000..7208317
--- /dev/null
+++ b/examples/plain_ruby/README.md
@@ -0,0 +1,22 @@
+# Example: Plain Ruby Script
+
+Uses RCM directly from a Ruby script — no Rake, no Bundler required.
+
+## Usage
+
+```sh
+# Dry run — show what would change, make no changes
+ruby config.rb --dry
+
+# Verbose output
+ruby config.rb --debug
+
+# Apply configuration
+ruby config.rb
+```
+
+## What it does
+
+- Creates `/tmp/example/hello.txt` with static content (parent directory created automatically)
+- Ensures the line `127.0.0.1 localhost` is present in `/tmp/example/hosts.txt`
+- Creates `/tmp/example/greeting.txt` from an inline ERB template
diff --git a/examples/rake/README.md b/examples/rake/README.md
new file mode 100644
index 0000000..93a83ec
--- /dev/null
+++ b/examples/rake/README.md
@@ -0,0 +1,29 @@
+# Example: With Rake
+
+Uses RCM from a Rake task with a `config.toml` for host group definitions.
+
+## Setup
+
+```sh
+bundle install
+```
+
+## Usage
+
+```sh
+# Dry run — show what would change, make no changes
+rake setup -- --dry
+
+# Verbose output
+rake setup -- --debug
+
+# Apply configuration
+rake setup
+```
+
+## What it does
+
+- Creates `/tmp/example/wg/wg0.conf` from an inline ERB template (parent directory created automatically)
+- Ensures the line `192.168.1.101 earth.local` is present in `/tmp/example/hosts.txt`
+
+Both operations only run when the current hostname is `earth`.