Modernize docs v2

.gitignore

@@ -4,6 +4,7 @@ __pycache__
 /.idea
 /.envrc
 /.direnv/
+/.claude
 
 # This is autogenerated, don't check it in.
 llms.txt

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

@@ -1,51 +1,73 @@
----
-description: Take your Infrastructure as Code to the next level
----
+# Hello, Spacelift!
 
-# 👋 Hello, Spacelift!
+Spacelift is a specialized CI/CD platform designed to address the collaborative challenges of Infrastructure as Code (IaC). While traditional CI/CD tools excel at stateless applications, infrastructure management presents unique challenges that Spacelift was specifically built to solve.
 
-Spacelift is a sophisticated, continuous integration and deployment (CI/CD) platform for _infrastructure-as-code,_  supporting [Terraform](vendors/terraform/README.md), [OpenTofu](https://opentofu.org/){: rel="nofollow"}, [Terragrunt](vendors/terragrunt/README.md), [Pulumi](vendors/pulumi/README.md), [AWS CloudFormation](vendors/cloudformation/README.md), [AWS CDK](vendors/cloudformation/integrating-with-cdk.md), [Kubernetes](vendors/kubernetes/README.md), [Ansible](vendors/ansible/README.md), and more. It's designed and implemented by long-time DevOps practitioners based on previous experience with large-scale installations - dozens of teams, hundreds of engineers, and tens of thousands of cloud resources.
+## Infrastructure as Code: The Multiplayer Challenge
 
-At the same time, Spacelift is super easy to get started with - you can go from zero to fully managing your cloud resources within less than a minute, with no pre-requisites. It integrates nicely with the large players in the field - notably [GitHub](integrations/source-control/github.md) and [AWS](integrations/cloud-providers/aws.md).
+Infrastructure as Code projects create a unique set of challenges:
 
-If you're new to Spacelift, please spend some time browsing through the articles in the same order as they appear in the menu - start with the main concepts and follow with integrations. If you're more advanced, you can navigate directly to the article you need, or use the search feature to find a specific piece of information. If you still have questions, feel free to [reach out to us.](https://spacelift.io/contact){: rel="nofollow"}
+- **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
 
-## Do I need another CI/CD for my infrastructure?
+Spacelift transforms infrastructure management from a risky solo endeavor into a collaborative experience with guardrails.
 
-Yes, we believe it's a good idea. While in an ideal world one CI system would be enough to cover all use cases, we don't live in an ideal world. Regular CI tools can get you started easily, but Terraform has a rather unusual execution model and a highly stateful nature. Also, mind the massive blast radius when things go wrong. We believe Spacelift offers a perfect blend of regular CI's versatility and methodological rigor of a specialized, security-conscious infrastructure tool - enough to give it a shot even if you're currently happy with your infra-as-code CI/CD setup.
+## The Graph of Graphs Problem
 
-In the following sections, we'll try to present the main challenges of running Terraform in a general purpose CI system, as well as show how Spacelift addresses those. At the end of the day, it's mostly about two things - collaboration and security.
+Most organizations face what we call the "graph of graphs" problem - the challenge of managing not just individual infrastructure stacks, but the complex relationships between them:
 
-### Collaboration
+1. **Stack Dependencies**: Infrastructure projects often depend on outputs from other stacks
+2. **Deployment Order**: Changes must be applied in the correct sequence to maintain system integrity
+3. **Cross-team Collaboration**: Different teams maintain different components with interdependencies
 
-> Wait, aren't CIs built for collaboration?
+Spacelift's [Stack Dependencies](concepts/stack/stack-dependencies.md) feature elegantly solves this by allowing you to:
 
-Yes, assuming stateless tools and processes. Running stateless builds and tests is what regular CIs are exceptionally good at. But many of us have noticed that deployments are actually trickier to get right. And that's hardly a surprise. They're more stateful, they may depend on what's already running. Terraform and your infrastructure, in general, is an **extreme example of a stateful system**. It's so stateful that it actually has something called [**state**](https://www.terraform.io/docs/state/index.html){: rel="nofollow"} (see what we just did there?) as one of its core concepts.
+- Define explicit relationships between stacks
+- Automatically receive outputs from upstream stacks as inputs
+- Trigger dependent stacks when upstream changes occur
+- Visualize the complete dependency graph of your infrastructure
 
-CIs generally struggle with that. They don't really _understand_ the workflows they run, so they can't for example serialize certain types of jobs. Like `terraform apply`, which introduces actual changes to your infrastructure. As far as your CI system is concerned, running those in parallel is fair game. But what it does to Terraform is nothing short of a disaster - your state is confused and no longer represents any kind of reality. Untangling this mess can take forever.
+## Self-service Infrastructure with Blueprints
 
-> But you can add manual approval steps
+Blueprints enable controlled self-service for your organization, allowing platform teams to create standardized infrastructure templates while giving application teams the freedom to deploy what they need.
 
-Yes, you can. But the whole point of your CI/CD system is to automate your work. First of all, becoming a human semaphore for a software tool isn't the best use of a highly skilled and motivated professional. Also, over-reliance on humans to oversee software processes will inevitably lead to costly mistakes because we, humans, are infinitely more fallible than well-programmed machines. It's ultimately much cheaper to use the right tool for the job than turn yourself into a part of a tool.
+With [Blueprints](concepts/blueprint/README.md), you can:
 
-> But you can do [state locking](https://www.terraform.io/docs/state/locking.html){: rel="nofollow"}!
+- **Standardize Infrastructure**: Create templated stack configurations that enforce best practices
+- **Enable Self-service**: Allow developers to provision infrastructure without deep IaC expertise
+- **Maintain Governance**: Embed security guardrails and compliance controls directly in templates
+- **Streamline Onboarding**: Reduce the time needed for teams to provision new environments
 
-Yup, we hear you. In theory, it's a great feature. In practice, it has its limitations. First, it's a massive pain when working as a team. Your CI won't serialize jobs that can write state, and state locking means that all but one of the parallel jobs will simply fail. It's a safe default, that's for sure, but not a great developer experience. And the more people work on your infrastructure, the more frustrating the process will become.
+Blueprints transform the platform team from a bottleneck into enablers of developer productivity while maintaining control over infrastructure standards and security.
 
-And that's just _applying_ changes. By default, running `terraform plan` locks the state, too. So you can't really run multiple CI jobs in parallel, even if they're only meant to preview changes, because each of them will attempt to lock the state. Yes, you can work around this by explicitly _not_ locking state in CI jobs that you know won't make any state changes, but at this point, you've already put so much work into creating a pipeline that's fragile at best and requires you to manually synchronize it.
+## Key Features
 
-And we haven't even discussed security yet.
+Spacelift supports a wide range of IaC tools including:
 
-### Security
+- [OpenTofu](https://opentofu.org/) and [Terraform](vendors/terraform/README.md)
+- [Ansible](vendors/ansible/README.md)
+- [Terragrunt](vendors/terragrunt/README.md)
+- [Pulumi](vendors/pulumi/README.md)
+- [AWS CloudFormation](vendors/cloudformation/README.md) and [AWS CDK](vendors/cloudformation/integrating-with-cdk.md)
+- [Kubernetes](vendors/kubernetes/README.md)
 
-Terraform is used to manage infrastructure, which normally requires credentials. Usually, very powerful credentials. Administrative credentials, sometimes. And these can do _a lot of damage_. The thing with CIs is that you need to provide those credentials statically, and once you do, there's no way you can control how they're used.
+With enterprise-grade capabilities:
 
-And that's what makes CIs powerful - after all, they let you run arbitrary code, normally based on some configuration file that you have checked in with your Terraform code. So, what's exactly stopping a prankster from adding `terraform destroy -auto-approve` as an extra CI step? Or printing out those credentials and using them to mine their crypto of choice?
+- **Policy as Code**: Define [governance rules](concepts/policy/README.md) for who can do what, when, and how
+- **Private Workers**: Run jobs within your own infrastructure for enhanced security
+- **RBAC & Spaces**: Organize resources and control access with fine-grained permissions
+- **Cloud Integrations**: Native integration with AWS, Azure, and GCP for secure credential management
+- **VCS Integrations**: Connect with GitHub, GitLab, Bitbucket, and Azure DevOps
 
-> There are better ways to get fired.
+## Getting Started
 
-...you'll say and we hear you. Those jobs _are_ audited after all. No, if we were disgruntled employees we'd never do something as stupid. We'd get an SSH session and leak those precious credentials this way. Since it's unlikely you rotate them every day, we'd take our sweet time before using them for our nefarious purposes. Which wouldn't be possible with Spacelift BTW, which generates [one-off temporary credentials](integrations/cloud-providers/aws.md) for major cloud providers.
+New to Spacelift? We recommend exploring our documentation in this order:
 
-> But nobody does that!
+1. [Core Concepts](concepts/stack/README.md) - Understand stacks, runs, and policies
+2. [Stack Dependencies](concepts/stack/stack-dependencies.md) - Learn how to manage inter-project dependencies
+3. [Blueprints](concepts/blueprint/README.md) - Discover how to enable self-service infrastructure
+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
 
-Yes, you don't hear many of those stories. Most mistakes happen to well-meaning people. But in the world of infrastructure, even the tiniest of mistakes can cause major outages - like that typo we once made in our DNS config. That's why Spacelift adds an extra layer of [policy](concepts/policy/README.md) that allows you to control - separately from your infrastructure project! - [what code can be executed](concepts/policy/run-initialization-policy.md), [what changes can be made](concepts/policy/terraform-plan-policy.md), [when and by whom](concepts/policy/stack-access-policy.md). This isn't only useful to protect yourself from the baddies, but allows you to implement an [automated code review pipeline](concepts/policy/terraform-plan-policy.md#automated-code-review).
+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

@@ -5,9 +5,9 @@
     This feature is only available on the Business plan and above. Please check out our [pricing page](https://spacelift.io/pricing){: rel="nofollow"} for more information.
 {% endif %}
 
-There are multiple ways to create [stacks](../stack/README.md) in Spacelift. Our recommended way is to use [our Terraform provider](../../vendors/terraform/terraform-provider.md) and programmatically create stacks using an [administrative](../stack/stack-settings.md#administrative) stack.
+There are multiple ways to create [stacks](../stack/README.md) in Spacelift. Our recommended way is to use [our OpenTofu/Terraform provider](../../vendors/terraform/terraform-provider.md) and programmatically create stacks using an [administrative](../stack/stack-settings.md#administrative) stack.
 
-However, some users might not be comfortable using Terraform code to create stacks. This is where Blueprints come in handy.
+However, some users might not be comfortable using OpenTofu/Terraform code to create stacks. This is where Blueprints come in handy.
 
 ## What is a Blueprint?
 
@@ -129,7 +129,7 @@ inputs:
       - "1.4.6"
       - "1.5.0"
   - id: manage_state
-    name: Should Spacelift manage the state of Terraform
+    name: Should Spacelift manage the state of OpenTofu
     default: true
     type: boolean
   - id: destroy_task_epoch
@@ -149,7 +149,7 @@ stack:
   is_disabled: ${{ inputs.environment != 'prod' }}
   labels:
     - Environment/${{ inputs.environment }}
-    - Vendor/Terraform
+    - Vendor/OpenTofu
     - Owner/${{ context.user.login }}
     - Blueprint/${{ context.blueprint.name }}
     - Space/${{ context.blueprint.space }}
@@ -380,9 +380,9 @@ stack:
   name: 'yes-my-stack'
 ```
 
-### Interaction with Terraform `templatefile`
+### Interaction with OpenTofu/Terraform `templatefile`
 
-When using the Terraform [`templatefile`](https://developer.hashicorp.com/terraform/language/functions/templatefile){: rel="nofollow"} function to generate a Blueprint template body, you can run into issues because the Blueprint template engine and `templatefile` both use `$` as template delimiters. This can result in error messages like the following:
+When using the OpenTofu/Terraform [`templatefile`](https://opentofu.org/docs/language/functions/templatefile/){: rel="nofollow"} function to generate a Blueprint template body, you can run into issues because the Blueprint template engine and `templatefile` both use `$` as template delimiters. This can result in error messages like the following:
 
 {% raw %}
 
@@ -654,7 +654,7 @@ Note that this is not a working example as it is missing a few things (`inputs`
 
 ## Stack Configuration
 
-Stacks can be configured in a similar fashion as if you were using the Terraform provider or the UI. Most of the options are straightforward; however, some require deeper knowledge and are covered in the sections below. For a full list of available options, please refer to the [Schema](#schema) section below.
+Stacks can be configured in a similar fashion as if you were using the OpenTofu/Terraform provider or the UI. Most of the options are straightforward; however, some require deeper knowledge and are covered in the sections below. For a full list of available options, please refer to the [Schema](#schema) section below.
 
 ### Dependencies
 
@@ -873,7 +873,7 @@ The up-to-date schema of a Blueprint is available through a [GraphQL query](../.
 ```
 
 !!! tip
-    Remember that there are multiple ways to interact with Spacelift. You can use the [GraphQL API](../../integrations/api.md), the [CLI](https://github.com/spacelift-io/spacectl){: rel="nofollow"}, the [Terraform Provider](https://registry.terraform.io/providers/spacelift-io/spacelift/latest/docs){: rel="nofollow"}, or the web UI itself if you're feeling fancy.
+    Remember that there are multiple ways to interact with Spacelift. You can use the [GraphQL API](../../integrations/api.md), the [CLI](https://github.com/spacelift-io/spacectl){: rel="nofollow"}, the [OpenTofu/Terraform Provider](https://search.opentofu.org/provider/spacelift-io/spacelift/latest){: rel="nofollow"}, or the web UI itself if you're feeling fancy.
 
 For simplicity, here is the current schema, but it might change in the future: