docs: vars ai fixups

docs/site/guides/vars-backend.md

@@ -11,7 +11,7 @@ For architectural concepts and design principles, see the [Concepts guide](vars-
 
 This guide assumes
 - Clan is set up already (see [Getting Started](../guides/getting-started/index.md))
-- a machine has been added to the clan (see [Adding Machines](./more-machines.md))
+- a machine has been added to the clan (see [Adding Machines](getting-started/add-machines.md))
 
 This section will walk you through the following steps:
 
@@ -117,7 +117,7 @@ If we just imported the `root-password.nix` from above into more machines, clan
 If the root password instead should only be entered once and shared across all machines, the generator defined above needs to be declared as `shared`, by adding `share = true` to it:
 ```nix
 {config, pkgs, ...}: {
-  clan.vars.generators.root-password = {
+  clan.core.vars.generators.root-password = {
     share = true;
     # ...
   }

docs/site/guides/vars-overview.md

@@ -0,0 +1,169 @@
+# Vars System Overview
+
+The vars system is clan's declarative solution for managing generated files, secrets, and dynamic configuration in your NixOS deployments. It eliminates the manual steps of generating credentials, certificates, and other dynamic values by automating these processes within your infrastructure-as-code workflow.
+
+## What Problems Does Vars Solve?
+
+### Before Vars: Manual Secret Management
+
+Traditional NixOS deployments require manual steps for secrets and generated files:
+
+```bash
+# Generate password hash manually
+mkpasswd -m sha-512 > /tmp/root-password-hash
+# Copy hash into configuration
+users.users.root.hashedPasswordFile = "/tmp/root-password-hash";
+```
+
+This approach has several problems:
+- **Not reproducible**: Manual steps vary between team members
+- **Hard to maintain**: Updating secrets requires remembering manual commands  
+- **Deployment friction**: Secrets must be managed outside of your configuration
+- **Team collaboration issues**: Sharing credentials securely is complex
+
+### After Vars: Declarative Generation
+
+With vars, the same process becomes declarative and automated:
+
+```nix
+clan.core.vars.generators.root-password = {
+  prompts.password.description = "Root password";
+  prompts.password.type = "hidden";
+  files.hash.secret = false;
+  script = "mkpasswd -m sha-512 < $prompts/password > $out/hash";
+  runtimeInputs = [ pkgs.mkpasswd ];
+};
+
+users.users.root.hashedPasswordFile = 
+  config.clan.core.vars.generators.root-password.files.hash.path;
+```
+
+## Core Benefits
+
+- **🔄 Reproducible**: Same inputs always produce the same outputs
+- **📝 Declarative**: Defined alongside your NixOS configuration
+- **🔐 Secure**: Automatic secret storage and encrypted deployment
+- **👥 Collaborative**: Built-in sharing for team environments
+- **🚀 Automated**: No manual intervention required for deployments
+- **🔗 Integrated**: Works seamlessly with clan's deployment workflow
+
+## How It Works
+
+```mermaid
+graph TB
+    A[Generator Declaration] --> B[clan vars generate]
+    B --> C{Prompts User}
+    C --> D[Execute Script]
+    D --> E[Output Files]
+    E --> F{Secret?}
+    F -->|Yes| G[Encrypted Storage]
+    F -->|No| H[Git Repository]
+    G --> I[Deploy to Machine]
+    H --> I
+    I --> J[Available in NixOS]
+```
+
+1. **Declare generators** in your NixOS configuration
+2. **Generate values** using `clan vars generate` (or automatically during deployment)
+3. **Store securely** in encrypted backends or version control
+4. **Deploy seamlessly** to your machines where they're accessible as file paths
+
+## Common Use Cases
+
+| Use Case | What Gets Generated | Benefits |
+|----------|-------------------|----------|
+| **User passwords** | Password hashes | No plaintext in config |
+| **SSH keys** | Host/user keypairs | Automated key rotation |
+| **TLS certificates** | Certificates + private keys | Automated PKI |
+| **Database credentials** | Passwords + connection strings | Secure service communication |
+| **API tokens** | Random tokens | Service authentication |
+| **Configuration files** | Complex configs with secrets | Dynamic config generation |
+
+## Architecture Overview
+
+The vars system has three main components:
+
+### 1. **Generators**
+Define how to create files from inputs:
+- **Prompts**: Values requested from users
+- **Scripts**: Generation logic  
+- **Dependencies**: Other generators this depends on
+- **Outputs**: Files that get created
+
+### 2. **Storage Backends**
+Handle secret storage and deployment:
+- **sops**: Encrypted files in git (recommended)
+- **password-store**: GPG/age-based secret storage
+- **vm**: For development/testing
+
+### 3. **Integration**
+Seamless NixOS integration:
+- File paths available at build time
+- Automatic deployment to machines
+- Service restarts on changes
+
+## Learning Path
+
+Ready to get started? Follow this recommended path:
+
+### 1. **🚀 Hands-On Tutorial**
+[Vars Getting Started Guide](vars-backend.md)
+Start here for a practical walkthrough with password generation.
+
+### 2. **🏗️ Understand the Design**  
+[Vars Concepts & Architecture](vars-concepts.md)
+Deep dive into design principles and advanced patterns.
+
+### 3. **💡 Real-World Examples**
+[Advanced Examples](vars-advanced-examples.md)
+Complex scenarios including certificates, SSH keys, and databases.
+
+### 4. **🔧 Troubleshooting**
+[Troubleshooting Guide](vars-troubleshooting.md)
+Solutions for common issues and debugging techniques.
+
+### 5. **📚 Complete Reference**
+- [NixOS Module Options](../reference/clan.core/vars.md)
+- [CLI Commands](../reference/cli/vars.md)
+
+## Quick Start Example
+
+Here's a complete example showing password generation and usage:
+
+```nix
+# generator.nix
+{ config, pkgs, ... }: {
+  clan.core.vars.generators.user-password = {
+    prompts.password = {
+      description = "User password";
+      type = "hidden";
+    };
+    files.hash = { secret = false; };
+    script = ''
+      mkpasswd -m sha-512 < $prompts/password > $out/hash
+    '';
+    runtimeInputs = [ pkgs.mkpasswd ];
+  };
+  
+  users.users.myuser = {
+    hashedPasswordFile = 
+      config.clan.core.vars.generators.user-password.files.hash.path;
+  };
+}
+```
+
+```bash
+# Generate the password
+clan vars generate my-machine
+
+# Deploy to machine
+clan machines update my-machine
+```
+
+## Migration from Facts
+
+If you're currently using the legacy facts system, see our [Migration Guide](migrations/migration-facts-vars.md) for step-by-step instructions on upgrading to vars.
+
+---
+
+**Ready to start?** Head to the [Getting Started Guide](vars-backend.md) for your first hands-on experience with the vars system.