docs: add Podman usage documentation (closes #24)

[gerchowl]

🚀 YOLO Mode Implementation

This PR was autonomously generated to resolve issue #24.

Description

Added comprehensive documentation for using the devcontainer with Podman in three different ways, providing users with flexibility to choose the workflow that best fits their needs without requiring VS Code's built-in devcontainer support.

See detailed plan: .cursor/plans/issue-24.md

Implementation Approach

Created a new README section "Using Podman Without VS Code Devcontainer" that documents three distinct approaches:

1. Direct Podman CLI - Maximum control and minimal dependencies
2. Podman Compose - Declarative configuration with familiar syntax
3. Dev Container CLI - Full devcontainer.json compatibility

Additionally created podman-compose.yml for Option 2 support.

Rationale:

• Provides flexibility for different user workflows and preferences
• Maintains consistency with existing documentation structure
• Includes all necessary technical details (SELinux, script execution order)
• Creates reusable compose file for declarative approach
• Follows existing documentation patterns and Keep a Changelog format

Changes

Core Implementation

• podman-compose.yml - Added declarative Podman Compose configuration

  • Volume mount with cached consistency
  • Working directory set to /workspace
  • Interactive terminal support
  • Matches devcontainer.json settings

• README.md - Added comprehensive "Using Podman Without VS Code Devcontainer" section

  • Option 1: Direct Podman CLI usage with proper volume mounts
  • Option 2: Podman Compose with installation and usage instructions
  • Option 3: Dev Container CLI for full compatibility
  • Comparison table of all three options
  • SELinux context handling (:Z flag) for Linux users
  • Proper script execution order (post-create.sh, post-attach.sh)
  • Recommendations for different use cases

• CHANGELOG.md - Added [Unreleased] section documenting new features

Documentation Details

Option 1: Direct Podman CLI

• Command-line usage with SELinux context for Linux
• Manual initialization script execution order
• Pros/cons comparison
• Platform-specific instructions (Linux vs macOS/Windows)

Option 2: Podman Compose

• Installation instructions for multiple platforms (pip, dnf, apt)
• Start/stop/exec commands
• Benefits of declarative configuration
• Reference to included compose file

Option 3: Dev Container CLI

• npm installation instructions
• Usage with --docker-path podman flag
• Automatic lifecycle script execution
• Full devcontainer.json feature support

Additional Documentation:

• Comparison table showing complexity, dependencies, and best use cases
• Clear recommendations for when to use each option
• Links to existing Quick Start guide for VS Code users
• Proper formatting following project markdown standards

Code Quality

This implementation follows:

• ✅ Documentation Best Practices - Clear, comprehensive, well-organized
• ✅ Keep a Changelog Format - Proper CHANGELOG entry with [Unreleased] section
• ✅ Project Conventions - Consistent with existing README structure
• ✅ Technical Accuracy - Correct Podman commands, flags, and usage patterns
• ✅ User-Centric - Addresses different user needs and workflows
• ✅ No Hardcoding - Uses proper configuration patterns

Quality Checks

• All linters passing (yamllint, pymarkdown)
• Markdown formatting consistent
• YAML syntax valid
• No broken links
• Follows project documentation patterns
• All three options clearly documented
• SELinux considerations included
• Script execution order explained

Commits

This PR includes 3 atomic commits:

1. feat(devcontainer): add podman-compose.yml for direct Podman usage
2. docs(readme): add comprehensive Podman usage documentation
3. docs(changelog): add entry for Podman usage documentation

Each commit is independently reviewable and follows conventional commit format.

Related Issues

Closes #24

Reviewer Notes

This was implemented in YOLO mode with:

• Autonomous decision-making
• Documentation best practices
• Comprehensive coverage of all requirements
• Production-ready quality

All acceptance criteria met:

• ✅ Option 1: Direct Podman CLI documented with proper command order
• ✅ Option 2: Podman Compose file created and documented
• ✅ Option 3: Dev Container CLI documented
• ✅ SELinux considerations mentioned for Linux users
• ✅ Script execution order clearly explained
• ✅ All three options documented in README

Please review for:

1. Technical accuracy of Podman commands
2. Documentation clarity and completeness
3. Consistency with project style
4. User experience and workflow guidance

Implementation Plan

Detailed implementation plan available at:
.cursor/plans/issue-24.md