Add comprehensive rockerc.yaml examples and documentation

[blooop]

Summary

• Adds 6 example rockerc.yaml files demonstrating common configurations
• Provides comprehensive documentation of YAML syntax and available options
• Documents how rocker CLI arguments translate to YAML configuration
• Includes configuration hierarchy, merge behavior, and troubleshooting guide

Changes

New Example Files

• examples/basic.yaml - Simple starter configuration
• examples/advanced.yaml - Feature-rich development setup
• examples/dockerfile.yaml - Using custom Dockerfile
• examples/global-config.yaml - System-wide defaults
• examples/vscode.yaml - VS Code optimized configuration
• examples/blacklist.yaml - Extension exclusion patterns

Documentation

• examples/README.md - Complete configuration reference with:
  • All configuration fields and their syntax
  • List of available rocker extensions
  • Configuration hierarchy and merge behavior
  • CLI integration patterns
  • Common development workflows
  • Quirks, limitations, and troubleshooting
• Updated main README.md with links to examples

Addresses

Closes #120

Test Plan

• Format and lint checks pass (pixi run format, pixi run ruff-lint)
• All example YAML files have valid syntax
• Documentation is comprehensive and accurate
• Examples demonstrate key use cases mentioned in the issue

🤖 Generated with Claude Code

Summary by Sourcery

Add example rockerc.yaml configurations and comprehensive configuration documentation, and link them from the main README.

New Features:

• Provide multiple example rockerc.yaml files covering basic usage, advanced setups, Dockerfile-based builds, global configuration, VS Code workflows, and extension blacklisting.

Enhancements:

• Add internal planning and spec documents describing the implementation plan and requirements for the new YAML examples.

Documentation:

• Add an examples/README.md guide documenting rockerc.yaml syntax, configuration fields, available extensions, configuration hierarchy, CLI integration, common patterns, quirks, and troubleshooting.
• Update the main README to point to the new examples directory and reference configurations.

[sourcery-ai]

Reviewer's Guide

Adds a new examples/ directory with multiple rockerc.yaml example configurations and an extensive configuration guide, and updates the main README to link to these resources; also includes internal spec/plan docs describing the examples work.

Sequence diagram for rockerc config loading and container startup

sequenceDiagram
  actor Developer
  participant Rockerc as rockerc
  participant ConfigLoader as ConfigLoader
  participant Rocker as rocker
  participant Docker as docker

  Developer ->> Rockerc: run rockerc with optional args
  Rockerc ->> ConfigLoader: load ~/.rockerc.yaml
  ConfigLoader -->> Rockerc: GlobalConfig
  Rockerc ->> ConfigLoader: load ./rockerc.yaml
  ConfigLoader -->> Rockerc: ProjectConfig
  Rockerc ->> Rockerc: merge args lists
  Rockerc ->> Rockerc: apply extension-blacklist
  Rockerc ->> Rockerc: apply CLI overrides and extra extensions
  Rockerc ->> Rocker: invoke rocker with merged config
  Rocker ->> Docker: create or reuse container
  Docker -->> Rocker: container id
  Rocker -->> Rockerc: container ready
  Rockerc -->> Developer: attached shell or VS Code session

Loading

File-Level Changes

Change	Details	Files
Add multiple documented rockerc.yaml example configurations for common workflows and features.	Introduce a basic example config showing minimal required fields and core extensions. Add an advanced development config demonstrating many extensions, custom volume mounts, and container naming. Provide a Dockerfile-based config showing how to build from a local Dockerfile instead of a pre-built image. Add a global configuration example illustrating how ~/.rockerc.yaml can define system-wide defaults. Add a VS Code-focused config tuned for rockerc --vsc / rockervsc devcontainer workflows. Add a blacklist example showing how extension-blacklist filters merged args from global and project configs.	examples/basic.yaml examples/advanced.yaml examples/dockerfile.yaml examples/global-config.yaml examples/vscode.yaml examples/blacklist.yaml
Introduce comprehensive configuration documentation for rockerc.yaml and reference it from the main README.	Create examples/README.md as a detailed rockerc.yaml configuration guide, covering syntax, fields, extension list, hierarchy/merge behavior, CLI integration, patterns, quirks, and troubleshooting. Update the root README.md with a "Configuration Examples" section linking to the example YAML files and the configuration guide, and summarizing what they demonstrate.	examples/README.md README.md
Document the implementation plan and spec for the YAML examples feature under specs/24.	Add an implementation plan describing the new examples directory, documentation updates, and example scenarios to cover. Add a short spec describing the goals and scope of the example rockerc.yaml files and docs, referencing issue Add example rockerc.yaml files #120.	specs/24/yaml-examples/plan.md specs/24/yaml-examples/spec.md

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#120	Provide example rockerc.yaml files demonstrating typical configurations and how rocker CLI arguments translate into YAML.	✅
#120	Document the YAML syntax, fields, and available configuration options for rockerc.yaml.	✅
#120	Describe any quirks, limitations, and configuration behaviors (e.g., config hierarchy and merging) relevant to rockerc.yaml usage.	✅

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've found 1 issue, and left some high level feedback:

• Consider removing or relocating specs/24/yaml-examples/plan.md from the main repo if it’s only an internal implementation note, as checked-in planning documents can easily become stale and confuse users browsing the tree.
• In examples/README.md, the list of extensions (e.g., claude, codex, gemini, homebrew) should match the actual supported rocker/rockerc extensions; if some are not real extensions, it would be clearer to either remove them or explicitly label them as hypothetical examples.
• There is some overlap between configuration explanations in the top-level README.md and examples/README.md; to reduce future drift, you might factor shared concepts into a single location and link to it from the other file.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- Consider removing or relocating `specs/24/yaml-examples/plan.md` from the main repo if it’s only an internal implementation note, as checked-in planning documents can easily become stale and confuse users browsing the tree.
- In `examples/README.md`, the list of extensions (e.g., `claude`, `codex`, `gemini`, `homebrew`) should match the actual supported rocker/rockerc extensions; if some are not real extensions, it would be clearer to either remove them or explicitly label them as hypothetical examples.
- There is some overlap between configuration explanations in the top-level `README.md` and `examples/README.md`; to reduce future drift, you might factor shared concepts into a single location and link to it from the other file.

## Individual Comments

### Comment 1
<location> `examples/blacklist.yaml:29` </location>
<code_context>
+  - cuda            # No CUDA support needed
+
+# How blacklist works:
+# 1. Global config (~/.rockerc.yaml) might have: [user, pull, git, x11, nvidia]
+# 2. Project config (this file) has args: [user, pull, git, cwd, pixi]
+# 3. Merged args before blacklist: [user, pull, git, x11, nvidia, cwd, pixi]
</code_context>

<issue_to_address>
**suggestion:** The example global args here use `nvidia`, but the dedicated global-config example later uses `cuda`, which may confuse users.

In this walkthrough, the global config uses `nvidia`, while `examples/global-config.yaml` uses `cuda` for GPU support. To avoid confusion for users copying from both, consider standardizing on one extension name or explicitly documenting the difference if both are valid.
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 63.04%. Comparing base (6ce2101) to head (26cf074).
⚠️ Report is 10 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #136      +/-   ##
==========================================
- Coverage   69.05%   63.04%   -6.02%     
==========================================
  Files           8        9       +1     
  Lines        1506     1840     +334     
==========================================
+ Hits         1040     1160     +120     
- Misses        466      680     +214     

see 2 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.