fix: make examples consistent and add tests

- Single examples now match full example patterns (no name:, cf- prefix, etc.)
- Add comprehensive tests for config example command (100% coverage on examples module)
- Add tests for examples module functions
- Fix VHS demo to only deploy traefik + whoami (avoid missing volume paths)

README.md

@@ -342,14 +342,18 @@ When you run `cf up autokuma`, it starts the stack on all hosts in parallel. Mul
 Compose Farm includes a `config` subcommand to help manage configuration files:
 
 ```bash
-cf config init      # Create a new config file with documented example
+cf config init              # Create a new config file with documented example
-cf config show      # Display current config with syntax highlighting
+cf config init --discover   # Auto-detect compose files and interactively create config
-cf config path      # Print the config file path (useful for scripting)
+cf config show              # Display current config with syntax highlighting
-cf config validate  # Validate config syntax and schema
+cf config path              # Print the config file path (useful for scripting)
-cf config edit      # Open config in $EDITOR
+cf config validate          # Validate config syntax and schema
+cf config edit              # Open config in $EDITOR
+cf config example --list    # List available example templates
+cf config example whoami    # Generate sample stack files
+cf config example full      # Generate complete Traefik + whoami setup
 ```
 
-Use `cf config init` to get started with a fully documented template.
+Use `cf config init` to get started with a template, or `cf config init --discover` if you already have compose files.
 
 ## Usage
 
@@ -995,6 +999,7 @@ Full `--help` output for each command. See the [Usage](#usage) table above for a
 │ validate   Validate the config file syntax and schema.                       │
 │ symlink    Create a symlink from the default config location to a config     │
 │            file.                                                             │
+│ example    Generate example stack files from built-in templates.             │
 ╰──────────────────────────────────────────────────────────────────────────────╯
 
 ```

docs/assets/config-example.gif

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:611d6fef767a8e0755367bf0c008dad016f38fa8b3be2362825ef7ef6ec2ec1a
+size 2444902

docs/assets/config-example.webm

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1e851879acc99234628abce0f8dadeeaf500effe4f78bebc63c4b17a0ae092f1
+size 900800

docs/commands.md

@@ -578,6 +578,10 @@ cf traefik-file plex jellyfin -o /opt/traefik/cf.yml
 
 Manage configuration files.
 
+<video autoplay loop muted playsinline>
+  <source src="/assets/config-example.webm" type="video/webm">
+</video>
+
 ```bash
 cf config COMMAND
 ```
@@ -592,17 +596,19 @@ cf config COMMAND
 | `validate` | Validate syntax and schema |
 | `edit` | Open in $EDITOR |
 | `symlink` | Create symlink from default location |
+| `example` | Generate example stack files |
 
 **Options by subcommand:**
 
 | Subcommand | Options |
 |------------|---------|
-| `init` | `--path/-p PATH`, `--force/-f` |
+| `init` | `--path/-p PATH`, `--force/-f`, `--discover/-d` |
 | `show` | `--path/-p PATH`, `--raw/-r` |
 | `edit` | `--path/-p PATH` |
 | `path` | `--path/-p PATH` |
 | `validate` | `--path/-p PATH` |
 | `symlink` | `--force/-f` |
+| `example` | `--list/-l`, `--output/-o PATH`, `--force/-f` |
 
 **Examples:**
 
@@ -610,6 +616,9 @@ cf config COMMAND
 # Create config at default location
 cf config init
 
+# Auto-discover compose files and interactively create config
+cf config init --discover
+
 # Create config at custom path
 cf config init --path /opt/compose-farm/config.yaml
 
@@ -633,6 +642,18 @@ cf config symlink
 
 # Create symlink to specific file
 cf config symlink /opt/compose-farm/config.yaml
+
+# List available example templates
+cf config example --list
+
+# Generate a sample stack (whoami, nginx, postgres)
+cf config example whoami
+
+# Generate complete Traefik + whoami setup
+cf config example full
+
+# Generate example in specific directory
+cf config example nginx --output /opt/compose
 ```
 
 ---

docs/demos/cli/README.md

@@ -27,6 +27,7 @@ python docs/demos/cli/record.py quickstart migration
 | `update.tape` | `cf update` |
 | `migration.tape` | Service migration |
 | `apply.tape` | `cf apply` |
+| `config-example.tape` | `cf config example` - generate example stacks |
 
 ## Output
 

docs/demos/cli/config-example.tape

@@ -0,0 +1,110 @@
+# Config Example Demo
+# Shows cf config example command
+
+Output docs/assets/config-example.gif
+Output docs/assets/config-example.webm
+
+Set Shell "bash"
+Set FontSize 14
+Set Width 900
+Set Height 600
+Set Theme "Catppuccin Mocha"
+Set FontFamily "FiraCode Nerd Font"
+Set TypingSpeed 50ms
+Env BAT_PAGING "always"
+
+Type "# Generate example stacks with cf config example"
+Enter
+Sleep 500ms
+
+Type "# List available templates"
+Enter
+Sleep 500ms
+
+Type "cf config example --list"
+Enter
+Wait+Screen /Usage:/
+Sleep 2s
+
+Type "# Create a directory for our stacks"
+Enter
+Sleep 500ms
+
+Type "mkdir -p ~/compose && cd ~/compose"
+Enter
+Wait
+Sleep 500ms
+
+Type "# Generate the full Traefik + whoami setup"
+Enter
+Sleep 500ms
+
+Type "cf config example full"
+Enter
+Wait
+Sleep 2s
+
+Type "# See what was created"
+Enter
+Sleep 500ms
+
+Type "tree ."
+Enter
+Wait
+Sleep 2s
+
+Type "# View the generated config"
+Enter
+Sleep 500ms
+
+Type "bat compose-farm.yaml"
+Enter
+Sleep 3s
+Type "q"
+Sleep 500ms
+
+Type "# View the traefik compose file"
+Enter
+Sleep 500ms
+
+Type "bat traefik/compose.yaml"
+Enter
+Sleep 3s
+Type "q"
+Sleep 500ms
+
+Type "# Validate the config"
+Enter
+Sleep 500ms
+
+Type "cf check --local"
+Enter
+Wait
+Sleep 2s
+
+Type "# Create the Docker network"
+Enter
+Sleep 500ms
+
+Type "cf init-network"
+Enter
+Wait
+Sleep 1s
+
+Type "# Deploy traefik and whoami"
+Enter
+Sleep 500ms
+
+Type "cf up traefik whoami"
+Enter
+Wait
+Sleep 3s
+
+Type "# Verify it's running"
+Enter
+Sleep 500ms
+
+Type "cf ps"
+Enter
+Wait
+Sleep 2s

docs/getting-started.md

@@ -149,6 +149,24 @@ cd /opt/stacks
 cf config init
 ```
 
+**Already have compose files?** Use `--discover` to auto-detect them and interactively build your config:
+
+```bash
+cf config init --discover
+```
+
+This scans for directories containing compose files, lets you select which stacks to include, and generates a ready-to-use config.
+
+**Starting fresh?** Generate example stacks to learn from:
+
+```bash
+# List available examples
+cf config example --list
+
+# Generate a complete Traefik + whoami setup
+cf config example full
+```
+
 Alternatively, use `~/.config/compose-farm/compose-farm.yaml` for a global config. You can also symlink a working directory config to the global location:
 
 ```bash

src/compose_farm/cli/config.py

@@ -37,6 +37,12 @@ _RawOption = Annotated[
     bool,
     typer.Option("--raw", "-r", help="Output raw file contents (for copy-paste)."),
 ]
+_DiscoverOption = Annotated[
+    bool,
+    typer.Option(
+        "--discover", "-d", help="Auto-detect compose files and interactively select stacks."
+    ),
+]
 
 
 def _get_editor() -> str:
@@ -68,6 +74,117 @@ def _get_config_file(path: Path | None) -> Path | None:
     return config_path.resolve() if config_path else None
 
 
+def _generate_discovered_config(
+    compose_dir: Path,
+    hostname: str,
+    host_address: str,
+    selected_stacks: list[str],
+) -> str:
+    """Generate config YAML from discovered stacks."""
+    import yaml  # noqa: PLC0415
+
+    config_data = {
+        "compose_dir": str(compose_dir),
+        "hosts": {hostname: host_address},
+        "stacks": dict.fromkeys(selected_stacks, hostname),
+    }
+
+    header = """\
+# Compose Farm configuration
+# Documentation: https://github.com/basnijholt/compose-farm
+#
+# Generated by: cf config init --discover
+
+"""
+    return header + yaml.dump(config_data, default_flow_style=False, sort_keys=False)
+
+
+def _interactive_stack_selection(stacks: list[str]) -> list[str]:
+    """Interactively select stacks to include."""
+    from rich.prompt import Confirm, Prompt  # noqa: PLC0415
+
+    console.print("\n[bold]Found stacks:[/bold]")
+    for stack in stacks:
+        console.print(f"  [cyan]{stack}[/cyan]")
+
+    console.print()
+
+    # Fast path: include all
+    if Confirm.ask(f"Include all {len(stacks)} stacks?", default=True):
+        return stacks
+
+    # Let user specify which to exclude
+    console.print(
+        "\n[dim]Enter stack names to exclude (comma-separated), or press Enter to select individually:[/dim]"
+    )
+    exclude_input = Prompt.ask("Exclude", default="")
+
+    if exclude_input.strip():
+        exclude = {s.strip() for s in exclude_input.split(",")}
+        return [s for s in stacks if s not in exclude]
+
+    # Fall back to individual selection
+    console.print()
+    return [
+        stack for stack in stacks if Confirm.ask(f"  Include [cyan]{stack}[/cyan]?", default=True)
+    ]
+
+
+def _run_discovery_flow() -> str | None:
+    """Run the interactive discovery flow and return generated config content."""
+    import socket  # noqa: PLC0415
+
+    from rich.prompt import Prompt  # noqa: PLC0415
+
+    console.print("[bold]Compose Farm Config Discovery[/bold]")
+    console.print("[dim]This will scan for compose files and generate a config.[/dim]\n")
+
+    # Step 1: Get compose directory
+    default_dir = Path.cwd()
+    compose_dir_str = Prompt.ask(
+        "Compose directory",
+        default=str(default_dir),
+    )
+    compose_dir = Path(compose_dir_str).expanduser().resolve()
+
+    if not compose_dir.exists():
+        print_error(f"Directory does not exist: {compose_dir}")
+        return None
+
+    if not compose_dir.is_dir():
+        print_error(f"Path is not a directory: {compose_dir}")
+        return None
+
+    # Step 2: Discover stacks
+    from compose_farm.config import discover_compose_dirs  # noqa: PLC0415
+
+    console.print(f"\n[dim]Scanning {compose_dir}...[/dim]")
+    stacks = discover_compose_dirs(compose_dir)
+
+    if not stacks:
+        print_error(f"No compose files found in {compose_dir}")
+        console.print("[dim]Each stack should be in a subdirectory with a compose.yaml file.[/dim]")
+        return None
+
+    console.print(f"[green]Found {len(stacks)} stack(s)[/green]")
+
+    # Step 3: Interactive selection
+    selected_stacks = _interactive_stack_selection(stacks)
+
+    if not selected_stacks:
+        console.print("\n[yellow]No stacks selected.[/yellow]")
+        return None
+
+    # Step 4: Get hostname and address
+    default_hostname = socket.gethostname()
+    hostname = Prompt.ask("\nHost name", default=default_hostname)
+    host_address = Prompt.ask("Host address", default="localhost")
+
+    # Step 5: Generate config
+    console.print(f"\n[dim]Generating config with {len(selected_stacks)} stack(s)...[/dim]")
+    return _generate_discovered_config(compose_dir, hostname, host_address, selected_stacks)
+
+
 def _report_missing_config(explicit_path: Path | None = None) -> None:
     """Report that a config file was not found."""
     console.print("[yellow]Config file not found.[/yellow]")
@@ -85,11 +202,15 @@ def _report_missing_config(explicit_path: Path | None = None) -> None:
 def config_init(
     path: _PathOption = None,
     force: _ForceOption = False,
+    discover: _DiscoverOption = False,
 ) -> None:
     """Create a new config file with documented example.
 
     The generated config file serves as a template showing all available
     options with explanatory comments.
+
+    Use --discover to auto-detect compose files and interactively select
+    which stacks to include.
     """
     target_path = (path.expanduser().resolve() if path else None) or default_config_path()
 
@@ -101,11 +222,17 @@ def config_init(
             console.print("[dim]Aborted.[/dim]")
             raise typer.Exit(0)
 
+    if discover:
+        template_content = _run_discovery_flow()
+        if template_content is None:
+            raise typer.Exit(0)
+    else:
+        template_content = _generate_template()
+
     # Create parent directories
     target_path.parent.mkdir(parents=True, exist_ok=True)
 
-    # Generate and write template
+    # Write config file
-    template_content = _generate_template()
     target_path.write_text(template_content, encoding="utf-8")
 
     print_success(f"Config file created at: {target_path}")
@@ -293,5 +420,115 @@ def config_symlink(
     console.print(f"    -> {target_path}")
 
 
+_ListOption = Annotated[
+    bool,
+    typer.Option("--list", "-l", help="List available example templates."),
+]
+
+
+@config_app.command("example")
+def config_example(
+    name: Annotated[
+        str | None,
+        typer.Argument(help="Example template name (e.g., whoami, full)"),
+    ] = None,
+    output_dir: Annotated[
+        Path | None,
+        typer.Option("--output", "-o", help="Output directory. Defaults to current directory."),
+    ] = None,
+    list_examples: _ListOption = False,
+    force: _ForceOption = False,
+) -> None:
+    """Generate example stack files from built-in templates.
+
+    Examples:
+        cf config example --list           # List available examples
+        cf config example whoami           # Generate whoami stack in ./whoami/
+        cf config example full             # Generate complete Traefik + whoami setup
+        cf config example nginx -o /opt/compose  # Generate in specific directory
+
+    """
+    from compose_farm.examples import (  # noqa: PLC0415
+        EXAMPLES,
+        SINGLE_STACK_EXAMPLES,
+        list_example_files,
+    )
+
+    # List mode
+    if list_examples:
+        console.print("[bold]Available example templates:[/bold]\n")
+        console.print("[dim]Single stack examples:[/dim]")
+        for example_name, description in SINGLE_STACK_EXAMPLES.items():
+            console.print(f"  [cyan]{example_name}[/cyan] - {description}")
+        console.print()
+        console.print("[dim]Complete setup:[/dim]")
+        console.print(f"  [cyan]full[/cyan] - {EXAMPLES['full']}")
+        console.print()
+        console.print("[dim]Usage: cf config example <name>[/dim]")
+        return
+
+    # Interactive selection if no name provided
+    if name is None:
+        from rich.prompt import Prompt  # noqa: PLC0415
+
+        console.print("[bold]Available example templates:[/bold]\n")
+        example_names = list(EXAMPLES.keys())
+        for i, (example_name, description) in enumerate(EXAMPLES.items(), 1):
+            console.print(f"  [{i}] [cyan]{example_name}[/cyan] - {description}")
+
+        console.print()
+        choice = Prompt.ask(
+            "Select example",
+            choices=[str(i) for i in range(1, len(example_names) + 1)] + example_names,
+            default="1",
+        )
+
+        # Handle numeric or name input
+        name = example_names[int(choice) - 1] if choice.isdigit() else choice
+
+    # Validate example name
+    if name not in EXAMPLES:
+        print_error(f"Unknown example: {name}")
+        console.print(f"Available examples: {', '.join(EXAMPLES.keys())}")
+        raise typer.Exit(1)
+
+    # Determine output directory
+    base_dir = (output_dir or Path.cwd()).expanduser().resolve()
+    # For 'full' example, use current dir; for single stacks, create subdir
+    target_dir = base_dir if name == "full" else base_dir / name
+
+    # Check for existing files
+    files = list_example_files(name)
+    existing_files = [f for f, _ in files if (target_dir / f).exists()]
+    if existing_files and not force:
+        console.print(f"[yellow]Files already exist in:[/yellow] {target_dir}")
+        console.print(f"[dim]  {len(existing_files)} file(s) would be overwritten[/dim]")
+        if not typer.confirm("Overwrite existing files?"):
+            console.print("[dim]Aborted.[/dim]")
+            raise typer.Exit(0)
+
+    # Create directories and copy files
+    for rel_path, content in files:
+        file_path = target_dir / rel_path
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+        file_path.write_text(content, encoding="utf-8")
+        console.print(f"  [green]Created[/green] {file_path}")
+
+    print_success(f"Example '{name}' created at: {target_dir}")
+
+    # Show appropriate next steps
+    if name == "full":
+        console.print("\n[dim]Next steps:[/dim]")
+        console.print(f"  1. Edit [cyan]{target_dir}/compose-farm.yaml[/cyan] with your host IP")
+        console.print("  2. Edit [cyan].env[/cyan] files with your domain")
+        console.print("  3. Create Docker network: [cyan]docker network create mynetwork[/cyan]")
+        console.print("  4. Deploy: [cyan]cf up traefik whoami[/cyan]")
+    else:
+        console.print("\n[dim]Next steps:[/dim]")
+        console.print(f"  1. Edit [cyan]{target_dir}/.env[/cyan] with your settings")
+        console.print(f"  2. Add to compose-farm.yaml: [cyan]{name}: <hostname>[/cyan]")
+        console.print(f"  3. Deploy with: [cyan]cf up {name}[/cyan]")
+
+
 # Register config subcommand on the shared app
 app.add_typer(config_app, name="config", rich_help_panel="Configuration")

src/compose_farm/config.py

@@ -15,6 +15,17 @@ from .paths import config_search_paths, find_config_path
 COMPOSE_FILENAMES = ("compose.yaml", "compose.yml", "docker-compose.yml", "docker-compose.yaml")
 
 
+def discover_compose_dirs(compose_dir: Path) -> list[str]:
+    """Find all directories in compose_dir that contain a compose file."""
+    if not compose_dir.exists():
+        return []
+    return sorted(
+        subdir.name
+        for subdir in compose_dir.iterdir()
+        if subdir.is_dir() and any((subdir / f).exists() for f in COMPOSE_FILENAMES)
+    )
+
+
 class Host(BaseModel, extra="forbid"):
     """SSH host configuration."""
 
@@ -105,13 +116,7 @@ class Config(BaseModel, extra="forbid"):
 
     def discover_compose_dirs(self) -> set[str]:
         """Find all directories in compose_dir that contain a compose file."""
-        found: set[str] = set()
+        return set(discover_compose_dirs(self.compose_dir))
-        if not self.compose_dir.exists():
-            return found
-        for subdir in self.compose_dir.iterdir():
-            if subdir.is_dir() and any((subdir / f).exists() for f in COMPOSE_FILENAMES):
-                found.add(subdir.name)
-        return found
 
 
 def _parse_hosts(raw_hosts: dict[str, Any]) -> dict[str, Host]:

src/compose_farm/examples/__init__.py

@@ -0,0 +1,41 @@
+"""Example stack templates for compose-farm."""
+
+from __future__ import annotations
+
+from importlib import resources
+from pathlib import Path
+
+# All available examples: name -> description
+# "full" is special: multi-stack setup with config file
+EXAMPLES = {
+    "whoami": "Simple HTTP service that returns hostname (great for testing Traefik)",
+    "nginx": "Basic nginx web server with static files",
+    "postgres": "PostgreSQL database with persistent volume",
+    "full": "Complete setup with Traefik + whoami (includes compose-farm.yaml)",
+}
+
+# Examples that are single stacks (everything except "full")
+SINGLE_STACK_EXAMPLES = {k: v for k, v in EXAMPLES.items() if k != "full"}
+
+
+def list_example_files(name: str) -> list[tuple[str, str]]:
+    """List files in an example template, returning (relative_path, content) tuples."""
+    if name not in EXAMPLES:
+        msg = f"Unknown example: {name}. Available: {', '.join(EXAMPLES.keys())}"
+        raise ValueError(msg)
+
+    example_dir = resources.files("compose_farm.examples") / name
+    example_path = Path(str(example_dir))
+    files: list[tuple[str, str]] = []
+
+    def walk_dir(directory: Path, prefix: str = "") -> None:
+        for item in sorted(directory.iterdir()):
+            rel_path = f"{prefix}{item.name}" if prefix else item.name
+            if item.is_file():
+                content = item.read_text(encoding="utf-8")
+                files.append((rel_path, content))
+            elif item.is_dir() and not item.name.startswith("__"):
+                walk_dir(item, f"{rel_path}/")
+
+    walk_dir(example_path)
+    return files

src/compose_farm/examples/full/README.md

@@ -0,0 +1,41 @@
+# Compose Farm Full Example
+
+A complete starter setup with Traefik reverse proxy and a test service.
+
+## Quick Start
+
+1. **Create the Docker network** (once per host):
+   ```bash
+   docker network create --subnet=172.20.0.0/16 --gateway=172.20.0.1 mynetwork
+   ```
+
+2. **Create data directory for Traefik**:
+   ```bash
+   mkdir -p /mnt/data/traefik
+   ```
+
+3. **Edit configuration**:
+   - Update `compose-farm.yaml` with your host IP
+   - Update `.env` files with your domain
+
+4. **Start the stacks**:
+   ```bash
+   cf up traefik whoami
+   ```
+
+5. **Test**:
+   - Dashboard: http://localhost:8080
+   - Whoami: Add `whoami.example.com` to /etc/hosts pointing to your host
+
+## Files
+
+```
+full/
+├── compose-farm.yaml    # Compose Farm config
+├── traefik/
+│   ├── compose.yaml     # Traefik reverse proxy
+│   └── .env
+└── whoami/
+    ├── compose.yaml     # Test HTTP service
+    └── .env
+```

src/compose_farm/examples/full/compose-farm.yaml

@@ -0,0 +1,17 @@
+# Compose Farm configuration
+# Edit the host address to match your setup
+
+compose_dir: .
+
+hosts:
+  local: localhost  # For remote hosts, use: myhost: 192.168.1.100
+
+stacks:
+  traefik: local
+  whoami: local
+  nginx: local
+  postgres: local
+
+# Traefik file-provider integration (optional)
+# traefik_file: ./traefik/dynamic.d/compose-farm.yml
+traefik_stack: traefik

src/compose_farm/examples/full/nginx/.env

@@ -0,0 +1,2 @@
+# Environment variables for nginx stack
+DOMAIN=example.com

src/compose_farm/examples/full/nginx/compose.yaml

@@ -0,0 +1,26 @@
+# Nginx - Basic web server
+services:
+  nginx:
+    image: nginx:alpine
+    container_name: cf-nginx
+    user: "1000:1000"
+    networks:
+      - mynetwork
+    volumes:
+      - /mnt/data/nginx/html:/usr/share/nginx/html:ro
+    ports:
+      - "9082:80"  # Use 80:80 or 8080:80 in production
+    restart: unless-stopped
+    labels:
+      - traefik.enable=true
+      - traefik.http.routers.nginx.rule=Host(`nginx.${DOMAIN}`)
+      - traefik.http.routers.nginx.entrypoints=websecure
+      - traefik.http.routers.nginx-local.rule=Host(`nginx.local`)
+      - traefik.http.routers.nginx-local.entrypoints=web
+      - traefik.http.services.nginx.loadbalancer.server.port=80
+      - kuma.nginx.http.name=Nginx
+      - kuma.nginx.http.url=https://nginx.${DOMAIN}
+
+networks:
+  mynetwork:
+    external: true

src/compose_farm/examples/full/postgres/.env

@@ -0,0 +1,5 @@
+# Environment variables for postgres stack
+# IMPORTANT: Change these values before deploying!
+POSTGRES_USER=postgres
+POSTGRES_PASSWORD=changeme
+POSTGRES_DB=myapp

src/compose_farm/examples/full/postgres/compose.yaml

@@ -0,0 +1,26 @@
+# PostgreSQL - Database with persistent storage
+services:
+  postgres:
+    image: postgres:16-alpine
+    container_name: cf-postgres
+    networks:
+      - mynetwork
+    environment:
+      - POSTGRES_USER=${POSTGRES_USER:-postgres}
+      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is required}
+      - POSTGRES_DB=${POSTGRES_DB:-postgres}
+      - PGDATA=/var/lib/postgresql/data/pgdata
+    volumes:
+      - /mnt/data/postgres:/var/lib/postgresql/data
+    ports:
+      - "5433:5432"  # Use 5432:5432 in production
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-postgres}"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+
+networks:
+  mynetwork:
+    external: true

src/compose_farm/examples/full/traefik/.env

@@ -0,0 +1 @@
+DOMAIN=example.com

src/compose_farm/examples/full/traefik/compose.yaml

@@ -0,0 +1,37 @@
+# Traefik - Reverse proxy and load balancer
+services:
+  traefik:
+    image: traefik:v2.11
+    container_name: cf-traefik
+    networks:
+      - mynetwork
+    ports:
+      - "9080:80"    # HTTP (use 80:80 in production)
+      - "9443:443"   # HTTPS (use 443:443 in production)
+      - "9081:8080"  # Dashboard - remove in production
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+      - /mnt/data/traefik:/etc/traefik
+    command:
+      - --api.dashboard=true
+      - --api.insecure=true
+      - --providers.docker=true
+      - --providers.docker.exposedbydefault=false
+      - --providers.docker.network=mynetwork
+      - --entrypoints.web.address=:80
+      - --entrypoints.websecure.address=:443
+      - --log.level=INFO
+    labels:
+      - traefik.enable=true
+      - traefik.http.routers.traefik.rule=Host(`traefik.${DOMAIN}`)
+      - traefik.http.routers.traefik.entrypoints=websecure
+      - traefik.http.routers.traefik-local.rule=Host(`traefik.local`)
+      - traefik.http.routers.traefik-local.entrypoints=web
+      - traefik.http.services.traefik.loadbalancer.server.port=8080
+      - kuma.traefik.http.name=Traefik
+      - kuma.traefik.http.url=https://traefik.${DOMAIN}
+    restart: unless-stopped
+
+networks:
+  mynetwork:
+    external: true

src/compose_farm/examples/full/whoami/.env

@@ -0,0 +1 @@
+DOMAIN=example.com

src/compose_farm/examples/full/whoami/compose.yaml

@@ -0,0 +1,23 @@
+# Whoami - Test service for Traefik routing
+services:
+  whoami:
+    image: traefik/whoami:latest
+    container_name: cf-whoami
+    networks:
+      - mynetwork
+    ports:
+      - "9000:80"
+    restart: unless-stopped
+    labels:
+      - traefik.enable=true
+      - traefik.http.routers.whoami.rule=Host(`whoami.${DOMAIN}`)
+      - traefik.http.routers.whoami.entrypoints=websecure
+      - traefik.http.routers.whoami-local.rule=Host(`whoami.local`)
+      - traefik.http.routers.whoami-local.entrypoints=web
+      - traefik.http.services.whoami.loadbalancer.server.port=80
+      - kuma.whoami.http.name=Whoami
+      - kuma.whoami.http.url=https://whoami.${DOMAIN}
+
+networks:
+  mynetwork:
+    external: true

src/compose_farm/examples/nginx/.env

@@ -0,0 +1,2 @@
+# Environment variables for nginx stack
+DOMAIN=example.com

src/compose_farm/examples/nginx/compose.yaml

@@ -0,0 +1,26 @@
+# Nginx - Basic web server
+services:
+  nginx:
+    image: nginx:alpine
+    container_name: cf-nginx
+    user: "1000:1000"
+    networks:
+      - mynetwork
+    volumes:
+      - /mnt/data/nginx/html:/usr/share/nginx/html:ro
+    ports:
+      - "9082:80"
+    restart: unless-stopped
+    labels:
+      - traefik.enable=true
+      - traefik.http.routers.nginx.rule=Host(`nginx.${DOMAIN}`)
+      - traefik.http.routers.nginx.entrypoints=websecure
+      - traefik.http.routers.nginx-local.rule=Host(`nginx.local`)
+      - traefik.http.routers.nginx-local.entrypoints=web
+      - traefik.http.services.nginx.loadbalancer.server.port=80
+      - kuma.nginx.http.name=Nginx
+      - kuma.nginx.http.url=https://nginx.${DOMAIN}
+
+networks:
+  mynetwork:
+    external: true

src/compose_farm/examples/postgres/.env

@@ -0,0 +1,5 @@
+# Environment variables for postgres stack
+# IMPORTANT: Change these values before deploying!
+POSTGRES_USER=postgres
+POSTGRES_PASSWORD=changeme
+POSTGRES_DB=myapp

src/compose_farm/examples/postgres/compose.yaml

@@ -0,0 +1,26 @@
+# PostgreSQL - Database with persistent storage
+services:
+  postgres:
+    image: postgres:16-alpine
+    container_name: cf-postgres
+    networks:
+      - mynetwork
+    environment:
+      - POSTGRES_USER=${POSTGRES_USER:-postgres}
+      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is required}
+      - POSTGRES_DB=${POSTGRES_DB:-postgres}
+      - PGDATA=/var/lib/postgresql/data/pgdata
+    volumes:
+      - /mnt/data/postgres:/var/lib/postgresql/data
+    ports:
+      - "5433:5432"
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-postgres}"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+
+networks:
+  mynetwork:
+    external: true

src/compose_farm/examples/whoami/.env

@@ -0,0 +1,2 @@
+# Environment variables for whoami stack
+DOMAIN=example.com

src/compose_farm/examples/whoami/compose.yaml

@@ -0,0 +1,24 @@
+# Whoami - Simple HTTP service for testing
+# Returns the container hostname - useful for testing load balancers and Traefik
+services:
+  whoami:
+    image: traefik/whoami:latest
+    container_name: cf-whoami
+    networks:
+      - mynetwork
+    ports:
+      - "9000:80"
+    restart: unless-stopped
+    labels:
+      - traefik.enable=true
+      - traefik.http.routers.whoami.rule=Host(`whoami.${DOMAIN}`)
+      - traefik.http.routers.whoami.entrypoints=websecure
+      - traefik.http.routers.whoami-local.rule=Host(`whoami.local`)
+      - traefik.http.routers.whoami-local.entrypoints=web
+      - traefik.http.services.whoami.loadbalancer.server.port=80
+      - kuma.whoami.http.name=Whoami
+      - kuma.whoami.http.url=https://whoami.${DOMAIN}
+
+networks:
+  mynetwork:
+    external: true

tests/test_config_cmd.py

@@ -228,3 +228,99 @@ class TestConfigValidate:
         # Error goes to stderr
         output = result.stdout + (result.stderr or "")
         assert "Config file not found" in output or "not found" in output.lower()
+
+
+class TestConfigExample:
+    """Tests for cf config example command."""
+
+    def test_example_list(self, runner: CliRunner) -> None:
+        result = runner.invoke(app, ["config", "example", "--list"])
+        assert result.exit_code == 0
+        assert "whoami" in result.stdout
+        assert "nginx" in result.stdout
+        assert "postgres" in result.stdout
+        assert "full" in result.stdout
+
+    def test_example_whoami(self, runner: CliRunner, tmp_path: Path) -> None:
+        result = runner.invoke(app, ["config", "example", "whoami", "-o", str(tmp_path)])
+        assert result.exit_code == 0
+        assert "Example 'whoami' created" in result.stdout
+        assert (tmp_path / "whoami" / "compose.yaml").exists()
+        assert (tmp_path / "whoami" / ".env").exists()
+
+    def test_example_full(self, runner: CliRunner, tmp_path: Path) -> None:
+        result = runner.invoke(app, ["config", "example", "full", "-o", str(tmp_path)])
+        assert result.exit_code == 0
+        assert "Example 'full' created" in result.stdout
+        assert (tmp_path / "compose-farm.yaml").exists()
+        assert (tmp_path / "traefik" / "compose.yaml").exists()
+        assert (tmp_path / "whoami" / "compose.yaml").exists()
+        assert (tmp_path / "nginx" / "compose.yaml").exists()
+        assert (tmp_path / "postgres" / "compose.yaml").exists()
+
+    def test_example_unknown(self, runner: CliRunner, tmp_path: Path) -> None:
+        result = runner.invoke(app, ["config", "example", "unknown", "-o", str(tmp_path)])
+        assert result.exit_code == 1
+        output = result.stdout + (result.stderr or "")
+        assert "Unknown example" in output
+
+    def test_example_force_overwrites(self, runner: CliRunner, tmp_path: Path) -> None:
+        # Create first time
+        runner.invoke(app, ["config", "example", "whoami", "-o", str(tmp_path)])
+        # Overwrite with force
+        result = runner.invoke(app, ["config", "example", "whoami", "-o", str(tmp_path), "-f"])
+        assert result.exit_code == 0
+
+    def test_example_prompts_on_existing(self, runner: CliRunner, tmp_path: Path) -> None:
+        # Create first time
+        runner.invoke(app, ["config", "example", "whoami", "-o", str(tmp_path)])
+        # Try again without force, decline
+        result = runner.invoke(
+            app, ["config", "example", "whoami", "-o", str(tmp_path)], input="n\n"
+        )
+        assert result.exit_code == 0
+        assert "Aborted" in result.stdout
+
+
+class TestExamplesModule:
+    """Tests for the examples module."""
+
+    def test_list_example_files_whoami(self) -> None:
+        from compose_farm.examples import list_example_files
+
+        files = list_example_files("whoami")
+        file_names = [f for f, _ in files]
+        assert ".env" in file_names
+        assert "compose.yaml" in file_names
+
+    def test_list_example_files_full(self) -> None:
+        from compose_farm.examples import list_example_files
+
+        files = list_example_files("full")
+        file_names = [f for f, _ in files]
+        assert "compose-farm.yaml" in file_names
+        assert "traefik/compose.yaml" in file_names
+        assert "whoami/compose.yaml" in file_names
+
+    def test_list_example_files_unknown(self) -> None:
+        from compose_farm.examples import list_example_files
+
+        with pytest.raises(ValueError, match="Unknown example"):
+            list_example_files("unknown")
+
+    def test_examples_dict(self) -> None:
+        from compose_farm.examples import EXAMPLES, SINGLE_STACK_EXAMPLES
+
+        assert "whoami" in EXAMPLES
+        assert "full" in EXAMPLES
+        assert "full" not in SINGLE_STACK_EXAMPLES
+        assert "whoami" in SINGLE_STACK_EXAMPLES
+
+
+class TestConfigInitDiscover:
+    """Tests for cf config init --discover."""
+
+    def test_discover_option_exists(self, runner: CliRunner) -> None:
+        result = runner.invoke(app, ["config", "init", "--help"])
+        assert "--discover" in result.stdout
+        assert "-d" in result.stdout