Add markdownlint configuration and fix all linting issues

Adds markdownlint enforcement and documentation standards to the project.

Changes:

.markdownlint.json - Configuration for markdown linting:
- Line length: 120 chars (excludes code blocks and tables)
- Enforces blank lines around headings and lists
- Requires language specs for fenced code blocks
- Standard markdown best practices

AGENTS.md - Updated with markdown requirements:
- Added "Documentation Standards" section
- Instructions for running markdownlint
- Added to DO list: lint markdown files before commit
- Fixed all linting issues:
  - Split long lines
  - Added language specs to code blocks (text, bash)
  - Converted bold text to proper headings (####)
  - Proper blank lines around lists and headings

AI-CONTRIBUTIONS.md - Fixed all linting issues:
- Split long lines for readability
- Converted PR titles from bold to proper headings (####)
- Added blank lines around sections
- Improved document structure

All *.md files now pass: npx markdownlint-cli *.md

Benefits:
- Consistent markdown formatting across the project
- Better readability and maintainability
- Catches common markdown issues automatically
- Standard enforced for human and AI contributors

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>

Author: chorrell

.markdownlint.json

@@ -0,0 +1,10 @@
+{
+  "default": true,
+  "MD013": {
+    "line_length": 120,
+    "code_blocks": false,
+    "tables": false
+  },
+  "MD033": false,
+  "MD041": false
+}

AGENTS.md

@@ -4,16 +4,21 @@ Instructions for AI coding agents working on this project.
 
 ## Project Overview
 
-This is a Serverspec-based testing framework for validating Docker images. The project tests Node.js Docker images built from custom Dockerfiles by creating containers, running Serverspec tests against them, and cleaning up resources.
+This is a Serverspec-based testing framework for validating Docker images.
+The project tests Node.js Docker images built from custom Dockerfiles by
+creating containers, running Serverspec tests against them, and cleaning up
+resources.
 
 **Tech Stack:**
+
 - Ruby 3.4+ and Ruby 4.0+
 - Serverspec 2.43+
 - Docker API gem 2.4+
 - RSpec 3.13+
 - Docker BuildKit
 
 **Current Node.js versions tested:**
+
 - Node.js 22.22.0 (Maintenance LTS)
 - Node.js 24.13.0 (Active LTS)
 
@@ -44,7 +49,7 @@ bundle exec rake --trace
 
 ## Project Structure
 
-```
+```text
 .
 ├── 22/                          # Node.js 22 Dockerfile
 ├── 24/                          # Node.js 24 Dockerfile
@@ -89,6 +94,30 @@ bundle update
 # Always remove BUNDLED WITH section from Gemfile.lock for CI compatibility
 ```
 
+## Documentation Standards
+
+### Markdown Linting
+
+All markdown files must pass markdownlint validation before committing.
+
+```bash
+# Check all markdown files
+npx markdownlint-cli *.md
+
+# Auto-fix issues where possible
+npx markdownlint-cli --fix *.md
+```
+
+**Configuration**: See `.markdownlint.json` for project rules.
+
+**Key Rules**:
+
+- Line length: 120 characters max (code blocks excluded)
+- Blank lines around headings and lists
+- Language specified for fenced code blocks
+- No bare URLs (use markdown links)
+- Use proper headings (not bold text as headings)
+
 ## Testing Instructions
 
 ### What Tests Validate
@@ -155,6 +184,7 @@ describe file("/usr/local/bin/node")
 ### GitHub Actions Matrix
 
 Tests run on:
+
 - Ruby 3.4 (current stable)
 - Ruby 4.0 (latest stable)
 
@@ -171,6 +201,7 @@ Both versions must pass before merge.
 
 - Test all changes locally before committing
 - Run full test suite: `bundle exec rake`
+- Lint markdown files: `npx markdownlint-cli *.md`
 - Keep Node.js versions on LTS releases
 - Update README.md when changing versions
 - Use version pinning in Gemfile (`~>` operator)
@@ -193,7 +224,7 @@ Both versions must pass before merge.
 
 ### Commit Message Format
 
-```
+```text
 <type>: <short summary>
 
 <detailed description>
@@ -214,7 +245,7 @@ Co-authored-by: <AI agent or human collaborator>
 
 ### Example
 
-```
+```text
 feat: Add Node.js 26 LTS support
 
 - Create 26/Dockerfile with NODE_VERSION=26.x.x
@@ -258,20 +289,24 @@ Tests pass on Ruby 3.4 and 4.0.
 
 ### Common Issues
 
-**Tests fail with "container not found"**
+#### Tests fail with "container not found"
+
 - Check that Docker daemon is running
 - Verify container cleanup in after(:all) block
 
-**Image build fails**
+#### Image build fails
+
 - Verify Node.js version exists on nodejs.org
 - Check GPG key servers are accessible
 - Review Docker BuildKit logs
 
-**Bundler version conflicts**
+#### Bundler version conflicts
+
 - Remove BUNDLED WITH section from Gemfile.lock
 - Let CI use its native Bundler version
 
-**Performance Issues**
+#### Performance Issues
+
 - Ensure Docker BuildKit is enabled
 - Verify parallel execution (multitask) is working
 - Check if Docker daemon has resource constraints
@@ -297,14 +332,15 @@ bundle exec rspec spec/24/Dockerfile_spec.rb --format documentation
 
 ## Resources
 
-- **Serverspec Documentation**: http://serverspec.org/resource_types.html
-- **Docker API Gem**: https://github.com/swipely/docker-api
-- **Node.js Releases**: https://nodejs.org/en/about/previous-releases
-- **Ruby Releases**: https://www.ruby-lang.org/en/downloads/releases/
+- **Serverspec Documentation**: <http://serverspec.org/resource_types.html>
+- **Docker API Gem**: <https://github.com/swipely/docker-api>
+- **Node.js Releases**: <https://nodejs.org/en/about/previous-releases>
+- **Ruby Releases**: <https://www.ruby-lang.org/en/downloads/releases/>
 
 ## Questions?
 
 When working on this project:
+
 1. Check existing patterns in similar files
 2. Run tests locally before committing
 3. Review CI output for multi-version compatibility

AI-CONTRIBUTIONS.md

@@ -6,83 +6,98 @@ This document tracks improvements made to this project with the assistance of AI
 
 ## Overview
 
-Between February 2026, this project underwent a comprehensive modernization effort with AI assistance. The collaboration resulted in 11 merged pull requests that transformed the codebase from having critical bugs and outdated dependencies to being a modern, efficient, and future-proof testing infrastructure.
+Between February 2026, this project underwent a comprehensive modernization
+effort with AI assistance. The collaboration resulted in 11 merged pull requests
+that transformed the codebase from having critical bugs and outdated dependencies
+to being a modern, efficient, and future-proof testing infrastructure.
 
 ## Improvements Summary
 
 ### 🔒 Critical Bug Fixes
 
-**PR #56: Fixed Unsafe Container Cleanup**
+#### PR #56: Fixed Unsafe Container Cleanup
+
 - **Issue**: `delete_image` was stopping ALL Docker containers on the system, including unrelated ones
 - **Fix**: Updated to only stop containers created from the test image
 - **Impact**: Prevented dangerous system-wide container disruptions
 
 ### ⚡ Performance Enhancements
 
-**PR #58: Parallel Test Execution**
+#### PR #58: Parallel Test Execution
+
 - **Change**: Implemented Rake multitask for parallel test execution
 - **Improvement**: ~47% faster test runs (35s → 18s)
 - **Method**: Tests run in separate subprocesses with isolated environments
 
-**PR #62: Docker BuildKit**
+#### PR #62: Docker BuildKit
+
 - **Change**: Enabled Docker BuildKit for image builds
 - **Benefits**: Faster builds, better caching, improved layer management
 
 ### 📦 Dependency Updates
 
-**PR #57: Updated Gem Dependencies**
+#### PR #57: Updated Gem Dependencies
+
 - Updated to latest stable versions with version pinning
 - Gems: docker-api ~> 2.4, rake ~> 13.0, rspec ~> 3.13, serverspec ~> 2.43
 - Includes security patches and bug fixes
 
-**PR #63: Logger Gem for Ruby 4.0**
+#### PR #63: Logger Gem for Ruby 4.0
+
 - Added explicit `logger` gem dependency
 - Fixes Ruby 4.0 deprecation warning
 - Ensures forward compatibility
 
 ### 🧪 Testing Improvements
 
-**PR #64: Ruby Version Matrix**
+#### PR #64: Ruby Version Matrix
+
 - Implemented GitHub Actions matrix testing
 - Tests on Ruby 3.4 (maintenance) and Ruby 4.0 (latest)
 - Ensures compatibility across Ruby versions
 - fail-fast: false allows all versions to complete
 
-**PR #65: Node.js LTS Updates**
+#### PR #65: Node.js LTS Updates
+
 - Updated from Node.js 20 & 22 to 22 & 24
 - Node.js 22.22.0 (Maintenance LTS)
 - Node.js 24.13.0 (Active LTS "Krypton")
 - Includes latest security patches (January 2026)
 
 ### 🛡️ Reliability & Error Handling
 
-**PR #61: Comprehensive Error Handling**
+#### PR #61: Comprehensive Error Handling
+
 - Added try/catch blocks in `create_image` and `delete_image`
 - Guards against nil @image references
 - Clear error messages for debugging
 - Informative status messages
 
-**PR #60: Removed Redundant Tagging**
+#### PR #60: Removed Redundant Tagging
+
 - Removed unused `@image.tag()` call
 - Simplified image lifecycle management
 
 ### 🔧 Developer Experience
 
-**PR #59: Bundler Config & .gitignore**
+#### PR #59: Bundler Config & .gitignore
+
 - Added `.bundle/config` for local gem installation
 - Created `.gitignore` to exclude vendor/bundle, .DS_Store, etc.
 - Enables `bundle install` without sudo
 - Cleaner repository
 
 ### 📚 Documentation
 
-**PR #66: Updated README**
+#### PR #66: Updated README
+
 - Updated directory references from (20 and 22) to (22 and 24)
 - Keeps documentation in sync with code changes
 
 ## Metrics
 
 ### Before AI Assistance
+
 - Critical container cleanup bug (system-wide impact)
 - Sequential test execution (~35 seconds)
 - Outdated dependencies
@@ -93,6 +108,7 @@ Between February 2026, this project underwent a comprehensive modernization effo
 - Sudo required for gem installation
 
 ### After AI Assistance
+
 - Safe, isolated container cleanup
 - Parallel test execution (~18 seconds, 47% faster)
 - Latest stable dependencies with version pinning
@@ -105,14 +121,17 @@ Between February 2026, this project underwent a comprehensive modernization effo
 ## Technology Stack Updates
 
 ### Ruby Versions Tested
+
 - Ruby 3.4.x (Stable maintenance)
 - Ruby 4.0.x (Latest stable)
 
 ### Node.js Versions Tested
+
 - Node.js 22.22.0 (Maintenance LTS "Jod")
 - Node.js 24.13.0 (Active LTS "Krypton")
 
 ### Gem Versions
+
 - docker-api ~> 2.4
 - rake ~> 13.0
 - rspec ~> 3.13
@@ -122,18 +141,21 @@ Between February 2026, this project underwent a comprehensive modernization effo
 ## AI Agent Methodology
 
 ### Analysis Phase
+
 1. Comprehensive code review of existing implementation
 2. Identification of bugs, inefficiencies, and technical debt
 3. Prioritization of issues by severity and impact
 4. Research of current best practices and latest versions
 
 ### Implementation Phase
+
 1. Incremental improvements via focused pull requests
 2. Testing at each step before proceeding
 3. CI/CD validation for all changes
 4. Clear documentation in commit messages and PR descriptions
 
 ### Verification Phase
+
 1. Local testing before each commit
 2. GitHub Actions CI validation
 3. Multi-version compatibility testing
@@ -142,6 +164,7 @@ Between February 2026, this project underwent a comprehensive modernization effo
 ## Pull Request Links
 
 All improvements are documented in individual pull requests:
+
 - [PR #56](../../pull/56) - Fixed unsafe container cleanup
 - [PR #57](../../pull/57) - Updated gem dependencies
 - [PR #58](../../pull/58) - Parallel test execution
@@ -157,24 +180,28 @@ All improvements are documented in individual pull requests:
 ## Best Practices Demonstrated
 
 ### Code Quality
+
 - Comprehensive error handling
 - Resource cleanup in all code paths
 - Clear, informative logging
 - No technical debt
 
 ### Testing
+
 - Multi-version testing (Ruby 3.4 & 4.0)
 - Multi-platform testing (Node.js 22 & 24)
 - Parallel execution for efficiency
 - CI/CD automation
 
 ### Dependencies
+
 - Version pinning for reproducibility
 - Regular updates for security
 - Explicit dependencies (no implicit defaults)
 - Forward compatibility considerations
 
 ### Documentation
+
 - Clear commit messages
 - Detailed PR descriptions
 - Updated README
@@ -191,14 +218,18 @@ All improvements are documented in individual pull requests:
 ## Future Considerations
 
 While the project is now in excellent shape, potential future improvements could include:
+
 - Additional Node.js LTS version testing (e.g., v26 when released)
 - Ruby 4.1 when it enters LTS
 - Container image caching between test runs
 - Performance benchmarking automation
 
 ## Acknowledgments
 
-This project benefited from AI assistance using Factory's Droid agent, which helped identify issues, research solutions, implement fixes, and ensure comprehensive testing. All changes were reviewed and approved by the project maintainer.
+This project benefited from AI assistance using Factory's Droid agent, which
+helped identify issues, research solutions, implement fixes, and ensure
+comprehensive testing. All changes were reviewed and approved by the project
+maintainer.
 
 ---