feat: [#339] AI training resources - config examples and questionnaire

[josecelano]

Overview

This PR implements Issue #339, providing structured resources to help AI agents guide users through environment configuration creation.

Implementation Summary

All 6 phases completed:

Phase 1: Schema Extension ✅

• Added optional description field to environment configuration schema
• Updated JSON schema (schemas/environment-config.json)
• Updated Rust DTO (src/application/command_handlers/create/config/environment_config.rs)
• Maintained backward compatibility (configs without description still work)

Phase 2: Questionnaire Template ✅

• Created comprehensive questionnaire at docs/ai-training/questionnaire.md (494 lines)
• Full decision tree covering all configuration requirements
• Includes validation rules and conditional logic

Phase 3-4: Example Configurations ✅

• Created all 15 example scenarios covering common deployment patterns
• All examples validated with cargo run -- validate --env-file
• Each example includes descriptive explanation (2-3 sentences)
• Examples use fixture keys only (no sensitive data)

Phase 5: Documentation ✅

• Created comprehensive README at docs/ai-training/README.md (469 lines)
• Includes scenarios table, usage instructions, customization guide
• Documents common decision points and best practices

Phase 6: Integration Test ✅

• Created integration test at tests/validate_ai_training_examples.rs
• 4 test functions validating all aspects:
  • Configuration validation (all 15 examples)
  • File count verification (exactly 15 examples)
  • Naming convention enforcement (NN-descriptive-name.json pattern)
  • Description field presence validation
• Added regex dependency for pattern matching
• All linters passing

Example Scenarios Coverage

ID	Scenario	Provider	Database	Trackers	HTTPS	Monitoring	Backup
01	Minimal development	LXD	SQLite	UDP+HTTP	No	No	No
02	Full-stack LXD	LXD	MySQL	2U+2H	Yes	Yes	Yes
03	Minimal Hetzner	Hetzner	SQLite	UDP+HTTP	No	No	No
04	Full-stack Hetzner	Hetzner	MySQL	2U+2H	Yes	Yes	Yes
...	(11 more scenarios)	...	...	...	...	...	...

Benefits

For AI Agents:

• Structured guidance through questionnaire
• Few-shot learning from validated examples
• Reduced hallucination with real configs as reference
• Faster iteration with less trial-and-error

For Users:

• Examples serve as documentation and starting points
• Clear mapping from requirements to configuration values
• Understanding of common deployment patterns

For Training/RAG:

• Curated dataset with high-quality examples
• Coverage of common and edge cases
• Machine-readable JSON format
• Versioned with deployer releases

Testing

• ✅ All linters pass: cargo run --bin linter all
• ✅ All examples validated: cargo run -- validate --env-file
• ✅ Integration tests pass: cargo test --test validate_ai_training_examples
• ✅ Pre-commit checks pass: ./scripts/pre-commit.sh

Files Changed

• schemas/environment-config.json - Added description field
• src/application/command_handlers/create/config/environment_config.rs - EnvironmentSection with description
• docs/ai-training/questionnaire.md - Decision tree questionnaire (494 lines)
• docs/ai-training/examples/*.json - 15 validated example configurations
• docs/ai-training/README.md - Comprehensive documentation (469 lines)
• tests/validate_ai_training_examples.rs - Integration test suite
• Cargo.toml - Added regex dev-dependency
• docs/issues/339-provide-config-examples-and-questionnaire-for-ai-agents.md - Updated progress
• docs/roadmap.md - Marked task 11.3 as completed

Acceptance Criteria

All criteria met:

• Optional description field added and validated
• Backward compatibility maintained
• Questionnaire template created
• All 15 examples created with descriptions
• Each example validated
• README with scenarios table and guidance
• Integration test created and passing
• All linters passing
• Examples use fixture keys only

Closes #339

[josecelano]

ACK 0bd9547