# Sync Docs

> Sync Docs is an Agent Skill for documents published in the mysticaltech/terraform-hcloud-kube-hetzner repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Use when documentation needs updating - ensures variables.tf, docs/llms.md, kube.tf.example, and README are in sync

- Skill name: `sync-docs`
- Category: [Documents](https://www.openparable.com/skill/documents/1)
- Source: https://github.com/mysticaltech/terraform-hcloud-kube-hetzner/blob/HEAD/.claude/skills/sync-docs/SKILL.md
- Repository: mysticaltech/terraform-hcloud-kube-hetzner (3,880 GitHub stars when collected)

## SKILL.md

# Sync Documentation

## Overview

Ensure documentation is synchronized across all key files when variables or features change.

## Usage

```
/sync-docs
```

## Documentation Files

| File | Purpose | Priority |
|------|---------|----------|
| `variables.tf` | Source of truth for all variables | PRIMARY |
| `docs/llms.md` | Comprehensive variable reference | HIGH |
| `kube.tf.example` | Working example configuration | HIGH |
| `README.md` | Project overview and quick start | MEDIUM |
| `MIGRATION.md` | Operator-facing upgrade contract and v2 -> v3 variable map | HIGH for major upgrades |
| `docs/v2-to-v3-migration.md` | Stepwise migration playbook | HIGH for major upgrades |
| `docs/selinux.md` | SELinux policy provenance and AVC workflow | HIGH for SELinux changes |
| `docs/v3-release-evidence.md` | Live proof and release evidence | HIGH for release claims |
| `docs/terraform.md` | Auto-generated terraform docs | AUTO |
| `docs/v3-topology-recommendations.md` | Topology chooser and release-shaping guidance | MEDIUM |
| `examples/*/README.md` | Feature-specific operator examples | MEDIUM |
| `tests/README.md` | Test gate expectations and live-test notes | MEDIUM |
| `.claude/skills/*/SKILL.md` | Agent/operator workflows | MEDIUM |

## Workflow

```dot
digraph sync_flow {
    rankdir=TB;
    node [shape=box];

    extract [label="1. Extract from variables.tf"];
    compare [label="2. Compare with docs/llms.md"];
    gaps [label="3. Identify gaps"];
    update_llms [label="4. Update docs/llms.md"];
    update_example [label="5. Update kube.tf.example"];
    update_readme [label="6. Update README if needed"];
    verify [label="7. Verify consistency"];

    extract -> compare;
    compare -> gaps;
    gaps -> update_llms;
    update_llms -> update_example;
    update_example -> update_readme;
    update_readme -> verify;
}
```

## Step 1: Extract Variables from Source

Use Gemini for large file analysis:

```bash
# List all variables from variables.tf
gemini --model gemini-3.1-pro-preview -p "@variables.tf List ALL variable names defined in this file, one per line"

# Get variable details
gemini --model gemini-3.1-pro-preview -p "@variables.tf For variable '<name>', provide: type, default, description"
```

## Step 2: Find Undocumented Variables

```bash
# Compare variables.tf with docs/llms.md
gemini --model gemini-3.1-pro-preview -p \
  "@variables.tf @docs/llms.md List ALL variables from variables.tf that are NOT documented in docs/llms.md. Output one per line."
```

## Step 3: Generate Documentation

### docs/llms.md Format

```markdown
**Variable Name**

```tf
variable_name = "default_value"
```

* **`variable_name` (Type, Optional/Required):**
  * **Default:** `default_value`
  * **Purpose:** Clear explanation of what this does
  * **Usage:** When and how to use it
  * **Considerations:** Important notes, limitations, impacts
  * **Example:** Practical usage example if helpful
```

### kube.tf.example Format

```tf
  # Description of what this controls
  # Additional context if needed
  # variable_name = "default_value"
```

## Step 4: Update docs/llms.md

For each undocumented variable:

1. Read variable definition from `variables.tf`
2. Understand its usage in `locals.tf` and other files
3. Write comprehensive documentation following the format above
4. Place in appropriate section of `docs/llms.md`

### Section Organization in docs/llms.md

| Section | Variables |
|---------|-----------|
| Cluster Basics | cluster_name, hcloud_token, ssh_* |
| Network | network_*, subnet_* |
| Control Plane | control_plane_* |
| Agents | agent_*, autoscaler_* |
| Load Balancer | lb_*, traefik_*, nginx_* |
| CNI | cni_*, cilium_*, calico_* |
| Node Transport | node_transport_mode, tailscale_* |
| Storage | longhorn_* |
| Security | firewall_*, audit_* |
| Advanced | Additional/misc options |

## Step 5: Update kube.tf.example

Ensure new variables appear in the example with:
- Clear comment explaining purpose
- Commented out with default value
- Grouped with related variables

```bash
# Check what's in example vs variables.tf
gemini --model gemini-3.1-pro-preview -p \
  "@variables.tf @kube.tf.example List variables from variables.tf missing from kube.tf.example"
```

## Step 6: Update README if Needed

Update README.md if:
- New major feature added
- New CNI or ingress option
- Significant capability change

Features section should match actual capabilities.

For Tailscale changes, keep these surfaces in sync:
- `README.md` support table and Multinetwork section
- `kube.tf.example` Tailscale node-transport comments
- `docs/llms.md` support levels and variable notes
- `docs/v3-topology-recommendations.md`
- `examples/tailscale-node-transport/README.md`
- `examples/external-overlay-tailscale/README.md`
- `examples/external-overlay-cloudflare-access/README.md` when access-boundary wording changes
- `.claude/skills/kh-assistant/SKILL.md`
- `.claude/skills/migrate-v2-to-v3/SKILL.md`

For Cloudflare Zero Trust wording, keep the boundary consistent:
- Cloudflare Access/Tunnel is a documented external operator/app access pattern.
- kube-hetzner does not add Cloudflare provider inputs or manage Cloudflare resources.
- Cloudflare Mesh/WARP is not supported kube-hetzner node transport in v3.
- Tailscale remains the supported managed node transport for secure multinetwork scale.

For Cilium Gateway API changes, keep these surfaces in sync:
- `variables.tf` validation for `cilium_gateway_api_enabled`
- `locals.tf` Cilium values and Gateway API CRD version mapping
- `README.md`
- `kube.tf.example`
- `docs/llms.md`
- `docs/v3-topology-recommendations.md`
- `examples/cilium-gateway-api/README.md`
- `.claude/skills/kh-assistant/SKILL.md`
- `.claude/skills/test-changes/SKILL.md`

For embedded registry mirror changes, keep these surfaces in sync:
- `variables.tf` validation for `embedded_registry_mirror`
- `locals.tf` effective generated registries YAML merge behavior
- host/control-plane/agent/autoscaler config rendering
- `README.md`
- `kube.tf.example`
- `docs/llms.md`
- `docs/v3-topology-recommendations.md`
- `.claude/skills/kh-assistant/SKILL.md`
- `.claude/skills/test-changes/SKILL.md`

For v2 -> v3 migration or production-upgrade safety changes, keep these
surfaces in sync:
- `MIGRATION.md`, especially "Production in-place upgrades: safety model"
- `docs/v2-to-v3-migration.md`
- `CHANGELOG.md` upgrade notes
- `docs/v3-release-evidence.md` live proof
- `.claude/skills/migrate-v2-to-v3/SKILL.md`
- `.claude/skills/upgrade-cluster/SKILL.md`
- `.claude/skills/kh-assistant/SKILL.md`

The no-destroy gate must include the full protected hcloud set:
`hcloud_server`, `hcloud_network`, `hcloud_network_subnet`,
`hcloud_load_balancer`, `hcloud_volume`, `hcloud_primary_ip`,
`hcloud_placement_group`, and `hcloud_firewall`.

For SELinux changes, keep these surfaces in sync:
- `docs/selinux.md`
- `templates/kube-hetzner-selinux.te`
- `templates/k8s-custom-policies.te`
- `variables.tf` `enable_selinux` and per-pool `selinux`
- `.claude/skills/debug-node/SKILL.md`
- `.claude/skills/kh-assistant/SKILL.md`

Do not make generic "disable SELinux" recommendations. The operator path is
AVC evidence, udica-first workload policy, upstream module policy only with
reproducible denials, and per-pool `selinux = false` as the last resort.

For release presentation changes, verify README's "What's New in v3" tag link
still points at the current release tag, and keep the section current with the
live GitHub release body.

## Step 7: Verify Consistency

```bash
# Final verification
gemini --model gemini-3.1-pro-preview -p \
  "@variables.tf @docs/llms.md @kube.tf.example Verify these files are consistent. List any discrepancies."
```

### Verification Checklist

- [ ] All variables.tf variables documented in docs/llms.md
- [ ] All major variables appear in kube.tf.example
- [ ] README features match actual capabilities
- [ ] No typos in variable names across files
- [ ] Default values consistent across docs
- [ ] Major-upgrade safety wording matches `MIGRATION.md`
- [ ] SELinux workload-denial wording points to `docs/selinux.md`
- [ ] README "What's New in v3" release-tag URL is current for the release train

## Common Sync Issues

### Variable renamed
1. Update in variables.tf
2. Search and replace in docs/llms.md
3. Search and replace in kube.tf.example
4. Add to CHANGELOG.md (breaking change!)

### Variable removed
1. Remove from variables.tf
2. Remove from docs/llms.md
3. Remove from kube.tf.example
4. Add to CHANGELOG.md (breaking change!)

### Default changed
1. Update in variables.tf
2. Update in docs/llms.md
3. Update in kube.tf.example
4. Consider if this is a breaking change

## Quick Commands

```bash
# Regenerate terraform docs
terraform-docs markdown . > docs/terraform.md

# Validate v3 topology/Gateway/registry surfaces
uv run scripts/validate_v3_final_polish_examples.py

# Validate rendered templates and negative contract cases when those surfaces change
uv run scripts/render_harness.py
uv run scripts/contract_negative_tests.py

# Search for variable across all docs
rg -n "variable_name" docs/ kube.tf.example README.md

# Find undocumented variables (quick check)
diff <(rg -o 'variable "([^"]+)"' -r '$1' variables.tf | sort) \
     <(rg -o '`[a-z_]+`' docs/llms.md | tr -d '`' | sort -u) | rg "^<"
```

## After Sync

1. Run `terraform fmt -recursive`
2. Commit only if the current task calls for a commit, with message: `docs: sync documentation with variables.tf`
3. If breaking changes, update CHANGELOG.md

---

Source: https://www.openparable.com/skill/documents/sync-docs (OpenParable). Cite the canonical URL above.