Review feedback

Author: marcinwyszynski

.gitignore

@@ -4,3 +4,4 @@ __pycache__
 /.idea
 /.envrc
 /.direnv/
+/.claude

CLAUDE.md

@@ -0,0 +1,107 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Documentation Build System
+
+This is the Spacelift user documentation repository using MkDocs with Material theme. The live documentation is at https://docs.spacelift.io/.
+
+## Common Commands
+
+### Development
+
+- `make run` - Run the documentation site locally via Docker Compose (http://localhost:8000)
+- `mkdocs serve` - Run locally with MkDocs directly
+- `mkdocs serve -a '0.0.0.0:8000'` - Run with external access
+
+### Testing and Linting
+
+- `make lint` - Run all linting checks (markdown + image optimization)
+- `pre-commit` - Run pre-commit hooks manually
+- `pre-commit install` - Install git hooks for automatic validation
+
+### Self-Hosted Documentation
+
+- `mike serve --branch self-hosted-releases-prod` - Preview self-hosted docs
+- Requires fetching: `git fetch origin self-hosted-releases-prod`
+
+## Architecture
+
+### Dual Documentation System
+
+The repository maintains two versions of documentation:
+
+- **SaaS version**: Standard documentation for cloud users
+- **Self-hosted version**: Documentation for on-premises installations
+
+This is managed through:
+
+- Two navigation files: `nav.yaml` (SaaS) and `nav.self-hosted.yaml` (self-hosted)
+- Conditional content using Jinja macros: `is_saas()` and `is_self_hosted()`
+- Environment variable `SPACELIFT_DISTRIBUTION` controls which version is built
+
+### Key Files and Structure
+
+- `docs/` - All Markdown documentation content
+- `mkdocs.yaml` - Main MkDocs configuration (uses `nav.yaml` by default)
+- `nav.yaml` / `nav.self-hosted.yaml` - Navigation structure for each version
+- `main.py` - Custom Jinja macros for conditional content
+- `hooks/` - MkDocs build hooks for banner fetching and URL processing
+- `overrides/` - Custom theme templates and components
+- `docs/assets/` - Static assets (CSS, images, screenshots)
+
+### Content Organization
+
+Documentation is organized into main sections:
+
+- **Getting Started** - Initial setup and onboarding
+- **Main Concepts** - Core concepts like Stack, Blueprint, Configuration, Run, Policy, Resources
+- **Vendors** - Tool-specific guides (Terraform, Ansible, Kubernetes, etc.)
+- **Integrations** - Third-party integrations and cloud providers
+- **Product** - Product-specific features and administration
+
+### Screenshots and Assets
+
+- Screenshots go in `docs/assets/screenshots/`
+- Images are automatically optimized with oxipng during pre-commit
+- Use descriptive filenames for screenshots
+
+### Conditional Content Patterns
+
+```markdown
+{% if is_saas() %}
+SaaS-only content here
+{% endif %}
+
+{% if is_self_hosted() %}
+Self-hosted-only content here
+{% endif %}
+```
+
+Use `{% raw %}` blocks when Jinja interferes with code examples containing template syntax.
+
+## Development Workflow
+
+### Making Changes
+
+1. Edit Markdown files in `docs/` directory
+2. Add new pages to appropriate navigation file(s)
+3. Test locally with `make run`
+4. Validate with pre-commit hooks
+5. Both SaaS and self-hosted versions are automatically built on PR
+
+### Adding New Pages
+
+- Add to `nav.yaml` for SaaS-only pages
+- Add to `nav.self-hosted.yaml` for self-hosted-only pages
+- Add to both files for pages that appear in both versions
+
+### Pre-commit Validation
+
+The repository uses pre-commit hooks for:
+
+- Large file detection
+- YAML validation
+- Markdown linting (markdownlint)
+- Link checking (markdown-link-check)
+- PNG optimization (oxipng)

docs/README.md

@@ -6,10 +6,10 @@ Spacelift is a specialized CI/CD platform designed to address the collaborative
 
 Infrastructure as Code projects create a unique set of challenges:
 
-- **State management**: Unlike application code, infrastructure changes rely on state files that track what's currently deployed
 - **Coordination**: Multiple team members working on the same infrastructure can create conflicts
 - **Dependencies**: Infrastructure components often depend on one another, creating complex deployment ordering requirements
 - **Security**: Infrastructure credentials have significant privileges and require careful handling
+- **State management**: Unlike application code, infrastructure changes rely on tracking what's currently deployed - this is particularly important for tools like Terraform, OpenTofu and Pulumi, which externally store a "digital twin" of your infrastructure state
 
 Spacelift transforms infrastructure management from a risky solo endeavor into a collaborative experience with guardrails.
 
@@ -70,4 +70,4 @@ New to Spacelift? We recommend exploring our documentation in this order:
 4. [Integrations](integrations/source-control/README.md) - Connect Spacelift to your existing tools
 5. [Workers](concepts/worker-pools/README.md) - Execute jobs securely in your environment
 
-If you're ready to try Spacelift, [sign up for a free trial](https://spacelift.io/free-trial) or [contact our team](https://spacelift.io/contact) for a personalized demo.
+If you're ready to try Spacelift, sign up for a free trial in [the EU region 🇪🇺](https://spacelift.io/free-trial), [the US region 🇺🇸](https://spacelift.io/free-trial) or [contact our team](https://spacelift.io/contact) for a personalized demo.

docs/concepts/blueprint/README.md

@@ -122,14 +122,14 @@ inputs:
     type: secret
     # secret means the input will be masked in the UI
   - id: tf_version
-    name: OpenTofu/Terraform version of the stack
+    name: Terraform version of the stack
     type: select
     options:
       - "1.3.0"
       - "1.4.6"
       - "1.5.0"
   - id: manage_state
-    name: Should Spacelift manage the state of OpenTofu/Terraform
+    name: Should Spacelift manage the state of OpenTofu
     default: true
     type: boolean
   - id: destroy_task_epoch