Documentation improvements

Problem Statement

The current README serves as a comprehensive reference but lacks onboarding structure, causing new users to read the documentation multiple times or dive into source code before being productive.

Proposed Improvements

1. Add Quick Start Section

Move this to the top of the README to give users immediate hands-on experience:

  • Promote the timofurrer/opentofu-test example from the bottom to a dedicated "Quick Start" section
  • Provide a minimal working example users can copy-paste and experiment with immediately
  • Explain what full-pipeline and other core templates do upfront, before diving into configuration details

Current issue: The Usage section jumps between examples, and "A concrete example may look like this" is buried mid-document. Template explanations are scattered throughout, forcing multiple reading passes.

2. Restructure Documentation Flow

Reorganise into a progressive learning path:

  1. Quick Start - Get running in 5 minutes
  2. Basic Usage - Core templates and common patterns
  3. Advanced Topics - Complex scenarios like "Utilising Plans from a Merged Merge Request Pipeline"
  4. Best Practices - Optimisation and production considerations

3. Make Lockfile Handling the Default (Critical)

This should be default for all new installations with opt-out options for backwards compatibility and not a Best Practice.

Current floating lockfile behaviour caused issues for me that were difficult to debug without deep component knowledge. I lost several hours debugging this and required maintainer intervention (pulled Timo into Slack/Zoom) to resolve.

Recommendation: Update all examples and templates to use explicit lockfile handling by default, with a clear explanation of why this matters so that new users have a robust/working configuration from the start. For existing users that need backwards compatibility, mention an option of removing the lockfile from the repo still being an option.